aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/stable/sysfs-class-backlight36
-rw-r--r--Documentation/ABI/testing/sysfs-bus-pci10
-rw-r--r--Documentation/ABI/testing/sysfs-class-lcd23
-rw-r--r--Documentation/ABI/testing/sysfs-class-led28
-rw-r--r--Documentation/ABI/testing/sysfs-gpio1
-rw-r--r--Documentation/ABI/testing/sysfs-platform-asus-laptop52
-rw-r--r--Documentation/ABI/testing/sysfs-platform-eeepc-laptop50
-rw-r--r--Documentation/DocBook/Makefile10
-rw-r--r--Documentation/DocBook/dvb/.gitignore1
-rw-r--r--Documentation/DocBook/dvb/audio.xml1473
-rw-r--r--Documentation/DocBook/dvb/ca.xml221
-rw-r--r--Documentation/DocBook/dvb/demux.xml973
-rw-r--r--Documentation/DocBook/dvb/dvbapi.xml87
-rw-r--r--Documentation/DocBook/dvb/dvbstb.pdfbin0 -> 1881 bytes
-rw-r--r--Documentation/DocBook/dvb/dvbstb.pngbin0 -> 22655 bytes
-rw-r--r--Documentation/DocBook/dvb/examples.xml365
-rw-r--r--Documentation/DocBook/dvb/frontend.xml1766
-rw-r--r--Documentation/DocBook/dvb/intro.xml191
-rw-r--r--Documentation/DocBook/dvb/isdbt.xml314
-rw-r--r--Documentation/DocBook/dvb/kdapi.xml2309
-rw-r--r--Documentation/DocBook/dvb/net.xml12
-rw-r--r--Documentation/DocBook/dvb/video.xml1971
-rw-r--r--Documentation/DocBook/media-entities.tmpl364
-rw-r--r--Documentation/DocBook/media-indices.tmpl85
-rw-r--r--Documentation/DocBook/media.tmpl112
-rw-r--r--Documentation/DocBook/mtdnand.tmpl2
-rw-r--r--Documentation/DocBook/scsi.tmpl2
-rw-r--r--Documentation/DocBook/stylesheet.xsl1
-rw-r--r--Documentation/DocBook/uio-howto.tmpl163
-rw-r--r--Documentation/DocBook/v4l/.gitignore1
-rw-r--r--Documentation/DocBook/v4l/biblio.xml188
-rw-r--r--Documentation/DocBook/v4l/capture.c.xml659
-rw-r--r--Documentation/DocBook/v4l/common.xml1160
-rw-r--r--Documentation/DocBook/v4l/compat.xml2457
-rw-r--r--Documentation/DocBook/v4l/controls.xml2049
-rw-r--r--Documentation/DocBook/v4l/crop.gifbin0 -> 5967 bytes
-rw-r--r--Documentation/DocBook/v4l/crop.pdfbin0 -> 5846 bytes
-rw-r--r--Documentation/DocBook/v4l/dev-capture.xml115
-rw-r--r--Documentation/DocBook/v4l/dev-codec.xml26
-rw-r--r--Documentation/DocBook/v4l/dev-effect.xml25
-rw-r--r--Documentation/DocBook/v4l/dev-osd.xml164
-rw-r--r--Documentation/DocBook/v4l/dev-output.xml111
-rw-r--r--Documentation/DocBook/v4l/dev-overlay.xml379
-rw-r--r--Documentation/DocBook/v4l/dev-radio.xml57
-rw-r--r--Documentation/DocBook/v4l/dev-raw-vbi.xml347
-rw-r--r--Documentation/DocBook/v4l/dev-rds.xml168
-rw-r--r--Documentation/DocBook/v4l/dev-sliced-vbi.xml708
-rw-r--r--Documentation/DocBook/v4l/dev-teletext.xml40
-rw-r--r--Documentation/DocBook/v4l/driver.xml208
-rw-r--r--Documentation/DocBook/v4l/fdl-appendix.xml671
-rw-r--r--Documentation/DocBook/v4l/fieldseq_bt.gifbin0 -> 25430 bytes
-rw-r--r--Documentation/DocBook/v4l/fieldseq_bt.pdfbin0 -> 9185 bytes
-rw-r--r--Documentation/DocBook/v4l/fieldseq_tb.gifbin0 -> 25323 bytes
-rw-r--r--Documentation/DocBook/v4l/fieldseq_tb.pdfbin0 -> 9173 bytes
-rw-r--r--Documentation/DocBook/v4l/func-close.xml70
-rw-r--r--Documentation/DocBook/v4l/func-ioctl.xml146
-rw-r--r--Documentation/DocBook/v4l/func-mmap.xml185
-rw-r--r--Documentation/DocBook/v4l/func-munmap.xml83
-rw-r--r--Documentation/DocBook/v4l/func-open.xml121
-rw-r--r--Documentation/DocBook/v4l/func-poll.xml127
-rw-r--r--Documentation/DocBook/v4l/func-read.xml189
-rw-r--r--Documentation/DocBook/v4l/func-select.xml138
-rw-r--r--Documentation/DocBook/v4l/func-write.xml136
-rw-r--r--Documentation/DocBook/v4l/io.xml1073
-rw-r--r--Documentation/DocBook/v4l/keytable.c.xml172
-rw-r--r--Documentation/DocBook/v4l/libv4l.xml167
-rw-r--r--Documentation/DocBook/v4l/pixfmt-grey.xml70
-rw-r--r--Documentation/DocBook/v4l/pixfmt-nv12.xml151
-rw-r--r--Documentation/DocBook/v4l/pixfmt-nv16.xml174
-rw-r--r--Documentation/DocBook/v4l/pixfmt-packed-rgb.xml862
-rw-r--r--Documentation/DocBook/v4l/pixfmt-packed-yuv.xml244
-rw-r--r--Documentation/DocBook/v4l/pixfmt-sbggr16.xml91
-rw-r--r--Documentation/DocBook/v4l/pixfmt-sbggr8.xml75
-rw-r--r--Documentation/DocBook/v4l/pixfmt-sgbrg8.xml75
-rw-r--r--Documentation/DocBook/v4l/pixfmt-sgrbg8.xml75
-rw-r--r--Documentation/DocBook/v4l/pixfmt-uyvy.xml128
-rw-r--r--Documentation/DocBook/v4l/pixfmt-vyuy.xml128
-rw-r--r--Documentation/DocBook/v4l/pixfmt-y16.xml89
-rw-r--r--Documentation/DocBook/v4l/pixfmt-y41p.xml157
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuv410.xml141
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuv411p.xml155
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuv420.xml157
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuv422p.xml161
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuyv.xml128
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yvyu.xml128
-rw-r--r--Documentation/DocBook/v4l/pixfmt.xml801
-rw-r--r--Documentation/DocBook/v4l/remote_controllers.xml175
-rw-r--r--Documentation/DocBook/v4l/v4l2.xml479
-rw-r--r--Documentation/DocBook/v4l/v4l2grab.c.xml164
-rw-r--r--Documentation/DocBook/v4l/vbi_525.gifbin0 -> 4741 bytes
-rw-r--r--Documentation/DocBook/v4l/vbi_525.pdfbin0 -> 3395 bytes
-rw-r--r--Documentation/DocBook/v4l/vbi_625.gifbin0 -> 5095 bytes
-rw-r--r--Documentation/DocBook/v4l/vbi_625.pdfbin0 -> 3683 bytes
-rw-r--r--Documentation/DocBook/v4l/vbi_hsync.gifbin0 -> 2400 bytes
-rw-r--r--Documentation/DocBook/v4l/vbi_hsync.pdfbin0 -> 7405 bytes
-rw-r--r--Documentation/DocBook/v4l/videodev2.h.xml1640
-rw-r--r--Documentation/DocBook/v4l/vidioc-cropcap.xml174
-rw-r--r--Documentation/DocBook/v4l/vidioc-dbg-g-chip-ident.xml275
-rw-r--r--Documentation/DocBook/v4l/vidioc-dbg-g-register.xml275
-rw-r--r--Documentation/DocBook/v4l/vidioc-encoder-cmd.xml204
-rw-r--r--Documentation/DocBook/v4l/vidioc-enum-fmt.xml164
-rw-r--r--Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml270
-rw-r--r--Documentation/DocBook/v4l/vidioc-enum-framesizes.xml282
-rw-r--r--Documentation/DocBook/v4l/vidioc-enumaudio.xml86
-rw-r--r--Documentation/DocBook/v4l/vidioc-enumaudioout.xml89
-rw-r--r--Documentation/DocBook/v4l/vidioc-enuminput.xml287
-rw-r--r--Documentation/DocBook/v4l/vidioc-enumoutput.xml172
-rw-r--r--Documentation/DocBook/v4l/vidioc-enumstd.xml391
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-audio.xml188
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-audioout.xml154
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-crop.xml143
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-ctrl.xml130
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-enc-index.xml213
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml307
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-fbuf.xml456
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-fmt.xml201
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-frequency.xml145
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-input.xml100
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-jpegcomp.xml180
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-modulator.xml246
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-output.xml100
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-parm.xml332
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-priority.xml144
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-sliced-vbi-cap.xml264
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-std.xml99
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-tuner.xml535
-rw-r--r--Documentation/DocBook/v4l/vidioc-log-status.xml58
-rw-r--r--Documentation/DocBook/v4l/vidioc-overlay.xml83
-rw-r--r--Documentation/DocBook/v4l/vidioc-qbuf.xml168
-rw-r--r--Documentation/DocBook/v4l/vidioc-querybuf.xml103
-rw-r--r--Documentation/DocBook/v4l/vidioc-querycap.xml284
-rw-r--r--Documentation/DocBook/v4l/vidioc-queryctrl.xml428
-rw-r--r--Documentation/DocBook/v4l/vidioc-querystd.xml83
-rw-r--r--Documentation/DocBook/v4l/vidioc-reqbufs.xml160
-rw-r--r--Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml129
-rw-r--r--Documentation/DocBook/v4l/vidioc-streamon.xml106
-rw-r--r--Documentation/Intel-IOMMU.txt6
-rw-r--r--Documentation/PCI/pci-error-recovery.txt119
-rw-r--r--Documentation/SubmittingPatches2
-rw-r--r--Documentation/accounting/getdelays.c12
-rw-r--r--Documentation/arm/OMAP/omap_pm129
-rw-r--r--Documentation/auxdisplay/cfag12864b-example.c23
-rw-r--r--Documentation/cgroups/cgroups.txt32
-rw-r--r--Documentation/cgroups/memory.txt41
-rw-r--r--Documentation/cpu-freq/user-guide.txt9
-rw-r--r--Documentation/dontdiff1
-rw-r--r--Documentation/dvb/get_dvb_firmware37
-rw-r--r--Documentation/dvb/technisat.txt75
-rw-r--r--Documentation/fb/ep93xx-fb.txt135
-rw-r--r--Documentation/fb/matroxfb.txt4
-rw-r--r--Documentation/feature-removal-schedule.txt18
-rw-r--r--Documentation/filesystems/9p.txt40
-rw-r--r--Documentation/filesystems/ext4.txt24
-rw-r--r--Documentation/filesystems/ncpfs.txt6
-rw-r--r--Documentation/filesystems/nfs41-server.txt54
-rw-r--r--Documentation/filesystems/nfsroot.txt2
-rw-r--r--Documentation/filesystems/proc.txt27
-rw-r--r--Documentation/filesystems/sharedsubtree.txt220
-rw-r--r--Documentation/gcov.txt2
-rw-r--r--Documentation/gpio.txt17
-rw-r--r--Documentation/hwmon/acpi_power_meter51
-rw-r--r--Documentation/hwmon/coretemp4
-rw-r--r--Documentation/hwmon/fscher169
-rw-r--r--Documentation/hwmon/hpfall.c115
-rw-r--r--Documentation/hwmon/pc874272
-rw-r--r--Documentation/hwmon/pcf859128
-rw-r--r--Documentation/hwmon/tmp42136
-rw-r--r--Documentation/hwmon/wm831x37
-rw-r--r--Documentation/hwmon/wm835026
-rw-r--r--Documentation/i2c/busses/i2c-piix42
-rw-r--r--Documentation/i2c/chips/pca953958
-rw-r--r--Documentation/i2c/chips/pcf857465
-rw-r--r--Documentation/i2c/chips/pcf857569
-rw-r--r--Documentation/ia64/aliasing-test.c8
-rw-r--r--Documentation/ioctl/ioctl-number.txt1
-rw-r--r--Documentation/kbuild/kbuild.txt16
-rw-r--r--Documentation/kbuild/makefiles.txt20
-rw-r--r--Documentation/kernel-doc-nano-HOWTO.txt4
-rw-r--r--Documentation/kernel-parameters.txt10
-rw-r--r--Documentation/kmemcheck.txt21
-rw-r--r--Documentation/kref.txt1
-rw-r--r--Documentation/laptops/asus-laptop.txt258
-rw-r--r--Documentation/laptops/thinkpad-acpi.txt8
-rw-r--r--Documentation/leds-class.txt9
-rw-r--r--Documentation/lguest/lguest.c26
-rw-r--r--Documentation/markers.txt104
-rw-r--r--Documentation/memory.txt31
-rw-r--r--Documentation/networking/regulatory.txt2
-rw-r--r--Documentation/numastat.txt8
-rw-r--r--Documentation/pcmcia/crc32hash.c2
-rw-r--r--Documentation/power/power_supply_class.txt7
-rw-r--r--Documentation/power/regulator/design.txt33
-rw-r--r--Documentation/power/regulator/machine.txt4
-rw-r--r--Documentation/power/regulator/overview.txt4
-rw-r--r--Documentation/power/regulator/regulator.txt5
-rw-r--r--Documentation/powerpc/dts-bindings/fsl/esdhc.txt2
-rw-r--r--Documentation/powerpc/dts-bindings/marvell.txt2
-rw-r--r--Documentation/powerpc/dts-bindings/mtd-physmap.txt42
-rw-r--r--Documentation/rtc.txt26
-rw-r--r--Documentation/scsi/ChangeLog.megaraid2
-rw-r--r--Documentation/scsi/scsi_fc_transport.txt2
-rw-r--r--Documentation/sound/alsa/HD-Audio-Models.txt2
-rw-r--r--Documentation/spi/spi-summary2
-rw-r--r--Documentation/spi/spidev_test.c4
-rw-r--r--Documentation/sysctl/fs.txt17
-rw-r--r--Documentation/sysctl/kernel.txt60
-rw-r--r--Documentation/sysctl/vm.txt4
-rw-r--r--Documentation/trace/events-kmem.txt107
-rw-r--r--Documentation/trace/events.txt210
-rw-r--r--Documentation/trace/ftrace-design.txt233
-rw-r--r--Documentation/trace/ftrace.txt8
-rw-r--r--Documentation/trace/postprocess/trace-pagealloc-postprocess.pl418
-rw-r--r--Documentation/trace/power.txt17
-rw-r--r--Documentation/trace/tracepoint-analysis.txt327
-rw-r--r--Documentation/usb/authorization.txt10
-rw-r--r--Documentation/usb/usbmon.txt8
-rw-r--r--Documentation/vgaarbiter.txt194
-rw-r--r--Documentation/video4linux/CARDLIST.cx238851
-rw-r--r--Documentation/video4linux/CARDLIST.em28xx3
-rw-r--r--Documentation/video4linux/CARDLIST.saa71341
-rw-r--r--Documentation/video4linux/CARDLIST.saa71649
-rw-r--r--Documentation/video4linux/CARDLIST.tuner2
-rw-r--r--Documentation/video4linux/gspca.txt2
-rw-r--r--Documentation/video4linux/soc-camera.txt40
-rw-r--r--Documentation/video4linux/v4l2-framework.txt61
-rw-r--r--Documentation/video4linux/v4lgrab.c2
-rw-r--r--Documentation/vm/.gitignore1
-rw-r--r--Documentation/vm/00-INDEX4
-rw-r--r--Documentation/vm/hugetlbpage.txt147
-rw-r--r--Documentation/vm/ksm.txt89
-rw-r--r--Documentation/vm/map_hugetlb.c77
-rw-r--r--Documentation/vm/page-types.c248
-rw-r--r--Documentation/vm/slabinfo.c68
-rw-r--r--Documentation/watchdog/src/watchdog-test.c2
-rw-r--r--Documentation/x86/boot.txt1
-rw-r--r--Documentation/x86/earlyprintk.txt39
236 files changed, 40993 insertions, 1198 deletions
diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight
new file mode 100644
index 000000000000..4d637e1c4ff7
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-class-backlight
@@ -0,0 +1,36 @@
1What: /sys/class/backlight/<backlight>/bl_power
2Date: April 2005
3KernelVersion: 2.6.12
4Contact: Richard Purdie <rpurdie@rpsys.net>
5Description:
6 Control BACKLIGHT power, values are FB_BLANK_* from fb.h
7 - FB_BLANK_UNBLANK (0) : power on.
8 - FB_BLANK_POWERDOWN (4) : power off
9Users: HAL
10
11What: /sys/class/backlight/<backlight>/brightness
12Date: April 2005
13KernelVersion: 2.6.12
14Contact: Richard Purdie <rpurdie@rpsys.net>
15Description:
16 Control the brightness for this <backlight>. Values
17 are between 0 and max_brightness. This file will also
18 show the brightness level stored in the driver, which
19 may not be the actual brightness (see actual_brightness).
20Users: HAL
21
22What: /sys/class/backlight/<backlight>/actual_brightness
23Date: March 2006
24KernelVersion: 2.6.17
25Contact: Richard Purdie <rpurdie@rpsys.net>
26Description:
27 Show the actual brightness by querying the hardware.
28Users: HAL
29
30What: /sys/class/backlight/<backlight>/max_brightness
31Date: April 2005
32KernelVersion: 2.6.12
33Contact: Richard Purdie <rpurdie@rpsys.net>
34Description:
35 Maximum brightness for <backlight>.
36Users: HAL
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
87What: /sys/bus/pci/devices/.../reset
88Date: July 2009
89Contact: Michael S. Tsirkin <mst@redhat.com>
90Description:
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
87What: /sys/bus/pci/devices/.../vpd 97What: /sys/bus/pci/devices/.../vpd
88Date: February 2008 98Date: February 2008
89Contact: Ben Hutchings <bhutchings@solarflare.com> 99Contact: Ben Hutchings <bhutchings@solarflare.com>
diff --git a/Documentation/ABI/testing/sysfs-class-lcd b/Documentation/ABI/testing/sysfs-class-lcd
new file mode 100644
index 000000000000..35906bf7aa70
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-lcd
@@ -0,0 +1,23 @@
1What: /sys/class/lcd/<lcd>/lcd_power
2Date: April 2005
3KernelVersion: 2.6.12
4Contact: Richard Purdie <rpurdie@rpsys.net>
5Description:
6 Control LCD power, values are FB_BLANK_* from fb.h
7 - FB_BLANK_UNBLANK (0) : power on.
8 - FB_BLANK_POWERDOWN (4) : power off
9
10What: /sys/class/lcd/<lcd>/contrast
11Date: April 2005
12KernelVersion: 2.6.12
13Contact: Richard Purdie <rpurdie@rpsys.net>
14Description:
15 Current contrast of this LCD device. Value is between 0 and
16 /sys/class/lcd/<lcd>/max_contrast.
17
18What: /sys/class/lcd/<lcd>/max_contrast
19Date: April 2005
20KernelVersion: 2.6.12
21Contact: Richard Purdie <rpurdie@rpsys.net>
22Description:
23 Maximum contrast for this LCD device.
diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
new file mode 100644
index 000000000000..9e4541d71cb6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led
@@ -0,0 +1,28 @@
1What: /sys/class/leds/<led>/brightness
2Date: March 2006
3KernelVersion: 2.6.17
4Contact: Richard Purdie <rpurdie@rpsys.net>
5Description:
6 Set the brightness of the LED. Most LEDs don't
7 have hardware brightness support so will just be turned on for
8 non-zero brightness settings. The value is between 0 and
9 /sys/class/leds/<led>/max_brightness.
10
11What: /sys/class/leds/<led>/max_brightness
12Date: March 2006
13KernelVersion: 2.6.17
14Contact: Richard Purdie <rpurdie@rpsys.net>
15Description:
16 Maximum brightness level for this led, default is 255 (LED_FULL).
17
18What: /sys/class/leds/<led>/trigger
19Date: March 2006
20KernelVersion: 2.6.17
21Contact: Richard Purdie <rpurdie@rpsys.net>
22Description:
23 Set the trigger for this LED. A trigger is a kernel based source
24 of led events.
25 You can change triggers in a similar manner to the way an IO
26 scheduler is chosen. Trigger specific parameters can appear in
27 /sys/class/leds/<led> once a given trigger is selected.
28
diff --git a/Documentation/ABI/testing/sysfs-gpio b/Documentation/ABI/testing/sysfs-gpio
index 8aab8092ad35..80f4c94c7bef 100644
--- a/Documentation/ABI/testing/sysfs-gpio
+++ b/Documentation/ABI/testing/sysfs-gpio
@@ -19,6 +19,7 @@ Description:
19 /gpioN ... for each exported GPIO #N 19 /gpioN ... for each exported GPIO #N
20 /value ... always readable, writes fail for input GPIOs 20 /value ... always readable, writes fail for input GPIOs
21 /direction ... r/w as: in, out (default low); write: high, low 21 /direction ... r/w as: in, out (default low); write: high, low
22 /edge ... r/w as: none, falling, rising, both
22 /gpiochipN ... for each gpiochip; #N is its first GPIO 23 /gpiochipN ... for each gpiochip; #N is its first GPIO
23 /base ... (r/o) same as N 24 /base ... (r/o) same as N
24 /label ... (r/o) descriptive, not necessarily unique 25 /label ... (r/o) descriptive, not necessarily unique
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop
new file mode 100644
index 000000000000..a1cb660c50cf
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
@@ -0,0 +1,52 @@
1What: /sys/devices/platform/asus-laptop/display
2Date: January 2007
3KernelVersion: 2.6.20
4Contact: "Corentin Chary" <corentincj@iksaif.net>
5Description:
6 This file allows display switching. The value
7 is composed by 4 bits and defined as follow:
8 4321
9 |||`- LCD
10 ||`-- CRT
11 |`--- TV
12 `---- DVI
13 Ex: - 0 (0000b) means no display
14 - 3 (0011b) CRT+LCD.
15
16What: /sys/devices/platform/asus-laptop/gps
17Date: January 2007
18KernelVersion: 2.6.20
19Contact: "Corentin Chary" <corentincj@iksaif.net>
20Description:
21 Control the gps device. 1 means on, 0 means off.
22Users: Lapsus
23
24What: /sys/devices/platform/asus-laptop/ledd
25Date: January 2007
26KernelVersion: 2.6.20
27Contact: "Corentin Chary" <corentincj@iksaif.net>
28Description:
29 Some models like the W1N have a LED display that can be
30 used to display several informations.
31 To control the LED display, use the following :
32 echo 0x0T000DDD > /sys/devices/platform/asus-laptop/
33 where T control the 3 letters display, and DDD the 3 digits display.
34 The DDD table can be found in Documentation/laptops/asus-laptop.txt
35
36What: /sys/devices/platform/asus-laptop/bluetooth
37Date: January 2007
38KernelVersion: 2.6.20
39Contact: "Corentin Chary" <corentincj@iksaif.net>
40Description:
41 Control the bluetooth device. 1 means on, 0 means off.
42 This may control the led, the device or both.
43Users: Lapsus
44
45What: /sys/devices/platform/asus-laptop/wlan
46Date: January 2007
47KernelVersion: 2.6.20
48Contact: "Corentin Chary" <corentincj@iksaif.net>
49Description:
50 Control the bluetooth device. 1 means on, 0 means off.
51 This may control the led, the device or both.
52Users: Lapsus
diff --git a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
new file mode 100644
index 000000000000..7445dfb321b5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
@@ -0,0 +1,50 @@
1What: /sys/devices/platform/eeepc-laptop/disp
2Date: May 2008
3KernelVersion: 2.6.26
4Contact: "Corentin Chary" <corentincj@iksaif.net>
5Description:
6 This file allows display switching.
7 - 1 = LCD
8 - 2 = CRT
9 - 3 = LCD+CRT
10 If you run X11, you should use xrandr instead.
11
12What: /sys/devices/platform/eeepc-laptop/camera
13Date: May 2008
14KernelVersion: 2.6.26
15Contact: "Corentin Chary" <corentincj@iksaif.net>
16Description:
17 Control the camera. 1 means on, 0 means off.
18
19What: /sys/devices/platform/eeepc-laptop/cardr
20Date: May 2008
21KernelVersion: 2.6.26
22Contact: "Corentin Chary" <corentincj@iksaif.net>
23Description:
24 Control the card reader. 1 means on, 0 means off.
25
26What: /sys/devices/platform/eeepc-laptop/cpufv
27Date: Jun 2009
28KernelVersion: 2.6.31
29Contact: "Corentin Chary" <corentincj@iksaif.net>
30Description:
31 Change CPU clock configuration.
32 On the Eee PC 1000H there are three available clock configuration:
33 * 0 -> Super Performance Mode
34 * 1 -> High Performance Mode
35 * 2 -> Power Saving Mode
36 On Eee PC 701 there is only 2 available clock configurations.
37 Available configuration are listed in available_cpufv file.
38 Reading this file will show the raw hexadecimal value which
39 is defined as follow:
40 | 8 bit | 8 bit |
41 | `---- Current mode
42 `------------ Availables modes
43 For example, 0x301 means: mode 1 selected, 3 available modes.
44
45What: /sys/devices/platform/eeepc-laptop/available_cpufv
46Date: Jun 2009
47KernelVersion: 2.6.31
48Contact: "Corentin Chary" <corentincj@iksaif.net>
49Description:
50 List available cpufv modes.
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.
35PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs 35PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs media
36 36
37BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) 37BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
38xmldocs: $(BOOKS) 38xmldocs: $(BOOKS)
@@ -45,12 +45,16 @@ PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
45pdfdocs: $(PDF) 45pdfdocs: $(PDF)
46 46
47HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) 47HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
48htmldocs: $(HTML) 48htmldocs: media $(HTML)
49 $(call build_main_index) 49 $(call build_main_index)
50 50
51MAN := $(patsubst %.xml, %.9, $(BOOKS)) 51MAN := $(patsubst %.xml, %.9, $(BOOKS))
52mandocs: $(MAN) 52mandocs: $(MAN)
53 53
54media:
55 mkdir -p $(srctree)/Documentation/DocBook/media/
56 cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(srctree)/Documentation/DocBook/media/
57
54installmandocs: mandocs 58installmandocs: 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
3can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and
4ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your
5application.
6</para>
7<para>Please note that some DVB cards don&#8217;t have their own MPEG decoder, which results in
8the 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
14audio 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
20the following values, depending on whether we are replaying from an internal (demux) or
21external (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
30DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY
31is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
32call.
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
39state 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
53following 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
67states 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
84volume.
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
97bits 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,
125Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the
126right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left
127and 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 /&#x22C6; bits: descr. &#x22C6;/
138 /&#x22C6; 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, &#x22C6;/
139 /&#x22C6; 12 multichannel extension &#x22C6;/
140 /&#x22C6; 11-10 audio type (0=not spec, 1=language included) &#x22C6;/
141 /&#x22C6; 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) &#x22C6;/
142 /&#x22C6; 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, &#x22C6;/
143 /&#x22C6; 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) &#x22C6;/
144 /&#x22C6; 2- 0 number of audio channels (n+1 channels) &#x22C6;/
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 &#x22C6;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 &#x22C6;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
362role="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
413role="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
465role="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
525role="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
596role="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
675role="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
754role="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&#8217;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
837role="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
906role="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 &#x22C6;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
974role="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 &#x22C6;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
1042role="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
1094role="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
1165role="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 &#x22C6;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
1231role="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
1292role="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
1352role="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
1413role="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 &#x22C6;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
4including <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 /&#x22C6; slot interface types and info &#x22C6;/
15
16 typedef struct ca_slot_info_s {
17 int num; /&#x22C6; slot number &#x22C6;/
18
19 int type; /&#x22C6; CA interface this slot supports &#x22C6;/
20 #define CA_CI 1 /&#x22C6; CI high level interface &#x22C6;/
21 #define CA_CI_LINK 2 /&#x22C6; CI link layer level interface &#x22C6;/
22 #define CA_CI_PHYS 4 /&#x22C6; CI physical layer level interface &#x22C6;/
23 #define CA_SC 128 /&#x22C6; simple smart card interface &#x22C6;/
24
25 unsigned int flags;
26 #define CA_CI_MODULE_PRESENT 1 /&#x22C6; module (or card) inserted &#x22C6;/
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; /&#x22C6; number of available descramblers (keys) &#x22C6;/
37 unsigned int type; /&#x22C6; type of supported scrambling system &#x22C6;/
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; /&#x22C6; total number of CA card and module slots &#x22C6;/
50 unsigned int slot_type; /&#x22C6; OR of all supported types &#x22C6;/
51 unsigned int descr_num; /&#x22C6; total number of descrambler slots (keys) &#x22C6;/
52 unsigned int descr_type;/&#x22C6; OR of all supported types &#x22C6;/
53 } ca_cap_t;
54</programlisting>
55
56</section>
57<section id="ca_msg_t">
58<title>ca_msg_t</title>
59 <programlisting>
60 /&#x22C6; a message to/from a CI-CAM &#x22C6;/
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 &#x22C6;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
4accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be
5accessed 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
21called.
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>,
24which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was
25specified.
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; /&#x22C6; input : which STC? 0..N &#x22C6;/
138 unsigned int base; /&#x22C6; output: divisor for stc to get 90 kHz clock &#x22C6;/
139 uint64_t stc; /&#x22C6; output: stc in 'base'&#x22C6;90 kHz units &#x22C6;/
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 &#x22C6;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>&#8220;Too many open files&#8221;, 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&#8217;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 &#x22C6;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 &#x22C6;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 &#8221;one-shot&#8221; 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 &#x22C6;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 &#x22C6;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 &#x22C6;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-&#x003E;stc /
913 stc-&#x003E;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 &#x22C6;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>
37Added 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
5with 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
11the demux devices. The example is given for QPSK tuners, but can easily be adjusted for
12QAM.
13</para>
14<programlisting>
15 #include &#x003C;sys/ioctl.h&#x003E;
16 #include &#x003C;stdio.h&#x003E;
17 #include &#x003C;stdint.h&#x003E;
18 #include &#x003C;sys/types.h&#x003E;
19 #include &#x003C;sys/stat.h&#x003E;
20 #include &#x003C;fcntl.h&#x003E;
21 #include &#x003C;time.h&#x003E;
22 #include &#x003C;unistd.h&#x003E;
23
24 #include &#x003C;linux/dvb/dmx.h&#x003E;
25 #include &#x003C;linux/dvb/frontend.h&#x003E;
26 #include &#x003C;linux/dvb/sec.h&#x003E;
27 #include &#x003C;sys/poll.h&#x003E;
28
29 #define DMX "/dev/dvb/adapter0/demux1"
30 #define FRONT "/dev/dvb/adapter0/frontend1"
31 #define SEC "/dev/dvb/adapter0/sec1"
32
33 /&#x22C6; routine for checking if we have a signal and other status information&#x22C6;/
34 int FEReadStatus(int fd, fe_status_t &#x22C6;stat)
35 {
36 int ans;
37
38 if ( (ans = ioctl(fd,FE_READ_STATUS,stat) &#x003C; 0)){
39 perror("FE READ STATUS: ");
40 return -1;
41 }
42
43 if (&#x22C6;stat &amp; FE_HAS_POWER)
44 printf("FE HAS POWER\n");
45
46 if (&#x22C6;stat &amp; FE_HAS_SIGNAL)
47 printf("FE HAS SIGNAL\n");
48
49 if (&#x22C6;stat &amp; FE_SPECTRUM_INV)
50 printf("SPEKTRUM INV\n");
51
52 return 0;
53 }
54
55
56 /&#x22C6; tune qpsk &#x22C6;/
57 /&#x22C6; freq: frequency of transponder &#x22C6;/
58 /&#x22C6; vpid, apid, tpid: PIDs of video, audio and teletext TS packets &#x22C6;/
59 /&#x22C6; diseqc: DiSEqC address of the used LNB &#x22C6;/
60 /&#x22C6; pol: Polarisation &#x22C6;/
61 /&#x22C6; srate: Symbol Rate &#x22C6;/
62 /&#x22C6; fec. FEC &#x22C6;/
63 /&#x22C6; lnb_lof1: local frequency of lower LNB band &#x22C6;/
64 /&#x22C6; lnb_lof2: local frequency of upper LNB band &#x22C6;/
65 /&#x22C6; lnb_slof: switch frequency of LNB &#x22C6;/
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)) &#x003C; 0){
83 perror("FRONTEND DEVICE: ");
84 return -1;
85 }
86
87 if((sec = open(SEC,O_RDWR)) &#x003C; 0){
88 perror("SEC DEVICE: ");
89 return -1;
90 }
91
92 if (demux1 &#x003C; 0){
93 if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
94 &#x003C; 0){
95 perror("DEMUX DEVICE: ");
96 return -1;
97 }
98 }
99
100 if (demux2 &#x003C; 0){
101 if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
102 &#x003C; 0){
103 perror("DEMUX DEVICE: ");
104 return -1;
105 }
106 }
107
108 if (demux3 &#x003C; 0){
109 if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
110 &#x003C; 0){
111 perror("DEMUX DEVICE: ");
112 return -1;
113 }
114 }
115
116 if (freq &#x003C; 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 &#x22C6; 4) &amp; 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=&amp;scmd;
138 if (ioctl(sec, SEC_SEND_SEQUENCE, &amp;scmds) &#x003C; 0){
139 perror("SEC SEND: ");
140 return -1;
141 }
142
143 if (ioctl(sec, SEC_SEND_SEQUENCE, &amp;scmds) &#x003C; 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, &amp;frp) &#x003C; 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 &amp; POLLIN){
161 printf("Getting QPSK event\n");
162 if ( ioctl(front, FE_GET_EVENT, &amp;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, &amp;pesFilterParams) &#x003C; 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, &amp;pesFilterParams) &#x003C; 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, &amp;pesFilterParams) &#x003C; 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
219switch with up to 4 addresses. Of course, you could build in some more checking if
220tuning was successful and maybe try to repeat the tuning process. Depending on the
221external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be
222necessary.
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 &#x003C;sys/ioctl.h&#x003E;
232 #include &#x003C;stdio.h&#x003E;
233 #include &#x003C;stdint.h&#x003E;
234 #include &#x003C;sys/types.h&#x003E;
235 #include &#x003C;sys/stat.h&#x003E;
236 #include &#x003C;fcntl.h&#x003E;
237 #include &#x003C;time.h&#x003E;
238 #include &#x003C;unistd.h&#x003E;
239
240 #include &#x003C;linux/dvb/dmx.h&#x003E;
241 #include &#x003C;linux/dvb/video.h&#x003E;
242 #include &#x003C;sys/poll.h&#x003E;
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&#x22C6;20)
248 #define MAX_LENGTH (1024&#x22C6;1024&#x22C6;5) /&#x22C6; record 5MB &#x22C6;/
249
250
251 /&#x22C6; switch the demuxes to recording, assuming the transponder is tuned &#x22C6;/
252
253 /&#x22C6; demux1, demux2: file descriptor of video and audio filters &#x22C6;/
254 /&#x22C6; vpid, apid: PIDs of video and audio channels &#x22C6;/
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 &#x003C; 0){
261 if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
262 &#x003C; 0){
263 perror("DEMUX DEVICE: ");
264 return -1;
265 }
266 }
267
268 if (demux2 &#x003C; 0){
269 if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
270 &#x003C; 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, &amp;pesFilterParams) &#x003C; 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, &amp;pesFilterParams) &#x003C; 0){
291 perror("DEMUX DEVICE");
292 return -1;
293 }
294 return 0;
295 }
296
297 /&#x22C6; start recording MAX_LENGTH , assuming the transponder is tuned &#x22C6;/
298
299 /&#x22C6; demux1, demux2: file descriptor of video and audio filters &#x22C6;/
300 /&#x22C6; vpid, apid: PIDs of video and audio channels &#x22C6;/
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 /&#x22C6; open dvr device &#x22C6;/
312 if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) &#x003C; 0){
313 perror("DVR DEVICE");
314 return -1;
315 }
316
317 /&#x22C6; switch video and audio demuxes to dvr &#x22C6;/
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&#x22C6;1024.0));
324 length = 0;
325
326 /&#x22C6; open output file &#x22C6;/
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)) &#x003C; 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 /&#x22C6; poll for dvr data and write to file &#x22C6;/
339 while (length &#x003C; MAX_LENGTH ) {
340 if (poll(pfd,1,1)){
341 if (pfd[0].revents &amp; POLLIN){
342 len = read(dvr, buf, BUFFY);
343 if (len &#x003C; 0){
344 perror("recording");
345 return -1;
346 }
347 if (len &#x003E; 0){
348 written = 0;
349 while (written &#x003C; 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
4hardware. It can be accessed through <emphasis
5role="tt">/dev/dvb/adapter0/frontend0</emphasis>. Data types and and
6ioctl definitions can be accessed by including <emphasis
7role="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)
11is not yet handled by this API but a future extension is possible. For
12DVB-S the frontend device also supports satellite equipment control
13(SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC)
14specification 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
18cards, 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
27transmission.</para>
28<programlisting>
29 typedef enum fe_type {
30 FE_QPSK, /&#x22C6; DVB-S &#x22C6;/
31 FE_QAM, /&#x22C6; DVB-C &#x22C6;/
32 FE_OFDM /&#x22C6; DVB-T &#x22C6;/
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
42a 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; /&#x22C6; ppm &#x22C6;/
89 uint32_t notifier_delay; /&#x22C6; ms &#x22C6;/
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]; /&#x22C6; { framing, address, command, data[3] } &#x22C6;/
102 uint8_t msg_len; /&#x22C6; valid values are 3...6 &#x22C6;/
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]; /&#x22C6; { framing, data [3] } &#x22C6;/
113 uint8_t msg_len; /&#x22C6; valid values are 0...4, 0 means no msg &#x22C6;/
114 int timeout; /&#x22C6; return from ioctl after timeout ms with &#x22C6;/
115 }; /&#x22C6; errorcode when no message was received &#x22C6;/
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
123consistently 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
136high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to
137be switched consistently to the DiSEqC commands as described in the DiSEqC
138spec.</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
151between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to
152be switched consistently to the DiSEqC commands as described in the DiSEqC
153spec.</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
167by</para>
168<programlisting>
169 typedef enum fe_status {
170 FE_HAS_SIGNAL = 0x01, /&#x22C6; found something above the noise level &#x22C6;/
171 FE_HAS_CARRIER = 0x02, /&#x22C6; found a DVB signal &#x22C6;/
172 FE_HAS_VITERBI = 0x04, /&#x22C6; FEC is stable &#x22C6;/
173 FE_HAS_SYNC = 0x08, /&#x22C6; found sync bytes &#x22C6;/
174 FE_HAS_LOCK = 0x10, /&#x22C6; everything's working... &#x22C6;/
175 FE_TIMEDOUT = 0x20, /&#x22C6; no lock within the last ~2 seconds &#x22C6;/
176 FE_REINIT = 0x40 /&#x22C6; frontend was reinitialized, &#x22C6;/
177 } fe_status_t; /&#x22C6; application is recommned to reset &#x22C6;/
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
187the kind of hardware you are using. All kinds of parameters are combined as an
188union in the FrontendParameters structure:</para>
189<programlisting>
190 struct dvb_frontend_parameters {
191 uint32_t frequency; /&#x22C6; (absolute) frequency in Hz for QAM/OFDM &#x22C6;/
192 /&#x22C6; intermediate frequency in kHz for QPSK &#x22C6;/
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; /&#x22C6; symbol rate in Symbols per second &#x22C6;/
205 fe_code_rate_t fec_inner; /&#x22C6; forward error correction (see above) &#x22C6;/
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; /&#x22C6; symbol rate in Symbols per second &#x22C6;/
212 fe_code_rate_t fec_inner; /&#x22C6; forward error correction (see above) &#x22C6;/
213 fe_modulation_t modulation; /&#x22C6; modulation type (see above) &#x22C6;/
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; /&#x22C6; high priority stream code rate &#x22C6;/
222 fe_code_rate_t code_rate_LP; /&#x22C6; low priority stream code rate &#x22C6;/
223 fe_modulation_t constellation; /&#x22C6; modulation type (see above) &#x22C6;/
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
230frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of
231the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and
232OFDM frontends the Frequency specifies the absolute frequency and is given in
233Hz.
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
246itself.
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
265detection.
266</para>
267<para>For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature
268modulation 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 &#x22C6;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 &#x22C6;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 &#x22C6;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 &#x22C6;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 &#x22C6;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 &#x22C6;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 &#x22C6;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 &#x22C6;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 &#x22C6;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 &#x22C6;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 &#x22C6;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 &#x22C6;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
7the area of digital video broadcasting (DVB) and should be familiar with
8part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
9you should know what a program/transport stream (PS/TS) is and what is
10meant 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
17how 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
25was an extension of the Video4Linux API which was primarily developed
26for frame grabber cards. As such it was not really well suited to be
27used for DVB cards and their new features like recording MPEG streams
28and 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
32new standard Linux DVB API. As a commitment to the development of
33terminals based on open standards, Nokia and Convergence made it
34available to all Linux developers and published it on
35<ulink url="http://www.linuxtv.org/" /> in September 2000.
36Convergence is the maintainer of the Linux DVB API. Together with the
37LinuxTV community (i.e. you, the reader of this document), the Linux DVB
38API will be constantly reviewed and improved. With the Linux driver for
39the Siemens/Hauppauge DVB PCI card Convergence provides a first
40implementation 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
59following 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
67or antenna or directly from cable. The frontend down-converts and
68demodulates this signal into an MPEG transport stream (TS). In case of a
69satellite frontend, this includes a facility for satellite equipment
70control (SEC), which allows control of LNB polarization, multi feed
71switches 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
80which the user has access (controlled by the smart card) are decoded in
81real 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
88video streams. Besides usually several of such audio and video streams
89it also contains data streams with information about the programs
90offered 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
98video decoders. After decoding they pass on the uncompressed audio and
99video to the computer screen or (through a PAL/NTSC encoder) to a TV
100set.</para>
101
102
103</listitem>
104</itemizedlist>
105
106<para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow
107between those components.</para>
108
109<para>On a DVB PCI card not all of these have to be present since some
110functionality can be provided by the main CPU of the PC (e.g. MPEG
111picture and sound decoding) or is not needed (e.g. for data-only uses
112like &#8220;internet over satellite&#8221;). Also not every card or STB
113provides 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
121through currently six Unix-style character devices for video, audio,
122frontend, demux, CA and IP-over-DVB networking. The video and audio
123devices control the MPEG2 decoder hardware, the frontend device the
124tuner and the DVB demodulator. The demux device gives you control over
125the PES and section filters of the hardware. If the hardware does not
126support filtering these filters can be implemented in software. Finally,
127the CA device controls all the conditional access capabilities of the
128hardware. It can depend on the individual security requirements of the
129platform, if and how many of the CA functions are made available to the
130application through this device.</para>
131
132<para>All devices can be found in the <emphasis role="tt">/dev</emphasis>
133tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices
134are 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
160from&#x00A0;0, and M enumerates the devices of each type within each
161adapter, starting from&#x00A0;0, too. We will omit the &#8220;<emphasis
162role="tt">/dev/dvb/adapterN/</emphasis>&#8221; in the further dicussion
163of these devices. The naming scheme for the devices is the same wheter
164devfs is used or not.</para>
165
166<para>More details about the data structures and function calls of all
167the 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.
175The DVB API include files should be included in application sources with
176a partial path like:</para>
177
178
179<programlisting>
180 #include &#x003C;linux/dvb/frontend.h&#x003E;
181</programlisting>
182
183<para>To enable applications to support different API version, an
184additional include file <emphasis
185role="tt">linux/dvb/version.h</emphasis> exists, which defines the
186constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document
187describes <emphasis role="tt">DVB_API_VERSION&#x00A0;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,
3hardware specific driver to a hardware independent demux layer. It is only of interest for
4DVB 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, /&#x22C6; Received Ok &#x22C6;/
19 DMX_LENGTH_ERROR, /&#x22C6; Incorrect length &#x22C6;/
20 DMX_OVERRUN_ERROR, /&#x22C6; Receiver ring buffer overrun &#x22C6;/
21 DMX_CRC_ERROR, /&#x22C6; Incorrect CRC &#x22C6;/
22 DMX_FRAME_ERROR, /&#x22C6; Frame alignment error &#x22C6;/
23 DMX_FIFO_ERROR, /&#x22C6; Receiver FIFO overrun &#x22C6;/
24 DMX_MISSED_ERROR /&#x22C6; Receiver missed packet &#x22C6;/
25 } dmx_success_t;
26</programlisting>
27
28</section>
29<section id="ts_filter_types">
30<title>TS filter types</title>
31 <programlisting>
32 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
33 /&#x22C6; TS packet reception &#x22C6;/
34 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
35
36 /&#x22C6; TS filter type for set_type() &#x22C6;/
37
38 #define TS_PACKET 1 /&#x22C6; send TS packets (188 bytes) to callback (default) &#x22C6;/
39 #define TS_PAYLOAD_ONLY 2 /&#x22C6; in case TS_PACKET is set, only send the TS
40 payload (&#x003C;=184 bytes per packet) to callback &#x22C6;/
41 #define TS_DECODER 4 /&#x22C6; send stream to built-in decoder (if present) &#x22C6;/
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, /&#x22C6; also send packets to audio decoder (if it exists) &#x22C6;/
53 DMX_TS_PES_VIDEO, /&#x22C6; ... &#x22C6;/
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
61should be kept identical) to the types in the demux device.
62</para>
63<programlisting>
64 struct dmx_ts_feed_s {
65 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
66 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
67 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
68 int (&#x22C6;set) (struct dmx_ts_feed_s&#x22C6; feed,
69 __u16 pid,
70 size_t callback_length,
71 size_t circular_buffer_size,
72 int descramble,
73 struct timespec timeout);
74 int (&#x22C6;start_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
75 int (&#x22C6;stop_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
76 int (&#x22C6;set_type) (struct dmx_ts_feed_s&#x22C6; 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 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
85 /&#x22C6; PES packet reception (not supported yet) &#x22C6;/
86 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
87
88 typedef struct dmx_pes_filter_s {
89 struct dmx_pes_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
90 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
91 } dmx_pes_filter_t;
92</programlisting>
93 <programlisting>
94 typedef struct dmx_pes_feed_s {
95 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
96 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
97 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
98 int (&#x22C6;set) (struct dmx_pes_feed_s&#x22C6; feed,
99 __u16 pid,
100 size_t circular_buffer_size,
101 int descramble,
102 struct timespec timeout);
103 int (&#x22C6;start_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
104 int (&#x22C6;stop_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
105 int (&#x22C6;allocate_filter) (struct dmx_pes_feed_s&#x22C6; feed,
106 dmx_pes_filter_t&#x22C6;&#x22C6; filter);
107 int (&#x22C6;release_filter) (struct dmx_pes_feed_s&#x22C6; feed,
108 dmx_pes_filter_t&#x22C6; 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&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
116 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
117 } dmx_section_filter_t;
118</programlisting>
119 <programlisting>
120 struct dmx_section_feed_s {
121 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
122 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
123 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
124 int (&#x22C6;set) (struct dmx_section_feed_s&#x22C6; feed,
125 __u16 pid,
126 size_t circular_buffer_size,
127 int descramble,
128 int check_crc);
129 int (&#x22C6;allocate_filter) (struct dmx_section_feed_s&#x22C6; feed,
130 dmx_section_filter_t&#x22C6;&#x22C6; filter);
131 int (&#x22C6;release_filter) (struct dmx_section_feed_s&#x22C6; feed,
132 dmx_section_filter_t&#x22C6; filter);
133 int (&#x22C6;start_filtering) (struct dmx_section_feed_s&#x22C6; feed);
134 int (&#x22C6;stop_filtering) (struct dmx_section_feed_s&#x22C6; feed);
135 };
136 typedef struct dmx_section_feed_s dmx_section_feed_t;
137
138 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
139 /&#x22C6; Callback functions &#x22C6;/
140 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
141
142 typedef int (&#x22C6;dmx_ts_cb) ( __u8 &#x22C6; buffer1,
143 size_t buffer1_length,
144 __u8 &#x22C6; buffer2,
145 size_t buffer2_length,
146 dmx_ts_feed_t&#x22C6; source,
147 dmx_success_t success);
148
149 typedef int (&#x22C6;dmx_section_cb) ( __u8 &#x22C6; buffer1,
150 size_t buffer1_len,
151 __u8 &#x22C6; buffer2,
152 size_t buffer2_len,
153 dmx_section_filter_t &#x22C6; source,
154 dmx_success_t success);
155
156 typedef int (&#x22C6;dmx_pes_cb) ( __u8 &#x22C6; buffer1,
157 size_t buffer1_len,
158 __u8 &#x22C6; buffer2,
159 size_t buffer2_len,
160 dmx_pes_filter_t&#x22C6; source,
161 dmx_success_t success);
162
163 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
164 /&#x22C6; DVB Front-End &#x22C6;/
165 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
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, /&#x22C6; DVB-ASI interface &#x22C6;/
174 DMX_MEMORY_FE
175 } dmx_frontend_source_t;
176
177 typedef struct {
178 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
179 char&#x22C6; id; /&#x22C6; Unique front-end identifier &#x22C6;/
180 char&#x22C6; vendor; /&#x22C6; Name of the front-end vendor &#x22C6;/
181 char&#x22C6; model; /&#x22C6; Name of the front-end model &#x22C6;/
182 struct list_head connectivity_list; /&#x22C6; List of front-ends that can
183 be connected to a particular
184 demux &#x22C6;/
185 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
186 dmx_frontend_source_t source;
187 } dmx_frontend_t;
188
189 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
190 /&#x22C6; MPEG-2 TS Demux &#x22C6;/
191 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
192
193 /&#x22C6;
194 &#x22C6; Flags OR'ed in the capabilites field of struct dmx_demux_s.
195 &#x22C6;/
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 /&#x22C6; write() available &#x22C6;/
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 /&#x22C6;
212 &#x22C6; DMX_FE_ENTRY(): Casts elements in the list of registered
213 &#x22C6; front-ends from the generic type struct list_head
214 &#x22C6; to the type &#x22C6; dmx_frontend_t
215 &#x22C6;.
216 &#x22C6;/
217
218 #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list)
219
220 struct dmx_demux_s {
221 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
222 char&#x22C6; id; /&#x22C6; Unique demux identifier &#x22C6;/
223 char&#x22C6; vendor; /&#x22C6; Name of the demux vendor &#x22C6;/
224 char&#x22C6; model; /&#x22C6; Name of the demux model &#x22C6;/
225 __u32 capabilities; /&#x22C6; Bitfield of capability flags &#x22C6;/
226 dmx_frontend_t&#x22C6; frontend; /&#x22C6; Front-end connected to the demux &#x22C6;/
227 struct list_head reg_list; /&#x22C6; List of registered demuxes &#x22C6;/
228 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
229 int users; /&#x22C6; Number of users &#x22C6;/
230 int (&#x22C6;open) (struct dmx_demux_s&#x22C6; demux);
231 int (&#x22C6;close) (struct dmx_demux_s&#x22C6; demux);
232 int (&#x22C6;write) (struct dmx_demux_s&#x22C6; demux, const char&#x22C6; buf, size_t count);
233 int (&#x22C6;allocate_ts_feed) (struct dmx_demux_s&#x22C6; demux,
234 dmx_ts_feed_t&#x22C6;&#x22C6; feed,
235 dmx_ts_cb callback);
236 int (&#x22C6;release_ts_feed) (struct dmx_demux_s&#x22C6; demux,
237 dmx_ts_feed_t&#x22C6; feed);
238 int (&#x22C6;allocate_pes_feed) (struct dmx_demux_s&#x22C6; demux,
239 dmx_pes_feed_t&#x22C6;&#x22C6; feed,
240 dmx_pes_cb callback);
241 int (&#x22C6;release_pes_feed) (struct dmx_demux_s&#x22C6; demux,
242 dmx_pes_feed_t&#x22C6; feed);
243 int (&#x22C6;allocate_section_feed) (struct dmx_demux_s&#x22C6; demux,
244 dmx_section_feed_t&#x22C6;&#x22C6; feed,
245 dmx_section_cb callback);
246 int (&#x22C6;release_section_feed) (struct dmx_demux_s&#x22C6; demux,
247 dmx_section_feed_t&#x22C6; feed);
248 int (&#x22C6;descramble_mac_address) (struct dmx_demux_s&#x22C6; demux,
249 __u8&#x22C6; buffer1,
250 size_t buffer1_length,
251 __u8&#x22C6; buffer2,
252 size_t buffer2_length,
253 __u16 pid);
254 int (&#x22C6;descramble_section_payload) (struct dmx_demux_s&#x22C6; demux,
255 __u8&#x22C6; buffer1,
256 size_t buffer1_length,
257 __u8&#x22C6; buffer2, size_t buffer2_length,
258 __u16 pid);
259 int (&#x22C6;add_frontend) (struct dmx_demux_s&#x22C6; demux,
260 dmx_frontend_t&#x22C6; frontend);
261 int (&#x22C6;remove_frontend) (struct dmx_demux_s&#x22C6; demux,
262 dmx_frontend_t&#x22C6; frontend);
263 struct list_head&#x22C6; (&#x22C6;get_frontends) (struct dmx_demux_s&#x22C6; demux);
264 int (&#x22C6;connect_frontend) (struct dmx_demux_s&#x22C6; demux,
265 dmx_frontend_t&#x22C6; frontend);
266 int (&#x22C6;disconnect_frontend) (struct dmx_demux_s&#x22C6; demux);
267
268
269 /&#x22C6; added because js cannot keep track of these himself &#x22C6;/
270 int (&#x22C6;get_pes_pids) (struct dmx_demux_s&#x22C6; demux, __u16 &#x22C6;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 /&#x22C6;
280 &#x22C6; DMX_DIR_ENTRY(): Casts elements in the list of registered
281 &#x22C6; demuxes from the generic type struct list_head&#x22C6; to the type dmx_demux_t
282 &#x22C6;.
283 &#x22C6;/
284
285 #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list)
286
287 int dmx_register_demux (dmx_demux_t&#x22C6; demux);
288 int dmx_unregister_demux (dmx_demux_t&#x22C6; demux);
289 struct list_head&#x22C6; 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
295MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers
296is 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
302role="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 &#x22C6;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
360role="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 &#x22C6;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
420role="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 &#x22C6;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
461the TS source of a demux and to manage the demux resources. When the demux
462client allocates a resource via the demux API, it receives a pointer to the API of that
463resource.
464</para>
465<para>Each demux receives its TS input from a DVB front-end or from memory, as set via the
466demux API. In a system with more than one front-end, the API can be used to select one of
467the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The
468demux API only controls front-ends regarding their connections with demuxes; the APIs
469used to set the other front-end parameters, such as tuning, are not defined in this
470document.
471</para>
472<para>The functions that implement the abstract interface demux should be defined static or
473module private and registered to the Demux Directory for external access. It is not necessary
474to implement every function in the demux_t struct, however (for example, a demux interface
475might support Section filtering, but not TS or PES filtering). The API client is expected to
476check the value of any function pointer before calling the function: the value of NULL means
477&#8220;function not available&#8221;.
478</para>
479<para>Whenever the functions of the demux API modify shared data, the possibilities of lost
480update and race condition problems should be addressed, e.g. by protecting parts of code with
481mutexes. 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
484kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if
485swapping is needed. For example, the Linux kernel calls the functions of a network device
486interface from a bottom half context. Thus, if a demux API function is called from network
487device 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&#x22C6; 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&#x22C6; 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&#x22C6; demux, const char&#x22C6; 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
679role="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&#x22C6; demux,
694 dmx_ts_feed_t&#x22C6;&#x22C6; 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
756role="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&#x22C6; demux,
770 dmx_ts_feed_t&#x22C6; 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
809role="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&#x22C6; demux,
828 dmx_section_feed_t &#x22C6;&#x22C6;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
891role="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&#x22C6; demux,
906 dmx_section_feed_t &#x22C6;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
946role="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&#x22C6; demux, __u8
962 &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;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
1044role="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 &#8220;plug-in&#8221; 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&#x22C6; demux,
1075 __u8 &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;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
1157role="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 &#x22C6;demux, dmx_frontend_t
1176 &#x22C6;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
1239role="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&#x22C6; demux,
1258 dmx_frontend_t&#x22C6; 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
1307role="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&#x22C6; get_frontends(dmx_demux_t&#x22C6; 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
1355role="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&#x22C6; demux,
1376 dmx_frontend_t&#x22C6; 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
1424role="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&#x22C6; 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
1472demux client. Unlike the other APIs, these API functions are provided by the client and called
1473from the demux code.
1474</para>
1475<para>The function pointers of this abstract interface are not packed into a structure as in the
1476other demux APIs, because the callback functions are registered and used independent
1477of each other. As an example, it is possible for the API client to provide several
1478callback functions for receiving TS packets and no callbacks for PES packets or
1479sections.
1480</para>
1481<para>The functions that implement the callback API need not be re-entrant: when a demux
1482driver calls one of these functions, the driver is not allowed to call the function again before
1483the original call returns. If a callback is triggered by a hardware interrupt, it is recommended
1484to use the Linux &#8220;bottom half&#8221; mechanism or start a tasklet instead of making the callback
1485function call directly from a hardware interrupt.
1486</para>
1487
1488<section
1489role="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 &#8221;wrapped&#8221; 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&#8212;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&#x22C6; buffer1, size_t buffer1_length,
1559 __u8&#x22C6; buffer2, size_t buffer2_length, dmx_ts_feed_t&#x22C6;
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
1630role="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&#x22C6; buffer1, size_t
1659 buffer1_length, __u8&#x22C6; buffer2, size_t
1660 buffer2_length, dmx_section_filter_t&#x22C6; 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.
1737Using this API, the client can set the filtering properties to start/stop filtering TS
1738packets on a particular TS feed. The API is defined as an abstract interface of the type
1739dmx_ts_feed_t.
1740</para>
1741<para>The functions that implement the interface should be defined static or module private. The
1742client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the
1743demux API.
1744</para>
1745
1746<section
1747role="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&#x22C6; 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
1850role="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&#x22C6; 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
1897role="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&#x22C6; 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
1943API, the client can set the properties of a section feed and to start/stop filtering. The API is
1944defined as an abstract interface of the type dmx_section_feed_t. The functions that implement
1945the interface should be defined static or module private. The client can get the handle of
1946a section feed API by calling the function allocate_section_feed() in the demux
1947API.
1948</para>
1949<para>On demux platforms that provide section filtering in hardware, the Section Feed API
1950implementation provides a software wrapper for the demux hardware. Other platforms may
1951support only PID filtering in hardware, requiring that TS packets are converted to sections in
1952software. In the latter case the Section Feed API implementation can be a client of the TS
1953Feed 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&#x22C6; 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
2057role="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 &#8211; 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&#x22C6; feed,
2101 dmx_section_filter_t&#x22C6;&#x22C6; 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
2149role="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&#x22C6; feed,
2165 dmx_section_filter_t&#x22C6; 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
2213role="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&#x22C6; 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
2263role="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&#x22C6; 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
3received via DVB into the Linux network protocol stack, e.g. for internet via satellite
4applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and
5and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your
6application.
7</para>
8<section id="dvb_net_types">
9<title>DVB Net Data Types</title>
10<para>To be written&#x2026;
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
3can be accessed through <emphasis role="tt">/dev/dvb/adapter0/video0</emphasis>. Data types and and
4ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your
5application.
6</para>
7<para>Note that the DVB video device only controls decoding of the MPEG video stream, not
8its presentation on the TV or computer screen. On PCs this is typically handled by an
9associated video4linux device, e.g. <emphasis role="tt">/dev/video</emphasis>, which allows scaling and defining output
10windows.
11</para>
12<para>Some DVB cards don&#8217;t have their own MPEG decoder, which results in the omission of
13the 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
16supported 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
32the 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
34VIDEO_GET_EVENT (??) which report about the display format of the current video
35stream.
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
42application has to specify how to handle the cropping of the picture. This can be done using
43the 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
59the following values, depending on whether we are replaying from an internal (demuxer) or
60external (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
69DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY
70is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
71call.
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
78state 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
92call.
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
108states 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
120stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is
121currently frozen, stopped, or being played back. The stream_source corresponds to the seleted
122source for the video stream. It can come either from the demultiplexer or from memory.
123The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently
124played video stream. Finally, display_format corresponds to the selected cropping
125mode in case the source video format is not the same as the format of the output
126device.
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
133following structure.
134</para>
135<programlisting>
136 /&#x22C6; pointer to and size of a single iframe in memory &#x22C6;/
137 struct video_still_picture {
138 char &#x22C6;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
147bits set according to the hardwares capabilities.
148</para>
149<programlisting>
150 /&#x22C6; bit definitions for capabilities: &#x22C6;/
151 /&#x22C6; can the hardware decode MPEG1 and/or MPEG2? &#x22C6;/
152 #define VIDEO_CAP_MPEG1 1
153 #define VIDEO_CAP_MPEG2 2
154 /&#x22C6; 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) &#x22C6;/
157 #define VIDEO_CAP_SYS 4
158 #define VIDEO_CAP_PROG 8
159 /&#x22C6; can the driver also handle SPU, NAVI and CSS encoded data?
160 (CSS API is not present yet) &#x22C6;/
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
170following 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
189call expects the following format for that information:
190</para>
191<programlisting>
192 typedef
193 struct video_highlight {
194 boolean active; /&#x22C6; 1=show highlight, 0=hide highlight &#x22C6;/
195 uint8_t contrast1; /&#x22C6; 7- 4 Pattern pixel contrast &#x22C6;/
196 /&#x22C6; 3- 0 Background pixel contrast &#x22C6;/
197 uint8_t contrast2; /&#x22C6; 7- 4 Emphasis pixel-2 contrast &#x22C6;/
198 /&#x22C6; 3- 0 Emphasis pixel-1 contrast &#x22C6;/
199 uint8_t color1; /&#x22C6; 7- 4 Pattern pixel color &#x22C6;/
200 /&#x22C6; 3- 0 Background pixel color &#x22C6;/
201 uint8_t color2; /&#x22C6; 7- 4 Emphasis pixel-2 color &#x22C6;/
202 /&#x22C6; 3- 0 Emphasis pixel-1 color &#x22C6;/
203 uint32_t ypos; /&#x22C6; 23-22 auto action mode &#x22C6;/
204 /&#x22C6; 21-12 start y &#x22C6;/
205 /&#x22C6; 9- 0 end y &#x22C6;/
206 uint32_t xpos; /&#x22C6; 23-22 button color number &#x22C6;/
207 /&#x22C6; 21-12 start x &#x22C6;/
208 /&#x22C6; 9- 0 end x &#x22C6;/
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
216following 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 &#x22C6;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
243VIDEO_GET_NAVI:
244</para>
245<programlisting>
246 typedef
247 struct video_navi_pack{
248 int length; /&#x22C6; 0 ... 1024 &#x22C6;/
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 /&#x22C6; bits: descr. &#x22C6;/
262 /&#x22C6; 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) &#x22C6;/
263 /&#x22C6; 13-12 TV system (0=525/60, 1=625/50) &#x22C6;/
264 /&#x22C6; 11-10 Aspect ratio (0=4:3, 3=16:9) &#x22C6;/
265 /&#x22C6; 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca &#x22C6;/
266 /&#x22C6; 7 line 21-1 data present in GOP (1=yes, 0=no) &#x22C6;/
267 /&#x22C6; 6 line 21-2 data present in GOP (1=yes, 0=no) &#x22C6;/
268 /&#x22C6; 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 &#x22C6;/
269 /&#x22C6; 2 source letterboxed (1=yes, 0=no) &#x22C6;/
270 /&#x22C6; 0 film/camera mode (0=camera, 1=film (625/50 only)) &#x22C6;/
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 &#x22C6;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 &#x22C6;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
492role="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
566role="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
619role="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
676role="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
729role="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
792role="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
865role="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 &#x22C6;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
933role="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 &#x22C6;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
1022role="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
1092role="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 &#x22C6;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
1162role="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
1236role="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
1310role="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 &#x22C6;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
1372role="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
1439role="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
1483role="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
1544role="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
1605role="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
1667role="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 &#x22C6;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
1727role="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 &#x22C6;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
1789role="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 &#x22C6;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&#8217;t handle SPU.</para>
1845</entry>
1846 </row></tbody></tgroup></informaltable>
1847
1848</section><section
1849role="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 &#x22C6;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
1911role="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/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&nbsp;<link linkend='v4l2-buf-type'>v4l2_buf_type</link>">
86<!ENTITY v4l2-colorspace "enum&nbsp;<link linkend='v4l2-colorspace'>v4l2_colorspace</link>">
87<!ENTITY v4l2-ctrl-type "enum&nbsp;<link linkend='v4l2-ctrl-type'>v4l2_ctrl_type</link>">
88<!ENTITY v4l2-exposure-auto-type "enum&nbsp;<link linkend='v4l2-exposure-auto-type'>v4l2_exposure_auto_type</link>">
89<!ENTITY v4l2-field "enum&nbsp;<link linkend='v4l2-field'>v4l2_field</link>">
90<!ENTITY v4l2-frmivaltypes "enum&nbsp;<link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link>">
91<!ENTITY v4l2-frmsizetypes "enum&nbsp;<link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link>">
92<!ENTITY v4l2-memory "enum&nbsp;<link linkend='v4l2-memory'>v4l2_memory</link>">
93<!ENTITY v4l2-mpeg-audio-ac3-bitrate "enum&nbsp;<link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link>">
94<!ENTITY v4l2-mpeg-audio-crc "enum&nbsp;<link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link>">
95<!ENTITY v4l2-mpeg-audio-emphasis "enum&nbsp;<link linkend='v4l2-mpeg-audio-emphasis'>v4l2_mpeg_audio_emphasis</link>">
96<!ENTITY v4l2-mpeg-audio-encoding "enum&nbsp;<link linkend='v4l2-mpeg-audio-encoding'>v4l2_mpeg_audio_encoding</link>">
97<!ENTITY v4l2-mpeg-audio-l1-bitrate "enum&nbsp;<link linkend='v4l2-mpeg-audio-l1-bitrate'>v4l2_mpeg_audio_l1_bitrate</link>">
98<!ENTITY v4l2-mpeg-audio-l2-bitrate "enum&nbsp;<link linkend='v4l2-mpeg-audio-l2-bitrate'>v4l2_mpeg_audio_l2_bitrate</link>">
99<!ENTITY v4l2-mpeg-audio-l3-bitrate "enum&nbsp;<link linkend='v4l2-mpeg-audio-l3-bitrate'>v4l2_mpeg_audio_l3_bitrate</link>">
100<!ENTITY v4l2-mpeg-audio-mode "enum&nbsp;<link linkend='v4l2-mpeg-audio-mode'>v4l2_mpeg_audio_mode</link>">
101<!ENTITY v4l2-mpeg-audio-mode-extension "enum&nbsp;<link linkend='v4l2-mpeg-audio-mode-extension'>v4l2_mpeg_audio_mode_extension</link>">
102<!ENTITY v4l2-mpeg-audio-sampling-freq "enum&nbsp;<link linkend='v4l2-mpeg-audio-sampling-freq'>v4l2_mpeg_audio_sampling_freq</link>">
103<!ENTITY chroma-spatial-filter-type "enum&nbsp;<link linkend='chroma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link>">
104<!ENTITY luma-spatial-filter-type "enum&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<link linkend='v4l2-mpeg-cx2341x-video-temporal-filter-mode'>v4l2_mpeg_cx2341x_video_temporal_filter_mode</link>">
108<!ENTITY v4l2-mpeg-stream-type "enum&nbsp;<link linkend='v4l2-mpeg-stream-type'>v4l2_mpeg_stream_type</link>">
109<!ENTITY v4l2-mpeg-stream-vbi-fmt "enum&nbsp;<link linkend='v4l2-mpeg-stream-vbi-fmt'>v4l2_mpeg_stream_vbi_fmt</link>">
110<!ENTITY v4l2-mpeg-video-aspect "enum&nbsp;<link linkend='v4l2-mpeg-video-aspect'>v4l2_mpeg_video_aspect</link>">
111<!ENTITY v4l2-mpeg-video-bitrate-mode "enum&nbsp;<link linkend='v4l2-mpeg-video-bitrate-mode'>v4l2_mpeg_video_bitrate_mode</link>">
112<!ENTITY v4l2-mpeg-video-encoding "enum&nbsp;<link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link>">
113<!ENTITY v4l2-power-line-frequency "enum&nbsp;<link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link>">
114<!ENTITY v4l2-priority "enum&nbsp;<link linkend='v4l2-priority'>v4l2_priority</link>">
115<!ENTITY v4l2-tuner-type "enum&nbsp;<link linkend='v4l2-tuner-type'>v4l2_tuner_type</link>">
116<!ENTITY v4l2-preemphasis "enum&nbsp;<link linkend='v4l2-preemphasis'>v4l2_preemphasis</link>">
117
118<!-- Structures -->
119<!ENTITY v4l2-audio "struct&nbsp;<link linkend='v4l2-audio'>v4l2_audio</link>">
120<!ENTITY v4l2-audioout "struct&nbsp;<link linkend='v4l2-audioout'>v4l2_audioout</link>">
121<!ENTITY v4l2-buffer "struct&nbsp;<link linkend='v4l2-buffer'>v4l2_buffer</link>">
122<!ENTITY v4l2-capability "struct&nbsp;<link linkend='v4l2-capability'>v4l2_capability</link>">
123<!ENTITY v4l2-captureparm "struct&nbsp;<link linkend='v4l2-captureparm'>v4l2_captureparm</link>">
124<!ENTITY v4l2-clip "struct&nbsp;<link linkend='v4l2-clip'>v4l2_clip</link>">
125<!ENTITY v4l2-control "struct&nbsp;<link linkend='v4l2-control'>v4l2_control</link>">
126<!ENTITY v4l2-crop "struct&nbsp;<link linkend='v4l2-crop'>v4l2_crop</link>">
127<!ENTITY v4l2-cropcap "struct&nbsp;<link linkend='v4l2-cropcap'>v4l2_cropcap</link>">
128<!ENTITY v4l2-dbg-chip-ident "struct&nbsp;<link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link>">
129<!ENTITY v4l2-dbg-match "struct&nbsp;<link linkend='v4l2-dbg-match'>v4l2_dbg_match</link>">
130<!ENTITY v4l2-dbg-register "struct&nbsp;<link linkend='v4l2-dbg-register'>v4l2_dbg_register</link>">
131<!ENTITY v4l2-enc-idx "struct&nbsp;<link linkend='v4l2-enc-idx'>v4l2_enc_idx</link>">
132<!ENTITY v4l2-enc-idx-entry "struct&nbsp;<link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link>">
133<!ENTITY v4l2-encoder-cmd "struct&nbsp;<link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link>">
134<!ENTITY v4l2-ext-control "struct&nbsp;<link linkend='v4l2-ext-control'>v4l2_ext_control</link>">
135<!ENTITY v4l2-ext-controls "struct&nbsp;<link linkend='v4l2-ext-controls'>v4l2_ext_controls</link>">
136<!ENTITY v4l2-fmtdesc "struct&nbsp;<link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link>">
137<!ENTITY v4l2-format "struct&nbsp;<link linkend='v4l2-format'>v4l2_format</link>">
138<!ENTITY v4l2-fract "struct&nbsp;<link linkend='v4l2-fract'>v4l2_fract</link>">
139<!ENTITY v4l2-framebuffer "struct&nbsp;<link linkend='v4l2-framebuffer'>v4l2_framebuffer</link>">
140<!ENTITY v4l2-frequency "struct&nbsp;<link linkend='v4l2-frequency'>v4l2_frequency</link>">
141<!ENTITY v4l2-frmival-stepwise "struct&nbsp;<link linkend='v4l2-frmival-stepwise'>v4l2_frmival_stepwise</link>">
142<!ENTITY v4l2-frmivalenum "struct&nbsp;<link linkend='v4l2-frmivalenum'>v4l2_frmivalenum</link>">
143<!ENTITY v4l2-frmsize-discrete "struct&nbsp;<link linkend='v4l2-frmsize-discrete'>v4l2_frmsize_discrete</link>">
144<!ENTITY v4l2-frmsize-stepwise "struct&nbsp;<link linkend='v4l2-frmsize-stepwise'>v4l2_frmsize_stepwise</link>">
145<!ENTITY v4l2-frmsizeenum "struct&nbsp;<link linkend='v4l2-frmsizeenum'>v4l2_frmsizeenum</link>">
146<!ENTITY v4l2-hw-freq-seek "struct&nbsp;<link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link>">
147<!ENTITY v4l2-input "struct&nbsp;<link linkend='v4l2-input'>v4l2_input</link>">
148<!ENTITY v4l2-jpegcompression "struct&nbsp;<link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link>">
149<!ENTITY v4l2-modulator "struct&nbsp;<link linkend='v4l2-modulator'>v4l2_modulator</link>">
150<!ENTITY v4l2-mpeg-vbi-fmt-ivtv "struct&nbsp;<link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link>">
151<!ENTITY v4l2-output "struct&nbsp;<link linkend='v4l2-output'>v4l2_output</link>">
152<!ENTITY v4l2-outputparm "struct&nbsp;<link linkend='v4l2-outputparm'>v4l2_outputparm</link>">
153<!ENTITY v4l2-pix-format "struct&nbsp;<link linkend='v4l2-pix-format'>v4l2_pix_format</link>">
154<!ENTITY v4l2-queryctrl "struct&nbsp;<link linkend='v4l2-queryctrl'>v4l2_queryctrl</link>">
155<!ENTITY v4l2-querymenu "struct&nbsp;<link linkend='v4l2-querymenu'>v4l2_querymenu</link>">
156<!ENTITY v4l2-rect "struct&nbsp;<link linkend='v4l2-rect'>v4l2_rect</link>">
157<!ENTITY v4l2-requestbuffers "struct&nbsp;<link linkend='v4l2-requestbuffers'>v4l2_requestbuffers</link>">
158<!ENTITY v4l2-sliced-vbi-cap "struct&nbsp;<link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link>">
159<!ENTITY v4l2-sliced-vbi-data "struct&nbsp;<link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link>">
160<!ENTITY v4l2-sliced-vbi-format "struct&nbsp;<link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link>">
161<!ENTITY v4l2-standard "struct&nbsp;<link linkend='v4l2-standard'>v4l2_standard</link>">
162<!ENTITY v4l2-streamparm "struct&nbsp;<link linkend='v4l2-streamparm'>v4l2_streamparm</link>">
163<!ENTITY v4l2-timecode "struct&nbsp;<link linkend='v4l2-timecode'>v4l2_timecode</link>">
164<!ENTITY v4l2-tuner "struct&nbsp;<link linkend='v4l2-tuner'>v4l2_tuner</link>">
165<!ENTITY v4l2-vbi-format "struct&nbsp;<link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>">
166<!ENTITY v4l2-window "struct&nbsp;<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&nbsp;<link linkend='v4l2-buf-type'>v4l2_buf_type</link></primaryie></indexentry>
6<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-colorspace'>v4l2_colorspace</link></primaryie></indexentry>
7<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-ctrl-type'>v4l2_ctrl_type</link></primaryie></indexentry>
8<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-exposure-auto-type'>v4l2_exposure_auto_type</link></primaryie></indexentry>
9<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-field'>v4l2_field</link></primaryie></indexentry>
10<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link></primaryie></indexentry>
11<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link></primaryie></indexentry>
12<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-memory'>v4l2_memory</link></primaryie></indexentry>
13<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link></primaryie></indexentry>
14<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link></primaryie></indexentry>
15<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-emphasis'>v4l2_mpeg_audio_emphasis</link></primaryie></indexentry>
16<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-encoding'>v4l2_mpeg_audio_encoding</link></primaryie></indexentry>
17<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-l1-bitrate'>v4l2_mpeg_audio_l1_bitrate</link></primaryie></indexentry>
18<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-l2-bitrate'>v4l2_mpeg_audio_l2_bitrate</link></primaryie></indexentry>
19<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-l3-bitrate'>v4l2_mpeg_audio_l3_bitrate</link></primaryie></indexentry>
20<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-mode'>v4l2_mpeg_audio_mode</link></primaryie></indexentry>
21<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-mode-extension'>v4l2_mpeg_audio_mode_extension</link></primaryie></indexentry>
22<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-audio-sampling-freq'>v4l2_mpeg_audio_sampling_freq</link></primaryie></indexentry>
23<indexentry><primaryie>enum&nbsp;<link linkend='chroma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link></primaryie></indexentry>
24<indexentry><primaryie>enum&nbsp;<link linkend='luma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link></primaryie></indexentry>
25<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-cx2341x-video-median-filter-type'>v4l2_mpeg_cx2341x_video_median_filter_type</link></primaryie></indexentry>
26<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-cx2341x-video-spatial-filter-mode'>v4l2_mpeg_cx2341x_video_spatial_filter_mode</link></primaryie></indexentry>
27<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-cx2341x-video-temporal-filter-mode'>v4l2_mpeg_cx2341x_video_temporal_filter_mode</link></primaryie></indexentry>
28<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-stream-type'>v4l2_mpeg_stream_type</link></primaryie></indexentry>
29<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-stream-vbi-fmt'>v4l2_mpeg_stream_vbi_fmt</link></primaryie></indexentry>
30<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-video-aspect'>v4l2_mpeg_video_aspect</link></primaryie></indexentry>
31<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-video-bitrate-mode'>v4l2_mpeg_video_bitrate_mode</link></primaryie></indexentry>
32<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link></primaryie></indexentry>
33<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link></primaryie></indexentry>
34<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-priority'>v4l2_priority</link></primaryie></indexentry>
35<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-tuner-type'>v4l2_tuner_type</link></primaryie></indexentry>
36<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-preemphasis'>v4l2_preemphasis</link></primaryie></indexentry>
37<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-audio'>v4l2_audio</link></primaryie></indexentry>
38<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-audioout'>v4l2_audioout</link></primaryie></indexentry>
39<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-buffer'>v4l2_buffer</link></primaryie></indexentry>
40<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-capability'>v4l2_capability</link></primaryie></indexentry>
41<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-captureparm'>v4l2_captureparm</link></primaryie></indexentry>
42<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-clip'>v4l2_clip</link></primaryie></indexentry>
43<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-control'>v4l2_control</link></primaryie></indexentry>
44<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-crop'>v4l2_crop</link></primaryie></indexentry>
45<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-cropcap'>v4l2_cropcap</link></primaryie></indexentry>
46<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link></primaryie></indexentry>
47<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dbg-match'>v4l2_dbg_match</link></primaryie></indexentry>
48<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dbg-register'>v4l2_dbg_register</link></primaryie></indexentry>
49<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-enc-idx'>v4l2_enc_idx</link></primaryie></indexentry>
50<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link></primaryie></indexentry>
51<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link></primaryie></indexentry>
52<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-ext-control'>v4l2_ext_control</link></primaryie></indexentry>
53<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-ext-controls'>v4l2_ext_controls</link></primaryie></indexentry>
54<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link></primaryie></indexentry>
55<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-format'>v4l2_format</link></primaryie></indexentry>
56<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-fract'>v4l2_fract</link></primaryie></indexentry>
57<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-framebuffer'>v4l2_framebuffer</link></primaryie></indexentry>
58<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frequency'>v4l2_frequency</link></primaryie></indexentry>
59<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frmival-stepwise'>v4l2_frmival_stepwise</link></primaryie></indexentry>
60<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frmivalenum'>v4l2_frmivalenum</link></primaryie></indexentry>
61<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frmsize-discrete'>v4l2_frmsize_discrete</link></primaryie></indexentry>
62<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frmsize-stepwise'>v4l2_frmsize_stepwise</link></primaryie></indexentry>
63<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-frmsizeenum'>v4l2_frmsizeenum</link></primaryie></indexentry>
64<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link></primaryie></indexentry>
65<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-input'>v4l2_input</link></primaryie></indexentry>
66<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link></primaryie></indexentry>
67<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-modulator'>v4l2_modulator</link></primaryie></indexentry>
68<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link></primaryie></indexentry>
69<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-output'>v4l2_output</link></primaryie></indexentry>
70<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-outputparm'>v4l2_outputparm</link></primaryie></indexentry>
71<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-pix-format'>v4l2_pix_format</link></primaryie></indexentry>
72<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-queryctrl'>v4l2_queryctrl</link></primaryie></indexentry>
73<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-querymenu'>v4l2_querymenu</link></primaryie></indexentry>
74<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-rect'>v4l2_rect</link></primaryie></indexentry>
75<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-requestbuffers'>v4l2_requestbuffers</link></primaryie></indexentry>
76<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link></primaryie></indexentry>
77<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link></primaryie></indexentry>
78<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link></primaryie></indexentry>
79<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-standard'>v4l2_standard</link></primaryie></indexentry>
80<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-streamparm'>v4l2_streamparm</link></primaryie></indexentry>
81<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-timecode'>v4l2_timecode</link></primaryie></indexentry>
82<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-tuner'>v4l2_tuner</link></primaryie></indexentry>
83<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-vbi-format'>v4l2_vbi_format</link></primaryie></indexentry>
84<indexentry><primaryie>struct&nbsp;<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.&nbsp;g.">
8<!ENTITY ie "i.&nbsp;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
38this document under the terms of the GNU Free Documentation License,
39Version 1.1 or any later version published by the Free Software
40Foundation. 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>
837Since the driver does not declare any device ids, it will not get loaded
838automatically and will not automatically bind to any devices, you must load it
839and allocate id to the driver yourself. For example:
840 <programlisting>
841 modprobe uio_pci_generic
842 echo &quot;8086 10f5&quot; &gt; /sys/bus/pci/drivers/uio_pci_generic/new_id
843 </programlisting>
844 </para>
845 <para>
846If there already is a hardware specific kernel driver for your device, the
847generic driver still won't bind to it, in this case if you want to use the
848generic driver (why would you?) you'll have to manually unbind the hardware
849specific driver and bind the generic driver, like this:
850 <programlisting>
851 echo -n 0000:00:19.0 &gt; /sys/bus/pci/drivers/e1000e/unbind
852 echo -n 0000:00:19.0 &gt; /sys/bus/pci/drivers/uio_pci_generic/bind
853 </programlisting>
854 </para>
855 <para>
856You can verify that the device has been bound to the driver
857by 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>
861Which if successful should print
862 <programlisting>
863 .../0000:00:19.0/driver -&gt; ../../../bus/pci/drivers/uio_pci_generic
864 </programlisting>
865Note that the generic driver will not bind to old PCI 2.2 devices.
866If binding the device failed, run the following command:
867 <programlisting>
868 dmesg
869 </programlisting>
870and 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>
877Interrupts are handled using the Interrupt Disable bit in the PCI command
878register and Interrupt Status bit in the PCI status register. All devices
879compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should
880support these bits. uio_pci_generic detects this support, and won't bind to
881devices which do not support the Interrupt Disable Bit in the command register.
882 </para>
883 <para>
884On each interrupt, uio_pci_generic sets the Interrupt Disable bit.
885This prevents the device from generating further interrupts
886until the bit is cleared. The userspace driver should clear this
887bit 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>
893Userspace driver can use pci sysfs interface, or the
894libpci libray that wraps it, to talk to the device and to
895re-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>
901Here is some sample userspace driver code using uio_pci_generic:
902<programlisting>
903#include &lt;stdlib.h&gt;
904#include &lt;stdio.h&gt;
905#include &lt;unistd.h&gt;
906#include &lt;sys/types.h&gt;
907#include &lt;sys/stat.h&gt;
908#include &lt;fcntl.h&gt;
909#include &lt;errno.h&gt;
910
911int 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(&quot;/dev/uio0&quot;, O_RDONLY);
921 if (uiofd &lt; 0) {
922 perror(&quot;uio open:&quot;);
923 return errno;
924 }
925 configfd = open(&quot;/sys/class/uio/uio0/device/config&quot;, O_RDWR);
926 if (uiofd &lt; 0) {
927 perror(&quot;config open:&quot;);
928 return errno;
929 }
930
931 /* Read and cache command value */
932 err = pread(configfd, &amp;command_high, 1, 5);
933 if (err != 1) {
934 perror(&quot;command config read:&quot;);
935 return errno;
936 }
937 command_high &amp;= ~0x4;
938
939 for(i = 0;; ++i) {
940 /* Print out a message, for debugging. */
941 if (i == 0)
942 fprintf(stderr, &quot;Started uio test driver.\n&quot;);
943 else
944 fprintf(stderr, &quot;Interrupts: %d\n&quot;, 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, &amp;command_high, 1, 5);
953 if (err != 1) {
954 perror(&quot;config write:&quot;);
955 break;
956 }
957
958 /* Wait for next interrupt. */
959 err = read(uiofd, &amp;icount, 4);
960 if (err != 4) {
961 perror(&quot;uio read:&quot;);
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&nbsp;608-B</abbrev>
6 <authorgroup>
7 <corpauthor>Electronic Industries Alliance (<ulink
8url="http://www.eia.org">http://www.eia.org</ulink>)</corpauthor>
9 </authorgroup>
10 <title>EIA 608-B "Recommended Practice for Line 21 Data
11Service"</title>
12 </biblioentry>
13
14 <biblioentry id="en300294">
15 <abbrev>EN&nbsp;300&nbsp;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&nbsp;300&nbsp;231</abbrev>
26 <authorgroup>
27 <corpauthor>European Telecommunication Standards Institute
28(<ulink
29url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
30 </authorgroup>
31 <title>ETS 300 231 "Specification of the domestic video
32Programme Delivery Control system (PDC)"</title>
33 </biblioentry>
34
35 <biblioentry id="ets300706">
36 <abbrev>ETS&nbsp;300&nbsp;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&nbsp;13818-1</abbrev>
46 <authorgroup>
47 <corpauthor>International Telecommunication Union (<ulink
48url="http://www.itu.ch">http://www.itu.ch</ulink>), International
49Organisation for Standardisation (<ulink
50url="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
53technology &mdash; Generic coding of moving pictures and associated
54audio information: Systems"</title>
55 </biblioentry>
56
57 <biblioentry id="mpeg2part2">
58 <abbrev>ISO&nbsp;13818-2</abbrev>
59 <authorgroup>
60 <corpauthor>International Telecommunication Union (<ulink
61url="http://www.itu.ch">http://www.itu.ch</ulink>), International
62Organisation for Standardisation (<ulink
63url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor>
64 </authorgroup>
65 <title>ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information
66technology &mdash; Generic coding of moving pictures and associated
67audio information: Video"</title>
68 </biblioentry>
69
70 <biblioentry id="itu470">
71 <abbrev>ITU&nbsp;BT.470</abbrev>
72 <authorgroup>
73 <corpauthor>International Telecommunication Union (<ulink
74url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
75 </authorgroup>
76 <title>ITU-R Recommendation BT.470-6 "Conventional Television
77Systems"</title>
78 </biblioentry>
79
80 <biblioentry id="itu601">
81 <abbrev>ITU&nbsp;BT.601</abbrev>
82 <authorgroup>
83 <corpauthor>International Telecommunication Union (<ulink
84url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
85 </authorgroup>
86 <title>ITU-R Recommendation BT.601-5 "Studio Encoding Parameters
87of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect
88Ratios"</title>
89 </biblioentry>
90
91 <biblioentry id="itu653">
92 <abbrev>ITU&nbsp;BT.653</abbrev>
93 <authorgroup>
94 <corpauthor>International Telecommunication Union (<ulink
95url="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&nbsp;BT.709</abbrev>
102 <authorgroup>
103 <corpauthor>International Telecommunication Union (<ulink
104url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
105 </authorgroup>
106 <title>ITU-R Recommendation BT.709-5 "Parameter values for the
107HDTV standards for production and international programme
108exchange"</title>
109 </biblioentry>
110
111 <biblioentry id="itu1119">
112 <abbrev>ITU&nbsp;BT.1119</abbrev>
113 <authorgroup>
114 <corpauthor>International Telecommunication Union (<ulink
115url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
116 </authorgroup>
117 <title>ITU-R Recommendation BT.1119 "625-line
118television Wide Screen Signalling (WSS)"</title>
119 </biblioentry>
120
121 <biblioentry id="jfif">
122 <abbrev>JFIF</abbrev>
123 <authorgroup>
124 <corpauthor>Independent JPEG Group (<ulink
125url="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&nbsp;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
138Control Code"</title>
139 </biblioentry>
140
141 <biblioentry id="smpte170m">
142 <abbrev>SMPTE&nbsp;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
148Signal - NTSC for Studio Applications"</title>
149 </biblioentry>
150
151 <biblioentry id="smpte240m">
152 <abbrev>SMPTE&nbsp;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 -
1581125-Line High-Definition Production"</title>
159 </biblioentry>
160
161 <biblioentry id="en50067">
162 <abbrev>EN&nbsp;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
168in 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 <!--
183Local Variables:
184mode: sgml
185sgml-parent-document: "v4l2.sgml"
186indent-tabs-mode: nil
187End:
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 &lt;stdio.h&gt;
12#include &lt;stdlib.h&gt;
13#include &lt;string.h&gt;
14#include &lt;assert.h&gt;
15
16#include &lt;getopt.h&gt; /* getopt_long() */
17
18#include &lt;fcntl.h&gt; /* low-level i/o */
19#include &lt;unistd.h&gt;
20#include &lt;errno.h&gt;
21#include &lt;sys/stat.h&gt;
22#include &lt;sys/types.h&gt;
23#include &lt;sys/time.h&gt;
24#include &lt;sys/mman.h&gt;
25#include &lt;sys/ioctl.h&gt;
26
27#include &lt;linux/videodev2.h&gt;
28
29#define CLEAR(x) memset(&amp;(x), 0, sizeof(x))
30
31enum io_method {
32 IO_METHOD_READ,
33 IO_METHOD_MMAP,
34 IO_METHOD_USERPTR,
35};
36
37struct buffer {
38 void *start;
39 size_t length;
40};
41
42static char *dev_name;
43static enum io_method io = IO_METHOD_MMAP;
44static int fd = -1;
45struct buffer *buffers;
46static unsigned int n_buffers;
47static int out_buf;
48static int force_format;
49static int frame_count = 70;
50
51static 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
57static 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 &amp;&amp; EINTR == errno);
64
65 return r;
66}
67
68static 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
78static 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, &amp;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 &lt; n_buffers);
125
126 process_image(buffers[buf.index].start, buf.bytesused);
127
128 if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;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, &amp;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 &lt; n_buffers; ++i)
154 if (buf.m.userptr == (unsigned long)buffers[i].start
155 &amp;&amp; buf.length == buffers[i].length)
156 break;
157
158 assert(i &lt; n_buffers);
159
160 process_image((void *)buf.m.userptr, buf.bytesused);
161
162 if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
163 errno_exit("VIDIOC_QBUF");
164 break;
165 }
166
167 return 1;
168}
169
170static void mainloop(void)
171{
172 unsigned int count;
173
174 count = frame_count;
175
176 while (count-- &gt; 0) {
177 for (;;) {
178 fd_set fds;
179 struct timeval tv;
180 int r;
181
182 FD_ZERO(&amp;fds);
183 FD_SET(fd, &amp;fds);
184
185 /* Timeout. */
186 tv.tv_sec = 2;
187 tv.tv_usec = 0;
188
189 r = select(fd + 1, &amp;fds, NULL, NULL, &amp;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
209static 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, &amp;type))
222 errno_exit("VIDIOC_STREAMOFF");
223 break;
224 }
225}
226
227static 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 &lt; 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, &amp;buf))
247 errno_exit("VIDIOC_QBUF");
248 }
249 type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
250 if (-1 == xioctl(fd, VIDIOC_STREAMON, &amp;type))
251 errno_exit("VIDIOC_STREAMON");
252 break;
253
254 case IO_METHOD_USERPTR:
255 for (i = 0; i &lt; 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, &amp;buf))
266 errno_exit("VIDIOC_QBUF");
267 }
268 type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
269 if (-1 == xioctl(fd, VIDIOC_STREAMON, &amp;type))
270 errno_exit("VIDIOC_STREAMON");
271 break;
272 }
273}
274
275static 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 &lt; 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 &lt; n_buffers; ++i)
292 free(buffers[i].start);
293 break;
294 }
295
296 free(buffers);
297}
298
299static 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
317static 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, &amp;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 &lt; 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 &lt; 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, &amp;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
375static 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, &amp;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 &lt; 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
413static 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, &amp;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 &amp; 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 &amp; 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 &amp; 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, &amp;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, &amp;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, &amp;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, &amp;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 &lt; min)
505 fmt.fmt.pix.bytesperline = min;
506 min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
507 if (fmt.fmt.pix.sizeimage &lt; 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
525static void close_device(void)
526{
527 if (-1 == close(fd))
528 errno_exit("close");
529
530 fd = -1;
531}
532
533static void open_device(void)
534{
535 struct stat st;
536
537 if (-1 == stat(dev_name, &amp;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
557static 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
575static const char short_options[] = "d:hmruofc:";
576
577static const struct option
578long_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
590int 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, &amp;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
4steps:</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
12input, video standard, picture brightness a.&nbsp;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
29order. It depends on the V4L2 device type, you can read about the
30details in <xref linkend="devices" />. In this chapter we will discuss
31the 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
40manually by the system administrator or automatically when a device is
41first opened. The driver modules plug into the "videodev" kernel
42module. It provides helper functions and a common application
43interface specified in this document.</para>
44
45 <para>Each driver thus loaded registers one or more device nodes
46with major number 81 and a minor number between 0 and 255. Assigning
47minor numbers to V4L2 devices is entirely up to the system administrator,
48this is primarily intended to solve conflicts between devices.<footnote>
49 <para>Access permissions are associated with character
50device special files, hence we must ensure device numbers cannot
51change with the module load order. To this end minor numbers are no
52longer automatically assigned by the "videodev" module as in V4L but
53requested by the driver. The defaults will suffice for most people
54unless two drivers compete for the same minor numbers.</para>
55 </footnote> The module options to select minor numbers are named
56after the device special file with a "_nr" suffix. For example "video_nr"
57for <filename>/dev/video</filename> video capture devices. The number is
58an 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
61where named after the device special file with a "unit_" prefix, expressing
62the minor number itself, not an offset. Rationale for this change is unknown.
63Lastly the naming and semantics are just a convention among driver writers,
64the point to note is that minor numbers are not supposed to be hardcoded
65into drivers.</para>
66 </footnote> When the driver supports multiple devices of the same
67type more than one minor number can be assigned, separated by commas:
68<informalexample>
69 <screen>
70&gt; 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
74written as: <informalexample>
75 <screen>
76alias char-major-81-0 mydriver
77alias char-major-81-1 mydriver
78alias char-major-81-64 mydriver <co id="alias" />
79options 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
84special 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
89minor number 0 and 1 (base number is 0), the first two radio device
90with minor number 64 and 65 (base 64).</para>
91 </callout>
92 </calloutlist>
93 </informalexample> When no minor number is given as module
94option the driver supplies a default. <xref linkend="devices" />
95recommends the base minor numbers to be used for the various device
96types. Obviously minor numbers must be unique. When the number is
97already in use the <emphasis>offending device</emphasis> will not be
98registered. <!-- Blessed by Linus Torvalds on
99linux-kernel@vger.kernel.org, 2002-11-20. --></para>
100
101 <para>By convention system administrators create various
102character device special files with these major and minor numbers in
103the <filename>/dev</filename> directory. The names recomended for the
104different 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
109devices cannot be opened by major and minor number. That means
110applications cannot <emphasis>reliable</emphasis> scan for loaded or
111installed drivers. The user must enter a device name, or the
112application can try the conventional device names.</para>
113
114 <para>Under the device filesystem (devfs) the minor number
115options are ignored. V4L2 drivers (or by proxy the "videodev" module)
116automatically create the required device files in the
117<filename>/dev/v4l</filename> directory using the conventional device
118names 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
125video capturing, video overlay and VBI capturing are related because
126these functions share, amongst other, the same video input and tuner
127frequency. V4L and earlier versions of V4L2 used the same device name
128and minor number for video capturing and overlay, but different ones
129for VBI. Experience showed this approach has several problems<footnote>
130 <para>Given a device file name one cannot reliable find
131related devices. For once names are arbitrary and in a system with
132multiple 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
136device file with a particular major and minor number.</para>
137 </footnote>, and to make things worse the V4L videodev module
138used to prohibit multiple opens of a device.</para>
139
140 <para>As a remedy the present version of the V4L2 API relaxed the
141concept of device types with specific names and minor numbers. For
142compatibility with old applications drivers must still register different
143minor numbers to assign a default function to the device. But if related
144functions are supported by the driver they must be available under all
145registered minor numbers. The desired function can be selected after
146opening the device as described in <xref linkend="devices" />.</para>
147
148 <para>Imagine a driver supporting video capturing, video
149overlay, raw VBI capturing, and FM radio reception. It registers three
150devices with minor number 0, 64 and 224 (this numbering scheme is
151inherited 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
154select any one of the video capturing, overlay or VBI capturing
155functions. Without programming (e.&nbsp;g. reading from the device
156with <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,
160unrelated to the video functions. Being unrelated does not imply the
161devices can be used at the same time, however. The &func-open;
162function may very well return an &EBUSY;.</para>
163
164 <para>Besides video input or output the hardware may also
165support audio sampling or playback. If so, these functions are
166implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
167audio mixer. The V4L2 API makes no provisions yet to find these
168related devices. If you have an idea please write to the linux-media
169mailing 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.
176When this is supported by the driver, users can for example start a
177"panel" application to change controls like brightness or audio
178volume, while another application captures video and audio. In other words, panel
179applications are comparable to an OSS or ALSA audio mixer application.
180When a device supports multiple functions like capturing and overlay
181<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
182use of the device by forked processes or specialized applications.</para>
183
184 <para>Multiple opens are optional, although drivers should
185permit at least concurrent accesses without data exchange, &ie; panel
186applications. This implies &func-open; can return an &EBUSY; when the
187device is already in use, as well as &func-ioctl; functions initiating
188data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
189and &func-write; functions.</para>
190
191 <para>Mere opening a V4L2 device does not grant exclusive
192access.<footnote>
193 <para>Drivers could recognize the
194<constant>O_EXCL</constant> open flag. Presently this is not required,
195so applications cannot know if it really works.</para>
196 </footnote> Initiating data exchange however assigns the right
197to read or write the requested type of data, and to change related
198properties, to this file descriptor. Applications can request
199additional 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
207reading or writing the same data stream on a device by copying
208buffers, time multiplexing or similar means. This is better handled by
209a proxy application in user space. When the driver supports stream
210sharing anyway it must be implemented transparently. The V4L2 API does
211not specify how conflicts are solved. <!-- For example O_EXCL when the
212application does not want to be preempted, PROT_READ mmapped buffers
213which can be mapped twice, what happens when image formats do not
214match 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
222programmed using the &func-ioctl; function as explained in the
223following 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
231aspects of the API are equally applicable to all types of devices.
232Furthermore devices of the same type have different capabilities and
233this specification permits the omission of a few complicated and less
234important parts of the API.</para>
235
236 <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel
237device is compatible with this specification, and to query the <link
238linkend="devices">functions</link> and <link linkend="io">I/O
239methods</link> supported by the device. Other features can be queried
240by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
241to learn about the number, types and names of video connectors on the
242device. Although abstraction is a major objective of this API, the
243ioctl also allows driver specific applications to reliable identify
244the driver.</para>
245
246 <para>All V4L2 drivers must support
247<constant>VIDIOC_QUERYCAP</constant>. Applications should always call
248this 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
255desirable to assign them different priorities. Contrary to the
256traditional "rm -rf /" school of thought a video recording application
257could for example block other applications from changing video
258controls or switching the current TV channel. Another objective is to
259permit low priority applications working in background, which can be
260preempted by user controlled applications and automatically regain
261control of the device at a later time.</para>
262
263 <para>Since these features cannot be implemented entirely in user
264space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
265ioctls to request and query the access priority associate with a file
266descriptor. Opening a device assigns a medium priority, compatible
267with earlier versions of V4L2 and drivers not supporting these ioctls.
268Applications requiring a different priority will usually call
269<constant>VIDIOC_S_PRIORITY</constant> after verifying the device with
270the &VIDIOC-QUERYCAP; ioctl.</para>
271
272 <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
273return an &EBUSY; after another application obtained higher priority.
274An event mechanism to notify applications about asynchronous property
275changes 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
282device. These can be for example RF connectors (antenna/cable), CVBS
283a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI
284capture devices have inputs, output devices have outputs, at least one
285each. Radio devices have no video inputs or outputs.</para>
286
287 <para>To learn about the number and attributes of the
288available 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>
291ioctl also contains signal status information applicable when the
292current video input is queried.</para>
293
294 <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the
295index of the current video input or output. To select a different
296input or output applications call the &VIDIOC-S-INPUT; and
297&VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls
298when the device has one or more inputs, all the output ioctls when the
299device 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;
323int index;
324
325if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;index)) {
326 perror ("VIDIOC_G_INPUT");
327 exit (EXIT_FAILURE);
328}
329
330memset (&amp;input, 0, sizeof (input));
331input.index = index;
332
333if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
334 perror ("VIDIOC_ENUMINPUT");
335 exit (EXIT_FAILURE);
336}
337
338printf ("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>
346int index;
347
348index = 0;
349
350if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &amp;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
362device. Video capture devices have inputs, output devices have
363outputs, zero or more each. Radio devices have no audio inputs or
364outputs. They have exactly one tuner which in fact
365<emphasis>is</emphasis> an audio source, but this API associates
366tuners with video inputs or outputs only, and radio devices have
367none of these.<footnote>
368 <para>Actually &v4l2-audio; ought to have a
369<structfield>tuner</structfield> field like &v4l2-input;, not only
370making the API more consistent but also permitting radio devices with
371multiple tuners.</para>
372 </footnote> A connector on a TV card to loop back the received
373audio signal to a sound card is not considered an audio output.</para>
374
375 <para>Audio and video inputs and outputs are associated. Selecting
376a video source also selects an audio source. This is most evident when
377the video and audio source is a tuner. Further audio connectors can
378combine with more than one video input or output. Assumed two
379composite video inputs and two audio inputs exist, there may be up to
380four valid combinations. The relation of video and audio connectors
381is defined in the <structfield>audioset</structfield> field of the
382respective &v4l2-input; or &v4l2-output;, where each bit represents
383the index number, starting at zero, of one audio input or output.</para>
384
385 <para>To learn about the number and attributes of the
386available 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
389also contains signal status information applicable when the current
390audio input is queried.</para>
391
392 <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report
393the current audio input and output, respectively. Note that, unlike
394&VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
395as <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
399applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
400output (which presently has no changeable properties) applications
401call the &VIDIOC-S-AUDOUT; ioctl.</para>
402
403 <para>Drivers must implement all input ioctls when the device
404has one or more inputs, all output ioctls when the device has one
405or more outputs. When the device has any audio inputs or outputs the
406driver 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
415memset (&amp;audio, 0, sizeof (audio));
416
417if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
418 perror ("VIDIOC_G_AUDIO");
419 exit (EXIT_FAILURE);
420}
421
422printf ("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
432memset (&amp;audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
433
434audio.index = 0;
435
436if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &amp;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
451demodulating a RF signal. Each tuner is associated with one or more
452video inputs, depending on the number of RF connectors on the tuner.
453The <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
457the tuner.</para>
458
459 <para>Radio devices have exactly one tuner with index zero, no
460video 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
465contains signal status information applicable when the tuner of the
466current video input, or a radio tuner is queried. Note that
467<constant>VIDIOC_S_TUNER</constant> does not switch the current tuner,
468when there is more than one at all. The tuner is solely determined by
469the current video input. Drivers must support both ioctls and set the
470<constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability;
471returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
472more tuners.</para>
473 </section>
474
475 <section>
476 <title>Modulators</title>
477
478 <para>Video output devices can have one or more modulators, uh,
479modulating a video signal for radiation or connection to the antenna
480input of a TV set or video recorder. Each modulator is associated with
481one or more video outputs, depending on the number of RF connectors on
482the modulator. The <structfield>type</structfield> field of the
483respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
484set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its
485<structfield>modulator</structfield> field contains the index number
486of the modulator. This specification does not define radio output
487devices.</para>
488
489 <para>To query and change modulator properties applications use
490the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
491<constant>VIDIOC_S_MODULATOR</constant> does not switch the current
492modulator, when there is more than one at all. The modulator is solely
493determined by the current video output. Drivers must support both
494ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
495the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
496device 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
503applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
504ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
505are used for TV and radio devices alike. Drivers must support both
506ioctls when the tuner or modulator ioctls are supported, or
507when 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
515standards or variations of standards. Each video input and output may
516support 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
522currently in use worldwide, and sets aside bits for driver defined
523standards, &eg; hybrid standards to watch NTSC video tapes on PAL TVs
524and vice versa. Applications can use the predefined bits to select a
525particular standard, although presenting the user a menu of supported
526standards is preferred. To enumerate and query the attributes of the
527supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
528
529 <para>Many of the defined standards are actually just variations
530of a few major standards. The hardware may in fact not distinguish
531between them, or do so internal and switch automatically. Therefore
532enumerated standards also contain sets of one or more standard
533bits.</para>
534
535 <para>Assume a hypothetic tuner capable of demodulating B/PAL,
536G/PAL and I/PAL signals. The first enumerated standard is a set of B
537and G/PAL, switched automatically depending on the selected radio
538frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
539choice. 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,
542NTSC and SECAM. There is no point asking them to distinguish between
543B, G, D, or K when the software or hardware can do that
544automatically.</para>
545 </footnote></para>
546
547 <para>To query and select the standard used by the current video
548input or output applications call the &VIDIOC-G-STD; and
549&VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
550standard 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
552to 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
555indices like <structfield>audioset</structfield>.</para>
556 <para>Indices are consistent with the rest of the API
557and identify the standard unambiguously. In the present scheme of
558things an enumerated standard is looked up by &v4l2-std-id;. Now the
559standards supported by the inputs of a device can overlap. Just
560assume the tuner and composite input in the example above both
561exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
562a choice which does not exist. We cannot merge or omit sets, because
563applications would be unable to find the standards reported by
564<constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
565for each input. Also selecting a standard by &v4l2-std-id; can be
566ambiguous. Advantage of this method is that applications need not
567identify the standard indirectly, after enumerating.</para><para>So in
568summary, the lookup itself is unavoidable. The difference is only
569whether the lookup is necessary to find an enumerated standard or to
570switch to a standard by &v4l2-std-id;.</para>
571 </footnote> Drivers must implement all video standard ioctls
572when 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
575standards makes little sense. More generally any capture device,
576output devices accordingly, which is <itemizedlist>
577 <listitem>
578 <para>incapable of capturing fields or frames at the nominal
579rate of the video standard, or</para>
580 </listitem>
581 <listitem>
582 <para>where <link linkend="buffer">timestamps</link> refer
583to the instant the field or frame was received by the driver, not the
584capture time, or</para>
585 </listitem>
586 <listitem>
587 <para>where <link linkend="buffer">sequence numbers</link>
588refer to the frames received by the driver, not the captured
589frames.</para>
590 </listitem>
591 </itemizedlist> Here the driver shall set the
592<structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
593to 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
599even USB cameras follow some well known video standard. It might have
600been better to explicitly indicate elsewhere if a device cannot live
601up 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
611if (-1 == ioctl (fd, &VIDIOC-G-STD;, &amp;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
620memset (&amp;standard, 0, sizeof (standard));
621standard.index = 0;
622
623while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
624 if (standard.id &amp; 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
635if (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
644input</title>
645
646 <programlisting>
647&v4l2-input; input;
648&v4l2-standard; standard;
649
650memset (&amp;input, 0, sizeof (input));
651
652if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
653 perror ("VIDIOC_G_INPUT");
654 exit (EXIT_FAILURE);
655}
656
657if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
658 perror ("VIDIOC_ENUM_INPUT");
659 exit (EXIT_FAILURE);
660}
661
662printf ("Current input %s supports:\n", input.name);
663
664memset (&amp;standard, 0, sizeof (standard));
665standard.index = 0;
666
667while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
668 if (standard.id &amp; 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
677if (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
691memset (&amp;input, 0, sizeof (input));
692
693if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
694 perror ("VIDIOC_G_INPUT");
695 exit (EXIT_FAILURE);
696}
697
698if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
699 perror ("VIDIOC_ENUM_INPUT");
700 exit (EXIT_FAILURE);
701}
702
703if (0 == (input.std &amp; 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
711std_id = V4L2_STD_PAL_BG;
712
713if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;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
730applications, for example video images, raw or sliced VBI data, RDS
731datagrams. Even within one kind many different formats are possible,
732in particular an abundance of image formats. Although drivers must
733provide a default and the selection persists across closing and
734reopening a device, applications should always negotiate a data format
735before engaging in data exchange. Negotiation means the application
736asks for a particular format and the driver selects and reports the
737best the hardware can do to satisfy the request. Of course
738applications can also just query the current selection.</para>
739
740 <para>A single mechanism exists to negotiate all data formats
741using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
742&VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
743used to examine what the hardware <emphasis>could</emphasis> do,
744without actually selecting a new data format. The data formats
745supported by the V4L2 API are covered in the respective device section
746in <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
750turning-point in the initialization sequence. Prior to this point
751multiple panel applications can access the same device concurrently to
752select the current input, change controls or modify other properties.
753The 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
757other file descriptor, can grab this stream or change device
758properties inconsistent with the negotiated parameters. A video
759standard change for example, when the new standard uses a different
760number of scan lines, can invalidate the selected image format.
761Therefore only the file descriptor owning the stream can make
762invalidating changes. Accordingly multiple file descriptors which
763grabbed different logical streams prevent each other from interfering
764with their settings. When for example video overlay is about to start
765or already in progress, simultaneous video capturing may be restricted
766to 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
770implied 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
775file descriptor, the exception being drivers permitting simultaneous
776video capturing and overlay using the same file descriptor for
777compatibility with V4L and earlier versions of V4L2. Switching the
778logical stream or returning into "panel mode" is possible by closing
779and reopening the device. Drivers <emphasis>may</emphasis> support a
780switch using <constant>VIDIOC_S_FMT</constant>.</para>
781
782 <para>All drivers exchanging data with
783applications 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
786optional.</para>
787 </section>
788
789 <section>
790 <title>Image Format Enumeration</title>
791
792 <para>Apart of the generic format negotiation functions
793a special ioctl to enumerate all image formats supported by video
794capture, overlay or output devices is available.<footnote>
795 <para>Enumerating formats an application has no a-priori
796knowledge of (otherwise it could explicitly ask for them and need not
797enumerate) seems useless, but there are applications serving as proxy
798between drivers and the actual video applications for which this is
799useful.</para>
800 </footnote></para>
801
802 <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
803by all drivers exchanging image data with applications.</para>
804
805 <important>
806 <para>Drivers are not supposed to convert image formats in
807kernel space. They must enumerate only formats directly supported by
808the hardware. If necessary driver writers should publish an example
809conversion 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
818picture and shrink or enlarge it to an image of arbitrary size. We
819call these abilities cropping and scaling. Some video output devices
820can scale an image up or down and insert it at an arbitrary scan line
821and horizontal offset into a video signal.</para>
822
823 <para>Applications can use the following API to select an area in
824the video signal, query the default area and the hardware limits.
825<emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
826and &VIDIOC-S-CROP; ioctls apply to input as well as output
827devices.</emphasis></para>
828
829 <para>Scaling requires a source and a target. On a video capture
830or overlay device the source is the video signal, and the cropping
831ioctls determine the area actually sampled. The target are images
832read by the application or overlaid onto the graphics screen. Their
833size (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
837by the application, and their size is again negotiated with the
838<constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
839compressed video stream. The target is the video signal, and the
840cropping ioctls determine the area where the images are
841inserted.</para>
842
843 <para>Source and target rectangles are defined even if the device
844does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
845ioctls. Their size (and position where applicable) will be fixed in
846this case. <emphasis>All capture and output device must support the
847<constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
848determine 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
869corner, width and height of the area which can be sampled is given by
870the <structfield>bounds</structfield> substructure of the
871&v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
872ioctl. To support a wide range of hardware this specification does not
873define an origin or units. However by convention drivers should
874horizontally count unscaled samples relative to 0H (the leading edge
875of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
876Vertically ITU-R line
877numbers of the first field (<xref linkend="vbi-525" />, <xref
878linkend="vbi-625" />), multiplied by two if the driver can capture both
879fields.</para>
880
881 <para>The top left corner, width and height of the source
882rectangle, that is the area actually sampled, is given by &v4l2-crop;
883using the same coordinate system as &v4l2-cropcap;. Applications can
884use the <constant>VIDIOC_G_CROP</constant> and
885<constant>VIDIOC_S_CROP</constant> ioctls to get and set this
886rectangle. It must lie completely within the capture boundaries and
887the driver may further adjust the requested size and/or position
888according to hardware limitations.</para>
889
890 <para>Each capture device has a default source rectangle, given
891by the <structfield>defrect</structfield> substructure of
892&v4l2-cropcap;. The center of this rectangle shall align with the
893center of the active picture area of the video signal, and cover what
894the driver writer considers the complete picture. Drivers shall reset
895the source rectangle to the default when the driver is first loaded,
896but not later.</para>
897
898 <para>For output devices these structures and ioctls are used
899accordingly, defining the <emphasis>target</emphasis> rectangle where
900the 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
908scaling limitations. It may only scale up or down, support only
909discrete scaling factors, or have different scaling abilities in
910horizontal and vertical direction. Also it may not support scaling at
911all. At the same time the &v4l2-crop; rectangle may have to be
912aligned, and both the source and target rectangles may have arbitrary
913upper and lower size limits. In particular the maximum
914<structfield>width</structfield> and <structfield>height</structfield>
915in &v4l2-crop; may be smaller than the
916&v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
917usual, drivers are expected to adjust the requested parameters and
918return the actual values selected.</para>
919
920 <para>Applications can change the source or the target rectangle
921first, as they may prefer a particular image size or a certain area in
922the video signal. If the driver has to adjust both to satisfy hardware
923limitations, the last requested rectangle shall take priority, and the
924driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
925ioctl however shall not change the driver state and therefore only
926adjust the requested rectangle.</para>
927
928 <para>Suppose scaling on a video capture device is restricted to
929a factor 1:1 or 2:1 in either direction and the target image size must
930be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
931rectangle is set to defaults, which are also the upper limit in this
932example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
933application requests an image size of 300&nbsp;&times;&nbsp;225
934pixels, assuming video will be scaled down from the "full picture"
935accordingly. The driver sets the image size to the closest possible
936values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
937closest to the requested size, that is 608&nbsp;&times;&nbsp;224
938(224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
9390,&nbsp;0 is still valid, thus unmodified. Given the default cropping
940rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
941application can easily propose another offset to center the cropping
942rectangle.</para>
943
944 <para>Now the application may insist on covering an area using a
945picture aspect ratio closer to the original request, so it asks for a
946cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
947scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
948driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
949the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
950
951 </section>
952
953 <section>
954 <title>Examples</title>
955
956 <para>Source and target rectangles shall remain unchanged across
957closing and reopening a device, such that piping data into or out of a
958device will work without special preparations. More advanced
959applications should ensure the parameters are suitable before starting
960I/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
967devices.)</para>
968
969 <programlisting>
970&v4l2-cropcap; cropcap;
971&v4l2-crop; crop;
972
973memset (&amp;cropcap, 0, sizeof (cropcap));
974cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
975
976if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
977 perror ("VIDIOC_CROPCAP");
978 exit (EXIT_FAILURE);
979}
980
981memset (&amp;crop, 0, sizeof (crop));
982crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
983crop.c = cropcap.defrect;
984
985/* Ignore if cropping is not supported (EINVAL). */
986
987if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &amp;crop)
988 &amp;&amp; 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
1004reset_cropping_parameters ();
1005
1006/* Scale down to 1/4 size of full picture. */
1007
1008memset (&amp;format, 0, sizeof (format)); /* defaults */
1009
1010format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1011
1012format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
1013format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
1014format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
1015
1016if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;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
1033memset (&amp;cropcap, 0, sizeof (cropcap));
1034cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1035
1036if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
1037 perror ("VIDIOC_CROPCAP");
1038 exit (EXIT_FAILURE);
1039}
1040
1041memset (&amp;crop, 0, sizeof (crop));
1042
1043crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1044crop.c = cropcap.defrect;
1045
1046/* Scale the width and height to 50 % of their original size
1047 and center the output. */
1048
1049crop.c.width /= 2;
1050crop.c.height /= 2;
1051crop.c.left += crop.c.width / 2;
1052crop.c.top += crop.c.height / 2;
1053
1054/* Ignore if cropping is not supported (EINVAL). */
1055
1056if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
1057 &amp;&amp; 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;
1073double hscale, vscale;
1074double aspect;
1075int dwidth, dheight;
1076
1077memset (&amp;cropcap, 0, sizeof (cropcap));
1078cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1079
1080if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1081 perror ("VIDIOC_CROPCAP");
1082 exit (EXIT_FAILURE);
1083}
1084
1085memset (&amp;crop, 0, sizeof (crop));
1086crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1087
1088if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;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
1098memset (&amp;format, 0, sizeof (format));
1099format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1100
1101if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
1102 perror ("VIDIOC_G_FMT");
1103 exit (EXIT_FAILURE);
1104}
1105
1106/* The scaling applied by the driver. */
1107
1108hscale = format.fmt.pix.width / (double) crop.c.width;
1109vscale = format.fmt.pix.height / (double) crop.c.height;
1110
1111aspect = cropcap.pixelaspect.numerator /
1112 (double) cropcap.pixelaspect.denominator;
1113aspect = 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
1119dwidth = format.fmt.pix.width / aspect;
1120dheight = 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
1130capture process as well as I/O. Presently applications can request a
1131high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
1132
1133 <para>The current video standard determines a nominal number of
1134frames per second. If less than this number of frames is to be
1135captured or output, applications can request frame skipping or
1136duplicating on the driver side. This is especially useful when using
1137the &func-read; or &func-write;, which are not augmented by timestamps
1138or sequence counters, and to avoid unneccessary data copying.</para>
1139
1140 <para>Finally these ioctls can be used to determine the number of
1141buffers used internally by a driver in read/write mode. For
1142implications see the section discussing the &func-read;
1143function.</para>
1144
1145 <para>To get and set the streaming parameters applications call
1146the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1147a pointer to a &v4l2-streamparm;, which contains a union holding
1148separate parameters for input and output devices.</para>
1149
1150 <para>These ioctls are optional, drivers need not implement
1151them. If so, they return the &EINVAL;.</para>
1152 </section>
1153
1154 <!--
1155Local Variables:
1156mode: sgml
1157sgml-parent-document: "v4l2.sgml"
1158indent-tabs-mode: nil
1159End:
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,
4errata or extensions. They are also intended to help application and
5driver 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
11unify and replace various TV and radio device related interfaces,
12developed independently by driver writers in prior years. Starting
13with Linux 2.5 the much improved V4L2 API replaces the V4L API,
14although existing drivers will continue to support V4L applications in
15the future, either directly or through the V4L2 compatibility layer in
16the <filename>videodev</filename> kernel module translating ioctls on
17the fly. For a transition period not all drivers will support the V4L2
18API.</para>
19
20 <section>
21 <title>Opening and Closing Devices</title>
22
23 <para>For compatibility reasons the character device file names
24recommended for V4L2 video capture, overlay, radio, teletext and raw
25vbi capture devices did not change from those used by V4L. They are
26listed in <xref linkend="devices" /> and below in <xref
27 linkend="v4l-dev" />.</para>
28
29 <para>The V4L <filename>videodev</filename> module automatically
30assigns minor numbers to drivers in load order, depending on the
31registered device type. We recommend that V4L2 drivers by default
32register devices with the same numbers, but the system administrator
33can assign arbitrary minor numbers using driver module options. The
34major 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
51Documentation/devices.txt these should be symbolic links to
52<filename>/dev/video0</filename>. Note the original bttv interface is
53not 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
87device file. V4L2 drivers <emphasis>may</emphasis> support multiple
88opens, see <xref linkend="open" /> for details and consequences.</para>
89
90 <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;. The
91compatibility layer in the V4L2 <filename>videodev</filename> module
92can translate V4L ioctl requests to their V4L2 counterpart, however a
93V4L2 driver usually needs more preparation to become fully V4L
94compatible. 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
102equivalent 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
109distinguish between device types like this, better think of basic
110video input, video output and radio devices supporting a set of
111related functions like video capturing, video overlay and VBI
112capturing. See <xref linkend="open" /> for an
113introduction.<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
130capture</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
136modulator</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
142capture</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
148overlay</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
153field <structfield>capability</structfield> of
154&v4l2-framebuffer;</entry>
155 <entry>Whether chromakey overlay is supported. For
156more 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>
162and <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
165supported, 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,
173see <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
179images. The V4L2 API implies the scale factor by setting the cropping
180dimensions and image size with the &VIDIOC-S-CROP; and &VIDIOC-S-FMT;
181ioctl, respectively. The driver returns the closest sizes possible.
182For 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
189formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
190supports grey scale capturing only. For more information on image
191formats 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
197to determine if the device supports capturing a subsection of the full
198picture ("cropping" in V4L2). If not, the ioctl returns the &EINVAL;.
199For 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
206formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
207supports 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
229by <structfield>capabilities</structfield> flag
230<constant>V4L2_CAP_AUDIO</constant>, indicating
231<emphasis>if</emphasis> the device has any audio inputs or outputs. To
232determine their number applications can enumerate audio inputs with
233the &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
241returns the closest size possible, taking into account the current
242video 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
251the video inputs of a V4L device. The equivalent V4L2 ioctls
252are &VIDIOC-ENUMINPUT;, &VIDIOC-G-INPUT; and &VIDIOC-S-INPUT;
253using &v4l2-input; as discussed in <xref linkend="video" />.</para>
254
255 <para>The <structfield>channel</structfield> field counting
256inputs was renamed to <structfield>index</structfield>, the video
257input 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
281expressing the number of tuners of this input, V4L2 assumes each video
282input is connected to at most one tuner. However a tuner can have more
283than one input, &ie; RF connectors, and a device can have multiple
284tuners. The index number of the tuner associated with the input, if
285any, 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
290dropped. 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
294up to 32 audio inputs. Each set bit in the
295<structfield>audioset</structfield> field represents one audio input
296this video input combines with. For information about audio inputs and
297how to switch between them see <xref linkend="audio" />.</para>
298
299 <para>The <structfield>norm</structfield> field describing the
300supported 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
303be changed. This flag was a later addition together with the
304<structfield>norm</structfield> field and has been removed in the
305meantime. V4L2 has a similar, albeit more comprehensive approach
306to video standards, see <xref linkend="standard" /> for more
307information.</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
316tuners 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
318covered in <xref linkend="tuner" />.</para>
319
320 <para>The <structfield>tuner</structfield> field counting tuners
321was renamed to <structfield>index</structfield>. The fields
322<structfield>name</structfield>, <structfield>rangelow</structfield>
323and <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
328video standards were dropped. This information is now contained in the
329associated &v4l2-input;. No replacement exists for the
330<constant>VIDEO_TUNER_NORM</constant> flag indicating whether the
331video standard can be switched. The <structfield>mode</structfield>
332field to select a different video standard was replaced by a whole new
333set of ioctls and structures described in <xref linkend="standard" />.
334Due to its ubiquity it should be mentioned the BTTV driver supports
335several 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,
340M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</para>
341
342 <para>The <constant>VIDEO_TUNER_STEREO_ON</constant> flag
343indicating stereo reception became
344<constant>V4L2_TUNER_SUB_STEREO</constant> in field
345<structfield>rxsubchans</structfield>. This field also permits the
346detection 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
352to <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
357where renamed to &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;. They
358take a pointer to a &v4l2-frequency; instead of an unsigned long
359integer.</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>
367ioctl and struct <structname>video_picture</structname>. The following
368fields 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
40365535 with no particular reset value. The V4L2 API permits arbitrary
404limits and defaults which can be queried with the &VIDIOC-QUERYCTRL;
405ioctl. For general information about controls see <xref
406linkend="control" />.</para>
407
408 <para>The <structfield>depth</structfield> (average number of
409bits per pixel) of a video image is implied by the selected image
410format. V4L2 does not explicitely provide such information assuming
411applications recognizing the format are aware of the image depth and
412others need not know. The <structfield>palette</structfield> field
413moved 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
427linkend="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
432linkend="pixfmt-reserved"><constant>V4L2_PIX_FMT_HI240</constant></link><footnote>
433 <para>This is a custom format used by the BTTV
434driver, 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
440linkend="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
445linkend="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
450linkend="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
455linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote>
456 <para>Presumably all V4L RGB formats are
457little-endian, although some drivers might interpret them according to machine endianess. V4L2 defines little-endian, big-endian and red/blue
458swapped 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
464linkend="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>
469and <constant>VIDEO_PALETTE_YUYV</constant> are the same formats. Some
470V4L drivers respond to one, some to the other.</para>
471 </footnote></para></entry>
472 <entry><para><link
473linkend="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
478linkend="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
487linkend="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
490format.</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
495as: "RAW capture (BT848)"</para> </footnote></para></entry>
496 </row>
497 <row>
498 <entry><constant>VIDEO_PALETTE_YUV422P</constant></entry>
499 <entry><para><link
500linkend="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
505linkend="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
508format.</para> </footnote></para></entry>
509 </row>
510 <row>
511 <entry><constant>VIDEO_PALETTE_YUV420P</constant></entry>
512 <entry><para><link
513linkend="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
518linkend="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
525linkend="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
535audio inputs of a V4L device. The equivalent V4L2 ioctls are
536&VIDIOC-G-AUDIO; and &VIDIOC-S-AUDIO; using &v4l2-audio; as
537discussed in <xref linkend="audio" />.</para>
538
539 <para>The <structfield>audio</structfield> "channel number"
540field 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>
545of 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
549the current audio standard is BTSC
550<constant>VIDEO_SOUND_LANG2</constant> refers to SAP and
551<constant>VIDEO_SOUND_LANG1</constant> is meaningless. Also
552undocumented in the V4L specification, there is no way to query the
553selected mode. On <constant>VIDIOCGAUDIO</constant> the driver returns
554the <emphasis>actually received</emphasis> audio programmes in this
555field. 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
558linkend="tuner" /> for more information on tuners. Related to audio
559modes &v4l2-audio; also reports if this is a mono or stereo
560input, regardless if the source is a tuner.</para>
561
562 <para>The following fields where replaced by V4L2 controls
563accessible 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
595driver 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
601supported. Accordingly the <constant>VIDEO_AUDIO_MUTABLE</constant>
602and <constant>VIDEO_AUDIO_MUTE</constant> flags where replaced by the
603boolean <constant>V4L2_CID_AUDIO_MUTE</constant> control.</para>
604
605 <para>All V4L2 controls have a <structfield>step</structfield>
606attribute replacing the struct <structname>video_audio</structname>
607<structfield>step</structfield> field. The V4L audio controls are
608assumed to range from 0 to 65535 with no particular reset value. The
609V4L2 API permits arbitrary limits and defaults which can be queried
610with the &VIDIOC-QUERYCTRL; ioctl. For general information about
611controls 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>
619are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The
620<structfield>base</structfield> field of struct
621<structname>video_buffer</structname> remained unchanged, except V4L2
622defines 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
626replaced by <structfield>pixelformat</structfield>. See <xref
627 linkend="pixfmt-rgb" /> for a list of RGB formats and their
628respective color depths.</para>
629
630 <para>Instead of the special ioctls
631<constant>VIDIOCGWIN</constant> and <constant>VIDIOCSWIN</constant>
632V4L2 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>
635member 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;
642substructure <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
648containing a struct <structname>v4l2_rect</structname>, but the
649semantics are still the same.</para>
650
651 <para>The <constant>VIDEO_WINDOW_INTERLACE</constant> flag was
652dropped. 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
664clipping, using a fixed size bitmap of 1024 &times; 625 bits. Struct
665<structname>v4l2_window</structname> has a separate
666<structfield>bitmap</structfield> pointer field for this purpose and
667the 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
671disable 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
678defines 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;
688substructure <structfield>c</structfield> of struct
689<structname>v4l2_crop</structname>. The
690<structfield>decimation</structfield> field was dropped. In the V4L2
691API the scaling factor is implied by the size of the cropping
692rectangle and the size of the captured or overlaid image.</para>
693
694 <para>The <constant>VIDEO_CAPTURE_ODD</constant>
695and <constant>VIDEO_CAPTURE_EVEN</constant> flags to capture only the
696odd 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
701overlay 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
711from a V4L or V4L2 device using the &func-read; function, however V4L2
712drivers are not required to support this I/O method. Applications can
713determine if the function is available with the &VIDIOC-QUERYCAP;
714ioctl. All V4L2 devices exchanging data with applications must support
715the &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>
719ioctls. 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>
723union 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
732buffers in device memory, or more often just buffers allocated in
733DMA-able system memory, into their address space. This avoids the data
734copying overhead of the read method. V4L2 supports memory mapping as
735well, 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
749buffers are allocated, with the &VIDIOC-S-FMT; ioctl. When no format
750is selected the driver may use the last, possibly by another
751application requested format.</entry>
752 </row>
753 <row>
754 <entry><para>Applications cannot change the number of
755buffers. The it is built into the driver, unless it has a module
756option to change the number when the driver module is
757loaded.</para></entry>
758 <entry><para>The &VIDIOC-REQBUFS; ioctl allocates the
759desired number of buffers, this is a required step in the initialization
760sequence.</para></entry>
761 </row>
762 <row>
763 <entry><para>Drivers map all buffers as one contiguous
764range of memory. The <constant>VIDIOCGMBUF</constant> ioctl is
765available to query the number of buffers, the offset of each buffer
766from the start of the virtual file, and the overall amount of memory
767used, which can be used as arguments for the &func-mmap;
768function.</para></entry>
769 <entry><para>Buffers are individually mapped. The
770offset 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>
775ioctl prepares a buffer for capturing. It also determines the image
776format for this buffer. The ioctl returns immediately, eventually with
777an &EAGAIN; if no video signal had been detected. When the driver
778supports more than one buffer applications can call the ioctl multiple
779times and thus have multiple outstanding capture
780requests.</para><para>The <constant>VIDIOCSYNC</constant> ioctl
781suspends execution until a particular buffer has been
782filled.</para></entry>
783 <entry><para>Drivers maintain an incoming and outgoing
784queue. &VIDIOC-QBUF; enqueues any empty buffer into the incoming
785queue. Filled buffers are dequeued from the outgoing queue with the
786&VIDIOC-DQBUF; ioctl. To wait until filled buffers become available this
787function, &func-select; or &func-poll; can be used. The
788&VIDIOC-STREAMON; ioctl must be called once after enqueuing one or
789more buffers to start capturing. Its counterpart
790&VIDIOC-STREAMOFF; stops capturing and dequeues all buffers from both
791queues. 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
799examples, 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
807interface, only the device file <filename>/dev/vbi</filename> was
808reserved for this purpose. The only driver supporting this interface
809was the BTTV driver, de-facto defining the V4L VBI interface. Reading
810from the device yields a raw VBI image with the following
811parameters:<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&nbsp;Hz NTSC (or any other 525-line
823standard); 35468950&nbsp;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
836machine 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
845versions used different values, eventually the custom
846<constant>BTTV_VBISIZE</constant> ioctl was added to query the
847correct 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
861image parameters. These ioctls are only partially compatible with the
862V4L2 VBI interface specified in <xref linkend="raw-vbi" />.</para>
863
864 <para>An <structfield>offset</structfield> field does not
865exist, <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
868probably equivalent to &v4l2-vbi-format;.</para>
869
870 <para>Apparently only the Zoran (ZR 36120) driver implements
871these ioctls. The semantics differ from those specified for V4L2 in two
872ways. The parameters are reset on &func-open; and
873<constant>VIDIOCSVBIFMT</constant> always returns an &EINVAL; if the
874parameters 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
882device associated with a video capture device (or vice versa) by
883reopening the device and requesting VBI data. For details see
884<xref linkend="open" />.</para>
885
886 <para>No replacement exists for <constant>VIDIOCKEY</constant>,
887and the V4L functions for microcode programming. A new interface for
888MPEG 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
898criticised as too inflexible. In August 1998 Bill Dirks proposed a
899number of improvements and began to work on documentation, example
900drivers and applications. With the help of other volunteers this
901eventually became the V4L2 API, not just an extension but a
902replacement for the V4L API. However it took another four years and
903two stable kernel releases until the new API was finally accepted for
904inclusion 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
915was 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
918flag if they intend to access controls only, as opposed to capture
919applications which need exclusive access. The
920<constant>VIDEO_STD_XXX</constant> identifiers are now ordinals
921instead of flags, and the <function>video_std_construct()</function>
922helper function takes id and transmission arguments.</para>
923
924 <para>1998-09-28: Revamped video standard. Made video controls
925individually enumerable.</para>
926
927 <para>1998-10-02: The <structfield>id</structfield> field was
928removed from struct <structname>video_standard</structname> and the
929color subcarrier fields were renamed. The &VIDIOC-QUERYSTD; ioctl was
930renamed to &VIDIOC-ENUMSTD;, &VIDIOC-G-INPUT; to &VIDIOC-ENUMINPUT;. A
931first draft of the Codec API was released.</para>
932
933 <para>1998-11-08: Many minor changes. Most symbols have been
934renamed. 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>
939changed 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
942accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under
943names 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
948image formats were added.</para>
949
950 <para>1998-11-28: A few ioctl symbols changed. Interfaces for codecs and
951video 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
962are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
963digital 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
972videodev.c. Driver writers, this changes how you implement your ioctl
973handler. See the Driver Writer's Guide. Added some more control id
974codes.</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
980v4l2_queryctrl objects before passing them to the driver. Required a
981minor change to the VIDIOC_QUERYCTRL handlers in the sample
982drivers.</para>
983 <para>1999-03-31: Better compatibility for v4l memory capture
984ioctls. Requires changes to drivers to fully support new compatibility
985features, see Driver Writer's Guide and v4l2cap.c. Added new control
986IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
987and _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
991V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</para>
992 <para>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing
993a malfunction of this ioctl.</para>
994 <para>1999-06-05: Changed the value of
995V4L2_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
1003versions. Purpose of these changes was to simplify the API, while
1004making it more extensible and following common Linux driver API
1005conventions.</para>
1006
1007 <orderedlist>
1008 <listitem>
1009 <para>Some typos in <constant>V4L2_FMT_FLAG</constant>
1010symbols were fixed. &v4l2-clip; was changed for compatibility with
1011v4l. (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
1021take a pointer to an integer. Where it makes sense, ioctls will return
1022the actual new value in the integer pointed to by the argument, a
1023common convention in the V4L2 API. The affected ioctls are:
1024VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
1025VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
1026<programlisting>
1027err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
1028</programlisting> becomes <programlisting>
1029int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &amp;a);
1030</programlisting>
1031 </para>
1032 </listitem>
1033
1034 <listitem>
1035 <para>All the different get- and set-format commands were
1036swept into one &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctl taking a union
1037and a type field selecting the union member as parameter. Purpose is to
1038simplify the API by eliminating several ioctls and to allow new and
1039driver 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;,
1049while &v4l2-format; is now the envelopping structure for all format
1050negotiations.</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;
1060selects 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
1069control 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
1074unavailable controls with <constant>V4L2_CTRL_FLAG_DISABLED</constant>
1075and <constant>V4L2_CTRL_FLAG_GRABBED</constant> respectively. The
1076<structfield>group</structfield> name indicates a possibly narrower
1077classification than the <structfield>category</structfield>. In other
1078words, there may be multiple groups within a category. Controls within
1079a group would typically be drawn within a group box. Controls in
1080different categories might have a greater separation, or may even
1081appear in separate windows.</para>
1082 </listitem>
1083
1084 <listitem>
1085 <para>The &v4l2-buffer; <structfield>timestamp</structfield>
1086was changed to a 64 bit integer, containing the sampling or output
1087time of the frame in nanoseconds. Additionally timestamps will be in
1088absolute system time, not starting from zero at the beginning of a
1089stream. The data type name for timestamps is stamp_t, defined as a
1090signed 64-bit integer. Output devices should not send a buffer out
1091until the time in the timestamp field has arrived. I would like to
1092follow SGI's lead, and adopt a multimedia timestamping system like
1093their UST (Unadjusted System Time). See
1094http://reality.sgi.com/cpirazzi_engr/lg/time/intro.html. [This link is
1095no longer valid.] UST uses timestamps that are 64-bit signed integers
1096(not struct timeval's) and given in nanosecond units. The UST clock
1097starts at zero when the system is booted and runs continuously and
1098uniformly. It takes a little over 292 years for UST to overflow. There
1099is no way to set the UST clock. The regular Linux time-of-day clock
1100can be changed periodically, which would cause errors if it were being
1101used for timestamping a multimedia stream. A real UST style clock will
1102require some support in the kernel that is not there yet. But in
1103anticipation, I will change the timestamp field to a 64-bit integer,
1104and I will change the v4l2_masterclock_gettime() function (used only
1105by drivers) to return a 64-bit integer.</para>
1106 </listitem>
1107
1108 <listitem>
1109 <para>A <structfield>sequence</structfield> field was added
1110to &v4l2-buffer;. The <structfield>sequence</structfield> field counts
1111captured frames, it is ignored by output devices. When a capture
1112driver drops a frame, the sequence number of that frame is
1113skipped.</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
1125clear 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
1131is now included by <filename>videodev.h</filename> for compatibility
1132with 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
1138added.</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
1148between the <filename>videodev.h</filename> file in Linux 2.4.0 and
1149the <filename>videodev.h</filename> file included in the
1150<filename>videodevX</filename> patch was fixed. Users of an earlier
1151version of <filename>videodevX</filename> on Linux 2.4.0 should
1152recompile their V4L and V4L2 drivers.</para>
1153
1154 <para>2001-01-26: A possible kernel-level incompatibility
1155between 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
1158applied was fixed.</para>
1159
1160 <para>2001-03-02: Certain V4L ioctls which pass data in both
1161direction although they are defined with read-only parameter, did not
1162work 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
1171into account.)</para>
1172
1173 <para>2000-09-18: <constant>V4L2_BUF_TYPE_VBI</constant> was
1174added. 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>
1177field does not contain <constant>V4L2_BUF_TYPE_VBI</constant>. In the
1178documentation of the &v4l2-vbi-format;
1179<structfield>offset</structfield> field the ambiguous phrase "rising
1180edge" 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
1187interface.</para>
1188
1189 <orderedlist>
1190 <listitem>
1191 <para>Figures clarifying the line numbering scheme were
1192added to the V4L2 API specification. The
1193<structfield>start</structfield>[0] and
1194<structfield>start</structfield>[1] fields no longer count line
1195numbers beginning at zero. Rationale: a) The previous definition was
1196unclear. b) The <structfield>start</structfield>[] values are ordinal
1197numbers. c) There is no point in inventing a new line numbering
1198scheme. We now use line number as defined by ITU-R, period.
1199Compatibility: Add one to the start values. Applications depending on
1200the previous semantics may not function correctly.</para>
1201 </listitem>
1202
1203 <listitem>
1204 <para>The restriction "count[0] &gt; 0 and count[1] &gt; 0"
1205has been relaxed to "(count[0] + count[1]) &gt; 0". Rationale:
1206Drivers may allocate resources at scan line granularity and some data
1207services are transmitted only on the first field. The comment that
1208both <structfield>count</structfield> values will usually be equal is
1209misleading and pointless and has been removed. This change
1210<emphasis>breaks compatibility</emphasis> with earlier versions:
1211Drivers may return EINVAL, applications may not function
1212correctly.</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
1218dropped is unclear. This change may <emphasis>break
1219compatibility</emphasis> with applications depending on the start
1220values being positive. The use of <constant>EBUSY</constant> and
1221<constant>EINVAL</constant> error codes with the &VIDIOC-S-FMT; ioctl
1222was clarified. The &EBUSY; was finally documented, and the
1223<structfield>reserved2</structfield> field which was previously
1224mentioned only in the <filename>videodev.h</filename> header
1225file.</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
1232alias for the old <constant>V4L2_TYPE_VBI</constant>, the latter was
1233missing 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
1247feature freeze of Linux 2.5, the API was revised, drawing from
1248experience with V4L2 0.20. This unnamed version was finally merged
1249into Linux 2.5.46.</para>
1250
1251 <orderedlist>
1252 <listitem>
1253 <para>As specified in <xref linkend="related" />, drivers
1254must make related device functions available under all minor device
1255numbers.</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
1261drivers exchanging data with applications must support the
1262<constant>O_NONBLOCK</constant> flag. The <constant>O_NOIO</constant>
1263flag, a V4L2 symbol which aliased the meaningless
1264<constant>O_TRUNC</constant> to indicate accesses without data
1265exchange (panel applications) was dropped. Drivers must stay in "panel
1266mode" 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
1272also the size of the structure changed, which is encoded in the ioctl
1273request code, thus older V4L2 devices will respond with an &EINVAL; to
1274the new &VIDIOC-QUERYCAP; ioctl.</para>
1275
1276 <para>There are new fields to identify the driver, a new RDS
1277device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the
1278<constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has
1279any audio connectors, another I/O capability
1280<constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to
1281these changes the <structfield>type</structfield> field became a bit
1282set 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>
1296and <structfield>audios</structfield> were removed. These properties
1297can be determined as described in <xref linkend="video" /> and <xref
1298linkend="audio" />.</para>
1299
1300 <para>The somewhat volatile and therefore barely useful
1301fields <structfield>maxwidth</structfield>,
1302<structfield>maxheight</structfield>,
1303<structfield>minwidth</structfield>,
1304<structfield>minheight</structfield>,
1305<structfield>maxframerate</structfield> were removed. This information
1306is available as described in <xref linkend="format" /> and
1307<xref linkend="standard" />.</para>
1308
1309 <para><constant>V4L2_FLAG_SELECT</constant> was removed. We
1310believe the select() function is important enough to require support
1311of it in all V4L2 drivers exchanging data with applications. The
1312redundant <constant>V4L2_FLAG_MONOCHROME</constant> flag was removed,
1313this 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
1323video input to one audio input this field reports all audio inputs
1324this 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
1343structures. A new capability flag
1344<constant>V4L2_AUDCAP_STEREO</constant> was added to indicated if the
1345audio 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
1348easily implemented using controls. (However the same applies to AVL
1349which 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
1360multiple tuners. The link between video inputs and tuners is now
1361reversed, inputs point to their tuner. The
1362<structfield>std</structfield> substructure became a
1363simple 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
1373or modulator index number. A tuner <structfield>type</structfield>
1374field was added and the <structfield>reserved</structfield> field
1375became larger for future extensions (satellite tuners in
1376particular).</para>
1377 </listitem>
1378
1379 <listitem>
1380 <para>The idea of completely transparent video standards was
1381dropped. Experience showed that applications must be able to work with
1382video standards beyond presenting the user a menu. Instead of
1383enumerating supported standards with an ioctl applications can now
1384refer 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
1389the hardware has this capability. In &v4l2-standard; an
1390<structfield>index</structfield> field was added for &VIDIOC-ENUMSTD;.
1391A &v4l2-std-id; field named <structfield>id</structfield> was added as
1392machine readable identifier, also replacing the
1393<structfield>transmission</structfield> field. The misleading
1394<structfield>framerate</structfield> field was renamed
1395to <structfield>frameperiod</structfield>. The now obsolete
1396<structfield>colorstandard</structfield> information, originally
1397needed to distguish between variations of standards, were
1398removed.</para>
1399
1400 <para>Struct <structname>v4l2_enumstd</structname> ceased to
1401be. &VIDIOC-ENUMSTD; now takes a pointer to a &v4l2-standard;
1402directly. The information which standards are supported by a
1403particular video input or output moved into &v4l2-input; and
1404&v4l2-output; fields named <structfield>std</structfield>,
1405respectively.</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
1412implemented as expected and therefore removed.</para>
1413 </listitem>
1414
1415 <listitem>
1416 <para>The &VIDIOC-TRY-FMT; ioctl was added to negotiate data
1417formats as with &VIDIOC-S-FMT;, but without the overhead of
1418programming the hardware and regardless of I/O in progress.</para>
1419
1420 <para>In &v4l2-format; the <structfield>fmt</structfield>
1421union was extended to contain &v4l2-window;. All image format
1422negotiations 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
1427overlay were removed. The <structfield>type</structfield> field
1428changed to type &v4l2-buf-type; and the buffer type names changed as
1429follows.<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
1499was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with
1500type <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
1506applications which recognize the format by its four-character-code
1507already know the color depth, and others do not care about it. The
1508same 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
1511because drivers are not supposed to convert images in kernel space. A
1512user library of conversion functions should be provided instead. The
1513<constant>V4L2_FMT_FLAG_BYTESPERLINE</constant> flag was redundant.
1514Applications can set the <structfield>bytesperline</structfield> field
1515to zero to get a reasonable default. Since the remaining flags were
1516replaced as well, the <structfield>flags</structfield> field itself
1517was removed.</para>
1518 <para>The interlace flags were replaced by a &v4l2-field;
1519value in a newly added <structfield>field</structfield>
1520field.<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
1579added to distinguish between I/O methods using buffers allocated
1580by the driver or the application. See <xref linkend="io" /> for
1581details.</para>
1582 </listitem>
1583
1584 <listitem>
1585 <para>In &v4l2-buffer; the <structfield>type</structfield>
1586field was properly defined as &v4l2-buf-type;. Buffer types changed as
1587mentioned above. A <structfield>field</structfield> field of type
1588&v4l2-field; was added to indicate if a buffer contains a top or
1589bottom field. The old field flags were removed. Since no unadjusted
1590system time clock was added to the kernel as planned, the
1591<structfield>timestamp</structfield> field changed back from type
1592stamp_t, an unsigned 64 bit integer expressing the sample time in
1593nanoseconds, to struct <structname>timeval</structname>. With the
1594addition 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
1598added to distinguish between I/O methods. See <xref linkend="io" />
1599for details.</para>
1600
1601 <para>The <constant>V4L2_BUF_REQ_CONTIG</constant>
1602flag was used by the V4L compatibility layer, after changes to this
1603code it was no longer needed. The
1604<constant>V4L2_BUF_ATTR_DEVICEMEM</constant> flag would indicate if
1605the buffer was indeed allocated in device memory rather than DMA-able
1606system 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
1612triple-buffering in off-screen video memory, however without defining
1613a 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.
1616Applications can determine this capability more accurately using the
1617new 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
1629were renamed to <structfield>left</structfield> and
1630<structfield>top</structfield>, &ie; offsets to a context dependent
1631origin.</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
1640to 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
1649cropping and scaling interface. The previously unused struct
1650<structname>v4l2_cropcap</structname> and
1651<structname>v4l2_crop</structname> where redefined for this purpose.
1652See <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
1658four-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
1667long to &v4l2-fract;. This allows the accurate expression of multiples
1668of the NTSC-M frame rate 30000 / 1001. A new field
1669<structfield>readbuffers</structfield> was added to control the driver
1670behaviour 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>
1677and <constant>VIDIOC_G_PERF</constant> ioctl were dropped. Except when
1678using the <link linkend="rw">read/write I/O method</link>, which is
1679limited anyway, this information is already available to
1680applications.</para>
1681 </listitem>
1682
1683 <listitem>
1684 <para>The example transformation from RGB to YCbCr color
1685space in the old V4L2 documentation was inaccurate, this has been
1686corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be
16870.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
1699to this change radio devices would identify solely by having exactly one
1700tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para>
1701 </listitem>
1702
1703 <listitem>
1704 <para>An optional driver access priority mechanism was
1705added, 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
1710incomplete.</para>
1711 <para>Previously the &VIDIOC-G-AUDIO;
1712ioctl would enumerate the available audio inputs. An ioctl to
1713determine the current audio input, if more than one combines with the
1714current 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
1717the future. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate
1718audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio
1719input.</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
1723translate between the old and new ioctls, but drivers and applications
1724must be updated to successfully compile again.</para>
1725 </listitem>
1726
1727 <listitem>
1728 <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with
1729write-read parameter. It was changed to write-only, while the write-read
1730version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old
1731ioctl will be removed in the future. Until further the "videodev"
1732kernel module will automatically translate to the new version, so drivers
1733must be recompiled, but not applications.</para>
1734 </listitem>
1735
1736 <listitem>
1737 <para><xref linkend="overlay" /> incorrectly stated that
1738clipping rectangles define regions where the video can be seen.
1739Correct is that clipping rectangles define regions where
1740<emphasis>no</emphasis> video shall be displayed and so the graphics
1741surface can be seen.</para>
1742 </listitem>
1743
1744 <listitem>
1745 <para>The &VIDIOC-S-PARM; and &VIDIOC-S-CTRL; ioctls were
1746defined with write-only parameter, inconsistent with other ioctls
1747modifying their argument. They were changed to write-read, while a
1748<constant>_OLD</constant> suffix was added to the write-only versions.
1749The old ioctls will be removed in the future. Drivers and
1750applications 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
1760formats were incorrectly transferred from Bill Dirks' V4L2
1761specification. Descriptions below refer to bytes in memory, in
1762ascending address order.<informaltable>
1763 <tgroup cols="3">
1764 <thead>
1765 <row>
1766 <entry>Symbol</entry>
1767 <entry>In this document prior to revision
17680.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
1797correct.</para>
1798 <para>In <xref linkend="v4l-image-properties" /> the mapping
1799of the V4L <constant>VIDEO_PALETTE_RGB24</constant> and
1800<constant>VIDEO_PALETTE_RGB32</constant> formats to V4L2 pixel formats
1801was accordingly corrected.</para>
1802 </listitem>
1803
1804 <listitem>
1805 <para>Unrelated to the fixes above, drivers may still
1806interpret some V4L2 RGB pixel formats differently. These issues have
1807yet 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
1818with read-only parameter. It is now defined as write-read ioctl, while
1819the read-only version was renamed to
1820<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl will be removed
1821in 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;
1832structure. Purpose of this field is to alternate between video inputs
1833(&eg; cameras) in step with the video capturing process. This function
1834must be enabled with the new <constant>V4L2_BUF_FLAG_INPUT</constant>
1835flag. The <structfield>flags</structfield> field is no longer
1836read-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
1857argument.</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
1864examples. Also on the <constant>VIDIOC_DQBUF</constant> page the &EIO;
1865was 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
1875in <xref linkend="sliced" /> and replaces the interface first
1876proposed 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),
1893and <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
1906was 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
19102.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" />
1918called the &VIDIOC-S-CROP; ioctl without checking if cropping is
1919supported. In the video standard selection example in
1920<xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong
1921argument 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
1930also if it is active. (The color killer disables color decoding when
1931it detects no color in the video signal to improve the image
1932quality.)</para>
1933 </listitem>
1934
1935 <listitem>
1936 <para>&VIDIOC-S-PARM; is a write-read ioctl, not write-only as
1937stated 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
1948seconds, 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
1959list, because drivers ignore the struct
1960<structname>v4l2_clip</structname>.<structfield>next</structfield>
1961pointer.</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
1972sets <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>
1983was defined to record both languages of a bilingual program. The
1984use of <constant>V4L2_TUNER_MODE_STEREO</constant> for this purpose
1985is deprecated now. See the &VIDIOC-G-TUNER; section for
1986details.</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
1998interface 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
2003that the &v4l2-audio; <structfield>mode</structfield> field is a flags
2004field.</para>
2005 </listitem>
2006
2007 <listitem>
2008 <para><xref linkend="vidioc-querycap" /> did not mention the
2009sliced VBI and radio capability flags.</para>
2010 </listitem>
2011
2012 <listitem>
2013 <para>In <xref linkend="vidioc-g-frequency" /> it was
2014clarified that applications must initialize the tuner
2015<structfield>type</structfield> field of &v4l2-frequency; before
2016calling &VIDIOC-S-FREQUENCY;.</para>
2017 </listitem>
2018
2019 <listitem>
2020 <para>The <structfield>reserved</structfield> array
2021in &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
2028by <filename>/dev/video</filename>.</para>
2029 </listitem>
2030
2031 <listitem>
2032 <para>With Linux 2.6.15 the possible range for VBI device minor
2033numbers was extended from 224-239 to 224-255. Accordingly device file names
2034<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> are
2035possible 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;
2045and &VIDIOC-TRY-EXT-CTRLS; were added, a flag to skip unsupported
2046controls 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
2065replacing a reserved field. Note on architectures where the size of
2066enum types differs from int types the size of the structure changed.
2067The &VIDIOC-G-SLICED-VBI-CAP; ioctl was redefined from being read-only
2068to write-read. Applications must initialize the type field and clear
2069the reserved fields now. These changes may <emphasis>break the
2070compatibility</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
2080linkend="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
2090linkend="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
2100now dual licensed under GNU General Public License version two or
2101later, 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
2118straight or inverted local alpha value were added to the video overlay
2119interface. 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
2122was added to <link
2123linkend="v4l2-window"><structname>v4l2_window</structname></link>,
2124extending the structure. This may <emphasis>break
2125compatibility</emphasis> with applications using a struct
2126<structname>v4l2_window</structname> directly. However the <link
2127linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, which take a
2128pointer to a <link linkend="v4l2-format">v4l2_format</link> parent
2129structure with padding bytes at the end, are not affected.</para>
2130 </listitem>
2131
2132 <listitem>
2133 <para>The format of the <structfield>chromakey</structfield>
2134field in &v4l2-window; changed from "host order RGB32" to a pixel
2135value in the same format as the framebuffer. This may <emphasis>break
2136compatibility</emphasis> with existing applications. Drivers
2137supporting 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
2163linkend="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
2173controls <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
2181class</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
2198by the <link linkend="extended-controls">extended controls</link>
2199interface 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
2251video 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
2266to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and &VIDIOC-DBG-G-CHIP-IDENT;
2267was introduced in its place. The old struct <structname>v4l2_chip_ident</structname>
2268was 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
2301version, 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
2305more 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
2336an extension of the X Window system, implemented for example by the
2337XFree86 project. Its scope is similar to V4L2, an API to video capture
2338and output devices for X clients. Xv allows applications to display
2339live video in a window, send window contents to a TV output, and
2340capture or output still images in XPixmaps<footnote>
2341 <para>This is not implemented in XFree86.</para>
2342 </footnote>. With their implementation XFree86 makes the
2343extension available across many operating systems and
2344architectures.</para>
2345
2346 <para>Because the driver is embedded into the X server Xv has a
2347number of advantages over the V4L2 <link linkend="overlay">video
2348overlay interface</link>. The driver can easily determine the overlay
2349target, &ie; visible graphics memory or off-screen buffers for a
2350destructive overlay. It can program the RAMDAC for a non-destructive
2351overlay, scaling or color-keying, or the clipping functions of the
2352video capture hardware, always in sync with drawing operations or
2353windows moving or changing their stacking order.</para>
2354
2355 <para>To combine the advantages of Xv and V4L a special Xv
2356driver exists in XFree86 and XOrg, just programming any overlay capable
2357Video4Linux device it finds. To enable it
2358<filename>/etc/X11/XF86Config</filename> must contain these lines:</para>
2359 <para><screen>
2360Section "Module"
2361 Load "v4l"
2362EndSection</screen></para>
2363
2364 <para>As of XFree86 4.2 this driver still supports only V4L
2365ioctls, however it should work just fine with all V4L2 devices through
2366the V4L2 backward-compatibility layer. Since V4L2 permits multiple
2367opens it is possible (if supported by the V4L2 driver) to capture
2368video while an X client requested video overlay. Restrictions of
2369simultaneous capturing and overlay are discussed in <xref
2370 linkend="overlay" /> apply.</para>
2371
2372 <para>Only marginally related to V4L2, XFree86 extended Xv to
2373support hardware YUV to RGB conversion and scaling for faster video
2374playback, and added an interface to MPEG-2 decoding hardware. This API
2375is 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
2382satellite broadcast. A separate project aiming at digital receivers
2383exists. You can find its homepage at <ulink
2384url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API
2385has no connection to the V4L2 API except that drivers for hybrid
2386hardware 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
2400and 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;
2424ioctls.</para>
2425 </listitem>
2426 <listitem>
2427 <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER;
2428ioctls.</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
2440interfaces 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 <!--
2452Local Variables:
2453mode: sgml
2454sgml-parent-document: "v4l2.sgml"
2455indent-tabs-mode: nil
2456End:
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
5such as brightness, saturation and so on, which would be presented to
6the user on a graphical user interface. But, different devices
7will have different controls available, and furthermore, the range of
8possible values, and the default value will vary from device to
9device. The control ioctls provide the information and a mechanism to
10create a nice user interface for these controls that will work
11correctly with any device.</para>
12
13 <para>All controls are accessed using an ID value. V4L2 defines
14several IDs for specific purposes. Drivers can also implement their
15own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant>
16and higher values. The pre-defined control IDs have the prefix
17<constant>V4L2_CID_</constant>, and are listed in <xref
18linkend="control-id" />. The ID is used when querying the attributes of
19a control, and when getting or setting the current value.</para>
20
21 <para>Generally applications should present controls to the user
22without assumptions about their purpose. Each control comes with a
23name string the user is supposed to understand. When the purpose is
24non-intuitive the driver writer should provide a user manual, a user
25interface plug-in or a driver specific panel application. Predefined
26IDs were introduced to change a few controls programmatically, for
27example to mute a device during a channel switch.</para>
28
29 <para>Drivers may enumerate different controls after switching
30the current video input or output, tuner or modulator, or audio input
31or output. Different in the sense of other bounds, another default and
32current value, step size or other menu items. A control with a certain
33<emphasis>custom</emphasis> ID can also change name and
34type.<footnote>
35 <para>It will be more convenient for applications if drivers
36make use of the <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag, but
37that was never required.</para>
38 </footnote> Control values are stored globally, they do not
39change when switching except to stay within the reported bounds. They
40also do not change &eg; when the device is opened or closed, when the
41tuner radio frequency is changed or generally never without
42application request. Since V4L2 specifies no event mechanism, panel
43applications intended to cooperate with other panel applications (be
44they built into a larger application, as a TV viewer) may need to
45regularly poll control values to update their user
46interface.<footnote>
47 <para>Applications could call an ioctl to request events.
48After another process called &VIDIOC-S-CTRL; or another ioctl changing
49shared properties the &func-select; function would indicate
50readability until any ioctl (querying the properties) is
51called.</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
81level.</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
102provide 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
108the 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
124without affecting <constant>V4L2_CID_AUDIO_VOLUME</constant>. Like
125ALSA drivers, V4L2 drivers must mute at load time to avoid excessive
126noise. Actually the entire device should be reset to a low power
127consumption 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
139and 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
150ignored), the device will do a white balance and then hold the current
151setting. Contrast this with the boolean
152<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant>, which, when
153activated, 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
174for <constant>V4L2_CID_GAMMA</constant>. This control is deprecated
175and 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
206deprecated. New drivers and applications should use the <link
207linkend="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
219control 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
229flicker. 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
238effect of setting <constant>V4L2_CID_HUE</constant> while automatic
239hue control is enabled is undefined, drivers should ignore such
240request.</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
246as a color temperature in Kelvin. A driver should have a minimum of
2472800 (incandescent) to 6500 (daylight). For more information about
248color temperature see <ulink
249url="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
255minimum value disables the filters, higher values give a sharper
256picture.</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
262minimum 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 &amp; 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.
293Applications depending on particular custom controls should check the
294driver 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
302control value with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls.
303Drivers 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
306controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or
307more 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
316static void
317enumerate_menu (void)
318{
319 printf (" Menu items:\n");
320
321 memset (&amp;querymenu, 0, sizeof (querymenu));
322 querymenu.id = queryctrl.id;
323
324 for (querymenu.index = queryctrl.minimum;
325 querymenu.index &lt;= queryctrl.maximum;
326 querymenu.index++) {
327 if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) {
328 printf (" %s\n", querymenu.name);
329 } else {
330 perror ("VIDIOC_QUERYMENU");
331 exit (EXIT_FAILURE);
332 }
333 }
334}
335
336memset (&amp;queryctrl, 0, sizeof (queryctrl));
337
338for (queryctrl.id = V4L2_CID_BASE;
339 queryctrl.id &lt; V4L2_CID_LASTP1;
340 queryctrl.id++) {
341 if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
342 if (queryctrl.flags &amp; 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
358for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
359 queryctrl.id++) {
360 if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
361 if (queryctrl.flags &amp; 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
386memset (&amp;queryctrl, 0, sizeof (queryctrl));
387queryctrl.id = V4L2_CID_BRIGHTNESS;
388
389if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;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 &amp; V4L2_CTRL_FLAG_DISABLED) {
397 printf ("V4L2_CID_BRIGHTNESS is not supported\n");
398} else {
399 memset (&amp;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;, &amp;control)) {
404 perror ("VIDIOC_S_CTRL");
405 exit (EXIT_FAILURE);
406 }
407}
408
409memset (&amp;control, 0, sizeof (control));
410control.id = V4L2_CID_CONTRAST;
411
412if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &amp;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;, &amp;control)
418 &amp;&amp; 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
428control.id = V4L2_CID_AUDIO_MUTE;
429control.value = TRUE; /* silence */
430
431/* Errors ignored */
432ioctl (fd, VIDIOC_S_CTRL, &amp;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
444to be used for user settings (brightness, saturation, etc). However,
445it turned out to be a very useful model for implementing more
446complicated driver APIs where each driver implements only a subset of
447a larger API.</para>
448
449 <para>The MPEG encoding API was the driving force behind
450designing and implementing this extended control mechanism: the MPEG
451standard is quite large and the currently supported hardware MPEG
452encoders each only implement a subset of this standard. Further more,
453many parameters relating to how the video is encoded into an MPEG
454stream are specific to the MPEG encoding chip since the MPEG standard
455only defines the format of the resulting MPEG stream, not how the
456video is actually encoded into that format.</para>
457
458 <para>Unfortunately, the original control API lacked some
459features 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
463to use the Extended Control API, nowadays there are also other classes
464of Extended Controls, such as Camera Controls and FM Transmitter Controls.
465The Extended Controls API as well as all Extended Controls classes are
466described 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
474arrays of controls (as opposed to the &VIDIOC-G-CTRL; and
475&VIDIOC-S-CTRL; ioctls that act on a single control). This is needed
476since it is often required to atomically change several controls at
477once.</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
481array, a count of the number of controls in that array and a control
482class. Control classes are used to group similar controls into a
483single 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
488relating to MPEG encoding, etc.</para>
489
490 <para>All controls in the control array must belong to the
491specified control class. An error is returned if this is not the
492case.</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
496supported.</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
501values and pointers to be passed.</para>
502
503 <para>It is important to realize that due to the flexibility of
504controls it is necessary to check whether the control you want to set
505actually is supported in the driver and what the valid range of values
506is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to
507check this. Also note that it is possible that some of the menu
508indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant>
509may not be supported (<constant>VIDIOC_QUERYMENU</constant> will
510return an error). A good example is the list of supported MPEG audio
511bitrates. Some drivers only support one or two bitrates, others
512support 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
519controls 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
526qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
527while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;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
537control with a higher ID than the specified one. When no such controls
538are found an error is returned.</para>
539
540 <para>If you want to get all controls within a specific control
541class, then you can set the initial
542<structfield>qctrl.id</structfield> value to the control class and add
543an extra check to break out of the loop when a control of another
544control class is found:</para>
545
546 <informalexample>
547 <programlisting>
548qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
549while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;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
559subdivided into three bit ranges: the top 4 bits are reserved for
560flags (&eg; <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>) and are not
561actually part of the ID. The remaining 28 bits form the control ID, of
562which the most significant 12 bits define the control class and the
563least significant 16 bits identify the control within the control
564class. It is guaranteed that these last 16 bits are always non-zero
565for controls. The range of 0x1000 and up are reserved for
566driver-specific controls. The macro
567<constant>V4L2_CTRL_ID2CLASS(id)</constant> returns the control class
568ID 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
572combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In
573that case the old method of enumerating control should be used (see
5741.8). But if it is supported, then it is guaranteed to enumerate over
575all 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
582user interface where the user can select the various controls.
583Basically you will have to iterate over all controls using the method
584described 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
587control class which can be used as the title of a tab page within a
588control panel.</para>
589
590 <para>The flags field of &v4l2-queryctrl; also contains hints on
591the behavior of the control. See the &VIDIOC-QUERYCTRL; documentation
592for 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
599described. First the generic controls, then controls specific for
600certain 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>&nbsp;</entry>
625 <entry>class</entry>
626 </row><row><entry spanname="descr">The MPEG class
627descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
628description of this control class. This description can be used as the
629caption 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>&nbsp;</entry>
634 <entry>enum&nbsp;v4l2_mpeg_stream_type</entry>
635 </row><row><entry spanname="descr">The MPEG-1, -2 or -4
636output stream type. One cannot assume anything here. Each hardware
637MPEG encoder tends to support different subsets of the available MPEG
638stream 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>&nbsp;</entry>
645 <entry>MPEG-2 program stream</entry>
646 </row>
647 <row>
648 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_TS</constant>&nbsp;</entry>
649 <entry>MPEG-2 transport stream</entry>
650 </row>
651 <row>
652 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_SS</constant>&nbsp;</entry>
653 <entry>MPEG-1 system stream</entry>
654 </row>
655 <row>
656 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_DVD</constant>&nbsp;</entry>
657 <entry>MPEG-2 DVD-compatible stream</entry>
658 </row>
659 <row>
660 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_VCD</constant>&nbsp;</entry>
661 <entry>MPEG-1 VCD-compatible stream</entry>
662 </row>
663 <row>
664 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD</constant>&nbsp;</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>&nbsp;</entry>
673 <entry>integer</entry>
674 </row><row><entry spanname="descr">Program Map Table
675Packet 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>&nbsp;</entry>
680 <entry>integer</entry>
681 </row><row><entry spanname="descr">Audio Packet ID for
682the 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>&nbsp;</entry>
687 <entry>integer</entry>
688 </row><row><entry spanname="descr">Video Packet ID for
689the 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>&nbsp;</entry>
694 <entry>integer</entry>
695 </row><row><entry spanname="descr">Packet ID for the
696MPEG 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>&nbsp;</entry>
701 <entry>integer</entry>
702 </row><row><entry spanname="descr">Audio ID for MPEG
703PES</entry>
704 </row>
705 <row><entry></entry></row>
706 <row>
707 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_VIDEO</constant>&nbsp;</entry>
708 <entry>integer</entry>
709 </row><row><entry spanname="descr">Video ID for MPEG
710PES</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>&nbsp;</entry>
715 <entry>enum&nbsp;v4l2_mpeg_stream_vbi_fmt</entry>
716 </row><row><entry spanname="descr">Some cards can embed
717VBI data (&eg; Closed Caption, Teletext) into the MPEG stream. This
718control selects whether VBI data should be embedded, and if so, what
719embedding method should be used. The list of possible VBI formats
720depends on the driver. The currently defined VBI format types
721are:</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>&nbsp;</entry>
728 <entry>No VBI in the MPEG stream</entry>
729 </row>
730 <row>
731 <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant>&nbsp;</entry>
732 <entry>VBI in private packets, IVTV format (documented
733in 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>&nbsp;</entry>
741 <entry>enum&nbsp;v4l2_mpeg_audio_sampling_freq</entry>
742 </row><row><entry spanname="descr">MPEG Audio sampling
743frequency. 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>&nbsp;</entry>
750 <entry>44.1 kHz</entry>
751 </row>
752 <row>
753 <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000</constant>&nbsp;</entry>
754 <entry>48 kHz</entry>
755 </row>
756 <row>
757 <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000</constant>&nbsp;</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>&nbsp;</entry>
766 <entry>enum&nbsp;v4l2_mpeg_audio_encoding</entry>
767 </row><row><entry spanname="descr">MPEG Audio encoding.
768Possible 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>&nbsp;</entry>
775 <entry>MPEG-1/2 Layer I encoding</entry>
776 </row>
777 <row>
778 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_2</constant>&nbsp;</entry>
779 <entry>MPEG-1/2 Layer II encoding</entry>
780 </row>
781 <row>
782 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_3</constant>&nbsp;</entry>
783 <entry>MPEG-1/2 Layer III encoding</entry>
784 </row>
785 <row>
786 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant>&nbsp;</entry>
787 <entry>MPEG-2/4 AAC (Advanced Audio Coding)</entry>
788 </row>
789 <row>
790 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant>&nbsp;</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>&nbsp;</entry>
799 <entry>enum&nbsp;v4l2_mpeg_audio_l1_bitrate</entry>
800 </row><row><entry spanname="descr">MPEG-1/2 Layer I bitrate.
801Possible 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>&nbsp;</entry>
808 <entry>32 kbit/s</entry></row>
809 <row>
810 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_64K</constant>&nbsp;</entry>
811 <entry>64 kbit/s</entry>
812 </row>
813 <row>
814 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_96K</constant>&nbsp;</entry>
815 <entry>96 kbit/s</entry>
816 </row>
817 <row>
818 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_128K</constant>&nbsp;</entry>
819 <entry>128 kbit/s</entry>
820 </row>
821 <row>
822 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_160K</constant>&nbsp;</entry>
823 <entry>160 kbit/s</entry>
824 </row>
825 <row>
826 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_192K</constant>&nbsp;</entry>
827 <entry>192 kbit/s</entry>
828 </row>
829 <row>
830 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_224K</constant>&nbsp;</entry>
831 <entry>224 kbit/s</entry>
832 </row>
833 <row>
834 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_256K</constant>&nbsp;</entry>
835 <entry>256 kbit/s</entry>
836 </row>
837 <row>
838 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_288K</constant>&nbsp;</entry>
839 <entry>288 kbit/s</entry>
840 </row>
841 <row>
842 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_320K</constant>&nbsp;</entry>
843 <entry>320 kbit/s</entry>
844 </row>
845 <row>
846 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_352K</constant>&nbsp;</entry>
847 <entry>352 kbit/s</entry>
848 </row>
849 <row>
850 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_384K</constant>&nbsp;</entry>
851 <entry>384 kbit/s</entry>
852 </row>
853 <row>
854 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_416K</constant>&nbsp;</entry>
855 <entry>416 kbit/s</entry>
856 </row>
857 <row>
858 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_448K</constant>&nbsp;</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>&nbsp;</entry>
867 <entry>enum&nbsp;v4l2_mpeg_audio_l2_bitrate</entry>
868 </row><row><entry spanname="descr">MPEG-1/2 Layer II bitrate.
869Possible 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>&nbsp;</entry>
876 <entry>32 kbit/s</entry>
877 </row>
878 <row>
879 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_48K</constant>&nbsp;</entry>
880 <entry>48 kbit/s</entry>
881 </row>
882 <row>
883 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_56K</constant>&nbsp;</entry>
884 <entry>56 kbit/s</entry>
885 </row>
886 <row>
887 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_64K</constant>&nbsp;</entry>
888 <entry>64 kbit/s</entry>
889 </row>
890 <row>
891 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_80K</constant>&nbsp;</entry>
892 <entry>80 kbit/s</entry>
893 </row>
894 <row>
895 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_96K</constant>&nbsp;</entry>
896 <entry>96 kbit/s</entry>
897 </row>
898 <row>
899 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_112K</constant>&nbsp;</entry>
900 <entry>112 kbit/s</entry>
901 </row>
902 <row>
903 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_128K</constant>&nbsp;</entry>
904 <entry>128 kbit/s</entry>
905 </row>
906 <row>
907 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_160K</constant>&nbsp;</entry>
908 <entry>160 kbit/s</entry>
909 </row>
910 <row>
911 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_192K</constant>&nbsp;</entry>
912 <entry>192 kbit/s</entry>
913 </row>
914 <row>
915 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_224K</constant>&nbsp;</entry>
916 <entry>224 kbit/s</entry>
917 </row>
918 <row>
919 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_256K</constant>&nbsp;</entry>
920 <entry>256 kbit/s</entry>
921 </row>
922 <row>
923 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_320K</constant>&nbsp;</entry>
924 <entry>320 kbit/s</entry>
925 </row>
926 <row>
927 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_384K</constant>&nbsp;</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>&nbsp;</entry>
936 <entry>enum&nbsp;v4l2_mpeg_audio_l3_bitrate</entry>
937 </row><row><entry spanname="descr">MPEG-1/2 Layer III bitrate.
938Possible 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>&nbsp;</entry>
945 <entry>32 kbit/s</entry>
946 </row>
947 <row>
948 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_40K</constant>&nbsp;</entry>
949 <entry>40 kbit/s</entry>
950 </row>
951 <row>
952 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_48K</constant>&nbsp;</entry>
953 <entry>48 kbit/s</entry>
954 </row>
955 <row>
956 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_56K</constant>&nbsp;</entry>
957 <entry>56 kbit/s</entry>
958 </row>
959 <row>
960 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_64K</constant>&nbsp;</entry>
961 <entry>64 kbit/s</entry>
962 </row>
963 <row>
964 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_80K</constant>&nbsp;</entry>
965 <entry>80 kbit/s</entry>
966 </row>
967 <row>
968 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_96K</constant>&nbsp;</entry>
969 <entry>96 kbit/s</entry>
970 </row>
971 <row>
972 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_112K</constant>&nbsp;</entry>
973 <entry>112 kbit/s</entry>
974 </row>
975 <row>
976 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_128K</constant>&nbsp;</entry>
977 <entry>128 kbit/s</entry>
978 </row>
979 <row>
980 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_160K</constant>&nbsp;</entry>
981 <entry>160 kbit/s</entry>
982 </row>
983 <row>
984 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_192K</constant>&nbsp;</entry>
985 <entry>192 kbit/s</entry>
986 </row>
987 <row>
988 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_224K</constant>&nbsp;</entry>
989 <entry>224 kbit/s</entry>
990 </row>
991 <row>
992 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_256K</constant>&nbsp;</entry>
993 <entry>256 kbit/s</entry>
994 </row>
995 <row>
996 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_320K</constant>&nbsp;</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>&nbsp;</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>&nbsp;</entry>
1011 <entry>enum&nbsp;v4l2_mpeg_audio_ac3_bitrate</entry>
1012 </row><row><entry spanname="descr">AC-3 bitrate.
1013Possible 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>&nbsp;</entry>
1020 <entry>32 kbit/s</entry>
1021 </row>
1022 <row>
1023 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_40K</constant>&nbsp;</entry>
1024 <entry>40 kbit/s</entry>
1025 </row>
1026 <row>
1027 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_48K</constant>&nbsp;</entry>
1028 <entry>48 kbit/s</entry>
1029 </row>
1030 <row>
1031 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_56K</constant>&nbsp;</entry>
1032 <entry>56 kbit/s</entry>
1033 </row>
1034 <row>
1035 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_64K</constant>&nbsp;</entry>
1036 <entry>64 kbit/s</entry>
1037 </row>
1038 <row>
1039 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_80K</constant>&nbsp;</entry>
1040 <entry>80 kbit/s</entry>
1041 </row>
1042 <row>
1043 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_96K</constant>&nbsp;</entry>
1044 <entry>96 kbit/s</entry>
1045 </row>
1046 <row>
1047 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_112K</constant>&nbsp;</entry>
1048 <entry>112 kbit/s</entry>
1049 </row>
1050 <row>
1051 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_128K</constant>&nbsp;</entry>
1052 <entry>128 kbit/s</entry>
1053 </row>
1054 <row>
1055 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_160K</constant>&nbsp;</entry>
1056 <entry>160 kbit/s</entry>
1057 </row>
1058 <row>
1059 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_192K</constant>&nbsp;</entry>
1060 <entry>192 kbit/s</entry>
1061 </row>
1062 <row>
1063 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_224K</constant>&nbsp;</entry>
1064 <entry>224 kbit/s</entry>
1065 </row>
1066 <row>
1067 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_256K</constant>&nbsp;</entry>
1068 <entry>256 kbit/s</entry>
1069 </row>
1070 <row>
1071 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_320K</constant>&nbsp;</entry>
1072 <entry>320 kbit/s</entry>
1073 </row>
1074 <row>
1075 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_384K</constant>&nbsp;</entry>
1076 <entry>384 kbit/s</entry>
1077 </row>
1078 <row>
1079 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_448K</constant>&nbsp;</entry>
1080 <entry>448 kbit/s</entry>
1081 </row>
1082 <row>
1083 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_512K</constant>&nbsp;</entry>
1084 <entry>512 kbit/s</entry>
1085 </row>
1086 <row>
1087 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_576K</constant>&nbsp;</entry>
1088 <entry>576 kbit/s</entry>
1089 </row>
1090 <row>
1091 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_640K</constant>&nbsp;</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>&nbsp;</entry>
1100 <entry>enum&nbsp;v4l2_mpeg_audio_mode</entry>
1101 </row><row><entry spanname="descr">MPEG Audio mode.
1102Possible 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>&nbsp;</entry>
1109 <entry>Stereo</entry>
1110 </row>
1111 <row>
1112 <entry><constant>V4L2_MPEG_AUDIO_MODE_JOINT_STEREO</constant>&nbsp;</entry>
1113 <entry>Joint Stereo</entry>
1114 </row>
1115 <row>
1116 <entry><constant>V4L2_MPEG_AUDIO_MODE_DUAL</constant>&nbsp;</entry>
1117 <entry>Bilingual</entry>
1118 </row>
1119 <row>
1120 <entry><constant>V4L2_MPEG_AUDIO_MODE_MONO</constant>&nbsp;</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>&nbsp;</entry>
1129 <entry>enum&nbsp;v4l2_mpeg_audio_mode_extension</entry>
1130 </row><row><entry spanname="descr">Joint Stereo
1131audio mode extension. In Layer I and II they indicate which subbands
1132are in intensity stereo. All other subbands are coded in stereo. Layer
1133III is not (yet) supported. Possible values
1134are:</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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</entry>
1161 <entry>enum&nbsp;v4l2_mpeg_audio_emphasis</entry>
1162 </row><row><entry spanname="descr">Audio Emphasis.
1163Possible 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>&nbsp;</entry>
1170 <entry>None</entry>
1171 </row>
1172 <row>
1173 <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS</constant>&nbsp;</entry>
1174 <entry>50/15 microsecond emphasis</entry>
1175 </row>
1176 <row>
1177 <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17</constant>&nbsp;</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>&nbsp;</entry>
1186 <entry>enum&nbsp;v4l2_mpeg_audio_crc</entry>
1187 </row><row><entry spanname="descr">CRC method. Possible
1188values 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>&nbsp;</entry>
1195 <entry>None</entry>
1196 </row>
1197 <row>
1198 <entry><constant>V4L2_MPEG_AUDIO_CRC_CRC16</constant>&nbsp;</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>&nbsp;</entry>
1207 <entry>boolean</entry>
1208 </row><row><entry spanname="descr">Mutes the audio when
1209capturing. This is not done by muting audio hardware, which can still
1210produce a slight hiss, but in the encoder itself, guaranteeing a fixed
1211and 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>&nbsp;</entry>
1216 <entry>enum&nbsp;v4l2_mpeg_video_encoding</entry>
1217 </row><row><entry spanname="descr">MPEG Video encoding
1218method. 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>&nbsp;</entry>
1225 <entry>MPEG-1 Video encoding</entry>
1226 </row>
1227 <row>
1228 <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_2</constant>&nbsp;</entry>
1229 <entry>MPEG-2 Video encoding</entry>
1230 </row>
1231 <row>
1232 <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant>&nbsp;</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>&nbsp;</entry>
1241 <entry>enum&nbsp;v4l2_mpeg_video_aspect</entry>
1242 </row><row><entry spanname="descr">Video aspect.
1243Possible 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>&nbsp;</entry>
1250 </row>
1251 <row>
1252 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_4x3</constant>&nbsp;</entry>
1253 </row>
1254 <row>
1255 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_16x9</constant>&nbsp;</entry>
1256 </row>
1257 <row>
1258 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_221x100</constant>&nbsp;</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>&nbsp;</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>&nbsp;</entry>
1273 <entry>integer</entry>
1274 </row><row><entry spanname="descr">GOP size (default
127512)</entry>
1276 </row>
1277 <row><entry></entry></row>
1278 <row>
1279 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_CLOSURE</constant>&nbsp;</entry>
1280 <entry>boolean</entry>
1281 </row><row><entry spanname="descr">GOP closure (default
12821)</entry>
1283 </row>
1284 <row><entry></entry></row>
1285 <row>
1286 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_PULLDOWN</constant>&nbsp;</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>&nbsp;</entry>
1294 <entry>enum&nbsp;v4l2_mpeg_video_bitrate_mode</entry>
1295 </row><row><entry spanname="descr">Video bitrate mode.
1296Possible 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>&nbsp;</entry>
1303 <entry>Variable bitrate</entry>
1304 </row>
1305 <row>
1306 <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_CBR</constant>&nbsp;</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>&nbsp;</entry>
1315 <entry>integer</entry>
1316 </row><row><entry spanname="descr">Video bitrate in bits
1317per second.</entry>
1318 </row>
1319 <row><entry></entry></row>
1320 <row>
1321 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_PEAK</constant>&nbsp;</entry>
1322 <entry>integer</entry>
1323 </row><row><entry spanname="descr">Peak video bitrate in
1324bits per second. Must be larger or equal to the average video bitrate.
1325It is ignored if the video bitrate mode is set to constant
1326bitrate.</entry>
1327 </row>
1328 <row><entry></entry></row>
1329 <row>
1330 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION</constant>&nbsp;</entry>
1331 <entry>integer</entry>
1332 </row><row><entry spanname="descr">For every captured
1333frame, 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>&nbsp;</entry>
1338 <entry>boolean</entry>
1339 </row>
1340 <row><entry spanname="descr">"Mutes" the video to a
1341fixed color when capturing. This is useful for testing, to produce a
1342fixed 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>&nbsp;</entry>
1347 <entry>integer</entry>
1348 </row><row><entry spanname="descr">Sets the "mute" color
1349of the video. The supplied 32-bit integer is interpreted as follows (bit
13500 = 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
1383encoding settings that are specific to the Conexant CX23415 and
1384CX23416 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>&nbsp;</entry>
1406 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_spatial_filter_mode</entry>
1407 </row><row><entry spanname="descr">Sets the Spatial
1408Filter mode (default <constant>MANUAL</constant>). Possible values
1409are:</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>&nbsp;</entry>
1416 <entry>Choose the filter manually</entry>
1417 </row>
1418 <row>
1419 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO</constant>&nbsp;</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>&nbsp;</entry>
1428 <entry>integer&nbsp;(0-15)</entry>
1429 </row><row><entry spanname="descr">The setting for the
1430Spatial 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>&nbsp;</entry>
1435 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</entry>
1436 </row><row><entry spanname="descr">Select the algorithm
1437to 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>&nbsp;</entry>
1445 <entry>No filter</entry>
1446 </row>
1447 <row>
1448 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR</constant>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</entry>
1461 <entry>Two-dimensional symmetrical
1462non-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>&nbsp;</entry>
1470 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</entry>
1471 </row><row><entry spanname="descr">Select the algorithm
1472for the Chroma Spatial Filter (default <constant>1D_HOR</constant>).
1473Possible 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>&nbsp;</entry>
1480 <entry>No filter</entry>
1481 </row>
1482 <row>
1483 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR</constant>&nbsp;</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>&nbsp;</entry>
1492 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_temporal_filter_mode</entry>
1493 </row><row><entry spanname="descr">Sets the Temporal
1494Filter mode (default <constant>MANUAL</constant>). Possible values
1495are:</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>&nbsp;</entry>
1502 <entry>Choose the filter manually</entry>
1503 </row>
1504 <row>
1505 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO</constant>&nbsp;</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>&nbsp;</entry>
1514 <entry>integer&nbsp;(0-31)</entry>
1515 </row><row><entry spanname="descr">The setting for the
1516Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for full-scale
1517capturing 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>&nbsp;</entry>
1522 <entry>enum&nbsp;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>&nbsp;</entry>
1531 <entry>No filter</entry>
1532 </row>
1533 <row>
1534 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR</constant>&nbsp;</entry>
1535 <entry>Horizontal filter</entry>
1536 </row>
1537 <row>
1538 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT</constant>&nbsp;</entry>
1539 <entry>Vertical filter</entry>
1540 </row>
1541 <row>
1542 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT</constant>&nbsp;</entry>
1543 <entry>Horizontal and vertical filter</entry>
1544 </row>
1545 <row>
1546 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG</constant>&nbsp;</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>&nbsp;</entry>
1555 <entry>integer&nbsp;(0-255)</entry>
1556 </row><row><entry spanname="descr">Threshold above which
1557the 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>&nbsp;</entry>
1562 <entry>integer&nbsp;(0-255)</entry>
1563 </row><row><entry spanname="descr">Threshold below which
1564the 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>&nbsp;</entry>
1569 <entry>integer&nbsp;(0-255)</entry>
1570 </row><row><entry spanname="descr">Threshold above which
1571the 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>&nbsp;</entry>
1576 <entry>integer&nbsp;(0-255)</entry>
1577 </row><row><entry spanname="descr">Threshold below which
1578the 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>&nbsp;</entry>
1583 <entry>boolean</entry>
1584 </row>
1585 <row><entry spanname="descr">The CX2341X MPEG encoder
1586can insert one empty MPEG-2 PES packet into the stream between every
1587four video frames. The packet size is 2048 bytes, including the
1588packet_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
1590in 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
1602equivalent digital) features of a device such as controllable lenses
1603or 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>&nbsp;</entry>
1625 <entry>class</entry>
1626 </row><row><entry spanname="descr">The Camera class
1627descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
1628description 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>&nbsp;</entry>
1634 <entry>enum&nbsp;v4l2_exposure_auto_type</entry>
1635 </row><row><entry spanname="descr">Enables automatic
1636adjustments of the exposure time and/or iris aperture. The effect of
1637manual changes of the exposure time or iris aperture while these
1638features are enabled is undefined, drivers should ignore such
1639requests. 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>&nbsp;</entry>
1646 <entry>Automatic exposure time, automatic iris
1647aperture.</entry>
1648 </row>
1649 <row>
1650 <entry><constant>V4L2_EXPOSURE_MANUAL</constant>&nbsp;</entry>
1651 <entry>Manual exposure time, manual iris.</entry>
1652 </row>
1653 <row>
1654 <entry><constant>V4L2_EXPOSURE_SHUTTER_PRIORITY</constant>&nbsp;</entry>
1655 <entry>Manual exposure time, auto iris.</entry>
1656 </row>
1657 <row>
1658 <entry><constant>V4L2_EXPOSURE_APERTURE_PRIORITY</constant>&nbsp;</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>&nbsp;</entry>
1668 <entry>integer</entry>
1669 </row><row><entry spanname="descr">Determines the exposure
1670time of the camera sensor. The exposure time is limited by the frame
1671interval. Drivers should interpret the values as 100 &micro;s units,
1672where the value 1 stands for 1/10000th of a second, 10000 for 1 second
1673and 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>&nbsp;</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>,
1683this control determines if the device may dynamically vary the frame
1684rate. By default this feature is disabled (0) and the frame rate must
1685remain constant.</entry>
1686 </row>
1687 <row><entry></entry></row>
1688
1689 <row>
1690 <entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant>&nbsp;</entry>
1691 <entry>integer</entry>
1692 </row><row><entry spanname="descr">This control turns the
1693camera horizontally by the specified amount. The unit is undefined. A
1694positive value moves the camera to the right (clockwise when viewed
1695from above), a negative value to the left. A value of zero does not
1696cause 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>&nbsp;</entry>
1702 <entry>integer</entry>
1703 </row><row><entry spanname="descr">This control turns the
1704camera vertically by the specified amount. The unit is undefined. A
1705positive value moves the camera up, a negative value down. A value of
1706zero 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>&nbsp;</entry>
1712 <entry>button</entry>
1713 </row><row><entry spanname="descr">When this control is set,
1714the 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>&nbsp;</entry>
1720 <entry>button</entry>
1721 </row><row><entry spanname="descr">When this control is set,
1722the 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>&nbsp;</entry>
1728 <entry>integer</entry>
1729 </row><row><entry spanname="descr">This control
1730turns the camera horizontally to the specified position. Positive
1731values move the camera to the right (clockwise when viewed from above),
1732negative values to the left. Drivers should interpret the values as arc
1733seconds, with valid values between -180 * 3600 and +180 * 3600
1734inclusive.</entry>
1735 </row>
1736 <row><entry></entry></row>
1737
1738 <row>
1739 <entry spanname="id"><constant>V4L2_CID_TILT_ABSOLUTE</constant>&nbsp;</entry>
1740 <entry>integer</entry>
1741 </row><row><entry spanname="descr">This control
1742turns the camera vertically to the specified position. Positive values
1743move the camera up, negative values down. Drivers should interpret the
1744values 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>&nbsp;</entry>
1751 <entry>integer</entry>
1752 </row><row><entry spanname="descr">This control sets the
1753focal point of the camera to the specified position. The unit is
1754undefined. Positive values set the focus closer to the camera,
1755negative values towards infinity.</entry>
1756 </row>
1757 <row><entry></entry></row>
1758
1759 <row>
1760 <entry spanname="id"><constant>V4L2_CID_FOCUS_RELATIVE</constant>&nbsp;</entry>
1761 <entry>integer</entry>
1762 </row><row><entry spanname="descr">This control moves the
1763focal point of the camera by the specified amount. The unit is
1764undefined. Positive values move the focus closer to the camera,
1765negative 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>&nbsp;</entry>
1771 <entry>boolean</entry>
1772 </row><row><entry spanname="descr">Enables automatic focus
1773adjustments. The effect of manual focus adjustments while this feature
1774is 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>&nbsp;</entry>
1780 <entry>integer</entry>
1781 </row><row><entry spanname="descr">Specify the objective lens
1782focal length as an absolute value. The zoom unit is driver-specific and its
1783value 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>&nbsp;</entry>
1789 <entry>integer</entry>
1790 </row><row><entry spanname="descr">Specify the objective lens
1791focal length relatively to the current value. Positive values move the zoom
1792lens group towards the telephoto direction, negative values towards the
1793wide-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>&nbsp;</entry>
1799 <entry>integer</entry>
1800 </row><row><entry spanname="descr">Move the objective lens group
1801at the specified speed until it reaches physical device limits or until an
1802explicit request to stop the movement. A positive value moves the zoom lens
1803group towards the telephoto direction. A value of zero stops the zoom lens
1804group movement. A negative value moves the zoom lens group towards the
1805wide-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>&nbsp;</entry>
1811 <entry>boolean</entry>
1812 </row><row><entry spanname="descr">Prevent video from being acquired
1813by the camera. When this control is set to <constant>TRUE</constant> (1), no
1814image can be captured by the camera. Common means to enforce privacy are
1815mechanical obturation of the sensor and firmware image processing, but the
1816device is not restricted to these methods. Devices that implement the privacy
1817control 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>&nbsp;</entry>
1822 <entry>integer</entry>
1823 </row><row><entry spanname="descr">Switch the band-stop filter of a
1824camera sensor on or off, or specify its strength. Such band-stop filters can
1825be 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
1837FM transmissions capable devices. Currently this class includes parameters for audio
1838compression, pilot tone generation, audio deviation limiter, RDS transmission and
1839tuning 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>&nbsp;</entry>
1862 <entry>class</entry>
1863 </row><row><entry spanname="descr">The FM_TX class
1864descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
1865description of this control class.</entry>
1866 </row>
1867 <row>
1868 <entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant>&nbsp;</entry>
1869 <entry>integer</entry>
1870 </row>
1871 <row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz.
1872The range and step are driver-specific.</entry>
1873 </row>
1874 <row>
1875 <entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant>&nbsp;</entry>
1876 <entry>integer</entry>
1877 </row>
1878 <row><entry spanname="descr">Sets the RDS Programme Identification field
1879for transmission.</entry>
1880 </row>
1881 <row>
1882 <entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant>&nbsp;</entry>
1883 <entry>integer</entry>
1884 </row>
1885 <row><entry spanname="descr">Sets the RDS Programme Type field for transmission.
1886This 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>&nbsp;</entry>
1890 <entry>string</entry>
1891 </row>
1892 <row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission.
1893It is intended for static display on a receiver. It is the primary aid to listeners in programme service
1894identification and selection. In Annex E of <xref linkend="en50067" />, the RDS specification,
1895there is a full description of the correct character encoding for Programme Service name strings.
1896Also from RDS specification, PS is usually a single eight character text. However, it is also possible
1897to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured
1898with 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>&nbsp;</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
1905what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names,
1906programme-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
1908in Annex E of <xref linkend="en50067" />. The length of Radio Text strings depends on which RDS Block is being
1909used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible
1910to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured
1911with 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>&nbsp;</entry>
1915 <entry>boolean</entry>
1916 </row>
1917 <row><entry spanname="descr">Enables or disables the audio deviation limiter feature.
1918The limiter is useful when trying to maximize the audio volume, minimize receiver-generated
1919distortion and prevent overmodulation.
1920</entry>
1921 </row>
1922 <row>
1923 <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant>&nbsp;</entry>
1924 <entry>integer</entry>
1925 </row>
1926 <row><entry spanname="descr">Sets the audio deviation limiter feature release time.
1927Unit 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>&nbsp;</entry>
1931 <entry>integer</entry>
1932 </row>
1933 <row><entry spanname="descr">Configures audio frequency deviation level in Hz.
1934The range and step are driver-specific.</entry>
1935 </row>
1936 <row>
1937 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant>&nbsp;</entry>
1938 <entry>boolean</entry>
1939 </row>
1940 <row><entry spanname="descr">Enables or disables the audio compression feature.
1941This feature amplifies signals below the threshold by a fixed gain and compresses audio
1942signals 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>&nbsp;</entry>
1946 <entry>integer</entry>
1947 </row>
1948 <row><entry spanname="descr">Sets the gain for audio compression feature. It is
1949a 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>&nbsp;</entry>
1953 <entry>integer</entry>
1954 </row>
1955 <row><entry spanname="descr">Sets the threshold level for audio compression freature.
1956It 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>&nbsp;</entry>
1960 <entry>integer</entry>
1961 </row>
1962 <row><entry spanname="descr">Sets the attack time for audio compression feature.
1963It 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>&nbsp;</entry>
1967 <entry>integer</entry>
1968 </row>
1969 <row><entry spanname="descr">Sets the release time for audio compression feature.
1970It 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>&nbsp;</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>&nbsp;</entry>
1980 <entry>integer</entry>
1981 </row>
1982 <row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is
1983in Hz. The range and step are driver-specific.</entry>
1984 </row>
1985 <row>
1986 <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant>&nbsp;</entry>
1987 <entry>integer</entry>
1988 </row>
1989 <row><entry spanname="descr">Configures pilot tone frequency value. Unit is
1990in Hz. The range and step are driver-specific.</entry>
1991 </row>
1992 <row>
1993 <entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant>&nbsp;</entry>
1994 <entry>integer</entry>
1995 </row>
1996 <row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting.
1997A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies.
1998Depending on the region, a time constant of either 50 or 75 useconds is used. The enum&nbsp;v4l2_preemphasis
1999defines 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>&nbsp;</entry>
2005 <entry>No pre-emphasis is applied.</entry>
2006 </row>
2007 <row>
2008 <entry><constant>V4L2_PREEMPHASIS_50_uS</constant>&nbsp;</entry>
2009 <entry>A pre-emphasis of 50 uS is used.</entry>
2010 </row>
2011 <row>
2012 <entry><constant>V4L2_PREEMPHASIS_75_uS</constant>&nbsp;</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>&nbsp;</entry>
2021 <entry>integer</entry>
2022 </row>
2023 <row><entry spanname="descr">Sets the output power level for signal transmission.
2024Unit 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>&nbsp;</entry>
2028 <entry>integer</entry>
2029 </row>
2030 <row><entry spanname="descr">This selects the value of antenna tuning capacitor
2031manually 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 <!--
2044Local Variables:
2045mode: sgml
2046sgml-parent-document: "common.sgml"
2047indent-tabs-mode: nil
2048End:
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
4the digitized images in memory. Today nearly all devices can capture
5at full 25 or 30 frames/second. With this interface applications can
6control the capture process and move images from the driver into user
7space.</para>
8
9 <para>Conventionally V4L2 video capture devices are accessed through
10character device special files named <filename>/dev/video</filename>
11and <filename>/dev/video0</filename> to
12<filename>/dev/video63</filename> with major number 81 and minor
13numbers 0 to 63. <filename>/dev/video</filename> is typically a
14symbolic link to the preferred video device. Note the same device
15files 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;
23returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
24they may also support the <link linkend="overlay">video overlay</link>
25(<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link
26linkend="raw-vbi">raw VBI capture</link>
27(<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of
28the read/write or streaming I/O methods must be supported. Tuners and
29audio inputs are optional.</para>
30 </section>
31
32 <section>
33 <title>Supplemental Functions</title>
34
35 <para>Video capture devices shall support <link
36linkend="audio">audio input</link>, <link
37linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
38<link linkend="crop">cropping and scaling</link> and <link
39linkend="streaming-par">streaming parameter</link> ioctls as needed.
40The <link linkend="video">video input</link> and <link
41linkend="standard">video standard</link> ioctls must be supported by
42all 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
49cropping and image format parameters. The former select an area of the
50video 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
52height. Together they also define how images are scaled in the
53process.</para>
54
55 <para>As usual these parameters are <emphasis>not</emphasis> reset
56at &func-open; time to permit Unix tool chains, programming a device
57and then reading from it as if it was a plain file. Well written V4L2
58applications ensure they really get what they want, including cropping
59and scaling.</para>
60
61 <para>Cropping initialization at minimum requires to reset the
62parameters to defaults. An example is given in <xref
63linkend="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
69the &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
74initialize all fields of the &v4l2-pix-format;
75<structfield>vbi</structfield> member of the
76<structfield>fmt</structfield> union, or better just modify the
77results of <constant>VIDIOC_G_FMT</constant>, and call the
78&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
79adjust 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
84without disabling I/O or possibly time consuming hardware
85preparations.</para>
86
87 <para>The contents of &v4l2-pix-format; are discussed in <xref
88linkend="pixfmt" />. See also the specification of the
89<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
90and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
91capture 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
95returns 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
103linkend="rw">read() function</link> and/or streaming (<link
104linkend="mmap">memory mapping</link> or <link
105linkend="userp">user pointer</link>) I/O. See <xref
106linkend="io" /> for details.</para>
107 </section>
108
109 <!--
110Local Variables:
111mode: sgml
112sgml-parent-document: "v4l2.sgml"
113indent-tabs-mode: nil
114End:
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
7implemented in Linux 2.6 until we have more experience with codec
8device interfaces.</para>
9 </note>
10
11 <para>A V4L2 codec can compress, decompress, transform, or otherwise
12convert video data from one format into another format, in memory.
13Applications 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
16I/O.</para>
17
18 <para>[to do]</para>
19
20 <!--
21Local Variables:
22mode: sgml
23sgml-parent-document: "v4l2.sgml"
24indent-tabs-mode: nil
25End:
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
7implemented in Linux 2.6 until we have more experience with effect
8device interfaces.</para>
9 </note>
10
11 <para>A V4L2 video effect device can do image effects, filtering, or
12combine two or more images or image streams. For example video
13transitions or wipes. Applications send data to be processed and
14receive the result data either with &func-read; and &func-write;
15functions, or through the streaming I/O mechanism.</para>
16
17 <para>[to do]</para>
18
19 <!--
20Local Variables:
21mode: sgml
22sgml-parent-document: "v4l2.sgml"
23indent-tabs-mode: nil
24End:
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>
8interface and may change in the future.</para>
9 </note>
10
11 <para>Some video output devices can overlay a framebuffer image onto
12the outgoing video signal. Applications can set up such an overlay
13using this interface, which borrows structures and ioctls of the <link
14linkend="overlay">Video Overlay</link> interface.</para>
15
16 <para>The OSD function is accessible through the same character
17special file as the <link linkend="capture">Video Output</link> function.
18Note the default function of such a <filename>/dev/video</filename> device
19is video capturing or output. The OSD function is only available after
20calling the &VIDIOC-S-FMT; ioctl.</para>
21
22 <section>
23 <title>Querying Capabilities</title>
24
25 <para>Devices supporting the <wordasword>Video Output
26Overlay</wordasword> interface set the
27<constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the
28<structfield>capabilities</structfield> field of &v4l2-capability;
29returned 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>
36interface the framebuffer is normally implemented on the TV card and
37not the graphics card. On Linux it is accessible as a framebuffer
38device (<filename>/dev/fbN</filename>). Given a V4L2 device,
39applications can find the corresponding framebuffer device by calling
40the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the
41physical address of the framebuffer in the
42<structfield>base</structfield> field of &v4l2-framebuffer;. The
43framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant>
44returns the same address in the <structfield>smem_start</structfield>
45field 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
51current video standard. A V4L2 driver may reject attempts to change
52the video standard (or any other ioctl which would imply a framebuffer
53size change) with an &EBUSY; until all applications closed the
54framebuffer device.</para>
55
56 <example>
57 <title>Finding a framebuffer device for OSD</title>
58
59 <programlisting>
60#include &lt;linux/fb.h&gt;
61
62&v4l2-framebuffer; fbuf;
63unsigned int i;
64int fb_fd;
65
66if (-1 == ioctl (fd, VIDIOC_G_FBUF, &amp;fbuf)) {
67 perror ("VIDIOC_G_FBUF");
68 exit (EXIT_FAILURE);
69}
70
71for (i = 0; i &gt; 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, &amp;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.
111The source rectangle selects a subsection of the framebuffer image to
112be overlaid, the target rectangle an area in the outgoing video signal
113where the image will appear. Drivers may or may not support scaling,
114and arbitrary sizes and positions of these rectangles. Further drivers
115may support any (or none) of the clipping/blending methods defined for
116the <link linkend="overlay">Video Overlay</link> interface.</para>
117
118 <para>A &v4l2-window; defines the size of the source rectangle,
119its position in the framebuffer and the clipping/blending method to be
120used for the overlay. To get the current parameters applications set
121the <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
126previously 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
131the <structfield>win</structfield> substructure and call the
132&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
133hardware 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
136used to learn about driver capabilities without actually changing
137driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
138after the overlay has been enabled.</para>
139
140 <para>A &v4l2-crop; defines the size and position of the target
141rectangle. The scaling factor of the overlay is implied by the width
142and height given in &v4l2-window; and &v4l2-crop;. The cropping API
143applies to <wordasword>Video Output</wordasword> and <wordasword>Video
144Output Overlay</wordasword> devices in the same way as to
145<wordasword>Video Capture</wordasword> and <wordasword>Video
146Overlay</wordasword> devices, merely reversing the direction of the
147data 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,
154however the framebuffer interface of the driver may support the
155<constant>FBIOBLANK</constant> ioctl.</para>
156 </section>
157
158 <!--
159Local Variables:
160mode: sgml
161sgml-parent-document: "v4l2.sgml"
162indent-tabs-mode: nil
163End:
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
4analog video signal. With this interface applications can
5control the encoding process and move images from user space to
6the driver.</para>
7
8 <para>Conventionally V4L2 video output devices are accessed through
9character device special files named <filename>/dev/video</filename>
10and <filename>/dev/video0</filename> to
11<filename>/dev/video63</filename> with major number 81 and minor
12numbers 0 to 63. <filename>/dev/video</filename> is typically a
13symbolic link to the preferred video device. Note the same device
14files 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;
22returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
23they may also support the <link linkend="raw-vbi">raw VBI
24output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At
25least one of the read/write or streaming I/O methods must be
26supported. 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
33linkend="audio">audio output</link>, <link
34linkend="tuner">modulator</link>, <link linkend="control">controls</link>,
35<link linkend="crop">cropping and scaling</link> and <link
36linkend="streaming-par">streaming parameter</link> ioctls as needed.
37The <link linkend="video">video output</link> and <link
38linkend="standard">video standard</link> ioctls must be supported by
39all 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
46parameters. The former select an area of the video picture where the
47image will appear, the latter how images are stored in memory, &ie; in
48RGB or YUV format, the number of bits per pixel or width and height.
49Together they also define how images are scaled in the process.</para>
50
51 <para>As usual these parameters are <emphasis>not</emphasis> reset
52at &func-open; time to permit Unix tool chains, programming a device
53and then writing to it as if it was a plain file. Well written V4L2
54applications ensure they really get what they want, including cropping
55and scaling.</para>
56
57 <para>Cropping initialization at minimum requires to reset the
58parameters to defaults. An example is given in <xref
59linkend="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
65the &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
70initialize all fields of the &v4l2-pix-format;
71<structfield>vbi</structfield> member of the
72<structfield>fmt</structfield> union, or better just modify the
73results of <constant>VIDIOC_G_FMT</constant>, and call the
74&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
75adjust 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
80without disabling I/O or possibly time consuming hardware
81preparations.</para>
82
83 <para>The contents of &v4l2-pix-format; are discussed in <xref
84linkend="pixfmt" />. See also the specification of the
85<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
86and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
87output 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
91returns 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
99linkend="rw">write() function</link> and/or streaming (<link
100linkend="mmap">memory mapping</link> or <link
101linkend="userp">user pointer</link>) I/O. See <xref
102linkend="io" /> for details.</para>
103 </section>
104
105 <!--
106Local Variables:
107mode: sgml
108sgml-parent-document: "v4l2.sgml"
109indent-tabs-mode: nil
110End:
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
5into the (VGA-)video signal of a graphics card, or to store captured
6images directly in video memory of a graphics card, typically with
7clipping. This can be considerable more efficient than capturing
8images and displaying them by other means. In the old days when only
9nuclear power plants needed cooling towers this used to be the only
10way to put live video into a window.</para>
11
12 <para>Video overlay devices are accessed through the same character
13special files as <link linkend="capture">video capture</link> devices.
14Note the default function of a <filename>/dev/video</filename> device
15is video capturing. The overlay function is only available after
16calling the &VIDIOC-S-FMT; ioctl.</para>
17
18 <para>The driver may support simultaneous overlay and capturing
19using the read/write and streaming I/O methods. If so, operation at
20the nominal frame rate of the video standard is not guaranteed. Frames
21may be directed away from overlay to capture, or one field may be used
22for overlay and the other for capture if the capture parameters permit
23this.</para>
24
25 <para>Applications should use different file descriptors for
26capturing and overlay. This must be supported by all drivers capable
27of simultaneous capturing and overlay. Optionally these drivers may
28also permit capturing and overlay with a single file descriptor for
29compatibility with V4L and earlier versions of V4L2.<footnote>
30 <para>A common application of two file descriptors is the
31XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and
32a V4L2 application. While the X server controls video overlay, the
33application can take advantage of memory mapping and DMA.</para>
34 <para>In the opinion of the designers of this API, no driver
35writer taking the efforts to support simultaneous capturing and
36overlay will restrict this ability by requiring a single file
37descriptor, as in V4L and earlier versions of V4L2. Making this
38optional means applications depending on two file descriptors need
39backup routines to be compatible with all drivers, which is
40considerable more work than using two fds in applications which do
41not. Also two fd's fit the general concept of one file descriptor for
42each 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;
53returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified
54below 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
61linkend="audio">audio input</link>, <link
62linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
63<link linkend="crop">cropping and scaling</link> and <link
64linkend="streaming-par">streaming parameter</link> ioctls as needed.
65The <link linkend="video">video input</link> and <link
66linkend="standard">video standard</link> ioctls must be supported by
67all video overlay devices.</para>
68 </section>
69
70 <section>
71 <title>Setup</title>
72
73 <para>Before overlay can commence applications must program the
74driver with frame buffer parameters, namely the address and size of
75the 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
77and set these parameters, respectively. The
78<constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it
79allows to set up DMA into physical memory, bypassing the memory
80protection mechanisms of the kernel. Only the superuser can change the
81frame buffer address and size. Users are not supposed to run TV
82applications as root or with SUID bit set. A small helper application
83with suitable privileges should query the graphics system and program
84the V4L2 driver at the appropriate time.</para>
85
86 <para>Some devices add the video overlay to the output signal
87of the graphics card. In this case the frame buffer is not modified by
88the video device, and the frame buffer address and pixel format are
89not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl
90is not privileged. An application can check for this type of device by
91calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para>
92
93 <para>A driver may support any (or none) of five clipping/blending
94methods:<orderedlist>
95 <listitem>
96 <para>Chroma-keying displays the overlaid image only where
97pixels 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
101to a pixel in the overlaid image. When the bit is set, the
102corresponding video pixel is displayed, otherwise a pixel of the
103graphics surface.</para>
104 </listitem>
105 <listitem>
106 <para>A list of clipping rectangles can be specified. In
107these regions <emphasis>no</emphasis> video is displayed, so the
108graphics surface can be seen here.</para>
109 </listitem>
110 <listitem>
111 <para>The framebuffer has an alpha channel that can be used
112to 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
116framebuffer contents with video images.</para>
117 </listitem>
118 </orderedlist></para>
119
120 <para>When simultaneous capturing and overlay is supported and
121the hardware prohibits different image and frame buffer formats, the
122format 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
131window parameters. The former select an area of the video picture to
132capture, the latter how images are overlaid and clipped. Cropping
133initialization at minimum requires to reset the parameters to
134defaults. An example is given in <xref linkend="crop" />.</para>
135
136 <para>The overlay window is described by a &v4l2-window;. It
137defines the size of the image, its position over the graphics surface
138and the clipping to be applied. To get the current parameters
139applications set the <structfield>type</structfield> field of a
140&v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant> and
141call 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
144previously 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
151hardware 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
154used to learn about driver capabilities without actually changing
155driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
156after the overlay has been enabled.</para>
157
158 <para>The scaling factor of the overlaid image is implied by the
159width and height given in &v4l2-window; and the size of the cropping
160rectangle. For more information see <xref linkend="crop" />.</para>
161
162 <para>When simultaneous capturing and overlay is supported and
163the hardware prohibits different image and window sizes, the size
164requested first takes precedence. The attempt to capture or overlay as
165well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly
166modified 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
177top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The
178window can extend the frame buffer width and height, the
179<structfield>x</structfield> and <structfield>y</structfield>
180coordinates can be negative, and it can lie completely outside the
181frame buffer. The driver clips the window accordingly, or if that is
182not 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
188video 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
193a 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
200for the chroma key. The format is the same as the pixel format of the
201framebuffer (&v4l2-framebuffer;
202<structfield>fmt.pixelformat</structfield> field), with bytes in host
203order. E.&nbsp;g. for <link
204linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link>
205the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big
206endian 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>
212been negotiated and &VIDIOC-G-FBUF; indicated this capability,
213applications can set this field to point to an array of
214clipping 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
221to the top, left corner of the frame buffer. However clipping
222rectangles must not extend the frame buffer width and height, and they
223must not overlap. If possible applications should merge adjacent
224rectangles. Whether this must create x-y or y-x bands, or the order of
225rectangles, is not defined. When clip lists are not supported the
226driver ignores this field. Its contents after calling &VIDIOC-S-FMT;
227are 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
234number of clipping rectangles in the list. When clip lists are not
235supported the driver ignores this field, its contents after calling
236<constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are
237supported but no clipping is desired this field must be set to
238zero.</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
245this capability, applications can set this field to point to a
246clipping bit mask.</entry>
247 </row>
248 <row>
249 <entry spanname="hspan"><para>It must be of the same size
250as the window, <structfield>w.width</structfield> and
251<structfield>w.height</structfield>. Each bit corresponds to a pixel
252in 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] &amp; (1 &lt;&lt; (x &amp; 7))</programlisting></para><para>where <structfield>0</structfield> &le; x &lt;
256<structfield>w.width</structfield> and <structfield>0</structfield> &le;
257y &lt;<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
262bit mask is not supported the driver ignores this field, its contents
263after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported
264but no clipping is desired this field must be set to
265<constant>NULL</constant>.</para><para>Applications need not create a
266clip list or bit mask. When they pass both, or despite negotiating
267chroma-keying, the results are undefined. Regardless of the chosen
268method, the clipping abilities of the hardware may be limited in
269quantity or quality. The results when these limits are exceeded are
270undefined.<footnote>
271 <para>When the image is written into frame buffer
272memory it will be undesirable if the driver clips out less pixels
273than expected, because the application and graphics system are not
274aware these regions need to be refreshed. The driver should clip out
275more 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
282framebuffer with video images, if global alpha blending has been
283negotiated (<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
290the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls,
291which take a pointer to a <link
292linkend="v4l2-format">v4l2_format</link> parent structure with padding
293bytes 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
302vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 -
303x1 and height = y2 - y1, so one cannot pass X11 clip lists
304directly.</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
313the top, left corner of the frame buffer. Only window pixels
314<emphasis>outside</emphasis> all clipping rectangles are
315displayed.</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
321this is the last rectangle. Drivers ignore this field, it cannot be
322used 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
340rectangle, 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
346rectangle, 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
357height cannot be negative, the fields are signed for hysterical
358reasons. <!-- 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
370the &VIDIOC-OVERLAY; ioctl.</para>
371 </section>
372
373 <!--
374Local Variables:
375mode: sgml
376sgml-parent-document: "v4l2.sgml"
377indent-tabs-mode: nil
378End:
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
4receivers and transmitters.</para>
5
6 <para>Conventionally V4L2 radio devices are accessed through
7character device special files named <filename>/dev/radio</filename>
8and <filename>/dev/radio0</filename> to
9<filename>/dev/radio63</filename> with major number 81 and minor
10numbers 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;
20returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of
21capability 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
28linkend="control">controls</link>, and must support the <link
29linkend="tuner">tuner or modulator</link> ioctls.</para>
30
31 <para>They do not support the video input or output, audio input
32or output, video standard, cropping and scaling, compression and
33streaming parameter, or overlay ioctls. All other ioctls and I/O
34methods 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
41in <xref linkend="control" />) such as a volume control, possibly custom
42controls. Further all radio devices have one tuner or modulator (these are
43discussed in <xref linkend="tuner" />) with index number zero to select
44the radio frequency and to determine if a monaural or FM stereo
45program is received/emitted. Drivers switch automatically between AM and FM
46depending on the selected frequency. The &VIDIOC-G-TUNER; or
47&VIDIOC-G-MODULATOR; ioctl
48reports the supported frequency range.</para>
49 </section>
50
51<!--
52Local Variables:
53mode: sgml
54sgml-parent-document: "v4l2.sgml"
55indent-tabs-mode: nil
56End:
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
4in the sequence of lines of an analog video signal. During VBI
5no picture information is transmitted, allowing some time while the
6electron beam of a cathode ray tube TV returns to the top of the
7screen. Using an oscilloscope you will find here the vertical
8synchronization pulses and short data packages ASK
9modulated<footnote><para>ASK: Amplitude-Shift Keying. A high signal
10level represents a '1' bit, a low level a '0' bit.</para></footnote>
11onto the video signal. These are transmissions of services such as
12Teletext or Closed Caption.</para>
13
14 <para>Subject of this interface type is raw VBI data, as sampled off
15a video signal, or to be added to a signal for output.
16The data format is similar to uncompressed video images, a number of
17lines 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
20device special files named <filename>/dev/vbi</filename> and
21<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> with
22major number 81 and minor numbers 224 to 255.
23<filename>/dev/vbi</filename> is typically a symbolic link to the
24preferred VBI device. This convention applies to both input and output
25devices.</para>
26
27 <para>To address the problems of finding related video and VBI
28devices VBI capturing and output is also available as device function
29under <filename>/dev/video</filename>. To capture or output raw VBI
30data with these devices applications must call the &VIDIOC-S-FMT;
31ioctl. Accessed as <filename>/dev/vbi</filename>, raw VBI capturing
32or 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
38the <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;
41returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
42read/write, streaming or asynchronous I/O methods must be
43supported. 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
50input or output</link>, <link linkend="tuner">tuner or
51modulator</link>, and <link linkend="control">controls</link> ioctls
52as needed. The <link linkend="standard">video standard</link> ioctls provide
53information vital to program a VBI device, therefore must be
54supported.</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
61sampling frequency. To properly interpret the data V4L2 specifies an
62ioctl to query the sampling parameters. Moreover, to allow for some
63flexibility applications can also suggest different parameters.</para>
64
65 <para>As usual these parameters are <emphasis>not</emphasis>
66reset at &func-open; time to permit Unix tool chains, programming a
67device and then reading from it as if it was a plain file. Well
68written V4L2 applications should always ensure they really get what
69they want, requesting reasonable parameters and then checking if the
70actual parameters are suitable.</para>
71
72 <para>To query the current raw VBI capture parameters
73applications 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
77the &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
82initialize all fields of the &v4l2-vbi-format;
83<structfield>vbi</structfield> member of the
84<structfield>fmt</structfield> union, or better just modify the
85results of <constant>VIDIOC_G_FMT</constant>, and call the
86&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers return
87an &EINVAL; only when the given parameters are ambiguous, otherwise
88they modify the parameters according to the hardware capabilites and
89return the actual parameters. When the driver allocates resources at
90this point, it may return an &EBUSY; to indicate the returned
91parameters are valid but the required resources are currently not
92available. That may happen for instance when the video and VBI areas
93to capture would overlap, or when the driver supports multiple opens
94and another process already requested VBI capturing or output. Anyway,
95applications must expect other resource allocation points which may
96return <errorcode>EBUSY</errorcode>, at the &VIDIOC-STREAMON; ioctl
97and 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
103returns 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.&nbsp;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,
120relative to the leading edge of the line synchronization pulse and
121counted 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
124edge. 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
135linkend="pixfmt" />, a four-character-code.<footnote>
136 <para>A few devices may be unable to
137sample VBI data at all but can extend the video capture window to the
138VBI region.</para>
139 </footnote> Usually this is
140<constant>V4L2_PIX_FMT_GREY</constant>, i.&nbsp;e. each sample
141consists of 8 bits with lower values oriented towards the black level.
142Do not assume any other correlation of values with the signal level.
143For 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
145signal. 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
151associated with the first line of the VBI image, of the first and the
152second field respectively. See <xref linkend="vbi-525" /> and
153<xref linkend="vbi-625" /> for valid values. VBI input drivers can
154return start values 0 if the hardware cannot reliable identify
155scanning lines, VBI acquisition may not require this
156information.</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
162field image, respectively.</entry>
163 </row>
164 <row>
165 <entry spanname="hspan"><para>Drivers should be as
166flexibility as possible. For example, it may be possible to extend or
167move the VBI capture window down to the picture area, implementing a
168'full field mode' to capture data service transmissions embedded in
169the picture.</para><para>An application can set the first or second
170<structfield>count</structfield> value to zero if no data is required
171from the respective field; <structfield>count</structfield>[1] if the
172scanning system is progressive, &ie; not interlaced. The
173corresponding start value shall be ignored by the application and
174driver. Anyway, drivers may not support single field capturing and
175return both count values non-zero.</para><para>Both
176<structfield>count</structfield> values set to zero, or line numbers
177outside the bounds depicted in <xref linkend="vbi-525" /> and <xref
178 linkend="vbi-625" />, or a field image covering
179lines of two fields, are invalid and shall not be returned by the
180driver.</para><para>To initialize the <structfield>start</structfield>
181and <structfield>count</structfield> fields, applications must first
182determine the current video standard selection. The &v4l2-std-id; or
183the <structfield>framelines</structfield> field of &v4l2-standard; can
184be 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
190only drivers set flags, applications must set this field to
191zero.</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.
197Drivers 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
212properly distinguish between fields. Normally the VBI image stores the
213first field (lower scanning line numbers) first in memory. This may be
214a top or bottom field depending on the video standard. When this flag
215is set the first or second field may be stored first, however the
216fields are still in correct temporal order with the older field first
217in memory.<footnote>
218 <para>Most VBI services transmit on both fields, but
219some have different semantics depending on the field number. These
220cannot 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
228sequentially; all lines of the first field followed by all lines of
229the 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
232field is first in memory depends on the video standard). When this
233flag is set, the two fields are interlaced (cf.
234<constant>V4L2_FIELD_INTERLACED</constant>). The first line of the
235first field followed by the first line of the second field, then the
236two second lines, and so on. Such a layout may be necessary when the
237hardware has been programmed to capture or output interlaced video
238images and is unable to separate the fields for VBI capturing at
239the 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
275starts in line 264 and not 263.5 because half line capturing is not
276supported.</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
295starts in line 314 and not 313.5 because half line capturing is not
296supported.</para>
297 </caption>
298 </mediaobject>
299 </figure>
300
301 <para>Remember the VBI image format depends on the selected
302video standard, therefore the application must choose a new standard or
303query the current standard first. Attempts to read or write data ahead
304of format negotiation, or after switching the video standard which may
305invalidate the negotiated VBI parameters, should be refused by the
306driver. 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
313implementation, the smallest unit of data passed at a time is one
314frame, consisting of two fields of VBI images immediately following in
315memory.</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,
324applications must check the <structfield>sample_format</structfield>
325field 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
331possibility of synchronizing video and
332VBI data by using buffer timestamps.</para>
333
334 <para>Remember the &VIDIOC-STREAMON; ioctl and the first read(),
335write() and select() call can be resource allocation points returning
336an &EBUSY; if the required hardware resources are temporarily
337unavailable, for example the device is already in use by another
338process.</para>
339 </section>
340
341 <!--
342Local Variables:
343mode: sgml
344sgml-parent-document: "v4l2.sgml"
345indent-tabs-mode: nil
346End:
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
4information in binary format, for example the station name or travel
5information, on an inaudible audio subcarrier of a radio program. This
6interface is aimed at devices capable of receiving and decoding RDS
7information.</para>
8
9 <para>For more information see the core RDS standard <xref linkend="en50067" />
10and the RBDS standard <xref linkend="nrsc4" />.</para>
11
12 <para>Note that the RBDS standard as is used in the USA is almost identical
13to the RDS standard. Any RDS decoder can also handle RBDS. Only some of the fields
14have 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).
17This is a proprietary format which seems to be discontinued. The RDS interface does not
18support this format. Should support for MMBS (or the so-called 'E blocks' in general)
19be 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
25set the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in
26the <structfield>capabilities</structfield> field of &v4l2-capability;
27returned by the &VIDIOC-QUERYCAP; ioctl.
28Any tuner that supports RDS will set the
29<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
30field of &v4l2-tuner;.
31Whether an RDS signal is present can be detected by looking at
32the <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
36set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in
37the <structfield>capabilities</structfield> field of &v4l2-capability;
38returned by the &VIDIOC-QUERYCAP; ioctl.
39Any modulator that supports RDS will set the
40<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
41field of &v4l2-modulator;.
42In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant>
43bit 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
51with the &func-read; function. The data is packed in groups of three bytes,
52as 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<!--
163Local Variables:
164mode: sgml
165sgml-parent-document: "v4l2.sgml"
166indent-tabs-mode: nil
167End:
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
4sequence of lines of an analog video signal. During VBI no picture
5information is transmitted, allowing some time while the electron beam
6of 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
9in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by
10software, see also the <link linkend="raw-vbi">raw VBI
11interface</link>. The data is passed as short packets of fixed size,
12covering one scan line each. The number of packets per video frame is
13variable.</para>
14
15 <para>Sliced VBI capture and output devices are accessed through the
16same character special files as raw VBI devices. When a driver
17supports both interfaces, the default function of a
18<filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI
19capturing or output, and the sliced VBI function is only available
20after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a
21<filename>/dev/video</filename> device may support the sliced VBI API,
22however the default function here is video capturing or output.
23Different file descriptors must be used to pass raw and sliced VBI
24data 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
30set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or
31<constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in
32the <structfield>capabilities</structfield> field of &v4l2-capability;
33returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
34read/write, streaming or asynchronous <link linkend="io">I/O
35methods</link> must be supported. Sliced VBI devices may have a tuner
36or modulator.</para>
37 </section>
38
39 <section>
40 <title>Supplemental Functions</title>
41
42 <para>Sliced VBI devices shall support <link linkend="video">video
43input or output</link> and <link linkend="tuner">tuner or
44modulator</link> ioctls if they have these capabilities, and they may
45support <link linkend="control">control</link> ioctls. The <link
46linkend="standard">video standard</link> ioctls provide information
47vital to program a sliced VBI device, therefore must be
48supported.</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
55hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl.
56All drivers implementing the sliced VBI interface must support this
57ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl
58when the number of VBI lines the hardware can capture or output per
59frame, or the number of services it can identify on a given line are
60limited. For example on PAL line 16 the hardware may be able to look
61for a VPS or Teletext signal, but not both at the same time.</para>
62
63 <para>To determine the currently selected services applications
64set the <structfield>type </structfield> field of &v4l2-format; to
65<constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant>
66V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT;
67ioctl fills the <structfield>fmt.sliced</structfield> member, a
68&v4l2-sliced-vbi-format;.</para>
69
70 <para>Applications can request different parameters by
71initializing or modifying the <structfield>fmt.sliced</structfield>
72member 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
76because the hardware must be told which VBI service to expect on each
77scan line. Not all services may be supported by the hardware on all
78lines (this is especially true for VBI output where Teletext is often
79unsupported and other services can only be inserted in one specific
80line). In many cases, however, it is sufficient to just set the
81<structfield>service_set</structfield> field to the required services
82and let the driver fill the <structfield>service_lines</structfield>
83array according to hardware capabilities. Only if more precise control
84is 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
88according to hardware capabilities. When the driver allocates
89resources at this point, it may return an &EBUSY; if the required
90resources are temporarily unavailable. Other resource allocation
91points 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
113driver according to the services specified in this field. For example,
114if <structfield>service_set</structfield> is initialized with
115<constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a
116driver for the cx25840 video decoder sets lines 7-22 of both
117fields<footnote><para>According to <link
118linkend="ets300706">ETS&nbsp;300&nbsp;706</link> lines 6-22 of the
119first field and lines 5-22 of the second field may carry Teletext
120data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant>
121and 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
124of <structfield>service_lines</structfield> will be used instead.
125</para><para>On return the driver sets this field to the union of all
126elements of the returned <structfield>service_lines</structfield>
127array. It may contain less services than requested, perhaps just one,
128if the hardware cannot handle more services simultaneously. It may be
129empty (zero) if none of the requested services are supported by the
130hardware.</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
136array with sets of data services the driver shall look for or insert
137on the respective scan line. Subject to hardware capabilities drivers
138return the requested set, a subset, which may be just a single
139service, or an empty set. When the hardware cannot handle multiple
140services on the same line the driver shall choose one. No assumptions
141can be made on which service the driver chooses.</para><para>Data
142services are defined in <xref linkend="vbi-services2" />. Array indices
143map to ITU-R line numbers (see also <xref linkend="vbi-525" /> and <xref
144 linkend="vbi-625" />) as follows: <!-- No nested
145tables, 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
194one &func-read; or &func-write; call, and the buffer size in bytes for
195the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to
196the size of &v4l2-sliced-vbi-data; times the number of non-zero
197elements in the returned <structfield>service_lines</structfield>
198array (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
204extensions. 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
237without 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
245ETS&nbsp;300&nbsp;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
253bit, 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>
261Byte 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
270line 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
276line systems.</entry>
277 </row>
278 </tbody>
279 </tgroup>
280 </table>
281
282 <para>Drivers may return an &EINVAL; when applications attempt to
283read or write data without prior format negotiation, after switching
284the video standard (which may invalidate the negotiated VBI
285parameters) and after switching the video input (which may change the
286video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return
287an &EBUSY; when applications attempt to change the format while i/o is
288in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call,
289and 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
296belonging to one video frame. That is an array of
297<structname>v4l2_sliced_vbi_data</structname> structures with one or
298more elements and a total size not exceeding
299<structfield>io_size</structfield> bytes. Likewise in streaming I/O
300mode one buffer of <structfield>io_size</structfield> bytes must
301contain data of one video frame. The <structfield>id</structfield> of
302unused <structname>v4l2_sliced_vbi_data</structname> elements must be
303zero.</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" />
315identifying the type of data in this packet. Only a single bit must be
316set. When the <structfield>id</structfield> of a captured packet is
317zero, the packet is empty and the contents of other fields are
318undefined. Applications shall ignore empty packets. When the
319<structfield>id</structfield> of a packet for output is zero the
320contents of the <structfield>data</structfield> field are undefined
321and 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
329from, or shall be inserted at. <constant>0</constant> for the first
330field, <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
336data has been captured from, or shall be inserted at. See <xref
337 linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid
338values. Sliced VBI capture devices can set the line number of all
339packets to <constant>0</constant> if the hardware cannot reliably
340identify 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.
346Applications 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
353bytes passed for each data type. The contents of padding bytes at the
354end of this array are undefined, drivers and applications shall ignore
355them.</entry>
356 </row>
357 </tbody>
358 </tgroup>
359 </table>
360
361 <para>Packets are always passed in ascending line number order,
362without duplicate line numbers. The &func-write; function and the
363&VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate
364this rule. They must also return an &EINVAL; when applications pass an
365incorrect 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
369unknown the driver must pass the packets in transmitted order. The
370driver can insert empty packets with <structfield>id</structfield> set
371to zero anywhere in the packet array.</para>
372
373 <para>To assure synchronization and to distinguish from frame
374dropping, when a captured frame does not carry any of the requested
375data services drivers must pass one or more empty packets. When an
376application fails to pass VBI data in time for output, the driver
377must output the last VPS and WSS packet again, and disable the output
378of Closed Caption and Teletext data, or output data which is ignored
379by Closed Caption and Teletext decoders.</para>
380
381 <para>A sliced VBI device may support <link
382linkend="rw">read/write</link> and/or streaming (<link
383linkend="mmap">memory mapping</link> and/or <link linkend="userp">user
384pointer</link>) I/O. The latter bears the possibility of synchronizing
385video 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
393capable of providing <link
394linkend="sliced-vbi-format-negotitation">negotiated sliced VBI
395services</link> as data embedded in the MPEG stream. Users or
396applications control this sliced VBI data insertion with the <link
397linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
398control.</para>
399
400 <para>If the driver does not provide the <link
401linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
402control, or only allows that control to be set to <link
403linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
404V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device
405cannot embed sliced VBI data in the MPEG stream.</para>
406
407 <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt">
408V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set
409the device driver to capture nor cease capturing sliced VBI data. The
410control only indicates to embed sliced VBI data in the MPEG stream, if
411an 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
414data in only certain types of MPEG streams: for example in an MPEG-2
415PS but not an MPEG-2 TS. In this situation, if sliced VBI data
416insertion is requested, the sliced VBI data will be embedded in MPEG
417stream types when supported, and silently omitted from MPEG stream
418types where sliced VBI data insertion is not supported by the device.
419</para>
420
421 <para>The following subsections specify the format of the
422embedded 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>
427V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI
428format shall be interpreted by drivers as a control to cease
429embedding sliced VBI data in MPEG streams. Neither the device nor
430driver shall insert "empty" embedded sliced VBI data packets in the
431MPEG stream when this format is set. No MPEG stream data structures
432are 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>
438V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI
439format, when supported, indicates to the driver to embed up to 36
440lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private
441Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis>
442Program Pack</emphasis> in the MPEG stream.</para>
443
444 <para><emphasis>Historical context</emphasis>: This format
445specification originates from a custom, embedded, sliced VBI data
446format used by the <filename>ivtv</filename> driver. This format
447has already been informally specified in the kernel sources in the
448file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>
449. The maximum size of the payload and other aspects of this format
450are driven by the CX23415 MPEG decoder's capabilities and limitations
451with respect to extracting, decoding, and displaying sliced VBI data
452embedded within an MPEG stream.</para>
453
454 <para>This format's use is <emphasis>not</emphasis> exclusive to
455the <filename>ivtv</filename> driver <emphasis>nor</emphasis>
456exclusive to CX2341x devices, as the sliced VBI data packet insertion
457into the MPEG stream is implemented in driver software. At least the
458<filename>cx18</filename> driver provides sliced VBI data insertion
459into an MPEG-2 PS in this format as well.</para>
460
461 <para>The following definitions specify the payload of the
462MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain
463sliced 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
466and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are
467not detailed here. Please refer to the MPEG-2 specifications for
468details 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
473length, depending on the actual number of lines of sliced VBI data
474present in a video frame. The payload may be padded at the end with
475unspecified fill bytes to align the end of the payload to a 4-byte
476boundary. The payload shall never exceed 1552 bytes (2 fields with
47718 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
492this is a valid sliced VBI data payload and also indicates which
493member 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
507that contains anywhere from 1 to 35 lines of sliced VBI data.
508Line masks are provided in this form of the payload indicating
509which 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
518used when 36 lines of sliced VBI data are present. No line masks are
519provided in this form of the payload; all valid line mask bits are
520implcitly 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>
544member 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>
551member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and
552that 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
568present. These <structfield>linemask</structfield> values are stored
569in little endian byte order in the MPEG stream. Some reference
570<structfield>linemask</structfield> bit positions with their
571corresponding VBI line number and video field are given below.
572b<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
588to 35 lines of sliced VBI data. The sliced VBI data lines present
589correspond to the bits set in the <structfield>linemask</structfield>
590array, starting from b<subscript>0</subscript> of <structfield>
591linemask</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
596found set in the <structfield>linemask</structfield> array,
597<structfield>line</structfield>[1] corresponds to the second bit
598found set in the <structfield>linemask</structfield> array, etc.
599If no <structfield>linemask</structfield> array bits are set, then
600<structfield>line</structfield>[0] may contain one line of
601unspecified 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
619data. <structfield>line</structfield>[0] through <structfield>line
620</structfield>[17] correspond to lines 6 through 23 of the
621first field. <structfield>line</structfield>[18] through
622<structfield>line</structfield>[35] corresponds to lines 6
623through 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
640the 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>
654v4l2_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">
671Sliced 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">
678Sliced 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">
685Sliced 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">
692Sliced 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<!--
703Local Variables:
704mode: sgml
705sgml-parent-document: "v4l2.sgml"
706indent-tabs-mode: nil
707End:
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
4Teletext data [<xref linkend="ets300706" />, <xref linkend="itu653" />], evaluating the
5Teletext packages and storing formatted pages in cache memory. Such
6devices are usually implemented as microcontrollers with serial
7interface (I<superscript>2</superscript>C) and can be found on older
8TV cards, dedicated Teletext decoding cards and home-brew devices
9connected to the PC parallel port.</para>
10
11 <para>The Teletext API was designed by Martin Buck. It is defined in
12the kernel header file <filename>linux/videotext.h</filename>, the
13specification is available from <ulink url="ftp://ftp.gwdg.de/pub/linux/misc/videotext/">
14ftp://ftp.gwdg.de/pub/linux/misc/videotext/</ulink>. (Videotext is the name of
15the German public television Teletext service.) Conventional character
16device file names are <filename>/dev/vtx</filename> and
17<filename>/dev/vttuner</filename>, with device number 83, 0 and 83, 16
18respectively. A similar interface exists for the Philips SAA5249
19Teletext 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
23with character device file names <filename>/dev/vtx0</filename> to
24<filename>/dev/vtx31</filename>, device major number 81, minor numbers
25192 to 223. For reference the V4L Teletext API specification is
26reproduced here in full: "Teletext interfaces talk the existing VTX
27API." Teletext devices with major number 83 and 102 will be removed in
28Linux 2.6.</para>
29
30 <para>There are no plans to replace the Teletext API or to integrate
31it into V4L2. Please write to the linux-media mailing list: &v4l-ml;
32when the need arises.</para>
33
34 <!--
35Local Variables:
36mode: sgml
37sgml-parent-document: "v4l2.sgml"
38indent-tabs-mode: nil
39End:
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"
9kernel module. When videodev initializes it registers as character device
10with major number 81, and it registers a set of file operations. All V4L2
11drivers are really clients of videodev, which calls V4L2 drivers through
12driver method functions. V4L2 drivers are also written as kernel modules.
13After probing the hardware they register one or more devices with
14videodev.</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
20called after the module was loaded into kernel, an exit function whis is
21called before the module is removed. When the driver is compiled into the
22kernel these functions called at system boot and shutdown time.</para>
23
24 <informalexample>
25 <programlisting>
26#include &lt;linux/module.h&gt;
27
28/* Export information about this module. For details and other useful
29 macros see <filename>linux/module.h</filename>. */
30MODULE_DESCRIPTION("my - driver for my hardware");
31MODULE_AUTHOR("Your name here");
32MODULE_LICENSE("GPL");
33
34static void
35my_module_exit (void)
36{
37 /* Free all resources allocated by my_module_init(). */
38}
39
40static int
41my_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. */
51module_init (my_module_init);
52module_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>
60include &lt;linux/moduleparam.h&gt;
61
62static int my_option = 123;
63static 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. */
67module_param (my_option, int, 0644);
68module_param_array (my_option_array, int, NULL, 0644);
69
70MODULE_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
75number of the device it will register. Purpose is to predictably link V4L2
76drivers to device nodes if more than one video device is installed. Use the
77name of the device node followed by a "_nr" suffix, for example "video_nr"
78for <filename>/dev/video</filename>.</para>
79
80 <informalexample>
81 <programlisting>
82/* Minor number of the device, -1 to allocate the first unused. */
83static int video_nr = -1;
84
85module_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>
97typedef struct {
98 /* State of one physical device. */
99} my_device;
100
101static int
102my_resume (struct pci_dev * pci_dev)
103{
104 /* Restore the suspended device to working state. */
105}
106
107static int
108my_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
119static void __devexit
120my_remove (struct pci_dev * pci_dev)
121{
122 my_device *my = pci_get_drvdata (pci_dev);
123
124 /* Describe me. */
125}
126
127static int __devinit
128my_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. */
144static struct pci_device_id
145my_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. */
152MODULE_DEVICE_TABLE (pci, my_pci_device_ids);
153
154static struct pci_driver
155my_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
167static void
168my_module_exit (void)
169{
170 pci_unregister_driver (&my_pci_driver);
171}
172
173static int
174my_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
190devices 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<!--
203Local Variables:
204mode: sgml
205sgml-parent-document: "v4l2.sgml"
206indent-tabs-mode: nil
207End:
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 &copy; 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 &lt;unistd.h&gt;</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
39resources associated with the file descriptor are freed. However data
40format parameters, current input or output, control values or other
41properties remain unchanged.</para>
42 </refsect1>
43
44 <refsect1>
45 <title>Return Value</title>
46
47 <para>The function returns <returnvalue>0</returnvalue> on
48success, <returnvalue>-1</returnvalue> on failure and the
49<varname>errno</varname> is set appropriately. Possible error
50codes:</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
57descriptor.</para>
58 </listitem>
59 </varlistentry>
60 </variablelist>
61 </refsect1>
62</refentry>
63
64<!--
65Local Variables:
66mode: sgml
67sgml-parent-document: "v4l2.sgml"
68indent-tabs-mode: nil
69End:
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 &lt;sys/ioctl.h&gt;</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
38linkend="videodev">videodev.h</link> header file, for example
39VIDIOC_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
55V4L2 devices. The argument <parameter>fd</parameter> must be an open
56file descriptor. An ioctl <parameter>request</parameter> has encoded
57in it whether the argument is an input, output or read/write
58parameter, and the size of the argument <parameter>argp</parameter> in
59bytes. Macros and defines specifying V4L2 ioctl requests are located
60in the <link linkend="videodev">videodev.h</link> header file.
61Applications should use their own copy, not include the version in the
62kernel sources on the system they compile on. All V4L2 ioctl requests,
63their 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
74output or read/write parameter it remains unmodified, and the
75<varname>errno</varname> variable is set appropriately. See below for
76possible error codes. Generic errors like <errorcode>EBADF</errorcode>
77or <errorcode>EFAULT</errorcode> are not listed in the sections
78discussing individual ioctl requests.</para>
79 <para>Note ioctls may return undefined error codes. Since errors
80may have side effects such as a driver reset applications should
81abort 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
88descriptor.</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
95this error code is returned when I/O is in progress or the driver
96supports 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
103memory 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
110character 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
117to by <parameter>argp</parameter> is not valid. This is a very common
118error 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
126complete 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<!--
141Local Variables:
142mode: sgml
143sgml-parent-document: "v4l2.sgml"
144indent-tabs-mode: nil
145End:
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 &lt;unistd.h&gt;
16#include &lt;sys/mman.h&gt;</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
36application's address space. When the <constant>MAP_FIXED</constant>
37flag is specified, <parameter>start</parameter> must be a multiple of the
38pagesize and mmap will fail when the specified address
39cannot be used. Use of this option is discouraged; applications should
40just 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
47same 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
55desired memory protection. Regardless of the device type and the
56direction of data exchange it should be set to
57<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>,
58permitting read and write access to image buffers. Drivers should
59support at least this combination of flags. Note the Linux
60<filename>video-buf</filename> kernel module, which is used by the
61bttv, saa7134, saa7146, cx88 and vivi driver supports only
62<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When
63the driver does not support the desired protection the
64<function>mmap()</function> function fails.</para>
65 <para>Note device memory accesses (&eg; the memory on a
66graphics card with video capturing hardware) may incur a performance
67penalty compared to main memory accesses, or reads may be
68significantly slower than writes or vice versa. Other I/O methods may
69be 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
76specifies the type of the mapped object, mapping options and whether
77modifications made to the mapped copy of the page are private to the
78process or are to be shared with other references.</para>
79 <para><constant>MAP_FIXED</constant> requests that the
80driver selects no other address than the one specified. If the
81specified 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
84of 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
88mapped memory with other (&eg; child-) processes. Note the Linux
89<filename>video-buf</filename> module which is used by the bttv,
90saa7134, saa7146, cx88 and vivi driver supports only
91<constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant>
92requests 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>
95flag.</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
108same 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,
122preferably at address <parameter>start</parameter>. This latter
123address 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
136the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is
137returned, and the <varname>errno</varname> variable is set
138appropriately. 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
145descriptor.</para>
146 </listitem>
147 </varlistentry>
148 <varlistentry>
149 <term><errorcode>EACCES</errorcode></term>
150 <listitem>
151 <para><parameter>fd</parameter> is
152not 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
160suitable. (E.&nbsp;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
172complete the request.</para>
173 </listitem>
174 </varlistentry>
175 </variablelist>
176 </refsect1>
177</refentry>
178
179<!--
180Local Variables:
181mode: sgml
182sgml-parent-document: "v4l2.sgml"
183indent-tabs-mode: nil
184End:
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 &lt;unistd.h&gt;
16#include &lt;sys/mman.h&gt;</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
38value as given to <function>mmap()</function> and returned by the
39driver in the &v4l2-buffer; <structfield>length</structfield>
40field.</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
50buffer and frees it, if possible. <!-- ? This function (not freeing)
51has no impact on I/O in progress, specifically it does not imply
52&VIDIOC-STREAMOFF; to terminate I/O. Unmapped buffers can still be
53enqueued, dequeued or queried, they are just not accessible by the
54application.--></para>
55 </refsect1>
56
57 <refsect1>
58 <title>Return Value</title>
59
60 <para>On success <function>munmap()</function> returns 0, on
61failure -1 and the <varname>errno</varname> variable is set
62appropriately:</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
70mapped yet.</para>
71 </listitem>
72 </varlistentry>
73 </variablelist>
74 </refsect1>
75</refentry>
76
77<!--
78Local Variables:
79mode: sgml
80sgml-parent-document: "v4l2.sgml"
81indent-tabs-mode: nil
82End:
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 &lt;fcntl.h&gt;</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
38still support only reading and output devices only writing.</para>
39 <para>When the <constant>O_NONBLOCK</constant> flag is
40given, the read() function and the &VIDIOC-DQBUF; ioctl will return
41the &EAGAIN; when no data is available or no buffer is in the driver
42outgoing queue, otherwise these functions block until data becomes
43available. All V4L2 drivers exchanging data with applications must
44support 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
55function has no side effects; all data format parameters, current
56input or output, control values or other properties remain unchanged.
57At the first <function>open()</function> call after loading the driver
58they will be reset to default values, drivers are never in an
59undefined state.</para>
60 </refsect1>
61 <refsect1>
62 <title>Return Value</title>
63
64 <para>On success <function>open</function> returns the new file
65descriptor. On error -1 is returned, and the <varname>errno</varname>
66variable 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
73device.</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
80device 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
87exists.</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
94request.</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
101files 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
108system has been reached.</para>
109 </listitem>
110 </varlistentry>
111 </variablelist>
112 </refsect1>
113</refentry>
114
115<!--
116Local Variables:
117mode: sgml
118sgml-parent-document: "v4l2.sgml"
119indent-tabs-mode: nil
120End:
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 &lt;sys/poll.h&gt;</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
28can suspend execution until the driver has captured data or is ready
29to accept data for output.</para>
30
31 <para>When streaming I/O has been negotiated this function waits
32until a buffer has been filled or displayed and can be dequeued with
33the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
34queue of the driver the function returns immediately.</para>
35
36 <para>On success <function>poll()</function> returns the number of
37file descriptors that have been selected (that is, file descriptors
38for which the <structfield>revents</structfield> field of the
39respective <structname>pollfd</structname> structure is non-zero).
40Capture 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>
44flags. When the function timed out it returns a value of zero, on
45failure it returns <returnvalue>-1</returnvalue> and the
46<varname>errno</varname> variable is set appropriately. When the
47application 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
53been negotiated and the driver does not capture yet, the
54<function>poll</function> function starts capturing. When that fails
55it returns a <constant>POLLERR</constant> as above. Otherwise it waits
56until data has been captured and can be read. When the driver captures
57continuously (as opposed to, for example, still images) the function
58may return immediately.</para>
59
60 <para>When use of the <function>write()</function> function has
61been negotiated the <function>poll</function> function just waits
62until 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
67support 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
77structures which have non-zero <structfield>revents</structfield>
78fields, 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
87specify 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
94streams 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
101memory 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
114than <constant>OPEN_MAX</constant>.</para>
115 </listitem>
116 </varlistentry>
117 </variablelist>
118 </refsect1>
119</refentry>
120
121<!--
122Local Variables:
123mode: sgml
124sgml-parent-document: "v4l2.sgml"
125indent-tabs-mode: nil
126End:
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 &lt;unistd.h&gt;</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
56discussed 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
60of the <parameter>count</parameter> value each
61<function>read()</function> call will provide at most one frame (two
62fields) worth of data.</para>
63
64 <para>By default <function>read()</function> blocks until data
65becomes available. When the <constant>O_NONBLOCK</constant> flag was
66given to the &func-open; function it
67returns immediately with an &EAGAIN; when no data is available. The
68&func-select; or &func-poll; functions
69can always be used to suspend execution until data becomes available. All
70drivers supporting the <function>read()</function> function must also
71support <function>select()</function> and
72<function>poll()</function>.</para>
73
74 <para>Drivers can implement read functionality in different
75ways, using a single or multiple buffers and discarding the oldest or
76newest frames once the internal buffers are filled.</para>
77
78 <para><function>read()</function> never returns a "snapshot" of a
79buffer being filled. Using a single buffer the driver will stop
80capturing when the application starts reading the buffer until the
81read is finished. Thus only the period of the vertical blanking
82interval is available for reading, or the capture rate must fall below
83the nominal frame rate of the video standard.</para>
84
85<para>The behavior of
86<function>read()</function> when called during the active picture
87period or the vertical blanking separating the top and bottom field
88depends on the discarding policy. A driver discarding the oldest
89frames keeps capturing into an internal buffer, continuously
90overwriting the previously, not read frame, and returns the frame
91being received at the time of the <function>read()</function> call as
92soon as it is complete.</para>
93
94 <para>A driver discarding the newest frames stops capturing until
95the next <function>read()</function> call. The frame being received at
96<function>read()</function> time is discarded, returning the following
97frame instead. Again this implies a reduction of the capture rate to
98one half or less of the nominal frame rate. An example of this model
99is the video read mode of the bttv driver, initiating a DMA to user
100memory when <function>read()</function> is called and returning when
101the DMA finished.</para>
102
103 <para>In the multiple buffer model drivers maintain a ring of
104internal buffers, automatically advancing to the next free buffer.
105This allows continuous capturing when the application can empty the
106buffers fast enough. Again, the behavior when the driver runs out of
107free buffers depends on the discarding policy.</para>
108
109 <para>Applications can get and set the number of buffers used
110internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM;
111ioctls. They are optional, however. The discarding policy is not
112reported 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
120an error if this number is smaller than the number of bytes requested,
121or the amount of data required for one frame. This may happen for
122example because <function>read()</function> was interrupted by a
123signal. On error, -1 is returned, and the <varname>errno</varname>
124variable is set appropriately. In this case the next read will start
125at 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
132O_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
139descriptor or is not open for reading, or the process already has the
140maximum 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
147device 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
154memory 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
161data 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
168failure 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
175supported by this driver, not on this device, or generally not on this
176type of device.</para>
177 </listitem>
178 </varlistentry>
179 </variablelist>
180 </refsect1>
181</refentry>
182
183<!--
184Local Variables:
185mode: sgml
186sgml-parent-document: "v4l2.sgml"
187indent-tabs-mode: nil
188End:
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 &lt;sys/time.h&gt;
16#include &lt;sys/types.h&gt;
17#include &lt;unistd.h&gt;</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
33can suspend execution until the driver has captured data or is ready
34to accept data for output.</para>
35
36 <para>When streaming I/O has been negotiated this function waits
37until a buffer has been filled or displayed and can be dequeued with
38the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
39queue of the driver the function returns immediately.</para>
40
41 <para>On success <function>select()</function> returns the total
42number of bits set in the <structname>fd_set</structname>s. When the
43function timed out it returns a value of zero. On failure it returns
44<returnvalue>-1</returnvalue> and the <varname>errno</varname>
45variable 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
48the file descriptor in <parameter>readfds</parameter> or
49<parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls
50will 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
57been negotiated and the driver does not capture yet, the
58<function>select()</function> function starts capturing. When that
59fails, <function>select()</function> returns successful and a
60subsequent <function>read()</function> call, which also attempts to
61start capturing, will return an appropriate error code. When the
62driver captures continuously (as opposed to, for example, still
63images) 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
67been negotiated the <function>select()</function> function just waits
68until 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
73support the <function>select()</function> function.</para>
74
75 <para>For more details see the <function>select()</function>
76manual page.</para>
77
78 </refsect1>
79
80 <refsect1>
81 <title>Return Value</title>
82
83 <para>On success, <function>select()</function> returns the number
84of descriptors contained in the three returned descriptor sets, which
85will 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
89are:</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
96file 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
103streams 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
112area.</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
125zero or greater than <constant>FD_SETSIZE</constant>.</para>
126 </listitem>
127 </varlistentry>
128 </variablelist>
129 </refsect1>
130</refentry>
131
132<!--
133Local Variables:
134mode: sgml
135sgml-parent-document: "v4l2.sgml"
136indent-tabs-mode: nil
137End:
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 &lt;unistd.h&gt;</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
54file descriptor <parameter>fd</parameter> from the buffer starting at
55<parameter>buf</parameter>. When the hardware outputs are not active
56yet, this function enables them. When <parameter>count</parameter> is
57zero, <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
61previous video frame, raw VBI image, sliced VPS or WSS data is
62displayed again. Sliced Teletext or Closed Caption data is not
63repeated, 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
70indicates nothing was written. On error, <returnvalue>-1</returnvalue>
71is returned, and the <varname>errno</varname> variable is set
72appropriately. In this case the next write will start at the beginning
73of 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
80linkend="func-open"><constant>O_NONBLOCK</constant></link> flag and no
81buffer 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
88descriptor 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
95device 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
102memory 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
109data 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
122supported by this driver, not on this device, or generally not on this
123type of device.</para>
124 </listitem>
125 </varlistentry>
126 </variablelist>
127 </refsect1>
128</refentry>
129
130<!--
131Local Variables:
132mode: sgml
133sgml-parent-document: "v4l2.sgml"
134indent-tabs-mode: nil
135End:
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
4write to a device. All drivers exchanging data with applications must
5support at least one of them.</para>
6
7 <para>The classic I/O method using the <function>read()</function>
8and <function>write()</function> function is automatically selected
9after opening a V4L2 device. When the driver does not support this
10method 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
13method with memory mapped or user buffers applications call the
14&VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined
15yet.</para>
16
17 <para>Video overlay can be considered another I/O method, although
18the application does not directly receive the image data. It is
19selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl.
20For more information see <xref linkend="overlay" />.</para>
21
22 <para>Generally exactly one I/O method, including overlay, is
23associated with each file descriptor. The only exceptions are
24applications not exchanging data with a driver ("panel applications",
25see <xref linkend="open" />) and drivers permitting simultaneous video capturing
26and overlay using the same file descriptor, for compatibility with V4L
27and 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,
31but for simplicity drivers need not support switching the I/O method
32(after first switching away from read/write) other than by closing
33and reopening the device.</para>
34
35 <para>The following sections describe the various I/O methods in
36more 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,
43respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in
44the <structfield>capabilities</structfield> field of &v4l2-capability;
45returned by the &VIDIOC-QUERYCAP; ioctl is set.</para>
46
47 <para>Drivers may need the CPU to copy the data, but they may also
48support DMA to or from user memory, so this I/O method is not
49necessarily less efficient than other methods merely exchanging buffer
50pointers. It is considered inferior though because no meta-information
51like frame counters or timestamps are passed. This information is
52necessary to recognize frame dropping and to synchronize with other
53data streams. However this is also the simplest I/O method, requiring
54little or no setup to exchange data. It permits command line stunts
55like this (the <application>vidctrl</application> tool is
56fictitious):</para>
57
58 <informalexample>
59 <screen>
60&gt; vidctrl /dev/video --input=0 --format=YUYV --size=352x288
61&gt; 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.
67Drivers must implement one I/O method if they
68exchange data with applications, but it need not be this.<footnote>
69 <para>It would be desirable if applications could depend on
70drivers supporting all I/O interfaces, but as much as the complex
71memory mapping I/O can be inadequate for some devices we have no
72reason to require this interface, which is most useful for simple
73applications capturing still images.</para>
74 </footnote> When reading or writing is supported, the driver
75must also support the &func-select; and &func-poll;
76function.<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;
89returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two
90streaming methods, to determine if the memory mapping flavor is
91supported applications must call the &VIDIOC-REQBUFS; ioctl.</para>
92
93 <para>Streaming is an I/O method where only pointers to buffers
94are exchanged between application and driver, the data itself is not
95copied. Memory mapping is primarily intended to map buffers in device
96memory into the application's address space. Device memory can be for
97example the video memory on a graphics card with a video capture
98add-on. However, being the most efficient I/O method available for a
99long time, many other drivers support streaming as well, allocating
100buffers in DMA-able main memory.</para>
101
102 <para>A driver can support many sets of buffers. Each set is
103identified by a unique buffer type value. The sets are independent and
104each set can hold a different type of data. To access different sets
105at the same time different file descriptors must be used.<footnote>
106 <para>One could use one file descriptor and set the buffer
107type field accordingly when calling &VIDIOC-QBUF; etc., but it makes
108the <function>select()</function> function ambiguous. We also like the
109clean approach of one file descriptor per logical stream. Video
110overlay for example is also a logical stream, although the CPU is not
111needed 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
116type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.
117This ioctl can also be used to change the number of buffers or to free
118the allocated memory, provided none of the buffers are still
119mapped.</para>
120
121 <para>Before applications can access the buffers they must map
122them into their address space with the &func-mmap; function. The
123location 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
126passed as sixth and second parameter to the
127<function>mmap()</function> function. The offset and length values
128must not be modified. Remember the buffers are allocated in physical
129memory, as opposed to virtual memory which can be swapped out to disk.
130Applications 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;
138struct {
139 void *start;
140 size_t length;
141} *buffers;
142unsigned int i;
143
144memset (&amp;reqbuf, 0, sizeof (reqbuf));
145reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
146reqbuf.memory = V4L2_MEMORY_MMAP;
147reqbuf.count = 20;
148
149if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &amp;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
160if (reqbuf.count &lt; 5) {
161 /* You may need to free the buffers here. */
162 printf ("Not enough buffer memory\n");
163 exit (EXIT_FAILURE);
164}
165
166buffers = calloc (reqbuf.count, sizeof (*buffers));
167assert (buffers != NULL);
168
169for (i = 0; i &lt; reqbuf.count; i++) {
170 &v4l2-buffer; buffer;
171
172 memset (&amp;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;, &amp;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
199for (i = 0; i &lt; 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
205and an outgoing queue. They separate the synchronous capture or output
206operation locked to a video clock from the application which is
207subject to random disk or network delays and preemption by
208other processes, thereby reducing the probability of data loss.
209The queues are organized as FIFOs, buffers will be
210output in the order enqueued in the incoming FIFO, and were
211captured in the order dequeued from the outgoing FIFO.</para>
212
213 <para>The driver may require a minimum number of buffers enqueued
214at all times to function, apart of this no limit exists on the number
215of buffers applications can enqueue in advance, or dequeue and
216process. They can also enqueue in a different order than buffers have
217been 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
220images out of order (such as video codecs) to return buffers earlier,
221reducing the probability of data loss. Random fill order allows
222drivers to reuse buffers on a LIFO-basis, taking advantage of caches
223holding 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
226identifies the buffer.</para>
227
228 <para>Initially all mapped buffers are in dequeued state,
229inaccessible by the driver. For capturing applications it is customary
230to first enqueue all mapped buffers, then to start capturing and enter
231the read loop. Here the application waits until a filled buffer can be
232dequeued, and re-enqueues the buffer when the data is no longer
233needed. Output applications fill and enqueue buffers, when enough
234buffers are stacked up the output is started with
235<constant>VIDIOC_STREAMON</constant>. In the write loop, when
236the application runs out of free buffers, it must wait until an empty
237buffer 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
241mapped, enqueued, full or empty can be determined at any time using the
242&VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the
243application until one or more buffers can be dequeued. By default
244<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
245outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
246given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
247returns 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
253queues as a side effect. Since there is no notion of doing anything
254"now" on a multitasking system, if an application needs to synchronize
255with another event it should examine the &v4l2-buffer;
256<structfield>timestamp</structfield> of captured buffers, or set the
257field before enqueuing buffers for output.</para>
258
259 <para>Drivers implementing memory mapping I/O must
260support 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>
267function.<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
271rest 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;
284returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user
285pointer method (not only memory mapping) is supported must be
286determined by calling the &VIDIOC-REQBUFS; ioctl.</para>
287
288 <para>This I/O method combines advantages of the read/write and
289memory mapping methods. Buffers are allocated by the application
290itself, and can reside for example in virtual or shared memory. Only
291pointers to data are exchanged, these pointers and meta-information
292are passed in &v4l2-buffer;. The driver must be switched
293into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the
294desired buffer type. No buffers are allocated beforehands,
295consequently they are not indexed and cannot be queried like mapped
296buffers 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
304memset (&amp;reqbuf, 0, sizeof (reqbuf));
305reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
306reqbuf.memory = V4L2_MEMORY_USERPTR;
307
308if (ioctl (fd, &VIDIOC-REQBUFS;, &amp;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,
321applications can pass different addresses and sizes at each
322<constant>VIDIOC_QBUF</constant> call. If required by the hardware the
323driver swaps memory pages within physical memory to create a
324continuous area of memory. This happens transparently to the
325application in the virtual memory subsystem of the kernel. When buffer
326pages have been swapped out to disk they are brought back and finally
327locked in physical memory for DMA.<footnote>
328 <para>We expect that frequently used buffers are typically not
329swapped out. Anyway, the process of swapping, locking or generating
330scatter-gather lists may be time consuming. The delay can be masked by
331the depth of the incoming buffer queue, and perhaps by maintaining
332caches assuming a buffer will be soon enqueued again. On the other
333hand, to optimize memory usage drivers can limit the number of buffers
334locked in advance and recycle the most recently used buffers first. Of
335course, the pages of empty buffers in the incoming queue need not be
336saved to disk. Output buffers must be saved on the incoming and
337outgoing queue because an application may share them with other
338processes.</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
343time between the completion of the DMA and this ioctl. The memory is
344also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
345when the device is closed. Applications must take care not to free
346buffers without dequeuing. For once, the buffers remain locked until
347further, wasting physical memory. Second the driver will not be
348notified when the memory is returned to the application's free list
349and subsequently reused for other purposes, possibly completing the
350requested DMA and overwriting valuable data.</para>
351
352 <para>For capturing applications it is customary to enqueue a
353number of empty buffers, to start capturing and enter the read loop.
354Here the application waits until a filled buffer can be dequeued, and
355re-enqueues the buffer when the data is no longer needed. Output
356applications fill and enqueue buffers, when enough buffers are stacked
357up output is started. In the write loop, when the application
358runs out of free buffers it must wait until an empty buffer can be
359dequeued and reused. Two methods exist to suspend execution of the
360application until one or more buffers can be dequeued. By default
361<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
362outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
363given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
364returns 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
370queues and unlocks all buffers as a side effect. Since there is no
371notion of doing anything "now" on a multitasking system, if an
372application needs to synchronize with another event it should examine
373the &v4l2-buffer; <structfield>timestamp</structfield> of captured
374buffers, or set the field before enqueuing buffers for output.</para>
375
376 <para>Drivers implementing user pointer I/O must
377support 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
385rest 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
399driver using one of the Streaming I/O methods. Only pointers to
400buffers are exchanged, the data itself is not copied. These pointers,
401together with meta-information like timestamps or field parity, are
402stored in a struct <structname>v4l2_buffer</structname>, argument to
403the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.</para>
404
405 <para>Nominally timestamps refer to the first data byte transmitted.
406In practice however the wide range of hardware covered by the V4L2 API
407limits timestamp accuracy. Often an interrupt routine will
408sample the system clock shortly after the field or frame was stored
409completely in memory. So applications must expect a constant
410difference up to one field or frame period plus a small (few scan
411lines) random error. The delay and error can be much
412larger due to compression or transmission over an external bus when
413the frames are not properly stamped by the sender. This is frequently
414the case with USB cameras. Here timestamps refer to the instant the
415field or frame was received by the driver, not the capture time. These
416devices identify by not enumerating any video standards, see <xref
417linkend="standard" />.</para>
418
419 <para>Similar limitations apply to output timestamps. Typically
420the video hardware locks to a clock controlling the video timing, the
421horizontal and vertical synchronization pulses. At some point in the
422line sequence, possibly the vertical blanking, an interrupt routine
423samples the system clock, compares against the timestamp and programs
424the hardware to repeat the previous field or frame, or to display the
425buffer contents.</para>
426
427 <para>Apart of limitations of the video device and natural
428inaccuracies of all clocks, it should be noted system time itself is
429not perfectly stable. It can be affected by power saving cycles,
430warped to insert leap seconds, or even turned back or forth by the
431system administrator affecting long term measurements. <footnote>
432 <para>Since no other Linux multimedia
433API supports unadjusted time it would be foolish to introduce here. We
434must use a universally supported clock to synchronize different media,
435hence 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
448field is only used for <link linkend="mmap">memory mapping</link> I/O
449and can range from zero to the number of buffers allocated
450with 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
465buffer. It depends on the negotiated data format and may change with
466each buffer for compressed variable size data like JPEG images.
467Drivers must set this field when <structfield>type</structfield>
468refers 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
475linkend="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
482buffer, see <xref linkend="v4l2-field" />. This field is not used when
483the buffer contains VBI data. Drivers must set it when
484<structfield>type</structfield> refers to an input stream,
485applications 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
492system time (as returned by the <function>gettimeofday()</function>
493function) when the first data byte was captured. For output streams
494the data will not be displayed before this time, secondary to the
495nominal frame rate determined by the current video standard in
496enqueued order. Applications can for example zero this field to
497display frames as soon as possible. The driver stores the time at
498which the first data byte was actually sent out in the
499<structfield>timestamp</structfield> field. This permits
500applications to monitor the drift between the video and system
501clock.</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
511timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
512mode the top and bottom field contain the same timecode.
513Timecodes are intended to help video editing and are typically recorded on
514video tapes, but also embedded in compressed formats like MPEG. This
515field 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
523sequence.</entry>
524 </row>
525 <row>
526 <entry spanname="hspan"><para>In <link
527linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and
528bottom field have the same sequence number. The count starts at zero
529and includes dropped or repeated frames. A dropped frame was received
530by an input device but could not be stored due to lack of free buffer
531space. A repeated frame was displayed again by an output device
532because the application did not pass new data in
533time.</para><para>Note this may count the frames received
534e.g. over USB, without taking into account the frames dropped by the
535remote hardware due to limited compression throughput or bus
536bandwidth. These devices identify by not enumerating any video
537standards, 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
544in 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
556from the start of the device memory. The value is returned by the
557driver and apart of serving as parameter to the &func-mmap; function
558not 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
566buffer (casted to unsigned long type) in virtual memory, set by the
567application. 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
580synchronous video input changes, a function useful for example in
581video surveillance applications. For this purpose applications set the
582<constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the
583number 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
649linkend="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
670into the application's address space, see <xref linkend="mmap" /> for details.
671Drivers 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
680incoming and outgoing queue. When this flag is set, the buffer is
681currently on the incoming queue. It automatically moves to the
682outgoing queue after the buffer has been filled (capture devices) or
683displayed (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
686always set and after <constant>VIDIOC_DQBUF</constant> always
687cleared.</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
693the outgoing queue, ready to be dequeued from the driver. Drivers set
694or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
695is called. After calling the <constant>VIDIOC_QBUF</constant> or
696<constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
697buffer 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.
700They can be both cleared however, then the buffer is in "dequeued"
701state, 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
708capture devices when the buffer contains a compressed image which is a
709key 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>
715this flags predicted frames or fields which contain only differences to a
716previous 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.
728Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
729ioctl 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.
735Applications 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
751mapping</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
757pointer</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
772designed 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.&nbsp;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
865in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
866each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
867count.</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
899video. Progressive video transmits all lines of a video image
900sequentially. Interlaced video divides an image into two fields,
901containing only the odd and even lines of the image, respectively.
902Alternating the so called odd and even field are transmitted, and due
903to a small delay between fields a cathode ray TV displays the lines
904interleaved, yielding the original frame. This curious technique was
905invented because at refresh rates similar to film the image would
906fade out too quickly. Transmitting fields reduces the flicker without
907the necessity of doubling the frame rate and with it the bandwidth
908required for each channel.</para>
909
910 <para>It is important to understand a video camera does not expose
911one frame at a time, merely transmitting the frames separated into
912fields. The fields are in fact captured at two different instances in
913time. An object on screen may well move between one field and the
914next. For applications analysing motion it is of paramount importance
915to recognize which field of a frame is older, the <emphasis>temporal
916order</emphasis>.</para>
917
918 <para>When the driver provides or accepts images field by field
919rather than interleaved, it is also important applications understand
920how the fields combine to frames. We distinguish between top and
921bottom fields, the <emphasis>spatial order</emphasis>: The first line
922of the top field is the first line of an interlaced frame, the first
923line of the bottom field is the second line of that frame.</para>
924
925 <para>However because fields were captured one after the other,
926arguing whether a frame commences with the top or bottom field is
927pointless. Any two successive top and bottom, or bottom and top fields
928yield a valid frame. Only when the source was progressive to begin
929with, &eg; when transferring film to video, two fields may come from
930the same frame, creating a natural order.</para>
931
932 <para>Counter to intuition the top field is not necessarily the
933older field. Whether the older field contains the top or bottom lines
934is a convention determined by the video standard. Hence the
935distinction between temporal and spatial order of fields. The diagrams
936below should make this clearer.</para>
937
938 <para>All video capture and output devices must report the current
939field order. Some drivers may permit the selection of a different
940order, to this end applications initialize the
941<structfield>field</structfield> field of &v4l2-pix-format; before
942calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
943have 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
954one 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.
958Drivers choose depending on hardware capabilities or e.&nbsp;g. the
959requested 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.
967The driver may also indicate this order when it cannot distinguish
968between <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.
980Applications may wish to prevent a device from capturing interlaced
981images because they will have "comb" or "feathering" artefacts around
982moving 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
988line. The temporal order of the fields (whether the top or bottom
989field is first transmitted) depends on the current video standard.
990M/NTSC transmits the bottom field first, all other standards the top
991field 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
997are stored first in memory, immediately followed by the bottom field
998lines. Fields are always stored in temporal order, the older one first
999in 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
1005lines are stored first in memory, immediately followed by the top
1006field lines. Fields are always stored in temporal order, the older one
1007first 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
1013buffers, in temporal order, &ie; the older one first. To indicate the field
1014parity (whether the current field is a top or bottom field) the driver
1015or 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
1019to build a frame. If fields are successive, without any dropped fields
1020between them (fields can drop individually), can be determined from
1021the &v4l2-buffer; <structfield>sequence</structfield> field. Image
1022sizes refer to the frame, not fields. This format cannot be selected
1023when using the read/write I/O method.<!-- Where it's indistinguishable
1024from 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
1030line, 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
1036line, 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 <!--
1068Local Variables:
1069mode: sgml
1070sgml-parent-document: "v4l2.sgml"
1071indent-tabs-mode: nil
1072End:
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 &lt;mchehab@infradead.org&gt;
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 &lt;ctype.h&gt;
17#include &lt;errno.h&gt;
18#include &lt;fcntl.h&gt;
19#include &lt;stdio.h&gt;
20#include &lt;stdlib.h&gt;
21#include &lt;string.h&gt;
22#include &lt;linux/input.h&gt;
23#include &lt;sys/ioctl.h&gt;
24
25#include "parse.h"
26
27void prtcode (int *codes)
28{
29 struct parse_key *p;
30
31 for (p=keynames;p-&gt;name!=NULL;p++) {
32 if (p-&gt;value == (unsigned)codes[1]) {
33 printf("scancode 0x%04x = %s (0x%02x)\n", codes[0], p-&gt;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
44int parse_code(char *string)
45{
46 struct parse_key *p;
47
48 for (p=keynames;p-&gt;name!=NULL;p++) {
49 if (!strcasecmp(p-&gt;name, string)) {
50 return p-&gt;value;
51 }
52 }
53 return -1;
54}
55
56int main (int argc, char *argv[])
57{
58 int fd;
59 unsigned int i, j;
60 int codes[2];
61
62 if (argc&lt;2 || argc&gt;4) {
63 printf ("usage: %s &lt;device&gt; to get table; or\n"
64 " %s &lt;device&gt; &lt;scancode&gt; &lt;keycode&gt;\n"
65 " %s &lt;device&gt; &lt;keycode_file&gt;\n",*argv,*argv,*argv);
66 return -1;
67 }
68
69 if ((fd = open(argv[1], O_RDONLY)) &lt; 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 &lt; 256; j++) {
109 for (i = 0; i &lt; 256; i++) {
110 codes[0] = (j &lt;&lt; 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 &lt; 256; j++) {
163 for (i = 0; i &lt; 256; i++) {
164 codes[0] = (j &lt;&lt; 8) | i;
165 if (!ioctl(fd, EVIOCGKEYCODE, codes) &amp;&amp; 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
6layer on top of video4linux2 devices. The purpose of this (thin) layer
7is to make it easy for application writers to support a wide variety of
8devices without having to write separate code for different devices in the
9same 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
19different pixelformats found in V4L2 drivers into a few common RGB and
20YUY 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>,
47and <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
50various video processing functions to improve webcam video quality.
51The video processing is split in to 2 parts: libv4lconvert/control and
52libv4lconvert/processing.</para>
53
54 <para>The control part is used to offer video controls which can
55be 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
60processing functionality.</para>
61 </section>
62 <section>
63 <title>libv4l1</title>
64 <para>This library offers functions that can be used to quickly
65make v4l1 applications work with v4l2 devices. These functions work exactly
66like the normal open/close/etc, except that libv4l1 does full emulation of
67the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it
68will just pass calls through.</para>
69 <para>Since those functions are emulations of the old V4L1 API,
70it 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
75applications.</para>
76 <para>It provides handles to call V4L2 open/ioctl/close/poll
77methods. Instead of just providing the raw output of the device, it enhances
78the calls in the sense that it will use libv4lconvert to provide more video
79formats and to enhance the image quality.</para>
80 <para>In most cases, libv4l2 just passes the calls directly
81through 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>
86and <link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link>
87in 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>,
91and <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>,
92if they aren't available in the driver.
93<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link>
94keeps enumerating the hardware supported formats, plus the emulated formats
95offered 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
100libv4l.</para>
101 <para>Those functions operate just like glibc
102open/close/dup/ioctl/read/mmap/munmap:</para>
103<itemizedlist><listitem>
104 <para>int v4l2_open(const char *file, int oflag,
105...) -
106operates like the standard <link linkend='func-open'>open()</link> function.
107</para></listitem><listitem>
108 <para>int v4l2_close(int fd) -
109operates like the standard <link linkend='func-close'>close()</link> function.
110</para></listitem><listitem>
111 <para>int v4l2_dup(int fd) -
112operates like the standard dup() function, duplicating a file handler.
113</para></listitem><listitem>
114 <para>int v4l2_ioctl (int fd, unsigned long int request, ...) -
115operates 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) -
118operates 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); -
121operates like the standard <link linkend='func-mmap'>mmap()</link> function.
122</para></listitem><listitem>
123 <para>int v4l2_munmap(void *_start, size_t length); -
124operates 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) -
130opens an already opened fd for further use through v4l2lib and possibly
131modify libv4l2's default behavior through the v4l2_flags argument.
132Currently, v4l2_flags can be <constant>V4L2_DISABLE_CONVERSION</constant>,
133to disable format conversion.
134</para></listitem><listitem>
135 <para>int v4l2_set_control(int fd, int cid, int value) -
136This function takes a value of 0 - 65535, and then scales that range to
137the actual range of the given v4l control id, and then if the cid exists
138and is not locked sets the cid to the scaled value.
139</para></listitem><listitem>
140 <para>int v4l2_get_control(int fd, int cid) -
141This function returns a value of 0 - 65535, scaled to from the actual range
142of the given v4l control id. when the cid does not exist, could not be
143accessed 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
153open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l
154counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also
155emulates V4L1 calls via V4L2 API.</para>
156 <para>It allows usage of binary legacy applications that
157still don't use libv4l.</para>
158 </section>
159
160</section>
161<!--
162Local Variables:
163mode: sgml
164sgml-parent-document: "v4l2.sgml"
165indent-tabs-mode: nil
166End:
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
14Y'CbCr format which simply contains no Cb or Cr data.</para>
15
16 <example>
17 <title><constant>V4L2_PIX_FMT_GREY</constant> 4 &times; 4
18pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
65Local Variables:
66mode: sgml
67sgml-parent-document: "pixfmt.sgml"
68indent-tabs-mode: nil
69End:
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 &frac12; horizontal and vertical
10chroma resolution, also known as YUV 4:2:0. One luminance and one
11chrominance 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.
18The three components are separated into two sub-images or planes. The
19Y plane is first. The Y plane has one byte per pixel. For
20<constant>V4L2_PIX_FMT_NV12</constant>, a combined CbCr plane
21immediately follows the Y plane in memory. The CbCr plane is the same
22width, in bytes, as the Y plane (and of the image), but is half as
23tall in pixels. Each CbCr pair belongs to four pixels. For example,
24Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
25Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
26Y'<subscript>10</subscript>, Y'<subscript>11</subscript>.
27<constant>V4L2_PIX_FMT_NV21</constant> is the same except the Cb and
28Cr 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
31CbCr plane has as many pad bytes after its rows.</para>
32
33 <example>
34 <title><constant>V4L2_PIX_FMT_NV12</constant> 4 &times; 4
35pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
146Local Variables:
147mode: sgml
148sgml-parent-document: "pixfmt.sgml"
149indent-tabs-mode: nil
150End:
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 &frac12; horizontal
10chroma resolution, also known as YUV 4:2:2. One luminance and one
11chrominance 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.
18The three components are separated into two sub-images or planes. The
19Y plane is first. The Y plane has one byte per pixel. For
20<constant>V4L2_PIX_FMT_NV16</constant>, a combined CbCr plane
21immediately follows the Y plane in memory. The CbCr plane is the same
22width and height, in bytes, as the Y plane (and of the image).
23Each CbCr pair belongs to two pixels. For example,
24Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
25Y'<subscript>00</subscript>, Y'<subscript>01</subscript>.
26<constant>V4L2_PIX_FMT_NV61</constant> is the same except the Cb and
27Cr 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
30CbCr plane has as many pad bytes after its rows.</para>
31
32 <example>
33 <title><constant>V4L2_PIX_FMT_NV16</constant> 4 &times; 4
34pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
169Local Variables:
170mode: sgml
171sgml-parent-document: "pixfmt.sgml"
172indent-tabs-mode: nil
173End:
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
14typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits
15per pixel. These are all packed-pixel formats, meaning all the data
16for a pixel lie next to each other in memory.</para>
17
18 <para>When one of these formats is used, drivers shall report the
19colorspace <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>&nbsp;</entry>
73 <entry spanname="b0">Byte&nbsp;0 in memory</entry>
74 <entry spanname="b1">Byte&nbsp;1</entry>
75 <entry spanname="b2">Byte&nbsp;2</entry>
76 <entry spanname="b3">Byte&nbsp;3</entry>
77 </row>
78 <row>
79 <entry>&nbsp;</entry>
80 <entry>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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
390bits is undefined when reading from the driver, ignored when writing
391to the driver, except when alpha blending has been negotiated for a
392<link linkend="overlay">Video Overlay</link> or <link
393linkend="osd">Video Output Overlay</link>.</para>
394
395 <example>
396 <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 &times; 4 pixel
397image</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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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
478defined 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>&nbsp;</entry>
533 <entry spanname="b0">Byte&nbsp;0 in memory</entry>
534 <entry spanname="b1">Byte&nbsp;1</entry>
535 <entry spanname="b2">Byte&nbsp;2</entry>
536 <entry spanname="b3">Byte&nbsp;3</entry>
537 </row>
538 <row>
539 <entry>&nbsp;</entry>
540 <entry>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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
850actually supports is available from the LinuxTV v4l-dvb repository.
851See &v4l-dvb; for access instructions.</para>
852
853 </refsect1>
854 </refentry>
855
856 <!--
857Local Variables:
858mode: sgml
859sgml-parent-document: "pixfmt.sgml"
860indent-tabs-mode: nil
861End:
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
14the Y, Cb and Cr component of each pixel in one 16 or 32 bit
15word.</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>&nbsp;</entry>
69 <entry spanname="b0">Byte&nbsp;0 in memory</entry>
70 <entry spanname="b1">Byte&nbsp;1</entry>
71 <entry spanname="b2">Byte&nbsp;2</entry>
72 <entry spanname="b3">Byte&nbsp;3</entry>
73 </row>
74 <row>
75 <entry>&nbsp;</entry>
76 <entry>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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
230bits is undefined when reading from the driver, ignored when writing
231to the driver, except when alpha blending has been negotiated for a
232<link linkend="overlay">Video Overlay</link> or <link
233linkend="osd">Video Output Overlay</link>.</para>
234
235 </refsect1>
236 </refentry>
237
238 <!--
239Local Variables:
240mode: sgml
241sgml-parent-document: "pixfmt.sgml"
242indent-tabs-mode: nil
243End:
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
14linkend="V4L2-PIX-FMT-SBGGR8">
15<constant>V4L2_PIX_FMT_SBGGR8</constant></link>, except each pixel has
16a depth of 16 bits. The least significant byte is stored at lower
17memory addresses (little-endian). Note the actual sampling precision
18may be lower than 16 bits, for example 10 bits per pixel with values
19in range 0 to 1023.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_SBGGR16</constant> 4 &times; 4
23pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
86Local Variables:
87mode: sgml
88sgml-parent-document: "pixfmt.sgml"
89indent-tabs-mode: nil
90End:
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,
14reflecting the arrangement of sensors on the CCD device. Only one red,
15green or blue value is given for each pixel. Missing components must
16be interpolated from neighbouring pixels. From left to right the first
17row consists of a blue and green value, the second row of a green and
18red value. This scheme repeats to the right and down for every two
19columns and rows.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_SBGGR8</constant> 4 &times; 4
23pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
70Local Variables:
71mode: sgml
72sgml-parent-document: "pixfmt.sgml"
73indent-tabs-mode: nil
74End:
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,
14reflecting the arrangement of sensors on the CCD device. Only one red,
15green or blue value is given for each pixel. Missing components must
16be interpolated from neighbouring pixels. From left to right the first
17row consists of a green and blue value, the second row of a red and
18green value. This scheme repeats to the right and down for every two
19columns and rows.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_SGBRG8</constant> 4 &times; 4
23pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
70Local Variables:
71mode: sgml
72sgml-parent-document: "pixfmt.sgml"
73indent-tabs-mode: nil
74End:
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,
14reflecting the arrangement of sensors on the CCD device. Only one red,
15green or blue value is given for each pixel. Missing components must
16be interpolated from neighbouring pixels. From left to right the first
17row consists of a green and blue value, the second row of a red and
18green value. This scheme repeats to the right and down for every two
19columns and rows.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_SGRBG8</constant> 4 &times;
234 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
70Local Variables:
71mode: sgml
72sgml-parent-document: "pixfmt.sgml"
73indent-tabs-mode: nil
74End:
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
10in memory</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>In this format each four bytes is two pixels. Each four
16bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
17the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
18components have half the horizontal resolution of the Y
19component.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_UYVY</constant> 4 &times; 4
23pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
123Local Variables:
124mode: sgml
125sgml-parent-document: "pixfmt.sgml"
126indent-tabs-mode: nil
127End:
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
10in memory</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>In this format each four bytes is two pixels. Each four
16bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
17the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
18components have half the horizontal resolution of the Y
19component.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_VYUY</constant> 4 &times; 4
23pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
123Local Variables:
124mode: sgml
125sgml-parent-document: "pixfmt.sgml"
126indent-tabs-mode: nil
127End:
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
14pixel. The least significant byte is stored at lower memory addresses
15(little-endian). Note the actual sampling precision may be lower than
1616 bits, for example 10 bits per pixel with values in range 0 to
171023.</para>
18
19 <example>
20 <title><constant>V4L2_PIX_FMT_Y16</constant> 4 &times; 4
21pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
84Local Variables:
85mode: sgml
86sgml-parent-document: "pixfmt.sgml"
87indent-tabs-mode: nil
88End:
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 &frac14; horizontal chroma
9resolution, 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
15twelve bytes are two CbCr pairs and eight Y's. The first CbCr pair
16goes with the first four Y's, and the second CbCr pair goes with the
17other four Y's. The Cb and Cr components have one fourth the
18horizontal resolution of the Y component.</para>
19
20 <para>Do not confuse this format with <link
21linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link>.
22Y41P is derived from "YUV 4:1:1 <emphasis>packed</emphasis>", while
23YUV411P stands for "YUV 4:1:1 <emphasis>planar</emphasis>".</para>
24
25 <example>
26 <title><constant>V4L2_PIX_FMT_Y41P</constant> 8 &times; 4
27pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
152Local Variables:
153mode: sgml
154sgml-parent-document: "pixfmt.sgml"
155indent-tabs-mode: nil
156End:
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 &frac14; horizontal and
10vertical 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.
16The three components are separated into three sub-images or planes.
17The Y plane is first. The Y plane has one byte per pixel. For
18<constant>V4L2_PIX_FMT_YVU410</constant>, the Cr plane immediately
19follows the Y plane in memory. The Cr plane is &frac14; the width and
20&frac14; the height of the Y plane (and of the image). Each Cr belongs
21to 16 pixels, a four-by-four square of the image. Following the Cr
22plane is the Cb plane, just like the Cr plane.
23<constant>V4L2_PIX_FMT_YUV410</constant> is the same, except the Cb
24plane comes first, then the Cr plane.</para>
25
26 <para>If the Y plane has pad bytes after each row, then the Cr
27and Cb planes have &frac14; as many pad bytes after their rows. In
28other words, four Cx rows (including padding) are exactly as long as
29one Y row (including padding).</para>
30
31 <example>
32 <title><constant>V4L2_PIX_FMT_YVU410</constant> 4 &times; 4
33pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;16:</entry>
72 <entry>Cr<subscript>00</subscript></entry>
73 </row>
74 <row>
75 <entry>start&nbsp;+&nbsp;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 <!--
136Local Variables:
137mode: sgml
138sgml-parent-document: "pixfmt.sgml"
139indent-tabs-mode: nil
140End:
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 &frac14; horizontal chroma resolution,
9also 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
16format similar to the 4:2:2 planar format except with half as many
17chroma. The three components are separated into three sub-images or
18planes. The Y plane is first. The Y plane has one byte per pixel. The
19Cb plane immediately follows the Y plane in memory. The Cb plane is
20&frac14; the width of the Y plane (and of the image). Each Cb belongs
21to 4 pixels all on the same row. For example,
22Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
23Y'<subscript>01</subscript>, Y'<subscript>02</subscript> and
24Y'<subscript>03</subscript>. Following the Cb plane is the Cr plane,
25just like the Cb plane.</para>
26
27 <para>If the Y plane has pad bytes after each row, then the Cr
28and Cb planes have &frac14; as many pad bytes after their rows. In
29other words, four C x rows (including padding) is exactly as long as
30one Y row (including padding).</para>
31
32 <example>
33 <title><constant>V4L2_PIX_FMT_YUV411P</constant> 4 &times; 4
34pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;16:</entry>
73 <entry>Cb<subscript>00</subscript></entry>
74 </row>
75 <row>
76 <entry>start&nbsp;+&nbsp;17:</entry>
77 <entry>Cb<subscript>10</subscript></entry>
78 </row>
79 <row>
80 <entry>start&nbsp;+&nbsp;18:</entry>
81 <entry>Cb<subscript>20</subscript></entry>
82 </row>
83 <row>
84 <entry>start&nbsp;+&nbsp;19:</entry>
85 <entry>Cb<subscript>30</subscript></entry>
86 </row>
87 <row>
88 <entry>start&nbsp;+&nbsp;20:</entry>
89 <entry>Cr<subscript>00</subscript></entry>
90 </row>
91 <row>
92 <entry>start&nbsp;+&nbsp;21:</entry>
93 <entry>Cr<subscript>10</subscript></entry>
94 </row>
95 <row>
96 <entry>start&nbsp;+&nbsp;22:</entry>
97 <entry>Cr<subscript>20</subscript></entry>
98 </row>
99 <row>
100 <entry>start&nbsp;+&nbsp;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 <!--
150Local Variables:
151mode: sgml
152sgml-parent-document: "v4l2.sgml"
153indent-tabs-mode: nil
154End:
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 &frac12; horizontal and
10vertical 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.
16The three components are separated into three sub- images or planes.
17The Y plane is first. The Y plane has one byte per pixel. For
18<constant>V4L2_PIX_FMT_YVU420</constant>, the Cr plane immediately
19follows the Y plane in memory. The Cr plane is half the width and half
20the height of the Y plane (and of the image). Each Cr belongs to four
21pixels, a two-by-two square of the image. For example,
22Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
23Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and
24Y'<subscript>11</subscript>. Following the Cr plane is the Cb plane,
25just like the Cr plane. <constant>V4L2_PIX_FMT_YUV420</constant> is
26the 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
29and Cb planes have half as many pad bytes after their rows. In other
30words, 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 &times; 4
35pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;16:</entry>
74 <entry>Cr<subscript>00</subscript></entry>
75 <entry>Cr<subscript>01</subscript></entry>
76 </row>
77 <row>
78 <entry>start&nbsp;+&nbsp;18:</entry>
79 <entry>Cr<subscript>10</subscript></entry>
80 <entry>Cr<subscript>11</subscript></entry>
81 </row>
82 <row>
83 <entry>start&nbsp;+&nbsp;20:</entry>
84 <entry>Cb<subscript>00</subscript></entry>
85 <entry>Cb<subscript>01</subscript></entry>
86 </row>
87 <row>
88 <entry>start&nbsp;+&nbsp;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 <!--
152Local Variables:
153mode: sgml
154sgml-parent-document: "pixfmt.sgml"
155indent-tabs-mode: nil
156End:
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 &frac12; horizontal chroma resolution,
9also 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
16version of the YUYV format. The three components are separated into
17three sub-images or planes. The Y plane is first. The Y plane has one
18byte per pixel. The Cb plane immediately follows the Y plane in
19memory. The Cb plane is half the width of the Y plane (and of the
20image). Each Cb belongs to two pixels. For example,
21Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
22Y'<subscript>01</subscript>. Following the Cb plane is the Cr plane,
23just like the Cb plane.</para>
24
25 <para>If the Y plane has pad bytes after each row, then the Cr
26and Cb planes have half as many pad bytes after their rows. In other
27words, 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 &times; 4
32pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;16:</entry>
71 <entry>Cb<subscript>00</subscript></entry>
72 <entry>Cb<subscript>01</subscript></entry>
73 </row>
74 <row>
75 <entry>start&nbsp;+&nbsp;18:</entry>
76 <entry>Cb<subscript>10</subscript></entry>
77 <entry>Cb<subscript>11</subscript></entry>
78 </row>
79 <row>
80 <entry>start&nbsp;+&nbsp;20:</entry>
81 <entry>Cb<subscript>20</subscript></entry>
82 <entry>Cb<subscript>21</subscript></entry>
83 </row>
84 <row>
85 <entry>start&nbsp;+&nbsp;22:</entry>
86 <entry>Cb<subscript>30</subscript></entry>
87 <entry>Cb<subscript>31</subscript></entry>
88 </row>
89 <row>
90 <entry>start&nbsp;+&nbsp;24:</entry>
91 <entry>Cr<subscript>00</subscript></entry>
92 <entry>Cr<subscript>01</subscript></entry>
93 </row>
94 <row>
95 <entry>start&nbsp;+&nbsp;26:</entry>
96 <entry>Cr<subscript>10</subscript></entry>
97 <entry>Cr<subscript>11</subscript></entry>
98 </row>
99 <row>
100 <entry>start&nbsp;+&nbsp;28:</entry>
101 <entry>Cr<subscript>20</subscript></entry>
102 <entry>Cr<subscript>21</subscript></entry>
103 </row>
104 <row>
105 <entry>start&nbsp;+&nbsp;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 <!--
156Local Variables:
157mode: sgml
158sgml-parent-document: "pixfmt.sgml"
159indent-tabs-mode: nil
160End:
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 &frac12; horizontal chroma
9resolution, 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
15bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
16the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
17components have half the horizontal resolution of the Y component.
18<constant>V4L2_PIX_FMT_YUYV </constant> is known in the Windows
19environment as YUY2.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_YUYV</constant> 4 &times; 4
23pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
123Local Variables:
124mode: sgml
125sgml-parent-document: "pixfmt.sgml"
126indent-tabs-mode: nil
127End:
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
10in memory</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>In this format each four bytes is two pixels. Each four
16bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
17the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
18components have half the horizontal resolution of the Y
19component.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_YVYU</constant> 4 &times; 4
23pixel 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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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&nbsp;+&nbsp;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 <!--
123Local Variables:
124mode: sgml
125sgml-parent-document: "pixfmt.sgml"
126indent-tabs-mode: nil
127End:
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
4image data with applications. The
5<structname>v4l2_pix_format</structname> structure defines the format
6and layout of an image in memory. Image formats are negotiated with
7the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
8capturing 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
28request an image size, drivers return the closest possible values. In
29case of planar formats the <structfield>width</structfield> and
30<structfield>height</structfield> applies to the largest plane. To
31avoid ambiguities drivers must return values rounded up to a multiple
32of the scale factor of any smaller planes. For example when the image
33format 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
40application. This is a little endian <link
41linkend="v4l2-fourcc">four character code</link>. V4L2 defines
42standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref
43linkend="yuv-formats" />, and reserved codes in <xref
44linkend="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
50can request to capture or output only the top or bottom field, or both
51fields interlaced or sequentially stored in one buffer or alternating
52in separate buffers. Drivers return the actual field order selected.
53For 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
59adjacent lines.</entry>
60 </row>
61 <row>
62 <entry spanname="hspan"><para>Both applications and drivers
63can set this field to request padding bytes at the end of each line.
64Drivers however may ignore the value requested by the application,
65returning <structfield>width</structfield> times bytes per pixel or a
66larger value required by the hardware. That implies applications can
67just set this field to zero to get a reasonable
68default.</para><para>Video hardware may access padding bytes,
69therefore they must reside in accessible memory. Consider cases where
70padding bytes after the last line of an image cross a system page
71boundary. Input devices may write padding bytes, the value is
72undefined. Output devices ignore the contents of padding
73bytes.</para><para>When the image format is planar the
74<structfield>bytesperline</structfield> value applies to the largest
75plane and is divided by the same factor as the
76<structfield>width</structfield> field for any smaller planes. For
77example the Cb and Cr planes of a YUV 4:2:0 image have half as many
78padding bytes following each line as the Y plane. To avoid ambiguities
79drivers must return a <structfield>bytesperline</structfield> value
80rounded 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,
86set by the driver. Usually this is
87<structfield>bytesperline</structfield> times
88<structfield>height</structfield>. When the image consists of variable
89length compressed data this is the maximum number of bytes required to
90hold 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,
97see <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
103information about formats. When not used drivers and applications must
104set 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
114applications, it is necessary to have standard image data formats
115which both sides will interpret the same way. V4L2 includes several
116such formats, and this section is intended to be an unambiguous
117specification of the standard image data formats in V4L2.</para>
118
119 <para>V4L2 drivers are not limited to these formats, however.
120Driver-specific formats are possible. In that case the application may
121depend on a codec to convert images to one of the standard formats
122when needed. But the data can still be stored and retrieved in the
123proprietary format. For example, a device may support a proprietary
124compressed format. Applications can still capture and save the data in
125the compressed format, saving much disk space, and later use a codec
126to convert the images to the X Windows screen format when the video is
127to be displayed.</para>
128
129 <para>Even so, ultimately, some standard formats are needed, so
130the V4L2 specification would not be complete without well-defined
131standard formats.</para>
132
133 <para>The V4L2 standard formats are mainly uncompressed formats. The
134pixels are always arranged in memory from left to right, and from top
135to bottom. The first byte of data in the image buffer is always for
136the leftmost pixel of the topmost row. Following that is the pixel
137immediately to its right, and so on until the end of the top row of
138pixels. Following the rightmost pixel of the row there may be zero or
139more bytes of padding to guarantee that each row of pixel data has a
140certain alignment. Following the pad bytes, if any, is data for the
141leftmost pixel of the second row from the top, and so on. The last row
142has 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
146linkend="videodev">videodev.h</link> header file. These identifiers
147represent <link linkend="v4l2-fourcc">four character codes</link>
148which are also listed below, however they are not the same as those
149used 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
158on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and
159http://vektor.theorem.ca/graphics/ycbcr/ and
160http://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
175signals</term>
176 <listitem>
177 <para>[to do]</para>
178 <para>E'<subscript>Y</subscript> =
179Coeff<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
196range [-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> =
200K<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> =
205K<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) &middot; E'<subscript>Y</subscript> + Lum. Offset</para>
216 <para>C<subscript>B</subscript> = (Chrom. Levels - 1)
217&middot; P<subscript>B</subscript> + Chrom. Offset</para>
218 <para>C<subscript>R</subscript> = (Chrom. Levels - 1)
219&middot; 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
222stored 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>
234int ER, EG, EB; /* gamma corrected RGB input [0;255] */
235int Y1, Cb, Cr; /* output [0;255] */
236
237double r, g, b; /* temporaries */
238double y1, pb, pr;
239
240int
241clamp (double x)
242{
243 int r = x; /* round to nearest */
244
245 if (r &lt; 0) return 0;
246 else if (r &gt; 255) return 255;
247 else return r;
248}
249
250r = ER / 255.0;
251g = EG / 255.0;
252b = EB / 255.0;
253
254y1 = 0.299 * r + 0.587 * g + 0.114 * b;
255pb = -0.169 * r - 0.331 * g + 0.5 * b;
256pr = 0.5 * r - 0.419 * g - 0.081 * b;
257
258Y1 = clamp (219 * y1 + 16);
259Cb = clamp (224 * pb + 128);
260Cr = clamp (224 * pr + 128);
261
262/* or shorter */
263
264y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB;
265
266Y1 = clamp ( (219 / 255.0) * y1 + 16);
267Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128);
268Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128);
269 </programlisting>
270
271 <para>Inverse Transformation</para>
272
273 <programlisting>
274int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */
275int ER, EG, EB; /* output [0;255] */
276
277double r, g, b; /* temporaries */
278double y1, pb, pr;
279
280int
281clamp (double x)
282{
283 int r = x; /* round to nearest */
284
285 if (r &lt; 0) return 0;
286 else if (r &gt; 255) return 255;
287 else return r;
288}
289
290y1 = (255 / 219.0) * (Y1 - 16);
291pb = (255 / 224.0) * (Cb - 128);
292pr = (255 / 224.0) * (Cr - 128);
293
294r = 1.0 * y1 + 0 * pb + 1.402 * pr;
295g = 1.0 * y1 - 0.344 * pb - 0.714 * pr;
296b = 1.0 * y1 + 1.772 * pb + 0 * pr;
297
298ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */
299EG = clamp (g * 255);
300EB = 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
328given 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&nbsp;=&nbsp;0.630, y&nbsp;=&nbsp;0.340</entry>
350 <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.595</entry>
351 <entry>x&nbsp;=&nbsp;0.155, y&nbsp;=&nbsp;0.070</entry>
352 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
353 Illuminant D<subscript>65</subscript></entry>
354 <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
3551.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
356 <entry>0.299&nbsp;E'<subscript>R</subscript>
357+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
358+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
359 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
360 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;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
366linkend="smpte240m" /></entry>
367 <entry>x&nbsp;=&nbsp;0.630, y&nbsp;=&nbsp;0.340</entry>
368 <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.595</entry>
369 <entry>x&nbsp;=&nbsp;0.155, y&nbsp;=&nbsp;0.070</entry>
370 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
371 Illuminant D<subscript>65</subscript></entry>
372 <entry>E' = 4&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.0228,
3731.1115&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.1115&nbsp;for&nbsp;0.0228&nbsp;&lt;&nbsp;I</entry>
374 <entry>0.212&nbsp;E'<subscript>R</subscript>
375+&nbsp;0.701&nbsp;E'<subscript>G</subscript>
376+&nbsp;0.087&nbsp;E'<subscript>B</subscript></entry>
377 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
378 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;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
384linkend="itu709" /></entry>
385 <entry>x&nbsp;=&nbsp;0.640, y&nbsp;=&nbsp;0.330</entry>
386 <entry>x&nbsp;=&nbsp;0.300, y&nbsp;=&nbsp;0.600</entry>
387 <entry>x&nbsp;=&nbsp;0.150, y&nbsp;=&nbsp;0.060</entry>
388 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
389 Illuminant D<subscript>65</subscript></entry>
390 <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
3911.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
392 <entry>0.2125&nbsp;E'<subscript>R</subscript>
393+&nbsp;0.7154&nbsp;E'<subscript>G</subscript>
394+&nbsp;0.0721&nbsp;E'<subscript>B</subscript></entry>
395 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
396 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;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
403quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range
404of Y' = 16 &hellip; 253, unlike Rec. 601 Y' = 16 &hellip;
405235. This is not a typo in the Bt878 documentation, it has been
406implemented 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&nbsp;E'<subscript>R</subscript>
414+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
415+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
416 <entry><emphasis>237</emphasis>&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
417 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;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
424the chromaticities of M/NTSC, the remaining parameters are equal to B and
425G/PAL.</para>
426 </footnote> according to <xref linkend="itu470" />, <xref
427 linkend="itu601" /></entry>
428 <entry>x&nbsp;=&nbsp;0.67, y&nbsp;=&nbsp;0.33</entry>
429 <entry>x&nbsp;=&nbsp;0.21, y&nbsp;=&nbsp;0.71</entry>
430 <entry>x&nbsp;=&nbsp;0.14, y&nbsp;=&nbsp;0.08</entry>
431 <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.316, Illuminant C</entry>
432 <entry>?</entry>
433 <entry>0.299&nbsp;E'<subscript>R</subscript>
434+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
435+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
436 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
437 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;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
443linkend="itu470" />, <xref linkend="itu601" /></entry>
444 <entry>x&nbsp;=&nbsp;0.64, y&nbsp;=&nbsp;0.33</entry>
445 <entry>x&nbsp;=&nbsp;0.29, y&nbsp;=&nbsp;0.60</entry>
446 <entry>x&nbsp;=&nbsp;0.15, y&nbsp;=&nbsp;0.06</entry>
447 <entry>x&nbsp;=&nbsp;0.313, y&nbsp;=&nbsp;0.329,
448Illuminant D<subscript>65</subscript></entry>
449 <entry>?</entry>
450 <entry>0.299&nbsp;E'<subscript>R</subscript>
451+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
452+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
453 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
454 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;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&nbsp;E'<subscript>R</subscript>
466+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
467+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
468 <entry>256&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16<footnote>
469 <para>Note JFIF quantizes
470Y'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
472are still clamped to [0;255].</para>
473 </footnote></entry>
474 <entry>256&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
475 </row>
476 <row>
477 <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry>
478 <entry>8</entry>
479 <entry>[?]</entry>
480 <entry>x&nbsp;=&nbsp;0.640, y&nbsp;=&nbsp;0.330</entry>
481 <entry>x&nbsp;=&nbsp;0.300, y&nbsp;=&nbsp;0.600</entry>
482 <entry>x&nbsp;=&nbsp;0.150, y&nbsp;=&nbsp;0.060</entry>
483 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
484 Illuminant D<subscript>65</subscript></entry>
485 <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
4861.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;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
498into a 256 entry ARGB palette. It is intended for <link
499linkend="osd">Video Output Overlays</link> only. There are no ioctls to
500access 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>&nbsp;</entry>
527 <entry spanname="b0">Byte&nbsp;0</entry>
528 </row>
529 <row>
530 <entry>&nbsp;</entry>
531 <entry>&nbsp;</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
576signals. It separates the brightness information (Y) from the color
577information (U and V or Cb and Cr). The color information consists of
578red and blue <emphasis>color difference</emphasis> signals, this way
579the green component can be reconstructed by subtracting from the
580brightness component. See <xref linkend="colorspaces" /> for conversion
581examples. YUV was chosen because early television would only transmit
582brightness information. To add color in a way compatible with existing
583receivers a new signal carrier was added to transmit the color
584difference signals. Secondary in the YUV format the U and V components
585usually have lower resolution than the Y component. This is an analog
586video compression technique taking advantage of a property of the
587human visual system, being more sensitive to brightness
588information.</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
631extended 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
643are just listed for reference and to avoid naming conflicts. If you
644want to register your own format, send an e-mail to the linux-media mailing
645list &v4l-ml; for inclusion in the <filename>videodev2.h</filename>
646file. If you want to share your format with other developers add a
647link to your documentation and send a copy to the linux-media mailing list
648for inclusion in this section. If you think your format should be listed
649in a standard format section please make a proposal on the linux-media mailing
650list.</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
683IVTV driver, <ulink url="http://www.ivtvdriver.org/">
684http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the
685kernel 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
777url="http://www.thedirks.org/winnov/">
778http://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 <!--
796Local Variables:
797mode: sgml
798sgml-parent-document: "v4l2.sgml"
799indent-tabs-mode: nil
800End:
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
6manufacturer has their own type of control. It is not rare for the same manufacturer to ship different
7types of controls, depending on the device.</para>
8<para>Unfortunately, for several years, there was no effort to create uniform IR keycodes for
9different devices. This caused the same IR keyname to be mapped completely differently on
10different IR devices. This resulted that the same IR keyname to be mapped completely different on
11different 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>&gt;&gt; / FORWARD</entry></row>
42<row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry>&lt;&lt;&lt; / BACK</entry></row>
43<row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>&gt;&gt;&gt; / 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>&lt;&lt; / 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 / &gt;</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>-&gt; ) / 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
170the /dev/input/event device, to allow changing the default
171keymapping.</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
24documentation.</contrib>
25 </author>
26
27 <author>
28 <firstname>Hans</firstname>
29 <surname>Verkuil</surname>
30 <contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl,
31the extended control ioctls and major parts of the sliced VBI
32API.</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
50and 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
57MPEG 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,
70Remote 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
92Rubli, 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,
101structs, ioctls) must be noted in more detail in the history chapter
102(compat.sgml), along with the possible impact on existing drivers and
103applications. -->
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
110the V4L2 API changes will be used by the Linux Kernel.
111Also 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;
133added 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
141capabilities. 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
149the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT.
150Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
151V4L2_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
159and 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.
167Clarified 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
175controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
176VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD,
177VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
178Clarifications in the cropping chapter, about RGB pixel formats, the
179mmap(), poll(), select(), read() and write() functions. Typographical
180fixes.</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
195struct 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
210Verkuil. 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
225VIDIOC_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
233BT.1119. capture.c/start_capturing() for user pointer I/O did not
234initialize the buffer index. Documented the V4L MPEG and MJPEG
235VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel
236formats. 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
244VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of
245digital 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
253clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2
254defines.</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
262v4l2_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
270v4l2_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
278clarifications.</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
286Verkuil and I rewrote the sliced VBI section. He also contributed a
287VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard
288selection 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
296example, 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
304enumeration, downscaling and aspect example. Added read and user
305pointer 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,
313various 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.
328SGML fixes. Added latest API changes. Closed gaps in the history
329chapter.</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
344Knorr.</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
352and 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
471using libv4l handlers. The advantage is that this grabber can potentially work
472with 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 &lt;mchehab@infradead.org&gt;
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 &lt;stdio.h&gt;
16#include &lt;stdlib.h&gt;
17#include &lt;string.h&gt;
18#include &lt;fcntl.h&gt;
19#include &lt;errno.h&gt;
20#include &lt;sys/ioctl.h&gt;
21#include &lt;sys/types.h&gt;
22#include &lt;sys/time.h&gt;
23#include &lt;sys/mman.h&gt;
24#include &lt;linux/videodev2.h&gt;
25#include "../libv4l/include/libv4l2.h"
26
27#define CLEAR(x) memset(&amp;(x), 0, sizeof(x))
28
29struct buffer {
30 void *start;
31 size_t length;
32};
33
34static 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 &amp;&amp; ((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
48int 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 &lt; 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, &amp;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, &amp;req);
89
90 buffers = calloc(req.count, sizeof(*buffers));
91 for (n_buffers = 0; n_buffers &lt; 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, &amp;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 &lt; 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, &amp;buf);
117 }
118 type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
119
120 xioctl(fd, VIDIOC_STREAMON, &amp;type);
121 for (i = 0; i &lt; 20; i++) {
122 do {
123 FD_ZERO(&amp;fds);
124 FD_SET(fd, &amp;fds);
125
126 /* Timeout. */
127 tv.tv_sec = 2;
128 tv.tv_usec = 0;
129
130 r = select(fd + 1, &amp;fds, NULL, NULL, &amp;tv);
131 } while ((r == -1 &amp;&amp; (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, &amp;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, &amp;buf);
154 }
155
156 type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
157 xioctl(fd, VIDIOC_STREAMOFF, &amp;type);
158 for (i = 0; i &lt; 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 &lt;bill@thedirks.org&gt;
53 * Justin Schoeman
54 * Hans Verkuil &lt;hverkuil@xs4all.nl&gt;
55 * et al.
56 */
57#ifndef __LINUX_VIDEODEV2_H
58#define __LINUX_VIDEODEV2_H
59
60#ifdef __KERNEL__
61#include &lt;linux/time.h&gt; /* need struct timeval */
62#else
63#include &lt;sys/time.h&gt;
64#endif
65#include &lt;linux/compiler.h&gt;
66#include &lt;linux/ioctl.h&gt;
67#include &lt;linux/types.h&gt;
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) &lt;&lt; 8) | ((__u32)(c) &lt;&lt; 16) | ((__u32)(d) &lt;&lt; 24))
103
104/*
105 * E N U M S
106 */
107enum <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
149enum <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
164enum <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
174enum <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
180enum <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/ */
187enum <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
214enum <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
222struct <link linkend="v4l2-rect">v4l2_rect</link> {
223 __s32 left;
224 __s32 top;
225 __s32 width;
226 __s32 height;
227};
228
229struct <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 */
237struct <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 */
271struct <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 */
370struct <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 */
387enum <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
393struct <link linkend="v4l2-frmsize-discrete">v4l2_frmsize_discrete</link> {
394 __u32 width; /* Frame width [pixel] */
395 __u32 height; /* Frame height [pixel] */
396};
397
398struct <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
407struct <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 */
423enum <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
429struct <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
435struct <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 */
454struct <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
479struct <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&lt;&lt;3) /* Define Huffman Tables */
501#define V4L2_JPEG_MARKER_DQT (1&lt;&lt;4) /* Define Quantization Tables */
502#define V4L2_JPEG_MARKER_DRI (1&lt;&lt;5) /* Define Restart Interval */
503#define V4L2_JPEG_MARKER_COM (1&lt;&lt;6) /* Comment segment */
504#define V4L2_JPEG_MARKER_APP (1&lt;&lt;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 */
511struct <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
518struct <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 */
552struct <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
576struct <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
581struct <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 */
594struct <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
607struct <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 */
619struct <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
626struct <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
635typedef __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
724struct <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 */
736struct <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 */
778struct <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 */
795struct <link linkend="v4l2-control">v4l2_control</link> {
796 __u32 id;
797 __s32 value;
798};
799
800struct <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
811struct <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) &amp; 0x0fff0000UL)
827#define V4L2_CTRL_DRIVER_PRIV(id) (((id) &amp; 0xffff) &gt;= 0x1000)
828
829/* Used in the VIDIOC_QUERYCTRL ioctl for querying controls */
830struct <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 */
843struct <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)
897enum <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)
909enum <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)
926enum <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)
941enum <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)
948enum <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)
954enum <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)
962enum <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)
979enum <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)
996enum <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)
1013enum <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)
1020enum <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)
1027enum <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)
1033enum <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)
1040enum <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)
1064enum <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)
1070enum <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)
1081enum <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)
1094enum <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)
1100enum <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)
1108enum <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)
1113enum <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)
1119enum <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)
1137enum <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)
1189enum <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 */
1200struct <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
1214struct <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
1249struct <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
1256struct <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
1268struct <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 */
1288struct <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
1303struct <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
1322struct <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)
1331struct <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 &lt;&lt; 0)
1346
1347struct <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 */
1367struct <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 &lt;&lt; 0)
1380#define V4L2_VBI_INTERLACED (1 &lt;&lt; 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
1389struct <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
1413struct <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
1424struct <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
1454struct <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
1459struct <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
1464struct <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
1471struct <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 */
1485struct <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 */
1499struct <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
1522struct <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
1530struct <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 */
1538struct <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 &lt;media/v4l2-chip-ident.h&gt; */
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
53limits, the pixel aspect of images and to calculate scale factors.
54They set the <structfield>type</structfield> field of a v4l2_cropcap
55structure to the respective buffer (stream) type and call the
56<constant>VIDIOC_CROPCAP</constant> ioctl with a pointer to this
57structure. Drivers fill the rest of the structure. The results are
58constant except when switching the video standard. Remember this
59switch can occur implicit when switching the video input or
60output.</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.
71Only 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
75defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
76and 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
82possible, this may exclude for example the horizontal and vertical
83blanking areas. The cropping rectangle cannot exceed these limits.
84Width and height are defined in pixels, the driver writer is free to
85choose origin and units of the coordinate system in the analog
86domain.</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
93640&nbsp;&times;&nbsp;480 rectangle for NTSC, a
94768&nbsp;&times;&nbsp;576 rectangle for PAL and SECAM centered over
95the 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
102scaling is applied, the ratio of the actual sampling
103frequency and the frequency required to get square
104pixels.</para><para>When cropping coordinates refer to square pixels,
105the driver sets <structfield>pixelaspect</structfield> to 1/1. Other
106common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled
107according 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
124rectangle, 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
130rectangle, 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
141and height cannot be negative, the fields are signed for
142hysterical reasons. <!-- video4linux-list@redhat.com
143on 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
159invalid or the ioctl is not supported. This is not permitted for
160video 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<!--
169Local Variables:
170mode: sgml
171sgml-parent-document: "v4l2.sgml"
172indent-tabs-mode: nil
173End:
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
56linkend="experimental">experimental</link> interface and may change in
57the future.</para>
58 </note>
59
60 <para>For driver debugging purposes this ioctl allows test
61applications to query the driver about the chips present on the TV
62card. Regular applications must not use it. When you found a chip
63specific bug, please contact the linux-media mailing list (&v4l-ml;)
64so 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>
69fields of a &v4l2-dbg-chip-ident;
70and call <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> with a pointer to
71this structure. On success the driver stores information about the
72selected chip in the <structfield>ident</structfield> and
73<structfield>revision</structfield> fields. On failure the structure
74remains 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
79on the TV card. You can enumerate all chips by starting at zero and
80incrementing <structfield>match.addr</structfield> by one until
81<constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;.
82The number zero always selects the host chip, &eg; the chip connected
83to 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.
88For instance
89<constant>"saa7127"</constant> will match any chip
90supported by the saa7127 driver, regardless of its &i2c; bus address.
91When multiple chips supported by the same driver are present, the
92ioctl 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
103on the TV card. You can enumerate all chips by starting at zero and
104incrementing <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
108contain 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
111specific value, or zero if no particular revision is associated with
112this 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
117the 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
125was introduced in Linux 2.6.21, but the API was changed to the
126one described here in 2.6.29.</para>
127
128 <para>We recommended the <application>v4l2-dbg</application>
129utility over calling this ioctl directly. It is available from the
130LinuxTV v4l-dvb repository; see <ulink
131url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
132access 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
145possible 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
156to 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
163to 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
184the 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
247could 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<!--
270Local Variables:
271mode: sgml
272sgml-parent-document: "v4l2.sgml"
273indent-tabs-mode: nil
274End:
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>
65interface and may change in the future.</para>
66 </note>
67
68 <para>For driver debugging purposes these ioctls allow test
69applications to access hardware registers directly. Regular
70applications must not use them.</para>
71
72 <para>Since writing or even reading registers can jeopardize the
73system security, its stability and damage the hardware, both ioctls
74require superuser privileges. Additionally the Linux kernel must be
75compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option
76to enable these ioctls.</para>
77
78 <para>To write a register applications must initialize all fields
79of a &v4l2-dbg-register; and call
80<constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this
81structure. The <structfield>match.type</structfield> and
82<structfield>match.addr</structfield> or <structfield>match.name</structfield>
83fields select a chip on the TV
84card, the <structfield>reg</structfield> field specifies a register
85number and the <structfield>val</structfield> field the value to be
86written 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
93structure. On success the driver stores the register value in the
94<structfield>val</structfield> field. On failure the structure remains
95unchanged.</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
100on the TV card. The number zero always selects the host chip, &eg; the
101chip connected to the PCI or USB bus. You can find out which chips are
102present 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.
107For instance
108<constant>"saa7127"</constant> will match any chip
109supported by the saa7127 driver, regardless of its &i2c; bus address.
110When multiple chips supported by the same driver are present, the
111effect of these ioctls is undefined. Again with the
112&VIDIOC-DBG-G-CHIP-IDENT; ioctl you can find out which &i2c; chips are
113present.</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;
118bus 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
123on 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
129return successfully without actually reading or writing a register. To
130catch the most likely failure we recommend a &VIDIOC-DBG-G-CHIP-IDENT;
131call confirming the presence of the selected &i2c; chip.</para>
132 </note>
133
134 <para>These ioctls are optional, not all drivers may support them.
135However 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
1412.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>
144utility over calling these ioctls directly. It is available from the
145LinuxTV v4l-dvb repository; see <ulink
146url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
147access 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
160possible 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
171to 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
178to 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
206register.</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
253was not compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant>
254option, or the <structfield>match_type</structfield> is invalid, or the
255selected 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
262to execute these ioctls.</para>
263 </listitem>
264 </varlistentry>
265 </variablelist>
266 </refsect1>
267</refentry>
268
269<!--
270Local Variables:
271mode: sgml
272sgml-parent-document: "v4l2.sgml"
273indent-tabs-mode: nil
274End:
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>
56interface 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
61encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to
62try 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
71command code. The <structfield>flags</structfield> field is currently
72only used by the STOP command and contains one bit: If the
73<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
74encoding will continue until the end of the current <wordasword>Group
75Of Pictures</wordasword>, otherwise it will stop immediately.</para>
76
77 <para>A <function>read</function>() call sends a START command to
78the encoder if it has not been started yet. After a STOP command,
79<function>read</function>() calls will read the remaining data
80buffered 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
85to the encoder, and all buffered data is discarded.</para>
86
87 <para>These ioctls are optional, not all drivers may support
88them. 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
105this command, drivers and applications must set this field to
106zero.</entry>
107 </row>
108 <row>
109 <entry>__u32</entry>
110 <entry><structfield>data</structfield>[8]</entry>
111 <entry>Reserved for future extensions. Drivers and
112applications 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
127running or paused, this command does nothing. No flags are defined for
128this 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,
135encoding will continue until the end of the current <wordasword>Group
136Of Pictures</wordasword>, otherwise encoding will stop immediately.
137When the encoder is already stopped, this command does
138nothing.</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
144started yet, the driver will return an &EPERM;. When the encoder is
145already paused, this command does nothing. No flags are defined for
146this 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
152encoder has not been started yet, the driver will return an &EPERM;.
153When the encoder is already running, this command does nothing. No
154flags 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
169Pictures</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
191the encoder was not running.</para>
192 </listitem>
193 </varlistentry>
194 </variablelist>
195 </refsect1>
196</refentry>
197
198<!--
199Local Variables:
200mode: sgml
201sgml-parent-document: "v4l2.sgml"
202indent-tabs-mode: nil
203End:
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>
54field of &v4l2-fmtdesc; and call the
55<constant>VIDIOC_ENUM_FMT</constant> ioctl with a pointer to this
56structure. Drivers fill the rest of the structure or return an
57&EINVAL;. All formats are enumerable by beginning at index zero and
58incrementing by one until <errorcode>EINVAL</errorcode> is
59returned.</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
70the application. This is in no way related to the <structfield>
71pixelformat</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.
77Only 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
81defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
82and 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
93string. This information is intended for the user, for example: "YUV
944: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
100four character code as computed by the v4l2_fourcc()
101macro:</entry>
102 </row>
103 <row>
104 <entry spanname="hspan"><para><programlisting id="v4l2-fourcc">
105#define v4l2_fourcc(a,b,c,d) (((__u32)(a)&lt;&lt;0)|((__u32)(b)&lt;&lt;8)|((__u32)(c)&lt;&lt;16)|((__u32)(d)&lt;&lt;24))
106</programlisting></para><para>Several image formats are already
107defined by this specification in <xref linkend="pixfmt" />. Note these
108codes 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
114the 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
134through software (usually libv4l2), where possible try to use a native format
135instead 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>
150is not supported or the <structfield>index</structfield> is out of
151bounds.</para>
152 </listitem>
153 </varlistentry>
154 </variablelist>
155 </refsect1>
156</refentry>
157
158<!--
159Local Variables:
160mode: sgml
161sgml-parent-document: "v4l2.sgml"
162indent-tabs-mode: nil
163End:
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
44contains 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
54intervals that the device supports for the given pixel format and
55frame size.</para>
56 <para>The supported pixel formats and frame sizes can be obtained
57by using the &VIDIOC-ENUM-FMT; and &VIDIOC-ENUM-FRAMESIZES;
58functions.</para>
59 <para>The return value and the content of the
60<structfield>v4l2_frmivalenum.type</structfield> field depend on the
61type of frame intervals the device supports. Here are the semantics of
62the function for the different cases:</para>
63 <itemizedlist>
64 <listitem>
65 <para><emphasis role="bold">Discrete:</emphasis> The function
66returns success if the given index value (zero-based) is valid. The
67application should increase the index by one for each call until
68<constant>EINVAL</constant> is returned. The `v4l2_frmivalenum.type`
69field is set to `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the
70union only the `discrete` member is valid.</para>
71 </listitem>
72 <listitem>
73 <para><emphasis role="bold">Step-wise:</emphasis> The function
74returns 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
78union only the <structfield>stepwise</structfield> member is
79valid.</para>
80 </listitem>
81 <listitem>
82 <para><emphasis role="bold">Continuous:</emphasis> This is a
83special case of the step-wise type above. The function returns success
84if the given index value is zero and <constant>EINVAL</constant> for
85any 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
88the union only the <structfield>stepwise</structfield> member is valid
89and 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
94must check the <structfield>type</structfield> field to determine the
95type of frame interval enumeration the device supports. Only for the
96<constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant> type does it make
97sense to increase the index value to receive more frame
98intervals.</para>
99 <para>Note that the order in which the frame intervals are
100returned has no special meaning. In particular does it not say
101anything about potential default frame intervals.</para>
102 <para>Applications can assume that the enumeration data does not
103change without any interaction from the application itself. This means
104that the enumeration data is consistent if the application does not
105perform any other ioctl calls while it runs the frame interval
106enumeration.</para>
107 </refsect1>
108
109 <refsect1>
110 <title>Notes</title>
111
112 <itemizedlist>
113 <listitem>
114 <para><emphasis role="bold">Frame intervals and frame
115rates:</emphasis> The V4L2 API uses frame intervals instead of frame
116rates. Given the frame interval the frame rate can be computed as
117follows:<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
127value that has to be filled in by the application,
128<emphasis>OUT</emphasis> denotes values that the driver fills in. The
129application 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
169enumeration.</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
176enumerated.</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
183enumerated.</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
190enumerated.</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
259values that <varname>errno</varname> can have.</para>
260 </refsect1>
261
262</refentry>
263
264<!--
265Local Variables:
266mode: sgml
267sgml-parent-document: "v4l2.sgml"
268indent-tabs-mode: nil
269End:
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
44and 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>
57interface 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
62given 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
67type of frame sizes the device supports. Here are the semantics of the
68function for the different cases:</para>
69
70 <itemizedlist>
71 <listitem>
72 <para><emphasis role="bold">Discrete:</emphasis> The function
73returns success if the given index value (zero-based) is valid. The
74application 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
78union only the <structfield>discrete</structfield> member is
79valid.</para>
80 </listitem>
81 <listitem>
82 <para><emphasis role="bold">Step-wise:</emphasis> The function
83returns 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
87union only the <structfield>stepwise</structfield> member is
88valid.</para>
89 </listitem>
90 <listitem>
91 <para><emphasis role="bold">Continuous:</emphasis> This is a
92special case of the step-wise type above. The function returns success
93if the given index value is zero and <constant>EINVAL</constant> for
94any 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
97the union only the <structfield>stepwise</structfield> member is valid
98and 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
104must check the <structfield>type</structfield> field to determine the
105type of frame size enumeration the device supports. Only for the
106<constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> type does it make
107sense to increase the index value to receive more frame sizes.</para>
108 <para>Note that the order in which the frame sizes are returned
109has no special meaning. In particular does it not say anything about
110potential default format sizes.</para>
111 <para>Applications can assume that the enumeration data does not
112change without any interaction from the application itself. This means
113that the enumeration data is consistent if the application does not
114perform any other ioctl calls while it runs the frame size
115enumeration.</para>
116 </refsect1>
117
118 <refsect1>
119 <title>Structs</title>
120
121 <para>In the structs below, <emphasis>IN</emphasis> denotes a
122value that has to be filled in by the application,
123<emphasis>OUT</emphasis> denotes values that the driver fills in. The
124application 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
272values that <varname>errno</varname> can have.</para>
273 </refsect1>
274</refentry>
275
276<!--
277Local Variables:
278mode: sgml
279sgml-parent-document: "v4l2.sgml"
280indent-tabs-mode: nil
281End:
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
52initialize the <structfield>index</structfield> field and zero out the
53<structfield>reserved</structfield> array of a &v4l2-audio;
54and call the <constant>VIDIOC_ENUMAUDIO</constant> ioctl with a pointer
55to 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
57inputs applications shall begin at index zero, incrementing by one
58until 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
72there are no audio inputs at all and this ioctl is not
73supported.</para>
74 </listitem>
75 </varlistentry>
76 </variablelist>
77 </refsect1>
78</refentry>
79
80<!--
81Local Variables:
82mode: sgml
83sgml-parent-document: "v4l2.sgml"
84indent-tabs-mode: nil
85End:
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
52initialize the <structfield>index</structfield> field and zero out the
53<structfield>reserved</structfield> array of a &v4l2-audioout; and
54call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
55to 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
57outputs applications shall begin at index zero, incrementing by one
58until the driver returns <errorcode>EINVAL</errorcode>.</para>
59
60 <para>Note connectors on a TV card to loop back the received audio
61signal 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
75there are no audio outputs at all and this ioctl is not
76supported.</para>
77 </listitem>
78 </varlistentry>
79 </variablelist>
80 </refsect1>
81</refentry>
82
83<!--
84Local Variables:
85mode: sgml
86sgml-parent-document: "v4l2.sgml"
87indent-tabs-mode: nil
88End:
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
53initialize the <structfield>index</structfield> field of &v4l2-input;
54and call the <constant>VIDIOC_ENUMINPUT</constant> ioctl with a
55pointer to this structure. Drivers fill the rest of the structure or
56return an &EINVAL; when the index is out of bounds. To enumerate all
57inputs applications shall begin at index zero, incrementing by one
58until 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
69application.</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
75string, for example: "Vin (Composite 2)". This information is intended
76for 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
88audio inputs. This field shows which audio inputs were selectable as
89audio source if this was the currently selected video input. It is a
90bit mask. The LSB corresponds to audio input 0, the MSB to input 31.
91Any number of bits can be set, or none.</para><para>When the driver
92does not enumerate audio inputs no bits must be set. Applications
93shall not interpret this as lack of audio support. Some drivers
94automatically select audio sources and do not enumerate them since
95there is no choice anyway.</para><para>For details on audio inputs and
96how 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
103demodulators). When the <structfield>type</structfield> is set to
104<constant>V4L2_INPUT_TYPE_TUNER</constant> this is an RF connector and
105this field identifies the tuner. It corresponds to
106&v4l2-tuner; field <structfield>index</structfield>. For details on
107tuners 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
113video standards. This field is a set of all supported standards. For
114details on video standards and how to switch see <xref
115linkend="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
121input. See <xref linkend="input-status" /> for flags.
122With the exception of the sensor orientation bits <structfield>status</structfield> is only valid when this is the
123current 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
129the 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 /
149Composite Video, S-Video, RGB.</entry>
150 </row>
151 </tbody>
152 </tgroup>
153 </table>
154
155 <!-- Status flags based on proposal by Mark McClelland,
156video4linux-list@redhat.com on 18 Oct 2002, subject "Re: [V4L] Re:
157v4l2 api". "Why are some of them inverted? So that the driver doesn't
158have to lie about the status in cases where it can't tell one way or
159the other. Plus, a status of zero would generally mean that everything
160is 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
188detect 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
197that is flipped horizontally and does not correct this before passing the
198signal 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
204that is flipped vertically and does not correct this before passing the
205signal 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
219decoding when it detects no color modulation. When this flag is set
220the color killer is enabled <emphasis>and</emphasis> has shut off
221color 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
248mangling the video signal to confuse video recorders. When this
249flag 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
274out of bounds.</para>
275 </listitem>
276 </varlistentry>
277 </variablelist>
278 </refsect1>
279</refentry>
280
281<!--
282Local Variables:
283mode: sgml
284sgml-parent-document: "v4l2.sgml"
285indent-tabs-mode: nil
286End:
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
52initialize the <structfield>index</structfield> field of &v4l2-output;
53and call the <constant>VIDIOC_ENUMOUTPUT</constant> ioctl with a
54pointer to this structure. Drivers fill the rest of the structure or
55return an &EINVAL; when the index is out of bounds. To enumerate all
56outputs applications shall begin at index zero, incrementing by one
57until 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
68application.</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
74string, for example: "Vout". This information is intended for the
75user, 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
87audio outputs. This field shows which audio outputs were
88selectable as the current output if this was the currently selected
89video output. It is a bit mask. The LSB corresponds to audio output 0,
90the MSB to output 31. Any number of bits can be set, or
91none.</para><para>When the driver does not enumerate audio outputs no
92bits must be set. Applications shall not interpret this as lack of
93audio support. Drivers may automatically select audio outputs without
94enumerating them.</para><para>For details on audio outputs and how to
95select 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.
101When the <structfield>type</structfield> is
102<constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> this is an RF
103connector and this field identifies the modulator. It corresponds to
104&v4l2-modulator; field <structfield>index</structfield>. For details
105on 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
111video standards. This field is a set of all supported standards. For
112details 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
119the 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 /
139CVBS, 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>
159is out of bounds.</para>
160 </listitem>
161 </varlistentry>
162 </variablelist>
163 </refsect1>
164</refentry>
165
166<!--
167Local Variables:
168mode: sgml
169sgml-parent-document: "v4l2.sgml"
170indent-tabs-mode: nil
171End:
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,
52especially 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
55structure. Drivers fill the rest of the structure or return an
56&EINVAL; when the index is out of bounds. To enumerate all standards
57applications shall begin at index zero, incrementing by one until the
58driver returns <errorcode>EINVAL</errorcode>. Drivers may enumerate a
59different set of standards after switching the video input or
60output.<footnote>
61 <para>The supported standards may overlap and we need an
62unambiguous 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
75application.</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
81one of the common standards listed in <xref linkend="v4l2-std-id" />,
82or if bits 32 to 63 are set as custom standards. Multiple bits can be
83set if the hardware does not distinguish between these standards,
84however 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
87output 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
93string, for example: "PAL-B/G", "NTSC Japan". This information is
94intended 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 /
10130000 seconds.</entry>
102 </row>
103 <row>
104 <entry>__u32</entry>
105 <entry><structfield>framelines</structfield></entry>
106 <entry>Total lines per frame including blanking,
107e.&nbsp;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
113the 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
147video standard as listed below and in <xref
148linkend="video-standards" />. The 32 most significant bits are reserved
149for 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
170a hybrid standard with 525 lines, 60 Hz refresh rate, and PAL color
171modulation with a 4.43 MHz color subcarrier. Some PAL video recorders
172can play back NTSC tapes in this mode for display on a 50/60 Hz agnostic
173PAL 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>
178is a hybrid standard with 525 lines, 60 Hz refresh rate, and NTSC
179color modulation with a 4.43 MHz color
180subcarrier.</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,
196video4linux-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
199TV standards. Presently the V4L2 API does not support digital TV. See
200also the Linux DVB API at <ulink
201url="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
273similar 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
277brackets apply to the combination N/PAL a.k.a.
278N<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 &plusmn;&nbsp;10</entry>
304 <entry>3579611.49 &plusmn;&nbsp;10</entry>
305 <entry>4433618.75 &plusmn;&nbsp;5 (3582056.25
306&plusmn;&nbsp;5)</entry>
307 <entry spanname="b">4433618.75 &plusmn;&nbsp;5</entry>
308 <entry>4433618.75 &plusmn;&nbsp;1</entry>
309 <entry spanname="s">f<subscript>OR</subscript>&nbsp;=
3104406250 &plusmn;&nbsp;2000, f<subscript>OB</subscript>&nbsp;= 4250000
311&plusmn;&nbsp;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>+&nbsp;4.5</entry>
332 <entry>+&nbsp;4.5</entry>
333 <entry>+&nbsp;4.5</entry>
334 <entry><para>+&nbsp;5.5 &plusmn;&nbsp;0.001
335<footnote><para>In the Federal Republic of Germany, Austria, Italy,
336the Netherlands, Slovakia and Switzerland a system of two sound
337carriers is used, the frequency of the second carrier being
338242.1875&nbsp;kHz above the frequency of the first sound carrier. For
339stereophonic sound transmissions a similar system is used in
340Australia.</para></footnote> <footnote><para>New Zealand uses a sound
341carrier displaced 5.4996 &plusmn;&nbsp;0.0005 MHz from the vision
342carrier.</para></footnote> <footnote><para>In Denmark, Finland, New
343Zealand, Sweden and Spain a system of two sound carriers is used. In
344Iceland, Norway and Poland the same system is being introduced. The
345second carrier is 5.85&nbsp;MHz above the vision carrier and is DQPSK
346modulated with 728&nbsp;kbit/s sound and data multiplex. (NICAM
347system)</para></footnote> <footnote><para>In the United Kingdom, a
348system of two sound carriers is used. The second sound carrier is
3496.552&nbsp;MHz above the vision carrier and is DQPSK modulated with a
350728&nbsp;kbit/s sound and data multiplex able to carry two sound
351channels. (NICAM system)</para></footnote></para></entry>
352 <entry>+&nbsp;6.5 &plusmn;&nbsp;0.001</entry>
353 <entry>+&nbsp;5.5</entry>
354 <entry>+&nbsp;5.9996 &plusmn;&nbsp;0.0005</entry>
355 <entry>+&nbsp;5.5 &plusmn;&nbsp;0.001</entry>
356 <entry>+&nbsp;6.5 &plusmn;&nbsp;0.001</entry>
357 <entry>+&nbsp;6.5</entry>
358 <entry><para>+&nbsp;6.5 <footnote><para>In France, a
359digital carrier 5.85 MHz away from the vision carrier may be used in
360addition to the main sound carrier. It is modulated in differentially
361encoded QPSK with a 728 kbit/s sound and data multiplexer capable of
362carrying two sound channels. (NICAM
363system)</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>
378is out of bounds.</para>
379 </listitem>
380 </varlistentry>
381 </variablelist>
382 </refsect1>
383</refentry>
384
385<!--
386Local Variables:
387mode: sgml
388sgml-parent-document: "v4l2.sgml"
389indent-tabs-mode: nil
390End:
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
11attributes</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;
63and call the <constant>VIDIOC_G_AUDIO</constant> ioctl with a pointer
64to 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
66with the current video input.</para>
67
68 <para>Audio inputs have one writable property, the audio mode. To
69select the current audio input <emphasis>and</emphasis> change the
70audio mode, applications initialize the
71<structfield>index</structfield> and <structfield>mode</structfield>
72fields, 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
76different audio mode if the request cannot be satisfied. However, this
77is a write-only ioctl, it does not return the actual new audio
78mode.</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
89driver 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
95string, for example: "Line In". This information is intended for the
96user, 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
114applications 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
129automatically disable stereo recording etc. when the signal is always
130monaural. The API provides no means to detect if stereo is
131<emphasis>received</emphasis>, unless the audio input belongs to a
132tuner.</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,
166or the number of the selected audio input is out of bounds or it does
167not combine, or there are no audio inputs at all and the ioctl is not
168supported.</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
175switched.</para>
176 </listitem>
177 </varlistentry>
178 </variablelist>
179 </refsect1>
180</refentry>
181
182<!--
183Local Variables:
184mode: sgml
185sgml-parent-document: "v4l2.sgml"
186indent-tabs-mode: nil
187End:
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
62call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
63to 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
65with the current video output.</para>
66
67 <para>Audio outputs have no writable properties. Nevertheless, to
68select the current audio output applications can initialize the
69<structfield>index</structfield> field and
70<structfield>reserved</structfield> array (which in the future may
71contain writable properties) of a
72<structname>v4l2_audioout</structname> structure and call the
73<constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the
74requested output or return the &EINVAL; when the index is out of
75bounds. This is a write-only ioctl, it does not return the current
76audio output attributes as <constant>VIDIOC_G_AUDOUT</constant>
77does.</para>
78
79 <para>Note connectors on a TV card to loop back the received audio
80signal 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
91driver 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
97string, for example: "Line Out". This information is intended for the
98user, 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
104must 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
110applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this
111field 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
117applications 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
132output, or the number of the selected audio output is out of bounds or
133it does not combine, or there are no audio outputs at all and the
134ioctl 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
141switched.</para>
142 </listitem>
143 </varlistentry>
144 </variablelist>
145 </refsect1>
146</refentry>
147
148<!--
149Local Variables:
150mode: sgml
151sgml-parent-document: "v4l2.sgml"
152indent-tabs-mode: nil
153End:
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
61applications 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
64with a pointer to this structure. The driver fills the rest of the
65structure 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
71structure.</para>
72
73 <para>The driver first adjusts the requested dimensions against
74hardware limits, &ie; the bounds given by the capture/output window,
75and it rounds to the closest possible values of horizontal and
76vertical offset, width and height. In particular the driver must round
77the vertical offset of the cropping rectangle to frame lines modulo
78two, such that the field order cannot be confused.</para>
79
80 <para>Second the driver adjusts the image size (the opposite
81rectangle of the scaling process, source or target depending on the
82data direction) to the closest size possible while maintaining the
83current horizontal and vertical scaling factor.</para>
84
85 <para>Finally the driver programs the hardware with the actual
86cropping and image parameters. <constant>VIDIOC_S_CROP</constant> is a
87write-only ioctl, it does not return the actual parameters. To query
88them applications must call <constant>VIDIOC_G_CROP</constant> and
89&VIDIOC-G-FMT;. When the parameters are unsuitable the application may
90modify the cropping or image parameters and repeat the cycle until
91satisfactory parameters have been negotiated.</para>
92
93 <para>When cropping is not supported then no parameters are
94changed 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.
106Only 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
109defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
110and 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
116for &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<!--
138Local Variables:
139mode: sgml
140sgml-parent-document: "v4l2.sgml"
141indent-tabs-mode: nil
142End:
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
54initialize 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
57structure. To change the value of a control applications initialize
58the <structfield>id</structfield> and <structfield>value</structfield>
59fields 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
63return an &EINVAL;. When the <structfield>value</structfield> is out
64of bounds drivers can choose to take the closest valid value or return
65an &ERANGE;, whatever seems more appropriate. However,
66<constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not
67return the actual new value.</para>
68
69 <para>These ioctls work only with user controls. For other
70control 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
82application.</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
102invalid.</para>
103 </listitem>
104 </varlistentry>
105 <varlistentry>
106 <term><errorcode>ERANGE</errorcode></term>
107 <listitem>
108 <para>The &v4l2-control; <structfield>value</structfield>
109is 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
116because another applications took over control of the device function
117this control belongs to.</para>
118 </listitem>
119 </varlistentry>
120 </variablelist>
121 </refsect1>
122</refentry>
123
124<!--
125Local Variables:
126mode: sgml
127sgml-parent-document: "v4l2.sgml"
128indent-tabs-mode: nil
129End:
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>
55interface and may change in the future.</para>
56 </note>
57
58 <para>The <constant>VIDIOC_G_ENC_INDEX</constant> ioctl provides
59meta data about a compressed video stream the same or another
60application currently reads from the driver, which is useful for
61random 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
67written in the <structfield>entries</structfield> field, and
68initializes the <structfield>entries_cap</structfield> field.</para>
69
70 <para>Each element of the <structfield>entry</structfield> array
71contains 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
74buffer, which can hold up to <structfield>entries_cap</structfield>
75entries. This number can be lower or higher than
76<constant>V4L2_ENC_IDX_ENTRIES</constant>, but not zero. When the
77application fails to read the meta data in time the oldest entries
78will be lost. When the buffer is empty or no capturing/encoding is in
79progress, <structfield>entries</structfield> will be zero.</para>
80
81 <para>Currently this ioctl is only defined for MPEG-2 program
82streams 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
99buffer. 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.
105Drivers 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
111element of the array corresponds to one picture, sorted in ascending
112order 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
127compressed 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
130header</wordasword> as defined in <xref linkend="mpeg2part2" />. When
131the 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
137Stamp</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.
155Drivers 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
180picture.</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
186this 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<!--
208Local Variables:
209mode: sgml
210sgml-parent-document: "v4l2.sgml"
211indent-tabs-mode: nil
212End:
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,
4VIDIOC_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
13values</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,
42VIDIOC_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
58controls atomically. Control IDs are grouped into control classes (see
59<xref linkend="ctrl-class" />) and all controls in the control array
60must 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
67initialize 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
71initialize the <structfield>id</structfield>,
72<structfield>size</structfield> and <structfield>reserved2</structfield> fields
73of each &v4l2-ext-control; and call the
74<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls
75must also set the <structfield>string</structfield> field.</para>
76
77 <para>If the <structfield>size</structfield> is too small to
78receive the control result (only relevant for pointer-type controls
79like strings), then the driver will set <structfield>size</structfield>
80to a valid value and return an &ENOSPC;. You should re-allocate the
81string memory to this new size and try again. It is possible that the
82same issue occurs again if the string has grown in the meantime. It is
83recommended to call &VIDIOC-QUERYCTRL; first and use
84<structfield>maximum</structfield>+1 as the new <structfield>size</structfield>
85value. It is guaranteed that that is sufficient memory.
86</para>
87
88 <para>To change the value of a set of controls applications
89initialize the <structfield>id</structfield>, <structfield>size</structfield>,
90<structfield>reserved2</structfield> and
91<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
92call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls
93will only be set if <emphasis>all</emphasis> control values are
94valid.</para>
95
96 <para>To check if a set of controls have correct values applications
97initialize the <structfield>id</structfield>, <structfield>size</structfield>,
98<structfield>reserved2</structfield> and
99<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
100call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to
101the driver whether wrong values are automatically adjusted to a valid
102value 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
107the closest valid value or return an &ERANGE;, whatever seems more
108appropriate. 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
112values are correct. This prevents the situation where only some of the
113controls were set/get. Only low-level errors (&eg; a failed i2c
114command) 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
126application.</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
133control. This is normally 0, but for pointer controls this should be
134set to the size of the memory containing the payload, or that will
135receive the payload. If <constant>VIDIOC_G_EXT_CTRLS</constant> finds
136that this value is less than is required to store
137the payload result, then it is set to a value large enough to store the
138payload result and ENOSPC is returned. Note that for string controls
139this <structfield>size</structfield> field should not be confused with the length of the string.
140This field refers to the size of the memory that contains the string.
141The 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
149applications 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
192also 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
198index of the control causing the error or equal to 'count' when the
199error is not associated with a particular control. Undefined when the
200ioctl 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
206applications 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
213if <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
228are described in <xref linkend="control" />. All controls that can be set
229using the &VIDIOC-S-CTRL; and &VIDIOC-G-CTRL; ioctl belong to this
230class.</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.
236These 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.
243These 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.
250These 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>
267is invalid or the &v4l2-ext-controls;
268<structfield>ctrl_class</structfield> is invalid. This error code is
269also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and
270<constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctls if two or more
271control 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>
278is 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
285because another applications took over control of the device function
286this 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.
293The field <structfield>size</structfield> is set to a value that is enough
294to store the payload and this error code is returned.</para>
295 </listitem>
296 </varlistentry>
297 </variablelist>
298 </refsect1>
299</refentry>
300
301<!--
302Local Variables:
303mode: sgml
304sgml-parent-document: "v4l2.sgml"
305indent-tabs-mode: nil
306End:
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
62framebuffer parameters for a <link linkend="overlay">Video
63Overlay</link> or <link linkend="osd">Video Output Overlay</link>
64(OSD). The type of overlay is implied by the device type (capture or
65output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl.
66One <filename>/dev/videoN</filename> device must not support both
67kinds of overlay.</para>
68
69 <para>The V4L2 API distinguishes destructive and non-destructive
70overlays. A destructive overlay copies captured video images into the
71video memory of a graphics card. A non-destructive overlay blends
72video images into a VGA signal or graphics into a video signal.
73<wordasword>Video Output Overlays</wordasword> are always
74non-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
79all fields of the structure or returns an &EINVAL; when overlays are
80not supported.</para>
81
82 <para>To set the parameters for a <wordasword>Video Output
83Overlay</wordasword>, applications must initialize the
84<structfield>flags</structfield> field of a struct
85<structname>v4l2_framebuffer</structname>. Since the framebuffer is
86implemented on the TV card all other parameters are determined by the
87driver. When an application calls <constant>VIDIOC_S_FBUF</constant>
88with a pointer to this structure, the driver prepares for the overlay
89and returns the framebuffer parameters as
90<constant>VIDIOC_G_FBUF</constant> does, or it returns an error
91code.</para>
92
93 <para>To set the parameters for a <wordasword>non-destructive
94Video 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
98overlay and returns the framebuffer parameters as
99<constant>VIDIOC_G_FBUF</constant> does, or it returns an error
100code.</para>
101
102 <para>For a <wordasword>destructive Video Overlay</wordasword>
103applications must additionally provide a
104<structfield>base</structfield> address. Setting up a DMA to a
105random memory location can jeopardize the system security, its
106stability or even damage the hardware, therefore only the superuser
107can 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
128driver, 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,
135that is the address of the pixel in the top left corner of the
136framebuffer.<footnote><para>A physical base address may not suit all
137platforms. GK notes in theory we should pass something like PCI device
138+ memory region + offset instead. If you encounter problems please
139discuss 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
148provide a base address. The driver may accept only base addresses
149which are a multiple of two, four or eight bytes. For
150<wordasword>Video Output Overlays</wordasword> the driver must return
151a valid base address, so applications can find the corresponding Linux
152framebuffer 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
160linkend="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
180framebuffer.</entry>
181 </row>
182 <row>
183 <entry></entry>
184 <entry></entry>
185 <entry></entry>
186 <entry>For <wordasword>non-destructive Video
187Overlays</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
195Overlays</wordasword> applications must initialize this field. For
196<wordasword>Video Output Overlays</wordasword> the driver must return
197a 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>)
205but YUV formats (only packed YUV formats when chroma keying is used,
206not 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
209behavior of the driver when an application requests a compressed
210format is undefined. See <xref linkend="pixfmt" /> for information on
211pixel 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.
218If applicable, the field order is selected with the &VIDIOC-S-FMT;
219ioctl, 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
227two adjacent lines.</entry>
228 </row>
229 <row>
230 <entry spanname="hspan"><para>This field is irrelevant to
231<wordasword>non-destructive Video
232Overlays</wordasword>.</para><para>For <wordasword>destructive Video
233Overlays</wordasword> both applications and drivers can set this field
234to request padding bytes at the end of each line. Drivers however may
235ignore the requested value, returning <structfield>width</structfield>
236times bytes-per-pixel or a larger value required by the hardware. That
237implies applications can just set this field to zero to get a
238reasonable default.</para><para>For <wordasword>Video Output
239Overlays</wordasword> the driver must return a valid
240value.</para><para>Video hardware may access padding bytes, therefore
241they must reside in accessible memory. Consider for example the case
242where padding bytes after the last line of an image cross a system
243page boundary. Capture devices may write padding bytes, the value is
244undefined. Output devices ignore the contents of padding
245bytes.</para><para>When the image format is planar the
246<structfield>bytesperline</structfield> value applies to the largest
247plane and is divided by the same factor as the
248<structfield>width</structfield> field for any smaller planes. For
249example the Cb and Cr planes of a YUV 4:2:0 image have half as many
250padding bytes following each line as the Y plane. To avoid ambiguities
251drivers must return a <structfield>bytesperline</structfield> value
252rounded 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
261initialize this field. For <wordasword>Video Output
262Overlays</wordasword> the driver must return a valid
263format.</para><para>Together with <structfield>base</structfield> it
264defines the framebuffer memory accessible by the
265driver.</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,
273see <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
281set 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.
296When the driver clears this flag, only destructive overlays are
297supported. There are no drivers yet which support both destructive and
298non-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
304images. That is, image pixels replace pixels in the VGA or video
305signal only where the latter assume a certain color. Chroma-keying
306makes 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
312rectangles.</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
323alpha channel of the framebuffer or VGA signal. Alpha blending makes
324no 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
330alpha 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
336inverted alpha channel of the framebuffer or VGA signal. Alpha
337blending 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.
352In 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
358size 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.
364Most 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
372determined by the <structfield>chromakey</structfield> field of
373&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
374 linkend="overlay" />
375and
376 <xref linkend="osd" />.</entry>
377 </row>
378 <row>
379 <entry spanname="hspan">There are no flags to enable
380clipping using a list of clip rectangles or a bitmap. These methods
381are 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
388blend framebuffer pixels with video images. The blend
389function is: output = framebuffer pixel * alpha + video pixel * (1 -
390alpha). The actual alpha depth depends on the framebuffer pixel
391format.</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
397with video images. The blend function is: output = (framebuffer pixel
398* alpha + video pixel * (255 - alpha)) / 255. The alpha value is
399determined by the <structfield>global_alpha</structfield> field of
400&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
401 linkend="overlay" />
402and <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
409of the framebuffer to clip or blend framebuffer pixels with video
410images, but with an inverted alpha value. The blend function is:
411output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The
412actual 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
427by a privileged user to negotiate the parameters for a destructive
428overlay.</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
435time because overlay is already enabled, or capturing is enabled
436and 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<!--
451Local Variables:
452mode: sgml
453sgml-parent-document: "v4l2.sgml"
454indent-tabs-mode: nil
455End:
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,
4VIDIOC_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
57application.</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)
62type. For example video capture devices use
63<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. When the application
64calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
65this structure the driver fills the respective member of the
66<structfield>fmt</structfield> union. In case of video capture devices
67that is the &v4l2-pix-format; <structfield>pix</structfield> member.
68When the requested buffer type is not supported drivers return an
69&EINVAL;.</para>
70
71 <para>To change the current format parameters applications
72initialize the <structfield>type</structfield> field and all
73fields of the respective <structfield>fmt</structfield>
74union member. For details see the documentation of the various devices
75types in <xref linkend="devices" />. Good practice is to query the
76current parameters first, and to
77modify only those parameters not suitable for the application. When
78the application calls the <constant>VIDIOC_S_FMT</constant> ioctl
79with a pointer to a <structname>v4l2_format</structname> structure
80the driver checks
81and adjusts the parameters against hardware abilities. Drivers
82should not return an error code unless the input is ambiguous, this is
83a mechanism to fathom device capabilities and to approach parameters
84acceptable for both the application and driver. On success the driver
85may program the hardware, allocate resources and generally prepare for
86data exchange.
87Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the
88current format parameters as <constant>VIDIOC_G_FMT</constant> does.
89Very simple, inflexible devices may even ignore all input and always
90return the default parameters. However all V4L2 devices exchanging
91data with the application must implement the
92<constant>VIDIOC_G_FMT</constant> and
93<constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer
94type is not supported drivers return an &EINVAL; on a
95<constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in
96progress or the resource is not available for other reasons drivers
97return the &EBUSY;.</para>
98
99 <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent
100to <constant>VIDIOC_S_FMT</constant> with one exception: it does not
101change driver state. It can also be called at any time, never
102returning <errorcode>EBUSY</errorcode>. This function is provided to
103negotiate parameters, to learn about hardware limitations, without
104disabling I/O or possibly time consuming hardware preparations.
105Although strongly recommended drivers are not required to implement
106this 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
133devices.</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
147discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI
148capture 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
156capture 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
179time, 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>
186field is invalid, the requested buffer type not supported, or
187<constant>VIDIOC_TRY_FMT</constant> was called and is not
188supported with this buffer type.</para>
189 </listitem>
190 </varlistentry>
191 </variablelist>
192 </refsect1>
193</refentry>
194
195<!--
196Local Variables:
197mode: sgml
198sgml-parent-document: "v4l2.sgml"
199indent-tabs-mode: nil
200End:
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
11frequency</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
64applications set the <structfield>tuner</structfield> field of a
65&v4l2-frequency; to the respective tuner or modulator number (only
66input devices have tuners, only output devices have modulators), zero
67out the <structfield>reserved</structfield> array and
68call the <constant>VIDIOC_G_FREQUENCY</constant> ioctl with a pointer
69to 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
73applications 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
77call the <constant>VIDIOC_S_FREQUENCY</constant> ioctl with a pointer
78to this structure. When the requested frequency is not possible the
79driver assumes the closest possible value. However
80<constant>VIDIOC_S_FREQUENCY</constant> is a write-only ioctl, it does
81not 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
92same value as in the &v4l2-input; <structfield>tuner</structfield>
93field and the &v4l2-tuner; <structfield>index</structfield> field, or
94the &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
102applicable 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
110Hz.</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
131bounds or the value in the <structfield>type</structfield> field is
132wrong.</para>
133 </listitem>
134 </varlistentry>
135 </variablelist>
136 </refsect1>
137</refentry>
138
139<!--
140Local Variables:
141mode: sgml
142sgml-parent-document: "v4l2.sgml"
143indent-tabs-mode: nil
144End:
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
54where the driver stores the number of the input, as in the
55&v4l2-input; <structfield>index</structfield> field. This ioctl will
56fail 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
60desired input in an integer and call the
61<constant>VIDIOC_S_INPUT</constant> ioctl with a pointer to this
62integer. Side effects are possible. For example inputs may support
63different video standards, so the driver may implicitly switch the
64current standard. It is good practice to select an input before
65querying 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
79there are no video inputs at all and this ioctl is not
80supported.</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
87switched.</para>
88 </listitem>
89 </varlistentry>
90 </variablelist>
91 </refsect1>
92</refentry>
93
94<!--
95Local Variables:
96mode: sgml
97sgml-parent-document: "v4l2.sgml"
98indent-tabs-mode: nil
99End:
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
68application can set it itself, and it'll be stored in the JPEG-encoded
69fields (eg; interlacing information for in an AVI or so). COM is the
70same, but it's comments, like 'encoded by me' or so.</para>
71
72 <para>jpeg_markers describes whether the huffman tables,
73quantization tables and the restart interval information (all
74JPEG-specific stuff) should be stored in the JPEG-encoded fields.
75These define how the JPEG field is encoded. If you omit them,
76applications assume you've used standard encoding. You usually do want
77to 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&lt;&lt;3)</entry>
133 <entry>Define Huffman Tables</entry>
134 </row>
135 <row>
136 <entry><constant>V4L2_JPEG_MARKER_DQT</constant></entry>
137 <entry>(1&lt;&lt;4)</entry>
138 <entry>Define Quantization Tables</entry>
139 </row>
140 <row>
141 <entry><constant>V4L2_JPEG_MARKER_DRI</constant></entry>
142 <entry>(1&lt;&lt;5)</entry>
143 <entry>Define Restart Interval</entry>
144 </row>
145 <row>
146 <entry><constant>V4L2_JPEG_MARKER_COM</constant></entry>
147 <entry>(1&lt;&lt;6)</entry>
148 <entry>Comment segment</entry>
149 </row>
150 <row>
151 <entry><constant>V4L2_JPEG_MARKER_APP</constant></entry>
152 <entry>(1&lt;&lt;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<!--
175Local Variables:
176mode: sgml
177sgml-parent-document: "v4l2.sgml"
178indent-tabs-mode: nil
179End:
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
63the <structfield>index</structfield> field and zero out the
64<structfield>reserved</structfield> array of a &v4l2-modulator; and
65call the <constant>VIDIOC_G_MODULATOR</constant> ioctl with a pointer
66to 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
68applications shall begin at index zero, incrementing by one until the
69driver returns <errorcode>EINVAL</errorcode>.</para>
70
71 <para>Modulators have two writable properties, an audio
72modulation set and the radio frequency. To change the modulated audio
73subprograms, 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
77different audio modulation if the request cannot be satisfied. However
78this is a write-only ioctl, it does not return the actual audio
79modulation selected.</para>
80
81 <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl
82is 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
93application.</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
99string. 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
105for this field, the tuner flags in &v4l2-tuner;
106are used accordingly. The audio flags indicate the ability
107to encode audio subprograms. They will <emphasis>not</emphasis>
108change 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
114KHz, or if the <structfield>capability</structfield> flag
115<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
116Hz.</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
122KHz, or if the <structfield>capability</structfield> flag
123<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
124Hz.</entry>
125 </row>
126 <row>
127 <entry>__u32</entry>
128 <entry><structfield>txsubchans</structfield></entry>
129 <entry>With this field applications can determine how
130audio sub-carriers shall be modulated. It contains a set of flags as
131defined in <xref linkend="modulator-txsubchans" />. Note the tuner
132<structfield>rxsubchans</structfield> flags are reused, but the
133semantics are different. Video output devices are assumed to have an
134analog or PCM audio input with 1-3 channels. The
135<structfield>txsubchans</structfield> flags select one or more
136channels for modulation, together with some audio subprogram
137indicator, 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
143applications 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
158has more channels, a down-mix of channel 1 and 2. This flag does not
159combine 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
166channel of a stereo audio signal. When the input has only one channel
167or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also
168set, channel 1 is encoded as left and right channel. This flag does
169not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or
170<constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not
171support 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
177language of a bilingual audio signal. When the input has only one
178channel it is used for both languages. It is not possible to encode
179the primary or secondary language only. This flag does not combine
180with <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
183support the respective audio matrix, or the current video standard
184does not permit bilingual audio the
185<constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL;
186and 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
199channel as Second Audio Program. When the input has only one channel
200it is used for both audio tracks. When the input has three channels
201the 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
203encoded as left and right stereo audio, channel 3 as Second Audio
204Program. When the input has only two channels, the first is encoded as
205left and right channel and the second as SAP. When the input has only
206one channel it is used for all audio tracks. It is not possible to
207encode 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
210support the respective audio matrix, or the current video standard
211does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl
212shall return an &EINVAL; and driver shall fall back to mono or stereo
213mode.</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<!--
241Local Variables:
242mode: sgml
243sgml-parent-document: "v4l2.sgml"
244indent-tabs-mode: nil
245End:
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
54where the driver stores the number of the output, as in the
55&v4l2-output; <structfield>index</structfield> field. This ioctl
56will 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
60desired output in an integer and call the
61<constant>VIDIOC_S_OUTPUT</constant> ioctl with a pointer to this integer.
62Side effects are possible. For example outputs may support different
63video standards, so the driver may implicitly switch the current
64standard. It is good practice to select an output before querying or
65negotiating 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
79there are no video outputs at all and this ioctl is not
80supported.</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
87switched.</para>
88 </listitem>
89 </varlistentry>
90 </variablelist>
91 </refsect1>
92</refentry>
93
94<!--
95Local Variables:
96mode: sgml
97sgml-parent-document: "v4l2.sgml"
98indent-tabs-mode: nil
99End:
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
53frames per second. If less than this number of frames is to be
54captured or output, applications can request frame skipping or
55duplicating on the driver side. This is especially useful when using
56the <function>read()</function> or <function>write()</function>, which
57are not augmented by timestamps or sequence counters, and to avoid
58unneccessary data copying.</para>
59
60 <para>Further these ioctls can be used to determine the number of
61buffers used internally by a driver in read/write mode. For
62implications see the section discussing the &func-read;
63function.</para>
64
65 <para>To get and set the streaming parameters applications call
66the <constant>VIDIOC_G_PARM</constant> and
67<constant>VIDIOC_S_PARM</constant> ioctl, respectively. They take a
68pointer to a struct <structname>v4l2_streamparm</structname> which
69contains a union holding separate parameters for input and output
70devices.</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
112higher.</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
137successive frames captured by the driver, in seconds. The
138field is intended to skip frames on the driver side, saving I/O
139bandwidth.</para><para>Applications store here the desired frame
140period, drivers return the actual frame period, which must be greater
141or equal to the nominal frame period determined by the current video
142standard (&v4l2-standard; <structfield>frameperiod</structfield>
143field). Changing the video standard (also implicitly by switching the
144video input) may reset this parameter to the nominal frame period. To
145reset manually applications can just set this field to
146zero.</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
154unused, applications and drivers must set this field to zero.
155Applications using this field should check the driver name and
156version, 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
162of buffers used internally by the driver in &func-read; mode. Drivers
163return the actual number of buffers. When an application requests zero
164buffers, drivers should just return the current setting rather than
165the 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
172applications 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
198successive frames output by the driver, in seconds.</entry>
199 </row>
200 <row>
201 <entry spanname="hspan"><para>The field is intended to
202repeat frames on the driver side in &func-write; mode (in streaming
203mode timestamps can be used to throttle the output), saving I/O
204bandwidth.</para><para>Applications store here the desired frame
205period, drivers return the actual frame period, which must be greater
206or equal to the nominal frame period determined by the current video
207standard (&v4l2-standard; <structfield>frameperiod</structfield>
208field). Changing the video standard (also implicitly by switching the
209video output) may reset this parameter to the nominal frame period. To
210reset manually applications can just set this field to
211zero.</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
219unused, applications and drivers must set this field to zero.
220Applications using this field should check the driver name and
221version, 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
227of buffers used internally by the driver in
228<function>write()</function> mode. Drivers return the actual number of
229buffers. When an application requests zero buffers, drivers should
230just return the current setting rather than the minimum or an error
231code. 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
237applications 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
267is intended for still imaging applications. The idea is to get the
268best possible image quality that the hardware can deliver. It is not
269defined how the driver writer may achieve that; it will depend on the
270hardware and the ingenuity of the driver writer. High quality mode is
271a different mode from the the regular motion video capture modes. In
272high quality mode:<itemizedlist>
273 <listitem>
274 <para>The driver may be able to capture higher
275resolutions than for motion capture.</para>
276 </listitem>
277 <listitem>
278 <para>The driver may support fewer pixel formats
279than motion capture (eg; true color).</para>
280 </listitem>
281 <listitem>
282 <para>The driver may capture and arithmetically
283combine multiple successive fields or frames to remove color edge
284artifacts and reduce the noise in the video data.
285</para>
286 </listitem>
287 <listitem>
288 <para>The driver may capture images in slices like
289a scanner in order to handle larger format images than would otherwise
290be possible. </para>
291 </listitem>
292 <listitem>
293 <para>An image capture operation may be
294significantly slower than motion capture. </para>
295 </listitem>
296 <listitem>
297 <para>Moving objects in the image might have
298excessive 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<!--
327Local Variables:
328mode: sgml
329sgml-parent-document: "v4l2.sgml"
330indent-tabs-mode: nil
331End:
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
11file 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
62applications call the <constant>VIDIOC_G_PRIORITY</constant> ioctl
63with a pointer to an enum v4l2_priority variable where the driver stores
64the current priority.</para>
65
66 <para>To request an access priority applications store the
67desired priority in an enum v4l2_priority variable and call
68<constant>VIDIOC_S_PRIORITY</constant> ioctl with a pointer to this
69variable.</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
85background, for example monitoring VBI transmissions. A proxy
86application running in user space will be necessary if multiple
87applications 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
98interactively controlled by the user. For example TV viewers, Teletext
99browsers, or just "panel" applications to change the channel or video
100controls. This is the default priority unless an application requests
101another.</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
107this priority, it blocks any other fd from changing device properties.
108Usually applications which must not be interrupted, like video
109recording.</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
124driver 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
131priority.</para>
132 </listitem>
133 </varlistentry>
134 </variablelist>
135 </refsect1>
136</refentry>
137
138<!--
139Local Variables:
140mode: sgml
141sgml-parent-document: "v4l2.sgml"
142indent-tabs-mode: nil
143End:
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
52VBI capture or output device, applications initialize the
53<structfield>type</structfield> field of a &v4l2-sliced-vbi-cap;,
54clear the <structfield>reserved</structfield> array and
55call the <constant>VIDIOC_G_SLICED_VBI_CAP</constant> ioctl. The
56driver fills in the remaining fields or returns an &EINVAL; if the
57sliced VBI API is unsupported or <structfield>type</structfield>
58is invalid.</para>
59
60 <para>Note the <structfield>type</structfield> field was added,
61and 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
77supported 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
84contains a set of data services the hardware can look for or insert
85into a particular scan line. Data services are defined in <xref
86 linkend="vbi-services" />. Array indices map to ITU-R
87line numbers (see also <xref
88 linkend="vbi-525" /> and <xref
89linkend="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
133hardware can capture or output per frame, or the number of services it
134can identify on a given line may be limited. For example on PAL line
13516 the hardware may be able to look for a VPS or Teletext signal, but
136not both at the same time. Applications can learn about these limits
137using 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
162extensions. 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
190System 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
195without 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
203ETS&nbsp;300&nbsp;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
211bit, 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>
219Byte 0 1
220 msb lsb msb lsb
221Bit 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
228line 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
234line 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
250output, or the value in the <structfield>type</structfield> field is
251wrong.</para>
252 </listitem>
253 </varlistentry>
254 </variablelist>
255 </refsect1>
256</refentry>
257
258<!--
259Local Variables:
260mode: sgml
261sgml-parent-document: "v4l2.sgml"
262indent-tabs-mode: nil
263End:
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
63use 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
65return a single flag or a set of flags as in &v4l2-standard; field
66<structfield>id</structfield>. The flags must be unambiguous such
67that they appear in only one enumerated <structname>v4l2_standard</structname> structure.</para>
68
69 <para><constant>VIDIOC_S_STD</constant> accepts one or more
70flags, 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
72the current input does not support the requested standard the driver
73returns an &EINVAL;. When the standard set is ambiguous drivers may
74return <errorcode>EINVAL</errorcode> or choose any of the requested
75standards.</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<!--
94Local Variables:
95mode: sgml
96sgml-parent-document: "v4l2.sgml"
97indent-tabs-mode: nil
98End:
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
66structure. Drivers fill the rest of the structure or return an
67&EINVAL; when the index is out of bounds. To enumerate all tuners
68applications shall begin at index zero, incrementing by one until the
69driver returns <errorcode>EINVAL</errorcode>.</para>
70
71 <para>Tuners have two writable properties, the audio mode and
72the radio frequency. To change the audio mode, applications initialize
73the <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
78by the current video input. Drivers may choose a different audio mode
79if the requested mode is invalid or unsupported. Since this is a
80<!-- FIXME -->write-only ioctl, it does not return the actually
81selected audio mode.</para>
82
83 <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl
84is 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
99application.</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
105NUL-terminated ASCII string. This information is intended for the
106user.<!-- FIXME Video inputs already have a name, the purpose of this
107field 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
120to decode audio subprograms. They will <emphasis>not</emphasis>
121change, for example with the current video standard.</para><para>When
122the 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
131units of 62.5 kHz, or if the <structfield>capability</structfield>
132flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
133Hz.</entry>
134 </row>
135 <row>
136 <entry>__u32</entry>
137 <entry><structfield>rangehigh</structfield></entry>
138 <entry spanname="hspan">The highest tunable frequency in
139units of 62.5 kHz, or if the <structfield>capability</structfield>
140flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
141Hz.</entry>
142 </row>
143 <row>
144 <entry>__u32</entry>
145 <entry><structfield>rxsubchans</structfield></entry>
146 <entry spanname="hspan"><para>Some tuners or audio
147decoders can determine the received audio subprograms by analyzing
148audio carriers, pilot tones or other indicators. To pass this
149information drivers set flags defined in <xref
150 linkend="tuner-rxsubchans" /> in this field. For
151example:</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
164program</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
171distinguish</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
184audio</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
195here.</para><para>This field is valid only if this is the tuner of the
196current video input, or when the structure refers to a radio
197tuner.</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
204not affect audio subprogram detection, and like a <link
205linkend="control">control</link> it does not automatically change
206unless the requested mode is invalid or unsupported. See <xref
207 linkend="tuner-matrix" /> for possible results when
208the selected and received audio programs do not
209match.</para><para>Currently this is the only field of struct
210<structname>v4l2_tuner</structname> applications can
211change.</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
217from 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
224low, when positive too high.<!-- FIXME need example what to do when it never
225settles 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
231applications 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
26562.5&nbsp;Hz, otherwise in units of 62.5&nbsp;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
271can 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
287audio program is supported. Bilingual audio is a feature of
288two-channel systems, transmitting the primary language monaural on the
289main audio carrier and a secondary language monaural on a second
290carrier. 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
297audio 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
304supported. This is a feature of the BTSC system which accompanies the
305NTSC video standard. Two audio carriers are available for mono or
306stereo transmissions of a primary language, and an independent third
307carrier 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
312supports the <constant>V4L2_STD_NTSC_M</constant> video
313standard.</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
319radio 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
344bilingual audio signal. Drivers must clear this flag when the current
345video 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
351bilingual 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
360current 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
380signal this a down-mix of the left and right channel. When the tuner
381receives a bilingual or SAP signal this mode selects the primary
382language.</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
388bilingual audio it may play different languages on the left and right
389channel or the primary language is played on both channels.</para><para>Playing
390different languages in this mode is
391deprecated. New drivers should do this only in
392<constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner
393receives no stereo signal or does not support stereo reception the
394driver 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
401mode.</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
407receives no bilingual audio or SAP, or their reception is not
408supported the driver shall fall back to mono or stereo mode. Only
409<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
410mode.</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
416receives no bilingual audio or SAP, or their reception is not
417supported the driver shall fall back to mono or stereo mode. Only
418<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode.
419Note 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
426secondary language on the right channel. When the tuner receives no
427bilingual audio or SAP, it shall fall back to
428<constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>.
429Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
430mode.</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
458mode has been added in Linux 2.6.17 and may not be supported by older
459drivers.</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&nbsp;1</entry>
498 <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of
499both languages in <constant>MODE_STEREO</constant> is deprecated. In
500the future drivers should produce only the primary language in this
501mode. Applications should request
502<constant>MODE_LANG1_LANG2</constant> to record both languages or a
503stereo signal.</para></footnote>) or
504Lang1/Lang1</entry>
505 <entry>Language&nbsp;1</entry>
506 <entry>Language&nbsp;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
522out of bounds.</para>
523 </listitem>
524 </varlistentry>
525 </variablelist>
526 </refsect1>
527</refentry>
528
529<!--
530Local Variables:
531mode: sgml
532sgml-parent-document: "v4l2.sgml"
533indent-tabs-mode: nil
534End:
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
26becomes harder to debug problems. When this ioctl is called the driver
27will output the current device status to the kernel log. This is
28particular useful when dealing with problems like no sound, no video
29and incorrectly tuned channels. Also many modern devices autodetect
30video and audio standards and this ioctl will report what the device
31thinks what the standard is. Mismatches may give an indication where
32the problem is.</para>
33
34 <para>This ioctl is optional and not all drivers support it. It
35was 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<!--
53Local Variables:
54mode: sgml
55sgml-parent-document: "v4l2.sgml"
56indent-tabs-mode: nil
57End:
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
69parameters have not been set up. See <xref
70linkend="overlay" /> for the necessary steps.</para>
71 </listitem>
72 </varlistentry>
73 </variablelist>
74 </refsect1>
75</refentry>
76
77<!--
78Local Variables:
79mode: sgml
80sgml-parent-document: "v4l2.sgml"
81indent-tabs-mode: nil
82End:
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
53to enqueue an empty (capturing) or filled (output) buffer in the
54driver's incoming queue. The semantics depend on the selected I/O
55method.</para>
56
57 <para>To enqueue a <link linkend="mmap">memory mapped</link>
58buffer 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>
62field to <constant>V4L2_MEMORY_MMAP</constant> and the
63<structfield>index</structfield> field. Valid index numbers range from
64zero to the number of buffers allocated with &VIDIOC-REQBUFS;
65(&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The
66contents of the struct <structname>v4l2_buffer</structname> returned
67by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is
68intended 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
71initialize 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
76structure 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>
84buffer 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>
88field to <constant>V4L2_MEMORY_USERPTR</constant> and the
89<structfield>m.userptr</structfield> field to the address of the
90buffer and <structfield>length</structfield> to its size. When the
91buffer is intended for output additional fields must be set as above.
92When <constant>VIDIOC_QBUF</constant> is called with a pointer to this
93structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant>
94flag 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.
97This ioctl locks the memory pages of the buffer in physical memory,
98they cannot be swapped out to disk. Buffers remain locked until
99dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl are
100called, or until the device is closed.</para>
101
102 <para>Applications call the <constant>VIDIOC_DQBUF</constant>
103ioctl to dequeue a filled (capturing) or displayed (output) buffer
104from the driver's outgoing queue. They just set the
105<structfield>type</structfield> and <structfield>memory</structfield>
106fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
107is called with a pointer to this structure the driver fills the
108remaining fields or returns an error code.</para>
109
110 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
111buffer is in the outgoing queue. When the
112<constant>O_NONBLOCK</constant> flag was given to the &func-open;
113function, <constant>VIDIOC_DQBUF</constant> returns immediately
114with an &EAGAIN; when no buffer is available.</para>
115
116 <para>The <structname>v4l2_buffer</structname> structure is
117specified 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
129queue.</para>
130 </listitem>
131 </varlistentry>
132 <varlistentry>
133 <term><errorcode>EINVAL</errorcode></term>
134 <listitem>
135 <para>The buffer <structfield>type</structfield> is not
136supported, or the <structfield>index</structfield> is out of bounds,
137or 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
146enqueue 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
153internal error. Can also indicate temporary problems like signal
154loss. Note the driver might dequeue an (empty) buffer despite
155returning an error, or even stop capturing.</para>
156 </listitem>
157 </varlistentry>
158 </variablelist>
159 </refsect1>
160</refentry>
161
162<!--
163Local Variables:
164mode: sgml
165sgml-parent-document: "v4l2.sgml"
166indent-tabs-mode: nil
167End:
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
52mapping</link> I/O method. It can be used to query the status of a
53buffer 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
61to the number of buffers allocated with &VIDIOC-REQBUFS;
62 (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.
63After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to
64 this structure drivers return an error code or fill the rest of
65the 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>
73contains the offset of the buffer from the start of the device memory,
74the <structfield>length</structfield> field its size. The driver may
75or may not set the remaining fields and flags, they are meaningless in
76this 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
90supported, or the <structfield>index</structfield> is out of bounds.</para>
91 </listitem>
92 </varlistentry>
93 </variablelist>
94 </refsect1>
95</refentry>
96
97<!--
98Local Variables:
99mode: sgml
100sgml-parent-document: "v4l2.sgml"
101indent-tabs-mode: nil
102End:
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
53kernel devices compatible with this specification and to obtain
54information about driver and hardware capabilities. The ioctl takes a
55pointer to a &v4l2-capability; which is filled by the driver. When the
56driver 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
68ASCII string. For example: "bttv". Driver specific applications can
69use this information to verify the driver identity. It is also useful
70to work around known bugs, or to identify drivers in error reports.
71The driver version is stored in the <structfield>version</structfield>
72field.</para><para>Storing strings in fixed sized arrays is bad
73practice but unavoidable here. Drivers and applications should take
74precautions to never read or write beyond the end of the array and to
75make 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.
81For example: "Yoyodyne TV/FM". One driver may support different brands
82or models of video hardware. This information is intended for users,
83for example in a menu of available devices. Since multiple TV cards of
84the same brand may be installed which are supported by the same
85driver, this name should be combined with the character device file
86name (&eg; <filename>/dev/video2</filename>) or the
87<structfield>bus_info</structfield> string to avoid
88ambiguities.</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
94NUL-terminated ASCII string. For example: "PCI Slot 4". This
95information is intended for users, to distinguish multiple
96identical devices. If no such information is available the field may
97simply count the devices controlled by the driver, or contain the
98empty 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
104the <structfield>driver</structfield> field this identifies a
105particular 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) &lt;&lt; 16) + ((b) &lt;&lt; 8) + (c))
112
113__u32 version = KERNEL_VERSION(0, 8, 1);
114
115printf ("Version: %u.%u.%u\n",
116 (version &gt;&gt; 16) &amp; 0xFF,
117 (version &gt;&gt; 8) &amp; 0xFF,
118 version &amp; 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
131this 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
146linkend="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
152linkend="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
158linkend="overlay">Video Overlay</link> interface. A video overlay device
159typically stores captured images directly in the video memory of a
160graphics 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
166VBI Capture</link> interface, providing Teletext and Closed Caption
167data.</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
193Output Overlay</link> (OSD) interface. Unlike the <wordasword>Video
194Overlay</wordasword> interface, this is a secondary function of video
195output devices and overlays an image onto an outgoing video signal.
196When the driver sets this flag, it must clear the
197<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag and vice
198versa.<footnote><para>The &v4l2-framebuffer; lacks an
199&v4l2-buf-type; field, therefore the type of overlay is implied by the
200driver 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
206hardware 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
212receive RF-modulated video signals. For more information about
213tuner 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
220may not support audio recording or playback, in PCM or compressed
221formats. PCM audio support must be implemented as ALSA or OSS
222interface. 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
234emit RF-modulated video/audio signals. For more information about
235modulator 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
242linkend="rw">read()</link> and/or <link linkend="rw">write()</link>
243I/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
249linkend="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
255linkend="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
270specification.</para>
271 </listitem>
272 </varlistentry>
273 </variablelist>
274 </refsect1>
275</refentry>
276
277<!--
278Local Variables:
279mode: sgml
280sgml-parent-document: "v4l2.sgml"
281indent-tabs-mode: nil
282End:
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
63structure. 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
72supported. Further applications can enumerate private controls, which
73are 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
81disabled and should be ignored by the application.<footnote>
82 <para><constant>V4L2_CTRL_FLAG_DISABLED</constant> was
83intended for two purposes: Drivers can skip predefined controls not
84supported by the hardware (although returning EINVAL would do as
85well), or disable predefined and private controls after hardware
86detection without the trouble of reordering control arrays and indices
87(EINVAL cannot be used to skip private controls because it would
88prematurely 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
92next supported control, or <errorcode>EINVAL</errorcode> if there is
93none. 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
97names of the menu items. To query them applications set the
98<structfield>id</structfield> and <structfield>index</structfield>
99fields of &v4l2-querymenu; and call the
100<constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this
101structure. 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
104by 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
121with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns
122the first control with a higher ID. Drivers which do not support this
123flag 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
135string. 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
141bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the
142lowest valid index (always 0) for <constant>V4L2_CTRL_TYPE_MENU</constant> controls.
143For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value
144gives the minimum length of the string. This length <emphasis>does not include the terminating
145zero</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
147signed 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
153bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the
154highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant>
155controls.
156For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value
157gives the maximum length of the string. This length <emphasis>does not include the terminating
158zero</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
160signed 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
168the string length that has to be a multiple of this step size.
169It may not be valid for any other type of control, including
170<constant>V4L2_CTRL_TYPE_INTEGER64</constant>
171controls.</para><para>Generally drivers should not scale hardware
172control values. It may be necessary for example when the
173<structfield>name</structfield> or <structfield>id</structfield> imply
174a particular unit and the hardware actually accepts only multiples of
175said unit. If so, drivers must take care values are properly rounded
176when scaling, such that errors will not accumulate on repeated
177read-write cycles.</para><para>This field gives the smallest change of
178an integer control actually affecting hardware. Often the information
179is needed when the user can change controls by keyboard or GUI
180buttons, rather than a slider. When for example a hardware register
181accepts values 0-511 and the driver reports 0-65535, step should be
182128.</para><para>Note that although signed, the step value is supposed to
183be 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.
191Not valid for other types of controls. Drivers reset controls only
192when the driver is loaded, not later, in particular not when the
193func-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
205the 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
220from 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
233string. 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
239the 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
269maximum inclusive. The step value indicates the increment between
270values 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
286the 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.
295Drivers 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
305and step size cannot be queried.</entry>
306 </row>
307 <row>
308 <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry>
309 <entry>&ge; 0</entry>
310 <entry>&ge; 1</entry>
311 <entry>&ge; 0</entry>
312 <entry>The minimum and maximum string lengths. The step size
313means that the string must be (minimum + N * step) characters long for
314N &ge; 0. These lengths do not include the terminating zero, so in order to
315pass 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
317set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1.
318Which character encoding is used will depend on the string control itself and
319should 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
328equal to a control class code (see <xref linkend="ctrl-class" />), the
329ioctl returns the name of the control class and this control type.
330Older 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
346ignored by the application. Any attempt to change the control will
347result 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
353example because another application took over control of the
354respective resource. Such controls may be displayed specially in a
355user 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
362attempt 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
368value of other controls within the same control class. Applications
369should 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
375configuration and should be displayed accordingly in a user interface.
376For example the flag may be set on a MPEG audio level 2 bitrate
377control when MPEG audio encoding level 1 was selected with another
378control.</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
384slider-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
390attempt to read the control will result in an &EACCES; error code. This
391flag is typically present for relative controls or action controls where
392writing a value will cause the device to carry out a given action
393(&eg; 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>
408is 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<!--
423Local Variables:
424mode: sgml
425sgml-parent-document: "v4l2.sgml"
426indent-tabs-mode: nil
427End:
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
10input</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
53standard automatically. To do so, applications call <constant>
54VIDIOC_QUERYSTD</constant> with a pointer to a &v4l2-std-id; type. The
55driver stores here a set of candidates, this can be a single flag or a
56set of supported standards if for example the hardware can only
57distinguish between 50 and 60 Hz systems. When detection is not
58possible or fails, the set must contain all standards supported by the
59current 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<!--
78Local Variables:
79mode: sgml
80sgml-parent-document: "v4l2.sgml"
81indent-tabs-mode: nil
82End:
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
52mapped</link> or <link linkend="userp">user pointer</link>
53I/O. Memory mapped buffers are located in device memory and must be
54allocated with this ioctl before they can be mapped into the
55application's address space. User buffers are allocated by
56applications themselves, and this ioctl is merely used to switch the
57driver into user pointer I/O mode.</para>
58
59 <para>To allocate device buffers applications initialize three
60fields of a <structname>v4l2_requestbuffers</structname> structure.
61They set the <structfield>type</structfield> field to the respective
62stream or buffer type, the <structfield>count</structfield> field to
63the desired number of buffers, and <structfield>memory</structfield>
64must be set to <constant>V4L2_MEMORY_MMAP</constant>. When the ioctl
65is called with a pointer to this structure the driver attempts to
66allocate the requested number of buffers and stores the actual number
67allocated in the <structfield>count</structfield> field. It can be
68smaller than the number requested, even zero, when the driver runs out
69of free memory. A larger number is possible when the driver requires
70more buffers to function correctly.<footnote>
71 <para>For example video output requires at least two buffers,
72one displayed and one filled by the application.</para>
73 </footnote> When memory mapping I/O is not supported the ioctl
74returns an &EINVAL;.</para>
75
76 <para>Applications can call <constant>VIDIOC_REQBUFS</constant>
77again to change the number of buffers, however this cannot succeed
78when any buffers are still mapped. A <structfield>count</structfield>
79value of zero frees all buffers, after aborting or finishing any DMA
80in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no
81reason why munmap()ping one or even all buffers must imply
82streamoff.--></para>
83
84 <para>To negotiate user pointer I/O, applications initialize only
85the <structfield>type</structfield> field and set
86<structfield>memory</structfield> to
87<constant>V4L2_MEMORY_USERPTR</constant>. When the ioctl is called
88with a pointer to this structure the driver prepares for user pointer
89I/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
101field 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
108as 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
123higher.</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
138in progress, or reallocation of buffers was attempted although one or
139more 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
146requested I/O method (<structfield>memory</structfield>) is not
147supported.</para>
148 </listitem>
149 </varlistentry>
150 </variablelist>
151 </refsect1>
152</refentry>
153
154<!--
155Local Variables:
156mode: sgml
157sgml-parent-document: "v4l2.sgml"
158indent-tabs-mode: nil
159End:
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.
53To 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
57call the <constant>VIDIOC_S_HW_FREQ_SEEK</constant> ioctl with a pointer
58to 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
71same value as in the &v4l2-input; <structfield>tuner</structfield>
72field 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
109bounds or the value in the <structfield>type</structfield> field is
110wrong.</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<!--
124Local Variables:
125mode: sgml
126sgml-parent-document: "v4l2.sgml"
127indent-tabs-mode: nil
128End:
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
54or output process during streaming (<link linkend="mmap">memory
55mapping</link> or <link linkend="userp">user pointer</link>) I/O.</para>
56
57 <para>Specifically the capture hardware is disabled and no input
58buffers are filled (if there are any empty buffers in the incoming
59queue) until <constant>VIDIOC_STREAMON</constant> has been called.
60Accordingly the output hardware is disabled, no video signal is
61produced until <constant>VIDIOC_STREAMON</constant> has been called.
62The ioctl will succeed only when at least one output buffer is in the
63incoming queue.</para>
64
65 <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of
66aborting or finishing any DMA in progress, unlocks any user pointer
67buffers locked in physical memory, and it removes all buffers from the
68incoming and outgoing queues. That means all images captured but not
69dequeued yet will be lost, likewise all images enqueued for output but
70not 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
74stream 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
78before or after the <constant>VIDIOC_STREAMON</constant> or
79<constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of
80starting or stopping "now". Buffer timestamps can be used to
81synchronize 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
93been allocated (memory mapping) or enqueued (output) yet.</para>
94 </listitem>
95 </varlistentry>
96 </variablelist>
97 </refsect1>
98</refentry>
99
100<!--
101Local Variables:
102mode: sgml
103sgml-parent-document: "v4l2.sgml"
104indent-tabs-mode: nil
105End:
106-->
diff --git a/Documentation/Intel-IOMMU.txt b/Documentation/Intel-IOMMU.txt
index 21bc416d887e..cf9431db8731 100644
--- a/Documentation/Intel-IOMMU.txt
+++ b/Documentation/Intel-IOMMU.txt
@@ -56,11 +56,7 @@ Graphics Problems?
56------------------ 56------------------
57If you encounter issues with graphics devices, you can try adding 57If you encounter issues with graphics devices, you can try adding
58option intel_iommu=igfx_off to turn off the integrated graphics engine. 58option intel_iommu=igfx_off to turn off the integrated graphics engine.
59 59If this fixes anything, please ensure you file a bug reporting the problem.
60If it happens to be a PCI device included in the INCLUDE_ALL Engine,
61then try enabling CONFIG_DMAR_GFX_WA to setup a 1-1 map. We hear
62graphics drivers may be in process of using DMA api's in the near
63future and at that time this option can be yanked out.
64 60
65Some exceptions to IOVA 61Some exceptions to IOVA
66----------------------- 62-----------------------
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
10Many PCI bus controllers are able to detect a variety of hardware 12Many PCI bus controllers are able to detect a variety of hardware
11PCI errors on the bus, such as parity errors on the data and address 13PCI errors on the bus, such as parity errors on the data and address
12busses, as well as SERR and PERR errors. Some of the more advanced 14busses, as well as SERR and PERR errors. Some of the more advanced
13chipsets are able to deal with these errors; these include PCI-E chipsets, 15chipsets are able to deal with these errors; these include PCI-E chipsets,
14and the PCI-host bridges found on IBM Power4 and Power5-based pSeries 16and the PCI-host bridges found on IBM Power4, Power5 and Power6-based
15boxes. A typical action taken is to disconnect the affected device, 17pSeries boxes. A typical action taken is to disconnect the affected device,
16halting all I/O to it. The goal of a disconnection is to avoid system 18halting all I/O to it. The goal of a disconnection is to avoid system
17corruption; for example, to halt system memory corruption due to DMA's 19corruption; for example, to halt system memory corruption due to DMA's
18to "wild" addresses. Typically, a reconnection mechanism is also 20to "wild" addresses. Typically, a reconnection mechanism is also
@@ -37,10 +39,11 @@ is forced by the need to handle multi-function devices, that is,
37devices that have multiple device drivers associated with them. 39devices that have multiple device drivers associated with them.
38In the first stage, each driver is allowed to indicate what type 40In the first stage, each driver is allowed to indicate what type
39of reset it desires, the choices being a simple re-enabling of I/O 41of reset it desires, the choices being a simple re-enabling of I/O
40or requesting a hard reset (a full electrical #RST of the PCI card). 42or requesting a slot reset.
41If any driver requests a full reset, that is what will be done.
42 43
43After a full reset and/or a re-enabling of I/O, all drivers are 44If any driver requests a slot reset, that is what will be done.
45
46After a reset and/or a re-enabling of I/O, all drivers are
44again notified, so that they may then perform any device setup/config 47again notified, so that they may then perform any device setup/config
45that may be required. After these have all completed, a final 48that 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
101is not implemented, the corresponding feature is considered unsupported. 104is not implemented, the corresponding feature is considered unsupported.
102For example, if mmio_enabled() and resume() aren't there, then it 105For example, if mmio_enabled() and resume() aren't there, then it
103is assumed that the driver is not doing any direct recovery and requires 106is assumed that the driver is not doing any direct recovery and requires
104a reset. If link_reset() is not implemented, the card is assumed as 107a slot reset. If link_reset() is not implemented, the card is assumed to
105not care about link resets. Typically a driver will want to know about 108not care about link resets. Typically a driver will want to know about
106a slot_reset(). 109a slot_reset().
107 110
@@ -111,7 +114,7 @@ sequence described below.
111 114
112STEP 0: Error Event 115STEP 0: Error Event
113------------------- 116-------------------
114PCI bus error is detect by the PCI hardware. On powerpc, the slot 117A PCI bus error is detected by the PCI hardware. On powerpc, the slot
115is isolated, in that all I/O is blocked: all reads return 0xffffffff, 118is isolated, in that all I/O is blocked: all reads return 0xffffffff,
116all writes are ignored. 119all 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
178STEP 2: MMIO Enabled 181STEP 2: MMIO Enabled
179------------------- 182-------------------
@@ -182,15 +185,14 @@ DMA), and then calls the mmio_enabled() callback on all affected
182device drivers. 185device drivers.
183 186
184This is the "early recovery" call. IOs are allowed again, but DMA is 187This is the "early recovery" call. IOs are allowed again, but DMA is
185not (hrm... to be discussed, I prefer not), with some restrictions. This 188not, with some restrictions. This is NOT a callback for the driver to
186is NOT a callback for the driver to start operations again, only to 189start operations again, only to peek/poke at the device, extract diagnostic
187peek/poke at the device, extract diagnostic information, if any, and 190information, if any, and eventually do things like trigger a device local
188eventually do things like trigger a device local reset or some such, 191reset or some such, but not restart operations. This callback is made if
189but not restart operations. This is callback is made if all drivers on 192all drivers on a segment agree that they can try to recover and if no automatic
190a segment agree that they can try to recover and if no automatic link reset 193link reset was performed by the HW. If the platform can't just re-enable IOs
191was performed by the HW. If the platform can't just re-enable IOs without 194without a slot reset or a link reset, it will not call this callback, and
192a slot reset or a link reset, it wont call this callback, and instead 195instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset)
193will 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).
228If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform 230If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform
229proceeds to STEP 4 (Slot Reset) 231proceeds to STEP 4 (Slot Reset)
230 232
231>>> The current powerpc implementation does not implement this callback.
232
233
234STEP 3: Link Reset 233STEP 3: Link Reset
235------------------ 234------------------
236The platform resets the link, and then calls the link_reset() callback 235The 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
257STEP 4: Slot Reset 255STEP 4: Slot Reset
258------------------ 256------------------
259The platform performs a soft or hard reset of the device, and then
260calls the slot_reset() callback.
261 257
262A soft reset consists of asserting the adapter #RST line and then 258In response to a return value of PCI_ERS_RESULT_NEED_RESET, the
259the platform will peform a slot reset on the requesting PCI device(s).
260The actual steps taken by a platform to perform a slot reset
261will be platform-dependent. Upon completion of slot reset, the
262platform will call the device slot_reset() callback.
263
264Powerpc platforms implement two levels of slot reset:
265soft reset(default) and fundamental(optional) reset.
266
267Powerpc soft reset consists of asserting the adapter #RST line and then
263restoring the PCI BAR's and PCI configuration header to a state 268restoring the PCI BAR's and PCI configuration header to a state
264that is equivalent to what it would be after a fresh system 269that is equivalent to what it would be after a fresh system
265power-on followed by power-on BIOS/system firmware initialization. 270power-on followed by power-on BIOS/system firmware initialization.
271Soft reset is also known as hot-reset.
272
273Powerpc fundamental reset is supported by PCI Express cards only
274and results in device's state machines, hardware logic, port states and
275configuration registers to initialize to their default conditions.
276
277For most PCI devices, a soft reset will be sufficient for recovery.
278Optional fundamental reset is provided to support a limited number
279of PCI Express PCI devices for which a soft reset is not sufficient
280for recovery.
281
266If the platform supports PCI hotplug, then the reset might be 282If the platform supports PCI hotplug, then the reset might be
267performed by toggling the slot electrical power off/on. 283performed 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
275This call gives drivers the chance to re-initialize the hardware 291This 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
277that he card is in a fresh state and is fully functional. In 293that the card is in a fresh state and is fully functional. The slot
278particular, interrupt generation should work normally. 294is unfrozen and the driver has full access to PCI config space,
295memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X)
296will also be available.
279 297
280Drivers should not yet restart normal I/O processing operations 298Drivers should not restart normal I/O processing operations
281at this point. If all device drivers report success on this 299at this point. If all device drivers report success on this
282callback, the platform will call resume() to complete the sequence, 300callback, the platform will call resume() to complete the sequence,
283and let the driver restart normal I/O processing. 301and 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
323Drivers for PCI Express cards that require a fundamental reset must
324set the needs_freset bit in the pci_dev structure in their probe function.
325For example, the QLogic qla2xxx driver sets the needs_freset bit for certain
326PCI 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
305Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent 333Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent
306Failure). 334Failure).
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
349Conclusion; General Remarks 377Conclusion; General Remarks
350--------------------------- 378---------------------------
351The way those callbacks are called is platform policy. A platform with 379The way the callbacks are called is platform policy. A platform with
352no slot reset capability may want to just "ignore" drivers that can't 380no slot reset capability may want to just "ignore" drivers that can't
353recover (disconnect them) and try to let other cards on the same segment 381recover (disconnect them) and try to let other cards on the same segment
354recover. Keep in mind that in most real life cases, though, there will 382recover. 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
363device on the segment starting from the error detection and until the 391device on the segment starting from the error detection and until the
364resume callback is sent, at which point interrupts are expected to be 392slot_reset callback is called, at which point interrupts are expected
365fully operational. 393to 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,
368a driver that gets an interrupt after detecting an error, or that detects 396a 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
395The End 430The End
396------- 431-------
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)
183a man-pages patch, or at least a notification of the change, 183a man-pages patch, or at least a notification of the change,
184so that some information makes its way into the manual pages. 184so that some information makes its way into the manual pages.
185 185
186Even if the maintainer did not respond in step #4, make sure to ALWAYS 186Even if the maintainer did not respond in step #5, make sure to ALWAYS
187copy the maintainer when you change their code. 187copy the maintainer when you change their code.
188 188
189For small patches you may want to CC the Trivial Patch Monkey 189For small patches you may want to CC the Trivial Patch Monkey
diff --git a/Documentation/accounting/getdelays.c b/Documentation/accounting/getdelays.c
index aa73e72fd793..6e25c2659e0a 100644
--- a/Documentation/accounting/getdelays.c
+++ b/Documentation/accounting/getdelays.c
@@ -116,7 +116,7 @@ error:
116} 116}
117 117
118 118
119int send_cmd(int sd, __u16 nlmsg_type, __u32 nlmsg_pid, 119static int send_cmd(int sd, __u16 nlmsg_type, __u32 nlmsg_pid,
120 __u8 genl_cmd, __u16 nla_type, 120 __u8 genl_cmd, __u16 nla_type,
121 void *nla_data, int nla_len) 121 void *nla_data, int nla_len)
122{ 122{
@@ -160,7 +160,7 @@ int send_cmd(int sd, __u16 nlmsg_type, __u32 nlmsg_pid,
160 * Probe the controller in genetlink to find the family id 160 * Probe the controller in genetlink to find the family id
161 * for the TASKSTATS family 161 * for the TASKSTATS family
162 */ 162 */
163int get_family_id(int sd) 163static int get_family_id(int sd)
164{ 164{
165 struct { 165 struct {
166 struct nlmsghdr n; 166 struct nlmsghdr n;
@@ -190,7 +190,7 @@ int get_family_id(int sd)
190 return id; 190 return id;
191} 191}
192 192
193void print_delayacct(struct taskstats *t) 193static void print_delayacct(struct taskstats *t)
194{ 194{
195 printf("\n\nCPU %15s%15s%15s%15s\n" 195 printf("\n\nCPU %15s%15s%15s%15s\n"
196 " %15llu%15llu%15llu%15llu\n" 196 " %15llu%15llu%15llu%15llu\n"
@@ -216,7 +216,7 @@ void print_delayacct(struct taskstats *t)
216 (unsigned long long)t->freepages_delay_total); 216 (unsigned long long)t->freepages_delay_total);
217} 217}
218 218
219void task_context_switch_counts(struct taskstats *t) 219static void task_context_switch_counts(struct taskstats *t)
220{ 220{
221 printf("\n\nTask %15s%15s\n" 221 printf("\n\nTask %15s%15s\n"
222 " %15llu%15llu\n", 222 " %15llu%15llu\n",
@@ -224,7 +224,7 @@ void task_context_switch_counts(struct taskstats *t)
224 (unsigned long long)t->nvcsw, (unsigned long long)t->nivcsw); 224 (unsigned long long)t->nvcsw, (unsigned long long)t->nivcsw);
225} 225}
226 226
227void print_cgroupstats(struct cgroupstats *c) 227static void print_cgroupstats(struct cgroupstats *c)
228{ 228{
229 printf("sleeping %llu, blocked %llu, running %llu, stopped %llu, " 229 printf("sleeping %llu, blocked %llu, running %llu, stopped %llu, "
230 "uninterruptible %llu\n", (unsigned long long)c->nr_sleeping, 230 "uninterruptible %llu\n", (unsigned long long)c->nr_sleeping,
@@ -235,7 +235,7 @@ void print_cgroupstats(struct cgroupstats *c)
235} 235}
236 236
237 237
238void print_ioacct(struct taskstats *t) 238static void print_ioacct(struct taskstats *t)
239{ 239{
240 printf("%s: read=%llu, write=%llu, cancelled_write=%llu\n", 240 printf("%s: read=%llu, write=%llu, cancelled_write=%llu\n",
241 t->ac_comm, 241 t->ac_comm,
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
2The OMAP PM interface
3=====================
4
5This document describes the temporary OMAP PM interface. Driver
6authors use these functions to communicate minimum latency or
7throughput constraints to the kernel power management code.
8Over time, the intention is to merge features from the OMAP PM
9interface into the Linux PM QoS code.
10
11Drivers 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
31This document proposes the OMAP PM interface, including the following
32five power management functions for driver code:
33
341. Set the maximum MPU wakeup latency:
35 (*pdata->set_max_mpu_wakeup_lat)(struct device *dev, unsigned long t)
36
372. Set the maximum device wakeup latency:
38 (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t)
39
403. Set the maximum system DMA transfer start latency (CORE pwrdm):
41 (*pdata->set_max_sdma_lat)(struct device *dev, long t)
42
434. 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
465. Return the number of times the device has lost context
47 (*pdata->get_dev_context_loss_count)(struct device *dev)
48
49
50Further documentation for all OMAP PM interface functions can be
51found in arch/arm/plat-omap/include/mach/omap-pm.h.
52
53
54The OMAP PM layer is intended to be temporary
55---------------------------------------------
56
57The intention is that eventually the Linux PM QoS layer should support
58the range of power management features present in OMAP3. As this
59happens, existing drivers using the OMAP PM interface can be modified
60to use the Linux PM QoS code; and the OMAP PM interface can disappear.
61
62
63Driver usage of the OMAP PM functions
64-------------------------------------
65
66As the 'pdata' in the above examples indicates, these functions are
67exposed to drivers through function pointers in driver .platform_data
68structures. The function pointers are initialized by the board-*.c
69files to point to the corresponding OMAP PM functions:
70.set_max_dev_wakeup_lat will point to
71omap_pm_set_max_dev_wakeup_lat(), etc. Other architectures which do
72not support these functions should leave these function pointers set
73to 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
78The most common usage of these functions will probably be to specify
79the maximum time from when an interrupt occurs, to when the device
80becomes accessible. To accomplish this, driver writers should use the
81set_max_mpu_wakeup_lat() function to to constrain the MPU wakeup
82latency, and the set_max_dev_wakeup_lat() function to constrain the
83device wakeup latency (from clk_enable() to accessibility). For
84example,
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
96The PM parameters can be overwritten by calling the function again
97with the new value. The settings can be removed by calling the
98function with a t argument of -1 (except in the case of
99set_max_bus_tput(), which should be called with an r argument of 0).
100
101The fifth function above, omap_pm_get_dev_context_loss_count(),
102is intended as an optimization to allow drivers to determine whether the
103device has lost its internal context. If context has been lost, the
104driver must restore its internal context before proceeding.
105
106
107Other specialized interface functions
108-------------------------------------
109
110The five functions listed above are intended to be usable by any
111device driver. DSPBridge and CPUFreq have a few special requirements.
112DSPBridge expresses target DSP performance levels in terms of OPP IDs.
113CPUFreq expresses target MPU performance levels in terms of MPU
114frequency. The OMAP PM interface contains functions for these
115specialized cases to convert that input information (OPPs/MPU
116frequency) into the form that the underlying power management
117implementation needs:
118
1196. (*pdata->dsp_get_opp_table)(void)
120
1217. (*pdata->dsp_set_min_opp)(u8 opp_id)
122
1238. (*pdata->dsp_get_opp)(void)
124
1259. (*pdata->cpu_get_freq_table)(void)
126
12710. (*pdata->cpu_set_freq)(unsigned long f)
128
12911. (*pdata->cpu_get_freq)(void)
diff --git a/Documentation/auxdisplay/cfag12864b-example.c b/Documentation/auxdisplay/cfag12864b-example.c
index 2caeea5e4993..e7823ffb1ca0 100644
--- a/Documentation/auxdisplay/cfag12864b-example.c
+++ b/Documentation/auxdisplay/cfag12864b-example.c
@@ -62,7 +62,7 @@ unsigned char cfag12864b_buffer[CFAG12864B_SIZE];
62 * Unable to open: return = -1 62 * Unable to open: return = -1
63 * Unable to mmap: return = -2 63 * Unable to mmap: return = -2
64 */ 64 */
65int cfag12864b_init(char *path) 65static int cfag12864b_init(char *path)
66{ 66{
67 cfag12864b_fd = open(path, O_RDWR); 67 cfag12864b_fd = open(path, O_RDWR);
68 if (cfag12864b_fd == -1) 68 if (cfag12864b_fd == -1)
@@ -81,7 +81,7 @@ int cfag12864b_init(char *path)
81/* 81/*
82 * exit a cfag12864b framebuffer device 82 * exit a cfag12864b framebuffer device
83 */ 83 */
84void cfag12864b_exit(void) 84static void cfag12864b_exit(void)
85{ 85{
86 munmap(cfag12864b_mem, CFAG12864B_SIZE); 86 munmap(cfag12864b_mem, CFAG12864B_SIZE);
87 close(cfag12864b_fd); 87 close(cfag12864b_fd);
@@ -90,7 +90,7 @@ void cfag12864b_exit(void)
90/* 90/*
91 * set (x, y) pixel 91 * set (x, y) pixel
92 */ 92 */
93void cfag12864b_set(unsigned char x, unsigned char y) 93static void cfag12864b_set(unsigned char x, unsigned char y)
94{ 94{
95 if (CFAG12864B_CHECK(x, y)) 95 if (CFAG12864B_CHECK(x, y))
96 cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] |= 96 cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] |=
@@ -100,7 +100,7 @@ void cfag12864b_set(unsigned char x, unsigned char y)
100/* 100/*
101 * unset (x, y) pixel 101 * unset (x, y) pixel
102 */ 102 */
103void cfag12864b_unset(unsigned char x, unsigned char y) 103static void cfag12864b_unset(unsigned char x, unsigned char y)
104{ 104{
105 if (CFAG12864B_CHECK(x, y)) 105 if (CFAG12864B_CHECK(x, y))
106 cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] &= 106 cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] &=
@@ -113,7 +113,7 @@ void cfag12864b_unset(unsigned char x, unsigned char y)
113 * Pixel off: return = 0 113 * Pixel off: return = 0
114 * Pixel on: return = 1 114 * Pixel on: return = 1
115 */ 115 */
116unsigned char cfag12864b_isset(unsigned char x, unsigned char y) 116static unsigned char cfag12864b_isset(unsigned char x, unsigned char y)
117{ 117{
118 if (CFAG12864B_CHECK(x, y)) 118 if (CFAG12864B_CHECK(x, y))
119 if (cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] & 119 if (cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] &
@@ -126,7 +126,7 @@ unsigned char cfag12864b_isset(unsigned char x, unsigned char y)
126/* 126/*
127 * not (x, y) pixel 127 * not (x, y) pixel
128 */ 128 */
129void cfag12864b_not(unsigned char x, unsigned char y) 129static void cfag12864b_not(unsigned char x, unsigned char y)
130{ 130{
131 if (cfag12864b_isset(x, y)) 131 if (cfag12864b_isset(x, y))
132 cfag12864b_unset(x, y); 132 cfag12864b_unset(x, y);
@@ -137,7 +137,7 @@ void cfag12864b_not(unsigned char x, unsigned char y)
137/* 137/*
138 * fill (set all pixels) 138 * fill (set all pixels)
139 */ 139 */
140void cfag12864b_fill(void) 140static void cfag12864b_fill(void)
141{ 141{
142 unsigned short i; 142 unsigned short i;
143 143
@@ -148,7 +148,7 @@ void cfag12864b_fill(void)
148/* 148/*
149 * clear (unset all pixels) 149 * clear (unset all pixels)
150 */ 150 */
151void cfag12864b_clear(void) 151static void cfag12864b_clear(void)
152{ 152{
153 unsigned short i; 153 unsigned short i;
154 154
@@ -162,7 +162,7 @@ void cfag12864b_clear(void)
162 * Pixel off: src[i] = 0 162 * Pixel off: src[i] = 0
163 * Pixel on: src[i] > 0 163 * Pixel on: src[i] > 0
164 */ 164 */
165void cfag12864b_format(unsigned char * matrix) 165static void cfag12864b_format(unsigned char * matrix)
166{ 166{
167 unsigned char i, j, n; 167 unsigned char i, j, n;
168 168
@@ -182,7 +182,7 @@ void cfag12864b_format(unsigned char * matrix)
182/* 182/*
183 * blit buffer to lcd 183 * blit buffer to lcd
184 */ 184 */
185void cfag12864b_blit(void) 185static void cfag12864b_blit(void)
186{ 186{
187 memcpy(cfag12864b_mem, cfag12864b_buffer, CFAG12864B_SIZE); 187 memcpy(cfag12864b_mem, cfag12864b_buffer, CFAG12864B_SIZE);
188} 188}
@@ -194,11 +194,10 @@ void cfag12864b_blit(void)
194 */ 194 */
195 195
196#include <stdio.h> 196#include <stdio.h>
197#include <string.h>
198 197
199#define EXAMPLES 6 198#define EXAMPLES 6
200 199
201void example(unsigned char n) 200static void example(unsigned char n)
202{ 201{
203 unsigned short i, j; 202 unsigned short i, j;
204 unsigned char matrix[CFAG12864B_WIDTH * CFAG12864B_HEIGHT]; 203 unsigned char matrix[CFAG12864B_WIDTH * CFAG12864B_HEIGHT];
diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroups/cgroups.txt
index 6eb1a97e88ce..455d4e6d346d 100644
--- a/Documentation/cgroups/cgroups.txt
+++ b/Documentation/cgroups/cgroups.txt
@@ -408,6 +408,26 @@ You can attach the current shell task by echoing 0:
408 408
409# echo 0 > tasks 409# echo 0 > tasks
410 410
4112.3 Mounting hierarchies by name
412--------------------------------
413
414Passing the name=<x> option when mounting a cgroups hierarchy
415associates the given name with the hierarchy. This can be used when
416mounting a pre-existing hierarchy, in order to refer to it by name
417rather than by its set of active subsystems. Each hierarchy is either
418nameless, or has a unique name.
419
420The name should match [\w.-]+
421
422When passing a name=<x> option for a new hierarchy, you need to
423specify subsystems manually; the legacy behaviour of mounting all
424subsystems when none are explicitly specified is not supported when
425you give a subsystem a name.
426
427The name of the subsystem appears as part of the hierarchy description
428in /proc/mounts and /proc/<pid>/cgroups.
429
430
4113. Kernel API 4313. Kernel API
412============= 432=============
413 433
@@ -501,7 +521,7 @@ rmdir() will fail with it. From this behavior, pre_destroy() can be
501called multiple times against a cgroup. 521called multiple times against a cgroup.
502 522
503int can_attach(struct cgroup_subsys *ss, struct cgroup *cgrp, 523int can_attach(struct cgroup_subsys *ss, struct cgroup *cgrp,
504 struct task_struct *task) 524 struct task_struct *task, bool threadgroup)
505(cgroup_mutex held by caller) 525(cgroup_mutex held by caller)
506 526
507Called prior to moving a task into a cgroup; if the subsystem 527Called prior to moving a task into a cgroup; if the subsystem
@@ -509,14 +529,20 @@ returns an error, this will abort the attach operation. If a NULL
509task is passed, then a successful result indicates that *any* 529task is passed, then a successful result indicates that *any*
510unspecified task can be moved into the cgroup. Note that this isn't 530unspecified task can be moved into the cgroup. Note that this isn't
511called on a fork. If this method returns 0 (success) then this should 531called on a fork. If this method returns 0 (success) then this should
512remain valid while the caller holds cgroup_mutex. 532remain valid while the caller holds cgroup_mutex. If threadgroup is
533true, then a successful result indicates that all threads in the given
534thread's threadgroup can be moved together.
513 535
514void attach(struct cgroup_subsys *ss, struct cgroup *cgrp, 536void attach(struct cgroup_subsys *ss, struct cgroup *cgrp,
515 struct cgroup *old_cgrp, struct task_struct *task) 537 struct cgroup *old_cgrp, struct task_struct *task,
538 bool threadgroup)
516(cgroup_mutex held by caller) 539(cgroup_mutex held by caller)
517 540
518Called after the task has been attached to the cgroup, to allow any 541Called after the task has been attached to the cgroup, to allow any
519post-attachment activity that requires memory allocations or blocking. 542post-attachment activity that requires memory allocations or blocking.
543If threadgroup is true, the subsystem should take care of all threads
544in the specified thread's threadgroup. Currently does not support any
545subsystem that might need the old_cgrp for every thread in the group.
520 546
521void fork(struct cgroup_subsy *ss, struct task_struct *task) 547void fork(struct cgroup_subsy *ss, struct task_struct *task)
522 548
diff --git a/Documentation/cgroups/memory.txt b/Documentation/cgroups/memory.txt
index 23d1262c0775..b871f2552b45 100644
--- a/Documentation/cgroups/memory.txt
+++ b/Documentation/cgroups/memory.txt
@@ -179,6 +179,9 @@ The reclaim algorithm has not been modified for cgroups, except that
179pages that are selected for reclaiming come from the per cgroup LRU 179pages that are selected for reclaiming come from the per cgroup LRU
180list. 180list.
181 181
182NOTE: Reclaim does not work for the root cgroup, since we cannot set any
183limits on the root cgroup.
184
1822. Locking 1852. Locking
183 186
184The memory controller uses the following hierarchy 187The memory controller uses the following hierarchy
@@ -210,6 +213,7 @@ We can alter the memory limit:
210NOTE: We can use a suffix (k, K, m, M, g or G) to indicate values in kilo, 213NOTE: We can use a suffix (k, K, m, M, g or G) to indicate values in kilo,
211mega or gigabytes. 214mega or gigabytes.
212NOTE: We can write "-1" to reset the *.limit_in_bytes(unlimited). 215NOTE: We can write "-1" to reset the *.limit_in_bytes(unlimited).
216NOTE: We cannot set limits on the root cgroup any more.
213 217
214# cat /cgroups/0/memory.limit_in_bytes 218# cat /cgroups/0/memory.limit_in_bytes
2154194304 2194194304
@@ -375,7 +379,42 @@ cgroups created below it.
375 379
376NOTE2: This feature can be enabled/disabled per subtree. 380NOTE2: This feature can be enabled/disabled per subtree.
377 381
3787. TODO 3827. Soft limits
383
384Soft limits allow for greater sharing of memory. The idea behind soft limits
385is to allow control groups to use as much of the memory as needed, provided
386
387a. There is no memory contention
388b. They do not exceed their hard limit
389
390When the system detects memory contention or low memory control groups
391are pushed back to their soft limits. If the soft limit of each control
392group is very high, they are pushed back as much as possible to make
393sure that one control group does not starve the others of memory.
394
395Please note that soft limits is a best effort feature, it comes with
396no guarantees, but it does its best to make sure that when memory is
397heavily contended for, memory is allocated based on the soft limit
398hints/setup. Currently soft limit based reclaim is setup such that
399it gets invoked from balance_pgdat (kswapd).
400
4017.1 Interface
402
403Soft limits can be setup by using the following commands (in this example we
404assume a soft limit of 256 megabytes)
405
406# echo 256M > memory.soft_limit_in_bytes
407
408If we want to change this to 1G, we can at any time use
409
410# echo 1G > memory.soft_limit_in_bytes
411
412NOTE1: Soft limits take effect over a long period of time, since they involve
413 reclaiming memory for balancing between memory cgroups
414NOTE2: It is recommended to set the soft limit always below the hard limit,
415 otherwise the hard limit will take precedence.
416
4178. TODO
379 418
3801. Add support for accounting huge pages (as a separate controller) 4191. Add support for accounting huge pages (as a separate controller)
3812. Make per-cgroup scanner reclaim not-shared pages first 4202. Make per-cgroup scanner reclaim not-shared pages first
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
179cpuinfo_cur_freq : Current speed of the CPU, in KHz. 179cpuinfo_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
181scaling_available_frequencies : List of available frequencies, in KHz. 183scaling_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
197scaling_driver : Hardware driver for cpufreq. 199scaling_driver : Hardware driver for cpufreq.
198 200
199scaling_cur_freq : Current frequency of the CPU, in KHz. 201scaling_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
201If you have selected the "userspace" governor which allows you to 206If you have selected the "userspace" governor which allows you to
202set the CPU operating frequency to a specific value, you can read out 207set 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
152piggyback 152piggyback
153pnmtologo 153pnmtologo
154ppc_defs.h* 154ppc_defs.h*
155promcon_tbl.c
156pss_boot.h 155pss_boot.h
157qconf 156qconf
158raid6altivec*.c 157raid6altivec*.c
diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware
index 3d1b0ab70c8e..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", "mpc718" ); 28 "opera1", "cx231xx", "cx18", "cx23885", "pvrusb2", "mpc718",
29 "af9015");
29 30
30# Check args 31# Check args
31syntax() if (scalar(@ARGV) != 1); 32syntax() if (scalar(@ARGV) != 1);
@@ -514,6 +515,40 @@ sub bluebird {
514 $outfile; 515 $outfile;
515} 516}
516 517
518sub 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
517# --------------------------------------------------------------- 552# ---------------------------------------------------------------
518# Utilities 553# Utilities
519 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
41) Find out what device you have 41) Find out what device you have
5================================ 5================================
6 6
7Important Notice: The driver does NOT support Technisat USB 2 devices!
8
7First start your linux box with a shipped kernel: 9First start your linux box with a shipped kernel:
8lspci -vvv for a PCI device (lsusb -vvv for an USB device) will show you for example: 10lspci -vvv for a PCI device (lsusb -vvv for an USB device) will show you for example:
902:0b.0 Network controller: Techsan Electronics Co Ltd B2C2 FlexCopII DVB chip / Technisat SkyStar2 DVB card (rev 02) 1102:0b.0 Network controller: Techsan Electronics Co Ltd B2C2 FlexCopII DVB chip /
12 Technisat SkyStar2 DVB card (rev 02)
10 13
11dmesg | grep frontend may show you for example: 14dmesg | grep frontend may show you for example:
12DVB: registering frontend 0 (Conexant CX24123/CX24109)... 15DVB: registering frontend 0 (Conexant CX24123/CX24109)...
@@ -14,62 +17,62 @@ DVB: registering frontend 0 (Conexant CX24123/CX24109)...
142) Kernel compilation: 172) Kernel compilation:
15====================== 18======================
16 19
17If the Technisat is the only TV device in your box get rid of unnecessary modules and check this one: 20If 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:
19In 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"
23In 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
21Then please activate: 26Then please activate:
222a) Main module part: 272a) Main module part:
28"Multimedia support" => "DVB/ATSC adapters"
29 => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters"
23 30
24a.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" 31a.) => "Technisat/B2C2 Air/Sky/Cable2PC PCI" (PCI card) or
25b.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Technisat/B2C2 Air/Sky/Cable2PC PCI" in case of a PCI card 32b.) => "Technisat/B2C2 Air/Sky/Cable2PC USB" (USB 1.1 adapter)
26OR 33 and for troubleshooting purposes:
27c.)"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 34c.) => "Enable debug for the B2C2 FlexCop drivers"
28d.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Enable debug for the B2C2 FlexCop drivers"
29Notice: d.) is helpful for troubleshooting
30 35
312b) Frontend module part: 362b) Frontend / Tuner / Demodulator module part:
37"Multimedia support" => "DVB/ATSC adapters"
38 => "Customise the frontend modules to build" "Customise DVB frontends" =>
32 39
331.) SkyStar DVB-S Revision 2.3: 401.) SkyStar DVB-S Revision 2.3:
34a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" 41a.) => "Zarlink VP310/MT312/ZL10313 based"
35b.)"Multimedia devices" => "Customise DVB frontends" => "Zarlink VP310/MT312/ZL10313 based" 42b.) => "Generic I2C PLL based tuners"
36 43
372.) SkyStar DVB-S Revision 2.6: 442.) SkyStar DVB-S Revision 2.6:
38a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" 45a.) => "ST STV0299 based"
39b.)"Multimedia devices" => "Customise DVB frontends" => "ST STV0299 based" 46b.) => "Generic I2C PLL based tuners"
40 47
413.) SkyStar DVB-S Revision 2.7: 483.) SkyStar DVB-S Revision 2.7:
42a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" 49a.) => "Samsung S5H1420 based"
43b.)"Multimedia devices" => "Customise DVB frontends" => "Samsung S5H1420 based" 50b.) => "Integrant ITD1000 Zero IF tuner for DVB-S/DSS"
44c.)"Multimedia devices" => "Customise DVB frontends" => "Integrant ITD1000 Zero IF tuner for DVB-S/DSS" 51c.) => "ISL6421 SEC controller"
45d.)"Multimedia devices" => "Customise DVB frontends" => "ISL6421 SEC controller"
46 52
474.) SkyStar DVB-S Revision 2.8: 534.) SkyStar DVB-S Revision 2.8:
48a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" 54a.) => "Conexant CX24123 based"
49b.)"Multimedia devices" => "Customise DVB frontends" => "Conexant CX24113/CX24128 tuner for DVB-S/DSS" 55b.) => "Conexant CX24113/CX24128 tuner for DVB-S/DSS"
50c.)"Multimedia devices" => "Customise DVB frontends" => "Conexant CX24123 based" 56c.) => "ISL6421 SEC controller"
51d.)"Multimedia devices" => "Customise DVB frontends" => "ISL6421 SEC controller"
52 57
535.) AirStar DVB-T card: 585.) AirStar DVB-T card:
54a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" 59a.) => "Zarlink MT352 based"
55b.)"Multimedia devices" => "Customise DVB frontends" => "Zarlink MT352 based" 60b.) => "Generic I2C PLL based tuners"
56 61
576.) CableStar DVB-C card: 626.) CableStar DVB-C card:
58a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" 63a.) => "ST STV0297 based"
59b.)"Multimedia devices" => "Customise DVB frontends" => "ST STV0297 based" 64b.) => "Generic I2C PLL based tuners"
60 65
617.) AirStar ATSC card 1st generation: 667.) AirStar ATSC card 1st generation:
62a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" 67a.) => "Broadcom BCM3510"
63b.)"Multimedia devices" => "Customise DVB frontends" => "Broadcom BCM3510"
64 68
658.) AirStar ATSC card 2nd generation: 698.) AirStar ATSC card 2nd generation:
66a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" 70a.) => "NxtWave Communications NXT2002/NXT2004 based"
67b.)"Multimedia devices" => "Customise DVB frontends" => "NxtWave Communications NXT2002/NXT2004 based" 71b.) => "Generic I2C PLL based tuners"
68c.)"Multimedia devices" => "Customise DVB frontends" => "Generic I2C PLL based tuners"
69 72
709.) AirStar ATSC card 3rd generation: 739.) AirStar ATSC card 3rd generation:
71a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" 74a.) => "LG Electronics LGDT3302/LGDT3303 based"
72b.)"Multimedia devices" => "Customise DVB frontends" => "LG Electronics LGDT3302/LGDT3303 based" 75b.) "Multimedia support" => "Customise analog and hybrid tuner modules to build"
73c.)"Multimedia devices" => "Customise analog and hybrid tuner modules to build" => "Simple tuner support" 76 => "Simple tuner support"
74 77
75Author: Uwe Bugla <uwe.bugla@gmx.de> February 2009 78Author: Uwe Bugla <uwe.bugla@gmx.de> August 2009
diff --git a/Documentation/fb/ep93xx-fb.txt b/Documentation/fb/ep93xx-fb.txt
new file mode 100644
index 000000000000..5af1bd9effae
--- /dev/null
+++ b/Documentation/fb/ep93xx-fb.txt
@@ -0,0 +1,135 @@
1================================
2Driver for EP93xx LCD controller
3================================
4
5The EP93xx LCD controller can drive both standard desktop monitors and
6embedded LCD displays. If you have a standard desktop monitor then you
7can use the standard Linux video mode database. In your board file:
8
9 static struct ep93xxfb_mach_info some_board_fb_info = {
10 .num_modes = EP93XXFB_USE_MODEDB,
11 .bpp = 16,
12 };
13
14If you have an embedded LCD display then you need to define a video
15mode for it as follows:
16
17 static struct fb_videomode some_board_video_modes[] = {
18 {
19 .name = "some_lcd_name",
20 /* Pixel clock, porches, etc */
21 },
22 };
23
24Note that the pixel clock value is in pico-seconds. You can use the
25KHZ2PICOS macro to convert the pixel clock value. Most other values
26are in pixel clocks. See Documentation/fb/framebuffer.txt for further
27details.
28
29The ep93xxfb_mach_info structure for your board should look like the
30following:
31
32 static struct ep93xxfb_mach_info some_board_fb_info = {
33 .num_modes = ARRAY_SIZE(some_board_video_modes),
34 .modes = some_board_video_modes,
35 .default_mode = &some_board_video_modes[0],
36 .bpp = 16,
37 };
38
39The framebuffer device can be registered by adding the following to
40your board initialisation function:
41
42 ep93xx_register_fb(&some_board_fb_info);
43
44=====================
45Video Attribute Flags
46=====================
47
48The ep93xxfb_mach_info structure has a flags field which can be used
49to configure the controller. The video attributes flags are fully
50documented in section 7 of the EP93xx users' guide. The following
51flags are available:
52
53EP93XXFB_PCLK_FALLING Clock data on the falling edge of the
54 pixel clock. The default is to clock
55 data on the rising edge.
56
57EP93XXFB_SYNC_BLANK_HIGH Blank signal is active high. By
58 default the blank signal is active low.
59
60EP93XXFB_SYNC_HORIZ_HIGH Horizontal sync is active high. By
61 default the horizontal sync is active low.
62
63EP93XXFB_SYNC_VERT_HIGH Vertical sync is active high. By
64 default the vertical sync is active high.
65
66The physical address of the framebuffer can be controlled using the
67following flags:
68
69EP93XXFB_USE_SDCSN0 Use SDCSn[0] for the framebuffer. This
70 is the default setting.
71
72EP93XXFB_USE_SDCSN1 Use SDCSn[1] for the framebuffer.
73
74EP93XXFB_USE_SDCSN2 Use SDCSn[2] for the framebuffer.
75
76EP93XXFB_USE_SDCSN3 Use SDCSn[3] for the framebuffer.
77
78==================
79Platform callbacks
80==================
81
82The EP93xx framebuffer driver supports three optional platform
83callbacks: setup, teardown and blank. The setup and teardown functions
84are called when the framebuffer driver is installed and removed
85respectively. The blank function is called whenever the display is
86blanked or unblanked.
87
88The setup and teardown devices pass the platform_device structure as
89an argument. The fb_info and ep93xxfb_mach_info structures can be
90obtained as follows:
91
92 static int some_board_fb_setup(struct platform_device *pdev)
93 {
94 struct ep93xxfb_mach_info *mach_info = pdev->dev.platform_data;
95 struct fb_info *fb_info = platform_get_drvdata(pdev);
96
97 /* Board specific framebuffer setup */
98 }
99
100======================
101Setting the video mode
102======================
103
104The video mode is set using the following syntax:
105
106 video=XRESxYRES[-BPP][@REFRESH]
107
108If the EP93xx video driver is built-in then the video mode is set on
109the Linux kernel command line, for example:
110
111 video=ep93xx-fb:800x600-16@60
112
113If the EP93xx video driver is built as a module then the video mode is
114set when the module is installed:
115
116 modprobe ep93xx-fb video=320x240
117
118==============
119Screenpage bug
120==============
121
122At least on the EP9315 there is a silicon bug which causes bit 27 of
123the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is
124an unofficial errata for this bug at:
125 http://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2
126
127By default the EP93xx framebuffer driver checks if the allocated physical
128address has bit 27 set. If it does, then the memory is freed and an
129error is returned. The check can be disabled by adding the following
130option when loading the driver:
131
132 ep93xx-fb.check_screenpage_bug=0
133
134In some cases it may be possible to reconfigure your SDRAM layout to
135avoid this bug. See section 13 of the EP93xx users' guide for details.
diff --git a/Documentation/fb/matroxfb.txt b/Documentation/fb/matroxfb.txt
index ad7a67707d62..e5ce8a1a978b 100644
--- a/Documentation/fb/matroxfb.txt
+++ b/Documentation/fb/matroxfb.txt
@@ -186,9 +186,7 @@ noinverse - show true colors on screen. It is default.
186dev:X - bind driver to device X. Driver numbers device from 0 up to N, 186dev:X - bind driver to device X. Driver numbers device from 0 up to N,
187 where device 0 is first `known' device found, 1 second and so on. 187 where device 0 is first `known' device found, 1 second and so on.
188 lspci lists devices in this order. 188 lspci lists devices in this order.
189 Default is `every' known device for driver with multihead support 189 Default is `every' known device.
190 and first working device (usually dev:0) for driver without
191 multihead support.
192nohwcursor - disables hardware cursor (use software cursor instead). 190nohwcursor - disables hardware cursor (use software cursor instead).
193hwcursor - enables hardware cursor. It is default. If you are using 191hwcursor - enables hardware cursor. It is default. If you are using
194 non-accelerated mode (`noaccel' or `fbset -accel false'), software 192 non-accelerated mode (`noaccel' or `fbset -accel false'), software
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt
index 503d21216d58..89a47b5aff07 100644
--- a/Documentation/feature-removal-schedule.txt
+++ b/Documentation/feature-removal-schedule.txt
@@ -354,14 +354,6 @@ Who: Krzysztof Piotr Oledzki <ole@ans.pl>
354 354
355--------------------------- 355---------------------------
356 356
357What: fscher and fscpos drivers
358When: June 2009
359Why: Deprecated by the new fschmd driver.
360Who: Hans de Goede <hdegoede@redhat.com>
361 Jean Delvare <khali@linux-fr.org>
362
363---------------------------
364
365What: sysfs ui for changing p4-clockmod parameters 357What: sysfs ui for changing p4-clockmod parameters
366When: September 2009 358When: September 2009
367Why: See commits 129f8ae9b1b5be94517da76009ea956e89104ce8 and 359Why: See commits 129f8ae9b1b5be94517da76009ea956e89104ce8 and
@@ -428,16 +420,6 @@ Who: Johannes Berg <johannes@sipsolutions.net>
428 420
429---------------------------- 421----------------------------
430 422
431What: CONFIG_X86_OLD_MCE
432When: 2.6.32
433Why: Remove the old legacy 32bit machine check code. This has been
434 superseded by the newer machine check code from the 64bit port,
435 but the old version has been kept around for easier testing. Note this
436 doesn't impact the old P5 and WinChip machine check handlers.
437Who: Andi Kleen <andi@firstfloor.org>
438
439----------------------------
440
441What: lock_policy_rwsem_* and unlock_policy_rwsem_* will not be 423What: lock_policy_rwsem_* and unlock_policy_rwsem_* will not be
442 exported interface anymore. 424 exported interface anymore.
443When: 2.6.33 425When: 2.6.33
diff --git a/Documentation/filesystems/9p.txt b/Documentation/filesystems/9p.txt
index 6208f55c44c3..57e0b80a5274 100644
--- a/Documentation/filesystems/9p.txt
+++ b/Documentation/filesystems/9p.txt
@@ -18,11 +18,11 @@ the 9p client is available in the form of a USENIX paper:
18 18
19Other applications are described in the following papers: 19Other applications are described in the following papers:
20 * XCPU & Clustering 20 * XCPU & Clustering
21 http://www.xcpu.org/xcpu-talk.pdf 21 http://xcpu.org/papers/xcpu-talk.pdf
22 * KVMFS: control file system for KVM 22 * KVMFS: control file system for KVM
23 http://www.xcpu.org/kvmfs.pdf 23 http://xcpu.org/papers/kvmfs.pdf
24 * CellFS: A New ProgrammingModel for the Cell BE 24 * CellFS: A New Programming Model for the Cell BE
25 http://www.xcpu.org/cellfs-talk.pdf 25 http://xcpu.org/papers/cellfs-talk.pdf
26 * PROSE I/O: Using 9p to enable Application Partitions 26 * PROSE I/O: Using 9p to enable Application Partitions
27 http://plan9.escet.urjc.es/iwp9/cready/PROSE_iwp9_2006.pdf 27 http://plan9.escet.urjc.es/iwp9/cready/PROSE_iwp9_2006.pdf
28 28
@@ -48,6 +48,7 @@ OPTIONS
48 (see rfdno and wfdno) 48 (see rfdno and wfdno)
49 virtio - connect to the next virtio channel available 49 virtio - connect to the next virtio channel available
50 (from lguest or KVM with trans_virtio module) 50 (from lguest or KVM with trans_virtio module)
51 rdma - connect to a specified RDMA channel
51 52
52 uname=name user name to attempt mount as on the remote server. The 53 uname=name user name to attempt mount as on the remote server. The
53 server may override or ignore this value. Certain user 54 server may override or ignore this value. Certain user
@@ -59,16 +60,22 @@ OPTIONS
59 cache=mode specifies a caching policy. By default, no caches are used. 60 cache=mode specifies a caching policy. By default, no caches are used.
60 loose = no attempts are made at consistency, 61 loose = no attempts are made at consistency,
61 intended for exclusive, read-only mounts 62 intended for exclusive, read-only mounts
63 fscache = use FS-Cache for a persistent, read-only
64 cache backend.
62 65
63 debug=n specifies debug level. The debug level is a bitmask. 66 debug=n specifies debug level. The debug level is a bitmask.
64 0x01 = display verbose error messages 67 0x01 = display verbose error messages
65 0x02 = developer debug (DEBUG_CURRENT) 68 0x02 = developer debug (DEBUG_CURRENT)
66 0x04 = display 9p trace 69 0x04 = display 9p trace
67 0x08 = display VFS trace 70 0x08 = display VFS trace
68 0x10 = display Marshalling debug 71 0x10 = display Marshalling debug
69 0x20 = display RPC debug 72 0x20 = display RPC debug
70 0x40 = display transport debug 73 0x40 = display transport debug
71 0x80 = display allocation debug 74 0x80 = display allocation debug
75 0x100 = display protocol message debug
76 0x200 = display Fid debug
77 0x400 = display packet debug
78 0x800 = display fscache tracing debug
72 79
73 rfdno=n the file descriptor for reading with trans=fd 80 rfdno=n the file descriptor for reading with trans=fd
74 81
@@ -100,6 +107,10 @@ OPTIONS
100 any = v9fs does single attach and performs all 107 any = v9fs does single attach and performs all
101 operations as one user 108 operations as one user
102 109
110 cachetag cache tag to use the specified persistent cache.
111 cache tags for existing cache sessions can be listed at
112 /sys/fs/9p/caches. (applies only to cache=fscache)
113
103RESOURCES 114RESOURCES
104========= 115=========
105 116
@@ -118,7 +129,7 @@ and export.
118A Linux version of the 9p server is now maintained under the npfs project 129A Linux version of the 9p server is now maintained under the npfs project
119on sourceforge (http://sourceforge.net/projects/npfs). The currently 130on sourceforge (http://sourceforge.net/projects/npfs). The currently
120maintained version is the single-threaded version of the server (named spfs) 131maintained version is the single-threaded version of the server (named spfs)
121available from the same CVS repository. 132available from the same SVN repository.
122 133
123There are user and developer mailing lists available through the v9fs project 134There are user and developer mailing lists available through the v9fs project
124on sourceforge (http://sourceforge.net/projects/v9fs). 135on sourceforge (http://sourceforge.net/projects/v9fs).
@@ -126,7 +137,8 @@ on sourceforge (http://sourceforge.net/projects/v9fs).
126A stand-alone version of the module (which should build for any 2.6 kernel) 137A stand-alone version of the module (which should build for any 2.6 kernel)
127is available via (http://github.com/ericvh/9p-sac/tree/master) 138is available via (http://github.com/ericvh/9p-sac/tree/master)
128 139
129News and other information is maintained on SWiK (http://swik.net/v9fs). 140News and other information is maintained on SWiK (http://swik.net/v9fs)
141and the Wiki (http://sf.net/apps/mediawiki/v9fs/index.php).
130 142
131Bug reports may be issued through the kernel.org bugzilla 143Bug reports may be issued through the kernel.org bugzilla
132(http://bugzilla.kernel.org) 144(http://bugzilla.kernel.org)
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
137journal_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
142journal_async_commit Commit block can be written to disk without waiting 137journal_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
147journal=update Update the ext4 file system's journal to the current 141journal=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
264sb=n Use alternate superblock at this location. 258sb=n Use alternate superblock at this location.
265 259
266quota 260quota These options are ignored by the filesystem. They
267noquota 261noquota are used only by quota tools to recognize volumes
268grpquota 262grpquota where quota should be turned on. See documentation
269usrquota 263usrquota in the quota-tools package for more details
264 (http://sourceforge.net/projects/linuxquota).
265
266jqfmt=<quota type> These options tell filesystem details about quota
267usrjquota=<file> so that quota information can be properly updated
268grpjquota=<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
271bh (*) ext4 associates buffer heads to data pages to 273bh (*) ext4 associates buffer heads to data pages to
272nobh (a) cache disk block mapping information 274nobh (a) cache disk block mapping information
diff --git a/Documentation/filesystems/ncpfs.txt b/Documentation/filesystems/ncpfs.txt
index f12c30c93f2f..5af164f4b37b 100644
--- a/Documentation/filesystems/ncpfs.txt
+++ b/Documentation/filesystems/ncpfs.txt
@@ -7,6 +7,6 @@ ftp.gwdg.de/pub/linux/misc/ncpfs, but sunsite and its many mirrors
7will have it as well. 7will have it as well.
8 8
9Related products are linware and mars_nwe, which will give Linux partial 9Related products are linware and mars_nwe, which will give Linux partial
10NetWare server functionality. Linware's home site is 10NetWare server functionality.
11klokan.sh.cvut.cz/pub/linux/linware; mars_nwe can be found on 11
12ftp.gwdg.de/pub/linux/misc/ncpfs. 12mars_nwe can be found on ftp.gwdg.de/pub/linux/misc/ncpfs.
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
11control file, the nfsd service must be taken down. Use your user-mode 11control file, the nfsd service must be taken down. Use your user-mode
12nfs-utils to set this up; see rpc.nfsd(8) 12nfs-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
16kernels must turn 4.1 on or off *before* turning support for version 4
17on or off; rpc.nfsd does this correctly.)
18
14The NFSv4 minorversion 1 (NFSv4.1) implementation in nfsd is based 19The NFSv4 minorversion 1 (NFSv4.1) implementation in nfsd is based
15on the latest NFSv4.1 Internet Draft: 20on the latest NFSv4.1 Internet Draft:
16http://tools.ietf.org/html/draft-ietf-nfsv4-minorversion1-29 21http://tools.ietf.org/html/draft-ietf-nfsv4-minorversion1-29
@@ -25,6 +30,49 @@ are still under development out of tree.
25See http://wiki.linux-nfs.org/wiki/index.php/PNFS_prototype_design 30See http://wiki.linux-nfs.org/wiki/index.php/PNFS_prototype_design
26for more information. 31for more information.
27 32
33The current implementation is intended for developers only: while it
34does support ordinary file operations on clients we have tested against
35(including the linux client), it is incomplete in ways which may limit
36features unexpectedly, cause known bugs in rare cases, or cause
37interoperability 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
69In addition, some limitations are inherited from the current NFSv4
70implementation:
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
28The table below, taken from the NFSv4.1 document, lists 76The table below, taken from the NFSv4.1 document, lists
29the operations that are mandatory to implement (REQ), optional 77the 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
143Implementation notes: 191Implementation notes:
144 192
193DELEGPURGE:
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
145EXCHANGE_ID: 199EXCHANGE_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 ffead13f9443..b5aee7838a00 100644
--- a/Documentation/filesystems/proc.txt
+++ b/Documentation/filesystems/proc.txt
@@ -176,6 +176,7 @@ read the file /proc/PID/status:
176 CapBnd: ffffffffffffffff 176 CapBnd: ffffffffffffffff
177 voluntary_ctxt_switches: 0 177 voluntary_ctxt_switches: 0
178 nonvoluntary_ctxt_switches: 1 178 nonvoluntary_ctxt_switches: 1
179 Stack usage: 12 kB
179 180
180This shows you nearly the same information you would get if you viewed it with 181This shows you nearly the same information you would get if you viewed it with
181the ps command. In fact, ps uses the proc file system to obtain its 182the ps command. In fact, ps uses the proc file system to obtain its
@@ -229,6 +230,7 @@ Table 1-2: Contents of the statm files (as of 2.6.30-rc7)
229 Mems_allowed_list Same as previous, but in "list format" 230 Mems_allowed_list Same as previous, but in "list format"
230 voluntary_ctxt_switches number of voluntary context switches 231 voluntary_ctxt_switches number of voluntary context switches
231 nonvoluntary_ctxt_switches number of non voluntary context switches 232 nonvoluntary_ctxt_switches number of non voluntary context switches
233 Stack usage: stack usage high water mark (round up to page size)
232.............................................................................. 234..............................................................................
233 235
234Table 1-3: Contents of the statm files (as of 2.6.8-rc3) 236Table 1-3: Contents of the statm files (as of 2.6.8-rc3)
@@ -307,7 +309,7 @@ address perms offset dev inode pathname
30708049000-0804a000 rw-p 00001000 03:00 8312 /opt/test 30908049000-0804a000 rw-p 00001000 03:00 8312 /opt/test
3080804a000-0806b000 rw-p 00000000 00:00 0 [heap] 3100804a000-0806b000 rw-p 00000000 00:00 0 [heap]
309a7cb1000-a7cb2000 ---p 00000000 00:00 0 311a7cb1000-a7cb2000 ---p 00000000 00:00 0
310a7cb2000-a7eb2000 rw-p 00000000 00:00 0 312a7cb2000-a7eb2000 rw-p 00000000 00:00 0 [threadstack:001ff4b4]
311a7eb2000-a7eb3000 ---p 00000000 00:00 0 313a7eb2000-a7eb3000 ---p 00000000 00:00 0
312a7eb3000-a7ed5000 rw-p 00000000 00:00 0 314a7eb3000-a7ed5000 rw-p 00000000 00:00 0
313a7ed5000-a8008000 r-xp 00000000 03:00 4222 /lib/libc.so.6 315a7ed5000-a8008000 r-xp 00000000 03:00 4222 /lib/libc.so.6
@@ -343,6 +345,7 @@ is not associated with a file:
343 [stack] = the stack of the main process 345 [stack] = the stack of the main process
344 [vdso] = the "virtual dynamic shared object", 346 [vdso] = the "virtual dynamic shared object",
345 the kernel system call handler 347 the kernel system call handler
348 [threadstack:xxxxxxxx] = the stack of the thread, xxxxxxxx is the stack size
346 349
347 or if empty, the mapping is anonymous. 350 or if empty, the mapping is anonymous.
348 351
@@ -375,6 +378,19 @@ of memory currently marked as referenced or accessed.
375This file is only present if the CONFIG_MMU kernel configuration option is 378This file is only present if the CONFIG_MMU kernel configuration option is
376enabled. 379enabled.
377 380
381The /proc/PID/clear_refs is used to reset the PG_Referenced and ACCESSED/YOUNG
382bits on both physical and virtual pages associated with a process.
383To clear the bits for all the pages associated with the process
384 > echo 1 > /proc/PID/clear_refs
385
386To clear the bits for the anonymous pages associated with the process
387 > echo 2 > /proc/PID/clear_refs
388
389To clear the bits for the file mapped pages associated with the process
390 > echo 3 > /proc/PID/clear_refs
391Any other value written to /proc/PID/clear_refs will have no effect.
392
393
3781.2 Kernel data 3941.2 Kernel data
379--------------- 395---------------
380 396
@@ -1032,9 +1048,9 @@ Various pieces of information about kernel activity are available in the
1032since the system first booted. For a quick look, simply cat the file: 1048since the system first booted. For a quick look, simply cat the file:
1033 1049
1034 > cat /proc/stat 1050 > cat /proc/stat
1035 cpu 2255 34 2290 22625563 6290 127 456 0 1051 cpu 2255 34 2290 22625563 6290 127 456 0 0
1036 cpu0 1132 34 1441 11311718 3675 127 438 0 1052 cpu0 1132 34 1441 11311718 3675 127 438 0 0
1037 cpu1 1123 0 849 11313845 2614 0 18 0 1053 cpu1 1123 0 849 11313845 2614 0 18 0 0
1038 intr 114930548 113199788 3 0 5 263 0 4 [... lots more numbers ...] 1054 intr 114930548 113199788 3 0 5 263 0 4 [... lots more numbers ...]
1039 ctxt 1990473 1055 ctxt 1990473
1040 btime 1062191376 1056 btime 1062191376
@@ -1056,6 +1072,7 @@ second). The meanings of the columns are as follows, from left to right:
1056- irq: servicing interrupts 1072- irq: servicing interrupts
1057- softirq: servicing softirqs 1073- softirq: servicing softirqs
1058- steal: involuntary wait 1074- steal: involuntary wait
1075- guest: running a guest
1059 1076
1060The "intr" line gives counts of interrupts serviced since boot time, for each 1077The "intr" line gives counts of interrupts serviced since boot time, for each
1061of the possible system interrupts. The first column is the total of all 1078of the possible system interrupts. The first column is the total of all
@@ -1191,7 +1208,7 @@ The following heuristics are then applied:
1191 * if the task was reniced, its score doubles 1208 * if the task was reniced, its score doubles
1192 * superuser or direct hardware access tasks (CAP_SYS_ADMIN, CAP_SYS_RESOURCE 1209 * superuser or direct hardware access tasks (CAP_SYS_ADMIN, CAP_SYS_RESOURCE
1193 or CAP_SYS_RAWIO) have their score divided by 4 1210 or CAP_SYS_RAWIO) have their score divided by 4
1194 * if oom condition happened in one cpuset and checked task does not belong 1211 * if oom condition happened in one cpuset and checked process does not belong
1195 to it, its score is divided by 8 1212 to it, its score is divided by 8
1196 * the resulting score is multiplied by two to the power of oom_adj, i.e. 1213 * the resulting score is multiplied by two to the power of oom_adj, i.e.
1197 points <<= oom_adj when it is positive and 1214 points <<= oom_adj when it is positive and
diff --git a/Documentation/filesystems/sharedsubtree.txt b/Documentation/filesystems/sharedsubtree.txt
index 736540045dc7..23a181074f94 100644
--- a/Documentation/filesystems/sharedsubtree.txt
+++ b/Documentation/filesystems/sharedsubtree.txt
@@ -4,7 +4,7 @@ Shared Subtrees
4Contents: 4Contents:
5 1) Overview 5 1) Overview
6 2) Features 6 2) Features
7 3) smount command 7 3) Setting mount states
8 4) Use-case 8 4) Use-case
9 5) Detailed semantics 9 5) Detailed semantics
10 6) Quiz 10 6) Quiz
@@ -41,14 +41,14 @@ replicas continue to be exactly same.
41 41
42 Here is an example: 42 Here is an example:
43 43
44 Lets say /mnt has a mount that is shared. 44 Let's say /mnt has a mount that is shared.
45 mount --make-shared /mnt 45 mount --make-shared /mnt
46 46
47 note: mount command does not yet support the --make-shared flag. 47 Note: mount(8) command now supports the --make-shared flag,
48 I have included a small C program which does the same by executing 48 so the sample 'smount' program is no longer needed and has been
49 'smount /mnt shared' 49 removed.
50 50
51 #mount --bind /mnt /tmp 51 # mount --bind /mnt /tmp
52 The above command replicates the mount at /mnt to the mountpoint /tmp 52 The above command replicates the mount at /mnt to the mountpoint /tmp
53 and the contents of both the mounts remain identical. 53 and the contents of both the mounts remain identical.
54 54
@@ -58,8 +58,8 @@ replicas continue to be exactly same.
58 #ls /tmp 58 #ls /tmp
59 a b c 59 a b c
60 60
61 Now lets say we mount a device at /tmp/a 61 Now let's say we mount a device at /tmp/a
62 #mount /dev/sd0 /tmp/a 62 # mount /dev/sd0 /tmp/a
63 63
64 #ls /tmp/a 64 #ls /tmp/a
65 t1 t2 t2 65 t1 t2 t2
@@ -80,21 +80,20 @@ replicas continue to be exactly same.
80 80
81 Here is an example: 81 Here is an example:
82 82
83 Lets say /mnt has a mount which is shared. 83 Let's say /mnt has a mount which is shared.
84 #mount --make-shared /mnt 84 # mount --make-shared /mnt
85 85
86 Lets bind mount /mnt to /tmp 86 Let's bind mount /mnt to /tmp
87 #mount --bind /mnt /tmp 87 # mount --bind /mnt /tmp
88 88
89 the new mount at /tmp becomes a shared mount and it is a replica of 89 the new mount at /tmp becomes a shared mount and it is a replica of
90 the mount at /mnt. 90 the mount at /mnt.
91 91
92 Now lets make the mount at /tmp; a slave of /mnt 92 Now let's make the mount at /tmp; a slave of /mnt
93 #mount --make-slave /tmp 93 # mount --make-slave /tmp
94 [or smount /tmp slave]
95 94
96 lets mount /dev/sd0 on /mnt/a 95 let's mount /dev/sd0 on /mnt/a
97 #mount /dev/sd0 /mnt/a 96 # mount /dev/sd0 /mnt/a
98 97
99 #ls /mnt/a 98 #ls /mnt/a
100 t1 t2 t3 99 t1 t2 t3
@@ -104,9 +103,9 @@ replicas continue to be exactly same.
104 103
105 Note the mount event has propagated to the mount at /tmp 104 Note the mount event has propagated to the mount at /tmp
106 105
107 However lets see what happens if we mount something on the mount at /tmp 106 However let's see what happens if we mount something on the mount at /tmp
108 107
109 #mount /dev/sd1 /tmp/b 108 # mount /dev/sd1 /tmp/b
110 109
111 #ls /tmp/b 110 #ls /tmp/b
112 s1 s2 s3 111 s1 s2 s3
@@ -124,12 +123,11 @@ replicas continue to be exactly same.
124 123
1252d) A unbindable mount is a unbindable private mount 1242d) A unbindable mount is a unbindable private mount
126 125
127 lets say we have a mount at /mnt and we make is unbindable 126 let's say we have a mount at /mnt and we make is unbindable
128 127
129 #mount --make-unbindable /mnt 128 # mount --make-unbindable /mnt
130 [ smount /mnt unbindable ]
131 129
132 Lets try to bind mount this mount somewhere else. 130 Let's try to bind mount this mount somewhere else.
133 # mount --bind /mnt /tmp 131 # mount --bind /mnt /tmp
134 mount: wrong fs type, bad option, bad superblock on /mnt, 132 mount: wrong fs type, bad option, bad superblock on /mnt,
135 or too many mounted file systems 133 or too many mounted file systems
@@ -137,149 +135,15 @@ replicas continue to be exactly same.
137 Binding a unbindable mount is a invalid operation. 135 Binding a unbindable mount is a invalid operation.
138 136
139 137
1403) smount command 1383) Setting mount states
141 139
142 Currently the mount command is not aware of shared subtree features. 140 The mount command (util-linux package) can be used to set mount
143 Work is in progress to add the support in mount ( util-linux package ). 141 states:
144 Till then use the following program.
145 142
146 ------------------------------------------------------------------------ 143 mount --make-shared mountpoint
147 // 144 mount --make-slave mountpoint
148 //this code was developed my Miklos Szeredi <miklos@szeredi.hu> 145 mount --make-private mountpoint
149 //and modified by Ram Pai <linuxram@us.ibm.com> 146 mount --make-unbindable mountpoint
150 // sample usage:
151 // smount /tmp shared
152 //
153 #include <stdio.h>
154 #include <stdlib.h>
155 #include <unistd.h>
156 #include <string.h>
157 #include <sys/mount.h>
158 #include <sys/fsuid.h>
159
160 #ifndef MS_REC
161 #define MS_REC 0x4000 /* 16384: Recursive loopback */
162 #endif
163
164 #ifndef MS_SHARED
165 #define MS_SHARED 1<<20 /* Shared */
166 #endif
167
168 #ifndef MS_PRIVATE
169 #define MS_PRIVATE 1<<18 /* Private */
170 #endif
171
172 #ifndef MS_SLAVE
173 #define MS_SLAVE 1<<19 /* Slave */
174 #endif
175
176 #ifndef MS_UNBINDABLE
177 #define MS_UNBINDABLE 1<<17 /* Unbindable */
178 #endif
179
180 int main(int argc, char *argv[])
181 {
182 int type;
183 if(argc != 3) {
184 fprintf(stderr, "usage: %s dir "
185 "<rshared|rslave|rprivate|runbindable|shared|slave"
186 "|private|unbindable>\n" , argv[0]);
187 return 1;
188 }
189
190 fprintf(stdout, "%s %s %s\n", argv[0], argv[1], argv[2]);
191
192 if (strcmp(argv[2],"rshared")==0)
193 type=(MS_SHARED|MS_REC);
194 else if (strcmp(argv[2],"rslave")==0)
195 type=(MS_SLAVE|MS_REC);
196 else if (strcmp(argv[2],"rprivate")==0)
197 type=(MS_PRIVATE|MS_REC);
198 else if (strcmp(argv[2],"runbindable")==0)
199 type=(MS_UNBINDABLE|MS_REC);
200 else if (strcmp(argv[2],"shared")==0)
201 type=MS_SHARED;
202 else if (strcmp(argv[2],"slave")==0)
203 type=MS_SLAVE;
204 else if (strcmp(argv[2],"private")==0)
205 type=MS_PRIVATE;
206 else if (strcmp(argv[2],"unbindable")==0)
207 type=MS_UNBINDABLE;
208 else {
209 fprintf(stderr, "invalid operation: %s\n", argv[2]);
210 return 1;
211 }
212 setfsuid(getuid());
213
214 if(mount("", argv[1], "dontcare", type, "") == -1) {
215 perror("mount");
216 return 1;
217 }
218 return 0;
219 }
220 -----------------------------------------------------------------------
221
222 Copy the above code snippet into smount.c
223 gcc -o smount smount.c
224
225
226 (i) To mark all the mounts under /mnt as shared execute the following
227 command:
228
229 smount /mnt rshared
230 the corresponding syntax planned for mount command is
231 mount --make-rshared /mnt
232
233 just to mark a mount /mnt as shared, execute the following
234 command:
235 smount /mnt shared
236 the corresponding syntax planned for mount command is
237 mount --make-shared /mnt
238
239 (ii) To mark all the shared mounts under /mnt as slave execute the
240 following
241
242 command:
243 smount /mnt rslave
244 the corresponding syntax planned for mount command is
245 mount --make-rslave /mnt
246
247 just to mark a mount /mnt as slave, execute the following
248 command:
249 smount /mnt slave
250 the corresponding syntax planned for mount command is
251 mount --make-slave /mnt
252
253 (iii) To mark all the mounts under /mnt as private execute the
254 following command:
255
256 smount /mnt rprivate
257 the corresponding syntax planned for mount command is
258 mount --make-rprivate /mnt
259
260 just to mark a mount /mnt as private, execute the following
261 command:
262 smount /mnt private
263 the corresponding syntax planned for mount command is
264 mount --make-private /mnt
265
266 NOTE: by default all the mounts are created as private. But if
267 you want to change some shared/slave/unbindable mount as
268 private at a later point in time, this command can help.
269
270 (iv) To mark all the mounts under /mnt as unbindable execute the
271 following
272
273 command:
274 smount /mnt runbindable
275 the corresponding syntax planned for mount command is
276 mount --make-runbindable /mnt
277
278 just to mark a mount /mnt as unbindable, execute the following
279 command:
280 smount /mnt unbindable
281 the corresponding syntax planned for mount command is
282 mount --make-unbindable /mnt
283 147
284 148
2854) Use cases 1494) Use cases
@@ -350,7 +214,7 @@ replicas continue to be exactly same.
350 mount --rbind / /view/v3 214 mount --rbind / /view/v3
351 mount --rbind / /view/v4 215 mount --rbind / /view/v4
352 216
353 and if /usr has a versioning filesystem mounted, than that 217 and if /usr has a versioning filesystem mounted, then that
354 mount appears at /view/v1/usr, /view/v2/usr, /view/v3/usr and 218 mount appears at /view/v1/usr, /view/v2/usr, /view/v3/usr and
355 /view/v4/usr too 219 /view/v4/usr too
356 220
@@ -390,7 +254,7 @@ replicas continue to be exactly same.
390 254
391 For example: 255 For example:
392 mount --make-shared /mnt 256 mount --make-shared /mnt
393 mount --bin /mnt /tmp 257 mount --bind /mnt /tmp
394 258
395 The mount at /mnt and that at /tmp are both shared and belong 259 The mount at /mnt and that at /tmp are both shared and belong
396 to the same peer group. Anything mounted or unmounted under 260 to the same peer group. Anything mounted or unmounted under
@@ -558,7 +422,7 @@ replicas continue to be exactly same.
558 then the subtree under the unbindable mount is pruned in the new 422 then the subtree under the unbindable mount is pruned in the new
559 location. 423 location.
560 424
561 eg: lets say we have the following mount tree. 425 eg: let's say we have the following mount tree.
562 426
563 A 427 A
564 / \ 428 / \
@@ -566,7 +430,7 @@ replicas continue to be exactly same.
566 / \ / \ 430 / \ / \
567 D E F G 431 D E F G
568 432
569 Lets say all the mount except the mount C in the tree are 433 Let's say all the mount except the mount C in the tree are
570 of a type other than unbindable. 434 of a type other than unbindable.
571 435
572 If this tree is rbound to say Z 436 If this tree is rbound to say Z
@@ -683,13 +547,13 @@ replicas continue to be exactly same.
683 'b' on mounts that receive propagation from mount 'B' and does not have 547 'b' on mounts that receive propagation from mount 'B' and does not have
684 sub-mounts within them are unmounted. 548 sub-mounts within them are unmounted.
685 549
686 Example: Lets say 'B1', 'B2', 'B3' are shared mounts that propagate to 550 Example: Let's say 'B1', 'B2', 'B3' are shared mounts that propagate to
687 each other. 551 each other.
688 552
689 lets say 'A1', 'A2', 'A3' are first mounted at dentry 'b' on mount 553 let's say 'A1', 'A2', 'A3' are first mounted at dentry 'b' on mount
690 'B1', 'B2' and 'B3' respectively. 554 'B1', 'B2' and 'B3' respectively.
691 555
692 lets say 'C1', 'C2', 'C3' are next mounted at the same dentry 'b' on 556 let's say 'C1', 'C2', 'C3' are next mounted at the same dentry 'b' on
693 mount 'B1', 'B2' and 'B3' respectively. 557 mount 'B1', 'B2' and 'B3' respectively.
694 558
695 if 'C1' is unmounted, all the mounts that are most-recently-mounted on 559 if 'C1' is unmounted, all the mounts that are most-recently-mounted on
@@ -710,7 +574,7 @@ replicas continue to be exactly same.
710 A cloned namespace contains all the mounts as that of the parent 574 A cloned namespace contains all the mounts as that of the parent
711 namespace. 575 namespace.
712 576
713 Lets say 'A' and 'B' are the corresponding mounts in the parent and the 577 Let's say 'A' and 'B' are the corresponding mounts in the parent and the
714 child namespace. 578 child namespace.
715 579
716 If 'A' is shared, then 'B' is also shared and 'A' and 'B' propagate to 580 If 'A' is shared, then 'B' is also shared and 'A' and 'B' propagate to
@@ -759,11 +623,11 @@ replicas continue to be exactly same.
759 mount --make-slave /mnt 623 mount --make-slave /mnt
760 624
761 At this point we have the first mount at /tmp and 625 At this point we have the first mount at /tmp and
762 its root dentry is 1. Lets call this mount 'A' 626 its root dentry is 1. Let's call this mount 'A'
763 And then we have a second mount at /tmp1 with root 627 And then we have a second mount at /tmp1 with root
764 dentry 2. Lets call this mount 'B' 628 dentry 2. Let's call this mount 'B'
765 Next we have a third mount at /mnt with root dentry 629 Next we have a third mount at /mnt with root dentry
766 mnt. Lets call this mount 'C' 630 mnt. Let's call this mount 'C'
767 631
768 'B' is the slave of 'A' and 'C' is a slave of 'B' 632 'B' is the slave of 'A' and 'C' is a slave of 'B'
769 A -> B -> C 633 A -> B -> C
@@ -794,7 +658,7 @@ replicas continue to be exactly same.
794 658
795 Q3 Why is unbindable mount needed? 659 Q3 Why is unbindable mount needed?
796 660
797 Lets say we want to replicate the mount tree at multiple 661 Let's say we want to replicate the mount tree at multiple
798 locations within the same subtree. 662 locations within the same subtree.
799 663
800 if one rbind mounts a tree within the same subtree 'n' times 664 if one rbind mounts a tree within the same subtree 'n' times
@@ -803,7 +667,7 @@ replicas continue to be exactly same.
803 mounts. Here is a example. 667 mounts. Here is a example.
804 668
805 step 1: 669 step 1:
806 lets say the root tree has just two directories with 670 let's say the root tree has just two directories with
807 one vfsmount. 671 one vfsmount.
808 root 672 root
809 / \ 673 / \
@@ -875,7 +739,7 @@ replicas continue to be exactly same.
875 Unclonable mounts come in handy here. 739 Unclonable mounts come in handy here.
876 740
877 step 1: 741 step 1:
878 lets say the root tree has just two directories with 742 let's say the root tree has just two directories with
879 one vfsmount. 743 one vfsmount.
880 root 744 root
881 / \ 745 / \
diff --git a/Documentation/gcov.txt b/Documentation/gcov.txt
index 40ec63352760..e7ca6478cd93 100644
--- a/Documentation/gcov.txt
+++ b/Documentation/gcov.txt
@@ -47,7 +47,7 @@ Possible uses:
47 47
48Configure the kernel with: 48Configure 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
53and to get coverage data for the entire kernel: 53and to get coverage data for the entire kernel:
diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt
index e4b6985044a2..fa4dc077ae0e 100644
--- a/Documentation/gpio.txt
+++ b/Documentation/gpio.txt
@@ -524,6 +524,13 @@ and have the following read/write attributes:
524 is configured as an output, this value may be written; 524 is configured as an output, this value may be written;
525 any nonzero value is treated as high. 525 any nonzero value is treated as high.
526 526
527 "edge" ... reads as either "none", "rising", "falling", or
528 "both". Write these strings to select the signal edge(s)
529 that will make poll(2) on the "value" file return.
530
531 This file exists only if the pin can be configured as an
532 interrupt generating input pin.
533
527GPIO controllers have paths like /sys/class/gpio/chipchip42/ (for the 534GPIO controllers have paths like /sys/class/gpio/chipchip42/ (for the
528controller implementing GPIOs starting at #42) and have the following 535controller implementing GPIOs starting at #42) and have the following
529read-only attributes: 536read-only attributes:
@@ -555,6 +562,11 @@ requested using gpio_request():
555 /* reverse gpio_export() */ 562 /* reverse gpio_export() */
556 void gpio_unexport(); 563 void gpio_unexport();
557 564
565 /* create a sysfs link to an exported GPIO node */
566 int gpio_export_link(struct device *dev, const char *name,
567 unsigned gpio)
568
569
558After a kernel driver requests a GPIO, it may only be made available in 570After a kernel driver requests a GPIO, it may only be made available in
559the sysfs interface by gpio_export(). The driver can control whether the 571the sysfs interface by gpio_export(). The driver can control whether the
560signal direction may change. This helps drivers prevent userspace code 572signal direction may change. This helps drivers prevent userspace code
@@ -563,3 +575,8 @@ from accidentally clobbering important system state.
563This explicit exporting can help with debugging (by making some kinds 575This explicit exporting can help with debugging (by making some kinds
564of experiments easier), or can provide an always-there interface that's 576of experiments easier), or can provide an always-there interface that's
565suitable for documenting as part of a board support package. 577suitable for documenting as part of a board support package.
578
579After the GPIO has been exported, gpio_export_link() allows creating
580symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can
581use this to provide the interface under their own device in sysfs with
582a descriptive name.
diff --git a/Documentation/hwmon/acpi_power_meter b/Documentation/hwmon/acpi_power_meter
new file mode 100644
index 000000000000..c80399a00c50
--- /dev/null
+++ b/Documentation/hwmon/acpi_power_meter
@@ -0,0 +1,51 @@
1Kernel driver power_meter
2=========================
3
4This driver talks to ACPI 4.0 power meters.
5
6Supported systems:
7 * Any recent system with ACPI 4.0.
8 Prefix: 'power_meter'
9 Datasheet: http://acpi.info/, section 10.4.
10
11Author: Darrick J. Wong
12
13Description
14-----------
15
16This driver implements sensor reading support for the power meters exposed in
17the ACPI 4.0 spec (Chapter 10.4). These devices have a simple set of
18features--a power meter that returns average power use over a configurable
19interval, an optional capping mechanism, and a couple of trip points. The
20sysfs interface conforms with the specification outlined in the "Power" section
21of Documentation/hwmon/sysfs-interface.
22
23Special Features
24----------------
25
26The power[1-*]_is_battery knob indicates if the power supply is a battery.
27Both power[1-*]_average_{min,max} must be set before the trip points will work.
28When both of them are set, an ACPI event will be broadcast on the ACPI netlink
29socket and a poll notification will be sent to the appropriate
30power[1-*]_average sysfs file.
31
32The power[1-*]_{model_number, serial_number, oem_info} fields display arbitrary
33strings that ACPI provides with the meter. The measures/ directory contains
34symlinks to the devices that this meter measures.
35
36Some computers have the ability to enforce a power cap in hardware. If this is
37the case, the power[1-*]_cap and related sysfs files will appear. When the
38average power consumption exceeds the cap, an ACPI event will be broadcast on
39the netlink event socket and a poll notification will be sent to the
40appropriate power[1-*]_alarm file to indicate that capping has begun, and the
41hardware has taken action to reduce power consumption. Most likely this will
42result in reduced performance.
43
44There are a few other ACPI notifications that can be sent by the firmware. In
45all cases the ACPI event will be broadcast on the ACPI netlink event socket as
46well as sent as a poll notification to a sysfs file. The events are as
47follows:
48
49power[1-*]_cap will be notified if the firmware changes the power cap.
50power[1-*]_interval will be notified if the firmware changes the averaging
51interval.
diff --git a/Documentation/hwmon/coretemp b/Documentation/hwmon/coretemp
index dbbe6c7025b0..92267b62db59 100644
--- a/Documentation/hwmon/coretemp
+++ b/Documentation/hwmon/coretemp
@@ -4,7 +4,9 @@ Kernel driver coretemp
4Supported chips: 4Supported chips:
5 * All Intel Core family 5 * All Intel Core family
6 Prefix: 'coretemp' 6 Prefix: 'coretemp'
7 CPUID: family 0x6, models 0xe, 0xf, 0x16, 0x17 7 CPUID: family 0x6, models 0xe (Pentium M DC), 0xf (Core 2 DC 65nm),
8 0x16 (Core 2 SC 65nm), 0x17 (Penryn 45nm),
9 0x1a (Nehalem), 0x1c (Atom), 0x1e (Lynnfield)
8 Datasheet: Intel 64 and IA-32 Architectures Software Developer's Manual 10 Datasheet: Intel 64 and IA-32 Architectures Software Developer's Manual
9 Volume 3A: System Programming Guide 11 Volume 3A: System Programming Guide
10 http://softwarecommunity.intel.com/Wiki/Mobility/720.htm 12 http://softwarecommunity.intel.com/Wiki/Mobility/720.htm
diff --git a/Documentation/hwmon/fscher b/Documentation/hwmon/fscher
deleted file mode 100644
index 64031659aff3..000000000000
--- a/Documentation/hwmon/fscher
+++ /dev/null
@@ -1,169 +0,0 @@
1Kernel driver fscher
2====================
3
4Supported chips:
5 * Fujitsu-Siemens Hermes chip
6 Prefix: 'fscher'
7 Addresses scanned: I2C 0x73
8
9Authors:
10 Reinhard Nissl <rnissl@gmx.de> based on work
11 from Hermann Jung <hej@odn.de>,
12 Frodo Looijaard <frodol@dds.nl>,
13 Philip Edelbrock <phil@netroedge.com>
14
15Description
16-----------
17
18This driver implements support for the Fujitsu-Siemens Hermes chip. It is
19described in the 'Register Set Specification BMC Hermes based Systemboard'
20from Fujitsu-Siemens.
21
22The Hermes chip implements a hardware-based system management, e.g. for
23controlling fan speed and core voltage. There is also a watchdog counter on
24the chip which can trigger an alarm and even shut the system down.
25
26The chip provides three temperature values (CPU, motherboard and
27auxiliary), three voltage values (+12V, +5V and battery) and three fans
28(power supply, CPU and auxiliary).
29
30Temperatures are measured in degrees Celsius. The resolution is 1 degree.
31
32Fan rotation speeds are reported in RPM (rotations per minute). The value
33can be divided by a programmable divider (1, 2 or 4) which is stored on
34the chip.
35
36Voltage sensors (also known as "in" sensors) report their values in volts.
37
38All values are reported as final values from the driver. There is no need
39for further calculations.
40
41
42Detailed description
43--------------------
44
45Below you'll find a single line description of all the bit values. With
46this information, you're able to decode e. g. alarms, wdog, etc. To make
47use of the watchdog, you'll need to set the watchdog time and enable the
48watchdog. After that it is necessary to restart the watchdog time within
49the specified period of time, or a system reset will occur.
50
51* revision
52 READING & 0xff = 0x??: HERMES revision identification
53
54* alarms
55 READING & 0x80 = 0x80: CPU throttling active
56 READING & 0x80 = 0x00: CPU running at full speed
57
58 READING & 0x10 = 0x10: software event (see control:1)
59 READING & 0x10 = 0x00: no software event
60
61 READING & 0x08 = 0x08: watchdog event (see wdog:2)
62 READING & 0x08 = 0x00: no watchdog event
63
64 READING & 0x02 = 0x02: thermal event (see temp*:1)
65 READING & 0x02 = 0x00: no thermal event
66
67 READING & 0x01 = 0x01: fan event (see fan*:1)
68 READING & 0x01 = 0x00: no fan event
69
70 READING & 0x13 ! 0x00: ALERT LED is flashing
71
72* control
73 READING & 0x01 = 0x01: software event
74 READING & 0x01 = 0x00: no software event
75
76 WRITING & 0x01 = 0x01: set software event
77 WRITING & 0x01 = 0x00: clear software event
78
79* watchdog_control
80 READING & 0x80 = 0x80: power off on watchdog event while thermal event
81 READING & 0x80 = 0x00: watchdog power off disabled (just system reset enabled)
82
83 READING & 0x40 = 0x40: watchdog timebase 60 seconds (see also wdog:1)
84 READING & 0x40 = 0x00: watchdog timebase 2 seconds
85
86 READING & 0x10 = 0x10: watchdog enabled
87 READING & 0x10 = 0x00: watchdog disabled
88
89 WRITING & 0x80 = 0x80: enable "power off on watchdog event while thermal event"
90 WRITING & 0x80 = 0x00: disable "power off on watchdog event while thermal event"
91
92 WRITING & 0x40 = 0x40: set watchdog timebase to 60 seconds
93 WRITING & 0x40 = 0x00: set watchdog timebase to 2 seconds
94
95 WRITING & 0x20 = 0x20: disable watchdog
96
97 WRITING & 0x10 = 0x10: enable watchdog / restart watchdog time
98
99* watchdog_state
100 READING & 0x02 = 0x02: watchdog system reset occurred
101 READING & 0x02 = 0x00: no watchdog system reset occurred
102
103 WRITING & 0x02 = 0x02: clear watchdog event
104
105* watchdog_preset
106 READING & 0xff = 0x??: configured watch dog time in units (see wdog:3 0x40)
107
108 WRITING & 0xff = 0x??: configure watch dog time in units
109
110* in* (0: +5V, 1: +12V, 2: onboard 3V battery)
111 READING: actual voltage value
112
113* temp*_status (1: CPU sensor, 2: onboard sensor, 3: auxiliary sensor)
114 READING & 0x02 = 0x02: thermal event (overtemperature)
115 READING & 0x02 = 0x00: no thermal event
116
117 READING & 0x01 = 0x01: sensor is working
118 READING & 0x01 = 0x00: sensor is faulty
119
120 WRITING & 0x02 = 0x02: clear thermal event
121
122* temp*_input (1: CPU sensor, 2: onboard sensor, 3: auxiliary sensor)
123 READING: actual temperature value
124
125* fan*_status (1: power supply fan, 2: CPU fan, 3: auxiliary fan)
126 READING & 0x04 = 0x04: fan event (fan fault)
127 READING & 0x04 = 0x00: no fan event
128
129 WRITING & 0x04 = 0x04: clear fan event
130
131* fan*_div (1: power supply fan, 2: CPU fan, 3: auxiliary fan)
132 Divisors 2,4 and 8 are supported, both for reading and writing
133
134* fan*_pwm (1: power supply fan, 2: CPU fan, 3: auxiliary fan)
135 READING & 0xff = 0x00: fan may be switched off
136 READING & 0xff = 0x01: fan must run at least at minimum speed (supply: 6V)
137 READING & 0xff = 0xff: fan must run at maximum speed (supply: 12V)
138 READING & 0xff = 0x??: fan must run at least at given speed (supply: 6V..12V)
139
140 WRITING & 0xff = 0x00: fan may be switched off
141 WRITING & 0xff = 0x01: fan must run at least at minimum speed (supply: 6V)
142 WRITING & 0xff = 0xff: fan must run at maximum speed (supply: 12V)
143 WRITING & 0xff = 0x??: fan must run at least at given speed (supply: 6V..12V)
144
145* fan*_input (1: power supply fan, 2: CPU fan, 3: auxiliary fan)
146 READING: actual RPM value
147
148
149Limitations
150-----------
151
152* Measuring fan speed
153It seems that the chip counts "ripples" (typical fans produce 2 ripples per
154rotation while VERAX fans produce 18) in a 9-bit register. This register is
155read out every second, then the ripple prescaler (2, 4 or 8) is applied and
156the result is stored in the 8 bit output register. Due to the limitation of
157the counting register to 9 bits, it is impossible to measure a VERAX fan
158properly (even with a prescaler of 8). At its maximum speed of 3500 RPM the
159fan produces 1080 ripples per second which causes the counting register to
160overflow twice, leading to only 186 RPM.
161
162* Measuring input voltages
163in2 ("battery") reports the voltage of the onboard lithium battery and not
164+3.3V from the power supply.
165
166* Undocumented features
167Fujitsu-Siemens Computers has not documented all features of the chip so
168far. Their software, System Guard, shows that there are a still some
169features which cannot be controlled by this implementation.
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
22char unload_heads_path[64];
23
24int 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}
36int 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
20void write_int(char *path, int i) 48void write_int(char *path, int i)
21{ 49{
@@ -40,7 +68,7 @@ void set_led(int on)
40 68
41void protect(int seconds) 69void 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
46int on_ac(void) 74int 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
63int main(int argc, char* argv[]) 90int 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, &param);
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
34signal. Speeds down to 83 RPM can be measured. 34signal. Speeds down to 83 RPM can be measured.
35 35
36An alarm is triggered if the rotation speed drops below a programmable 36An alarm is triggered if the rotation speed drops below a programmable
37limit. Another alarm is triggered if the speed is too low to to be measured 37limit. 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
4Supported chips: 4Supported 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
11Authors: 11Authors:
12 Aurelien Jarno <aurelien@aurel32.net> 12 Aurelien Jarno <aurelien@aurel32.net>
@@ -16,9 +16,10 @@ Authors:
16 16
17Description 17Description
18----------- 18-----------
19
19The PCF8591 is an 8-bit A/D and D/A converter (4 analog inputs and one 20The PCF8591 is an 8-bit A/D and D/A converter (4 analog inputs and one
20analog output) for the I2C bus produced by Philips Semiconductors. It 21analog output) for the I2C bus produced by Philips Semiconductors (now NXP).
21is designed to provide a byte I2C interface to up to 4 separate devices. 22It is designed to provide a byte I2C interface to up to 4 separate devices.
22 23
23The PCF8591 has 4 analog inputs programmable as single-ended or 24The PCF8591 has 4 analog inputs programmable as single-ended or
24differential inputs : 25differential inputs :
@@ -58,8 +59,8 @@ Accessing PCF8591 via /sys interface
58------------------------------------- 59-------------------------------------
59 60
60! Be careful ! 61! Be careful !
61The PCF8591 is plainly impossible to detect ! Stupid chip. 62The PCF8591 is plainly impossible to detect! Stupid chip.
62So every chip with address in the interval [48..4f] is 63So every chip with address in the interval [0x48..0x4f] is
63detected as PCF8591. If you have other chips in this address 64detected as PCF8591. If you have other chips in this address
64range, the workaround is to load this module after the one 65range, the workaround is to load this module after the one
65for your others chips. 66for your others chips.
@@ -67,19 +68,20 @@ for your others chips.
67On detection (i.e. insmod, modprobe et al.), directories are being 68On detection (i.e. insmod, modprobe et al.), directories are being
68created for each detected PCF8591: 69created for each detected PCF8591:
69 70
70/sys/bus/devices/<0>-<1>/ 71/sys/bus/i2c/devices/<0>-<1>/
71where <0> is the bus the chip was detected on (e. g. i2c-0) 72where <0> is the bus the chip was detected on (e. g. i2c-0)
72and <1> the chip address ([48..4f]) 73and <1> the chip address ([48..4f])
73 74
74Inside these directories, there are such files: 75Inside these directories, there are such files:
75in0, in1, in2, in3, out0_enable, out0_output, name 76in0_input, in1_input, in2_input, in3_input, out0_enable, out0_output, name
76 77
77Name contains chip name. 78Name contains chip name.
78 79
79The in0, in1, in2 and in3 files are RO. Reading gives the value of the 80The in0_input, in1_input, in2_input and in3_input files are RO. Reading gives
80corresponding channel. Depending on the current analog inputs configuration, 81the value of the corresponding channel. Depending on the current analog inputs
81files in2 and/or in3 do not exist. Values range are from 0 to 255 for single 82configuration, files in2_input and in3_input may not exist. Values range
82ended inputs and -128 to +127 for differential inputs (8-bit ADC). 83from 0 to 255 for single ended inputs and -128 to +127 for differential inputs
84(8-bit ADC).
83 85
84The out0_enable file is RW. Reading gives "1" for analog output enabled and 86The 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 @@
1Kernel driver tmp421
2====================
3
4Supported 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
18Authors:
19 Andre Prendel <andre.prendel@gmx.de>
20
21Description
22-----------
23
24This driver implements support for Texas Instruments TMP421, TMP422
25and TMP423 temperature sensor chips. These chips implement one local
26and up to one (TMP421), up to two (TMP422) or up to three (TMP423)
27remote sensors. Temperature is measured in degrees Celsius. The chips
28are wired over I2C/SMBus and specified over a temperature range of -40
29to +125 degrees Celsius. Resolution for both the local and remote
30channels is 0.0625 degree C.
31
32The chips support only temperature measurement. The driver exports
33the temperature values via the following sysfs files:
34
35temp[1-4]_input
36temp[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 @@
1Kernel driver wm831x-hwmon
2==========================
3
4Supported 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
12Authors: Mark Brown <broonie@opensource.wolfsonmicro.com>
13
14Description
15-----------
16
17The WM831x series of PMICs include an AUXADC which can be used to
18monitor a range of system operating parameters, including the voltages
19of the major supplies within the system. Currently the driver provides
20reporting of all the input values but does not provide any alarms.
21
22Voltage Monitoring
23------------------
24
25Voltages are sampled by a 12 bit ADC. Voltages in milivolts are 1.465
26times the ADC value.
27
28Temperature Monitoring
29----------------------
30
31Temperatures are sampled by a 12 bit ADC. Chip and battery temperatures
32are available. The chip temperature is calculated as:
33
34 Degrees celsius = (512.18 - data) / 1.0983
35
36while the battery temperature calculation will depend on the NTC
37thermistor 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 @@
1Kernel driver wm8350-hwmon
2==========================
3
4Supported 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
12Authors: Mark Brown <broonie@opensource.wolfsonmicro.com>
13
14Description
15-----------
16
17The WM835x series of PMICs include an AUXADC which can be used to
18monitor a range of system operating parameters, including the voltages
19of the major supplies within the system. Currently the driver provides
20simple access to these major supplies.
21
22Voltage Monitoring
23------------------
24
25Voltages are sampled by a 12 bit ADC. For the internal supplies the ADC
26is referenced to the system VRTC.
diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4
index f889481762b5..c5b37c570554 100644
--- a/Documentation/i2c/busses/i2c-piix4
+++ b/Documentation/i2c/busses/i2c-piix4
@@ -8,6 +8,8 @@ Supported adapters:
8 Datasheet: Only available via NDA from ServerWorks 8 Datasheet: Only available via NDA from ServerWorks
9 * ATI IXP200, IXP300, IXP400, SB600, SB700 and SB800 southbridges 9 * ATI IXP200, IXP300, IXP400, SB600, SB700 and SB800 southbridges
10 Datasheet: Not publicly available 10 Datasheet: Not publicly available
11 * AMD SB900
12 Datasheet: Not publicly available
11 * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge 13 * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
12 Datasheet: Publicly available at the SMSC website http://www.smsc.com 14 Datasheet: Publicly available at the SMSC website http://www.smsc.com
13 15
diff --git a/Documentation/i2c/chips/pca9539 b/Documentation/i2c/chips/pca9539
deleted file mode 100644
index 6aff890088b1..000000000000
--- a/Documentation/i2c/chips/pca9539
+++ /dev/null
@@ -1,58 +0,0 @@
1Kernel driver pca9539
2=====================
3
4NOTE: this driver is deprecated and will be dropped soon, use
5drivers/gpio/pca9539.c instead.
6
7Supported chips:
8 * Philips PCA9539
9 Prefix: 'pca9539'
10 Addresses scanned: none
11 Datasheet:
12 http://www.semiconductors.philips.com/acrobat/datasheets/PCA9539_2.pdf
13
14Author: Ben Gardner <bgardner@wabtec.com>
15
16
17Description
18-----------
19
20The Philips PCA9539 is a 16 bit low power I/O device.
21All 16 lines can be individually configured as an input or output.
22The input sense can also be inverted.
23The 16 lines are split between two bytes.
24
25
26Detection
27---------
28
29The PCA9539 is difficult to detect and not commonly found in PC machines,
30so you have to pass the I2C bus and address of the installed PCA9539
31devices explicitly to the driver at load time via the force=... parameter.
32
33
34Sysfs entries
35-------------
36
37Each is a byte that maps to the 8 I/O bits.
38A '0' suffix is for bits 0-7, while '1' is for bits 8-15.
39
40input[01] - read the current value
41output[01] - sets the output value
42direction[01] - direction of each bit: 1=input, 0=output
43invert[01] - toggle the input bit sense
44
45input reads the actual state of the line and is always available.
46The direction defaults to input for all channels.
47
48
49General Remarks
50---------------
51
52Note that each output, direction, and invert entry controls 8 lines.
53You should use the read, modify, write sequence.
54For example. to set output bit 0 of 1.
55 val=$(cat output0)
56 val=$(( $val | 1 ))
57 echo $val > output0
58
diff --git a/Documentation/i2c/chips/pcf8574 b/Documentation/i2c/chips/pcf8574
deleted file mode 100644
index 235815c075ff..000000000000
--- a/Documentation/i2c/chips/pcf8574
+++ /dev/null
@@ -1,65 +0,0 @@
1Kernel driver pcf8574
2=====================
3
4Supported chips:
5 * Philips PCF8574
6 Prefix: 'pcf8574'
7 Addresses scanned: none
8 Datasheet: Publicly available at the Philips Semiconductors website
9 http://www.semiconductors.philips.com/pip/PCF8574P.html
10
11 * Philips PCF8574A
12 Prefix: 'pcf8574a'
13 Addresses scanned: none
14 Datasheet: Publicly available at the Philips Semiconductors website
15 http://www.semiconductors.philips.com/pip/PCF8574P.html
16
17Authors:
18 Frodo Looijaard <frodol@dds.nl>,
19 Philip Edelbrock <phil@netroedge.com>,
20 Dan Eaton <dan.eaton@rocketlogix.com>,
21 Aurelien Jarno <aurelien@aurel32.net>,
22 Jean Delvare <khali@linux-fr.org>,
23
24
25Description
26-----------
27The PCF8574(A) is an 8-bit I/O expander for the I2C bus produced by Philips
28Semiconductors. It is designed to provide a byte I2C interface to up to 16
29separate devices (8 x PCF8574 and 8 x PCF8574A).
30
31This device consists of a quasi-bidirectional port. Each of the eight I/Os
32can be independently used as an input or output. To setup an I/O as an
33input, you have to write a 1 to the corresponding output.
34
35For more informations see the datasheet.
36
37
38Accessing PCF8574(A) via /sys interface
39-------------------------------------
40
41The PCF8574(A) is plainly impossible to detect ! Stupid chip.
42So, you have to pass the I2C bus and address of the installed PCF857A
43and PCF8574A devices explicitly to the driver at load time via the
44force=... parameter.
45
46On detection (i.e. insmod, modprobe et al.), directories are being
47created for each detected PCF8574(A):
48
49/sys/bus/i2c/devices/<0>-<1>/
50where <0> is the bus the chip was detected on (e. g. i2c-0)
51and <1> the chip address ([20..27] or [38..3f]):
52
53(example: /sys/bus/i2c/devices/1-0020/)
54
55Inside these directories, there are two files each:
56read and write (and one file with chip name).
57
58The read file is read-only. Reading gives you the current I/O input
59if the corresponding output is set as 1, otherwise the current output
60value, that is to say 0.
61
62The write file is read/write. Writing a value outputs it on the I/O
63port. Reading returns the last written value. As it is not possible
64to read this value from the chip, you need to write at least once to
65this file before you can read back from it.
diff --git a/Documentation/i2c/chips/pcf8575 b/Documentation/i2c/chips/pcf8575
deleted file mode 100644
index 40b268eb276f..000000000000
--- a/Documentation/i2c/chips/pcf8575
+++ /dev/null
@@ -1,69 +0,0 @@
1About the PCF8575 chip and the pcf8575 kernel driver
2====================================================
3
4The PCF8575 chip is produced by the following manufacturers:
5
6 * Philips NXP
7 http://www.nxp.com/#/pip/cb=[type=product,path=50807/41735/41850,final=PCF8575_3]|pip=[pip=PCF8575_3][0]
8
9 * Texas Instruments
10 http://focus.ti.com/docs/prod/folders/print/pcf8575.html
11
12
13Some vendors sell small PCB's with the PCF8575 mounted on it. You can connect
14such a board to a Linux host via e.g. an USB to I2C interface. Examples of
15PCB boards with a PCF8575:
16
17 * SFE Breakout Board for PCF8575 I2C Expander by RobotShop
18 http://www.robotshop.ca/home/products/robot-parts/electronics/adapters-converters/sfe-pcf8575-i2c-expander-board.html
19
20 * Breakout Board for PCF8575 I2C Expander by Spark Fun Electronics
21 http://www.sparkfun.com/commerce/product_info.php?products_id=8130
22
23
24Description
25-----------
26The PCF8575 chip is a 16-bit I/O expander for the I2C bus. Up to eight of
27these chips can be connected to the same I2C bus. You can find this
28chip on some custom designed hardware, but you won't find it on PC
29motherboards.
30
31The PCF8575 chip consists of a 16-bit quasi-bidirectional port and an I2C-bus
32interface. Each of the sixteen I/O's can be independently used as an input or
33an output. To set up an I/O pin as an input, you have to write a 1 to the
34corresponding output.
35
36For more information please see the datasheet.
37
38
39Detection
40---------
41
42There is no method known to detect whether a chip on a given I2C address is
43a PCF8575 or whether it is any other I2C device, so you have to pass the I2C
44bus and address of the installed PCF8575 devices explicitly to the driver at
45load time via the force=... parameter.
46
47/sys interface
48--------------
49
50For each address on which a PCF8575 chip was found or forced the following
51files will be created under /sys:
52* /sys/bus/i2c/devices/<bus>-<address>/read
53* /sys/bus/i2c/devices/<bus>-<address>/write
54where bus is the I2C bus number (0, 1, ...) and address is the four-digit
55hexadecimal representation of the 7-bit I2C address of the PCF8575
56(0020 .. 0027).
57
58The read file is read-only. Reading it will trigger an I2C read and will hence
59report the current input state for the pins configured as inputs, and the
60current output value for the pins configured as outputs.
61
62The write file is read-write. Writing a value to it will configure all pins
63as output for which the corresponding bit is zero. Reading the write file will
64return the value last written, or -EAGAIN if no value has yet been written to
65the write file.
66
67On module initialization the configuration of the chip is not changed -- the
68chip is left in the state it was already configured in through either power-up
69or through previous I2C write actions.
diff --git a/Documentation/ia64/aliasing-test.c b/Documentation/ia64/aliasing-test.c
index d23610fb2ff9..3dfb76ca6931 100644
--- a/Documentation/ia64/aliasing-test.c
+++ b/Documentation/ia64/aliasing-test.c
@@ -24,7 +24,7 @@
24 24
25int sum; 25int sum;
26 26
27int map_mem(char *path, off_t offset, size_t length, int touch) 27static int map_mem(char *path, off_t offset, size_t length, int touch)
28{ 28{
29 int fd, rc; 29 int fd, rc;
30 void *addr; 30 void *addr;
@@ -62,7 +62,7 @@ int map_mem(char *path, off_t offset, size_t length, int touch)
62 return 0; 62 return 0;
63} 63}
64 64
65int scan_tree(char *path, char *file, off_t offset, size_t length, int touch) 65static int scan_tree(char *path, char *file, off_t offset, size_t length, int touch)
66{ 66{
67 struct dirent **namelist; 67 struct dirent **namelist;
68 char *name, *path2; 68 char *name, *path2;
@@ -119,7 +119,7 @@ skip:
119 119
120char buf[1024]; 120char buf[1024];
121 121
122int read_rom(char *path) 122static int read_rom(char *path)
123{ 123{
124 int fd, rc; 124 int fd, rc;
125 size_t size = 0; 125 size_t size = 0;
@@ -146,7 +146,7 @@ int read_rom(char *path)
146 return size; 146 return size;
147} 147}
148 148
149int scan_rom(char *path, char *file) 149static int scan_rom(char *path, char *file)
150{ 150{
151 struct dirent **namelist; 151 struct dirent **namelist;
152 char *name, *path2; 152 char *name, *path2;
diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt
index aafca0a8f66a..947374977ca5 100644
--- a/Documentation/ioctl/ioctl-number.txt
+++ b/Documentation/ioctl/ioctl-number.txt
@@ -135,6 +135,7 @@ Code Seq# Include File Comments
135 <http://mikonos.dia.unisa.it/tcfs> 135 <http://mikonos.dia.unisa.it/tcfs>
136'l' 40-7F linux/udf_fs_i.h in development: 136'l' 40-7F linux/udf_fs_i.h in development:
137 <http://sourceforge.net/projects/linux-udf/> 137 <http://sourceforge.net/projects/linux-udf/>
138'm' 00-09 linux/mmtimer.h
138'm' all linux/mtio.h conflict! 139'm' all linux/mtio.h conflict!
139'm' all linux/soundcard.h conflict! 140'm' all linux/soundcard.h conflict!
140'm' all linux/synclink.h conflict! 141'm' all linux/synclink.h conflict!
diff --git a/Documentation/kbuild/kbuild.txt b/Documentation/kbuild/kbuild.txt
index f3355b6812df..bb3bf38f03da 100644
--- a/Documentation/kbuild/kbuild.txt
+++ b/Documentation/kbuild/kbuild.txt
@@ -65,6 +65,22 @@ INSTALL_PATH
65INSTALL_PATH specifies where to place the updated kernel and system map 65INSTALL_PATH specifies where to place the updated kernel and system map
66images. Default is /boot, but you can set it to other values. 66images. Default is /boot, but you can set it to other values.
67 67
68INSTALLKERNEL
69--------------------------------------------------
70Install script called when using "make install".
71The default name is "installkernel".
72
73The script will be called with the following arguments:
74 $1 - kernel version
75 $2 - kernel image file
76 $3 - kernel map file
77 $4 - default install path (use root directory if blank)
78
79The implmentation of "make install" is architecture specific
80and it may differ from the above.
81
82INSTALLKERNEL is provided to enable the possibility to
83specify a custom installer when cross compiling a kernel.
68 84
69MODLIB 85MODLIB
70-------------------------------------------------- 86--------------------------------------------------
diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt
index d76cfd8712e1..71c602d61680 100644
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -18,6 +18,7 @@ This document describes the Linux kernel Makefiles.
18 --- 3.9 Dependency tracking 18 --- 3.9 Dependency tracking
19 --- 3.10 Special Rules 19 --- 3.10 Special Rules
20 --- 3.11 $(CC) support functions 20 --- 3.11 $(CC) support functions
21 --- 3.12 $(LD) support functions
21 22
22 === 4 Host Program support 23 === 4 Host Program support
23 --- 4.1 Simple Host Program 24 --- 4.1 Simple Host Program
@@ -435,14 +436,14 @@ more details, with real examples.
435 The second argument is optional, and if supplied will be used 436 The second argument is optional, and if supplied will be used
436 if first argument is not supported. 437 if first argument is not supported.
437 438
438 ld-option 439 cc-ldoption
439 ld-option is used to check if $(CC) when used to link object files 440 cc-ldoption is used to check if $(CC) when used to link object files
440 supports the given option. An optional second option may be 441 supports the given option. An optional second option may be
441 specified if first option are not supported. 442 specified if first option are not supported.
442 443
443 Example: 444 Example:
444 #arch/i386/kernel/Makefile 445 #arch/i386/kernel/Makefile
445 vsyscall-flags += $(call ld-option, -Wl$(comma)--hash-style=sysv) 446 vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)
446 447
447 In the above example, vsyscall-flags will be assigned the option 448 In the above example, vsyscall-flags will be assigned the option
448 -Wl$(comma)--hash-style=sysv if it is supported by $(CC). 449 -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
@@ -570,6 +571,19 @@ more details, with real examples.
570 endif 571 endif
571 endif 572 endif
572 573
574--- 3.12 $(LD) support functions
575
576 ld-option
577 ld-option is used to check if $(LD) supports the supplied option.
578 ld-option takes two options as arguments.
579 The second argument is an optional option that can be used if the
580 first option is not supported by $(LD).
581
582 Example:
583 #Makefile
584 LDFLAGS_vmlinux += $(call really-ld-option, -X)
585
586
573=== 4 Host Program support 587=== 4 Host Program support
574 588
575Kbuild supports building executables on the host for use during the 589Kbuild supports building executables on the host for use during the
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
69The first line, with the short description, must be on a single line. 69The short description following the subject can span multiple lines
70and ends with an @argument description, an empty line or the end of
71the comment block.
70 72
71The @argument descriptions must begin on the very next line following 73The @argument descriptions must begin on the very next line following
72this opening short function description line, with no intervening 74this opening short function description line, with no intervening
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
index 4c12a290bee5..6fa7292947e5 100644
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -671,7 +671,7 @@ and is between 256 and 4096 characters. It is defined in the file
671 earlyprintk= [X86,SH,BLACKFIN] 671 earlyprintk= [X86,SH,BLACKFIN]
672 earlyprintk=vga 672 earlyprintk=vga
673 earlyprintk=serial[,ttySn[,baudrate]] 673 earlyprintk=serial[,ttySn[,baudrate]]
674 earlyprintk=dbgp 674 earlyprintk=dbgp[debugController#]
675 675
676 Append ",keep" to not disable it when the real console 676 Append ",keep" to not disable it when the real console
677 takes over. 677 takes over.
@@ -933,7 +933,7 @@ and is between 256 and 4096 characters. It is defined in the file
933 1 -- enable informational integrity auditing messages. 933 1 -- enable informational integrity auditing messages.
934 934
935 ima_hash= [IMA] 935 ima_hash= [IMA]
936 Formt: { "sha1" | "md5" } 936 Format: { "sha1" | "md5" }
937 default: "sha1" 937 default: "sha1"
938 938
939 ima_tcb [IMA] 939 ima_tcb [IMA]
@@ -1286,6 +1286,10 @@ and is between 256 and 4096 characters. It is defined in the file
1286 (machvec) in a generic kernel. 1286 (machvec) in a generic kernel.
1287 Example: machvec=hpzx1_swiotlb 1287 Example: machvec=hpzx1_swiotlb
1288 1288
1289 machtype= [Loongson] Share the same kernel image file between different
1290 yeeloong laptop.
1291 Example: machtype=lemote-yeeloong-2f-7inch
1292
1289 max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater 1293 max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater
1290 than or equal to this physical address is ignored. 1294 than or equal to this physical address is ignored.
1291 1295
@@ -1561,7 +1565,7 @@ and is between 256 and 4096 characters. It is defined in the file
1561 of returning the full 64-bit number. 1565 of returning the full 64-bit number.
1562 The default is to return 64-bit inode numbers. 1566 The default is to return 64-bit inode numbers.
1563 1567
1564 nmi_debug= [KNL,AVR32] Specify one or more actions to take 1568 nmi_debug= [KNL,AVR32,SH] Specify one or more actions to take
1565 when a NMI is triggered. 1569 when a NMI is triggered.
1566 Format: [state][,regs][,debounce][,die] 1570 Format: [state][,regs][,debounce][,die]
1567 1571
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.
431. Downloading 431. Downloading
44============== 44==============
45 45
46kmemcheck can only be downloaded using git. If you want to write patches 46As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel.
47against the current code, you should use the kmemcheck development branch of
48the tip tree. It is also possible to use the linux-next tree, which also
49includes the latest version of kmemcheck.
50
51Assuming that you've already cloned the linux-2.6.git repository, all you
52have 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
56To actually download the tree, fetch the remote:
57
58 $ git fetch tip
59
60And to check out a new local branch with the kmemcheck code:
61
62 $ git checkout -b kmemcheck tip/kmemcheck
63
64General instructions for the -tip tree can be found here:
65http://people.redhat.com/mingo/tip.git/readme.txt
66 47
67 48
682. Configuring and compiling 492. Configuring and compiling
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/laptops/asus-laptop.txt b/Documentation/laptops/asus-laptop.txt
new file mode 100644
index 000000000000..c1c5be84e4b1
--- /dev/null
+++ b/Documentation/laptops/asus-laptop.txt
@@ -0,0 +1,258 @@
1Asus Laptop Extras
2
3Version 0.1
4August 6, 2009
5
6Corentin Chary <corentincj@iksaif.net>
7http://acpi4asus.sf.net/
8
9 This driver provides support for extra features of ACPI-compatible ASUS laptops.
10 It may also support some MEDION, JVC or VICTOR laptops (such as MEDION 9675 or
11 VICTOR XP7210 for example). It makes all the extra buttons generate standard
12 ACPI events that go through /proc/acpi/events and input events (like keyboards).
13 On some models adds support for changing the display brightness and output,
14 switching the LCD backlight on and off, and most importantly, allows you to
15 blink those fancy LEDs intended for reporting mail and wireless status.
16
17This driver supercedes the old asus_acpi driver.
18
19Requirements
20------------
21
22 Kernel 2.6.X sources, configured for your computer, with ACPI support.
23 You also need CONFIG_INPUT and CONFIG_ACPI.
24
25Status
26------
27
28 The features currently supported are the following (see below for
29 detailed description):
30
31 - Fn key combinations
32 - Bluetooth enable and disable
33 - Wlan enable and disable
34 - GPS enable and disable
35 - Video output switching
36 - Ambient Light Sensor on and off
37 - LED control
38 - LED Display control
39 - LCD brightness control
40 - LCD on and off
41
42 A compatibility table by model and feature is maintained on the web
43 site, http://acpi4asus.sf.net/.
44
45Usage
46-----
47
48 Try "modprobe asus_acpi". Check your dmesg (simply type dmesg). You should
49 see some lines like this :
50
51 Asus Laptop Extras version 0.42
52 L2D model detected.
53
54 If it is not the output you have on your laptop, send it (and the laptop's
55 DSDT) to me.
56
57 That's all, now, all the events generated by the hotkeys of your laptop
58 should be reported in your /proc/acpi/event entry. You can check with
59 "acpi_listen".
60
61 Hotkeys are also reported as input keys (like keyboards) you can check
62 which key are supported using "xev" under X11.
63
64 You can get informations on the version of your DSDT table by reading the
65 /sys/devices/platform/asus-laptop/infos entry. If you have a question or a
66 bug report to do, please include the output of this entry.
67
68LEDs
69----
70
71 You can modify LEDs be echoing values to /sys/class/leds/asus::*/brightness :
72 echo 1 > /sys/class/leds/asus::mail/brightness
73 will switch the mail LED on.
74 You can also know if they are on/off by reading their content and use
75 kernel triggers like ide-disk or heartbeat.
76
77Backlight
78---------
79
80 You can control lcd backlight power and brightness with
81 /sys/class/backlight/asus-laptop/. Brightness Values are between 0 and 15.
82
83Wireless devices
84---------------
85
86 You can turn the internal Bluetooth adapter on/off with the bluetooth entry
87 (only on models with Bluetooth). This usually controls the associated LED.
88 Same for Wlan adapter.
89
90Display switching
91-----------------
92
93 Note: the display switching code is currently considered EXPERIMENTAL.
94
95 Switching works for the following models:
96 L3800C
97 A2500H
98 L5800C
99 M5200N
100 W1000N (albeit with some glitches)
101 M6700R
102 A6JC
103 F3J
104
105 Switching doesn't work for the following:
106 M3700N
107 L2X00D (locks the laptop under certain conditions)
108
109 To switch the displays, echo values from 0 to 15 to
110 /sys/devices/platform/asus-laptop/display. The significance of those values
111 is as follows:
112
113 +-------+-----+-----+-----+-----+-----+
114 | Bin | Val | DVI | TV | CRT | LCD |
115 +-------+-----+-----+-----+-----+-----+
116 + 0000 + 0 + + + + +
117 +-------+-----+-----+-----+-----+-----+
118 + 0001 + 1 + + + + X +
119 +-------+-----+-----+-----+-----+-----+
120 + 0010 + 2 + + + X + +
121 +-------+-----+-----+-----+-----+-----+
122 + 0011 + 3 + + + X + X +
123 +-------+-----+-----+-----+-----+-----+
124 + 0100 + 4 + + X + + +
125 +-------+-----+-----+-----+-----+-----+
126 + 0101 + 5 + + X + + X +
127 +-------+-----+-----+-----+-----+-----+
128 + 0110 + 6 + + X + X + +
129 +-------+-----+-----+-----+-----+-----+
130 + 0111 + 7 + + X + X + X +
131 +-------+-----+-----+-----+-----+-----+
132 + 1000 + 8 + X + + + +
133 +-------+-----+-----+-----+-----+-----+
134 + 1001 + 9 + X + + + X +
135 +-------+-----+-----+-----+-----+-----+
136 + 1010 + 10 + X + + X + +
137 +-------+-----+-----+-----+-----+-----+
138 + 1011 + 11 + X + + X + X +
139 +-------+-----+-----+-----+-----+-----+
140 + 1100 + 12 + X + X + + +
141 +-------+-----+-----+-----+-----+-----+
142 + 1101 + 13 + X + X + + X +
143 +-------+-----+-----+-----+-----+-----+
144 + 1110 + 14 + X + X + X + +
145 +-------+-----+-----+-----+-----+-----+
146 + 1111 + 15 + X + X + X + X +
147 +-------+-----+-----+-----+-----+-----+
148
149 In most cases, the appropriate displays must be plugged in for the above
150 combinations to work. TV-Out may need to be initialized at boot time.
151
152 Debugging:
153 1) Check whether the Fn+F8 key:
154 a) does not lock the laptop (try disabling CONFIG_X86_UP_APIC or boot with
155 noapic / nolapic if it does)
156 b) generates events (0x6n, where n is the value corresponding to the
157 configuration above)
158 c) actually works
159 Record the disp value at every configuration.
160 2) Echo values from 0 to 15 to /sys/devices/platform/asus-laptop/display.
161 Record its value, note any change. If nothing changes, try a broader range,
162 up to 65535.
163 3) Send ANY output (both positive and negative reports are needed, unless your
164 machine is already listed above) to the acpi4asus-user mailing list.
165
166 Note: on some machines (e.g. L3C), after the module has been loaded, only 0x6n
167 events are generated and no actual switching occurs. In such a case, a line
168 like:
169
170 echo $((10#$arg-60)) > /sys/devices/platform/asus-laptop/display
171
172 will usually do the trick ($arg is the 0000006n-like event passed to acpid).
173
174 Note: there is currently no reliable way to read display status on xxN
175 (Centrino) models.
176
177LED display
178-----------
179
180 Some models like the W1N have a LED display that can be used to display
181 several informations.
182
183 LED display works for the following models:
184 W1000N
185 W1J
186
187 To control the LED display, use the following :
188
189 echo 0x0T000DDD > /sys/devices/platform/asus-laptop/
190
191 where T control the 3 letters display, and DDD the 3 digits display,
192 according to the tables below.
193
194 DDD (digits)
195 000 to 999 = display digits
196 AAA = ---
197 BBB to FFF = turn-off
198
199 T (type)
200 0 = off
201 1 = dvd
202 2 = vcd
203 3 = mp3
204 4 = cd
205 5 = tv
206 6 = cpu
207 7 = vol
208
209 For example "echo 0x01000001 >/sys/devices/platform/asus-laptop/ledd"
210 would display "DVD001".
211
212Driver options:
213---------------
214
215 Options can be passed to the asus-laptop driver using the standard
216 module argument syntax (<param>=<value> when passing the option to the
217 module or asus-laptop.<param>=<value> on the kernel boot line when
218 asus-laptop is statically linked into the kernel).
219
220 wapf: WAPF defines the behavior of the Fn+Fx wlan key
221 The significance of values is yet to be found, but
222 most of the time:
223 - 0x0 should do nothing
224 - 0x1 should allow to control the device with Fn+Fx key.
225 - 0x4 should send an ACPI event (0x88) while pressing the Fn+Fx key
226 - 0x5 like 0x1 or 0x4
227
228 The default value is 0x1.
229
230Unsupported models
231------------------
232
233 These models will never be supported by this module, as they use a completely
234 different mechanism to handle LEDs and extra stuff (meaning we have no clue
235 how it works):
236
237 - ASUS A1300 (A1B), A1370D
238 - ASUS L7300G
239 - ASUS L8400
240
241Patches, Errors, Questions:
242--------------------------
243
244 I appreciate any success or failure
245 reports, especially if they add to or correct the compatibility table.
246 Please include the following information in your report:
247
248 - Asus model name
249 - a copy of your ACPI tables, using the "acpidump" utility
250 - a copy of /sys/devices/platform/asus-laptop/infos
251 - which driver features work and which don't
252 - the observed behavior of non-working features
253
254 Any other comments or patches are also more than welcome.
255
256 acpi4asus-user@lists.sourceforge.net
257 http://sourceforge.net/projects/acpi4asus
258
diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt
index e2ddcdeb61b6..6d03487ef1c7 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.txt
@@ -219,7 +219,7 @@ The following commands can be written to the /proc/acpi/ibm/hotkey file:
219 echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys 219 echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
220 echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys 220 echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
221 ... any other 8-hex-digit mask ... 221 ... any other 8-hex-digit mask ...
222 echo reset > /proc/acpi/ibm/hotkey -- restore the original mask 222 echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask
223 223
224The following commands have been deprecated and will cause the kernel 224The following commands have been deprecated and will cause the kernel
225to log a warning: 225to log a warning:
@@ -240,9 +240,13 @@ sysfs notes:
240 Returns 0. 240 Returns 0.
241 241
242 hotkey_bios_mask: 242 hotkey_bios_mask:
243 DEPRECATED, DON'T USE, WILL BE REMOVED IN THE FUTURE.
244
243 Returns the hot keys mask when thinkpad-acpi was loaded. 245 Returns the hot keys mask when thinkpad-acpi was loaded.
244 Upon module unload, the hot keys mask will be restored 246 Upon module unload, the hot keys mask will be restored
245 to this value. 247 to this value. This is always 0x80c, because those are
248 the hotkeys that were supported by ancient firmware
249 without mask support.
246 250
247 hotkey_enable: 251 hotkey_enable:
248 DEPRECATED, WILL BE REMOVED SOON. 252 DEPRECATED, WILL BE REMOVED SOON.
diff --git a/Documentation/leds-class.txt b/Documentation/leds-class.txt
index 6399557cdab3..8fd5ca2ae32d 100644
--- a/Documentation/leds-class.txt
+++ b/Documentation/leds-class.txt
@@ -1,3 +1,4 @@
1
1LED handling under Linux 2LED handling under Linux
2======================== 3========================
3 4
@@ -5,10 +6,10 @@ If you're reading this and thinking about keyboard leds, these are
5handled by the input subsystem and the led class is *not* needed. 6handled by the input subsystem and the led class is *not* needed.
6 7
7In its simplest form, the LED class just allows control of LEDs from 8In its simplest form, the LED class just allows control of LEDs from
8userspace. LEDs appear in /sys/class/leds/. The brightness file will 9userspace. LEDs appear in /sys/class/leds/. The maximum brightness of the
9set the brightness of the LED (taking a value 0-255). Most LEDs don't 10LED is defined in max_brightness file. The brightness file will set the brightness
10have hardware brightness support so will just be turned on for non-zero 11of the LED (taking a value 0-max_brightness). Most LEDs don't have hardware
11brightness settings. 12brightness support so will just be turned on for non-zero brightness settings.
12 13
13The class also introduces the optional concept of an LED trigger. A trigger 14The class also introduces the optional concept of an LED trigger. A trigger
14is a kernel based source of led events. Triggers can either be simple or 15is a kernel based source of led events. Triggers can either be simple or
diff --git a/Documentation/lguest/lguest.c b/Documentation/lguest/lguest.c
index 950cde6d6e58..ba9373f82ab5 100644
--- a/Documentation/lguest/lguest.c
+++ b/Documentation/lguest/lguest.c
@@ -42,6 +42,7 @@
42#include <signal.h> 42#include <signal.h>
43#include "linux/lguest_launcher.h" 43#include "linux/lguest_launcher.h"
44#include "linux/virtio_config.h" 44#include "linux/virtio_config.h"
45#include <linux/virtio_ids.h>
45#include "linux/virtio_net.h" 46#include "linux/virtio_net.h"
46#include "linux/virtio_blk.h" 47#include "linux/virtio_blk.h"
47#include "linux/virtio_console.h" 48#include "linux/virtio_console.h"
@@ -133,6 +134,9 @@ struct device {
133 /* Is it operational */ 134 /* Is it operational */
134 bool running; 135 bool running;
135 136
137 /* Does Guest want an intrrupt on empty? */
138 bool irq_on_empty;
139
136 /* Device-specific data. */ 140 /* Device-specific data. */
137 void *priv; 141 void *priv;
138}; 142};
@@ -623,10 +627,13 @@ static void trigger_irq(struct virtqueue *vq)
623 return; 627 return;
624 vq->pending_used = 0; 628 vq->pending_used = 0;
625 629
626 /* If they don't want an interrupt, don't send one, unless empty. */ 630 /* If they don't want an interrupt, don't send one... */
627 if ((vq->vring.avail->flags & VRING_AVAIL_F_NO_INTERRUPT) 631 if (vq->vring.avail->flags & VRING_AVAIL_F_NO_INTERRUPT) {
628 && lg_last_avail(vq) != vq->vring.avail->idx) 632 /* ... unless they've asked us to force one on empty. */
629 return; 633 if (!vq->dev->irq_on_empty
634 || lg_last_avail(vq) != vq->vring.avail->idx)
635 return;
636 }
630 637
631 /* Send the Guest an interrupt tell them we used something up. */ 638 /* Send the Guest an interrupt tell them we used something up. */
632 if (write(lguest_fd, buf, sizeof(buf)) != 0) 639 if (write(lguest_fd, buf, sizeof(buf)) != 0)
@@ -1042,6 +1049,15 @@ static void create_thread(struct virtqueue *vq)
1042 close(vq->eventfd); 1049 close(vq->eventfd);
1043} 1050}
1044 1051
1052static bool accepted_feature(struct device *dev, unsigned int bit)
1053{
1054 const u8 *features = get_feature_bits(dev) + dev->feature_len;
1055
1056 if (dev->feature_len < bit / CHAR_BIT)
1057 return false;
1058 return features[bit / CHAR_BIT] & (1 << (bit % CHAR_BIT));
1059}
1060
1045static void start_device(struct device *dev) 1061static void start_device(struct device *dev)
1046{ 1062{
1047 unsigned int i; 1063 unsigned int i;
@@ -1055,6 +1071,8 @@ static void start_device(struct device *dev)
1055 verbose(" %02x", get_feature_bits(dev) 1071 verbose(" %02x", get_feature_bits(dev)
1056 [dev->feature_len+i]); 1072 [dev->feature_len+i]);
1057 1073
1074 dev->irq_on_empty = accepted_feature(dev, VIRTIO_F_NOTIFY_ON_EMPTY);
1075
1058 for (vq = dev->vq; vq; vq = vq->next) { 1076 for (vq = dev->vq; vq; vq = vq->next) {
1059 if (vq->service) 1077 if (vq->service)
1060 create_thread(vq); 1078 create_thread(vq);
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
6This document introduces Linux Kernel Markers and their use. It provides
7examples of how to insert markers in the kernel and connect probe functions to
8them and provides some examples of probe functions.
9
10
11* Purpose of markers
12
13A marker placed in code provides a hook to call a function (probe) that you can
14provide 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
16adding a tiny time penalty (checking a condition for a branch) and space
17penalty (adding a few bytes for the function call at the end of the
18instrumented function and adds a data structure in a separate section). When a
19marker is "on", the function you provide is called each time the marker is
20executed, in the execution context of the caller. When the function provided
21ends its execution, it returns to the caller (continuing from the marker site).
22
23You can put markers at important locations in the code. Markers are
24lightweight hooks that can pass an arbitrary number of parameters,
25described in a printk-like format string, to the attached probe function.
26
27They can be used for tracing and performance accounting.
28
29
30* Usage
31
32In order to use the macro trace_mark, you should include linux/marker.h.
33
34#include <linux/marker.h>
35
36And,
37
38trace_mark(subsystem_event, "myint %d mystring %s", someint, somestring);
39Where :
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
49Connecting a function (probe) to a marker is done by providing a probe (function
50to call) for the specific marker through marker_probe_register() and can be
51activated by calling marker_arm(). Marker deactivation can be done by calling
52marker_disarm() as many times as marker_arm() has been called. Removing a probe
53is done through marker_probe_unregister(); it will disarm the probe.
54
55marker_synchronize_unregister() must be called between probe unregistration and
56the 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.
61This, and the fact that preemption is disabled around the probe call, make sure
62that probe removal and module unload are safe. See the "Probe example" section
63below for a sample probe module.
64
65The marker mechanism supports inserting multiple instances of the same marker.
66Markers can be put in inline functions, inlined static functions, and
67unrolled loops as well as regular functions.
68
69The naming scheme "subsystem_event" is suggested here as a convention intended
70to limit collisions. Marker names are global to the kernel: they are considered
71as being the same whether they are in the core kernel image or in modules.
72Conflicting format strings for markers with the same name will cause the markers
73to be detected to have a different format string not to be armed and will output
74a printk warning which identifies the inconsistency:
75
76"Format mismatch for probe probe_name (format), marker (format)"
77
78Another way to use markers is to simply define the marker without generating any
79function call to actually call into the marker. This is useful in combination
80with tracepoint probes in a scheme like this :
81
82void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk);
83
84DEFINE_MARKER_TP(marker_eventname, tracepoint_name, probe_tracepoint_name,
85 "arg1 %u pid %d");
86
87notrace 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
95See the example provided in samples/markers/src
96
97Compile them with your kernel.
98
99Run, as root :
100modprobe marker-example (insmod order is not important)
101modprobe probe-example
102cat /proc/marker-example (returns an expected error)
103rmmod marker-example probe-example
104dmesg
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 @@
1There are several classic problems related to memory on Linux 1There are several classic problems related to memory on Linux
2systems. 2systems.
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.
24If you use "mem=" on a machine with PCI, consider using "memmap=" to avoid 13If you use "mem=" on a machine with PCI, consider using "memmap=" to avoid
25physical address space collisions. 14physical address space collisions.
26 15
27See the documentation of your boot loader (LILO, loadlin, etc.) about 16See the documentation of your boot loader (LILO, grub, loadlin, etc.) about
28how to pass options to the kernel. 17how to pass options to the kernel.
29 18
30There are other memory problems which Linux cannot deal with. Random 19There 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
54Other 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/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
97This example comes from the zd1211rw device driver. You can start 97This example comes from the zd1211rw device driver. You can start
98by having a mapping of your device's EEPROM country/regulatory 98by having a mapping of your device's EEPROM country/regulatory
99domain value to to a specific alpha2 as follows: 99domain value to a specific alpha2 as follows:
100 100
101static struct zd_reg_alpha2_map reg_alpha2_map[] = { 101static 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
8numa_hit A process wanted to allocate memory from this node, 8numa_hit A process wanted to allocate memory from this node,
9 and succeeded. 9 and succeeded.
10numa_miss A process wanted to allocate memory from this node, 10numa_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.
12numa_foreign A process wanted to allocate on another node, 12numa_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.
14local_node A process ran on this node and got memory from it. 14local_node A process ran on this node and got memory from it.
15other_node A process ran on this node and got memory from another node. 15other_node A process ran on this node and got memory from another node.
16interleave_hit Interleaving wanted to allocate from this node 16interleave_hit Interleaving wanted to allocate from this node
diff --git a/Documentation/pcmcia/crc32hash.c b/Documentation/pcmcia/crc32hash.c
index 4210e5abab8a..44f8beea7260 100644
--- a/Documentation/pcmcia/crc32hash.c
+++ b/Documentation/pcmcia/crc32hash.c
@@ -8,7 +8,7 @@ $ ./crc32hash "Dual Speed"
8#include <ctype.h> 8#include <ctype.h>
9#include <stdlib.h> 9#include <stdlib.h>
10 10
11unsigned int crc32(unsigned char const *p, unsigned int len) 11static unsigned int crc32(unsigned char const *p, unsigned int len)
12{ 12{
13 int i; 13 int i;
14 unsigned int crc = 0; 14 unsigned int crc = 0;
diff --git a/Documentation/power/power_supply_class.txt b/Documentation/power/power_supply_class.txt
index c6cd4956047c..9f16c5178b66 100644
--- a/Documentation/power/power_supply_class.txt
+++ b/Documentation/power/power_supply_class.txt
@@ -76,6 +76,11 @@ STATUS - this attribute represents operating status (charging, full,
76discharging (i.e. powering a load), etc.). This corresponds to 76discharging (i.e. powering a load), etc.). This corresponds to
77BATTERY_STATUS_* values, as defined in battery.h. 77BATTERY_STATUS_* values, as defined in battery.h.
78 78
79CHARGE_TYPE - batteries can typically charge at different rates.
80This defines trickle and fast charges. For batteries that
81are already charged or discharging, 'n/a' can be displayed (or
82'unknown', if the status is not known).
83
79HEALTH - represents health of the battery, values corresponds to 84HEALTH - represents health of the battery, values corresponds to
80POWER_SUPPLY_HEALTH_*, defined in battery.h. 85POWER_SUPPLY_HEALTH_*, defined in battery.h.
81 86
@@ -108,6 +113,8 @@ relative, time-based measurements.
108ENERGY_FULL, ENERGY_EMPTY - same as above but for energy. 113ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
109 114
110CAPACITY - capacity in percents. 115CAPACITY - capacity in percents.
116CAPACITY_LEVEL - capacity level. This corresponds to
117POWER_SUPPLY_CAPACITY_LEVEL_*.
111 118
112TEMP - temperature of the power supply. 119TEMP - temperature of the power supply.
113TEMP_AMBIENT - ambient temperature. 120TEMP_AMBIENT - ambient temperature.
diff --git a/Documentation/power/regulator/design.txt b/Documentation/power/regulator/design.txt
new file mode 100644
index 000000000000..f9b56b72b782
--- /dev/null
+++ b/Documentation/power/regulator/design.txt
@@ -0,0 +1,33 @@
1Regulator API design notes
2==========================
3
4This document provides a brief, partially structured, overview of some
5of the design considerations which impact the regulator API design.
6
7Safety
8------
9
10 - Errors in regulator configuration can have very serious consequences
11 for the system, potentially including lasting hardware damage.
12 - It is not possible to automatically determine the power confugration
13 of the system - software-equivalent variants of the same chip may
14 have different power requirments, and not all components with power
15 requirements are visible to software.
16
17 => The API should make no changes to the hardware state unless it has
18 specific knowledge that these changes are safe to do perform on
19 this particular system.
20
21Consumer use cases
22------------------
23
24 - The overwhelming majority of devices in a system will have no
25 requirement to do any runtime configuration of their power beyond
26 being able to turn it on or off.
27
28 - Many of the power supplies in the system will be shared between many
29 different consumers.
30
31 => The consumer API should be structured so that these use cases are
32 very easy to handle and so that consumers will work with shared
33 supplies without any additional effort.
diff --git a/Documentation/power/regulator/machine.txt b/Documentation/power/regulator/machine.txt
index ce3487d99abe..63728fed620b 100644
--- a/Documentation/power/regulator/machine.txt
+++ b/Documentation/power/regulator/machine.txt
@@ -87,7 +87,7 @@ static struct platform_device regulator_devices[] = {
87}, 87},
88}; 88};
89/* register regulator 1 device */ 89/* register regulator 1 device */
90platform_device_register(&wm8350_regulator_devices[0]); 90platform_device_register(&regulator_devices[0]);
91 91
92/* register regulator 2 device */ 92/* register regulator 2 device */
93platform_device_register(&wm8350_regulator_devices[1]); 93platform_device_register(&regulator_devices[1]);
diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.txt
index 0cded696ca01..ffd185bb6054 100644
--- a/Documentation/power/regulator/overview.txt
+++ b/Documentation/power/regulator/overview.txt
@@ -29,7 +29,7 @@ Some terms used in this document:-
29 29
30 30
31 o PMIC - Power Management IC. An IC that contains numerous regulators 31 o PMIC - Power Management IC. An IC that contains numerous regulators
32 and often contains other susbsystems. 32 and often contains other subsystems.
33 33
34 34
35 o Consumer - Electronic device that is supplied power by a regulator. 35 o Consumer - Electronic device that is supplied power by a regulator.
@@ -168,4 +168,4 @@ relevant to non SoC devices and is split into the following four interfaces:-
168 userspace via sysfs. This could be used to help monitor device power 168 userspace via sysfs. This could be used to help monitor device power
169 consumption and status. 169 consumption and status.
170 170
171 See Documentation/ABI/testing/regulator-sysfs.txt 171 See Documentation/ABI/testing/sysfs-class-regulator
diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt
index 4200accb9bba..3f8b528f237e 100644
--- a/Documentation/power/regulator/regulator.txt
+++ b/Documentation/power/regulator/regulator.txt
@@ -10,8 +10,9 @@ Registration
10 10
11Drivers can register a regulator by calling :- 11Drivers can register a regulator by calling :-
12 12
13struct regulator_dev *regulator_register(struct device *dev, 13struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
14 struct regulator_desc *regulator_desc); 14 struct device *dev, struct regulator_init_data *init_data,
15 void *driver_data);
15 16
16This will register the regulators capabilities and operations to the regulator 17This will register the regulators capabilities and operations to the regulator
17core. 18core.
diff --git a/Documentation/powerpc/dts-bindings/fsl/esdhc.txt b/Documentation/powerpc/dts-bindings/fsl/esdhc.txt
index 3ed3797b5086..8a0040738969 100644
--- a/Documentation/powerpc/dts-bindings/fsl/esdhc.txt
+++ b/Documentation/powerpc/dts-bindings/fsl/esdhc.txt
@@ -10,6 +10,8 @@ Required properties:
10 - interrupts : should contain eSDHC interrupt. 10 - interrupts : should contain eSDHC interrupt.
11 - interrupt-parent : interrupt source phandle. 11 - interrupt-parent : interrupt source phandle.
12 - clock-frequency : specifies eSDHC base clock frequency. 12 - clock-frequency : specifies eSDHC base clock frequency.
13 - sdhci,wp-inverted : (optional) specifies that eSDHC controller
14 reports inverted write-protect state;
13 - sdhci,1-bit-only : (optional) specifies that a controller can 15 - sdhci,1-bit-only : (optional) specifies that a controller can
14 only handle 1-bit data transfers. 16 only handle 1-bit data transfers.
15 17
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/powerpc/dts-bindings/mtd-physmap.txt b/Documentation/powerpc/dts-bindings/mtd-physmap.txt
index 667c9bde8699..80152cb567d9 100644
--- a/Documentation/powerpc/dts-bindings/mtd-physmap.txt
+++ b/Documentation/powerpc/dts-bindings/mtd-physmap.txt
@@ -1,18 +1,19 @@
1CFI or JEDEC memory-mapped NOR flash 1CFI or JEDEC memory-mapped NOR flash, MTD-RAM (NVRAM...)
2 2
3Flash chips (Memory Technology Devices) are often used for solid state 3Flash chips (Memory Technology Devices) are often used for solid state
4file systems on embedded devices. 4file systems on embedded devices.
5 5
6 - compatible : should contain the specific model of flash chip(s) 6 - compatible : should contain the specific model of mtd chip(s)
7 used, if known, followed by either "cfi-flash" or "jedec-flash" 7 used, if known, followed by either "cfi-flash", "jedec-flash"
8 - reg : Address range(s) of the flash chip(s) 8 or "mtd-ram".
9 - reg : Address range(s) of the mtd chip(s)
9 It's possible to (optionally) define multiple "reg" tuples so that 10 It's possible to (optionally) define multiple "reg" tuples so that
10 non-identical NOR chips can be described in one flash node. 11 non-identical chips can be described in one node.
11 - bank-width : Width (in bytes) of the flash bank. Equal to the 12 - bank-width : Width (in bytes) of the bank. Equal to the
12 device width times the number of interleaved chips. 13 device width times the number of interleaved chips.
13 - device-width : (optional) Width of a single flash chip. If 14 - device-width : (optional) Width of a single mtd chip. If
14 omitted, assumed to be equal to 'bank-width'. 15 omitted, assumed to be equal to 'bank-width'.
15 - #address-cells, #size-cells : Must be present if the flash has 16 - #address-cells, #size-cells : Must be present if the device has
16 sub-nodes representing partitions (see below). In this case 17 sub-nodes representing partitions (see below). In this case
17 both #address-cells and #size-cells must be equal to 1. 18 both #address-cells and #size-cells must be equal to 1.
18 19
@@ -22,24 +23,24 @@ are defined:
22 - vendor-id : Contains the flash chip's vendor id (1 byte). 23 - vendor-id : Contains the flash chip's vendor id (1 byte).
23 - device-id : Contains the flash chip's device id (1 byte). 24 - device-id : Contains the flash chip's device id (1 byte).
24 25
25In addition to the information on the flash bank itself, the 26In addition to the information on the mtd bank itself, the
26device tree may optionally contain additional information 27device tree may optionally contain additional information
27describing partitions of the flash address space. This can be 28describing partitions of the address space. This can be
28used on platforms which have strong conventions about which 29used on platforms which have strong conventions about which
29portions of the flash are used for what purposes, but which don't 30portions of a flash are used for what purposes, but which don't
30use an on-flash partition table such as RedBoot. 31use an on-flash partition table such as RedBoot.
31 32
32Each partition is represented as a sub-node of the flash device. 33Each partition is represented as a sub-node of the mtd device.
33Each node's name represents the name of the corresponding 34Each node's name represents the name of the corresponding
34partition of the flash device. 35partition of the mtd device.
35 36
36Flash partitions 37Flash partitions
37 - reg : The partition's offset and size within the flash bank. 38 - reg : The partition's offset and size within the mtd bank.
38 - label : (optional) The label / name for this flash partition. 39 - label : (optional) The label / name for this partition.
39 If omitted, the label is taken from the node name (excluding 40 If omitted, the label is taken from the node name (excluding
40 the unit address). 41 the unit address).
41 - read-only : (optional) This parameter, if present, is a hint to 42 - read-only : (optional) This parameter, if present, is a hint to
42 Linux that this flash partition should only be mounted 43 Linux that this partition should only be mounted
43 read-only. This is usually used for flash partitions 44 read-only. This is usually used for flash partitions
44 containing early-boot firmware images or data which should not 45 containing early-boot firmware images or data which should not
45 be clobbered. 46 be clobbered.
@@ -78,3 +79,12 @@ Here an example with multiple "reg" tuples:
78 reg = <0 0x04000000>; 79 reg = <0 0x04000000>;
79 }; 80 };
80 }; 81 };
82
83An example using SRAM:
84
85 sram@2,0 {
86 compatible = "samsung,k6f1616u6a", "mtd-ram";
87 reg = <2 0 0x00200000>;
88 bank-width = <2>;
89 };
90
diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
index 8deffcd68cb8..9104c1062084 100644
--- a/Documentation/rtc.txt
+++ b/Documentation/rtc.txt
@@ -135,6 +135,30 @@ a high functionality RTC is integrated into the SOC. That system might read
135the system clock from the discrete RTC, but use the integrated one for all 135the system clock from the discrete RTC, but use the integrated one for all
136other tasks, because of its greater functionality. 136other tasks, because of its greater functionality.
137 137
138SYSFS INTERFACE
139---------------
140
141The sysfs interface under /sys/class/rtc/rtcN provides access to various
142rtc attributes without requiring the use of ioctls. All dates and times
143are in the RTC's timezone, rather than in system time.
144
145date: RTC-provided date
146hctosys: 1 if the RTC provided the system time at boot via the
147 CONFIG_RTC_HCTOSYS kernel option, 0 otherwise
148max_user_freq: The maximum interrupt rate an unprivileged user may request
149 from this RTC.
150name: The name of the RTC corresponding to this sysfs directory
151since_epoch: The number of seconds since the epoch according to the RTC
152time: RTC-provided time
153wakealarm: The time at which the clock will generate a system wakeup
154 event. This is a one shot wakeup event, so must be reset
155 after wake if a daily wakeup is required. Format is either
156 seconds since the epoch or, if there's a leading +, seconds
157 in the future.
158
159IOCTL INTERFACE
160---------------
161
138The ioctl() calls supported by /dev/rtc are also supported by the RTC class 162The ioctl() calls supported by /dev/rtc are also supported by the RTC class
139framework. However, because the chips and systems are not standardized, 163framework. However, because the chips and systems are not standardized,
140some PC/AT functionality might not be provided. And in the same way, some 164some PC/AT functionality might not be provided. And in the same way, some
@@ -185,6 +209,8 @@ driver returns ENOIOCTLCMD. Some common examples:
185 hardware in the irq_set_freq function. If it isn't, return -EINVAL. If 209 hardware in the irq_set_freq function. If it isn't, return -EINVAL. If
186 you cannot actually change the frequency, do not define irq_set_freq. 210 you cannot actually change the frequency, do not define irq_set_freq.
187 211
212 * RTC_PIE_ON, RTC_PIE_OFF: the irq_set_state function will be called.
213
188If all else fails, check out the rtc-test.c driver! 214If all else fails, check out the rtc-test.c driver!
189 215
190 216
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
515v. Remove redundant __megaraid_busywait_mbox routine 515v. Remove redundant __megaraid_busywait_mbox routine
516 516
517vi. Fix bug in the managment module, which causes a system lockup when the 517vi. 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/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt
index 97eebd63bedc..f1708b79f963 100644
--- a/Documentation/sound/alsa/HD-Audio-Models.txt
+++ b/Documentation/sound/alsa/HD-Audio-Models.txt
@@ -387,7 +387,7 @@ STAC92HD73*
387STAC92HD83* 387STAC92HD83*
388=========== 388===========
389 ref Reference board 389 ref Reference board
390 mic-ref Reference board with power managment for ports 390 mic-ref Reference board with power management for ports
391 dell-s14 Dell laptop 391 dell-s14 Dell laptop
392 auto BIOS setup (default) 392 auto BIOS setup (default)
393 393
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary
index 4a02d2508bc8..deab51ddc33e 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary
@@ -350,7 +350,7 @@ SPI protocol drivers somewhat resemble platform device drivers:
350 .resume = CHIP_resume, 350 .resume = CHIP_resume,
351 }; 351 };
352 352
353The driver core will autmatically attempt to bind this driver to any SPI 353The driver core will automatically attempt to bind this driver to any SPI
354device whose board_info gave a modalias of "CHIP". Your probe() code 354device whose board_info gave a modalias of "CHIP". Your probe() code
355might look like this unless you're creating a device which is managing 355might look like this unless you're creating a device which is managing
356a bus (appearing under /sys/class/spi_master). 356a bus (appearing under /sys/class/spi_master).
diff --git a/Documentation/spi/spidev_test.c b/Documentation/spi/spidev_test.c
index c1a5aad3c75a..10abd3773e49 100644
--- a/Documentation/spi/spidev_test.c
+++ b/Documentation/spi/spidev_test.c
@@ -69,7 +69,7 @@ static void transfer(int fd)
69 puts(""); 69 puts("");
70} 70}
71 71
72void print_usage(const char *prog) 72static void print_usage(const char *prog)
73{ 73{
74 printf("Usage: %s [-DsbdlHOLC3]\n", prog); 74 printf("Usage: %s [-DsbdlHOLC3]\n", prog);
75 puts(" -D --device device to use (default /dev/spidev1.1)\n" 75 puts(" -D --device device to use (default /dev/spidev1.1)\n"
@@ -85,7 +85,7 @@ void print_usage(const char *prog)
85 exit(1); 85 exit(1);
86} 86}
87 87
88void parse_opts(int argc, char *argv[]) 88static void parse_opts(int argc, char *argv[])
89{ 89{
90 while (1) { 90 while (1) {
91 static const struct option lopts[] = { 91 static const struct option lopts[] = {
diff --git a/Documentation/sysctl/fs.txt b/Documentation/sysctl/fs.txt
index 1458448436cc..62682500878a 100644
--- a/Documentation/sysctl/fs.txt
+++ b/Documentation/sysctl/fs.txt
@@ -96,13 +96,16 @@ handles that the Linux kernel will allocate. When you get lots
96of error messages about running out of file handles, you might 96of error messages about running out of file handles, you might
97want to increase this limit. 97want to increase this limit.
98 98
99The three values in file-nr denote the number of allocated 99Historically, the three values in file-nr denoted the number of
100file handles, the number of unused file handles and the maximum 100allocated file handles, the number of allocated but unused file
101number of file handles. When the allocated file handles come 101handles, and the maximum number of file handles. Linux 2.6 always
102close to the maximum, but the number of unused file handles is 102reports 0 as the number of free file handles -- this is not an
103significantly greater than 0, you've encountered a peak in your 103error, it just means that the number of allocated file handles
104usage of file handles and you don't need to increase the maximum. 104exactly matches the number of used file handles.
105 105
106Attempts to allocate more file descriptors than file-max are
107reported with printk, look for "VFS: file-max limit <number>
108reached".
106============================================================== 109==============================================================
107 110
108nr_open: 111nr_open:
diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
index 2dbff53369d0..a028b92001ed 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.txt
@@ -22,6 +22,7 @@ show up in /proc/sys/kernel:
22- callhome [ S390 only ] 22- callhome [ S390 only ]
23- auto_msgmni 23- auto_msgmni
24- core_pattern 24- core_pattern
25- core_pipe_limit
25- core_uses_pid 26- core_uses_pid
26- ctrl-alt-del 27- ctrl-alt-del
27- dentry-state 28- dentry-state
@@ -135,6 +136,27 @@ core_pattern is used to specify a core dumpfile pattern name.
135 136
136============================================================== 137==============================================================
137 138
139core_pipe_limit:
140
141This sysctl is only applicable when core_pattern is configured to pipe core
142files to user space helper a (when the first character of core_pattern is a '|',
143see above). When collecting cores via a pipe to an application, it is
144occasionally usefull for the collecting application to gather data about the
145crashing process from its /proc/pid directory. In order to do this safely, the
146kernel must wait for the collecting process to exit, so as not to remove the
147crashing processes proc files prematurely. This in turn creates the possibility
148that a misbehaving userspace collecting process can block the reaping of a
149crashed process simply by never exiting. This sysctl defends against that. It
150defines how many concurrent crashing processes may be piped to user space
151applications in parallel. If this value is exceeded, then those crashing
152processes above that value are noted via the kernel log and their cores are
153skipped. 0 is a special value, indicating that unlimited processes may be
154captured in parallel, but that no waiting will take place (i.e. the collecting
155process is not guaranteed access to /proc/<crahing pid>/). This value defaults
156to 0.
157
158==============================================================
159
138core_uses_pid: 160core_uses_pid:
139 161
140The default coredump filename is "core". By setting 162The default coredump filename is "core". By setting
@@ -313,31 +335,43 @@ send before ratelimiting kicks in.
313 335
314============================================================== 336==============================================================
315 337
338printk_delay:
339
340Delay each printk message in printk_delay milliseconds
341
342Value from 0 - 10000 is allowed.
343
344==============================================================
345
316randomize-va-space: 346randomize-va-space:
317 347
318This option can be used to select the type of process address 348This option can be used to select the type of process address
319space randomization that is used in the system, for architectures 349space randomization that is used in the system, for architectures
320that support this feature. 350that support this feature.
321 351
3220 - Turn the process address space randomization off by default. 3520 - Turn the process address space randomization off. This is the
353 default for architectures that do not support this feature anyways,
354 and kernels that are booted with the "norandmaps" parameter.
323 355
3241 - Make the addresses of mmap base, stack and VDSO page randomized. 3561 - Make the addresses of mmap base, stack and VDSO page randomized.
325 This, among other things, implies that shared libraries will be 357 This, among other things, implies that shared libraries will be
326 loaded to random addresses. Also for PIE-linked binaries, the location 358 loaded to random addresses. Also for PIE-linked binaries, the
327 of code start is randomized. 359 location of code start is randomized. This is the default if the
360 CONFIG_COMPAT_BRK option is enabled.
328 361
329 With heap randomization, the situation is a little bit more 3622 - Additionally enable heap randomization. This is the default if
330 complicated. 363 CONFIG_COMPAT_BRK is disabled.
331 There a few legacy applications out there (such as some ancient 364
365 There are a few legacy applications out there (such as some ancient
332 versions of libc.so.5 from 1996) that assume that brk area starts 366 versions of libc.so.5 from 1996) that assume that brk area starts
333 just after the end of the code+bss. These applications break when 367 just after the end of the code+bss. These applications break when
334 start of the brk area is randomized. There are however no known 368 start of the brk area is randomized. There are however no known
335 non-legacy applications that would be broken this way, so for most 369 non-legacy applications that would be broken this way, so for most
336 systems it is safe to choose full randomization. However there is 370 systems it is safe to choose full randomization.
337 a CONFIG_COMPAT_BRK option for systems with ancient and/or broken 371
338 binaries, that makes heap non-randomized, but keeps all other 372 Systems with ancient and/or broken binaries should be configured
339 parts of process address space randomized if randomize_va_space 373 with CONFIG_COMPAT_BRK enabled, which excludes the heap from process
340 sysctl is turned on. 374 address space randomization.
341 375
342============================================================== 376==============================================================
343 377
diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
index faf62740aa2c..a6e360d2055c 100644
--- a/Documentation/sysctl/vm.txt
+++ b/Documentation/sysctl/vm.txt
@@ -624,7 +624,9 @@ caching of directory and inode objects.
624At the default value of vfs_cache_pressure=100 the kernel will attempt to 624At the default value of vfs_cache_pressure=100 the kernel will attempt to
625reclaim dentries and inodes at a "fair" rate with respect to pagecache and 625reclaim dentries and inodes at a "fair" rate with respect to pagecache and
626swapcache reclaim. Decreasing vfs_cache_pressure causes the kernel to prefer 626swapcache reclaim. Decreasing vfs_cache_pressure causes the kernel to prefer
627to retain dentry and inode caches. Increasing vfs_cache_pressure beyond 100 627to retain dentry and inode caches. When vfs_cache_pressure=0, the kernel will
628never reclaim dentries and inodes due to memory pressure and this can easily
629lead to out-of-memory conditions. Increasing vfs_cache_pressure beyond 100
628causes the kernel to prefer to reclaim dentries and inodes. 630causes the kernel to prefer to reclaim dentries and inodes.
629 631
630============================================================== 632==============================================================
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
3The tracing system kmem captures events related to object and page allocation
4within 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
12This document will describe what each of the tracepoints are and why they
13might be useful.
14
151. Slab allocation of small objects of unknown type
16===================================================
17kmalloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s
18kmalloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d
19kfree call_site=%lx ptr=%p
20
21Heavy activity for these events may indicate that a specific cache is
22justified, particularly if kmalloc slab pages are getting significantly
23internal fragmented as a result of the allocation pattern. By correlating
24kmalloc with kfree, it may be possible to identify memory leaks and where
25the allocation sites were.
26
27
282. Slab allocation of small objects of known type
29=================================================
30kmem_cache_alloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s
31kmem_cache_alloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d
32kmem_cache_free call_site=%lx ptr=%p
33
34These events are similar in usage to the kmalloc-related events except that
35it is likely easier to pin the event down to a specific cache. At the time
36of writing, no information is available on what slab is being allocated from,
37but the call_site can usually be used to extrapolate that information
38
393. Page allocation
40==================
41mm_page_alloc page=%p pfn=%lu order=%d migratetype=%d gfp_flags=%s
42mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d
43mm_page_free_direct page=%p pfn=%lu order=%d
44mm_pagevec_free page=%p pfn=%lu order=%d cold=%d
45
46These four events deal with page allocation and freeing. mm_page_alloc is
47a simple indicator of page allocator activity. Pages may be allocated from
48the per-CPU allocator (high performance) or the buddy allocator.
49
50If pages are allocated directly from the buddy allocator, the
51mm_page_alloc_zone_locked event is triggered. This event is important as high
52amounts of activity imply high activity on the zone->lock. Taking this lock
53impairs performance by disabling interrupts, dirtying cache lines between
54CPUs and serialising many CPUs.
55
56When a page is freed directly by the caller, the mm_page_free_direct event
57is triggered. Significant amounts of activity here could indicate that the
58callers should be batching their activities.
59
60When pages are freed using a pagevec, the mm_pagevec_free is
61triggered. Broadly speaking, pages are taken off the LRU lock in bulk and
62freed in batch with a pagevec. Significant amounts of activity here could
63indicate that the system is under memory pressure and can also indicate
64contention on the zone->lru_lock.
65
664. Per-CPU Allocator Activity
67=============================
68mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d
69mm_page_pcpu_drain page=%p pfn=%lu order=%d cpu=%d migratetype=%d
70
71In front of the page allocator is a per-cpu page allocator. It exists only
72for order-0 pages, reduces contention on the zone->lock and reduces the
73amount of writing on struct page.
74
75When a per-CPU list is empty or pages of the wrong type are allocated,
76the zone->lock will be taken once and the per-CPU list refilled. The event
77triggered is mm_page_alloc_zone_locked for each page allocated with the
78event indicating whether it is for a percpu_refill or not.
79
80When the per-CPU list is too full, a number of pages are freed, each one
81which triggers a mm_page_pcpu_drain event.
82
83The individual nature of the events are so that pages can be tracked
84between allocation and freeing. A number of drain or refill pages that occur
85consecutively imply the zone->lock being taken once. Large amounts of PCP
86refills and drains could imply an imbalance between CPUs where too much work
87is being concentrated in one place. It could also indicate that the per-CPU
88lists should be a larger size. Finally, large amounts of refills on one CPU
89and drains on another could be a factor in causing large amounts of cache
90line bounces due to writes between CPUs and worth investigating if pages
91can be allocated and freed on the same CPU through some algorithm change.
92
935. External Fragmentation
94=========================
95mm_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
97External fragmentation affects whether a high-order allocation will be
98successful or not. For some types of hardware, this is important although
99it is avoided where possible. If the system is using huge pages and needs
100to be able to resize the pool over the lifetime of the system, this value
101is important.
102
103Large numbers of this event implies that memory is fragmenting and
104high-order allocations will start failing at some time in the future. One
105means of reducing the occurange of this event is to increase the size of
106min_free_kbytes in increments of 3*pageblock_size*nr_online_nodes where
107pageblock_size is usually the size of the default hugepage size.
diff --git a/Documentation/trace/events.txt b/Documentation/trace/events.txt
index 2bcc8d4dea29..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
61. Introduction 61. Introduction
7=============== 7===============
@@ -22,12 +22,12 @@ tracing information should be printed.
22--------------------------------- 22---------------------------------
23 23
24The events which are available for tracing can be found in the file 24The 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
27To enable a particular event, such as 'sched_wakeup', simply echo it 27To enable a particular event, such as 'sched_wakeup', simply echo it
28to /debug/tracing/set_event. For example: 28to /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:
35To disable an event, echo the event name to the set_event file prefixed 35To disable an event, echo the event name to the set_event file prefixed
36with an exclamation point: 36with 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
40To disable all events, echo an empty line to the set_event file: 40To 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
44To enable all events, echo '*:*' or '*:' to the set_event file: 44To 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
48The events are organized into subsystems, such as ext4, irq, sched, 48The events are organized into subsystems, such as ext4, irq, sched,
49etc., and a full event name looks like this: <subsystem>:<event>. The 49etc., 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
53command: 53command:
54 54
55 # echo 'irq:*' > /debug/tracing/set_event 55 # echo 'irq:*' > /sys/kernel/debug/tracing/set_event
56 56
572.2 Via the 'enable' toggle 572.2 Via the 'enable' toggle
58--------------------------- 58---------------------------
59 59
60The events available are also listed in /debug/tracing/events/ hierarchy 60The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy
61of directories. 61of directories.
62 62
63To enable event 'sched_wakeup': 63To 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
67To disable it: 67To 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
71To enable all events in sched subsystem: 71To 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
75To eanble all events: 75To enable all events:
76 76
77 # echo 1 > /debug/tracing/events/enable 77 # echo 1 > /sys/kernel/debug/tracing/events/enable
78 78
79When reading one of these enable files, there are four results: 79When reading one of these enable files, there are four results:
80 80
@@ -97,3 +97,185 @@ The format of this boot option is the same as described in section 2.1.
97 97
98See The example provided in samples/trace_events 98See The example provided in samples/trace_events
99 99
1004. Event formats
101================
102
103Each trace event has a 'format' file associated with it that contains
104a description of each field in a logged event. This information can
105be used to parse the binary trace stream, and is also the place to
106find the field names that can be used in event filters (see section 5).
107
108It also displays the format string that will be used to print the
109event in text mode, along with the event name and ID used for
110profiling.
111
112Every event has a set of 'common' fields associated with it; these are
113the fields prefixed with 'common_'. The other fields vary between
114events and correspond to the fields defined in the TRACE_EVENT
115definition for that event.
116
117Each field in the format has the form:
118
119 field:field-type field-name; offset:N; size:N;
120
121where offset is the offset of the field in the trace record and size
122is the size of the data item, in bytes.
123
124For example, here's the information displayed for the 'sched_wakeup'
125event:
126
127# cat /debug/tracing/events/sched/sched_wakeup/format
128
129name: sched_wakeup
130ID: 60
131format:
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
144print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid,
145 REC->prio, REC->success, REC->cpu
146
147This event contains 10 fields, the first 5 common and the remaining 5
148event-specific. All the fields for this event are numeric, except for
149'comm' which is a string, a distinction important for event filtering.
150
1515. Event filtering
152==================
153
154Trace events can be filtered in the kernel by associating boolean
155'filter expressions' with them. As soon as an event is logged into
156the trace buffer, its fields are checked against the filter expression
157associated with that event type. An event with field values that
158'match' the filter will appear in the trace output, and an event whose
159values don't match will be discarded. An event with no filter
160associated with it matches everything, and is the default when no
161filter has been set for an event.
162
1635.1 Expression syntax
164---------------------
165
166A filter expression consists of one or more 'predicates' that can be
167combined using the logical operators '&&' and '||'. A predicate is
168simply a clause that compares the value of a field contained within a
169logged event with a constant value and returns either 0 or 1 depending
170on whether the field value matched (1) or didn't match (0):
171
172 field-name relational-operator value
173
174Parentheses can be used to provide arbitrary logical groupings and
175double-quotes can be used to prevent the shell from interpreting
176operators as shell metacharacters.
177
178The field-names available for use in filters can be found in the
179'format' files for trace events (see section 4).
180
181The relational-operators depend on the type of the field being tested:
182
183The operators available for numeric fields are:
184
185==, !=, <, <=, >, >=
186
187And for string fields they are:
188
189==, !=
190
191Currently, only exact string matches are supported.
192
193Currently, the maximum number of predicates in a filter is 16.
194
1955.2 Setting filters
196-------------------
197
198A filter for an individual event is set by writing a filter expression
199to the 'filter' file for the given event.
200
201For example:
202
203# cd /debug/tracing/events/sched/sched_wakeup
204# echo "common_preempt_count > 4" > filter
205
206A 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
211If there is an error in the expression, you'll get an 'Invalid
212argument' error when setting it, and the erroneous string along with
213an 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^
221parse_error: Field not found
222
223Currently the caret ('^') for an error always appears at the beginning of
224the filter string; the error message should still be useful though
225even without more accurate position info.
226
2275.3 Clearing filters
228--------------------
229
230To clear the filter for an event, write a '0' to the event's filter
231file.
232
233To clear the filters for all events in a subsystem, write a '0' to the
234subsystem's filter file.
235
2365.3 Subsystem filters
237---------------------
238
239For convenience, filters for every event in a subsystem can be set or
240cleared as a group by writing a filter expression into the filter file
241at the root of the subsytem. Note however, that if a filter for any
242event within the subsystem lacks a field specified in the subsystem
243filter, or if the filter can't be applied for any other reason, the
244filter for that event will retain its previous setting. This can
245result in an unintended mixture of filters which could lead to
246confusing (to the user who might think different filters are in
247effect) trace output. Only filters that reference just the common
248fields can be guaranteed to propagate successfully to all events.
249
250Here are a few subsystem filter examples that also illustrate the
251above points:
252
253Clear 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
258none
259# cat sched_wakeup/filter
260none
261
262Set a filter using only common fields for all events in the sched
263subsytem (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
268common_pid == 0
269# cat sched_wakeup/filter
270common_pid == 0
271
272Attempt to set a filter using a non-common field for all events in the
273sched subsytem (all events but those that have a prev_pid field retain
274their old filters):
275
276# cd /sys/kernel/debug/tracing/events/sched
277# echo prev_pid == 0 > filter
278# cat sched_switch/filter
279prev_pid == 0
280# cat sched_wakeup/filter
281common_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
4Introduction
5------------
6
7Here we will cover the architecture pieces that the common function tracing
8code relies on for proper functioning. Things are broken down into increasing
9complexity so that you can start simple and at least get basic functionality.
10
11Note that this focuses on architecture implementation details only. If you
12want more explanation of a feature in terms of common code, review the common
13ftrace.txt file.
14
15
16Prerequisites
17-------------
18
19Ftrace relies on these features being implemented:
20 STACKTRACE_SUPPORT - implement save_stack_trace()
21 TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h
22
23
24HAVE_FUNCTION_TRACER
25--------------------
26
27You will need to implement the mcount and the ftrace_stub functions.
28
29The 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
31running something like:
32 $ echo 'main(){}' | gcc -x c -S -o - - -pg | grep mcount
33 call mcount
34We'll make the assumption below that the symbol is "mcount" just to keep things
35nice and simple in the examples.
36
37Keep 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,
39sorry. Dig up some old documentation and/or find someone more familiar than
40you to bang ideas off of. Typically, register usage (argument/scratch/etc...)
41is a major issue at this point, especially in relation to the location of the
42mcount call (before/after function prologue). You might also want to look at
43how glibc has implemented the mcount function for your architecture. It might
44be (semi-)relevant.
45
46The mcount function should check the function pointer ftrace_trace_function
47to see if it is set to ftrace_stub. If it is, there is nothing for you to do,
48so return immediately. If it isn't, then call that function in the same way
49the mcount function normally calls __mcount_internal -- the first argument is
50the "frompc" while the second argument is the "selfpc" (adjusted to remove the
51size of the mcount call that is embedded in the function).
52
53For example, if the function foo() calls bar(), when the bar() function calls
54mcount(), 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
58Also keep in mind that this mcount function will be called *a lot*, so
59optimizing for the default case of no tracer will help the smooth running of
60your system when tracing is disabled. So the start of the mcount function is
61typically the bare min with checking things before returning. That also means
62the code flow should usually kept linear (i.e. no branching in the nop case).
63This is of course an optimization and not a hard requirement.
64
65Here is some pseudo code that should help (these functions should actually be
66implemented in assembly):
67
68void ftrace_stub(void)
69{
70 return;
71}
72
73void 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
85do_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
96Don't forget to export mcount for modules !
97extern void mcount(void);
98EXPORT_SYMBOL(mcount);
99
100
101HAVE_FUNCTION_TRACE_MCOUNT_TEST
102-------------------------------
103
104This is an optional optimization for the normal case when tracing is turned off
105in the system. If you do not enable this Kconfig option, the common ftrace
106code will take care of doing the checking for you.
107
108To support this feature, you only need to check the function_trace_stop
109variable in the mcount function. If it is non-zero, there is no tracing to be
110done at all, so you can return.
111
112This additional pseudo code would simply be:
113void 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
125HAVE_FUNCTION_GRAPH_TRACER
126--------------------------
127
128Deep breath ... time to do some real work. Here you will need to update the
129mcount function to check ftrace graph function pointers, as well as implement
130some functions to save (hijack) and restore the return address.
131
132The mcount function should check the function pointers ftrace_graph_return
133(compare to ftrace_stub) and ftrace_graph_entry (compare to
134ftrace_graph_entry_stub). If either of those are not set to the relevant stub
135function, call the arch-specific function ftrace_graph_caller which in turn
136calls the arch-specific function prepare_ftrace_return. Neither of these
137function names are strictly required, but you should use them anyways to stay
138consistent across the architecture ports -- easier to compare & contrast
139things.
140
141The arguments to prepare_ftrace_return are slightly different than what are
142passed to ftrace_trace_function. The second argument "selfpc" is the same,
143but the first argument should be a pointer to the "frompc". Typically this is
144located on the stack. This allows the function to hijack the return address
145temporarily to have it point to the arch-specific function return_to_handler.
146That function will simply call the common ftrace_return_to_handler function and
147that will return the original return address with which, you can return to the
148original call site.
149
150Here is the updated mcount pseudo code:
151void 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
168Here is the pseudo code for the new ftrace_graph_caller assembly function:
169#ifdef CONFIG_FUNCTION_GRAPH_TRACER
170void 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
182For information on how to implement prepare_ftrace_return(), simply look at
183the x86 version. The only architecture-specific piece in it is the setup of
184the fault recovery table (the asm(...) code). The rest should be the same
185across architectures.
186
187Here is the pseudo code for the new return_to_handler assembly function. Note
188that the ABI that applies here is different from what applies to the mcount
189code. Since you are returning from a function (after the epilogue), you might
190be able to skimp on things saved/restored (usually just registers used to pass
191return values).
192
193#ifdef CONFIG_FUNCTION_GRAPH_TRACER
194void 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
208HAVE_FTRACE_NMI_ENTER
209---------------------
210
211If you can't trace NMI functions, then skip this option.
212
213<details to be filled>
214
215
216HAVE_FTRACE_SYSCALLS
217---------------------
218
219<details to be filled>
220
221
222HAVE_FTRACE_MCOUNT_RECORD
223-------------------------
224
225See scripts/recordmcount.pl for more info.
226
227<details to be filled>
228
229
230HAVE_DYNAMIC_FTRACE
231---------------------
232
233<details to be filled>
diff --git a/Documentation/trace/ftrace.txt b/Documentation/trace/ftrace.txt
index 355d0f1f8c50..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
26means that the list of tracers can always grow). 26means that the list of tracers can always grow).
27 27
28 28
29Implementation Details
30----------------------
31
32See ftrace-design.txt for details for arch porters and such.
33
34
29The File System 35The File System
30--------------- 36---------------
31 37
@@ -127,7 +133,7 @@ of ftrace. Here is a list of some of the key files:
127 than requested, the rest of the page will be used, 133 than requested, the rest of the page will be used,
128 making the actual allocation bigger than requested. 134 making the actual allocation bigger than requested.
129 ( 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
130 due to buffer managment overhead. ) 136 due to buffer management overhead. )
131 137
132 This can only be updated when the current_tracer 138 This can only be updated when the current_tracer
133 is set to "nop". 139 is set to "nop".
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>
15use strict;
16use Getopt::Long;
17
18# Tracepoint events
19use constant MM_PAGE_ALLOC => 1;
20use constant MM_PAGE_FREE_DIRECT => 2;
21use constant MM_PAGEVEC_FREE => 3;
22use constant MM_PAGE_PCPU_DRAIN => 4;
23use constant MM_PAGE_ALLOC_ZONE_LOCKED => 5;
24use constant MM_PAGE_ALLOC_EXTFRAG => 6;
25use constant EVENT_UNKNOWN => 7;
26
27# Constants used to track state
28use constant STATE_PCPU_PAGES_DRAINED => 8;
29use constant STATE_PCPU_PAGES_REFILLED => 9;
30
31# High-level events extrapolated from tracepoints
32use constant HIGH_PCPU_DRAINS => 10;
33use constant HIGH_PCPU_REFILLS => 11;
34use constant HIGH_EXT_FRAGMENT => 12;
35use constant HIGH_EXT_FRAGMENT_SEVERE => 13;
36use constant HIGH_EXT_FRAGMENT_MODERATE => 14;
37use constant HIGH_EXT_FRAGMENT_CHANGED => 15;
38
39my %perprocesspid;
40my %perprocess;
41my $opt_ignorepid;
42my $opt_read_procstat;
43my $opt_prepend_parent;
44
45# Catch sigint and exit on request
46my $sigint_report = 0;
47my $sigint_exit = 0;
48my $sigint_pending = 0;
49my $sigint_received = 0;
50sub 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
73GetOptions(
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
80my $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
83my $regex_fragdetails;
84
85# Static regex used. Specified like this for readability and for use with /o
86# (process_pid) (cpus ) ( time ) (tpoint ) (details)
87my $regex_traceevent = '\s*([a-zA-Z0-9-]*)\s*(\[[0-9]*\])\s*([0-9.]*):\s*([a-zA-Z_]*):\s*(.*)';
88my $regex_statname = '[-0-9]*\s\((.*)\).*';
89my $regex_statppid = '[-0-9]*\s\(.*\)\s[A-Za-z]\s([0-9]*).*';
90
91sub 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
136sub 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
152sub 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
166sub 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
184sub 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
194EVENT_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
298sub 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
353sub 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
381sub 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
391sub 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
417signal_loop();
418report();
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 @@
1The power tracer collects detailed information about C-state and P-state
2transitions, instead of just looking at the high-level "average"
3information.
4
5There is a helper script found in scrips/tracing/power.pl in the kernel
6sources which can be used to parse this information and create a
7Scalable Vector Graphics (SVG) picture from the trace data.
8
9To 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/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
61. Introduction
7===============
8
9Tracepoints (see Documentation/trace/tracepoints.txt) can be used without
10creating custom kernel modules to register probe functions using the event
11tracing infrastructure.
12
13Simplistically, tracepoints will represent an important event that when can
14be taken in conjunction with other tracepoints to build a "Big Picture" of
15what is going on within the system. There are a large number of methods for
16gathering and interpreting these events. Lacking any current Best Practises,
17this document describes some of the methods that can be used.
18
19This document assumes that debugfs is mounted on /sys/kernel/debug and that
20the appropriate tracing options have been configured into the kernel. It is
21assumed that the PCL tool tools/perf has been installed and is in your path.
22
232. Listing Available Events
24===========================
25
262.1 Standard Utilities
27----------------------
28
29All possible events are visible from /sys/kernel/debug/tracing/events. Simply
30calling
31
32 $ find /sys/kernel/debug/tracing/events -type d
33
34will give a fair indication of the number of events available.
35
362.2 PCL
37-------
38
39Discovery and enumeration of all counters and events, including tracepoints
40are available with the perf tool. Getting a list of available events is a
41simple 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
522. Enabling Events
53==================
54
552.1 System-Wide Event Enabling
56------------------------------
57
58See Documentation/trace/events.txt for a proper description on how events
59can be enabled system-wide. A short example of enabling all events related
60to 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
642.2 System-Wide Event Enabling with SystemTap
65---------------------------------------------
66
67In SystemTap, tracepoints are accessible using the kernel.trace() function
68call. The following is an example that reports every 5 seconds what processes
69were 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
892.3 System-Wide Event Enabling with PCL
90---------------------------------------
91
92By specifying the -a switch and analysing sleep, the system-wide events
93for 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
107Similarly, one could execute a shell and exit it as desired to get a report
108at that point.
109
1102.4 Local Event Enabling
111------------------------
112
113Documentation/trace/ftrace.txt describes how to enable events on a per-thread
114basis using set_ftrace_pid.
115
1162.5 Local Event Enablement with PCL
117-----------------------------------
118
119Events can be activate and tracked for the duration of a process on a local
120basis 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
1343. Event Filtering
135==================
136
137Documentation/trace/ftrace.txt covers in-depth how to filter events in
138ftrace. Obviously using grep and awk of trace_pipe is an option as well
139as any script reading trace_pipe.
140
1414. Analysing Event Variances with PCL
142=====================================
143
144Any workload can exhibit variances between runs and it can be important
145to know what the standard deviation in. By and large, this is left to the
146performance analyst to do it by hand. In the event that the discrete event
147occurrences 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
165In the event that some higher-level event is required that depends on some
166aggregation of discrete events, then a script would need to be developed.
167
168Using --repeat, it is also possible to view how events are fluctuating over
169time 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
1835. Higher-Level Analysis with Helper Scripts
184============================================
185
186When 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
188options exist as well. By post-processing the output, further information can
189be 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
195Documentation/trace/postprocess/trace-pagealloc-postprocess.pl is an example
196script that can read trace_pipe from STDIN or a copy of a trace. When used
197on-line, it can be interrupted once to generate a report without existing
198and twice to exit.
199
200Simplistically, the script just reads STDIN and counts up events but it
201also 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
2156. Lower-Level Analysis with PCL
216================================
217
218There may also be a requirement to identify what functions with a program
219were generating events within the kernel. To begin this sort of analysis, the
220data 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
229Note the use of '-c 1' to set the event period to sample. The default sample
230period is quite high to minimise overhead but the information collected can be
231very coarse as a result.
232
233This record outputted a file called perf.data which can be analysed using
234perf 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
256According to this, the vast majority of events occured triggered on events
257within the VDSO. With simple binaries, this will often be the case so lets
258take a slightly different example. In the course of writing this, it was
259noticed that X was generating an insane amount of page allocations so lets look
260at 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
267This 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
283So, almost half of the events are occuring in a library. To get an idea which
284symbol.
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
300To 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
323At a glance, it looks like the time is being spent copying pixmaps to
324the card. Further investigation would be needed to determine why pixmaps
325are being copied around so much but a starting point would be to take an
326ancient build of libpixmap out of the library path where it was totally
327forgotten about from months ago!
diff --git a/Documentation/usb/authorization.txt b/Documentation/usb/authorization.txt
index 381b22ee7834..c069b6884c77 100644
--- a/Documentation/usb/authorization.txt
+++ b/Documentation/usb/authorization.txt
@@ -16,20 +16,20 @@ Usage:
16 16
17Authorize a device to connect: 17Authorize a device to connect:
18 18
19$ echo 1 > /sys/usb/devices/DEVICE/authorized 19$ echo 1 > /sys/bus/usb/devices/DEVICE/authorized
20 20
21Deauthorize a device: 21Deauthorize a device:
22 22
23$ echo 0 > /sys/usb/devices/DEVICE/authorized 23$ echo 0 > /sys/bus/usb/devices/DEVICE/authorized
24 24
25Set new devices connected to hostX to be deauthorized by default (ie: 25Set new devices connected to hostX to be deauthorized by default (ie:
26lock down): 26lock down):
27 27
28$ echo 0 > /sys/bus/devices/usbX/authorized_default 28$ echo 0 > /sys/bus/usb/devices/usbX/authorized_default
29 29
30Remove the lock down: 30Remove the lock down:
31 31
32$ echo 1 > /sys/bus/devices/usbX/authorized_default 32$ echo 1 > /sys/bus/usb/devices/usbX/authorized_default
33 33
34By default, Wired USB devices are authorized by default to 34By default, Wired USB devices are authorized by default to
35connect. Wireless USB hosts deauthorize by default all new connected 35connect. Wireless USB hosts deauthorize by default all new connected
@@ -47,7 +47,7 @@ USB port):
47boot up 47boot up
48rc.local -> 48rc.local ->
49 49
50 for host in /sys/bus/devices/usb* 50 for host in /sys/bus/usb/devices/usb*
51 do 51 do
52 echo 0 > $host/authorized_default 52 echo 0 > $host/authorized_default
53 done 53 done
diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt
index 6c3c625b7f30..66f92d1194c1 100644
--- a/Documentation/usb/usbmon.txt
+++ b/Documentation/usb/usbmon.txt
@@ -33,7 +33,7 @@ if usbmon is built into the kernel.
33 33
34Verify that bus sockets are present. 34Verify that bus sockets are present.
35 35
36# ls /sys/kernel/debug/usbmon 36# ls /sys/kernel/debug/usb/usbmon
370s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u 370s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u
38# 38#
39 39
@@ -58,11 +58,11 @@ Bus=03 means it's bus 3.
58 58
593. Start 'cat' 593. Start 'cat'
60 60
61# cat /sys/kernel/debug/usbmon/3u > /tmp/1.mon.out 61# cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out
62 62
63to listen on a single bus, otherwise, to listen on all buses, type: 63to listen on a single bus, otherwise, to listen on all buses, type:
64 64
65# cat /sys/kernel/debug/usbmon/0u > /tmp/1.mon.out 65# cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out
66 66
67This process will be reading until killed. Naturally, the output can be 67This process will be reading until killed. Naturally, the output can be
68redirected to a desirable location. This is preferred, because it is going 68redirected to a desirable location. This is preferred, because it is going
@@ -305,7 +305,7 @@ Before the call, hdr, data, and alloc should be filled. Upon return, the area
305pointed by hdr contains the next event structure, and the data buffer contains 305pointed by hdr contains the next event structure, and the data buffer contains
306the data, if any. The event is removed from the kernel buffer. 306the data, if any. The event is removed from the kernel buffer.
307 307
308The MON_IOCX_GET copies 48 bytes, MON_IOCX_GETX copies 64 bytes. 308The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes.
309 309
310 MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg) 310 MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)
311 311
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
2VGA Arbiter
3===========
4
5Graphic devices are accessed through ranges in I/O or memory space. While most
6modern devices allow relocation of such ranges, some "Legacy" VGA devices
7implemented on PCI will typically have the same "hard-decoded" addresses as
8they did on ISA. For more details see "PCI Bus Binding to IEEE Std 1275-1994
9Standard for Boot (Initialization Configuration) Firmware Revision 2.1"
10Section 7, Legacy Devices.
11
12The Resource Access Control (RAC) module inside the X server [0] existed for
13the legacy VGA arbitration task (besides other bus management tasks) when more
14than one legacy device co-exists on the same machine. But the problem happens
15when these devices are trying to be accessed by different userspace clients
16(e.g. two server in parallel). Their address assignments conflict. Moreover,
17ideally, being an userspace application, it is not the role of the the X
18server to control bus resources. Therefore an arbitration scheme outside of
19the X server is needed to control the sharing of these resources. This
20document introduces the operation of the VGA arbiter implemented for Linux
21kernel.
22
23----------------------------------------------------------------------------
24
25I. Details and Theory of Operation
26 I.1 vgaarb
27 I.2 libpciaccess
28 I.3 xf86VGAArbiter (X server implementation)
29II. Credits
30III.References
31
32
33I. Details and Theory of Operation
34==================================
35
36I.1 vgaarb
37----------
38
39The vgaarb is a module of the Linux Kernel. When it is initially loaded, it
40scans all PCI devices and adds the VGA ones inside the arbitration. The
41arbiter then enables/disables the decoding on different devices of the VGA
42legacy instructions. Device which do not want/need to use the arbiter may
43explicitly tell it by calling vga_set_legacy_decoding().
44
45The kernel exports a char device interface (/dev/vga_arbiter) to the clients,
46which 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
85Note about locks:
86
87The driver keeps track of which user has which locks on which card. It
88supports stacking, like the kernel one. This complexifies the implementation
89a bit, but makes the arbiter more tolerant to user space problems and able
90to properly cleanup in all cases when a process dies.
91Currently, a max of 16 cards can have locks simultaneously issued from
92user space for a given user (file descriptor instance) of the arbiter.
93
94In the case of devices hot-{un,}plugged, there is a hook - pci_notify() - to
95notify them being added/removed in the system and automatically added/removed
96in the arbiter.
97
98There's also a in-kernel API of the arbiter in the case of DRM, vgacon and
99others which may use the arbiter.
100
101
102I.2 libpciaccess
103----------------
104
105To use the vga arbiter char device it was implemented an API inside the
106libpciaccess library. One fieldd was added to struct pci_device (each device
107on the system):
108
109 /* the type of resource decoded by the device */
110 int vgaarb_rsrc;
111
112Besides 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
120The vga_count is usually need to keep informed how many cards are being
121arbitrated, so for instance if there's only one then it can totally escape the
122scheme.
123
124
125These functions below acquire VGA resources for the given card and mark those
126resources as locked. If the resources requested are "normal" (and not legacy)
127resources, the arbiter will first check whether the card is doing legacy
128decoding for that type of resource. If yes, the lock is "converted" into a
129legacy resource lock. The arbiter will first look for all VGA cards that
130might conflict and disable their IOs and/or Memory access, including VGA
131forwarding on P2P bridges if necessary, so that the requested resources can
132be used. Then, the card is marked as locking these resources and the IO and/or
133Memory access is enabled on the card (including VGA forwarding on parent
134P2P bridges if any). In the case of vga_arb_lock(), the function will block
135if some conflicting card is already locking one of the required resources (or
136any resource on a different bus segment, since P2P bridges don't differentiate
137VGA memory and IO afaik). If the card already owns the resources, the function
138succeeds. vga_arb_trylock() will return (-EBUSY) instead of blocking. Nested
139calls are supported (a per-resource counter is maintained).
140
141
142Set the target device of this client.
143 int pci_device_vgaarb_set_target (struct pci_device *dev);
144
145
146For instance, in x86 if two devices on the same bus want to lock different
147resources, both will succeed (lock). If devices are in different buses and
148trying 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
152Unlock resources of device.
153 int pci_device_vgaarb_unlock (void);
154
155Indicates to the arbiter if the card decodes legacy VGA IOs, legacy VGA
156Memory, both, or none. All cards default to both, the card driver (fbdev for
157example) should tell the arbiter if it has disabled legacy decoding, so the
158card can be left out of the arbitration process (and can be safe to take
159interrupts at any time.
160 int pci_device_vgaarb_decodes (int new_vgaarb_rsrc);
161
162Connects to the arbiter device, allocates the struct
163 int pci_device_vgaarb_init (void);
164
165Close the connection
166 void pci_device_vgaarb_fini (void);
167
168
169I.3 xf86VGAArbiter (X server implementation)
170--------------------------------------------
171
172(TODO)
173
174X server basically wraps all the functions that touch VGA registers somehow.
175
176
177II. Credits
178===========
179
180Benjamin Herrenschmidt (IBM?) started this work when he discussed such design
181with the Xorg community in 2005 [1, 2]. In the end of 2007, Paulo Zanoni and
182Tiago Vignatti (both of C3SL/Federal University of Paraná) proceeded his work
183enhancing the kernel code to adapt as a kernel module and also did the
184implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave
185Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree.
186
187
188III. 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 525edb37c758..5f33d8486102 100644
--- a/Documentation/video4linux/CARDLIST.cx23885
+++ b/Documentation/video4linux/CARDLIST.cx23885
@@ -23,3 +23,4 @@
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] 24 23 -> Magic-Pro ProHDTV Extreme 2 [14f1:8657]
25 24 -> Hauppauge WinTV-HVR1850 [0070:8541] 25 24 -> Hauppauge WinTV-HVR1850 [0070:8541]
26 25 -> Compro VideoMate E800 [1858:e800]
diff --git a/Documentation/video4linux/CARDLIST.em28xx b/Documentation/video4linux/CARDLIST.em28xx
index b13fcbd5d94b..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:2710,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]
@@ -68,3 +68,4 @@
68 70 -> Evga inDtube (em2882) 68 70 -> Evga inDtube (em2882)
69 71 -> Silvercrest Webcam 1.3mpix (em2820/em2840) 69 71 -> Silvercrest Webcam 1.3mpix (em2820/em2840)
70 72 -> Gadmei UTV330+ (em2861) 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 0ac4d2544778..2620d60341ee 100644
--- a/Documentation/video4linux/CARDLIST.saa7134
+++ b/Documentation/video4linux/CARDLIST.saa7134
@@ -171,3 +171,4 @@
171170 -> AverMedia AverTV Studio 505 [1461:a115] 171170 -> AverMedia AverTV Studio 505 [1461:a115]
172171 -> Beholder BeholdTV X7 [5ace:7595] 172171 -> Beholder BeholdTV X7 [5ace:7595]
173172 -> RoverMedia TV Link Pro FM [19d1:0138] 173172 -> RoverMedia TV Link Pro FM [19d1:0138]
174173 -> 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 ba9fa679e2d3..e0d298fe8830 100644
--- a/Documentation/video4linux/CARDLIST.tuner
+++ b/Documentation/video4linux/CARDLIST.tuner
@@ -79,3 +79,5 @@ tuner=78 - Philips FMD1216MEX MK3 Hybrid Tuner
79tuner=79 - Philips PAL/SECAM multi (FM1216 MK5) 79tuner=79 - Philips PAL/SECAM multi (FM1216 MK5)
80tuner=80 - Philips FQ1216LME MK3 PAL/SECAM w/active loopthrough 80tuner=80 - Philips FQ1216LME MK3 PAL/SECAM w/active loopthrough
81tuner=81 - Partsnic (Daewoo) PTI-5NF05 81tuner=81 - Partsnic (Daewoo) PTI-5NF05
82tuner=82 - Philips CU1216L
83tuner=83 - NXP TDA18271
diff --git a/Documentation/video4linux/gspca.txt b/Documentation/video4linux/gspca.txt
index 4686e84dd800..3f61825be499 100644
--- a/Documentation/video4linux/gspca.txt
+++ b/Documentation/video4linux/gspca.txt
@@ -173,6 +173,8 @@ ov519 05a9:8519 OmniVision
173ov519 05a9:a518 D-Link DSB-C310 Webcam 173ov519 05a9:a518 D-Link DSB-C310 Webcam
174sunplus 05da:1018 Digital Dream Enigma 1.3 174sunplus 05da:1018 Digital Dream Enigma 1.3
175stk014 05e1:0893 Syntek DV4000 175stk014 05e1:0893 Syntek DV4000
176gl860 05e3:0503 Genesys Logic PC Camera
177gl860 05e3:f191 Genesys Logic PC Camera
176spca561 060b:a001 Maxell Compact Pc PM3 178spca561 060b:a001 Maxell Compact Pc PM3
177zc3xx 0698:2003 CTX M730V built in 179zc3xx 0698:2003 CTX M730V built in
178spca500 06bd:0404 Agfa CL20 180spca500 06bd:0404 Agfa CL20
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.
116struct soc_camera_device also links to an array of struct soc_camera_data_format, 116struct soc_camera_device also links to an array of struct soc_camera_data_format,
117listing pixel formats, supported by the camera. 117listing pixel formats, supported by the camera.
118 118
119VIDIOC_S_CROP and VIDIOC_S_FMT behaviour
120----------------------------------------
121
122Above user ioctls modify image geometry as follows:
123
124VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensor
125pixel. Changing sensor window sizes preserves any scaling factors, therefore
126user window sizes change as well.
127
128VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window as
129much as possible by modifying scaling factors. If the sensor window cannot be
130preserved precisely, it may be changed too.
131
132In soc-camera there are two locations, where scaling and cropping can taks
133place: in the camera driver and in the host driver. User ioctls are first passed
134to the host driver, which then generally passes them down to the camera driver.
135It is more efficient to perform scaling and cropping in the camera driver to
136save camera bus bandwidth and maximise the framerate. However, if the camera
137driver failed to set the required parameters with sufficient precision, the host
138driver may decide to also use its own scaling and cropping to fulfill the user's
139request.
140
141Camera drivers are interfaced to the soc-camera core and to host drivers over
142the v4l2-subdev API, which is completely functional, it doesn't pass any data.
143Therefore all camera drivers shall reply to .g_fmt() requests with their current
144output 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
146factors have to be maintained by camera drivers internally. According to the
147V4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence we
148rely on camera drivers implementing .cropcap(). If the camera driver does not
149support cropping, it may choose to not implement .s_crop(), but to enable
150cropping support by the camera host driver at least the .g_crop method must be
151implemented.
152
153User window geometry is kept in .user_width and .user_height fields in struct
154soc_camera_device and used by the soc-camera core and host drivers. The core
155updates these fields upon successful completion of a .s_fmt() call, but if these
156fields change elsewhere, e.g., during .s_crop() processing, the host driver is
157responsible for updating them.
158
119-- 159--
120Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de> 160Author: 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.
370The bridge driver also has some helper functions it can use: 370The bridge driver also has some helper functions it can use:
371 371
372struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter, 372struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
373 "module_foo", "chipid", 0x36); 373 "module_foo", "chipid", 0x36, NULL);
374 374
375This loads the given module (can be NULL if no module needs to be loaded) and 375This loads the given module (can be NULL if no module needs to be loaded) and
376calls i2c_new_device() with the given i2c_adapter and chip/address arguments. 376calls i2c_new_device() with the given i2c_adapter and chip/address arguments.
377If all goes well, then it registers the subdev with the v4l2_device. 377If all goes well, then it registers the subdev with the v4l2_device.
378 378
379You can also use v4l2_i2c_new_probed_subdev() which is very similar to 379You can also use the last argument of v4l2_i2c_new_subdev() to pass an array
380v4l2_i2c_new_subdev(), except that it has an array of possible I2C addresses 380of possible I2C addresses that it should probe. These probe addresses are
381that it should probe. Internally it calls i2c_new_probed_device(). 381only used if the previous argument is 0. A non-zero argument means that you
382know the exact i2c address so in that case no probing will take place.
382 383
383Both functions return NULL if something went wrong. 384Both functions return NULL if something went wrong.
384 385
385Note that the chipid you pass to v4l2_i2c_new_(probed_)subdev() is usually 386Note that the chipid you pass to v4l2_i2c_new_subdev() is usually
386the same as the module name. It allows you to specify a chip variant, e.g. 387the 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.
388The use of chipid is something that needs to be looked at more closely at a 389The 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
410v4l2_i2c_new_(probed_)subdev functions will call s_config as well, but with 411v4l2_i2c_new_(probed_)subdev functions will call s_config as well, but with
411irq set to 0 and platform_data set to NULL. 412irq set to 0 and platform_data set to NULL.
412 413
413Note that in the next kernel release the functions v4l2_i2c_new_subdev,
414v4l2_i2c_new_probed_subdev and v4l2_i2c_new_probed_subdev_addr will all be
415replaced by a single v4l2_i2c_new_subdev that is identical to
416v4l2_i2c_new_subdev_cfg but without the irq and platform_data arguments.
417
418struct video_device 414struct video_device
419------------------- 415-------------------
420 416
@@ -490,31 +486,35 @@ VFL_TYPE_RADIO: radioX for radio tuners
490VFL_TYPE_VTX: vtxX for teletext devices (deprecated, don't use) 486VFL_TYPE_VTX: vtxX for teletext devices (deprecated, don't use)
491 487
492The last argument gives you a certain amount of control over the device 488The last argument gives you a certain amount of control over the device
493kernel number used (i.e. the X in videoX). Normally you will pass -1 to 489device node number used (i.e. the X in videoX). Normally you will pass -1
494let the v4l2 framework pick the first free number. But if a driver creates 490to let the v4l2 framework pick the first free number. But sometimes users
495many devices, then it can be useful to have different video devices in 491want to select a specific node number. It is common that drivers allow
496separate ranges. For example, video capture devices start at 0, video 492the user to select a specific device node number through a driver module
497output devices start at 16. 493option. That number is then passed to this function and video_register_device
498 494will attempt to select that device node number. If that number was already
499So you can use the last argument to specify a minimum kernel number and 495in use, then the next free device node number will be selected and it
500the v4l2 framework will try to pick the first free number that is equal 496will send a warning to the kernel log.
497
498Another use-case is if a driver creates many devices. In that case it can
499be useful to place different video devices in separate ranges. For example,
500video capture devices start at 0, video output devices start at 16.
501So you can use the last argument to specify a minimum device node number
502and the v4l2 framework will try to pick the first free number that is equal
501or higher to what you passed. If that fails, then it will just pick the 503or higher to what you passed. If that fails, then it will just pick the
502first free number. 504first free number.
503 505
506Since in this case you do not care about a warning about not being able
507to select the specified device node number, you can call the function
508video_register_device_no_warn() instead.
509
504Whenever a device node is created some attributes are also created for you. 510Whenever a device node is created some attributes are also created for you.
505If you look in /sys/class/video4linux you see the devices. Go into e.g. 511If you look in /sys/class/video4linux you see the devices. Go into e.g.
506video0 and you will see 'name' and 'index' attributes. The 'name' attribute 512video0 and you will see 'name' and 'index' attributes. The 'name' attribute
507is the 'name' field of the video_device struct. The 'index' attribute is 513is the 'name' field of the video_device struct.
508a device node index that can be assigned by the driver, or that is calculated
509for you.
510
511If you call video_register_device(), then the index is just increased by
5121 for each device node you register. The first video device node you register
513always starts off with 0.
514 514
515Alternatively you can call video_register_device_index() which is identical 515The 'index' attribute is the index of the device node: for each call to
516to video_register_device(), but with an extra index argument. Here you can 516video_register_device() the index is just increased by 1. The first video
517pass a specific index value (between 0 and 31) that should be used. 517device node you register always starts with index 0.
518 518
519Users can setup udev rules that utilize the index attribute to make fancy 519Users can setup udev rules that utilize the index attribute to make fancy
520device names (e.g. 'mpegX' for MPEG video capture device nodes). 520device 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
530If the registration failed, then you need to call video_device_release() 529If the registration failed, then you need to call video_device_release()
531to free the allocated video_device struct, or free your own struct if the 530to free the allocated video_device struct, or free your own struct if the
diff --git a/Documentation/video4linux/v4lgrab.c b/Documentation/video4linux/v4lgrab.c
index 05769cff1009..c8ded175796e 100644
--- a/Documentation/video4linux/v4lgrab.c
+++ b/Documentation/video4linux/v4lgrab.c
@@ -89,7 +89,7 @@
89 } \ 89 } \
90} 90}
91 91
92int get_brightness_adj(unsigned char *image, long size, int *brightness) { 92static int get_brightness_adj(unsigned char *image, long size, int *brightness) {
93 long i, tot = 0; 93 long i, tot = 0;
94 for (i=0;i<size*3;i++) 94 for (i=0;i<size*3;i++)
95 tot += image[i]; 95 tot += image[i];
diff --git a/Documentation/vm/.gitignore b/Documentation/vm/.gitignore
index 33e8a023df02..09b164a5700f 100644
--- a/Documentation/vm/.gitignore
+++ b/Documentation/vm/.gitignore
@@ -1 +1,2 @@
1page-types
1slabinfo 2slabinfo
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.
7hugetlbpage.txt 7hugetlbpage.txt
8 - a brief summary of hugetlbpage support in the Linux kernel. 8 - a brief summary of hugetlbpage support in the Linux kernel.
9ksm.txt
10 - how to use the Kernel Samepage Merging feature.
9locking 11locking
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.
11numa 13numa
@@ -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.
21slub.txt 23slub.txt
22 - a short users guide for SLUB. 24 - a short users guide for SLUB.
25map_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
18automatically when CONFIG_HUGETLBFS is selected) configuration 18automatically when CONFIG_HUGETLBFS is selected) configuration
19options. 19options.
20 20
21The kernel built with hugepage support should show the number of configured 21The kernel built with huge page support should show the number of configured
22hugepages in the system by running the "cat /proc/meminfo" command. 22huge 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
25pages configured in the kernel. It also displays information about the 25pages configured in the kernel. It also displays information about the
26number of free hugetlb pages at any time. It also displays information about 26number of free hugetlb pages at any time. It also displays information about
27the configured hugepage size - this is needed for generating the proper 27the configured huge page size - this is needed for generating the proper
28alignment and size of the arguments to the above system calls. 28alignment and size of the arguments to the above system calls.
29 29
30The output of "cat /proc/meminfo" will have lines like: 30The output of "cat /proc/meminfo" will have lines like:
@@ -37,25 +37,27 @@ HugePages_Surp: yyy
37Hugepagesize: zzz kB 37Hugepagesize: zzz kB
38 38
39where: 39where:
40HugePages_Total is the size of the pool of hugepages. 40HugePages_Total is the size of the pool of huge pages.
41HugePages_Free is the number of hugepages in the pool that are not yet 41HugePages_Free is the number of huge pages in the pool that are not yet
42allocated. 42 allocated.
43HugePages_Rsvd is short for "reserved," and is the number of hugepages 43HugePages_Rsvd is short for "reserved," and is the number of huge pages for
44for 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,
45allocation has yet been made. It's vaguely analogous to overcommit. 45 but no allocation has yet been made. Reserved huge pages
46HugePages_Surp is short for "surplus," and is the number of hugepages in 46 guarantee that an application will be able to allocate a
47the pool above the value in /proc/sys/vm/nr_hugepages. The maximum 47 huge page from the pool of huge pages at fault time.
48number of surplus hugepages is controlled by 48HugePages_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
52in the kernel. 54in 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
55pages in the kernel. Super user can dynamically request more (or free some 57pages in the kernel. Super user can dynamically request more (or free some
56pre-configured) hugepages. 58pre-configured) huge pages.
57The allocation (or deallocation) of hugetlb pages is possible only if there are 59The allocation (or deallocation) of hugetlb pages is possible only if there are
58enough physically contiguous free pages in system (freeing of hugepages is 60enough physically contiguous free pages in system (freeing of huge pages is
59possible only if there are enough hugetlb pages free that can be transferred 61possible only if there are enough hugetlb pages free that can be transferred
60back to regular memory pool). 62back to regular memory pool).
61 63
@@ -67,43 +69,82 @@ use either the mmap system call or shared memory system calls to start using
67the huge pages. It is required that the system administrator preallocate 69the huge pages. It is required that the system administrator preallocate
68enough memory for huge page purposes. 70enough memory for huge page purposes.
69 71
70Use the following command to dynamically allocate/deallocate hugepages: 72The administrator can preallocate huge pages on the kernel boot command line by
73specifying the "hugepages=N" parameter, where 'N' = the number of huge pages
74requested. This is the most reliable method for preallocating huge pages as
75memory has not yet become fragmented.
76
77Some platforms support multiple huge page sizes. To preallocate huge pages
78of a specific size, one must preceed the huge pages boot command parameters
79with a huge page size selection parameter "hugepagesz=<size>". <size> must
80be specified in bytes with optional scale suffix [kKmMgG]. The default huge
81page 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
84size] hugetlb pages in the kernel. Super user can dynamically request more
85(or free some pre-configured) huge pages.
86
87Use the following command to dynamically allocate/deallocate default sized
88huge pages:
71 89
72 echo 20 > /proc/sys/vm/nr_hugepages 90 echo 20 > /proc/sys/vm/nr_hugepages
73 91
74This command will try to configure 20 hugepages in the system. The success 92This command will try to configure 20 default sized huge pages in the system.
75or failure of allocation depends on the amount of physically contiguous 93On a NUMA platform, the kernel will attempt to distribute the huge page pool
76memory that is preset in system at this time. System administrators may want 94over the all on-line nodes. These huge pages, allocated when nr_hugepages
77to put this command in one of the local rc init files. This will enable the 95is increased, are called "persistent huge pages".
78kernel to request huge pages early in the boot process (when the possibility 96
79of getting physical contiguous pages is still very high). In either 97The success or failure of huge page allocation depends on the amount of
80case, administrators will want to verify the number of hugepages actually 98physically contiguous memory that is preset in system at the time of the
81allocated by checking the sysctl or meminfo. 99allocation attempt. If the kernel is unable to allocate huge pages from
82 100some 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 101allocating extra pages on other nodes with sufficient available contiguous
84hugepages can grow, if more hugepages than /proc/sys/vm/nr_hugepages are 102memory, if any.
85requested by applications. echo'ing any non-zero value into this file 103
86indicates that the hugetlb subsystem is allowed to try to obtain 104System administrators may want to put this command in one of the local rc init
87hugepages from the buddy allocator, if the normal pool is exhausted. As 105files. This will enable the kernel to request huge pages early in the boot
88these surplus hugepages go out of use, they are freed back to the buddy 106process when the possibility of getting physical contiguous pages is still
107very high. Administrators can verify the number of huge pages actually
108allocated by checking the sysctl or meminfo. To check the per node
109distribution 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
114huge pages can grow, if more huge pages than /proc/sys/vm/nr_hugepages are
115requested by applications. Writing any non-zero value into this file
116indicates that the hugetlb subsystem is allowed to try to obtain "surplus"
117huge pages from the buddy allocator, when the normal pool is exhausted. As
118these surplus huge pages go out of use, they are freed back to the buddy
89allocator. 119allocator.
90 120
121When increasing the huge page pool size via nr_hugepages, any surplus
122pages will first be promoted to persistent huge pages. Then, additional
123huge pages will be allocated, if necessary and if possible, to fulfill
124the new huge page pool size.
125
126The administrator may shrink the pool of preallocated huge pages for
127the default huge page size by setting the nr_hugepages sysctl to a
128smaller value. The kernel will attempt to balance the freeing of huge pages
129across all on-line nodes. Any free huge pages on the selected nodes will
130be freed back to the buddy allocator.
131
91Caveat: Shrinking the pool via nr_hugepages such that it becomes less 132Caveat: Shrinking the pool via nr_hugepages such that it becomes less
92than the number of hugepages in use will convert the balance to surplus 133than the number of huge pages in use will convert the balance to surplus
93huge pages even if it would exceed the overcommit value. As long as 134huge pages even if it would exceed the overcommit value. As long as
94this condition holds, however, no more surplus huge pages will be 135this condition holds, however, no more surplus huge pages will be
95allowed on the system until one of the two sysctls are increased 136allowed on the system until one of the two sysctls are increased
96sufficiently, or the surplus huge pages go out of use and are freed. 137sufficiently, or the surplus huge pages go out of use and are freed.
97 138
98With support for multiple hugepage pools at run-time available, much of 139With support for multiple huge page pools at run-time available, much of
99the hugepage userspace interface has been duplicated in sysfs. The above 140the huge page userspace interface has been duplicated in sysfs. The above
100information applies to the default hugepage size (which will be 141information applies to the default huge page size which will be
101controlled by the proc interfaces for backwards compatibility). The root 142controlled by the /proc interfaces for backwards compatibility. The root
102hugepage control directory is 143huge page control directory in sysfs is:
103 144
104 /sys/kernel/mm/hugepages 145 /sys/kernel/mm/hugepages
105 146
106For each hugepage size supported by the running kernel, a subdirectory 147For each huge page size supported by the running kernel, a subdirectory
107will exist, of the form 148will 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
119which function as described above for the default hugepage-sized case. 160which function as described above for the default huge page-sized case.
120 161
121If the user applications are going to request hugepages using mmap system 162If the user applications are going to request huge pages using mmap system
122call, then it is required that system administrator mount a file system of 163call, then it is required that system administrator mount a file system of
123type hugetlbfs: 164type hugetlbfs:
124 165
@@ -127,7 +168,7 @@ type hugetlbfs:
127 none /mnt/huge 168 none /mnt/huge
128 169
129This command mounts a (pseudo) filesystem of type hugetlbfs on the directory 170This 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
131options sets the owner and group of the root of the file system. By default 172options sets the owner and group of the root of the file system. By default
132the uid and gid of the current process are taken. The mode option sets the 173the uid and gid of the current process are taken. The mode option sets the
133mode of root of file system to value & 0777. This value is given in octal. 174mode 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
146used to change the file attributes on hugetlbfs. 187used to change the file attributes on hugetlbfs.
147 188
148Also, it is important to note that no such mount command is required if the 189Also, it is important to note that no such mount command is required if the
149applications are going to use only shmat/shmget system calls. Users who 190applications are going to use only shmat/shmget system calls or mmap with
150wish to use hugetlb page via shared memory segment should be a member of 191MAP_HUGETLB. Users who wish to use hugetlb page via shared memory segment
151a supplementary group and system admin needs to configure that gid into 192should 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 193configure that gid into /proc/sys/vm/hugetlb_shm_group. It is possible for
153applications to use any combination of mmaps and shm* calls, though the 194same or different applications to use any combination of mmaps and shm*
154mount of filesystem will be required for using mmap calls. 195calls, though the mount of filesystem will be required for using mmap calls
196without MAP_HUGETLB. For an example of how to use mmap with MAP_HUGETLB see
197map_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 @@
1How to use the Kernel Samepage Merging feature
2----------------------------------------------
3
4KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y,
5added to the Linux kernel in 2.6.32. See mm/ksm.c for its implementation,
6and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/
7
8The KSM daemon ksmd periodically scans those areas of user memory which
9have been registered with it, looking for pages of identical content which
10can be replaced by a single write-protected page (which is automatically
11copied if a process later wants to update its content).
12
13KSM was originally developed for use with KVM (where it was known as
14Kernel Shared Memory), to fit more virtual machines into physical memory,
15by sharing the data common between them. But it can be useful to any
16application which generates many instances of the same data.
17
18KSM only merges anonymous (private) pages, never pagecache (file) pages.
19KSM's merged pages are at present locked into kernel memory for as long
20as they are shared: so cannot be swapped out like the user pages they
21replace (but swapping KSM pages should follow soon in a later release).
22
23KSM only operates on those areas of address space which an application
24has advised to be likely candidates for merging, by using the madvise(2)
25system call: int madvise(addr, length, MADV_MERGEABLE).
26
27The app may call int madvise(addr, length, MADV_UNMERGEABLE) to cancel
28that advice and restore unshared pages: whereupon KSM unmerges whatever
29it merged in that range. Note: this unmerging call may suddenly require
30more memory than is available - possibly failing with EAGAIN, but more
31probably arousing the Out-Of-Memory killer.
32
33If KSM is not configured into the running kernel, madvise MADV_MERGEABLE
34and MADV_UNMERGEABLE simply fail with EINVAL. If the running kernel was
35built with CONFIG_KSM=y, those calls will normally succeed: even if the
36the KSM daemon is not currently running, MADV_MERGEABLE still registers
37the range for whenever the KSM daemon is started; even if the range
38cannot contain any pages which KSM could actually merge; even if
39MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE.
40
41Like other madvise calls, they are intended for use on mapped areas of
42the user address space: they will report ENOMEM if the specified range
43includes unmapped gaps (though working on the intervening mapped areas),
44and might fail with EAGAIN if not enough memory for internal structures.
45
46Applications should be considerate in their use of MADV_MERGEABLE,
47restricting its use to areas likely to benefit. KSM's scans may use
48a lot of processing power, and its kernel-resident pages are a limited
49resource. Some installations will disable KSM for these reasons.
50
51The KSM daemon is controlled by sysfs files in /sys/kernel/mm/ksm/,
52readable by all but writable only by root:
53
54max_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
61pages_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
65sleep_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
69run - 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
75The effectiveness of KSM and MADV_MERGEABLE is shown in /sys/kernel/mm/ksm/:
76
77pages_shared - how many shared unswappable kernel pages KSM is using
78pages_sharing - how many more sites are sharing them i.e. how much saved
79pages_unshared - how many pages unique but repeatedly checked for merging
80pages_volatile - how many pages changing too fast to be placed in a tree
81full_scans - how many times all mergeable areas have been scanned
82
83A high ratio of pages_sharing to pages_shared indicates good sharing, but
84a high ratio of pages_unshared to pages_sharing indicates wasted effort.
85pages_volatile embraces several different kinds of activity, but a high
86proportion there would also indicate poor use of madvise MADV_MERGEABLE.
87
88Izik Eidus,
89Hugh 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
34void check_bytes(char *addr)
35{
36 printf("First hex is %x\n", *((unsigned int *)addr));
37}
38
39void write_bytes(char *addr)
40{
41 unsigned long i;
42
43 for (i = 0; i < LENGTH; i++)
44 *(addr + i) = (char)i;
45}
46
47void 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
59int 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/page-types.c b/Documentation/vm/page-types.c
index 0833f44ba16b..fa1a30d9e9d5 100644
--- a/Documentation/vm/page-types.c
+++ b/Documentation/vm/page-types.c
@@ -5,6 +5,7 @@
5 * Copyright (C) 2009 Wu Fengguang <fengguang.wu@intel.com> 5 * Copyright (C) 2009 Wu Fengguang <fengguang.wu@intel.com>
6 */ 6 */
7 7
8#define _LARGEFILE64_SOURCE
8#include <stdio.h> 9#include <stdio.h>
9#include <stdlib.h> 10#include <stdlib.h>
10#include <unistd.h> 11#include <unistd.h>
@@ -13,12 +14,33 @@
13#include <string.h> 14#include <string.h>
14#include <getopt.h> 15#include <getopt.h>
15#include <limits.h> 16#include <limits.h>
17#include <assert.h>
16#include <sys/types.h> 18#include <sys/types.h>
17#include <sys/errno.h> 19#include <sys/errno.h>
18#include <sys/fcntl.h> 20#include <sys/fcntl.h>
19 21
20 22
21/* 23/*
24 * pagemap kernel ABI bits
25 */
26
27#define PM_ENTRY_BYTES sizeof(uint64_t)
28#define PM_STATUS_BITS 3
29#define PM_STATUS_OFFSET (64 - PM_STATUS_BITS)
30#define PM_STATUS_MASK (((1LL << PM_STATUS_BITS) - 1) << PM_STATUS_OFFSET)
31#define PM_STATUS(nr) (((nr) << PM_STATUS_OFFSET) & PM_STATUS_MASK)
32#define PM_PSHIFT_BITS 6
33#define PM_PSHIFT_OFFSET (PM_STATUS_OFFSET - PM_PSHIFT_BITS)
34#define PM_PSHIFT_MASK (((1LL << PM_PSHIFT_BITS) - 1) << PM_PSHIFT_OFFSET)
35#define PM_PSHIFT(x) (((u64) (x) << PM_PSHIFT_OFFSET) & PM_PSHIFT_MASK)
36#define PM_PFRAME_MASK ((1LL << PM_PSHIFT_OFFSET) - 1)
37#define PM_PFRAME(x) ((x) & PM_PFRAME_MASK)
38
39#define PM_PRESENT PM_STATUS(4LL)
40#define PM_SWAP PM_STATUS(2LL)
41
42
43/*
22 * kernel page flags 44 * kernel page flags
23 */ 45 */
24 46
@@ -126,6 +148,14 @@ static int nr_addr_ranges;
126static unsigned long opt_offset[MAX_ADDR_RANGES]; 148static unsigned long opt_offset[MAX_ADDR_RANGES];
127static unsigned long opt_size[MAX_ADDR_RANGES]; 149static unsigned long opt_size[MAX_ADDR_RANGES];
128 150
151#define MAX_VMAS 10240
152static int nr_vmas;
153static unsigned long pg_start[MAX_VMAS];
154static unsigned long pg_end[MAX_VMAS];
155static unsigned long voffset;
156
157static int pagemap_fd;
158
129#define MAX_BIT_FILTERS 64 159#define MAX_BIT_FILTERS 64
130static int nr_bit_filters; 160static int nr_bit_filters;
131static uint64_t opt_mask[MAX_BIT_FILTERS]; 161static uint64_t opt_mask[MAX_BIT_FILTERS];
@@ -135,7 +165,6 @@ static int page_size;
135 165
136#define PAGES_BATCH (64 << 10) /* 64k pages */ 166#define PAGES_BATCH (64 << 10) /* 64k pages */
137static int kpageflags_fd; 167static int kpageflags_fd;
138static uint64_t kpageflags_buf[KPF_BYTES * PAGES_BATCH];
139 168
140#define HASH_SHIFT 13 169#define HASH_SHIFT 13
141#define HASH_SIZE (1 << HASH_SHIFT) 170#define HASH_SIZE (1 << HASH_SHIFT)
@@ -158,12 +187,17 @@ static uint64_t page_flags[HASH_SIZE];
158 type __min2 = (y); \ 187 type __min2 = (y); \
159 __min1 < __min2 ? __min1 : __min2; }) 188 __min1 < __min2 ? __min1 : __min2; })
160 189
161unsigned long pages2mb(unsigned long pages) 190#define max_t(type, x, y) ({ \
191 type __max1 = (x); \
192 type __max2 = (y); \
193 __max1 > __max2 ? __max1 : __max2; })
194
195static unsigned long pages2mb(unsigned long pages)
162{ 196{
163 return (pages * page_size) >> 20; 197 return (pages * page_size) >> 20;
164} 198}
165 199
166void fatal(const char *x, ...) 200static void fatal(const char *x, ...)
167{ 201{
168 va_list ap; 202 va_list ap;
169 203
@@ -178,7 +212,7 @@ void fatal(const char *x, ...)
178 * page flag names 212 * page flag names
179 */ 213 */
180 214
181char *page_flag_name(uint64_t flags) 215static char *page_flag_name(uint64_t flags)
182{ 216{
183 static char buf[65]; 217 static char buf[65];
184 int present; 218 int present;
@@ -197,7 +231,7 @@ char *page_flag_name(uint64_t flags)
197 return buf; 231 return buf;
198} 232}
199 233
200char *page_flag_longname(uint64_t flags) 234static char *page_flag_longname(uint64_t flags)
201{ 235{
202 static char buf[1024]; 236 static char buf[1024];
203 int i, n; 237 int i, n;
@@ -221,32 +255,40 @@ char *page_flag_longname(uint64_t flags)
221 * page list and summary 255 * page list and summary
222 */ 256 */
223 257
224void show_page_range(unsigned long offset, uint64_t flags) 258static void show_page_range(unsigned long offset, uint64_t flags)
225{ 259{
226 static uint64_t flags0; 260 static uint64_t flags0;
261 static unsigned long voff;
227 static unsigned long index; 262 static unsigned long index;
228 static unsigned long count; 263 static unsigned long count;
229 264
230 if (flags == flags0 && offset == index + count) { 265 if (flags == flags0 && offset == index + count &&
266 (!opt_pid || voffset == voff + count)) {
231 count++; 267 count++;
232 return; 268 return;
233 } 269 }
234 270
235 if (count) 271 if (count) {
236 printf("%lu\t%lu\t%s\n", 272 if (opt_pid)
273 printf("%lx\t", voff);
274 printf("%lx\t%lx\t%s\n",
237 index, count, page_flag_name(flags0)); 275 index, count, page_flag_name(flags0));
276 }
238 277
239 flags0 = flags; 278 flags0 = flags;
240 index = offset; 279 index = offset;
280 voff = voffset;
241 count = 1; 281 count = 1;
242} 282}
243 283
244void show_page(unsigned long offset, uint64_t flags) 284static void show_page(unsigned long offset, uint64_t flags)
245{ 285{
246 printf("%lu\t%s\n", offset, page_flag_name(flags)); 286 if (opt_pid)
287 printf("%lx\t", voffset);
288 printf("%lx\t%s\n", offset, page_flag_name(flags));
247} 289}
248 290
249void show_summary(void) 291static void show_summary(void)
250{ 292{
251 int i; 293 int i;
252 294
@@ -272,7 +314,7 @@ void show_summary(void)
272 * page flag filters 314 * page flag filters
273 */ 315 */
274 316
275int bit_mask_ok(uint64_t flags) 317static int bit_mask_ok(uint64_t flags)
276{ 318{
277 int i; 319 int i;
278 320
@@ -289,7 +331,7 @@ int bit_mask_ok(uint64_t flags)
289 return 1; 331 return 1;
290} 332}
291 333
292uint64_t expand_overloaded_flags(uint64_t flags) 334static uint64_t expand_overloaded_flags(uint64_t flags)
293{ 335{
294 /* SLOB/SLUB overload several page flags */ 336 /* SLOB/SLUB overload several page flags */
295 if (flags & BIT(SLAB)) { 337 if (flags & BIT(SLAB)) {
@@ -308,7 +350,7 @@ uint64_t expand_overloaded_flags(uint64_t flags)
308 return flags; 350 return flags;
309} 351}
310 352
311uint64_t well_known_flags(uint64_t flags) 353static uint64_t well_known_flags(uint64_t flags)
312{ 354{
313 /* hide flags intended only for kernel hacker */ 355 /* hide flags intended only for kernel hacker */
314 flags &= ~KPF_HACKERS_BITS; 356 flags &= ~KPF_HACKERS_BITS;
@@ -325,7 +367,7 @@ uint64_t well_known_flags(uint64_t flags)
325 * page frame walker 367 * page frame walker
326 */ 368 */
327 369
328int hash_slot(uint64_t flags) 370static int hash_slot(uint64_t flags)
329{ 371{
330 int k = HASH_KEY(flags); 372 int k = HASH_KEY(flags);
331 int i; 373 int i;
@@ -352,7 +394,7 @@ int hash_slot(uint64_t flags)
352 exit(EXIT_FAILURE); 394 exit(EXIT_FAILURE);
353} 395}
354 396
355void add_page(unsigned long offset, uint64_t flags) 397static void add_page(unsigned long offset, uint64_t flags)
356{ 398{
357 flags = expand_overloaded_flags(flags); 399 flags = expand_overloaded_flags(flags);
358 400
@@ -371,7 +413,7 @@ void add_page(unsigned long offset, uint64_t flags)
371 total_pages++; 413 total_pages++;
372} 414}
373 415
374void walk_pfn(unsigned long index, unsigned long count) 416static void walk_pfn(unsigned long index, unsigned long count)
375{ 417{
376 unsigned long batch; 418 unsigned long batch;
377 unsigned long n; 419 unsigned long n;
@@ -383,6 +425,8 @@ void walk_pfn(unsigned long index, unsigned long count)
383 lseek(kpageflags_fd, index * KPF_BYTES, SEEK_SET); 425 lseek(kpageflags_fd, index * KPF_BYTES, SEEK_SET);
384 426
385 while (count) { 427 while (count) {
428 uint64_t kpageflags_buf[KPF_BYTES * PAGES_BATCH];
429
386 batch = min_t(unsigned long, count, PAGES_BATCH); 430 batch = min_t(unsigned long, count, PAGES_BATCH);
387 n = read(kpageflags_fd, kpageflags_buf, batch * KPF_BYTES); 431 n = read(kpageflags_fd, kpageflags_buf, batch * KPF_BYTES);
388 if (n == 0) 432 if (n == 0)
@@ -404,7 +448,82 @@ void walk_pfn(unsigned long index, unsigned long count)
404 } 448 }
405} 449}
406 450
407void walk_addr_ranges(void) 451
452#define PAGEMAP_BATCH 4096
453static unsigned long task_pfn(unsigned long pgoff)
454{
455 static uint64_t buf[PAGEMAP_BATCH];
456 static unsigned long start;
457 static long count;
458 uint64_t pfn;
459
460 if (pgoff < start || pgoff >= start + count) {
461 if (lseek64(pagemap_fd,
462 (uint64_t)pgoff * PM_ENTRY_BYTES,
463 SEEK_SET) < 0) {
464 perror("pagemap seek");
465 exit(EXIT_FAILURE);
466 }
467 count = read(pagemap_fd, buf, sizeof(buf));
468 if (count == 0)
469 return 0;
470 if (count < 0) {
471 perror("pagemap read");
472 exit(EXIT_FAILURE);
473 }
474 if (count % PM_ENTRY_BYTES) {
475 fatal("pagemap read not aligned.\n");
476 exit(EXIT_FAILURE);
477 }
478 count /= PM_ENTRY_BYTES;
479 start = pgoff;
480 }
481
482 pfn = buf[pgoff - start];
483 if (pfn & PM_PRESENT)
484 pfn = PM_PFRAME(pfn);
485 else
486 pfn = 0;
487
488 return pfn;
489}
490
491static void walk_task(unsigned long index, unsigned long count)
492{
493 int i = 0;
494 const unsigned long end = index + count;
495
496 while (index < end) {
497
498 while (pg_end[i] <= index)
499 if (++i >= nr_vmas)
500 return;
501 if (pg_start[i] >= end)
502 return;
503
504 voffset = max_t(unsigned long, pg_start[i], index);
505 index = min_t(unsigned long, pg_end[i], end);
506
507 assert(voffset < index);
508 for (; voffset < index; voffset++) {
509 unsigned long pfn = task_pfn(voffset);
510 if (pfn)
511 walk_pfn(pfn, 1);
512 }
513 }
514}
515
516static void add_addr_range(unsigned long offset, unsigned long size)
517{
518 if (nr_addr_ranges >= MAX_ADDR_RANGES)
519 fatal("too many addr ranges\n");
520
521 opt_offset[nr_addr_ranges] = offset;
522 opt_size[nr_addr_ranges] = min_t(unsigned long, size, ULONG_MAX-offset);
523 nr_addr_ranges++;
524}
525
526static void walk_addr_ranges(void)
408{ 527{
409 int i; 528 int i;
410 529
@@ -415,10 +534,13 @@ void walk_addr_ranges(void)
415 } 534 }
416 535
417 if (!nr_addr_ranges) 536 if (!nr_addr_ranges)
418 walk_pfn(0, ULONG_MAX); 537 add_addr_range(0, ULONG_MAX);
419 538
420 for (i = 0; i < nr_addr_ranges; i++) 539 for (i = 0; i < nr_addr_ranges; i++)
421 walk_pfn(opt_offset[i], opt_size[i]); 540 if (!opt_pid)
541 walk_pfn(opt_offset[i], opt_size[i]);
542 else
543 walk_task(opt_offset[i], opt_size[i]);
422 544
423 close(kpageflags_fd); 545 close(kpageflags_fd);
424} 546}
@@ -428,7 +550,7 @@ void walk_addr_ranges(void)
428 * user interface 550 * user interface
429 */ 551 */
430 552
431const char *page_flag_type(uint64_t flag) 553static const char *page_flag_type(uint64_t flag)
432{ 554{
433 if (flag & KPF_HACKERS_BITS) 555 if (flag & KPF_HACKERS_BITS)
434 return "(r)"; 556 return "(r)";
@@ -437,7 +559,7 @@ const char *page_flag_type(uint64_t flag)
437 return " "; 559 return " ";
438} 560}
439 561
440void usage(void) 562static void usage(void)
441{ 563{
442 int i, j; 564 int i, j;
443 565
@@ -446,8 +568,8 @@ void usage(void)
446" -r|--raw Raw mode, for kernel developers\n" 568" -r|--raw Raw mode, for kernel developers\n"
447" -a|--addr addr-spec Walk a range of pages\n" 569" -a|--addr addr-spec Walk a range of pages\n"
448" -b|--bits bits-spec Walk pages with specified bits\n" 570" -b|--bits bits-spec Walk pages with specified bits\n"
449#if 0 /* planned features */
450" -p|--pid pid Walk process address space\n" 571" -p|--pid pid Walk process address space\n"
572#if 0 /* planned features */
451" -f|--file filename Walk file address space\n" 573" -f|--file filename Walk file address space\n"
452#endif 574#endif
453" -l|--list Show page details in ranges\n" 575" -l|--list Show page details in ranges\n"
@@ -459,7 +581,7 @@ void usage(void)
459" N+M pages range from N to N+M-1\n" 581" N+M pages range from N to N+M-1\n"
460" N,M pages range from N to M-1\n" 582" N,M pages range from N to M-1\n"
461" N, pages range from N to end\n" 583" N, pages range from N to end\n"
462" ,M pages range from 0 to M\n" 584" ,M pages range from 0 to M-1\n"
463"bits-spec:\n" 585"bits-spec:\n"
464" bit1,bit2 (flags & (bit1|bit2)) != 0\n" 586" bit1,bit2 (flags & (bit1|bit2)) != 0\n"
465" bit1,bit2=bit1 (flags & (bit1|bit2)) == bit1\n" 587" bit1,bit2=bit1 (flags & (bit1|bit2)) == bit1\n"
@@ -482,7 +604,7 @@ void usage(void)
482 "(r) raw mode bits (o) overloaded bits\n"); 604 "(r) raw mode bits (o) overloaded bits\n");
483} 605}
484 606
485unsigned long long parse_number(const char *str) 607static unsigned long long parse_number(const char *str)
486{ 608{
487 unsigned long long n; 609 unsigned long long n;
488 610
@@ -494,26 +616,62 @@ unsigned long long parse_number(const char *str)
494 return n; 616 return n;
495} 617}
496 618
497void parse_pid(const char *str) 619static void parse_pid(const char *str)
498{ 620{
621 FILE *file;
622 char buf[5000];
623
499 opt_pid = parse_number(str); 624 opt_pid = parse_number(str);
500}
501 625
502void parse_file(const char *name) 626 sprintf(buf, "/proc/%d/pagemap", opt_pid);
503{ 627 pagemap_fd = open(buf, O_RDONLY);
628 if (pagemap_fd < 0) {
629 perror(buf);
630 exit(EXIT_FAILURE);
631 }
632
633 sprintf(buf, "/proc/%d/maps", opt_pid);
634 file = fopen(buf, "r");
635 if (!file) {
636 perror(buf);
637 exit(EXIT_FAILURE);
638 }
639
640 while (fgets(buf, sizeof(buf), file) != NULL) {
641 unsigned long vm_start;
642 unsigned long vm_end;
643 unsigned long long pgoff;
644 int major, minor;
645 char r, w, x, s;
646 unsigned long ino;
647 int n;
648
649 n = sscanf(buf, "%lx-%lx %c%c%c%c %llx %x:%x %lu",
650 &vm_start,
651 &vm_end,
652 &r, &w, &x, &s,
653 &pgoff,
654 &major, &minor,
655 &ino);
656 if (n < 10) {
657 fprintf(stderr, "unexpected line: %s\n", buf);
658 continue;
659 }
660 pg_start[nr_vmas] = vm_start / page_size;
661 pg_end[nr_vmas] = vm_end / page_size;
662 if (++nr_vmas >= MAX_VMAS) {
663 fprintf(stderr, "too many VMAs\n");
664 break;
665 }
666 }
667 fclose(file);
504} 668}
505 669
506void add_addr_range(unsigned long offset, unsigned long size) 670static void parse_file(const char *name)
507{ 671{
508 if (nr_addr_ranges >= MAX_ADDR_RANGES)
509 fatal("too much addr ranges\n");
510
511 opt_offset[nr_addr_ranges] = offset;
512 opt_size[nr_addr_ranges] = size;
513 nr_addr_ranges++;
514} 672}
515 673
516void parse_addr_range(const char *optarg) 674static void parse_addr_range(const char *optarg)
517{ 675{
518 unsigned long offset; 676 unsigned long offset;
519 unsigned long size; 677 unsigned long size;
@@ -547,7 +705,7 @@ void parse_addr_range(const char *optarg)
547 add_addr_range(offset, size); 705 add_addr_range(offset, size);
548} 706}
549 707
550void add_bits_filter(uint64_t mask, uint64_t bits) 708static void add_bits_filter(uint64_t mask, uint64_t bits)
551{ 709{
552 if (nr_bit_filters >= MAX_BIT_FILTERS) 710 if (nr_bit_filters >= MAX_BIT_FILTERS)
553 fatal("too much bit filters\n"); 711 fatal("too much bit filters\n");
@@ -557,7 +715,7 @@ void add_bits_filter(uint64_t mask, uint64_t bits)
557 nr_bit_filters++; 715 nr_bit_filters++;
558} 716}
559 717
560uint64_t parse_flag_name(const char *str, int len) 718static uint64_t parse_flag_name(const char *str, int len)
561{ 719{
562 int i; 720 int i;
563 721
@@ -577,7 +735,7 @@ uint64_t parse_flag_name(const char *str, int len)
577 return parse_number(str); 735 return parse_number(str);
578} 736}
579 737
580uint64_t parse_flag_names(const char *str, int all) 738static uint64_t parse_flag_names(const char *str, int all)
581{ 739{
582 const char *p = str; 740 const char *p = str;
583 uint64_t flags = 0; 741 uint64_t flags = 0;
@@ -596,7 +754,7 @@ uint64_t parse_flag_names(const char *str, int all)
596 return flags; 754 return flags;
597} 755}
598 756
599void parse_bits_mask(const char *optarg) 757static void parse_bits_mask(const char *optarg)
600{ 758{
601 uint64_t mask; 759 uint64_t mask;
602 uint64_t bits; 760 uint64_t bits;
@@ -621,7 +779,7 @@ void parse_bits_mask(const char *optarg)
621} 779}
622 780
623 781
624struct option opts[] = { 782static struct option opts[] = {
625 { "raw" , 0, NULL, 'r' }, 783 { "raw" , 0, NULL, 'r' },
626 { "pid" , 1, NULL, 'p' }, 784 { "pid" , 1, NULL, 'p' },
627 { "file" , 1, NULL, 'f' }, 785 { "file" , 1, NULL, 'f' },
@@ -676,8 +834,10 @@ int main(int argc, char *argv[])
676 } 834 }
677 } 835 }
678 836
837 if (opt_list && opt_pid)
838 printf("voffset\t");
679 if (opt_list == 1) 839 if (opt_list == 1)
680 printf("offset\tcount\tflags\n"); 840 printf("offset\tlen\tflags\n");
681 if (opt_list == 2) 841 if (opt_list == 2)
682 printf("offset\tflags\n"); 842 printf("offset\tflags\n");
683 843
diff --git a/Documentation/vm/slabinfo.c b/Documentation/vm/slabinfo.c
index df3227605d59..92e729f4b676 100644
--- a/Documentation/vm/slabinfo.c
+++ b/Documentation/vm/slabinfo.c
@@ -87,7 +87,7 @@ int page_size;
87 87
88regex_t pattern; 88regex_t pattern;
89 89
90void fatal(const char *x, ...) 90static void fatal(const char *x, ...)
91{ 91{
92 va_list ap; 92 va_list ap;
93 93
@@ -97,7 +97,7 @@ void fatal(const char *x, ...)
97 exit(EXIT_FAILURE); 97 exit(EXIT_FAILURE);
98} 98}
99 99
100void usage(void) 100static void usage(void)
101{ 101{
102 printf("slabinfo 5/7/2007. (c) 2007 sgi.\n\n" 102 printf("slabinfo 5/7/2007. (c) 2007 sgi.\n\n"
103 "slabinfo [-ahnpvtsz] [-d debugopts] [slab-regexp]\n" 103 "slabinfo [-ahnpvtsz] [-d debugopts] [slab-regexp]\n"
@@ -131,7 +131,7 @@ void usage(void)
131 ); 131 );
132} 132}
133 133
134unsigned long read_obj(const char *name) 134static unsigned long read_obj(const char *name)
135{ 135{
136 FILE *f = fopen(name, "r"); 136 FILE *f = fopen(name, "r");
137 137
@@ -151,7 +151,7 @@ unsigned long read_obj(const char *name)
151/* 151/*
152 * Get the contents of an attribute 152 * Get the contents of an attribute
153 */ 153 */
154unsigned long get_obj(const char *name) 154static unsigned long get_obj(const char *name)
155{ 155{
156 if (!read_obj(name)) 156 if (!read_obj(name))
157 return 0; 157 return 0;
@@ -159,7 +159,7 @@ unsigned long get_obj(const char *name)
159 return atol(buffer); 159 return atol(buffer);
160} 160}
161 161
162unsigned long get_obj_and_str(const char *name, char **x) 162static unsigned long get_obj_and_str(const char *name, char **x)
163{ 163{
164 unsigned long result = 0; 164 unsigned long result = 0;
165 char *p; 165 char *p;
@@ -178,7 +178,7 @@ unsigned long get_obj_and_str(const char *name, char **x)
178 return result; 178 return result;
179} 179}
180 180
181void set_obj(struct slabinfo *s, const char *name, int n) 181static void set_obj(struct slabinfo *s, const char *name, int n)
182{ 182{
183 char x[100]; 183 char x[100];
184 FILE *f; 184 FILE *f;
@@ -192,7 +192,7 @@ void set_obj(struct slabinfo *s, const char *name, int n)
192 fclose(f); 192 fclose(f);
193} 193}
194 194
195unsigned long read_slab_obj(struct slabinfo *s, const char *name) 195static unsigned long read_slab_obj(struct slabinfo *s, const char *name)
196{ 196{
197 char x[100]; 197 char x[100];
198 FILE *f; 198 FILE *f;
@@ -215,7 +215,7 @@ unsigned long read_slab_obj(struct slabinfo *s, const char *name)
215/* 215/*
216 * Put a size string together 216 * Put a size string together
217 */ 217 */
218int store_size(char *buffer, unsigned long value) 218static int store_size(char *buffer, unsigned long value)
219{ 219{
220 unsigned long divisor = 1; 220 unsigned long divisor = 1;
221 char trailer = 0; 221 char trailer = 0;
@@ -247,7 +247,7 @@ int store_size(char *buffer, unsigned long value)
247 return n; 247 return n;
248} 248}
249 249
250void decode_numa_list(int *numa, char *t) 250static void decode_numa_list(int *numa, char *t)
251{ 251{
252 int node; 252 int node;
253 int nr; 253 int nr;
@@ -272,7 +272,7 @@ void decode_numa_list(int *numa, char *t)
272 } 272 }
273} 273}
274 274
275void slab_validate(struct slabinfo *s) 275static void slab_validate(struct slabinfo *s)
276{ 276{
277 if (strcmp(s->name, "*") == 0) 277 if (strcmp(s->name, "*") == 0)
278 return; 278 return;
@@ -280,7 +280,7 @@ void slab_validate(struct slabinfo *s)
280 set_obj(s, "validate", 1); 280 set_obj(s, "validate", 1);
281} 281}
282 282
283void slab_shrink(struct slabinfo *s) 283static void slab_shrink(struct slabinfo *s)
284{ 284{
285 if (strcmp(s->name, "*") == 0) 285 if (strcmp(s->name, "*") == 0)
286 return; 286 return;
@@ -290,7 +290,7 @@ void slab_shrink(struct slabinfo *s)
290 290
291int line = 0; 291int line = 0;
292 292
293void first_line(void) 293static void first_line(void)
294{ 294{
295 if (show_activity) 295 if (show_activity)
296 printf("Name Objects Alloc Free %%Fast Fallb O\n"); 296 printf("Name Objects Alloc Free %%Fast Fallb O\n");
@@ -302,7 +302,7 @@ void first_line(void)
302/* 302/*
303 * Find the shortest alias of a slab 303 * Find the shortest alias of a slab
304 */ 304 */
305struct aliasinfo *find_one_alias(struct slabinfo *find) 305static struct aliasinfo *find_one_alias(struct slabinfo *find)
306{ 306{
307 struct aliasinfo *a; 307 struct aliasinfo *a;
308 struct aliasinfo *best = NULL; 308 struct aliasinfo *best = NULL;
@@ -318,18 +318,18 @@ struct aliasinfo *find_one_alias(struct slabinfo *find)
318 return best; 318 return best;
319} 319}
320 320
321unsigned long slab_size(struct slabinfo *s) 321static unsigned long slab_size(struct slabinfo *s)
322{ 322{
323 return s->slabs * (page_size << s->order); 323 return s->slabs * (page_size << s->order);
324} 324}
325 325
326unsigned long slab_activity(struct slabinfo *s) 326static unsigned long slab_activity(struct slabinfo *s)
327{ 327{
328 return s->alloc_fastpath + s->free_fastpath + 328 return s->alloc_fastpath + s->free_fastpath +
329 s->alloc_slowpath + s->free_slowpath; 329 s->alloc_slowpath + s->free_slowpath;
330} 330}
331 331
332void slab_numa(struct slabinfo *s, int mode) 332static void slab_numa(struct slabinfo *s, int mode)
333{ 333{
334 int node; 334 int node;
335 335
@@ -374,7 +374,7 @@ void slab_numa(struct slabinfo *s, int mode)
374 line++; 374 line++;
375} 375}
376 376
377void show_tracking(struct slabinfo *s) 377static void show_tracking(struct slabinfo *s)
378{ 378{
379 printf("\n%s: Kernel object allocation\n", s->name); 379 printf("\n%s: Kernel object allocation\n", s->name);
380 printf("-----------------------------------------------------------------------\n"); 380 printf("-----------------------------------------------------------------------\n");
@@ -392,7 +392,7 @@ void show_tracking(struct slabinfo *s)
392 392
393} 393}
394 394
395void ops(struct slabinfo *s) 395static void ops(struct slabinfo *s)
396{ 396{
397 if (strcmp(s->name, "*") == 0) 397 if (strcmp(s->name, "*") == 0)
398 return; 398 return;
@@ -405,14 +405,14 @@ void ops(struct slabinfo *s)
405 printf("\n%s has no kmem_cache operations\n", s->name); 405 printf("\n%s has no kmem_cache operations\n", s->name);
406} 406}
407 407
408const char *onoff(int x) 408static const char *onoff(int x)
409{ 409{
410 if (x) 410 if (x)
411 return "On "; 411 return "On ";
412 return "Off"; 412 return "Off";
413} 413}
414 414
415void slab_stats(struct slabinfo *s) 415static void slab_stats(struct slabinfo *s)
416{ 416{
417 unsigned long total_alloc; 417 unsigned long total_alloc;
418 unsigned long total_free; 418 unsigned long total_free;
@@ -477,7 +477,7 @@ void slab_stats(struct slabinfo *s)
477 s->deactivate_to_tail, (s->deactivate_to_tail * 100) / total); 477 s->deactivate_to_tail, (s->deactivate_to_tail * 100) / total);
478} 478}
479 479
480void report(struct slabinfo *s) 480static void report(struct slabinfo *s)
481{ 481{
482 if (strcmp(s->name, "*") == 0) 482 if (strcmp(s->name, "*") == 0)
483 return; 483 return;
@@ -518,7 +518,7 @@ void report(struct slabinfo *s)
518 slab_stats(s); 518 slab_stats(s);
519} 519}
520 520
521void slabcache(struct slabinfo *s) 521static void slabcache(struct slabinfo *s)
522{ 522{
523 char size_str[20]; 523 char size_str[20];
524 char dist_str[40]; 524 char dist_str[40];
@@ -593,7 +593,7 @@ void slabcache(struct slabinfo *s)
593/* 593/*
594 * Analyze debug options. Return false if something is amiss. 594 * Analyze debug options. Return false if something is amiss.
595 */ 595 */
596int debug_opt_scan(char *opt) 596static int debug_opt_scan(char *opt)
597{ 597{
598 if (!opt || !opt[0] || strcmp(opt, "-") == 0) 598 if (!opt || !opt[0] || strcmp(opt, "-") == 0)
599 return 1; 599 return 1;
@@ -642,7 +642,7 @@ int debug_opt_scan(char *opt)
642 return 1; 642 return 1;
643} 643}
644 644
645int slab_empty(struct slabinfo *s) 645static int slab_empty(struct slabinfo *s)
646{ 646{
647 if (s->objects > 0) 647 if (s->objects > 0)
648 return 0; 648 return 0;
@@ -657,7 +657,7 @@ int slab_empty(struct slabinfo *s)
657 return 1; 657 return 1;
658} 658}
659 659
660void slab_debug(struct slabinfo *s) 660static void slab_debug(struct slabinfo *s)
661{ 661{
662 if (strcmp(s->name, "*") == 0) 662 if (strcmp(s->name, "*") == 0)
663 return; 663 return;
@@ -717,7 +717,7 @@ void slab_debug(struct slabinfo *s)
717 set_obj(s, "trace", 1); 717 set_obj(s, "trace", 1);
718} 718}
719 719
720void totals(void) 720static void totals(void)
721{ 721{
722 struct slabinfo *s; 722 struct slabinfo *s;
723 723
@@ -976,7 +976,7 @@ void totals(void)
976 b1, b2, b3); 976 b1, b2, b3);
977} 977}
978 978
979void sort_slabs(void) 979static void sort_slabs(void)
980{ 980{
981 struct slabinfo *s1,*s2; 981 struct slabinfo *s1,*s2;
982 982
@@ -1005,7 +1005,7 @@ void sort_slabs(void)
1005 } 1005 }
1006} 1006}
1007 1007
1008void sort_aliases(void) 1008static void sort_aliases(void)
1009{ 1009{
1010 struct aliasinfo *a1,*a2; 1010 struct aliasinfo *a1,*a2;
1011 1011
@@ -1030,7 +1030,7 @@ void sort_aliases(void)
1030 } 1030 }
1031} 1031}
1032 1032
1033void link_slabs(void) 1033static void link_slabs(void)
1034{ 1034{
1035 struct aliasinfo *a; 1035 struct aliasinfo *a;
1036 struct slabinfo *s; 1036 struct slabinfo *s;
@@ -1048,7 +1048,7 @@ void link_slabs(void)
1048 } 1048 }
1049} 1049}
1050 1050
1051void alias(void) 1051static void alias(void)
1052{ 1052{
1053 struct aliasinfo *a; 1053 struct aliasinfo *a;
1054 char *active = NULL; 1054 char *active = NULL;
@@ -1079,7 +1079,7 @@ void alias(void)
1079} 1079}
1080 1080
1081 1081
1082void rename_slabs(void) 1082static void rename_slabs(void)
1083{ 1083{
1084 struct slabinfo *s; 1084 struct slabinfo *s;
1085 struct aliasinfo *a; 1085 struct aliasinfo *a;
@@ -1102,12 +1102,12 @@ void rename_slabs(void)
1102 } 1102 }
1103} 1103}
1104 1104
1105int slab_mismatch(char *slab) 1105static int slab_mismatch(char *slab)
1106{ 1106{
1107 return regexec(&pattern, slab, 0, NULL, 0); 1107 return regexec(&pattern, slab, 0, NULL, 0);
1108} 1108}
1109 1109
1110void read_slab_dir(void) 1110static void read_slab_dir(void)
1111{ 1111{
1112 DIR *dir; 1112 DIR *dir;
1113 struct dirent *de; 1113 struct dirent *de;
@@ -1209,7 +1209,7 @@ void read_slab_dir(void)
1209 fatal("Too many aliases\n"); 1209 fatal("Too many aliases\n");
1210} 1210}
1211 1211
1212void output_slabs(void) 1212static void output_slabs(void)
1213{ 1213{
1214 struct slabinfo *slab; 1214 struct slabinfo *slab;
1215 1215
diff --git a/Documentation/watchdog/src/watchdog-test.c b/Documentation/watchdog/src/watchdog-test.c
index 65f6c19cb865..a750532ffcf8 100644
--- a/Documentation/watchdog/src/watchdog-test.c
+++ b/Documentation/watchdog/src/watchdog-test.c
@@ -18,7 +18,7 @@ int fd;
18 * the PC Watchdog card to reset its internal timer so it doesn't trigger 18 * the PC Watchdog card to reset its internal timer so it doesn't trigger
19 * a computer reset. 19 * a computer reset.
20 */ 20 */
21void keep_alive(void) 21static void keep_alive(void)
22{ 22{
23 int dummy; 23 int dummy;
24 24
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
603Field name: hardware_subarch_data 604Field name: hardware_subarch_data
604Type: write (subarch-dependent) 605Type: write (subarch-dependent)
diff --git a/Documentation/x86/earlyprintk.txt b/Documentation/x86/earlyprintk.txt
index 607b1a016064..f19802c0f485 100644
--- a/Documentation/x86/earlyprintk.txt
+++ b/Documentation/x86/earlyprintk.txt
@@ -7,7 +7,7 @@ and two USB cables, connected like this:
7 7
8 [host/target] <-------> [USB debug key] <-------> [client/console] 8 [host/target] <-------> [USB debug key] <-------> [client/console]
9 9
101. There are three specific hardware requirements: 101. There are a number of specific hardware requirements:
11 11
12 a.) Host/target system needs to have USB debug port capability. 12 a.) Host/target system needs to have USB debug port capability.
13 13
@@ -42,7 +42,35 @@ and two USB cables, connected like this:
42 This is a small blue plastic connector with two USB connections, 42 This is a small blue plastic connector with two USB connections,
43 it draws power from its USB connections. 43 it draws power from its USB connections.
44 44
45 c.) Thirdly, you need a second client/console system with a regular USB port. 45 c.) You need a second client/console system with a high speed USB 2.0
46 port.
47
48 d.) The Netchip device must be plugged directly into the physical
49 debug port on the "host/target" system. You cannot use a USB hub in
50 between the physical debug port and the "host/target" system.
51
52 The EHCI debug controller is bound to a specific physical USB
53 port and the Netchip device will only work as an early printk
54 device in this port. The EHCI host controllers are electrically
55 wired such that the EHCI debug controller is hooked up to the
56 first physical and there is no way to change this via software.
57 You can find the physical port through experimentation by trying
58 each physical port on the system and rebooting. Or you can try
59 and use lsusb or look at the kernel info messages emitted by the
60 usb stack when you plug a usb device into various ports on the
61 "host/target" system.
62
63 Some hardware vendors do not expose the usb debug port with a
64 physical connector and if you find such a device send a complaint
65 to the hardware vendor, because there is no reason not to wire
66 this port into one of the physically accessible ports.
67
68 e.) It is also important to note, that many versions of the Netchip
69 device require the "client/console" system to be plugged into the
70 right and side of the device (with the product logo facing up and
71 readable left to right). The reason being is that the 5 volt
72 power supply is taken from only one side of the device and it
73 must be the side that does not get rebooted.
46 74
472. Software requirements: 752. Software requirements:
48 76
@@ -56,6 +84,13 @@ and two USB cables, connected like this:
56 (If you are using Grub, append it to the 'kernel' line in 84 (If you are using Grub, append it to the 'kernel' line in
57 /etc/grub.conf) 85 /etc/grub.conf)
58 86
87 On systems with more than one EHCI debug controller you must
88 specify the correct EHCI debug controller number. The ordering
89 comes from the PCI bus enumeration of the EHCI controllers. The
90 default with no number argument is "0" the first EHCI debug
91 controller. To use the second EHCI debug controller, you would
92 use the command line: "earlyprintk=dbgp1"
93
59 NOTE: normally earlyprintk console gets turned off once the 94 NOTE: normally earlyprintk console gets turned off once the
60 regular console is alive - use "earlyprintk=dbgp,keep" to keep 95 regular console is alive - use "earlyprintk=dbgp,keep" to keep
61 this channel open beyond early bootup. This can be useful for 96 this channel open beyond early bootup. This can be useful for