diff options
Diffstat (limited to 'Documentation')
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 @@ | |||
| 1 | What: /sys/class/backlight/<backlight>/bl_power | ||
| 2 | Date: April 2005 | ||
| 3 | KernelVersion: 2.6.12 | ||
| 4 | Contact: Richard Purdie <rpurdie@rpsys.net> | ||
| 5 | Description: | ||
| 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 | ||
| 9 | Users: HAL | ||
| 10 | |||
| 11 | What: /sys/class/backlight/<backlight>/brightness | ||
| 12 | Date: April 2005 | ||
| 13 | KernelVersion: 2.6.12 | ||
| 14 | Contact: Richard Purdie <rpurdie@rpsys.net> | ||
| 15 | Description: | ||
| 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). | ||
| 20 | Users: HAL | ||
| 21 | |||
| 22 | What: /sys/class/backlight/<backlight>/actual_brightness | ||
| 23 | Date: March 2006 | ||
| 24 | KernelVersion: 2.6.17 | ||
| 25 | Contact: Richard Purdie <rpurdie@rpsys.net> | ||
| 26 | Description: | ||
| 27 | Show the actual brightness by querying the hardware. | ||
| 28 | Users: HAL | ||
| 29 | |||
| 30 | What: /sys/class/backlight/<backlight>/max_brightness | ||
| 31 | Date: April 2005 | ||
| 32 | KernelVersion: 2.6.12 | ||
| 33 | Contact: Richard Purdie <rpurdie@rpsys.net> | ||
| 34 | Description: | ||
| 35 | Maximum brightness for <backlight>. | ||
| 36 | Users: 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 | ||
| 87 | What: /sys/bus/pci/devices/.../reset | ||
| 88 | Date: July 2009 | ||
| 89 | Contact: Michael S. Tsirkin <mst@redhat.com> | ||
| 90 | Description: | ||
| 91 | Some devices allow an individual function to be reset | ||
| 92 | without affecting other functions in the same device. | ||
| 93 | For devices that have this support, a file named reset | ||
| 94 | will be present in sysfs. Writing 1 to this file | ||
| 95 | will perform reset. | ||
| 96 | |||
| 87 | What: /sys/bus/pci/devices/.../vpd | 97 | What: /sys/bus/pci/devices/.../vpd |
| 88 | Date: February 2008 | 98 | Date: February 2008 |
| 89 | Contact: Ben Hutchings <bhutchings@solarflare.com> | 99 | Contact: Ben Hutchings <bhutchings@solarflare.com> |
diff --git a/Documentation/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 @@ | |||
| 1 | What: /sys/class/lcd/<lcd>/lcd_power | ||
| 2 | Date: April 2005 | ||
| 3 | KernelVersion: 2.6.12 | ||
| 4 | Contact: Richard Purdie <rpurdie@rpsys.net> | ||
| 5 | Description: | ||
| 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 | |||
| 10 | What: /sys/class/lcd/<lcd>/contrast | ||
| 11 | Date: April 2005 | ||
| 12 | KernelVersion: 2.6.12 | ||
| 13 | Contact: Richard Purdie <rpurdie@rpsys.net> | ||
| 14 | Description: | ||
| 15 | Current contrast of this LCD device. Value is between 0 and | ||
| 16 | /sys/class/lcd/<lcd>/max_contrast. | ||
| 17 | |||
| 18 | What: /sys/class/lcd/<lcd>/max_contrast | ||
| 19 | Date: April 2005 | ||
| 20 | KernelVersion: 2.6.12 | ||
| 21 | Contact: Richard Purdie <rpurdie@rpsys.net> | ||
| 22 | Description: | ||
| 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 @@ | |||
| 1 | What: /sys/class/leds/<led>/brightness | ||
| 2 | Date: March 2006 | ||
| 3 | KernelVersion: 2.6.17 | ||
| 4 | Contact: Richard Purdie <rpurdie@rpsys.net> | ||
| 5 | Description: | ||
| 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 | |||
| 11 | What: /sys/class/leds/<led>/max_brightness | ||
| 12 | Date: March 2006 | ||
| 13 | KernelVersion: 2.6.17 | ||
| 14 | Contact: Richard Purdie <rpurdie@rpsys.net> | ||
| 15 | Description: | ||
| 16 | Maximum brightness level for this led, default is 255 (LED_FULL). | ||
| 17 | |||
| 18 | What: /sys/class/leds/<led>/trigger | ||
| 19 | Date: March 2006 | ||
| 20 | KernelVersion: 2.6.17 | ||
| 21 | Contact: Richard Purdie <rpurdie@rpsys.net> | ||
| 22 | Description: | ||
| 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 @@ | |||
| 1 | What: /sys/devices/platform/asus-laptop/display | ||
| 2 | Date: January 2007 | ||
| 3 | KernelVersion: 2.6.20 | ||
| 4 | Contact: "Corentin Chary" <corentincj@iksaif.net> | ||
| 5 | Description: | ||
| 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 | |||
| 16 | What: /sys/devices/platform/asus-laptop/gps | ||
| 17 | Date: January 2007 | ||
| 18 | KernelVersion: 2.6.20 | ||
| 19 | Contact: "Corentin Chary" <corentincj@iksaif.net> | ||
| 20 | Description: | ||
| 21 | Control the gps device. 1 means on, 0 means off. | ||
| 22 | Users: Lapsus | ||
| 23 | |||
| 24 | What: /sys/devices/platform/asus-laptop/ledd | ||
| 25 | Date: January 2007 | ||
| 26 | KernelVersion: 2.6.20 | ||
| 27 | Contact: "Corentin Chary" <corentincj@iksaif.net> | ||
| 28 | Description: | ||
| 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 | |||
| 36 | What: /sys/devices/platform/asus-laptop/bluetooth | ||
| 37 | Date: January 2007 | ||
| 38 | KernelVersion: 2.6.20 | ||
| 39 | Contact: "Corentin Chary" <corentincj@iksaif.net> | ||
| 40 | Description: | ||
| 41 | Control the bluetooth device. 1 means on, 0 means off. | ||
| 42 | This may control the led, the device or both. | ||
| 43 | Users: Lapsus | ||
| 44 | |||
| 45 | What: /sys/devices/platform/asus-laptop/wlan | ||
| 46 | Date: January 2007 | ||
| 47 | KernelVersion: 2.6.20 | ||
| 48 | Contact: "Corentin Chary" <corentincj@iksaif.net> | ||
| 49 | Description: | ||
| 50 | Control the bluetooth device. 1 means on, 0 means off. | ||
| 51 | This may control the led, the device or both. | ||
| 52 | Users: 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 @@ | |||
| 1 | What: /sys/devices/platform/eeepc-laptop/disp | ||
| 2 | Date: May 2008 | ||
| 3 | KernelVersion: 2.6.26 | ||
| 4 | Contact: "Corentin Chary" <corentincj@iksaif.net> | ||
| 5 | Description: | ||
| 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 | |||
| 12 | What: /sys/devices/platform/eeepc-laptop/camera | ||
| 13 | Date: May 2008 | ||
| 14 | KernelVersion: 2.6.26 | ||
| 15 | Contact: "Corentin Chary" <corentincj@iksaif.net> | ||
| 16 | Description: | ||
| 17 | Control the camera. 1 means on, 0 means off. | ||
| 18 | |||
| 19 | What: /sys/devices/platform/eeepc-laptop/cardr | ||
| 20 | Date: May 2008 | ||
| 21 | KernelVersion: 2.6.26 | ||
| 22 | Contact: "Corentin Chary" <corentincj@iksaif.net> | ||
| 23 | Description: | ||
| 24 | Control the card reader. 1 means on, 0 means off. | ||
| 25 | |||
| 26 | What: /sys/devices/platform/eeepc-laptop/cpufv | ||
| 27 | Date: Jun 2009 | ||
| 28 | KernelVersion: 2.6.31 | ||
| 29 | Contact: "Corentin Chary" <corentincj@iksaif.net> | ||
| 30 | Description: | ||
| 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 | |||
| 45 | What: /sys/devices/platform/eeepc-laptop/available_cpufv | ||
| 46 | Date: Jun 2009 | ||
| 47 | KernelVersion: 2.6.31 | ||
| 48 | Contact: "Corentin Chary" <corentincj@iksaif.net> | ||
| 49 | Description: | ||
| 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. |
| 35 | PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs | 35 | PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs media |
| 36 | 36 | ||
| 37 | BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) | 37 | BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) |
| 38 | xmldocs: $(BOOKS) | 38 | xmldocs: $(BOOKS) |
| @@ -45,12 +45,16 @@ PDF := $(patsubst %.xml, %.pdf, $(BOOKS)) | |||
| 45 | pdfdocs: $(PDF) | 45 | pdfdocs: $(PDF) |
| 46 | 46 | ||
| 47 | HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) | 47 | HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) |
| 48 | htmldocs: $(HTML) | 48 | htmldocs: media $(HTML) |
| 49 | $(call build_main_index) | 49 | $(call build_main_index) |
| 50 | 50 | ||
| 51 | MAN := $(patsubst %.xml, %.9, $(BOOKS)) | 51 | MAN := $(patsubst %.xml, %.9, $(BOOKS)) |
| 52 | mandocs: $(MAN) | 52 | mandocs: $(MAN) |
| 53 | 53 | ||
| 54 | media: | ||
| 55 | mkdir -p $(srctree)/Documentation/DocBook/media/ | ||
| 56 | cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(srctree)/Documentation/DocBook/media/ | ||
| 57 | |||
| 54 | installmandocs: mandocs | 58 | installmandocs: mandocs |
| 55 | mkdir -p /usr/local/man/man9/ | 59 | mkdir -p /usr/local/man/man9/ |
| 56 | install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/ | 60 | install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/ |
diff --git a/Documentation/DocBook/dvb/.gitignore b/Documentation/DocBook/dvb/.gitignore new file mode 100644 index 000000000000..d7ec32eafac9 --- /dev/null +++ b/Documentation/DocBook/dvb/.gitignore | |||
| @@ -0,0 +1 @@ | |||
| !*.xml | |||
diff --git a/Documentation/DocBook/dvb/audio.xml b/Documentation/DocBook/dvb/audio.xml new file mode 100644 index 000000000000..eeb96b8a0864 --- /dev/null +++ b/Documentation/DocBook/dvb/audio.xml | |||
| @@ -0,0 +1,1473 @@ | |||
| 1 | <title>DVB Audio Device</title> | ||
| 2 | <para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It | ||
| 3 | can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and | ||
| 4 | ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your | ||
| 5 | application. | ||
| 6 | </para> | ||
| 7 | <para>Please note that some DVB cards don’t have their own MPEG decoder, which results in | ||
| 8 | the omission of the audio and video device. | ||
| 9 | </para> | ||
| 10 | |||
| 11 | <section id="audio_data_types"> | ||
| 12 | <title>Audio Data Types</title> | ||
| 13 | <para>This section describes the structures, data types and defines used when talking to the | ||
| 14 | audio device. | ||
| 15 | </para> | ||
| 16 | |||
| 17 | <section id="audio_stream_source_t"> | ||
| 18 | <title>audio_stream_source_t</title> | ||
| 19 | <para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take | ||
| 20 | the following values, depending on whether we are replaying from an internal (demux) or | ||
| 21 | external (user write) source. | ||
| 22 | </para> | ||
| 23 | <programlisting> | ||
| 24 | typedef enum { | ||
| 25 | AUDIO_SOURCE_DEMUX, | ||
| 26 | AUDIO_SOURCE_MEMORY | ||
| 27 | } audio_stream_source_t; | ||
| 28 | </programlisting> | ||
| 29 | <para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the | ||
| 30 | DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY | ||
| 31 | is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system | ||
| 32 | call. | ||
| 33 | </para> | ||
| 34 | |||
| 35 | </section> | ||
| 36 | <section id="audio_play_state_t"> | ||
| 37 | <title>audio_play_state_t</title> | ||
| 38 | <para>The following values can be returned by the AUDIO_GET_STATUS call representing the | ||
| 39 | state of audio playback. | ||
| 40 | </para> | ||
| 41 | <programlisting> | ||
| 42 | typedef enum { | ||
| 43 | AUDIO_STOPPED, | ||
| 44 | AUDIO_PLAYING, | ||
| 45 | AUDIO_PAUSED | ||
| 46 | } audio_play_state_t; | ||
| 47 | </programlisting> | ||
| 48 | |||
| 49 | </section> | ||
| 50 | <section id="audio_channel_select_t"> | ||
| 51 | <title>audio_channel_select_t</title> | ||
| 52 | <para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the | ||
| 53 | following values. | ||
| 54 | </para> | ||
| 55 | <programlisting> | ||
| 56 | typedef enum { | ||
| 57 | AUDIO_STEREO, | ||
| 58 | AUDIO_MONO_LEFT, | ||
| 59 | AUDIO_MONO_RIGHT, | ||
| 60 | } audio_channel_select_t; | ||
| 61 | </programlisting> | ||
| 62 | |||
| 63 | </section> | ||
| 64 | <section id="struct_audio_status"> | ||
| 65 | <title>struct audio_status</title> | ||
| 66 | <para>The AUDIO_GET_STATUS call returns the following structure informing about various | ||
| 67 | states of the playback operation. | ||
| 68 | </para> | ||
| 69 | <programlisting> | ||
| 70 | typedef struct audio_status { | ||
| 71 | boolean AV_sync_state; | ||
| 72 | boolean mute_state; | ||
| 73 | audio_play_state_t play_state; | ||
| 74 | audio_stream_source_t stream_source; | ||
| 75 | audio_channel_select_t channel_select; | ||
| 76 | boolean bypass_mode; | ||
| 77 | } audio_status_t; | ||
| 78 | </programlisting> | ||
| 79 | |||
| 80 | </section> | ||
| 81 | <section id="struct_audio_mixer"> | ||
| 82 | <title>struct audio_mixer</title> | ||
| 83 | <para>The following structure is used by the AUDIO_SET_MIXER call to set the audio | ||
| 84 | volume. | ||
| 85 | </para> | ||
| 86 | <programlisting> | ||
| 87 | typedef struct audio_mixer { | ||
| 88 | unsigned int volume_left; | ||
| 89 | unsigned int volume_right; | ||
| 90 | } audio_mixer_t; | ||
| 91 | </programlisting> | ||
| 92 | |||
| 93 | </section> | ||
| 94 | <section id="audio_encodings"> | ||
| 95 | <title>audio encodings</title> | ||
| 96 | <para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following | ||
| 97 | bits set according to the hardwares capabilities. | ||
| 98 | </para> | ||
| 99 | <programlisting> | ||
| 100 | #define AUDIO_CAP_DTS 1 | ||
| 101 | #define AUDIO_CAP_LPCM 2 | ||
| 102 | #define AUDIO_CAP_MP1 4 | ||
| 103 | #define AUDIO_CAP_MP2 8 | ||
| 104 | #define AUDIO_CAP_MP3 16 | ||
| 105 | #define AUDIO_CAP_AAC 32 | ||
| 106 | #define AUDIO_CAP_OGG 64 | ||
| 107 | #define AUDIO_CAP_SDDS 128 | ||
| 108 | #define AUDIO_CAP_AC3 256 | ||
| 109 | </programlisting> | ||
| 110 | |||
| 111 | </section> | ||
| 112 | <section id="struct_audio_karaoke"> | ||
| 113 | <title>struct audio_karaoke</title> | ||
| 114 | <para>The ioctl AUDIO_SET_KARAOKE uses the following format: | ||
| 115 | </para> | ||
| 116 | <programlisting> | ||
| 117 | typedef | ||
| 118 | struct audio_karaoke{ | ||
| 119 | int vocal1; | ||
| 120 | int vocal2; | ||
| 121 | int melody; | ||
| 122 | } audio_karaoke_t; | ||
| 123 | </programlisting> | ||
| 124 | <para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both, | ||
| 125 | Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the | ||
| 126 | right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left | ||
| 127 | and right. | ||
| 128 | </para> | ||
| 129 | |||
| 130 | </section> | ||
| 131 | <section id="audio_attributes"> | ||
| 132 | <title>audio attributes</title> | ||
| 133 | <para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES: | ||
| 134 | </para> | ||
| 135 | <programlisting> | ||
| 136 | typedef uint16_t audio_attributes_t; | ||
| 137 | /⋆ bits: descr. ⋆/ | ||
| 138 | /⋆ 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, ⋆/ | ||
| 139 | /⋆ 12 multichannel extension ⋆/ | ||
| 140 | /⋆ 11-10 audio type (0=not spec, 1=language included) ⋆/ | ||
| 141 | /⋆ 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) ⋆/ | ||
| 142 | /⋆ 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, ⋆/ | ||
| 143 | /⋆ 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) ⋆/ | ||
| 144 | /⋆ 2- 0 number of audio channels (n+1 channels) ⋆/ | ||
| 145 | </programlisting> | ||
| 146 | </section></section> | ||
| 147 | <section id="audio_function_calls"> | ||
| 148 | <title>Audio Function Calls</title> | ||
| 149 | |||
| 150 | |||
| 151 | <section id="audio_fopen"> | ||
| 152 | <title>open()</title> | ||
| 153 | <para>DESCRIPTION | ||
| 154 | </para> | ||
| 155 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 156 | align="char"> | ||
| 157 | <para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0) | ||
| 158 | for subsequent use. When an open() call has succeeded, the device will be ready | ||
| 159 | for use. The significance of blocking or non-blocking mode is described in the | ||
| 160 | documentation for functions where there is a difference. It does not affect the | ||
| 161 | semantics of the open() call itself. A device opened in blocking mode can later | ||
| 162 | be put into non-blocking mode (and vice versa) using the F_SETFL command | ||
| 163 | of the fcntl system call. This is a standard system call, documented in the Linux | ||
| 164 | manual page for fcntl. Only one user can open the Audio Device in O_RDWR | ||
| 165 | mode. All other attempts to open the device in this mode will fail, and an error | ||
| 166 | code will be returned. If the Audio Device is opened in O_RDONLY mode, the | ||
| 167 | only ioctl call that can be used is AUDIO_GET_STATUS. All other call will | ||
| 168 | return with an error code.</para> | ||
| 169 | </entry> | ||
| 170 | </row></tbody></tgroup></informaltable> | ||
| 171 | <para>SYNOPSIS | ||
| 172 | </para> | ||
| 173 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 174 | align="char"> | ||
| 175 | <para>int open(const char ⋆deviceName, int flags);</para> | ||
| 176 | </entry> | ||
| 177 | </row></tbody></tgroup></informaltable> | ||
| 178 | <para>PARAMETERS | ||
| 179 | </para> | ||
| 180 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 181 | align="char"> | ||
| 182 | <para>const char | ||
| 183 | *deviceName</para> | ||
| 184 | </entry><entry | ||
| 185 | align="char"> | ||
| 186 | <para>Name of specific audio device.</para> | ||
| 187 | </entry> | ||
| 188 | </row><row><entry | ||
| 189 | align="char"> | ||
| 190 | <para>int flags</para> | ||
| 191 | </entry><entry | ||
| 192 | align="char"> | ||
| 193 | <para>A bit-wise OR of the following flags:</para> | ||
| 194 | </entry> | ||
| 195 | </row><row><entry | ||
| 196 | align="char"> | ||
| 197 | </entry><entry | ||
| 198 | align="char"> | ||
| 199 | <para>O_RDONLY read-only access</para> | ||
| 200 | </entry> | ||
| 201 | </row><row><entry | ||
| 202 | align="char"> | ||
| 203 | </entry><entry | ||
| 204 | align="char"> | ||
| 205 | <para>O_RDWR read/write access</para> | ||
| 206 | </entry> | ||
| 207 | </row><row><entry | ||
| 208 | align="char"> | ||
| 209 | </entry><entry | ||
| 210 | align="char"> | ||
| 211 | <para>O_NONBLOCK open in non-blocking mode</para> | ||
| 212 | </entry> | ||
| 213 | </row><row><entry | ||
| 214 | align="char"> | ||
| 215 | </entry><entry | ||
| 216 | align="char"> | ||
| 217 | <para>(blocking mode is the default)</para> | ||
| 218 | </entry> | ||
| 219 | </row></tbody></tgroup></informaltable> | ||
| 220 | <para>ERRORS | ||
| 221 | </para> | ||
| 222 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 223 | align="char"> | ||
| 224 | <para>ENODEV</para> | ||
| 225 | </entry><entry | ||
| 226 | align="char"> | ||
| 227 | <para>Device driver not loaded/available.</para> | ||
| 228 | </entry> | ||
| 229 | </row><row><entry | ||
| 230 | align="char"> | ||
| 231 | <para>EINTERNAL</para> | ||
| 232 | </entry><entry | ||
| 233 | align="char"> | ||
| 234 | <para>Internal error.</para> | ||
| 235 | </entry> | ||
| 236 | </row><row><entry | ||
| 237 | align="char"> | ||
| 238 | <para>EBUSY</para> | ||
| 239 | </entry><entry | ||
| 240 | align="char"> | ||
| 241 | <para>Device or resource busy.</para> | ||
| 242 | </entry> | ||
| 243 | </row><row><entry | ||
| 244 | align="char"> | ||
| 245 | <para>EINVAL</para> | ||
| 246 | </entry><entry | ||
| 247 | align="char"> | ||
| 248 | <para>Invalid argument.</para> | ||
| 249 | </entry> | ||
| 250 | </row></tbody></tgroup></informaltable> | ||
| 251 | |||
| 252 | </section> | ||
| 253 | <section id="audio_fclose"> | ||
| 254 | <title>close()</title> | ||
| 255 | <para>DESCRIPTION | ||
| 256 | </para> | ||
| 257 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 258 | align="char"> | ||
| 259 | <para>This system call closes a previously opened audio device.</para> | ||
| 260 | </entry> | ||
| 261 | </row></tbody></tgroup></informaltable> | ||
| 262 | <para>SYNOPSIS | ||
| 263 | </para> | ||
| 264 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 265 | align="char"> | ||
| 266 | <para>int close(int fd);</para> | ||
| 267 | </entry> | ||
| 268 | </row></tbody></tgroup></informaltable> | ||
| 269 | <para>PARAMETERS | ||
| 270 | </para> | ||
| 271 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 272 | align="char"> | ||
| 273 | <para>int fd</para> | ||
| 274 | </entry><entry | ||
| 275 | align="char"> | ||
| 276 | <para>File descriptor returned by a previous call to open().</para> | ||
| 277 | </entry> | ||
| 278 | </row></tbody></tgroup></informaltable> | ||
| 279 | <para>ERRORS | ||
| 280 | </para> | ||
| 281 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 282 | align="char"> | ||
| 283 | <para>EBADF</para> | ||
| 284 | </entry><entry | ||
| 285 | align="char"> | ||
| 286 | <para>fd is not a valid open file descriptor.</para> | ||
| 287 | </entry> | ||
| 288 | </row></tbody></tgroup></informaltable> | ||
| 289 | |||
| 290 | </section> | ||
| 291 | <section id="audio_fwrite"> | ||
| 292 | <title>write()</title> | ||
| 293 | <para>DESCRIPTION | ||
| 294 | </para> | ||
| 295 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 296 | align="char"> | ||
| 297 | <para>This system call can only be used if AUDIO_SOURCE_MEMORY is selected | ||
| 298 | in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in | ||
| 299 | PES format. If O_NONBLOCK is not specified the function will block until | ||
| 300 | buffer space is available. The amount of data to be transferred is implied by | ||
| 301 | count.</para> | ||
| 302 | </entry> | ||
| 303 | </row></tbody></tgroup></informaltable> | ||
| 304 | <para>SYNOPSIS | ||
| 305 | </para> | ||
| 306 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 307 | align="char"> | ||
| 308 | <para>size_t write(int fd, const void ⋆buf, size_t count);</para> | ||
| 309 | </entry> | ||
| 310 | </row></tbody></tgroup></informaltable> | ||
| 311 | <para>PARAMETERS | ||
| 312 | </para> | ||
| 313 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 314 | align="char"> | ||
| 315 | <para>int fd</para> | ||
| 316 | </entry><entry | ||
| 317 | align="char"> | ||
| 318 | <para>File descriptor returned by a previous call to open().</para> | ||
| 319 | </entry> | ||
| 320 | </row><row><entry | ||
| 321 | align="char"> | ||
| 322 | <para>void *buf</para> | ||
| 323 | </entry><entry | ||
| 324 | align="char"> | ||
| 325 | <para>Pointer to the buffer containing the PES data.</para> | ||
| 326 | </entry> | ||
| 327 | </row><row><entry | ||
| 328 | align="char"> | ||
| 329 | <para>size_t count</para> | ||
| 330 | </entry><entry | ||
| 331 | align="char"> | ||
| 332 | <para>Size of buf.</para> | ||
| 333 | </entry> | ||
| 334 | </row></tbody></tgroup></informaltable> | ||
| 335 | <para>ERRORS | ||
| 336 | </para> | ||
| 337 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 338 | align="char"> | ||
| 339 | <para>EPERM</para> | ||
| 340 | </entry><entry | ||
| 341 | align="char"> | ||
| 342 | <para>Mode AUDIO_SOURCE_MEMORY not selected.</para> | ||
| 343 | </entry> | ||
| 344 | </row><row><entry | ||
| 345 | align="char"> | ||
| 346 | <para>ENOMEM</para> | ||
| 347 | </entry><entry | ||
| 348 | align="char"> | ||
| 349 | <para>Attempted to write more data than the internal buffer can | ||
| 350 | hold.</para> | ||
| 351 | </entry> | ||
| 352 | </row><row><entry | ||
| 353 | align="char"> | ||
| 354 | <para>EBADF</para> | ||
| 355 | </entry><entry | ||
| 356 | align="char"> | ||
| 357 | <para>fd is not a valid open file descriptor.</para> | ||
| 358 | </entry> | ||
| 359 | </row></tbody></tgroup></informaltable> | ||
| 360 | |||
| 361 | </section><section | ||
| 362 | role="subsection"><title>AUDIO_STOP</title> | ||
| 363 | <para>DESCRIPTION | ||
| 364 | </para> | ||
| 365 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 366 | align="char"> | ||
| 367 | <para>This ioctl call asks the Audio Device to stop playing the current stream.</para> | ||
| 368 | </entry> | ||
| 369 | </row></tbody></tgroup></informaltable> | ||
| 370 | <para>SYNOPSIS | ||
| 371 | </para> | ||
| 372 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 373 | align="char"> | ||
| 374 | <para>int ioctl(int fd, int request = AUDIO_STOP);</para> | ||
| 375 | </entry> | ||
| 376 | </row></tbody></tgroup></informaltable> | ||
| 377 | <para>PARAMETERS | ||
| 378 | </para> | ||
| 379 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 380 | align="char"> | ||
| 381 | <para>int fd</para> | ||
| 382 | </entry><entry | ||
| 383 | align="char"> | ||
| 384 | <para>File descriptor returned by a previous call to open().</para> | ||
| 385 | </entry> | ||
| 386 | </row><row><entry | ||
| 387 | align="char"> | ||
| 388 | <para>int request</para> | ||
| 389 | </entry><entry | ||
| 390 | align="char"> | ||
| 391 | <para>Equals AUDIO_STOP for this command.</para> | ||
| 392 | </entry> | ||
| 393 | </row></tbody></tgroup></informaltable> | ||
| 394 | <para>ERRORS | ||
| 395 | </para> | ||
| 396 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 397 | align="char"> | ||
| 398 | <para>EBADF</para> | ||
| 399 | </entry><entry | ||
| 400 | align="char"> | ||
| 401 | <para>fd is not a valid open file descriptor</para> | ||
| 402 | </entry> | ||
| 403 | </row><row><entry | ||
| 404 | align="char"> | ||
| 405 | <para>EINTERNAL</para> | ||
| 406 | </entry><entry | ||
| 407 | align="char"> | ||
| 408 | <para>Internal error.</para> | ||
| 409 | </entry> | ||
| 410 | </row></tbody></tgroup></informaltable> | ||
| 411 | |||
| 412 | </section><section | ||
| 413 | role="subsection"><title>AUDIO_PLAY</title> | ||
| 414 | <para>DESCRIPTION | ||
| 415 | </para> | ||
| 416 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 417 | align="char"> | ||
| 418 | <para>This ioctl call asks the Audio Device to start playing an audio stream from the | ||
| 419 | selected source.</para> | ||
| 420 | </entry> | ||
| 421 | </row></tbody></tgroup></informaltable> | ||
| 422 | <para>SYNOPSIS | ||
| 423 | </para> | ||
| 424 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 425 | align="char"> | ||
| 426 | <para>int ioctl(int fd, int request = AUDIO_PLAY);</para> | ||
| 427 | </entry> | ||
| 428 | </row></tbody></tgroup></informaltable> | ||
| 429 | <para>PARAMETERS | ||
| 430 | </para> | ||
| 431 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 432 | align="char"> | ||
| 433 | <para>int fd</para> | ||
| 434 | </entry><entry | ||
| 435 | align="char"> | ||
| 436 | <para>File descriptor returned by a previous call to open().</para> | ||
| 437 | </entry> | ||
| 438 | </row><row><entry | ||
| 439 | align="char"> | ||
| 440 | <para>int request</para> | ||
| 441 | </entry><entry | ||
| 442 | align="char"> | ||
| 443 | <para>Equals AUDIO_PLAY for this command.</para> | ||
| 444 | </entry> | ||
| 445 | </row></tbody></tgroup></informaltable> | ||
| 446 | <para>ERRORS | ||
| 447 | </para> | ||
| 448 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 449 | align="char"> | ||
| 450 | <para>EBADF</para> | ||
| 451 | </entry><entry | ||
| 452 | align="char"> | ||
| 453 | <para>fd is not a valid open file descriptor</para> | ||
| 454 | </entry> | ||
| 455 | </row><row><entry | ||
| 456 | align="char"> | ||
| 457 | <para>EINTERNAL</para> | ||
| 458 | </entry><entry | ||
| 459 | align="char"> | ||
| 460 | <para>Internal error.</para> | ||
| 461 | </entry> | ||
| 462 | </row></tbody></tgroup></informaltable> | ||
| 463 | |||
| 464 | </section><section | ||
| 465 | role="subsection"><title>AUDIO_PAUSE</title> | ||
| 466 | <para>DESCRIPTION | ||
| 467 | </para> | ||
| 468 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 469 | align="char"> | ||
| 470 | <para>This ioctl call suspends the audio stream being played. Decoding and playing | ||
| 471 | are paused. It is then possible to restart again decoding and playing process of | ||
| 472 | the audio stream using AUDIO_CONTINUE command.</para> | ||
| 473 | </entry> | ||
| 474 | </row><row><entry | ||
| 475 | align="char"> | ||
| 476 | <para>If AUDIO_SOURCE_MEMORY is selected in the ioctl call | ||
| 477 | AUDIO_SELECT_SOURCE, the DVB-subsystem will not decode (consume) | ||
| 478 | any more data until the ioctl call AUDIO_CONTINUE or AUDIO_PLAY is | ||
| 479 | performed.</para> | ||
| 480 | </entry> | ||
| 481 | </row></tbody></tgroup></informaltable> | ||
| 482 | <para>SYNOPSIS | ||
| 483 | </para> | ||
| 484 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 485 | align="char"> | ||
| 486 | <para>int ioctl(int fd, int request = AUDIO_PAUSE);</para> | ||
| 487 | </entry> | ||
| 488 | </row></tbody></tgroup></informaltable> | ||
| 489 | <para>PARAMETERS | ||
| 490 | </para> | ||
| 491 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 492 | align="char"> | ||
| 493 | <para>int fd</para> | ||
| 494 | </entry><entry | ||
| 495 | align="char"> | ||
| 496 | <para>File descriptor returned by a previous call to open().</para> | ||
| 497 | </entry> | ||
| 498 | </row><row><entry | ||
| 499 | align="char"> | ||
| 500 | <para>int request</para> | ||
| 501 | </entry><entry | ||
| 502 | align="char"> | ||
| 503 | <para>Equals AUDIO_PAUSE for this command.</para> | ||
| 504 | </entry> | ||
| 505 | </row></tbody></tgroup></informaltable> | ||
| 506 | <para>ERRORS | ||
| 507 | </para> | ||
| 508 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 509 | align="char"> | ||
| 510 | <para>EBADF</para> | ||
| 511 | </entry><entry | ||
| 512 | align="char"> | ||
| 513 | <para>fd is not a valid open file descriptor.</para> | ||
| 514 | </entry> | ||
| 515 | </row><row><entry | ||
| 516 | align="char"> | ||
| 517 | <para>EINTERNAL</para> | ||
| 518 | </entry><entry | ||
| 519 | align="char"> | ||
| 520 | <para>Internal error.</para> | ||
| 521 | </entry> | ||
| 522 | </row></tbody></tgroup></informaltable> | ||
| 523 | |||
| 524 | </section><section | ||
| 525 | role="subsection"><title>AUDIO_SELECT_SOURCE</title> | ||
| 526 | <para>DESCRIPTION | ||
| 527 | </para> | ||
| 528 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 529 | align="char"> | ||
| 530 | <para>This ioctl call informs the audio device which source shall be used | ||
| 531 | for the input data. The possible sources are demux or memory. If | ||
| 532 | AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device | ||
| 533 | through the write command.</para> | ||
| 534 | </entry> | ||
| 535 | </row></tbody></tgroup></informaltable> | ||
| 536 | <para>SYNOPSIS | ||
| 537 | </para> | ||
| 538 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 539 | align="char"> | ||
| 540 | <para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, | ||
| 541 | audio_stream_source_t source);</para> | ||
| 542 | </entry> | ||
| 543 | </row></tbody></tgroup></informaltable> | ||
| 544 | <para>PARAMETERS | ||
| 545 | </para> | ||
| 546 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 547 | align="char"> | ||
| 548 | <para>int fd</para> | ||
| 549 | </entry><entry | ||
| 550 | align="char"> | ||
| 551 | <para>File descriptor returned by a previous call to open().</para> | ||
| 552 | </entry> | ||
| 553 | </row><row><entry | ||
| 554 | align="char"> | ||
| 555 | <para>int request</para> | ||
| 556 | </entry><entry | ||
| 557 | align="char"> | ||
| 558 | <para>Equals AUDIO_SELECT_SOURCE for this command.</para> | ||
| 559 | </entry> | ||
| 560 | </row><row><entry | ||
| 561 | align="char"> | ||
| 562 | <para>audio_stream_source_t | ||
| 563 | source</para> | ||
| 564 | </entry><entry | ||
| 565 | align="char"> | ||
| 566 | <para>Indicates the source that shall be used for the Audio | ||
| 567 | stream.</para> | ||
| 568 | </entry> | ||
| 569 | </row></tbody></tgroup></informaltable> | ||
| 570 | <para>ERRORS | ||
| 571 | </para> | ||
| 572 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 573 | align="char"> | ||
| 574 | <para>EBADF</para> | ||
| 575 | </entry><entry | ||
| 576 | align="char"> | ||
| 577 | <para>fd is not a valid open file descriptor.</para> | ||
| 578 | </entry> | ||
| 579 | </row><row><entry | ||
| 580 | align="char"> | ||
| 581 | <para>EINTERNAL</para> | ||
| 582 | </entry><entry | ||
| 583 | align="char"> | ||
| 584 | <para>Internal error.</para> | ||
| 585 | </entry> | ||
| 586 | </row><row><entry | ||
| 587 | align="char"> | ||
| 588 | <para>EINVAL</para> | ||
| 589 | </entry><entry | ||
| 590 | align="char"> | ||
| 591 | <para>Illegal input parameter.</para> | ||
| 592 | </entry> | ||
| 593 | </row></tbody></tgroup></informaltable> | ||
| 594 | |||
| 595 | </section><section | ||
| 596 | role="subsection"><title>AUDIO_SET_MUTE</title> | ||
| 597 | <para>DESCRIPTION | ||
| 598 | </para> | ||
| 599 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 600 | align="char"> | ||
| 601 | <para>This ioctl call asks the audio device to mute the stream that is currently being | ||
| 602 | played.</para> | ||
| 603 | </entry> | ||
| 604 | </row></tbody></tgroup></informaltable> | ||
| 605 | <para>SYNOPSIS | ||
| 606 | </para> | ||
| 607 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 608 | align="char"> | ||
| 609 | <para>int ioctl(int fd, int request = AUDIO_SET_MUTE, | ||
| 610 | boolean state);</para> | ||
| 611 | </entry> | ||
| 612 | </row></tbody></tgroup></informaltable> | ||
| 613 | <para>PARAMETERS | ||
| 614 | </para> | ||
| 615 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 616 | align="char"> | ||
| 617 | <para>int fd</para> | ||
| 618 | </entry><entry | ||
| 619 | align="char"> | ||
| 620 | <para>File descriptor returned by a previous call to open().</para> | ||
| 621 | </entry> | ||
| 622 | </row><row><entry | ||
| 623 | align="char"> | ||
| 624 | <para>int request</para> | ||
| 625 | </entry><entry | ||
| 626 | align="char"> | ||
| 627 | <para>Equals AUDIO_SET_MUTE for this command.</para> | ||
| 628 | </entry> | ||
| 629 | </row><row><entry | ||
| 630 | align="char"> | ||
| 631 | <para>boolean state</para> | ||
| 632 | </entry><entry | ||
| 633 | align="char"> | ||
| 634 | <para>Indicates if audio device shall mute or not.</para> | ||
| 635 | </entry> | ||
| 636 | </row><row><entry | ||
| 637 | align="char"> | ||
| 638 | </entry><entry | ||
| 639 | align="char"> | ||
| 640 | <para>TRUE Audio Mute</para> | ||
| 641 | </entry> | ||
| 642 | </row><row><entry | ||
| 643 | align="char"> | ||
| 644 | </entry><entry | ||
| 645 | align="char"> | ||
| 646 | <para>FALSE Audio Un-mute</para> | ||
| 647 | </entry> | ||
| 648 | </row></tbody></tgroup></informaltable> | ||
| 649 | <para>ERRORS | ||
| 650 | </para> | ||
| 651 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 652 | align="char"> | ||
| 653 | <para>EBADF</para> | ||
| 654 | </entry><entry | ||
| 655 | align="char"> | ||
| 656 | <para>fd is not a valid open file descriptor.</para> | ||
| 657 | </entry> | ||
| 658 | </row><row><entry | ||
| 659 | align="char"> | ||
| 660 | <para>EINTERNAL</para> | ||
| 661 | </entry><entry | ||
| 662 | align="char"> | ||
| 663 | <para>Internal error.</para> | ||
| 664 | </entry> | ||
| 665 | </row><row><entry | ||
| 666 | align="char"> | ||
| 667 | <para>EINVAL</para> | ||
| 668 | </entry><entry | ||
| 669 | align="char"> | ||
| 670 | <para>Illegal input parameter.</para> | ||
| 671 | </entry> | ||
| 672 | </row></tbody></tgroup></informaltable> | ||
| 673 | |||
| 674 | </section><section | ||
| 675 | role="subsection"><title>AUDIO_SET_AV_SYNC</title> | ||
| 676 | <para>DESCRIPTION | ||
| 677 | </para> | ||
| 678 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 679 | align="char"> | ||
| 680 | <para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para> | ||
| 681 | </entry> | ||
| 682 | </row></tbody></tgroup></informaltable> | ||
| 683 | <para>SYNOPSIS | ||
| 684 | </para> | ||
| 685 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 686 | align="char"> | ||
| 687 | <para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, | ||
| 688 | boolean state);</para> | ||
| 689 | </entry> | ||
| 690 | </row></tbody></tgroup></informaltable> | ||
| 691 | <para>PARAMETERS | ||
| 692 | </para> | ||
| 693 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 694 | align="char"> | ||
| 695 | <para>int fd</para> | ||
| 696 | </entry><entry | ||
| 697 | align="char"> | ||
| 698 | <para>File descriptor returned by a previous call to open().</para> | ||
| 699 | </entry> | ||
| 700 | </row><row><entry | ||
| 701 | align="char"> | ||
| 702 | <para>int request</para> | ||
| 703 | </entry><entry | ||
| 704 | align="char"> | ||
| 705 | <para>Equals AUDIO_AV_SYNC for this command.</para> | ||
| 706 | </entry> | ||
| 707 | </row><row><entry | ||
| 708 | align="char"> | ||
| 709 | <para>boolean state</para> | ||
| 710 | </entry><entry | ||
| 711 | align="char"> | ||
| 712 | <para>Tells the DVB subsystem if A/V synchronization shall be | ||
| 713 | ON or OFF.</para> | ||
| 714 | </entry> | ||
| 715 | </row><row><entry | ||
| 716 | align="char"> | ||
| 717 | </entry><entry | ||
| 718 | align="char"> | ||
| 719 | <para>TRUE AV-sync ON</para> | ||
| 720 | </entry> | ||
| 721 | </row><row><entry | ||
| 722 | align="char"> | ||
| 723 | </entry><entry | ||
| 724 | align="char"> | ||
| 725 | <para>FALSE AV-sync OFF</para> | ||
| 726 | </entry> | ||
| 727 | </row></tbody></tgroup></informaltable> | ||
| 728 | <para>ERRORS | ||
| 729 | </para> | ||
| 730 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 731 | align="char"> | ||
| 732 | <para>EBADF</para> | ||
| 733 | </entry><entry | ||
| 734 | align="char"> | ||
| 735 | <para>fd is not a valid open file descriptor.</para> | ||
| 736 | </entry> | ||
| 737 | </row><row><entry | ||
| 738 | align="char"> | ||
| 739 | <para>EINTERNAL</para> | ||
| 740 | </entry><entry | ||
| 741 | align="char"> | ||
| 742 | <para>Internal error.</para> | ||
| 743 | </entry> | ||
| 744 | </row><row><entry | ||
| 745 | align="char"> | ||
| 746 | <para>EINVAL</para> | ||
| 747 | </entry><entry | ||
| 748 | align="char"> | ||
| 749 | <para>Illegal input parameter.</para> | ||
| 750 | </entry> | ||
| 751 | </row></tbody></tgroup></informaltable> | ||
| 752 | |||
| 753 | </section><section | ||
| 754 | role="subsection"><title>AUDIO_SET_BYPASS_MODE</title> | ||
| 755 | <para>DESCRIPTION | ||
| 756 | </para> | ||
| 757 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 758 | align="char"> | ||
| 759 | <para>This ioctl call asks the Audio Device to bypass the Audio decoder and forward | ||
| 760 | the stream without decoding. This mode shall be used if streams that can’t be | ||
| 761 | handled by the DVB system shall be decoded. Dolby DigitalTM streams are | ||
| 762 | automatically forwarded by the DVB subsystem if the hardware can handle it.</para> | ||
| 763 | </entry> | ||
| 764 | </row></tbody></tgroup></informaltable> | ||
| 765 | <para>SYNOPSIS | ||
| 766 | </para> | ||
| 767 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 768 | align="char"> | ||
| 769 | <para>int ioctl(int fd, int request = | ||
| 770 | AUDIO_SET_BYPASS_MODE, boolean mode);</para> | ||
| 771 | </entry> | ||
| 772 | </row></tbody></tgroup></informaltable> | ||
| 773 | <para>PARAMETERS | ||
| 774 | </para> | ||
| 775 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 776 | align="char"> | ||
| 777 | <para>int fd</para> | ||
| 778 | </entry><entry | ||
| 779 | align="char"> | ||
| 780 | <para>File descriptor returned by a previous call to open().</para> | ||
| 781 | </entry> | ||
| 782 | </row><row><entry | ||
| 783 | align="char"> | ||
| 784 | <para>int request</para> | ||
| 785 | </entry><entry | ||
| 786 | align="char"> | ||
| 787 | <para>Equals AUDIO_SET_BYPASS_MODE for this | ||
| 788 | command.</para> | ||
| 789 | </entry> | ||
| 790 | </row><row><entry | ||
| 791 | align="char"> | ||
| 792 | <para>boolean mode</para> | ||
| 793 | </entry><entry | ||
| 794 | align="char"> | ||
| 795 | <para>Enables or disables the decoding of the current Audio | ||
| 796 | stream in the DVB subsystem.</para> | ||
| 797 | </entry> | ||
| 798 | </row><row><entry | ||
| 799 | align="char"> | ||
| 800 | </entry><entry | ||
| 801 | align="char"> | ||
| 802 | <para>TRUE Bypass is disabled</para> | ||
| 803 | </entry> | ||
| 804 | </row><row><entry | ||
| 805 | align="char"> | ||
| 806 | </entry><entry | ||
| 807 | align="char"> | ||
| 808 | <para>FALSE Bypass is enabled</para> | ||
| 809 | </entry> | ||
| 810 | </row></tbody></tgroup></informaltable> | ||
| 811 | <para>ERRORS | ||
| 812 | </para> | ||
| 813 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 814 | align="char"> | ||
| 815 | <para>EBADF</para> | ||
| 816 | </entry><entry | ||
| 817 | align="char"> | ||
| 818 | <para>fd is not a valid open file descriptor.</para> | ||
| 819 | </entry> | ||
| 820 | </row><row><entry | ||
| 821 | align="char"> | ||
| 822 | <para>EINTERNAL</para> | ||
| 823 | </entry><entry | ||
| 824 | align="char"> | ||
| 825 | <para>Internal error.</para> | ||
| 826 | </entry> | ||
| 827 | </row><row><entry | ||
| 828 | align="char"> | ||
| 829 | <para>EINVAL</para> | ||
| 830 | </entry><entry | ||
| 831 | align="char"> | ||
| 832 | <para>Illegal input parameter.</para> | ||
| 833 | </entry> | ||
| 834 | </row></tbody></tgroup></informaltable> | ||
| 835 | |||
| 836 | </section><section | ||
| 837 | role="subsection"><title>AUDIO_CHANNEL_SELECT</title> | ||
| 838 | <para>DESCRIPTION | ||
| 839 | </para> | ||
| 840 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 841 | align="char"> | ||
| 842 | <para>This ioctl call asks the Audio Device to select the requested channel if possible.</para> | ||
| 843 | </entry> | ||
| 844 | </row></tbody></tgroup></informaltable> | ||
| 845 | <para>SYNOPSIS | ||
| 846 | </para> | ||
| 847 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 848 | align="char"> | ||
| 849 | <para>int ioctl(int fd, int request = | ||
| 850 | AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para> | ||
| 851 | </entry> | ||
| 852 | </row></tbody></tgroup></informaltable> | ||
| 853 | <para>PARAMETERS | ||
| 854 | </para> | ||
| 855 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 856 | align="char"> | ||
| 857 | <para>int fd</para> | ||
| 858 | </entry><entry | ||
| 859 | align="char"> | ||
| 860 | <para>File descriptor returned by a previous call to open().</para> | ||
| 861 | </entry> | ||
| 862 | </row><row><entry | ||
| 863 | align="char"> | ||
| 864 | <para>int request</para> | ||
| 865 | </entry><entry | ||
| 866 | align="char"> | ||
| 867 | <para>Equals AUDIO_CHANNEL_SELECT for this | ||
| 868 | command.</para> | ||
| 869 | </entry> | ||
| 870 | </row><row><entry | ||
| 871 | align="char"> | ||
| 872 | <para>audio_channel_select_t | ||
| 873 | ch</para> | ||
| 874 | </entry><entry | ||
| 875 | align="char"> | ||
| 876 | <para>Select the output format of the audio (mono left/right, | ||
| 877 | stereo).</para> | ||
| 878 | </entry> | ||
| 879 | </row></tbody></tgroup></informaltable> | ||
| 880 | <para>ERRORS | ||
| 881 | </para> | ||
| 882 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 883 | align="char"> | ||
| 884 | <para>EBADF</para> | ||
| 885 | </entry><entry | ||
| 886 | align="char"> | ||
| 887 | <para>fd is not a valid open file descriptor.</para> | ||
| 888 | </entry> | ||
| 889 | </row><row><entry | ||
| 890 | align="char"> | ||
| 891 | <para>EINTERNAL</para> | ||
| 892 | </entry><entry | ||
| 893 | align="char"> | ||
| 894 | <para>Internal error.</para> | ||
| 895 | </entry> | ||
| 896 | </row><row><entry | ||
| 897 | align="char"> | ||
| 898 | <para>EINVAL</para> | ||
| 899 | </entry><entry | ||
| 900 | align="char"> | ||
| 901 | <para>Illegal input parameter ch.</para> | ||
| 902 | </entry> | ||
| 903 | </row></tbody></tgroup></informaltable> | ||
| 904 | |||
| 905 | </section><section | ||
| 906 | role="subsection"><title>AUDIO_GET_STATUS</title> | ||
| 907 | <para>DESCRIPTION | ||
| 908 | </para> | ||
| 909 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 910 | align="char"> | ||
| 911 | <para>This ioctl call asks the Audio Device to return the current state of the Audio | ||
| 912 | Device.</para> | ||
| 913 | </entry> | ||
| 914 | </row></tbody></tgroup></informaltable> | ||
| 915 | <para>SYNOPSIS | ||
| 916 | </para> | ||
| 917 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 918 | align="char"> | ||
| 919 | <para>int ioctl(int fd, int request = AUDIO_GET_STATUS, | ||
| 920 | struct audio_status ⋆status);</para> | ||
| 921 | </entry> | ||
| 922 | </row></tbody></tgroup></informaltable> | ||
| 923 | <para>PARAMETERS | ||
| 924 | </para> | ||
| 925 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 926 | align="char"> | ||
| 927 | <para>int fd</para> | ||
| 928 | </entry><entry | ||
| 929 | align="char"> | ||
| 930 | <para>File descriptor returned by a previous call to open().</para> | ||
| 931 | </entry> | ||
| 932 | </row><row><entry | ||
| 933 | align="char"> | ||
| 934 | <para>int request</para> | ||
| 935 | </entry><entry | ||
| 936 | align="char"> | ||
| 937 | <para>Equals AUDIO_GET_STATUS for this command.</para> | ||
| 938 | </entry> | ||
| 939 | </row><row><entry | ||
| 940 | align="char"> | ||
| 941 | <para>struct audio_status | ||
| 942 | *status</para> | ||
| 943 | </entry><entry | ||
| 944 | align="char"> | ||
| 945 | <para>Returns the current state of Audio Device.</para> | ||
| 946 | </entry> | ||
| 947 | </row></tbody></tgroup></informaltable> | ||
| 948 | <para>ERRORS | ||
| 949 | </para> | ||
| 950 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 951 | align="char"> | ||
| 952 | <para>EBADF</para> | ||
| 953 | </entry><entry | ||
| 954 | align="char"> | ||
| 955 | <para>fd is not a valid open file descriptor.</para> | ||
| 956 | </entry> | ||
| 957 | </row><row><entry | ||
| 958 | align="char"> | ||
| 959 | <para>EINTERNAL</para> | ||
| 960 | </entry><entry | ||
| 961 | align="char"> | ||
| 962 | <para>Internal error.</para> | ||
| 963 | </entry> | ||
| 964 | </row><row><entry | ||
| 965 | align="char"> | ||
| 966 | <para>EFAULT</para> | ||
| 967 | </entry><entry | ||
| 968 | align="char"> | ||
| 969 | <para>status points to invalid address.</para> | ||
| 970 | </entry> | ||
| 971 | </row></tbody></tgroup></informaltable> | ||
| 972 | |||
| 973 | </section><section | ||
| 974 | role="subsection"><title>AUDIO_GET_CAPABILITIES</title> | ||
| 975 | <para>DESCRIPTION | ||
| 976 | </para> | ||
| 977 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 978 | align="char"> | ||
| 979 | <para>This ioctl call asks the Audio Device to tell us about the decoding capabilities | ||
| 980 | of the audio hardware.</para> | ||
| 981 | </entry> | ||
| 982 | </row></tbody></tgroup></informaltable> | ||
| 983 | <para>SYNOPSIS | ||
| 984 | </para> | ||
| 985 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 986 | align="char"> | ||
| 987 | <para>int ioctl(int fd, int request = | ||
| 988 | AUDIO_GET_CAPABILITIES, unsigned int ⋆cap);</para> | ||
| 989 | </entry> | ||
| 990 | </row></tbody></tgroup></informaltable> | ||
| 991 | <para>PARAMETERS | ||
| 992 | </para> | ||
| 993 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 994 | align="char"> | ||
| 995 | <para>int fd</para> | ||
| 996 | </entry><entry | ||
| 997 | align="char"> | ||
| 998 | <para>File descriptor returned by a previous call to open().</para> | ||
| 999 | </entry> | ||
| 1000 | </row><row><entry | ||
| 1001 | align="char"> | ||
| 1002 | <para>int request</para> | ||
| 1003 | </entry><entry | ||
| 1004 | align="char"> | ||
| 1005 | <para>Equals AUDIO_GET_CAPABILITIES for this | ||
| 1006 | command.</para> | ||
| 1007 | </entry> | ||
| 1008 | </row><row><entry | ||
| 1009 | align="char"> | ||
| 1010 | <para>unsigned int *cap</para> | ||
| 1011 | </entry><entry | ||
| 1012 | align="char"> | ||
| 1013 | <para>Returns a bit array of supported sound formats.</para> | ||
| 1014 | </entry> | ||
| 1015 | </row></tbody></tgroup></informaltable> | ||
| 1016 | <para>ERRORS | ||
| 1017 | </para> | ||
| 1018 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1019 | align="char"> | ||
| 1020 | <para>EBADF</para> | ||
| 1021 | </entry><entry | ||
| 1022 | align="char"> | ||
| 1023 | <para>fd is not a valid open file descriptor.</para> | ||
| 1024 | </entry> | ||
| 1025 | </row><row><entry | ||
| 1026 | align="char"> | ||
| 1027 | <para>EINTERNAL</para> | ||
| 1028 | </entry><entry | ||
| 1029 | align="char"> | ||
| 1030 | <para>Internal error.</para> | ||
| 1031 | </entry> | ||
| 1032 | </row><row><entry | ||
| 1033 | align="char"> | ||
| 1034 | <para>EFAULT</para> | ||
| 1035 | </entry><entry | ||
| 1036 | align="char"> | ||
| 1037 | <para>cap points to an invalid address.</para> | ||
| 1038 | </entry> | ||
| 1039 | </row></tbody></tgroup></informaltable> | ||
| 1040 | |||
| 1041 | </section><section | ||
| 1042 | role="subsection"><title>AUDIO_CLEAR_BUFFER</title> | ||
| 1043 | <para>DESCRIPTION | ||
| 1044 | </para> | ||
| 1045 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1046 | align="char"> | ||
| 1047 | <para>This ioctl call asks the Audio Device to clear all software and hardware buffers | ||
| 1048 | of the audio decoder device.</para> | ||
| 1049 | </entry> | ||
| 1050 | </row></tbody></tgroup></informaltable> | ||
| 1051 | <para>SYNOPSIS | ||
| 1052 | </para> | ||
| 1053 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1054 | align="char"> | ||
| 1055 | <para>int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);</para> | ||
| 1056 | </entry> | ||
| 1057 | </row></tbody></tgroup></informaltable> | ||
| 1058 | <para>PARAMETERS | ||
| 1059 | </para> | ||
| 1060 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1061 | align="char"> | ||
| 1062 | <para>int fd</para> | ||
| 1063 | </entry><entry | ||
| 1064 | align="char"> | ||
| 1065 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1066 | </entry> | ||
| 1067 | </row><row><entry | ||
| 1068 | align="char"> | ||
| 1069 | <para>int request</para> | ||
| 1070 | </entry><entry | ||
| 1071 | align="char"> | ||
| 1072 | <para>Equals AUDIO_CLEAR_BUFFER for this command.</para> | ||
| 1073 | </entry> | ||
| 1074 | </row></tbody></tgroup></informaltable> | ||
| 1075 | <para>ERRORS | ||
| 1076 | </para> | ||
| 1077 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1078 | align="char"> | ||
| 1079 | <para>EBADF</para> | ||
| 1080 | </entry><entry | ||
| 1081 | align="char"> | ||
| 1082 | <para>fd is not a valid open file descriptor.</para> | ||
| 1083 | </entry> | ||
| 1084 | </row><row><entry | ||
| 1085 | align="char"> | ||
| 1086 | <para>EINTERNAL</para> | ||
| 1087 | </entry><entry | ||
| 1088 | align="char"> | ||
| 1089 | <para>Internal error.</para> | ||
| 1090 | </entry> | ||
| 1091 | </row></tbody></tgroup></informaltable> | ||
| 1092 | |||
| 1093 | </section><section | ||
| 1094 | role="subsection"><title>AUDIO_SET_ID</title> | ||
| 1095 | <para>DESCRIPTION | ||
| 1096 | </para> | ||
| 1097 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1098 | align="char"> | ||
| 1099 | <para>This ioctl selects which sub-stream is to be decoded if a program or system | ||
| 1100 | stream is sent to the video device. If no audio stream type is set the id has to be | ||
| 1101 | in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] | ||
| 1102 | for LPCM. More specifications may follow for other stream types. If the stream | ||
| 1103 | type is set the id just specifies the substream id of the audio stream and only | ||
| 1104 | the first 5 bits are recognized.</para> | ||
| 1105 | </entry> | ||
| 1106 | </row></tbody></tgroup></informaltable> | ||
| 1107 | <para>SYNOPSIS | ||
| 1108 | </para> | ||
| 1109 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1110 | align="char"> | ||
| 1111 | <para>int ioctl(int fd, int request = AUDIO_SET_ID, int | ||
| 1112 | id);</para> | ||
| 1113 | </entry> | ||
| 1114 | </row></tbody></tgroup></informaltable> | ||
| 1115 | <para>PARAMETERS | ||
| 1116 | </para> | ||
| 1117 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1118 | align="char"> | ||
| 1119 | <para>int fd</para> | ||
| 1120 | </entry><entry | ||
| 1121 | align="char"> | ||
| 1122 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1123 | </entry> | ||
| 1124 | </row><row><entry | ||
| 1125 | align="char"> | ||
| 1126 | <para>int request</para> | ||
| 1127 | </entry><entry | ||
| 1128 | align="char"> | ||
| 1129 | <para>Equals AUDIO_SET_ID for this command.</para> | ||
| 1130 | </entry> | ||
| 1131 | </row><row><entry | ||
| 1132 | align="char"> | ||
| 1133 | <para>int id</para> | ||
| 1134 | </entry><entry | ||
| 1135 | align="char"> | ||
| 1136 | <para>audio sub-stream id</para> | ||
| 1137 | </entry> | ||
| 1138 | </row></tbody></tgroup></informaltable> | ||
| 1139 | <para>ERRORS | ||
| 1140 | </para> | ||
| 1141 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1142 | align="char"> | ||
| 1143 | <para>EBADF</para> | ||
| 1144 | </entry><entry | ||
| 1145 | align="char"> | ||
| 1146 | <para>fd is not a valid open file descriptor.</para> | ||
| 1147 | </entry> | ||
| 1148 | </row><row><entry | ||
| 1149 | align="char"> | ||
| 1150 | <para>EINTERNAL</para> | ||
| 1151 | </entry><entry | ||
| 1152 | align="char"> | ||
| 1153 | <para>Internal error.</para> | ||
| 1154 | </entry> | ||
| 1155 | </row><row><entry | ||
| 1156 | align="char"> | ||
| 1157 | <para>EINVAL</para> | ||
| 1158 | </entry><entry | ||
| 1159 | align="char"> | ||
| 1160 | <para>Invalid sub-stream id.</para> | ||
| 1161 | </entry> | ||
| 1162 | </row></tbody></tgroup></informaltable> | ||
| 1163 | |||
| 1164 | </section><section | ||
| 1165 | role="subsection"><title>AUDIO_SET_MIXER</title> | ||
| 1166 | <para>DESCRIPTION | ||
| 1167 | </para> | ||
| 1168 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1169 | align="char"> | ||
| 1170 | <para>This ioctl lets you adjust the mixer settings of the audio decoder.</para> | ||
| 1171 | </entry> | ||
| 1172 | </row></tbody></tgroup></informaltable> | ||
| 1173 | <para>SYNOPSIS | ||
| 1174 | </para> | ||
| 1175 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1176 | align="char"> | ||
| 1177 | <para>int ioctl(int fd, int request = AUDIO_SET_MIXER, | ||
| 1178 | audio_mixer_t ⋆mix);</para> | ||
| 1179 | </entry> | ||
| 1180 | </row></tbody></tgroup></informaltable> | ||
| 1181 | <para>PARAMETERS | ||
| 1182 | </para> | ||
| 1183 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1184 | align="char"> | ||
| 1185 | <para>int fd</para> | ||
| 1186 | </entry><entry | ||
| 1187 | align="char"> | ||
| 1188 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1189 | </entry> | ||
| 1190 | </row><row><entry | ||
| 1191 | align="char"> | ||
| 1192 | <para>int request</para> | ||
| 1193 | </entry><entry | ||
| 1194 | align="char"> | ||
| 1195 | <para>Equals AUDIO_SET_ID for this command.</para> | ||
| 1196 | </entry> | ||
| 1197 | </row><row><entry | ||
| 1198 | align="char"> | ||
| 1199 | <para>audio_mixer_t *mix</para> | ||
| 1200 | </entry><entry | ||
| 1201 | align="char"> | ||
| 1202 | <para>mixer settings.</para> | ||
| 1203 | </entry> | ||
| 1204 | </row></tbody></tgroup></informaltable> | ||
| 1205 | <para>ERRORS | ||
| 1206 | </para> | ||
| 1207 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1208 | align="char"> | ||
| 1209 | <para>EBADF</para> | ||
| 1210 | </entry><entry | ||
| 1211 | align="char"> | ||
| 1212 | <para>fd is not a valid open file descriptor.</para> | ||
| 1213 | </entry> | ||
| 1214 | </row><row><entry | ||
| 1215 | align="char"> | ||
| 1216 | <para>EINTERNAL</para> | ||
| 1217 | </entry><entry | ||
| 1218 | align="char"> | ||
| 1219 | <para>Internal error.</para> | ||
| 1220 | </entry> | ||
| 1221 | </row><row><entry | ||
| 1222 | align="char"> | ||
| 1223 | <para>EFAULT</para> | ||
| 1224 | </entry><entry | ||
| 1225 | align="char"> | ||
| 1226 | <para>mix points to an invalid address.</para> | ||
| 1227 | </entry> | ||
| 1228 | </row></tbody></tgroup></informaltable> | ||
| 1229 | |||
| 1230 | </section><section | ||
| 1231 | role="subsection"><title>AUDIO_SET_STREAMTYPE</title> | ||
| 1232 | <para>DESCRIPTION | ||
| 1233 | </para> | ||
| 1234 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1235 | align="char"> | ||
| 1236 | <para>This ioctl tells the driver which kind of audio stream to expect. This is useful | ||
| 1237 | if the stream offers several audio sub-streams like LPCM and AC3.</para> | ||
| 1238 | </entry> | ||
| 1239 | </row></tbody></tgroup></informaltable> | ||
| 1240 | <para>SYNOPSIS | ||
| 1241 | </para> | ||
| 1242 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1243 | align="char"> | ||
| 1244 | <para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, | ||
| 1245 | int type);</para> | ||
| 1246 | </entry> | ||
| 1247 | </row></tbody></tgroup></informaltable> | ||
| 1248 | <para>PARAMETERS | ||
| 1249 | </para> | ||
| 1250 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1251 | align="char"> | ||
| 1252 | <para>int fd</para> | ||
| 1253 | </entry><entry | ||
| 1254 | align="char"> | ||
| 1255 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1256 | </entry> | ||
| 1257 | </row><row><entry | ||
| 1258 | align="char"> | ||
| 1259 | <para>int request</para> | ||
| 1260 | </entry><entry | ||
| 1261 | align="char"> | ||
| 1262 | <para>Equals AUDIO_SET_STREAMTYPE for this | ||
| 1263 | command.</para> | ||
| 1264 | </entry> | ||
| 1265 | </row><row><entry | ||
| 1266 | align="char"> | ||
| 1267 | <para>int type</para> | ||
| 1268 | </entry><entry | ||
| 1269 | align="char"> | ||
| 1270 | <para>stream type</para> | ||
| 1271 | </entry> | ||
| 1272 | </row></tbody></tgroup></informaltable> | ||
| 1273 | <para>ERRORS | ||
| 1274 | </para> | ||
| 1275 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1276 | align="char"> | ||
| 1277 | <para>EBADF</para> | ||
| 1278 | </entry><entry | ||
| 1279 | align="char"> | ||
| 1280 | <para>fd is not a valid open file descriptor</para> | ||
| 1281 | </entry> | ||
| 1282 | </row><row><entry | ||
| 1283 | align="char"> | ||
| 1284 | <para>EINVAL</para> | ||
| 1285 | </entry><entry | ||
| 1286 | align="char"> | ||
| 1287 | <para>type is not a valid or supported stream type.</para> | ||
| 1288 | </entry> | ||
| 1289 | </row></tbody></tgroup></informaltable> | ||
| 1290 | |||
| 1291 | </section><section | ||
| 1292 | role="subsection"><title>AUDIO_SET_EXT_ID</title> | ||
| 1293 | <para>DESCRIPTION | ||
| 1294 | </para> | ||
| 1295 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1296 | align="char"> | ||
| 1297 | <para>This ioctl can be used to set the extension id for MPEG streams in DVD | ||
| 1298 | playback. Only the first 3 bits are recognized.</para> | ||
| 1299 | </entry> | ||
| 1300 | </row></tbody></tgroup></informaltable> | ||
| 1301 | <para>SYNOPSIS | ||
| 1302 | </para> | ||
| 1303 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1304 | align="char"> | ||
| 1305 | <para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int | ||
| 1306 | id);</para> | ||
| 1307 | </entry> | ||
| 1308 | </row></tbody></tgroup></informaltable> | ||
| 1309 | <para>PARAMETERS | ||
| 1310 | </para> | ||
| 1311 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1312 | align="char"> | ||
| 1313 | <para>int fd</para> | ||
| 1314 | </entry><entry | ||
| 1315 | align="char"> | ||
| 1316 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1317 | </entry> | ||
| 1318 | </row><row><entry | ||
| 1319 | align="char"> | ||
| 1320 | <para>int request</para> | ||
| 1321 | </entry><entry | ||
| 1322 | align="char"> | ||
| 1323 | <para>Equals AUDIO_SET_EXT_ID for this command.</para> | ||
| 1324 | </entry> | ||
| 1325 | </row><row><entry | ||
| 1326 | align="char"> | ||
| 1327 | <para>int id</para> | ||
| 1328 | </entry><entry | ||
| 1329 | align="char"> | ||
| 1330 | <para>audio sub_stream_id</para> | ||
| 1331 | </entry> | ||
| 1332 | </row></tbody></tgroup></informaltable> | ||
| 1333 | <para>ERRORS | ||
| 1334 | </para> | ||
| 1335 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1336 | align="char"> | ||
| 1337 | <para>EBADF</para> | ||
| 1338 | </entry><entry | ||
| 1339 | align="char"> | ||
| 1340 | <para>fd is not a valid open file descriptor</para> | ||
| 1341 | </entry> | ||
| 1342 | </row><row><entry | ||
| 1343 | align="char"> | ||
| 1344 | <para>EINVAL</para> | ||
| 1345 | </entry><entry | ||
| 1346 | align="char"> | ||
| 1347 | <para>id is not a valid id.</para> | ||
| 1348 | </entry> | ||
| 1349 | </row></tbody></tgroup></informaltable> | ||
| 1350 | |||
| 1351 | </section><section | ||
| 1352 | role="subsection"><title>AUDIO_SET_ATTRIBUTES</title> | ||
| 1353 | <para>DESCRIPTION | ||
| 1354 | </para> | ||
| 1355 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1356 | align="char"> | ||
| 1357 | <para>This ioctl is intended for DVD playback and allows you to set certain | ||
| 1358 | information about the audio stream.</para> | ||
| 1359 | </entry> | ||
| 1360 | </row></tbody></tgroup></informaltable> | ||
| 1361 | <para>SYNOPSIS | ||
| 1362 | </para> | ||
| 1363 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1364 | align="char"> | ||
| 1365 | <para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, | ||
| 1366 | audio_attributes_t attr );</para> | ||
| 1367 | </entry> | ||
| 1368 | </row></tbody></tgroup></informaltable> | ||
| 1369 | <para>PARAMETERS | ||
| 1370 | </para> | ||
| 1371 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1372 | align="char"> | ||
| 1373 | <para>int fd</para> | ||
| 1374 | </entry><entry | ||
| 1375 | align="char"> | ||
| 1376 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1377 | </entry> | ||
| 1378 | </row><row><entry | ||
| 1379 | align="char"> | ||
| 1380 | <para>int request</para> | ||
| 1381 | </entry><entry | ||
| 1382 | align="char"> | ||
| 1383 | <para>Equals AUDIO_SET_ATTRIBUTES for this command.</para> | ||
| 1384 | </entry> | ||
| 1385 | </row><row><entry | ||
| 1386 | align="char"> | ||
| 1387 | <para>audio_attributes_t | ||
| 1388 | attr</para> | ||
| 1389 | </entry><entry | ||
| 1390 | align="char"> | ||
| 1391 | <para>audio attributes according to section ??</para> | ||
| 1392 | </entry> | ||
| 1393 | </row></tbody></tgroup></informaltable> | ||
| 1394 | <para>ERRORS | ||
| 1395 | </para> | ||
| 1396 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1397 | align="char"> | ||
| 1398 | <para>EBADF</para> | ||
| 1399 | </entry><entry | ||
| 1400 | align="char"> | ||
| 1401 | <para>fd is not a valid open file descriptor</para> | ||
| 1402 | </entry> | ||
| 1403 | </row><row><entry | ||
| 1404 | align="char"> | ||
| 1405 | <para>EINVAL</para> | ||
| 1406 | </entry><entry | ||
| 1407 | align="char"> | ||
| 1408 | <para>attr is not a valid or supported attribute setting.</para> | ||
| 1409 | </entry> | ||
| 1410 | </row></tbody></tgroup></informaltable> | ||
| 1411 | |||
| 1412 | </section><section | ||
| 1413 | role="subsection"><title>AUDIO_SET_KARAOKE</title> | ||
| 1414 | <para>DESCRIPTION | ||
| 1415 | </para> | ||
| 1416 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1417 | align="char"> | ||
| 1418 | <para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para> | ||
| 1419 | </entry> | ||
| 1420 | </row></tbody></tgroup></informaltable> | ||
| 1421 | <para>SYNOPSIS | ||
| 1422 | </para> | ||
| 1423 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1424 | align="char"> | ||
| 1425 | <para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, | ||
| 1426 | audio_karaoke_t ⋆karaoke);</para> | ||
| 1427 | </entry> | ||
| 1428 | </row></tbody></tgroup></informaltable> | ||
| 1429 | <para>PARAMETERS | ||
| 1430 | </para> | ||
| 1431 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1432 | align="char"> | ||
| 1433 | <para>int fd</para> | ||
| 1434 | </entry><entry | ||
| 1435 | align="char"> | ||
| 1436 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1437 | </entry> | ||
| 1438 | </row><row><entry | ||
| 1439 | align="char"> | ||
| 1440 | <para>int request</para> | ||
| 1441 | </entry><entry | ||
| 1442 | align="char"> | ||
| 1443 | <para>Equals AUDIO_SET_STREAMTYPE for this | ||
| 1444 | command.</para> | ||
| 1445 | </entry> | ||
| 1446 | </row><row><entry | ||
| 1447 | align="char"> | ||
| 1448 | <para>audio_karaoke_t | ||
| 1449 | *karaoke</para> | ||
| 1450 | </entry><entry | ||
| 1451 | align="char"> | ||
| 1452 | <para>karaoke settings according to section ??.</para> | ||
| 1453 | </entry> | ||
| 1454 | </row></tbody></tgroup></informaltable> | ||
| 1455 | <para>ERRORS | ||
| 1456 | </para> | ||
| 1457 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1458 | align="char"> | ||
| 1459 | <para>EBADF</para> | ||
| 1460 | </entry><entry | ||
| 1461 | align="char"> | ||
| 1462 | <para>fd is not a valid open file descriptor</para> | ||
| 1463 | </entry> | ||
| 1464 | </row><row><entry | ||
| 1465 | align="char"> | ||
| 1466 | <para>EINVAL</para> | ||
| 1467 | </entry><entry | ||
| 1468 | align="char"> | ||
| 1469 | <para>karaoke is not a valid or supported karaoke setting.</para> | ||
| 1470 | </entry> | ||
| 1471 | </row></tbody></tgroup></informaltable> | ||
| 1472 | </section> | ||
| 1473 | </section> | ||
diff --git a/Documentation/DocBook/dvb/ca.xml b/Documentation/DocBook/dvb/ca.xml new file mode 100644 index 000000000000..b1f1d2fad654 --- /dev/null +++ b/Documentation/DocBook/dvb/ca.xml | |||
| @@ -0,0 +1,221 @@ | |||
| 1 | <title>DVB CA Device</title> | ||
| 2 | <para>The DVB CA device controls the conditional access hardware. It can be accessed through | ||
| 3 | <emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by | ||
| 4 | including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application. | ||
| 5 | </para> | ||
| 6 | |||
| 7 | <section id="ca_data_types"> | ||
| 8 | <title>CA Data Types</title> | ||
| 9 | |||
| 10 | |||
| 11 | <section id="ca_slot_info_t"> | ||
| 12 | <title>ca_slot_info_t</title> | ||
| 13 | <programlisting> | ||
| 14 | /⋆ slot interface types and info ⋆/ | ||
| 15 | |||
| 16 | typedef struct ca_slot_info_s { | ||
| 17 | int num; /⋆ slot number ⋆/ | ||
| 18 | |||
| 19 | int type; /⋆ CA interface this slot supports ⋆/ | ||
| 20 | #define CA_CI 1 /⋆ CI high level interface ⋆/ | ||
| 21 | #define CA_CI_LINK 2 /⋆ CI link layer level interface ⋆/ | ||
| 22 | #define CA_CI_PHYS 4 /⋆ CI physical layer level interface ⋆/ | ||
| 23 | #define CA_SC 128 /⋆ simple smart card interface ⋆/ | ||
| 24 | |||
| 25 | unsigned int flags; | ||
| 26 | #define CA_CI_MODULE_PRESENT 1 /⋆ module (or card) inserted ⋆/ | ||
| 27 | #define CA_CI_MODULE_READY 2 | ||
| 28 | } ca_slot_info_t; | ||
| 29 | </programlisting> | ||
| 30 | |||
| 31 | </section> | ||
| 32 | <section id="ca_descr_info_t"> | ||
| 33 | <title>ca_descr_info_t</title> | ||
| 34 | <programlisting> | ||
| 35 | typedef struct ca_descr_info_s { | ||
| 36 | unsigned int num; /⋆ number of available descramblers (keys) ⋆/ | ||
| 37 | unsigned int type; /⋆ type of supported scrambling system ⋆/ | ||
| 38 | #define CA_ECD 1 | ||
| 39 | #define CA_NDS 2 | ||
| 40 | #define CA_DSS 4 | ||
| 41 | } ca_descr_info_t; | ||
| 42 | </programlisting> | ||
| 43 | |||
| 44 | </section> | ||
| 45 | <section id="ca_cap_t"> | ||
| 46 | <title>ca_cap_t</title> | ||
| 47 | <programlisting> | ||
| 48 | typedef struct ca_cap_s { | ||
| 49 | unsigned int slot_num; /⋆ total number of CA card and module slots ⋆/ | ||
| 50 | unsigned int slot_type; /⋆ OR of all supported types ⋆/ | ||
| 51 | unsigned int descr_num; /⋆ total number of descrambler slots (keys) ⋆/ | ||
| 52 | unsigned int descr_type;/⋆ OR of all supported types ⋆/ | ||
| 53 | } ca_cap_t; | ||
| 54 | </programlisting> | ||
| 55 | |||
| 56 | </section> | ||
| 57 | <section id="ca_msg_t"> | ||
| 58 | <title>ca_msg_t</title> | ||
| 59 | <programlisting> | ||
| 60 | /⋆ a message to/from a CI-CAM ⋆/ | ||
| 61 | typedef struct ca_msg_s { | ||
| 62 | unsigned int index; | ||
| 63 | unsigned int type; | ||
| 64 | unsigned int length; | ||
| 65 | unsigned char msg[256]; | ||
| 66 | } ca_msg_t; | ||
| 67 | </programlisting> | ||
| 68 | |||
| 69 | </section> | ||
| 70 | <section id="ca_descr_t"> | ||
| 71 | <title>ca_descr_t</title> | ||
| 72 | <programlisting> | ||
| 73 | typedef struct ca_descr_s { | ||
| 74 | unsigned int index; | ||
| 75 | unsigned int parity; | ||
| 76 | unsigned char cw[8]; | ||
| 77 | } ca_descr_t; | ||
| 78 | </programlisting> | ||
| 79 | </section></section> | ||
| 80 | <section id="ca_function_calls"> | ||
| 81 | <title>CA Function Calls</title> | ||
| 82 | |||
| 83 | |||
| 84 | <section id="ca_fopen"> | ||
| 85 | <title>open()</title> | ||
| 86 | <para>DESCRIPTION | ||
| 87 | </para> | ||
| 88 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 89 | align="char"> | ||
| 90 | <para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para> | ||
| 91 | <para>When an open() call has succeeded, the device will be ready for use. | ||
| 92 | The significance of blocking or non-blocking mode is described in the | ||
| 93 | documentation for functions where there is a difference. It does not affect the | ||
| 94 | semantics of the open() call itself. A device opened in blocking mode can later | ||
| 95 | be put into non-blocking mode (and vice versa) using the F_SETFL command | ||
| 96 | of the fcntl system call. This is a standard system call, documented in the Linux | ||
| 97 | manual page for fcntl. Only one user can open the CA Device in O_RDWR | ||
| 98 | mode. All other attempts to open the device in this mode will fail, and an error | ||
| 99 | code will be returned.</para> | ||
| 100 | </entry> | ||
| 101 | </row></tbody></tgroup></informaltable> | ||
| 102 | <para>SYNOPSIS | ||
| 103 | </para> | ||
| 104 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 105 | align="char"> | ||
| 106 | <para>int open(const char ⋆deviceName, int flags);</para> | ||
| 107 | </entry> | ||
| 108 | </row></tbody></tgroup></informaltable> | ||
| 109 | <para>PARAMETERS | ||
| 110 | </para> | ||
| 111 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 112 | align="char"> | ||
| 113 | <para>const char | ||
| 114 | *deviceName</para> | ||
| 115 | </entry><entry | ||
| 116 | align="char"> | ||
| 117 | <para>Name of specific video device.</para> | ||
| 118 | </entry> | ||
| 119 | </row><row><entry | ||
| 120 | align="char"> | ||
| 121 | <para>int flags</para> | ||
| 122 | </entry><entry | ||
| 123 | align="char"> | ||
| 124 | <para>A bit-wise OR of the following flags:</para> | ||
| 125 | </entry> | ||
| 126 | </row><row><entry | ||
| 127 | align="char"> | ||
| 128 | </entry><entry | ||
| 129 | align="char"> | ||
| 130 | <para>O_RDONLY read-only access</para> | ||
| 131 | </entry> | ||
| 132 | </row><row><entry | ||
| 133 | align="char"> | ||
| 134 | </entry><entry | ||
| 135 | align="char"> | ||
| 136 | <para>O_RDWR read/write access</para> | ||
| 137 | </entry> | ||
| 138 | </row><row><entry | ||
| 139 | align="char"> | ||
| 140 | </entry><entry | ||
| 141 | align="char"> | ||
| 142 | <para>O_NONBLOCK open in non-blocking mode</para> | ||
| 143 | </entry> | ||
| 144 | </row><row><entry | ||
| 145 | align="char"> | ||
| 146 | </entry><entry | ||
| 147 | align="char"> | ||
| 148 | <para>(blocking mode is the default)</para> | ||
| 149 | </entry> | ||
| 150 | </row></tbody></tgroup></informaltable> | ||
| 151 | <para>ERRORS | ||
| 152 | </para> | ||
| 153 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 154 | align="char"> | ||
| 155 | <para>ENODEV</para> | ||
| 156 | </entry><entry | ||
| 157 | align="char"> | ||
| 158 | <para>Device driver not loaded/available.</para> | ||
| 159 | </entry> | ||
| 160 | </row><row><entry | ||
| 161 | align="char"> | ||
| 162 | <para>EINTERNAL</para> | ||
| 163 | </entry><entry | ||
| 164 | align="char"> | ||
| 165 | <para>Internal error.</para> | ||
| 166 | </entry> | ||
| 167 | </row><row><entry | ||
| 168 | align="char"> | ||
| 169 | <para>EBUSY</para> | ||
| 170 | </entry><entry | ||
| 171 | align="char"> | ||
| 172 | <para>Device or resource busy.</para> | ||
| 173 | </entry> | ||
| 174 | </row><row><entry | ||
| 175 | align="char"> | ||
| 176 | <para>EINVAL</para> | ||
| 177 | </entry><entry | ||
| 178 | align="char"> | ||
| 179 | <para>Invalid argument.</para> | ||
| 180 | </entry> | ||
| 181 | </row></tbody></tgroup></informaltable> | ||
| 182 | |||
| 183 | </section> | ||
| 184 | <section id="ca_fclose"> | ||
| 185 | <title>close()</title> | ||
| 186 | <para>DESCRIPTION | ||
| 187 | </para> | ||
| 188 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 189 | align="char"> | ||
| 190 | <para>This system call closes a previously opened audio device.</para> | ||
| 191 | </entry> | ||
| 192 | </row></tbody></tgroup></informaltable> | ||
| 193 | <para>SYNOPSIS | ||
| 194 | </para> | ||
| 195 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 196 | align="char"> | ||
| 197 | <para>int close(int fd);</para> | ||
| 198 | </entry> | ||
| 199 | </row></tbody></tgroup></informaltable> | ||
| 200 | <para>PARAMETERS | ||
| 201 | </para> | ||
| 202 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 203 | align="char"> | ||
| 204 | <para>int fd</para> | ||
| 205 | </entry><entry | ||
| 206 | align="char"> | ||
| 207 | <para>File descriptor returned by a previous call to open().</para> | ||
| 208 | </entry> | ||
| 209 | </row></tbody></tgroup></informaltable> | ||
| 210 | <para>ERRORS | ||
| 211 | </para> | ||
| 212 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 213 | align="char"> | ||
| 214 | <para>EBADF</para> | ||
| 215 | </entry><entry | ||
| 216 | align="char"> | ||
| 217 | <para>fd is not a valid open file descriptor.</para> | ||
| 218 | </entry> | ||
| 219 | </row></tbody></tgroup></informaltable> | ||
| 220 | </section> | ||
| 221 | </section> | ||
diff --git a/Documentation/DocBook/dvb/demux.xml b/Documentation/DocBook/dvb/demux.xml new file mode 100644 index 000000000000..1b8c4e9835b9 --- /dev/null +++ b/Documentation/DocBook/dvb/demux.xml | |||
| @@ -0,0 +1,973 @@ | |||
| 1 | <title>DVB Demux Device</title> | ||
| 2 | |||
| 3 | <para>The DVB demux device controls the filters of the DVB hardware/software. It can be | ||
| 4 | accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be | ||
| 5 | accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application. | ||
| 6 | </para> | ||
| 7 | <section id="dmx_types"> | ||
| 8 | <title>Demux Data Types</title> | ||
| 9 | |||
| 10 | <section id="dmx_output_t"> | ||
| 11 | <title>dmx_output_t</title> | ||
| 12 | <programlisting> | ||
| 13 | typedef enum | ||
| 14 | { | ||
| 15 | DMX_OUT_DECODER, | ||
| 16 | DMX_OUT_TAP, | ||
| 17 | DMX_OUT_TS_TAP | ||
| 18 | } dmx_output_t; | ||
| 19 | </programlisting> | ||
| 20 | <para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is | ||
| 21 | called. | ||
| 22 | </para> | ||
| 23 | <para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>, | ||
| 24 | which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was | ||
| 25 | specified. | ||
| 26 | </para> | ||
| 27 | </section> | ||
| 28 | |||
| 29 | <section id="dmx_input_t"> | ||
| 30 | <title>dmx_input_t</title> | ||
| 31 | <programlisting> | ||
| 32 | typedef enum | ||
| 33 | { | ||
| 34 | DMX_IN_FRONTEND, | ||
| 35 | DMX_IN_DVR | ||
| 36 | } dmx_input_t; | ||
| 37 | </programlisting> | ||
| 38 | </section> | ||
| 39 | |||
| 40 | <section id="dmx_pes_type_t"> | ||
| 41 | <title>dmx_pes_type_t</title> | ||
| 42 | <programlisting> | ||
| 43 | typedef enum | ||
| 44 | { | ||
| 45 | DMX_PES_AUDIO, | ||
| 46 | DMX_PES_VIDEO, | ||
| 47 | DMX_PES_TELETEXT, | ||
| 48 | DMX_PES_SUBTITLE, | ||
| 49 | DMX_PES_PCR, | ||
| 50 | DMX_PES_OTHER | ||
| 51 | } dmx_pes_type_t; | ||
| 52 | </programlisting> | ||
| 53 | </section> | ||
| 54 | |||
| 55 | <section id="dmx_event_t"> | ||
| 56 | <title>dmx_event_t</title> | ||
| 57 | <programlisting> | ||
| 58 | typedef enum | ||
| 59 | { | ||
| 60 | DMX_SCRAMBLING_EV, | ||
| 61 | DMX_FRONTEND_EV | ||
| 62 | } dmx_event_t; | ||
| 63 | </programlisting> | ||
| 64 | </section> | ||
| 65 | |||
| 66 | <section id="dmx_scrambling_status_t"> | ||
| 67 | <title>dmx_scrambling_status_t</title> | ||
| 68 | <programlisting> | ||
| 69 | typedef enum | ||
| 70 | { | ||
| 71 | DMX_SCRAMBLING_OFF, | ||
| 72 | DMX_SCRAMBLING_ON | ||
| 73 | } dmx_scrambling_status_t; | ||
| 74 | </programlisting> | ||
| 75 | </section> | ||
| 76 | |||
| 77 | <section id="dmx_filter"> | ||
| 78 | <title>struct dmx_filter</title> | ||
| 79 | <programlisting> | ||
| 80 | typedef struct dmx_filter | ||
| 81 | { | ||
| 82 | uint8_t filter[DMX_FILTER_SIZE]; | ||
| 83 | uint8_t mask[DMX_FILTER_SIZE]; | ||
| 84 | } dmx_filter_t; | ||
| 85 | </programlisting> | ||
| 86 | </section> | ||
| 87 | |||
| 88 | <section id="dmx_sct_filter_params"> | ||
| 89 | <title>struct dmx_sct_filter_params</title> | ||
| 90 | <programlisting> | ||
| 91 | struct dmx_sct_filter_params | ||
| 92 | { | ||
| 93 | uint16_t pid; | ||
| 94 | dmx_filter_t filter; | ||
| 95 | uint32_t timeout; | ||
| 96 | uint32_t flags; | ||
| 97 | #define DMX_CHECK_CRC 1 | ||
| 98 | #define DMX_ONESHOT 2 | ||
| 99 | #define DMX_IMMEDIATE_START 4 | ||
| 100 | }; | ||
| 101 | </programlisting> | ||
| 102 | </section> | ||
| 103 | |||
| 104 | <section id="dmx_pes_filter_params"> | ||
| 105 | <title>struct dmx_pes_filter_params</title> | ||
| 106 | <programlisting> | ||
| 107 | struct dmx_pes_filter_params | ||
| 108 | { | ||
| 109 | uint16_t pid; | ||
| 110 | dmx_input_t input; | ||
| 111 | dmx_output_t output; | ||
| 112 | dmx_pes_type_t pes_type; | ||
| 113 | uint32_t flags; | ||
| 114 | }; | ||
| 115 | </programlisting> | ||
| 116 | </section> | ||
| 117 | |||
| 118 | <section id="dmx_event"> | ||
| 119 | <title>struct dmx_event</title> | ||
| 120 | <programlisting> | ||
| 121 | struct dmx_event | ||
| 122 | { | ||
| 123 | dmx_event_t event; | ||
| 124 | time_t timeStamp; | ||
| 125 | union | ||
| 126 | { | ||
| 127 | dmx_scrambling_status_t scrambling; | ||
| 128 | } u; | ||
| 129 | }; | ||
| 130 | </programlisting> | ||
| 131 | </section> | ||
| 132 | |||
| 133 | <section id="dmx_stc"> | ||
| 134 | <title>struct dmx_stc</title> | ||
| 135 | <programlisting> | ||
| 136 | struct dmx_stc { | ||
| 137 | unsigned int num; /⋆ input : which STC? 0..N ⋆/ | ||
| 138 | unsigned int base; /⋆ output: divisor for stc to get 90 kHz clock ⋆/ | ||
| 139 | uint64_t stc; /⋆ output: stc in 'base'⋆90 kHz units ⋆/ | ||
| 140 | }; | ||
| 141 | </programlisting> | ||
| 142 | </section> | ||
| 143 | |||
| 144 | </section> | ||
| 145 | |||
| 146 | <section id="dmx_fcalls"> | ||
| 147 | <title>Demux Function Calls</title> | ||
| 148 | |||
| 149 | <section id="dmx_fopen"> | ||
| 150 | <title>open()</title> | ||
| 151 | <para>DESCRIPTION | ||
| 152 | </para> | ||
| 153 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 154 | align="char"> | ||
| 155 | <para>This system call, used with a device name of /dev/dvb/adapter0/demux0, | ||
| 156 | allocates a new filter and returns a handle which can be used for subsequent | ||
| 157 | control of that filter. This call has to be made for each filter to be used, i.e. every | ||
| 158 | returned file descriptor is a reference to a single filter. /dev/dvb/adapter0/dvr0 | ||
| 159 | is a logical device to be used for retrieving Transport Streams for digital | ||
| 160 | video recording. When reading from this device a transport stream containing | ||
| 161 | the packets from all PES filters set in the corresponding demux device | ||
| 162 | (/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A | ||
| 163 | recorded Transport Stream is replayed by writing to this device. </para> | ||
| 164 | <para>The significance of blocking or non-blocking mode is described in the | ||
| 165 | documentation for functions where there is a difference. It does not affect the | ||
| 166 | semantics of the open() call itself. A device opened in blocking mode can later | ||
| 167 | be put into non-blocking mode (and vice versa) using the F_SETFL command | ||
| 168 | of the fcntl system call.</para> | ||
| 169 | </entry> | ||
| 170 | </row></tbody></tgroup></informaltable> | ||
| 171 | <para>SYNOPSIS | ||
| 172 | </para> | ||
| 173 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 174 | align="char"> | ||
| 175 | <para>int open(const char ⋆deviceName, int flags);</para> | ||
| 176 | </entry> | ||
| 177 | </row></tbody></tgroup></informaltable> | ||
| 178 | <para>PARAMETERS | ||
| 179 | </para> | ||
| 180 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 181 | align="char"> | ||
| 182 | <para>const char | ||
| 183 | *deviceName</para> | ||
| 184 | </entry><entry | ||
| 185 | align="char"> | ||
| 186 | <para>Name of demux device.</para> | ||
| 187 | </entry> | ||
| 188 | </row><row><entry | ||
| 189 | align="char"> | ||
| 190 | <para>int flags</para> | ||
| 191 | </entry><entry | ||
| 192 | align="char"> | ||
| 193 | <para>A bit-wise OR of the following flags:</para> | ||
| 194 | </entry> | ||
| 195 | </row><row><entry | ||
| 196 | align="char"> | ||
| 197 | </entry><entry | ||
| 198 | align="char"> | ||
| 199 | <para>O_RDWR read/write access</para> | ||
| 200 | </entry> | ||
| 201 | </row><row><entry | ||
| 202 | align="char"> | ||
| 203 | </entry><entry | ||
| 204 | align="char"> | ||
| 205 | <para>O_NONBLOCK open in non-blocking mode</para> | ||
| 206 | </entry> | ||
| 207 | </row><row><entry | ||
| 208 | align="char"> | ||
| 209 | </entry><entry | ||
| 210 | align="char"> | ||
| 211 | <para>(blocking mode is the default)</para> | ||
| 212 | </entry> | ||
| 213 | </row></tbody></tgroup></informaltable> | ||
| 214 | <para>ERRORS | ||
| 215 | </para> | ||
| 216 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 217 | align="char"> | ||
| 218 | <para>ENODEV</para> | ||
| 219 | </entry><entry | ||
| 220 | align="char"> | ||
| 221 | <para>Device driver not loaded/available.</para> | ||
| 222 | </entry> | ||
| 223 | </row><row><entry | ||
| 224 | align="char"> | ||
| 225 | <para>EINVAL</para> | ||
| 226 | </entry><entry | ||
| 227 | align="char"> | ||
| 228 | <para>Invalid argument.</para> | ||
| 229 | </entry> | ||
| 230 | </row><row><entry | ||
| 231 | align="char"> | ||
| 232 | <para>EMFILE</para> | ||
| 233 | </entry><entry | ||
| 234 | align="char"> | ||
| 235 | <para>“Too many open files”, i.e. no more filters available.</para> | ||
| 236 | </entry> | ||
| 237 | </row><row><entry | ||
| 238 | align="char"> | ||
| 239 | <para>ENOMEM</para> | ||
| 240 | </entry><entry | ||
| 241 | align="char"> | ||
| 242 | <para>The driver failed to allocate enough memory.</para> | ||
| 243 | </entry> | ||
| 244 | </row></tbody></tgroup></informaltable> | ||
| 245 | </section> | ||
| 246 | |||
| 247 | <section id="dmx_fclose"> | ||
| 248 | <title>close()</title> | ||
| 249 | <para>DESCRIPTION | ||
| 250 | </para> | ||
| 251 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 252 | align="char"> | ||
| 253 | <para>This system call deactivates and deallocates a filter that was previously | ||
| 254 | allocated via the open() call.</para> | ||
| 255 | </entry> | ||
| 256 | </row></tbody></tgroup></informaltable> | ||
| 257 | <para>SYNOPSIS | ||
| 258 | </para> | ||
| 259 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 260 | align="char"> | ||
| 261 | <para>int close(int fd);</para> | ||
| 262 | </entry> | ||
| 263 | </row></tbody></tgroup></informaltable> | ||
| 264 | <para>PARAMETERS | ||
| 265 | </para> | ||
| 266 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 267 | align="char"> | ||
| 268 | <para>int fd</para> | ||
| 269 | </entry><entry | ||
| 270 | align="char"> | ||
| 271 | <para>File descriptor returned by a previous call to open().</para> | ||
| 272 | </entry> | ||
| 273 | </row></tbody></tgroup></informaltable> | ||
| 274 | <para>ERRORS | ||
| 275 | </para> | ||
| 276 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 277 | align="char"> | ||
| 278 | <para>EBADF</para> | ||
| 279 | </entry><entry | ||
| 280 | align="char"> | ||
| 281 | <para>fd is not a valid open file descriptor.</para> | ||
| 282 | </entry> | ||
| 283 | </row></tbody></tgroup></informaltable> | ||
| 284 | </section> | ||
| 285 | |||
| 286 | <section id="dmx_fread"> | ||
| 287 | <title>read()</title> | ||
| 288 | <para>DESCRIPTION | ||
| 289 | </para> | ||
| 290 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 291 | align="char"> | ||
| 292 | <para>This system call returns filtered data, which might be section or PES data. The | ||
| 293 | filtered data is transferred from the driver’s internal circular buffer to buf. The | ||
| 294 | maximum amount of data to be transferred is implied by count.</para> | ||
| 295 | </entry> | ||
| 296 | </row><row><entry | ||
| 297 | align="char"> | ||
| 298 | <para>When returning section data the driver always tries to return a complete single | ||
| 299 | section (even though buf would provide buffer space for more data). If the size | ||
| 300 | of the buffer is smaller than the section as much as possible will be returned, | ||
| 301 | and the remaining data will be provided in subsequent calls.</para> | ||
| 302 | </entry> | ||
| 303 | </row><row><entry | ||
| 304 | align="char"> | ||
| 305 | <para>The size of the internal buffer is 2 * 4096 bytes (the size of two maximum | ||
| 306 | sized sections) by default. The size of this buffer may be changed by using the | ||
| 307 | DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, or if | ||
| 308 | the read operations are not performed fast enough, this may result in a buffer | ||
| 309 | overflow error. In this case EOVERFLOW will be returned, and the circular | ||
| 310 | buffer will be emptied. This call is blocking if there is no data to return, i.e. the | ||
| 311 | process will be put to sleep waiting for data, unless the O_NONBLOCK flag | ||
| 312 | is specified.</para> | ||
| 313 | </entry> | ||
| 314 | </row><row><entry | ||
| 315 | align="char"> | ||
| 316 | <para>Note that in order to be able to read, the filtering process has to be started | ||
| 317 | by defining either a section or a PES filter by means of the ioctl functions, | ||
| 318 | and then starting the filtering process via the DMX_START ioctl function | ||
| 319 | or by setting the DMX_IMMEDIATE_START flag. If the reading is done | ||
| 320 | from a logical DVR demux device, the data will constitute a Transport Stream | ||
| 321 | including the packets from all PES filters in the corresponding demux device | ||
| 322 | /dev/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para> | ||
| 323 | </entry> | ||
| 324 | </row></tbody></tgroup></informaltable> | ||
| 325 | <para>SYNOPSIS | ||
| 326 | </para> | ||
| 327 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 328 | align="char"> | ||
| 329 | <para>size_t read(int fd, void ⋆buf, size_t count);</para> | ||
| 330 | </entry> | ||
| 331 | </row></tbody></tgroup></informaltable> | ||
| 332 | <para>PARAMETERS | ||
| 333 | </para> | ||
| 334 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 335 | align="char"> | ||
| 336 | <para>int fd</para> | ||
| 337 | </entry><entry | ||
| 338 | align="char"> | ||
| 339 | <para>File descriptor returned by a previous call to open().</para> | ||
| 340 | </entry> | ||
| 341 | </row><row><entry | ||
| 342 | align="char"> | ||
| 343 | <para>void *buf</para> | ||
| 344 | </entry><entry | ||
| 345 | align="char"> | ||
| 346 | <para>Pointer to the buffer to be used for returned filtered data.</para> | ||
| 347 | </entry> | ||
| 348 | </row><row><entry | ||
| 349 | align="char"> | ||
| 350 | <para>size_t count</para> | ||
| 351 | </entry><entry | ||
| 352 | align="char"> | ||
| 353 | <para>Size of buf.</para> | ||
| 354 | </entry> | ||
| 355 | </row></tbody></tgroup></informaltable> | ||
| 356 | <para>ERRORS | ||
| 357 | </para> | ||
| 358 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 359 | align="char"> | ||
| 360 | <para>EWOULDBLOCK</para> | ||
| 361 | </entry><entry | ||
| 362 | align="char"> | ||
| 363 | <para>No data to return and O_NONBLOCK was specified.</para> | ||
| 364 | </entry> | ||
| 365 | </row><row><entry | ||
| 366 | align="char"> | ||
| 367 | <para>EBADF</para> | ||
| 368 | </entry><entry | ||
| 369 | align="char"> | ||
| 370 | <para>fd is not a valid open file descriptor.</para> | ||
| 371 | </entry> | ||
| 372 | </row><row><entry | ||
| 373 | align="char"> | ||
| 374 | <para>ECRC</para> | ||
| 375 | </entry><entry | ||
| 376 | align="char"> | ||
| 377 | <para>Last section had a CRC error - no data returned. The | ||
| 378 | buffer is flushed.</para> | ||
| 379 | </entry> | ||
| 380 | </row><row><entry | ||
| 381 | align="char"> | ||
| 382 | <para>EOVERFLOW</para> | ||
| 383 | </entry><entry | ||
| 384 | align="char"> | ||
| 385 | </entry> | ||
| 386 | </row><row><entry | ||
| 387 | align="char"> | ||
| 388 | </entry><entry | ||
| 389 | align="char"> | ||
| 390 | <para>The filtered data was not read from the buffer in due | ||
| 391 | time, resulting in non-read data being lost. The buffer is | ||
| 392 | flushed.</para> | ||
| 393 | </entry> | ||
| 394 | </row><row><entry | ||
| 395 | align="char"> | ||
| 396 | <para>ETIMEDOUT</para> | ||
| 397 | </entry><entry | ||
| 398 | align="char"> | ||
| 399 | <para>The section was not loaded within the stated timeout | ||
| 400 | period. See ioctl DMX_SET_FILTER for how to set a | ||
| 401 | timeout.</para> | ||
| 402 | </entry> | ||
| 403 | </row><row><entry | ||
| 404 | align="char"> | ||
| 405 | <para>EFAULT</para> | ||
| 406 | </entry><entry | ||
| 407 | align="char"> | ||
| 408 | <para>The driver failed to write to the callers buffer due to an | ||
| 409 | invalid *buf pointer.</para> | ||
| 410 | </entry> | ||
| 411 | </row></tbody></tgroup></informaltable> | ||
| 412 | </section> | ||
| 413 | |||
| 414 | <section id="dmx_fwrite"> | ||
| 415 | <title>write()</title> | ||
| 416 | <para>DESCRIPTION | ||
| 417 | </para> | ||
| 418 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 419 | align="char"> | ||
| 420 | <para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0, | ||
| 421 | associated with the physical demux device that provides the actual DVR | ||
| 422 | functionality. It is used for replay of a digitally recorded Transport Stream. | ||
| 423 | Matching filters have to be defined in the corresponding physical demux | ||
| 424 | device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is | ||
| 425 | implied by count.</para> | ||
| 426 | </entry> | ||
| 427 | </row></tbody></tgroup></informaltable> | ||
| 428 | <para>SYNOPSIS | ||
| 429 | </para> | ||
| 430 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 431 | align="char"> | ||
| 432 | <para>ssize_t write(int fd, const void ⋆buf, size_t | ||
| 433 | count);</para> | ||
| 434 | </entry> | ||
| 435 | </row></tbody></tgroup></informaltable> | ||
| 436 | <para>PARAMETERS | ||
| 437 | </para> | ||
| 438 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 439 | align="char"> | ||
| 440 | <para>int fd</para> | ||
| 441 | </entry><entry | ||
| 442 | align="char"> | ||
| 443 | <para>File descriptor returned by a previous call to open().</para> | ||
| 444 | </entry> | ||
| 445 | </row><row><entry | ||
| 446 | align="char"> | ||
| 447 | <para>void *buf</para> | ||
| 448 | </entry><entry | ||
| 449 | align="char"> | ||
| 450 | <para>Pointer to the buffer containing the Transport Stream.</para> | ||
| 451 | </entry> | ||
| 452 | </row><row><entry | ||
| 453 | align="char"> | ||
| 454 | <para>size_t count</para> | ||
| 455 | </entry><entry | ||
| 456 | align="char"> | ||
| 457 | <para>Size of buf.</para> | ||
| 458 | </entry> | ||
| 459 | </row></tbody></tgroup></informaltable> | ||
| 460 | <para>ERRORS | ||
| 461 | </para> | ||
| 462 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 463 | align="char"> | ||
| 464 | <para>EWOULDBLOCK</para> | ||
| 465 | </entry><entry | ||
| 466 | align="char"> | ||
| 467 | <para>No data was written. This | ||
| 468 | might happen if O_NONBLOCK was specified and there | ||
| 469 | is no more buffer space available (if O_NONBLOCK is | ||
| 470 | not specified the function will block until buffer space is | ||
| 471 | available).</para> | ||
| 472 | </entry> | ||
| 473 | </row><row><entry | ||
| 474 | align="char"> | ||
| 475 | <para>EBUSY</para> | ||
| 476 | </entry><entry | ||
| 477 | align="char"> | ||
| 478 | <para>This error code indicates that there are conflicting | ||
| 479 | requests. The corresponding demux device is setup to | ||
| 480 | receive data from the front- end. Make sure that these | ||
| 481 | filters are stopped and that the filters with input set to | ||
| 482 | DMX_IN_DVR are started.</para> | ||
| 483 | </entry> | ||
| 484 | </row><row><entry | ||
| 485 | align="char"> | ||
| 486 | <para>EBADF</para> | ||
| 487 | </entry><entry | ||
| 488 | align="char"> | ||
| 489 | <para>fd is not a valid open file descriptor.</para> | ||
| 490 | </entry> | ||
| 491 | </row></tbody></tgroup></informaltable> | ||
| 492 | </section> | ||
| 493 | |||
| 494 | <section id="dmx_start"> | ||
| 495 | <title>DMX_START</title> | ||
| 496 | <para>DESCRIPTION | ||
| 497 | </para> | ||
| 498 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 499 | align="char"> | ||
| 500 | <para>This ioctl call is used to start the actual filtering operation defined via the ioctl | ||
| 501 | calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para> | ||
| 502 | </entry> | ||
| 503 | </row></tbody></tgroup></informaltable> | ||
| 504 | <para>SYNOPSIS | ||
| 505 | </para> | ||
| 506 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 507 | align="char"> | ||
| 508 | <para>int ioctl( int fd, int request = DMX_START);</para> | ||
| 509 | </entry> | ||
| 510 | </row></tbody></tgroup></informaltable> | ||
| 511 | <para>PARAMETERS | ||
| 512 | </para> | ||
| 513 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 514 | align="char"> | ||
| 515 | <para>int fd</para> | ||
| 516 | </entry><entry | ||
| 517 | align="char"> | ||
| 518 | <para>File descriptor returned by a previous call to open().</para> | ||
| 519 | </entry> | ||
| 520 | </row><row><entry | ||
| 521 | align="char"> | ||
| 522 | <para>int request</para> | ||
| 523 | </entry><entry | ||
| 524 | align="char"> | ||
| 525 | <para>Equals DMX_START for this command.</para> | ||
| 526 | </entry> | ||
| 527 | </row></tbody></tgroup></informaltable> | ||
| 528 | <para>ERRORS | ||
| 529 | </para> | ||
| 530 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 531 | align="char"> | ||
| 532 | <para>EBADF</para> | ||
| 533 | </entry><entry | ||
| 534 | align="char"> | ||
| 535 | <para>fd is not a valid file descriptor.</para> | ||
| 536 | </entry> | ||
| 537 | </row><row><entry | ||
| 538 | align="char"> | ||
| 539 | <para>EINVAL</para> | ||
| 540 | </entry><entry | ||
| 541 | align="char"> | ||
| 542 | <para>Invalid argument, i.e. no filtering parameters provided via | ||
| 543 | the DMX_SET_FILTER or DMX_SET_PES_FILTER | ||
| 544 | functions.</para> | ||
| 545 | </entry> | ||
| 546 | </row><row><entry | ||
| 547 | align="char"> | ||
| 548 | <para>EBUSY</para> | ||
| 549 | </entry><entry | ||
| 550 | align="char"> | ||
| 551 | <para>This error code indicates that there are conflicting | ||
| 552 | requests. There are active filters filtering data from | ||
| 553 | another input source. Make sure that these filters are | ||
| 554 | stopped before starting this filter.</para> | ||
| 555 | </entry> | ||
| 556 | </row></tbody></tgroup></informaltable> | ||
| 557 | </section> | ||
| 558 | |||
| 559 | <section id="dmx_stop"> | ||
| 560 | <title>DMX_STOP</title> | ||
| 561 | <para>DESCRIPTION | ||
| 562 | </para> | ||
| 563 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 564 | align="char"> | ||
| 565 | <para>This ioctl call is used to stop the actual filtering operation defined via the | ||
| 566 | ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via | ||
| 567 | the DMX_START command.</para> | ||
| 568 | </entry> | ||
| 569 | </row></tbody></tgroup></informaltable> | ||
| 570 | <para>SYNOPSIS | ||
| 571 | </para> | ||
| 572 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 573 | align="char"> | ||
| 574 | <para>int ioctl( int fd, int request = DMX_STOP);</para> | ||
| 575 | </entry> | ||
| 576 | </row></tbody></tgroup></informaltable> | ||
| 577 | <para>PARAMETERS | ||
| 578 | </para> | ||
| 579 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 580 | align="char"> | ||
| 581 | <para>int fd</para> | ||
| 582 | </entry><entry | ||
| 583 | align="char"> | ||
| 584 | <para>File descriptor returned by a previous call to open().</para> | ||
| 585 | </entry> | ||
| 586 | </row><row><entry | ||
| 587 | align="char"> | ||
| 588 | <para>int request</para> | ||
| 589 | </entry><entry | ||
| 590 | align="char"> | ||
| 591 | <para>Equals DMX_STOP for this command.</para> | ||
| 592 | </entry> | ||
| 593 | </row></tbody></tgroup></informaltable> | ||
| 594 | <para>ERRORS | ||
| 595 | </para> | ||
| 596 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 597 | align="char"> | ||
| 598 | <para>EBADF</para> | ||
| 599 | </entry><entry | ||
| 600 | align="char"> | ||
| 601 | <para>fd is not a valid file descriptor.</para> | ||
| 602 | </entry> | ||
| 603 | </row></tbody></tgroup></informaltable> | ||
| 604 | </section> | ||
| 605 | |||
| 606 | <section id="dmx_set_filter"> | ||
| 607 | <title>DMX_SET_FILTER</title> | ||
| 608 | <para>DESCRIPTION | ||
| 609 | </para> | ||
| 610 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 611 | align="char"> | ||
| 612 | <para>This ioctl call sets up a filter according to the filter and mask parameters | ||
| 613 | provided. A timeout may be defined stating number of seconds to wait for a | ||
| 614 | section to be loaded. A value of 0 means that no timeout should be applied. | ||
| 615 | Finally there is a flag field where it is possible to state whether a section should | ||
| 616 | be CRC-checked, whether the filter should be a ”one-shot” filter, i.e. if the | ||
| 617 | filtering operation should be stopped after the first section is received, and | ||
| 618 | whether the filtering operation should be started immediately (without waiting | ||
| 619 | for a DMX_START ioctl call). If a filter was previously set-up, this filter will | ||
| 620 | be canceled, and the receive buffer will be flushed.</para> | ||
| 621 | </entry> | ||
| 622 | </row></tbody></tgroup></informaltable> | ||
| 623 | <para>SYNOPSIS | ||
| 624 | </para> | ||
| 625 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 626 | align="char"> | ||
| 627 | <para>int ioctl( int fd, int request = DMX_SET_FILTER, | ||
| 628 | struct dmx_sct_filter_params ⋆params);</para> | ||
| 629 | </entry> | ||
| 630 | </row></tbody></tgroup></informaltable> | ||
| 631 | <para>PARAMETERS | ||
| 632 | </para> | ||
| 633 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 634 | align="char"> | ||
| 635 | <para>int fd</para> | ||
| 636 | </entry><entry | ||
| 637 | align="char"> | ||
| 638 | <para>File descriptor returned by a previous call to open().</para> | ||
| 639 | </entry> | ||
| 640 | </row><row><entry | ||
| 641 | align="char"> | ||
| 642 | <para>int request</para> | ||
| 643 | </entry><entry | ||
| 644 | align="char"> | ||
| 645 | <para>Equals DMX_SET_FILTER for this command.</para> | ||
| 646 | </entry> | ||
| 647 | </row><row><entry | ||
| 648 | align="char"> | ||
| 649 | <para>struct | ||
| 650 | dmx_sct_filter_params | ||
| 651 | *params</para> | ||
| 652 | </entry><entry | ||
| 653 | align="char"> | ||
| 654 | <para>Pointer to structure containing filter parameters.</para> | ||
| 655 | </entry> | ||
| 656 | </row></tbody></tgroup></informaltable> | ||
| 657 | <para>ERRORS | ||
| 658 | </para> | ||
| 659 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 660 | align="char"> | ||
| 661 | <para>EBADF</para> | ||
| 662 | </entry><entry | ||
| 663 | align="char"> | ||
| 664 | <para>fd is not a valid file descriptor.</para> | ||
| 665 | </entry> | ||
| 666 | </row><row><entry | ||
| 667 | align="char"> | ||
| 668 | <para>EINVAL</para> | ||
| 669 | </entry><entry | ||
| 670 | align="char"> | ||
| 671 | <para>Invalid argument.</para> | ||
| 672 | </entry> | ||
| 673 | </row></tbody></tgroup></informaltable> | ||
| 674 | </section> | ||
| 675 | |||
| 676 | <section id="dmx_set_pes_filter"> | ||
| 677 | <title>DMX_SET_PES_FILTER</title> | ||
| 678 | <para>DESCRIPTION | ||
| 679 | </para> | ||
| 680 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 681 | align="char"> | ||
| 682 | <para>This ioctl call sets up a PES filter according to the parameters provided. By a | ||
| 683 | PES filter is meant a filter that is based just on the packet identifier (PID), i.e. | ||
| 684 | no PES header or payload filtering capability is supported.</para> | ||
| 685 | </entry> | ||
| 686 | </row><row><entry | ||
| 687 | align="char"> | ||
| 688 | <para>The transport stream destination for the filtered output may be set. Also the | ||
| 689 | PES type may be stated in order to be able to e.g. direct a video stream directly | ||
| 690 | to the video decoder. Finally there is a flag field where it is possible to state | ||
| 691 | whether the filtering operation should be started immediately (without waiting | ||
| 692 | for a DMX_START ioctl call). If a filter was previously set-up, this filter will | ||
| 693 | be cancelled, and the receive buffer will be flushed.</para> | ||
| 694 | </entry> | ||
| 695 | </row></tbody></tgroup></informaltable> | ||
| 696 | <para>SYNOPSIS | ||
| 697 | </para> | ||
| 698 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 699 | align="char"> | ||
| 700 | <para>int ioctl( int fd, int request = DMX_SET_PES_FILTER, | ||
| 701 | struct dmx_pes_filter_params ⋆params);</para> | ||
| 702 | </entry> | ||
| 703 | </row></tbody></tgroup></informaltable> | ||
| 704 | <para>PARAMETERS | ||
| 705 | </para> | ||
| 706 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 707 | align="char"> | ||
| 708 | <para>int fd</para> | ||
| 709 | </entry><entry | ||
| 710 | align="char"> | ||
| 711 | <para>File descriptor returned by a previous call to open().</para> | ||
| 712 | </entry> | ||
| 713 | </row><row><entry | ||
| 714 | align="char"> | ||
| 715 | <para>int request</para> | ||
| 716 | </entry><entry | ||
| 717 | align="char"> | ||
| 718 | <para>Equals DMX_SET_PES_FILTER for this command.</para> | ||
| 719 | </entry> | ||
| 720 | </row><row><entry | ||
| 721 | align="char"> | ||
| 722 | <para>struct | ||
| 723 | dmx_pes_filter_params | ||
| 724 | *params</para> | ||
| 725 | </entry><entry | ||
| 726 | align="char"> | ||
| 727 | <para>Pointer to structure containing filter parameters.</para> | ||
| 728 | </entry> | ||
| 729 | </row></tbody></tgroup></informaltable> | ||
| 730 | <para>ERRORS | ||
| 731 | </para> | ||
| 732 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 733 | align="char"> | ||
| 734 | <para>EBADF</para> | ||
| 735 | </entry><entry | ||
| 736 | align="char"> | ||
| 737 | <para>fd is not a valid file descriptor.</para> | ||
| 738 | </entry> | ||
| 739 | </row><row><entry | ||
| 740 | align="char"> | ||
| 741 | <para>EINVAL</para> | ||
| 742 | </entry><entry | ||
| 743 | align="char"> | ||
| 744 | <para>Invalid argument.</para> | ||
| 745 | </entry> | ||
| 746 | </row><row><entry | ||
| 747 | align="char"> | ||
| 748 | <para>EBUSY</para> | ||
| 749 | </entry><entry | ||
| 750 | align="char"> | ||
| 751 | <para>This error code indicates that there are conflicting | ||
| 752 | requests. There are active filters filtering data from | ||
| 753 | another input source. Make sure that these filters are | ||
| 754 | stopped before starting this filter.</para> | ||
| 755 | </entry> | ||
| 756 | </row></tbody></tgroup></informaltable> | ||
| 757 | </section> | ||
| 758 | |||
| 759 | <section id="dms_set_buffer_size"> | ||
| 760 | <title>DMX_SET_BUFFER_SIZE</title> | ||
| 761 | <para>DESCRIPTION | ||
| 762 | </para> | ||
| 763 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 764 | align="char"> | ||
| 765 | <para>This ioctl call is used to set the size of the circular buffer used for filtered data. | ||
| 766 | The default size is two maximum sized sections, i.e. if this function is not called | ||
| 767 | a buffer size of 2 * 4096 bytes will be used.</para> | ||
| 768 | </entry> | ||
| 769 | </row></tbody></tgroup></informaltable> | ||
| 770 | <para>SYNOPSIS | ||
| 771 | </para> | ||
| 772 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 773 | align="char"> | ||
| 774 | <para>int ioctl( int fd, int request = | ||
| 775 | DMX_SET_BUFFER_SIZE, unsigned long size);</para> | ||
| 776 | </entry> | ||
| 777 | </row></tbody></tgroup></informaltable> | ||
| 778 | <para>PARAMETERS | ||
| 779 | </para> | ||
| 780 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 781 | align="char"> | ||
| 782 | <para>int fd</para> | ||
| 783 | </entry><entry | ||
| 784 | align="char"> | ||
| 785 | <para>File descriptor returned by a previous call to open().</para> | ||
| 786 | </entry> | ||
| 787 | </row><row><entry | ||
| 788 | align="char"> | ||
| 789 | <para>int request</para> | ||
| 790 | </entry><entry | ||
| 791 | align="char"> | ||
| 792 | <para>Equals DMX_SET_BUFFER_SIZE for this command.</para> | ||
| 793 | </entry> | ||
| 794 | </row><row><entry | ||
| 795 | align="char"> | ||
| 796 | <para>unsigned long size</para> | ||
| 797 | </entry><entry | ||
| 798 | align="char"> | ||
| 799 | <para>Size of circular buffer.</para> | ||
| 800 | </entry> | ||
| 801 | </row></tbody></tgroup></informaltable> | ||
| 802 | <para>ERRORS | ||
| 803 | </para> | ||
| 804 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 805 | align="char"> | ||
| 806 | <para>EBADF</para> | ||
| 807 | </entry><entry | ||
| 808 | align="char"> | ||
| 809 | <para>fd is not a valid file descriptor.</para> | ||
| 810 | </entry> | ||
| 811 | </row><row><entry | ||
| 812 | align="char"> | ||
| 813 | <para>ENOMEM</para> | ||
| 814 | </entry><entry | ||
| 815 | align="char"> | ||
| 816 | <para>The driver was not able to allocate a buffer of the | ||
| 817 | requested size.</para> | ||
| 818 | </entry> | ||
| 819 | </row></tbody></tgroup></informaltable> | ||
| 820 | </section> | ||
| 821 | |||
| 822 | <section id="dmx_get_event"> | ||
| 823 | <title>DMX_GET_EVENT</title> | ||
| 824 | <para>DESCRIPTION | ||
| 825 | </para> | ||
| 826 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 827 | align="char"> | ||
| 828 | <para>This ioctl call returns an event if available. If an event is not available, | ||
| 829 | the behavior depends on whether the device is in blocking or non-blocking | ||
| 830 | mode. In the latter case, the call fails immediately with errno set to | ||
| 831 | EWOULDBLOCK. In the former case, the call blocks until an event becomes | ||
| 832 | available.</para> | ||
| 833 | </entry> | ||
| 834 | </row><row><entry | ||
| 835 | align="char"> | ||
| 836 | <para>The standard Linux poll() and/or select() system calls can be used with the | ||
| 837 | device file descriptor to watch for new events. For select(), the file descriptor | ||
| 838 | should be included in the exceptfds argument, and for poll(), POLLPRI should | ||
| 839 | be specified as the wake-up condition. Only the latest event for each filter is | ||
| 840 | saved.</para> | ||
| 841 | </entry> | ||
| 842 | </row></tbody></tgroup></informaltable> | ||
| 843 | <para>SYNOPSIS | ||
| 844 | </para> | ||
| 845 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 846 | align="char"> | ||
| 847 | <para>int ioctl( int fd, int request = DMX_GET_EVENT, | ||
| 848 | struct dmx_event ⋆ev);</para> | ||
| 849 | </entry> | ||
| 850 | </row></tbody></tgroup></informaltable> | ||
| 851 | <para>PARAMETERS | ||
| 852 | </para> | ||
| 853 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 854 | align="char"> | ||
| 855 | <para>int fd</para> | ||
| 856 | </entry><entry | ||
| 857 | align="char"> | ||
| 858 | <para>File descriptor returned by a previous call to open().</para> | ||
| 859 | </entry> | ||
| 860 | </row><row><entry | ||
| 861 | align="char"> | ||
| 862 | <para>int request</para> | ||
| 863 | </entry><entry | ||
| 864 | align="char"> | ||
| 865 | <para>Equals DMX_GET_EVENT for this command.</para> | ||
| 866 | </entry> | ||
| 867 | </row><row><entry | ||
| 868 | align="char"> | ||
| 869 | <para>struct dmx_event *ev</para> | ||
| 870 | </entry><entry | ||
| 871 | align="char"> | ||
| 872 | <para>Pointer to the location where the event is to be stored.</para> | ||
| 873 | </entry> | ||
| 874 | </row></tbody></tgroup></informaltable> | ||
| 875 | <para>ERRORS | ||
| 876 | </para> | ||
| 877 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 878 | align="char"> | ||
| 879 | <para>EBADF</para> | ||
| 880 | </entry><entry | ||
| 881 | align="char"> | ||
| 882 | <para>fd is not a valid file descriptor.</para> | ||
| 883 | </entry> | ||
| 884 | </row><row><entry | ||
| 885 | align="char"> | ||
| 886 | <para>EFAULT</para> | ||
| 887 | </entry><entry | ||
| 888 | align="char"> | ||
| 889 | <para>ev points to an invalid address.</para> | ||
| 890 | </entry> | ||
| 891 | </row><row><entry | ||
| 892 | align="char"> | ||
| 893 | <para>EWOULDBLOCK</para> | ||
| 894 | </entry><entry | ||
| 895 | align="char"> | ||
| 896 | <para>There is no event pending, and the device is in | ||
| 897 | non-blocking mode.</para> | ||
| 898 | </entry> | ||
| 899 | </row></tbody></tgroup></informaltable> | ||
| 900 | </section> | ||
| 901 | |||
| 902 | <section id="dmx_get_stc"> | ||
| 903 | <title>DMX_GET_STC</title> | ||
| 904 | <para>DESCRIPTION | ||
| 905 | </para> | ||
| 906 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 907 | align="char"> | ||
| 908 | <para>This ioctl call returns the current value of the system time counter (which is driven | ||
| 909 | by a PES filter of type DMX_PES_PCR). Some hardware supports more than one | ||
| 910 | STC, so you must specify which one by setting the num field of stc before the ioctl | ||
| 911 | (range 0...n). The result is returned in form of a ratio with a 64 bit numerator | ||
| 912 | and a 32 bit denominator, so the real 90kHz STC value is stc->stc / | ||
| 913 | stc->base | ||
| 914 | .</para> | ||
| 915 | </entry> | ||
| 916 | </row></tbody></tgroup></informaltable> | ||
| 917 | <para>SYNOPSIS | ||
| 918 | </para> | ||
| 919 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 920 | align="char"> | ||
| 921 | <para>int ioctl( int fd, int request = DMX_GET_STC, struct | ||
| 922 | dmx_stc ⋆stc);</para> | ||
| 923 | </entry> | ||
| 924 | </row></tbody></tgroup></informaltable> | ||
| 925 | <para>PARAMETERS | ||
| 926 | </para> | ||
| 927 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 928 | align="char"> | ||
| 929 | <para>int fd</para> | ||
| 930 | </entry><entry | ||
| 931 | align="char"> | ||
| 932 | <para>File descriptor returned by a previous call to open().</para> | ||
| 933 | </entry> | ||
| 934 | </row><row><entry | ||
| 935 | align="char"> | ||
| 936 | <para>int request</para> | ||
| 937 | </entry><entry | ||
| 938 | align="char"> | ||
| 939 | <para>Equals DMX_GET_STC for this command.</para> | ||
| 940 | </entry> | ||
| 941 | </row><row><entry | ||
| 942 | align="char"> | ||
| 943 | <para>struct dmx_stc *stc</para> | ||
| 944 | </entry><entry | ||
| 945 | align="char"> | ||
| 946 | <para>Pointer to the location where the stc is to be stored.</para> | ||
| 947 | </entry> | ||
| 948 | </row></tbody></tgroup></informaltable> | ||
| 949 | <para>ERRORS | ||
| 950 | </para> | ||
| 951 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 952 | align="char"> | ||
| 953 | <para>EBADF</para> | ||
| 954 | </entry><entry | ||
| 955 | align="char"> | ||
| 956 | <para>fd is not a valid file descriptor.</para> | ||
| 957 | </entry> | ||
| 958 | </row><row><entry | ||
| 959 | align="char"> | ||
| 960 | <para>EFAULT</para> | ||
| 961 | </entry><entry | ||
| 962 | align="char"> | ||
| 963 | <para>stc points to an invalid address.</para> | ||
| 964 | </entry> | ||
| 965 | </row><row><entry | ||
| 966 | align="char"> | ||
| 967 | <para>EINVAL</para> | ||
| 968 | </entry><entry | ||
| 969 | align="char"> | ||
| 970 | <para>Invalid stc number.</para> | ||
| 971 | </entry> | ||
| 972 | </row></tbody></tgroup></informaltable> | ||
| 973 | </section></section> | ||
diff --git a/Documentation/DocBook/dvb/dvbapi.xml b/Documentation/DocBook/dvb/dvbapi.xml new file mode 100644 index 000000000000..4fc5b23470a3 --- /dev/null +++ b/Documentation/DocBook/dvb/dvbapi.xml | |||
| @@ -0,0 +1,87 @@ | |||
| 1 | <partinfo> | ||
| 2 | <authorgroup> | ||
| 3 | <author> | ||
| 4 | <firstname>Ralph</firstname> | ||
| 5 | <surname>Metzler</surname> | ||
| 6 | <othername role="mi">J. K.</othername> | ||
| 7 | <affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> | ||
| 8 | </author> | ||
| 9 | <author> | ||
| 10 | <firstname>Marcus</firstname> | ||
| 11 | <surname>Metzler</surname> | ||
| 12 | <othername role="mi">O. C.</othername> | ||
| 13 | <affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> | ||
| 14 | </author> | ||
| 15 | <author> | ||
| 16 | <firstname>Mauro</firstname> | ||
| 17 | <surname>Chehab</surname> | ||
| 18 | <othername role="mi">Carvalho</othername> | ||
| 19 | <affiliation><address><email>mchehab@redhat.com</email></address></affiliation> | ||
| 20 | <contrib>Ported document to Docbook XML.</contrib> | ||
| 21 | </author> | ||
| 22 | </authorgroup> | ||
| 23 | <copyright> | ||
| 24 | <year>2002</year> | ||
| 25 | <year>2003</year> | ||
| 26 | <year>2009</year> | ||
| 27 | <holder>Convergence GmbH</holder> | ||
| 28 | </copyright> | ||
| 29 | |||
| 30 | <revhistory> | ||
| 31 | <!-- Put document revisions here, newest first. --> | ||
| 32 | <revision> | ||
| 33 | <revnumber>2.0.1</revnumber> | ||
| 34 | <date>2009-09-16</date> | ||
| 35 | <authorinitials>mcc</authorinitials> | ||
| 36 | <revremark> | ||
| 37 | Added ISDB-T test originally written by Patrick Boettcher | ||
| 38 | </revremark> | ||
| 39 | </revision> | ||
| 40 | <revision> | ||
| 41 | <revnumber>2.0.0</revnumber> | ||
| 42 | <date>2009-09-06</date> | ||
| 43 | <authorinitials>mcc</authorinitials> | ||
| 44 | <revremark>Conversion from LaTex to DocBook XML. The | ||
| 45 | contents is the same as the original LaTex version.</revremark> | ||
| 46 | </revision> | ||
| 47 | <revision> | ||
| 48 | <revnumber>1.0.0</revnumber> | ||
| 49 | <date>2003-07-24</date> | ||
| 50 | <authorinitials>rjkm</authorinitials> | ||
| 51 | <revremark>Initial revision on LaTEX.</revremark> | ||
| 52 | </revision> | ||
| 53 | </revhistory> | ||
| 54 | </partinfo> | ||
| 55 | |||
| 56 | |||
| 57 | <title>LINUX DVB API</title> | ||
| 58 | <subtitle>Version 3</subtitle> | ||
| 59 | <!-- ADD THE CHAPTERS HERE --> | ||
| 60 | <chapter id="dvb_introdution"> | ||
| 61 | &sub-intro; | ||
| 62 | </chapter> | ||
| 63 | <chapter id="dvb_frontend"> | ||
| 64 | &sub-frontend; | ||
| 65 | </chapter> | ||
| 66 | <chapter id="dvb_demux"> | ||
| 67 | &sub-demux; | ||
| 68 | </chapter> | ||
| 69 | <chapter id="dvb_video"> | ||
| 70 | &sub-video; | ||
| 71 | </chapter> | ||
| 72 | <chapter id="dvb_audio"> | ||
| 73 | &sub-audio; | ||
| 74 | </chapter> | ||
| 75 | <chapter id="dvb_ca"> | ||
| 76 | &sub-ca; | ||
| 77 | </chapter> | ||
| 78 | <chapter id="dvb_net"> | ||
| 79 | &sub-net; | ||
| 80 | </chapter> | ||
| 81 | <chapter id="dvb_kdapi"> | ||
| 82 | &sub-kdapi; | ||
| 83 | </chapter> | ||
| 84 | <chapter id="dvb_examples"> | ||
| 85 | &sub-examples; | ||
| 86 | </chapter> | ||
| 87 | <!-- END OF CHAPTERS --> | ||
diff --git a/Documentation/DocBook/dvb/dvbstb.pdf b/Documentation/DocBook/dvb/dvbstb.pdf new file mode 100644 index 000000000000..0fa75d90c3eb --- /dev/null +++ b/Documentation/DocBook/dvb/dvbstb.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/dvb/dvbstb.png b/Documentation/DocBook/dvb/dvbstb.png new file mode 100644 index 000000000000..9b8f372e7afd --- /dev/null +++ b/Documentation/DocBook/dvb/dvbstb.png | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/dvb/examples.xml b/Documentation/DocBook/dvb/examples.xml new file mode 100644 index 000000000000..f037e568eb6e --- /dev/null +++ b/Documentation/DocBook/dvb/examples.xml | |||
| @@ -0,0 +1,365 @@ | |||
| 1 | <title>Examples</title> | ||
| 2 | <para>In this section we would like to present some examples for using the DVB API. | ||
| 3 | </para> | ||
| 4 | <para>Maintainer note: This section is out of date. Please refer to the sample programs packaged | ||
| 5 | with the driver distribution from <ulink url="http://linuxtv.org/hg/dvb-apps" />. | ||
| 6 | </para> | ||
| 7 | |||
| 8 | <section id="tuning"> | ||
| 9 | <title>Tuning</title> | ||
| 10 | <para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as | ||
| 11 | the demux devices. The example is given for QPSK tuners, but can easily be adjusted for | ||
| 12 | QAM. | ||
| 13 | </para> | ||
| 14 | <programlisting> | ||
| 15 | #include <sys/ioctl.h> | ||
| 16 | #include <stdio.h> | ||
| 17 | #include <stdint.h> | ||
| 18 | #include <sys/types.h> | ||
| 19 | #include <sys/stat.h> | ||
| 20 | #include <fcntl.h> | ||
| 21 | #include <time.h> | ||
| 22 | #include <unistd.h> | ||
| 23 | |||
| 24 | #include <linux/dvb/dmx.h> | ||
| 25 | #include <linux/dvb/frontend.h> | ||
| 26 | #include <linux/dvb/sec.h> | ||
| 27 | #include <sys/poll.h> | ||
| 28 | |||
| 29 | #define DMX "/dev/dvb/adapter0/demux1" | ||
| 30 | #define FRONT "/dev/dvb/adapter0/frontend1" | ||
| 31 | #define SEC "/dev/dvb/adapter0/sec1" | ||
| 32 | |||
| 33 | /⋆ routine for checking if we have a signal and other status information⋆/ | ||
| 34 | int FEReadStatus(int fd, fe_status_t ⋆stat) | ||
| 35 | { | ||
| 36 | int ans; | ||
| 37 | |||
| 38 | if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ | ||
| 39 | perror("FE READ STATUS: "); | ||
| 40 | return -1; | ||
| 41 | } | ||
| 42 | |||
| 43 | if (⋆stat & FE_HAS_POWER) | ||
| 44 | printf("FE HAS POWER\n"); | ||
| 45 | |||
| 46 | if (⋆stat & FE_HAS_SIGNAL) | ||
| 47 | printf("FE HAS SIGNAL\n"); | ||
| 48 | |||
| 49 | if (⋆stat & FE_SPECTRUM_INV) | ||
| 50 | printf("SPEKTRUM INV\n"); | ||
| 51 | |||
| 52 | return 0; | ||
| 53 | } | ||
| 54 | |||
| 55 | |||
| 56 | /⋆ tune qpsk ⋆/ | ||
| 57 | /⋆ freq: frequency of transponder ⋆/ | ||
| 58 | /⋆ vpid, apid, tpid: PIDs of video, audio and teletext TS packets ⋆/ | ||
| 59 | /⋆ diseqc: DiSEqC address of the used LNB ⋆/ | ||
| 60 | /⋆ pol: Polarisation ⋆/ | ||
| 61 | /⋆ srate: Symbol Rate ⋆/ | ||
| 62 | /⋆ fec. FEC ⋆/ | ||
| 63 | /⋆ lnb_lof1: local frequency of lower LNB band ⋆/ | ||
| 64 | /⋆ lnb_lof2: local frequency of upper LNB band ⋆/ | ||
| 65 | /⋆ lnb_slof: switch frequency of LNB ⋆/ | ||
| 66 | |||
| 67 | int set_qpsk_channel(int freq, int vpid, int apid, int tpid, | ||
| 68 | int diseqc, int pol, int srate, int fec, int lnb_lof1, | ||
| 69 | int lnb_lof2, int lnb_slof) | ||
| 70 | { | ||
| 71 | struct secCommand scmd; | ||
| 72 | struct secCmdSequence scmds; | ||
| 73 | struct dmx_pes_filter_params pesFilterParams; | ||
| 74 | FrontendParameters frp; | ||
| 75 | struct pollfd pfd[1]; | ||
| 76 | FrontendEvent event; | ||
| 77 | int demux1, demux2, demux3, front; | ||
| 78 | |||
| 79 | frequency = (uint32_t) freq; | ||
| 80 | symbolrate = (uint32_t) srate; | ||
| 81 | |||
| 82 | if((front = open(FRONT,O_RDWR)) < 0){ | ||
| 83 | perror("FRONTEND DEVICE: "); | ||
| 84 | return -1; | ||
| 85 | } | ||
| 86 | |||
| 87 | if((sec = open(SEC,O_RDWR)) < 0){ | ||
| 88 | perror("SEC DEVICE: "); | ||
| 89 | return -1; | ||
| 90 | } | ||
| 91 | |||
| 92 | if (demux1 < 0){ | ||
| 93 | if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) | ||
| 94 | < 0){ | ||
| 95 | perror("DEMUX DEVICE: "); | ||
| 96 | return -1; | ||
| 97 | } | ||
| 98 | } | ||
| 99 | |||
| 100 | if (demux2 < 0){ | ||
| 101 | if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) | ||
| 102 | < 0){ | ||
| 103 | perror("DEMUX DEVICE: "); | ||
| 104 | return -1; | ||
| 105 | } | ||
| 106 | } | ||
| 107 | |||
| 108 | if (demux3 < 0){ | ||
| 109 | if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) | ||
| 110 | < 0){ | ||
| 111 | perror("DEMUX DEVICE: "); | ||
| 112 | return -1; | ||
| 113 | } | ||
| 114 | } | ||
| 115 | |||
| 116 | if (freq < lnb_slof) { | ||
| 117 | frp.Frequency = (freq - lnb_lof1); | ||
| 118 | scmds.continuousTone = SEC_TONE_OFF; | ||
| 119 | } else { | ||
| 120 | frp.Frequency = (freq - lnb_lof2); | ||
| 121 | scmds.continuousTone = SEC_TONE_ON; | ||
| 122 | } | ||
| 123 | frp.Inversion = INVERSION_AUTO; | ||
| 124 | if (pol) scmds.voltage = SEC_VOLTAGE_18; | ||
| 125 | else scmds.voltage = SEC_VOLTAGE_13; | ||
| 126 | |||
| 127 | scmd.type=0; | ||
| 128 | scmd.u.diseqc.addr=0x10; | ||
| 129 | scmd.u.diseqc.cmd=0x38; | ||
| 130 | scmd.u.diseqc.numParams=1; | ||
| 131 | scmd.u.diseqc.params[0] = 0xF0 | ((diseqc ⋆ 4) & 0x0F) | | ||
| 132 | (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) | | ||
| 133 | (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0); | ||
| 134 | |||
| 135 | scmds.miniCommand=SEC_MINI_NONE; | ||
| 136 | scmds.numCommands=1; | ||
| 137 | scmds.commands=&scmd; | ||
| 138 | if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ | ||
| 139 | perror("SEC SEND: "); | ||
| 140 | return -1; | ||
| 141 | } | ||
| 142 | |||
| 143 | if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ | ||
| 144 | perror("SEC SEND: "); | ||
| 145 | return -1; | ||
| 146 | } | ||
| 147 | |||
| 148 | frp.u.qpsk.SymbolRate = srate; | ||
| 149 | frp.u.qpsk.FEC_inner = fec; | ||
| 150 | |||
| 151 | if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ | ||
| 152 | perror("QPSK TUNE: "); | ||
| 153 | return -1; | ||
| 154 | } | ||
| 155 | |||
| 156 | pfd[0].fd = front; | ||
| 157 | pfd[0].events = POLLIN; | ||
| 158 | |||
| 159 | if (poll(pfd,1,3000)){ | ||
| 160 | if (pfd[0].revents & POLLIN){ | ||
| 161 | printf("Getting QPSK event\n"); | ||
| 162 | if ( ioctl(front, FE_GET_EVENT, &event) | ||
| 163 | |||
| 164 | == -EOVERFLOW){ | ||
| 165 | perror("qpsk get event"); | ||
| 166 | return -1; | ||
| 167 | } | ||
| 168 | printf("Received "); | ||
| 169 | switch(event.type){ | ||
| 170 | case FE_UNEXPECTED_EV: | ||
| 171 | printf("unexpected event\n"); | ||
| 172 | return -1; | ||
| 173 | case FE_FAILURE_EV: | ||
| 174 | printf("failure event\n"); | ||
| 175 | return -1; | ||
| 176 | |||
| 177 | case FE_COMPLETION_EV: | ||
| 178 | printf("completion event\n"); | ||
| 179 | } | ||
| 180 | } | ||
| 181 | } | ||
| 182 | |||
| 183 | |||
| 184 | pesFilterParams.pid = vpid; | ||
| 185 | pesFilterParams.input = DMX_IN_FRONTEND; | ||
| 186 | pesFilterParams.output = DMX_OUT_DECODER; | ||
| 187 | pesFilterParams.pes_type = DMX_PES_VIDEO; | ||
| 188 | pesFilterParams.flags = DMX_IMMEDIATE_START; | ||
| 189 | if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ | ||
| 190 | perror("set_vpid"); | ||
| 191 | return -1; | ||
| 192 | } | ||
| 193 | |||
| 194 | pesFilterParams.pid = apid; | ||
| 195 | pesFilterParams.input = DMX_IN_FRONTEND; | ||
| 196 | pesFilterParams.output = DMX_OUT_DECODER; | ||
| 197 | pesFilterParams.pes_type = DMX_PES_AUDIO; | ||
| 198 | pesFilterParams.flags = DMX_IMMEDIATE_START; | ||
| 199 | if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ | ||
| 200 | perror("set_apid"); | ||
| 201 | return -1; | ||
| 202 | } | ||
| 203 | |||
| 204 | pesFilterParams.pid = tpid; | ||
| 205 | pesFilterParams.input = DMX_IN_FRONTEND; | ||
| 206 | pesFilterParams.output = DMX_OUT_DECODER; | ||
| 207 | pesFilterParams.pes_type = DMX_PES_TELETEXT; | ||
| 208 | pesFilterParams.flags = DMX_IMMEDIATE_START; | ||
| 209 | if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ | ||
| 210 | perror("set_tpid"); | ||
| 211 | return -1; | ||
| 212 | } | ||
| 213 | |||
| 214 | return has_signal(fds); | ||
| 215 | } | ||
| 216 | |||
| 217 | </programlisting> | ||
| 218 | <para>The program assumes that you are using a universal LNB and a standard DiSEqC | ||
| 219 | switch with up to 4 addresses. Of course, you could build in some more checking if | ||
| 220 | tuning was successful and maybe try to repeat the tuning process. Depending on the | ||
| 221 | external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be | ||
| 222 | necessary. | ||
| 223 | </para> | ||
| 224 | </section> | ||
| 225 | |||
| 226 | <section id="the_dvr_device"> | ||
| 227 | <title>The DVR device</title> | ||
| 228 | <para>The following program code shows how to use the DVR device for recording. | ||
| 229 | </para> | ||
| 230 | <programlisting> | ||
| 231 | #include <sys/ioctl.h> | ||
| 232 | #include <stdio.h> | ||
| 233 | #include <stdint.h> | ||
| 234 | #include <sys/types.h> | ||
| 235 | #include <sys/stat.h> | ||
| 236 | #include <fcntl.h> | ||
| 237 | #include <time.h> | ||
| 238 | #include <unistd.h> | ||
| 239 | |||
| 240 | #include <linux/dvb/dmx.h> | ||
| 241 | #include <linux/dvb/video.h> | ||
| 242 | #include <sys/poll.h> | ||
| 243 | #define DVR "/dev/dvb/adapter0/dvr1" | ||
| 244 | #define AUDIO "/dev/dvb/adapter0/audio1" | ||
| 245 | #define VIDEO "/dev/dvb/adapter0/video1" | ||
| 246 | |||
| 247 | #define BUFFY (188⋆20) | ||
| 248 | #define MAX_LENGTH (1024⋆1024⋆5) /⋆ record 5MB ⋆/ | ||
| 249 | |||
| 250 | |||
| 251 | /⋆ switch the demuxes to recording, assuming the transponder is tuned ⋆/ | ||
| 252 | |||
| 253 | /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ | ||
| 254 | /⋆ vpid, apid: PIDs of video and audio channels ⋆/ | ||
| 255 | |||
| 256 | int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) | ||
| 257 | { | ||
| 258 | struct dmx_pes_filter_params pesFilterParams; | ||
| 259 | |||
| 260 | if (demux1 < 0){ | ||
| 261 | if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) | ||
| 262 | < 0){ | ||
| 263 | perror("DEMUX DEVICE: "); | ||
| 264 | return -1; | ||
| 265 | } | ||
| 266 | } | ||
| 267 | |||
| 268 | if (demux2 < 0){ | ||
| 269 | if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) | ||
| 270 | < 0){ | ||
| 271 | perror("DEMUX DEVICE: "); | ||
| 272 | return -1; | ||
| 273 | } | ||
| 274 | } | ||
| 275 | |||
| 276 | pesFilterParams.pid = vpid; | ||
| 277 | pesFilterParams.input = DMX_IN_FRONTEND; | ||
| 278 | pesFilterParams.output = DMX_OUT_TS_TAP; | ||
| 279 | pesFilterParams.pes_type = DMX_PES_VIDEO; | ||
| 280 | pesFilterParams.flags = DMX_IMMEDIATE_START; | ||
| 281 | if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ | ||
| 282 | perror("DEMUX DEVICE"); | ||
| 283 | return -1; | ||
| 284 | } | ||
| 285 | pesFilterParams.pid = apid; | ||
| 286 | pesFilterParams.input = DMX_IN_FRONTEND; | ||
| 287 | pesFilterParams.output = DMX_OUT_TS_TAP; | ||
| 288 | pesFilterParams.pes_type = DMX_PES_AUDIO; | ||
| 289 | pesFilterParams.flags = DMX_IMMEDIATE_START; | ||
| 290 | if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ | ||
| 291 | perror("DEMUX DEVICE"); | ||
| 292 | return -1; | ||
| 293 | } | ||
| 294 | return 0; | ||
| 295 | } | ||
| 296 | |||
| 297 | /⋆ start recording MAX_LENGTH , assuming the transponder is tuned ⋆/ | ||
| 298 | |||
| 299 | /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ | ||
| 300 | /⋆ vpid, apid: PIDs of video and audio channels ⋆/ | ||
| 301 | int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid) | ||
| 302 | { | ||
| 303 | int i; | ||
| 304 | int len; | ||
| 305 | int written; | ||
| 306 | uint8_t buf[BUFFY]; | ||
| 307 | uint64_t length; | ||
| 308 | struct pollfd pfd[1]; | ||
| 309 | int dvr, dvr_out; | ||
| 310 | |||
| 311 | /⋆ open dvr device ⋆/ | ||
| 312 | if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){ | ||
| 313 | perror("DVR DEVICE"); | ||
| 314 | return -1; | ||
| 315 | } | ||
| 316 | |||
| 317 | /⋆ switch video and audio demuxes to dvr ⋆/ | ||
| 318 | printf ("Switching dvr on\n"); | ||
| 319 | i = switch_to_record(demux1, demux2, vpid, apid); | ||
| 320 | printf("finished: "); | ||
| 321 | |||
| 322 | printf("Recording %2.0f MB of test file in TS format\n", | ||
| 323 | MAX_LENGTH/(1024.0⋆1024.0)); | ||
| 324 | length = 0; | ||
| 325 | |||
| 326 | /⋆ open output file ⋆/ | ||
| 327 | if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT | ||
| 328 | |O_TRUNC, S_IRUSR|S_IWUSR | ||
| 329 | |S_IRGRP|S_IWGRP|S_IROTH| | ||
| 330 | S_IWOTH)) < 0){ | ||
| 331 | perror("Can't open file for dvr test"); | ||
| 332 | return -1; | ||
| 333 | } | ||
| 334 | |||
| 335 | pfd[0].fd = dvr; | ||
| 336 | pfd[0].events = POLLIN; | ||
| 337 | |||
| 338 | /⋆ poll for dvr data and write to file ⋆/ | ||
| 339 | while (length < MAX_LENGTH ) { | ||
| 340 | if (poll(pfd,1,1)){ | ||
| 341 | if (pfd[0].revents & POLLIN){ | ||
| 342 | len = read(dvr, buf, BUFFY); | ||
| 343 | if (len < 0){ | ||
| 344 | perror("recording"); | ||
| 345 | return -1; | ||
| 346 | } | ||
| 347 | if (len > 0){ | ||
| 348 | written = 0; | ||
| 349 | while (written < len) | ||
| 350 | written += | ||
| 351 | write (dvr_out, | ||
| 352 | buf, len); | ||
| 353 | length += len; | ||
| 354 | printf("written %2.0f MB\r", | ||
| 355 | length/1024./1024.); | ||
| 356 | } | ||
| 357 | } | ||
| 358 | } | ||
| 359 | } | ||
| 360 | return 0; | ||
| 361 | } | ||
| 362 | |||
| 363 | </programlisting> | ||
| 364 | |||
| 365 | </section> | ||
diff --git a/Documentation/DocBook/dvb/frontend.xml b/Documentation/DocBook/dvb/frontend.xml new file mode 100644 index 000000000000..9d89a7b94fd5 --- /dev/null +++ b/Documentation/DocBook/dvb/frontend.xml | |||
| @@ -0,0 +1,1766 @@ | |||
| 1 | <title>DVB Frontend API</title> | ||
| 2 | |||
| 3 | <para>The DVB frontend device controls the tuner and DVB demodulator | ||
| 4 | hardware. It can be accessed through <emphasis | ||
| 5 | role="tt">/dev/dvb/adapter0/frontend0</emphasis>. Data types and and | ||
| 6 | ioctl definitions can be accessed by including <emphasis | ||
| 7 | role="tt">linux/dvb/frontend.h</emphasis> in your application.</para> | ||
| 8 | |||
| 9 | <para>DVB frontends come in three varieties: DVB-S (satellite), DVB-C | ||
| 10 | (cable) and DVB-T (terrestrial). Transmission via the internet (DVB-IP) | ||
| 11 | is not yet handled by this API but a future extension is possible. For | ||
| 12 | DVB-S the frontend device also supports satellite equipment control | ||
| 13 | (SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) | ||
| 14 | specification is available from | ||
| 15 | <ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</para> | ||
| 16 | |||
| 17 | <para>Note that the DVB API may also be used for MPEG decoder-only PCI | ||
| 18 | cards, in which case there exists no frontend device.</para> | ||
| 19 | |||
| 20 | <section id="frontend_types"> | ||
| 21 | <title>Frontend Data Types</title> | ||
| 22 | |||
| 23 | <section id="frontend_type"> | ||
| 24 | <title>frontend type</title> | ||
| 25 | |||
| 26 | <para>For historical reasons frontend types are named after the type of modulation used in | ||
| 27 | transmission.</para> | ||
| 28 | <programlisting> | ||
| 29 | typedef enum fe_type { | ||
| 30 | FE_QPSK, /⋆ DVB-S ⋆/ | ||
| 31 | FE_QAM, /⋆ DVB-C ⋆/ | ||
| 32 | FE_OFDM /⋆ DVB-T ⋆/ | ||
| 33 | } fe_type_t; | ||
| 34 | </programlisting> | ||
| 35 | |||
| 36 | </section> | ||
| 37 | |||
| 38 | <section id="frontend_caps"> | ||
| 39 | <title>frontend capabilities</title> | ||
| 40 | |||
| 41 | <para>Capabilities describe what a frontend can do. Some capabilities can only be supported for | ||
| 42 | a specific frontend type.</para> | ||
| 43 | <programlisting> | ||
| 44 | typedef enum fe_caps { | ||
| 45 | FE_IS_STUPID = 0, | ||
| 46 | FE_CAN_INVERSION_AUTO = 0x1, | ||
| 47 | FE_CAN_FEC_1_2 = 0x2, | ||
| 48 | FE_CAN_FEC_2_3 = 0x4, | ||
| 49 | FE_CAN_FEC_3_4 = 0x8, | ||
| 50 | FE_CAN_FEC_4_5 = 0x10, | ||
| 51 | FE_CAN_FEC_5_6 = 0x20, | ||
| 52 | FE_CAN_FEC_6_7 = 0x40, | ||
| 53 | FE_CAN_FEC_7_8 = 0x80, | ||
| 54 | FE_CAN_FEC_8_9 = 0x100, | ||
| 55 | FE_CAN_FEC_AUTO = 0x200, | ||
| 56 | FE_CAN_QPSK = 0x400, | ||
| 57 | FE_CAN_QAM_16 = 0x800, | ||
| 58 | FE_CAN_QAM_32 = 0x1000, | ||
| 59 | FE_CAN_QAM_64 = 0x2000, | ||
| 60 | FE_CAN_QAM_128 = 0x4000, | ||
| 61 | FE_CAN_QAM_256 = 0x8000, | ||
| 62 | FE_CAN_QAM_AUTO = 0x10000, | ||
| 63 | FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000, | ||
| 64 | FE_CAN_BANDWIDTH_AUTO = 0x40000, | ||
| 65 | FE_CAN_GUARD_INTERVAL_AUTO = 0x80000, | ||
| 66 | FE_CAN_HIERARCHY_AUTO = 0x100000, | ||
| 67 | FE_CAN_MUTE_TS = 0x80000000, | ||
| 68 | FE_CAN_CLEAN_SETUP = 0x40000000 | ||
| 69 | } fe_caps_t; | ||
| 70 | </programlisting> | ||
| 71 | </section> | ||
| 72 | |||
| 73 | <section id="frontend_info"> | ||
| 74 | <title>frontend information</title> | ||
| 75 | |||
| 76 | <para>Information about the frontend ca be queried with FE_GET_INFO.</para> | ||
| 77 | |||
| 78 | <programlisting> | ||
| 79 | struct dvb_frontend_info { | ||
| 80 | char name[128]; | ||
| 81 | fe_type_t type; | ||
| 82 | uint32_t frequency_min; | ||
| 83 | uint32_t frequency_max; | ||
| 84 | uint32_t frequency_stepsize; | ||
| 85 | uint32_t frequency_tolerance; | ||
| 86 | uint32_t symbol_rate_min; | ||
| 87 | uint32_t symbol_rate_max; | ||
| 88 | uint32_t symbol_rate_tolerance; /⋆ ppm ⋆/ | ||
| 89 | uint32_t notifier_delay; /⋆ ms ⋆/ | ||
| 90 | fe_caps_t caps; | ||
| 91 | }; | ||
| 92 | </programlisting> | ||
| 93 | </section> | ||
| 94 | |||
| 95 | <section id="frontend_diseqc"> | ||
| 96 | <title>diseqc master command</title> | ||
| 97 | |||
| 98 | <para>A message sent from the frontend to DiSEqC capable equipment.</para> | ||
| 99 | <programlisting> | ||
| 100 | struct dvb_diseqc_master_cmd { | ||
| 101 | uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/ | ||
| 102 | uint8_t msg_len; /⋆ valid values are 3...6 ⋆/ | ||
| 103 | }; | ||
| 104 | </programlisting> | ||
| 105 | </section> | ||
| 106 | <section role="subsection"> | ||
| 107 | <title>diseqc slave reply</title> | ||
| 108 | |||
| 109 | <para>A reply to the frontend from DiSEqC 2.0 capable equipment.</para> | ||
| 110 | <programlisting> | ||
| 111 | struct dvb_diseqc_slave_reply { | ||
| 112 | uint8_t msg [4]; /⋆ { framing, data [3] } ⋆/ | ||
| 113 | uint8_t msg_len; /⋆ valid values are 0...4, 0 means no msg ⋆/ | ||
| 114 | int timeout; /⋆ return from ioctl after timeout ms with ⋆/ | ||
| 115 | }; /⋆ errorcode when no message was received ⋆/ | ||
| 116 | </programlisting> | ||
| 117 | </section> | ||
| 118 | |||
| 119 | <section id="frontend_diseqc_slave_reply"> | ||
| 120 | <title>diseqc slave reply</title> | ||
| 121 | <para>The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation | ||
| 122 | (horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched | ||
| 123 | consistently to the DiSEqC commands as described in the DiSEqC spec.</para> | ||
| 124 | <programlisting> | ||
| 125 | typedef enum fe_sec_voltage { | ||
| 126 | SEC_VOLTAGE_13, | ||
| 127 | SEC_VOLTAGE_18 | ||
| 128 | } fe_sec_voltage_t; | ||
| 129 | </programlisting> | ||
| 130 | </section> | ||
| 131 | |||
| 132 | <section id="frontend_sec_tone"> | ||
| 133 | <title>SEC continuous tone</title> | ||
| 134 | |||
| 135 | <para>The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the | ||
| 136 | high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to | ||
| 137 | be switched consistently to the DiSEqC commands as described in the DiSEqC | ||
| 138 | spec.</para> | ||
| 139 | <programlisting> | ||
| 140 | typedef enum fe_sec_tone_mode { | ||
| 141 | SEC_TONE_ON, | ||
| 142 | SEC_TONE_OFF | ||
| 143 | } fe_sec_tone_mode_t; | ||
| 144 | </programlisting> | ||
| 145 | </section> | ||
| 146 | |||
| 147 | <section id="frontend_sec_burst"> | ||
| 148 | <title>SEC tone burst</title> | ||
| 149 | |||
| 150 | <para>The 22KHz tone burst is usually used with non-DiSEqC capable switches to select | ||
| 151 | between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to | ||
| 152 | be switched consistently to the DiSEqC commands as described in the DiSEqC | ||
| 153 | spec.</para> | ||
| 154 | <programlisting> | ||
| 155 | typedef enum fe_sec_mini_cmd { | ||
| 156 | SEC_MINI_A, | ||
| 157 | SEC_MINI_B | ||
| 158 | } fe_sec_mini_cmd_t; | ||
| 159 | </programlisting> | ||
| 160 | |||
| 161 | <para></para> | ||
| 162 | </section> | ||
| 163 | |||
| 164 | <section id="frontend_status"> | ||
| 165 | <title>frontend status</title> | ||
| 166 | <para>Several functions of the frontend device use the fe_status data type defined | ||
| 167 | by</para> | ||
| 168 | <programlisting> | ||
| 169 | typedef enum fe_status { | ||
| 170 | FE_HAS_SIGNAL = 0x01, /⋆ found something above the noise level ⋆/ | ||
| 171 | FE_HAS_CARRIER = 0x02, /⋆ found a DVB signal ⋆/ | ||
| 172 | FE_HAS_VITERBI = 0x04, /⋆ FEC is stable ⋆/ | ||
| 173 | FE_HAS_SYNC = 0x08, /⋆ found sync bytes ⋆/ | ||
| 174 | FE_HAS_LOCK = 0x10, /⋆ everything's working... ⋆/ | ||
| 175 | FE_TIMEDOUT = 0x20, /⋆ no lock within the last ~2 seconds ⋆/ | ||
| 176 | FE_REINIT = 0x40 /⋆ frontend was reinitialized, ⋆/ | ||
| 177 | } fe_status_t; /⋆ application is recommned to reset ⋆/ | ||
| 178 | </programlisting> | ||
| 179 | <para>to indicate the current state and/or state changes of the frontend hardware. | ||
| 180 | </para> | ||
| 181 | |||
| 182 | </section> | ||
| 183 | |||
| 184 | <section id="frontend_params"> | ||
| 185 | <title>frontend parameters</title> | ||
| 186 | <para>The kind of parameters passed to the frontend device for tuning depend on | ||
| 187 | the kind of hardware you are using. All kinds of parameters are combined as an | ||
| 188 | union in the FrontendParameters structure:</para> | ||
| 189 | <programlisting> | ||
| 190 | struct dvb_frontend_parameters { | ||
| 191 | uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ | ||
| 192 | /⋆ intermediate frequency in kHz for QPSK ⋆/ | ||
| 193 | fe_spectral_inversion_t inversion; | ||
| 194 | union { | ||
| 195 | struct dvb_qpsk_parameters qpsk; | ||
| 196 | struct dvb_qam_parameters qam; | ||
| 197 | struct dvb_ofdm_parameters ofdm; | ||
| 198 | } u; | ||
| 199 | }; | ||
| 200 | </programlisting> | ||
| 201 | <para>For satellite QPSK frontends you have to use the <constant>QPSKParameters</constant> member defined by</para> | ||
| 202 | <programlisting> | ||
| 203 | struct dvb_qpsk_parameters { | ||
| 204 | uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ | ||
| 205 | fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ | ||
| 206 | }; | ||
| 207 | </programlisting> | ||
| 208 | <para>for cable QAM frontend you use the <constant>QAMParameters</constant> structure</para> | ||
| 209 | <programlisting> | ||
| 210 | struct dvb_qam_parameters { | ||
| 211 | uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ | ||
| 212 | fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ | ||
| 213 | fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ | ||
| 214 | }; | ||
| 215 | </programlisting> | ||
| 216 | <para>DVB-T frontends are supported by the <constant>OFDMParamters</constant> structure | ||
| 217 | </para> | ||
| 218 | <programlisting> | ||
| 219 | struct dvb_ofdm_parameters { | ||
| 220 | fe_bandwidth_t bandwidth; | ||
| 221 | fe_code_rate_t code_rate_HP; /⋆ high priority stream code rate ⋆/ | ||
| 222 | fe_code_rate_t code_rate_LP; /⋆ low priority stream code rate ⋆/ | ||
| 223 | fe_modulation_t constellation; /⋆ modulation type (see above) ⋆/ | ||
| 224 | fe_transmit_mode_t transmission_mode; | ||
| 225 | fe_guard_interval_t guard_interval; | ||
| 226 | fe_hierarchy_t hierarchy_information; | ||
| 227 | }; | ||
| 228 | </programlisting> | ||
| 229 | <para>In the case of QPSK frontends the <constant>Frequency</constant> field specifies the intermediate | ||
| 230 | frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of | ||
| 231 | the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and | ||
| 232 | OFDM frontends the Frequency specifies the absolute frequency and is given in | ||
| 233 | Hz. | ||
| 234 | </para> | ||
| 235 | <para>The Inversion field can take one of these values: | ||
| 236 | </para> | ||
| 237 | <programlisting> | ||
| 238 | typedef enum fe_spectral_inversion { | ||
| 239 | INVERSION_OFF, | ||
| 240 | INVERSION_ON, | ||
| 241 | INVERSION_AUTO | ||
| 242 | } fe_spectral_inversion_t; | ||
| 243 | </programlisting> | ||
| 244 | <para>It indicates if spectral inversion should be presumed or not. In the automatic setting | ||
| 245 | (<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by | ||
| 246 | itself. | ||
| 247 | </para> | ||
| 248 | <para>The possible values for the <constant>FEC_inner</constant> field are | ||
| 249 | </para> | ||
| 250 | <programlisting> | ||
| 251 | typedef enum fe_code_rate { | ||
| 252 | FEC_NONE = 0, | ||
| 253 | FEC_1_2, | ||
| 254 | FEC_2_3, | ||
| 255 | FEC_3_4, | ||
| 256 | FEC_4_5, | ||
| 257 | FEC_5_6, | ||
| 258 | FEC_6_7, | ||
| 259 | FEC_7_8, | ||
| 260 | FEC_8_9, | ||
| 261 | FEC_AUTO | ||
| 262 | } fe_code_rate_t; | ||
| 263 | </programlisting> | ||
| 264 | <para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto | ||
| 265 | detection. | ||
| 266 | </para> | ||
| 267 | <para>For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature | ||
| 268 | modulation mode which can be one of the following: | ||
| 269 | </para> | ||
| 270 | <programlisting> | ||
| 271 | typedef enum fe_modulation { | ||
| 272 | QPSK, | ||
| 273 | QAM_16, | ||
| 274 | QAM_32, | ||
| 275 | QAM_64, | ||
| 276 | QAM_128, | ||
| 277 | QAM_256, | ||
| 278 | QAM_AUTO | ||
| 279 | } fe_modulation_t; | ||
| 280 | </programlisting> | ||
| 281 | <para>Finally, there are several more parameters for OFDM: | ||
| 282 | </para> | ||
| 283 | <programlisting> | ||
| 284 | typedef enum fe_transmit_mode { | ||
| 285 | TRANSMISSION_MODE_2K, | ||
| 286 | TRANSMISSION_MODE_8K, | ||
| 287 | TRANSMISSION_MODE_AUTO | ||
| 288 | } fe_transmit_mode_t; | ||
| 289 | </programlisting> | ||
| 290 | <programlisting> | ||
| 291 | typedef enum fe_bandwidth { | ||
| 292 | BANDWIDTH_8_MHZ, | ||
| 293 | BANDWIDTH_7_MHZ, | ||
| 294 | BANDWIDTH_6_MHZ, | ||
| 295 | BANDWIDTH_AUTO | ||
| 296 | } fe_bandwidth_t; | ||
| 297 | </programlisting> | ||
| 298 | <programlisting> | ||
| 299 | typedef enum fe_guard_interval { | ||
| 300 | GUARD_INTERVAL_1_32, | ||
| 301 | GUARD_INTERVAL_1_16, | ||
| 302 | GUARD_INTERVAL_1_8, | ||
| 303 | GUARD_INTERVAL_1_4, | ||
| 304 | GUARD_INTERVAL_AUTO | ||
| 305 | } fe_guard_interval_t; | ||
| 306 | </programlisting> | ||
| 307 | <programlisting> | ||
| 308 | typedef enum fe_hierarchy { | ||
| 309 | HIERARCHY_NONE, | ||
| 310 | HIERARCHY_1, | ||
| 311 | HIERARCHY_2, | ||
| 312 | HIERARCHY_4, | ||
| 313 | HIERARCHY_AUTO | ||
| 314 | } fe_hierarchy_t; | ||
| 315 | </programlisting> | ||
| 316 | |||
| 317 | </section> | ||
| 318 | |||
| 319 | <section id="frontend_events"> | ||
| 320 | <title>frontend events</title> | ||
| 321 | <programlisting> | ||
| 322 | struct dvb_frontend_event { | ||
| 323 | fe_status_t status; | ||
| 324 | struct dvb_frontend_parameters parameters; | ||
| 325 | }; | ||
| 326 | </programlisting> | ||
| 327 | </section> | ||
| 328 | </section> | ||
| 329 | |||
| 330 | |||
| 331 | <section id="frontend_fcalls"> | ||
| 332 | <title>Frontend Function Calls</title> | ||
| 333 | |||
| 334 | <section id="frontend_f_open"> | ||
| 335 | <title>open()</title> | ||
| 336 | <para>DESCRIPTION</para> | ||
| 337 | <informaltable><tgroup cols="1"><tbody><row> | ||
| 338 | <entry align="char"> | ||
| 339 | <para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0) | ||
| 340 | for subsequent use. Usually the first thing to do after a successful open is to | ||
| 341 | find out the frontend type with FE_GET_INFO.</para> | ||
| 342 | <para>The device can be opened in read-only mode, which only allows monitoring of | ||
| 343 | device status and statistics, or read/write mode, which allows any kind of use | ||
| 344 | (e.g. performing tuning operations.) | ||
| 345 | </para> | ||
| 346 | <para>In a system with multiple front-ends, it is usually the case that multiple devices | ||
| 347 | cannot be open in read/write mode simultaneously. As long as a front-end | ||
| 348 | device is opened in read/write mode, other open() calls in read/write mode will | ||
| 349 | either fail or block, depending on whether non-blocking or blocking mode was | ||
| 350 | specified. A front-end device opened in blocking mode can later be put into | ||
| 351 | non-blocking mode (and vice versa) using the F_SETFL command of the fcntl | ||
| 352 | system call. This is a standard system call, documented in the Linux manual | ||
| 353 | page for fcntl. When an open() call has succeeded, the device will be ready | ||
| 354 | for use in the specified mode. This implies that the corresponding hardware is | ||
| 355 | powered up, and that other front-ends may have been powered down to make | ||
| 356 | that possible.</para> | ||
| 357 | </entry> | ||
| 358 | </row></tbody></tgroup></informaltable> | ||
| 359 | |||
| 360 | <para>SYNOPSIS</para> | ||
| 361 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 362 | align="char"> | ||
| 363 | <para>int open(const char ⋆deviceName, int flags);</para> | ||
| 364 | </entry> | ||
| 365 | </row></tbody></tgroup></informaltable> | ||
| 366 | <para>PARAMETERS | ||
| 367 | </para> | ||
| 368 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 369 | align="char"> | ||
| 370 | <para>const char | ||
| 371 | *deviceName</para> | ||
| 372 | </entry><entry | ||
| 373 | align="char"> | ||
| 374 | <para>Name of specific video device.</para> | ||
| 375 | </entry> | ||
| 376 | </row><row><entry | ||
| 377 | align="char"> | ||
| 378 | <para>int flags</para> | ||
| 379 | </entry><entry | ||
| 380 | align="char"> | ||
| 381 | <para>A bit-wise OR of the following flags:</para> | ||
| 382 | </entry> | ||
| 383 | </row><row><entry | ||
| 384 | align="char"> | ||
| 385 | </entry><entry | ||
| 386 | align="char"> | ||
| 387 | <para>O_RDONLY read-only access</para> | ||
| 388 | </entry> | ||
| 389 | </row><row><entry | ||
| 390 | align="char"> | ||
| 391 | </entry><entry | ||
| 392 | align="char"> | ||
| 393 | <para>O_RDWR read/write access</para> | ||
| 394 | </entry> | ||
| 395 | </row><row><entry | ||
| 396 | align="char"> | ||
| 397 | </entry><entry | ||
| 398 | align="char"> | ||
| 399 | <para>O_NONBLOCK open in non-blocking mode</para> | ||
| 400 | </entry> | ||
| 401 | </row><row><entry | ||
| 402 | align="char"> | ||
| 403 | </entry><entry | ||
| 404 | align="char"> | ||
| 405 | <para>(blocking mode is the default)</para> | ||
| 406 | </entry> | ||
| 407 | </row></tbody></tgroup></informaltable> | ||
| 408 | <para>ERRORS | ||
| 409 | </para> | ||
| 410 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 411 | align="char"> | ||
| 412 | <para>ENODEV</para> | ||
| 413 | </entry><entry | ||
| 414 | align="char"> | ||
| 415 | <para>Device driver not loaded/available.</para> | ||
| 416 | </entry> | ||
| 417 | </row><row><entry | ||
| 418 | align="char"> | ||
| 419 | <para>EINTERNAL</para> | ||
| 420 | </entry><entry | ||
| 421 | align="char"> | ||
| 422 | <para>Internal error.</para> | ||
| 423 | </entry> | ||
| 424 | </row><row><entry | ||
| 425 | align="char"> | ||
| 426 | <para>EBUSY</para> | ||
| 427 | </entry><entry | ||
| 428 | align="char"> | ||
| 429 | <para>Device or resource busy.</para> | ||
| 430 | </entry> | ||
| 431 | </row><row><entry | ||
| 432 | align="char"> | ||
| 433 | <para>EINVAL</para> | ||
| 434 | </entry><entry | ||
| 435 | align="char"> | ||
| 436 | <para>Invalid argument.</para> | ||
| 437 | </entry> | ||
| 438 | </row></tbody></tgroup></informaltable> | ||
| 439 | </section> | ||
| 440 | |||
| 441 | <section id="frontend_f_close"> | ||
| 442 | <title>close()</title> | ||
| 443 | <para>DESCRIPTION | ||
| 444 | </para> | ||
| 445 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 446 | align="char"> | ||
| 447 | <para>This system call closes a previously opened front-end device. After closing | ||
| 448 | a front-end device, its corresponding hardware might be powered down | ||
| 449 | automatically.</para> | ||
| 450 | </entry> | ||
| 451 | </row></tbody></tgroup></informaltable> | ||
| 452 | <para>SYNOPSIS | ||
| 453 | </para> | ||
| 454 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 455 | align="char"> | ||
| 456 | <para>int close(int fd);</para> | ||
| 457 | </entry> | ||
| 458 | </row></tbody></tgroup></informaltable> | ||
| 459 | <para>PARAMETERS | ||
| 460 | </para> | ||
| 461 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 462 | align="char"> | ||
| 463 | <para>int fd</para> | ||
| 464 | </entry><entry | ||
| 465 | align="char"> | ||
| 466 | <para>File descriptor returned by a previous call to open().</para> | ||
| 467 | </entry> | ||
| 468 | </row></tbody></tgroup></informaltable> | ||
| 469 | <para>ERRORS | ||
| 470 | </para> | ||
| 471 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 472 | align="char"> | ||
| 473 | <para>EBADF</para> | ||
| 474 | </entry><entry | ||
| 475 | align="char"> | ||
| 476 | <para>fd is not a valid open file descriptor.</para> | ||
| 477 | </entry> | ||
| 478 | </row></tbody></tgroup></informaltable> | ||
| 479 | </section> | ||
| 480 | |||
| 481 | <section id="frontend_read_status"> | ||
| 482 | <title>FE_READ_STATUS</title> | ||
| 483 | <para>DESCRIPTION | ||
| 484 | </para> | ||
| 485 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 486 | align="char"> | ||
| 487 | <para>This ioctl call returns status information about the front-end. This call only | ||
| 488 | requires read-only access to the device.</para> | ||
| 489 | </entry> | ||
| 490 | </row></tbody></tgroup></informaltable> | ||
| 491 | <para>SYNOPSIS | ||
| 492 | </para> | ||
| 493 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 494 | align="char"> | ||
| 495 | <para>int ioctl(int fd, int request = FE_READ_STATUS, | ||
| 496 | fe_status_t ⋆status);</para> | ||
| 497 | </entry> | ||
| 498 | </row></tbody></tgroup></informaltable> | ||
| 499 | <para>PARAMETERS | ||
| 500 | </para> | ||
| 501 | |||
| 502 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 503 | align="char"> | ||
| 504 | <para>int fd</para> | ||
| 505 | </entry><entry | ||
| 506 | align="char"> | ||
| 507 | <para>File descriptor returned by a previous call to open().</para> | ||
| 508 | </entry> | ||
| 509 | </row><row><entry | ||
| 510 | align="char"> | ||
| 511 | <para>int request</para> | ||
| 512 | </entry><entry | ||
| 513 | align="char"> | ||
| 514 | <para>Equals FE_READ_STATUS for this command.</para> | ||
| 515 | </entry> | ||
| 516 | </row><row><entry | ||
| 517 | align="char"> | ||
| 518 | <para>struct fe_status_t | ||
| 519 | *status</para> | ||
| 520 | </entry><entry | ||
| 521 | align="char"> | ||
| 522 | <para>Points to the location where the front-end status word is | ||
| 523 | to be stored.</para> | ||
| 524 | </entry> | ||
| 525 | </row></tbody></tgroup></informaltable> | ||
| 526 | <para>ERRORS | ||
| 527 | </para> | ||
| 528 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 529 | align="char"> | ||
| 530 | <para>EBADF</para> | ||
| 531 | </entry><entry | ||
| 532 | align="char"> | ||
| 533 | <para>fd is not a valid open file descriptor.</para> | ||
| 534 | </entry> | ||
| 535 | </row><row><entry | ||
| 536 | align="char"> | ||
| 537 | <para>EFAULT</para> | ||
| 538 | </entry><entry | ||
| 539 | align="char"> | ||
| 540 | <para>status points to invalid address.</para> | ||
| 541 | </entry> | ||
| 542 | </row></tbody></tgroup></informaltable> | ||
| 543 | </section> | ||
| 544 | |||
| 545 | <section id="frontend_read_ber"> | ||
| 546 | <title>FE_READ_BER</title> | ||
| 547 | <para>DESCRIPTION | ||
| 548 | </para> | ||
| 549 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 550 | align="char"> | ||
| 551 | <para>This ioctl call returns the bit error rate for the signal currently | ||
| 552 | received/demodulated by the front-end. For this command, read-only access to | ||
| 553 | the device is sufficient.</para> | ||
| 554 | </entry> | ||
| 555 | </row></tbody></tgroup></informaltable> | ||
| 556 | <para>SYNOPSIS | ||
| 557 | </para> | ||
| 558 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 559 | align="char"> | ||
| 560 | <para>int ioctl(int fd, int request = FE_READ_BER, | ||
| 561 | uint32_t ⋆ber);</para> | ||
| 562 | </entry> | ||
| 563 | </row></tbody></tgroup></informaltable> | ||
| 564 | <para>PARAMETERS | ||
| 565 | </para> | ||
| 566 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 567 | align="char"> | ||
| 568 | <para>int fd</para> | ||
| 569 | </entry><entry | ||
| 570 | align="char"> | ||
| 571 | <para>File descriptor returned by a previous call to open().</para> | ||
| 572 | </entry> | ||
| 573 | </row><row><entry | ||
| 574 | align="char"> | ||
| 575 | <para>int request</para> | ||
| 576 | </entry><entry | ||
| 577 | align="char"> | ||
| 578 | <para>Equals FE_READ_BER for this command.</para> | ||
| 579 | </entry> | ||
| 580 | </row><row><entry | ||
| 581 | align="char"> | ||
| 582 | <para>uint32_t *ber</para> | ||
| 583 | </entry><entry | ||
| 584 | align="char"> | ||
| 585 | <para>The bit error rate is stored into *ber.</para> | ||
| 586 | </entry> | ||
| 587 | </row></tbody></tgroup></informaltable> | ||
| 588 | <para>ERRORS | ||
| 589 | </para> | ||
| 590 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 591 | align="char"> | ||
| 592 | <para>EBADF</para> | ||
| 593 | </entry><entry | ||
| 594 | align="char"> | ||
| 595 | <para>fd is not a valid open file descriptor.</para> | ||
| 596 | </entry> | ||
| 597 | </row><row><entry | ||
| 598 | align="char"> | ||
| 599 | <para>EFAULT</para> | ||
| 600 | </entry><entry | ||
| 601 | align="char"> | ||
| 602 | <para>ber points to invalid address.</para> | ||
| 603 | </entry> | ||
| 604 | </row><row><entry | ||
| 605 | align="char"> | ||
| 606 | <para>ENOSIGNAL</para> | ||
| 607 | </entry><entry | ||
| 608 | align="char"> | ||
| 609 | <para>There is no signal, thus no meaningful bit error rate. Also | ||
| 610 | returned if the front-end is not turned on.</para> | ||
| 611 | </entry> | ||
| 612 | </row><row><entry | ||
| 613 | align="char"> | ||
| 614 | <para>ENOSYS</para> | ||
| 615 | </entry><entry | ||
| 616 | align="char"> | ||
| 617 | <para>Function not available for this device.</para> | ||
| 618 | </entry> | ||
| 619 | </row></tbody></tgroup></informaltable> | ||
| 620 | </section> | ||
| 621 | |||
| 622 | <section id="frontend_read_snr"> | ||
| 623 | <title>FE_READ_SNR</title> | ||
| 624 | |||
| 625 | <para>DESCRIPTION | ||
| 626 | </para> | ||
| 627 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 628 | align="char"> | ||
| 629 | <para>This ioctl call returns the signal-to-noise ratio for the signal currently received | ||
| 630 | by the front-end. For this command, read-only access to the device is sufficient.</para> | ||
| 631 | </entry> | ||
| 632 | </row></tbody></tgroup></informaltable> | ||
| 633 | <para>SYNOPSIS | ||
| 634 | </para> | ||
| 635 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 636 | align="char"> | ||
| 637 | <para>int ioctl(int fd, int request = FE_READ_SNR, int16_t | ||
| 638 | ⋆snr);</para> | ||
| 639 | </entry> | ||
| 640 | </row></tbody></tgroup></informaltable> | ||
| 641 | <para>PARAMETERS | ||
| 642 | </para> | ||
| 643 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 644 | align="char"> | ||
| 645 | <para>int fd</para> | ||
| 646 | </entry><entry | ||
| 647 | align="char"> | ||
| 648 | <para>File descriptor returned by a previous call to open().</para> | ||
| 649 | </entry> | ||
| 650 | </row><row><entry | ||
| 651 | align="char"> | ||
| 652 | <para>int request</para> | ||
| 653 | </entry><entry | ||
| 654 | align="char"> | ||
| 655 | <para>Equals FE_READ_SNR for this command.</para> | ||
| 656 | </entry> | ||
| 657 | </row><row><entry | ||
| 658 | align="char"> | ||
| 659 | <para>int16_t *snr</para> | ||
| 660 | </entry><entry | ||
| 661 | align="char"> | ||
| 662 | <para>The signal-to-noise ratio is stored into *snr.</para> | ||
| 663 | </entry> | ||
| 664 | </row></tbody></tgroup></informaltable> | ||
| 665 | |||
| 666 | <para>ERRORS | ||
| 667 | </para> | ||
| 668 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 669 | align="char"> | ||
| 670 | <para>EBADF</para> | ||
| 671 | </entry><entry | ||
| 672 | align="char"> | ||
| 673 | <para>fd is not a valid open file descriptor.</para> | ||
| 674 | </entry> | ||
| 675 | </row><row><entry | ||
| 676 | align="char"> | ||
| 677 | <para>EFAULT</para> | ||
| 678 | </entry><entry | ||
| 679 | align="char"> | ||
| 680 | <para>snr points to invalid address.</para> | ||
| 681 | </entry> | ||
| 682 | </row><row><entry | ||
| 683 | align="char"> | ||
| 684 | <para>ENOSIGNAL</para> | ||
| 685 | </entry><entry | ||
| 686 | align="char"> | ||
| 687 | <para>There is no signal, thus no meaningful signal strength | ||
| 688 | value. Also returned if front-end is not turned on.</para> | ||
| 689 | </entry> | ||
| 690 | </row><row><entry | ||
| 691 | align="char"> | ||
| 692 | <para>ENOSYS</para> | ||
| 693 | </entry><entry | ||
| 694 | align="char"> | ||
| 695 | <para>Function not available for this device.</para> | ||
| 696 | </entry> | ||
| 697 | </row></tbody></tgroup></informaltable> | ||
| 698 | </section> | ||
| 699 | |||
| 700 | <section id="frontend_read_signal_strength"> | ||
| 701 | <title>FE_READ_SIGNAL_STRENGTH</title> | ||
| 702 | <para>DESCRIPTION | ||
| 703 | </para> | ||
| 704 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 705 | align="char"> | ||
| 706 | <para>This ioctl call returns the signal strength value for the signal currently received | ||
| 707 | by the front-end. For this command, read-only access to the device is sufficient.</para> | ||
| 708 | </entry> | ||
| 709 | </row></tbody></tgroup></informaltable> | ||
| 710 | <para>SYNOPSIS | ||
| 711 | </para> | ||
| 712 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 713 | align="char"> | ||
| 714 | <para>int ioctl( int fd, int request = | ||
| 715 | FE_READ_SIGNAL_STRENGTH, int16_t ⋆strength);</para> | ||
| 716 | </entry> | ||
| 717 | </row></tbody></tgroup></informaltable> | ||
| 718 | |||
| 719 | <para>PARAMETERS | ||
| 720 | </para> | ||
| 721 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 722 | align="char"> | ||
| 723 | <para>int fd</para> | ||
| 724 | </entry><entry | ||
| 725 | align="char"> | ||
| 726 | <para>File descriptor returned by a previous call to open().</para> | ||
| 727 | </entry> | ||
| 728 | </row><row><entry | ||
| 729 | align="char"> | ||
| 730 | <para>int request</para> | ||
| 731 | </entry><entry | ||
| 732 | align="char"> | ||
| 733 | <para>Equals FE_READ_SIGNAL_STRENGTH for this | ||
| 734 | command.</para> | ||
| 735 | </entry> | ||
| 736 | </row><row><entry | ||
| 737 | align="char"> | ||
| 738 | <para>int16_t *strength</para> | ||
| 739 | </entry><entry | ||
| 740 | align="char"> | ||
| 741 | <para>The signal strength value is stored into *strength.</para> | ||
| 742 | </entry> | ||
| 743 | </row></tbody></tgroup></informaltable> | ||
| 744 | <para>ERRORS | ||
| 745 | </para> | ||
| 746 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 747 | align="char"> | ||
| 748 | <para>EBADF</para> | ||
| 749 | </entry><entry | ||
| 750 | align="char"> | ||
| 751 | <para>fd is not a valid open file descriptor.</para> | ||
| 752 | </entry> | ||
| 753 | </row><row><entry | ||
| 754 | align="char"> | ||
| 755 | <para>EFAULT</para> | ||
| 756 | </entry><entry | ||
| 757 | align="char"> | ||
| 758 | <para>status points to invalid address.</para> | ||
| 759 | </entry> | ||
| 760 | </row><row><entry | ||
| 761 | align="char"> | ||
| 762 | <para>ENOSIGNAL</para> | ||
| 763 | </entry><entry | ||
| 764 | align="char"> | ||
| 765 | <para>There is no signal, thus no meaningful signal strength | ||
| 766 | value. Also returned if front-end is not turned on.</para> | ||
| 767 | </entry> | ||
| 768 | </row><row><entry | ||
| 769 | align="char"> | ||
| 770 | <para>ENOSYS</para> | ||
| 771 | </entry><entry | ||
| 772 | align="char"> | ||
| 773 | <para>Function not available for this device.</para> | ||
| 774 | </entry> | ||
| 775 | </row></tbody></tgroup></informaltable> | ||
| 776 | </section> | ||
| 777 | |||
| 778 | <section id="frontend_read_ub"> | ||
| 779 | <title>FE_READ_UNCORRECTED_BLOCKS</title> | ||
| 780 | <para>DESCRIPTION | ||
| 781 | </para> | ||
| 782 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 783 | align="char"> | ||
| 784 | <para>This ioctl call returns the number of uncorrected blocks detected by the device | ||
| 785 | driver during its lifetime. For meaningful measurements, the increment in block | ||
| 786 | count during a specific time interval should be calculated. For this command, | ||
| 787 | read-only access to the device is sufficient.</para> | ||
| 788 | </entry> | ||
| 789 | </row><row><entry | ||
| 790 | align="char"> | ||
| 791 | <para>Note that the counter will wrap to zero after its maximum count has been | ||
| 792 | reached.</para> | ||
| 793 | </entry> | ||
| 794 | </row></tbody></tgroup></informaltable> | ||
| 795 | <para>SYNOPSIS | ||
| 796 | </para> | ||
| 797 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 798 | align="char"> | ||
| 799 | <para>int ioctl( int fd, int request = | ||
| 800 | FE_READ_UNCORRECTED_BLOCKS, uint32_t ⋆ublocks);</para> | ||
| 801 | </entry> | ||
| 802 | </row></tbody></tgroup></informaltable> | ||
| 803 | <para>PARAMETERS | ||
| 804 | </para> | ||
| 805 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 806 | align="char"> | ||
| 807 | <para>int fd</para> | ||
| 808 | </entry><entry | ||
| 809 | align="char"> | ||
| 810 | <para>File descriptor returned by a previous call to open().</para> | ||
| 811 | </entry> | ||
| 812 | </row><row><entry | ||
| 813 | align="char"> | ||
| 814 | <para>int request</para> | ||
| 815 | </entry><entry | ||
| 816 | align="char"> | ||
| 817 | <para>Equals FE_READ_UNCORRECTED_BLOCKS for this | ||
| 818 | command.</para> | ||
| 819 | </entry> | ||
| 820 | </row><row><entry | ||
| 821 | align="char"> | ||
| 822 | <para>uint32_t *ublocks</para> | ||
| 823 | </entry><entry | ||
| 824 | align="char"> | ||
| 825 | <para>The total number of uncorrected blocks seen by the driver | ||
| 826 | so far.</para> | ||
| 827 | </entry> | ||
| 828 | </row></tbody></tgroup></informaltable> | ||
| 829 | <para>ERRORS | ||
| 830 | </para> | ||
| 831 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 832 | align="char"> | ||
| 833 | <para>EBADF</para> | ||
| 834 | </entry><entry | ||
| 835 | align="char"> | ||
| 836 | <para>fd is not a valid open file descriptor.</para> | ||
| 837 | </entry> | ||
| 838 | </row><row><entry | ||
| 839 | align="char"> | ||
| 840 | <para>EFAULT</para> | ||
| 841 | </entry><entry | ||
| 842 | align="char"> | ||
| 843 | <para>ublocks points to invalid address.</para> | ||
| 844 | </entry> | ||
| 845 | </row><row><entry | ||
| 846 | align="char"> | ||
| 847 | <para>ENOSYS</para> | ||
| 848 | </entry><entry | ||
| 849 | align="char"> | ||
| 850 | <para>Function not available for this device.</para> | ||
| 851 | </entry> | ||
| 852 | </row></tbody></tgroup></informaltable> | ||
| 853 | </section> | ||
| 854 | |||
| 855 | <section id="frontend_set_fe"> | ||
| 856 | <title>FE_SET_FRONTEND</title> | ||
| 857 | <para>DESCRIPTION | ||
| 858 | </para> | ||
| 859 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 860 | align="char"> | ||
| 861 | <para>This ioctl call starts a tuning operation using specified parameters. The result | ||
| 862 | of this call will be successful if the parameters were valid and the tuning could | ||
| 863 | be initiated. The result of the tuning operation in itself, however, will arrive | ||
| 864 | asynchronously as an event (see documentation for FE_GET_EVENT and | ||
| 865 | FrontendEvent.) If a new FE_SET_FRONTEND operation is initiated before | ||
| 866 | the previous one was completed, the previous operation will be aborted in favor | ||
| 867 | of the new one. This command requires read/write access to the device.</para> | ||
| 868 | </entry> | ||
| 869 | </row></tbody></tgroup></informaltable> | ||
| 870 | |||
| 871 | <para>SYNOPSIS | ||
| 872 | </para> | ||
| 873 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 874 | align="char"> | ||
| 875 | <para>int ioctl(int fd, int request = FE_SET_FRONTEND, | ||
| 876 | struct dvb_frontend_parameters ⋆p);</para> | ||
| 877 | </entry> | ||
| 878 | </row></tbody></tgroup></informaltable> | ||
| 879 | <para>PARAMETERS | ||
| 880 | </para> | ||
| 881 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 882 | align="char"> | ||
| 883 | <para>int fd</para> | ||
| 884 | </entry><entry | ||
| 885 | align="char"> | ||
| 886 | <para>File descriptor returned by a previous call to open().</para> | ||
| 887 | </entry> | ||
| 888 | </row><row><entry | ||
| 889 | align="char"> | ||
| 890 | <para>int request</para> | ||
| 891 | </entry><entry | ||
| 892 | align="char"> | ||
| 893 | <para>Equals FE_SET_FRONTEND for this command.</para> | ||
| 894 | </entry> | ||
| 895 | </row><row><entry | ||
| 896 | align="char"> | ||
| 897 | <para>struct | ||
| 898 | dvb_frontend_parameters | ||
| 899 | *p</para> | ||
| 900 | </entry><entry | ||
| 901 | align="char"> | ||
| 902 | <para>Points to parameters for tuning operation.</para> | ||
| 903 | </entry> | ||
| 904 | </row></tbody></tgroup></informaltable> | ||
| 905 | <para>ERRORS | ||
| 906 | </para> | ||
| 907 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 908 | align="char"> | ||
| 909 | <para>EBADF</para> | ||
| 910 | </entry><entry | ||
| 911 | align="char"> | ||
| 912 | <para>fd is not a valid open file descriptor.</para> | ||
| 913 | </entry> | ||
| 914 | </row><row><entry | ||
| 915 | align="char"> | ||
| 916 | <para>EFAULT</para> | ||
| 917 | </entry><entry | ||
| 918 | align="char"> | ||
| 919 | <para>p points to invalid address.</para> | ||
| 920 | </entry> | ||
| 921 | </row><row><entry | ||
| 922 | align="char"> | ||
| 923 | <para>EINVAL</para> | ||
| 924 | </entry><entry | ||
| 925 | align="char"> | ||
| 926 | <para>Maximum supported symbol rate reached.</para> | ||
| 927 | </entry> | ||
| 928 | </row></tbody></tgroup></informaltable> | ||
| 929 | </section> | ||
| 930 | |||
| 931 | <section id="frontend_get_fe"> | ||
| 932 | <title>FE_GET_FRONTEND</title> | ||
| 933 | <para>DESCRIPTION | ||
| 934 | </para> | ||
| 935 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 936 | align="char"> | ||
| 937 | <para>This ioctl call queries the currently effective frontend parameters. For this | ||
| 938 | command, read-only access to the device is sufficient.</para> | ||
| 939 | </entry> | ||
| 940 | </row></tbody></tgroup></informaltable> | ||
| 941 | |||
| 942 | <para>SYNOPSIS | ||
| 943 | </para> | ||
| 944 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 945 | align="char"> | ||
| 946 | <para>int ioctl(int fd, int request = FE_GET_FRONTEND, | ||
| 947 | struct dvb_frontend_parameters ⋆p);</para> | ||
| 948 | </entry> | ||
| 949 | </row></tbody></tgroup></informaltable> | ||
| 950 | |||
| 951 | <para>PARAMETERS | ||
| 952 | </para> | ||
| 953 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 954 | align="char"> | ||
| 955 | <para>int fd</para> | ||
| 956 | </entry><entry | ||
| 957 | align="char"> | ||
| 958 | <para>File descriptor returned by a previous call to open().</para> | ||
| 959 | </entry> | ||
| 960 | </row><row><entry | ||
| 961 | align="char"> | ||
| 962 | <para>int request</para> | ||
| 963 | </entry><entry | ||
| 964 | align="char"> | ||
| 965 | <para>Equals FE_SET_FRONTEND for this command.</para> | ||
| 966 | </entry> | ||
| 967 | </row><row><entry | ||
| 968 | align="char"> | ||
| 969 | <para>struct | ||
| 970 | dvb_frontend_parameters | ||
| 971 | *p</para> | ||
| 972 | </entry><entry | ||
| 973 | align="char"> | ||
| 974 | <para>Points to parameters for tuning operation.</para> | ||
| 975 | </entry> | ||
| 976 | </row></tbody></tgroup></informaltable> | ||
| 977 | |||
| 978 | <para>ERRORS | ||
| 979 | </para> | ||
| 980 | |||
| 981 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 982 | align="char"> | ||
| 983 | <para>EBADF</para> | ||
| 984 | </entry><entry | ||
| 985 | align="char"> | ||
| 986 | <para>fd is not a valid open file descriptor.</para> | ||
| 987 | </entry> | ||
| 988 | </row><row><entry | ||
| 989 | align="char"> | ||
| 990 | <para>EFAULT</para> | ||
| 991 | </entry><entry | ||
| 992 | align="char"> | ||
| 993 | <para>p points to invalid address.</para> | ||
| 994 | </entry> | ||
| 995 | </row><row><entry | ||
| 996 | align="char"> | ||
| 997 | <para>EINVAL</para> | ||
| 998 | </entry><entry | ||
| 999 | align="char"> | ||
| 1000 | <para>Maximum supported symbol rate reached.</para> | ||
| 1001 | </entry> | ||
| 1002 | </row></tbody></tgroup></informaltable> | ||
| 1003 | |||
| 1004 | </section> | ||
| 1005 | |||
| 1006 | <section id="frontend_get_event"> | ||
| 1007 | <title>FE_GET_EVENT</title> | ||
| 1008 | <para>DESCRIPTION | ||
| 1009 | </para> | ||
| 1010 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1011 | align="char"> | ||
| 1012 | <para>This ioctl call returns a frontend event if available. If an event is not | ||
| 1013 | available, the behavior depends on whether the device is in blocking or | ||
| 1014 | non-blocking mode. In the latter case, the call fails immediately with errno | ||
| 1015 | set to EWOULDBLOCK. In the former case, the call blocks until an event | ||
| 1016 | becomes available.</para> | ||
| 1017 | </entry> | ||
| 1018 | </row><row><entry | ||
| 1019 | align="char"> | ||
| 1020 | <para>The standard Linux poll() and/or select() system calls can be used with the | ||
| 1021 | device file descriptor to watch for new events. For select(), the file descriptor | ||
| 1022 | should be included in the exceptfds argument, and for poll(), POLLPRI should | ||
| 1023 | be specified as the wake-up condition. Since the event queue allocated is | ||
| 1024 | rather small (room for 8 events), the queue must be serviced regularly to avoid | ||
| 1025 | overflow. If an overflow happens, the oldest event is discarded from the queue, | ||
| 1026 | and an error (EOVERFLOW) occurs the next time the queue is read. After | ||
| 1027 | reporting the error condition in this fashion, subsequent FE_GET_EVENT | ||
| 1028 | calls will return events from the queue as usual.</para> | ||
| 1029 | </entry> | ||
| 1030 | </row><row><entry | ||
| 1031 | align="char"> | ||
| 1032 | <para>For the sake of implementation simplicity, this command requires read/write | ||
| 1033 | access to the device.</para> | ||
| 1034 | </entry> | ||
| 1035 | </row></tbody></tgroup></informaltable> | ||
| 1036 | |||
| 1037 | <para>SYNOPSIS | ||
| 1038 | </para> | ||
| 1039 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1040 | align="char"> | ||
| 1041 | <para>int ioctl(int fd, int request = QPSK_GET_EVENT, | ||
| 1042 | struct dvb_frontend_event ⋆ev);</para> | ||
| 1043 | </entry> | ||
| 1044 | </row></tbody></tgroup></informaltable> | ||
| 1045 | |||
| 1046 | <para>PARAMETERS | ||
| 1047 | </para> | ||
| 1048 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1049 | align="char"> | ||
| 1050 | <para>int fd</para> | ||
| 1051 | </entry><entry | ||
| 1052 | align="char"> | ||
| 1053 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1054 | </entry> | ||
| 1055 | </row><row><entry | ||
| 1056 | align="char"> | ||
| 1057 | <para>int request</para> | ||
| 1058 | </entry><entry | ||
| 1059 | align="char"> | ||
| 1060 | <para>Equals FE_GET_EVENT for this command.</para> | ||
| 1061 | </entry> | ||
| 1062 | </row><row><entry | ||
| 1063 | align="char"> | ||
| 1064 | <para>struct | ||
| 1065 | dvb_frontend_event | ||
| 1066 | *ev</para> | ||
| 1067 | </entry><entry | ||
| 1068 | align="char"> | ||
| 1069 | <para>Points to the location where the event,</para> | ||
| 1070 | </entry> | ||
| 1071 | </row><row><entry | ||
| 1072 | align="char"> | ||
| 1073 | </entry><entry | ||
| 1074 | align="char"> | ||
| 1075 | <para>if any, is to be stored.</para> | ||
| 1076 | </entry> | ||
| 1077 | </row></tbody></tgroup></informaltable> | ||
| 1078 | |||
| 1079 | <para>ERRORS | ||
| 1080 | </para> | ||
| 1081 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1082 | align="char"> | ||
| 1083 | <para>EBADF</para> | ||
| 1084 | </entry><entry | ||
| 1085 | align="char"> | ||
| 1086 | <para>fd is not a valid open file descriptor.</para> | ||
| 1087 | </entry> | ||
| 1088 | </row><row><entry | ||
| 1089 | align="char"> | ||
| 1090 | <para>EFAULT</para> | ||
| 1091 | </entry><entry | ||
| 1092 | align="char"> | ||
| 1093 | <para>ev points to invalid address.</para> | ||
| 1094 | </entry> | ||
| 1095 | </row><row><entry | ||
| 1096 | align="char"> | ||
| 1097 | <para>EWOULDBLOCK</para> | ||
| 1098 | </entry><entry | ||
| 1099 | align="char"> | ||
| 1100 | <para>There is no event pending, and the device is in | ||
| 1101 | non-blocking mode.</para> | ||
| 1102 | </entry> | ||
| 1103 | </row><row><entry | ||
| 1104 | align="char"> | ||
| 1105 | <para>EOVERFLOW</para> | ||
| 1106 | </entry><entry | ||
| 1107 | align="char"> | ||
| 1108 | </entry> | ||
| 1109 | </row><row><entry | ||
| 1110 | align="char"> | ||
| 1111 | </entry><entry | ||
| 1112 | align="char"> | ||
| 1113 | <para>Overflow in event queue - one or more events were lost.</para> | ||
| 1114 | </entry> | ||
| 1115 | </row></tbody></tgroup></informaltable> | ||
| 1116 | </section> | ||
| 1117 | |||
| 1118 | <section id="frontend_get_info"> | ||
| 1119 | <title>FE_GET_INFO</title> | ||
| 1120 | <para>DESCRIPTION | ||
| 1121 | </para> | ||
| 1122 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1123 | align="char"> | ||
| 1124 | <para>This ioctl call returns information about the front-end. This call only requires | ||
| 1125 | read-only access to the device.</para> | ||
| 1126 | </entry> | ||
| 1127 | </row></tbody></tgroup></informaltable> | ||
| 1128 | <para>SYNOPSIS | ||
| 1129 | </para> | ||
| 1130 | |||
| 1131 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1132 | align="char"> | ||
| 1133 | <para> int ioctl(int fd, int request = FE_GET_INFO, struct | ||
| 1134 | dvb_frontend_info ⋆info);</para> | ||
| 1135 | </entry> | ||
| 1136 | </row></tbody></tgroup></informaltable> | ||
| 1137 | <para>PARAMETERS | ||
| 1138 | </para> | ||
| 1139 | |||
| 1140 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1141 | align="char"> | ||
| 1142 | <para>int fd</para> | ||
| 1143 | </entry><entry | ||
| 1144 | align="char"> | ||
| 1145 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1146 | </entry> | ||
| 1147 | </row><row><entry | ||
| 1148 | align="char"> | ||
| 1149 | <para>int request</para> | ||
| 1150 | </entry><entry | ||
| 1151 | align="char"> | ||
| 1152 | <para>Equals FE_GET_INFO for this command.</para> | ||
| 1153 | </entry> | ||
| 1154 | </row><row><entry | ||
| 1155 | align="char"> | ||
| 1156 | <para>struct | ||
| 1157 | dvb_frontend_info | ||
| 1158 | *info</para> | ||
| 1159 | </entry><entry | ||
| 1160 | align="char"> | ||
| 1161 | <para>Points to the location where the front-end information is | ||
| 1162 | to be stored.</para> | ||
| 1163 | </entry> | ||
| 1164 | </row></tbody></tgroup></informaltable> | ||
| 1165 | <para>ERRORS | ||
| 1166 | </para> | ||
| 1167 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1168 | align="char"> | ||
| 1169 | <para>EBADF</para> | ||
| 1170 | </entry><entry | ||
| 1171 | align="char"> | ||
| 1172 | <para>fd is not a valid open file descriptor.</para> | ||
| 1173 | </entry> | ||
| 1174 | </row><row><entry | ||
| 1175 | align="char"> | ||
| 1176 | <para>EFAULT</para> | ||
| 1177 | </entry><entry | ||
| 1178 | align="char"> | ||
| 1179 | <para>info points to invalid address.</para> | ||
| 1180 | </entry> | ||
| 1181 | </row></tbody></tgroup></informaltable> | ||
| 1182 | </section> | ||
| 1183 | |||
| 1184 | <section id="frontend_diseqc_reset_overload"> | ||
| 1185 | <title>FE_DISEQC_RESET_OVERLOAD</title> | ||
| 1186 | <para>DESCRIPTION | ||
| 1187 | </para> | ||
| 1188 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1189 | align="char"> | ||
| 1190 | <para>If the bus has been automatically powered off due to power overload, this ioctl | ||
| 1191 | call restores the power to the bus. The call requires read/write access to the | ||
| 1192 | device. This call has no effect if the device is manually powered off. Not all | ||
| 1193 | DVB adapters support this ioctl.</para> | ||
| 1194 | </entry> | ||
| 1195 | </row></tbody></tgroup></informaltable> | ||
| 1196 | |||
| 1197 | <para>SYNOPSIS | ||
| 1198 | </para> | ||
| 1199 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1200 | align="char"> | ||
| 1201 | <para>int ioctl(int fd, int request = | ||
| 1202 | FE_DISEQC_RESET_OVERLOAD);</para> | ||
| 1203 | </entry> | ||
| 1204 | </row></tbody></tgroup></informaltable> | ||
| 1205 | <para>PARAMETERS | ||
| 1206 | </para> | ||
| 1207 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1208 | align="char"> | ||
| 1209 | <para>int fd</para> | ||
| 1210 | </entry><entry | ||
| 1211 | align="char"> | ||
| 1212 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1213 | </entry> | ||
| 1214 | </row><row><entry | ||
| 1215 | align="char"> | ||
| 1216 | <para>int request</para> | ||
| 1217 | </entry><entry | ||
| 1218 | align="char"> | ||
| 1219 | <para>Equals FE_DISEQC_RESET_OVERLOAD for this | ||
| 1220 | command.</para> | ||
| 1221 | </entry> | ||
| 1222 | </row></tbody></tgroup></informaltable> | ||
| 1223 | |||
| 1224 | <para>ERRORS | ||
| 1225 | </para> | ||
| 1226 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1227 | align="char"> | ||
| 1228 | <para>EBADF</para> | ||
| 1229 | </entry><entry | ||
| 1230 | align="char"> | ||
| 1231 | <para>fd is not a valid file descriptor.</para> | ||
| 1232 | </entry> | ||
| 1233 | </row><row><entry | ||
| 1234 | align="char"> | ||
| 1235 | <para>EPERM</para> | ||
| 1236 | </entry><entry | ||
| 1237 | align="char"> | ||
| 1238 | <para>Permission denied (needs read/write access).</para> | ||
| 1239 | </entry> | ||
| 1240 | </row><row><entry | ||
| 1241 | align="char"> | ||
| 1242 | <para>EINTERNAL</para> | ||
| 1243 | </entry><entry | ||
| 1244 | align="char"> | ||
| 1245 | <para>Internal error in the device driver.</para> | ||
| 1246 | </entry> | ||
| 1247 | </row></tbody></tgroup></informaltable> | ||
| 1248 | </section> | ||
| 1249 | |||
| 1250 | <section id="frontend_diseqc_send_master_cmd"> | ||
| 1251 | <title>FE_DISEQC_SEND_MASTER_CMD</title> | ||
| 1252 | <para>DESCRIPTION | ||
| 1253 | </para> | ||
| 1254 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1255 | align="char"> | ||
| 1256 | <para>This ioctl call is used to send a a DiSEqC command.</para> | ||
| 1257 | </entry> | ||
| 1258 | </row></tbody></tgroup></informaltable> | ||
| 1259 | <para>SYNOPSIS | ||
| 1260 | </para> | ||
| 1261 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1262 | align="char"> | ||
| 1263 | <para>int ioctl(int fd, int request = | ||
| 1264 | FE_DISEQC_SEND_MASTER_CMD, struct | ||
| 1265 | dvb_diseqc_master_cmd ⋆cmd);</para> | ||
| 1266 | </entry> | ||
| 1267 | </row></tbody></tgroup></informaltable> | ||
| 1268 | |||
| 1269 | <para>PARAMETERS | ||
| 1270 | </para> | ||
| 1271 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1272 | align="char"> | ||
| 1273 | <para>int fd</para> | ||
| 1274 | </entry><entry | ||
| 1275 | align="char"> | ||
| 1276 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1277 | </entry> | ||
| 1278 | </row><row><entry | ||
| 1279 | align="char"> | ||
| 1280 | <para>int request</para> | ||
| 1281 | </entry><entry | ||
| 1282 | align="char"> | ||
| 1283 | <para>Equals FE_DISEQC_SEND_MASTER_CMD for this | ||
| 1284 | command.</para> | ||
| 1285 | </entry> | ||
| 1286 | </row><row><entry | ||
| 1287 | align="char"> | ||
| 1288 | <para>struct | ||
| 1289 | dvb_diseqc_master_cmd | ||
| 1290 | *cmd</para> | ||
| 1291 | </entry><entry | ||
| 1292 | align="char"> | ||
| 1293 | <para>Pointer to the command to be transmitted.</para> | ||
| 1294 | </entry> | ||
| 1295 | </row></tbody></tgroup></informaltable> | ||
| 1296 | |||
| 1297 | <para>ERRORS | ||
| 1298 | </para> | ||
| 1299 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1300 | align="char"> | ||
| 1301 | <para>EBADF</para> | ||
| 1302 | </entry><entry | ||
| 1303 | align="char"> | ||
| 1304 | <para>fd is not a valid file descriptor.</para> | ||
| 1305 | </entry> | ||
| 1306 | </row><row><entry | ||
| 1307 | align="char"> | ||
| 1308 | <para>EFAULT</para> | ||
| 1309 | </entry><entry | ||
| 1310 | align="char"> | ||
| 1311 | <para>Seq points to an invalid address.</para> | ||
| 1312 | </entry> | ||
| 1313 | </row><row><entry | ||
| 1314 | align="char"> | ||
| 1315 | <para>EINVAL</para> | ||
| 1316 | </entry><entry | ||
| 1317 | align="char"> | ||
| 1318 | <para>The data structure referred to by seq is invalid in some | ||
| 1319 | way.</para> | ||
| 1320 | </entry> | ||
| 1321 | </row><row><entry | ||
| 1322 | align="char"> | ||
| 1323 | <para>EPERM</para> | ||
| 1324 | </entry><entry | ||
| 1325 | align="char"> | ||
| 1326 | <para>Permission denied (needs read/write access).</para> | ||
| 1327 | </entry> | ||
| 1328 | </row><row><entry | ||
| 1329 | align="char"> | ||
| 1330 | <para>EINTERNAL</para> | ||
| 1331 | </entry><entry | ||
| 1332 | align="char"> | ||
| 1333 | <para>Internal error in the device driver.</para> | ||
| 1334 | </entry> | ||
| 1335 | </row></tbody></tgroup></informaltable> | ||
| 1336 | </section> | ||
| 1337 | |||
| 1338 | <section id="frontend_diseqc_recv_slave_reply"> | ||
| 1339 | <title>FE_DISEQC_RECV_SLAVE_REPLY</title> | ||
| 1340 | <para>DESCRIPTION | ||
| 1341 | </para> | ||
| 1342 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1343 | align="char"> | ||
| 1344 | <para>This ioctl call is used to receive reply to a DiSEqC 2.0 command.</para> | ||
| 1345 | </entry> | ||
| 1346 | </row></tbody></tgroup></informaltable> | ||
| 1347 | |||
| 1348 | <para>SYNOPSIS | ||
| 1349 | </para> | ||
| 1350 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1351 | align="char"> | ||
| 1352 | <para>int ioctl(int fd, int request = | ||
| 1353 | FE_DISEQC_RECV_SLAVE_REPLY, struct | ||
| 1354 | dvb_diseqc_slave_reply ⋆reply);</para> | ||
| 1355 | </entry> | ||
| 1356 | </row></tbody></tgroup></informaltable> | ||
| 1357 | |||
| 1358 | <para>PARAMETERS | ||
| 1359 | </para> | ||
| 1360 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1361 | align="char"> | ||
| 1362 | <para>int fd</para> | ||
| 1363 | </entry><entry | ||
| 1364 | align="char"> | ||
| 1365 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1366 | </entry> | ||
| 1367 | </row><row><entry | ||
| 1368 | align="char"> | ||
| 1369 | <para>int request</para> | ||
| 1370 | </entry><entry | ||
| 1371 | align="char"> | ||
| 1372 | <para>Equals FE_DISEQC_RECV_SLAVE_REPLY for this | ||
| 1373 | command.</para> | ||
| 1374 | </entry> | ||
| 1375 | </row><row><entry | ||
| 1376 | align="char"> | ||
| 1377 | <para>struct | ||
| 1378 | dvb_diseqc_slave_reply | ||
| 1379 | *reply</para> | ||
| 1380 | </entry><entry | ||
| 1381 | align="char"> | ||
| 1382 | <para>Pointer to the command to be received.</para> | ||
| 1383 | </entry> | ||
| 1384 | </row></tbody></tgroup></informaltable> | ||
| 1385 | <para>ERRORS | ||
| 1386 | </para> | ||
| 1387 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1388 | align="char"> | ||
| 1389 | <para>EBADF</para> | ||
| 1390 | </entry><entry | ||
| 1391 | align="char"> | ||
| 1392 | <para>fd is not a valid file descriptor.</para> | ||
| 1393 | </entry> | ||
| 1394 | </row><row><entry | ||
| 1395 | align="char"> | ||
| 1396 | <para>EFAULT</para> | ||
| 1397 | </entry><entry | ||
| 1398 | align="char"> | ||
| 1399 | <para>Seq points to an invalid address.</para> | ||
| 1400 | </entry> | ||
| 1401 | </row><row><entry | ||
| 1402 | align="char"> | ||
| 1403 | <para>EINVAL</para> | ||
| 1404 | </entry><entry | ||
| 1405 | align="char"> | ||
| 1406 | <para>The data structure referred to by seq is invalid in some | ||
| 1407 | way.</para> | ||
| 1408 | </entry> | ||
| 1409 | </row><row><entry | ||
| 1410 | align="char"> | ||
| 1411 | <para>EPERM</para> | ||
| 1412 | </entry><entry | ||
| 1413 | align="char"> | ||
| 1414 | <para>Permission denied (needs read/write access).</para> | ||
| 1415 | </entry> | ||
| 1416 | </row><row><entry | ||
| 1417 | align="char"> | ||
| 1418 | <para>EINTERNAL</para> | ||
| 1419 | </entry><entry | ||
| 1420 | align="char"> | ||
| 1421 | <para>Internal error in the device driver.</para> | ||
| 1422 | </entry> | ||
| 1423 | </row></tbody></tgroup></informaltable> | ||
| 1424 | </section> | ||
| 1425 | |||
| 1426 | <section id="frontend_diseqc_send_burst"> | ||
| 1427 | <title>FE_DISEQC_SEND_BURST</title> | ||
| 1428 | <para>DESCRIPTION | ||
| 1429 | </para> | ||
| 1430 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1431 | align="char"> | ||
| 1432 | <para>This ioctl call is used to send a 22KHz tone burst.</para> | ||
| 1433 | </entry> | ||
| 1434 | </row></tbody></tgroup></informaltable> | ||
| 1435 | |||
| 1436 | <para>SYNOPSIS | ||
| 1437 | </para> | ||
| 1438 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1439 | align="char"> | ||
| 1440 | <para>int ioctl(int fd, int request = | ||
| 1441 | FE_DISEQC_SEND_BURST, fe_sec_mini_cmd_t burst);</para> | ||
| 1442 | </entry> | ||
| 1443 | </row></tbody></tgroup></informaltable> | ||
| 1444 | |||
| 1445 | <para>PARAMETERS | ||
| 1446 | </para> | ||
| 1447 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1448 | align="char"> | ||
| 1449 | <para>int fd</para> | ||
| 1450 | </entry><entry | ||
| 1451 | align="char"> | ||
| 1452 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1453 | </entry> | ||
| 1454 | </row><row><entry | ||
| 1455 | align="char"> | ||
| 1456 | <para>int request</para> | ||
| 1457 | </entry><entry | ||
| 1458 | align="char"> | ||
| 1459 | <para>Equals FE_DISEQC_SEND_BURST for this command.</para> | ||
| 1460 | </entry> | ||
| 1461 | </row><row><entry | ||
| 1462 | align="char"> | ||
| 1463 | <para>fe_sec_mini_cmd_t | ||
| 1464 | burst</para> | ||
| 1465 | </entry><entry | ||
| 1466 | align="char"> | ||
| 1467 | <para>burst A or B.</para> | ||
| 1468 | </entry> | ||
| 1469 | </row></tbody></tgroup></informaltable> | ||
| 1470 | |||
| 1471 | <para>ERRORS | ||
| 1472 | </para> | ||
| 1473 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1474 | align="char"> | ||
| 1475 | <para>EBADF</para> | ||
| 1476 | </entry><entry | ||
| 1477 | align="char"> | ||
| 1478 | <para>fd is not a valid file descriptor.</para> | ||
| 1479 | </entry> | ||
| 1480 | </row><row><entry | ||
| 1481 | align="char"> | ||
| 1482 | <para>EFAULT</para> | ||
| 1483 | </entry><entry | ||
| 1484 | align="char"> | ||
| 1485 | <para>Seq points to an invalid address.</para> | ||
| 1486 | </entry> | ||
| 1487 | </row><row><entry | ||
| 1488 | align="char"> | ||
| 1489 | <para>EINVAL</para> | ||
| 1490 | </entry><entry | ||
| 1491 | align="char"> | ||
| 1492 | <para>The data structure referred to by seq is invalid in some | ||
| 1493 | way.</para> | ||
| 1494 | </entry> | ||
| 1495 | </row><row><entry | ||
| 1496 | align="char"> | ||
| 1497 | <para>EPERM</para> | ||
| 1498 | </entry><entry | ||
| 1499 | align="char"> | ||
| 1500 | <para>Permission denied (needs read/write access).</para> | ||
| 1501 | </entry> | ||
| 1502 | </row><row><entry | ||
| 1503 | align="char"> | ||
| 1504 | <para>EINTERNAL</para> | ||
| 1505 | </entry><entry | ||
| 1506 | align="char"> | ||
| 1507 | <para>Internal error in the device driver.</para> | ||
| 1508 | </entry> | ||
| 1509 | </row></tbody></tgroup></informaltable> | ||
| 1510 | </section> | ||
| 1511 | |||
| 1512 | <section id="frontend_set_tone"> | ||
| 1513 | <title>FE_SET_TONE</title> | ||
| 1514 | <para>DESCRIPTION | ||
| 1515 | </para> | ||
| 1516 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1517 | align="char"> | ||
| 1518 | <para>This call is used to set the generation of the continuous 22kHz tone. This call | ||
| 1519 | requires read/write permissions.</para> | ||
| 1520 | </entry> | ||
| 1521 | </row></tbody></tgroup></informaltable> | ||
| 1522 | <para>SYNOPSIS | ||
| 1523 | </para> | ||
| 1524 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1525 | align="char"> | ||
| 1526 | <para>int ioctl(int fd, int request = FE_SET_TONE, | ||
| 1527 | fe_sec_tone_mode_t tone);</para> | ||
| 1528 | </entry> | ||
| 1529 | </row></tbody></tgroup></informaltable> | ||
| 1530 | <para>PARAMETERS | ||
| 1531 | </para> | ||
| 1532 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1533 | align="char"> | ||
| 1534 | <para>int fd</para> | ||
| 1535 | </entry><entry | ||
| 1536 | align="char"> | ||
| 1537 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1538 | </entry> | ||
| 1539 | </row><row><entry | ||
| 1540 | align="char"> | ||
| 1541 | <para>int request</para> | ||
| 1542 | </entry><entry | ||
| 1543 | align="char"> | ||
| 1544 | <para>Equals FE_SET_TONE for this command.</para> | ||
| 1545 | </entry> | ||
| 1546 | </row><row><entry | ||
| 1547 | align="char"> | ||
| 1548 | <para>fe_sec_tone_mode_t | ||
| 1549 | tone</para> | ||
| 1550 | </entry><entry | ||
| 1551 | align="char"> | ||
| 1552 | <para>The requested tone generation mode (on/off).</para> | ||
| 1553 | </entry> | ||
| 1554 | </row></tbody></tgroup></informaltable> | ||
| 1555 | <para>ERRORS | ||
| 1556 | </para> | ||
| 1557 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1558 | align="char"> | ||
| 1559 | <para>ENODEV</para> | ||
| 1560 | </entry><entry | ||
| 1561 | align="char"> | ||
| 1562 | <para>Device driver not loaded/available.</para> | ||
| 1563 | </entry> | ||
| 1564 | </row><row><entry | ||
| 1565 | align="char"> | ||
| 1566 | <para>EBUSY</para> | ||
| 1567 | </entry><entry | ||
| 1568 | align="char"> | ||
| 1569 | <para>Device or resource busy.</para> | ||
| 1570 | </entry> | ||
| 1571 | </row><row><entry | ||
| 1572 | align="char"> | ||
| 1573 | <para>EINVAL</para> | ||
| 1574 | </entry><entry | ||
| 1575 | align="char"> | ||
| 1576 | <para>Invalid argument.</para> | ||
| 1577 | </entry> | ||
| 1578 | </row><row><entry | ||
| 1579 | align="char"> | ||
| 1580 | <para>EPERM</para> | ||
| 1581 | </entry><entry | ||
| 1582 | align="char"> | ||
| 1583 | <para>File not opened with read permissions.</para> | ||
| 1584 | </entry> | ||
| 1585 | </row><row><entry | ||
| 1586 | align="char"> | ||
| 1587 | <para>EINTERNAL</para> | ||
| 1588 | </entry><entry | ||
| 1589 | align="char"> | ||
| 1590 | <para>Internal error in the device driver.</para> | ||
| 1591 | </entry> | ||
| 1592 | </row></tbody></tgroup></informaltable> | ||
| 1593 | </section> | ||
| 1594 | |||
| 1595 | <section id="fe_set_voltage"> | ||
| 1596 | <title>FE_SET_VOLTAGE</title> | ||
| 1597 | <para>DESCRIPTION | ||
| 1598 | </para> | ||
| 1599 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1600 | align="char"> | ||
| 1601 | <para>This call is used to set the bus voltage. This call requires read/write | ||
| 1602 | permissions.</para> | ||
| 1603 | </entry> | ||
| 1604 | </row></tbody></tgroup></informaltable> | ||
| 1605 | <para>SYNOPSIS | ||
| 1606 | </para> | ||
| 1607 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1608 | align="char"> | ||
| 1609 | <para>int ioctl(int fd, int request = FE_SET_VOLTAGE, | ||
| 1610 | fe_sec_voltage_t voltage);</para> | ||
| 1611 | </entry> | ||
| 1612 | </row></tbody></tgroup></informaltable> | ||
| 1613 | |||
| 1614 | <para>PARAMETERS | ||
| 1615 | </para> | ||
| 1616 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1617 | align="char"> | ||
| 1618 | <para>int fd</para> | ||
| 1619 | </entry><entry | ||
| 1620 | align="char"> | ||
| 1621 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1622 | </entry> | ||
| 1623 | </row><row><entry | ||
| 1624 | align="char"> | ||
| 1625 | <para>int request</para> | ||
| 1626 | </entry><entry | ||
| 1627 | align="char"> | ||
| 1628 | <para>Equals FE_SET_VOLTAGE for this command.</para> | ||
| 1629 | </entry> | ||
| 1630 | </row><row><entry | ||
| 1631 | align="char"> | ||
| 1632 | <para>fe_sec_voltage_t | ||
| 1633 | voltage</para> | ||
| 1634 | </entry><entry | ||
| 1635 | align="char"> | ||
| 1636 | <para>The requested bus voltage.</para> | ||
| 1637 | </entry> | ||
| 1638 | </row></tbody></tgroup></informaltable> | ||
| 1639 | |||
| 1640 | <para>ERRORS | ||
| 1641 | </para> | ||
| 1642 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1643 | align="char"> | ||
| 1644 | <para>ENODEV</para> | ||
| 1645 | </entry><entry | ||
| 1646 | align="char"> | ||
| 1647 | <para>Device driver not loaded/available.</para> | ||
| 1648 | </entry> | ||
| 1649 | </row><row><entry | ||
| 1650 | align="char"> | ||
| 1651 | <para>EBUSY</para> | ||
| 1652 | </entry><entry | ||
| 1653 | align="char"> | ||
| 1654 | <para>Device or resource busy.</para> | ||
| 1655 | </entry> | ||
| 1656 | </row><row><entry | ||
| 1657 | align="char"> | ||
| 1658 | <para>EINVAL</para> | ||
| 1659 | </entry><entry | ||
| 1660 | align="char"> | ||
| 1661 | <para>Invalid argument.</para> | ||
| 1662 | </entry> | ||
| 1663 | </row><row><entry | ||
| 1664 | align="char"> | ||
| 1665 | <para>EPERM</para> | ||
| 1666 | </entry><entry | ||
| 1667 | align="char"> | ||
| 1668 | <para>File not opened with read permissions.</para> | ||
| 1669 | </entry> | ||
| 1670 | </row><row><entry | ||
| 1671 | align="char"> | ||
| 1672 | <para>EINTERNAL</para> | ||
| 1673 | </entry><entry | ||
| 1674 | align="char"> | ||
| 1675 | <para>Internal error in the device driver.</para> | ||
| 1676 | </entry> | ||
| 1677 | </row></tbody></tgroup></informaltable> | ||
| 1678 | </section> | ||
| 1679 | |||
| 1680 | <section id="frontend_enable_high_lnb_volt"> | ||
| 1681 | <title>FE_ENABLE_HIGH_LNB_VOLTAGE</title> | ||
| 1682 | <para>DESCRIPTION | ||
| 1683 | </para> | ||
| 1684 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1685 | align="char"> | ||
| 1686 | <para>If high != 0 enables slightly higher voltages instead of 13/18V (to compensate | ||
| 1687 | for long cables). This call requires read/write permissions. Not all DVB | ||
| 1688 | adapters support this ioctl.</para> | ||
| 1689 | </entry> | ||
| 1690 | </row></tbody></tgroup></informaltable> | ||
| 1691 | |||
| 1692 | <para>SYNOPSIS | ||
| 1693 | </para> | ||
| 1694 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1695 | align="char"> | ||
| 1696 | <para>int ioctl(int fd, int request = | ||
| 1697 | FE_ENABLE_HIGH_LNB_VOLTAGE, int high);</para> | ||
| 1698 | </entry> | ||
| 1699 | </row></tbody></tgroup></informaltable> | ||
| 1700 | |||
| 1701 | <para>PARAMETERS | ||
| 1702 | </para> | ||
| 1703 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1704 | align="char"> | ||
| 1705 | <para>int fd</para> | ||
| 1706 | </entry><entry | ||
| 1707 | align="char"> | ||
| 1708 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1709 | </entry> | ||
| 1710 | </row><row><entry | ||
| 1711 | align="char"> | ||
| 1712 | <para>int request</para> | ||
| 1713 | </entry><entry | ||
| 1714 | align="char"> | ||
| 1715 | <para>Equals FE_SET_VOLTAGE for this command.</para> | ||
| 1716 | </entry> | ||
| 1717 | </row><row><entry | ||
| 1718 | align="char"> | ||
| 1719 | <para>int high</para> | ||
| 1720 | </entry><entry | ||
| 1721 | align="char"> | ||
| 1722 | <para>The requested bus voltage.</para> | ||
| 1723 | </entry> | ||
| 1724 | </row></tbody></tgroup></informaltable> | ||
| 1725 | |||
| 1726 | <para>ERRORS | ||
| 1727 | </para> | ||
| 1728 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1729 | align="char"> | ||
| 1730 | <para>ENODEV</para> | ||
| 1731 | </entry><entry | ||
| 1732 | align="char"> | ||
| 1733 | <para>Device driver not loaded/available.</para> | ||
| 1734 | </entry> | ||
| 1735 | </row><row><entry | ||
| 1736 | align="char"> | ||
| 1737 | <para>EBUSY</para> | ||
| 1738 | </entry><entry | ||
| 1739 | align="char"> | ||
| 1740 | <para>Device or resource busy.</para> | ||
| 1741 | </entry> | ||
| 1742 | </row><row><entry | ||
| 1743 | align="char"> | ||
| 1744 | <para>EINVAL</para> | ||
| 1745 | </entry><entry | ||
| 1746 | align="char"> | ||
| 1747 | <para>Invalid argument.</para> | ||
| 1748 | </entry> | ||
| 1749 | </row><row><entry | ||
| 1750 | align="char"> | ||
| 1751 | <para>EPERM</para> | ||
| 1752 | </entry><entry | ||
| 1753 | align="char"> | ||
| 1754 | <para>File not opened with read permissions.</para> | ||
| 1755 | </entry> | ||
| 1756 | </row><row><entry | ||
| 1757 | align="char"> | ||
| 1758 | <para>EINTERNAL</para> | ||
| 1759 | </entry><entry | ||
| 1760 | align="char"> | ||
| 1761 | <para>Internal error in the device driver.</para> | ||
| 1762 | </entry> | ||
| 1763 | </row></tbody></tgroup></informaltable> | ||
| 1764 | </section> | ||
| 1765 | </section> | ||
| 1766 | &sub-isdbt; | ||
diff --git a/Documentation/DocBook/dvb/intro.xml b/Documentation/DocBook/dvb/intro.xml new file mode 100644 index 000000000000..0dc83f672ea2 --- /dev/null +++ b/Documentation/DocBook/dvb/intro.xml | |||
| @@ -0,0 +1,191 @@ | |||
| 1 | <title>Introduction</title> | ||
| 2 | |||
| 3 | <section id="requisites"> | ||
| 4 | <title>What you need to know</title> | ||
| 5 | |||
| 6 | <para>The reader of this document is required to have some knowledge in | ||
| 7 | the area of digital video broadcasting (DVB) and should be familiar with | ||
| 8 | part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e | ||
| 9 | you should know what a program/transport stream (PS/TS) is and what is | ||
| 10 | meant by a packetized elementary stream (PES) or an I-frame.</para> | ||
| 11 | |||
| 12 | <para>Various DVB standards documents are available from | ||
| 13 | <ulink url="http://www.dvb.org" /> and/or | ||
| 14 | <ulink url="http://www.etsi.org" />.</para> | ||
| 15 | |||
| 16 | <para>It is also necessary to know how to access unix/linux devices and | ||
| 17 | how to use ioctl calls. This also includes the knowledge of C or C++. | ||
| 18 | </para> | ||
| 19 | </section> | ||
| 20 | |||
| 21 | <section id="history"> | ||
| 22 | <title>History</title> | ||
| 23 | |||
| 24 | <para>The first API for DVB cards we used at Convergence in late 1999 | ||
| 25 | was an extension of the Video4Linux API which was primarily developed | ||
| 26 | for frame grabber cards. As such it was not really well suited to be | ||
| 27 | used for DVB cards and their new features like recording MPEG streams | ||
| 28 | and filtering several section and PES data streams at the same time. | ||
| 29 | </para> | ||
| 30 | |||
| 31 | <para>In early 2000, we were approached by Nokia with a proposal for a | ||
| 32 | new standard Linux DVB API. As a commitment to the development of | ||
| 33 | terminals based on open standards, Nokia and Convergence made it | ||
| 34 | available to all Linux developers and published it on | ||
| 35 | <ulink url="http://www.linuxtv.org/" /> in September 2000. | ||
| 36 | Convergence is the maintainer of the Linux DVB API. Together with the | ||
| 37 | LinuxTV community (i.e. you, the reader of this document), the Linux DVB | ||
| 38 | API will be constantly reviewed and improved. With the Linux driver for | ||
| 39 | the Siemens/Hauppauge DVB PCI card Convergence provides a first | ||
| 40 | implementation of the Linux DVB API.</para> | ||
| 41 | </section> | ||
| 42 | |||
| 43 | <section id="overview"> | ||
| 44 | <title>Overview</title> | ||
| 45 | |||
| 46 | <figure id="stb_components"> | ||
| 47 | <title>Components of a DVB card/STB</title> | ||
| 48 | <mediaobject> | ||
| 49 | <imageobject> | ||
| 50 | <imagedata fileref="dvbstb.pdf" format="PS" /> | ||
| 51 | </imageobject> | ||
| 52 | <imageobject> | ||
| 53 | <imagedata fileref="dvbstb.png" format="PNG" /> | ||
| 54 | </imageobject> | ||
| 55 | </mediaobject> | ||
| 56 | </figure> | ||
| 57 | |||
| 58 | <para>A DVB PCI card or DVB set-top-box (STB) usually consists of the | ||
| 59 | following main hardware components: </para> | ||
| 60 | |||
| 61 | <itemizedlist> | ||
| 62 | <listitem> | ||
| 63 | |||
| 64 | <para>Frontend consisting of tuner and DVB demodulator</para> | ||
| 65 | |||
| 66 | <para>Here the raw signal reaches the DVB hardware from a satellite dish | ||
| 67 | or antenna or directly from cable. The frontend down-converts and | ||
| 68 | demodulates this signal into an MPEG transport stream (TS). In case of a | ||
| 69 | satellite frontend, this includes a facility for satellite equipment | ||
| 70 | control (SEC), which allows control of LNB polarization, multi feed | ||
| 71 | switches or dish rotors.</para> | ||
| 72 | |||
| 73 | </listitem> | ||
| 74 | <listitem> | ||
| 75 | |||
| 76 | <para>Conditional Access (CA) hardware like CI adapters and smartcard slots | ||
| 77 | </para> | ||
| 78 | |||
| 79 | <para>The complete TS is passed through the CA hardware. Programs to | ||
| 80 | which the user has access (controlled by the smart card) are decoded in | ||
| 81 | real time and re-inserted into the TS.</para> | ||
| 82 | |||
| 83 | </listitem> | ||
| 84 | <listitem> | ||
| 85 | <para>Demultiplexer which filters the incoming DVB stream</para> | ||
| 86 | |||
| 87 | <para>The demultiplexer splits the TS into its components like audio and | ||
| 88 | video streams. Besides usually several of such audio and video streams | ||
| 89 | it also contains data streams with information about the programs | ||
| 90 | offered in this or other streams of the same provider.</para> | ||
| 91 | |||
| 92 | </listitem> | ||
| 93 | <listitem> | ||
| 94 | |||
| 95 | <para>MPEG2 audio and video decoder</para> | ||
| 96 | |||
| 97 | <para>The main targets of the demultiplexer are the MPEG2 audio and | ||
| 98 | video decoders. After decoding they pass on the uncompressed audio and | ||
| 99 | video to the computer screen or (through a PAL/NTSC encoder) to a TV | ||
| 100 | set.</para> | ||
| 101 | |||
| 102 | |||
| 103 | </listitem> | ||
| 104 | </itemizedlist> | ||
| 105 | |||
| 106 | <para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow | ||
| 107 | between those components.</para> | ||
| 108 | |||
| 109 | <para>On a DVB PCI card not all of these have to be present since some | ||
| 110 | functionality can be provided by the main CPU of the PC (e.g. MPEG | ||
| 111 | picture and sound decoding) or is not needed (e.g. for data-only uses | ||
| 112 | like “internet over satellite”). Also not every card or STB | ||
| 113 | provides conditional access hardware.</para> | ||
| 114 | |||
| 115 | </section> | ||
| 116 | |||
| 117 | <section id="dvb_devices"> | ||
| 118 | <title>Linux DVB Devices</title> | ||
| 119 | |||
| 120 | <para>The Linux DVB API lets you control these hardware components | ||
| 121 | through currently six Unix-style character devices for video, audio, | ||
| 122 | frontend, demux, CA and IP-over-DVB networking. The video and audio | ||
| 123 | devices control the MPEG2 decoder hardware, the frontend device the | ||
| 124 | tuner and the DVB demodulator. The demux device gives you control over | ||
| 125 | the PES and section filters of the hardware. If the hardware does not | ||
| 126 | support filtering these filters can be implemented in software. Finally, | ||
| 127 | the CA device controls all the conditional access capabilities of the | ||
| 128 | hardware. It can depend on the individual security requirements of the | ||
| 129 | platform, if and how many of the CA functions are made available to the | ||
| 130 | application through this device.</para> | ||
| 131 | |||
| 132 | <para>All devices can be found in the <emphasis role="tt">/dev</emphasis> | ||
| 133 | tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices | ||
| 134 | are called:</para> | ||
| 135 | |||
| 136 | <itemizedlist> | ||
| 137 | <listitem> | ||
| 138 | |||
| 139 | <para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>,</para> | ||
| 140 | </listitem> | ||
| 141 | <listitem> | ||
| 142 | <para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>,</para> | ||
| 143 | </listitem> | ||
| 144 | <listitem> | ||
| 145 | <para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>,</para> | ||
| 146 | </listitem> | ||
| 147 | <listitem> | ||
| 148 | |||
| 149 | <para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>,</para> | ||
| 150 | </listitem> | ||
| 151 | <listitem> | ||
| 152 | |||
| 153 | <para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>,</para> | ||
| 154 | </listitem> | ||
| 155 | <listitem> | ||
| 156 | |||
| 157 | <para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist> | ||
| 158 | |||
| 159 | <para>where N enumerates the DVB PCI cards in a system starting | ||
| 160 | from 0, and M enumerates the devices of each type within each | ||
| 161 | adapter, starting from 0, too. We will omit the “<emphasis | ||
| 162 | role="tt">/dev/dvb/adapterN/</emphasis>” in the further dicussion | ||
| 163 | of these devices. The naming scheme for the devices is the same wheter | ||
| 164 | devfs is used or not.</para> | ||
| 165 | |||
| 166 | <para>More details about the data structures and function calls of all | ||
| 167 | the devices are described in the following chapters.</para> | ||
| 168 | |||
| 169 | </section> | ||
| 170 | |||
| 171 | <section id="include_files"> | ||
| 172 | <title>API include files</title> | ||
| 173 | |||
| 174 | <para>For each of the DVB devices a corresponding include file exists. | ||
| 175 | The DVB API include files should be included in application sources with | ||
| 176 | a partial path like:</para> | ||
| 177 | |||
| 178 | |||
| 179 | <programlisting> | ||
| 180 | #include <linux/dvb/frontend.h> | ||
| 181 | </programlisting> | ||
| 182 | |||
| 183 | <para>To enable applications to support different API version, an | ||
| 184 | additional include file <emphasis | ||
| 185 | role="tt">linux/dvb/version.h</emphasis> exists, which defines the | ||
| 186 | constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document | ||
| 187 | describes <emphasis role="tt">DVB_API_VERSION 3</emphasis>. | ||
| 188 | </para> | ||
| 189 | |||
| 190 | </section> | ||
| 191 | |||
diff --git a/Documentation/DocBook/dvb/isdbt.xml b/Documentation/DocBook/dvb/isdbt.xml new file mode 100644 index 000000000000..92855222fccb --- /dev/null +++ b/Documentation/DocBook/dvb/isdbt.xml | |||
| @@ -0,0 +1,314 @@ | |||
| 1 | <section id="isdbt"> | ||
| 2 | <title>ISDB-T frontend</title> | ||
| 3 | <para>This section describes shortly what are the possible parameters in the Linux | ||
| 4 | DVB-API called "S2API" and now DVB API 5 in order to tune an ISDB-T/ISDB-Tsb | ||
| 5 | demodulator:</para> | ||
| 6 | |||
| 7 | <para>This ISDB-T/ISDB-Tsb API extension should reflect all information | ||
| 8 | needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible | ||
| 9 | that some very sophisticated devices won't need certain parameters to | ||
| 10 | tune.</para> | ||
| 11 | |||
| 12 | <para>The information given here should help application writers to know how | ||
| 13 | to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para> | ||
| 14 | |||
| 15 | <para>The details given here about ISDB-T and ISDB-Tsb are just enough to | ||
| 16 | basically show the dependencies between the needed parameter values, | ||
| 17 | but surely some information is left out. For more detailed information | ||
| 18 | see the following documents:</para> | ||
| 19 | |||
| 20 | <para>ARIB STD-B31 - "Transmission System for Digital Terrestrial | ||
| 21 | Television Broadcasting" and</para> | ||
| 22 | <para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial | ||
| 23 | Television Broadcasting".</para> | ||
| 24 | |||
| 25 | <para>In order to read this document one has to have some knowledge the | ||
| 26 | channel structure in ISDB-T and ISDB-Tsb. I.e. it has to be known to | ||
| 27 | the reader that an ISDB-T channel consists of 13 segments, that it can | ||
| 28 | have up to 3 layer sharing those segments, and things like that.</para> | ||
| 29 | |||
| 30 | <para>Parameters used by ISDB-T and ISDB-Tsb.</para> | ||
| 31 | |||
| 32 | <section id="isdbt-parms"> | ||
| 33 | <title>Parameters that are common with DVB-T and ATSC</title> | ||
| 34 | |||
| 35 | <section id="isdbt-freq"> | ||
| 36 | <title><constant>DTV_FREQUENCY</constant></title> | ||
| 37 | |||
| 38 | <para>Central frequency of the channel.</para> | ||
| 39 | |||
| 40 | <para>For ISDB-T the channels are usally transmitted with an offset of 143kHz. E.g. a | ||
| 41 | valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of | ||
| 42 | the channel which is 6MHz.</para> | ||
| 43 | |||
| 44 | <para>As in ISDB-Tsb the channel consists of only one or three segments the | ||
| 45 | frequency step is 429kHz, 3*429 respectively. As for ISDB-T the | ||
| 46 | central frequency of the channel is expected.</para> | ||
| 47 | </section> | ||
| 48 | |||
| 49 | <section id="isdbt-bw"> | ||
| 50 | <title><constant>DTV_BANDWIDTH_HZ</constant> (optional)</title> | ||
| 51 | |||
| 52 | <para>Possible values:</para> | ||
| 53 | |||
| 54 | <para>For ISDB-T it should be always 6000000Hz (6MHz)</para> | ||
| 55 | <para>For ISDB-Tsb it can vary depending on the number of connected segments</para> | ||
| 56 | |||
| 57 | <para>Note: Hardware specific values might be given here, but standard | ||
| 58 | applications should not bother to set a value to this field as | ||
| 59 | standard demods are ignoring it anyway.</para> | ||
| 60 | |||
| 61 | <para>Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from | ||
| 62 | other parameters (DTV_ISDBT_SB_SEGMENT_IDX, | ||
| 63 | DTV_ISDBT_SB_SEGMENT_COUNT).</para> | ||
| 64 | </section> | ||
| 65 | |||
| 66 | <section id="isdbt-delivery-sys"> | ||
| 67 | <title><constant>DTV_DELIVERY_SYSTEM</constant></title> | ||
| 68 | |||
| 69 | <para>Possible values: <constant>SYS_ISDBT</constant></para> | ||
| 70 | </section> | ||
| 71 | |||
| 72 | <section id="isdbt-tx-mode"> | ||
| 73 | <title><constant>DTV_TRANSMISSION_MODE</constant></title> | ||
| 74 | |||
| 75 | <para>ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called | ||
| 76 | 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para> | ||
| 77 | |||
| 78 | <para>Possible values: <constant>TRANSMISSION_MODE_2K</constant>, <constant>TRANSMISSION_MODE_8K</constant>, | ||
| 79 | <constant>TRANSMISSION_MODE_AUTO</constant>, <constant>TRANSMISSION_MODE_4K</constant></para> | ||
| 80 | |||
| 81 | <para>If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the | ||
| 82 | hardware will try to find the correct FFT-size (if capable) and will | ||
| 83 | use TMCC to fill in the missing parameters.</para> | ||
| 84 | |||
| 85 | <para><constant>TRANSMISSION_MODE_4K</constant> is added at the same time as the other new parameters.</para> | ||
| 86 | </section> | ||
| 87 | |||
| 88 | <section id="isdbt-guard-interval"> | ||
| 89 | <title><constant>DTV_GUARD_INTERVAL</constant></title> | ||
| 90 | |||
| 91 | <para>Possible values: <constant>GUARD_INTERVAL_1_32</constant>, <constant>GUARD_INTERVAL_1_16</constant>, <constant>GUARD_INTERVAL_1_8</constant>, | ||
| 92 | <constant>GUARD_INTERVAL_1_4</constant>, <constant>GUARD_INTERVAL_AUTO</constant></para> | ||
| 93 | |||
| 94 | <para>If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will | ||
| 95 | try to find the correct guard interval (if capable) and will use TMCC to fill | ||
| 96 | in the missing parameters.</para> | ||
| 97 | </section> | ||
| 98 | </section> | ||
| 99 | <section id="isdbt-new-parms"> | ||
| 100 | <title>ISDB-T only parameters</title> | ||
| 101 | |||
| 102 | <section id="isdbt-part-rec"> | ||
| 103 | <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title> | ||
| 104 | |||
| 105 | <para><constant>If DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether | ||
| 106 | the channel is in partial reception mode or not.</para> | ||
| 107 | |||
| 108 | <para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and | ||
| 109 | <constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para> | ||
| 110 | |||
| 111 | <para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1' | ||
| 112 | <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel | ||
| 113 | is consisting of one segment and layer or three segments and two layers.</para> | ||
| 114 | |||
| 115 | <para>Possible values: 0, 1, -1 (AUTO)</para> | ||
| 116 | </section> | ||
| 117 | |||
| 118 | <section id="isdbt-sound-bcast"> | ||
| 119 | <title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title> | ||
| 120 | |||
| 121 | <para>This field represents whether the other DTV_ISDBT_*-parameters are | ||
| 122 | referring to an ISDB-T and an ISDB-Tsb channel. (See also | ||
| 123 | <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para> | ||
| 124 | |||
| 125 | <para>Possible values: 0, 1, -1 (AUTO)</para> | ||
| 126 | </section> | ||
| 127 | |||
| 128 | <section id="isdbt-sb-ch-id"> | ||
| 129 | <title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title> | ||
| 130 | |||
| 131 | <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> | ||
| 132 | |||
| 133 | <para>(Note of the author: This might not be the correct description of the | ||
| 134 | <constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical | ||
| 135 | background needed to program a device)</para> | ||
| 136 | |||
| 137 | <para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a | ||
| 138 | set of connected ISDB-Tsb channels. In this set of channels every | ||
| 139 | channel can be received independently. The number of connected | ||
| 140 | ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum | ||
| 141 | bandwidth available.</para> | ||
| 142 | |||
| 143 | <para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The | ||
| 144 | broadcaster has several possibilities to put those channels in the | ||
| 145 | air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8 | ||
| 146 | segments from position 1-8 to 5-13 or anything in between.</para> | ||
| 147 | |||
| 148 | <para>The underlying layer of segments are subchannels: each segment is | ||
| 149 | consisting of several subchannels with a predefined IDs. A sub-channel | ||
| 150 | is used to help the demodulator to synchronize on the channel.</para> | ||
| 151 | |||
| 152 | <para>An ISDB-T channel is always centered over all sub-channels. As for | ||
| 153 | the example above, in ISDB-Tsb it is no longer as simple as that.</para> | ||
| 154 | |||
| 155 | <para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the | ||
| 156 | sub-channel ID of the segment to be demodulated.</para> | ||
| 157 | |||
| 158 | <para>Possible values: 0 .. 41, -1 (AUTO)</para> | ||
| 159 | </section> | ||
| 160 | |||
| 161 | <section id="isdbt-sb-seg-idx"> | ||
| 162 | |||
| 163 | <title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title> | ||
| 164 | |||
| 165 | <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> | ||
| 166 | |||
| 167 | <para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be | ||
| 168 | demodulated for an ISDB-Tsb channel where several of them are | ||
| 169 | transmitted in the connected manner.</para> | ||
| 170 | |||
| 171 | <para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para> | ||
| 172 | |||
| 173 | <para>Note: This value cannot be determined by an automatic channel search.</para> | ||
| 174 | </section> | ||
| 175 | |||
| 176 | <section id="isdbt-sb-seg-cnt"> | ||
| 177 | <title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title> | ||
| 178 | |||
| 179 | <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> | ||
| 180 | |||
| 181 | <para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb | ||
| 182 | channels.</para> | ||
| 183 | |||
| 184 | <para>Possible values: 1 .. 13</para> | ||
| 185 | |||
| 186 | <para>Note: This value cannot be determined by an automatic channel search.</para> | ||
| 187 | </section> | ||
| 188 | |||
| 189 | <section id="isdb-hierq-layers"> | ||
| 190 | <title>Hierarchical layers</title> | ||
| 191 | |||
| 192 | <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in | ||
| 193 | ISDB-T hierarchical layers can be decoded simultaneously. For that | ||
| 194 | reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders.</para> | ||
| 195 | |||
| 196 | <para>ISDB-T has 3 hierarchical layers which each can use a part of the | ||
| 197 | available segments. The total number of segments over all layers has | ||
| 198 | to 13 in ISDB-T.</para> | ||
| 199 | |||
| 200 | <section id="isdbt-layer-ena"> | ||
| 201 | <title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title> | ||
| 202 | |||
| 203 | <para>Hierarchical reception in ISDB-T is achieved by enabling or disabling | ||
| 204 | layers in the decoding process. Setting all bits of | ||
| 205 | <constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be | ||
| 206 | demodulated. This is the default.</para> | ||
| 207 | |||
| 208 | <para>If the channel is in the partial reception mode | ||
| 209 | (<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded | ||
| 210 | independently of the other 12 segments. In that mode layer A has to | ||
| 211 | have a <constant>SEGMENT_COUNT</constant> of 1.</para> | ||
| 212 | |||
| 213 | <para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb | ||
| 214 | according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled | ||
| 215 | accordingly.</para> | ||
| 216 | |||
| 217 | <para>Possible values: 0x1, 0x2, 0x4 (|-able)</para> | ||
| 218 | |||
| 219 | <para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para> | ||
| 220 | <para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para> | ||
| 221 | <para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para> | ||
| 222 | <para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para> | ||
| 223 | </section> | ||
| 224 | |||
| 225 | <section id="isdbt-layer-fec"> | ||
| 226 | <title><constant>DTV_ISDBT_LAYER*_FEC</constant></title> | ||
| 227 | |||
| 228 | <para>Possible values: <constant>FEC_AUTO</constant>, <constant>FEC_1_2</constant>, <constant>FEC_2_3</constant>, <constant>FEC_3_4</constant>, <constant>FEC_5_6</constant>, <constant>FEC_7_8</constant></para> | ||
| 229 | </section> | ||
| 230 | |||
| 231 | <section id="isdbt-layer-mod"> | ||
| 232 | <title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title> | ||
| 233 | |||
| 234 | <para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para> | ||
| 235 | |||
| 236 | <para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant> | ||
| 237 | and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para> | ||
| 238 | </section> | ||
| 239 | |||
| 240 | <section id="isdbt-layer-seg-cnt"> | ||
| 241 | <title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title> | ||
| 242 | |||
| 243 | <para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para> | ||
| 244 | |||
| 245 | <para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and | ||
| 246 | <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para> | ||
| 247 | |||
| 248 | <informaltable id="isdbt-layer_seg-cnt-table"> | ||
| 249 | <tgroup cols="6"> | ||
| 250 | |||
| 251 | <tbody> | ||
| 252 | <row> | ||
| 253 | <entry>PR</entry> | ||
| 254 | <entry>SB</entry> | ||
| 255 | <entry>Layer A width</entry> | ||
| 256 | <entry>Layer B width</entry> | ||
| 257 | <entry>Layer C width</entry> | ||
| 258 | <entry>total width</entry> | ||
| 259 | </row> | ||
| 260 | |||
| 261 | <row> | ||
| 262 | <entry>0</entry> | ||
| 263 | <entry>0</entry> | ||
| 264 | <entry>1 .. 13</entry> | ||
| 265 | <entry>1 .. 13</entry> | ||
| 266 | <entry>1 .. 13</entry> | ||
| 267 | <entry>13</entry> | ||
| 268 | </row> | ||
| 269 | |||
| 270 | <row> | ||
| 271 | <entry>1</entry> | ||
| 272 | <entry>0</entry> | ||
| 273 | <entry>1</entry> | ||
| 274 | <entry>1 .. 13</entry> | ||
| 275 | <entry>1 .. 13</entry> | ||
| 276 | <entry>13</entry> | ||
| 277 | </row> | ||
| 278 | |||
| 279 | <row> | ||
| 280 | <entry>0</entry> | ||
| 281 | <entry>1</entry> | ||
| 282 | <entry>1</entry> | ||
| 283 | <entry>0</entry> | ||
| 284 | <entry>0</entry> | ||
| 285 | <entry>1</entry> | ||
| 286 | </row> | ||
| 287 | |||
| 288 | <row> | ||
| 289 | <entry>1</entry> | ||
| 290 | <entry>1</entry> | ||
| 291 | <entry>1</entry> | ||
| 292 | <entry>2</entry> | ||
| 293 | <entry>0</entry> | ||
| 294 | <entry>13</entry> | ||
| 295 | </row> | ||
| 296 | </tbody> | ||
| 297 | |||
| 298 | </tgroup> | ||
| 299 | </informaltable> | ||
| 300 | |||
| 301 | </section> | ||
| 302 | |||
| 303 | <section id="isdbt_layer_t_interl"> | ||
| 304 | <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title> | ||
| 305 | |||
| 306 | <para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para> | ||
| 307 | |||
| 308 | <para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values | ||
| 309 | here are referring to what can be found in the TMCC-structure - | ||
| 310 | independent of the mode.</para> | ||
| 311 | </section> | ||
| 312 | </section> | ||
| 313 | </section> | ||
| 314 | </section> | ||
diff --git a/Documentation/DocBook/dvb/kdapi.xml b/Documentation/DocBook/dvb/kdapi.xml new file mode 100644 index 000000000000..6c67481eaa4b --- /dev/null +++ b/Documentation/DocBook/dvb/kdapi.xml | |||
| @@ -0,0 +1,2309 @@ | |||
| 1 | <title>Kernel Demux API</title> | ||
| 2 | <para>The kernel demux API defines a driver-internal interface for registering low-level, | ||
| 3 | hardware specific driver to a hardware independent demux layer. It is only of interest for | ||
| 4 | DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in | ||
| 5 | <emphasis role="tt">drivers/media/dvb/dvb-core</emphasis>. | ||
| 6 | </para> | ||
| 7 | <para>Maintainer note: This section must be reviewed. It is probably out of date. | ||
| 8 | </para> | ||
| 9 | |||
| 10 | <section id="kernel_demux_data_types"> | ||
| 11 | <title>Kernel Demux Data Types</title> | ||
| 12 | |||
| 13 | |||
| 14 | <section id="dmx_success_t"> | ||
| 15 | <title>dmx_success_t</title> | ||
| 16 | <programlisting> | ||
| 17 | typedef enum { | ||
| 18 | DMX_OK = 0, /⋆ Received Ok ⋆/ | ||
| 19 | DMX_LENGTH_ERROR, /⋆ Incorrect length ⋆/ | ||
| 20 | DMX_OVERRUN_ERROR, /⋆ Receiver ring buffer overrun ⋆/ | ||
| 21 | DMX_CRC_ERROR, /⋆ Incorrect CRC ⋆/ | ||
| 22 | DMX_FRAME_ERROR, /⋆ Frame alignment error ⋆/ | ||
| 23 | DMX_FIFO_ERROR, /⋆ Receiver FIFO overrun ⋆/ | ||
| 24 | DMX_MISSED_ERROR /⋆ Receiver missed packet ⋆/ | ||
| 25 | } dmx_success_t; | ||
| 26 | </programlisting> | ||
| 27 | |||
| 28 | </section> | ||
| 29 | <section id="ts_filter_types"> | ||
| 30 | <title>TS filter types</title> | ||
| 31 | <programlisting> | ||
| 32 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 33 | /⋆ TS packet reception ⋆/ | ||
| 34 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 35 | |||
| 36 | /⋆ TS filter type for set_type() ⋆/ | ||
| 37 | |||
| 38 | #define TS_PACKET 1 /⋆ send TS packets (188 bytes) to callback (default) ⋆/ | ||
| 39 | #define TS_PAYLOAD_ONLY 2 /⋆ in case TS_PACKET is set, only send the TS | ||
| 40 | payload (<=184 bytes per packet) to callback ⋆/ | ||
| 41 | #define TS_DECODER 4 /⋆ send stream to built-in decoder (if present) ⋆/ | ||
| 42 | </programlisting> | ||
| 43 | |||
| 44 | </section> | ||
| 45 | <section id="dmx_ts_pes_t"> | ||
| 46 | <title>dmx_ts_pes_t</title> | ||
| 47 | <para>The structure | ||
| 48 | </para> | ||
| 49 | <programlisting> | ||
| 50 | typedef enum | ||
| 51 | { | ||
| 52 | DMX_TS_PES_AUDIO, /⋆ also send packets to audio decoder (if it exists) ⋆/ | ||
| 53 | DMX_TS_PES_VIDEO, /⋆ ... ⋆/ | ||
| 54 | DMX_TS_PES_TELETEXT, | ||
| 55 | DMX_TS_PES_SUBTITLE, | ||
| 56 | DMX_TS_PES_PCR, | ||
| 57 | DMX_TS_PES_OTHER, | ||
| 58 | } dmx_ts_pes_t; | ||
| 59 | </programlisting> | ||
| 60 | <para>describes the PES type for filters which write to a built-in decoder. The correspond (and | ||
| 61 | should be kept identical) to the types in the demux device. | ||
| 62 | </para> | ||
| 63 | <programlisting> | ||
| 64 | struct dmx_ts_feed_s { | ||
| 65 | int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ | ||
| 66 | struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ | ||
| 67 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 68 | int (⋆set) (struct dmx_ts_feed_s⋆ feed, | ||
| 69 | __u16 pid, | ||
| 70 | size_t callback_length, | ||
| 71 | size_t circular_buffer_size, | ||
| 72 | int descramble, | ||
| 73 | struct timespec timeout); | ||
| 74 | int (⋆start_filtering) (struct dmx_ts_feed_s⋆ feed); | ||
| 75 | int (⋆stop_filtering) (struct dmx_ts_feed_s⋆ feed); | ||
| 76 | int (⋆set_type) (struct dmx_ts_feed_s⋆ feed, | ||
| 77 | int type, | ||
| 78 | dmx_ts_pes_t pes_type); | ||
| 79 | }; | ||
| 80 | |||
| 81 | typedef struct dmx_ts_feed_s dmx_ts_feed_t; | ||
| 82 | </programlisting> | ||
| 83 | <programlisting> | ||
| 84 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 85 | /⋆ PES packet reception (not supported yet) ⋆/ | ||
| 86 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 87 | |||
| 88 | typedef struct dmx_pes_filter_s { | ||
| 89 | struct dmx_pes_s⋆ parent; /⋆ Back-pointer ⋆/ | ||
| 90 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 91 | } dmx_pes_filter_t; | ||
| 92 | </programlisting> | ||
| 93 | <programlisting> | ||
| 94 | typedef struct dmx_pes_feed_s { | ||
| 95 | int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ | ||
| 96 | struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ | ||
| 97 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 98 | int (⋆set) (struct dmx_pes_feed_s⋆ feed, | ||
| 99 | __u16 pid, | ||
| 100 | size_t circular_buffer_size, | ||
| 101 | int descramble, | ||
| 102 | struct timespec timeout); | ||
| 103 | int (⋆start_filtering) (struct dmx_pes_feed_s⋆ feed); | ||
| 104 | int (⋆stop_filtering) (struct dmx_pes_feed_s⋆ feed); | ||
| 105 | int (⋆allocate_filter) (struct dmx_pes_feed_s⋆ feed, | ||
| 106 | dmx_pes_filter_t⋆⋆ filter); | ||
| 107 | int (⋆release_filter) (struct dmx_pes_feed_s⋆ feed, | ||
| 108 | dmx_pes_filter_t⋆ filter); | ||
| 109 | } dmx_pes_feed_t; | ||
| 110 | </programlisting> | ||
| 111 | <programlisting> | ||
| 112 | typedef struct { | ||
| 113 | __u8 filter_value [DMX_MAX_FILTER_SIZE]; | ||
| 114 | __u8 filter_mask [DMX_MAX_FILTER_SIZE]; | ||
| 115 | struct dmx_section_feed_s⋆ parent; /⋆ Back-pointer ⋆/ | ||
| 116 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 117 | } dmx_section_filter_t; | ||
| 118 | </programlisting> | ||
| 119 | <programlisting> | ||
| 120 | struct dmx_section_feed_s { | ||
| 121 | int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ | ||
| 122 | struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ | ||
| 123 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 124 | int (⋆set) (struct dmx_section_feed_s⋆ feed, | ||
| 125 | __u16 pid, | ||
| 126 | size_t circular_buffer_size, | ||
| 127 | int descramble, | ||
| 128 | int check_crc); | ||
| 129 | int (⋆allocate_filter) (struct dmx_section_feed_s⋆ feed, | ||
| 130 | dmx_section_filter_t⋆⋆ filter); | ||
| 131 | int (⋆release_filter) (struct dmx_section_feed_s⋆ feed, | ||
| 132 | dmx_section_filter_t⋆ filter); | ||
| 133 | int (⋆start_filtering) (struct dmx_section_feed_s⋆ feed); | ||
| 134 | int (⋆stop_filtering) (struct dmx_section_feed_s⋆ feed); | ||
| 135 | }; | ||
| 136 | typedef struct dmx_section_feed_s dmx_section_feed_t; | ||
| 137 | |||
| 138 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 139 | /⋆ Callback functions ⋆/ | ||
| 140 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 141 | |||
| 142 | typedef int (⋆dmx_ts_cb) ( __u8 ⋆ buffer1, | ||
| 143 | size_t buffer1_length, | ||
| 144 | __u8 ⋆ buffer2, | ||
| 145 | size_t buffer2_length, | ||
| 146 | dmx_ts_feed_t⋆ source, | ||
| 147 | dmx_success_t success); | ||
| 148 | |||
| 149 | typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1, | ||
| 150 | size_t buffer1_len, | ||
| 151 | __u8 ⋆ buffer2, | ||
| 152 | size_t buffer2_len, | ||
| 153 | dmx_section_filter_t ⋆ source, | ||
| 154 | dmx_success_t success); | ||
| 155 | |||
| 156 | typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1, | ||
| 157 | size_t buffer1_len, | ||
| 158 | __u8 ⋆ buffer2, | ||
| 159 | size_t buffer2_len, | ||
| 160 | dmx_pes_filter_t⋆ source, | ||
| 161 | dmx_success_t success); | ||
| 162 | |||
| 163 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 164 | /⋆ DVB Front-End ⋆/ | ||
| 165 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 166 | |||
| 167 | typedef enum { | ||
| 168 | DMX_OTHER_FE = 0, | ||
| 169 | DMX_SATELLITE_FE, | ||
| 170 | DMX_CABLE_FE, | ||
| 171 | DMX_TERRESTRIAL_FE, | ||
| 172 | DMX_LVDS_FE, | ||
| 173 | DMX_ASI_FE, /⋆ DVB-ASI interface ⋆/ | ||
| 174 | DMX_MEMORY_FE | ||
| 175 | } dmx_frontend_source_t; | ||
| 176 | |||
| 177 | typedef struct { | ||
| 178 | /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ | ||
| 179 | char⋆ id; /⋆ Unique front-end identifier ⋆/ | ||
| 180 | char⋆ vendor; /⋆ Name of the front-end vendor ⋆/ | ||
| 181 | char⋆ model; /⋆ Name of the front-end model ⋆/ | ||
| 182 | struct list_head connectivity_list; /⋆ List of front-ends that can | ||
| 183 | be connected to a particular | ||
| 184 | demux ⋆/ | ||
| 185 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 186 | dmx_frontend_source_t source; | ||
| 187 | } dmx_frontend_t; | ||
| 188 | |||
| 189 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 190 | /⋆ MPEG-2 TS Demux ⋆/ | ||
| 191 | /⋆--------------------------------------------------------------------------⋆/ | ||
| 192 | |||
| 193 | /⋆ | ||
| 194 | ⋆ Flags OR'ed in the capabilites field of struct dmx_demux_s. | ||
| 195 | ⋆/ | ||
| 196 | |||
| 197 | #define DMX_TS_FILTERING 1 | ||
| 198 | #define DMX_PES_FILTERING 2 | ||
| 199 | #define DMX_SECTION_FILTERING 4 | ||
| 200 | #define DMX_MEMORY_BASED_FILTERING 8 /⋆ write() available ⋆/ | ||
| 201 | #define DMX_CRC_CHECKING 16 | ||
| 202 | #define DMX_TS_DESCRAMBLING 32 | ||
| 203 | #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64 | ||
| 204 | #define DMX_MAC_ADDRESS_DESCRAMBLING 128 | ||
| 205 | </programlisting> | ||
| 206 | |||
| 207 | </section> | ||
| 208 | <section id="demux_demux_t"> | ||
| 209 | <title>demux_demux_t</title> | ||
| 210 | <programlisting> | ||
| 211 | /⋆ | ||
| 212 | ⋆ DMX_FE_ENTRY(): Casts elements in the list of registered | ||
| 213 | ⋆ front-ends from the generic type struct list_head | ||
| 214 | ⋆ to the type ⋆ dmx_frontend_t | ||
| 215 | ⋆. | ||
| 216 | ⋆/ | ||
| 217 | |||
| 218 | #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) | ||
| 219 | |||
| 220 | struct dmx_demux_s { | ||
| 221 | /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ | ||
| 222 | char⋆ id; /⋆ Unique demux identifier ⋆/ | ||
| 223 | char⋆ vendor; /⋆ Name of the demux vendor ⋆/ | ||
| 224 | char⋆ model; /⋆ Name of the demux model ⋆/ | ||
| 225 | __u32 capabilities; /⋆ Bitfield of capability flags ⋆/ | ||
| 226 | dmx_frontend_t⋆ frontend; /⋆ Front-end connected to the demux ⋆/ | ||
| 227 | struct list_head reg_list; /⋆ List of registered demuxes ⋆/ | ||
| 228 | void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ | ||
| 229 | int users; /⋆ Number of users ⋆/ | ||
| 230 | int (⋆open) (struct dmx_demux_s⋆ demux); | ||
| 231 | int (⋆close) (struct dmx_demux_s⋆ demux); | ||
| 232 | int (⋆write) (struct dmx_demux_s⋆ demux, const char⋆ buf, size_t count); | ||
| 233 | int (⋆allocate_ts_feed) (struct dmx_demux_s⋆ demux, | ||
| 234 | dmx_ts_feed_t⋆⋆ feed, | ||
| 235 | dmx_ts_cb callback); | ||
| 236 | int (⋆release_ts_feed) (struct dmx_demux_s⋆ demux, | ||
| 237 | dmx_ts_feed_t⋆ feed); | ||
| 238 | int (⋆allocate_pes_feed) (struct dmx_demux_s⋆ demux, | ||
| 239 | dmx_pes_feed_t⋆⋆ feed, | ||
| 240 | dmx_pes_cb callback); | ||
| 241 | int (⋆release_pes_feed) (struct dmx_demux_s⋆ demux, | ||
| 242 | dmx_pes_feed_t⋆ feed); | ||
| 243 | int (⋆allocate_section_feed) (struct dmx_demux_s⋆ demux, | ||
| 244 | dmx_section_feed_t⋆⋆ feed, | ||
| 245 | dmx_section_cb callback); | ||
| 246 | int (⋆release_section_feed) (struct dmx_demux_s⋆ demux, | ||
| 247 | dmx_section_feed_t⋆ feed); | ||
| 248 | int (⋆descramble_mac_address) (struct dmx_demux_s⋆ demux, | ||
| 249 | __u8⋆ buffer1, | ||
| 250 | size_t buffer1_length, | ||
| 251 | __u8⋆ buffer2, | ||
| 252 | size_t buffer2_length, | ||
| 253 | __u16 pid); | ||
| 254 | int (⋆descramble_section_payload) (struct dmx_demux_s⋆ demux, | ||
| 255 | __u8⋆ buffer1, | ||
| 256 | size_t buffer1_length, | ||
| 257 | __u8⋆ buffer2, size_t buffer2_length, | ||
| 258 | __u16 pid); | ||
| 259 | int (⋆add_frontend) (struct dmx_demux_s⋆ demux, | ||
| 260 | dmx_frontend_t⋆ frontend); | ||
| 261 | int (⋆remove_frontend) (struct dmx_demux_s⋆ demux, | ||
| 262 | dmx_frontend_t⋆ frontend); | ||
| 263 | struct list_head⋆ (⋆get_frontends) (struct dmx_demux_s⋆ demux); | ||
| 264 | int (⋆connect_frontend) (struct dmx_demux_s⋆ demux, | ||
| 265 | dmx_frontend_t⋆ frontend); | ||
| 266 | int (⋆disconnect_frontend) (struct dmx_demux_s⋆ demux); | ||
| 267 | |||
| 268 | |||
| 269 | /⋆ added because js cannot keep track of these himself ⋆/ | ||
| 270 | int (⋆get_pes_pids) (struct dmx_demux_s⋆ demux, __u16 ⋆pids); | ||
| 271 | }; | ||
| 272 | typedef struct dmx_demux_s dmx_demux_t; | ||
| 273 | </programlisting> | ||
| 274 | |||
| 275 | </section> | ||
| 276 | <section id="demux_directory"> | ||
| 277 | <title>Demux directory</title> | ||
| 278 | <programlisting> | ||
| 279 | /⋆ | ||
| 280 | ⋆ DMX_DIR_ENTRY(): Casts elements in the list of registered | ||
| 281 | ⋆ demuxes from the generic type struct list_head⋆ to the type dmx_demux_t | ||
| 282 | ⋆. | ||
| 283 | ⋆/ | ||
| 284 | |||
| 285 | #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list) | ||
| 286 | |||
| 287 | int dmx_register_demux (dmx_demux_t⋆ demux); | ||
| 288 | int dmx_unregister_demux (dmx_demux_t⋆ demux); | ||
| 289 | struct list_head⋆ dmx_get_demuxes (void); | ||
| 290 | </programlisting> | ||
| 291 | </section></section> | ||
| 292 | <section id="demux_directory_api"> | ||
| 293 | <title>Demux Directory API</title> | ||
| 294 | <para>The demux directory is a Linux kernel-wide facility for registering and accessing the | ||
| 295 | MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers | ||
| 296 | is possible using this API. | ||
| 297 | </para> | ||
| 298 | <para>All demux drivers in the directory implement the abstract interface dmx_demux_t. | ||
| 299 | </para> | ||
| 300 | |||
| 301 | <section | ||
| 302 | role="subsection"><title>dmx_register_demux()</title> | ||
| 303 | <para>DESCRIPTION | ||
| 304 | </para> | ||
| 305 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 306 | align="char"> | ||
| 307 | <para>This function makes a demux driver interface available to the Linux kernel. It is | ||
| 308 | usually called by the init_module() function of the kernel module that contains | ||
| 309 | the demux driver. The caller of this function is responsible for allocating | ||
| 310 | dynamic or static memory for the demux structure and for initializing its fields | ||
| 311 | before calling this function. The memory allocated for the demux structure | ||
| 312 | must not be freed before calling dmx_unregister_demux(),</para> | ||
| 313 | </entry> | ||
| 314 | </row></tbody></tgroup></informaltable> | ||
| 315 | <para>SYNOPSIS | ||
| 316 | </para> | ||
| 317 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 318 | align="char"> | ||
| 319 | <para>int dmx_register_demux ( dmx_demux_t ⋆demux )</para> | ||
| 320 | </entry> | ||
| 321 | </row></tbody></tgroup></informaltable> | ||
| 322 | <para>PARAMETERS | ||
| 323 | </para> | ||
| 324 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 325 | align="char"> | ||
| 326 | <para>dmx_demux_t* | ||
| 327 | demux</para> | ||
| 328 | </entry><entry | ||
| 329 | align="char"> | ||
| 330 | <para>Pointer to the demux structure.</para> | ||
| 331 | </entry> | ||
| 332 | </row></tbody></tgroup></informaltable> | ||
| 333 | <para>RETURNS | ||
| 334 | </para> | ||
| 335 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 336 | align="char"> | ||
| 337 | <para>0</para> | ||
| 338 | </entry><entry | ||
| 339 | align="char"> | ||
| 340 | <para>The function was completed without errors.</para> | ||
| 341 | </entry> | ||
| 342 | </row><row><entry | ||
| 343 | align="char"> | ||
| 344 | <para>-EEXIST</para> | ||
| 345 | </entry><entry | ||
| 346 | align="char"> | ||
| 347 | <para>A demux with the same value of the id field already stored | ||
| 348 | in the directory.</para> | ||
| 349 | </entry> | ||
| 350 | </row><row><entry | ||
| 351 | align="char"> | ||
| 352 | <para>-ENOSPC</para> | ||
| 353 | </entry><entry | ||
| 354 | align="char"> | ||
| 355 | <para>No space left in the directory.</para> | ||
| 356 | </entry> | ||
| 357 | </row></tbody></tgroup></informaltable> | ||
| 358 | |||
| 359 | </section><section | ||
| 360 | role="subsection"><title>dmx_unregister_demux()</title> | ||
| 361 | <para>DESCRIPTION | ||
| 362 | </para> | ||
| 363 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 364 | align="char"> | ||
| 365 | <para>This function is called to indicate that the given demux interface is no | ||
| 366 | longer available. The caller of this function is responsible for freeing the | ||
| 367 | memory of the demux structure, if it was dynamically allocated before calling | ||
| 368 | dmx_register_demux(). The cleanup_module() function of the kernel module | ||
| 369 | that contains the demux driver should call this function. Note that this function | ||
| 370 | fails if the demux is currently in use, i.e., release_demux() has not been called | ||
| 371 | for the interface.</para> | ||
| 372 | </entry> | ||
| 373 | </row></tbody></tgroup></informaltable> | ||
| 374 | <para>SYNOPSIS | ||
| 375 | </para> | ||
| 376 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 377 | align="char"> | ||
| 378 | <para>int dmx_unregister_demux ( dmx_demux_t ⋆demux )</para> | ||
| 379 | </entry> | ||
| 380 | </row></tbody></tgroup></informaltable> | ||
| 381 | <para>PARAMETERS | ||
| 382 | </para> | ||
| 383 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 384 | align="char"> | ||
| 385 | <para>dmx_demux_t* | ||
| 386 | demux</para> | ||
| 387 | </entry><entry | ||
| 388 | align="char"> | ||
| 389 | <para>Pointer to the demux structure which is to be | ||
| 390 | unregistered.</para> | ||
| 391 | </entry> | ||
| 392 | </row></tbody></tgroup></informaltable> | ||
| 393 | <para>RETURNS | ||
| 394 | </para> | ||
| 395 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 396 | align="char"> | ||
| 397 | <para>0</para> | ||
| 398 | </entry><entry | ||
| 399 | align="char"> | ||
| 400 | <para>The function was completed without errors.</para> | ||
| 401 | </entry> | ||
| 402 | </row><row><entry | ||
| 403 | align="char"> | ||
| 404 | <para>ENODEV</para> | ||
| 405 | </entry><entry | ||
| 406 | align="char"> | ||
| 407 | <para>The specified demux is not registered in the demux | ||
| 408 | directory.</para> | ||
| 409 | </entry> | ||
| 410 | </row><row><entry | ||
| 411 | align="char"> | ||
| 412 | <para>EBUSY</para> | ||
| 413 | </entry><entry | ||
| 414 | align="char"> | ||
| 415 | <para>The specified demux is currently in use.</para> | ||
| 416 | </entry> | ||
| 417 | </row></tbody></tgroup></informaltable> | ||
| 418 | |||
| 419 | </section><section | ||
| 420 | role="subsection"><title>dmx_get_demuxes()</title> | ||
| 421 | <para>DESCRIPTION | ||
| 422 | </para> | ||
| 423 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 424 | align="char"> | ||
| 425 | <para>Provides the caller with the list of registered demux interfaces, using the | ||
| 426 | standard list structure defined in the include file linux/list.h. The include file | ||
| 427 | demux.h defines the macro DMX_DIR_ENTRY() for converting an element of | ||
| 428 | the generic type struct list_head* to the type dmx_demux_t*. The caller must | ||
| 429 | not free the memory of any of the elements obtained via this function call.</para> | ||
| 430 | </entry> | ||
| 431 | </row></tbody></tgroup></informaltable> | ||
| 432 | <para>SYNOPSIS | ||
| 433 | </para> | ||
| 434 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 435 | align="char"> | ||
| 436 | <para>struct list_head ⋆dmx_get_demuxes ()</para> | ||
| 437 | </entry> | ||
| 438 | </row></tbody></tgroup></informaltable> | ||
| 439 | <para>PARAMETERS | ||
| 440 | </para> | ||
| 441 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 442 | align="char"> | ||
| 443 | <para>none</para> | ||
| 444 | </entry> | ||
| 445 | </row></tbody></tgroup></informaltable> | ||
| 446 | <para>RETURNS | ||
| 447 | </para> | ||
| 448 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 449 | align="char"> | ||
| 450 | <para>struct list_head *</para> | ||
| 451 | </entry><entry | ||
| 452 | align="char"> | ||
| 453 | <para>A list of demux interfaces, or NULL in the case of an | ||
| 454 | empty list.</para> | ||
| 455 | </entry> | ||
| 456 | </row></tbody></tgroup></informaltable> | ||
| 457 | </section></section> | ||
| 458 | <section id="demux_api"> | ||
| 459 | <title>Demux API</title> | ||
| 460 | <para>The demux API should be implemented for each demux in the system. It is used to select | ||
| 461 | the TS source of a demux and to manage the demux resources. When the demux | ||
| 462 | client allocates a resource via the demux API, it receives a pointer to the API of that | ||
| 463 | resource. | ||
| 464 | </para> | ||
| 465 | <para>Each demux receives its TS input from a DVB front-end or from memory, as set via the | ||
| 466 | demux API. In a system with more than one front-end, the API can be used to select one of | ||
| 467 | the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The | ||
| 468 | demux API only controls front-ends regarding their connections with demuxes; the APIs | ||
| 469 | used to set the other front-end parameters, such as tuning, are not defined in this | ||
| 470 | document. | ||
| 471 | </para> | ||
| 472 | <para>The functions that implement the abstract interface demux should be defined static or | ||
| 473 | module private and registered to the Demux Directory for external access. It is not necessary | ||
| 474 | to implement every function in the demux_t struct, however (for example, a demux interface | ||
| 475 | might support Section filtering, but not TS or PES filtering). The API client is expected to | ||
| 476 | check the value of any function pointer before calling the function: the value of NULL means | ||
| 477 | “function not available”. | ||
| 478 | </para> | ||
| 479 | <para>Whenever the functions of the demux API modify shared data, the possibilities of lost | ||
| 480 | update and race condition problems should be addressed, e.g. by protecting parts of code with | ||
| 481 | mutexes. This is especially important on multi-processor hosts. | ||
| 482 | </para> | ||
| 483 | <para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x | ||
| 484 | kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if | ||
| 485 | swapping is needed. For example, the Linux kernel calls the functions of a network device | ||
| 486 | interface from a bottom half context. Thus, if a demux API function is called from network | ||
| 487 | device code, the function must not sleep. | ||
| 488 | </para> | ||
| 489 | |||
| 490 | |||
| 491 | <section id="kdapi_fopen"> | ||
| 492 | <title>open()</title> | ||
| 493 | <para>DESCRIPTION | ||
| 494 | </para> | ||
| 495 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 496 | align="char"> | ||
| 497 | <para>This function reserves the demux for use by the caller and, if necessary, | ||
| 498 | initializes the demux. When the demux is no longer needed, the function close() | ||
| 499 | should be called. It should be possible for multiple clients to access the demux | ||
| 500 | at the same time. Thus, the function implementation should increment the | ||
| 501 | demux usage count when open() is called and decrement it when close() is | ||
| 502 | called.</para> | ||
| 503 | </entry> | ||
| 504 | </row></tbody></tgroup></informaltable> | ||
| 505 | <para>SYNOPSIS | ||
| 506 | </para> | ||
| 507 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 508 | align="char"> | ||
| 509 | <para>int open ( demux_t⋆ demux );</para> | ||
| 510 | </entry> | ||
| 511 | </row></tbody></tgroup></informaltable> | ||
| 512 | <para>PARAMETERS | ||
| 513 | </para> | ||
| 514 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 515 | align="char"> | ||
| 516 | <para>demux_t* demux</para> | ||
| 517 | </entry><entry | ||
| 518 | align="char"> | ||
| 519 | <para>Pointer to the demux API and instance data.</para> | ||
| 520 | </entry> | ||
| 521 | </row></tbody></tgroup></informaltable> | ||
| 522 | <para>RETURNS | ||
| 523 | </para> | ||
| 524 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 525 | align="char"> | ||
| 526 | <para>0</para> | ||
| 527 | </entry><entry | ||
| 528 | align="char"> | ||
| 529 | <para>The function was completed without errors.</para> | ||
| 530 | </entry> | ||
| 531 | </row><row><entry | ||
| 532 | align="char"> | ||
| 533 | <para>-EUSERS</para> | ||
| 534 | </entry><entry | ||
| 535 | align="char"> | ||
| 536 | <para>Maximum usage count reached.</para> | ||
| 537 | </entry> | ||
| 538 | </row><row><entry | ||
| 539 | align="char"> | ||
| 540 | <para>-EINVAL</para> | ||
| 541 | </entry><entry | ||
| 542 | align="char"> | ||
| 543 | <para>Bad parameter.</para> | ||
| 544 | </entry> | ||
| 545 | </row></tbody></tgroup></informaltable> | ||
| 546 | |||
| 547 | </section> | ||
| 548 | <section id="kdapi_fclose"> | ||
| 549 | <title>close()</title> | ||
| 550 | <para>DESCRIPTION | ||
| 551 | </para> | ||
| 552 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 553 | align="char"> | ||
| 554 | <para>This function reserves the demux for use by the caller and, if necessary, | ||
| 555 | initializes the demux. When the demux is no longer needed, the function close() | ||
| 556 | should be called. It should be possible for multiple clients to access the demux | ||
| 557 | at the same time. Thus, the function implementation should increment the | ||
| 558 | demux usage count when open() is called and decrement it when close() is | ||
| 559 | called.</para> | ||
| 560 | </entry> | ||
| 561 | </row></tbody></tgroup></informaltable> | ||
| 562 | <para>SYNOPSIS | ||
| 563 | </para> | ||
| 564 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 565 | align="char"> | ||
| 566 | <para>int close(demux_t⋆ demux);</para> | ||
| 567 | </entry> | ||
| 568 | </row></tbody></tgroup></informaltable> | ||
| 569 | <para>PARAMETERS | ||
| 570 | </para> | ||
| 571 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 572 | align="char"> | ||
| 573 | <para>demux_t* demux</para> | ||
| 574 | </entry><entry | ||
| 575 | align="char"> | ||
| 576 | <para>Pointer to the demux API and instance data.</para> | ||
| 577 | </entry> | ||
| 578 | </row></tbody></tgroup></informaltable> | ||
| 579 | <para>RETURNS | ||
| 580 | </para> | ||
| 581 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 582 | align="char"> | ||
| 583 | <para>0</para> | ||
| 584 | </entry><entry | ||
| 585 | align="char"> | ||
| 586 | <para>The function was completed without errors.</para> | ||
| 587 | </entry> | ||
| 588 | </row><row><entry | ||
| 589 | align="char"> | ||
| 590 | <para>-ENODEV</para> | ||
| 591 | </entry><entry | ||
| 592 | align="char"> | ||
| 593 | <para>The demux was not in use.</para> | ||
| 594 | </entry> | ||
| 595 | </row><row><entry | ||
| 596 | align="char"> | ||
| 597 | <para>-EINVAL</para> | ||
| 598 | </entry><entry | ||
| 599 | align="char"> | ||
| 600 | <para>Bad parameter.</para> | ||
| 601 | </entry> | ||
| 602 | </row></tbody></tgroup></informaltable> | ||
| 603 | |||
| 604 | </section> | ||
| 605 | <section id="kdapi_fwrite"> | ||
| 606 | <title>write()</title> | ||
| 607 | <para>DESCRIPTION | ||
| 608 | </para> | ||
| 609 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 610 | align="char"> | ||
| 611 | <para>This function provides the demux driver with a memory buffer containing TS | ||
| 612 | packets. Instead of receiving TS packets from the DVB front-end, the demux | ||
| 613 | driver software will read packets from memory. Any clients of this demux | ||
| 614 | with active TS, PES or Section filters will receive filtered data via the Demux | ||
| 615 | callback API (see 0). The function returns when all the data in the buffer has | ||
| 616 | been consumed by the demux. Demux hardware typically cannot read TS from | ||
| 617 | memory. If this is the case, memory-based filtering has to be implemented | ||
| 618 | entirely in software.</para> | ||
| 619 | </entry> | ||
| 620 | </row></tbody></tgroup></informaltable> | ||
| 621 | <para>SYNOPSIS | ||
| 622 | </para> | ||
| 623 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 624 | align="char"> | ||
| 625 | <para>int write(demux_t⋆ demux, const char⋆ buf, size_t | ||
| 626 | count);</para> | ||
| 627 | </entry> | ||
| 628 | </row></tbody></tgroup></informaltable> | ||
| 629 | <para>PARAMETERS | ||
| 630 | </para> | ||
| 631 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 632 | align="char"> | ||
| 633 | <para>demux_t* demux</para> | ||
| 634 | </entry><entry | ||
| 635 | align="char"> | ||
| 636 | <para>Pointer to the demux API and instance data.</para> | ||
| 637 | </entry> | ||
| 638 | </row><row><entry | ||
| 639 | align="char"> | ||
| 640 | <para>const char* buf</para> | ||
| 641 | </entry><entry | ||
| 642 | align="char"> | ||
| 643 | <para>Pointer to the TS data in kernel-space memory.</para> | ||
| 644 | </entry> | ||
| 645 | </row><row><entry | ||
| 646 | align="char"> | ||
| 647 | <para>size_t length</para> | ||
| 648 | </entry><entry | ||
| 649 | align="char"> | ||
| 650 | <para>Length of the TS data.</para> | ||
| 651 | </entry> | ||
| 652 | </row></tbody></tgroup></informaltable> | ||
| 653 | <para>RETURNS | ||
| 654 | </para> | ||
| 655 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 656 | align="char"> | ||
| 657 | <para>0</para> | ||
| 658 | </entry><entry | ||
| 659 | align="char"> | ||
| 660 | <para>The function was completed without errors.</para> | ||
| 661 | </entry> | ||
| 662 | </row><row><entry | ||
| 663 | align="char"> | ||
| 664 | <para>-ENOSYS</para> | ||
| 665 | </entry><entry | ||
| 666 | align="char"> | ||
| 667 | <para>The command is not implemented.</para> | ||
| 668 | </entry> | ||
| 669 | </row><row><entry | ||
| 670 | align="char"> | ||
| 671 | <para>-EINVAL</para> | ||
| 672 | </entry><entry | ||
| 673 | align="char"> | ||
| 674 | <para>Bad parameter.</para> | ||
| 675 | </entry> | ||
| 676 | </row></tbody></tgroup></informaltable> | ||
| 677 | |||
| 678 | </section><section | ||
| 679 | role="subsection"><title>allocate_ts_feed()</title> | ||
| 680 | <para>DESCRIPTION | ||
| 681 | </para> | ||
| 682 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 683 | align="char"> | ||
| 684 | <para>Allocates a new TS feed, which is used to filter the TS packets carrying a | ||
| 685 | certain PID. The TS feed normally corresponds to a hardware PID filter on the | ||
| 686 | demux chip.</para> | ||
| 687 | </entry> | ||
| 688 | </row></tbody></tgroup></informaltable> | ||
| 689 | <para>SYNOPSIS | ||
| 690 | </para> | ||
| 691 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 692 | align="char"> | ||
| 693 | <para>int allocate_ts_feed(dmx_demux_t⋆ demux, | ||
| 694 | dmx_ts_feed_t⋆⋆ feed, dmx_ts_cb callback);</para> | ||
| 695 | </entry> | ||
| 696 | </row></tbody></tgroup></informaltable> | ||
| 697 | <para>PARAMETERS | ||
| 698 | </para> | ||
| 699 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 700 | align="char"> | ||
| 701 | <para>demux_t* demux</para> | ||
| 702 | </entry><entry | ||
| 703 | align="char"> | ||
| 704 | <para>Pointer to the demux API and instance data.</para> | ||
| 705 | </entry> | ||
| 706 | </row><row><entry | ||
| 707 | align="char"> | ||
| 708 | <para>dmx_ts_feed_t** | ||
| 709 | feed</para> | ||
| 710 | </entry><entry | ||
| 711 | align="char"> | ||
| 712 | <para>Pointer to the TS feed API and instance data.</para> | ||
| 713 | </entry> | ||
| 714 | </row><row><entry | ||
| 715 | align="char"> | ||
| 716 | <para>dmx_ts_cb callback</para> | ||
| 717 | </entry><entry | ||
| 718 | align="char"> | ||
| 719 | <para>Pointer to the callback function for passing received TS | ||
| 720 | packet</para> | ||
| 721 | </entry> | ||
| 722 | </row></tbody></tgroup></informaltable> | ||
| 723 | <para>RETURNS | ||
| 724 | </para> | ||
| 725 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 726 | align="char"> | ||
| 727 | <para>0</para> | ||
| 728 | </entry><entry | ||
| 729 | align="char"> | ||
| 730 | <para>The function was completed without errors.</para> | ||
| 731 | </entry> | ||
| 732 | </row><row><entry | ||
| 733 | align="char"> | ||
| 734 | <para>-EBUSY</para> | ||
| 735 | </entry><entry | ||
| 736 | align="char"> | ||
| 737 | <para>No more TS feeds available.</para> | ||
| 738 | </entry> | ||
| 739 | </row><row><entry | ||
| 740 | align="char"> | ||
| 741 | <para>-ENOSYS</para> | ||
| 742 | </entry><entry | ||
| 743 | align="char"> | ||
| 744 | <para>The command is not implemented.</para> | ||
| 745 | </entry> | ||
| 746 | </row><row><entry | ||
| 747 | align="char"> | ||
| 748 | <para>-EINVAL</para> | ||
| 749 | </entry><entry | ||
| 750 | align="char"> | ||
| 751 | <para>Bad parameter.</para> | ||
| 752 | </entry> | ||
| 753 | </row></tbody></tgroup></informaltable> | ||
| 754 | |||
| 755 | </section><section | ||
| 756 | role="subsection"><title>release_ts_feed()</title> | ||
| 757 | <para>DESCRIPTION | ||
| 758 | </para> | ||
| 759 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 760 | align="char"> | ||
| 761 | <para>Releases the resources allocated with allocate_ts_feed(). Any filtering in | ||
| 762 | progress on the TS feed should be stopped before calling this function.</para> | ||
| 763 | </entry> | ||
| 764 | </row></tbody></tgroup></informaltable> | ||
| 765 | <para>SYNOPSIS | ||
| 766 | </para> | ||
| 767 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 768 | align="char"> | ||
| 769 | <para>int release_ts_feed(dmx_demux_t⋆ demux, | ||
| 770 | dmx_ts_feed_t⋆ feed);</para> | ||
| 771 | </entry> | ||
| 772 | </row></tbody></tgroup></informaltable> | ||
| 773 | <para>PARAMETERS | ||
| 774 | </para> | ||
| 775 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 776 | align="char"> | ||
| 777 | <para>demux_t* demux</para> | ||
| 778 | </entry><entry | ||
| 779 | align="char"> | ||
| 780 | <para>Pointer to the demux API and instance data.</para> | ||
| 781 | </entry> | ||
| 782 | </row><row><entry | ||
| 783 | align="char"> | ||
| 784 | <para>dmx_ts_feed_t* feed</para> | ||
| 785 | </entry><entry | ||
| 786 | align="char"> | ||
| 787 | <para>Pointer to the TS feed API and instance data.</para> | ||
| 788 | </entry> | ||
| 789 | </row></tbody></tgroup></informaltable> | ||
| 790 | <para>RETURNS | ||
| 791 | </para> | ||
| 792 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 793 | align="char"> | ||
| 794 | <para>0</para> | ||
| 795 | </entry><entry | ||
| 796 | align="char"> | ||
| 797 | <para>The function was completed without errors.</para> | ||
| 798 | </entry> | ||
| 799 | </row><row><entry | ||
| 800 | align="char"> | ||
| 801 | <para>-EINVAL</para> | ||
| 802 | </entry><entry | ||
| 803 | align="char"> | ||
| 804 | <para>Bad parameter.</para> | ||
| 805 | </entry> | ||
| 806 | </row></tbody></tgroup></informaltable> | ||
| 807 | |||
| 808 | </section><section | ||
| 809 | role="subsection"><title>allocate_section_feed()</title> | ||
| 810 | <para>DESCRIPTION | ||
| 811 | </para> | ||
| 812 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 813 | align="char"> | ||
| 814 | <para>Allocates a new section feed, i.e. a demux resource for filtering and receiving | ||
| 815 | sections. On platforms with hardware support for section filtering, a section | ||
| 816 | feed is directly mapped to the demux HW. On other platforms, TS packets are | ||
| 817 | first PID filtered in hardware and a hardware section filter then emulated in | ||
| 818 | software. The caller obtains an API pointer of type dmx_section_feed_t as an | ||
| 819 | out parameter. Using this API the caller can set filtering parameters and start | ||
| 820 | receiving sections.</para> | ||
| 821 | </entry> | ||
| 822 | </row></tbody></tgroup></informaltable> | ||
| 823 | <para>SYNOPSIS | ||
| 824 | </para> | ||
| 825 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 826 | align="char"> | ||
| 827 | <para>int allocate_section_feed(dmx_demux_t⋆ demux, | ||
| 828 | dmx_section_feed_t ⋆⋆feed, dmx_section_cb callback);</para> | ||
| 829 | </entry> | ||
| 830 | </row></tbody></tgroup></informaltable> | ||
| 831 | <para>PARAMETERS | ||
| 832 | </para> | ||
| 833 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 834 | align="char"> | ||
| 835 | <para>demux_t *demux</para> | ||
| 836 | </entry><entry | ||
| 837 | align="char"> | ||
| 838 | <para>Pointer to the demux API and instance data.</para> | ||
| 839 | </entry> | ||
| 840 | </row><row><entry | ||
| 841 | align="char"> | ||
| 842 | <para>dmx_section_feed_t | ||
| 843 | **feed</para> | ||
| 844 | </entry><entry | ||
| 845 | align="char"> | ||
| 846 | <para>Pointer to the section feed API and instance data.</para> | ||
| 847 | </entry> | ||
| 848 | </row><row><entry | ||
| 849 | align="char"> | ||
| 850 | <para>dmx_section_cb | ||
| 851 | callback</para> | ||
| 852 | </entry><entry | ||
| 853 | align="char"> | ||
| 854 | <para>Pointer to the callback function for passing received | ||
| 855 | sections.</para> | ||
| 856 | </entry> | ||
| 857 | </row></tbody></tgroup></informaltable> | ||
| 858 | <para>RETURNS | ||
| 859 | </para> | ||
| 860 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 861 | align="char"> | ||
| 862 | <para>0</para> | ||
| 863 | </entry><entry | ||
| 864 | align="char"> | ||
| 865 | <para>The function was completed without errors.</para> | ||
| 866 | </entry> | ||
| 867 | </row><row><entry | ||
| 868 | align="char"> | ||
| 869 | <para>-EBUSY</para> | ||
| 870 | </entry><entry | ||
| 871 | align="char"> | ||
| 872 | <para>No more section feeds available.</para> | ||
| 873 | </entry> | ||
| 874 | </row><row><entry | ||
| 875 | align="char"> | ||
| 876 | <para>-ENOSYS</para> | ||
| 877 | </entry><entry | ||
| 878 | align="char"> | ||
| 879 | <para>The command is not implemented.</para> | ||
| 880 | </entry> | ||
| 881 | </row><row><entry | ||
| 882 | align="char"> | ||
| 883 | <para>-EINVAL</para> | ||
| 884 | </entry><entry | ||
| 885 | align="char"> | ||
| 886 | <para>Bad parameter.</para> | ||
| 887 | </entry> | ||
| 888 | </row></tbody></tgroup></informaltable> | ||
| 889 | |||
| 890 | </section><section | ||
| 891 | role="subsection"><title>release_section_feed()</title> | ||
| 892 | <para>DESCRIPTION | ||
| 893 | </para> | ||
| 894 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 895 | align="char"> | ||
| 896 | <para>Releases the resources allocated with allocate_section_feed(), including | ||
| 897 | allocated filters. Any filtering in progress on the section feed should be stopped | ||
| 898 | before calling this function.</para> | ||
| 899 | </entry> | ||
| 900 | </row></tbody></tgroup></informaltable> | ||
| 901 | <para>SYNOPSIS | ||
| 902 | </para> | ||
| 903 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 904 | align="char"> | ||
| 905 | <para>int release_section_feed(dmx_demux_t⋆ demux, | ||
| 906 | dmx_section_feed_t ⋆feed);</para> | ||
| 907 | </entry> | ||
| 908 | </row></tbody></tgroup></informaltable> | ||
| 909 | <para>PARAMETERS | ||
| 910 | </para> | ||
| 911 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 912 | align="char"> | ||
| 913 | <para>demux_t *demux</para> | ||
| 914 | </entry><entry | ||
| 915 | align="char"> | ||
| 916 | <para>Pointer to the demux API and instance data.</para> | ||
| 917 | </entry> | ||
| 918 | </row><row><entry | ||
| 919 | align="char"> | ||
| 920 | <para>dmx_section_feed_t | ||
| 921 | *feed</para> | ||
| 922 | </entry><entry | ||
| 923 | align="char"> | ||
| 924 | <para>Pointer to the section feed API and instance data.</para> | ||
| 925 | </entry> | ||
| 926 | </row></tbody></tgroup></informaltable> | ||
| 927 | <para>RETURNS | ||
| 928 | </para> | ||
| 929 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 930 | align="char"> | ||
| 931 | <para>0</para> | ||
| 932 | </entry><entry | ||
| 933 | align="char"> | ||
| 934 | <para>The function was completed without errors.</para> | ||
| 935 | </entry> | ||
| 936 | </row><row><entry | ||
| 937 | align="char"> | ||
| 938 | <para>-EINVAL</para> | ||
| 939 | </entry><entry | ||
| 940 | align="char"> | ||
| 941 | <para>Bad parameter.</para> | ||
| 942 | </entry> | ||
| 943 | </row></tbody></tgroup></informaltable> | ||
| 944 | |||
| 945 | </section><section | ||
| 946 | role="subsection"><title>descramble_mac_address()</title> | ||
| 947 | <para>DESCRIPTION | ||
| 948 | </para> | ||
| 949 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 950 | align="char"> | ||
| 951 | <para>This function runs a descrambling algorithm on the destination MAC | ||
| 952 | address field of a DVB Datagram Section, replacing the original address | ||
| 953 | with its un-encrypted version. Otherwise, the description on the function | ||
| 954 | descramble_section_payload() applies also to this function.</para> | ||
| 955 | </entry> | ||
| 956 | </row></tbody></tgroup></informaltable> | ||
| 957 | <para>SYNOPSIS | ||
| 958 | </para> | ||
| 959 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 960 | align="char"> | ||
| 961 | <para>int descramble_mac_address(dmx_demux_t⋆ demux, __u8 | ||
| 962 | ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, | ||
| 963 | size_t buffer2_length, __u16 pid);</para> | ||
| 964 | </entry> | ||
| 965 | </row></tbody></tgroup></informaltable> | ||
| 966 | <para>PARAMETERS | ||
| 967 | </para> | ||
| 968 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 969 | align="char"> | ||
| 970 | <para>dmx_demux_t | ||
| 971 | *demux</para> | ||
| 972 | </entry><entry | ||
| 973 | align="char"> | ||
| 974 | <para>Pointer to the demux API and instance data.</para> | ||
| 975 | </entry> | ||
| 976 | </row><row><entry | ||
| 977 | align="char"> | ||
| 978 | <para>__u8 *buffer1</para> | ||
| 979 | </entry><entry | ||
| 980 | align="char"> | ||
| 981 | <para>Pointer to the first byte of the section.</para> | ||
| 982 | </entry> | ||
| 983 | </row><row><entry | ||
| 984 | align="char"> | ||
| 985 | <para>size_t buffer1_length</para> | ||
| 986 | </entry><entry | ||
| 987 | align="char"> | ||
| 988 | <para>Length of the section data, including headers and CRC, | ||
| 989 | in buffer1.</para> | ||
| 990 | </entry> | ||
| 991 | </row><row><entry | ||
| 992 | align="char"> | ||
| 993 | <para>__u8* buffer2</para> | ||
| 994 | </entry><entry | ||
| 995 | align="char"> | ||
| 996 | <para>Pointer to the tail of the section data, or NULL. The | ||
| 997 | pointer has a non-NULL value if the section wraps past | ||
| 998 | the end of a circular buffer.</para> | ||
| 999 | </entry> | ||
| 1000 | </row><row><entry | ||
| 1001 | align="char"> | ||
| 1002 | <para>size_t buffer2_length</para> | ||
| 1003 | </entry><entry | ||
| 1004 | align="char"> | ||
| 1005 | <para>Length of the section data, including headers and CRC, | ||
| 1006 | in buffer2.</para> | ||
| 1007 | </entry> | ||
| 1008 | </row><row><entry | ||
| 1009 | align="char"> | ||
| 1010 | <para>__u16 pid</para> | ||
| 1011 | </entry><entry | ||
| 1012 | align="char"> | ||
| 1013 | <para>The PID on which the section was received. Useful | ||
| 1014 | for obtaining the descrambling key, e.g. from a DVB | ||
| 1015 | Common Access facility.</para> | ||
| 1016 | </entry> | ||
| 1017 | </row></tbody></tgroup></informaltable> | ||
| 1018 | <para>RETURNS | ||
| 1019 | </para> | ||
| 1020 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1021 | align="char"> | ||
| 1022 | <para>0</para> | ||
| 1023 | </entry><entry | ||
| 1024 | align="char"> | ||
| 1025 | <para>The function was completed without errors.</para> | ||
| 1026 | </entry> | ||
| 1027 | </row><row><entry | ||
| 1028 | align="char"> | ||
| 1029 | <para>-ENOSYS</para> | ||
| 1030 | </entry><entry | ||
| 1031 | align="char"> | ||
| 1032 | <para>No descrambling facility available.</para> | ||
| 1033 | </entry> | ||
| 1034 | </row><row><entry | ||
| 1035 | align="char"> | ||
| 1036 | <para>-EINVAL</para> | ||
| 1037 | </entry><entry | ||
| 1038 | align="char"> | ||
| 1039 | <para>Bad parameter.</para> | ||
| 1040 | </entry> | ||
| 1041 | </row></tbody></tgroup></informaltable> | ||
| 1042 | |||
| 1043 | </section><section | ||
| 1044 | role="subsection"><title>descramble_section_payload()</title> | ||
| 1045 | <para>DESCRIPTION | ||
| 1046 | </para> | ||
| 1047 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1048 | align="char"> | ||
| 1049 | <para>This function runs a descrambling algorithm on the payload of a DVB | ||
| 1050 | Datagram Section, replacing the original payload with its un-encrypted | ||
| 1051 | version. The function will be called from the demux API implementation; | ||
| 1052 | the API client need not call this function directly. Section-level scrambling | ||
| 1053 | algorithms are currently standardized only for DVB-RCC (return channel | ||
| 1054 | over 2-directional cable TV network) systems. For all other DVB networks, | ||
| 1055 | encryption schemes are likely to be proprietary to each data broadcaster. Thus, | ||
| 1056 | it is expected that this function pointer will have the value of NULL (i.e., | ||
| 1057 | function not available) in most demux API implementations. Nevertheless, it | ||
| 1058 | should be possible to use the function pointer as a hook for dynamically adding | ||
| 1059 | a “plug-in” descrambling facility to a demux driver.</para> | ||
| 1060 | </entry> | ||
| 1061 | </row><row><entry | ||
| 1062 | align="char"> | ||
| 1063 | <para>While this function is not needed with hardware-based section descrambling, | ||
| 1064 | the descramble_section_payload function pointer can be used to override the | ||
| 1065 | default hardware-based descrambling algorithm: if the function pointer has a | ||
| 1066 | non-NULL value, the corresponding function should be used instead of any | ||
| 1067 | descrambling hardware.</para> | ||
| 1068 | </entry> | ||
| 1069 | </row></tbody></tgroup></informaltable> | ||
| 1070 | <para>SYNOPSIS | ||
| 1071 | </para> | ||
| 1072 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1073 | align="char"> | ||
| 1074 | <para>int descramble_section_payload(dmx_demux_t⋆ demux, | ||
| 1075 | __u8 ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, | ||
| 1076 | size_t buffer2_length, __u16 pid);</para> | ||
| 1077 | </entry> | ||
| 1078 | </row></tbody></tgroup></informaltable> | ||
| 1079 | <para>PARAMETERS | ||
| 1080 | </para> | ||
| 1081 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1082 | align="char"> | ||
| 1083 | <para>dmx_demux_t | ||
| 1084 | *demux</para> | ||
| 1085 | </entry><entry | ||
| 1086 | align="char"> | ||
| 1087 | <para>Pointer to the demux API and instance data.</para> | ||
| 1088 | </entry> | ||
| 1089 | </row><row><entry | ||
| 1090 | align="char"> | ||
| 1091 | <para>__u8 *buffer1</para> | ||
| 1092 | </entry><entry | ||
| 1093 | align="char"> | ||
| 1094 | <para>Pointer to the first byte of the section.</para> | ||
| 1095 | </entry> | ||
| 1096 | </row><row><entry | ||
| 1097 | align="char"> | ||
| 1098 | <para>size_t buffer1_length</para> | ||
| 1099 | </entry><entry | ||
| 1100 | align="char"> | ||
| 1101 | <para>Length of the section data, including headers and CRC, | ||
| 1102 | in buffer1.</para> | ||
| 1103 | </entry> | ||
| 1104 | </row><row><entry | ||
| 1105 | align="char"> | ||
| 1106 | <para>__u8 *buffer2</para> | ||
| 1107 | </entry><entry | ||
| 1108 | align="char"> | ||
| 1109 | <para>Pointer to the tail of the section data, or NULL. The | ||
| 1110 | pointer has a non-NULL value if the section wraps past | ||
| 1111 | the end of a circular buffer.</para> | ||
| 1112 | </entry> | ||
| 1113 | </row><row><entry | ||
| 1114 | align="char"> | ||
| 1115 | <para>size_t buffer2_length</para> | ||
| 1116 | </entry><entry | ||
| 1117 | align="char"> | ||
| 1118 | <para>Length of the section data, including headers and CRC, | ||
| 1119 | in buffer2.</para> | ||
| 1120 | </entry> | ||
| 1121 | </row><row><entry | ||
| 1122 | align="char"> | ||
| 1123 | <para>__u16 pid</para> | ||
| 1124 | </entry><entry | ||
| 1125 | align="char"> | ||
| 1126 | <para>The PID on which the section was received. Useful | ||
| 1127 | for obtaining the descrambling key, e.g. from a DVB | ||
| 1128 | Common Access facility.</para> | ||
| 1129 | </entry> | ||
| 1130 | </row></tbody></tgroup></informaltable> | ||
| 1131 | <para>RETURNS | ||
| 1132 | </para> | ||
| 1133 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1134 | align="char"> | ||
| 1135 | <para>0</para> | ||
| 1136 | </entry><entry | ||
| 1137 | align="char"> | ||
| 1138 | <para>The function was completed without errors.</para> | ||
| 1139 | </entry> | ||
| 1140 | </row><row><entry | ||
| 1141 | align="char"> | ||
| 1142 | <para>-ENOSYS</para> | ||
| 1143 | </entry><entry | ||
| 1144 | align="char"> | ||
| 1145 | <para>No descrambling facility available.</para> | ||
| 1146 | </entry> | ||
| 1147 | </row><row><entry | ||
| 1148 | align="char"> | ||
| 1149 | <para>-EINVAL</para> | ||
| 1150 | </entry><entry | ||
| 1151 | align="char"> | ||
| 1152 | <para>Bad parameter.</para> | ||
| 1153 | </entry> | ||
| 1154 | </row></tbody></tgroup></informaltable> | ||
| 1155 | |||
| 1156 | </section><section | ||
| 1157 | role="subsection"><title>add_frontend()</title> | ||
| 1158 | <para>DESCRIPTION | ||
| 1159 | </para> | ||
| 1160 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1161 | align="char"> | ||
| 1162 | <para>Registers a connectivity between a demux and a front-end, i.e., indicates that | ||
| 1163 | the demux can be connected via a call to connect_frontend() to use the given | ||
| 1164 | front-end as a TS source. The client of this function has to allocate dynamic or | ||
| 1165 | static memory for the frontend structure and initialize its fields before calling | ||
| 1166 | this function. This function is normally called during the driver initialization. | ||
| 1167 | The caller must not free the memory of the frontend struct before successfully | ||
| 1168 | calling remove_frontend().</para> | ||
| 1169 | </entry> | ||
| 1170 | </row></tbody></tgroup></informaltable> | ||
| 1171 | <para>SYNOPSIS | ||
| 1172 | </para> | ||
| 1173 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1174 | align="char"> | ||
| 1175 | <para>int add_frontend(dmx_demux_t ⋆demux, dmx_frontend_t | ||
| 1176 | ⋆frontend);</para> | ||
| 1177 | </entry> | ||
| 1178 | </row></tbody></tgroup></informaltable> | ||
| 1179 | <para>PARAMETERS | ||
| 1180 | </para> | ||
| 1181 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1182 | align="char"> | ||
| 1183 | <para>dmx_demux_t* | ||
| 1184 | demux</para> | ||
| 1185 | </entry><entry | ||
| 1186 | align="char"> | ||
| 1187 | <para>Pointer to the demux API and instance data.</para> | ||
| 1188 | </entry> | ||
| 1189 | </row><row><entry | ||
| 1190 | align="char"> | ||
| 1191 | <para>dmx_frontend_t* | ||
| 1192 | frontend</para> | ||
| 1193 | </entry><entry | ||
| 1194 | align="char"> | ||
| 1195 | <para>Pointer to the front-end instance data.</para> | ||
| 1196 | </entry> | ||
| 1197 | </row></tbody></tgroup></informaltable> | ||
| 1198 | <para>RETURNS | ||
| 1199 | </para> | ||
| 1200 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1201 | align="char"> | ||
| 1202 | <para>0</para> | ||
| 1203 | </entry><entry | ||
| 1204 | align="char"> | ||
| 1205 | <para>The function was completed without errors.</para> | ||
| 1206 | </entry> | ||
| 1207 | </row><row><entry | ||
| 1208 | align="char"> | ||
| 1209 | <para>-EEXIST</para> | ||
| 1210 | </entry><entry | ||
| 1211 | align="char"> | ||
| 1212 | <para>A front-end with the same value of the id field already | ||
| 1213 | registered.</para> | ||
| 1214 | </entry> | ||
| 1215 | </row><row><entry | ||
| 1216 | align="char"> | ||
| 1217 | <para>-EINUSE</para> | ||
| 1218 | </entry><entry | ||
| 1219 | align="char"> | ||
| 1220 | <para>The demux is in use.</para> | ||
| 1221 | </entry> | ||
| 1222 | </row><row><entry | ||
| 1223 | align="char"> | ||
| 1224 | <para>-ENOMEM</para> | ||
| 1225 | </entry><entry | ||
| 1226 | align="char"> | ||
| 1227 | <para>No more front-ends can be added.</para> | ||
| 1228 | </entry> | ||
| 1229 | </row><row><entry | ||
| 1230 | align="char"> | ||
| 1231 | <para>-EINVAL</para> | ||
| 1232 | </entry><entry | ||
| 1233 | align="char"> | ||
| 1234 | <para>Bad parameter.</para> | ||
| 1235 | </entry> | ||
| 1236 | </row></tbody></tgroup></informaltable> | ||
| 1237 | |||
| 1238 | </section><section | ||
| 1239 | role="subsection"><title>remove_frontend()</title> | ||
| 1240 | <para>DESCRIPTION | ||
| 1241 | </para> | ||
| 1242 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1243 | align="char"> | ||
| 1244 | <para>Indicates that the given front-end, registered by a call to add_frontend(), can | ||
| 1245 | no longer be connected as a TS source by this demux. The function should be | ||
| 1246 | called when a front-end driver or a demux driver is removed from the system. | ||
| 1247 | If the front-end is in use, the function fails with the return value of -EBUSY. | ||
| 1248 | After successfully calling this function, the caller can free the memory of | ||
| 1249 | the frontend struct if it was dynamically allocated before the add_frontend() | ||
| 1250 | operation.</para> | ||
| 1251 | </entry> | ||
| 1252 | </row></tbody></tgroup></informaltable> | ||
| 1253 | <para>SYNOPSIS | ||
| 1254 | </para> | ||
| 1255 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1256 | align="char"> | ||
| 1257 | <para>int remove_frontend(dmx_demux_t⋆ demux, | ||
| 1258 | dmx_frontend_t⋆ frontend);</para> | ||
| 1259 | </entry> | ||
| 1260 | </row></tbody></tgroup></informaltable> | ||
| 1261 | <para>PARAMETERS | ||
| 1262 | </para> | ||
| 1263 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1264 | align="char"> | ||
| 1265 | <para>dmx_demux_t* | ||
| 1266 | demux</para> | ||
| 1267 | </entry><entry | ||
| 1268 | align="char"> | ||
| 1269 | <para>Pointer to the demux API and instance data.</para> | ||
| 1270 | </entry> | ||
| 1271 | </row><row><entry | ||
| 1272 | align="char"> | ||
| 1273 | <para>dmx_frontend_t* | ||
| 1274 | frontend</para> | ||
| 1275 | </entry><entry | ||
| 1276 | align="char"> | ||
| 1277 | <para>Pointer to the front-end instance data.</para> | ||
| 1278 | </entry> | ||
| 1279 | </row></tbody></tgroup></informaltable> | ||
| 1280 | <para>RETURNS | ||
| 1281 | </para> | ||
| 1282 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1283 | align="char"> | ||
| 1284 | <para>0</para> | ||
| 1285 | </entry><entry | ||
| 1286 | align="char"> | ||
| 1287 | <para>The function was completed without errors.</para> | ||
| 1288 | </entry> | ||
| 1289 | </row><row><entry | ||
| 1290 | align="char"> | ||
| 1291 | <para>-EINVAL</para> | ||
| 1292 | </entry><entry | ||
| 1293 | align="char"> | ||
| 1294 | <para>Bad parameter.</para> | ||
| 1295 | </entry> | ||
| 1296 | </row><row><entry | ||
| 1297 | align="char"> | ||
| 1298 | <para>-EBUSY</para> | ||
| 1299 | </entry><entry | ||
| 1300 | align="char"> | ||
| 1301 | <para>The front-end is in use, i.e. a call to connect_frontend() | ||
| 1302 | has not been followed by a call to disconnect_frontend().</para> | ||
| 1303 | </entry> | ||
| 1304 | </row></tbody></tgroup></informaltable> | ||
| 1305 | |||
| 1306 | </section><section | ||
| 1307 | role="subsection"><title>get_frontends()</title> | ||
| 1308 | <para>DESCRIPTION | ||
| 1309 | </para> | ||
| 1310 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1311 | align="char"> | ||
| 1312 | <para>Provides the APIs of the front-ends that have been registered for this demux. | ||
| 1313 | Any of the front-ends obtained with this call can be used as a parameter for | ||
| 1314 | connect_frontend().</para> | ||
| 1315 | </entry> | ||
| 1316 | </row><row><entry | ||
| 1317 | align="char"> | ||
| 1318 | <para>The include file demux.h contains the macro DMX_FE_ENTRY() for | ||
| 1319 | converting an element of the generic type struct list_head* to the type | ||
| 1320 | dmx_frontend_t*. The caller must not free the memory of any of the elements | ||
| 1321 | obtained via this function call.</para> | ||
| 1322 | </entry> | ||
| 1323 | </row></tbody></tgroup></informaltable> | ||
| 1324 | <para>SYNOPSIS | ||
| 1325 | </para> | ||
| 1326 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1327 | align="char"> | ||
| 1328 | <para>struct list_head⋆ get_frontends(dmx_demux_t⋆ demux);</para> | ||
| 1329 | </entry> | ||
| 1330 | </row></tbody></tgroup></informaltable> | ||
| 1331 | <para>PARAMETERS | ||
| 1332 | </para> | ||
| 1333 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1334 | align="char"> | ||
| 1335 | <para>dmx_demux_t* | ||
| 1336 | demux</para> | ||
| 1337 | </entry><entry | ||
| 1338 | align="char"> | ||
| 1339 | <para>Pointer to the demux API and instance data.</para> | ||
| 1340 | </entry> | ||
| 1341 | </row></tbody></tgroup></informaltable> | ||
| 1342 | <para>RETURNS | ||
| 1343 | </para> | ||
| 1344 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1345 | align="char"> | ||
| 1346 | <para>dmx_demux_t*</para> | ||
| 1347 | </entry><entry | ||
| 1348 | align="char"> | ||
| 1349 | <para>A list of front-end interfaces, or NULL in the case of an | ||
| 1350 | empty list.</para> | ||
| 1351 | </entry> | ||
| 1352 | </row></tbody></tgroup></informaltable> | ||
| 1353 | |||
| 1354 | </section><section | ||
| 1355 | role="subsection"><title>connect_frontend()</title> | ||
| 1356 | <para>DESCRIPTION | ||
| 1357 | </para> | ||
| 1358 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1359 | align="char"> | ||
| 1360 | <para>Connects the TS output of the front-end to the input of the demux. A demux | ||
| 1361 | can only be connected to a front-end registered to the demux with the function | ||
| 1362 | add_frontend().</para> | ||
| 1363 | </entry> | ||
| 1364 | </row><row><entry | ||
| 1365 | align="char"> | ||
| 1366 | <para>It may or may not be possible to connect multiple demuxes to the same | ||
| 1367 | front-end, depending on the capabilities of the HW platform. When not used, | ||
| 1368 | the front-end should be released by calling disconnect_frontend().</para> | ||
| 1369 | </entry> | ||
| 1370 | </row></tbody></tgroup></informaltable> | ||
| 1371 | <para>SYNOPSIS | ||
| 1372 | </para> | ||
| 1373 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1374 | align="char"> | ||
| 1375 | <para>int connect_frontend(dmx_demux_t⋆ demux, | ||
| 1376 | dmx_frontend_t⋆ frontend);</para> | ||
| 1377 | </entry> | ||
| 1378 | </row></tbody></tgroup></informaltable> | ||
| 1379 | <para>PARAMETERS | ||
| 1380 | </para> | ||
| 1381 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1382 | align="char"> | ||
| 1383 | <para>dmx_demux_t* | ||
| 1384 | demux</para> | ||
| 1385 | </entry><entry | ||
| 1386 | align="char"> | ||
| 1387 | <para>Pointer to the demux API and instance data.</para> | ||
| 1388 | </entry> | ||
| 1389 | </row><row><entry | ||
| 1390 | align="char"> | ||
| 1391 | <para>dmx_frontend_t* | ||
| 1392 | frontend</para> | ||
| 1393 | </entry><entry | ||
| 1394 | align="char"> | ||
| 1395 | <para>Pointer to the front-end instance data.</para> | ||
| 1396 | </entry> | ||
| 1397 | </row></tbody></tgroup></informaltable> | ||
| 1398 | <para>RETURNS | ||
| 1399 | </para> | ||
| 1400 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1401 | align="char"> | ||
| 1402 | <para>0</para> | ||
| 1403 | </entry><entry | ||
| 1404 | align="char"> | ||
| 1405 | <para>The function was completed without errors.</para> | ||
| 1406 | </entry> | ||
| 1407 | </row><row><entry | ||
| 1408 | align="char"> | ||
| 1409 | <para>-EINVAL</para> | ||
| 1410 | </entry><entry | ||
| 1411 | align="char"> | ||
| 1412 | <para>Bad parameter.</para> | ||
| 1413 | </entry> | ||
| 1414 | </row><row><entry | ||
| 1415 | align="char"> | ||
| 1416 | <para>-EBUSY</para> | ||
| 1417 | </entry><entry | ||
| 1418 | align="char"> | ||
| 1419 | <para>The front-end is in use.</para> | ||
| 1420 | </entry> | ||
| 1421 | </row></tbody></tgroup></informaltable> | ||
| 1422 | |||
| 1423 | </section><section | ||
| 1424 | role="subsection"><title>disconnect_frontend()</title> | ||
| 1425 | <para>DESCRIPTION | ||
| 1426 | </para> | ||
| 1427 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1428 | align="char"> | ||
| 1429 | <para>Disconnects the demux and a front-end previously connected by a | ||
| 1430 | connect_frontend() call.</para> | ||
| 1431 | </entry> | ||
| 1432 | </row></tbody></tgroup></informaltable> | ||
| 1433 | <para>SYNOPSIS | ||
| 1434 | </para> | ||
| 1435 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1436 | align="char"> | ||
| 1437 | <para>int disconnect_frontend(dmx_demux_t⋆ demux);</para> | ||
| 1438 | </entry> | ||
| 1439 | </row></tbody></tgroup></informaltable> | ||
| 1440 | <para>PARAMETERS | ||
| 1441 | </para> | ||
| 1442 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1443 | align="char"> | ||
| 1444 | <para>dmx_demux_t* | ||
| 1445 | demux</para> | ||
| 1446 | </entry><entry | ||
| 1447 | align="char"> | ||
| 1448 | <para>Pointer to the demux API and instance data.</para> | ||
| 1449 | </entry> | ||
| 1450 | </row></tbody></tgroup></informaltable> | ||
| 1451 | <para>RETURNS | ||
| 1452 | </para> | ||
| 1453 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1454 | align="char"> | ||
| 1455 | <para>0</para> | ||
| 1456 | </entry><entry | ||
| 1457 | align="char"> | ||
| 1458 | <para>The function was completed without errors.</para> | ||
| 1459 | </entry> | ||
| 1460 | </row><row><entry | ||
| 1461 | align="char"> | ||
| 1462 | <para>-EINVAL</para> | ||
| 1463 | </entry><entry | ||
| 1464 | align="char"> | ||
| 1465 | <para>Bad parameter.</para> | ||
| 1466 | </entry> | ||
| 1467 | </row></tbody></tgroup></informaltable> | ||
| 1468 | </section></section> | ||
| 1469 | <section id="demux_callback_api"> | ||
| 1470 | <title>Demux Callback API</title> | ||
| 1471 | <para>This kernel-space API comprises the callback functions that deliver filtered data to the | ||
| 1472 | demux client. Unlike the other APIs, these API functions are provided by the client and called | ||
| 1473 | from the demux code. | ||
| 1474 | </para> | ||
| 1475 | <para>The function pointers of this abstract interface are not packed into a structure as in the | ||
| 1476 | other demux APIs, because the callback functions are registered and used independent | ||
| 1477 | of each other. As an example, it is possible for the API client to provide several | ||
| 1478 | callback functions for receiving TS packets and no callbacks for PES packets or | ||
| 1479 | sections. | ||
| 1480 | </para> | ||
| 1481 | <para>The functions that implement the callback API need not be re-entrant: when a demux | ||
| 1482 | driver calls one of these functions, the driver is not allowed to call the function again before | ||
| 1483 | the original call returns. If a callback is triggered by a hardware interrupt, it is recommended | ||
| 1484 | to use the Linux “bottom half” mechanism or start a tasklet instead of making the callback | ||
| 1485 | function call directly from a hardware interrupt. | ||
| 1486 | </para> | ||
| 1487 | |||
| 1488 | <section | ||
| 1489 | role="subsection"><title>dmx_ts_cb()</title> | ||
| 1490 | <para>DESCRIPTION | ||
| 1491 | </para> | ||
| 1492 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1493 | align="char"> | ||
| 1494 | <para>This function, provided by the client of the demux API, is called from the | ||
| 1495 | demux code. The function is only called when filtering on this TS feed has | ||
| 1496 | been enabled using the start_filtering() function.</para> | ||
| 1497 | </entry> | ||
| 1498 | </row><row><entry | ||
| 1499 | align="char"> | ||
| 1500 | <para>Any TS packets that match the filter settings are copied to a circular buffer. The | ||
| 1501 | filtered TS packets are delivered to the client using this callback function. The | ||
| 1502 | size of the circular buffer is controlled by the circular_buffer_size parameter | ||
| 1503 | of the set() function in the TS Feed API. It is expected that the buffer1 and | ||
| 1504 | buffer2 callback parameters point to addresses within the circular buffer, but | ||
| 1505 | other implementations are also possible. Note that the called party should not | ||
| 1506 | try to free the memory the buffer1 and buffer2 parameters point to.</para> | ||
| 1507 | </entry> | ||
| 1508 | </row><row><entry | ||
| 1509 | align="char"> | ||
| 1510 | <para>When this function is called, the buffer1 parameter typically points to the | ||
| 1511 | start of the first undelivered TS packet within a circular buffer. The buffer2 | ||
| 1512 | buffer parameter is normally NULL, except when the received TS packets have | ||
| 1513 | crossed the last address of the circular buffer and ”wrapped” to the beginning | ||
| 1514 | of the buffer. In the latter case the buffer1 parameter would contain an address | ||
| 1515 | within the circular buffer, while the buffer2 parameter would contain the first | ||
| 1516 | address of the circular buffer.</para> | ||
| 1517 | </entry> | ||
| 1518 | </row><row><entry | ||
| 1519 | align="char"> | ||
| 1520 | <para>The number of bytes delivered with this function (i.e. buffer1_length + | ||
| 1521 | buffer2_length) is usually equal to the value of callback_length parameter | ||
| 1522 | given in the set() function, with one exception: if a timeout occurs before | ||
| 1523 | receiving callback_length bytes of TS data, any undelivered packets are | ||
| 1524 | immediately delivered to the client by calling this function. The timeout | ||
| 1525 | duration is controlled by the set() function in the TS Feed API.</para> | ||
| 1526 | </entry> | ||
| 1527 | </row><row><entry | ||
| 1528 | align="char"> | ||
| 1529 | <para>If a TS packet is received with errors that could not be fixed by the TS-level | ||
| 1530 | forward error correction (FEC), the Transport_error_indicator flag of the TS | ||
| 1531 | packet header should be set. The TS packet should not be discarded, as | ||
| 1532 | the error can possibly be corrected by a higher layer protocol. If the called | ||
| 1533 | party is slow in processing the callback, it is possible that the circular buffer | ||
| 1534 | eventually fills up. If this happens, the demux driver should discard any TS | ||
| 1535 | packets received while the buffer is full. The error should be indicated to the | ||
| 1536 | client on the next callback by setting the success parameter to the value of | ||
| 1537 | DMX_OVERRUN_ERROR.</para> | ||
| 1538 | </entry> | ||
| 1539 | </row><row><entry | ||
| 1540 | align="char"> | ||
| 1541 | <para>The type of data returned to the callback can be selected by the new | ||
| 1542 | function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t | ||
| 1543 | pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the | ||
| 1544 | include file ost/demux.h) The type parameter decides if the raw TS packet | ||
| 1545 | (TS_PACKET) or just the payload (TS_PACKET—TS_PAYLOAD_ONLY) | ||
| 1546 | should be returned. If additionally the TS_DECODER bit is set the stream | ||
| 1547 | will also be sent to the hardware MPEG decoder. In this case, the second | ||
| 1548 | flag decides as what kind of data the stream should be interpreted. The | ||
| 1549 | possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO, | ||
| 1550 | DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE, | ||
| 1551 | DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para> | ||
| 1552 | </entry> | ||
| 1553 | </row></tbody></tgroup></informaltable> | ||
| 1554 | <para>SYNOPSIS | ||
| 1555 | </para> | ||
| 1556 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1557 | align="char"> | ||
| 1558 | <para>int dmx_ts_cb(__u8⋆ buffer1, size_t buffer1_length, | ||
| 1559 | __u8⋆ buffer2, size_t buffer2_length, dmx_ts_feed_t⋆ | ||
| 1560 | source, dmx_success_t success);</para> | ||
| 1561 | </entry> | ||
| 1562 | </row></tbody></tgroup></informaltable> | ||
| 1563 | <para>PARAMETERS | ||
| 1564 | </para> | ||
| 1565 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1566 | align="char"> | ||
| 1567 | <para>__u8* buffer1</para> | ||
| 1568 | </entry><entry | ||
| 1569 | align="char"> | ||
| 1570 | <para>Pointer to the start of the filtered TS packets.</para> | ||
| 1571 | </entry> | ||
| 1572 | </row><row><entry | ||
| 1573 | align="char"> | ||
| 1574 | <para>size_t buffer1_length</para> | ||
| 1575 | </entry><entry | ||
| 1576 | align="char"> | ||
| 1577 | <para>Length of the TS data in buffer1.</para> | ||
| 1578 | </entry> | ||
| 1579 | </row><row><entry | ||
| 1580 | align="char"> | ||
| 1581 | <para>__u8* buffer2</para> | ||
| 1582 | </entry><entry | ||
| 1583 | align="char"> | ||
| 1584 | <para>Pointer to the tail of the filtered TS packets, or NULL.</para> | ||
| 1585 | </entry> | ||
| 1586 | </row><row><entry | ||
| 1587 | align="char"> | ||
| 1588 | <para>size_t buffer2_length</para> | ||
| 1589 | </entry><entry | ||
| 1590 | align="char"> | ||
| 1591 | <para>Length of the TS data in buffer2.</para> | ||
| 1592 | </entry> | ||
| 1593 | </row><row><entry | ||
| 1594 | align="char"> | ||
| 1595 | <para>dmx_ts_feed_t* | ||
| 1596 | source</para> | ||
| 1597 | </entry><entry | ||
| 1598 | align="char"> | ||
| 1599 | <para>Indicates which TS feed is the source of the callback.</para> | ||
| 1600 | </entry> | ||
| 1601 | </row><row><entry | ||
| 1602 | align="char"> | ||
| 1603 | <para>dmx_success_t | ||
| 1604 | success</para> | ||
| 1605 | </entry><entry | ||
| 1606 | align="char"> | ||
| 1607 | <para>Indicates if there was an error in TS reception.</para> | ||
| 1608 | </entry> | ||
| 1609 | </row></tbody></tgroup></informaltable> | ||
| 1610 | <para>RETURNS | ||
| 1611 | </para> | ||
| 1612 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1613 | align="char"> | ||
| 1614 | <para>0</para> | ||
| 1615 | </entry><entry | ||
| 1616 | align="char"> | ||
| 1617 | <para>Continue filtering.</para> | ||
| 1618 | </entry> | ||
| 1619 | </row><row><entry | ||
| 1620 | align="char"> | ||
| 1621 | <para>-1</para> | ||
| 1622 | </entry><entry | ||
| 1623 | align="char"> | ||
| 1624 | <para>Stop filtering - has the same effect as a call to | ||
| 1625 | stop_filtering() on the TS Feed API.</para> | ||
| 1626 | </entry> | ||
| 1627 | </row></tbody></tgroup></informaltable> | ||
| 1628 | |||
| 1629 | </section><section | ||
| 1630 | role="subsection"><title>dmx_section_cb()</title> | ||
| 1631 | <para>DESCRIPTION | ||
| 1632 | </para> | ||
| 1633 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1634 | align="char"> | ||
| 1635 | <para>This function, provided by the client of the demux API, is called from the | ||
| 1636 | demux code. The function is only called when filtering of sections has been | ||
| 1637 | enabled using the function start_filtering() of the section feed API. When the | ||
| 1638 | demux driver has received a complete section that matches at least one section | ||
| 1639 | filter, the client is notified via this callback function. Normally this function is | ||
| 1640 | called for each received section; however, it is also possible to deliver multiple | ||
| 1641 | sections with one callback, for example when the system load is high. If an | ||
| 1642 | error occurs while receiving a section, this function should be called with | ||
| 1643 | the corresponding error type set in the success field, whether or not there is | ||
| 1644 | data to deliver. The Section Feed implementation should maintain a circular | ||
| 1645 | buffer for received sections. However, this is not necessary if the Section Feed | ||
| 1646 | API is implemented as a client of the TS Feed API, because the TS Feed | ||
| 1647 | implementation then buffers the received data. The size of the circular buffer | ||
| 1648 | can be configured using the set() function in the Section Feed API. If there | ||
| 1649 | is no room in the circular buffer when a new section is received, the section | ||
| 1650 | must be discarded. If this happens, the value of the success parameter should | ||
| 1651 | be DMX_OVERRUN_ERROR on the next callback.</para> | ||
| 1652 | </entry> | ||
| 1653 | </row></tbody></tgroup></informaltable> | ||
| 1654 | <para>SYNOPSIS | ||
| 1655 | </para> | ||
| 1656 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1657 | align="char"> | ||
| 1658 | <para>int dmx_section_cb(__u8⋆ buffer1, size_t | ||
| 1659 | buffer1_length, __u8⋆ buffer2, size_t | ||
| 1660 | buffer2_length, dmx_section_filter_t⋆ source, | ||
| 1661 | dmx_success_t success);</para> | ||
| 1662 | </entry> | ||
| 1663 | </row></tbody></tgroup></informaltable> | ||
| 1664 | <para>PARAMETERS | ||
| 1665 | </para> | ||
| 1666 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1667 | align="char"> | ||
| 1668 | <para>__u8* buffer1</para> | ||
| 1669 | </entry><entry | ||
| 1670 | align="char"> | ||
| 1671 | <para>Pointer to the start of the filtered section, e.g. within the | ||
| 1672 | circular buffer of the demux driver.</para> | ||
| 1673 | </entry> | ||
| 1674 | </row><row><entry | ||
| 1675 | align="char"> | ||
| 1676 | <para>size_t buffer1_length</para> | ||
| 1677 | </entry><entry | ||
| 1678 | align="char"> | ||
| 1679 | <para>Length of the filtered section data in buffer1, including | ||
| 1680 | headers and CRC.</para> | ||
| 1681 | </entry> | ||
| 1682 | </row><row><entry | ||
| 1683 | align="char"> | ||
| 1684 | <para>__u8* buffer2</para> | ||
| 1685 | </entry><entry | ||
| 1686 | align="char"> | ||
| 1687 | <para>Pointer to the tail of the filtered section data, or NULL. | ||
| 1688 | Useful to handle the wrapping of a circular buffer.</para> | ||
| 1689 | </entry> | ||
| 1690 | </row><row><entry | ||
| 1691 | align="char"> | ||
| 1692 | <para>size_t buffer2_length</para> | ||
| 1693 | </entry><entry | ||
| 1694 | align="char"> | ||
| 1695 | <para>Length of the filtered section data in buffer2, including | ||
| 1696 | headers and CRC.</para> | ||
| 1697 | </entry> | ||
| 1698 | </row><row><entry | ||
| 1699 | align="char"> | ||
| 1700 | <para>dmx_section_filter_t* | ||
| 1701 | filter</para> | ||
| 1702 | </entry><entry | ||
| 1703 | align="char"> | ||
| 1704 | <para>Indicates the filter that triggered the callback.</para> | ||
| 1705 | </entry> | ||
| 1706 | </row><row><entry | ||
| 1707 | align="char"> | ||
| 1708 | <para>dmx_success_t | ||
| 1709 | success</para> | ||
| 1710 | </entry><entry | ||
| 1711 | align="char"> | ||
| 1712 | <para>Indicates if there was an error in section reception.</para> | ||
| 1713 | </entry> | ||
| 1714 | </row></tbody></tgroup></informaltable> | ||
| 1715 | <para>RETURNS | ||
| 1716 | </para> | ||
| 1717 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1718 | align="char"> | ||
| 1719 | <para>0</para> | ||
| 1720 | </entry><entry | ||
| 1721 | align="char"> | ||
| 1722 | <para>Continue filtering.</para> | ||
| 1723 | </entry> | ||
| 1724 | </row><row><entry | ||
| 1725 | align="char"> | ||
| 1726 | <para>-1</para> | ||
| 1727 | </entry><entry | ||
| 1728 | align="char"> | ||
| 1729 | <para>Stop filtering - has the same effect as a call to | ||
| 1730 | stop_filtering() on the Section Feed API.</para> | ||
| 1731 | </entry> | ||
| 1732 | </row></tbody></tgroup></informaltable> | ||
| 1733 | </section></section> | ||
| 1734 | <section id="ts_feed_api"> | ||
| 1735 | <title>TS Feed API</title> | ||
| 1736 | <para>A TS feed is typically mapped to a hardware PID filter on the demux chip. | ||
| 1737 | Using this API, the client can set the filtering properties to start/stop filtering TS | ||
| 1738 | packets on a particular TS feed. The API is defined as an abstract interface of the type | ||
| 1739 | dmx_ts_feed_t. | ||
| 1740 | </para> | ||
| 1741 | <para>The functions that implement the interface should be defined static or module private. The | ||
| 1742 | client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the | ||
| 1743 | demux API. | ||
| 1744 | </para> | ||
| 1745 | |||
| 1746 | <section | ||
| 1747 | role="subsection"><title>set()</title> | ||
| 1748 | <para>DESCRIPTION | ||
| 1749 | </para> | ||
| 1750 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1751 | align="char"> | ||
| 1752 | <para>This function sets the parameters of a TS feed. Any filtering in progress on the | ||
| 1753 | TS feed must be stopped before calling this function.</para> | ||
| 1754 | </entry> | ||
| 1755 | </row></tbody></tgroup></informaltable> | ||
| 1756 | <para>SYNOPSIS | ||
| 1757 | </para> | ||
| 1758 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1759 | align="char"> | ||
| 1760 | <para>int set ( dmx_ts_feed_t⋆ feed, __u16 pid, size_t | ||
| 1761 | callback_length, size_t circular_buffer_size, int | ||
| 1762 | descramble, struct timespec timeout);</para> | ||
| 1763 | </entry> | ||
| 1764 | </row></tbody></tgroup></informaltable> | ||
| 1765 | <para>PARAMETERS | ||
| 1766 | </para> | ||
| 1767 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1768 | align="char"> | ||
| 1769 | <para>dmx_ts_feed_t* feed</para> | ||
| 1770 | </entry><entry | ||
| 1771 | align="char"> | ||
| 1772 | <para>Pointer to the TS feed API and instance data.</para> | ||
| 1773 | </entry> | ||
| 1774 | </row><row><entry | ||
| 1775 | align="char"> | ||
| 1776 | <para>__u16 pid</para> | ||
| 1777 | </entry><entry | ||
| 1778 | align="char"> | ||
| 1779 | <para>PID value to filter. Only the TS packets carrying the | ||
| 1780 | specified PID will be passed to the API client.</para> | ||
| 1781 | </entry> | ||
| 1782 | </row><row><entry | ||
| 1783 | align="char"> | ||
| 1784 | <para>size_t | ||
| 1785 | callback_length</para> | ||
| 1786 | </entry><entry | ||
| 1787 | align="char"> | ||
| 1788 | <para>Number of bytes to deliver with each call to the | ||
| 1789 | dmx_ts_cb() callback function. The value of this | ||
| 1790 | parameter should be a multiple of 188.</para> | ||
| 1791 | </entry> | ||
| 1792 | </row><row><entry | ||
| 1793 | align="char"> | ||
| 1794 | <para>size_t | ||
| 1795 | circular_buffer_size</para> | ||
| 1796 | </entry><entry | ||
| 1797 | align="char"> | ||
| 1798 | <para>Size of the circular buffer for the filtered TS packets.</para> | ||
| 1799 | </entry> | ||
| 1800 | </row><row><entry | ||
| 1801 | align="char"> | ||
| 1802 | <para>int descramble</para> | ||
| 1803 | </entry><entry | ||
| 1804 | align="char"> | ||
| 1805 | <para>If non-zero, descramble the filtered TS packets.</para> | ||
| 1806 | </entry> | ||
| 1807 | </row><row><entry | ||
| 1808 | align="char"> | ||
| 1809 | <para>struct timespec | ||
| 1810 | timeout</para> | ||
| 1811 | </entry><entry | ||
| 1812 | align="char"> | ||
| 1813 | <para>Maximum time to wait before delivering received TS | ||
| 1814 | packets to the client.</para> | ||
| 1815 | </entry> | ||
| 1816 | </row></tbody></tgroup></informaltable> | ||
| 1817 | <para>RETURNS | ||
| 1818 | </para> | ||
| 1819 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1820 | align="char"> | ||
| 1821 | <para>0</para> | ||
| 1822 | </entry><entry | ||
| 1823 | align="char"> | ||
| 1824 | <para>The function was completed without errors.</para> | ||
| 1825 | </entry> | ||
| 1826 | </row><row><entry | ||
| 1827 | align="char"> | ||
| 1828 | <para>-ENOMEM</para> | ||
| 1829 | </entry><entry | ||
| 1830 | align="char"> | ||
| 1831 | <para>Not enough memory for the requested buffer size.</para> | ||
| 1832 | </entry> | ||
| 1833 | </row><row><entry | ||
| 1834 | align="char"> | ||
| 1835 | <para>-ENOSYS</para> | ||
| 1836 | </entry><entry | ||
| 1837 | align="char"> | ||
| 1838 | <para>No descrambling facility available for TS.</para> | ||
| 1839 | </entry> | ||
| 1840 | </row><row><entry | ||
| 1841 | align="char"> | ||
| 1842 | <para>-EINVAL</para> | ||
| 1843 | </entry><entry | ||
| 1844 | align="char"> | ||
| 1845 | <para>Bad parameter.</para> | ||
| 1846 | </entry> | ||
| 1847 | </row></tbody></tgroup></informaltable> | ||
| 1848 | |||
| 1849 | </section><section | ||
| 1850 | role="subsection"><title>start_filtering()</title> | ||
| 1851 | <para>DESCRIPTION | ||
| 1852 | </para> | ||
| 1853 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1854 | align="char"> | ||
| 1855 | <para>Starts filtering TS packets on this TS feed, according to its settings. The PID | ||
| 1856 | value to filter can be set by the API client. All matching TS packets are | ||
| 1857 | delivered asynchronously to the client, using the callback function registered | ||
| 1858 | with allocate_ts_feed().</para> | ||
| 1859 | </entry> | ||
| 1860 | </row></tbody></tgroup></informaltable> | ||
| 1861 | <para>SYNOPSIS | ||
| 1862 | </para> | ||
| 1863 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1864 | align="char"> | ||
| 1865 | <para>int start_filtering(dmx_ts_feed_t⋆ feed);</para> | ||
| 1866 | </entry> | ||
| 1867 | </row></tbody></tgroup></informaltable> | ||
| 1868 | <para>PARAMETERS | ||
| 1869 | </para> | ||
| 1870 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1871 | align="char"> | ||
| 1872 | <para>dmx_ts_feed_t* feed</para> | ||
| 1873 | </entry><entry | ||
| 1874 | align="char"> | ||
| 1875 | <para>Pointer to the TS feed API and instance data.</para> | ||
| 1876 | </entry> | ||
| 1877 | </row></tbody></tgroup></informaltable> | ||
| 1878 | <para>RETURNS | ||
| 1879 | </para> | ||
| 1880 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1881 | align="char"> | ||
| 1882 | <para>0</para> | ||
| 1883 | </entry><entry | ||
| 1884 | align="char"> | ||
| 1885 | <para>The function was completed without errors.</para> | ||
| 1886 | </entry> | ||
| 1887 | </row><row><entry | ||
| 1888 | align="char"> | ||
| 1889 | <para>-EINVAL</para> | ||
| 1890 | </entry><entry | ||
| 1891 | align="char"> | ||
| 1892 | <para>Bad parameter.</para> | ||
| 1893 | </entry> | ||
| 1894 | </row></tbody></tgroup></informaltable> | ||
| 1895 | |||
| 1896 | </section><section | ||
| 1897 | role="subsection"><title>stop_filtering()</title> | ||
| 1898 | <para>DESCRIPTION | ||
| 1899 | </para> | ||
| 1900 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1901 | align="char"> | ||
| 1902 | <para>Stops filtering TS packets on this TS feed.</para> | ||
| 1903 | </entry> | ||
| 1904 | </row></tbody></tgroup></informaltable> | ||
| 1905 | <para>SYNOPSIS | ||
| 1906 | </para> | ||
| 1907 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1908 | align="char"> | ||
| 1909 | <para>int stop_filtering(dmx_ts_feed_t⋆ feed);</para> | ||
| 1910 | </entry> | ||
| 1911 | </row></tbody></tgroup></informaltable> | ||
| 1912 | <para>PARAMETERS | ||
| 1913 | </para> | ||
| 1914 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1915 | align="char"> | ||
| 1916 | <para>dmx_ts_feed_t* feed</para> | ||
| 1917 | </entry><entry | ||
| 1918 | align="char"> | ||
| 1919 | <para>Pointer to the TS feed API and instance data.</para> | ||
| 1920 | </entry> | ||
| 1921 | </row></tbody></tgroup></informaltable> | ||
| 1922 | <para>RETURNS | ||
| 1923 | </para> | ||
| 1924 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1925 | align="char"> | ||
| 1926 | <para>0</para> | ||
| 1927 | </entry><entry | ||
| 1928 | align="char"> | ||
| 1929 | <para>The function was completed without errors.</para> | ||
| 1930 | </entry> | ||
| 1931 | </row><row><entry | ||
| 1932 | align="char"> | ||
| 1933 | <para>-EINVAL</para> | ||
| 1934 | </entry><entry | ||
| 1935 | align="char"> | ||
| 1936 | <para>Bad parameter.</para> | ||
| 1937 | </entry> | ||
| 1938 | </row></tbody></tgroup></informaltable> | ||
| 1939 | </section></section> | ||
| 1940 | <section id="section_feed_api"> | ||
| 1941 | <title>Section Feed API</title> | ||
| 1942 | <para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this | ||
| 1943 | API, the client can set the properties of a section feed and to start/stop filtering. The API is | ||
| 1944 | defined as an abstract interface of the type dmx_section_feed_t. The functions that implement | ||
| 1945 | the interface should be defined static or module private. The client can get the handle of | ||
| 1946 | a section feed API by calling the function allocate_section_feed() in the demux | ||
| 1947 | API. | ||
| 1948 | </para> | ||
| 1949 | <para>On demux platforms that provide section filtering in hardware, the Section Feed API | ||
| 1950 | implementation provides a software wrapper for the demux hardware. Other platforms may | ||
| 1951 | support only PID filtering in hardware, requiring that TS packets are converted to sections in | ||
| 1952 | software. In the latter case the Section Feed API implementation can be a client of the TS | ||
| 1953 | Feed API. | ||
| 1954 | </para> | ||
| 1955 | |||
| 1956 | </section> | ||
| 1957 | <section id="kdapi_set"> | ||
| 1958 | <title>set()</title> | ||
| 1959 | <para>DESCRIPTION | ||
| 1960 | </para> | ||
| 1961 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1962 | align="char"> | ||
| 1963 | <para>This function sets the parameters of a section feed. Any filtering in progress on | ||
| 1964 | the section feed must be stopped before calling this function. If descrambling | ||
| 1965 | is enabled, the payload_scrambling_control and address_scrambling_control | ||
| 1966 | fields of received DVB datagram sections should be observed. If either one is | ||
| 1967 | non-zero, the section should be descrambled either in hardware or using the | ||
| 1968 | functions descramble_mac_address() and descramble_section_payload() of the | ||
| 1969 | demux API. Note that according to the MPEG-2 Systems specification, only | ||
| 1970 | the payloads of private sections can be scrambled while the rest of the section | ||
| 1971 | data must be sent in the clear.</para> | ||
| 1972 | </entry> | ||
| 1973 | </row></tbody></tgroup></informaltable> | ||
| 1974 | <para>SYNOPSIS | ||
| 1975 | </para> | ||
| 1976 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1977 | align="char"> | ||
| 1978 | <para>int set(dmx_section_feed_t⋆ feed, __u16 pid, size_t | ||
| 1979 | circular_buffer_size, int descramble, int | ||
| 1980 | check_crc);</para> | ||
| 1981 | </entry> | ||
| 1982 | </row></tbody></tgroup></informaltable> | ||
| 1983 | <para>PARAMETERS | ||
| 1984 | </para> | ||
| 1985 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1986 | align="char"> | ||
| 1987 | <para>dmx_section_feed_t* | ||
| 1988 | feed</para> | ||
| 1989 | </entry><entry | ||
| 1990 | align="char"> | ||
| 1991 | <para>Pointer to the section feed API and instance data.</para> | ||
| 1992 | </entry> | ||
| 1993 | </row><row><entry | ||
| 1994 | align="char"> | ||
| 1995 | <para>__u16 pid</para> | ||
| 1996 | </entry><entry | ||
| 1997 | align="char"> | ||
| 1998 | <para>PID value to filter; only the TS packets carrying the | ||
| 1999 | specified PID will be accepted.</para> | ||
| 2000 | </entry> | ||
| 2001 | </row><row><entry | ||
| 2002 | align="char"> | ||
| 2003 | <para>size_t | ||
| 2004 | circular_buffer_size</para> | ||
| 2005 | </entry><entry | ||
| 2006 | align="char"> | ||
| 2007 | <para>Size of the circular buffer for filtered sections.</para> | ||
| 2008 | </entry> | ||
| 2009 | </row><row><entry | ||
| 2010 | align="char"> | ||
| 2011 | <para>int descramble</para> | ||
| 2012 | </entry><entry | ||
| 2013 | align="char"> | ||
| 2014 | <para>If non-zero, descramble any sections that are scrambled.</para> | ||
| 2015 | </entry> | ||
| 2016 | </row><row><entry | ||
| 2017 | align="char"> | ||
| 2018 | <para>int check_crc</para> | ||
| 2019 | </entry><entry | ||
| 2020 | align="char"> | ||
| 2021 | <para>If non-zero, check the CRC values of filtered sections.</para> | ||
| 2022 | </entry> | ||
| 2023 | </row></tbody></tgroup></informaltable> | ||
| 2024 | <para>RETURNS | ||
| 2025 | </para> | ||
| 2026 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2027 | align="char"> | ||
| 2028 | <para>0</para> | ||
| 2029 | </entry><entry | ||
| 2030 | align="char"> | ||
| 2031 | <para>The function was completed without errors.</para> | ||
| 2032 | </entry> | ||
| 2033 | </row><row><entry | ||
| 2034 | align="char"> | ||
| 2035 | <para>-ENOMEM</para> | ||
| 2036 | </entry><entry | ||
| 2037 | align="char"> | ||
| 2038 | <para>Not enough memory for the requested buffer size.</para> | ||
| 2039 | </entry> | ||
| 2040 | </row><row><entry | ||
| 2041 | align="char"> | ||
| 2042 | <para>-ENOSYS</para> | ||
| 2043 | </entry><entry | ||
| 2044 | align="char"> | ||
| 2045 | <para>No descrambling facility available for sections.</para> | ||
| 2046 | </entry> | ||
| 2047 | </row><row><entry | ||
| 2048 | align="char"> | ||
| 2049 | <para>-EINVAL</para> | ||
| 2050 | </entry><entry | ||
| 2051 | align="char"> | ||
| 2052 | <para>Bad parameters.</para> | ||
| 2053 | </entry> | ||
| 2054 | </row></tbody></tgroup></informaltable> | ||
| 2055 | |||
| 2056 | </section><section | ||
| 2057 | role="subsection"><title>allocate_filter()</title> | ||
| 2058 | <para>DESCRIPTION | ||
| 2059 | </para> | ||
| 2060 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2061 | align="char"> | ||
| 2062 | <para>This function is used to allocate a section filter on the demux. It should only be | ||
| 2063 | called when no filtering is in progress on this section feed. If a filter cannot be | ||
| 2064 | allocated, the function fails with -ENOSPC. See in section ?? for the format of | ||
| 2065 | the section filter.</para> | ||
| 2066 | </entry> | ||
| 2067 | </row><row><entry | ||
| 2068 | align="char"> | ||
| 2069 | <para>The bitfields filter_mask and filter_value should only be modified when no | ||
| 2070 | filtering is in progress on this section feed. filter_mask controls which bits of | ||
| 2071 | filter_value are compared with the section headers/payload. On a binary value | ||
| 2072 | of 1 in filter_mask, the corresponding bits are compared. The filter only accepts | ||
| 2073 | sections that are equal to filter_value in all the tested bit positions. Any changes | ||
| 2074 | to the values of filter_mask and filter_value are guaranteed to take effect only | ||
| 2075 | when the start_filtering() function is called next time. The parent pointer in | ||
| 2076 | the struct is initialized by the API implementation to the value of the feed | ||
| 2077 | parameter. The priv pointer is not used by the API implementation, and can | ||
| 2078 | thus be freely utilized by the caller of this function. Any data pointed to by the | ||
| 2079 | priv pointer is available to the recipient of the dmx_section_cb() function call.</para> | ||
| 2080 | </entry> | ||
| 2081 | </row><row><entry | ||
| 2082 | align="char"> | ||
| 2083 | <para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is | ||
| 2084 | currently set at 16 bytes, hardware filters of that size are not available on all | ||
| 2085 | platforms. Therefore, section filtering will often take place first in hardware, | ||
| 2086 | followed by filtering in software for the header bytes that were not covered | ||
| 2087 | by a hardware filter. The filter_mask field can be checked to determine how | ||
| 2088 | many bytes of the section filter are actually used, and if the hardware filter will | ||
| 2089 | suffice. Additionally, software-only section filters can optionally be allocated | ||
| 2090 | to clients when all hardware section filters are in use. Note that on most demux | ||
| 2091 | hardware it is not possible to filter on the section_length field of the section | ||
| 2092 | header – thus this field is ignored, even though it is included in filter_value and | ||
| 2093 | filter_mask fields.</para> | ||
| 2094 | </entry> | ||
| 2095 | </row></tbody></tgroup></informaltable> | ||
| 2096 | <para>SYNOPSIS | ||
| 2097 | </para> | ||
| 2098 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2099 | align="char"> | ||
| 2100 | <para>int allocate_filter(dmx_section_feed_t⋆ feed, | ||
| 2101 | dmx_section_filter_t⋆⋆ filter);</para> | ||
| 2102 | </entry> | ||
| 2103 | </row></tbody></tgroup></informaltable> | ||
| 2104 | <para>PARAMETERS | ||
| 2105 | </para> | ||
| 2106 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2107 | align="char"> | ||
| 2108 | <para>dmx_section_feed_t* | ||
| 2109 | feed</para> | ||
| 2110 | </entry><entry | ||
| 2111 | align="char"> | ||
| 2112 | <para>Pointer to the section feed API and instance data.</para> | ||
| 2113 | </entry> | ||
| 2114 | </row><row><entry | ||
| 2115 | align="char"> | ||
| 2116 | <para>dmx_section_filter_t** | ||
| 2117 | filter</para> | ||
| 2118 | </entry><entry | ||
| 2119 | align="char"> | ||
| 2120 | <para>Pointer to the allocated filter.</para> | ||
| 2121 | </entry> | ||
| 2122 | </row></tbody></tgroup></informaltable> | ||
| 2123 | <para>RETURNS | ||
| 2124 | </para> | ||
| 2125 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2126 | align="char"> | ||
| 2127 | <para>0</para> | ||
| 2128 | </entry><entry | ||
| 2129 | align="char"> | ||
| 2130 | <para>The function was completed without errors.</para> | ||
| 2131 | </entry> | ||
| 2132 | </row><row><entry | ||
| 2133 | align="char"> | ||
| 2134 | <para>-ENOSPC</para> | ||
| 2135 | </entry><entry | ||
| 2136 | align="char"> | ||
| 2137 | <para>No filters of given type and length available.</para> | ||
| 2138 | </entry> | ||
| 2139 | </row><row><entry | ||
| 2140 | align="char"> | ||
| 2141 | <para>-EINVAL</para> | ||
| 2142 | </entry><entry | ||
| 2143 | align="char"> | ||
| 2144 | <para>Bad parameters.</para> | ||
| 2145 | </entry> | ||
| 2146 | </row></tbody></tgroup></informaltable> | ||
| 2147 | |||
| 2148 | </section><section | ||
| 2149 | role="subsection"><title>release_filter()</title> | ||
| 2150 | <para>DESCRIPTION | ||
| 2151 | </para> | ||
| 2152 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2153 | align="char"> | ||
| 2154 | <para>This function releases all the resources of a previously allocated section filter. | ||
| 2155 | The function should not be called while filtering is in progress on this section | ||
| 2156 | feed. After calling this function, the caller should not try to dereference the | ||
| 2157 | filter pointer.</para> | ||
| 2158 | </entry> | ||
| 2159 | </row></tbody></tgroup></informaltable> | ||
| 2160 | <para>SYNOPSIS | ||
| 2161 | </para> | ||
| 2162 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2163 | align="char"> | ||
| 2164 | <para>int release_filter ( dmx_section_feed_t⋆ feed, | ||
| 2165 | dmx_section_filter_t⋆ filter);</para> | ||
| 2166 | </entry> | ||
| 2167 | </row></tbody></tgroup></informaltable> | ||
| 2168 | <para>PARAMETERS | ||
| 2169 | </para> | ||
| 2170 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2171 | align="char"> | ||
| 2172 | <para>dmx_section_feed_t* | ||
| 2173 | feed</para> | ||
| 2174 | </entry><entry | ||
| 2175 | align="char"> | ||
| 2176 | <para>Pointer to the section feed API and instance data.</para> | ||
| 2177 | </entry> | ||
| 2178 | </row><row><entry | ||
| 2179 | align="char"> | ||
| 2180 | <para>dmx_section_filter_t* | ||
| 2181 | filter</para> | ||
| 2182 | </entry><entry | ||
| 2183 | align="char"> | ||
| 2184 | <para>I/O Pointer to the instance data of a section filter.</para> | ||
| 2185 | </entry> | ||
| 2186 | </row></tbody></tgroup></informaltable> | ||
| 2187 | <para>RETURNS | ||
| 2188 | </para> | ||
| 2189 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2190 | align="char"> | ||
| 2191 | <para>0</para> | ||
| 2192 | </entry><entry | ||
| 2193 | align="char"> | ||
| 2194 | <para>The function was completed without errors.</para> | ||
| 2195 | </entry> | ||
| 2196 | </row><row><entry | ||
| 2197 | align="char"> | ||
| 2198 | <para>-ENODEV</para> | ||
| 2199 | </entry><entry | ||
| 2200 | align="char"> | ||
| 2201 | <para>No such filter allocated.</para> | ||
| 2202 | </entry> | ||
| 2203 | </row><row><entry | ||
| 2204 | align="char"> | ||
| 2205 | <para>-EINVAL</para> | ||
| 2206 | </entry><entry | ||
| 2207 | align="char"> | ||
| 2208 | <para>Bad parameter.</para> | ||
| 2209 | </entry> | ||
| 2210 | </row></tbody></tgroup></informaltable> | ||
| 2211 | |||
| 2212 | </section><section | ||
| 2213 | role="subsection"><title>start_filtering()</title> | ||
| 2214 | <para>DESCRIPTION | ||
| 2215 | </para> | ||
| 2216 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2217 | align="char"> | ||
| 2218 | <para>Starts filtering sections on this section feed, according to its settings. Sections | ||
| 2219 | are first filtered based on their PID and then matched with the section | ||
| 2220 | filters allocated for this feed. If the section matches the PID filter and | ||
| 2221 | at least one section filter, it is delivered to the API client. The section | ||
| 2222 | is delivered asynchronously using the callback function registered with | ||
| 2223 | allocate_section_feed().</para> | ||
| 2224 | </entry> | ||
| 2225 | </row></tbody></tgroup></informaltable> | ||
| 2226 | <para>SYNOPSIS | ||
| 2227 | </para> | ||
| 2228 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2229 | align="char"> | ||
| 2230 | <para>int start_filtering ( dmx_section_feed_t⋆ feed );</para> | ||
| 2231 | </entry> | ||
| 2232 | </row></tbody></tgroup></informaltable> | ||
| 2233 | <para>PARAMETERS | ||
| 2234 | </para> | ||
| 2235 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2236 | align="char"> | ||
| 2237 | <para>dmx_section_feed_t* | ||
| 2238 | feed</para> | ||
| 2239 | </entry><entry | ||
| 2240 | align="char"> | ||
| 2241 | <para>Pointer to the section feed API and instance data.</para> | ||
| 2242 | </entry> | ||
| 2243 | </row></tbody></tgroup></informaltable> | ||
| 2244 | <para>RETURNS | ||
| 2245 | </para> | ||
| 2246 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2247 | align="char"> | ||
| 2248 | <para>0</para> | ||
| 2249 | </entry><entry | ||
| 2250 | align="char"> | ||
| 2251 | <para>The function was completed without errors.</para> | ||
| 2252 | </entry> | ||
| 2253 | </row><row><entry | ||
| 2254 | align="char"> | ||
| 2255 | <para>-EINVAL</para> | ||
| 2256 | </entry><entry | ||
| 2257 | align="char"> | ||
| 2258 | <para>Bad parameter.</para> | ||
| 2259 | </entry> | ||
| 2260 | </row></tbody></tgroup></informaltable> | ||
| 2261 | |||
| 2262 | </section><section | ||
| 2263 | role="subsection"><title>stop_filtering()</title> | ||
| 2264 | <para>DESCRIPTION | ||
| 2265 | </para> | ||
| 2266 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2267 | align="char"> | ||
| 2268 | <para>Stops filtering sections on this section feed. Note that any changes to the | ||
| 2269 | filtering parameters (filter_value, filter_mask, etc.) should only be made when | ||
| 2270 | filtering is stopped.</para> | ||
| 2271 | </entry> | ||
| 2272 | </row></tbody></tgroup></informaltable> | ||
| 2273 | <para>SYNOPSIS | ||
| 2274 | </para> | ||
| 2275 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 2276 | align="char"> | ||
| 2277 | <para>int stop_filtering ( dmx_section_feed_t⋆ feed );</para> | ||
| 2278 | </entry> | ||
| 2279 | </row></tbody></tgroup></informaltable> | ||
| 2280 | <para>PARAMETERS | ||
| 2281 | </para> | ||
| 2282 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2283 | align="char"> | ||
| 2284 | <para>dmx_section_feed_t* | ||
| 2285 | feed</para> | ||
| 2286 | </entry><entry | ||
| 2287 | align="char"> | ||
| 2288 | <para>Pointer to the section feed API and instance data.</para> | ||
| 2289 | </entry> | ||
| 2290 | </row></tbody></tgroup></informaltable> | ||
| 2291 | <para>RETURNS | ||
| 2292 | </para> | ||
| 2293 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 2294 | align="char"> | ||
| 2295 | <para>0</para> | ||
| 2296 | </entry><entry | ||
| 2297 | align="char"> | ||
| 2298 | <para>The function was completed without errors.</para> | ||
| 2299 | </entry> | ||
| 2300 | </row><row><entry | ||
| 2301 | align="char"> | ||
| 2302 | <para>-EINVAL</para> | ||
| 2303 | </entry><entry | ||
| 2304 | align="char"> | ||
| 2305 | <para>Bad parameter.</para> | ||
| 2306 | </entry> | ||
| 2307 | </row></tbody></tgroup></informaltable> | ||
| 2308 | |||
| 2309 | </section> | ||
diff --git a/Documentation/DocBook/dvb/net.xml b/Documentation/DocBook/dvb/net.xml new file mode 100644 index 000000000000..94e388d94c0d --- /dev/null +++ b/Documentation/DocBook/dvb/net.xml | |||
| @@ -0,0 +1,12 @@ | |||
| 1 | <title>DVB Network API</title> | ||
| 2 | <para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets | ||
| 3 | received via DVB into the Linux network protocol stack, e.g. for internet via satellite | ||
| 4 | applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and | ||
| 5 | and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your | ||
| 6 | application. | ||
| 7 | </para> | ||
| 8 | <section id="dvb_net_types"> | ||
| 9 | <title>DVB Net Data Types</title> | ||
| 10 | <para>To be written… | ||
| 11 | </para> | ||
| 12 | </section> | ||
diff --git a/Documentation/DocBook/dvb/video.xml b/Documentation/DocBook/dvb/video.xml new file mode 100644 index 000000000000..7bb287e67c8e --- /dev/null +++ b/Documentation/DocBook/dvb/video.xml | |||
| @@ -0,0 +1,1971 @@ | |||
| 1 | <title>DVB Video Device</title> | ||
| 2 | <para>The DVB video device controls the MPEG2 video decoder of the DVB hardware. It | ||
| 3 | can be accessed through <emphasis role="tt">/dev/dvb/adapter0/video0</emphasis>. Data types and and | ||
| 4 | ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your | ||
| 5 | application. | ||
| 6 | </para> | ||
| 7 | <para>Note that the DVB video device only controls decoding of the MPEG video stream, not | ||
| 8 | its presentation on the TV or computer screen. On PCs this is typically handled by an | ||
| 9 | associated video4linux device, e.g. <emphasis role="tt">/dev/video</emphasis>, which allows scaling and defining output | ||
| 10 | windows. | ||
| 11 | </para> | ||
| 12 | <para>Some DVB cards don’t have their own MPEG decoder, which results in the omission of | ||
| 13 | the audio and video device as well as the video4linux device. | ||
| 14 | </para> | ||
| 15 | <para>The ioctls that deal with SPUs (sub picture units) and navigation packets are only | ||
| 16 | supported on some MPEG decoders made for DVD playback. | ||
| 17 | </para> | ||
| 18 | <section id="video_types"> | ||
| 19 | <title>Video Data Types</title> | ||
| 20 | |||
| 21 | <section id="video_format_t"> | ||
| 22 | <title>video_format_t</title> | ||
| 23 | <para>The <emphasis role="tt">video_format_t</emphasis> data type defined by | ||
| 24 | </para> | ||
| 25 | <programlisting> | ||
| 26 | typedef enum { | ||
| 27 | VIDEO_FORMAT_4_3, | ||
| 28 | VIDEO_FORMAT_16_9 | ||
| 29 | } video_format_t; | ||
| 30 | </programlisting> | ||
| 31 | <para>is used in the VIDEO_SET_FORMAT function (??) to tell the driver which aspect ratio | ||
| 32 | the output hardware (e.g. TV) has. It is also used in the data structures video_status | ||
| 33 | (??) returned by VIDEO_GET_STATUS (??) and video_event (??) returned by | ||
| 34 | VIDEO_GET_EVENT (??) which report about the display format of the current video | ||
| 35 | stream. | ||
| 36 | </para> | ||
| 37 | </section> | ||
| 38 | |||
| 39 | <section id="video_display_format_t"> | ||
| 40 | <title>video_display_format_t</title> | ||
| 41 | <para>In case the display format of the video stream and of the display hardware differ the | ||
| 42 | application has to specify how to handle the cropping of the picture. This can be done using | ||
| 43 | the VIDEO_SET_DISPLAY_FORMAT call (??) which accepts | ||
| 44 | </para> | ||
| 45 | <programlisting> | ||
| 46 | typedef enum { | ||
| 47 | VIDEO_PAN_SCAN, | ||
| 48 | VIDEO_LETTER_BOX, | ||
| 49 | VIDEO_CENTER_CUT_OUT | ||
| 50 | } video_display_format_t; | ||
| 51 | </programlisting> | ||
| 52 | <para>as argument. | ||
| 53 | </para> | ||
| 54 | </section> | ||
| 55 | |||
| 56 | <section id="video_stream_source"> | ||
| 57 | <title>video stream source</title> | ||
| 58 | <para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take | ||
| 59 | the following values, depending on whether we are replaying from an internal (demuxer) or | ||
| 60 | external (user write) source. | ||
| 61 | </para> | ||
| 62 | <programlisting> | ||
| 63 | typedef enum { | ||
| 64 | VIDEO_SOURCE_DEMUX, | ||
| 65 | VIDEO_SOURCE_MEMORY | ||
| 66 | } video_stream_source_t; | ||
| 67 | </programlisting> | ||
| 68 | <para>VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the | ||
| 69 | DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY | ||
| 70 | is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system | ||
| 71 | call. | ||
| 72 | </para> | ||
| 73 | </section> | ||
| 74 | |||
| 75 | <section id="video_play_state"> | ||
| 76 | <title>video play state</title> | ||
| 77 | <para>The following values can be returned by the VIDEO_GET_STATUS call representing the | ||
| 78 | state of video playback. | ||
| 79 | </para> | ||
| 80 | <programlisting> | ||
| 81 | typedef enum { | ||
| 82 | VIDEO_STOPPED, | ||
| 83 | VIDEO_PLAYING, | ||
| 84 | VIDEO_FREEZED | ||
| 85 | } video_play_state_t; | ||
| 86 | </programlisting> | ||
| 87 | </section> | ||
| 88 | |||
| 89 | <section id="video_event"> | ||
| 90 | <title>struct video_event</title> | ||
| 91 | <para>The following is the structure of a video event as it is returned by the VIDEO_GET_EVENT | ||
| 92 | call. | ||
| 93 | </para> | ||
| 94 | <programlisting> | ||
| 95 | struct video_event { | ||
| 96 | int32_t type; | ||
| 97 | time_t timestamp; | ||
| 98 | union { | ||
| 99 | video_format_t video_format; | ||
| 100 | } u; | ||
| 101 | }; | ||
| 102 | </programlisting> | ||
| 103 | </section> | ||
| 104 | |||
| 105 | <section id="video_status"> | ||
| 106 | <title>struct video_status</title> | ||
| 107 | <para>The VIDEO_GET_STATUS call returns the following structure informing about various | ||
| 108 | states of the playback operation. | ||
| 109 | </para> | ||
| 110 | <programlisting> | ||
| 111 | struct video_status { | ||
| 112 | boolean video_blank; | ||
| 113 | video_play_state_t play_state; | ||
| 114 | video_stream_source_t stream_source; | ||
| 115 | video_format_t video_format; | ||
| 116 | video_displayformat_t display_format; | ||
| 117 | }; | ||
| 118 | </programlisting> | ||
| 119 | <para>If video_blank is set video will be blanked out if the channel is changed or if playback is | ||
| 120 | stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is | ||
| 121 | currently frozen, stopped, or being played back. The stream_source corresponds to the seleted | ||
| 122 | source for the video stream. It can come either from the demultiplexer or from memory. | ||
| 123 | The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently | ||
| 124 | played video stream. Finally, display_format corresponds to the selected cropping | ||
| 125 | mode in case the source video format is not the same as the format of the output | ||
| 126 | device. | ||
| 127 | </para> | ||
| 128 | </section> | ||
| 129 | |||
| 130 | <section id="video_still_picture"> | ||
| 131 | <title>struct video_still_picture</title> | ||
| 132 | <para>An I-frame displayed via the VIDEO_STILLPICTURE call is passed on within the | ||
| 133 | following structure. | ||
| 134 | </para> | ||
| 135 | <programlisting> | ||
| 136 | /⋆ pointer to and size of a single iframe in memory ⋆/ | ||
| 137 | struct video_still_picture { | ||
| 138 | char ⋆iFrame; | ||
| 139 | int32_t size; | ||
| 140 | }; | ||
| 141 | </programlisting> | ||
| 142 | </section> | ||
| 143 | |||
| 144 | <section id="video_caps"> | ||
| 145 | <title>video capabilities</title> | ||
| 146 | <para>A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the following | ||
| 147 | bits set according to the hardwares capabilities. | ||
| 148 | </para> | ||
| 149 | <programlisting> | ||
| 150 | /⋆ bit definitions for capabilities: ⋆/ | ||
| 151 | /⋆ can the hardware decode MPEG1 and/or MPEG2? ⋆/ | ||
| 152 | #define VIDEO_CAP_MPEG1 1 | ||
| 153 | #define VIDEO_CAP_MPEG2 2 | ||
| 154 | /⋆ can you send a system and/or program stream to video device? | ||
| 155 | (you still have to open the video and the audio device but only | ||
| 156 | send the stream to the video device) ⋆/ | ||
| 157 | #define VIDEO_CAP_SYS 4 | ||
| 158 | #define VIDEO_CAP_PROG 8 | ||
| 159 | /⋆ can the driver also handle SPU, NAVI and CSS encoded data? | ||
| 160 | (CSS API is not present yet) ⋆/ | ||
| 161 | #define VIDEO_CAP_SPU 16 | ||
| 162 | #define VIDEO_CAP_NAVI 32 | ||
| 163 | #define VIDEO_CAP_CSS 64 | ||
| 164 | </programlisting> | ||
| 165 | </section> | ||
| 166 | |||
| 167 | <section id="video_system"> | ||
| 168 | <title>video system</title> | ||
| 169 | <para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The | ||
| 170 | following system types can be set: | ||
| 171 | </para> | ||
| 172 | <programlisting> | ||
| 173 | typedef enum { | ||
| 174 | VIDEO_SYSTEM_PAL, | ||
| 175 | VIDEO_SYSTEM_NTSC, | ||
| 176 | VIDEO_SYSTEM_PALN, | ||
| 177 | VIDEO_SYSTEM_PALNc, | ||
| 178 | VIDEO_SYSTEM_PALM, | ||
| 179 | VIDEO_SYSTEM_NTSC60, | ||
| 180 | VIDEO_SYSTEM_PAL60, | ||
| 181 | VIDEO_SYSTEM_PALM60 | ||
| 182 | } video_system_t; | ||
| 183 | </programlisting> | ||
| 184 | </section> | ||
| 185 | |||
| 186 | <section id="video_highlight"> | ||
| 187 | <title>struct video_highlight</title> | ||
| 188 | <para>Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight information. The | ||
| 189 | call expects the following format for that information: | ||
| 190 | </para> | ||
| 191 | <programlisting> | ||
| 192 | typedef | ||
| 193 | struct video_highlight { | ||
| 194 | boolean active; /⋆ 1=show highlight, 0=hide highlight ⋆/ | ||
| 195 | uint8_t contrast1; /⋆ 7- 4 Pattern pixel contrast ⋆/ | ||
| 196 | /⋆ 3- 0 Background pixel contrast ⋆/ | ||
| 197 | uint8_t contrast2; /⋆ 7- 4 Emphasis pixel-2 contrast ⋆/ | ||
| 198 | /⋆ 3- 0 Emphasis pixel-1 contrast ⋆/ | ||
| 199 | uint8_t color1; /⋆ 7- 4 Pattern pixel color ⋆/ | ||
| 200 | /⋆ 3- 0 Background pixel color ⋆/ | ||
| 201 | uint8_t color2; /⋆ 7- 4 Emphasis pixel-2 color ⋆/ | ||
| 202 | /⋆ 3- 0 Emphasis pixel-1 color ⋆/ | ||
| 203 | uint32_t ypos; /⋆ 23-22 auto action mode ⋆/ | ||
| 204 | /⋆ 21-12 start y ⋆/ | ||
| 205 | /⋆ 9- 0 end y ⋆/ | ||
| 206 | uint32_t xpos; /⋆ 23-22 button color number ⋆/ | ||
| 207 | /⋆ 21-12 start x ⋆/ | ||
| 208 | /⋆ 9- 0 end x ⋆/ | ||
| 209 | } video_highlight_t; | ||
| 210 | </programlisting> | ||
| 211 | |||
| 212 | </section> | ||
| 213 | <section id="video_spu"> | ||
| 214 | <title>video SPU</title> | ||
| 215 | <para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the | ||
| 216 | following format: | ||
| 217 | </para> | ||
| 218 | <programlisting> | ||
| 219 | typedef | ||
| 220 | struct video_spu { | ||
| 221 | boolean active; | ||
| 222 | int stream_id; | ||
| 223 | } video_spu_t; | ||
| 224 | </programlisting> | ||
| 225 | |||
| 226 | </section> | ||
| 227 | <section id="video_spu_palette"> | ||
| 228 | <title>video SPU palette</title> | ||
| 229 | <para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE: | ||
| 230 | </para> | ||
| 231 | <programlisting> | ||
| 232 | typedef | ||
| 233 | struct video_spu_palette{ | ||
| 234 | int length; | ||
| 235 | uint8_t ⋆palette; | ||
| 236 | } video_spu_palette_t; | ||
| 237 | </programlisting> | ||
| 238 | |||
| 239 | </section> | ||
| 240 | <section id="video_navi_pack"> | ||
| 241 | <title>video NAVI pack</title> | ||
| 242 | <para>In order to get the navigational data the following structure has to be passed to the ioctl | ||
| 243 | VIDEO_GET_NAVI: | ||
| 244 | </para> | ||
| 245 | <programlisting> | ||
| 246 | typedef | ||
| 247 | struct video_navi_pack{ | ||
| 248 | int length; /⋆ 0 ... 1024 ⋆/ | ||
| 249 | uint8_t data[1024]; | ||
| 250 | } video_navi_pack_t; | ||
| 251 | </programlisting> | ||
| 252 | </section> | ||
| 253 | |||
| 254 | |||
| 255 | <section id="video_attributes"> | ||
| 256 | <title>video attributes</title> | ||
| 257 | <para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES: | ||
| 258 | </para> | ||
| 259 | <programlisting> | ||
| 260 | typedef uint16_t video_attributes_t; | ||
| 261 | /⋆ bits: descr. ⋆/ | ||
| 262 | /⋆ 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) ⋆/ | ||
| 263 | /⋆ 13-12 TV system (0=525/60, 1=625/50) ⋆/ | ||
| 264 | /⋆ 11-10 Aspect ratio (0=4:3, 3=16:9) ⋆/ | ||
| 265 | /⋆ 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca ⋆/ | ||
| 266 | /⋆ 7 line 21-1 data present in GOP (1=yes, 0=no) ⋆/ | ||
| 267 | /⋆ 6 line 21-2 data present in GOP (1=yes, 0=no) ⋆/ | ||
| 268 | /⋆ 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 ⋆/ | ||
| 269 | /⋆ 2 source letterboxed (1=yes, 0=no) ⋆/ | ||
| 270 | /⋆ 0 film/camera mode (0=camera, 1=film (625/50 only)) ⋆/ | ||
| 271 | </programlisting> | ||
| 272 | </section></section> | ||
| 273 | |||
| 274 | |||
| 275 | <section id="video_function_calls"> | ||
| 276 | <title>Video Function Calls</title> | ||
| 277 | |||
| 278 | |||
| 279 | <section id="video_fopen"> | ||
| 280 | <title>open()</title> | ||
| 281 | <para>DESCRIPTION | ||
| 282 | </para> | ||
| 283 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 284 | align="char"> | ||
| 285 | <para>This system call opens a named video device (e.g. /dev/dvb/adapter0/video0) | ||
| 286 | for subsequent use.</para> | ||
| 287 | <para>When an open() call has succeeded, the device will be ready for use. | ||
| 288 | The significance of blocking or non-blocking mode is described in the | ||
| 289 | documentation for functions where there is a difference. It does not affect the | ||
| 290 | semantics of the open() call itself. A device opened in blocking mode can later | ||
| 291 | be put into non-blocking mode (and vice versa) using the F_SETFL command | ||
| 292 | of the fcntl system call. This is a standard system call, documented in the Linux | ||
| 293 | manual page for fcntl. Only one user can open the Video Device in O_RDWR | ||
| 294 | mode. All other attempts to open the device in this mode will fail, and an | ||
| 295 | error-code will be returned. If the Video Device is opened in O_RDONLY | ||
| 296 | mode, the only ioctl call that can be used is VIDEO_GET_STATUS. All other | ||
| 297 | call will return an error code.</para> | ||
| 298 | </entry> | ||
| 299 | </row></tbody></tgroup></informaltable> | ||
| 300 | |||
| 301 | <para>SYNOPSIS | ||
| 302 | </para> | ||
| 303 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 304 | align="char"> | ||
| 305 | <para>int open(const char ⋆deviceName, int flags);</para> | ||
| 306 | </entry> | ||
| 307 | </row></tbody></tgroup></informaltable> | ||
| 308 | <para>PARAMETERS | ||
| 309 | </para> | ||
| 310 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 311 | align="char"> | ||
| 312 | <para>const char | ||
| 313 | *deviceName</para> | ||
| 314 | </entry><entry | ||
| 315 | align="char"> | ||
| 316 | <para>Name of specific video device.</para> | ||
| 317 | </entry> | ||
| 318 | </row><row><entry | ||
| 319 | align="char"> | ||
| 320 | <para>int flags</para> | ||
| 321 | </entry><entry | ||
| 322 | align="char"> | ||
| 323 | <para>A bit-wise OR of the following flags:</para> | ||
| 324 | </entry> | ||
| 325 | </row><row><entry | ||
| 326 | align="char"> | ||
| 327 | </entry><entry | ||
| 328 | align="char"> | ||
| 329 | <para>O_RDONLY read-only access</para> | ||
| 330 | </entry> | ||
| 331 | </row><row><entry | ||
| 332 | align="char"> | ||
| 333 | </entry><entry | ||
| 334 | align="char"> | ||
| 335 | <para>O_RDWR read/write access</para> | ||
| 336 | </entry> | ||
| 337 | </row><row><entry | ||
| 338 | align="char"> | ||
| 339 | </entry><entry | ||
| 340 | align="char"> | ||
| 341 | <para>O_NONBLOCK open in non-blocking mode</para> | ||
| 342 | </entry> | ||
| 343 | </row><row><entry | ||
| 344 | align="char"> | ||
| 345 | </entry><entry | ||
| 346 | align="char"> | ||
| 347 | <para>(blocking mode is the default)</para> | ||
| 348 | </entry> | ||
| 349 | </row></tbody></tgroup></informaltable> | ||
| 350 | <para>ERRORS | ||
| 351 | </para> | ||
| 352 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 353 | align="char"> | ||
| 354 | <para>ENODEV</para> | ||
| 355 | </entry><entry | ||
| 356 | align="char"> | ||
| 357 | <para>Device driver not loaded/available.</para> | ||
| 358 | </entry> | ||
| 359 | </row><row><entry | ||
| 360 | align="char"> | ||
| 361 | <para>EINTERNAL</para> | ||
| 362 | </entry><entry | ||
| 363 | align="char"> | ||
| 364 | <para>Internal error.</para> | ||
| 365 | </entry> | ||
| 366 | </row><row><entry | ||
| 367 | align="char"> | ||
| 368 | <para>EBUSY</para> | ||
| 369 | </entry><entry | ||
| 370 | align="char"> | ||
| 371 | <para>Device or resource busy.</para> | ||
| 372 | </entry> | ||
| 373 | </row><row><entry | ||
| 374 | align="char"> | ||
| 375 | <para>EINVAL</para> | ||
| 376 | </entry><entry | ||
| 377 | align="char"> | ||
| 378 | <para>Invalid argument.</para> | ||
| 379 | </entry> | ||
| 380 | </row></tbody></tgroup></informaltable> | ||
| 381 | |||
| 382 | </section> | ||
| 383 | <section id="video_fclose"> | ||
| 384 | <title>close()</title> | ||
| 385 | <para>DESCRIPTION | ||
| 386 | </para> | ||
| 387 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 388 | align="char"> | ||
| 389 | <para>This system call closes a previously opened video device.</para> | ||
| 390 | </entry> | ||
| 391 | </row></tbody></tgroup></informaltable> | ||
| 392 | <para>SYNOPSIS | ||
| 393 | </para> | ||
| 394 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 395 | align="char"> | ||
| 396 | <para>int close(int fd);</para> | ||
| 397 | </entry> | ||
| 398 | </row></tbody></tgroup></informaltable> | ||
| 399 | <para>PARAMETERS | ||
| 400 | </para> | ||
| 401 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 402 | align="char"> | ||
| 403 | <para>int fd</para> | ||
| 404 | </entry><entry | ||
| 405 | align="char"> | ||
| 406 | <para>File descriptor returned by a previous call to open().</para> | ||
| 407 | </entry> | ||
| 408 | </row></tbody></tgroup></informaltable> | ||
| 409 | <para>ERRORS | ||
| 410 | </para> | ||
| 411 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 412 | align="char"> | ||
| 413 | <para>EBADF</para> | ||
| 414 | </entry><entry | ||
| 415 | align="char"> | ||
| 416 | <para>fd is not a valid open file descriptor.</para> | ||
| 417 | </entry> | ||
| 418 | </row></tbody></tgroup></informaltable> | ||
| 419 | |||
| 420 | </section> | ||
| 421 | <section id="video_fwrite"> | ||
| 422 | <title>write()</title> | ||
| 423 | <para>DESCRIPTION | ||
| 424 | </para> | ||
| 425 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 426 | align="char"> | ||
| 427 | <para>This system call can only be used if VIDEO_SOURCE_MEMORY is selected | ||
| 428 | in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in | ||
| 429 | PES format, unless the capability allows other formats. If O_NONBLOCK is | ||
| 430 | not specified the function will block until buffer space is available. The amount | ||
| 431 | of data to be transferred is implied by count.</para> | ||
| 432 | </entry> | ||
| 433 | </row></tbody></tgroup></informaltable> | ||
| 434 | <para>SYNOPSIS | ||
| 435 | </para> | ||
| 436 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 437 | align="char"> | ||
| 438 | <para>size_t write(int fd, const void ⋆buf, size_t count);</para> | ||
| 439 | </entry> | ||
| 440 | </row></tbody></tgroup></informaltable> | ||
| 441 | <para>PARAMETERS | ||
| 442 | </para> | ||
| 443 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 444 | align="char"> | ||
| 445 | <para>int fd</para> | ||
| 446 | </entry><entry | ||
| 447 | align="char"> | ||
| 448 | <para>File descriptor returned by a previous call to open().</para> | ||
| 449 | </entry> | ||
| 450 | </row><row><entry | ||
| 451 | align="char"> | ||
| 452 | <para>void *buf</para> | ||
| 453 | </entry><entry | ||
| 454 | align="char"> | ||
| 455 | <para>Pointer to the buffer containing the PES data.</para> | ||
| 456 | </entry> | ||
| 457 | </row><row><entry | ||
| 458 | align="char"> | ||
| 459 | <para>size_t count</para> | ||
| 460 | </entry><entry | ||
| 461 | align="char"> | ||
| 462 | <para>Size of buf.</para> | ||
| 463 | </entry> | ||
| 464 | </row></tbody></tgroup></informaltable> | ||
| 465 | <para>ERRORS | ||
| 466 | </para> | ||
| 467 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 468 | align="char"> | ||
| 469 | <para>EPERM</para> | ||
| 470 | </entry><entry | ||
| 471 | align="char"> | ||
| 472 | <para>Mode VIDEO_SOURCE_MEMORY not selected.</para> | ||
| 473 | </entry> | ||
| 474 | </row><row><entry | ||
| 475 | align="char"> | ||
| 476 | <para>ENOMEM</para> | ||
| 477 | </entry><entry | ||
| 478 | align="char"> | ||
| 479 | <para>Attempted to write more data than the internal buffer can | ||
| 480 | hold.</para> | ||
| 481 | </entry> | ||
| 482 | </row><row><entry | ||
| 483 | align="char"> | ||
| 484 | <para>EBADF</para> | ||
| 485 | </entry><entry | ||
| 486 | align="char"> | ||
| 487 | <para>fd is not a valid open file descriptor.</para> | ||
| 488 | </entry> | ||
| 489 | </row></tbody></tgroup></informaltable> | ||
| 490 | |||
| 491 | </section><section | ||
| 492 | role="subsection"><title>VIDEO_STOP</title> | ||
| 493 | <para>DESCRIPTION | ||
| 494 | </para> | ||
| 495 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 496 | align="char"> | ||
| 497 | <para>This ioctl call asks the Video Device to stop playing the current stream. | ||
| 498 | Depending on the input parameter, the screen can be blanked out or displaying | ||
| 499 | the last decoded frame.</para> | ||
| 500 | </entry> | ||
| 501 | </row></tbody></tgroup></informaltable> | ||
| 502 | <para>SYNOPSIS | ||
| 503 | </para> | ||
| 504 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 505 | align="char"> | ||
| 506 | <para>int ioctl(fd, int request = VIDEO_STOP, boolean | ||
| 507 | mode);</para> | ||
| 508 | </entry> | ||
| 509 | </row></tbody></tgroup></informaltable> | ||
| 510 | <para>PARAMETERS | ||
| 511 | </para> | ||
| 512 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 513 | align="char"> | ||
| 514 | <para>int fd</para> | ||
| 515 | </entry><entry | ||
| 516 | align="char"> | ||
| 517 | <para>File descriptor returned by a previous call to open().</para> | ||
| 518 | </entry> | ||
| 519 | </row><row><entry | ||
| 520 | align="char"> | ||
| 521 | <para>int request</para> | ||
| 522 | </entry><entry | ||
| 523 | align="char"> | ||
| 524 | <para>Equals VIDEO_STOP for this command.</para> | ||
| 525 | </entry> | ||
| 526 | </row><row><entry | ||
| 527 | align="char"> | ||
| 528 | <para>Boolean mode</para> | ||
| 529 | </entry><entry | ||
| 530 | align="char"> | ||
| 531 | <para>Indicates how the screen shall be handled.</para> | ||
| 532 | </entry> | ||
| 533 | </row><row><entry | ||
| 534 | align="char"> | ||
| 535 | </entry><entry | ||
| 536 | align="char"> | ||
| 537 | <para>TRUE: Blank screen when stop.</para> | ||
| 538 | </entry> | ||
| 539 | </row><row><entry | ||
| 540 | align="char"> | ||
| 541 | </entry><entry | ||
| 542 | align="char"> | ||
| 543 | <para>FALSE: Show last decoded frame.</para> | ||
| 544 | </entry> | ||
| 545 | </row></tbody></tgroup></informaltable> | ||
| 546 | <para>ERRORS | ||
| 547 | </para> | ||
| 548 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 549 | align="char"> | ||
| 550 | <para>EBADF</para> | ||
| 551 | </entry><entry | ||
| 552 | align="char"> | ||
| 553 | <para>fd is not a valid open file descriptor</para> | ||
| 554 | </entry> | ||
| 555 | </row><row><entry | ||
| 556 | align="char"> | ||
| 557 | <para>EINTERNAL</para> | ||
| 558 | </entry><entry | ||
| 559 | align="char"> | ||
| 560 | <para>Internal error, possibly in the communication with the | ||
| 561 | DVB subsystem.</para> | ||
| 562 | </entry> | ||
| 563 | </row></tbody></tgroup></informaltable> | ||
| 564 | |||
| 565 | </section><section | ||
| 566 | role="subsection"><title>VIDEO_PLAY</title> | ||
| 567 | <para>DESCRIPTION | ||
| 568 | </para> | ||
| 569 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 570 | align="char"> | ||
| 571 | <para>This ioctl call asks the Video Device to start playing a video stream from the | ||
| 572 | selected source.</para> | ||
| 573 | </entry> | ||
| 574 | </row></tbody></tgroup></informaltable> | ||
| 575 | <para>SYNOPSIS | ||
| 576 | </para> | ||
| 577 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 578 | align="char"> | ||
| 579 | <para>int ioctl(fd, int request = VIDEO_PLAY);</para> | ||
| 580 | </entry> | ||
| 581 | </row></tbody></tgroup></informaltable> | ||
| 582 | <para>PARAMETERS | ||
| 583 | </para> | ||
| 584 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 585 | align="char"> | ||
| 586 | <para>int fd</para> | ||
| 587 | </entry><entry | ||
| 588 | align="char"> | ||
| 589 | <para>File descriptor returned by a previous call to open().</para> | ||
| 590 | </entry> | ||
| 591 | </row><row><entry | ||
| 592 | align="char"> | ||
| 593 | <para>int request</para> | ||
| 594 | </entry><entry | ||
| 595 | align="char"> | ||
| 596 | <para>Equals VIDEO_PLAY for this command.</para> | ||
| 597 | </entry> | ||
| 598 | </row></tbody></tgroup></informaltable> | ||
| 599 | <para>ERRORS | ||
| 600 | </para> | ||
| 601 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 602 | align="char"> | ||
| 603 | <para>EBADF</para> | ||
| 604 | </entry><entry | ||
| 605 | align="char"> | ||
| 606 | <para>fd is not a valid open file descriptor</para> | ||
| 607 | </entry> | ||
| 608 | </row><row><entry | ||
| 609 | align="char"> | ||
| 610 | <para>EINTERNAL</para> | ||
| 611 | </entry><entry | ||
| 612 | align="char"> | ||
| 613 | <para>Internal error, possibly in the communication with the | ||
| 614 | DVB subsystem.</para> | ||
| 615 | </entry> | ||
| 616 | </row></tbody></tgroup></informaltable> | ||
| 617 | |||
| 618 | </section><section | ||
| 619 | role="subsection"><title>VIDEO_FREEZE</title> | ||
| 620 | <para>DESCRIPTION | ||
| 621 | </para> | ||
| 622 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 623 | align="char"> | ||
| 624 | <para>This ioctl call suspends the live video stream being played. Decoding | ||
| 625 | and playing are frozen. It is then possible to restart the decoding | ||
| 626 | and playing process of the video stream using the VIDEO_CONTINUE | ||
| 627 | command. If VIDEO_SOURCE_MEMORY is selected in the ioctl call | ||
| 628 | VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more | ||
| 629 | data until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.</para> | ||
| 630 | </entry> | ||
| 631 | </row></tbody></tgroup></informaltable> | ||
| 632 | <para>SYNOPSIS | ||
| 633 | </para> | ||
| 634 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 635 | align="char"> | ||
| 636 | <para>int ioctl(fd, int request = VIDEO_FREEZE);</para> | ||
| 637 | </entry> | ||
| 638 | </row></tbody></tgroup></informaltable> | ||
| 639 | <para>PARAMETERS | ||
| 640 | </para> | ||
| 641 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 642 | align="char"> | ||
| 643 | <para>int fd</para> | ||
| 644 | </entry><entry | ||
| 645 | align="char"> | ||
| 646 | <para>File descriptor returned by a previous call to open().</para> | ||
| 647 | </entry> | ||
| 648 | </row><row><entry | ||
| 649 | align="char"> | ||
| 650 | <para>int request</para> | ||
| 651 | </entry><entry | ||
| 652 | align="char"> | ||
| 653 | <para>Equals VIDEO_FREEZE for this command.</para> | ||
| 654 | </entry> | ||
| 655 | </row></tbody></tgroup></informaltable> | ||
| 656 | <para>ERRORS | ||
| 657 | </para> | ||
| 658 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 659 | align="char"> | ||
| 660 | <para>EBADF</para> | ||
| 661 | </entry><entry | ||
| 662 | align="char"> | ||
| 663 | <para>fd is not a valid open file descriptor</para> | ||
| 664 | </entry> | ||
| 665 | </row><row><entry | ||
| 666 | align="char"> | ||
| 667 | <para>EINTERNAL</para> | ||
| 668 | </entry><entry | ||
| 669 | align="char"> | ||
| 670 | <para>Internal error, possibly in the communication with the | ||
| 671 | DVB subsystem.</para> | ||
| 672 | </entry> | ||
| 673 | </row></tbody></tgroup></informaltable> | ||
| 674 | |||
| 675 | </section><section | ||
| 676 | role="subsection"><title>VIDEO_CONTINUE</title> | ||
| 677 | <para>DESCRIPTION | ||
| 678 | </para> | ||
| 679 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 680 | align="char"> | ||
| 681 | <para>This ioctl call restarts decoding and playing processes of the video stream | ||
| 682 | which was played before a call to VIDEO_FREEZE was made.</para> | ||
| 683 | </entry> | ||
| 684 | </row></tbody></tgroup></informaltable> | ||
| 685 | <para>SYNOPSIS | ||
| 686 | </para> | ||
| 687 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 688 | align="char"> | ||
| 689 | <para>int ioctl(fd, int request = VIDEO_CONTINUE);</para> | ||
| 690 | </entry> | ||
| 691 | </row></tbody></tgroup></informaltable> | ||
| 692 | <para>PARAMETERS | ||
| 693 | </para> | ||
| 694 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 695 | align="char"> | ||
| 696 | <para>int fd</para> | ||
| 697 | </entry><entry | ||
| 698 | align="char"> | ||
| 699 | <para>File descriptor returned by a previous call to open().</para> | ||
| 700 | </entry> | ||
| 701 | </row><row><entry | ||
| 702 | align="char"> | ||
| 703 | <para>int request</para> | ||
| 704 | </entry><entry | ||
| 705 | align="char"> | ||
| 706 | <para>Equals VIDEO_CONTINUE for this command.</para> | ||
| 707 | </entry> | ||
| 708 | </row></tbody></tgroup></informaltable> | ||
| 709 | <para>ERRORS | ||
| 710 | </para> | ||
| 711 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 712 | align="char"> | ||
| 713 | <para>EBADF</para> | ||
| 714 | </entry><entry | ||
| 715 | align="char"> | ||
| 716 | <para>fd is not a valid open file descriptor</para> | ||
| 717 | </entry> | ||
| 718 | </row><row><entry | ||
| 719 | align="char"> | ||
| 720 | <para>EINTERNAL</para> | ||
| 721 | </entry><entry | ||
| 722 | align="char"> | ||
| 723 | <para>Internal error, possibly in the communication with the | ||
| 724 | DVB subsystem.</para> | ||
| 725 | </entry> | ||
| 726 | </row></tbody></tgroup></informaltable> | ||
| 727 | |||
| 728 | </section><section | ||
| 729 | role="subsection"><title>VIDEO_SELECT_SOURCE</title> | ||
| 730 | <para>DESCRIPTION | ||
| 731 | </para> | ||
| 732 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 733 | align="char"> | ||
| 734 | <para>This ioctl call informs the video device which source shall be used for the input | ||
| 735 | data. The possible sources are demux or memory. If memory is selected, the | ||
| 736 | data is fed to the video device through the write command.</para> | ||
| 737 | </entry> | ||
| 738 | </row></tbody></tgroup></informaltable> | ||
| 739 | <para>SYNOPSIS | ||
| 740 | </para> | ||
| 741 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 742 | align="char"> | ||
| 743 | <para>int ioctl(fd, int request = VIDEO_SELECT_SOURCE, | ||
| 744 | video_stream_source_t source);</para> | ||
| 745 | </entry> | ||
| 746 | </row></tbody></tgroup></informaltable> | ||
| 747 | <para>PARAMETERS | ||
| 748 | </para> | ||
| 749 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 750 | align="char"> | ||
| 751 | <para>int fd</para> | ||
| 752 | </entry><entry | ||
| 753 | align="char"> | ||
| 754 | <para>File descriptor returned by a previous call to open().</para> | ||
| 755 | </entry> | ||
| 756 | </row><row><entry | ||
| 757 | align="char"> | ||
| 758 | <para>int request</para> | ||
| 759 | </entry><entry | ||
| 760 | align="char"> | ||
| 761 | <para>Equals VIDEO_SELECT_SOURCE for this command.</para> | ||
| 762 | </entry> | ||
| 763 | </row><row><entry | ||
| 764 | align="char"> | ||
| 765 | <para>video_stream_source_t | ||
| 766 | source</para> | ||
| 767 | </entry><entry | ||
| 768 | align="char"> | ||
| 769 | <para>Indicates which source shall be used for the Video stream.</para> | ||
| 770 | </entry> | ||
| 771 | </row></tbody></tgroup></informaltable> | ||
| 772 | <para>ERRORS | ||
| 773 | </para> | ||
| 774 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 775 | align="char"> | ||
| 776 | <para>EBADF</para> | ||
| 777 | </entry><entry | ||
| 778 | align="char"> | ||
| 779 | <para>fd is not a valid open file descriptor</para> | ||
| 780 | </entry> | ||
| 781 | </row><row><entry | ||
| 782 | align="char"> | ||
| 783 | <para>EINTERNAL</para> | ||
| 784 | </entry><entry | ||
| 785 | align="char"> | ||
| 786 | <para>Internal error, possibly in the communication with the | ||
| 787 | DVB subsystem.</para> | ||
| 788 | </entry> | ||
| 789 | </row></tbody></tgroup></informaltable> | ||
| 790 | |||
| 791 | </section><section | ||
| 792 | role="subsection"><title>VIDEO_SET_BLANK</title> | ||
| 793 | <para>DESCRIPTION | ||
| 794 | </para> | ||
| 795 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 796 | align="char"> | ||
| 797 | <para>This ioctl call asks the Video Device to blank out the picture.</para> | ||
| 798 | </entry> | ||
| 799 | </row></tbody></tgroup></informaltable> | ||
| 800 | <para>SYNOPSIS | ||
| 801 | </para> | ||
| 802 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 803 | align="char"> | ||
| 804 | <para>int ioctl(fd, int request = VIDEO_SET_BLANK, boolean | ||
| 805 | mode);</para> | ||
| 806 | </entry> | ||
| 807 | </row></tbody></tgroup></informaltable> | ||
| 808 | <para>PARAMETERS | ||
| 809 | </para> | ||
| 810 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 811 | align="char"> | ||
| 812 | <para>int fd</para> | ||
| 813 | </entry><entry | ||
| 814 | align="char"> | ||
| 815 | <para>File descriptor returned by a previous call to open().</para> | ||
| 816 | </entry> | ||
| 817 | </row><row><entry | ||
| 818 | align="char"> | ||
| 819 | <para>int request</para> | ||
| 820 | </entry><entry | ||
| 821 | align="char"> | ||
| 822 | <para>Equals VIDEO_SET_BLANK for this command.</para> | ||
| 823 | </entry> | ||
| 824 | </row><row><entry | ||
| 825 | align="char"> | ||
| 826 | <para>boolean mode</para> | ||
| 827 | </entry><entry | ||
| 828 | align="char"> | ||
| 829 | <para>TRUE: Blank screen when stop.</para> | ||
| 830 | </entry> | ||
| 831 | </row><row><entry | ||
| 832 | align="char"> | ||
| 833 | </entry><entry | ||
| 834 | align="char"> | ||
| 835 | <para>FALSE: Show last decoded frame.</para> | ||
| 836 | </entry> | ||
| 837 | </row></tbody></tgroup></informaltable> | ||
| 838 | <para>ERRORS | ||
| 839 | </para> | ||
| 840 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 841 | align="char"> | ||
| 842 | <para>EBADF</para> | ||
| 843 | </entry><entry | ||
| 844 | align="char"> | ||
| 845 | <para>fd is not a valid open file descriptor</para> | ||
| 846 | </entry> | ||
| 847 | </row><row><entry | ||
| 848 | align="char"> | ||
| 849 | <para>EINTERNAL</para> | ||
| 850 | </entry><entry | ||
| 851 | align="char"> | ||
| 852 | <para>Internal error, possibly in the communication with the | ||
| 853 | DVB subsystem.</para> | ||
| 854 | </entry> | ||
| 855 | </row><row><entry | ||
| 856 | align="char"> | ||
| 857 | <para>EINVAL</para> | ||
| 858 | </entry><entry | ||
| 859 | align="char"> | ||
| 860 | <para>Illegal input parameter</para> | ||
| 861 | </entry> | ||
| 862 | </row></tbody></tgroup></informaltable> | ||
| 863 | |||
| 864 | </section><section | ||
| 865 | role="subsection"><title>VIDEO_GET_STATUS</title> | ||
| 866 | <para>DESCRIPTION | ||
| 867 | </para> | ||
| 868 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 869 | align="char"> | ||
| 870 | <para>This ioctl call asks the Video Device to return the current status of the device.</para> | ||
| 871 | </entry> | ||
| 872 | </row></tbody></tgroup></informaltable> | ||
| 873 | <para>SYNOPSIS | ||
| 874 | </para> | ||
| 875 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 876 | align="char"> | ||
| 877 | <para> int ioctl(fd, int request = VIDEO_GET_STATUS, struct | ||
| 878 | video_status ⋆status);</para> | ||
| 879 | </entry> | ||
| 880 | </row></tbody></tgroup></informaltable> | ||
| 881 | <para>PARAMETERS | ||
| 882 | </para> | ||
| 883 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 884 | align="char"> | ||
| 885 | <para>int fd</para> | ||
| 886 | </entry><entry | ||
| 887 | align="char"> | ||
| 888 | <para>File descriptor returned by a previous call to open().</para> | ||
| 889 | </entry> | ||
| 890 | </row><row><entry | ||
| 891 | align="char"> | ||
| 892 | <para>int request</para> | ||
| 893 | </entry><entry | ||
| 894 | align="char"> | ||
| 895 | <para>Equals VIDEO_GET_STATUS for this command.</para> | ||
| 896 | </entry> | ||
| 897 | </row><row><entry | ||
| 898 | align="char"> | ||
| 899 | <para>struct video_status | ||
| 900 | *status</para> | ||
| 901 | </entry><entry | ||
| 902 | align="char"> | ||
| 903 | <para>Returns the current status of the Video Device.</para> | ||
| 904 | </entry> | ||
| 905 | </row></tbody></tgroup></informaltable> | ||
| 906 | <para>ERRORS | ||
| 907 | </para> | ||
| 908 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 909 | align="char"> | ||
| 910 | <para>EBADF</para> | ||
| 911 | </entry><entry | ||
| 912 | align="char"> | ||
| 913 | <para>fd is not a valid open file descriptor</para> | ||
| 914 | </entry> | ||
| 915 | </row><row><entry | ||
| 916 | align="char"> | ||
| 917 | <para>EINTERNAL</para> | ||
| 918 | </entry><entry | ||
| 919 | align="char"> | ||
| 920 | <para>Internal error, possibly in the communication with the | ||
| 921 | DVB subsystem.</para> | ||
| 922 | </entry> | ||
| 923 | </row><row><entry | ||
| 924 | align="char"> | ||
| 925 | <para>EFAULT</para> | ||
| 926 | </entry><entry | ||
| 927 | align="char"> | ||
| 928 | <para>status points to invalid address</para> | ||
| 929 | </entry> | ||
| 930 | </row></tbody></tgroup></informaltable> | ||
| 931 | |||
| 932 | </section><section | ||
| 933 | role="subsection"><title>VIDEO_GET_EVENT</title> | ||
| 934 | <para>DESCRIPTION | ||
| 935 | </para> | ||
| 936 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 937 | align="char"> | ||
| 938 | <para>This ioctl call returns an event of type video_event if available. If an event is | ||
| 939 | not available, the behavior depends on whether the device is in blocking or | ||
| 940 | non-blocking mode. In the latter case, the call fails immediately with errno | ||
| 941 | set to EWOULDBLOCK. In the former case, the call blocks until an event | ||
| 942 | becomes available. The standard Linux poll() and/or select() system calls can | ||
| 943 | be used with the device file descriptor to watch for new events. For select(), | ||
| 944 | the file descriptor should be included in the exceptfds argument, and for | ||
| 945 | poll(), POLLPRI should be specified as the wake-up condition. Read-only | ||
| 946 | permissions are sufficient for this ioctl call.</para> | ||
| 947 | </entry> | ||
| 948 | </row></tbody></tgroup></informaltable> | ||
| 949 | <para>SYNOPSIS | ||
| 950 | </para> | ||
| 951 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 952 | align="char"> | ||
| 953 | <para> int ioctl(fd, int request = VIDEO_GET_EVENT, struct | ||
| 954 | video_event ⋆ev);</para> | ||
| 955 | </entry> | ||
| 956 | </row></tbody></tgroup></informaltable> | ||
| 957 | <para>PARAMETERS | ||
| 958 | </para> | ||
| 959 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 960 | align="char"> | ||
| 961 | <para>int fd</para> | ||
| 962 | </entry><entry | ||
| 963 | align="char"> | ||
| 964 | <para>File descriptor returned by a previous call to open().</para> | ||
| 965 | </entry> | ||
| 966 | </row><row><entry | ||
| 967 | align="char"> | ||
| 968 | <para>int request</para> | ||
| 969 | </entry><entry | ||
| 970 | align="char"> | ||
| 971 | <para>Equals VIDEO_GET_EVENT for this command.</para> | ||
| 972 | </entry> | ||
| 973 | </row><row><entry | ||
| 974 | align="char"> | ||
| 975 | <para>struct video_event | ||
| 976 | *ev</para> | ||
| 977 | </entry><entry | ||
| 978 | align="char"> | ||
| 979 | <para>Points to the location where the event, if any, is to be | ||
| 980 | stored.</para> | ||
| 981 | </entry> | ||
| 982 | </row></tbody></tgroup></informaltable> | ||
| 983 | <para>ERRORS | ||
| 984 | </para> | ||
| 985 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 986 | align="char"> | ||
| 987 | <para>EBADF</para> | ||
| 988 | </entry><entry | ||
| 989 | align="char"> | ||
| 990 | <para>fd is not a valid open file descriptor</para> | ||
| 991 | </entry> | ||
| 992 | </row><row><entry | ||
| 993 | align="char"> | ||
| 994 | <para>EFAULT</para> | ||
| 995 | </entry><entry | ||
| 996 | align="char"> | ||
| 997 | <para>ev points to invalid address</para> | ||
| 998 | </entry> | ||
| 999 | </row><row><entry | ||
| 1000 | align="char"> | ||
| 1001 | <para>EWOULDBLOCK</para> | ||
| 1002 | </entry><entry | ||
| 1003 | align="char"> | ||
| 1004 | <para>There is no event pending, and the device is in | ||
| 1005 | non-blocking mode.</para> | ||
| 1006 | </entry> | ||
| 1007 | </row><row><entry | ||
| 1008 | align="char"> | ||
| 1009 | <para>EOVERFLOW</para> | ||
| 1010 | </entry><entry | ||
| 1011 | align="char"> | ||
| 1012 | </entry> | ||
| 1013 | </row><row><entry | ||
| 1014 | align="char"> | ||
| 1015 | </entry><entry | ||
| 1016 | align="char"> | ||
| 1017 | <para>Overflow in event queue - one or more events were lost.</para> | ||
| 1018 | </entry> | ||
| 1019 | </row></tbody></tgroup></informaltable> | ||
| 1020 | |||
| 1021 | </section><section | ||
| 1022 | role="subsection"><title>VIDEO_SET_DISPLAY_FORMAT</title> | ||
| 1023 | <para>DESCRIPTION | ||
| 1024 | </para> | ||
| 1025 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1026 | align="char"> | ||
| 1027 | <para>This ioctl call asks the Video Device to select the video format to be applied | ||
| 1028 | by the MPEG chip on the video.</para> | ||
| 1029 | </entry> | ||
| 1030 | </row></tbody></tgroup></informaltable> | ||
| 1031 | <para>SYNOPSIS | ||
| 1032 | </para> | ||
| 1033 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1034 | align="char"> | ||
| 1035 | <para> int ioctl(fd, int request = | ||
| 1036 | VIDEO_SET_DISPLAY_FORMAT, video_display_format_t | ||
| 1037 | format);</para> | ||
| 1038 | </entry> | ||
| 1039 | </row></tbody></tgroup></informaltable> | ||
| 1040 | <para>PARAMETERS | ||
| 1041 | </para> | ||
| 1042 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1043 | align="char"> | ||
| 1044 | <para>int fd</para> | ||
| 1045 | </entry><entry | ||
| 1046 | align="char"> | ||
| 1047 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1048 | </entry> | ||
| 1049 | </row><row><entry | ||
| 1050 | align="char"> | ||
| 1051 | <para>int request</para> | ||
| 1052 | </entry><entry | ||
| 1053 | align="char"> | ||
| 1054 | <para>Equals VIDEO_SET_DISPLAY_FORMAT for this | ||
| 1055 | command.</para> | ||
| 1056 | </entry> | ||
| 1057 | </row><row><entry | ||
| 1058 | align="char"> | ||
| 1059 | <para>video_display_format_t | ||
| 1060 | format</para> | ||
| 1061 | </entry><entry | ||
| 1062 | align="char"> | ||
| 1063 | <para>Selects the video format to be used.</para> | ||
| 1064 | </entry> | ||
| 1065 | </row></tbody></tgroup></informaltable> | ||
| 1066 | <para>ERRORS | ||
| 1067 | </para> | ||
| 1068 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1069 | align="char"> | ||
| 1070 | <para>EBADF</para> | ||
| 1071 | </entry><entry | ||
| 1072 | align="char"> | ||
| 1073 | <para>fd is not a valid open file descriptor</para> | ||
| 1074 | </entry> | ||
| 1075 | </row><row><entry | ||
| 1076 | align="char"> | ||
| 1077 | <para>EINTERNAL</para> | ||
| 1078 | </entry><entry | ||
| 1079 | align="char"> | ||
| 1080 | <para>Internal error.</para> | ||
| 1081 | </entry> | ||
| 1082 | </row><row><entry | ||
| 1083 | align="char"> | ||
| 1084 | <para>EINVAL</para> | ||
| 1085 | </entry><entry | ||
| 1086 | align="char"> | ||
| 1087 | <para>Illegal parameter format.</para> | ||
| 1088 | </entry> | ||
| 1089 | </row></tbody></tgroup></informaltable> | ||
| 1090 | |||
| 1091 | </section><section | ||
| 1092 | role="subsection"><title>VIDEO_STILLPICTURE</title> | ||
| 1093 | <para>DESCRIPTION | ||
| 1094 | </para> | ||
| 1095 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1096 | align="char"> | ||
| 1097 | <para>This ioctl call asks the Video Device to display a still picture (I-frame). The | ||
| 1098 | input data shall contain an I-frame. If the pointer is NULL, then the current | ||
| 1099 | displayed still picture is blanked.</para> | ||
| 1100 | </entry> | ||
| 1101 | </row></tbody></tgroup></informaltable> | ||
| 1102 | <para>SYNOPSIS | ||
| 1103 | </para> | ||
| 1104 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1105 | align="char"> | ||
| 1106 | <para>int ioctl(fd, int request = VIDEO_STILLPICTURE, | ||
| 1107 | struct video_still_picture ⋆sp);</para> | ||
| 1108 | </entry> | ||
| 1109 | </row></tbody></tgroup></informaltable> | ||
| 1110 | <para>PARAMETERS | ||
| 1111 | </para> | ||
| 1112 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1113 | align="char"> | ||
| 1114 | <para>int fd</para> | ||
| 1115 | </entry><entry | ||
| 1116 | align="char"> | ||
| 1117 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1118 | </entry> | ||
| 1119 | </row><row><entry | ||
| 1120 | align="char"> | ||
| 1121 | <para>int request</para> | ||
| 1122 | </entry><entry | ||
| 1123 | align="char"> | ||
| 1124 | <para>Equals VIDEO_STILLPICTURE for this command.</para> | ||
| 1125 | </entry> | ||
| 1126 | </row><row><entry | ||
| 1127 | align="char"> | ||
| 1128 | <para>struct | ||
| 1129 | video_still_picture | ||
| 1130 | *sp</para> | ||
| 1131 | </entry><entry | ||
| 1132 | align="char"> | ||
| 1133 | <para>Pointer to a location where an I-frame and size is stored.</para> | ||
| 1134 | </entry> | ||
| 1135 | </row></tbody></tgroup></informaltable> | ||
| 1136 | <para>ERRORS | ||
| 1137 | </para> | ||
| 1138 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1139 | align="char"> | ||
| 1140 | <para>EBADF</para> | ||
| 1141 | </entry><entry | ||
| 1142 | align="char"> | ||
| 1143 | <para>fd is not a valid open file descriptor</para> | ||
| 1144 | </entry> | ||
| 1145 | </row><row><entry | ||
| 1146 | align="char"> | ||
| 1147 | <para>EINTERNAL</para> | ||
| 1148 | </entry><entry | ||
| 1149 | align="char"> | ||
| 1150 | <para>Internal error.</para> | ||
| 1151 | </entry> | ||
| 1152 | </row><row><entry | ||
| 1153 | align="char"> | ||
| 1154 | <para>EFAULT</para> | ||
| 1155 | </entry><entry | ||
| 1156 | align="char"> | ||
| 1157 | <para>sp points to an invalid iframe.</para> | ||
| 1158 | </entry> | ||
| 1159 | </row></tbody></tgroup></informaltable> | ||
| 1160 | |||
| 1161 | </section><section | ||
| 1162 | role="subsection"><title>VIDEO_FAST_FORWARD</title> | ||
| 1163 | <para>DESCRIPTION | ||
| 1164 | </para> | ||
| 1165 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1166 | align="char"> | ||
| 1167 | <para>This ioctl call asks the Video Device to skip decoding of N number of I-frames. | ||
| 1168 | This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para> | ||
| 1169 | </entry> | ||
| 1170 | </row></tbody></tgroup></informaltable> | ||
| 1171 | <para>SYNOPSIS | ||
| 1172 | </para> | ||
| 1173 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1174 | align="char"> | ||
| 1175 | <para>int ioctl(fd, int request = VIDEO_FAST_FORWARD, int | ||
| 1176 | nFrames);</para> | ||
| 1177 | </entry> | ||
| 1178 | </row></tbody></tgroup></informaltable> | ||
| 1179 | <para>PARAMETERS | ||
| 1180 | </para> | ||
| 1181 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1182 | align="char"> | ||
| 1183 | <para>int fd</para> | ||
| 1184 | </entry><entry | ||
| 1185 | align="char"> | ||
| 1186 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1187 | </entry> | ||
| 1188 | </row><row><entry | ||
| 1189 | align="char"> | ||
| 1190 | <para>int request</para> | ||
| 1191 | </entry><entry | ||
| 1192 | align="char"> | ||
| 1193 | <para>Equals VIDEO_FAST_FORWARD for this command.</para> | ||
| 1194 | </entry> | ||
| 1195 | </row><row><entry | ||
| 1196 | align="char"> | ||
| 1197 | <para>int nFrames</para> | ||
| 1198 | </entry><entry | ||
| 1199 | align="char"> | ||
| 1200 | <para>The number of frames to skip.</para> | ||
| 1201 | </entry> | ||
| 1202 | </row></tbody></tgroup></informaltable> | ||
| 1203 | <para>ERRORS | ||
| 1204 | </para> | ||
| 1205 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1206 | align="char"> | ||
| 1207 | <para>EBADF</para> | ||
| 1208 | </entry><entry | ||
| 1209 | align="char"> | ||
| 1210 | <para>fd is not a valid open file descriptor</para> | ||
| 1211 | </entry> | ||
| 1212 | </row><row><entry | ||
| 1213 | align="char"> | ||
| 1214 | <para>EINTERNAL</para> | ||
| 1215 | </entry><entry | ||
| 1216 | align="char"> | ||
| 1217 | <para>Internal error.</para> | ||
| 1218 | </entry> | ||
| 1219 | </row><row><entry | ||
| 1220 | align="char"> | ||
| 1221 | <para>EPERM</para> | ||
| 1222 | </entry><entry | ||
| 1223 | align="char"> | ||
| 1224 | <para>Mode VIDEO_SOURCE_MEMORY not selected.</para> | ||
| 1225 | </entry> | ||
| 1226 | </row><row><entry | ||
| 1227 | align="char"> | ||
| 1228 | <para>EINVAL</para> | ||
| 1229 | </entry><entry | ||
| 1230 | align="char"> | ||
| 1231 | <para>Illegal parameter format.</para> | ||
| 1232 | </entry> | ||
| 1233 | </row></tbody></tgroup></informaltable> | ||
| 1234 | |||
| 1235 | </section><section | ||
| 1236 | role="subsection"><title>VIDEO_SLOWMOTION</title> | ||
| 1237 | <para>DESCRIPTION | ||
| 1238 | </para> | ||
| 1239 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1240 | align="char"> | ||
| 1241 | <para>This ioctl call asks the video device to repeat decoding frames N number of | ||
| 1242 | times. This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para> | ||
| 1243 | </entry> | ||
| 1244 | </row></tbody></tgroup></informaltable> | ||
| 1245 | <para>SYNOPSIS | ||
| 1246 | </para> | ||
| 1247 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1248 | align="char"> | ||
| 1249 | <para>int ioctl(fd, int request = VIDEO_SLOWMOTION, int | ||
| 1250 | nFrames);</para> | ||
| 1251 | </entry> | ||
| 1252 | </row></tbody></tgroup></informaltable> | ||
| 1253 | <para>PARAMETERS | ||
| 1254 | </para> | ||
| 1255 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1256 | align="char"> | ||
| 1257 | <para>int fd</para> | ||
| 1258 | </entry><entry | ||
| 1259 | align="char"> | ||
| 1260 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1261 | </entry> | ||
| 1262 | </row><row><entry | ||
| 1263 | align="char"> | ||
| 1264 | <para>int request</para> | ||
| 1265 | </entry><entry | ||
| 1266 | align="char"> | ||
| 1267 | <para>Equals VIDEO_SLOWMOTION for this command.</para> | ||
| 1268 | </entry> | ||
| 1269 | </row><row><entry | ||
| 1270 | align="char"> | ||
| 1271 | <para>int nFrames</para> | ||
| 1272 | </entry><entry | ||
| 1273 | align="char"> | ||
| 1274 | <para>The number of times to repeat each frame.</para> | ||
| 1275 | </entry> | ||
| 1276 | </row></tbody></tgroup></informaltable> | ||
| 1277 | <para>ERRORS | ||
| 1278 | </para> | ||
| 1279 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1280 | align="char"> | ||
| 1281 | <para>EBADF</para> | ||
| 1282 | </entry><entry | ||
| 1283 | align="char"> | ||
| 1284 | <para>fd is not a valid open file descriptor</para> | ||
| 1285 | </entry> | ||
| 1286 | </row><row><entry | ||
| 1287 | align="char"> | ||
| 1288 | <para>EINTERNAL</para> | ||
| 1289 | </entry><entry | ||
| 1290 | align="char"> | ||
| 1291 | <para>Internal error.</para> | ||
| 1292 | </entry> | ||
| 1293 | </row><row><entry | ||
| 1294 | align="char"> | ||
| 1295 | <para>EPERM</para> | ||
| 1296 | </entry><entry | ||
| 1297 | align="char"> | ||
| 1298 | <para>Mode VIDEO_SOURCE_MEMORY not selected.</para> | ||
| 1299 | </entry> | ||
| 1300 | </row><row><entry | ||
| 1301 | align="char"> | ||
| 1302 | <para>EINVAL</para> | ||
| 1303 | </entry><entry | ||
| 1304 | align="char"> | ||
| 1305 | <para>Illegal parameter format.</para> | ||
| 1306 | </entry> | ||
| 1307 | </row></tbody></tgroup></informaltable> | ||
| 1308 | |||
| 1309 | </section><section | ||
| 1310 | role="subsection"><title>VIDEO_GET_CAPABILITIES</title> | ||
| 1311 | <para>DESCRIPTION | ||
| 1312 | </para> | ||
| 1313 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1314 | align="char"> | ||
| 1315 | <para>This ioctl call asks the video device about its decoding capabilities. On success | ||
| 1316 | it returns and integer which has bits set according to the defines in section ??.</para> | ||
| 1317 | </entry> | ||
| 1318 | </row></tbody></tgroup></informaltable> | ||
| 1319 | <para>SYNOPSIS | ||
| 1320 | </para> | ||
| 1321 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1322 | align="char"> | ||
| 1323 | <para>int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, | ||
| 1324 | unsigned int ⋆cap);</para> | ||
| 1325 | </entry> | ||
| 1326 | </row></tbody></tgroup></informaltable> | ||
| 1327 | <para>PARAMETERS | ||
| 1328 | </para> | ||
| 1329 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1330 | align="char"> | ||
| 1331 | <para>int fd</para> | ||
| 1332 | </entry><entry | ||
| 1333 | align="char"> | ||
| 1334 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1335 | </entry> | ||
| 1336 | </row><row><entry | ||
| 1337 | align="char"> | ||
| 1338 | <para>int request</para> | ||
| 1339 | </entry><entry | ||
| 1340 | align="char"> | ||
| 1341 | <para>Equals VIDEO_GET_CAPABILITIES for this | ||
| 1342 | command.</para> | ||
| 1343 | </entry> | ||
| 1344 | </row><row><entry | ||
| 1345 | align="char"> | ||
| 1346 | <para>unsigned int *cap</para> | ||
| 1347 | </entry><entry | ||
| 1348 | align="char"> | ||
| 1349 | <para>Pointer to a location where to store the capability | ||
| 1350 | information.</para> | ||
| 1351 | </entry> | ||
| 1352 | </row></tbody></tgroup></informaltable> | ||
| 1353 | <para>ERRORS | ||
| 1354 | </para> | ||
| 1355 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1356 | align="char"> | ||
| 1357 | <para>EBADF</para> | ||
| 1358 | </entry><entry | ||
| 1359 | align="char"> | ||
| 1360 | <para>fd is not a valid open file descriptor</para> | ||
| 1361 | </entry> | ||
| 1362 | </row><row><entry | ||
| 1363 | align="char"> | ||
| 1364 | <para>EFAULT</para> | ||
| 1365 | </entry><entry | ||
| 1366 | align="char"> | ||
| 1367 | <para>cap points to an invalid iframe.</para> | ||
| 1368 | </entry> | ||
| 1369 | </row></tbody></tgroup></informaltable> | ||
| 1370 | |||
| 1371 | </section><section | ||
| 1372 | role="subsection"><title>VIDEO_SET_ID</title> | ||
| 1373 | <para>DESCRIPTION | ||
| 1374 | </para> | ||
| 1375 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1376 | align="char"> | ||
| 1377 | <para>This ioctl selects which sub-stream is to be decoded if a program or system | ||
| 1378 | stream is sent to the video device.</para> | ||
| 1379 | </entry> | ||
| 1380 | </row></tbody></tgroup></informaltable> | ||
| 1381 | <para>SYNOPSIS | ||
| 1382 | </para> | ||
| 1383 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1384 | align="char"> | ||
| 1385 | <para>int ioctl(int fd, int request = VIDEO_SET_ID, int | ||
| 1386 | id);</para> | ||
| 1387 | </entry> | ||
| 1388 | </row></tbody></tgroup></informaltable> | ||
| 1389 | <para>PARAMETERS | ||
| 1390 | </para> | ||
| 1391 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1392 | align="char"> | ||
| 1393 | <para>int fd</para> | ||
| 1394 | </entry><entry | ||
| 1395 | align="char"> | ||
| 1396 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1397 | </entry> | ||
| 1398 | </row><row><entry | ||
| 1399 | align="char"> | ||
| 1400 | <para>int request</para> | ||
| 1401 | </entry><entry | ||
| 1402 | align="char"> | ||
| 1403 | <para>Equals VIDEO_SET_ID for this command.</para> | ||
| 1404 | </entry> | ||
| 1405 | </row><row><entry | ||
| 1406 | align="char"> | ||
| 1407 | <para>int id</para> | ||
| 1408 | </entry><entry | ||
| 1409 | align="char"> | ||
| 1410 | <para>video sub-stream id</para> | ||
| 1411 | </entry> | ||
| 1412 | </row></tbody></tgroup></informaltable> | ||
| 1413 | <para>ERRORS | ||
| 1414 | </para> | ||
| 1415 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1416 | align="char"> | ||
| 1417 | <para>EBADF</para> | ||
| 1418 | </entry><entry | ||
| 1419 | align="char"> | ||
| 1420 | <para>fd is not a valid open file descriptor.</para> | ||
| 1421 | </entry> | ||
| 1422 | </row><row><entry | ||
| 1423 | align="char"> | ||
| 1424 | <para>EINTERNAL</para> | ||
| 1425 | </entry><entry | ||
| 1426 | align="char"> | ||
| 1427 | <para>Internal error.</para> | ||
| 1428 | </entry> | ||
| 1429 | </row><row><entry | ||
| 1430 | align="char"> | ||
| 1431 | <para>EINVAL</para> | ||
| 1432 | </entry><entry | ||
| 1433 | align="char"> | ||
| 1434 | <para>Invalid sub-stream id.</para> | ||
| 1435 | </entry> | ||
| 1436 | </row></tbody></tgroup></informaltable> | ||
| 1437 | |||
| 1438 | </section><section | ||
| 1439 | role="subsection"><title>VIDEO_CLEAR_BUFFER</title> | ||
| 1440 | <para>DESCRIPTION | ||
| 1441 | </para> | ||
| 1442 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1443 | align="char"> | ||
| 1444 | <para>This ioctl call clears all video buffers in the driver and in the decoder hardware.</para> | ||
| 1445 | </entry> | ||
| 1446 | </row></tbody></tgroup></informaltable> | ||
| 1447 | <para>SYNOPSIS | ||
| 1448 | </para> | ||
| 1449 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1450 | align="char"> | ||
| 1451 | <para>int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);</para> | ||
| 1452 | </entry> | ||
| 1453 | </row></tbody></tgroup></informaltable> | ||
| 1454 | <para>PARAMETERS | ||
| 1455 | </para> | ||
| 1456 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1457 | align="char"> | ||
| 1458 | <para>int fd</para> | ||
| 1459 | </entry><entry | ||
| 1460 | align="char"> | ||
| 1461 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1462 | </entry> | ||
| 1463 | </row><row><entry | ||
| 1464 | align="char"> | ||
| 1465 | <para>int request</para> | ||
| 1466 | </entry><entry | ||
| 1467 | align="char"> | ||
| 1468 | <para>Equals VIDEO_CLEAR_BUFFER for this command.</para> | ||
| 1469 | </entry> | ||
| 1470 | </row></tbody></tgroup></informaltable> | ||
| 1471 | <para>ERRORS | ||
| 1472 | </para> | ||
| 1473 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1474 | align="char"> | ||
| 1475 | <para>EBADF</para> | ||
| 1476 | </entry><entry | ||
| 1477 | align="char"> | ||
| 1478 | <para>fd is not a valid open file descriptor</para> | ||
| 1479 | </entry> | ||
| 1480 | </row></tbody></tgroup></informaltable> | ||
| 1481 | |||
| 1482 | </section><section | ||
| 1483 | role="subsection"><title>VIDEO_SET_STREAMTYPE</title> | ||
| 1484 | <para>DESCRIPTION | ||
| 1485 | </para> | ||
| 1486 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1487 | align="char"> | ||
| 1488 | <para>This ioctl tells the driver which kind of stream to expect being written to it. If | ||
| 1489 | this call is not used the default of video PES is used. Some drivers might not | ||
| 1490 | support this call and always expect PES.</para> | ||
| 1491 | </entry> | ||
| 1492 | </row></tbody></tgroup></informaltable> | ||
| 1493 | <para>SYNOPSIS | ||
| 1494 | </para> | ||
| 1495 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1496 | align="char"> | ||
| 1497 | <para>int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, | ||
| 1498 | int type);</para> | ||
| 1499 | </entry> | ||
| 1500 | </row></tbody></tgroup></informaltable> | ||
| 1501 | <para>PARAMETERS | ||
| 1502 | </para> | ||
| 1503 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1504 | align="char"> | ||
| 1505 | <para>int fd</para> | ||
| 1506 | </entry><entry | ||
| 1507 | align="char"> | ||
| 1508 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1509 | </entry> | ||
| 1510 | </row><row><entry | ||
| 1511 | align="char"> | ||
| 1512 | <para>int request</para> | ||
| 1513 | </entry><entry | ||
| 1514 | align="char"> | ||
| 1515 | <para>Equals VIDEO_SET_STREAMTYPE for this command.</para> | ||
| 1516 | </entry> | ||
| 1517 | </row><row><entry | ||
| 1518 | align="char"> | ||
| 1519 | <para>int type</para> | ||
| 1520 | </entry><entry | ||
| 1521 | align="char"> | ||
| 1522 | <para>stream type</para> | ||
| 1523 | </entry> | ||
| 1524 | </row></tbody></tgroup></informaltable> | ||
| 1525 | <para>ERRORS | ||
| 1526 | </para> | ||
| 1527 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1528 | align="char"> | ||
| 1529 | <para>EBADF</para> | ||
| 1530 | </entry><entry | ||
| 1531 | align="char"> | ||
| 1532 | <para>fd is not a valid open file descriptor</para> | ||
| 1533 | </entry> | ||
| 1534 | </row><row><entry | ||
| 1535 | align="char"> | ||
| 1536 | <para>EINVAL</para> | ||
| 1537 | </entry><entry | ||
| 1538 | align="char"> | ||
| 1539 | <para>type is not a valid or supported stream type.</para> | ||
| 1540 | </entry> | ||
| 1541 | </row></tbody></tgroup></informaltable> | ||
| 1542 | |||
| 1543 | </section><section | ||
| 1544 | role="subsection"><title>VIDEO_SET_FORMAT</title> | ||
| 1545 | <para>DESCRIPTION | ||
| 1546 | </para> | ||
| 1547 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1548 | align="char"> | ||
| 1549 | <para>This ioctl sets the screen format (aspect ratio) of the connected output device | ||
| 1550 | (TV) so that the output of the decoder can be adjusted accordingly.</para> | ||
| 1551 | </entry> | ||
| 1552 | </row></tbody></tgroup></informaltable> | ||
| 1553 | <para>SYNOPSIS | ||
| 1554 | </para> | ||
| 1555 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1556 | align="char"> | ||
| 1557 | <para> int ioctl(fd, int request = VIDEO_SET_FORMAT, | ||
| 1558 | video_format_t format);</para> | ||
| 1559 | </entry> | ||
| 1560 | </row></tbody></tgroup></informaltable> | ||
| 1561 | <para>PARAMETERS | ||
| 1562 | </para> | ||
| 1563 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1564 | align="char"> | ||
| 1565 | <para>int fd</para> | ||
| 1566 | </entry><entry | ||
| 1567 | align="char"> | ||
| 1568 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1569 | </entry> | ||
| 1570 | </row><row><entry | ||
| 1571 | align="char"> | ||
| 1572 | <para>int request</para> | ||
| 1573 | </entry><entry | ||
| 1574 | align="char"> | ||
| 1575 | <para>Equals VIDEO_SET_FORMAT for this command.</para> | ||
| 1576 | </entry> | ||
| 1577 | </row><row><entry | ||
| 1578 | align="char"> | ||
| 1579 | <para>video_format_t | ||
| 1580 | format</para> | ||
| 1581 | </entry><entry | ||
| 1582 | align="char"> | ||
| 1583 | <para>video format of TV as defined in section ??.</para> | ||
| 1584 | </entry> | ||
| 1585 | </row></tbody></tgroup></informaltable> | ||
| 1586 | <para>ERRORS | ||
| 1587 | </para> | ||
| 1588 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1589 | align="char"> | ||
| 1590 | <para>EBADF</para> | ||
| 1591 | </entry><entry | ||
| 1592 | align="char"> | ||
| 1593 | <para>fd is not a valid open file descriptor</para> | ||
| 1594 | </entry> | ||
| 1595 | </row><row><entry | ||
| 1596 | align="char"> | ||
| 1597 | <para>EINVAL</para> | ||
| 1598 | </entry><entry | ||
| 1599 | align="char"> | ||
| 1600 | <para>format is not a valid video format.</para> | ||
| 1601 | </entry> | ||
| 1602 | </row></tbody></tgroup></informaltable> | ||
| 1603 | |||
| 1604 | </section><section | ||
| 1605 | role="subsection"><title>VIDEO_SET_SYSTEM</title> | ||
| 1606 | <para>DESCRIPTION | ||
| 1607 | </para> | ||
| 1608 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1609 | align="char"> | ||
| 1610 | <para>This ioctl sets the television output format. The format (see section ??) may | ||
| 1611 | vary from the color format of the displayed MPEG stream. If the hardware is | ||
| 1612 | not able to display the requested format the call will return an error.</para> | ||
| 1613 | </entry> | ||
| 1614 | </row></tbody></tgroup></informaltable> | ||
| 1615 | <para>SYNOPSIS | ||
| 1616 | </para> | ||
| 1617 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1618 | align="char"> | ||
| 1619 | <para> int ioctl(fd, int request = VIDEO_SET_SYSTEM , | ||
| 1620 | video_system_t system);</para> | ||
| 1621 | </entry> | ||
| 1622 | </row></tbody></tgroup></informaltable> | ||
| 1623 | <para>PARAMETERS | ||
| 1624 | </para> | ||
| 1625 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1626 | align="char"> | ||
| 1627 | <para>int fd</para> | ||
| 1628 | </entry><entry | ||
| 1629 | align="char"> | ||
| 1630 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1631 | </entry> | ||
| 1632 | </row><row><entry | ||
| 1633 | align="char"> | ||
| 1634 | <para>int request</para> | ||
| 1635 | </entry><entry | ||
| 1636 | align="char"> | ||
| 1637 | <para>Equals VIDEO_SET_FORMAT for this command.</para> | ||
| 1638 | </entry> | ||
| 1639 | </row><row><entry | ||
| 1640 | align="char"> | ||
| 1641 | <para>video_system_t | ||
| 1642 | system</para> | ||
| 1643 | </entry><entry | ||
| 1644 | align="char"> | ||
| 1645 | <para>video system of TV output.</para> | ||
| 1646 | </entry> | ||
| 1647 | </row></tbody></tgroup></informaltable> | ||
| 1648 | <para>ERRORS | ||
| 1649 | </para> | ||
| 1650 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1651 | align="char"> | ||
| 1652 | <para>EBADF</para> | ||
| 1653 | </entry><entry | ||
| 1654 | align="char"> | ||
| 1655 | <para>fd is not a valid open file descriptor</para> | ||
| 1656 | </entry> | ||
| 1657 | </row><row><entry | ||
| 1658 | align="char"> | ||
| 1659 | <para>EINVAL</para> | ||
| 1660 | </entry><entry | ||
| 1661 | align="char"> | ||
| 1662 | <para>system is not a valid or supported video system.</para> | ||
| 1663 | </entry> | ||
| 1664 | </row></tbody></tgroup></informaltable> | ||
| 1665 | |||
| 1666 | </section><section | ||
| 1667 | role="subsection"><title>VIDEO_SET_HIGHLIGHT</title> | ||
| 1668 | <para>DESCRIPTION | ||
| 1669 | </para> | ||
| 1670 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1671 | align="char"> | ||
| 1672 | <para>This ioctl sets the SPU highlight information for the menu access of a DVD.</para> | ||
| 1673 | </entry> | ||
| 1674 | </row></tbody></tgroup></informaltable> | ||
| 1675 | <para>SYNOPSIS | ||
| 1676 | </para> | ||
| 1677 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1678 | align="char"> | ||
| 1679 | <para> int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT | ||
| 1680 | ,video_highlight_t ⋆vhilite)</para> | ||
| 1681 | </entry> | ||
| 1682 | </row></tbody></tgroup></informaltable> | ||
| 1683 | <para>PARAMETERS | ||
| 1684 | </para> | ||
| 1685 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1686 | align="char"> | ||
| 1687 | <para>int fd</para> | ||
| 1688 | </entry><entry | ||
| 1689 | align="char"> | ||
| 1690 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1691 | </entry> | ||
| 1692 | </row><row><entry | ||
| 1693 | align="char"> | ||
| 1694 | <para>int request</para> | ||
| 1695 | </entry><entry | ||
| 1696 | align="char"> | ||
| 1697 | <para>Equals VIDEO_SET_HIGHLIGHT for this command.</para> | ||
| 1698 | </entry> | ||
| 1699 | </row><row><entry | ||
| 1700 | align="char"> | ||
| 1701 | <para>video_highlight_t | ||
| 1702 | *vhilite</para> | ||
| 1703 | </entry><entry | ||
| 1704 | align="char"> | ||
| 1705 | <para>SPU Highlight information according to section ??.</para> | ||
| 1706 | </entry> | ||
| 1707 | </row></tbody></tgroup></informaltable> | ||
| 1708 | <para>ERRORS | ||
| 1709 | </para> | ||
| 1710 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1711 | align="char"> | ||
| 1712 | <para>EBADF</para> | ||
| 1713 | </entry><entry | ||
| 1714 | align="char"> | ||
| 1715 | <para>fd is not a valid open file descriptor.</para> | ||
| 1716 | </entry> | ||
| 1717 | </row><row><entry | ||
| 1718 | align="char"> | ||
| 1719 | <para>EINVAL</para> | ||
| 1720 | </entry><entry | ||
| 1721 | align="char"> | ||
| 1722 | <para>input is not a valid highlight setting.</para> | ||
| 1723 | </entry> | ||
| 1724 | </row></tbody></tgroup></informaltable> | ||
| 1725 | |||
| 1726 | </section><section | ||
| 1727 | role="subsection"><title>VIDEO_SET_SPU</title> | ||
| 1728 | <para>DESCRIPTION | ||
| 1729 | </para> | ||
| 1730 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1731 | align="char"> | ||
| 1732 | <para>This ioctl activates or deactivates SPU decoding in a DVD input stream. It can | ||
| 1733 | only be used, if the driver is able to handle a DVD stream.</para> | ||
| 1734 | </entry> | ||
| 1735 | </row></tbody></tgroup></informaltable> | ||
| 1736 | <para>SYNOPSIS | ||
| 1737 | </para> | ||
| 1738 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1739 | align="char"> | ||
| 1740 | <para> int ioctl(fd, int request = VIDEO_SET_SPU , | ||
| 1741 | video_spu_t ⋆spu)</para> | ||
| 1742 | </entry> | ||
| 1743 | </row></tbody></tgroup></informaltable> | ||
| 1744 | <para>PARAMETERS | ||
| 1745 | </para> | ||
| 1746 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1747 | align="char"> | ||
| 1748 | <para>int fd</para> | ||
| 1749 | </entry><entry | ||
| 1750 | align="char"> | ||
| 1751 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1752 | </entry> | ||
| 1753 | </row><row><entry | ||
| 1754 | align="char"> | ||
| 1755 | <para>int request</para> | ||
| 1756 | </entry><entry | ||
| 1757 | align="char"> | ||
| 1758 | <para>Equals VIDEO_SET_SPU for this command.</para> | ||
| 1759 | </entry> | ||
| 1760 | </row><row><entry | ||
| 1761 | align="char"> | ||
| 1762 | <para>video_spu_t *spu</para> | ||
| 1763 | </entry><entry | ||
| 1764 | align="char"> | ||
| 1765 | <para>SPU decoding (de)activation and subid setting according | ||
| 1766 | to section ??.</para> | ||
| 1767 | </entry> | ||
| 1768 | </row></tbody></tgroup></informaltable> | ||
| 1769 | <para>ERRORS | ||
| 1770 | </para> | ||
| 1771 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1772 | align="char"> | ||
| 1773 | <para>EBADF</para> | ||
| 1774 | </entry><entry | ||
| 1775 | align="char"> | ||
| 1776 | <para>fd is not a valid open file descriptor</para> | ||
| 1777 | </entry> | ||
| 1778 | </row><row><entry | ||
| 1779 | align="char"> | ||
| 1780 | <para>EINVAL</para> | ||
| 1781 | </entry><entry | ||
| 1782 | align="char"> | ||
| 1783 | <para>input is not a valid spu setting or driver cannot handle | ||
| 1784 | SPU.</para> | ||
| 1785 | </entry> | ||
| 1786 | </row></tbody></tgroup></informaltable> | ||
| 1787 | |||
| 1788 | </section><section | ||
| 1789 | role="subsection"><title>VIDEO_SET_SPU_PALETTE</title> | ||
| 1790 | <para>DESCRIPTION | ||
| 1791 | </para> | ||
| 1792 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1793 | align="char"> | ||
| 1794 | <para>This ioctl sets the SPU color palette.</para> | ||
| 1795 | </entry> | ||
| 1796 | </row></tbody></tgroup></informaltable> | ||
| 1797 | <para>SYNOPSIS | ||
| 1798 | </para> | ||
| 1799 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1800 | align="char"> | ||
| 1801 | <para> int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE | ||
| 1802 | ,video_spu_palette_t ⋆palette )</para> | ||
| 1803 | </entry> | ||
| 1804 | </row></tbody></tgroup></informaltable> | ||
| 1805 | <para>PARAMETERS | ||
| 1806 | </para> | ||
| 1807 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1808 | align="char"> | ||
| 1809 | <para>int fd</para> | ||
| 1810 | </entry><entry | ||
| 1811 | align="char"> | ||
| 1812 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1813 | </entry> | ||
| 1814 | </row><row><entry | ||
| 1815 | align="char"> | ||
| 1816 | <para>int request</para> | ||
| 1817 | </entry><entry | ||
| 1818 | align="char"> | ||
| 1819 | <para>Equals VIDEO_SET_SPU_PALETTE for this command.</para> | ||
| 1820 | </entry> | ||
| 1821 | </row><row><entry | ||
| 1822 | align="char"> | ||
| 1823 | <para>video_spu_palette_t | ||
| 1824 | *palette</para> | ||
| 1825 | </entry><entry | ||
| 1826 | align="char"> | ||
| 1827 | <para>SPU palette according to section ??.</para> | ||
| 1828 | </entry> | ||
| 1829 | </row></tbody></tgroup></informaltable> | ||
| 1830 | <para>ERRORS | ||
| 1831 | </para> | ||
| 1832 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1833 | align="char"> | ||
| 1834 | <para>EBADF</para> | ||
| 1835 | </entry><entry | ||
| 1836 | align="char"> | ||
| 1837 | <para>fd is not a valid open file descriptor</para> | ||
| 1838 | </entry> | ||
| 1839 | </row><row><entry | ||
| 1840 | align="char"> | ||
| 1841 | <para>EINVAL</para> | ||
| 1842 | </entry><entry | ||
| 1843 | align="char"> | ||
| 1844 | <para>input is not a valid palette or driver doesn’t handle SPU.</para> | ||
| 1845 | </entry> | ||
| 1846 | </row></tbody></tgroup></informaltable> | ||
| 1847 | |||
| 1848 | </section><section | ||
| 1849 | role="subsection"><title>VIDEO_GET_NAVI</title> | ||
| 1850 | <para>DESCRIPTION | ||
| 1851 | </para> | ||
| 1852 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1853 | align="char"> | ||
| 1854 | <para>This ioctl returns navigational information from the DVD stream. This is | ||
| 1855 | especially needed if an encoded stream has to be decoded by the hardware.</para> | ||
| 1856 | </entry> | ||
| 1857 | </row></tbody></tgroup></informaltable> | ||
| 1858 | <para>SYNOPSIS | ||
| 1859 | </para> | ||
| 1860 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1861 | align="char"> | ||
| 1862 | <para> int ioctl(fd, int request = VIDEO_GET_NAVI , | ||
| 1863 | video_navi_pack_t ⋆navipack)</para> | ||
| 1864 | </entry> | ||
| 1865 | </row></tbody></tgroup></informaltable> | ||
| 1866 | <para>PARAMETERS | ||
| 1867 | </para> | ||
| 1868 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1869 | align="char"> | ||
| 1870 | <para>int fd</para> | ||
| 1871 | </entry><entry | ||
| 1872 | align="char"> | ||
| 1873 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1874 | </entry> | ||
| 1875 | </row><row><entry | ||
| 1876 | align="char"> | ||
| 1877 | <para>int request</para> | ||
| 1878 | </entry><entry | ||
| 1879 | align="char"> | ||
| 1880 | <para>Equals VIDEO_GET_NAVI for this command.</para> | ||
| 1881 | </entry> | ||
| 1882 | </row><row><entry | ||
| 1883 | align="char"> | ||
| 1884 | <para>video_navi_pack_t | ||
| 1885 | *navipack</para> | ||
| 1886 | </entry><entry | ||
| 1887 | align="char"> | ||
| 1888 | <para>PCI or DSI pack (private stream 2) according to section | ||
| 1889 | ??.</para> | ||
| 1890 | </entry> | ||
| 1891 | </row></tbody></tgroup></informaltable> | ||
| 1892 | <para>ERRORS | ||
| 1893 | </para> | ||
| 1894 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1895 | align="char"> | ||
| 1896 | <para>EBADF</para> | ||
| 1897 | </entry><entry | ||
| 1898 | align="char"> | ||
| 1899 | <para>fd is not a valid open file descriptor</para> | ||
| 1900 | </entry> | ||
| 1901 | </row><row><entry | ||
| 1902 | align="char"> | ||
| 1903 | <para>EFAULT</para> | ||
| 1904 | </entry><entry | ||
| 1905 | align="char"> | ||
| 1906 | <para>driver is not able to return navigational information</para> | ||
| 1907 | </entry> | ||
| 1908 | </row></tbody></tgroup></informaltable> | ||
| 1909 | |||
| 1910 | </section><section | ||
| 1911 | role="subsection"><title>VIDEO_SET_ATTRIBUTES</title> | ||
| 1912 | <para>DESCRIPTION | ||
| 1913 | </para> | ||
| 1914 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1915 | align="char"> | ||
| 1916 | <para>This ioctl is intended for DVD playback and allows you to set certain | ||
| 1917 | information about the stream. Some hardware may not need this information, | ||
| 1918 | but the call also tells the hardware to prepare for DVD playback.</para> | ||
| 1919 | </entry> | ||
| 1920 | </row></tbody></tgroup></informaltable> | ||
| 1921 | <para>SYNOPSIS | ||
| 1922 | </para> | ||
| 1923 | <informaltable><tgroup cols="1"><tbody><row><entry | ||
| 1924 | align="char"> | ||
| 1925 | <para> int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE | ||
| 1926 | ,video_attributes_t vattr)</para> | ||
| 1927 | </entry> | ||
| 1928 | </row></tbody></tgroup></informaltable> | ||
| 1929 | <para>PARAMETERS | ||
| 1930 | </para> | ||
| 1931 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1932 | align="char"> | ||
| 1933 | <para>int fd</para> | ||
| 1934 | </entry><entry | ||
| 1935 | align="char"> | ||
| 1936 | <para>File descriptor returned by a previous call to open().</para> | ||
| 1937 | </entry> | ||
| 1938 | </row><row><entry | ||
| 1939 | align="char"> | ||
| 1940 | <para>int request</para> | ||
| 1941 | </entry><entry | ||
| 1942 | align="char"> | ||
| 1943 | <para>Equals VIDEO_SET_ATTRIBUTE for this command.</para> | ||
| 1944 | </entry> | ||
| 1945 | </row><row><entry | ||
| 1946 | align="char"> | ||
| 1947 | <para>video_attributes_t | ||
| 1948 | vattr</para> | ||
| 1949 | </entry><entry | ||
| 1950 | align="char"> | ||
| 1951 | <para>video attributes according to section ??.</para> | ||
| 1952 | </entry> | ||
| 1953 | </row></tbody></tgroup></informaltable> | ||
| 1954 | <para>ERRORS | ||
| 1955 | </para> | ||
| 1956 | <informaltable><tgroup cols="2"><tbody><row><entry | ||
| 1957 | align="char"> | ||
| 1958 | <para>EBADF</para> | ||
| 1959 | </entry><entry | ||
| 1960 | align="char"> | ||
| 1961 | <para>fd is not a valid open file descriptor</para> | ||
| 1962 | </entry> | ||
| 1963 | </row><row><entry | ||
| 1964 | align="char"> | ||
| 1965 | <para>EINVAL</para> | ||
| 1966 | </entry><entry | ||
| 1967 | align="char"> | ||
| 1968 | <para>input is not a valid attribute setting.</para> | ||
| 1969 | </entry> | ||
| 1970 | </row></tbody></tgroup></informaltable> | ||
| 1971 | </section></section> | ||
diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl new file mode 100644 index 000000000000..0eb43c1970bb --- /dev/null +++ b/Documentation/DocBook/media-entities.tmpl | |||
| @@ -0,0 +1,364 @@ | |||
| 1 | <!-- Generated file! Do not edit. --> | ||
| 2 | |||
| 3 | <!-- Functions --> | ||
| 4 | <!ENTITY func-close "<link linkend='func-close'><function>close()</function></link>"> | ||
| 5 | <!ENTITY func-ioctl "<link linkend='func-ioctl'><function>ioctl()</function></link>"> | ||
| 6 | <!ENTITY func-mmap "<link linkend='func-mmap'><function>mmap()</function></link>"> | ||
| 7 | <!ENTITY func-munmap "<link linkend='func-munmap'><function>munmap()</function></link>"> | ||
| 8 | <!ENTITY func-open "<link linkend='func-open'><function>open()</function></link>"> | ||
| 9 | <!ENTITY func-poll "<link linkend='func-poll'><function>poll()</function></link>"> | ||
| 10 | <!ENTITY func-read "<link linkend='func-read'><function>read()</function></link>"> | ||
| 11 | <!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>"> | ||
| 12 | <!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>"> | ||
| 13 | |||
| 14 | <!-- Ioctls --> | ||
| 15 | <!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>"> | ||
| 16 | <!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>"> | ||
| 17 | <!ENTITY VIDIOC-DBG-G-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_G_REGISTER</constant></link>"> | ||
| 18 | <!ENTITY VIDIOC-DBG-S-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_S_REGISTER</constant></link>"> | ||
| 19 | <!ENTITY VIDIOC-DQBUF "<link linkend='vidioc-qbuf'><constant>VIDIOC_DQBUF</constant></link>"> | ||
| 20 | <!ENTITY VIDIOC-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_ENCODER_CMD</constant></link>"> | ||
| 21 | <!ENTITY VIDIOC-ENUMAUDIO "<link linkend='vidioc-enumaudio'><constant>VIDIOC_ENUMAUDIO</constant></link>"> | ||
| 22 | <!ENTITY VIDIOC-ENUMAUDOUT "<link linkend='vidioc-enumaudioout'><constant>VIDIOC_ENUMAUDOUT</constant></link>"> | ||
| 23 | <!ENTITY VIDIOC-ENUMINPUT "<link linkend='vidioc-enuminput'><constant>VIDIOC_ENUMINPUT</constant></link>"> | ||
| 24 | <!ENTITY VIDIOC-ENUMOUTPUT "<link linkend='vidioc-enumoutput'><constant>VIDIOC_ENUMOUTPUT</constant></link>"> | ||
| 25 | <!ENTITY VIDIOC-ENUMSTD "<link linkend='vidioc-enumstd'><constant>VIDIOC_ENUMSTD</constant></link>"> | ||
| 26 | <!ENTITY VIDIOC-ENUM-FMT "<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link>"> | ||
| 27 | <!ENTITY VIDIOC-ENUM-FRAMEINTERVALS "<link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link>"> | ||
| 28 | <!ENTITY VIDIOC-ENUM-FRAMESIZES "<link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link>"> | ||
| 29 | <!ENTITY VIDIOC-G-AUDIO "<link linkend='vidioc-g-audio'><constant>VIDIOC_G_AUDIO</constant></link>"> | ||
| 30 | <!ENTITY VIDIOC-G-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_G_AUDOUT</constant></link>"> | ||
| 31 | <!ENTITY VIDIOC-G-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_G_CROP</constant></link>"> | ||
| 32 | <!ENTITY VIDIOC-G-CTRL "<link linkend='vidioc-g-ctrl'><constant>VIDIOC_G_CTRL</constant></link>"> | ||
| 33 | <!ENTITY VIDIOC-G-ENC-INDEX "<link linkend='vidioc-g-enc-index'><constant>VIDIOC_G_ENC_INDEX</constant></link>"> | ||
| 34 | <!ENTITY VIDIOC-G-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_G_EXT_CTRLS</constant></link>"> | ||
| 35 | <!ENTITY VIDIOC-G-FBUF "<link linkend='vidioc-g-fbuf'><constant>VIDIOC_G_FBUF</constant></link>"> | ||
| 36 | <!ENTITY VIDIOC-G-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link>"> | ||
| 37 | <!ENTITY VIDIOC-G-FREQUENCY "<link linkend='vidioc-g-frequency'><constant>VIDIOC_G_FREQUENCY</constant></link>"> | ||
| 38 | <!ENTITY VIDIOC-G-INPUT "<link linkend='vidioc-g-input'><constant>VIDIOC_G_INPUT</constant></link>"> | ||
| 39 | <!ENTITY VIDIOC-G-JPEGCOMP "<link linkend='vidioc-g-jpegcomp'><constant>VIDIOC_G_JPEGCOMP</constant></link>"> | ||
| 40 | <!ENTITY VIDIOC-G-MPEGCOMP "<link linkend=''><constant>VIDIOC_G_MPEGCOMP</constant></link>"> | ||
| 41 | <!ENTITY VIDIOC-G-MODULATOR "<link linkend='vidioc-g-modulator'><constant>VIDIOC_G_MODULATOR</constant></link>"> | ||
| 42 | <!ENTITY VIDIOC-G-OUTPUT "<link linkend='vidioc-g-output'><constant>VIDIOC_G_OUTPUT</constant></link>"> | ||
| 43 | <!ENTITY VIDIOC-G-PARM "<link linkend='vidioc-g-parm'><constant>VIDIOC_G_PARM</constant></link>"> | ||
| 44 | <!ENTITY VIDIOC-G-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_G_PRIORITY</constant></link>"> | ||
| 45 | <!ENTITY VIDIOC-G-SLICED-VBI-CAP "<link linkend='vidioc-g-sliced-vbi-cap'><constant>VIDIOC_G_SLICED_VBI_CAP</constant></link>"> | ||
| 46 | <!ENTITY VIDIOC-G-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_G_STD</constant></link>"> | ||
| 47 | <!ENTITY VIDIOC-G-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_G_TUNER</constant></link>"> | ||
| 48 | <!ENTITY VIDIOC-LOG-STATUS "<link linkend='vidioc-log-status'><constant>VIDIOC_LOG_STATUS</constant></link>"> | ||
| 49 | <!ENTITY VIDIOC-OVERLAY "<link linkend='vidioc-overlay'><constant>VIDIOC_OVERLAY</constant></link>"> | ||
| 50 | <!ENTITY VIDIOC-QBUF "<link linkend='vidioc-qbuf'><constant>VIDIOC_QBUF</constant></link>"> | ||
| 51 | <!ENTITY VIDIOC-QUERYBUF "<link linkend='vidioc-querybuf'><constant>VIDIOC_QUERYBUF</constant></link>"> | ||
| 52 | <!ENTITY VIDIOC-QUERYCAP "<link linkend='vidioc-querycap'><constant>VIDIOC_QUERYCAP</constant></link>"> | ||
| 53 | <!ENTITY VIDIOC-QUERYCTRL "<link linkend='vidioc-queryctrl'><constant>VIDIOC_QUERYCTRL</constant></link>"> | ||
| 54 | <!ENTITY VIDIOC-QUERYMENU "<link linkend='vidioc-queryctrl'><constant>VIDIOC_QUERYMENU</constant></link>"> | ||
| 55 | <!ENTITY VIDIOC-QUERYSTD "<link linkend='vidioc-querystd'><constant>VIDIOC_QUERYSTD</constant></link>"> | ||
| 56 | <!ENTITY VIDIOC-REQBUFS "<link linkend='vidioc-reqbufs'><constant>VIDIOC_REQBUFS</constant></link>"> | ||
| 57 | <!ENTITY VIDIOC-STREAMOFF "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMOFF</constant></link>"> | ||
| 58 | <!ENTITY VIDIOC-STREAMON "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMON</constant></link>"> | ||
| 59 | <!ENTITY VIDIOC-S-AUDIO "<link linkend='vidioc-g-audio'><constant>VIDIOC_S_AUDIO</constant></link>"> | ||
| 60 | <!ENTITY VIDIOC-S-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_S_AUDOUT</constant></link>"> | ||
| 61 | <!ENTITY VIDIOC-S-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_S_CROP</constant></link>"> | ||
| 62 | <!ENTITY VIDIOC-S-CTRL "<link linkend='vidioc-g-ctrl'><constant>VIDIOC_S_CTRL</constant></link>"> | ||
| 63 | <!ENTITY VIDIOC-S-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_S_EXT_CTRLS</constant></link>"> | ||
| 64 | <!ENTITY VIDIOC-S-FBUF "<link linkend='vidioc-g-fbuf'><constant>VIDIOC_S_FBUF</constant></link>"> | ||
| 65 | <!ENTITY VIDIOC-S-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link>"> | ||
| 66 | <!ENTITY VIDIOC-S-FREQUENCY "<link linkend='vidioc-g-frequency'><constant>VIDIOC_S_FREQUENCY</constant></link>"> | ||
| 67 | <!ENTITY VIDIOC-S-HW-FREQ-SEEK "<link linkend='vidioc-s-hw-freq-seek'><constant>VIDIOC_S_HW_FREQ_SEEK</constant></link>"> | ||
| 68 | <!ENTITY VIDIOC-S-INPUT "<link linkend='vidioc-g-input'><constant>VIDIOC_S_INPUT</constant></link>"> | ||
| 69 | <!ENTITY VIDIOC-S-JPEGCOMP "<link linkend='vidioc-g-jpegcomp'><constant>VIDIOC_S_JPEGCOMP</constant></link>"> | ||
| 70 | <!ENTITY VIDIOC-S-MPEGCOMP "<link linkend=''><constant>VIDIOC_S_MPEGCOMP</constant></link>"> | ||
| 71 | <!ENTITY VIDIOC-S-MODULATOR "<link linkend='vidioc-g-modulator'><constant>VIDIOC_S_MODULATOR</constant></link>"> | ||
| 72 | <!ENTITY VIDIOC-S-OUTPUT "<link linkend='vidioc-g-output'><constant>VIDIOC_S_OUTPUT</constant></link>"> | ||
| 73 | <!ENTITY VIDIOC-S-PARM "<link linkend='vidioc-g-parm'><constant>VIDIOC_S_PARM</constant></link>"> | ||
| 74 | <!ENTITY VIDIOC-S-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_S_PRIORITY</constant></link>"> | ||
| 75 | <!ENTITY VIDIOC-S-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_S_STD</constant></link>"> | ||
| 76 | <!ENTITY VIDIOC-S-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_S_TUNER</constant></link>"> | ||
| 77 | <!ENTITY VIDIOC-TRY-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_TRY_ENCODER_CMD</constant></link>"> | ||
| 78 | <!ENTITY VIDIOC-TRY-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_TRY_EXT_CTRLS</constant></link>"> | ||
| 79 | <!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>"> | ||
| 80 | |||
| 81 | <!-- Types --> | ||
| 82 | <!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>"> | ||
| 83 | |||
| 84 | <!-- Enums --> | ||
| 85 | <!ENTITY v4l2-buf-type "enum <link linkend='v4l2-buf-type'>v4l2_buf_type</link>"> | ||
| 86 | <!ENTITY v4l2-colorspace "enum <link linkend='v4l2-colorspace'>v4l2_colorspace</link>"> | ||
| 87 | <!ENTITY v4l2-ctrl-type "enum <link linkend='v4l2-ctrl-type'>v4l2_ctrl_type</link>"> | ||
| 88 | <!ENTITY v4l2-exposure-auto-type "enum <link linkend='v4l2-exposure-auto-type'>v4l2_exposure_auto_type</link>"> | ||
| 89 | <!ENTITY v4l2-field "enum <link linkend='v4l2-field'>v4l2_field</link>"> | ||
| 90 | <!ENTITY v4l2-frmivaltypes "enum <link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link>"> | ||
| 91 | <!ENTITY v4l2-frmsizetypes "enum <link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link>"> | ||
| 92 | <!ENTITY v4l2-memory "enum <link linkend='v4l2-memory'>v4l2_memory</link>"> | ||
| 93 | <!ENTITY v4l2-mpeg-audio-ac3-bitrate "enum <link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link>"> | ||
| 94 | <!ENTITY v4l2-mpeg-audio-crc "enum <link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link>"> | ||
| 95 | <!ENTITY v4l2-mpeg-audio-emphasis "enum <link linkend='v4l2-mpeg-audio-emphasis'>v4l2_mpeg_audio_emphasis</link>"> | ||
| 96 | <!ENTITY v4l2-mpeg-audio-encoding "enum <link linkend='v4l2-mpeg-audio-encoding'>v4l2_mpeg_audio_encoding</link>"> | ||
| 97 | <!ENTITY v4l2-mpeg-audio-l1-bitrate "enum <link linkend='v4l2-mpeg-audio-l1-bitrate'>v4l2_mpeg_audio_l1_bitrate</link>"> | ||
| 98 | <!ENTITY v4l2-mpeg-audio-l2-bitrate "enum <link linkend='v4l2-mpeg-audio-l2-bitrate'>v4l2_mpeg_audio_l2_bitrate</link>"> | ||
| 99 | <!ENTITY v4l2-mpeg-audio-l3-bitrate "enum <link linkend='v4l2-mpeg-audio-l3-bitrate'>v4l2_mpeg_audio_l3_bitrate</link>"> | ||
| 100 | <!ENTITY v4l2-mpeg-audio-mode "enum <link linkend='v4l2-mpeg-audio-mode'>v4l2_mpeg_audio_mode</link>"> | ||
| 101 | <!ENTITY v4l2-mpeg-audio-mode-extension "enum <link linkend='v4l2-mpeg-audio-mode-extension'>v4l2_mpeg_audio_mode_extension</link>"> | ||
| 102 | <!ENTITY v4l2-mpeg-audio-sampling-freq "enum <link linkend='v4l2-mpeg-audio-sampling-freq'>v4l2_mpeg_audio_sampling_freq</link>"> | ||
| 103 | <!ENTITY chroma-spatial-filter-type "enum <link linkend='chroma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link>"> | ||
| 104 | <!ENTITY luma-spatial-filter-type "enum <link linkend='luma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link>"> | ||
| 105 | <!ENTITY v4l2-mpeg-cx2341x-video-median-filter-type "enum <link linkend='v4l2-mpeg-cx2341x-video-median-filter-type'>v4l2_mpeg_cx2341x_video_median_filter_type</link>"> | ||
| 106 | <!ENTITY v4l2-mpeg-cx2341x-video-spatial-filter-mode "enum <link linkend='v4l2-mpeg-cx2341x-video-spatial-filter-mode'>v4l2_mpeg_cx2341x_video_spatial_filter_mode</link>"> | ||
| 107 | <!ENTITY v4l2-mpeg-cx2341x-video-temporal-filter-mode "enum <link linkend='v4l2-mpeg-cx2341x-video-temporal-filter-mode'>v4l2_mpeg_cx2341x_video_temporal_filter_mode</link>"> | ||
| 108 | <!ENTITY v4l2-mpeg-stream-type "enum <link linkend='v4l2-mpeg-stream-type'>v4l2_mpeg_stream_type</link>"> | ||
| 109 | <!ENTITY v4l2-mpeg-stream-vbi-fmt "enum <link linkend='v4l2-mpeg-stream-vbi-fmt'>v4l2_mpeg_stream_vbi_fmt</link>"> | ||
| 110 | <!ENTITY v4l2-mpeg-video-aspect "enum <link linkend='v4l2-mpeg-video-aspect'>v4l2_mpeg_video_aspect</link>"> | ||
| 111 | <!ENTITY v4l2-mpeg-video-bitrate-mode "enum <link linkend='v4l2-mpeg-video-bitrate-mode'>v4l2_mpeg_video_bitrate_mode</link>"> | ||
| 112 | <!ENTITY v4l2-mpeg-video-encoding "enum <link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link>"> | ||
| 113 | <!ENTITY v4l2-power-line-frequency "enum <link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link>"> | ||
| 114 | <!ENTITY v4l2-priority "enum <link linkend='v4l2-priority'>v4l2_priority</link>"> | ||
| 115 | <!ENTITY v4l2-tuner-type "enum <link linkend='v4l2-tuner-type'>v4l2_tuner_type</link>"> | ||
| 116 | <!ENTITY v4l2-preemphasis "enum <link linkend='v4l2-preemphasis'>v4l2_preemphasis</link>"> | ||
| 117 | |||
| 118 | <!-- Structures --> | ||
| 119 | <!ENTITY v4l2-audio "struct <link linkend='v4l2-audio'>v4l2_audio</link>"> | ||
| 120 | <!ENTITY v4l2-audioout "struct <link linkend='v4l2-audioout'>v4l2_audioout</link>"> | ||
| 121 | <!ENTITY v4l2-buffer "struct <link linkend='v4l2-buffer'>v4l2_buffer</link>"> | ||
| 122 | <!ENTITY v4l2-capability "struct <link linkend='v4l2-capability'>v4l2_capability</link>"> | ||
| 123 | <!ENTITY v4l2-captureparm "struct <link linkend='v4l2-captureparm'>v4l2_captureparm</link>"> | ||
| 124 | <!ENTITY v4l2-clip "struct <link linkend='v4l2-clip'>v4l2_clip</link>"> | ||
| 125 | <!ENTITY v4l2-control "struct <link linkend='v4l2-control'>v4l2_control</link>"> | ||
| 126 | <!ENTITY v4l2-crop "struct <link linkend='v4l2-crop'>v4l2_crop</link>"> | ||
| 127 | <!ENTITY v4l2-cropcap "struct <link linkend='v4l2-cropcap'>v4l2_cropcap</link>"> | ||
| 128 | <!ENTITY v4l2-dbg-chip-ident "struct <link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link>"> | ||
| 129 | <!ENTITY v4l2-dbg-match "struct <link linkend='v4l2-dbg-match'>v4l2_dbg_match</link>"> | ||
| 130 | <!ENTITY v4l2-dbg-register "struct <link linkend='v4l2-dbg-register'>v4l2_dbg_register</link>"> | ||
| 131 | <!ENTITY v4l2-enc-idx "struct <link linkend='v4l2-enc-idx'>v4l2_enc_idx</link>"> | ||
| 132 | <!ENTITY v4l2-enc-idx-entry "struct <link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link>"> | ||
| 133 | <!ENTITY v4l2-encoder-cmd "struct <link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link>"> | ||
| 134 | <!ENTITY v4l2-ext-control "struct <link linkend='v4l2-ext-control'>v4l2_ext_control</link>"> | ||
| 135 | <!ENTITY v4l2-ext-controls "struct <link linkend='v4l2-ext-controls'>v4l2_ext_controls</link>"> | ||
| 136 | <!ENTITY v4l2-fmtdesc "struct <link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link>"> | ||
| 137 | <!ENTITY v4l2-format "struct <link linkend='v4l2-format'>v4l2_format</link>"> | ||
| 138 | <!ENTITY v4l2-fract "struct <link linkend='v4l2-fract'>v4l2_fract</link>"> | ||
| 139 | <!ENTITY v4l2-framebuffer "struct <link linkend='v4l2-framebuffer'>v4l2_framebuffer</link>"> | ||
| 140 | <!ENTITY v4l2-frequency "struct <link linkend='v4l2-frequency'>v4l2_frequency</link>"> | ||
| 141 | <!ENTITY v4l2-frmival-stepwise "struct <link linkend='v4l2-frmival-stepwise'>v4l2_frmival_stepwise</link>"> | ||
| 142 | <!ENTITY v4l2-frmivalenum "struct <link linkend='v4l2-frmivalenum'>v4l2_frmivalenum</link>"> | ||
| 143 | <!ENTITY v4l2-frmsize-discrete "struct <link linkend='v4l2-frmsize-discrete'>v4l2_frmsize_discrete</link>"> | ||
| 144 | <!ENTITY v4l2-frmsize-stepwise "struct <link linkend='v4l2-frmsize-stepwise'>v4l2_frmsize_stepwise</link>"> | ||
| 145 | <!ENTITY v4l2-frmsizeenum "struct <link linkend='v4l2-frmsizeenum'>v4l2_frmsizeenum</link>"> | ||
| 146 | <!ENTITY v4l2-hw-freq-seek "struct <link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link>"> | ||
| 147 | <!ENTITY v4l2-input "struct <link linkend='v4l2-input'>v4l2_input</link>"> | ||
| 148 | <!ENTITY v4l2-jpegcompression "struct <link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link>"> | ||
| 149 | <!ENTITY v4l2-modulator "struct <link linkend='v4l2-modulator'>v4l2_modulator</link>"> | ||
| 150 | <!ENTITY v4l2-mpeg-vbi-fmt-ivtv "struct <link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link>"> | ||
| 151 | <!ENTITY v4l2-output "struct <link linkend='v4l2-output'>v4l2_output</link>"> | ||
| 152 | <!ENTITY v4l2-outputparm "struct <link linkend='v4l2-outputparm'>v4l2_outputparm</link>"> | ||
| 153 | <!ENTITY v4l2-pix-format "struct <link linkend='v4l2-pix-format'>v4l2_pix_format</link>"> | ||
| 154 | <!ENTITY v4l2-queryctrl "struct <link linkend='v4l2-queryctrl'>v4l2_queryctrl</link>"> | ||
| 155 | <!ENTITY v4l2-querymenu "struct <link linkend='v4l2-querymenu'>v4l2_querymenu</link>"> | ||
| 156 | <!ENTITY v4l2-rect "struct <link linkend='v4l2-rect'>v4l2_rect</link>"> | ||
| 157 | <!ENTITY v4l2-requestbuffers "struct <link linkend='v4l2-requestbuffers'>v4l2_requestbuffers</link>"> | ||
| 158 | <!ENTITY v4l2-sliced-vbi-cap "struct <link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link>"> | ||
| 159 | <!ENTITY v4l2-sliced-vbi-data "struct <link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link>"> | ||
| 160 | <!ENTITY v4l2-sliced-vbi-format "struct <link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link>"> | ||
| 161 | <!ENTITY v4l2-standard "struct <link linkend='v4l2-standard'>v4l2_standard</link>"> | ||
| 162 | <!ENTITY v4l2-streamparm "struct <link linkend='v4l2-streamparm'>v4l2_streamparm</link>"> | ||
| 163 | <!ENTITY v4l2-timecode "struct <link linkend='v4l2-timecode'>v4l2_timecode</link>"> | ||
| 164 | <!ENTITY v4l2-tuner "struct <link linkend='v4l2-tuner'>v4l2_tuner</link>"> | ||
| 165 | <!ENTITY v4l2-vbi-format "struct <link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>"> | ||
| 166 | <!ENTITY v4l2-window "struct <link linkend='v4l2-window'>v4l2_window</link>"> | ||
| 167 | |||
| 168 | <!-- Error Codes --> | ||
| 169 | <!ENTITY EACCES "<errorcode>EACCES</errorcode> error code"> | ||
| 170 | <!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code"> | ||
| 171 | <!ENTITY EBADF "<errorcode>EBADF</errorcode> error code"> | ||
| 172 | <!ENTITY EBUSY "<errorcode>EBUSY</errorcode> error code"> | ||
| 173 | <!ENTITY EFAULT "<errorcode>EFAULT</errorcode> error code"> | ||
| 174 | <!ENTITY EIO "<errorcode>EIO</errorcode> error code"> | ||
| 175 | <!ENTITY EINTR "<errorcode>EINTR</errorcode> error code"> | ||
| 176 | <!ENTITY EINVAL "<errorcode>EINVAL</errorcode> error code"> | ||
| 177 | <!ENTITY ENFILE "<errorcode>ENFILE</errorcode> error code"> | ||
| 178 | <!ENTITY ENOMEM "<errorcode>ENOMEM</errorcode> error code"> | ||
| 179 | <!ENTITY ENOSPC "<errorcode>ENOSPC</errorcode> error code"> | ||
| 180 | <!ENTITY ENOTTY "<errorcode>ENOTTY</errorcode> error code"> | ||
| 181 | <!ENTITY ENXIO "<errorcode>ENXIO</errorcode> error code"> | ||
| 182 | <!ENTITY EMFILE "<errorcode>EMFILE</errorcode> error code"> | ||
| 183 | <!ENTITY EPERM "<errorcode>EPERM</errorcode> error code"> | ||
| 184 | <!ENTITY ERANGE "<errorcode>ERANGE</errorcode> error code"> | ||
| 185 | |||
| 186 | <!-- Subsections --> | ||
| 187 | <!ENTITY sub-biblio SYSTEM "v4l/biblio.xml"> | ||
| 188 | <!ENTITY sub-common SYSTEM "v4l/common.xml"> | ||
| 189 | <!ENTITY sub-compat SYSTEM "v4l/compat.xml"> | ||
| 190 | <!ENTITY sub-controls SYSTEM "v4l/controls.xml"> | ||
| 191 | <!ENTITY sub-dev-capture SYSTEM "v4l/dev-capture.xml"> | ||
| 192 | <!ENTITY sub-dev-codec SYSTEM "v4l/dev-codec.xml"> | ||
| 193 | <!ENTITY sub-dev-effect SYSTEM "v4l/dev-effect.xml"> | ||
| 194 | <!ENTITY sub-dev-osd SYSTEM "v4l/dev-osd.xml"> | ||
| 195 | <!ENTITY sub-dev-output SYSTEM "v4l/dev-output.xml"> | ||
| 196 | <!ENTITY sub-dev-overlay SYSTEM "v4l/dev-overlay.xml"> | ||
| 197 | <!ENTITY sub-dev-radio SYSTEM "v4l/dev-radio.xml"> | ||
| 198 | <!ENTITY sub-dev-raw-vbi SYSTEM "v4l/dev-raw-vbi.xml"> | ||
| 199 | <!ENTITY sub-dev-rds SYSTEM "v4l/dev-rds.xml"> | ||
| 200 | <!ENTITY sub-dev-sliced-vbi SYSTEM "v4l/dev-sliced-vbi.xml"> | ||
| 201 | <!ENTITY sub-dev-teletext SYSTEM "v4l/dev-teletext.xml"> | ||
| 202 | <!ENTITY sub-driver SYSTEM "v4l/driver.xml"> | ||
| 203 | <!ENTITY sub-libv4l SYSTEM "v4l/libv4l.xml"> | ||
| 204 | <!ENTITY sub-remote_controllers SYSTEM "v4l/remote_controllers.xml"> | ||
| 205 | <!ENTITY sub-fdl-appendix SYSTEM "v4l/fdl-appendix.xml"> | ||
| 206 | <!ENTITY sub-close SYSTEM "v4l/func-close.xml"> | ||
| 207 | <!ENTITY sub-ioctl SYSTEM "v4l/func-ioctl.xml"> | ||
| 208 | <!ENTITY sub-mmap SYSTEM "v4l/func-mmap.xml"> | ||
| 209 | <!ENTITY sub-munmap SYSTEM "v4l/func-munmap.xml"> | ||
| 210 | <!ENTITY sub-open SYSTEM "v4l/func-open.xml"> | ||
| 211 | <!ENTITY sub-poll SYSTEM "v4l/func-poll.xml"> | ||
| 212 | <!ENTITY sub-read SYSTEM "v4l/func-read.xml"> | ||
| 213 | <!ENTITY sub-select SYSTEM "v4l/func-select.xml"> | ||
| 214 | <!ENTITY sub-write SYSTEM "v4l/func-write.xml"> | ||
| 215 | <!ENTITY sub-io SYSTEM "v4l/io.xml"> | ||
| 216 | <!ENTITY sub-grey SYSTEM "v4l/pixfmt-grey.xml"> | ||
| 217 | <!ENTITY sub-nv12 SYSTEM "v4l/pixfmt-nv12.xml"> | ||
| 218 | <!ENTITY sub-nv16 SYSTEM "v4l/pixfmt-nv16.xml"> | ||
| 219 | <!ENTITY sub-packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml"> | ||
| 220 | <!ENTITY sub-packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml"> | ||
| 221 | <!ENTITY sub-sbggr16 SYSTEM "v4l/pixfmt-sbggr16.xml"> | ||
| 222 | <!ENTITY sub-sbggr8 SYSTEM "v4l/pixfmt-sbggr8.xml"> | ||
| 223 | <!ENTITY sub-sgbrg8 SYSTEM "v4l/pixfmt-sgbrg8.xml"> | ||
| 224 | <!ENTITY sub-sgrbg8 SYSTEM "v4l/pixfmt-sgrbg8.xml"> | ||
| 225 | <!ENTITY sub-uyvy SYSTEM "v4l/pixfmt-uyvy.xml"> | ||
| 226 | <!ENTITY sub-vyuy SYSTEM "v4l/pixfmt-vyuy.xml"> | ||
| 227 | <!ENTITY sub-y16 SYSTEM "v4l/pixfmt-y16.xml"> | ||
| 228 | <!ENTITY sub-y41p SYSTEM "v4l/pixfmt-y41p.xml"> | ||
| 229 | <!ENTITY sub-yuv410 SYSTEM "v4l/pixfmt-yuv410.xml"> | ||
| 230 | <!ENTITY sub-yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml"> | ||
| 231 | <!ENTITY sub-yuv420 SYSTEM "v4l/pixfmt-yuv420.xml"> | ||
| 232 | <!ENTITY sub-yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml"> | ||
| 233 | <!ENTITY sub-yuyv SYSTEM "v4l/pixfmt-yuyv.xml"> | ||
| 234 | <!ENTITY sub-yvyu SYSTEM "v4l/pixfmt-yvyu.xml"> | ||
| 235 | <!ENTITY sub-pixfmt SYSTEM "v4l/pixfmt.xml"> | ||
| 236 | <!ENTITY sub-cropcap SYSTEM "v4l/vidioc-cropcap.xml"> | ||
| 237 | <!ENTITY sub-dbg-g-register SYSTEM "v4l/vidioc-dbg-g-register.xml"> | ||
| 238 | <!ENTITY sub-encoder-cmd SYSTEM "v4l/vidioc-encoder-cmd.xml"> | ||
| 239 | <!ENTITY sub-enum-fmt SYSTEM "v4l/vidioc-enum-fmt.xml"> | ||
| 240 | <!ENTITY sub-enum-frameintervals SYSTEM "v4l/vidioc-enum-frameintervals.xml"> | ||
| 241 | <!ENTITY sub-enum-framesizes SYSTEM "v4l/vidioc-enum-framesizes.xml"> | ||
| 242 | <!ENTITY sub-enumaudio SYSTEM "v4l/vidioc-enumaudio.xml"> | ||
| 243 | <!ENTITY sub-enumaudioout SYSTEM "v4l/vidioc-enumaudioout.xml"> | ||
| 244 | <!ENTITY sub-enuminput SYSTEM "v4l/vidioc-enuminput.xml"> | ||
| 245 | <!ENTITY sub-enumoutput SYSTEM "v4l/vidioc-enumoutput.xml"> | ||
| 246 | <!ENTITY sub-enumstd SYSTEM "v4l/vidioc-enumstd.xml"> | ||
| 247 | <!ENTITY sub-g-audio SYSTEM "v4l/vidioc-g-audio.xml"> | ||
| 248 | <!ENTITY sub-g-audioout SYSTEM "v4l/vidioc-g-audioout.xml"> | ||
| 249 | <!ENTITY sub-dbg-g-chip-ident SYSTEM "v4l/vidioc-dbg-g-chip-ident.xml"> | ||
| 250 | <!ENTITY sub-g-crop SYSTEM "v4l/vidioc-g-crop.xml"> | ||
| 251 | <!ENTITY sub-g-ctrl SYSTEM "v4l/vidioc-g-ctrl.xml"> | ||
| 252 | <!ENTITY sub-g-enc-index SYSTEM "v4l/vidioc-g-enc-index.xml"> | ||
| 253 | <!ENTITY sub-g-ext-ctrls SYSTEM "v4l/vidioc-g-ext-ctrls.xml"> | ||
| 254 | <!ENTITY sub-g-fbuf SYSTEM "v4l/vidioc-g-fbuf.xml"> | ||
| 255 | <!ENTITY sub-g-fmt SYSTEM "v4l/vidioc-g-fmt.xml"> | ||
| 256 | <!ENTITY sub-g-frequency SYSTEM "v4l/vidioc-g-frequency.xml"> | ||
| 257 | <!ENTITY sub-g-input SYSTEM "v4l/vidioc-g-input.xml"> | ||
| 258 | <!ENTITY sub-g-jpegcomp SYSTEM "v4l/vidioc-g-jpegcomp.xml"> | ||
| 259 | <!ENTITY sub-g-modulator SYSTEM "v4l/vidioc-g-modulator.xml"> | ||
| 260 | <!ENTITY sub-g-output SYSTEM "v4l/vidioc-g-output.xml"> | ||
| 261 | <!ENTITY sub-g-parm SYSTEM "v4l/vidioc-g-parm.xml"> | ||
| 262 | <!ENTITY sub-g-priority SYSTEM "v4l/vidioc-g-priority.xml"> | ||
| 263 | <!ENTITY sub-g-sliced-vbi-cap SYSTEM "v4l/vidioc-g-sliced-vbi-cap.xml"> | ||
| 264 | <!ENTITY sub-g-std SYSTEM "v4l/vidioc-g-std.xml"> | ||
| 265 | <!ENTITY sub-g-tuner SYSTEM "v4l/vidioc-g-tuner.xml"> | ||
| 266 | <!ENTITY sub-log-status SYSTEM "v4l/vidioc-log-status.xml"> | ||
| 267 | <!ENTITY sub-overlay SYSTEM "v4l/vidioc-overlay.xml"> | ||
| 268 | <!ENTITY sub-qbuf SYSTEM "v4l/vidioc-qbuf.xml"> | ||
| 269 | <!ENTITY sub-querybuf SYSTEM "v4l/vidioc-querybuf.xml"> | ||
| 270 | <!ENTITY sub-querycap SYSTEM "v4l/vidioc-querycap.xml"> | ||
| 271 | <!ENTITY sub-queryctrl SYSTEM "v4l/vidioc-queryctrl.xml"> | ||
| 272 | <!ENTITY sub-querystd SYSTEM "v4l/vidioc-querystd.xml"> | ||
| 273 | <!ENTITY sub-reqbufs SYSTEM "v4l/vidioc-reqbufs.xml"> | ||
| 274 | <!ENTITY sub-s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml"> | ||
| 275 | <!ENTITY sub-streamon SYSTEM "v4l/vidioc-streamon.xml"> | ||
| 276 | <!ENTITY sub-capture-c SYSTEM "v4l/capture.c.xml"> | ||
| 277 | <!ENTITY sub-keytable-c SYSTEM "v4l/keytable.c.xml"> | ||
| 278 | <!ENTITY sub-v4l2grab-c SYSTEM "v4l/v4l2grab.c.xml"> | ||
| 279 | <!ENTITY sub-videodev2-h SYSTEM "v4l/videodev2.h.xml"> | ||
| 280 | <!ENTITY sub-v4l2 SYSTEM "v4l/v4l2.xml"> | ||
| 281 | <!ENTITY sub-intro SYSTEM "dvb/intro.xml"> | ||
| 282 | <!ENTITY sub-frontend SYSTEM "dvb/frontend.xml"> | ||
| 283 | <!ENTITY sub-isdbt SYSTEM "dvb/isdbt.xml"> | ||
| 284 | <!ENTITY sub-demux SYSTEM "dvb/demux.xml"> | ||
| 285 | <!ENTITY sub-video SYSTEM "dvb/video.xml"> | ||
| 286 | <!ENTITY sub-audio SYSTEM "dvb/audio.xml"> | ||
| 287 | <!ENTITY sub-ca SYSTEM "dvb/ca.xml"> | ||
| 288 | <!ENTITY sub-net SYSTEM "dvb/net.xml"> | ||
| 289 | <!ENTITY sub-kdapi SYSTEM "dvb/kdapi.xml"> | ||
| 290 | <!ENTITY sub-examples SYSTEM "dvb/examples.xml"> | ||
| 291 | <!ENTITY sub-dvbapi SYSTEM "dvb/dvbapi.xml"> | ||
| 292 | <!ENTITY sub-media SYSTEM "media.xml"> | ||
| 293 | <!ENTITY sub-media-entities SYSTEM "media-entities.tmpl"> | ||
| 294 | <!ENTITY sub-media-indices SYSTEM "media-indices.tmpl"> | ||
| 295 | |||
| 296 | <!-- Function Reference --> | ||
| 297 | <!ENTITY close SYSTEM "v4l/func-close.xml"> | ||
| 298 | <!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml"> | ||
| 299 | <!ENTITY mmap SYSTEM "v4l/func-mmap.xml"> | ||
| 300 | <!ENTITY munmap SYSTEM "v4l/func-munmap.xml"> | ||
| 301 | <!ENTITY open SYSTEM "v4l/func-open.xml"> | ||
| 302 | <!ENTITY poll SYSTEM "v4l/func-poll.xml"> | ||
| 303 | <!ENTITY read SYSTEM "v4l/func-read.xml"> | ||
| 304 | <!ENTITY select SYSTEM "v4l/func-select.xml"> | ||
| 305 | <!ENTITY write SYSTEM "v4l/func-write.xml"> | ||
| 306 | <!ENTITY grey SYSTEM "v4l/pixfmt-grey.xml"> | ||
| 307 | <!ENTITY nv12 SYSTEM "v4l/pixfmt-nv12.xml"> | ||
| 308 | <!ENTITY nv16 SYSTEM "v4l/pixfmt-nv16.xml"> | ||
| 309 | <!ENTITY packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml"> | ||
| 310 | <!ENTITY packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml"> | ||
| 311 | <!ENTITY sbggr16 SYSTEM "v4l/pixfmt-sbggr16.xml"> | ||
| 312 | <!ENTITY sbggr8 SYSTEM "v4l/pixfmt-sbggr8.xml"> | ||
| 313 | <!ENTITY sgbrg8 SYSTEM "v4l/pixfmt-sgbrg8.xml"> | ||
| 314 | <!ENTITY sgrbg8 SYSTEM "v4l/pixfmt-sgrbg8.xml"> | ||
| 315 | <!ENTITY uyvy SYSTEM "v4l/pixfmt-uyvy.xml"> | ||
| 316 | <!ENTITY vyuy SYSTEM "v4l/pixfmt-vyuy.xml"> | ||
| 317 | <!ENTITY y16 SYSTEM "v4l/pixfmt-y16.xml"> | ||
| 318 | <!ENTITY y41p SYSTEM "v4l/pixfmt-y41p.xml"> | ||
| 319 | <!ENTITY yuv410 SYSTEM "v4l/pixfmt-yuv410.xml"> | ||
| 320 | <!ENTITY yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml"> | ||
| 321 | <!ENTITY yuv420 SYSTEM "v4l/pixfmt-yuv420.xml"> | ||
| 322 | <!ENTITY yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml"> | ||
| 323 | <!ENTITY yuyv SYSTEM "v4l/pixfmt-yuyv.xml"> | ||
| 324 | <!ENTITY yvyu SYSTEM "v4l/pixfmt-yvyu.xml"> | ||
| 325 | <!ENTITY cropcap SYSTEM "v4l/vidioc-cropcap.xml"> | ||
| 326 | <!ENTITY dbg-g-register SYSTEM "v4l/vidioc-dbg-g-register.xml"> | ||
| 327 | <!ENTITY encoder-cmd SYSTEM "v4l/vidioc-encoder-cmd.xml"> | ||
| 328 | <!ENTITY enum-fmt SYSTEM "v4l/vidioc-enum-fmt.xml"> | ||
| 329 | <!ENTITY enum-frameintervals SYSTEM "v4l/vidioc-enum-frameintervals.xml"> | ||
| 330 | <!ENTITY enum-framesizes SYSTEM "v4l/vidioc-enum-framesizes.xml"> | ||
| 331 | <!ENTITY enumaudio SYSTEM "v4l/vidioc-enumaudio.xml"> | ||
| 332 | <!ENTITY enumaudioout SYSTEM "v4l/vidioc-enumaudioout.xml"> | ||
| 333 | <!ENTITY enuminput SYSTEM "v4l/vidioc-enuminput.xml"> | ||
| 334 | <!ENTITY enumoutput SYSTEM "v4l/vidioc-enumoutput.xml"> | ||
| 335 | <!ENTITY enumstd SYSTEM "v4l/vidioc-enumstd.xml"> | ||
| 336 | <!ENTITY g-audio SYSTEM "v4l/vidioc-g-audio.xml"> | ||
| 337 | <!ENTITY g-audioout SYSTEM "v4l/vidioc-g-audioout.xml"> | ||
| 338 | <!ENTITY dbg-g-chip-ident SYSTEM "v4l/vidioc-dbg-g-chip-ident.xml"> | ||
| 339 | <!ENTITY g-crop SYSTEM "v4l/vidioc-g-crop.xml"> | ||
| 340 | <!ENTITY g-ctrl SYSTEM "v4l/vidioc-g-ctrl.xml"> | ||
| 341 | <!ENTITY g-enc-index SYSTEM "v4l/vidioc-g-enc-index.xml"> | ||
| 342 | <!ENTITY g-ext-ctrls SYSTEM "v4l/vidioc-g-ext-ctrls.xml"> | ||
| 343 | <!ENTITY g-fbuf SYSTEM "v4l/vidioc-g-fbuf.xml"> | ||
| 344 | <!ENTITY g-fmt SYSTEM "v4l/vidioc-g-fmt.xml"> | ||
| 345 | <!ENTITY g-frequency SYSTEM "v4l/vidioc-g-frequency.xml"> | ||
| 346 | <!ENTITY g-input SYSTEM "v4l/vidioc-g-input.xml"> | ||
| 347 | <!ENTITY g-jpegcomp SYSTEM "v4l/vidioc-g-jpegcomp.xml"> | ||
| 348 | <!ENTITY g-modulator SYSTEM "v4l/vidioc-g-modulator.xml"> | ||
| 349 | <!ENTITY g-output SYSTEM "v4l/vidioc-g-output.xml"> | ||
| 350 | <!ENTITY g-parm SYSTEM "v4l/vidioc-g-parm.xml"> | ||
| 351 | <!ENTITY g-priority SYSTEM "v4l/vidioc-g-priority.xml"> | ||
| 352 | <!ENTITY g-sliced-vbi-cap SYSTEM "v4l/vidioc-g-sliced-vbi-cap.xml"> | ||
| 353 | <!ENTITY g-std SYSTEM "v4l/vidioc-g-std.xml"> | ||
| 354 | <!ENTITY g-tuner SYSTEM "v4l/vidioc-g-tuner.xml"> | ||
| 355 | <!ENTITY log-status SYSTEM "v4l/vidioc-log-status.xml"> | ||
| 356 | <!ENTITY overlay SYSTEM "v4l/vidioc-overlay.xml"> | ||
| 357 | <!ENTITY qbuf SYSTEM "v4l/vidioc-qbuf.xml"> | ||
| 358 | <!ENTITY querybuf SYSTEM "v4l/vidioc-querybuf.xml"> | ||
| 359 | <!ENTITY querycap SYSTEM "v4l/vidioc-querycap.xml"> | ||
| 360 | <!ENTITY queryctrl SYSTEM "v4l/vidioc-queryctrl.xml"> | ||
| 361 | <!ENTITY querystd SYSTEM "v4l/vidioc-querystd.xml"> | ||
| 362 | <!ENTITY reqbufs SYSTEM "v4l/vidioc-reqbufs.xml"> | ||
| 363 | <!ENTITY s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml"> | ||
| 364 | <!ENTITY streamon SYSTEM "v4l/vidioc-streamon.xml"> | ||
diff --git a/Documentation/DocBook/media-indices.tmpl b/Documentation/DocBook/media-indices.tmpl new file mode 100644 index 000000000000..9e30a236d74f --- /dev/null +++ b/Documentation/DocBook/media-indices.tmpl | |||
| @@ -0,0 +1,85 @@ | |||
| 1 | <!-- Generated file! Do not edit. --> | ||
| 2 | |||
| 3 | <index><title>List of Types</title> | ||
| 4 | <indexentry><primaryie><link linkend='v4l2-std-id'>v4l2_std_id</link></primaryie></indexentry> | ||
| 5 | <indexentry><primaryie>enum <link linkend='v4l2-buf-type'>v4l2_buf_type</link></primaryie></indexentry> | ||
| 6 | <indexentry><primaryie>enum <link linkend='v4l2-colorspace'>v4l2_colorspace</link></primaryie></indexentry> | ||
| 7 | <indexentry><primaryie>enum <link linkend='v4l2-ctrl-type'>v4l2_ctrl_type</link></primaryie></indexentry> | ||
| 8 | <indexentry><primaryie>enum <link linkend='v4l2-exposure-auto-type'>v4l2_exposure_auto_type</link></primaryie></indexentry> | ||
| 9 | <indexentry><primaryie>enum <link linkend='v4l2-field'>v4l2_field</link></primaryie></indexentry> | ||
| 10 | <indexentry><primaryie>enum <link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link></primaryie></indexentry> | ||
| 11 | <indexentry><primaryie>enum <link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link></primaryie></indexentry> | ||
| 12 | <indexentry><primaryie>enum <link linkend='v4l2-memory'>v4l2_memory</link></primaryie></indexentry> | ||
| 13 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link></primaryie></indexentry> | ||
| 14 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link></primaryie></indexentry> | ||
| 15 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-emphasis'>v4l2_mpeg_audio_emphasis</link></primaryie></indexentry> | ||
| 16 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-encoding'>v4l2_mpeg_audio_encoding</link></primaryie></indexentry> | ||
| 17 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-l1-bitrate'>v4l2_mpeg_audio_l1_bitrate</link></primaryie></indexentry> | ||
| 18 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-l2-bitrate'>v4l2_mpeg_audio_l2_bitrate</link></primaryie></indexentry> | ||
| 19 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-l3-bitrate'>v4l2_mpeg_audio_l3_bitrate</link></primaryie></indexentry> | ||
| 20 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-mode'>v4l2_mpeg_audio_mode</link></primaryie></indexentry> | ||
| 21 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-mode-extension'>v4l2_mpeg_audio_mode_extension</link></primaryie></indexentry> | ||
| 22 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-sampling-freq'>v4l2_mpeg_audio_sampling_freq</link></primaryie></indexentry> | ||
| 23 | <indexentry><primaryie>enum <link linkend='chroma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link></primaryie></indexentry> | ||
| 24 | <indexentry><primaryie>enum <link linkend='luma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link></primaryie></indexentry> | ||
| 25 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-cx2341x-video-median-filter-type'>v4l2_mpeg_cx2341x_video_median_filter_type</link></primaryie></indexentry> | ||
| 26 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-cx2341x-video-spatial-filter-mode'>v4l2_mpeg_cx2341x_video_spatial_filter_mode</link></primaryie></indexentry> | ||
| 27 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-cx2341x-video-temporal-filter-mode'>v4l2_mpeg_cx2341x_video_temporal_filter_mode</link></primaryie></indexentry> | ||
| 28 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-stream-type'>v4l2_mpeg_stream_type</link></primaryie></indexentry> | ||
| 29 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-stream-vbi-fmt'>v4l2_mpeg_stream_vbi_fmt</link></primaryie></indexentry> | ||
| 30 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-video-aspect'>v4l2_mpeg_video_aspect</link></primaryie></indexentry> | ||
| 31 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-video-bitrate-mode'>v4l2_mpeg_video_bitrate_mode</link></primaryie></indexentry> | ||
| 32 | <indexentry><primaryie>enum <link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link></primaryie></indexentry> | ||
| 33 | <indexentry><primaryie>enum <link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link></primaryie></indexentry> | ||
| 34 | <indexentry><primaryie>enum <link linkend='v4l2-priority'>v4l2_priority</link></primaryie></indexentry> | ||
| 35 | <indexentry><primaryie>enum <link linkend='v4l2-tuner-type'>v4l2_tuner_type</link></primaryie></indexentry> | ||
| 36 | <indexentry><primaryie>enum <link linkend='v4l2-preemphasis'>v4l2_preemphasis</link></primaryie></indexentry> | ||
| 37 | <indexentry><primaryie>struct <link linkend='v4l2-audio'>v4l2_audio</link></primaryie></indexentry> | ||
| 38 | <indexentry><primaryie>struct <link linkend='v4l2-audioout'>v4l2_audioout</link></primaryie></indexentry> | ||
| 39 | <indexentry><primaryie>struct <link linkend='v4l2-buffer'>v4l2_buffer</link></primaryie></indexentry> | ||
| 40 | <indexentry><primaryie>struct <link linkend='v4l2-capability'>v4l2_capability</link></primaryie></indexentry> | ||
| 41 | <indexentry><primaryie>struct <link linkend='v4l2-captureparm'>v4l2_captureparm</link></primaryie></indexentry> | ||
| 42 | <indexentry><primaryie>struct <link linkend='v4l2-clip'>v4l2_clip</link></primaryie></indexentry> | ||
| 43 | <indexentry><primaryie>struct <link linkend='v4l2-control'>v4l2_control</link></primaryie></indexentry> | ||
| 44 | <indexentry><primaryie>struct <link linkend='v4l2-crop'>v4l2_crop</link></primaryie></indexentry> | ||
| 45 | <indexentry><primaryie>struct <link linkend='v4l2-cropcap'>v4l2_cropcap</link></primaryie></indexentry> | ||
| 46 | <indexentry><primaryie>struct <link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link></primaryie></indexentry> | ||
| 47 | <indexentry><primaryie>struct <link linkend='v4l2-dbg-match'>v4l2_dbg_match</link></primaryie></indexentry> | ||
| 48 | <indexentry><primaryie>struct <link linkend='v4l2-dbg-register'>v4l2_dbg_register</link></primaryie></indexentry> | ||
| 49 | <indexentry><primaryie>struct <link linkend='v4l2-enc-idx'>v4l2_enc_idx</link></primaryie></indexentry> | ||
| 50 | <indexentry><primaryie>struct <link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link></primaryie></indexentry> | ||
| 51 | <indexentry><primaryie>struct <link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link></primaryie></indexentry> | ||
| 52 | <indexentry><primaryie>struct <link linkend='v4l2-ext-control'>v4l2_ext_control</link></primaryie></indexentry> | ||
| 53 | <indexentry><primaryie>struct <link linkend='v4l2-ext-controls'>v4l2_ext_controls</link></primaryie></indexentry> | ||
| 54 | <indexentry><primaryie>struct <link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link></primaryie></indexentry> | ||
| 55 | <indexentry><primaryie>struct <link linkend='v4l2-format'>v4l2_format</link></primaryie></indexentry> | ||
| 56 | <indexentry><primaryie>struct <link linkend='v4l2-fract'>v4l2_fract</link></primaryie></indexentry> | ||
| 57 | <indexentry><primaryie>struct <link linkend='v4l2-framebuffer'>v4l2_framebuffer</link></primaryie></indexentry> | ||
| 58 | <indexentry><primaryie>struct <link linkend='v4l2-frequency'>v4l2_frequency</link></primaryie></indexentry> | ||
| 59 | <indexentry><primaryie>struct <link linkend='v4l2-frmival-stepwise'>v4l2_frmival_stepwise</link></primaryie></indexentry> | ||
| 60 | <indexentry><primaryie>struct <link linkend='v4l2-frmivalenum'>v4l2_frmivalenum</link></primaryie></indexentry> | ||
| 61 | <indexentry><primaryie>struct <link linkend='v4l2-frmsize-discrete'>v4l2_frmsize_discrete</link></primaryie></indexentry> | ||
| 62 | <indexentry><primaryie>struct <link linkend='v4l2-frmsize-stepwise'>v4l2_frmsize_stepwise</link></primaryie></indexentry> | ||
| 63 | <indexentry><primaryie>struct <link linkend='v4l2-frmsizeenum'>v4l2_frmsizeenum</link></primaryie></indexentry> | ||
| 64 | <indexentry><primaryie>struct <link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link></primaryie></indexentry> | ||
| 65 | <indexentry><primaryie>struct <link linkend='v4l2-input'>v4l2_input</link></primaryie></indexentry> | ||
| 66 | <indexentry><primaryie>struct <link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link></primaryie></indexentry> | ||
| 67 | <indexentry><primaryie>struct <link linkend='v4l2-modulator'>v4l2_modulator</link></primaryie></indexentry> | ||
| 68 | <indexentry><primaryie>struct <link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link></primaryie></indexentry> | ||
| 69 | <indexentry><primaryie>struct <link linkend='v4l2-output'>v4l2_output</link></primaryie></indexentry> | ||
| 70 | <indexentry><primaryie>struct <link linkend='v4l2-outputparm'>v4l2_outputparm</link></primaryie></indexentry> | ||
| 71 | <indexentry><primaryie>struct <link linkend='v4l2-pix-format'>v4l2_pix_format</link></primaryie></indexentry> | ||
| 72 | <indexentry><primaryie>struct <link linkend='v4l2-queryctrl'>v4l2_queryctrl</link></primaryie></indexentry> | ||
| 73 | <indexentry><primaryie>struct <link linkend='v4l2-querymenu'>v4l2_querymenu</link></primaryie></indexentry> | ||
| 74 | <indexentry><primaryie>struct <link linkend='v4l2-rect'>v4l2_rect</link></primaryie></indexentry> | ||
| 75 | <indexentry><primaryie>struct <link linkend='v4l2-requestbuffers'>v4l2_requestbuffers</link></primaryie></indexentry> | ||
| 76 | <indexentry><primaryie>struct <link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link></primaryie></indexentry> | ||
| 77 | <indexentry><primaryie>struct <link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link></primaryie></indexentry> | ||
| 78 | <indexentry><primaryie>struct <link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link></primaryie></indexentry> | ||
| 79 | <indexentry><primaryie>struct <link linkend='v4l2-standard'>v4l2_standard</link></primaryie></indexentry> | ||
| 80 | <indexentry><primaryie>struct <link linkend='v4l2-streamparm'>v4l2_streamparm</link></primaryie></indexentry> | ||
| 81 | <indexentry><primaryie>struct <link linkend='v4l2-timecode'>v4l2_timecode</link></primaryie></indexentry> | ||
| 82 | <indexentry><primaryie>struct <link linkend='v4l2-tuner'>v4l2_tuner</link></primaryie></indexentry> | ||
| 83 | <indexentry><primaryie>struct <link linkend='v4l2-vbi-format'>v4l2_vbi_format</link></primaryie></indexentry> | ||
| 84 | <indexentry><primaryie>struct <link linkend='v4l2-window'>v4l2_window</link></primaryie></indexentry> | ||
| 85 | </index> | ||
diff --git a/Documentation/DocBook/media.tmpl b/Documentation/DocBook/media.tmpl new file mode 100644 index 000000000000..eea564bb12cb --- /dev/null +++ b/Documentation/DocBook/media.tmpl | |||
| @@ -0,0 +1,112 @@ | |||
| 1 | <?xml version="1.0"?> | ||
| 2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | ||
| 3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ | ||
| 4 | <!ENTITY % media-entities SYSTEM "./media-entities.tmpl"> %media-entities; | ||
| 5 | <!ENTITY media-indices SYSTEM "./media-indices.tmpl"> | ||
| 6 | |||
| 7 | <!ENTITY eg "e. g."> | ||
| 8 | <!ENTITY ie "i. e."> | ||
| 9 | <!ENTITY fd "File descriptor returned by <link linkend='func-open'><function>open()</function></link>."> | ||
| 10 | <!ENTITY i2c "I<superscript>2</superscript>C"> | ||
| 11 | <!ENTITY return-value "<title>Return Value</title><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately:</para>"> | ||
| 12 | <!ENTITY manvol "<manvolnum>2</manvolnum>"> | ||
| 13 | |||
| 14 | <!-- Table templates: structs, structs w/union, defines. --> | ||
| 15 | <!ENTITY cs-str "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> | ||
| 16 | <!ENTITY cs-ustr "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='1*' /><colspec colname='c4' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c4' />"> | ||
| 17 | <!ENTITY cs-def "<colspec colname='c1' colwidth='3*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='4*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> | ||
| 18 | |||
| 19 | <!-- Video for Linux mailing list address. --> | ||
| 20 | <!ENTITY v4l-ml "<ulink url='http://www.linuxtv.org/lists.php'>http://www.linuxtv.org/lists.php</ulink>"> | ||
| 21 | |||
| 22 | <!-- LinuxTV v4l-dvb repository. --> | ||
| 23 | <!ENTITY v4l-dvb "<ulink url='http://linuxtv.org/repo/'>http://linuxtv.org/repo/</ulink>"> | ||
| 24 | ]> | ||
| 25 | |||
| 26 | <book id="media_api"> | ||
| 27 | <bookinfo> | ||
| 28 | <title>LINUX MEDIA INFRASTRUCTURE API</title> | ||
| 29 | |||
| 30 | <copyright> | ||
| 31 | <year>2009</year> | ||
| 32 | <holder>LinuxTV Developers</holder> | ||
| 33 | </copyright> | ||
| 34 | |||
| 35 | <legalnotice> | ||
| 36 | |||
| 37 | <para>Permission is granted to copy, distribute and/or modify | ||
| 38 | this document under the terms of the GNU Free Documentation License, | ||
| 39 | Version 1.1 or any later version published by the Free Software | ||
| 40 | Foundation. A copy of the license is included in the chapter entitled | ||
| 41 | "GNU Free Documentation License"</para> | ||
| 42 | </legalnotice> | ||
| 43 | |||
| 44 | </bookinfo> | ||
| 45 | |||
| 46 | <toc></toc> <!-- autogenerated --> | ||
| 47 | |||
| 48 | <preface> | ||
| 49 | <title>Introduction</title> | ||
| 50 | |||
| 51 | <para>This document covers the Linux Kernel to Userspace API's used by | ||
| 52 | video and radio straming devices, including video cameras, | ||
| 53 | analog and digital TV receiver cards, AM/FM receiver cards, | ||
| 54 | streaming capture devices.</para> | ||
| 55 | <para>It is divided into three parts.</para> | ||
| 56 | <para>The first part covers radio, capture, | ||
| 57 | cameras and analog TV devices.</para> | ||
| 58 | <para>The second part covers the | ||
| 59 | API used for digital TV and Internet reception via one of the | ||
| 60 | several digital tv standards. While it is called as DVB API, | ||
| 61 | in fact it covers several different video standards including | ||
| 62 | DVB-T, DVB-S, DVB-C and ATSC. The API is currently being updated | ||
| 63 | to documment support also for DVB-S2, ISDB-T and ISDB-S.</para> | ||
| 64 | <para>The third part covers other API's used by all media infrastructure devices</para> | ||
| 65 | <para>For additional information and for the latest development code, | ||
| 66 | see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> | ||
| 67 | <para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para> | ||
| 68 | |||
| 69 | </preface> | ||
| 70 | |||
| 71 | <part id="v4l2spec"> | ||
| 72 | &sub-v4l2; | ||
| 73 | </part> | ||
| 74 | <part id="dvbapi"> | ||
| 75 | &sub-dvbapi; | ||
| 76 | </part> | ||
| 77 | <part id="v4ldvb_common"> | ||
| 78 | <partinfo> | ||
| 79 | <authorgroup> | ||
| 80 | <author> | ||
| 81 | <firstname>Mauro</firstname> | ||
| 82 | <surname>Chehab</surname> | ||
| 83 | <othername role="mi">Carvalho</othername> | ||
| 84 | <affiliation><address><email>mchehab@redhat.com</email></address></affiliation> | ||
| 85 | <contrib>Initial version.</contrib> | ||
| 86 | </author> | ||
| 87 | </authorgroup> | ||
| 88 | <copyright> | ||
| 89 | <year>2009</year> | ||
| 90 | <holder>Mauro Carvalho Chehab</holder> | ||
| 91 | </copyright> | ||
| 92 | |||
| 93 | <revhistory> | ||
| 94 | <!-- Put document revisions here, newest first. --> | ||
| 95 | <revision> | ||
| 96 | <revnumber>1.0.0</revnumber> | ||
| 97 | <date>2009-09-06</date> | ||
| 98 | <authorinitials>mcc</authorinitials> | ||
| 99 | <revremark>Initial revision</revremark> | ||
| 100 | </revision> | ||
| 101 | </revhistory> | ||
| 102 | </partinfo> | ||
| 103 | |||
| 104 | <title>Other API's used by media infrastructure drivers</title> | ||
| 105 | <chapter id="remote_controllers"> | ||
| 106 | &sub-remote_controllers; | ||
| 107 | </chapter> | ||
| 108 | </part> | ||
| 109 | |||
| 110 | &sub-fdl-appendix; | ||
| 111 | |||
| 112 | </book> | ||
diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl index 8e145857fc9d..df0d089d0fb9 100644 --- a/Documentation/DocBook/mtdnand.tmpl +++ b/Documentation/DocBook/mtdnand.tmpl | |||
| @@ -568,7 +568,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) | |||
| 568 | <para> | 568 | <para> |
| 569 | The blocks in which the tables are stored are procteted against | 569 | The blocks in which the tables are stored are procteted against |
| 570 | accidental access by marking them bad in the memory bad block | 570 | accidental access by marking them bad in the memory bad block |
| 571 | table. The bad block table managment functions are allowed | 571 | table. The bad block table management functions are allowed |
| 572 | to circumvernt this protection. | 572 | to circumvernt this protection. |
| 573 | </para> | 573 | </para> |
| 574 | <para> | 574 | <para> |
diff --git a/Documentation/DocBook/scsi.tmpl b/Documentation/DocBook/scsi.tmpl index 10a150ae2a7e..d87f4569e768 100644 --- a/Documentation/DocBook/scsi.tmpl +++ b/Documentation/DocBook/scsi.tmpl | |||
| @@ -317,7 +317,7 @@ | |||
| 317 | <para> | 317 | <para> |
| 318 | The SAS transport class contains common code to deal with SAS HBAs, | 318 | The SAS transport class contains common code to deal with SAS HBAs, |
| 319 | an aproximated representation of SAS topologies in the driver model, | 319 | an aproximated representation of SAS topologies in the driver model, |
| 320 | and various sysfs attributes to expose these topologies and managment | 320 | and various sysfs attributes to expose these topologies and management |
| 321 | interfaces to userspace. | 321 | interfaces to userspace. |
| 322 | </para> | 322 | </para> |
| 323 | <para> | 323 | <para> |
diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl index 974e17ccf106..254c1d5d2e50 100644 --- a/Documentation/DocBook/stylesheet.xsl +++ b/Documentation/DocBook/stylesheet.xsl | |||
| @@ -3,6 +3,7 @@ | |||
| 3 | <param name="chunk.quietly">1</param> | 3 | <param name="chunk.quietly">1</param> |
| 4 | <param name="funcsynopsis.style">ansi</param> | 4 | <param name="funcsynopsis.style">ansi</param> |
| 5 | <param name="funcsynopsis.tabular.threshold">80</param> | 5 | <param name="funcsynopsis.tabular.threshold">80</param> |
| 6 | <param name="callout.graphics">0</param> | ||
| 6 | <!-- <param name="paper.type">A4</param> --> | 7 | <!-- <param name="paper.type">A4</param> --> |
| 7 | <param name="generate.section.toc.level">2</param> | 8 | <param name="generate.section.toc.level">2</param> |
| 8 | </stylesheet> | 9 | </stylesheet> |
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index 8f6e3b2403c7..4d4ce0e61e42 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl | |||
| @@ -25,6 +25,10 @@ | |||
| 25 | <year>2006-2008</year> | 25 | <year>2006-2008</year> |
| 26 | <holder>Hans-Jürgen Koch.</holder> | 26 | <holder>Hans-Jürgen Koch.</holder> |
| 27 | </copyright> | 27 | </copyright> |
| 28 | <copyright> | ||
| 29 | <year>2009</year> | ||
| 30 | <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder> | ||
| 31 | </copyright> | ||
| 28 | 32 | ||
| 29 | <legalnotice> | 33 | <legalnotice> |
| 30 | <para> | 34 | <para> |
| @@ -42,6 +46,13 @@ GPL version 2. | |||
| 42 | 46 | ||
| 43 | <revhistory> | 47 | <revhistory> |
| 44 | <revision> | 48 | <revision> |
| 49 | <revnumber>0.9</revnumber> | ||
| 50 | <date>2009-07-16</date> | ||
| 51 | <authorinitials>mst</authorinitials> | ||
| 52 | <revremark>Added generic pci driver | ||
| 53 | </revremark> | ||
| 54 | </revision> | ||
| 55 | <revision> | ||
| 45 | <revnumber>0.8</revnumber> | 56 | <revnumber>0.8</revnumber> |
| 46 | <date>2008-12-24</date> | 57 | <date>2008-12-24</date> |
| 47 | <authorinitials>hjk</authorinitials> | 58 | <authorinitials>hjk</authorinitials> |
| @@ -809,6 +820,158 @@ framework to set up sysfs files for this region. Simply leave it alone. | |||
| 809 | 820 | ||
| 810 | </chapter> | 821 | </chapter> |
| 811 | 822 | ||
| 823 | <chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards"> | ||
| 824 | <?dbhtml filename="uio_pci_generic.html"?> | ||
| 825 | <title>Generic PCI UIO driver</title> | ||
| 826 | <para> | ||
| 827 | The generic driver is a kernel module named uio_pci_generic. | ||
| 828 | It can work with any device compliant to PCI 2.3 (circa 2002) and | ||
| 829 | any compliant PCI Express device. Using this, you only need to | ||
| 830 | write the userspace driver, removing the need to write | ||
| 831 | a hardware-specific kernel module. | ||
| 832 | </para> | ||
| 833 | |||
| 834 | <sect1 id="uio_pci_generic_binding"> | ||
| 835 | <title>Making the driver recognize the device</title> | ||
| 836 | <para> | ||
| 837 | Since the driver does not declare any device ids, it will not get loaded | ||
| 838 | automatically and will not automatically bind to any devices, you must load it | ||
| 839 | and allocate id to the driver yourself. For example: | ||
| 840 | <programlisting> | ||
| 841 | modprobe uio_pci_generic | ||
| 842 | echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id | ||
| 843 | </programlisting> | ||
| 844 | </para> | ||
| 845 | <para> | ||
| 846 | If there already is a hardware specific kernel driver for your device, the | ||
| 847 | generic driver still won't bind to it, in this case if you want to use the | ||
| 848 | generic driver (why would you?) you'll have to manually unbind the hardware | ||
| 849 | specific driver and bind the generic driver, like this: | ||
| 850 | <programlisting> | ||
| 851 | echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind | ||
| 852 | echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind | ||
| 853 | </programlisting> | ||
| 854 | </para> | ||
| 855 | <para> | ||
| 856 | You can verify that the device has been bound to the driver | ||
| 857 | by looking for it in sysfs, for example like the following: | ||
| 858 | <programlisting> | ||
| 859 | ls -l /sys/bus/pci/devices/0000:00:19.0/driver | ||
| 860 | </programlisting> | ||
| 861 | Which if successful should print | ||
| 862 | <programlisting> | ||
| 863 | .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic | ||
| 864 | </programlisting> | ||
| 865 | Note that the generic driver will not bind to old PCI 2.2 devices. | ||
| 866 | If binding the device failed, run the following command: | ||
| 867 | <programlisting> | ||
| 868 | dmesg | ||
| 869 | </programlisting> | ||
| 870 | and look in the output for failure reasons | ||
| 871 | </para> | ||
| 872 | </sect1> | ||
| 873 | |||
| 874 | <sect1 id="uio_pci_generic_internals"> | ||
| 875 | <title>Things to know about uio_pci_generic</title> | ||
| 876 | <para> | ||
| 877 | Interrupts are handled using the Interrupt Disable bit in the PCI command | ||
| 878 | register and Interrupt Status bit in the PCI status register. All devices | ||
| 879 | compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should | ||
| 880 | support these bits. uio_pci_generic detects this support, and won't bind to | ||
| 881 | devices which do not support the Interrupt Disable Bit in the command register. | ||
| 882 | </para> | ||
| 883 | <para> | ||
| 884 | On each interrupt, uio_pci_generic sets the Interrupt Disable bit. | ||
| 885 | This prevents the device from generating further interrupts | ||
| 886 | until the bit is cleared. The userspace driver should clear this | ||
| 887 | bit before blocking and waiting for more interrupts. | ||
| 888 | </para> | ||
| 889 | </sect1> | ||
| 890 | <sect1 id="uio_pci_generic_userspace"> | ||
| 891 | <title>Writing userspace driver using uio_pci_generic</title> | ||
| 892 | <para> | ||
| 893 | Userspace driver can use pci sysfs interface, or the | ||
| 894 | libpci libray that wraps it, to talk to the device and to | ||
| 895 | re-enable interrupts by writing to the command register. | ||
| 896 | </para> | ||
| 897 | </sect1> | ||
| 898 | <sect1 id="uio_pci_generic_example"> | ||
| 899 | <title>Example code using uio_pci_generic</title> | ||
| 900 | <para> | ||
| 901 | Here is some sample userspace driver code using uio_pci_generic: | ||
| 902 | <programlisting> | ||
| 903 | #include <stdlib.h> | ||
| 904 | #include <stdio.h> | ||
| 905 | #include <unistd.h> | ||
| 906 | #include <sys/types.h> | ||
| 907 | #include <sys/stat.h> | ||
| 908 | #include <fcntl.h> | ||
| 909 | #include <errno.h> | ||
| 910 | |||
| 911 | int main() | ||
| 912 | { | ||
| 913 | int uiofd; | ||
| 914 | int configfd; | ||
| 915 | int err; | ||
| 916 | int i; | ||
| 917 | unsigned icount; | ||
| 918 | unsigned char command_high; | ||
| 919 | |||
| 920 | uiofd = open("/dev/uio0", O_RDONLY); | ||
| 921 | if (uiofd < 0) { | ||
| 922 | perror("uio open:"); | ||
| 923 | return errno; | ||
| 924 | } | ||
| 925 | configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); | ||
| 926 | if (uiofd < 0) { | ||
| 927 | perror("config open:"); | ||
| 928 | return errno; | ||
| 929 | } | ||
| 930 | |||
| 931 | /* Read and cache command value */ | ||
| 932 | err = pread(configfd, &command_high, 1, 5); | ||
| 933 | if (err != 1) { | ||
| 934 | perror("command config read:"); | ||
| 935 | return errno; | ||
| 936 | } | ||
| 937 | command_high &= ~0x4; | ||
| 938 | |||
| 939 | for(i = 0;; ++i) { | ||
| 940 | /* Print out a message, for debugging. */ | ||
| 941 | if (i == 0) | ||
| 942 | fprintf(stderr, "Started uio test driver.\n"); | ||
| 943 | else | ||
| 944 | fprintf(stderr, "Interrupts: %d\n", icount); | ||
| 945 | |||
| 946 | /****************************************/ | ||
| 947 | /* Here we got an interrupt from the | ||
| 948 | device. Do something to it. */ | ||
| 949 | /****************************************/ | ||
| 950 | |||
| 951 | /* Re-enable interrupts. */ | ||
| 952 | err = pwrite(configfd, &command_high, 1, 5); | ||
| 953 | if (err != 1) { | ||
| 954 | perror("config write:"); | ||
| 955 | break; | ||
| 956 | } | ||
| 957 | |||
| 958 | /* Wait for next interrupt. */ | ||
| 959 | err = read(uiofd, &icount, 4); | ||
| 960 | if (err != 4) { | ||
| 961 | perror("uio read:"); | ||
| 962 | break; | ||
| 963 | } | ||
| 964 | |||
| 965 | } | ||
| 966 | return errno; | ||
| 967 | } | ||
| 968 | |||
| 969 | </programlisting> | ||
| 970 | </para> | ||
| 971 | </sect1> | ||
| 972 | |||
| 973 | </chapter> | ||
| 974 | |||
| 812 | <appendix id="app1"> | 975 | <appendix id="app1"> |
| 813 | <title>Further information</title> | 976 | <title>Further information</title> |
| 814 | <itemizedlist> | 977 | <itemizedlist> |
diff --git a/Documentation/DocBook/v4l/.gitignore b/Documentation/DocBook/v4l/.gitignore new file mode 100644 index 000000000000..d7ec32eafac9 --- /dev/null +++ b/Documentation/DocBook/v4l/.gitignore | |||
| @@ -0,0 +1 @@ | |||
| !*.xml | |||
diff --git a/Documentation/DocBook/v4l/biblio.xml b/Documentation/DocBook/v4l/biblio.xml new file mode 100644 index 000000000000..afc8a0dd2601 --- /dev/null +++ b/Documentation/DocBook/v4l/biblio.xml | |||
| @@ -0,0 +1,188 @@ | |||
| 1 | <bibliography> | ||
| 2 | <title>References</title> | ||
| 3 | |||
| 4 | <biblioentry id="eia608"> | ||
| 5 | <abbrev>EIA 608-B</abbrev> | ||
| 6 | <authorgroup> | ||
| 7 | <corpauthor>Electronic Industries Alliance (<ulink | ||
| 8 | url="http://www.eia.org">http://www.eia.org</ulink>)</corpauthor> | ||
| 9 | </authorgroup> | ||
| 10 | <title>EIA 608-B "Recommended Practice for Line 21 Data | ||
| 11 | Service"</title> | ||
| 12 | </biblioentry> | ||
| 13 | |||
| 14 | <biblioentry id="en300294"> | ||
| 15 | <abbrev>EN 300 294</abbrev> | ||
| 16 | <authorgroup> | ||
| 17 | <corpauthor>European Telecommunication Standards Institute | ||
| 18 | (<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor> | ||
| 19 | </authorgroup> | ||
| 20 | <title>EN 300 294 "625-line television Wide Screen Signalling | ||
| 21 | (WSS)"</title> | ||
| 22 | </biblioentry> | ||
| 23 | |||
| 24 | <biblioentry id="ets300231"> | ||
| 25 | <abbrev>ETS 300 231</abbrev> | ||
| 26 | <authorgroup> | ||
| 27 | <corpauthor>European Telecommunication Standards Institute | ||
| 28 | (<ulink | ||
| 29 | url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor> | ||
| 30 | </authorgroup> | ||
| 31 | <title>ETS 300 231 "Specification of the domestic video | ||
| 32 | Programme Delivery Control system (PDC)"</title> | ||
| 33 | </biblioentry> | ||
| 34 | |||
| 35 | <biblioentry id="ets300706"> | ||
| 36 | <abbrev>ETS 300 706</abbrev> | ||
| 37 | <authorgroup> | ||
| 38 | <corpauthor>European Telecommunication Standards Institute | ||
| 39 | (<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor> | ||
| 40 | </authorgroup> | ||
| 41 | <title>ETS 300 706 "Enhanced Teletext specification"</title> | ||
| 42 | </biblioentry> | ||
| 43 | |||
| 44 | <biblioentry id="mpeg2part1"> | ||
| 45 | <abbrev>ISO 13818-1</abbrev> | ||
| 46 | <authorgroup> | ||
| 47 | <corpauthor>International Telecommunication Union (<ulink | ||
| 48 | url="http://www.itu.ch">http://www.itu.ch</ulink>), International | ||
| 49 | Organisation for Standardisation (<ulink | ||
| 50 | url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor> | ||
| 51 | </authorgroup> | ||
| 52 | <title>ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information | ||
| 53 | technology — Generic coding of moving pictures and associated | ||
| 54 | audio information: Systems"</title> | ||
| 55 | </biblioentry> | ||
| 56 | |||
| 57 | <biblioentry id="mpeg2part2"> | ||
| 58 | <abbrev>ISO 13818-2</abbrev> | ||
| 59 | <authorgroup> | ||
| 60 | <corpauthor>International Telecommunication Union (<ulink | ||
| 61 | url="http://www.itu.ch">http://www.itu.ch</ulink>), International | ||
| 62 | Organisation for Standardisation (<ulink | ||
| 63 | url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor> | ||
| 64 | </authorgroup> | ||
| 65 | <title>ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information | ||
| 66 | technology — Generic coding of moving pictures and associated | ||
| 67 | audio information: Video"</title> | ||
| 68 | </biblioentry> | ||
| 69 | |||
| 70 | <biblioentry id="itu470"> | ||
| 71 | <abbrev>ITU BT.470</abbrev> | ||
| 72 | <authorgroup> | ||
| 73 | <corpauthor>International Telecommunication Union (<ulink | ||
| 74 | url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> | ||
| 75 | </authorgroup> | ||
| 76 | <title>ITU-R Recommendation BT.470-6 "Conventional Television | ||
| 77 | Systems"</title> | ||
| 78 | </biblioentry> | ||
| 79 | |||
| 80 | <biblioentry id="itu601"> | ||
| 81 | <abbrev>ITU BT.601</abbrev> | ||
| 82 | <authorgroup> | ||
| 83 | <corpauthor>International Telecommunication Union (<ulink | ||
| 84 | url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> | ||
| 85 | </authorgroup> | ||
| 86 | <title>ITU-R Recommendation BT.601-5 "Studio Encoding Parameters | ||
| 87 | of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect | ||
| 88 | Ratios"</title> | ||
| 89 | </biblioentry> | ||
| 90 | |||
| 91 | <biblioentry id="itu653"> | ||
| 92 | <abbrev>ITU BT.653</abbrev> | ||
| 93 | <authorgroup> | ||
| 94 | <corpauthor>International Telecommunication Union (<ulink | ||
| 95 | url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> | ||
| 96 | </authorgroup> | ||
| 97 | <title>ITU-R Recommendation BT.653-3 "Teletext systems"</title> | ||
| 98 | </biblioentry> | ||
| 99 | |||
| 100 | <biblioentry id="itu709"> | ||
| 101 | <abbrev>ITU BT.709</abbrev> | ||
| 102 | <authorgroup> | ||
| 103 | <corpauthor>International Telecommunication Union (<ulink | ||
| 104 | url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> | ||
| 105 | </authorgroup> | ||
| 106 | <title>ITU-R Recommendation BT.709-5 "Parameter values for the | ||
| 107 | HDTV standards for production and international programme | ||
| 108 | exchange"</title> | ||
| 109 | </biblioentry> | ||
| 110 | |||
| 111 | <biblioentry id="itu1119"> | ||
| 112 | <abbrev>ITU BT.1119</abbrev> | ||
| 113 | <authorgroup> | ||
| 114 | <corpauthor>International Telecommunication Union (<ulink | ||
| 115 | url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> | ||
| 116 | </authorgroup> | ||
| 117 | <title>ITU-R Recommendation BT.1119 "625-line | ||
| 118 | television Wide Screen Signalling (WSS)"</title> | ||
| 119 | </biblioentry> | ||
| 120 | |||
| 121 | <biblioentry id="jfif"> | ||
| 122 | <abbrev>JFIF</abbrev> | ||
| 123 | <authorgroup> | ||
| 124 | <corpauthor>Independent JPEG Group (<ulink | ||
| 125 | url="http://www.ijg.org">http://www.ijg.org</ulink>)</corpauthor> | ||
| 126 | </authorgroup> | ||
| 127 | <title>JPEG File Interchange Format</title> | ||
| 128 | <subtitle>Version 1.02</subtitle> | ||
| 129 | </biblioentry> | ||
| 130 | |||
| 131 | <biblioentry id="smpte12m"> | ||
| 132 | <abbrev>SMPTE 12M</abbrev> | ||
| 133 | <authorgroup> | ||
| 134 | <corpauthor>Society of Motion Picture and Television Engineers | ||
| 135 | (<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> | ||
| 136 | </authorgroup> | ||
| 137 | <title>SMPTE 12M-1999 "Television, Audio and Film - Time and | ||
| 138 | Control Code"</title> | ||
| 139 | </biblioentry> | ||
| 140 | |||
| 141 | <biblioentry id="smpte170m"> | ||
| 142 | <abbrev>SMPTE 170M</abbrev> | ||
| 143 | <authorgroup> | ||
| 144 | <corpauthor>Society of Motion Picture and Television Engineers | ||
| 145 | (<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> | ||
| 146 | </authorgroup> | ||
| 147 | <title>SMPTE 170M-1999 "Television - Composite Analog Video | ||
| 148 | Signal - NTSC for Studio Applications"</title> | ||
| 149 | </biblioentry> | ||
| 150 | |||
| 151 | <biblioentry id="smpte240m"> | ||
| 152 | <abbrev>SMPTE 240M</abbrev> | ||
| 153 | <authorgroup> | ||
| 154 | <corpauthor>Society of Motion Picture and Television Engineers | ||
| 155 | (<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> | ||
| 156 | </authorgroup> | ||
| 157 | <title>SMPTE 240M-1999 "Television - Signal Parameters - | ||
| 158 | 1125-Line High-Definition Production"</title> | ||
| 159 | </biblioentry> | ||
| 160 | |||
| 161 | <biblioentry id="en50067"> | ||
| 162 | <abbrev>EN 50067</abbrev> | ||
| 163 | <authorgroup> | ||
| 164 | <corpauthor>European Committee for Electrotechnical Standardization | ||
| 165 | (<ulink url="http://www.cenelec.eu">http://www.cenelec.eu</ulink>)</corpauthor> | ||
| 166 | </authorgroup> | ||
| 167 | <title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting | ||
| 168 | in the frequency range from 87,5 to 108,0 MHz</title> | ||
| 169 | </biblioentry> | ||
| 170 | |||
| 171 | <biblioentry id="nrsc4"> | ||
| 172 | <abbrev>NRSC-4</abbrev> | ||
| 173 | <authorgroup> | ||
| 174 | <corpauthor>National Radio Systems Committee | ||
| 175 | (<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor> | ||
| 176 | </authorgroup> | ||
| 177 | <title>NTSC-4: United States RBDS Standard</title> | ||
| 178 | </biblioentry> | ||
| 179 | |||
| 180 | </bibliography> | ||
| 181 | |||
| 182 | <!-- | ||
| 183 | Local Variables: | ||
| 184 | mode: sgml | ||
| 185 | sgml-parent-document: "v4l2.sgml" | ||
| 186 | indent-tabs-mode: nil | ||
| 187 | End: | ||
| 188 | --> | ||
diff --git a/Documentation/DocBook/v4l/capture.c.xml b/Documentation/DocBook/v4l/capture.c.xml new file mode 100644 index 000000000000..1c5c49a2de59 --- /dev/null +++ b/Documentation/DocBook/v4l/capture.c.xml | |||
| @@ -0,0 +1,659 @@ | |||
| 1 | <programlisting> | ||
| 2 | /* | ||
| 3 | * V4L2 video capture example | ||
| 4 | * | ||
| 5 | * This program can be used and distributed without restrictions. | ||
| 6 | * | ||
| 7 | * This program is provided with the V4L2 API | ||
| 8 | * see http://linuxtv.org/docs.php for more information | ||
| 9 | */ | ||
| 10 | |||
| 11 | #include <stdio.h> | ||
| 12 | #include <stdlib.h> | ||
| 13 | #include <string.h> | ||
| 14 | #include <assert.h> | ||
| 15 | |||
| 16 | #include <getopt.h> /* getopt_long() */ | ||
| 17 | |||
| 18 | #include <fcntl.h> /* low-level i/o */ | ||
| 19 | #include <unistd.h> | ||
| 20 | #include <errno.h> | ||
| 21 | #include <sys/stat.h> | ||
| 22 | #include <sys/types.h> | ||
| 23 | #include <sys/time.h> | ||
| 24 | #include <sys/mman.h> | ||
| 25 | #include <sys/ioctl.h> | ||
| 26 | |||
| 27 | #include <linux/videodev2.h> | ||
| 28 | |||
| 29 | #define CLEAR(x) memset(&(x), 0, sizeof(x)) | ||
| 30 | |||
| 31 | enum io_method { | ||
| 32 | IO_METHOD_READ, | ||
| 33 | IO_METHOD_MMAP, | ||
| 34 | IO_METHOD_USERPTR, | ||
| 35 | }; | ||
| 36 | |||
| 37 | struct buffer { | ||
| 38 | void *start; | ||
| 39 | size_t length; | ||
| 40 | }; | ||
| 41 | |||
| 42 | static char *dev_name; | ||
| 43 | static enum io_method io = IO_METHOD_MMAP; | ||
| 44 | static int fd = -1; | ||
| 45 | struct buffer *buffers; | ||
| 46 | static unsigned int n_buffers; | ||
| 47 | static int out_buf; | ||
| 48 | static int force_format; | ||
| 49 | static int frame_count = 70; | ||
| 50 | |||
| 51 | static void errno_exit(const char *s) | ||
| 52 | { | ||
| 53 | fprintf(stderr, "%s error %d, %s\n", s, errno, strerror(errno)); | ||
| 54 | exit(EXIT_FAILURE); | ||
| 55 | } | ||
| 56 | |||
| 57 | static int xioctl(int fh, int request, void *arg) | ||
| 58 | { | ||
| 59 | int r; | ||
| 60 | |||
| 61 | do { | ||
| 62 | r = ioctl(fh, request, arg); | ||
| 63 | } while (-1 == r && EINTR == errno); | ||
| 64 | |||
| 65 | return r; | ||
| 66 | } | ||
| 67 | |||
| 68 | static void process_image(const void *p, int size) | ||
| 69 | { | ||
| 70 | if (out_buf) | ||
| 71 | fwrite(p, size, 1, stdout); | ||
| 72 | |||
| 73 | fflush(stderr); | ||
| 74 | fprintf(stderr, "."); | ||
| 75 | fflush(stdout); | ||
| 76 | } | ||
| 77 | |||
| 78 | static int read_frame(void) | ||
| 79 | { | ||
| 80 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; | ||
| 81 | unsigned int i; | ||
| 82 | |||
| 83 | switch (io) { | ||
| 84 | case IO_METHOD_READ: | ||
| 85 | if (-1 == read(fd, buffers[0].start, buffers[0].length)) { | ||
| 86 | switch (errno) { | ||
| 87 | case EAGAIN: | ||
| 88 | return 0; | ||
| 89 | |||
| 90 | case EIO: | ||
| 91 | /* Could ignore EIO, see spec. */ | ||
| 92 | |||
| 93 | /* fall through */ | ||
| 94 | |||
| 95 | default: | ||
| 96 | errno_exit("read"); | ||
| 97 | } | ||
| 98 | } | ||
| 99 | |||
| 100 | process_image(buffers[0].start, buffers[0].length); | ||
| 101 | break; | ||
| 102 | |||
| 103 | case IO_METHOD_MMAP: | ||
| 104 | CLEAR(buf); | ||
| 105 | |||
| 106 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 107 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 108 | |||
| 109 | if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { | ||
| 110 | switch (errno) { | ||
| 111 | case EAGAIN: | ||
| 112 | return 0; | ||
| 113 | |||
| 114 | case EIO: | ||
| 115 | /* Could ignore EIO, see spec. */ | ||
| 116 | |||
| 117 | /* fall through */ | ||
| 118 | |||
| 119 | default: | ||
| 120 | errno_exit("VIDIOC_DQBUF"); | ||
| 121 | } | ||
| 122 | } | ||
| 123 | |||
| 124 | assert(buf.index < n_buffers); | ||
| 125 | |||
| 126 | process_image(buffers[buf.index].start, buf.bytesused); | ||
| 127 | |||
| 128 | if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) | ||
| 129 | errno_exit("VIDIOC_QBUF"); | ||
| 130 | break; | ||
| 131 | |||
| 132 | case IO_METHOD_USERPTR: | ||
| 133 | CLEAR(buf); | ||
| 134 | |||
| 135 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 136 | buf.memory = V4L2_MEMORY_USERPTR; | ||
| 137 | |||
| 138 | if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { | ||
| 139 | switch (errno) { | ||
| 140 | case EAGAIN: | ||
| 141 | return 0; | ||
| 142 | |||
| 143 | case EIO: | ||
| 144 | /* Could ignore EIO, see spec. */ | ||
| 145 | |||
| 146 | /* fall through */ | ||
| 147 | |||
| 148 | default: | ||
| 149 | errno_exit("VIDIOC_DQBUF"); | ||
| 150 | } | ||
| 151 | } | ||
| 152 | |||
| 153 | for (i = 0; i < n_buffers; ++i) | ||
| 154 | if (buf.m.userptr == (unsigned long)buffers[i].start | ||
| 155 | && buf.length == buffers[i].length) | ||
| 156 | break; | ||
| 157 | |||
| 158 | assert(i < n_buffers); | ||
| 159 | |||
| 160 | process_image((void *)buf.m.userptr, buf.bytesused); | ||
| 161 | |||
| 162 | if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) | ||
| 163 | errno_exit("VIDIOC_QBUF"); | ||
| 164 | break; | ||
| 165 | } | ||
| 166 | |||
| 167 | return 1; | ||
| 168 | } | ||
| 169 | |||
| 170 | static void mainloop(void) | ||
| 171 | { | ||
| 172 | unsigned int count; | ||
| 173 | |||
| 174 | count = frame_count; | ||
| 175 | |||
| 176 | while (count-- > 0) { | ||
| 177 | for (;;) { | ||
| 178 | fd_set fds; | ||
| 179 | struct timeval tv; | ||
| 180 | int r; | ||
| 181 | |||
| 182 | FD_ZERO(&fds); | ||
| 183 | FD_SET(fd, &fds); | ||
| 184 | |||
| 185 | /* Timeout. */ | ||
| 186 | tv.tv_sec = 2; | ||
| 187 | tv.tv_usec = 0; | ||
| 188 | |||
| 189 | r = select(fd + 1, &fds, NULL, NULL, &tv); | ||
| 190 | |||
| 191 | if (-1 == r) { | ||
| 192 | if (EINTR == errno) | ||
| 193 | continue; | ||
| 194 | errno_exit("select"); | ||
| 195 | } | ||
| 196 | |||
| 197 | if (0 == r) { | ||
| 198 | fprintf(stderr, "select timeout\n"); | ||
| 199 | exit(EXIT_FAILURE); | ||
| 200 | } | ||
| 201 | |||
| 202 | if (read_frame()) | ||
| 203 | break; | ||
| 204 | /* EAGAIN - continue select loop. */ | ||
| 205 | } | ||
| 206 | } | ||
| 207 | } | ||
| 208 | |||
| 209 | static void stop_capturing(void) | ||
| 210 | { | ||
| 211 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 212 | |||
| 213 | switch (io) { | ||
| 214 | case IO_METHOD_READ: | ||
| 215 | /* Nothing to do. */ | ||
| 216 | break; | ||
| 217 | |||
| 218 | case IO_METHOD_MMAP: | ||
| 219 | case IO_METHOD_USERPTR: | ||
| 220 | type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 221 | if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type)) | ||
| 222 | errno_exit("VIDIOC_STREAMOFF"); | ||
| 223 | break; | ||
| 224 | } | ||
| 225 | } | ||
| 226 | |||
| 227 | static void start_capturing(void) | ||
| 228 | { | ||
| 229 | unsigned int i; | ||
| 230 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 231 | |||
| 232 | switch (io) { | ||
| 233 | case IO_METHOD_READ: | ||
| 234 | /* Nothing to do. */ | ||
| 235 | break; | ||
| 236 | |||
| 237 | case IO_METHOD_MMAP: | ||
| 238 | for (i = 0; i < n_buffers; ++i) { | ||
| 239 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; | ||
| 240 | |||
| 241 | CLEAR(buf); | ||
| 242 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 243 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 244 | buf.index = i; | ||
| 245 | |||
| 246 | if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) | ||
| 247 | errno_exit("VIDIOC_QBUF"); | ||
| 248 | } | ||
| 249 | type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 250 | if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) | ||
| 251 | errno_exit("VIDIOC_STREAMON"); | ||
| 252 | break; | ||
| 253 | |||
| 254 | case IO_METHOD_USERPTR: | ||
| 255 | for (i = 0; i < n_buffers; ++i) { | ||
| 256 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; | ||
| 257 | |||
| 258 | CLEAR(buf); | ||
| 259 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 260 | buf.memory = V4L2_MEMORY_USERPTR; | ||
| 261 | buf.index = i; | ||
| 262 | buf.m.userptr = (unsigned long)buffers[i].start; | ||
| 263 | buf.length = buffers[i].length; | ||
| 264 | |||
| 265 | if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) | ||
| 266 | errno_exit("VIDIOC_QBUF"); | ||
| 267 | } | ||
| 268 | type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 269 | if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) | ||
| 270 | errno_exit("VIDIOC_STREAMON"); | ||
| 271 | break; | ||
| 272 | } | ||
| 273 | } | ||
| 274 | |||
| 275 | static void uninit_device(void) | ||
| 276 | { | ||
| 277 | unsigned int i; | ||
| 278 | |||
| 279 | switch (io) { | ||
| 280 | case IO_METHOD_READ: | ||
| 281 | free(buffers[0].start); | ||
| 282 | break; | ||
| 283 | |||
| 284 | case IO_METHOD_MMAP: | ||
| 285 | for (i = 0; i < n_buffers; ++i) | ||
| 286 | if (-1 == munmap(buffers[i].start, buffers[i].length)) | ||
| 287 | errno_exit("munmap"); | ||
| 288 | break; | ||
| 289 | |||
| 290 | case IO_METHOD_USERPTR: | ||
| 291 | for (i = 0; i < n_buffers; ++i) | ||
| 292 | free(buffers[i].start); | ||
| 293 | break; | ||
| 294 | } | ||
| 295 | |||
| 296 | free(buffers); | ||
| 297 | } | ||
| 298 | |||
| 299 | static void init_read(unsigned int buffer_size) | ||
| 300 | { | ||
| 301 | buffers = calloc(1, sizeof(*buffers)); | ||
| 302 | |||
| 303 | if (!buffers) { | ||
| 304 | fprintf(stderr, "Out of memory\n"); | ||
| 305 | exit(EXIT_FAILURE); | ||
| 306 | } | ||
| 307 | |||
| 308 | buffers[0].length = buffer_size; | ||
| 309 | buffers[0].start = malloc(buffer_size); | ||
| 310 | |||
| 311 | if (!buffers[0].start) { | ||
| 312 | fprintf(stderr, "Out of memory\n"); | ||
| 313 | exit(EXIT_FAILURE); | ||
| 314 | } | ||
| 315 | } | ||
| 316 | |||
| 317 | static void init_mmap(void) | ||
| 318 | { | ||
| 319 | struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req; | ||
| 320 | |||
| 321 | CLEAR(req); | ||
| 322 | |||
| 323 | req.count = 4; | ||
| 324 | req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 325 | req.memory = V4L2_MEMORY_MMAP; | ||
| 326 | |||
| 327 | if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { | ||
| 328 | if (EINVAL == errno) { | ||
| 329 | fprintf(stderr, "%s does not support " | ||
| 330 | "memory mapping\n", dev_name); | ||
| 331 | exit(EXIT_FAILURE); | ||
| 332 | } else { | ||
| 333 | errno_exit("VIDIOC_REQBUFS"); | ||
| 334 | } | ||
| 335 | } | ||
| 336 | |||
| 337 | if (req.count < 2) { | ||
| 338 | fprintf(stderr, "Insufficient buffer memory on %s\n", | ||
| 339 | dev_name); | ||
| 340 | exit(EXIT_FAILURE); | ||
| 341 | } | ||
| 342 | |||
| 343 | buffers = calloc(req.count, sizeof(*buffers)); | ||
| 344 | |||
| 345 | if (!buffers) { | ||
| 346 | fprintf(stderr, "Out of memory\n"); | ||
| 347 | exit(EXIT_FAILURE); | ||
| 348 | } | ||
| 349 | |||
| 350 | for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { | ||
| 351 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; | ||
| 352 | |||
| 353 | CLEAR(buf); | ||
| 354 | |||
| 355 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 356 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 357 | buf.index = n_buffers; | ||
| 358 | |||
| 359 | if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf)) | ||
| 360 | errno_exit("VIDIOC_QUERYBUF"); | ||
| 361 | |||
| 362 | buffers[n_buffers].length = buf.length; | ||
| 363 | buffers[n_buffers].start = | ||
| 364 | mmap(NULL /* start anywhere */, | ||
| 365 | buf.length, | ||
| 366 | PROT_READ | PROT_WRITE /* required */, | ||
| 367 | MAP_SHARED /* recommended */, | ||
| 368 | fd, buf.m.offset); | ||
| 369 | |||
| 370 | if (MAP_FAILED == buffers[n_buffers].start) | ||
| 371 | errno_exit("mmap"); | ||
| 372 | } | ||
| 373 | } | ||
| 374 | |||
| 375 | static void init_userp(unsigned int buffer_size) | ||
| 376 | { | ||
| 377 | struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req; | ||
| 378 | |||
| 379 | CLEAR(req); | ||
| 380 | |||
| 381 | req.count = 4; | ||
| 382 | req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 383 | req.memory = V4L2_MEMORY_USERPTR; | ||
| 384 | |||
| 385 | if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { | ||
| 386 | if (EINVAL == errno) { | ||
| 387 | fprintf(stderr, "%s does not support " | ||
| 388 | "user pointer i/o\n", dev_name); | ||
| 389 | exit(EXIT_FAILURE); | ||
| 390 | } else { | ||
| 391 | errno_exit("VIDIOC_REQBUFS"); | ||
| 392 | } | ||
| 393 | } | ||
| 394 | |||
| 395 | buffers = calloc(4, sizeof(*buffers)); | ||
| 396 | |||
| 397 | if (!buffers) { | ||
| 398 | fprintf(stderr, "Out of memory\n"); | ||
| 399 | exit(EXIT_FAILURE); | ||
| 400 | } | ||
| 401 | |||
| 402 | for (n_buffers = 0; n_buffers < 4; ++n_buffers) { | ||
| 403 | buffers[n_buffers].length = buffer_size; | ||
| 404 | buffers[n_buffers].start = malloc(buffer_size); | ||
| 405 | |||
| 406 | if (!buffers[n_buffers].start) { | ||
| 407 | fprintf(stderr, "Out of memory\n"); | ||
| 408 | exit(EXIT_FAILURE); | ||
| 409 | } | ||
| 410 | } | ||
| 411 | } | ||
| 412 | |||
| 413 | static void init_device(void) | ||
| 414 | { | ||
| 415 | struct <link linkend="v4l2-capability">v4l2_capability</link> cap; | ||
| 416 | struct <link linkend="v4l2-cropcap">v4l2_cropcap</link> cropcap; | ||
| 417 | struct <link linkend="v4l2-crop">v4l2_crop</link> crop; | ||
| 418 | struct <link linkend="v4l2-format">v4l2_format</link> fmt; | ||
| 419 | unsigned int min; | ||
| 420 | |||
| 421 | if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) { | ||
| 422 | if (EINVAL == errno) { | ||
| 423 | fprintf(stderr, "%s is no V4L2 device\n", | ||
| 424 | dev_name); | ||
| 425 | exit(EXIT_FAILURE); | ||
| 426 | } else { | ||
| 427 | errno_exit("VIDIOC_QUERYCAP"); | ||
| 428 | } | ||
| 429 | } | ||
| 430 | |||
| 431 | if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { | ||
| 432 | fprintf(stderr, "%s is no video capture device\n", | ||
| 433 | dev_name); | ||
| 434 | exit(EXIT_FAILURE); | ||
| 435 | } | ||
| 436 | |||
| 437 | switch (io) { | ||
| 438 | case IO_METHOD_READ: | ||
| 439 | if (!(cap.capabilities & V4L2_CAP_READWRITE)) { | ||
| 440 | fprintf(stderr, "%s does not support read i/o\n", | ||
| 441 | dev_name); | ||
| 442 | exit(EXIT_FAILURE); | ||
| 443 | } | ||
| 444 | break; | ||
| 445 | |||
| 446 | case IO_METHOD_MMAP: | ||
| 447 | case IO_METHOD_USERPTR: | ||
| 448 | if (!(cap.capabilities & V4L2_CAP_STREAMING)) { | ||
| 449 | fprintf(stderr, "%s does not support streaming i/o\n", | ||
| 450 | dev_name); | ||
| 451 | exit(EXIT_FAILURE); | ||
| 452 | } | ||
| 453 | break; | ||
| 454 | } | ||
| 455 | |||
| 456 | |||
| 457 | /* Select video input, video standard and tune here. */ | ||
| 458 | |||
| 459 | |||
| 460 | CLEAR(cropcap); | ||
| 461 | |||
| 462 | cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 463 | |||
| 464 | if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) { | ||
| 465 | crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 466 | crop.c = cropcap.defrect; /* reset to default */ | ||
| 467 | |||
| 468 | if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) { | ||
| 469 | switch (errno) { | ||
| 470 | case EINVAL: | ||
| 471 | /* Cropping not supported. */ | ||
| 472 | break; | ||
| 473 | default: | ||
| 474 | /* Errors ignored. */ | ||
| 475 | break; | ||
| 476 | } | ||
| 477 | } | ||
| 478 | } else { | ||
| 479 | /* Errors ignored. */ | ||
| 480 | } | ||
| 481 | |||
| 482 | |||
| 483 | CLEAR(fmt); | ||
| 484 | |||
| 485 | fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 486 | if (force_format) { | ||
| 487 | fmt.fmt.pix.width = 640; | ||
| 488 | fmt.fmt.pix.height = 480; | ||
| 489 | fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; | ||
| 490 | fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; | ||
| 491 | |||
| 492 | if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt)) | ||
| 493 | errno_exit("VIDIOC_S_FMT"); | ||
| 494 | |||
| 495 | /* Note VIDIOC_S_FMT may change width and height. */ | ||
| 496 | } else { | ||
| 497 | /* Preserve original settings as set by v4l2-ctl for example */ | ||
| 498 | if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt)) | ||
| 499 | errno_exit("VIDIOC_G_FMT"); | ||
| 500 | } | ||
| 501 | |||
| 502 | /* Buggy driver paranoia. */ | ||
| 503 | min = fmt.fmt.pix.width * 2; | ||
| 504 | if (fmt.fmt.pix.bytesperline < min) | ||
| 505 | fmt.fmt.pix.bytesperline = min; | ||
| 506 | min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height; | ||
| 507 | if (fmt.fmt.pix.sizeimage < min) | ||
| 508 | fmt.fmt.pix.sizeimage = min; | ||
| 509 | |||
| 510 | switch (io) { | ||
| 511 | case IO_METHOD_READ: | ||
| 512 | init_read(fmt.fmt.pix.sizeimage); | ||
| 513 | break; | ||
| 514 | |||
| 515 | case IO_METHOD_MMAP: | ||
| 516 | init_mmap(); | ||
| 517 | break; | ||
| 518 | |||
| 519 | case IO_METHOD_USERPTR: | ||
| 520 | init_userp(fmt.fmt.pix.sizeimage); | ||
| 521 | break; | ||
| 522 | } | ||
| 523 | } | ||
| 524 | |||
| 525 | static void close_device(void) | ||
| 526 | { | ||
| 527 | if (-1 == close(fd)) | ||
| 528 | errno_exit("close"); | ||
| 529 | |||
| 530 | fd = -1; | ||
| 531 | } | ||
| 532 | |||
| 533 | static void open_device(void) | ||
| 534 | { | ||
| 535 | struct stat st; | ||
| 536 | |||
| 537 | if (-1 == stat(dev_name, &st)) { | ||
| 538 | fprintf(stderr, "Cannot identify '%s': %d, %s\n", | ||
| 539 | dev_name, errno, strerror(errno)); | ||
| 540 | exit(EXIT_FAILURE); | ||
| 541 | } | ||
| 542 | |||
| 543 | if (!S_ISCHR(st.st_mode)) { | ||
| 544 | fprintf(stderr, "%s is no device\n", dev_name); | ||
| 545 | exit(EXIT_FAILURE); | ||
| 546 | } | ||
| 547 | |||
| 548 | fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0); | ||
| 549 | |||
| 550 | if (-1 == fd) { | ||
| 551 | fprintf(stderr, "Cannot open '%s': %d, %s\n", | ||
| 552 | dev_name, errno, strerror(errno)); | ||
| 553 | exit(EXIT_FAILURE); | ||
| 554 | } | ||
| 555 | } | ||
| 556 | |||
| 557 | static void usage(FILE *fp, int argc, char **argv) | ||
| 558 | { | ||
| 559 | fprintf(fp, | ||
| 560 | "Usage: %s [options]\n\n" | ||
| 561 | "Version 1.3\n" | ||
| 562 | "Options:\n" | ||
| 563 | "-d | --device name Video device name [%s]\n" | ||
| 564 | "-h | --help Print this message\n" | ||
| 565 | "-m | --mmap Use memory mapped buffers [default]\n" | ||
| 566 | "-r | --read Use read() calls\n" | ||
| 567 | "-u | --userp Use application allocated buffers\n" | ||
| 568 | "-o | --output Outputs stream to stdout\n" | ||
| 569 | "-f | --format Force format to 640x480 YUYV\n" | ||
| 570 | "-c | --count Number of frames to grab [%i]\n" | ||
| 571 | "", | ||
| 572 | argv[0], dev_name, frame_count); | ||
| 573 | } | ||
| 574 | |||
| 575 | static const char short_options[] = "d:hmruofc:"; | ||
| 576 | |||
| 577 | static const struct option | ||
| 578 | long_options[] = { | ||
| 579 | { "device", required_argument, NULL, 'd' }, | ||
| 580 | { "help", no_argument, NULL, 'h' }, | ||
| 581 | { "mmap", no_argument, NULL, 'm' }, | ||
| 582 | { "read", no_argument, NULL, 'r' }, | ||
| 583 | { "userp", no_argument, NULL, 'u' }, | ||
| 584 | { "output", no_argument, NULL, 'o' }, | ||
| 585 | { "format", no_argument, NULL, 'f' }, | ||
| 586 | { "count", required_argument, NULL, 'c' }, | ||
| 587 | { 0, 0, 0, 0 } | ||
| 588 | }; | ||
| 589 | |||
| 590 | int main(int argc, char **argv) | ||
| 591 | { | ||
| 592 | dev_name = "/dev/video0"; | ||
| 593 | |||
| 594 | for (;;) { | ||
| 595 | int idx; | ||
| 596 | int c; | ||
| 597 | |||
| 598 | c = getopt_long(argc, argv, | ||
| 599 | short_options, long_options, &idx); | ||
| 600 | |||
| 601 | if (-1 == c) | ||
| 602 | break; | ||
| 603 | |||
| 604 | switch (c) { | ||
| 605 | case 0: /* getopt_long() flag */ | ||
| 606 | break; | ||
| 607 | |||
| 608 | case 'd': | ||
| 609 | dev_name = optarg; | ||
| 610 | break; | ||
| 611 | |||
| 612 | case 'h': | ||
| 613 | usage(stdout, argc, argv); | ||
| 614 | exit(EXIT_SUCCESS); | ||
| 615 | |||
| 616 | case 'm': | ||
| 617 | io = IO_METHOD_MMAP; | ||
| 618 | break; | ||
| 619 | |||
| 620 | case 'r': | ||
| 621 | io = IO_METHOD_READ; | ||
| 622 | break; | ||
| 623 | |||
| 624 | case 'u': | ||
| 625 | io = IO_METHOD_USERPTR; | ||
| 626 | break; | ||
| 627 | |||
| 628 | case 'o': | ||
| 629 | out_buf++; | ||
| 630 | break; | ||
| 631 | |||
| 632 | case 'f': | ||
| 633 | force_format++; | ||
| 634 | break; | ||
| 635 | |||
| 636 | case 'c': | ||
| 637 | errno = 0; | ||
| 638 | frame_count = strtol(optarg, NULL, 0); | ||
| 639 | if (errno) | ||
| 640 | errno_exit(optarg); | ||
| 641 | break; | ||
| 642 | |||
| 643 | default: | ||
| 644 | usage(stderr, argc, argv); | ||
| 645 | exit(EXIT_FAILURE); | ||
| 646 | } | ||
| 647 | } | ||
| 648 | |||
| 649 | open_device(); | ||
| 650 | init_device(); | ||
| 651 | start_capturing(); | ||
| 652 | mainloop(); | ||
| 653 | stop_capturing(); | ||
| 654 | uninit_device(); | ||
| 655 | close_device(); | ||
| 656 | fprintf(stderr, "\n"); | ||
| 657 | return 0; | ||
| 658 | } | ||
| 659 | </programlisting> | ||
diff --git a/Documentation/DocBook/v4l/common.xml b/Documentation/DocBook/v4l/common.xml new file mode 100644 index 000000000000..b1a81d246d58 --- /dev/null +++ b/Documentation/DocBook/v4l/common.xml | |||
| @@ -0,0 +1,1160 @@ | |||
| 1 | <title>Common API Elements</title> | ||
| 2 | |||
| 3 | <para>Programming a V4L2 device consists of these | ||
| 4 | steps:</para> | ||
| 5 | |||
| 6 | <itemizedlist> | ||
| 7 | <listitem> | ||
| 8 | <para>Opening the device</para> | ||
| 9 | </listitem> | ||
| 10 | <listitem> | ||
| 11 | <para>Changing device properties, selecting a video and audio | ||
| 12 | input, video standard, picture brightness a. o.</para> | ||
| 13 | </listitem> | ||
| 14 | <listitem> | ||
| 15 | <para>Negotiating a data format</para> | ||
| 16 | </listitem> | ||
| 17 | <listitem> | ||
| 18 | <para>Negotiating an input/output method</para> | ||
| 19 | </listitem> | ||
| 20 | <listitem> | ||
| 21 | <para>The actual input/output loop</para> | ||
| 22 | </listitem> | ||
| 23 | <listitem> | ||
| 24 | <para>Closing the device</para> | ||
| 25 | </listitem> | ||
| 26 | </itemizedlist> | ||
| 27 | |||
| 28 | <para>In practice most steps are optional and can be executed out of | ||
| 29 | order. It depends on the V4L2 device type, you can read about the | ||
| 30 | details in <xref linkend="devices" />. In this chapter we will discuss | ||
| 31 | the basic concepts applicable to all devices.</para> | ||
| 32 | |||
| 33 | <section id="open"> | ||
| 34 | <title>Opening and Closing Devices</title> | ||
| 35 | |||
| 36 | <section> | ||
| 37 | <title>Device Naming</title> | ||
| 38 | |||
| 39 | <para>V4L2 drivers are implemented as kernel modules, loaded | ||
| 40 | manually by the system administrator or automatically when a device is | ||
| 41 | first opened. The driver modules plug into the "videodev" kernel | ||
| 42 | module. It provides helper functions and a common application | ||
| 43 | interface specified in this document.</para> | ||
| 44 | |||
| 45 | <para>Each driver thus loaded registers one or more device nodes | ||
| 46 | with major number 81 and a minor number between 0 and 255. Assigning | ||
| 47 | minor numbers to V4L2 devices is entirely up to the system administrator, | ||
| 48 | this is primarily intended to solve conflicts between devices.<footnote> | ||
| 49 | <para>Access permissions are associated with character | ||
| 50 | device special files, hence we must ensure device numbers cannot | ||
| 51 | change with the module load order. To this end minor numbers are no | ||
| 52 | longer automatically assigned by the "videodev" module as in V4L but | ||
| 53 | requested by the driver. The defaults will suffice for most people | ||
| 54 | unless two drivers compete for the same minor numbers.</para> | ||
| 55 | </footnote> The module options to select minor numbers are named | ||
| 56 | after the device special file with a "_nr" suffix. For example "video_nr" | ||
| 57 | for <filename>/dev/video</filename> video capture devices. The number is | ||
| 58 | an offset to the base minor number associated with the device type. | ||
| 59 | <footnote> | ||
| 60 | <para>In earlier versions of the V4L2 API the module options | ||
| 61 | where named after the device special file with a "unit_" prefix, expressing | ||
| 62 | the minor number itself, not an offset. Rationale for this change is unknown. | ||
| 63 | Lastly the naming and semantics are just a convention among driver writers, | ||
| 64 | the point to note is that minor numbers are not supposed to be hardcoded | ||
| 65 | into drivers.</para> | ||
| 66 | </footnote> When the driver supports multiple devices of the same | ||
| 67 | type more than one minor number can be assigned, separated by commas: | ||
| 68 | <informalexample> | ||
| 69 | <screen> | ||
| 70 | > insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen> | ||
| 71 | </informalexample></para> | ||
| 72 | |||
| 73 | <para>In <filename>/etc/modules.conf</filename> this may be | ||
| 74 | written as: <informalexample> | ||
| 75 | <screen> | ||
| 76 | alias char-major-81-0 mydriver | ||
| 77 | alias char-major-81-1 mydriver | ||
| 78 | alias char-major-81-64 mydriver <co id="alias" /> | ||
| 79 | options mydriver video_nr=0,1 radio_nr=0,1 <co id="options" /> | ||
| 80 | </screen> | ||
| 81 | <calloutlist> | ||
| 82 | <callout arearefs="alias"> | ||
| 83 | <para>When an application attempts to open a device | ||
| 84 | special file with major number 81 and minor number 0, 1, or 64, load | ||
| 85 | "mydriver" (and the "videodev" module it depends upon).</para> | ||
| 86 | </callout> | ||
| 87 | <callout arearefs="options"> | ||
| 88 | <para>Register the first two video capture devices with | ||
| 89 | minor number 0 and 1 (base number is 0), the first two radio device | ||
| 90 | with minor number 64 and 65 (base 64).</para> | ||
| 91 | </callout> | ||
| 92 | </calloutlist> | ||
| 93 | </informalexample> When no minor number is given as module | ||
| 94 | option the driver supplies a default. <xref linkend="devices" /> | ||
| 95 | recommends the base minor numbers to be used for the various device | ||
| 96 | types. Obviously minor numbers must be unique. When the number is | ||
| 97 | already in use the <emphasis>offending device</emphasis> will not be | ||
| 98 | registered. <!-- Blessed by Linus Torvalds on | ||
| 99 | linux-kernel@vger.kernel.org, 2002-11-20. --></para> | ||
| 100 | |||
| 101 | <para>By convention system administrators create various | ||
| 102 | character device special files with these major and minor numbers in | ||
| 103 | the <filename>/dev</filename> directory. The names recomended for the | ||
| 104 | different V4L2 device types are listed in <xref linkend="devices" />. | ||
| 105 | </para> | ||
| 106 | |||
| 107 | <para>The creation of character special files (with | ||
| 108 | <application>mknod</application>) is a privileged operation and | ||
| 109 | devices cannot be opened by major and minor number. That means | ||
| 110 | applications cannot <emphasis>reliable</emphasis> scan for loaded or | ||
| 111 | installed drivers. The user must enter a device name, or the | ||
| 112 | application can try the conventional device names.</para> | ||
| 113 | |||
| 114 | <para>Under the device filesystem (devfs) the minor number | ||
| 115 | options are ignored. V4L2 drivers (or by proxy the "videodev" module) | ||
| 116 | automatically create the required device files in the | ||
| 117 | <filename>/dev/v4l</filename> directory using the conventional device | ||
| 118 | names above.</para> | ||
| 119 | </section> | ||
| 120 | |||
| 121 | <section id="related"> | ||
| 122 | <title>Related Devices</title> | ||
| 123 | |||
| 124 | <para>Devices can support several related functions. For example | ||
| 125 | video capturing, video overlay and VBI capturing are related because | ||
| 126 | these functions share, amongst other, the same video input and tuner | ||
| 127 | frequency. V4L and earlier versions of V4L2 used the same device name | ||
| 128 | and minor number for video capturing and overlay, but different ones | ||
| 129 | for VBI. Experience showed this approach has several problems<footnote> | ||
| 130 | <para>Given a device file name one cannot reliable find | ||
| 131 | related devices. For once names are arbitrary and in a system with | ||
| 132 | multiple devices, where only some support VBI capturing, a | ||
| 133 | <filename>/dev/video2</filename> is not necessarily related to | ||
| 134 | <filename>/dev/vbi2</filename>. The V4L | ||
| 135 | <constant>VIDIOCGUNIT</constant> ioctl would require a search for a | ||
| 136 | device file with a particular major and minor number.</para> | ||
| 137 | </footnote>, and to make things worse the V4L videodev module | ||
| 138 | used to prohibit multiple opens of a device.</para> | ||
| 139 | |||
| 140 | <para>As a remedy the present version of the V4L2 API relaxed the | ||
| 141 | concept of device types with specific names and minor numbers. For | ||
| 142 | compatibility with old applications drivers must still register different | ||
| 143 | minor numbers to assign a default function to the device. But if related | ||
| 144 | functions are supported by the driver they must be available under all | ||
| 145 | registered minor numbers. The desired function can be selected after | ||
| 146 | opening the device as described in <xref linkend="devices" />.</para> | ||
| 147 | |||
| 148 | <para>Imagine a driver supporting video capturing, video | ||
| 149 | overlay, raw VBI capturing, and FM radio reception. It registers three | ||
| 150 | devices with minor number 0, 64 and 224 (this numbering scheme is | ||
| 151 | inherited from the V4L API). Regardless if | ||
| 152 | <filename>/dev/video</filename> (81, 0) or | ||
| 153 | <filename>/dev/vbi</filename> (81, 224) is opened the application can | ||
| 154 | select any one of the video capturing, overlay or VBI capturing | ||
| 155 | functions. Without programming (e. g. reading from the device | ||
| 156 | with <application>dd</application> or <application>cat</application>) | ||
| 157 | <filename>/dev/video</filename> captures video images, while | ||
| 158 | <filename>/dev/vbi</filename> captures raw VBI data. | ||
| 159 | <filename>/dev/radio</filename> (81, 64) is invariable a radio device, | ||
| 160 | unrelated to the video functions. Being unrelated does not imply the | ||
| 161 | devices can be used at the same time, however. The &func-open; | ||
| 162 | function may very well return an &EBUSY;.</para> | ||
| 163 | |||
| 164 | <para>Besides video input or output the hardware may also | ||
| 165 | support audio sampling or playback. If so, these functions are | ||
| 166 | implemented as OSS or ALSA PCM devices and eventually OSS or ALSA | ||
| 167 | audio mixer. The V4L2 API makes no provisions yet to find these | ||
| 168 | related devices. If you have an idea please write to the linux-media | ||
| 169 | mailing list: &v4l-ml;.</para> | ||
| 170 | </section> | ||
| 171 | |||
| 172 | <section> | ||
| 173 | <title>Multiple Opens</title> | ||
| 174 | |||
| 175 | <para>In general, V4L2 devices can be opened more than once. | ||
| 176 | When this is supported by the driver, users can for example start a | ||
| 177 | "panel" application to change controls like brightness or audio | ||
| 178 | volume, while another application captures video and audio. In other words, panel | ||
| 179 | applications are comparable to an OSS or ALSA audio mixer application. | ||
| 180 | When a device supports multiple functions like capturing and overlay | ||
| 181 | <emphasis>simultaneously</emphasis>, multiple opens allow concurrent | ||
| 182 | use of the device by forked processes or specialized applications.</para> | ||
| 183 | |||
| 184 | <para>Multiple opens are optional, although drivers should | ||
| 185 | permit at least concurrent accesses without data exchange, &ie; panel | ||
| 186 | applications. This implies &func-open; can return an &EBUSY; when the | ||
| 187 | device is already in use, as well as &func-ioctl; functions initiating | ||
| 188 | data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read; | ||
| 189 | and &func-write; functions.</para> | ||
| 190 | |||
| 191 | <para>Mere opening a V4L2 device does not grant exclusive | ||
| 192 | access.<footnote> | ||
| 193 | <para>Drivers could recognize the | ||
| 194 | <constant>O_EXCL</constant> open flag. Presently this is not required, | ||
| 195 | so applications cannot know if it really works.</para> | ||
| 196 | </footnote> Initiating data exchange however assigns the right | ||
| 197 | to read or write the requested type of data, and to change related | ||
| 198 | properties, to this file descriptor. Applications can request | ||
| 199 | additional access privileges using the priority mechanism described in | ||
| 200 | <xref linkend="app-pri" />.</para> | ||
| 201 | </section> | ||
| 202 | |||
| 203 | <section> | ||
| 204 | <title>Shared Data Streams</title> | ||
| 205 | |||
| 206 | <para>V4L2 drivers should not support multiple applications | ||
| 207 | reading or writing the same data stream on a device by copying | ||
| 208 | buffers, time multiplexing or similar means. This is better handled by | ||
| 209 | a proxy application in user space. When the driver supports stream | ||
| 210 | sharing anyway it must be implemented transparently. The V4L2 API does | ||
| 211 | not specify how conflicts are solved. <!-- For example O_EXCL when the | ||
| 212 | application does not want to be preempted, PROT_READ mmapped buffers | ||
| 213 | which can be mapped twice, what happens when image formats do not | ||
| 214 | match etc.--></para> | ||
| 215 | </section> | ||
| 216 | |||
| 217 | <section> | ||
| 218 | <title>Functions</title> | ||
| 219 | |||
| 220 | <para>To open and close V4L2 devices applications use the | ||
| 221 | &func-open; and &func-close; function, respectively. Devices are | ||
| 222 | programmed using the &func-ioctl; function as explained in the | ||
| 223 | following sections.</para> | ||
| 224 | </section> | ||
| 225 | </section> | ||
| 226 | |||
| 227 | <section id="querycap"> | ||
| 228 | <title>Querying Capabilities</title> | ||
| 229 | |||
| 230 | <para>Because V4L2 covers a wide variety of devices not all | ||
| 231 | aspects of the API are equally applicable to all types of devices. | ||
| 232 | Furthermore devices of the same type have different capabilities and | ||
| 233 | this specification permits the omission of a few complicated and less | ||
| 234 | important parts of the API.</para> | ||
| 235 | |||
| 236 | <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel | ||
| 237 | device is compatible with this specification, and to query the <link | ||
| 238 | linkend="devices">functions</link> and <link linkend="io">I/O | ||
| 239 | methods</link> supported by the device. Other features can be queried | ||
| 240 | by calling the respective ioctl, for example &VIDIOC-ENUMINPUT; | ||
| 241 | to learn about the number, types and names of video connectors on the | ||
| 242 | device. Although abstraction is a major objective of this API, the | ||
| 243 | ioctl also allows driver specific applications to reliable identify | ||
| 244 | the driver.</para> | ||
| 245 | |||
| 246 | <para>All V4L2 drivers must support | ||
| 247 | <constant>VIDIOC_QUERYCAP</constant>. Applications should always call | ||
| 248 | this ioctl after opening the device.</para> | ||
| 249 | </section> | ||
| 250 | |||
| 251 | <section id="app-pri"> | ||
| 252 | <title>Application Priority</title> | ||
| 253 | |||
| 254 | <para>When multiple applications share a device it may be | ||
| 255 | desirable to assign them different priorities. Contrary to the | ||
| 256 | traditional "rm -rf /" school of thought a video recording application | ||
| 257 | could for example block other applications from changing video | ||
| 258 | controls or switching the current TV channel. Another objective is to | ||
| 259 | permit low priority applications working in background, which can be | ||
| 260 | preempted by user controlled applications and automatically regain | ||
| 261 | control of the device at a later time.</para> | ||
| 262 | |||
| 263 | <para>Since these features cannot be implemented entirely in user | ||
| 264 | space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY; | ||
| 265 | ioctls to request and query the access priority associate with a file | ||
| 266 | descriptor. Opening a device assigns a medium priority, compatible | ||
| 267 | with earlier versions of V4L2 and drivers not supporting these ioctls. | ||
| 268 | Applications requiring a different priority will usually call | ||
| 269 | <constant>VIDIOC_S_PRIORITY</constant> after verifying the device with | ||
| 270 | the &VIDIOC-QUERYCAP; ioctl.</para> | ||
| 271 | |||
| 272 | <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;, | ||
| 273 | return an &EBUSY; after another application obtained higher priority. | ||
| 274 | An event mechanism to notify applications about asynchronous property | ||
| 275 | changes has been proposed but not added yet.</para> | ||
| 276 | </section> | ||
| 277 | |||
| 278 | <section id="video"> | ||
| 279 | <title>Video Inputs and Outputs</title> | ||
| 280 | |||
| 281 | <para>Video inputs and outputs are physical connectors of a | ||
| 282 | device. These can be for example RF connectors (antenna/cable), CVBS | ||
| 283 | a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI | ||
| 284 | capture devices have inputs, output devices have outputs, at least one | ||
| 285 | each. Radio devices have no video inputs or outputs.</para> | ||
| 286 | |||
| 287 | <para>To learn about the number and attributes of the | ||
| 288 | available inputs and outputs applications can enumerate them with the | ||
| 289 | &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The | ||
| 290 | &v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant> | ||
| 291 | ioctl also contains signal status information applicable when the | ||
| 292 | current video input is queried.</para> | ||
| 293 | |||
| 294 | <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the | ||
| 295 | index of the current video input or output. To select a different | ||
| 296 | input or output applications call the &VIDIOC-S-INPUT; and | ||
| 297 | &VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls | ||
| 298 | when the device has one or more inputs, all the output ioctls when the | ||
| 299 | device has one or more outputs.</para> | ||
| 300 | |||
| 301 | <!-- | ||
| 302 | <figure id=io-tree> | ||
| 303 | <title>Input and output enumeration is the root of most device properties.</title> | ||
| 304 | <mediaobject> | ||
| 305 | <imageobject> | ||
| 306 | <imagedata fileref="links.pdf" format="ps" /> | ||
| 307 | </imageobject> | ||
| 308 | <imageobject> | ||
| 309 | <imagedata fileref="links.gif" format="gif" /> | ||
| 310 | </imageobject> | ||
| 311 | <textobject> | ||
| 312 | <phrase>Links between various device property structures.</phrase> | ||
| 313 | </textobject> | ||
| 314 | </mediaobject> | ||
| 315 | </figure> | ||
| 316 | --> | ||
| 317 | |||
| 318 | <example> | ||
| 319 | <title>Information about the current video input</title> | ||
| 320 | |||
| 321 | <programlisting> | ||
| 322 | &v4l2-input; input; | ||
| 323 | int index; | ||
| 324 | |||
| 325 | if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &index)) { | ||
| 326 | perror ("VIDIOC_G_INPUT"); | ||
| 327 | exit (EXIT_FAILURE); | ||
| 328 | } | ||
| 329 | |||
| 330 | memset (&input, 0, sizeof (input)); | ||
| 331 | input.index = index; | ||
| 332 | |||
| 333 | if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { | ||
| 334 | perror ("VIDIOC_ENUMINPUT"); | ||
| 335 | exit (EXIT_FAILURE); | ||
| 336 | } | ||
| 337 | |||
| 338 | printf ("Current input: %s\n", input.name); | ||
| 339 | </programlisting> | ||
| 340 | </example> | ||
| 341 | |||
| 342 | <example> | ||
| 343 | <title>Switching to the first video input</title> | ||
| 344 | |||
| 345 | <programlisting> | ||
| 346 | int index; | ||
| 347 | |||
| 348 | index = 0; | ||
| 349 | |||
| 350 | if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &index)) { | ||
| 351 | perror ("VIDIOC_S_INPUT"); | ||
| 352 | exit (EXIT_FAILURE); | ||
| 353 | } | ||
| 354 | </programlisting> | ||
| 355 | </example> | ||
| 356 | </section> | ||
| 357 | |||
| 358 | <section id="audio"> | ||
| 359 | <title>Audio Inputs and Outputs</title> | ||
| 360 | |||
| 361 | <para>Audio inputs and outputs are physical connectors of a | ||
| 362 | device. Video capture devices have inputs, output devices have | ||
| 363 | outputs, zero or more each. Radio devices have no audio inputs or | ||
| 364 | outputs. They have exactly one tuner which in fact | ||
| 365 | <emphasis>is</emphasis> an audio source, but this API associates | ||
| 366 | tuners with video inputs or outputs only, and radio devices have | ||
| 367 | none of these.<footnote> | ||
| 368 | <para>Actually &v4l2-audio; ought to have a | ||
| 369 | <structfield>tuner</structfield> field like &v4l2-input;, not only | ||
| 370 | making the API more consistent but also permitting radio devices with | ||
| 371 | multiple tuners.</para> | ||
| 372 | </footnote> A connector on a TV card to loop back the received | ||
| 373 | audio signal to a sound card is not considered an audio output.</para> | ||
| 374 | |||
| 375 | <para>Audio and video inputs and outputs are associated. Selecting | ||
| 376 | a video source also selects an audio source. This is most evident when | ||
| 377 | the video and audio source is a tuner. Further audio connectors can | ||
| 378 | combine with more than one video input or output. Assumed two | ||
| 379 | composite video inputs and two audio inputs exist, there may be up to | ||
| 380 | four valid combinations. The relation of video and audio connectors | ||
| 381 | is defined in the <structfield>audioset</structfield> field of the | ||
| 382 | respective &v4l2-input; or &v4l2-output;, where each bit represents | ||
| 383 | the index number, starting at zero, of one audio input or output.</para> | ||
| 384 | |||
| 385 | <para>To learn about the number and attributes of the | ||
| 386 | available inputs and outputs applications can enumerate them with the | ||
| 387 | &VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The | ||
| 388 | &v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl | ||
| 389 | also contains signal status information applicable when the current | ||
| 390 | audio input is queried.</para> | ||
| 391 | |||
| 392 | <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report | ||
| 393 | the current audio input and output, respectively. Note that, unlike | ||
| 394 | &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure | ||
| 395 | as <constant>VIDIOC_ENUMAUDIO</constant> and | ||
| 396 | <constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para> | ||
| 397 | |||
| 398 | <para>To select an audio input and change its properties | ||
| 399 | applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio | ||
| 400 | output (which presently has no changeable properties) applications | ||
| 401 | call the &VIDIOC-S-AUDOUT; ioctl.</para> | ||
| 402 | |||
| 403 | <para>Drivers must implement all input ioctls when the device | ||
| 404 | has one or more inputs, all output ioctls when the device has one | ||
| 405 | or more outputs. When the device has any audio inputs or outputs the | ||
| 406 | driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the | ||
| 407 | &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para> | ||
| 408 | |||
| 409 | <example> | ||
| 410 | <title>Information about the current audio input</title> | ||
| 411 | |||
| 412 | <programlisting> | ||
| 413 | &v4l2-audio; audio; | ||
| 414 | |||
| 415 | memset (&audio, 0, sizeof (audio)); | ||
| 416 | |||
| 417 | if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &audio)) { | ||
| 418 | perror ("VIDIOC_G_AUDIO"); | ||
| 419 | exit (EXIT_FAILURE); | ||
| 420 | } | ||
| 421 | |||
| 422 | printf ("Current input: %s\n", audio.name); | ||
| 423 | </programlisting> | ||
| 424 | </example> | ||
| 425 | |||
| 426 | <example> | ||
| 427 | <title>Switching to the first audio input</title> | ||
| 428 | |||
| 429 | <programlisting> | ||
| 430 | &v4l2-audio; audio; | ||
| 431 | |||
| 432 | memset (&audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */ | ||
| 433 | |||
| 434 | audio.index = 0; | ||
| 435 | |||
| 436 | if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &audio)) { | ||
| 437 | perror ("VIDIOC_S_AUDIO"); | ||
| 438 | exit (EXIT_FAILURE); | ||
| 439 | } | ||
| 440 | </programlisting> | ||
| 441 | </example> | ||
| 442 | </section> | ||
| 443 | |||
| 444 | <section id="tuner"> | ||
| 445 | <title>Tuners and Modulators</title> | ||
| 446 | |||
| 447 | <section> | ||
| 448 | <title>Tuners</title> | ||
| 449 | |||
| 450 | <para>Video input devices can have one or more tuners | ||
| 451 | demodulating a RF signal. Each tuner is associated with one or more | ||
| 452 | video inputs, depending on the number of RF connectors on the tuner. | ||
| 453 | The <structfield>type</structfield> field of the respective | ||
| 454 | &v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to | ||
| 455 | <constant>V4L2_INPUT_TYPE_TUNER</constant> and its | ||
| 456 | <structfield>tuner</structfield> field contains the index number of | ||
| 457 | the tuner.</para> | ||
| 458 | |||
| 459 | <para>Radio devices have exactly one tuner with index zero, no | ||
| 460 | video inputs.</para> | ||
| 461 | |||
| 462 | <para>To query and change tuner properties applications use the | ||
| 463 | &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The | ||
| 464 | &v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also | ||
| 465 | contains signal status information applicable when the tuner of the | ||
| 466 | current video input, or a radio tuner is queried. Note that | ||
| 467 | <constant>VIDIOC_S_TUNER</constant> does not switch the current tuner, | ||
| 468 | when there is more than one at all. The tuner is solely determined by | ||
| 469 | the current video input. Drivers must support both ioctls and set the | ||
| 470 | <constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability; | ||
| 471 | returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or | ||
| 472 | more tuners.</para> | ||
| 473 | </section> | ||
| 474 | |||
| 475 | <section> | ||
| 476 | <title>Modulators</title> | ||
| 477 | |||
| 478 | <para>Video output devices can have one or more modulators, uh, | ||
| 479 | modulating a video signal for radiation or connection to the antenna | ||
| 480 | input of a TV set or video recorder. Each modulator is associated with | ||
| 481 | one or more video outputs, depending on the number of RF connectors on | ||
| 482 | the modulator. The <structfield>type</structfield> field of the | ||
| 483 | respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is | ||
| 484 | set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its | ||
| 485 | <structfield>modulator</structfield> field contains the index number | ||
| 486 | of the modulator. This specification does not define radio output | ||
| 487 | devices.</para> | ||
| 488 | |||
| 489 | <para>To query and change modulator properties applications use | ||
| 490 | the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that | ||
| 491 | <constant>VIDIOC_S_MODULATOR</constant> does not switch the current | ||
| 492 | modulator, when there is more than one at all. The modulator is solely | ||
| 493 | determined by the current video output. Drivers must support both | ||
| 494 | ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in | ||
| 495 | the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the | ||
| 496 | device has one or more modulators.</para> | ||
| 497 | </section> | ||
| 498 | |||
| 499 | <section> | ||
| 500 | <title>Radio Frequency</title> | ||
| 501 | |||
| 502 | <para>To get and set the tuner or modulator radio frequency | ||
| 503 | applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY; | ||
| 504 | ioctl which both take a pointer to a &v4l2-frequency;. These ioctls | ||
| 505 | are used for TV and radio devices alike. Drivers must support both | ||
| 506 | ioctls when the tuner or modulator ioctls are supported, or | ||
| 507 | when the device is a radio device.</para> | ||
| 508 | </section> | ||
| 509 | </section> | ||
| 510 | |||
| 511 | <section id="standard"> | ||
| 512 | <title>Video Standards</title> | ||
| 513 | |||
| 514 | <para>Video devices typically support one or more different video | ||
| 515 | standards or variations of standards. Each video input and output may | ||
| 516 | support another set of standards. This set is reported by the | ||
| 517 | <structfield>std</structfield> field of &v4l2-input; and | ||
| 518 | &v4l2-output; returned by the &VIDIOC-ENUMINPUT; and | ||
| 519 | &VIDIOC-ENUMOUTPUT; ioctl, respectively.</para> | ||
| 520 | |||
| 521 | <para>V4L2 defines one bit for each analog video standard | ||
| 522 | currently in use worldwide, and sets aside bits for driver defined | ||
| 523 | standards, ⪚ hybrid standards to watch NTSC video tapes on PAL TVs | ||
| 524 | and vice versa. Applications can use the predefined bits to select a | ||
| 525 | particular standard, although presenting the user a menu of supported | ||
| 526 | standards is preferred. To enumerate and query the attributes of the | ||
| 527 | supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para> | ||
| 528 | |||
| 529 | <para>Many of the defined standards are actually just variations | ||
| 530 | of a few major standards. The hardware may in fact not distinguish | ||
| 531 | between them, or do so internal and switch automatically. Therefore | ||
| 532 | enumerated standards also contain sets of one or more standard | ||
| 533 | bits.</para> | ||
| 534 | |||
| 535 | <para>Assume a hypothetic tuner capable of demodulating B/PAL, | ||
| 536 | G/PAL and I/PAL signals. The first enumerated standard is a set of B | ||
| 537 | and G/PAL, switched automatically depending on the selected radio | ||
| 538 | frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I" | ||
| 539 | choice. Similar a Composite input may collapse standards, enumerating | ||
| 540 | "PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote> | ||
| 541 | <para>Some users are already confused by technical terms PAL, | ||
| 542 | NTSC and SECAM. There is no point asking them to distinguish between | ||
| 543 | B, G, D, or K when the software or hardware can do that | ||
| 544 | automatically.</para> | ||
| 545 | </footnote></para> | ||
| 546 | |||
| 547 | <para>To query and select the standard used by the current video | ||
| 548 | input or output applications call the &VIDIOC-G-STD; and | ||
| 549 | &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis> | ||
| 550 | standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote> | ||
| 551 | <para>An alternative to the current scheme is to use pointers | ||
| 552 | to indices as arguments of <constant>VIDIOC_G_STD</constant> and | ||
| 553 | <constant>VIDIOC_S_STD</constant>, the &v4l2-input; and | ||
| 554 | &v4l2-output; <structfield>std</structfield> field would be a set of | ||
| 555 | indices like <structfield>audioset</structfield>.</para> | ||
| 556 | <para>Indices are consistent with the rest of the API | ||
| 557 | and identify the standard unambiguously. In the present scheme of | ||
| 558 | things an enumerated standard is looked up by &v4l2-std-id;. Now the | ||
| 559 | standards supported by the inputs of a device can overlap. Just | ||
| 560 | assume the tuner and composite input in the example above both | ||
| 561 | exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests | ||
| 562 | a choice which does not exist. We cannot merge or omit sets, because | ||
| 563 | applications would be unable to find the standards reported by | ||
| 564 | <constant>VIDIOC_G_STD</constant>. That leaves separate enumerations | ||
| 565 | for each input. Also selecting a standard by &v4l2-std-id; can be | ||
| 566 | ambiguous. Advantage of this method is that applications need not | ||
| 567 | identify the standard indirectly, after enumerating.</para><para>So in | ||
| 568 | summary, the lookup itself is unavoidable. The difference is only | ||
| 569 | whether the lookup is necessary to find an enumerated standard or to | ||
| 570 | switch to a standard by &v4l2-std-id;.</para> | ||
| 571 | </footnote> Drivers must implement all video standard ioctls | ||
| 572 | when the device has one or more video inputs or outputs.</para> | ||
| 573 | |||
| 574 | <para>Special rules apply to USB cameras where the notion of video | ||
| 575 | standards makes little sense. More generally any capture device, | ||
| 576 | output devices accordingly, which is <itemizedlist> | ||
| 577 | <listitem> | ||
| 578 | <para>incapable of capturing fields or frames at the nominal | ||
| 579 | rate of the video standard, or</para> | ||
| 580 | </listitem> | ||
| 581 | <listitem> | ||
| 582 | <para>where <link linkend="buffer">timestamps</link> refer | ||
| 583 | to the instant the field or frame was received by the driver, not the | ||
| 584 | capture time, or</para> | ||
| 585 | </listitem> | ||
| 586 | <listitem> | ||
| 587 | <para>where <link linkend="buffer">sequence numbers</link> | ||
| 588 | refer to the frames received by the driver, not the captured | ||
| 589 | frames.</para> | ||
| 590 | </listitem> | ||
| 591 | </itemizedlist> Here the driver shall set the | ||
| 592 | <structfield>std</structfield> field of &v4l2-input; and &v4l2-output; | ||
| 593 | to zero, the <constant>VIDIOC_G_STD</constant>, | ||
| 594 | <constant>VIDIOC_S_STD</constant>, | ||
| 595 | <constant>VIDIOC_QUERYSTD</constant> and | ||
| 596 | <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the | ||
| 597 | &EINVAL;.<footnote> | ||
| 598 | <para>See <xref linkend="buffer" /> for a rationale. Probably | ||
| 599 | even USB cameras follow some well known video standard. It might have | ||
| 600 | been better to explicitly indicate elsewhere if a device cannot live | ||
| 601 | up to normal expectations, instead of this exception.</para> | ||
| 602 | </footnote></para> | ||
| 603 | |||
| 604 | <example> | ||
| 605 | <title>Information about the current video standard</title> | ||
| 606 | |||
| 607 | <programlisting> | ||
| 608 | &v4l2-std-id; std_id; | ||
| 609 | &v4l2-standard; standard; | ||
| 610 | |||
| 611 | if (-1 == ioctl (fd, &VIDIOC-G-STD;, &std_id)) { | ||
| 612 | /* Note when VIDIOC_ENUMSTD always returns EINVAL this | ||
| 613 | is no video device or it falls under the USB exception, | ||
| 614 | and VIDIOC_G_STD returning EINVAL is no error. */ | ||
| 615 | |||
| 616 | perror ("VIDIOC_G_STD"); | ||
| 617 | exit (EXIT_FAILURE); | ||
| 618 | } | ||
| 619 | |||
| 620 | memset (&standard, 0, sizeof (standard)); | ||
| 621 | standard.index = 0; | ||
| 622 | |||
| 623 | while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) { | ||
| 624 | if (standard.id & std_id) { | ||
| 625 | printf ("Current video standard: %s\n", standard.name); | ||
| 626 | exit (EXIT_SUCCESS); | ||
| 627 | } | ||
| 628 | |||
| 629 | standard.index++; | ||
| 630 | } | ||
| 631 | |||
| 632 | /* EINVAL indicates the end of the enumeration, which cannot be | ||
| 633 | empty unless this device falls under the USB exception. */ | ||
| 634 | |||
| 635 | if (errno == EINVAL || standard.index == 0) { | ||
| 636 | perror ("VIDIOC_ENUMSTD"); | ||
| 637 | exit (EXIT_FAILURE); | ||
| 638 | } | ||
| 639 | </programlisting> | ||
| 640 | </example> | ||
| 641 | |||
| 642 | <example> | ||
| 643 | <title>Listing the video standards supported by the current | ||
| 644 | input</title> | ||
| 645 | |||
| 646 | <programlisting> | ||
| 647 | &v4l2-input; input; | ||
| 648 | &v4l2-standard; standard; | ||
| 649 | |||
| 650 | memset (&input, 0, sizeof (input)); | ||
| 651 | |||
| 652 | if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &input.index)) { | ||
| 653 | perror ("VIDIOC_G_INPUT"); | ||
| 654 | exit (EXIT_FAILURE); | ||
| 655 | } | ||
| 656 | |||
| 657 | if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { | ||
| 658 | perror ("VIDIOC_ENUM_INPUT"); | ||
| 659 | exit (EXIT_FAILURE); | ||
| 660 | } | ||
| 661 | |||
| 662 | printf ("Current input %s supports:\n", input.name); | ||
| 663 | |||
| 664 | memset (&standard, 0, sizeof (standard)); | ||
| 665 | standard.index = 0; | ||
| 666 | |||
| 667 | while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) { | ||
| 668 | if (standard.id & input.std) | ||
| 669 | printf ("%s\n", standard.name); | ||
| 670 | |||
| 671 | standard.index++; | ||
| 672 | } | ||
| 673 | |||
| 674 | /* EINVAL indicates the end of the enumeration, which cannot be | ||
| 675 | empty unless this device falls under the USB exception. */ | ||
| 676 | |||
| 677 | if (errno != EINVAL || standard.index == 0) { | ||
| 678 | perror ("VIDIOC_ENUMSTD"); | ||
| 679 | exit (EXIT_FAILURE); | ||
| 680 | } | ||
| 681 | </programlisting> | ||
| 682 | </example> | ||
| 683 | |||
| 684 | <example> | ||
| 685 | <title>Selecting a new video standard</title> | ||
| 686 | |||
| 687 | <programlisting> | ||
| 688 | &v4l2-input; input; | ||
| 689 | &v4l2-std-id; std_id; | ||
| 690 | |||
| 691 | memset (&input, 0, sizeof (input)); | ||
| 692 | |||
| 693 | if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &input.index)) { | ||
| 694 | perror ("VIDIOC_G_INPUT"); | ||
| 695 | exit (EXIT_FAILURE); | ||
| 696 | } | ||
| 697 | |||
| 698 | if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) { | ||
| 699 | perror ("VIDIOC_ENUM_INPUT"); | ||
| 700 | exit (EXIT_FAILURE); | ||
| 701 | } | ||
| 702 | |||
| 703 | if (0 == (input.std & V4L2_STD_PAL_BG)) { | ||
| 704 | fprintf (stderr, "Oops. B/G PAL is not supported.\n"); | ||
| 705 | exit (EXIT_FAILURE); | ||
| 706 | } | ||
| 707 | |||
| 708 | /* Note this is also supposed to work when only B | ||
| 709 | <emphasis>or</emphasis> G/PAL is supported. */ | ||
| 710 | |||
| 711 | std_id = V4L2_STD_PAL_BG; | ||
| 712 | |||
| 713 | if (-1 == ioctl (fd, &VIDIOC-S-STD;, &std_id)) { | ||
| 714 | perror ("VIDIOC_S_STD"); | ||
| 715 | exit (EXIT_FAILURE); | ||
| 716 | } | ||
| 717 | </programlisting> | ||
| 718 | </example> | ||
| 719 | </section> | ||
| 720 | |||
| 721 | &sub-controls; | ||
| 722 | |||
| 723 | <section id="format"> | ||
| 724 | <title>Data Formats</title> | ||
| 725 | |||
| 726 | <section> | ||
| 727 | <title>Data Format Negotiation</title> | ||
| 728 | |||
| 729 | <para>Different devices exchange different kinds of data with | ||
| 730 | applications, for example video images, raw or sliced VBI data, RDS | ||
| 731 | datagrams. Even within one kind many different formats are possible, | ||
| 732 | in particular an abundance of image formats. Although drivers must | ||
| 733 | provide a default and the selection persists across closing and | ||
| 734 | reopening a device, applications should always negotiate a data format | ||
| 735 | before engaging in data exchange. Negotiation means the application | ||
| 736 | asks for a particular format and the driver selects and reports the | ||
| 737 | best the hardware can do to satisfy the request. Of course | ||
| 738 | applications can also just query the current selection.</para> | ||
| 739 | |||
| 740 | <para>A single mechanism exists to negotiate all data formats | ||
| 741 | using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and | ||
| 742 | &VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be | ||
| 743 | used to examine what the hardware <emphasis>could</emphasis> do, | ||
| 744 | without actually selecting a new data format. The data formats | ||
| 745 | supported by the V4L2 API are covered in the respective device section | ||
| 746 | in <xref linkend="devices" />. For a closer look at image formats see | ||
| 747 | <xref linkend="pixfmt" />.</para> | ||
| 748 | |||
| 749 | <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major | ||
| 750 | turning-point in the initialization sequence. Prior to this point | ||
| 751 | multiple panel applications can access the same device concurrently to | ||
| 752 | select the current input, change controls or modify other properties. | ||
| 753 | The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream | ||
| 754 | (video data, VBI data etc.) exclusively to one file descriptor.</para> | ||
| 755 | |||
| 756 | <para>Exclusive means no other application, more precisely no | ||
| 757 | other file descriptor, can grab this stream or change device | ||
| 758 | properties inconsistent with the negotiated parameters. A video | ||
| 759 | standard change for example, when the new standard uses a different | ||
| 760 | number of scan lines, can invalidate the selected image format. | ||
| 761 | Therefore only the file descriptor owning the stream can make | ||
| 762 | invalidating changes. Accordingly multiple file descriptors which | ||
| 763 | grabbed different logical streams prevent each other from interfering | ||
| 764 | with their settings. When for example video overlay is about to start | ||
| 765 | or already in progress, simultaneous video capturing may be restricted | ||
| 766 | to the same cropping and image size.</para> | ||
| 767 | |||
| 768 | <para>When applications omit the | ||
| 769 | <constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are | ||
| 770 | implied by the next step, the selection of an I/O method with the | ||
| 771 | &VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or | ||
| 772 | &func-write; call.</para> | ||
| 773 | |||
| 774 | <para>Generally only one logical stream can be assigned to a | ||
| 775 | file descriptor, the exception being drivers permitting simultaneous | ||
| 776 | video capturing and overlay using the same file descriptor for | ||
| 777 | compatibility with V4L and earlier versions of V4L2. Switching the | ||
| 778 | logical stream or returning into "panel mode" is possible by closing | ||
| 779 | and reopening the device. Drivers <emphasis>may</emphasis> support a | ||
| 780 | switch using <constant>VIDIOC_S_FMT</constant>.</para> | ||
| 781 | |||
| 782 | <para>All drivers exchanging data with | ||
| 783 | applications must support the <constant>VIDIOC_G_FMT</constant> and | ||
| 784 | <constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the | ||
| 785 | <constant>VIDIOC_TRY_FMT</constant> is highly recommended but | ||
| 786 | optional.</para> | ||
| 787 | </section> | ||
| 788 | |||
| 789 | <section> | ||
| 790 | <title>Image Format Enumeration</title> | ||
| 791 | |||
| 792 | <para>Apart of the generic format negotiation functions | ||
| 793 | a special ioctl to enumerate all image formats supported by video | ||
| 794 | capture, overlay or output devices is available.<footnote> | ||
| 795 | <para>Enumerating formats an application has no a-priori | ||
| 796 | knowledge of (otherwise it could explicitly ask for them and need not | ||
| 797 | enumerate) seems useless, but there are applications serving as proxy | ||
| 798 | between drivers and the actual video applications for which this is | ||
| 799 | useful.</para> | ||
| 800 | </footnote></para> | ||
| 801 | |||
| 802 | <para>The &VIDIOC-ENUM-FMT; ioctl must be supported | ||
| 803 | by all drivers exchanging image data with applications.</para> | ||
| 804 | |||
| 805 | <important> | ||
| 806 | <para>Drivers are not supposed to convert image formats in | ||
| 807 | kernel space. They must enumerate only formats directly supported by | ||
| 808 | the hardware. If necessary driver writers should publish an example | ||
| 809 | conversion routine or library for integration into applications.</para> | ||
| 810 | </important> | ||
| 811 | </section> | ||
| 812 | </section> | ||
| 813 | |||
| 814 | <section id="crop"> | ||
| 815 | <title>Image Cropping, Insertion and Scaling</title> | ||
| 816 | |||
| 817 | <para>Some video capture devices can sample a subsection of the | ||
| 818 | picture and shrink or enlarge it to an image of arbitrary size. We | ||
| 819 | call these abilities cropping and scaling. Some video output devices | ||
| 820 | can scale an image up or down and insert it at an arbitrary scan line | ||
| 821 | and horizontal offset into a video signal.</para> | ||
| 822 | |||
| 823 | <para>Applications can use the following API to select an area in | ||
| 824 | the video signal, query the default area and the hardware limits. | ||
| 825 | <emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP; | ||
| 826 | and &VIDIOC-S-CROP; ioctls apply to input as well as output | ||
| 827 | devices.</emphasis></para> | ||
| 828 | |||
| 829 | <para>Scaling requires a source and a target. On a video capture | ||
| 830 | or overlay device the source is the video signal, and the cropping | ||
| 831 | ioctls determine the area actually sampled. The target are images | ||
| 832 | read by the application or overlaid onto the graphics screen. Their | ||
| 833 | size (and position for an overlay) is negotiated with the | ||
| 834 | &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para> | ||
| 835 | |||
| 836 | <para>On a video output device the source are the images passed in | ||
| 837 | by the application, and their size is again negotiated with the | ||
| 838 | <constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a | ||
| 839 | compressed video stream. The target is the video signal, and the | ||
| 840 | cropping ioctls determine the area where the images are | ||
| 841 | inserted.</para> | ||
| 842 | |||
| 843 | <para>Source and target rectangles are defined even if the device | ||
| 844 | does not support scaling or the <constant>VIDIOC_G/S_CROP</constant> | ||
| 845 | ioctls. Their size (and position where applicable) will be fixed in | ||
| 846 | this case. <emphasis>All capture and output device must support the | ||
| 847 | <constant>VIDIOC_CROPCAP</constant> ioctl such that applications can | ||
| 848 | determine if scaling takes place.</emphasis></para> | ||
| 849 | |||
| 850 | <section> | ||
| 851 | <title>Cropping Structures</title> | ||
| 852 | |||
| 853 | <figure id="crop-scale"> | ||
| 854 | <title>Image Cropping, Insertion and Scaling</title> | ||
| 855 | <mediaobject> | ||
| 856 | <imageobject> | ||
| 857 | <imagedata fileref="crop.pdf" format="PS" /> | ||
| 858 | </imageobject> | ||
| 859 | <imageobject> | ||
| 860 | <imagedata fileref="crop.gif" format="GIF" /> | ||
| 861 | </imageobject> | ||
| 862 | <textobject> | ||
| 863 | <phrase>The cropping, insertion and scaling process</phrase> | ||
| 864 | </textobject> | ||
| 865 | </mediaobject> | ||
| 866 | </figure> | ||
| 867 | |||
| 868 | <para>For capture devices the coordinates of the top left | ||
| 869 | corner, width and height of the area which can be sampled is given by | ||
| 870 | the <structfield>bounds</structfield> substructure of the | ||
| 871 | &v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant> | ||
| 872 | ioctl. To support a wide range of hardware this specification does not | ||
| 873 | define an origin or units. However by convention drivers should | ||
| 874 | horizontally count unscaled samples relative to 0H (the leading edge | ||
| 875 | of the horizontal sync pulse, see <xref linkend="vbi-hsync" />). | ||
| 876 | Vertically ITU-R line | ||
| 877 | numbers of the first field (<xref linkend="vbi-525" />, <xref | ||
| 878 | linkend="vbi-625" />), multiplied by two if the driver can capture both | ||
| 879 | fields.</para> | ||
| 880 | |||
| 881 | <para>The top left corner, width and height of the source | ||
| 882 | rectangle, that is the area actually sampled, is given by &v4l2-crop; | ||
| 883 | using the same coordinate system as &v4l2-cropcap;. Applications can | ||
| 884 | use the <constant>VIDIOC_G_CROP</constant> and | ||
| 885 | <constant>VIDIOC_S_CROP</constant> ioctls to get and set this | ||
| 886 | rectangle. It must lie completely within the capture boundaries and | ||
| 887 | the driver may further adjust the requested size and/or position | ||
| 888 | according to hardware limitations.</para> | ||
| 889 | |||
| 890 | <para>Each capture device has a default source rectangle, given | ||
| 891 | by the <structfield>defrect</structfield> substructure of | ||
| 892 | &v4l2-cropcap;. The center of this rectangle shall align with the | ||
| 893 | center of the active picture area of the video signal, and cover what | ||
| 894 | the driver writer considers the complete picture. Drivers shall reset | ||
| 895 | the source rectangle to the default when the driver is first loaded, | ||
| 896 | but not later.</para> | ||
| 897 | |||
| 898 | <para>For output devices these structures and ioctls are used | ||
| 899 | accordingly, defining the <emphasis>target</emphasis> rectangle where | ||
| 900 | the images will be inserted into the video signal.</para> | ||
| 901 | |||
| 902 | </section> | ||
| 903 | |||
| 904 | <section> | ||
| 905 | <title>Scaling Adjustments</title> | ||
| 906 | |||
| 907 | <para>Video hardware can have various cropping, insertion and | ||
| 908 | scaling limitations. It may only scale up or down, support only | ||
| 909 | discrete scaling factors, or have different scaling abilities in | ||
| 910 | horizontal and vertical direction. Also it may not support scaling at | ||
| 911 | all. At the same time the &v4l2-crop; rectangle may have to be | ||
| 912 | aligned, and both the source and target rectangles may have arbitrary | ||
| 913 | upper and lower size limits. In particular the maximum | ||
| 914 | <structfield>width</structfield> and <structfield>height</structfield> | ||
| 915 | in &v4l2-crop; may be smaller than the | ||
| 916 | &v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as | ||
| 917 | usual, drivers are expected to adjust the requested parameters and | ||
| 918 | return the actual values selected.</para> | ||
| 919 | |||
| 920 | <para>Applications can change the source or the target rectangle | ||
| 921 | first, as they may prefer a particular image size or a certain area in | ||
| 922 | the video signal. If the driver has to adjust both to satisfy hardware | ||
| 923 | limitations, the last requested rectangle shall take priority, and the | ||
| 924 | driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT; | ||
| 925 | ioctl however shall not change the driver state and therefore only | ||
| 926 | adjust the requested rectangle.</para> | ||
| 927 | |||
| 928 | <para>Suppose scaling on a video capture device is restricted to | ||
| 929 | a factor 1:1 or 2:1 in either direction and the target image size must | ||
| 930 | be a multiple of 16 × 16 pixels. The source cropping | ||
| 931 | rectangle is set to defaults, which are also the upper limit in this | ||
| 932 | example, of 640 × 400 pixels at offset 0, 0. An | ||
| 933 | application requests an image size of 300 × 225 | ||
| 934 | pixels, assuming video will be scaled down from the "full picture" | ||
| 935 | accordingly. The driver sets the image size to the closest possible | ||
| 936 | values 304 × 224, then chooses the cropping rectangle | ||
| 937 | closest to the requested size, that is 608 × 224 | ||
| 938 | (224 × 2:1 would exceed the limit 400). The offset | ||
| 939 | 0, 0 is still valid, thus unmodified. Given the default cropping | ||
| 940 | rectangle reported by <constant>VIDIOC_CROPCAP</constant> the | ||
| 941 | application can easily propose another offset to center the cropping | ||
| 942 | rectangle.</para> | ||
| 943 | |||
| 944 | <para>Now the application may insist on covering an area using a | ||
| 945 | picture aspect ratio closer to the original request, so it asks for a | ||
| 946 | cropping rectangle of 608 × 456 pixels. The present | ||
| 947 | scaling factors limit cropping to 640 × 384, so the | ||
| 948 | driver returns the cropping size 608 × 384 and adjusts | ||
| 949 | the image size to closest possible 304 × 192.</para> | ||
| 950 | |||
| 951 | </section> | ||
| 952 | |||
| 953 | <section> | ||
| 954 | <title>Examples</title> | ||
| 955 | |||
| 956 | <para>Source and target rectangles shall remain unchanged across | ||
| 957 | closing and reopening a device, such that piping data into or out of a | ||
| 958 | device will work without special preparations. More advanced | ||
| 959 | applications should ensure the parameters are suitable before starting | ||
| 960 | I/O.</para> | ||
| 961 | |||
| 962 | <example> | ||
| 963 | <title>Resetting the cropping parameters</title> | ||
| 964 | |||
| 965 | <para>(A video capture device is assumed; change | ||
| 966 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other | ||
| 967 | devices.)</para> | ||
| 968 | |||
| 969 | <programlisting> | ||
| 970 | &v4l2-cropcap; cropcap; | ||
| 971 | &v4l2-crop; crop; | ||
| 972 | |||
| 973 | memset (&cropcap, 0, sizeof (cropcap)); | ||
| 974 | cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 975 | |||
| 976 | if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) { | ||
| 977 | perror ("VIDIOC_CROPCAP"); | ||
| 978 | exit (EXIT_FAILURE); | ||
| 979 | } | ||
| 980 | |||
| 981 | memset (&crop, 0, sizeof (crop)); | ||
| 982 | crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 983 | crop.c = cropcap.defrect; | ||
| 984 | |||
| 985 | /* Ignore if cropping is not supported (EINVAL). */ | ||
| 986 | |||
| 987 | if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &crop) | ||
| 988 | && errno != EINVAL) { | ||
| 989 | perror ("VIDIOC_S_CROP"); | ||
| 990 | exit (EXIT_FAILURE); | ||
| 991 | } | ||
| 992 | </programlisting> | ||
| 993 | </example> | ||
| 994 | |||
| 995 | <example> | ||
| 996 | <title>Simple downscaling</title> | ||
| 997 | |||
| 998 | <para>(A video capture device is assumed.)</para> | ||
| 999 | |||
| 1000 | <programlisting> | ||
| 1001 | &v4l2-cropcap; cropcap; | ||
| 1002 | &v4l2-format; format; | ||
| 1003 | |||
| 1004 | reset_cropping_parameters (); | ||
| 1005 | |||
| 1006 | /* Scale down to 1/4 size of full picture. */ | ||
| 1007 | |||
| 1008 | memset (&format, 0, sizeof (format)); /* defaults */ | ||
| 1009 | |||
| 1010 | format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 1011 | |||
| 1012 | format.fmt.pix.width = cropcap.defrect.width >> 1; | ||
| 1013 | format.fmt.pix.height = cropcap.defrect.height >> 1; | ||
| 1014 | format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; | ||
| 1015 | |||
| 1016 | if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &format)) { | ||
| 1017 | perror ("VIDIOC_S_FORMAT"); | ||
| 1018 | exit (EXIT_FAILURE); | ||
| 1019 | } | ||
| 1020 | |||
| 1021 | /* We could check the actual image size now, the actual scaling factor | ||
| 1022 | or if the driver can scale at all. */ | ||
| 1023 | </programlisting> | ||
| 1024 | </example> | ||
| 1025 | |||
| 1026 | <example> | ||
| 1027 | <title>Selecting an output area</title> | ||
| 1028 | |||
| 1029 | <programlisting> | ||
| 1030 | &v4l2-cropcap; cropcap; | ||
| 1031 | &v4l2-crop; crop; | ||
| 1032 | |||
| 1033 | memset (&cropcap, 0, sizeof (cropcap)); | ||
| 1034 | cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; | ||
| 1035 | |||
| 1036 | if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { | ||
| 1037 | perror ("VIDIOC_CROPCAP"); | ||
| 1038 | exit (EXIT_FAILURE); | ||
| 1039 | } | ||
| 1040 | |||
| 1041 | memset (&crop, 0, sizeof (crop)); | ||
| 1042 | |||
| 1043 | crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; | ||
| 1044 | crop.c = cropcap.defrect; | ||
| 1045 | |||
| 1046 | /* Scale the width and height to 50 % of their original size | ||
| 1047 | and center the output. */ | ||
| 1048 | |||
| 1049 | crop.c.width /= 2; | ||
| 1050 | crop.c.height /= 2; | ||
| 1051 | crop.c.left += crop.c.width / 2; | ||
| 1052 | crop.c.top += crop.c.height / 2; | ||
| 1053 | |||
| 1054 | /* Ignore if cropping is not supported (EINVAL). */ | ||
| 1055 | |||
| 1056 | if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) | ||
| 1057 | && errno != EINVAL) { | ||
| 1058 | perror ("VIDIOC_S_CROP"); | ||
| 1059 | exit (EXIT_FAILURE); | ||
| 1060 | } | ||
| 1061 | </programlisting> | ||
| 1062 | </example> | ||
| 1063 | |||
| 1064 | <example> | ||
| 1065 | <title>Current scaling factor and pixel aspect</title> | ||
| 1066 | |||
| 1067 | <para>(A video capture device is assumed.)</para> | ||
| 1068 | |||
| 1069 | <programlisting> | ||
| 1070 | &v4l2-cropcap; cropcap; | ||
| 1071 | &v4l2-crop; crop; | ||
| 1072 | &v4l2-format; format; | ||
| 1073 | double hscale, vscale; | ||
| 1074 | double aspect; | ||
| 1075 | int dwidth, dheight; | ||
| 1076 | |||
| 1077 | memset (&cropcap, 0, sizeof (cropcap)); | ||
| 1078 | cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 1079 | |||
| 1080 | if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) { | ||
| 1081 | perror ("VIDIOC_CROPCAP"); | ||
| 1082 | exit (EXIT_FAILURE); | ||
| 1083 | } | ||
| 1084 | |||
| 1085 | memset (&crop, 0, sizeof (crop)); | ||
| 1086 | crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 1087 | |||
| 1088 | if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &crop)) { | ||
| 1089 | if (errno != EINVAL) { | ||
| 1090 | perror ("VIDIOC_G_CROP"); | ||
| 1091 | exit (EXIT_FAILURE); | ||
| 1092 | } | ||
| 1093 | |||
| 1094 | /* Cropping not supported. */ | ||
| 1095 | crop.c = cropcap.defrect; | ||
| 1096 | } | ||
| 1097 | |||
| 1098 | memset (&format, 0, sizeof (format)); | ||
| 1099 | format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 1100 | |||
| 1101 | if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &format)) { | ||
| 1102 | perror ("VIDIOC_G_FMT"); | ||
| 1103 | exit (EXIT_FAILURE); | ||
| 1104 | } | ||
| 1105 | |||
| 1106 | /* The scaling applied by the driver. */ | ||
| 1107 | |||
| 1108 | hscale = format.fmt.pix.width / (double) crop.c.width; | ||
| 1109 | vscale = format.fmt.pix.height / (double) crop.c.height; | ||
| 1110 | |||
| 1111 | aspect = cropcap.pixelaspect.numerator / | ||
| 1112 | (double) cropcap.pixelaspect.denominator; | ||
| 1113 | aspect = aspect * hscale / vscale; | ||
| 1114 | |||
| 1115 | /* Devices following ITU-R BT.601 do not capture | ||
| 1116 | square pixels. For playback on a computer monitor | ||
| 1117 | we should scale the images to this size. */ | ||
| 1118 | |||
| 1119 | dwidth = format.fmt.pix.width / aspect; | ||
| 1120 | dheight = format.fmt.pix.height; | ||
| 1121 | </programlisting> | ||
| 1122 | </example> | ||
| 1123 | </section> | ||
| 1124 | </section> | ||
| 1125 | |||
| 1126 | <section id="streaming-par"> | ||
| 1127 | <title>Streaming Parameters</title> | ||
| 1128 | |||
| 1129 | <para>Streaming parameters are intended to optimize the video | ||
| 1130 | capture process as well as I/O. Presently applications can request a | ||
| 1131 | high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para> | ||
| 1132 | |||
| 1133 | <para>The current video standard determines a nominal number of | ||
| 1134 | frames per second. If less than this number of frames is to be | ||
| 1135 | captured or output, applications can request frame skipping or | ||
| 1136 | duplicating on the driver side. This is especially useful when using | ||
| 1137 | the &func-read; or &func-write;, which are not augmented by timestamps | ||
| 1138 | or sequence counters, and to avoid unneccessary data copying.</para> | ||
| 1139 | |||
| 1140 | <para>Finally these ioctls can be used to determine the number of | ||
| 1141 | buffers used internally by a driver in read/write mode. For | ||
| 1142 | implications see the section discussing the &func-read; | ||
| 1143 | function.</para> | ||
| 1144 | |||
| 1145 | <para>To get and set the streaming parameters applications call | ||
| 1146 | the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take | ||
| 1147 | a pointer to a &v4l2-streamparm;, which contains a union holding | ||
| 1148 | separate parameters for input and output devices.</para> | ||
| 1149 | |||
| 1150 | <para>These ioctls are optional, drivers need not implement | ||
| 1151 | them. If so, they return the &EINVAL;.</para> | ||
| 1152 | </section> | ||
| 1153 | |||
| 1154 | <!-- | ||
| 1155 | Local Variables: | ||
| 1156 | mode: sgml | ||
| 1157 | sgml-parent-document: "v4l2.sgml" | ||
| 1158 | indent-tabs-mode: nil | ||
| 1159 | End: | ||
| 1160 | --> | ||
diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml new file mode 100644 index 000000000000..4d1902a54d61 --- /dev/null +++ b/Documentation/DocBook/v4l/compat.xml | |||
| @@ -0,0 +1,2457 @@ | |||
| 1 | <title>Changes</title> | ||
| 2 | |||
| 3 | <para>The following chapters document the evolution of the V4L2 API, | ||
| 4 | errata or extensions. They are also intended to help application and | ||
| 5 | driver writers to port or update their code.</para> | ||
| 6 | |||
| 7 | <section id="diff-v4l"> | ||
| 8 | <title>Differences between V4L and V4L2</title> | ||
| 9 | |||
| 10 | <para>The Video For Linux API was first introduced in Linux 2.1 to | ||
| 11 | unify and replace various TV and radio device related interfaces, | ||
| 12 | developed independently by driver writers in prior years. Starting | ||
| 13 | with Linux 2.5 the much improved V4L2 API replaces the V4L API, | ||
| 14 | although existing drivers will continue to support V4L applications in | ||
| 15 | the future, either directly or through the V4L2 compatibility layer in | ||
| 16 | the <filename>videodev</filename> kernel module translating ioctls on | ||
| 17 | the fly. For a transition period not all drivers will support the V4L2 | ||
| 18 | API.</para> | ||
| 19 | |||
| 20 | <section> | ||
| 21 | <title>Opening and Closing Devices</title> | ||
| 22 | |||
| 23 | <para>For compatibility reasons the character device file names | ||
| 24 | recommended for V4L2 video capture, overlay, radio, teletext and raw | ||
| 25 | vbi capture devices did not change from those used by V4L. They are | ||
| 26 | listed in <xref linkend="devices" /> and below in <xref | ||
| 27 | linkend="v4l-dev" />.</para> | ||
| 28 | |||
| 29 | <para>The V4L <filename>videodev</filename> module automatically | ||
| 30 | assigns minor numbers to drivers in load order, depending on the | ||
| 31 | registered device type. We recommend that V4L2 drivers by default | ||
| 32 | register devices with the same numbers, but the system administrator | ||
| 33 | can assign arbitrary minor numbers using driver module options. The | ||
| 34 | major device number remains 81.</para> | ||
| 35 | |||
| 36 | <table id="v4l-dev"> | ||
| 37 | <title>V4L Device Types, Names and Numbers</title> | ||
| 38 | <tgroup cols="3"> | ||
| 39 | <thead> | ||
| 40 | <row> | ||
| 41 | <entry>Device Type</entry> | ||
| 42 | <entry>File Name</entry> | ||
| 43 | <entry>Minor Numbers</entry> | ||
| 44 | </row> | ||
| 45 | </thead> | ||
| 46 | <tbody valign="top"> | ||
| 47 | <row> | ||
| 48 | <entry>Video capture and overlay</entry> | ||
| 49 | <entry><para><filename>/dev/video</filename> and | ||
| 50 | <filename>/dev/bttv0</filename><footnote> <para>According to | ||
| 51 | Documentation/devices.txt these should be symbolic links to | ||
| 52 | <filename>/dev/video0</filename>. Note the original bttv interface is | ||
| 53 | not compatible with V4L or V4L2.</para> </footnote>, | ||
| 54 | <filename>/dev/video0</filename> to | ||
| 55 | <filename>/dev/video63</filename></para></entry> | ||
| 56 | <entry>0-63</entry> | ||
| 57 | </row> | ||
| 58 | <row> | ||
| 59 | <entry>Radio receiver</entry> | ||
| 60 | <entry><para><filename>/dev/radio</filename><footnote> | ||
| 61 | <para>According to | ||
| 62 | <filename>Documentation/devices.txt</filename> a symbolic link to | ||
| 63 | <filename>/dev/radio0</filename>.</para> | ||
| 64 | </footnote>, <filename>/dev/radio0</filename> to | ||
| 65 | <filename>/dev/radio63</filename></para></entry> | ||
| 66 | <entry>64-127</entry> | ||
| 67 | </row> | ||
| 68 | <row> | ||
| 69 | <entry>Teletext decoder</entry> | ||
| 70 | <entry><para><filename>/dev/vtx</filename>, | ||
| 71 | <filename>/dev/vtx0</filename> to | ||
| 72 | <filename>/dev/vtx31</filename></para></entry> | ||
| 73 | <entry>192-223</entry> | ||
| 74 | </row> | ||
| 75 | <row> | ||
| 76 | <entry>Raw VBI capture</entry> | ||
| 77 | <entry><para><filename>/dev/vbi</filename>, | ||
| 78 | <filename>/dev/vbi0</filename> to | ||
| 79 | <filename>/dev/vbi31</filename></para></entry> | ||
| 80 | <entry>224-255</entry> | ||
| 81 | </row> | ||
| 82 | </tbody> | ||
| 83 | </tgroup> | ||
| 84 | </table> | ||
| 85 | |||
| 86 | <para>V4L prohibits (or used to prohibit) multiple opens of a | ||
| 87 | device file. V4L2 drivers <emphasis>may</emphasis> support multiple | ||
| 88 | opens, see <xref linkend="open" /> for details and consequences.</para> | ||
| 89 | |||
| 90 | <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;. The | ||
| 91 | compatibility layer in the V4L2 <filename>videodev</filename> module | ||
| 92 | can translate V4L ioctl requests to their V4L2 counterpart, however a | ||
| 93 | V4L2 driver usually needs more preparation to become fully V4L | ||
| 94 | compatible. This is covered in more detail in <xref | ||
| 95 | linkend="driver" />.</para> | ||
| 96 | </section> | ||
| 97 | |||
| 98 | <section> | ||
| 99 | <title>Querying Capabilities</title> | ||
| 100 | |||
| 101 | <para>The V4L <constant>VIDIOCGCAP</constant> ioctl is | ||
| 102 | equivalent to V4L2's &VIDIOC-QUERYCAP;.</para> | ||
| 103 | |||
| 104 | <para>The <structfield>name</structfield> field in struct | ||
| 105 | <structname>video_capability</structname> became | ||
| 106 | <structfield>card</structfield> in &v4l2-capability;, | ||
| 107 | <structfield>type</structfield> was replaced by | ||
| 108 | <structfield>capabilities</structfield>. Note V4L2 does not | ||
| 109 | distinguish between device types like this, better think of basic | ||
| 110 | video input, video output and radio devices supporting a set of | ||
| 111 | related functions like video capturing, video overlay and VBI | ||
| 112 | capturing. See <xref linkend="open" /> for an | ||
| 113 | introduction.<informaltable> | ||
| 114 | <tgroup cols="3"> | ||
| 115 | <thead> | ||
| 116 | <row> | ||
| 117 | <entry>struct | ||
| 118 | <structname>video_capability</structname> | ||
| 119 | <structfield>type</structfield></entry> | ||
| 120 | <entry>&v4l2-capability; | ||
| 121 | <structfield>capabilities</structfield> flags</entry> | ||
| 122 | <entry>Purpose</entry> | ||
| 123 | </row> | ||
| 124 | </thead> | ||
| 125 | <tbody valign="top"> | ||
| 126 | <row> | ||
| 127 | <entry><constant>VID_TYPE_CAPTURE</constant></entry> | ||
| 128 | <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry> | ||
| 129 | <entry>The <link linkend="capture">video | ||
| 130 | capture</link> interface is supported.</entry> | ||
| 131 | </row> | ||
| 132 | <row> | ||
| 133 | <entry><constant>VID_TYPE_TUNER</constant></entry> | ||
| 134 | <entry><constant>V4L2_CAP_TUNER</constant></entry> | ||
| 135 | <entry>The device has a <link linkend="tuner">tuner or | ||
| 136 | modulator</link>.</entry> | ||
| 137 | </row> | ||
| 138 | <row> | ||
| 139 | <entry><constant>VID_TYPE_TELETEXT</constant></entry> | ||
| 140 | <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry> | ||
| 141 | <entry>The <link linkend="raw-vbi">raw VBI | ||
| 142 | capture</link> interface is supported.</entry> | ||
| 143 | </row> | ||
| 144 | <row> | ||
| 145 | <entry><constant>VID_TYPE_OVERLAY</constant></entry> | ||
| 146 | <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry> | ||
| 147 | <entry>The <link linkend="overlay">video | ||
| 148 | overlay</link> interface is supported.</entry> | ||
| 149 | </row> | ||
| 150 | <row> | ||
| 151 | <entry><constant>VID_TYPE_CHROMAKEY</constant></entry> | ||
| 152 | <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant> in | ||
| 153 | field <structfield>capability</structfield> of | ||
| 154 | &v4l2-framebuffer;</entry> | ||
| 155 | <entry>Whether chromakey overlay is supported. For | ||
| 156 | more information on overlay see | ||
| 157 | <xref linkend="overlay" />.</entry> | ||
| 158 | </row> | ||
| 159 | <row> | ||
| 160 | <entry><constant>VID_TYPE_CLIPPING</constant></entry> | ||
| 161 | <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> | ||
| 162 | and <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant> in field | ||
| 163 | <structfield>capability</structfield> of &v4l2-framebuffer;</entry> | ||
| 164 | <entry>Whether clipping the overlaid image is | ||
| 165 | supported, see <xref linkend="overlay" />.</entry> | ||
| 166 | </row> | ||
| 167 | <row> | ||
| 168 | <entry><constant>VID_TYPE_FRAMERAM</constant></entry> | ||
| 169 | <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant> | ||
| 170 | <emphasis>not set</emphasis> in field | ||
| 171 | <structfield>capability</structfield> of &v4l2-framebuffer;</entry> | ||
| 172 | <entry>Whether overlay overwrites frame buffer memory, | ||
| 173 | see <xref linkend="overlay" />.</entry> | ||
| 174 | </row> | ||
| 175 | <row> | ||
| 176 | <entry><constant>VID_TYPE_SCALES</constant></entry> | ||
| 177 | <entry><constant>-</constant></entry> | ||
| 178 | <entry>This flag indicates if the hardware can scale | ||
| 179 | images. The V4L2 API implies the scale factor by setting the cropping | ||
| 180 | dimensions and image size with the &VIDIOC-S-CROP; and &VIDIOC-S-FMT; | ||
| 181 | ioctl, respectively. The driver returns the closest sizes possible. | ||
| 182 | For more information on cropping and scaling see <xref | ||
| 183 | linkend="crop" />.</entry> | ||
| 184 | </row> | ||
| 185 | <row> | ||
| 186 | <entry><constant>VID_TYPE_MONOCHROME</constant></entry> | ||
| 187 | <entry><constant>-</constant></entry> | ||
| 188 | <entry>Applications can enumerate the supported image | ||
| 189 | formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device | ||
| 190 | supports grey scale capturing only. For more information on image | ||
| 191 | formats see <xref linkend="pixfmt" />.</entry> | ||
| 192 | </row> | ||
| 193 | <row> | ||
| 194 | <entry><constant>VID_TYPE_SUBCAPTURE</constant></entry> | ||
| 195 | <entry><constant>-</constant></entry> | ||
| 196 | <entry>Applications can call the &VIDIOC-G-CROP; ioctl | ||
| 197 | to determine if the device supports capturing a subsection of the full | ||
| 198 | picture ("cropping" in V4L2). If not, the ioctl returns the &EINVAL;. | ||
| 199 | For more information on cropping and scaling see <xref | ||
| 200 | linkend="crop" />.</entry> | ||
| 201 | </row> | ||
| 202 | <row> | ||
| 203 | <entry><constant>VID_TYPE_MPEG_DECODER</constant></entry> | ||
| 204 | <entry><constant>-</constant></entry> | ||
| 205 | <entry>Applications can enumerate the supported image | ||
| 206 | formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device | ||
| 207 | supports MPEG streams.</entry> | ||
| 208 | </row> | ||
| 209 | <row> | ||
| 210 | <entry><constant>VID_TYPE_MPEG_ENCODER</constant></entry> | ||
| 211 | <entry><constant>-</constant></entry> | ||
| 212 | <entry>See above.</entry> | ||
| 213 | </row> | ||
| 214 | <row> | ||
| 215 | <entry><constant>VID_TYPE_MJPEG_DECODER</constant></entry> | ||
| 216 | <entry><constant>-</constant></entry> | ||
| 217 | <entry>See above.</entry> | ||
| 218 | </row> | ||
| 219 | <row> | ||
| 220 | <entry><constant>VID_TYPE_MJPEG_ENCODER</constant></entry> | ||
| 221 | <entry><constant>-</constant></entry> | ||
| 222 | <entry>See above.</entry> | ||
| 223 | </row> | ||
| 224 | </tbody> | ||
| 225 | </tgroup> | ||
| 226 | </informaltable></para> | ||
| 227 | |||
| 228 | <para>The <structfield>audios</structfield> field was replaced | ||
| 229 | by <structfield>capabilities</structfield> flag | ||
| 230 | <constant>V4L2_CAP_AUDIO</constant>, indicating | ||
| 231 | <emphasis>if</emphasis> the device has any audio inputs or outputs. To | ||
| 232 | determine their number applications can enumerate audio inputs with | ||
| 233 | the &VIDIOC-G-AUDIO; ioctl. The audio ioctls are described in <xref | ||
| 234 | linkend="audio" />.</para> | ||
| 235 | |||
| 236 | <para>The <structfield>maxwidth</structfield>, | ||
| 237 | <structfield>maxheight</structfield>, | ||
| 238 | <structfield>minwidth</structfield> and | ||
| 239 | <structfield>minheight</structfield> fields were removed. Calling the | ||
| 240 | &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; ioctl with the desired dimensions | ||
| 241 | returns the closest size possible, taking into account the current | ||
| 242 | video standard, cropping and scaling limitations.</para> | ||
| 243 | </section> | ||
| 244 | |||
| 245 | <section> | ||
| 246 | <title>Video Sources</title> | ||
| 247 | |||
| 248 | <para>V4L provides the <constant>VIDIOCGCHAN</constant> and | ||
| 249 | <constant>VIDIOCSCHAN</constant> ioctl using struct | ||
| 250 | <structname>video_channel</structname> to enumerate | ||
| 251 | the video inputs of a V4L device. The equivalent V4L2 ioctls | ||
| 252 | are &VIDIOC-ENUMINPUT;, &VIDIOC-G-INPUT; and &VIDIOC-S-INPUT; | ||
| 253 | using &v4l2-input; as discussed in <xref linkend="video" />.</para> | ||
| 254 | |||
| 255 | <para>The <structfield>channel</structfield> field counting | ||
| 256 | inputs was renamed to <structfield>index</structfield>, the video | ||
| 257 | input types were renamed as follows: <informaltable> | ||
| 258 | <tgroup cols="2"> | ||
| 259 | <thead> | ||
| 260 | <row> | ||
| 261 | <entry>struct <structname>video_channel</structname> | ||
| 262 | <structfield>type</structfield></entry> | ||
| 263 | <entry>&v4l2-input; | ||
| 264 | <structfield>type</structfield></entry> | ||
| 265 | </row> | ||
| 266 | </thead> | ||
| 267 | <tbody valign="top"> | ||
| 268 | <row> | ||
| 269 | <entry><constant>VIDEO_TYPE_TV</constant></entry> | ||
| 270 | <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry> | ||
| 271 | </row> | ||
| 272 | <row> | ||
| 273 | <entry><constant>VIDEO_TYPE_CAMERA</constant></entry> | ||
| 274 | <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry> | ||
| 275 | </row> | ||
| 276 | </tbody> | ||
| 277 | </tgroup> | ||
| 278 | </informaltable></para> | ||
| 279 | |||
| 280 | <para>Unlike the <structfield>tuners</structfield> field | ||
| 281 | expressing the number of tuners of this input, V4L2 assumes each video | ||
| 282 | input is connected to at most one tuner. However a tuner can have more | ||
| 283 | than one input, &ie; RF connectors, and a device can have multiple | ||
| 284 | tuners. The index number of the tuner associated with the input, if | ||
| 285 | any, is stored in field <structfield>tuner</structfield> of | ||
| 286 | &v4l2-input;. Enumeration of tuners is discussed in <xref | ||
| 287 | linkend="tuner" />.</para> | ||
| 288 | |||
| 289 | <para>The redundant <constant>VIDEO_VC_TUNER</constant> flag was | ||
| 290 | dropped. Video inputs associated with a tuner are of type | ||
| 291 | <constant>V4L2_INPUT_TYPE_TUNER</constant>. The | ||
| 292 | <constant>VIDEO_VC_AUDIO</constant> flag was replaced by the | ||
| 293 | <structfield>audioset</structfield> field. V4L2 considers devices with | ||
| 294 | up to 32 audio inputs. Each set bit in the | ||
| 295 | <structfield>audioset</structfield> field represents one audio input | ||
| 296 | this video input combines with. For information about audio inputs and | ||
| 297 | how to switch between them see <xref linkend="audio" />.</para> | ||
| 298 | |||
| 299 | <para>The <structfield>norm</structfield> field describing the | ||
| 300 | supported video standards was replaced by | ||
| 301 | <structfield>std</structfield>. The V4L specification mentions a flag | ||
| 302 | <constant>VIDEO_VC_NORM</constant> indicating whether the standard can | ||
| 303 | be changed. This flag was a later addition together with the | ||
| 304 | <structfield>norm</structfield> field and has been removed in the | ||
| 305 | meantime. V4L2 has a similar, albeit more comprehensive approach | ||
| 306 | to video standards, see <xref linkend="standard" /> for more | ||
| 307 | information.</para> | ||
| 308 | </section> | ||
| 309 | |||
| 310 | <section> | ||
| 311 | <title>Tuning</title> | ||
| 312 | |||
| 313 | <para>The V4L <constant>VIDIOCGTUNER</constant> and | ||
| 314 | <constant>VIDIOCSTUNER</constant> ioctl and struct | ||
| 315 | <structname>video_tuner</structname> can be used to enumerate the | ||
| 316 | tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are | ||
| 317 | &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; using &v4l2-tuner;. Tuners are | ||
| 318 | covered in <xref linkend="tuner" />.</para> | ||
| 319 | |||
| 320 | <para>The <structfield>tuner</structfield> field counting tuners | ||
| 321 | was renamed to <structfield>index</structfield>. The fields | ||
| 322 | <structfield>name</structfield>, <structfield>rangelow</structfield> | ||
| 323 | and <structfield>rangehigh</structfield> remained unchanged.</para> | ||
| 324 | |||
| 325 | <para>The <constant>VIDEO_TUNER_PAL</constant>, | ||
| 326 | <constant>VIDEO_TUNER_NTSC</constant> and | ||
| 327 | <constant>VIDEO_TUNER_SECAM</constant> flags indicating the supported | ||
| 328 | video standards were dropped. This information is now contained in the | ||
| 329 | associated &v4l2-input;. No replacement exists for the | ||
| 330 | <constant>VIDEO_TUNER_NORM</constant> flag indicating whether the | ||
| 331 | video standard can be switched. The <structfield>mode</structfield> | ||
| 332 | field to select a different video standard was replaced by a whole new | ||
| 333 | set of ioctls and structures described in <xref linkend="standard" />. | ||
| 334 | Due to its ubiquity it should be mentioned the BTTV driver supports | ||
| 335 | several standards in addition to the regular | ||
| 336 | <constant>VIDEO_MODE_PAL</constant> (0), | ||
| 337 | <constant>VIDEO_MODE_NTSC</constant>, | ||
| 338 | <constant>VIDEO_MODE_SECAM</constant> and | ||
| 339 | <constant>VIDEO_MODE_AUTO</constant> (3). Namely N/PAL Argentina, | ||
| 340 | M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</para> | ||
| 341 | |||
| 342 | <para>The <constant>VIDEO_TUNER_STEREO_ON</constant> flag | ||
| 343 | indicating stereo reception became | ||
| 344 | <constant>V4L2_TUNER_SUB_STEREO</constant> in field | ||
| 345 | <structfield>rxsubchans</structfield>. This field also permits the | ||
| 346 | detection of monaural and bilingual audio, see the definition of | ||
| 347 | &v4l2-tuner; for details. Presently no replacement exists for the | ||
| 348 | <constant>VIDEO_TUNER_RDS_ON</constant> and | ||
| 349 | <constant>VIDEO_TUNER_MBS_ON</constant> flags.</para> | ||
| 350 | |||
| 351 | <para> The <constant>VIDEO_TUNER_LOW</constant> flag was renamed | ||
| 352 | to <constant>V4L2_TUNER_CAP_LOW</constant> in the &v4l2-tuner; | ||
| 353 | <structfield>capability</structfield> field.</para> | ||
| 354 | |||
| 355 | <para>The <constant>VIDIOCGFREQ</constant> and | ||
| 356 | <constant>VIDIOCSFREQ</constant> ioctl to change the tuner frequency | ||
| 357 | where renamed to &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;. They | ||
| 358 | take a pointer to a &v4l2-frequency; instead of an unsigned long | ||
| 359 | integer.</para> | ||
| 360 | </section> | ||
| 361 | |||
| 362 | <section id="v4l-image-properties"> | ||
| 363 | <title>Image Properties</title> | ||
| 364 | |||
| 365 | <para>V4L2 has no equivalent of the | ||
| 366 | <constant>VIDIOCGPICT</constant> and <constant>VIDIOCSPICT</constant> | ||
| 367 | ioctl and struct <structname>video_picture</structname>. The following | ||
| 368 | fields where replaced by V4L2 controls accessible with the | ||
| 369 | &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls:<informaltable> | ||
| 370 | <tgroup cols="2"> | ||
| 371 | <thead> | ||
| 372 | <row> | ||
| 373 | <entry>struct <structname>video_picture</structname></entry> | ||
| 374 | <entry>V4L2 Control ID</entry> | ||
| 375 | </row> | ||
| 376 | </thead> | ||
| 377 | <tbody valign="top"> | ||
| 378 | <row> | ||
| 379 | <entry><structfield>brightness</structfield></entry> | ||
| 380 | <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry> | ||
| 381 | </row> | ||
| 382 | <row> | ||
| 383 | <entry><structfield>hue</structfield></entry> | ||
| 384 | <entry><constant>V4L2_CID_HUE</constant></entry> | ||
| 385 | </row> | ||
| 386 | <row> | ||
| 387 | <entry><structfield>colour</structfield></entry> | ||
| 388 | <entry><constant>V4L2_CID_SATURATION</constant></entry> | ||
| 389 | </row> | ||
| 390 | <row> | ||
| 391 | <entry><structfield>contrast</structfield></entry> | ||
| 392 | <entry><constant>V4L2_CID_CONTRAST</constant></entry> | ||
| 393 | </row> | ||
| 394 | <row> | ||
| 395 | <entry><structfield>whiteness</structfield></entry> | ||
| 396 | <entry><constant>V4L2_CID_WHITENESS</constant></entry> | ||
| 397 | </row> | ||
| 398 | </tbody> | ||
| 399 | </tgroup> | ||
| 400 | </informaltable></para> | ||
| 401 | |||
| 402 | <para>The V4L picture controls are assumed to range from 0 to | ||
| 403 | 65535 with no particular reset value. The V4L2 API permits arbitrary | ||
| 404 | limits and defaults which can be queried with the &VIDIOC-QUERYCTRL; | ||
| 405 | ioctl. For general information about controls see <xref | ||
| 406 | linkend="control" />.</para> | ||
| 407 | |||
| 408 | <para>The <structfield>depth</structfield> (average number of | ||
| 409 | bits per pixel) of a video image is implied by the selected image | ||
| 410 | format. V4L2 does not explicitely provide such information assuming | ||
| 411 | applications recognizing the format are aware of the image depth and | ||
| 412 | others need not know. The <structfield>palette</structfield> field | ||
| 413 | moved into the &v4l2-pix-format;:<informaltable> | ||
| 414 | <tgroup cols="2"> | ||
| 415 | <thead> | ||
| 416 | <row> | ||
| 417 | <entry>struct <structname>video_picture</structname> | ||
| 418 | <structfield>palette</structfield></entry> | ||
| 419 | <entry>&v4l2-pix-format; | ||
| 420 | <structfield>pixfmt</structfield></entry> | ||
| 421 | </row> | ||
| 422 | </thead> | ||
| 423 | <tbody valign="top"> | ||
| 424 | <row> | ||
| 425 | <entry><constant>VIDEO_PALETTE_GREY</constant></entry> | ||
| 426 | <entry><para><link | ||
| 427 | linkend="V4L2-PIX-FMT-GREY"><constant>V4L2_PIX_FMT_GREY</constant></link></para></entry> | ||
| 428 | </row> | ||
| 429 | <row> | ||
| 430 | <entry><constant>VIDEO_PALETTE_HI240</constant></entry> | ||
| 431 | <entry><para><link | ||
| 432 | linkend="pixfmt-reserved"><constant>V4L2_PIX_FMT_HI240</constant></link><footnote> | ||
| 433 | <para>This is a custom format used by the BTTV | ||
| 434 | driver, not one of the V4L2 standard formats.</para> | ||
| 435 | </footnote></para></entry> | ||
| 436 | </row> | ||
| 437 | <row> | ||
| 438 | <entry><constant>VIDEO_PALETTE_RGB565</constant></entry> | ||
| 439 | <entry><para><link | ||
| 440 | linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB565</constant></link></para></entry> | ||
| 441 | </row> | ||
| 442 | <row> | ||
| 443 | <entry><constant>VIDEO_PALETTE_RGB555</constant></entry> | ||
| 444 | <entry><para><link | ||
| 445 | linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB555</constant></link></para></entry> | ||
| 446 | </row> | ||
| 447 | <row> | ||
| 448 | <entry><constant>VIDEO_PALETTE_RGB24</constant></entry> | ||
| 449 | <entry><para><link | ||
| 450 | linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entry> | ||
| 451 | </row> | ||
| 452 | <row> | ||
| 453 | <entry><constant>VIDEO_PALETTE_RGB32</constant></entry> | ||
| 454 | <entry><para><link | ||
| 455 | linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote> | ||
| 456 | <para>Presumably all V4L RGB formats are | ||
| 457 | little-endian, although some drivers might interpret them according to machine endianess. V4L2 defines little-endian, big-endian and red/blue | ||
| 458 | swapped variants. For details see <xref linkend="pixfmt-rgb" />.</para> | ||
| 459 | </footnote></para></entry> | ||
| 460 | </row> | ||
| 461 | <row> | ||
| 462 | <entry><constant>VIDEO_PALETTE_YUV422</constant></entry> | ||
| 463 | <entry><para><link | ||
| 464 | linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry> | ||
| 465 | </row> | ||
| 466 | <row> | ||
| 467 | <entry><para><constant>VIDEO_PALETTE_YUYV</constant><footnote> | ||
| 468 | <para><constant>VIDEO_PALETTE_YUV422</constant> | ||
| 469 | and <constant>VIDEO_PALETTE_YUYV</constant> are the same formats. Some | ||
| 470 | V4L drivers respond to one, some to the other.</para> | ||
| 471 | </footnote></para></entry> | ||
| 472 | <entry><para><link | ||
| 473 | linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry> | ||
| 474 | </row> | ||
| 475 | <row> | ||
| 476 | <entry><constant>VIDEO_PALETTE_UYVY</constant></entry> | ||
| 477 | <entry><para><link | ||
| 478 | linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link></para></entry> | ||
| 479 | </row> | ||
| 480 | <row> | ||
| 481 | <entry><constant>VIDEO_PALETTE_YUV420</constant></entry> | ||
| 482 | <entry>None</entry> | ||
| 483 | </row> | ||
| 484 | <row> | ||
| 485 | <entry><constant>VIDEO_PALETTE_YUV411</constant></entry> | ||
| 486 | <entry><para><link | ||
| 487 | linkend="V4L2-PIX-FMT-Y41P"><constant>V4L2_PIX_FMT_Y41P</constant></link><footnote> | ||
| 488 | <para>Not to be confused with | ||
| 489 | <constant>V4L2_PIX_FMT_YUV411P</constant>, which is a planar | ||
| 490 | format.</para> </footnote></para></entry> | ||
| 491 | </row> | ||
| 492 | <row> | ||
| 493 | <entry><constant>VIDEO_PALETTE_RAW</constant></entry> | ||
| 494 | <entry><para>None<footnote> <para>V4L explains this | ||
| 495 | as: "RAW capture (BT848)"</para> </footnote></para></entry> | ||
| 496 | </row> | ||
| 497 | <row> | ||
| 498 | <entry><constant>VIDEO_PALETTE_YUV422P</constant></entry> | ||
| 499 | <entry><para><link | ||
| 500 | linkend="V4L2-PIX-FMT-YUV422P"><constant>V4L2_PIX_FMT_YUV422P</constant></link></para></entry> | ||
| 501 | </row> | ||
| 502 | <row> | ||
| 503 | <entry><constant>VIDEO_PALETTE_YUV411P</constant></entry> | ||
| 504 | <entry><para><link | ||
| 505 | linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link><footnote> | ||
| 506 | <para>Not to be confused with | ||
| 507 | <constant>V4L2_PIX_FMT_Y41P</constant>, which is a packed | ||
| 508 | format.</para> </footnote></para></entry> | ||
| 509 | </row> | ||
| 510 | <row> | ||
| 511 | <entry><constant>VIDEO_PALETTE_YUV420P</constant></entry> | ||
| 512 | <entry><para><link | ||
| 513 | linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link></para></entry> | ||
| 514 | </row> | ||
| 515 | <row> | ||
| 516 | <entry><constant>VIDEO_PALETTE_YUV410P</constant></entry> | ||
| 517 | <entry><para><link | ||
| 518 | linkend="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></link></para></entry> | ||
| 519 | </row> | ||
| 520 | </tbody> | ||
| 521 | </tgroup> | ||
| 522 | </informaltable></para> | ||
| 523 | |||
| 524 | <para>V4L2 image formats are defined in <xref | ||
| 525 | linkend="pixfmt" />. The image format can be selected with the | ||
| 526 | &VIDIOC-S-FMT; ioctl.</para> | ||
| 527 | </section> | ||
| 528 | |||
| 529 | <section> | ||
| 530 | <title>Audio</title> | ||
| 531 | |||
| 532 | <para>The <constant>VIDIOCGAUDIO</constant> and | ||
| 533 | <constant>VIDIOCSAUDIO</constant> ioctl and struct | ||
| 534 | <structname>video_audio</structname> are used to enumerate the | ||
| 535 | audio inputs of a V4L device. The equivalent V4L2 ioctls are | ||
| 536 | &VIDIOC-G-AUDIO; and &VIDIOC-S-AUDIO; using &v4l2-audio; as | ||
| 537 | discussed in <xref linkend="audio" />.</para> | ||
| 538 | |||
| 539 | <para>The <structfield>audio</structfield> "channel number" | ||
| 540 | field counting audio inputs was renamed to | ||
| 541 | <structfield>index</structfield>.</para> | ||
| 542 | |||
| 543 | <para>On <constant>VIDIOCSAUDIO</constant> the | ||
| 544 | <structfield>mode</structfield> field selects <emphasis>one</emphasis> | ||
| 545 | of the <constant>VIDEO_SOUND_MONO</constant>, | ||
| 546 | <constant>VIDEO_SOUND_STEREO</constant>, | ||
| 547 | <constant>VIDEO_SOUND_LANG1</constant> or | ||
| 548 | <constant>VIDEO_SOUND_LANG2</constant> audio demodulation modes. When | ||
| 549 | the current audio standard is BTSC | ||
| 550 | <constant>VIDEO_SOUND_LANG2</constant> refers to SAP and | ||
| 551 | <constant>VIDEO_SOUND_LANG1</constant> is meaningless. Also | ||
| 552 | undocumented in the V4L specification, there is no way to query the | ||
| 553 | selected mode. On <constant>VIDIOCGAUDIO</constant> the driver returns | ||
| 554 | the <emphasis>actually received</emphasis> audio programmes in this | ||
| 555 | field. In the V4L2 API this information is stored in the &v4l2-tuner; | ||
| 556 | <structfield>rxsubchans</structfield> and | ||
| 557 | <structfield>audmode</structfield> fields, respectively. See <xref | ||
| 558 | linkend="tuner" /> for more information on tuners. Related to audio | ||
| 559 | modes &v4l2-audio; also reports if this is a mono or stereo | ||
| 560 | input, regardless if the source is a tuner.</para> | ||
| 561 | |||
| 562 | <para>The following fields where replaced by V4L2 controls | ||
| 563 | accessible with the &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and | ||
| 564 | &VIDIOC-S-CTRL; ioctls:<informaltable> | ||
| 565 | <tgroup cols="2"> | ||
| 566 | <thead> | ||
| 567 | <row> | ||
| 568 | <entry>struct | ||
| 569 | <structname>video_audio</structname></entry> | ||
| 570 | <entry>V4L2 Control ID</entry> | ||
| 571 | </row> | ||
| 572 | </thead> | ||
| 573 | <tbody valign="top"> | ||
| 574 | <row> | ||
| 575 | <entry><structfield>volume</structfield></entry> | ||
| 576 | <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry> | ||
| 577 | </row> | ||
| 578 | <row> | ||
| 579 | <entry><structfield>bass</structfield></entry> | ||
| 580 | <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry> | ||
| 581 | </row> | ||
| 582 | <row> | ||
| 583 | <entry><structfield>treble</structfield></entry> | ||
| 584 | <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry> | ||
| 585 | </row> | ||
| 586 | <row> | ||
| 587 | <entry><structfield>balance</structfield></entry> | ||
| 588 | <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry> | ||
| 589 | </row> | ||
| 590 | </tbody> | ||
| 591 | </tgroup> | ||
| 592 | </informaltable></para> | ||
| 593 | |||
| 594 | <para>To determine which of these controls are supported by a | ||
| 595 | driver V4L provides the <structfield>flags</structfield> | ||
| 596 | <constant>VIDEO_AUDIO_VOLUME</constant>, | ||
| 597 | <constant>VIDEO_AUDIO_BASS</constant>, | ||
| 598 | <constant>VIDEO_AUDIO_TREBLE</constant> and | ||
| 599 | <constant>VIDEO_AUDIO_BALANCE</constant>. In the V4L2 API the | ||
| 600 | &VIDIOC-QUERYCTRL; ioctl reports if the respective control is | ||
| 601 | supported. Accordingly the <constant>VIDEO_AUDIO_MUTABLE</constant> | ||
| 602 | and <constant>VIDEO_AUDIO_MUTE</constant> flags where replaced by the | ||
| 603 | boolean <constant>V4L2_CID_AUDIO_MUTE</constant> control.</para> | ||
| 604 | |||
| 605 | <para>All V4L2 controls have a <structfield>step</structfield> | ||
| 606 | attribute replacing the struct <structname>video_audio</structname> | ||
| 607 | <structfield>step</structfield> field. The V4L audio controls are | ||
| 608 | assumed to range from 0 to 65535 with no particular reset value. The | ||
| 609 | V4L2 API permits arbitrary limits and defaults which can be queried | ||
| 610 | with the &VIDIOC-QUERYCTRL; ioctl. For general information about | ||
| 611 | controls see <xref linkend="control" />.</para> | ||
| 612 | </section> | ||
| 613 | |||
| 614 | <section> | ||
| 615 | <title>Frame Buffer Overlay</title> | ||
| 616 | |||
| 617 | <para>The V4L2 ioctls equivalent to | ||
| 618 | <constant>VIDIOCGFBUF</constant> and <constant>VIDIOCSFBUF</constant> | ||
| 619 | are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The | ||
| 620 | <structfield>base</structfield> field of struct | ||
| 621 | <structname>video_buffer</structname> remained unchanged, except V4L2 | ||
| 622 | defines a flag to indicate non-destructive overlays instead of a | ||
| 623 | <constant>NULL</constant> pointer. All other fields moved into the | ||
| 624 | &v4l2-pix-format; <structfield>fmt</structfield> substructure of | ||
| 625 | &v4l2-framebuffer;. The <structfield>depth</structfield> field was | ||
| 626 | replaced by <structfield>pixelformat</structfield>. See <xref | ||
| 627 | linkend="pixfmt-rgb" /> for a list of RGB formats and their | ||
| 628 | respective color depths.</para> | ||
| 629 | |||
| 630 | <para>Instead of the special ioctls | ||
| 631 | <constant>VIDIOCGWIN</constant> and <constant>VIDIOCSWIN</constant> | ||
| 632 | V4L2 uses the general-purpose data format negotiation ioctls | ||
| 633 | &VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a | ||
| 634 | &v4l2-format; as argument. Here the <structfield>win</structfield> | ||
| 635 | member of the <structfield>fmt</structfield> union is used, a | ||
| 636 | &v4l2-window;.</para> | ||
| 637 | |||
| 638 | <para>The <structfield>x</structfield>, | ||
| 639 | <structfield>y</structfield>, <structfield>width</structfield> and | ||
| 640 | <structfield>height</structfield> fields of struct | ||
| 641 | <structname>video_window</structname> moved into &v4l2-rect; | ||
| 642 | substructure <structfield>w</structfield> of struct | ||
| 643 | <structname>v4l2_window</structname>. The | ||
| 644 | <structfield>chromakey</structfield>, | ||
| 645 | <structfield>clips</structfield>, and | ||
| 646 | <structfield>clipcount</structfield> fields remained unchanged. Struct | ||
| 647 | <structname>video_clip</structname> was renamed to &v4l2-clip;, also | ||
| 648 | containing a struct <structname>v4l2_rect</structname>, but the | ||
| 649 | semantics are still the same.</para> | ||
| 650 | |||
| 651 | <para>The <constant>VIDEO_WINDOW_INTERLACE</constant> flag was | ||
| 652 | dropped. Instead applications must set the | ||
| 653 | <structfield>field</structfield> field to | ||
| 654 | <constant>V4L2_FIELD_ANY</constant> or | ||
| 655 | <constant>V4L2_FIELD_INTERLACED</constant>. The | ||
| 656 | <constant>VIDEO_WINDOW_CHROMAKEY</constant> flag moved into | ||
| 657 | &v4l2-framebuffer;, under the new name | ||
| 658 | <constant>V4L2_FBUF_FLAG_CHROMAKEY</constant>.</para> | ||
| 659 | |||
| 660 | <para>In V4L, storing a bitmap pointer in | ||
| 661 | <structfield>clips</structfield> and setting | ||
| 662 | <structfield>clipcount</structfield> to | ||
| 663 | <constant>VIDEO_CLIP_BITMAP</constant> (-1) requests bitmap | ||
| 664 | clipping, using a fixed size bitmap of 1024 × 625 bits. Struct | ||
| 665 | <structname>v4l2_window</structname> has a separate | ||
| 666 | <structfield>bitmap</structfield> pointer field for this purpose and | ||
| 667 | the bitmap size is determined by <structfield>w.width</structfield> and | ||
| 668 | <structfield>w.height</structfield>.</para> | ||
| 669 | |||
| 670 | <para>The <constant>VIDIOCCAPTURE</constant> ioctl to enable or | ||
| 671 | disable overlay was renamed to &VIDIOC-OVERLAY;.</para> | ||
| 672 | </section> | ||
| 673 | |||
| 674 | <section> | ||
| 675 | <title>Cropping</title> | ||
| 676 | |||
| 677 | <para>To capture only a subsection of the full picture V4L | ||
| 678 | defines the <constant>VIDIOCGCAPTURE</constant> and | ||
| 679 | <constant>VIDIOCSCAPTURE</constant> ioctls using struct | ||
| 680 | <structname>video_capture</structname>. The equivalent V4L2 ioctls are | ||
| 681 | &VIDIOC-G-CROP; and &VIDIOC-S-CROP; using &v4l2-crop;, and the related | ||
| 682 | &VIDIOC-CROPCAP; ioctl. This is a rather complex matter, see | ||
| 683 | <xref linkend="crop" /> for details.</para> | ||
| 684 | |||
| 685 | <para>The <structfield>x</structfield>, | ||
| 686 | <structfield>y</structfield>, <structfield>width</structfield> and | ||
| 687 | <structfield>height</structfield> fields moved into &v4l2-rect; | ||
| 688 | substructure <structfield>c</structfield> of struct | ||
| 689 | <structname>v4l2_crop</structname>. The | ||
| 690 | <structfield>decimation</structfield> field was dropped. In the V4L2 | ||
| 691 | API the scaling factor is implied by the size of the cropping | ||
| 692 | rectangle and the size of the captured or overlaid image.</para> | ||
| 693 | |||
| 694 | <para>The <constant>VIDEO_CAPTURE_ODD</constant> | ||
| 695 | and <constant>VIDEO_CAPTURE_EVEN</constant> flags to capture only the | ||
| 696 | odd or even field, respectively, were replaced by | ||
| 697 | <constant>V4L2_FIELD_TOP</constant> and | ||
| 698 | <constant>V4L2_FIELD_BOTTOM</constant> in the field named | ||
| 699 | <structfield>field</structfield> of &v4l2-pix-format; and | ||
| 700 | &v4l2-window;. These structures are used to select a capture or | ||
| 701 | overlay format with the &VIDIOC-S-FMT; ioctl.</para> | ||
| 702 | </section> | ||
| 703 | |||
| 704 | <section> | ||
| 705 | <title>Reading Images, Memory Mapping</title> | ||
| 706 | |||
| 707 | <section> | ||
| 708 | <title>Capturing using the read method</title> | ||
| 709 | |||
| 710 | <para>There is no essential difference between reading images | ||
| 711 | from a V4L or V4L2 device using the &func-read; function, however V4L2 | ||
| 712 | drivers are not required to support this I/O method. Applications can | ||
| 713 | determine if the function is available with the &VIDIOC-QUERYCAP; | ||
| 714 | ioctl. All V4L2 devices exchanging data with applications must support | ||
| 715 | the &func-select; and &func-poll; functions.</para> | ||
| 716 | |||
| 717 | <para>To select an image format and size, V4L provides the | ||
| 718 | <constant>VIDIOCSPICT</constant> and <constant>VIDIOCSWIN</constant> | ||
| 719 | ioctls. V4L2 uses the general-purpose data format negotiation ioctls | ||
| 720 | &VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a | ||
| 721 | &v4l2-format; as argument, here the &v4l2-pix-format; named | ||
| 722 | <structfield>pix</structfield> of its <structfield>fmt</structfield> | ||
| 723 | union is used.</para> | ||
| 724 | |||
| 725 | <para>For more information about the V4L2 read interface see | ||
| 726 | <xref linkend="rw" />.</para> | ||
| 727 | </section> | ||
| 728 | <section> | ||
| 729 | <title>Capturing using memory mapping</title> | ||
| 730 | |||
| 731 | <para>Applications can read from V4L devices by mapping | ||
| 732 | buffers in device memory, or more often just buffers allocated in | ||
| 733 | DMA-able system memory, into their address space. This avoids the data | ||
| 734 | copying overhead of the read method. V4L2 supports memory mapping as | ||
| 735 | well, with a few differences.</para> | ||
| 736 | |||
| 737 | <informaltable> | ||
| 738 | <tgroup cols="2"> | ||
| 739 | <thead> | ||
| 740 | <row> | ||
| 741 | <entry>V4L</entry> | ||
| 742 | <entry>V4L2</entry> | ||
| 743 | </row> | ||
| 744 | </thead> | ||
| 745 | <tbody valign="top"> | ||
| 746 | <row> | ||
| 747 | <entry></entry> | ||
| 748 | <entry>The image format must be selected before | ||
| 749 | buffers are allocated, with the &VIDIOC-S-FMT; ioctl. When no format | ||
| 750 | is selected the driver may use the last, possibly by another | ||
| 751 | application requested format.</entry> | ||
| 752 | </row> | ||
| 753 | <row> | ||
| 754 | <entry><para>Applications cannot change the number of | ||
| 755 | buffers. The it is built into the driver, unless it has a module | ||
| 756 | option to change the number when the driver module is | ||
| 757 | loaded.</para></entry> | ||
| 758 | <entry><para>The &VIDIOC-REQBUFS; ioctl allocates the | ||
| 759 | desired number of buffers, this is a required step in the initialization | ||
| 760 | sequence.</para></entry> | ||
| 761 | </row> | ||
| 762 | <row> | ||
| 763 | <entry><para>Drivers map all buffers as one contiguous | ||
| 764 | range of memory. The <constant>VIDIOCGMBUF</constant> ioctl is | ||
| 765 | available to query the number of buffers, the offset of each buffer | ||
| 766 | from the start of the virtual file, and the overall amount of memory | ||
| 767 | used, which can be used as arguments for the &func-mmap; | ||
| 768 | function.</para></entry> | ||
| 769 | <entry><para>Buffers are individually mapped. The | ||
| 770 | offset and size of each buffer can be determined with the | ||
| 771 | &VIDIOC-QUERYBUF; ioctl.</para></entry> | ||
| 772 | </row> | ||
| 773 | <row> | ||
| 774 | <entry><para>The <constant>VIDIOCMCAPTURE</constant> | ||
| 775 | ioctl prepares a buffer for capturing. It also determines the image | ||
| 776 | format for this buffer. The ioctl returns immediately, eventually with | ||
| 777 | an &EAGAIN; if no video signal had been detected. When the driver | ||
| 778 | supports more than one buffer applications can call the ioctl multiple | ||
| 779 | times and thus have multiple outstanding capture | ||
| 780 | requests.</para><para>The <constant>VIDIOCSYNC</constant> ioctl | ||
| 781 | suspends execution until a particular buffer has been | ||
| 782 | filled.</para></entry> | ||
| 783 | <entry><para>Drivers maintain an incoming and outgoing | ||
| 784 | queue. &VIDIOC-QBUF; enqueues any empty buffer into the incoming | ||
| 785 | queue. Filled buffers are dequeued from the outgoing queue with the | ||
| 786 | &VIDIOC-DQBUF; ioctl. To wait until filled buffers become available this | ||
| 787 | function, &func-select; or &func-poll; can be used. The | ||
| 788 | &VIDIOC-STREAMON; ioctl must be called once after enqueuing one or | ||
| 789 | more buffers to start capturing. Its counterpart | ||
| 790 | &VIDIOC-STREAMOFF; stops capturing and dequeues all buffers from both | ||
| 791 | queues. Applications can query the signal status, if known, with the | ||
| 792 | &VIDIOC-ENUMINPUT; ioctl.</para></entry> | ||
| 793 | </row> | ||
| 794 | </tbody> | ||
| 795 | </tgroup> | ||
| 796 | </informaltable> | ||
| 797 | |||
| 798 | <para>For a more in-depth discussion of memory mapping and | ||
| 799 | examples, see <xref linkend="mmap" />.</para> | ||
| 800 | </section> | ||
| 801 | </section> | ||
| 802 | |||
| 803 | <section> | ||
| 804 | <title>Reading Raw VBI Data</title> | ||
| 805 | |||
| 806 | <para>Originally the V4L API did not specify a raw VBI capture | ||
| 807 | interface, only the device file <filename>/dev/vbi</filename> was | ||
| 808 | reserved for this purpose. The only driver supporting this interface | ||
| 809 | was the BTTV driver, de-facto defining the V4L VBI interface. Reading | ||
| 810 | from the device yields a raw VBI image with the following | ||
| 811 | parameters:<informaltable> | ||
| 812 | <tgroup cols="2"> | ||
| 813 | <thead> | ||
| 814 | <row> | ||
| 815 | <entry>&v4l2-vbi-format;</entry> | ||
| 816 | <entry>V4L, BTTV driver</entry> | ||
| 817 | </row> | ||
| 818 | </thead> | ||
| 819 | <tbody valign="top"> | ||
| 820 | <row> | ||
| 821 | <entry>sampling_rate</entry> | ||
| 822 | <entry>28636363 Hz NTSC (or any other 525-line | ||
| 823 | standard); 35468950 Hz PAL and SECAM (625-line standards)</entry> | ||
| 824 | </row> | ||
| 825 | <row> | ||
| 826 | <entry>offset</entry> | ||
| 827 | <entry>?</entry> | ||
| 828 | </row> | ||
| 829 | <row> | ||
| 830 | <entry>samples_per_line</entry> | ||
| 831 | <entry>2048</entry> | ||
| 832 | </row> | ||
| 833 | <row> | ||
| 834 | <entry>sample_format</entry> | ||
| 835 | <entry>V4L2_PIX_FMT_GREY. The last four bytes (a | ||
| 836 | machine endianess integer) contain a frame counter.</entry> | ||
| 837 | </row> | ||
| 838 | <row> | ||
| 839 | <entry>start[]</entry> | ||
| 840 | <entry>10, 273 NTSC; 22, 335 PAL and SECAM</entry> | ||
| 841 | </row> | ||
| 842 | <row> | ||
| 843 | <entry>count[]</entry> | ||
| 844 | <entry><para>16, 16<footnote><para>Old driver | ||
| 845 | versions used different values, eventually the custom | ||
| 846 | <constant>BTTV_VBISIZE</constant> ioctl was added to query the | ||
| 847 | correct values.</para></footnote></para></entry> | ||
| 848 | </row> | ||
| 849 | <row> | ||
| 850 | <entry>flags</entry> | ||
| 851 | <entry>0</entry> | ||
| 852 | </row> | ||
| 853 | </tbody> | ||
| 854 | </tgroup> | ||
| 855 | </informaltable></para> | ||
| 856 | |||
| 857 | <para>Undocumented in the V4L specification, in Linux 2.3 the | ||
| 858 | <constant>VIDIOCGVBIFMT</constant> and | ||
| 859 | <constant>VIDIOCSVBIFMT</constant> ioctls using struct | ||
| 860 | <structname>vbi_format</structname> were added to determine the VBI | ||
| 861 | image parameters. These ioctls are only partially compatible with the | ||
| 862 | V4L2 VBI interface specified in <xref linkend="raw-vbi" />.</para> | ||
| 863 | |||
| 864 | <para>An <structfield>offset</structfield> field does not | ||
| 865 | exist, <structfield>sample_format</structfield> is supposed to be | ||
| 866 | <constant>VIDEO_PALETTE_RAW</constant>, equivalent to | ||
| 867 | <constant>V4L2_PIX_FMT_GREY</constant>. The remaining fields are | ||
| 868 | probably equivalent to &v4l2-vbi-format;.</para> | ||
| 869 | |||
| 870 | <para>Apparently only the Zoran (ZR 36120) driver implements | ||
| 871 | these ioctls. The semantics differ from those specified for V4L2 in two | ||
| 872 | ways. The parameters are reset on &func-open; and | ||
| 873 | <constant>VIDIOCSVBIFMT</constant> always returns an &EINVAL; if the | ||
| 874 | parameters are invalid.</para> | ||
| 875 | </section> | ||
| 876 | |||
| 877 | <section> | ||
| 878 | <title>Miscellaneous</title> | ||
| 879 | |||
| 880 | <para>V4L2 has no equivalent of the | ||
| 881 | <constant>VIDIOCGUNIT</constant> ioctl. Applications can find the VBI | ||
| 882 | device associated with a video capture device (or vice versa) by | ||
| 883 | reopening the device and requesting VBI data. For details see | ||
| 884 | <xref linkend="open" />.</para> | ||
| 885 | |||
| 886 | <para>No replacement exists for <constant>VIDIOCKEY</constant>, | ||
| 887 | and the V4L functions for microcode programming. A new interface for | ||
| 888 | MPEG compression and playback devices is documented in <xref | ||
| 889 | linkend="extended-controls" />.</para> | ||
| 890 | </section> | ||
| 891 | |||
| 892 | </section> | ||
| 893 | |||
| 894 | <section id="hist-v4l2"> | ||
| 895 | <title>Changes of the V4L2 API</title> | ||
| 896 | |||
| 897 | <para>Soon after the V4L API was added to the kernel it was | ||
| 898 | criticised as too inflexible. In August 1998 Bill Dirks proposed a | ||
| 899 | number of improvements and began to work on documentation, example | ||
| 900 | drivers and applications. With the help of other volunteers this | ||
| 901 | eventually became the V4L2 API, not just an extension but a | ||
| 902 | replacement for the V4L API. However it took another four years and | ||
| 903 | two stable kernel releases until the new API was finally accepted for | ||
| 904 | inclusion into the kernel in its present form.</para> | ||
| 905 | |||
| 906 | <section> | ||
| 907 | <title>Early Versions</title> | ||
| 908 | <para>1998-08-20: First version.</para> | ||
| 909 | |||
| 910 | <para>1998-08-27: The &func-select; function was introduced.</para> | ||
| 911 | |||
| 912 | <para>1998-09-10: New video standard interface.</para> | ||
| 913 | |||
| 914 | <para>1998-09-18: The <constant>VIDIOC_NONCAP</constant> ioctl | ||
| 915 | was replaced by the otherwise meaningless <constant>O_TRUNC</constant> | ||
| 916 | &func-open; flag, and the aliases <constant>O_NONCAP</constant> and | ||
| 917 | <constant>O_NOIO</constant> were defined. Applications can set this | ||
| 918 | flag if they intend to access controls only, as opposed to capture | ||
| 919 | applications which need exclusive access. The | ||
| 920 | <constant>VIDEO_STD_XXX</constant> identifiers are now ordinals | ||
| 921 | instead of flags, and the <function>video_std_construct()</function> | ||
| 922 | helper function takes id and transmission arguments.</para> | ||
| 923 | |||
| 924 | <para>1998-09-28: Revamped video standard. Made video controls | ||
| 925 | individually enumerable.</para> | ||
| 926 | |||
| 927 | <para>1998-10-02: The <structfield>id</structfield> field was | ||
| 928 | removed from struct <structname>video_standard</structname> and the | ||
| 929 | color subcarrier fields were renamed. The &VIDIOC-QUERYSTD; ioctl was | ||
| 930 | renamed to &VIDIOC-ENUMSTD;, &VIDIOC-G-INPUT; to &VIDIOC-ENUMINPUT;. A | ||
| 931 | first draft of the Codec API was released.</para> | ||
| 932 | |||
| 933 | <para>1998-11-08: Many minor changes. Most symbols have been | ||
| 934 | renamed. Some material changes to &v4l2-capability;.</para> | ||
| 935 | |||
| 936 | <para>1998-11-12: The read/write directon of some ioctls was misdefined.</para> | ||
| 937 | |||
| 938 | <para>1998-11-14: <constant>V4L2_PIX_FMT_RGB24</constant> | ||
| 939 | changed to <constant>V4L2_PIX_FMT_BGR24</constant>, and | ||
| 940 | <constant>V4L2_PIX_FMT_RGB32</constant> changed to | ||
| 941 | <constant>V4L2_PIX_FMT_BGR32</constant>. Audio controls are now | ||
| 942 | accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under | ||
| 943 | names starting with <constant>V4L2_CID_AUDIO</constant>. The | ||
| 944 | <constant>V4L2_MAJOR</constant> define was removed from | ||
| 945 | <filename>videodev.h</filename> since it was only used once in the | ||
| 946 | <filename>videodev</filename> kernel module. The | ||
| 947 | <constant>YUV422</constant> and <constant>YUV411</constant> planar | ||
| 948 | image formats were added.</para> | ||
| 949 | |||
| 950 | <para>1998-11-28: A few ioctl symbols changed. Interfaces for codecs and | ||
| 951 | video output devices were added.</para> | ||
| 952 | |||
| 953 | <para>1999-01-14: A raw VBI capture interface was added.</para> | ||
| 954 | |||
| 955 | <para>1999-01-19: The <constant>VIDIOC_NEXTBUF</constant> ioctl | ||
| 956 | was removed.</para> | ||
| 957 | </section> | ||
| 958 | |||
| 959 | <section> | ||
| 960 | <title>V4L2 Version 0.16 1999-01-31</title> | ||
| 961 | <para>1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF | ||
| 962 | are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added | ||
| 963 | digital zoom (cropping) controls.</para> | ||
| 964 | </section> | ||
| 965 | |||
| 966 | <!-- Where's 0.17? mhs couldn't find that videodev.h, perhaps Bill | ||
| 967 | forgot to bump the version number or never released it. --> | ||
| 968 | |||
| 969 | <section> | ||
| 970 | <title>V4L2 Version 0.18 1999-03-16</title> | ||
| 971 | <para>Added a v4l to V4L2 ioctl compatibility layer to | ||
| 972 | videodev.c. Driver writers, this changes how you implement your ioctl | ||
| 973 | handler. See the Driver Writer's Guide. Added some more control id | ||
| 974 | codes.</para> | ||
| 975 | </section> | ||
| 976 | |||
| 977 | <section> | ||
| 978 | <title>V4L2 Version 0.19 1999-06-05</title> | ||
| 979 | <para>1999-03-18: Fill in the category and catname fields of | ||
| 980 | v4l2_queryctrl objects before passing them to the driver. Required a | ||
| 981 | minor change to the VIDIOC_QUERYCTRL handlers in the sample | ||
| 982 | drivers.</para> | ||
| 983 | <para>1999-03-31: Better compatibility for v4l memory capture | ||
| 984 | ioctls. Requires changes to drivers to fully support new compatibility | ||
| 985 | features, see Driver Writer's Guide and v4l2cap.c. Added new control | ||
| 986 | IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P, | ||
| 987 | and _YUV411P to _YUV411P.</para> | ||
| 988 | <para>1999-04-04: Added a few more control IDs.</para> | ||
| 989 | <para>1999-04-07: Added the button control type.</para> | ||
| 990 | <para>1999-05-02: Fixed a typo in videodev.h, and added the | ||
| 991 | V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</para> | ||
| 992 | <para>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing | ||
| 993 | a malfunction of this ioctl.</para> | ||
| 994 | <para>1999-06-05: Changed the value of | ||
| 995 | V4L2_CID_WHITENESS.</para> | ||
| 996 | </section> | ||
| 997 | |||
| 998 | <section> | ||
| 999 | <title>V4L2 Version 0.20 (1999-09-10)</title> | ||
| 1000 | |||
| 1001 | <para>Version 0.20 introduced a number of changes which were | ||
| 1002 | <emphasis>not backward compatible</emphasis> with 0.19 and earlier | ||
| 1003 | versions. Purpose of these changes was to simplify the API, while | ||
| 1004 | making it more extensible and following common Linux driver API | ||
| 1005 | conventions.</para> | ||
| 1006 | |||
| 1007 | <orderedlist> | ||
| 1008 | <listitem> | ||
| 1009 | <para>Some typos in <constant>V4L2_FMT_FLAG</constant> | ||
| 1010 | symbols were fixed. &v4l2-clip; was changed for compatibility with | ||
| 1011 | v4l. (1999-08-30)</para> | ||
| 1012 | </listitem> | ||
| 1013 | |||
| 1014 | <listitem> | ||
| 1015 | <para><constant>V4L2_TUNER_SUB_LANG1</constant> was added. | ||
| 1016 | (1999-09-05)</para> | ||
| 1017 | </listitem> | ||
| 1018 | |||
| 1019 | <listitem> | ||
| 1020 | <para>All ioctl() commands that used an integer argument now | ||
| 1021 | take a pointer to an integer. Where it makes sense, ioctls will return | ||
| 1022 | the actual new value in the integer pointed to by the argument, a | ||
| 1023 | common convention in the V4L2 API. The affected ioctls are: | ||
| 1024 | VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, | ||
| 1025 | VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example | ||
| 1026 | <programlisting> | ||
| 1027 | err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); | ||
| 1028 | </programlisting> becomes <programlisting> | ||
| 1029 | int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a); | ||
| 1030 | </programlisting> | ||
| 1031 | </para> | ||
| 1032 | </listitem> | ||
| 1033 | |||
| 1034 | <listitem> | ||
| 1035 | <para>All the different get- and set-format commands were | ||
| 1036 | swept into one &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctl taking a union | ||
| 1037 | and a type field selecting the union member as parameter. Purpose is to | ||
| 1038 | simplify the API by eliminating several ioctls and to allow new and | ||
| 1039 | driver private data streams without adding new ioctls.</para> | ||
| 1040 | |||
| 1041 | <para>This change obsoletes the following ioctls: | ||
| 1042 | <constant>VIDIOC_S_INFMT</constant>, | ||
| 1043 | <constant>VIDIOC_G_INFMT</constant>, | ||
| 1044 | <constant>VIDIOC_S_OUTFMT</constant>, | ||
| 1045 | <constant>VIDIOC_G_OUTFMT</constant>, | ||
| 1046 | <constant>VIDIOC_S_VBIFMT</constant> and | ||
| 1047 | <constant>VIDIOC_G_VBIFMT</constant>. The image format structure | ||
| 1048 | <structname>v4l2_format</structname> was renamed to &v4l2-pix-format;, | ||
| 1049 | while &v4l2-format; is now the envelopping structure for all format | ||
| 1050 | negotiations.</para> | ||
| 1051 | </listitem> | ||
| 1052 | |||
| 1053 | <listitem> | ||
| 1054 | <para>Similar to the changes above, the | ||
| 1055 | <constant>VIDIOC_G_PARM</constant> and | ||
| 1056 | <constant>VIDIOC_S_PARM</constant> ioctls were merged with | ||
| 1057 | <constant>VIDIOC_G_OUTPARM</constant> and | ||
| 1058 | <constant>VIDIOC_S_OUTPARM</constant>. A | ||
| 1059 | <structfield>type</structfield> field in the new &v4l2-streamparm; | ||
| 1060 | selects the respective union member.</para> | ||
| 1061 | |||
| 1062 | <para>This change obsoletes the | ||
| 1063 | <constant>VIDIOC_G_OUTPARM</constant> and | ||
| 1064 | <constant>VIDIOC_S_OUTPARM</constant> ioctls.</para> | ||
| 1065 | </listitem> | ||
| 1066 | |||
| 1067 | <listitem> | ||
| 1068 | <para>Control enumeration was simplified, and two new | ||
| 1069 | control flags were introduced and one dropped. The | ||
| 1070 | <structfield>catname</structfield> field was replaced by a | ||
| 1071 | <structfield>group</structfield> field.</para> | ||
| 1072 | |||
| 1073 | <para>Drivers can now flag unsupported and temporarily | ||
| 1074 | unavailable controls with <constant>V4L2_CTRL_FLAG_DISABLED</constant> | ||
| 1075 | and <constant>V4L2_CTRL_FLAG_GRABBED</constant> respectively. The | ||
| 1076 | <structfield>group</structfield> name indicates a possibly narrower | ||
| 1077 | classification than the <structfield>category</structfield>. In other | ||
| 1078 | words, there may be multiple groups within a category. Controls within | ||
| 1079 | a group would typically be drawn within a group box. Controls in | ||
| 1080 | different categories might have a greater separation, or may even | ||
| 1081 | appear in separate windows.</para> | ||
| 1082 | </listitem> | ||
| 1083 | |||
| 1084 | <listitem> | ||
| 1085 | <para>The &v4l2-buffer; <structfield>timestamp</structfield> | ||
| 1086 | was changed to a 64 bit integer, containing the sampling or output | ||
| 1087 | time of the frame in nanoseconds. Additionally timestamps will be in | ||
| 1088 | absolute system time, not starting from zero at the beginning of a | ||
| 1089 | stream. The data type name for timestamps is stamp_t, defined as a | ||
| 1090 | signed 64-bit integer. Output devices should not send a buffer out | ||
| 1091 | until the time in the timestamp field has arrived. I would like to | ||
| 1092 | follow SGI's lead, and adopt a multimedia timestamping system like | ||
| 1093 | their UST (Unadjusted System Time). See | ||
| 1094 | http://reality.sgi.com/cpirazzi_engr/lg/time/intro.html. [This link is | ||
| 1095 | no longer valid.] UST uses timestamps that are 64-bit signed integers | ||
| 1096 | (not struct timeval's) and given in nanosecond units. The UST clock | ||
| 1097 | starts at zero when the system is booted and runs continuously and | ||
| 1098 | uniformly. It takes a little over 292 years for UST to overflow. There | ||
| 1099 | is no way to set the UST clock. The regular Linux time-of-day clock | ||
| 1100 | can be changed periodically, which would cause errors if it were being | ||
| 1101 | used for timestamping a multimedia stream. A real UST style clock will | ||
| 1102 | require some support in the kernel that is not there yet. But in | ||
| 1103 | anticipation, I will change the timestamp field to a 64-bit integer, | ||
| 1104 | and I will change the v4l2_masterclock_gettime() function (used only | ||
| 1105 | by drivers) to return a 64-bit integer.</para> | ||
| 1106 | </listitem> | ||
| 1107 | |||
| 1108 | <listitem> | ||
| 1109 | <para>A <structfield>sequence</structfield> field was added | ||
| 1110 | to &v4l2-buffer;. The <structfield>sequence</structfield> field counts | ||
| 1111 | captured frames, it is ignored by output devices. When a capture | ||
| 1112 | driver drops a frame, the sequence number of that frame is | ||
| 1113 | skipped.</para> | ||
| 1114 | </listitem> | ||
| 1115 | </orderedlist> | ||
| 1116 | </section> | ||
| 1117 | |||
| 1118 | <section> | ||
| 1119 | <title>V4L2 Version 0.20 incremental changes</title> | ||
| 1120 | <!-- Version number didn't change anymore, reason unknown. --> | ||
| 1121 | |||
| 1122 | <para>1999-12-23: In &v4l2-vbi-format; the | ||
| 1123 | <structfield>reserved1</structfield> field became | ||
| 1124 | <structfield>offset</structfield>. Previously drivers were required to | ||
| 1125 | clear the <structfield>reserved1</structfield> field.</para> | ||
| 1126 | |||
| 1127 | <para>2000-01-13: The | ||
| 1128 | <constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant> flag was added.</para> | ||
| 1129 | |||
| 1130 | <para>2000-07-31: The <filename>linux/poll.h</filename> header | ||
| 1131 | is now included by <filename>videodev.h</filename> for compatibility | ||
| 1132 | with the original <filename>videodev.h</filename> file.</para> | ||
| 1133 | |||
| 1134 | <para>2000-11-20: <constant>V4L2_TYPE_VBI_OUTPUT</constant> and | ||
| 1135 | <constant>V4L2_PIX_FMT_Y41P</constant> were added.</para> | ||
| 1136 | |||
| 1137 | <para>2000-11-25: <constant>V4L2_TYPE_VBI_INPUT</constant> was | ||
| 1138 | added.</para> | ||
| 1139 | |||
| 1140 | <para>2000-12-04: A couple typos in symbol names were fixed.</para> | ||
| 1141 | |||
| 1142 | <para>2001-01-18: To avoid namespace conflicts the | ||
| 1143 | <constant>fourcc</constant> macro defined in the | ||
| 1144 | <filename>videodev.h</filename> header file was renamed to | ||
| 1145 | <constant>v4l2_fourcc</constant>.</para> | ||
| 1146 | |||
| 1147 | <para>2001-01-25: A possible driver-level compatibility problem | ||
| 1148 | between the <filename>videodev.h</filename> file in Linux 2.4.0 and | ||
| 1149 | the <filename>videodev.h</filename> file included in the | ||
| 1150 | <filename>videodevX</filename> patch was fixed. Users of an earlier | ||
| 1151 | version of <filename>videodevX</filename> on Linux 2.4.0 should | ||
| 1152 | recompile their V4L and V4L2 drivers.</para> | ||
| 1153 | |||
| 1154 | <para>2001-01-26: A possible kernel-level incompatibility | ||
| 1155 | between the <filename>videodev.h</filename> file in the | ||
| 1156 | <filename>videodevX</filename> patch and the | ||
| 1157 | <filename>videodev.h</filename> file in Linux 2.2.x with devfs patches | ||
| 1158 | applied was fixed.</para> | ||
| 1159 | |||
| 1160 | <para>2001-03-02: Certain V4L ioctls which pass data in both | ||
| 1161 | direction although they are defined with read-only parameter, did not | ||
| 1162 | work correctly through the backward compatibility layer. | ||
| 1163 | [Solution?]</para> | ||
| 1164 | |||
| 1165 | <para>2001-04-13: Big endian 16-bit RGB formats were added.</para> | ||
| 1166 | |||
| 1167 | <para>2001-09-17: New YUV formats and the &VIDIOC-G-FREQUENCY; and | ||
| 1168 | &VIDIOC-S-FREQUENCY; ioctls were added. (The old | ||
| 1169 | <constant>VIDIOC_G_FREQ</constant> and | ||
| 1170 | <constant>VIDIOC_S_FREQ</constant> ioctls did not take multiple tuners | ||
| 1171 | into account.)</para> | ||
| 1172 | |||
| 1173 | <para>2000-09-18: <constant>V4L2_BUF_TYPE_VBI</constant> was | ||
| 1174 | added. This may <emphasis>break compatibility</emphasis> as the | ||
| 1175 | &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls may fail now if the struct | ||
| 1176 | <structname>v4l2_fmt</structname> <structfield>type</structfield> | ||
| 1177 | field does not contain <constant>V4L2_BUF_TYPE_VBI</constant>. In the | ||
| 1178 | documentation of the &v4l2-vbi-format; | ||
| 1179 | <structfield>offset</structfield> field the ambiguous phrase "rising | ||
| 1180 | edge" was changed to "leading edge".</para> | ||
| 1181 | </section> | ||
| 1182 | |||
| 1183 | <section> | ||
| 1184 | <title>V4L2 Version 0.20 2000-11-23</title> | ||
| 1185 | |||
| 1186 | <para>A number of changes were made to the raw VBI | ||
| 1187 | interface.</para> | ||
| 1188 | |||
| 1189 | <orderedlist> | ||
| 1190 | <listitem> | ||
| 1191 | <para>Figures clarifying the line numbering scheme were | ||
| 1192 | added to the V4L2 API specification. The | ||
| 1193 | <structfield>start</structfield>[0] and | ||
| 1194 | <structfield>start</structfield>[1] fields no longer count line | ||
| 1195 | numbers beginning at zero. Rationale: a) The previous definition was | ||
| 1196 | unclear. b) The <structfield>start</structfield>[] values are ordinal | ||
| 1197 | numbers. c) There is no point in inventing a new line numbering | ||
| 1198 | scheme. We now use line number as defined by ITU-R, period. | ||
| 1199 | Compatibility: Add one to the start values. Applications depending on | ||
| 1200 | the previous semantics may not function correctly.</para> | ||
| 1201 | </listitem> | ||
| 1202 | |||
| 1203 | <listitem> | ||
| 1204 | <para>The restriction "count[0] > 0 and count[1] > 0" | ||
| 1205 | has been relaxed to "(count[0] + count[1]) > 0". Rationale: | ||
| 1206 | Drivers may allocate resources at scan line granularity and some data | ||
| 1207 | services are transmitted only on the first field. The comment that | ||
| 1208 | both <structfield>count</structfield> values will usually be equal is | ||
| 1209 | misleading and pointless and has been removed. This change | ||
| 1210 | <emphasis>breaks compatibility</emphasis> with earlier versions: | ||
| 1211 | Drivers may return EINVAL, applications may not function | ||
| 1212 | correctly.</para> | ||
| 1213 | </listitem> | ||
| 1214 | |||
| 1215 | <listitem> | ||
| 1216 | <para>Drivers are again permitted to return negative | ||
| 1217 | (unknown) start values as proposed earlier. Why this feature was | ||
| 1218 | dropped is unclear. This change may <emphasis>break | ||
| 1219 | compatibility</emphasis> with applications depending on the start | ||
| 1220 | values being positive. The use of <constant>EBUSY</constant> and | ||
| 1221 | <constant>EINVAL</constant> error codes with the &VIDIOC-S-FMT; ioctl | ||
| 1222 | was clarified. The &EBUSY; was finally documented, and the | ||
| 1223 | <structfield>reserved2</structfield> field which was previously | ||
| 1224 | mentioned only in the <filename>videodev.h</filename> header | ||
| 1225 | file.</para> | ||
| 1226 | </listitem> | ||
| 1227 | |||
| 1228 | <listitem> | ||
| 1229 | <para>New buffer types | ||
| 1230 | <constant>V4L2_TYPE_VBI_INPUT</constant> and | ||
| 1231 | <constant>V4L2_TYPE_VBI_OUTPUT</constant> were added. The former is an | ||
| 1232 | alias for the old <constant>V4L2_TYPE_VBI</constant>, the latter was | ||
| 1233 | missing in the <filename>videodev.h</filename> file.</para> | ||
| 1234 | </listitem> | ||
| 1235 | </orderedlist> | ||
| 1236 | </section> | ||
| 1237 | |||
| 1238 | <section> | ||
| 1239 | <title>V4L2 Version 0.20 2002-07-25</title> | ||
| 1240 | <para>Added sliced VBI interface proposal.</para> | ||
| 1241 | </section> | ||
| 1242 | |||
| 1243 | <section> | ||
| 1244 | <title>V4L2 in Linux 2.5.46, 2002-10</title> | ||
| 1245 | |||
| 1246 | <para>Around October-November 2002, prior to an announced | ||
| 1247 | feature freeze of Linux 2.5, the API was revised, drawing from | ||
| 1248 | experience with V4L2 0.20. This unnamed version was finally merged | ||
| 1249 | into Linux 2.5.46.</para> | ||
| 1250 | |||
| 1251 | <orderedlist> | ||
| 1252 | <listitem> | ||
| 1253 | <para>As specified in <xref linkend="related" />, drivers | ||
| 1254 | must make related device functions available under all minor device | ||
| 1255 | numbers.</para> | ||
| 1256 | </listitem> | ||
| 1257 | |||
| 1258 | <listitem> | ||
| 1259 | <para>The &func-open; function requires access mode | ||
| 1260 | <constant>O_RDWR</constant> regardless of the device type. All V4L2 | ||
| 1261 | drivers exchanging data with applications must support the | ||
| 1262 | <constant>O_NONBLOCK</constant> flag. The <constant>O_NOIO</constant> | ||
| 1263 | flag, a V4L2 symbol which aliased the meaningless | ||
| 1264 | <constant>O_TRUNC</constant> to indicate accesses without data | ||
| 1265 | exchange (panel applications) was dropped. Drivers must stay in "panel | ||
| 1266 | mode" until the application attempts to initiate a data exchange, see | ||
| 1267 | <xref linkend="open" />.</para> | ||
| 1268 | </listitem> | ||
| 1269 | |||
| 1270 | <listitem> | ||
| 1271 | <para>The &v4l2-capability; changed dramatically. Note that | ||
| 1272 | also the size of the structure changed, which is encoded in the ioctl | ||
| 1273 | request code, thus older V4L2 devices will respond with an &EINVAL; to | ||
| 1274 | the new &VIDIOC-QUERYCAP; ioctl.</para> | ||
| 1275 | |||
| 1276 | <para>There are new fields to identify the driver, a new RDS | ||
| 1277 | device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the | ||
| 1278 | <constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has | ||
| 1279 | any audio connectors, another I/O capability | ||
| 1280 | <constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to | ||
| 1281 | these changes the <structfield>type</structfield> field became a bit | ||
| 1282 | set and was merged into the <structfield>flags</structfield> field. | ||
| 1283 | <constant>V4L2_FLAG_TUNER</constant> was renamed to | ||
| 1284 | <constant>V4L2_CAP_TUNER</constant>, | ||
| 1285 | <constant>V4L2_CAP_VIDEO_OVERLAY</constant> replaced | ||
| 1286 | <constant>V4L2_FLAG_PREVIEW</constant> and | ||
| 1287 | <constant>V4L2_CAP_VBI_CAPTURE</constant> and | ||
| 1288 | <constant>V4L2_CAP_VBI_OUTPUT</constant> replaced | ||
| 1289 | <constant>V4L2_FLAG_DATA_SERVICE</constant>. | ||
| 1290 | <constant>V4L2_FLAG_READ</constant> and | ||
| 1291 | <constant>V4L2_FLAG_WRITE</constant> were merged into | ||
| 1292 | <constant>V4L2_CAP_READWRITE</constant>.</para> | ||
| 1293 | |||
| 1294 | <para>The redundant fields | ||
| 1295 | <structfield>inputs</structfield>, <structfield>outputs</structfield> | ||
| 1296 | and <structfield>audios</structfield> were removed. These properties | ||
| 1297 | can be determined as described in <xref linkend="video" /> and <xref | ||
| 1298 | linkend="audio" />.</para> | ||
| 1299 | |||
| 1300 | <para>The somewhat volatile and therefore barely useful | ||
| 1301 | fields <structfield>maxwidth</structfield>, | ||
| 1302 | <structfield>maxheight</structfield>, | ||
| 1303 | <structfield>minwidth</structfield>, | ||
| 1304 | <structfield>minheight</structfield>, | ||
| 1305 | <structfield>maxframerate</structfield> were removed. This information | ||
| 1306 | is available as described in <xref linkend="format" /> and | ||
| 1307 | <xref linkend="standard" />.</para> | ||
| 1308 | |||
| 1309 | <para><constant>V4L2_FLAG_SELECT</constant> was removed. We | ||
| 1310 | believe the select() function is important enough to require support | ||
| 1311 | of it in all V4L2 drivers exchanging data with applications. The | ||
| 1312 | redundant <constant>V4L2_FLAG_MONOCHROME</constant> flag was removed, | ||
| 1313 | this information is available as described in <xref | ||
| 1314 | linkend="format" />.</para> | ||
| 1315 | </listitem> | ||
| 1316 | |||
| 1317 | <listitem> | ||
| 1318 | <para>In &v4l2-input; the | ||
| 1319 | <structfield>assoc_audio</structfield> field and the | ||
| 1320 | <structfield>capability</structfield> field and its only flag | ||
| 1321 | <constant>V4L2_INPUT_CAP_AUDIO</constant> was replaced by the new | ||
| 1322 | <structfield>audioset</structfield> field. Instead of linking one | ||
| 1323 | video input to one audio input this field reports all audio inputs | ||
| 1324 | this video input combines with.</para> | ||
| 1325 | |||
| 1326 | <para>New fields are <structfield>tuner</structfield> | ||
| 1327 | (reversing the former link from tuners to video inputs), | ||
| 1328 | <structfield>std</structfield> and | ||
| 1329 | <structfield>status</structfield>.</para> | ||
| 1330 | |||
| 1331 | <para>Accordingly &v4l2-output; lost its | ||
| 1332 | <structfield>capability</structfield> and | ||
| 1333 | <structfield>assoc_audio</structfield> fields. | ||
| 1334 | <structfield>audioset</structfield>, | ||
| 1335 | <structfield>modulator</structfield> and | ||
| 1336 | <structfield>std</structfield> where added instead.</para> | ||
| 1337 | </listitem> | ||
| 1338 | |||
| 1339 | <listitem> | ||
| 1340 | <para>The &v4l2-audio; field | ||
| 1341 | <structfield>audio</structfield> was renamed to | ||
| 1342 | <structfield>index</structfield>, for consistency with other | ||
| 1343 | structures. A new capability flag | ||
| 1344 | <constant>V4L2_AUDCAP_STEREO</constant> was added to indicated if the | ||
| 1345 | audio input in question supports stereo sound. | ||
| 1346 | <constant>V4L2_AUDCAP_EFFECTS</constant> and the corresponding | ||
| 1347 | <constant>V4L2_AUDMODE</constant> flags where removed. This can be | ||
| 1348 | easily implemented using controls. (However the same applies to AVL | ||
| 1349 | which is still there.)</para> | ||
| 1350 | |||
| 1351 | <para>Again for consistency the &v4l2-audioout; field | ||
| 1352 | <structfield>audio</structfield> was renamed to | ||
| 1353 | <structfield>index</structfield>.</para> | ||
| 1354 | </listitem> | ||
| 1355 | |||
| 1356 | <listitem> | ||
| 1357 | <para>The &v4l2-tuner; | ||
| 1358 | <structfield>input</structfield> field was replaced by an | ||
| 1359 | <structfield>index</structfield> field, permitting devices with | ||
| 1360 | multiple tuners. The link between video inputs and tuners is now | ||
| 1361 | reversed, inputs point to their tuner. The | ||
| 1362 | <structfield>std</structfield> substructure became a | ||
| 1363 | simple set (more about this below) and moved into &v4l2-input;. A | ||
| 1364 | <structfield>type</structfield> field was added.</para> | ||
| 1365 | |||
| 1366 | <para>Accordingly in &v4l2-modulator; the | ||
| 1367 | <structfield>output</structfield> was replaced by an | ||
| 1368 | <structfield>index</structfield> field.</para> | ||
| 1369 | |||
| 1370 | <para>In &v4l2-frequency; the | ||
| 1371 | <structfield>port</structfield> field was replaced by a | ||
| 1372 | <structfield>tuner</structfield> field containing the respective tuner | ||
| 1373 | or modulator index number. A tuner <structfield>type</structfield> | ||
| 1374 | field was added and the <structfield>reserved</structfield> field | ||
| 1375 | became larger for future extensions (satellite tuners in | ||
| 1376 | particular).</para> | ||
| 1377 | </listitem> | ||
| 1378 | |||
| 1379 | <listitem> | ||
| 1380 | <para>The idea of completely transparent video standards was | ||
| 1381 | dropped. Experience showed that applications must be able to work with | ||
| 1382 | video standards beyond presenting the user a menu. Instead of | ||
| 1383 | enumerating supported standards with an ioctl applications can now | ||
| 1384 | refer to standards by &v4l2-std-id; and symbols defined in the | ||
| 1385 | <filename>videodev2.h</filename> header file. For details see <xref | ||
| 1386 | linkend="standard" />. The &VIDIOC-G-STD; and | ||
| 1387 | &VIDIOC-S-STD; now take a pointer to this type as argument. | ||
| 1388 | &VIDIOC-QUERYSTD; was added to autodetect the received standard, if | ||
| 1389 | the hardware has this capability. In &v4l2-standard; an | ||
| 1390 | <structfield>index</structfield> field was added for &VIDIOC-ENUMSTD;. | ||
| 1391 | A &v4l2-std-id; field named <structfield>id</structfield> was added as | ||
| 1392 | machine readable identifier, also replacing the | ||
| 1393 | <structfield>transmission</structfield> field. The misleading | ||
| 1394 | <structfield>framerate</structfield> field was renamed | ||
| 1395 | to <structfield>frameperiod</structfield>. The now obsolete | ||
| 1396 | <structfield>colorstandard</structfield> information, originally | ||
| 1397 | needed to distguish between variations of standards, were | ||
| 1398 | removed.</para> | ||
| 1399 | |||
| 1400 | <para>Struct <structname>v4l2_enumstd</structname> ceased to | ||
| 1401 | be. &VIDIOC-ENUMSTD; now takes a pointer to a &v4l2-standard; | ||
| 1402 | directly. The information which standards are supported by a | ||
| 1403 | particular video input or output moved into &v4l2-input; and | ||
| 1404 | &v4l2-output; fields named <structfield>std</structfield>, | ||
| 1405 | respectively.</para> | ||
| 1406 | </listitem> | ||
| 1407 | |||
| 1408 | <listitem> | ||
| 1409 | <para>The &v4l2-queryctrl; fields | ||
| 1410 | <structfield>category</structfield> and | ||
| 1411 | <structfield>group</structfield> did not catch on and/or were not | ||
| 1412 | implemented as expected and therefore removed.</para> | ||
| 1413 | </listitem> | ||
| 1414 | |||
| 1415 | <listitem> | ||
| 1416 | <para>The &VIDIOC-TRY-FMT; ioctl was added to negotiate data | ||
| 1417 | formats as with &VIDIOC-S-FMT;, but without the overhead of | ||
| 1418 | programming the hardware and regardless of I/O in progress.</para> | ||
| 1419 | |||
| 1420 | <para>In &v4l2-format; the <structfield>fmt</structfield> | ||
| 1421 | union was extended to contain &v4l2-window;. All image format | ||
| 1422 | negotiations are now possible with <constant>VIDIOC_G_FMT</constant>, | ||
| 1423 | <constant>VIDIOC_S_FMT</constant> and | ||
| 1424 | <constant>VIDIOC_TRY_FMT</constant>; ioctl. The | ||
| 1425 | <constant>VIDIOC_G_WIN</constant> and | ||
| 1426 | <constant>VIDIOC_S_WIN</constant> ioctls to prepare for a video | ||
| 1427 | overlay were removed. The <structfield>type</structfield> field | ||
| 1428 | changed to type &v4l2-buf-type; and the buffer type names changed as | ||
| 1429 | follows.<informaltable> | ||
| 1430 | <tgroup cols="2"> | ||
| 1431 | <thead> | ||
| 1432 | <row> | ||
| 1433 | <entry>Old defines</entry> | ||
| 1434 | <entry>&v4l2-buf-type;</entry> | ||
| 1435 | </row> | ||
| 1436 | </thead> | ||
| 1437 | <tbody valign="top"> | ||
| 1438 | <row> | ||
| 1439 | <entry><constant>V4L2_BUF_TYPE_CAPTURE</constant></entry> | ||
| 1440 | <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> | ||
| 1441 | </row> | ||
| 1442 | <row> | ||
| 1443 | <entry><constant>V4L2_BUF_TYPE_CODECIN</constant></entry> | ||
| 1444 | <entry>Omitted for now</entry> | ||
| 1445 | </row> | ||
| 1446 | <row> | ||
| 1447 | <entry><constant>V4L2_BUF_TYPE_CODECOUT</constant></entry> | ||
| 1448 | <entry>Omitted for now</entry> | ||
| 1449 | </row> | ||
| 1450 | <row> | ||
| 1451 | <entry><constant>V4L2_BUF_TYPE_EFFECTSIN</constant></entry> | ||
| 1452 | <entry>Omitted for now</entry> | ||
| 1453 | </row> | ||
| 1454 | <row> | ||
| 1455 | <entry><constant>V4L2_BUF_TYPE_EFFECTSIN2</constant></entry> | ||
| 1456 | <entry>Omitted for now</entry> | ||
| 1457 | </row> | ||
| 1458 | <row> | ||
| 1459 | <entry><constant>V4L2_BUF_TYPE_EFFECTSOUT</constant></entry> | ||
| 1460 | <entry>Omitted for now</entry> | ||
| 1461 | </row> | ||
| 1462 | <row> | ||
| 1463 | <entry><constant>V4L2_BUF_TYPE_VIDEOOUT</constant></entry> | ||
| 1464 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> | ||
| 1465 | </row> | ||
| 1466 | <row> | ||
| 1467 | <entry><constant>-</constant></entry> | ||
| 1468 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> | ||
| 1469 | </row> | ||
| 1470 | <row> | ||
| 1471 | <entry><constant>-</constant></entry> | ||
| 1472 | <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> | ||
| 1473 | </row> | ||
| 1474 | <row> | ||
| 1475 | <entry><constant>-</constant></entry> | ||
| 1476 | <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> | ||
| 1477 | </row> | ||
| 1478 | <row> | ||
| 1479 | <entry><constant>-</constant></entry> | ||
| 1480 | <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> | ||
| 1481 | </row> | ||
| 1482 | <row> | ||
| 1483 | <entry><constant>-</constant></entry> | ||
| 1484 | <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> | ||
| 1485 | </row> | ||
| 1486 | <row> | ||
| 1487 | <entry><constant>V4L2_BUF_TYPE_PRIVATE_BASE</constant></entry> | ||
| 1488 | <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry> | ||
| 1489 | </row> | ||
| 1490 | </tbody> | ||
| 1491 | </tgroup> | ||
| 1492 | </informaltable></para> | ||
| 1493 | </listitem> | ||
| 1494 | |||
| 1495 | <listitem> | ||
| 1496 | <para>In &v4l2-fmtdesc; a &v4l2-buf-type; field named | ||
| 1497 | <structfield>type</structfield> was added as in &v4l2-format;. The | ||
| 1498 | <constant>VIDIOC_ENUM_FBUFFMT</constant> ioctl is no longer needed and | ||
| 1499 | was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with | ||
| 1500 | type <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para> | ||
| 1501 | </listitem> | ||
| 1502 | |||
| 1503 | <listitem> | ||
| 1504 | <para>In &v4l2-pix-format; the | ||
| 1505 | <structfield>depth</structfield> field was removed, assuming | ||
| 1506 | applications which recognize the format by its four-character-code | ||
| 1507 | already know the color depth, and others do not care about it. The | ||
| 1508 | same rationale lead to the removal of the | ||
| 1509 | <constant>V4L2_FMT_FLAG_COMPRESSED</constant> flag. The | ||
| 1510 | <constant>V4L2_FMT_FLAG_SWCONVECOMPRESSED</constant> flag was removed | ||
| 1511 | because drivers are not supposed to convert images in kernel space. A | ||
| 1512 | user library of conversion functions should be provided instead. The | ||
| 1513 | <constant>V4L2_FMT_FLAG_BYTESPERLINE</constant> flag was redundant. | ||
| 1514 | Applications can set the <structfield>bytesperline</structfield> field | ||
| 1515 | to zero to get a reasonable default. Since the remaining flags were | ||
| 1516 | replaced as well, the <structfield>flags</structfield> field itself | ||
| 1517 | was removed.</para> | ||
| 1518 | <para>The interlace flags were replaced by a &v4l2-field; | ||
| 1519 | value in a newly added <structfield>field</structfield> | ||
| 1520 | field.<informaltable> | ||
| 1521 | <tgroup cols="2"> | ||
| 1522 | <thead> | ||
| 1523 | <row> | ||
| 1524 | <entry>Old flag</entry> | ||
| 1525 | <entry>&v4l2-field;</entry> | ||
| 1526 | </row> | ||
| 1527 | </thead> | ||
| 1528 | <tbody valign="top"> | ||
| 1529 | <row> | ||
| 1530 | <entry><constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant></entry> | ||
| 1531 | <entry>?</entry> | ||
| 1532 | </row> | ||
| 1533 | <row> | ||
| 1534 | <entry><constant>V4L2_FMT_FLAG_INTERLACED</constant> | ||
| 1535 | = <constant>V4L2_FMT_FLAG_COMBINED</constant></entry> | ||
| 1536 | <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> | ||
| 1537 | </row> | ||
| 1538 | <row> | ||
| 1539 | <entry><constant>V4L2_FMT_FLAG_TOPFIELD</constant> | ||
| 1540 | = <constant>V4L2_FMT_FLAG_ODDFIELD</constant></entry> | ||
| 1541 | <entry><constant>V4L2_FIELD_TOP</constant></entry> | ||
| 1542 | </row> | ||
| 1543 | <row> | ||
| 1544 | <entry><constant>V4L2_FMT_FLAG_BOTFIELD</constant> | ||
| 1545 | = <constant>V4L2_FMT_FLAG_EVENFIELD</constant></entry> | ||
| 1546 | <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> | ||
| 1547 | </row> | ||
| 1548 | <row> | ||
| 1549 | <entry><constant>-</constant></entry> | ||
| 1550 | <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> | ||
| 1551 | </row> | ||
| 1552 | <row> | ||
| 1553 | <entry><constant>-</constant></entry> | ||
| 1554 | <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> | ||
| 1555 | </row> | ||
| 1556 | <row> | ||
| 1557 | <entry><constant>-</constant></entry> | ||
| 1558 | <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> | ||
| 1559 | </row> | ||
| 1560 | </tbody> | ||
| 1561 | </tgroup> | ||
| 1562 | </informaltable></para> | ||
| 1563 | |||
| 1564 | <para>The color space flags were replaced by a | ||
| 1565 | &v4l2-colorspace; value in a newly added | ||
| 1566 | <structfield>colorspace</structfield> field, where one of | ||
| 1567 | <constant>V4L2_COLORSPACE_SMPTE170M</constant>, | ||
| 1568 | <constant>V4L2_COLORSPACE_BT878</constant>, | ||
| 1569 | <constant>V4L2_COLORSPACE_470_SYSTEM_M</constant> or | ||
| 1570 | <constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant> replaces | ||
| 1571 | <constant>V4L2_FMT_CS_601YUV</constant>.</para> | ||
| 1572 | </listitem> | ||
| 1573 | |||
| 1574 | <listitem> | ||
| 1575 | <para>In &v4l2-requestbuffers; the | ||
| 1576 | <structfield>type</structfield> field was properly defined as | ||
| 1577 | &v4l2-buf-type;. Buffer types changed as mentioned above. A new | ||
| 1578 | <structfield>memory</structfield> field of type &v4l2-memory; was | ||
| 1579 | added to distinguish between I/O methods using buffers allocated | ||
| 1580 | by the driver or the application. See <xref linkend="io" /> for | ||
| 1581 | details.</para> | ||
| 1582 | </listitem> | ||
| 1583 | |||
| 1584 | <listitem> | ||
| 1585 | <para>In &v4l2-buffer; the <structfield>type</structfield> | ||
| 1586 | field was properly defined as &v4l2-buf-type;. Buffer types changed as | ||
| 1587 | mentioned above. A <structfield>field</structfield> field of type | ||
| 1588 | &v4l2-field; was added to indicate if a buffer contains a top or | ||
| 1589 | bottom field. The old field flags were removed. Since no unadjusted | ||
| 1590 | system time clock was added to the kernel as planned, the | ||
| 1591 | <structfield>timestamp</structfield> field changed back from type | ||
| 1592 | stamp_t, an unsigned 64 bit integer expressing the sample time in | ||
| 1593 | nanoseconds, to struct <structname>timeval</structname>. With the | ||
| 1594 | addition of a second memory mapping method the | ||
| 1595 | <structfield>offset</structfield> field moved into union | ||
| 1596 | <structfield>m</structfield>, and a new | ||
| 1597 | <structfield>memory</structfield> field of type &v4l2-memory; was | ||
| 1598 | added to distinguish between I/O methods. See <xref linkend="io" /> | ||
| 1599 | for details.</para> | ||
| 1600 | |||
| 1601 | <para>The <constant>V4L2_BUF_REQ_CONTIG</constant> | ||
| 1602 | flag was used by the V4L compatibility layer, after changes to this | ||
| 1603 | code it was no longer needed. The | ||
| 1604 | <constant>V4L2_BUF_ATTR_DEVICEMEM</constant> flag would indicate if | ||
| 1605 | the buffer was indeed allocated in device memory rather than DMA-able | ||
| 1606 | system memory. It was barely useful and so was removed.</para> | ||
| 1607 | </listitem> | ||
| 1608 | |||
| 1609 | <listitem> | ||
| 1610 | <para>In &v4l2-framebuffer; the | ||
| 1611 | <structfield>base[3]</structfield> array anticipating double- and | ||
| 1612 | triple-buffering in off-screen video memory, however without defining | ||
| 1613 | a synchronization mechanism, was replaced by a single pointer. The | ||
| 1614 | <constant>V4L2_FBUF_CAP_SCALEUP</constant> and | ||
| 1615 | <constant>V4L2_FBUF_CAP_SCALEDOWN</constant> flags were removed. | ||
| 1616 | Applications can determine this capability more accurately using the | ||
| 1617 | new cropping and scaling interface. The | ||
| 1618 | <constant>V4L2_FBUF_CAP_CLIPPING</constant> flag was replaced by | ||
| 1619 | <constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> and | ||
| 1620 | <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant>.</para> | ||
| 1621 | </listitem> | ||
| 1622 | |||
| 1623 | <listitem> | ||
| 1624 | <para>In &v4l2-clip; the <structfield>x</structfield>, | ||
| 1625 | <structfield>y</structfield>, <structfield>width</structfield> and | ||
| 1626 | <structfield>height</structfield> field moved into a | ||
| 1627 | <structfield>c</structfield> substructure of type &v4l2-rect;. The | ||
| 1628 | <structfield>x</structfield> and <structfield>y</structfield> fields | ||
| 1629 | were renamed to <structfield>left</structfield> and | ||
| 1630 | <structfield>top</structfield>, &ie; offsets to a context dependent | ||
| 1631 | origin.</para> | ||
| 1632 | </listitem> | ||
| 1633 | |||
| 1634 | <listitem> | ||
| 1635 | <para>In &v4l2-window; the <structfield>x</structfield>, | ||
| 1636 | <structfield>y</structfield>, <structfield>width</structfield> and | ||
| 1637 | <structfield>height</structfield> field moved into a | ||
| 1638 | <structfield>w</structfield> substructure as above. A | ||
| 1639 | <structfield>field</structfield> field of type %v4l2-field; was added | ||
| 1640 | to distinguish between field and frame (interlaced) overlay.</para> | ||
| 1641 | </listitem> | ||
| 1642 | |||
| 1643 | <listitem> | ||
| 1644 | <para>The digital zoom interface, including struct | ||
| 1645 | <structname>v4l2_zoomcap</structname>, struct | ||
| 1646 | <structname>v4l2_zoom</structname>, | ||
| 1647 | <constant>V4L2_ZOOM_NONCAP</constant> and | ||
| 1648 | <constant>V4L2_ZOOM_WHILESTREAMING</constant> was replaced by a new | ||
| 1649 | cropping and scaling interface. The previously unused struct | ||
| 1650 | <structname>v4l2_cropcap</structname> and | ||
| 1651 | <structname>v4l2_crop</structname> where redefined for this purpose. | ||
| 1652 | See <xref linkend="crop" /> for details.</para> | ||
| 1653 | </listitem> | ||
| 1654 | |||
| 1655 | <listitem> | ||
| 1656 | <para>In &v4l2-vbi-format; the | ||
| 1657 | <structfield>SAMPLE_FORMAT</structfield> field now contains a | ||
| 1658 | four-character-code as used to identify video image formats and | ||
| 1659 | <constant>V4L2_PIX_FMT_GREY</constant> replaces the | ||
| 1660 | <constant>V4L2_VBI_SF_UBYTE</constant> define. The | ||
| 1661 | <structfield>reserved</structfield> field was extended.</para> | ||
| 1662 | </listitem> | ||
| 1663 | |||
| 1664 | <listitem> | ||
| 1665 | <para>In &v4l2-captureparm; the type of the | ||
| 1666 | <structfield>timeperframe</structfield> field changed from unsigned | ||
| 1667 | long to &v4l2-fract;. This allows the accurate expression of multiples | ||
| 1668 | of the NTSC-M frame rate 30000 / 1001. A new field | ||
| 1669 | <structfield>readbuffers</structfield> was added to control the driver | ||
| 1670 | behaviour in read I/O mode.</para> | ||
| 1671 | |||
| 1672 | <para>Similar changes were made to &v4l2-outputparm;.</para> | ||
| 1673 | </listitem> | ||
| 1674 | |||
| 1675 | <listitem> | ||
| 1676 | <para>The struct <structname>v4l2_performance</structname> | ||
| 1677 | and <constant>VIDIOC_G_PERF</constant> ioctl were dropped. Except when | ||
| 1678 | using the <link linkend="rw">read/write I/O method</link>, which is | ||
| 1679 | limited anyway, this information is already available to | ||
| 1680 | applications.</para> | ||
| 1681 | </listitem> | ||
| 1682 | |||
| 1683 | <listitem> | ||
| 1684 | <para>The example transformation from RGB to YCbCr color | ||
| 1685 | space in the old V4L2 documentation was inaccurate, this has been | ||
| 1686 | corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be | ||
| 1687 | 0.587, and 127/112 != 255/224 --></para> | ||
| 1688 | </listitem> | ||
| 1689 | </orderedlist> | ||
| 1690 | </section> | ||
| 1691 | |||
| 1692 | <section> | ||
| 1693 | <title>V4L2 2003-06-19</title> | ||
| 1694 | |||
| 1695 | <orderedlist> | ||
| 1696 | <listitem> | ||
| 1697 | <para>A new capability flag | ||
| 1698 | <constant>V4L2_CAP_RADIO</constant> was added for radio devices. Prior | ||
| 1699 | to this change radio devices would identify solely by having exactly one | ||
| 1700 | tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para> | ||
| 1701 | </listitem> | ||
| 1702 | |||
| 1703 | <listitem> | ||
| 1704 | <para>An optional driver access priority mechanism was | ||
| 1705 | added, see <xref linkend="app-pri" /> for details.</para> | ||
| 1706 | </listitem> | ||
| 1707 | |||
| 1708 | <listitem> | ||
| 1709 | <para>The audio input and output interface was found to be | ||
| 1710 | incomplete.</para> | ||
| 1711 | <para>Previously the &VIDIOC-G-AUDIO; | ||
| 1712 | ioctl would enumerate the available audio inputs. An ioctl to | ||
| 1713 | determine the current audio input, if more than one combines with the | ||
| 1714 | current video input, did not exist. So | ||
| 1715 | <constant>VIDIOC_G_AUDIO</constant> was renamed to | ||
| 1716 | <constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl will be removed in | ||
| 1717 | the future. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate | ||
| 1718 | audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio | ||
| 1719 | input.</para> | ||
| 1720 | <para>The same changes were made to &VIDIOC-G-AUDOUT; and | ||
| 1721 | &VIDIOC-ENUMAUDOUT;.</para> | ||
| 1722 | <para>Until further the "videodev" module will automatically | ||
| 1723 | translate between the old and new ioctls, but drivers and applications | ||
| 1724 | must be updated to successfully compile again.</para> | ||
| 1725 | </listitem> | ||
| 1726 | |||
| 1727 | <listitem> | ||
| 1728 | <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with | ||
| 1729 | write-read parameter. It was changed to write-only, while the write-read | ||
| 1730 | version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old | ||
| 1731 | ioctl will be removed in the future. Until further the "videodev" | ||
| 1732 | kernel module will automatically translate to the new version, so drivers | ||
| 1733 | must be recompiled, but not applications.</para> | ||
| 1734 | </listitem> | ||
| 1735 | |||
| 1736 | <listitem> | ||
| 1737 | <para><xref linkend="overlay" /> incorrectly stated that | ||
| 1738 | clipping rectangles define regions where the video can be seen. | ||
| 1739 | Correct is that clipping rectangles define regions where | ||
| 1740 | <emphasis>no</emphasis> video shall be displayed and so the graphics | ||
| 1741 | surface can be seen.</para> | ||
| 1742 | </listitem> | ||
| 1743 | |||
| 1744 | <listitem> | ||
| 1745 | <para>The &VIDIOC-S-PARM; and &VIDIOC-S-CTRL; ioctls were | ||
| 1746 | defined with write-only parameter, inconsistent with other ioctls | ||
| 1747 | modifying their argument. They were changed to write-read, while a | ||
| 1748 | <constant>_OLD</constant> suffix was added to the write-only versions. | ||
| 1749 | The old ioctls will be removed in the future. Drivers and | ||
| 1750 | applications assuming a constant parameter need an update.</para> | ||
| 1751 | </listitem> | ||
| 1752 | </orderedlist> | ||
| 1753 | </section> | ||
| 1754 | |||
| 1755 | <section> | ||
| 1756 | <title>V4L2 2003-11-05</title> | ||
| 1757 | <orderedlist> | ||
| 1758 | <listitem> | ||
| 1759 | <para>In <xref linkend="pixfmt-rgb" /> the following pixel | ||
| 1760 | formats were incorrectly transferred from Bill Dirks' V4L2 | ||
| 1761 | specification. Descriptions below refer to bytes in memory, in | ||
| 1762 | ascending address order.<informaltable> | ||
| 1763 | <tgroup cols="3"> | ||
| 1764 | <thead> | ||
| 1765 | <row> | ||
| 1766 | <entry>Symbol</entry> | ||
| 1767 | <entry>In this document prior to revision | ||
| 1768 | 0.5</entry> | ||
| 1769 | <entry>Corrected</entry> | ||
| 1770 | </row> | ||
| 1771 | </thead> | ||
| 1772 | <tbody valign="top"> | ||
| 1773 | <row> | ||
| 1774 | <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry> | ||
| 1775 | <entry>B, G, R</entry> | ||
| 1776 | <entry>R, G, B</entry> | ||
| 1777 | </row> | ||
| 1778 | <row> | ||
| 1779 | <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> | ||
| 1780 | <entry>R, G, B</entry> | ||
| 1781 | <entry>B, G, R</entry> | ||
| 1782 | </row> | ||
| 1783 | <row> | ||
| 1784 | <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> | ||
| 1785 | <entry>B, G, R, X</entry> | ||
| 1786 | <entry>R, G, B, X</entry> | ||
| 1787 | </row> | ||
| 1788 | <row> | ||
| 1789 | <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> | ||
| 1790 | <entry>R, G, B, X</entry> | ||
| 1791 | <entry>B, G, R, X</entry> | ||
| 1792 | </row> | ||
| 1793 | </tbody> | ||
| 1794 | </tgroup> | ||
| 1795 | </informaltable> The | ||
| 1796 | <constant>V4L2_PIX_FMT_BGR24</constant> example was always | ||
| 1797 | correct.</para> | ||
| 1798 | <para>In <xref linkend="v4l-image-properties" /> the mapping | ||
| 1799 | of the V4L <constant>VIDEO_PALETTE_RGB24</constant> and | ||
| 1800 | <constant>VIDEO_PALETTE_RGB32</constant> formats to V4L2 pixel formats | ||
| 1801 | was accordingly corrected.</para> | ||
| 1802 | </listitem> | ||
| 1803 | |||
| 1804 | <listitem> | ||
| 1805 | <para>Unrelated to the fixes above, drivers may still | ||
| 1806 | interpret some V4L2 RGB pixel formats differently. These issues have | ||
| 1807 | yet to be addressed, for details see <xref | ||
| 1808 | linkend="pixfmt-rgb" />.</para> | ||
| 1809 | </listitem> | ||
| 1810 | </orderedlist> | ||
| 1811 | </section> | ||
| 1812 | |||
| 1813 | <section> | ||
| 1814 | <title>V4L2 in Linux 2.6.6, 2004-05-09</title> | ||
| 1815 | <orderedlist> | ||
| 1816 | <listitem> | ||
| 1817 | <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined | ||
| 1818 | with read-only parameter. It is now defined as write-read ioctl, while | ||
| 1819 | the read-only version was renamed to | ||
| 1820 | <constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl will be removed | ||
| 1821 | in the future.</para> | ||
| 1822 | </listitem> | ||
| 1823 | </orderedlist> | ||
| 1824 | </section> | ||
| 1825 | |||
| 1826 | <section> | ||
| 1827 | <title>V4L2 in Linux 2.6.8</title> | ||
| 1828 | <orderedlist> | ||
| 1829 | <listitem> | ||
| 1830 | <para>A new field <structfield>input</structfield> (former | ||
| 1831 | <structfield>reserved[0]</structfield>) was added to the &v4l2-buffer; | ||
| 1832 | structure. Purpose of this field is to alternate between video inputs | ||
| 1833 | (⪚ cameras) in step with the video capturing process. This function | ||
| 1834 | must be enabled with the new <constant>V4L2_BUF_FLAG_INPUT</constant> | ||
| 1835 | flag. The <structfield>flags</structfield> field is no longer | ||
| 1836 | read-only.</para> | ||
| 1837 | </listitem> | ||
| 1838 | </orderedlist> | ||
| 1839 | </section> | ||
| 1840 | |||
| 1841 | <section> | ||
| 1842 | <title>V4L2 spec erratum 2004-08-01</title> | ||
| 1843 | |||
| 1844 | <orderedlist> | ||
| 1845 | <listitem> | ||
| 1846 | <para>The return value of the | ||
| 1847 | <xref linkend="func-open" /> function was incorrectly documented.</para> | ||
| 1848 | </listitem> | ||
| 1849 | |||
| 1850 | <listitem> | ||
| 1851 | <para>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</para> | ||
| 1852 | </listitem> | ||
| 1853 | |||
| 1854 | <listitem> | ||
| 1855 | <para>In the Current Audio Input example the | ||
| 1856 | <constant>VIDIOC_G_AUDIO</constant> ioctl took the wrong | ||
| 1857 | argument.</para> | ||
| 1858 | </listitem> | ||
| 1859 | |||
| 1860 | <listitem> | ||
| 1861 | <para>The documentation of the &VIDIOC-QBUF; and | ||
| 1862 | &VIDIOC-DQBUF; ioctls did not mention the &v4l2-buffer; | ||
| 1863 | <structfield>memory</structfield> field. It was also missing from | ||
| 1864 | examples. Also on the <constant>VIDIOC_DQBUF</constant> page the &EIO; | ||
| 1865 | was not documented.</para> | ||
| 1866 | </listitem> | ||
| 1867 | </orderedlist> | ||
| 1868 | </section> | ||
| 1869 | |||
| 1870 | <section> | ||
| 1871 | <title>V4L2 in Linux 2.6.14</title> | ||
| 1872 | <orderedlist> | ||
| 1873 | <listitem> | ||
| 1874 | <para>A new sliced VBI interface was added. It is documented | ||
| 1875 | in <xref linkend="sliced" /> and replaces the interface first | ||
| 1876 | proposed in V4L2 specification 0.8.</para> | ||
| 1877 | </listitem> | ||
| 1878 | </orderedlist> | ||
| 1879 | </section> | ||
| 1880 | |||
| 1881 | <section> | ||
| 1882 | <title>V4L2 in Linux 2.6.15</title> | ||
| 1883 | <orderedlist> | ||
| 1884 | <listitem> | ||
| 1885 | <para>The &VIDIOC-LOG-STATUS; ioctl was added.</para> | ||
| 1886 | </listitem> | ||
| 1887 | |||
| 1888 | <listitem> | ||
| 1889 | <para>New video standards | ||
| 1890 | <constant>V4L2_STD_NTSC_443</constant>, | ||
| 1891 | <constant>V4L2_STD_SECAM_LC</constant>, | ||
| 1892 | <constant>V4L2_STD_SECAM_DK</constant> (a set of SECAM D, K and K1), | ||
| 1893 | and <constant>V4L2_STD_ATSC</constant> (a set of | ||
| 1894 | <constant>V4L2_STD_ATSC_8_VSB</constant> and | ||
| 1895 | <constant>V4L2_STD_ATSC_16_VSB</constant>) were defined. Note the | ||
| 1896 | <constant>V4L2_STD_525_60</constant> set now includes | ||
| 1897 | <constant>V4L2_STD_NTSC_443</constant>. See also <xref | ||
| 1898 | linkend="v4l2-std-id" />.</para> | ||
| 1899 | </listitem> | ||
| 1900 | |||
| 1901 | <listitem> | ||
| 1902 | <para>The <constant>VIDIOC_G_COMP</constant> and | ||
| 1903 | <constant>VIDIOC_S_COMP</constant> ioctl were renamed to | ||
| 1904 | <constant>VIDIOC_G_MPEGCOMP</constant> and | ||
| 1905 | <constant>VIDIOC_S_MPEGCOMP</constant> respectively. Their argument | ||
| 1906 | was replaced by a struct | ||
| 1907 | <structname>v4l2_mpeg_compression</structname> pointer. (The | ||
| 1908 | <constant>VIDIOC_G_MPEGCOMP</constant> and | ||
| 1909 | <constant>VIDIOC_S_MPEGCOMP</constant> ioctls where removed in Linux | ||
| 1910 | 2.6.25.)</para> | ||
| 1911 | </listitem> | ||
| 1912 | </orderedlist> | ||
| 1913 | </section> | ||
| 1914 | |||
| 1915 | <section> | ||
| 1916 | <title>V4L2 spec erratum 2005-11-27</title> | ||
| 1917 | <para>The capture example in <xref linkend="capture-example" /> | ||
| 1918 | called the &VIDIOC-S-CROP; ioctl without checking if cropping is | ||
| 1919 | supported. In the video standard selection example in | ||
| 1920 | <xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong | ||
| 1921 | argument type.</para> | ||
| 1922 | </section> | ||
| 1923 | |||
| 1924 | <section> | ||
| 1925 | <title>V4L2 spec erratum 2006-01-10</title> | ||
| 1926 | <orderedlist> | ||
| 1927 | <listitem> | ||
| 1928 | <para>The <constant>V4L2_IN_ST_COLOR_KILL</constant> flag in | ||
| 1929 | &v4l2-input; not only indicates if the color killer is enabled, but | ||
| 1930 | also if it is active. (The color killer disables color decoding when | ||
| 1931 | it detects no color in the video signal to improve the image | ||
| 1932 | quality.)</para> | ||
| 1933 | </listitem> | ||
| 1934 | |||
| 1935 | <listitem> | ||
| 1936 | <para>&VIDIOC-S-PARM; is a write-read ioctl, not write-only as | ||
| 1937 | stated on its reference page. The ioctl changed in 2003 as noted above.</para> | ||
| 1938 | </listitem> | ||
| 1939 | </orderedlist> | ||
| 1940 | </section> | ||
| 1941 | |||
| 1942 | <section> | ||
| 1943 | <title>V4L2 spec erratum 2006-02-03</title> | ||
| 1944 | <orderedlist> | ||
| 1945 | <listitem> | ||
| 1946 | <para>In &v4l2-captureparm; and &v4l2-outputparm; the | ||
| 1947 | <structfield>timeperframe</structfield> field gives the time in | ||
| 1948 | seconds, not microseconds.</para> | ||
| 1949 | </listitem> | ||
| 1950 | </orderedlist> | ||
| 1951 | </section> | ||
| 1952 | |||
| 1953 | <section> | ||
| 1954 | <title>V4L2 spec erratum 2006-02-04</title> | ||
| 1955 | <orderedlist> | ||
| 1956 | <listitem> | ||
| 1957 | <para>The <structfield>clips</structfield> field in | ||
| 1958 | &v4l2-window; must point to an array of &v4l2-clip;, not a linked | ||
| 1959 | list, because drivers ignore the struct | ||
| 1960 | <structname>v4l2_clip</structname>.<structfield>next</structfield> | ||
| 1961 | pointer.</para> | ||
| 1962 | </listitem> | ||
| 1963 | </orderedlist> | ||
| 1964 | </section> | ||
| 1965 | |||
| 1966 | <section> | ||
| 1967 | <title>V4L2 in Linux 2.6.17</title> | ||
| 1968 | <orderedlist> | ||
| 1969 | <listitem> | ||
| 1970 | <para>New video standard macros were added: | ||
| 1971 | <constant>V4L2_STD_NTSC_M_KR</constant> (NTSC M South Korea), and the | ||
| 1972 | sets <constant>V4L2_STD_MN</constant>, | ||
| 1973 | <constant>V4L2_STD_B</constant>, <constant>V4L2_STD_GH</constant> and | ||
| 1974 | <constant>V4L2_STD_DK</constant>. The | ||
| 1975 | <constant>V4L2_STD_NTSC</constant> and | ||
| 1976 | <constant>V4L2_STD_SECAM</constant> sets now include | ||
| 1977 | <constant>V4L2_STD_NTSC_M_KR</constant> and | ||
| 1978 | <constant>V4L2_STD_SECAM_LC</constant> respectively.</para> | ||
| 1979 | </listitem> | ||
| 1980 | |||
| 1981 | <listitem> | ||
| 1982 | <para>A new <constant>V4L2_TUNER_MODE_LANG1_LANG2</constant> | ||
| 1983 | was defined to record both languages of a bilingual program. The | ||
| 1984 | use of <constant>V4L2_TUNER_MODE_STEREO</constant> for this purpose | ||
| 1985 | is deprecated now. See the &VIDIOC-G-TUNER; section for | ||
| 1986 | details.</para> | ||
| 1987 | </listitem> | ||
| 1988 | </orderedlist> | ||
| 1989 | </section> | ||
| 1990 | |||
| 1991 | <section> | ||
| 1992 | <title>V4L2 spec erratum 2006-09-23 (Draft 0.15)</title> | ||
| 1993 | <orderedlist> | ||
| 1994 | <listitem> | ||
| 1995 | <para>In various places | ||
| 1996 | <constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> and | ||
| 1997 | <constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant> of the sliced VBI | ||
| 1998 | interface were not mentioned along with other buffer types.</para> | ||
| 1999 | </listitem> | ||
| 2000 | |||
| 2001 | <listitem> | ||
| 2002 | <para>In <xref linkend="vidioc-g-audio" /> it was clarified | ||
| 2003 | that the &v4l2-audio; <structfield>mode</structfield> field is a flags | ||
| 2004 | field.</para> | ||
| 2005 | </listitem> | ||
| 2006 | |||
| 2007 | <listitem> | ||
| 2008 | <para><xref linkend="vidioc-querycap" /> did not mention the | ||
| 2009 | sliced VBI and radio capability flags.</para> | ||
| 2010 | </listitem> | ||
| 2011 | |||
| 2012 | <listitem> | ||
| 2013 | <para>In <xref linkend="vidioc-g-frequency" /> it was | ||
| 2014 | clarified that applications must initialize the tuner | ||
| 2015 | <structfield>type</structfield> field of &v4l2-frequency; before | ||
| 2016 | calling &VIDIOC-S-FREQUENCY;.</para> | ||
| 2017 | </listitem> | ||
| 2018 | |||
| 2019 | <listitem> | ||
| 2020 | <para>The <structfield>reserved</structfield> array | ||
| 2021 | in &v4l2-requestbuffers; has 2 elements, not 32.</para> | ||
| 2022 | </listitem> | ||
| 2023 | |||
| 2024 | <listitem> | ||
| 2025 | <para>In <xref linkend="output" /> and <xref | ||
| 2026 | linkend="raw-vbi" /> the device file names | ||
| 2027 | <filename>/dev/vout</filename> which never caught on were replaced | ||
| 2028 | by <filename>/dev/video</filename>.</para> | ||
| 2029 | </listitem> | ||
| 2030 | |||
| 2031 | <listitem> | ||
| 2032 | <para>With Linux 2.6.15 the possible range for VBI device minor | ||
| 2033 | numbers was extended from 224-239 to 224-255. Accordingly device file names | ||
| 2034 | <filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> are | ||
| 2035 | possible now.</para> | ||
| 2036 | </listitem> | ||
| 2037 | </orderedlist> | ||
| 2038 | </section> | ||
| 2039 | |||
| 2040 | <section> | ||
| 2041 | <title>V4L2 in Linux 2.6.18</title> | ||
| 2042 | <orderedlist> | ||
| 2043 | <listitem> | ||
| 2044 | <para>New ioctls &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; | ||
| 2045 | and &VIDIOC-TRY-EXT-CTRLS; were added, a flag to skip unsupported | ||
| 2046 | controls with &VIDIOC-QUERYCTRL;, new control types | ||
| 2047 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and | ||
| 2048 | <constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant> (<xref | ||
| 2049 | linkend="v4l2-ctrl-type" />), and new control flags | ||
| 2050 | <constant>V4L2_CTRL_FLAG_READ_ONLY</constant>, | ||
| 2051 | <constant>V4L2_CTRL_FLAG_UPDATE</constant>, | ||
| 2052 | <constant>V4L2_CTRL_FLAG_INACTIVE</constant> and | ||
| 2053 | <constant>V4L2_CTRL_FLAG_SLIDER</constant> (<xref | ||
| 2054 | linkend="control-flags" />). See <xref | ||
| 2055 | linkend="extended-controls" /> for details.</para> | ||
| 2056 | </listitem> | ||
| 2057 | </orderedlist> | ||
| 2058 | </section> | ||
| 2059 | |||
| 2060 | <section> | ||
| 2061 | <title>V4L2 in Linux 2.6.19</title> | ||
| 2062 | <orderedlist> | ||
| 2063 | <listitem> | ||
| 2064 | <para>In &v4l2-sliced-vbi-cap; a buffer type field was added | ||
| 2065 | replacing a reserved field. Note on architectures where the size of | ||
| 2066 | enum types differs from int types the size of the structure changed. | ||
| 2067 | The &VIDIOC-G-SLICED-VBI-CAP; ioctl was redefined from being read-only | ||
| 2068 | to write-read. Applications must initialize the type field and clear | ||
| 2069 | the reserved fields now. These changes may <emphasis>break the | ||
| 2070 | compatibility</emphasis> with older drivers and applications.</para> | ||
| 2071 | </listitem> | ||
| 2072 | |||
| 2073 | <listitem> | ||
| 2074 | <para>The ioctls &VIDIOC-ENUM-FRAMESIZES; and | ||
| 2075 | &VIDIOC-ENUM-FRAMEINTERVALS; were added.</para> | ||
| 2076 | </listitem> | ||
| 2077 | |||
| 2078 | <listitem> | ||
| 2079 | <para>A new pixel format <constant>V4L2_PIX_FMT_RGB444</constant> (<xref | ||
| 2080 | linkend="rgb-formats" />) was added.</para> | ||
| 2081 | </listitem> | ||
| 2082 | </orderedlist> | ||
| 2083 | </section> | ||
| 2084 | |||
| 2085 | <section> | ||
| 2086 | <title>V4L2 spec erratum 2006-10-12 (Draft 0.17)</title> | ||
| 2087 | <orderedlist> | ||
| 2088 | <listitem> | ||
| 2089 | <para><constant>V4L2_PIX_FMT_HM12</constant> (<xref | ||
| 2090 | linkend="reserved-formats" />) is a YUV 4:2:0, not 4:2:2 format.</para> | ||
| 2091 | </listitem> | ||
| 2092 | </orderedlist> | ||
| 2093 | </section> | ||
| 2094 | |||
| 2095 | <section> | ||
| 2096 | <title>V4L2 in Linux 2.6.21</title> | ||
| 2097 | <orderedlist> | ||
| 2098 | <listitem> | ||
| 2099 | <para>The <filename>videodev2.h</filename> header file is | ||
| 2100 | now dual licensed under GNU General Public License version two or | ||
| 2101 | later, and under a 3-clause BSD-style license.</para> | ||
| 2102 | </listitem> | ||
| 2103 | </orderedlist> | ||
| 2104 | </section> | ||
| 2105 | |||
| 2106 | <section> | ||
| 2107 | <title>V4L2 in Linux 2.6.22</title> | ||
| 2108 | <orderedlist> | ||
| 2109 | <listitem> | ||
| 2110 | <para>Two new field orders | ||
| 2111 | <constant>V4L2_FIELD_INTERLACED_TB</constant> and | ||
| 2112 | <constant>V4L2_FIELD_INTERLACED_BT</constant> were | ||
| 2113 | added. See <xref linkend="v4l2-field" /> for details.</para> | ||
| 2114 | </listitem> | ||
| 2115 | |||
| 2116 | <listitem> | ||
| 2117 | <para>Three new clipping/blending methods with a global or | ||
| 2118 | straight or inverted local alpha value were added to the video overlay | ||
| 2119 | interface. See the description of the &VIDIOC-G-FBUF; and | ||
| 2120 | &VIDIOC-S-FBUF; ioctls for details.</para> | ||
| 2121 | <para>A new <structfield>global_alpha</structfield> field | ||
| 2122 | was added to <link | ||
| 2123 | linkend="v4l2-window"><structname>v4l2_window</structname></link>, | ||
| 2124 | extending the structure. This may <emphasis>break | ||
| 2125 | compatibility</emphasis> with applications using a struct | ||
| 2126 | <structname>v4l2_window</structname> directly. However the <link | ||
| 2127 | linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, which take a | ||
| 2128 | pointer to a <link linkend="v4l2-format">v4l2_format</link> parent | ||
| 2129 | structure with padding bytes at the end, are not affected.</para> | ||
| 2130 | </listitem> | ||
| 2131 | |||
| 2132 | <listitem> | ||
| 2133 | <para>The format of the <structfield>chromakey</structfield> | ||
| 2134 | field in &v4l2-window; changed from "host order RGB32" to a pixel | ||
| 2135 | value in the same format as the framebuffer. This may <emphasis>break | ||
| 2136 | compatibility</emphasis> with existing applications. Drivers | ||
| 2137 | supporting the "host order RGB32" format are not known.</para> | ||
| 2138 | </listitem> | ||
| 2139 | |||
| 2140 | </orderedlist> | ||
| 2141 | </section> | ||
| 2142 | |||
| 2143 | <section> | ||
| 2144 | <title>V4L2 in Linux 2.6.24</title> | ||
| 2145 | <orderedlist> | ||
| 2146 | <listitem> | ||
| 2147 | <para>The pixel formats | ||
| 2148 | <constant>V4L2_PIX_FMT_PAL8</constant>, | ||
| 2149 | <constant>V4L2_PIX_FMT_YUV444</constant>, | ||
| 2150 | <constant>V4L2_PIX_FMT_YUV555</constant>, | ||
| 2151 | <constant>V4L2_PIX_FMT_YUV565</constant> and | ||
| 2152 | <constant>V4L2_PIX_FMT_YUV32</constant> were added.</para> | ||
| 2153 | </listitem> | ||
| 2154 | </orderedlist> | ||
| 2155 | </section> | ||
| 2156 | |||
| 2157 | <section> | ||
| 2158 | <title>V4L2 in Linux 2.6.25</title> | ||
| 2159 | <orderedlist> | ||
| 2160 | <listitem> | ||
| 2161 | <para>The pixel formats <link linkend="V4L2-PIX-FMT-Y16"> | ||
| 2162 | <constant>V4L2_PIX_FMT_Y16</constant></link> and <link | ||
| 2163 | linkend="V4L2-PIX-FMT-SBGGR16"> | ||
| 2164 | <constant>V4L2_PIX_FMT_SBGGR16</constant></link> were added.</para> | ||
| 2165 | </listitem> | ||
| 2166 | <listitem> | ||
| 2167 | <para>New <link linkend="control">controls</link> | ||
| 2168 | <constant>V4L2_CID_POWER_LINE_FREQUENCY</constant>, | ||
| 2169 | <constant>V4L2_CID_HUE_AUTO</constant>, | ||
| 2170 | <constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant>, | ||
| 2171 | <constant>V4L2_CID_SHARPNESS</constant> and | ||
| 2172 | <constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant> were added. The | ||
| 2173 | controls <constant>V4L2_CID_BLACK_LEVEL</constant>, | ||
| 2174 | <constant>V4L2_CID_WHITENESS</constant>, | ||
| 2175 | <constant>V4L2_CID_HCENTER</constant> and | ||
| 2176 | <constant>V4L2_CID_VCENTER</constant> were deprecated. | ||
| 2177 | </para> | ||
| 2178 | </listitem> | ||
| 2179 | <listitem> | ||
| 2180 | <para>A <link linkend="camera-controls">Camera controls | ||
| 2181 | class</link> was added, with the new controls | ||
| 2182 | <constant>V4L2_CID_EXPOSURE_AUTO</constant>, | ||
| 2183 | <constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>, | ||
| 2184 | <constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>, | ||
| 2185 | <constant>V4L2_CID_PAN_RELATIVE</constant>, | ||
| 2186 | <constant>V4L2_CID_TILT_RELATIVE</constant>, | ||
| 2187 | <constant>V4L2_CID_PAN_RESET</constant>, | ||
| 2188 | <constant>V4L2_CID_TILT_RESET</constant>, | ||
| 2189 | <constant>V4L2_CID_PAN_ABSOLUTE</constant>, | ||
| 2190 | <constant>V4L2_CID_TILT_ABSOLUTE</constant>, | ||
| 2191 | <constant>V4L2_CID_FOCUS_ABSOLUTE</constant>, | ||
| 2192 | <constant>V4L2_CID_FOCUS_RELATIVE</constant> and | ||
| 2193 | <constant>V4L2_CID_FOCUS_AUTO</constant>.</para> | ||
| 2194 | </listitem> | ||
| 2195 | <listitem> | ||
| 2196 | <para>The <constant>VIDIOC_G_MPEGCOMP</constant> and | ||
| 2197 | <constant>VIDIOC_S_MPEGCOMP</constant> ioctls, which were superseded | ||
| 2198 | by the <link linkend="extended-controls">extended controls</link> | ||
| 2199 | interface in Linux 2.6.18, where finally removed from the | ||
| 2200 | <filename>videodev2.h</filename> header file.</para> | ||
| 2201 | </listitem> | ||
| 2202 | </orderedlist> | ||
| 2203 | </section> | ||
| 2204 | |||
| 2205 | <section> | ||
| 2206 | <title>V4L2 in Linux 2.6.26</title> | ||
| 2207 | <orderedlist> | ||
| 2208 | <listitem> | ||
| 2209 | <para>The pixel formats | ||
| 2210 | <constant>V4L2_PIX_FMT_Y16</constant> and | ||
| 2211 | <constant>V4L2_PIX_FMT_SBGGR16</constant> were added.</para> | ||
| 2212 | </listitem> | ||
| 2213 | <listitem> | ||
| 2214 | <para>Added user controls | ||
| 2215 | <constant>V4L2_CID_CHROMA_AGC</constant> and | ||
| 2216 | <constant>V4L2_CID_COLOR_KILLER</constant>.</para> | ||
| 2217 | </listitem> | ||
| 2218 | </orderedlist> | ||
| 2219 | </section> | ||
| 2220 | |||
| 2221 | <section> | ||
| 2222 | <title>V4L2 in Linux 2.6.27</title> | ||
| 2223 | <orderedlist> | ||
| 2224 | <listitem> | ||
| 2225 | <para>The &VIDIOC-S-HW-FREQ-SEEK; ioctl and the | ||
| 2226 | <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability were added.</para> | ||
| 2227 | </listitem> | ||
| 2228 | <listitem> | ||
| 2229 | <para>The pixel formats | ||
| 2230 | <constant>V4L2_PIX_FMT_YVYU</constant>, | ||
| 2231 | <constant>V4L2_PIX_FMT_PCA501</constant>, | ||
| 2232 | <constant>V4L2_PIX_FMT_PCA505</constant>, | ||
| 2233 | <constant>V4L2_PIX_FMT_PCA508</constant>, | ||
| 2234 | <constant>V4L2_PIX_FMT_PCA561</constant>, | ||
| 2235 | <constant>V4L2_PIX_FMT_SGBRG8</constant>, | ||
| 2236 | <constant>V4L2_PIX_FMT_PAC207</constant> and | ||
| 2237 | <constant>V4L2_PIX_FMT_PJPG</constant> were added.</para> | ||
| 2238 | </listitem> | ||
| 2239 | </orderedlist> | ||
| 2240 | </section> | ||
| 2241 | |||
| 2242 | <section> | ||
| 2243 | <title>V4L2 in Linux 2.6.28</title> | ||
| 2244 | <orderedlist> | ||
| 2245 | <listitem> | ||
| 2246 | <para>Added <constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> and | ||
| 2247 | <constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> MPEG audio encodings.</para> | ||
| 2248 | </listitem> | ||
| 2249 | <listitem> | ||
| 2250 | <para>Added <constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> MPEG | ||
| 2251 | video encoding.</para> | ||
| 2252 | </listitem> | ||
| 2253 | <listitem> | ||
| 2254 | <para>The pixel formats | ||
| 2255 | <constant>V4L2_PIX_FMT_SGRBG10</constant> and | ||
| 2256 | <constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant> were added.</para> | ||
| 2257 | </listitem> | ||
| 2258 | </orderedlist> | ||
| 2259 | </section> | ||
| 2260 | |||
| 2261 | <section> | ||
| 2262 | <title>V4L2 in Linux 2.6.29</title> | ||
| 2263 | <orderedlist> | ||
| 2264 | <listitem> | ||
| 2265 | <para>The <constant>VIDIOC_G_CHIP_IDENT</constant> ioctl was renamed | ||
| 2266 | to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and &VIDIOC-DBG-G-CHIP-IDENT; | ||
| 2267 | was introduced in its place. The old struct <structname>v4l2_chip_ident</structname> | ||
| 2268 | was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para> | ||
| 2269 | </listitem> | ||
| 2270 | <listitem> | ||
| 2271 | <para>The pixel formats | ||
| 2272 | <constant>V4L2_PIX_FMT_VYUY</constant>, | ||
| 2273 | <constant>V4L2_PIX_FMT_NV16</constant> and | ||
| 2274 | <constant>V4L2_PIX_FMT_NV61</constant> were added.</para> | ||
| 2275 | </listitem> | ||
| 2276 | <listitem> | ||
| 2277 | <para>Added camera controls | ||
| 2278 | <constant>V4L2_CID_ZOOM_ABSOLUTE</constant>, | ||
| 2279 | <constant>V4L2_CID_ZOOM_RELATIVE</constant>, | ||
| 2280 | <constant>V4L2_CID_ZOOM_CONTINUOUS</constant> and | ||
| 2281 | <constant>V4L2_CID_PRIVACY</constant>.</para> | ||
| 2282 | </listitem> | ||
| 2283 | </orderedlist> | ||
| 2284 | </section> | ||
| 2285 | <section> | ||
| 2286 | <title>V4L2 in Linux 2.6.30</title> | ||
| 2287 | <orderedlist> | ||
| 2288 | <listitem> | ||
| 2289 | <para>New control flag <constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant> was added.</para> | ||
| 2290 | </listitem> | ||
| 2291 | <listitem> | ||
| 2292 | <para>New control <constant>V4L2_CID_COLORFX</constant> was added.</para> | ||
| 2293 | </listitem> | ||
| 2294 | </orderedlist> | ||
| 2295 | </section> | ||
| 2296 | <section> | ||
| 2297 | <title>V4L2 in Linux 2.6.32</title> | ||
| 2298 | <orderedlist> | ||
| 2299 | <listitem> | ||
| 2300 | <para>In order to be easier to compare a V4L2 API and a kernel | ||
| 2301 | version, now V4L2 API is numbered using the Linux Kernel version numeration.</para> | ||
| 2302 | </listitem> | ||
| 2303 | <listitem> | ||
| 2304 | <para>Finalized the RDS capture API. See <xref linkend="rds" /> for | ||
| 2305 | more information.</para> | ||
| 2306 | </listitem> | ||
| 2307 | <listitem> | ||
| 2308 | <para>Added new capabilities for modulators and RDS encoders.</para> | ||
| 2309 | </listitem> | ||
| 2310 | <listitem> | ||
| 2311 | <para>Add description for libv4l API.</para> | ||
| 2312 | </listitem> | ||
| 2313 | <listitem> | ||
| 2314 | <para>Added support for string controls via new type <constant>V4L2_CTRL_TYPE_STRING</constant>.</para> | ||
| 2315 | </listitem> | ||
| 2316 | <listitem> | ||
| 2317 | <para>Added <constant>V4L2_CID_BAND_STOP_FILTER</constant> documentation.</para> | ||
| 2318 | </listitem> | ||
| 2319 | <listitem> | ||
| 2320 | <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para> | ||
| 2321 | </listitem> | ||
| 2322 | <listitem> | ||
| 2323 | <para>Added Remote Controller chapter, describing the default Remote Controller mapping for media devices.</para> | ||
| 2324 | </listitem> | ||
| 2325 | </orderedlist> | ||
| 2326 | </section> | ||
| 2327 | </section> | ||
| 2328 | |||
| 2329 | <section id="other"> | ||
| 2330 | <title>Relation of V4L2 to other Linux multimedia APIs</title> | ||
| 2331 | |||
| 2332 | <section id="xvideo"> | ||
| 2333 | <title>X Video Extension</title> | ||
| 2334 | |||
| 2335 | <para>The X Video Extension (abbreviated XVideo or just Xv) is | ||
| 2336 | an extension of the X Window system, implemented for example by the | ||
| 2337 | XFree86 project. Its scope is similar to V4L2, an API to video capture | ||
| 2338 | and output devices for X clients. Xv allows applications to display | ||
| 2339 | live video in a window, send window contents to a TV output, and | ||
| 2340 | capture or output still images in XPixmaps<footnote> | ||
| 2341 | <para>This is not implemented in XFree86.</para> | ||
| 2342 | </footnote>. With their implementation XFree86 makes the | ||
| 2343 | extension available across many operating systems and | ||
| 2344 | architectures.</para> | ||
| 2345 | |||
| 2346 | <para>Because the driver is embedded into the X server Xv has a | ||
| 2347 | number of advantages over the V4L2 <link linkend="overlay">video | ||
| 2348 | overlay interface</link>. The driver can easily determine the overlay | ||
| 2349 | target, &ie; visible graphics memory or off-screen buffers for a | ||
| 2350 | destructive overlay. It can program the RAMDAC for a non-destructive | ||
| 2351 | overlay, scaling or color-keying, or the clipping functions of the | ||
| 2352 | video capture hardware, always in sync with drawing operations or | ||
| 2353 | windows moving or changing their stacking order.</para> | ||
| 2354 | |||
| 2355 | <para>To combine the advantages of Xv and V4L a special Xv | ||
| 2356 | driver exists in XFree86 and XOrg, just programming any overlay capable | ||
| 2357 | Video4Linux device it finds. To enable it | ||
| 2358 | <filename>/etc/X11/XF86Config</filename> must contain these lines:</para> | ||
| 2359 | <para><screen> | ||
| 2360 | Section "Module" | ||
| 2361 | Load "v4l" | ||
| 2362 | EndSection</screen></para> | ||
| 2363 | |||
| 2364 | <para>As of XFree86 4.2 this driver still supports only V4L | ||
| 2365 | ioctls, however it should work just fine with all V4L2 devices through | ||
| 2366 | the V4L2 backward-compatibility layer. Since V4L2 permits multiple | ||
| 2367 | opens it is possible (if supported by the V4L2 driver) to capture | ||
| 2368 | video while an X client requested video overlay. Restrictions of | ||
| 2369 | simultaneous capturing and overlay are discussed in <xref | ||
| 2370 | linkend="overlay" /> apply.</para> | ||
| 2371 | |||
| 2372 | <para>Only marginally related to V4L2, XFree86 extended Xv to | ||
| 2373 | support hardware YUV to RGB conversion and scaling for faster video | ||
| 2374 | playback, and added an interface to MPEG-2 decoding hardware. This API | ||
| 2375 | is useful to display images captured with V4L2 devices.</para> | ||
| 2376 | </section> | ||
| 2377 | |||
| 2378 | <section> | ||
| 2379 | <title>Digital Video</title> | ||
| 2380 | |||
| 2381 | <para>V4L2 does not support digital terrestrial, cable or | ||
| 2382 | satellite broadcast. A separate project aiming at digital receivers | ||
| 2383 | exists. You can find its homepage at <ulink | ||
| 2384 | url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API | ||
| 2385 | has no connection to the V4L2 API except that drivers for hybrid | ||
| 2386 | hardware may support both.</para> | ||
| 2387 | </section> | ||
| 2388 | |||
| 2389 | <section> | ||
| 2390 | <title>Audio Interfaces</title> | ||
| 2391 | |||
| 2392 | <para>[to do - OSS/ALSA]</para> | ||
| 2393 | </section> | ||
| 2394 | </section> | ||
| 2395 | |||
| 2396 | <section id="experimental"> | ||
| 2397 | <title>Experimental API Elements</title> | ||
| 2398 | |||
| 2399 | <para>The following V4L2 API elements are currently experimental | ||
| 2400 | and may change in the future.</para> | ||
| 2401 | |||
| 2402 | <itemizedlist> | ||
| 2403 | <listitem> | ||
| 2404 | <para>Video Output Overlay (OSD) Interface, <xref | ||
| 2405 | linkend="osd" />.</para> | ||
| 2406 | </listitem> | ||
| 2407 | <listitem> | ||
| 2408 | <para><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, | ||
| 2409 | &v4l2-buf-type;, <xref linkend="v4l2-buf-type" />.</para> | ||
| 2410 | </listitem> | ||
| 2411 | <listitem> | ||
| 2412 | <para><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant>, | ||
| 2413 | &VIDIOC-QUERYCAP; ioctl, <xref linkend="device-capabilities" />.</para> | ||
| 2414 | </listitem> | ||
| 2415 | <listitem> | ||
| 2416 | <para>&VIDIOC-ENUM-FRAMESIZES; and | ||
| 2417 | &VIDIOC-ENUM-FRAMEINTERVALS; ioctls.</para> | ||
| 2418 | </listitem> | ||
| 2419 | <listitem> | ||
| 2420 | <para>&VIDIOC-G-ENC-INDEX; ioctl.</para> | ||
| 2421 | </listitem> | ||
| 2422 | <listitem> | ||
| 2423 | <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; | ||
| 2424 | ioctls.</para> | ||
| 2425 | </listitem> | ||
| 2426 | <listitem> | ||
| 2427 | <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; | ||
| 2428 | ioctls.</para> | ||
| 2429 | </listitem> | ||
| 2430 | <listitem> | ||
| 2431 | <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para> | ||
| 2432 | </listitem> | ||
| 2433 | </itemizedlist> | ||
| 2434 | </section> | ||
| 2435 | |||
| 2436 | <section id="obsolete"> | ||
| 2437 | <title>Obsolete API Elements</title> | ||
| 2438 | |||
| 2439 | <para>The following V4L2 API elements were superseded by new | ||
| 2440 | interfaces and should not be implemented in new drivers.</para> | ||
| 2441 | |||
| 2442 | <itemizedlist> | ||
| 2443 | <listitem> | ||
| 2444 | <para><constant>VIDIOC_G_MPEGCOMP</constant> and | ||
| 2445 | <constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls, | ||
| 2446 | <xref linkend="extended-controls" />.</para> | ||
| 2447 | </listitem> | ||
| 2448 | </itemizedlist> | ||
| 2449 | </section> | ||
| 2450 | |||
| 2451 | <!-- | ||
| 2452 | Local Variables: | ||
| 2453 | mode: sgml | ||
| 2454 | sgml-parent-document: "v4l2.sgml" | ||
| 2455 | indent-tabs-mode: nil | ||
| 2456 | End: | ||
| 2457 | --> | ||
diff --git a/Documentation/DocBook/v4l/controls.xml b/Documentation/DocBook/v4l/controls.xml new file mode 100644 index 000000000000..f492accb691d --- /dev/null +++ b/Documentation/DocBook/v4l/controls.xml | |||
| @@ -0,0 +1,2049 @@ | |||
| 1 | <section id="control"> | ||
| 2 | <title>User Controls</title> | ||
| 3 | |||
| 4 | <para>Devices typically have a number of user-settable controls | ||
| 5 | such as brightness, saturation and so on, which would be presented to | ||
| 6 | the user on a graphical user interface. But, different devices | ||
| 7 | will have different controls available, and furthermore, the range of | ||
| 8 | possible values, and the default value will vary from device to | ||
| 9 | device. The control ioctls provide the information and a mechanism to | ||
| 10 | create a nice user interface for these controls that will work | ||
| 11 | correctly with any device.</para> | ||
| 12 | |||
| 13 | <para>All controls are accessed using an ID value. V4L2 defines | ||
| 14 | several IDs for specific purposes. Drivers can also implement their | ||
| 15 | own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant> | ||
| 16 | and higher values. The pre-defined control IDs have the prefix | ||
| 17 | <constant>V4L2_CID_</constant>, and are listed in <xref | ||
| 18 | linkend="control-id" />. The ID is used when querying the attributes of | ||
| 19 | a control, and when getting or setting the current value.</para> | ||
| 20 | |||
| 21 | <para>Generally applications should present controls to the user | ||
| 22 | without assumptions about their purpose. Each control comes with a | ||
| 23 | name string the user is supposed to understand. When the purpose is | ||
| 24 | non-intuitive the driver writer should provide a user manual, a user | ||
| 25 | interface plug-in or a driver specific panel application. Predefined | ||
| 26 | IDs were introduced to change a few controls programmatically, for | ||
| 27 | example to mute a device during a channel switch.</para> | ||
| 28 | |||
| 29 | <para>Drivers may enumerate different controls after switching | ||
| 30 | the current video input or output, tuner or modulator, or audio input | ||
| 31 | or output. Different in the sense of other bounds, another default and | ||
| 32 | current value, step size or other menu items. A control with a certain | ||
| 33 | <emphasis>custom</emphasis> ID can also change name and | ||
| 34 | type.<footnote> | ||
| 35 | <para>It will be more convenient for applications if drivers | ||
| 36 | make use of the <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag, but | ||
| 37 | that was never required.</para> | ||
| 38 | </footnote> Control values are stored globally, they do not | ||
| 39 | change when switching except to stay within the reported bounds. They | ||
| 40 | also do not change ⪚ when the device is opened or closed, when the | ||
| 41 | tuner radio frequency is changed or generally never without | ||
| 42 | application request. Since V4L2 specifies no event mechanism, panel | ||
| 43 | applications intended to cooperate with other panel applications (be | ||
| 44 | they built into a larger application, as a TV viewer) may need to | ||
| 45 | regularly poll control values to update their user | ||
| 46 | interface.<footnote> | ||
| 47 | <para>Applications could call an ioctl to request events. | ||
| 48 | After another process called &VIDIOC-S-CTRL; or another ioctl changing | ||
| 49 | shared properties the &func-select; function would indicate | ||
| 50 | readability until any ioctl (querying the properties) is | ||
| 51 | called.</para> | ||
| 52 | </footnote></para> | ||
| 53 | |||
| 54 | <table pgwide="1" frame="none" id="control-id"> | ||
| 55 | <title>Control IDs</title> | ||
| 56 | <tgroup cols="3"> | ||
| 57 | &cs-def; | ||
| 58 | <thead> | ||
| 59 | <row> | ||
| 60 | <entry>ID</entry> | ||
| 61 | <entry>Type</entry> | ||
| 62 | <entry>Description</entry> | ||
| 63 | </row> | ||
| 64 | </thead> | ||
| 65 | <tbody valign="top"> | ||
| 66 | <row> | ||
| 67 | <entry><constant>V4L2_CID_BASE</constant></entry> | ||
| 68 | <entry></entry> | ||
| 69 | <entry>First predefined ID, equal to | ||
| 70 | <constant>V4L2_CID_BRIGHTNESS</constant>.</entry> | ||
| 71 | </row> | ||
| 72 | <row> | ||
| 73 | <entry><constant>V4L2_CID_USER_BASE</constant></entry> | ||
| 74 | <entry></entry> | ||
| 75 | <entry>Synonym of <constant>V4L2_CID_BASE</constant>.</entry> | ||
| 76 | </row> | ||
| 77 | <row> | ||
| 78 | <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry> | ||
| 79 | <entry>integer</entry> | ||
| 80 | <entry>Picture brightness, or more precisely, the black | ||
| 81 | level.</entry> | ||
| 82 | </row> | ||
| 83 | <row> | ||
| 84 | <entry><constant>V4L2_CID_CONTRAST</constant></entry> | ||
| 85 | <entry>integer</entry> | ||
| 86 | <entry>Picture contrast or luma gain.</entry> | ||
| 87 | </row> | ||
| 88 | <row> | ||
| 89 | <entry><constant>V4L2_CID_SATURATION</constant></entry> | ||
| 90 | <entry>integer</entry> | ||
| 91 | <entry>Picture color saturation or chroma gain.</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry><constant>V4L2_CID_HUE</constant></entry> | ||
| 95 | <entry>integer</entry> | ||
| 96 | <entry>Hue or color balance.</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry> | ||
| 100 | <entry>integer</entry> | ||
| 101 | <entry>Overall audio volume. Note some drivers also | ||
| 102 | provide an OSS or ALSA mixer interface.</entry> | ||
| 103 | </row> | ||
| 104 | <row> | ||
| 105 | <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry> | ||
| 106 | <entry>integer</entry> | ||
| 107 | <entry>Audio stereo balance. Minimum corresponds to all | ||
| 108 | the way left, maximum to right.</entry> | ||
| 109 | </row> | ||
| 110 | <row> | ||
| 111 | <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry> | ||
| 112 | <entry>integer</entry> | ||
| 113 | <entry>Audio bass adjustment.</entry> | ||
| 114 | </row> | ||
| 115 | <row> | ||
| 116 | <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry> | ||
| 117 | <entry>integer</entry> | ||
| 118 | <entry>Audio treble adjustment.</entry> | ||
| 119 | </row> | ||
| 120 | <row> | ||
| 121 | <entry><constant>V4L2_CID_AUDIO_MUTE</constant></entry> | ||
| 122 | <entry>boolean</entry> | ||
| 123 | <entry>Mute audio, &ie; set the volume to zero, however | ||
| 124 | without affecting <constant>V4L2_CID_AUDIO_VOLUME</constant>. Like | ||
| 125 | ALSA drivers, V4L2 drivers must mute at load time to avoid excessive | ||
| 126 | noise. Actually the entire device should be reset to a low power | ||
| 127 | consumption state.</entry> | ||
| 128 | </row> | ||
| 129 | <row> | ||
| 130 | <entry><constant>V4L2_CID_AUDIO_LOUDNESS</constant></entry> | ||
| 131 | <entry>boolean</entry> | ||
| 132 | <entry>Loudness mode (bass boost).</entry> | ||
| 133 | </row> | ||
| 134 | <row> | ||
| 135 | <entry><constant>V4L2_CID_BLACK_LEVEL</constant></entry> | ||
| 136 | <entry>integer</entry> | ||
| 137 | <entry>Another name for brightness (not a synonym of | ||
| 138 | <constant>V4L2_CID_BRIGHTNESS</constant>). This control is deprecated | ||
| 139 | and should not be used in new drivers and applications.</entry> | ||
| 140 | </row> | ||
| 141 | <row> | ||
| 142 | <entry><constant>V4L2_CID_AUTO_WHITE_BALANCE</constant></entry> | ||
| 143 | <entry>boolean</entry> | ||
| 144 | <entry>Automatic white balance (cameras).</entry> | ||
| 145 | </row> | ||
| 146 | <row> | ||
| 147 | <entry><constant>V4L2_CID_DO_WHITE_BALANCE</constant></entry> | ||
| 148 | <entry>button</entry> | ||
| 149 | <entry>This is an action control. When set (the value is | ||
| 150 | ignored), the device will do a white balance and then hold the current | ||
| 151 | setting. Contrast this with the boolean | ||
| 152 | <constant>V4L2_CID_AUTO_WHITE_BALANCE</constant>, which, when | ||
| 153 | activated, keeps adjusting the white balance.</entry> | ||
| 154 | </row> | ||
| 155 | <row> | ||
| 156 | <entry><constant>V4L2_CID_RED_BALANCE</constant></entry> | ||
| 157 | <entry>integer</entry> | ||
| 158 | <entry>Red chroma balance.</entry> | ||
| 159 | </row> | ||
| 160 | <row> | ||
| 161 | <entry><constant>V4L2_CID_BLUE_BALANCE</constant></entry> | ||
| 162 | <entry>integer</entry> | ||
| 163 | <entry>Blue chroma balance.</entry> | ||
| 164 | </row> | ||
| 165 | <row> | ||
| 166 | <entry><constant>V4L2_CID_GAMMA</constant></entry> | ||
| 167 | <entry>integer</entry> | ||
| 168 | <entry>Gamma adjust.</entry> | ||
| 169 | </row> | ||
| 170 | <row> | ||
| 171 | <entry><constant>V4L2_CID_WHITENESS</constant></entry> | ||
| 172 | <entry>integer</entry> | ||
| 173 | <entry>Whiteness for grey-scale devices. This is a synonym | ||
| 174 | for <constant>V4L2_CID_GAMMA</constant>. This control is deprecated | ||
| 175 | and should not be used in new drivers and applications.</entry> | ||
| 176 | </row> | ||
| 177 | <row> | ||
| 178 | <entry><constant>V4L2_CID_EXPOSURE</constant></entry> | ||
| 179 | <entry>integer</entry> | ||
| 180 | <entry>Exposure (cameras). [Unit?]</entry> | ||
| 181 | </row> | ||
| 182 | <row> | ||
| 183 | <entry><constant>V4L2_CID_AUTOGAIN</constant></entry> | ||
| 184 | <entry>boolean</entry> | ||
| 185 | <entry>Automatic gain/exposure control.</entry> | ||
| 186 | </row> | ||
| 187 | <row> | ||
| 188 | <entry><constant>V4L2_CID_GAIN</constant></entry> | ||
| 189 | <entry>integer</entry> | ||
| 190 | <entry>Gain control.</entry> | ||
| 191 | </row> | ||
| 192 | <row> | ||
| 193 | <entry><constant>V4L2_CID_HFLIP</constant></entry> | ||
| 194 | <entry>boolean</entry> | ||
| 195 | <entry>Mirror the picture horizontally.</entry> | ||
| 196 | </row> | ||
| 197 | <row> | ||
| 198 | <entry><constant>V4L2_CID_VFLIP</constant></entry> | ||
| 199 | <entry>boolean</entry> | ||
| 200 | <entry>Mirror the picture vertically.</entry> | ||
| 201 | </row> | ||
| 202 | <row> | ||
| 203 | <entry><constant>V4L2_CID_HCENTER_DEPRECATED</constant> (formerly <constant>V4L2_CID_HCENTER</constant>)</entry> | ||
| 204 | <entry>integer</entry> | ||
| 205 | <entry>Horizontal image centering. This control is | ||
| 206 | deprecated. New drivers and applications should use the <link | ||
| 207 | linkend="camera-controls">Camera class controls</link> | ||
| 208 | <constant>V4L2_CID_PAN_ABSOLUTE</constant>, | ||
| 209 | <constant>V4L2_CID_PAN_RELATIVE</constant> and | ||
| 210 | <constant>V4L2_CID_PAN_RESET</constant> instead.</entry> | ||
| 211 | </row> | ||
| 212 | <row> | ||
| 213 | <entry><constant>V4L2_CID_VCENTER_DEPRECATED</constant> | ||
| 214 | (formerly <constant>V4L2_CID_VCENTER</constant>)</entry> | ||
| 215 | <entry>integer</entry> | ||
| 216 | <entry>Vertical image centering. Centering is intended to | ||
| 217 | <emphasis>physically</emphasis> adjust cameras. For image cropping see | ||
| 218 | <xref linkend="crop" />, for clipping <xref linkend="overlay" />. This | ||
| 219 | control is deprecated. New drivers and applications should use the | ||
| 220 | <link linkend="camera-controls">Camera class controls</link> | ||
| 221 | <constant>V4L2_CID_TILT_ABSOLUTE</constant>, | ||
| 222 | <constant>V4L2_CID_TILT_RELATIVE</constant> and | ||
| 223 | <constant>V4L2_CID_TILT_RESET</constant> instead.</entry> | ||
| 224 | </row> | ||
| 225 | <row id="v4l2-power-line-frequency"> | ||
| 226 | <entry><constant>V4L2_CID_POWER_LINE_FREQUENCY</constant></entry> | ||
| 227 | <entry>enum</entry> | ||
| 228 | <entry>Enables a power line frequency filter to avoid | ||
| 229 | flicker. Possible values for <constant>enum v4l2_power_line_frequency</constant> are: | ||
| 230 | <constant>V4L2_CID_POWER_LINE_FREQUENCY_DISABLED</constant> (0), | ||
| 231 | <constant>V4L2_CID_POWER_LINE_FREQUENCY_50HZ</constant> (1) and | ||
| 232 | <constant>V4L2_CID_POWER_LINE_FREQUENCY_60HZ</constant> (2).</entry> | ||
| 233 | </row> | ||
| 234 | <row> | ||
| 235 | <entry><constant>V4L2_CID_HUE_AUTO</constant></entry> | ||
| 236 | <entry>boolean</entry> | ||
| 237 | <entry>Enables automatic hue control by the device. The | ||
| 238 | effect of setting <constant>V4L2_CID_HUE</constant> while automatic | ||
| 239 | hue control is enabled is undefined, drivers should ignore such | ||
| 240 | request.</entry> | ||
| 241 | </row> | ||
| 242 | <row> | ||
| 243 | <entry><constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant></entry> | ||
| 244 | <entry>integer</entry> | ||
| 245 | <entry>This control specifies the white balance settings | ||
| 246 | as a color temperature in Kelvin. A driver should have a minimum of | ||
| 247 | 2800 (incandescent) to 6500 (daylight). For more information about | ||
| 248 | color temperature see <ulink | ||
| 249 | url="http://en.wikipedia.org/wiki/Color_temperature">Wikipedia</ulink>.</entry> | ||
| 250 | </row> | ||
| 251 | <row> | ||
| 252 | <entry><constant>V4L2_CID_SHARPNESS</constant></entry> | ||
| 253 | <entry>integer</entry> | ||
| 254 | <entry>Adjusts the sharpness filters in a camera. The | ||
| 255 | minimum value disables the filters, higher values give a sharper | ||
| 256 | picture.</entry> | ||
| 257 | </row> | ||
| 258 | <row> | ||
| 259 | <entry><constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant></entry> | ||
| 260 | <entry>integer</entry> | ||
| 261 | <entry>Adjusts the backlight compensation in a camera. The | ||
| 262 | minimum value disables backlight compensation.</entry> | ||
| 263 | </row> | ||
| 264 | <row> | ||
| 265 | <entry><constant>V4L2_CID_CHROMA_AGC</constant></entry> | ||
| 266 | <entry>boolean</entry> | ||
| 267 | <entry>Chroma automatic gain control.</entry> | ||
| 268 | </row> | ||
| 269 | <row> | ||
| 270 | <entry><constant>V4L2_CID_COLOR_KILLER</constant></entry> | ||
| 271 | <entry>boolean</entry> | ||
| 272 | <entry>Enable the color killer (&ie; force a black & white image in case of a weak video signal).</entry> | ||
| 273 | </row> | ||
| 274 | <row id="v4l2-colorfx"> | ||
| 275 | <entry><constant>V4L2_CID_COLORFX</constant></entry> | ||
| 276 | <entry>enum</entry> | ||
| 277 | <entry>Selects a color effect. Possible values for | ||
| 278 | <constant>enum v4l2_colorfx</constant> are: | ||
| 279 | <constant>V4L2_COLORFX_NONE</constant> (0), | ||
| 280 | <constant>V4L2_COLORFX_BW</constant> (1) and | ||
| 281 | <constant>V4L2_COLORFX_SEPIA</constant> (2).</entry> | ||
| 282 | </row> | ||
| 283 | <row> | ||
| 284 | <entry><constant>V4L2_CID_LASTP1</constant></entry> | ||
| 285 | <entry></entry> | ||
| 286 | <entry>End of the predefined control IDs (currently | ||
| 287 | <constant>V4L2_CID_COLORFX</constant> + 1).</entry> | ||
| 288 | </row> | ||
| 289 | <row> | ||
| 290 | <entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry> | ||
| 291 | <entry></entry> | ||
| 292 | <entry>ID of the first custom (driver specific) control. | ||
| 293 | Applications depending on particular custom controls should check the | ||
| 294 | driver name and version, see <xref linkend="querycap" />.</entry> | ||
| 295 | </row> | ||
| 296 | </tbody> | ||
| 297 | </tgroup> | ||
| 298 | </table> | ||
| 299 | |||
| 300 | <para>Applications can enumerate the available controls with the | ||
| 301 | &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls, get and set a | ||
| 302 | control value with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls. | ||
| 303 | Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>, | ||
| 304 | <constant>VIDIOC_G_CTRL</constant> and | ||
| 305 | <constant>VIDIOC_S_CTRL</constant> when the device has one or more | ||
| 306 | controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or | ||
| 307 | more menu type controls.</para> | ||
| 308 | |||
| 309 | <example> | ||
| 310 | <title>Enumerating all controls</title> | ||
| 311 | |||
| 312 | <programlisting> | ||
| 313 | &v4l2-queryctrl; queryctrl; | ||
| 314 | &v4l2-querymenu; querymenu; | ||
| 315 | |||
| 316 | static void | ||
| 317 | enumerate_menu (void) | ||
| 318 | { | ||
| 319 | printf (" Menu items:\n"); | ||
| 320 | |||
| 321 | memset (&querymenu, 0, sizeof (querymenu)); | ||
| 322 | querymenu.id = queryctrl.id; | ||
| 323 | |||
| 324 | for (querymenu.index = queryctrl.minimum; | ||
| 325 | querymenu.index <= queryctrl.maximum; | ||
| 326 | querymenu.index++) { | ||
| 327 | if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &querymenu)) { | ||
| 328 | printf (" %s\n", querymenu.name); | ||
| 329 | } else { | ||
| 330 | perror ("VIDIOC_QUERYMENU"); | ||
| 331 | exit (EXIT_FAILURE); | ||
| 332 | } | ||
| 333 | } | ||
| 334 | } | ||
| 335 | |||
| 336 | memset (&queryctrl, 0, sizeof (queryctrl)); | ||
| 337 | |||
| 338 | for (queryctrl.id = V4L2_CID_BASE; | ||
| 339 | queryctrl.id < V4L2_CID_LASTP1; | ||
| 340 | queryctrl.id++) { | ||
| 341 | if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { | ||
| 342 | if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) | ||
| 343 | continue; | ||
| 344 | |||
| 345 | printf ("Control %s\n", queryctrl.name); | ||
| 346 | |||
| 347 | if (queryctrl.type == V4L2_CTRL_TYPE_MENU) | ||
| 348 | enumerate_menu (); | ||
| 349 | } else { | ||
| 350 | if (errno == EINVAL) | ||
| 351 | continue; | ||
| 352 | |||
| 353 | perror ("VIDIOC_QUERYCTRL"); | ||
| 354 | exit (EXIT_FAILURE); | ||
| 355 | } | ||
| 356 | } | ||
| 357 | |||
| 358 | for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; | ||
| 359 | queryctrl.id++) { | ||
| 360 | if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { | ||
| 361 | if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) | ||
| 362 | continue; | ||
| 363 | |||
| 364 | printf ("Control %s\n", queryctrl.name); | ||
| 365 | |||
| 366 | if (queryctrl.type == V4L2_CTRL_TYPE_MENU) | ||
| 367 | enumerate_menu (); | ||
| 368 | } else { | ||
| 369 | if (errno == EINVAL) | ||
| 370 | break; | ||
| 371 | |||
| 372 | perror ("VIDIOC_QUERYCTRL"); | ||
| 373 | exit (EXIT_FAILURE); | ||
| 374 | } | ||
| 375 | } | ||
| 376 | </programlisting> | ||
| 377 | </example> | ||
| 378 | |||
| 379 | <example> | ||
| 380 | <title>Changing controls</title> | ||
| 381 | |||
| 382 | <programlisting> | ||
| 383 | &v4l2-queryctrl; queryctrl; | ||
| 384 | &v4l2-control; control; | ||
| 385 | |||
| 386 | memset (&queryctrl, 0, sizeof (queryctrl)); | ||
| 387 | queryctrl.id = V4L2_CID_BRIGHTNESS; | ||
| 388 | |||
| 389 | if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { | ||
| 390 | if (errno != EINVAL) { | ||
| 391 | perror ("VIDIOC_QUERYCTRL"); | ||
| 392 | exit (EXIT_FAILURE); | ||
| 393 | } else { | ||
| 394 | printf ("V4L2_CID_BRIGHTNESS is not supported\n"); | ||
| 395 | } | ||
| 396 | } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { | ||
| 397 | printf ("V4L2_CID_BRIGHTNESS is not supported\n"); | ||
| 398 | } else { | ||
| 399 | memset (&control, 0, sizeof (control)); | ||
| 400 | control.id = V4L2_CID_BRIGHTNESS; | ||
| 401 | control.value = queryctrl.default_value; | ||
| 402 | |||
| 403 | if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control)) { | ||
| 404 | perror ("VIDIOC_S_CTRL"); | ||
| 405 | exit (EXIT_FAILURE); | ||
| 406 | } | ||
| 407 | } | ||
| 408 | |||
| 409 | memset (&control, 0, sizeof (control)); | ||
| 410 | control.id = V4L2_CID_CONTRAST; | ||
| 411 | |||
| 412 | if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &control)) { | ||
| 413 | control.value += 1; | ||
| 414 | |||
| 415 | /* The driver may clamp the value or return ERANGE, ignored here */ | ||
| 416 | |||
| 417 | if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control) | ||
| 418 | && errno != ERANGE) { | ||
| 419 | perror ("VIDIOC_S_CTRL"); | ||
| 420 | exit (EXIT_FAILURE); | ||
| 421 | } | ||
| 422 | /* Ignore if V4L2_CID_CONTRAST is unsupported */ | ||
| 423 | } else if (errno != EINVAL) { | ||
| 424 | perror ("VIDIOC_G_CTRL"); | ||
| 425 | exit (EXIT_FAILURE); | ||
| 426 | } | ||
| 427 | |||
| 428 | control.id = V4L2_CID_AUDIO_MUTE; | ||
| 429 | control.value = TRUE; /* silence */ | ||
| 430 | |||
| 431 | /* Errors ignored */ | ||
| 432 | ioctl (fd, VIDIOC_S_CTRL, &control); | ||
| 433 | </programlisting> | ||
| 434 | </example> | ||
| 435 | </section> | ||
| 436 | |||
| 437 | <section id="extended-controls"> | ||
| 438 | <title>Extended Controls</title> | ||
| 439 | |||
| 440 | <section> | ||
| 441 | <title>Introduction</title> | ||
| 442 | |||
| 443 | <para>The control mechanism as originally designed was meant | ||
| 444 | to be used for user settings (brightness, saturation, etc). However, | ||
| 445 | it turned out to be a very useful model for implementing more | ||
| 446 | complicated driver APIs where each driver implements only a subset of | ||
| 447 | a larger API.</para> | ||
| 448 | |||
| 449 | <para>The MPEG encoding API was the driving force behind | ||
| 450 | designing and implementing this extended control mechanism: the MPEG | ||
| 451 | standard is quite large and the currently supported hardware MPEG | ||
| 452 | encoders each only implement a subset of this standard. Further more, | ||
| 453 | many parameters relating to how the video is encoded into an MPEG | ||
| 454 | stream are specific to the MPEG encoding chip since the MPEG standard | ||
| 455 | only defines the format of the resulting MPEG stream, not how the | ||
| 456 | video is actually encoded into that format.</para> | ||
| 457 | |||
| 458 | <para>Unfortunately, the original control API lacked some | ||
| 459 | features needed for these new uses and so it was extended into the | ||
| 460 | (not terribly originally named) extended control API.</para> | ||
| 461 | |||
| 462 | <para>Even though the MPEG encoding API was the first effort | ||
| 463 | to use the Extended Control API, nowadays there are also other classes | ||
| 464 | of Extended Controls, such as Camera Controls and FM Transmitter Controls. | ||
| 465 | The Extended Controls API as well as all Extended Controls classes are | ||
| 466 | described in the following text.</para> | ||
| 467 | </section> | ||
| 468 | |||
| 469 | <section> | ||
| 470 | <title>The Extended Control API</title> | ||
| 471 | |||
| 472 | <para>Three new ioctls are available: &VIDIOC-G-EXT-CTRLS;, | ||
| 473 | &VIDIOC-S-EXT-CTRLS; and &VIDIOC-TRY-EXT-CTRLS;. These ioctls act on | ||
| 474 | arrays of controls (as opposed to the &VIDIOC-G-CTRL; and | ||
| 475 | &VIDIOC-S-CTRL; ioctls that act on a single control). This is needed | ||
| 476 | since it is often required to atomically change several controls at | ||
| 477 | once.</para> | ||
| 478 | |||
| 479 | <para>Each of the new ioctls expects a pointer to a | ||
| 480 | &v4l2-ext-controls;. This structure contains a pointer to the control | ||
| 481 | array, a count of the number of controls in that array and a control | ||
| 482 | class. Control classes are used to group similar controls into a | ||
| 483 | single class. For example, control class | ||
| 484 | <constant>V4L2_CTRL_CLASS_USER</constant> contains all user controls | ||
| 485 | (&ie; all controls that can also be set using the old | ||
| 486 | <constant>VIDIOC_S_CTRL</constant> ioctl). Control class | ||
| 487 | <constant>V4L2_CTRL_CLASS_MPEG</constant> contains all controls | ||
| 488 | relating to MPEG encoding, etc.</para> | ||
| 489 | |||
| 490 | <para>All controls in the control array must belong to the | ||
| 491 | specified control class. An error is returned if this is not the | ||
| 492 | case.</para> | ||
| 493 | |||
| 494 | <para>It is also possible to use an empty control array (count | ||
| 495 | == 0) to check whether the specified control class is | ||
| 496 | supported.</para> | ||
| 497 | |||
| 498 | <para>The control array is a &v4l2-ext-control; array. The | ||
| 499 | <structname>v4l2_ext_control</structname> structure is very similar to | ||
| 500 | &v4l2-control;, except for the fact that it also allows for 64-bit | ||
| 501 | values and pointers to be passed.</para> | ||
| 502 | |||
| 503 | <para>It is important to realize that due to the flexibility of | ||
| 504 | controls it is necessary to check whether the control you want to set | ||
| 505 | actually is supported in the driver and what the valid range of values | ||
| 506 | is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to | ||
| 507 | check this. Also note that it is possible that some of the menu | ||
| 508 | indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant> | ||
| 509 | may not be supported (<constant>VIDIOC_QUERYMENU</constant> will | ||
| 510 | return an error). A good example is the list of supported MPEG audio | ||
| 511 | bitrates. Some drivers only support one or two bitrates, others | ||
| 512 | support a wider range.</para> | ||
| 513 | </section> | ||
| 514 | |||
| 515 | <section> | ||
| 516 | <title>Enumerating Extended Controls</title> | ||
| 517 | |||
| 518 | <para>The recommended way to enumerate over the extended | ||
| 519 | controls is by using &VIDIOC-QUERYCTRL; in combination with the | ||
| 520 | <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag:</para> | ||
| 521 | |||
| 522 | <informalexample> | ||
| 523 | <programlisting> | ||
| 524 | &v4l2-queryctrl; qctrl; | ||
| 525 | |||
| 526 | qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; | ||
| 527 | while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) { | ||
| 528 | /* ... */ | ||
| 529 | qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; | ||
| 530 | } | ||
| 531 | </programlisting> | ||
| 532 | </informalexample> | ||
| 533 | |||
| 534 | <para>The initial control ID is set to 0 ORed with the | ||
| 535 | <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag. The | ||
| 536 | <constant>VIDIOC_QUERYCTRL</constant> ioctl will return the first | ||
| 537 | control with a higher ID than the specified one. When no such controls | ||
| 538 | are found an error is returned.</para> | ||
| 539 | |||
| 540 | <para>If you want to get all controls within a specific control | ||
| 541 | class, then you can set the initial | ||
| 542 | <structfield>qctrl.id</structfield> value to the control class and add | ||
| 543 | an extra check to break out of the loop when a control of another | ||
| 544 | control class is found:</para> | ||
| 545 | |||
| 546 | <informalexample> | ||
| 547 | <programlisting> | ||
| 548 | qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; | ||
| 549 | while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) { | ||
| 550 | if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG) | ||
| 551 | break; | ||
| 552 | /* ... */ | ||
| 553 | qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; | ||
| 554 | } | ||
| 555 | </programlisting> | ||
| 556 | </informalexample> | ||
| 557 | |||
| 558 | <para>The 32-bit <structfield>qctrl.id</structfield> value is | ||
| 559 | subdivided into three bit ranges: the top 4 bits are reserved for | ||
| 560 | flags (⪚ <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>) and are not | ||
| 561 | actually part of the ID. The remaining 28 bits form the control ID, of | ||
| 562 | which the most significant 12 bits define the control class and the | ||
| 563 | least significant 16 bits identify the control within the control | ||
| 564 | class. It is guaranteed that these last 16 bits are always non-zero | ||
| 565 | for controls. The range of 0x1000 and up are reserved for | ||
| 566 | driver-specific controls. The macro | ||
| 567 | <constant>V4L2_CTRL_ID2CLASS(id)</constant> returns the control class | ||
| 568 | ID based on a control ID.</para> | ||
| 569 | |||
| 570 | <para>If the driver does not support extended controls, then | ||
| 571 | <constant>VIDIOC_QUERYCTRL</constant> will fail when used in | ||
| 572 | combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In | ||
| 573 | that case the old method of enumerating control should be used (see | ||
| 574 | 1.8). But if it is supported, then it is guaranteed to enumerate over | ||
| 575 | all controls, including driver-private controls.</para> | ||
| 576 | </section> | ||
| 577 | |||
| 578 | <section> | ||
| 579 | <title>Creating Control Panels</title> | ||
| 580 | |||
| 581 | <para>It is possible to create control panels for a graphical | ||
| 582 | user interface where the user can select the various controls. | ||
| 583 | Basically you will have to iterate over all controls using the method | ||
| 584 | described above. Each control class starts with a control of type | ||
| 585 | <constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant>. | ||
| 586 | <constant>VIDIOC_QUERYCTRL</constant> will return the name of this | ||
| 587 | control class which can be used as the title of a tab page within a | ||
| 588 | control panel.</para> | ||
| 589 | |||
| 590 | <para>The flags field of &v4l2-queryctrl; also contains hints on | ||
| 591 | the behavior of the control. See the &VIDIOC-QUERYCTRL; documentation | ||
| 592 | for more details.</para> | ||
| 593 | </section> | ||
| 594 | |||
| 595 | <section id="mpeg-controls"> | ||
| 596 | <title>MPEG Control Reference</title> | ||
| 597 | |||
| 598 | <para>Below all controls within the MPEG control class are | ||
| 599 | described. First the generic controls, then controls specific for | ||
| 600 | certain hardware.</para> | ||
| 601 | |||
| 602 | <section> | ||
| 603 | <title>Generic MPEG Controls</title> | ||
| 604 | |||
| 605 | <table pgwide="1" frame="none" id="mpeg-control-id"> | ||
| 606 | <title>MPEG Control IDs</title> | ||
| 607 | <tgroup cols="4"> | ||
| 608 | <colspec colname="c1" colwidth="1*" /> | ||
| 609 | <colspec colname="c2" colwidth="6*" /> | ||
| 610 | <colspec colname="c3" colwidth="2*" /> | ||
| 611 | <colspec colname="c4" colwidth="6*" /> | ||
| 612 | <spanspec namest="c1" nameend="c2" spanname="id" /> | ||
| 613 | <spanspec namest="c2" nameend="c4" spanname="descr" /> | ||
| 614 | <thead> | ||
| 615 | <row> | ||
| 616 | <entry spanname="id" align="left">ID</entry> | ||
| 617 | <entry align="left">Type</entry> | ||
| 618 | </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> | ||
| 619 | </row> | ||
| 620 | </thead> | ||
| 621 | <tbody valign="top"> | ||
| 622 | <row><entry></entry></row> | ||
| 623 | <row> | ||
| 624 | <entry spanname="id"><constant>V4L2_CID_MPEG_CLASS</constant> </entry> | ||
| 625 | <entry>class</entry> | ||
| 626 | </row><row><entry spanname="descr">The MPEG class | ||
| 627 | descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a | ||
| 628 | description of this control class. This description can be used as the | ||
| 629 | caption of a Tab page in a GUI, for example.</entry> | ||
| 630 | </row> | ||
| 631 | <row><entry></entry></row> | ||
| 632 | <row id="v4l2-mpeg-stream-type"> | ||
| 633 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_TYPE</constant> </entry> | ||
| 634 | <entry>enum v4l2_mpeg_stream_type</entry> | ||
| 635 | </row><row><entry spanname="descr">The MPEG-1, -2 or -4 | ||
| 636 | output stream type. One cannot assume anything here. Each hardware | ||
| 637 | MPEG encoder tends to support different subsets of the available MPEG | ||
| 638 | stream types. The currently defined stream types are:</entry> | ||
| 639 | </row> | ||
| 640 | <row> | ||
| 641 | <entrytbl spanname="descr" cols="2"> | ||
| 642 | <tbody valign="top"> | ||
| 643 | <row> | ||
| 644 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_PS</constant> </entry> | ||
| 645 | <entry>MPEG-2 program stream</entry> | ||
| 646 | </row> | ||
| 647 | <row> | ||
| 648 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_TS</constant> </entry> | ||
| 649 | <entry>MPEG-2 transport stream</entry> | ||
| 650 | </row> | ||
| 651 | <row> | ||
| 652 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_SS</constant> </entry> | ||
| 653 | <entry>MPEG-1 system stream</entry> | ||
| 654 | </row> | ||
| 655 | <row> | ||
| 656 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_DVD</constant> </entry> | ||
| 657 | <entry>MPEG-2 DVD-compatible stream</entry> | ||
| 658 | </row> | ||
| 659 | <row> | ||
| 660 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_VCD</constant> </entry> | ||
| 661 | <entry>MPEG-1 VCD-compatible stream</entry> | ||
| 662 | </row> | ||
| 663 | <row> | ||
| 664 | <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD</constant> </entry> | ||
| 665 | <entry>MPEG-2 SVCD-compatible stream</entry> | ||
| 666 | </row> | ||
| 667 | </tbody> | ||
| 668 | </entrytbl> | ||
| 669 | </row> | ||
| 670 | <row><entry></entry></row> | ||
| 671 | <row> | ||
| 672 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PMT</constant> </entry> | ||
| 673 | <entry>integer</entry> | ||
| 674 | </row><row><entry spanname="descr">Program Map Table | ||
| 675 | Packet ID for the MPEG transport stream (default 16)</entry> | ||
| 676 | </row> | ||
| 677 | <row><entry></entry></row> | ||
| 678 | <row> | ||
| 679 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_AUDIO</constant> </entry> | ||
| 680 | <entry>integer</entry> | ||
| 681 | </row><row><entry spanname="descr">Audio Packet ID for | ||
| 682 | the MPEG transport stream (default 256)</entry> | ||
| 683 | </row> | ||
| 684 | <row><entry></entry></row> | ||
| 685 | <row> | ||
| 686 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_VIDEO</constant> </entry> | ||
| 687 | <entry>integer</entry> | ||
| 688 | </row><row><entry spanname="descr">Video Packet ID for | ||
| 689 | the MPEG transport stream (default 260)</entry> | ||
| 690 | </row> | ||
| 691 | <row><entry></entry></row> | ||
| 692 | <row> | ||
| 693 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PCR</constant> </entry> | ||
| 694 | <entry>integer</entry> | ||
| 695 | </row><row><entry spanname="descr">Packet ID for the | ||
| 696 | MPEG transport stream carrying PCR fields (default 259)</entry> | ||
| 697 | </row> | ||
| 698 | <row><entry></entry></row> | ||
| 699 | <row> | ||
| 700 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_AUDIO</constant> </entry> | ||
| 701 | <entry>integer</entry> | ||
| 702 | </row><row><entry spanname="descr">Audio ID for MPEG | ||
| 703 | PES</entry> | ||
| 704 | </row> | ||
| 705 | <row><entry></entry></row> | ||
| 706 | <row> | ||
| 707 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_VIDEO</constant> </entry> | ||
| 708 | <entry>integer</entry> | ||
| 709 | </row><row><entry spanname="descr">Video ID for MPEG | ||
| 710 | PES</entry> | ||
| 711 | </row> | ||
| 712 | <row><entry></entry></row> | ||
| 713 | <row id="v4l2-mpeg-stream-vbi-fmt"> | ||
| 714 | <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_VBI_FMT</constant> </entry> | ||
| 715 | <entry>enum v4l2_mpeg_stream_vbi_fmt</entry> | ||
| 716 | </row><row><entry spanname="descr">Some cards can embed | ||
| 717 | VBI data (⪚ Closed Caption, Teletext) into the MPEG stream. This | ||
| 718 | control selects whether VBI data should be embedded, and if so, what | ||
| 719 | embedding method should be used. The list of possible VBI formats | ||
| 720 | depends on the driver. The currently defined VBI format types | ||
| 721 | are:</entry> | ||
| 722 | </row> | ||
| 723 | <row> | ||
| 724 | <entrytbl spanname="descr" cols="2"> | ||
| 725 | <tbody valign="top"> | ||
| 726 | <row> | ||
| 727 | <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_NONE</constant> </entry> | ||
| 728 | <entry>No VBI in the MPEG stream</entry> | ||
| 729 | </row> | ||
| 730 | <row> | ||
| 731 | <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant> </entry> | ||
| 732 | <entry>VBI in private packets, IVTV format (documented | ||
| 733 | in the kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>)</entry> | ||
| 734 | </row> | ||
| 735 | </tbody> | ||
| 736 | </entrytbl> | ||
| 737 | </row> | ||
| 738 | <row><entry></entry></row> | ||
| 739 | <row id="v4l2-mpeg-audio-sampling-freq"> | ||
| 740 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ</constant> </entry> | ||
| 741 | <entry>enum v4l2_mpeg_audio_sampling_freq</entry> | ||
| 742 | </row><row><entry spanname="descr">MPEG Audio sampling | ||
| 743 | frequency. Possible values are:</entry> | ||
| 744 | </row> | ||
| 745 | <row> | ||
| 746 | <entrytbl spanname="descr" cols="2"> | ||
| 747 | <tbody valign="top"> | ||
| 748 | <row> | ||
| 749 | <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100</constant> </entry> | ||
| 750 | <entry>44.1 kHz</entry> | ||
| 751 | </row> | ||
| 752 | <row> | ||
| 753 | <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000</constant> </entry> | ||
| 754 | <entry>48 kHz</entry> | ||
| 755 | </row> | ||
| 756 | <row> | ||
| 757 | <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000</constant> </entry> | ||
| 758 | <entry>32 kHz</entry> | ||
| 759 | </row> | ||
| 760 | </tbody> | ||
| 761 | </entrytbl> | ||
| 762 | </row> | ||
| 763 | <row><entry></entry></row> | ||
| 764 | <row id="v4l2-mpeg-audio-encoding"> | ||
| 765 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_ENCODING</constant> </entry> | ||
| 766 | <entry>enum v4l2_mpeg_audio_encoding</entry> | ||
| 767 | </row><row><entry spanname="descr">MPEG Audio encoding. | ||
| 768 | Possible values are:</entry> | ||
| 769 | </row> | ||
| 770 | <row> | ||
| 771 | <entrytbl spanname="descr" cols="2"> | ||
| 772 | <tbody valign="top"> | ||
| 773 | <row> | ||
| 774 | <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_1</constant> </entry> | ||
| 775 | <entry>MPEG-1/2 Layer I encoding</entry> | ||
| 776 | </row> | ||
| 777 | <row> | ||
| 778 | <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_2</constant> </entry> | ||
| 779 | <entry>MPEG-1/2 Layer II encoding</entry> | ||
| 780 | </row> | ||
| 781 | <row> | ||
| 782 | <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_3</constant> </entry> | ||
| 783 | <entry>MPEG-1/2 Layer III encoding</entry> | ||
| 784 | </row> | ||
| 785 | <row> | ||
| 786 | <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> </entry> | ||
| 787 | <entry>MPEG-2/4 AAC (Advanced Audio Coding)</entry> | ||
| 788 | </row> | ||
| 789 | <row> | ||
| 790 | <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> </entry> | ||
| 791 | <entry>AC-3 aka ATSC A/52 encoding</entry> | ||
| 792 | </row> | ||
| 793 | </tbody> | ||
| 794 | </entrytbl> | ||
| 795 | </row> | ||
| 796 | <row><entry></entry></row> | ||
| 797 | <row id="v4l2-mpeg-audio-l1-bitrate"> | ||
| 798 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L1_BITRATE</constant> </entry> | ||
| 799 | <entry>enum v4l2_mpeg_audio_l1_bitrate</entry> | ||
| 800 | </row><row><entry spanname="descr">MPEG-1/2 Layer I bitrate. | ||
| 801 | Possible values are:</entry> | ||
| 802 | </row> | ||
| 803 | <row> | ||
| 804 | <entrytbl spanname="descr" cols="2"> | ||
| 805 | <tbody valign="top"> | ||
| 806 | <row> | ||
| 807 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_32K</constant> </entry> | ||
| 808 | <entry>32 kbit/s</entry></row> | ||
| 809 | <row> | ||
| 810 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_64K</constant> </entry> | ||
| 811 | <entry>64 kbit/s</entry> | ||
| 812 | </row> | ||
| 813 | <row> | ||
| 814 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_96K</constant> </entry> | ||
| 815 | <entry>96 kbit/s</entry> | ||
| 816 | </row> | ||
| 817 | <row> | ||
| 818 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_128K</constant> </entry> | ||
| 819 | <entry>128 kbit/s</entry> | ||
| 820 | </row> | ||
| 821 | <row> | ||
| 822 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_160K</constant> </entry> | ||
| 823 | <entry>160 kbit/s</entry> | ||
| 824 | </row> | ||
| 825 | <row> | ||
| 826 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_192K</constant> </entry> | ||
| 827 | <entry>192 kbit/s</entry> | ||
| 828 | </row> | ||
| 829 | <row> | ||
| 830 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_224K</constant> </entry> | ||
| 831 | <entry>224 kbit/s</entry> | ||
| 832 | </row> | ||
| 833 | <row> | ||
| 834 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_256K</constant> </entry> | ||
| 835 | <entry>256 kbit/s</entry> | ||
| 836 | </row> | ||
| 837 | <row> | ||
| 838 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_288K</constant> </entry> | ||
| 839 | <entry>288 kbit/s</entry> | ||
| 840 | </row> | ||
| 841 | <row> | ||
| 842 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_320K</constant> </entry> | ||
| 843 | <entry>320 kbit/s</entry> | ||
| 844 | </row> | ||
| 845 | <row> | ||
| 846 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_352K</constant> </entry> | ||
| 847 | <entry>352 kbit/s</entry> | ||
| 848 | </row> | ||
| 849 | <row> | ||
| 850 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_384K</constant> </entry> | ||
| 851 | <entry>384 kbit/s</entry> | ||
| 852 | </row> | ||
| 853 | <row> | ||
| 854 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_416K</constant> </entry> | ||
| 855 | <entry>416 kbit/s</entry> | ||
| 856 | </row> | ||
| 857 | <row> | ||
| 858 | <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_448K</constant> </entry> | ||
| 859 | <entry>448 kbit/s</entry> | ||
| 860 | </row> | ||
| 861 | </tbody> | ||
| 862 | </entrytbl> | ||
| 863 | </row> | ||
| 864 | <row><entry></entry></row> | ||
| 865 | <row id="v4l2-mpeg-audio-l2-bitrate"> | ||
| 866 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L2_BITRATE</constant> </entry> | ||
| 867 | <entry>enum v4l2_mpeg_audio_l2_bitrate</entry> | ||
| 868 | </row><row><entry spanname="descr">MPEG-1/2 Layer II bitrate. | ||
| 869 | Possible values are:</entry> | ||
| 870 | </row> | ||
| 871 | <row> | ||
| 872 | <entrytbl spanname="descr" cols="2"> | ||
| 873 | <tbody valign="top"> | ||
| 874 | <row> | ||
| 875 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_32K</constant> </entry> | ||
| 876 | <entry>32 kbit/s</entry> | ||
| 877 | </row> | ||
| 878 | <row> | ||
| 879 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_48K</constant> </entry> | ||
| 880 | <entry>48 kbit/s</entry> | ||
| 881 | </row> | ||
| 882 | <row> | ||
| 883 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_56K</constant> </entry> | ||
| 884 | <entry>56 kbit/s</entry> | ||
| 885 | </row> | ||
| 886 | <row> | ||
| 887 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_64K</constant> </entry> | ||
| 888 | <entry>64 kbit/s</entry> | ||
| 889 | </row> | ||
| 890 | <row> | ||
| 891 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_80K</constant> </entry> | ||
| 892 | <entry>80 kbit/s</entry> | ||
| 893 | </row> | ||
| 894 | <row> | ||
| 895 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_96K</constant> </entry> | ||
| 896 | <entry>96 kbit/s</entry> | ||
| 897 | </row> | ||
| 898 | <row> | ||
| 899 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_112K</constant> </entry> | ||
| 900 | <entry>112 kbit/s</entry> | ||
| 901 | </row> | ||
| 902 | <row> | ||
| 903 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_128K</constant> </entry> | ||
| 904 | <entry>128 kbit/s</entry> | ||
| 905 | </row> | ||
| 906 | <row> | ||
| 907 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_160K</constant> </entry> | ||
| 908 | <entry>160 kbit/s</entry> | ||
| 909 | </row> | ||
| 910 | <row> | ||
| 911 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_192K</constant> </entry> | ||
| 912 | <entry>192 kbit/s</entry> | ||
| 913 | </row> | ||
| 914 | <row> | ||
| 915 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_224K</constant> </entry> | ||
| 916 | <entry>224 kbit/s</entry> | ||
| 917 | </row> | ||
| 918 | <row> | ||
| 919 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_256K</constant> </entry> | ||
| 920 | <entry>256 kbit/s</entry> | ||
| 921 | </row> | ||
| 922 | <row> | ||
| 923 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_320K</constant> </entry> | ||
| 924 | <entry>320 kbit/s</entry> | ||
| 925 | </row> | ||
| 926 | <row> | ||
| 927 | <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_384K</constant> </entry> | ||
| 928 | <entry>384 kbit/s</entry> | ||
| 929 | </row> | ||
| 930 | </tbody> | ||
| 931 | </entrytbl> | ||
| 932 | </row> | ||
| 933 | <row><entry></entry></row> | ||
| 934 | <row id="v4l2-mpeg-audio-l3-bitrate"> | ||
| 935 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L3_BITRATE</constant> </entry> | ||
| 936 | <entry>enum v4l2_mpeg_audio_l3_bitrate</entry> | ||
| 937 | </row><row><entry spanname="descr">MPEG-1/2 Layer III bitrate. | ||
| 938 | Possible values are:</entry> | ||
| 939 | </row> | ||
| 940 | <row> | ||
| 941 | <entrytbl spanname="descr" cols="2"> | ||
| 942 | <tbody valign="top"> | ||
| 943 | <row> | ||
| 944 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_32K</constant> </entry> | ||
| 945 | <entry>32 kbit/s</entry> | ||
| 946 | </row> | ||
| 947 | <row> | ||
| 948 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_40K</constant> </entry> | ||
| 949 | <entry>40 kbit/s</entry> | ||
| 950 | </row> | ||
| 951 | <row> | ||
| 952 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_48K</constant> </entry> | ||
| 953 | <entry>48 kbit/s</entry> | ||
| 954 | </row> | ||
| 955 | <row> | ||
| 956 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_56K</constant> </entry> | ||
| 957 | <entry>56 kbit/s</entry> | ||
| 958 | </row> | ||
| 959 | <row> | ||
| 960 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_64K</constant> </entry> | ||
| 961 | <entry>64 kbit/s</entry> | ||
| 962 | </row> | ||
| 963 | <row> | ||
| 964 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_80K</constant> </entry> | ||
| 965 | <entry>80 kbit/s</entry> | ||
| 966 | </row> | ||
| 967 | <row> | ||
| 968 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_96K</constant> </entry> | ||
| 969 | <entry>96 kbit/s</entry> | ||
| 970 | </row> | ||
| 971 | <row> | ||
| 972 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_112K</constant> </entry> | ||
| 973 | <entry>112 kbit/s</entry> | ||
| 974 | </row> | ||
| 975 | <row> | ||
| 976 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_128K</constant> </entry> | ||
| 977 | <entry>128 kbit/s</entry> | ||
| 978 | </row> | ||
| 979 | <row> | ||
| 980 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_160K</constant> </entry> | ||
| 981 | <entry>160 kbit/s</entry> | ||
| 982 | </row> | ||
| 983 | <row> | ||
| 984 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_192K</constant> </entry> | ||
| 985 | <entry>192 kbit/s</entry> | ||
| 986 | </row> | ||
| 987 | <row> | ||
| 988 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_224K</constant> </entry> | ||
| 989 | <entry>224 kbit/s</entry> | ||
| 990 | </row> | ||
| 991 | <row> | ||
| 992 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_256K</constant> </entry> | ||
| 993 | <entry>256 kbit/s</entry> | ||
| 994 | </row> | ||
| 995 | <row> | ||
| 996 | <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_320K</constant> </entry> | ||
| 997 | <entry>320 kbit/s</entry> | ||
| 998 | </row> | ||
| 999 | </tbody> | ||
| 1000 | </entrytbl> | ||
| 1001 | </row> | ||
| 1002 | <row><entry></entry></row> | ||
| 1003 | <row> | ||
| 1004 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AAC_BITRATE</constant> </entry> | ||
| 1005 | <entry>integer</entry> | ||
| 1006 | </row><row><entry spanname="descr">AAC bitrate in bits per second.</entry> | ||
| 1007 | </row> | ||
| 1008 | <row><entry></entry></row> | ||
| 1009 | <row id="v4l2-mpeg-audio-ac3-bitrate"> | ||
| 1010 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AC3_BITRATE</constant> </entry> | ||
| 1011 | <entry>enum v4l2_mpeg_audio_ac3_bitrate</entry> | ||
| 1012 | </row><row><entry spanname="descr">AC-3 bitrate. | ||
| 1013 | Possible values are:</entry> | ||
| 1014 | </row> | ||
| 1015 | <row> | ||
| 1016 | <entrytbl spanname="descr" cols="2"> | ||
| 1017 | <tbody valign="top"> | ||
| 1018 | <row> | ||
| 1019 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_32K</constant> </entry> | ||
| 1020 | <entry>32 kbit/s</entry> | ||
| 1021 | </row> | ||
| 1022 | <row> | ||
| 1023 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_40K</constant> </entry> | ||
| 1024 | <entry>40 kbit/s</entry> | ||
| 1025 | </row> | ||
| 1026 | <row> | ||
| 1027 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_48K</constant> </entry> | ||
| 1028 | <entry>48 kbit/s</entry> | ||
| 1029 | </row> | ||
| 1030 | <row> | ||
| 1031 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_56K</constant> </entry> | ||
| 1032 | <entry>56 kbit/s</entry> | ||
| 1033 | </row> | ||
| 1034 | <row> | ||
| 1035 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_64K</constant> </entry> | ||
| 1036 | <entry>64 kbit/s</entry> | ||
| 1037 | </row> | ||
| 1038 | <row> | ||
| 1039 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_80K</constant> </entry> | ||
| 1040 | <entry>80 kbit/s</entry> | ||
| 1041 | </row> | ||
| 1042 | <row> | ||
| 1043 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_96K</constant> </entry> | ||
| 1044 | <entry>96 kbit/s</entry> | ||
| 1045 | </row> | ||
| 1046 | <row> | ||
| 1047 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_112K</constant> </entry> | ||
| 1048 | <entry>112 kbit/s</entry> | ||
| 1049 | </row> | ||
| 1050 | <row> | ||
| 1051 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_128K</constant> </entry> | ||
| 1052 | <entry>128 kbit/s</entry> | ||
| 1053 | </row> | ||
| 1054 | <row> | ||
| 1055 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_160K</constant> </entry> | ||
| 1056 | <entry>160 kbit/s</entry> | ||
| 1057 | </row> | ||
| 1058 | <row> | ||
| 1059 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_192K</constant> </entry> | ||
| 1060 | <entry>192 kbit/s</entry> | ||
| 1061 | </row> | ||
| 1062 | <row> | ||
| 1063 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_224K</constant> </entry> | ||
| 1064 | <entry>224 kbit/s</entry> | ||
| 1065 | </row> | ||
| 1066 | <row> | ||
| 1067 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_256K</constant> </entry> | ||
| 1068 | <entry>256 kbit/s</entry> | ||
| 1069 | </row> | ||
| 1070 | <row> | ||
| 1071 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_320K</constant> </entry> | ||
| 1072 | <entry>320 kbit/s</entry> | ||
| 1073 | </row> | ||
| 1074 | <row> | ||
| 1075 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_384K</constant> </entry> | ||
| 1076 | <entry>384 kbit/s</entry> | ||
| 1077 | </row> | ||
| 1078 | <row> | ||
| 1079 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_448K</constant> </entry> | ||
| 1080 | <entry>448 kbit/s</entry> | ||
| 1081 | </row> | ||
| 1082 | <row> | ||
| 1083 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_512K</constant> </entry> | ||
| 1084 | <entry>512 kbit/s</entry> | ||
| 1085 | </row> | ||
| 1086 | <row> | ||
| 1087 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_576K</constant> </entry> | ||
| 1088 | <entry>576 kbit/s</entry> | ||
| 1089 | </row> | ||
| 1090 | <row> | ||
| 1091 | <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_640K</constant> </entry> | ||
| 1092 | <entry>640 kbit/s</entry> | ||
| 1093 | </row> | ||
| 1094 | </tbody> | ||
| 1095 | </entrytbl> | ||
| 1096 | </row> | ||
| 1097 | <row><entry></entry></row> | ||
| 1098 | <row id="v4l2-mpeg-audio-mode"> | ||
| 1099 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE</constant> </entry> | ||
| 1100 | <entry>enum v4l2_mpeg_audio_mode</entry> | ||
| 1101 | </row><row><entry spanname="descr">MPEG Audio mode. | ||
| 1102 | Possible values are:</entry> | ||
| 1103 | </row> | ||
| 1104 | <row> | ||
| 1105 | <entrytbl spanname="descr" cols="2"> | ||
| 1106 | <tbody valign="top"> | ||
| 1107 | <row> | ||
| 1108 | <entry><constant>V4L2_MPEG_AUDIO_MODE_STEREO</constant> </entry> | ||
| 1109 | <entry>Stereo</entry> | ||
| 1110 | </row> | ||
| 1111 | <row> | ||
| 1112 | <entry><constant>V4L2_MPEG_AUDIO_MODE_JOINT_STEREO</constant> </entry> | ||
| 1113 | <entry>Joint Stereo</entry> | ||
| 1114 | </row> | ||
| 1115 | <row> | ||
| 1116 | <entry><constant>V4L2_MPEG_AUDIO_MODE_DUAL</constant> </entry> | ||
| 1117 | <entry>Bilingual</entry> | ||
| 1118 | </row> | ||
| 1119 | <row> | ||
| 1120 | <entry><constant>V4L2_MPEG_AUDIO_MODE_MONO</constant> </entry> | ||
| 1121 | <entry>Mono</entry> | ||
| 1122 | </row> | ||
| 1123 | </tbody> | ||
| 1124 | </entrytbl> | ||
| 1125 | </row> | ||
| 1126 | <row><entry></entry></row> | ||
| 1127 | <row id="v4l2-mpeg-audio-mode-extension"> | ||
| 1128 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE_EXTENSION</constant> </entry> | ||
| 1129 | <entry>enum v4l2_mpeg_audio_mode_extension</entry> | ||
| 1130 | </row><row><entry spanname="descr">Joint Stereo | ||
| 1131 | audio mode extension. In Layer I and II they indicate which subbands | ||
| 1132 | are in intensity stereo. All other subbands are coded in stereo. Layer | ||
| 1133 | III is not (yet) supported. Possible values | ||
| 1134 | are:</entry> | ||
| 1135 | </row> | ||
| 1136 | <row> | ||
| 1137 | <entrytbl spanname="descr" cols="2"> | ||
| 1138 | <tbody valign="top"> | ||
| 1139 | <row> | ||
| 1140 | <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4</constant> </entry> | ||
| 1141 | <entry>Subbands 4-31 in intensity stereo</entry> | ||
| 1142 | </row> | ||
| 1143 | <row> | ||
| 1144 | <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8</constant> </entry> | ||
| 1145 | <entry>Subbands 8-31 in intensity stereo</entry> | ||
| 1146 | </row> | ||
| 1147 | <row> | ||
| 1148 | <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12</constant> </entry> | ||
| 1149 | <entry>Subbands 12-31 in intensity stereo</entry> | ||
| 1150 | </row> | ||
| 1151 | <row> | ||
| 1152 | <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16</constant> </entry> | ||
| 1153 | <entry>Subbands 16-31 in intensity stereo</entry> | ||
| 1154 | </row> | ||
| 1155 | </tbody> | ||
| 1156 | </entrytbl> | ||
| 1157 | </row> | ||
| 1158 | <row><entry></entry></row> | ||
| 1159 | <row id="v4l2-mpeg-audio-emphasis"> | ||
| 1160 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_EMPHASIS</constant> </entry> | ||
| 1161 | <entry>enum v4l2_mpeg_audio_emphasis</entry> | ||
| 1162 | </row><row><entry spanname="descr">Audio Emphasis. | ||
| 1163 | Possible values are:</entry> | ||
| 1164 | </row> | ||
| 1165 | <row> | ||
| 1166 | <entrytbl spanname="descr" cols="2"> | ||
| 1167 | <tbody valign="top"> | ||
| 1168 | <row> | ||
| 1169 | <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_NONE</constant> </entry> | ||
| 1170 | <entry>None</entry> | ||
| 1171 | </row> | ||
| 1172 | <row> | ||
| 1173 | <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS</constant> </entry> | ||
| 1174 | <entry>50/15 microsecond emphasis</entry> | ||
| 1175 | </row> | ||
| 1176 | <row> | ||
| 1177 | <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17</constant> </entry> | ||
| 1178 | <entry>CCITT J.17</entry> | ||
| 1179 | </row> | ||
| 1180 | </tbody> | ||
| 1181 | </entrytbl> | ||
| 1182 | </row> | ||
| 1183 | <row><entry></entry></row> | ||
| 1184 | <row id="v4l2-mpeg-audio-crc"> | ||
| 1185 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_CRC</constant> </entry> | ||
| 1186 | <entry>enum v4l2_mpeg_audio_crc</entry> | ||
| 1187 | </row><row><entry spanname="descr">CRC method. Possible | ||
| 1188 | values are:</entry> | ||
| 1189 | </row> | ||
| 1190 | <row> | ||
| 1191 | <entrytbl spanname="descr" cols="2"> | ||
| 1192 | <tbody valign="top"> | ||
| 1193 | <row> | ||
| 1194 | <entry><constant>V4L2_MPEG_AUDIO_CRC_NONE</constant> </entry> | ||
| 1195 | <entry>None</entry> | ||
| 1196 | </row> | ||
| 1197 | <row> | ||
| 1198 | <entry><constant>V4L2_MPEG_AUDIO_CRC_CRC16</constant> </entry> | ||
| 1199 | <entry>16 bit parity check</entry> | ||
| 1200 | </row> | ||
| 1201 | </tbody> | ||
| 1202 | </entrytbl> | ||
| 1203 | </row> | ||
| 1204 | <row><entry></entry></row> | ||
| 1205 | <row> | ||
| 1206 | <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MUTE</constant> </entry> | ||
| 1207 | <entry>boolean</entry> | ||
| 1208 | </row><row><entry spanname="descr">Mutes the audio when | ||
| 1209 | capturing. This is not done by muting audio hardware, which can still | ||
| 1210 | produce a slight hiss, but in the encoder itself, guaranteeing a fixed | ||
| 1211 | and reproducable audio bitstream. 0 = unmuted, 1 = muted.</entry> | ||
| 1212 | </row> | ||
| 1213 | <row><entry></entry></row> | ||
| 1214 | <row id="v4l2-mpeg-video-encoding"> | ||
| 1215 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ENCODING</constant> </entry> | ||
| 1216 | <entry>enum v4l2_mpeg_video_encoding</entry> | ||
| 1217 | </row><row><entry spanname="descr">MPEG Video encoding | ||
| 1218 | method. Possible values are:</entry> | ||
| 1219 | </row> | ||
| 1220 | <row> | ||
| 1221 | <entrytbl spanname="descr" cols="2"> | ||
| 1222 | <tbody valign="top"> | ||
| 1223 | <row> | ||
| 1224 | <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_1</constant> </entry> | ||
| 1225 | <entry>MPEG-1 Video encoding</entry> | ||
| 1226 | </row> | ||
| 1227 | <row> | ||
| 1228 | <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_2</constant> </entry> | ||
| 1229 | <entry>MPEG-2 Video encoding</entry> | ||
| 1230 | </row> | ||
| 1231 | <row> | ||
| 1232 | <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> </entry> | ||
| 1233 | <entry>MPEG-4 AVC (H.264) Video encoding</entry> | ||
| 1234 | </row> | ||
| 1235 | </tbody> | ||
| 1236 | </entrytbl> | ||
| 1237 | </row> | ||
| 1238 | <row><entry></entry></row> | ||
| 1239 | <row id="v4l2-mpeg-video-aspect"> | ||
| 1240 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ASPECT</constant> </entry> | ||
| 1241 | <entry>enum v4l2_mpeg_video_aspect</entry> | ||
| 1242 | </row><row><entry spanname="descr">Video aspect. | ||
| 1243 | Possible values are:</entry> | ||
| 1244 | </row> | ||
| 1245 | <row> | ||
| 1246 | <entrytbl spanname="descr" cols="2"> | ||
| 1247 | <tbody valign="top"> | ||
| 1248 | <row> | ||
| 1249 | <entry><constant>V4L2_MPEG_VIDEO_ASPECT_1x1</constant> </entry> | ||
| 1250 | </row> | ||
| 1251 | <row> | ||
| 1252 | <entry><constant>V4L2_MPEG_VIDEO_ASPECT_4x3</constant> </entry> | ||
| 1253 | </row> | ||
| 1254 | <row> | ||
| 1255 | <entry><constant>V4L2_MPEG_VIDEO_ASPECT_16x9</constant> </entry> | ||
| 1256 | </row> | ||
| 1257 | <row> | ||
| 1258 | <entry><constant>V4L2_MPEG_VIDEO_ASPECT_221x100</constant> </entry> | ||
| 1259 | </row> | ||
| 1260 | </tbody> | ||
| 1261 | </entrytbl> | ||
| 1262 | </row> | ||
| 1263 | <row><entry></entry></row> | ||
| 1264 | <row> | ||
| 1265 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_B_FRAMES</constant> </entry> | ||
| 1266 | <entry>integer</entry> | ||
| 1267 | </row><row><entry spanname="descr">Number of B-Frames | ||
| 1268 | (default 2)</entry> | ||
| 1269 | </row> | ||
| 1270 | <row><entry></entry></row> | ||
| 1271 | <row> | ||
| 1272 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_SIZE</constant> </entry> | ||
| 1273 | <entry>integer</entry> | ||
| 1274 | </row><row><entry spanname="descr">GOP size (default | ||
| 1275 | 12)</entry> | ||
| 1276 | </row> | ||
| 1277 | <row><entry></entry></row> | ||
| 1278 | <row> | ||
| 1279 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_CLOSURE</constant> </entry> | ||
| 1280 | <entry>boolean</entry> | ||
| 1281 | </row><row><entry spanname="descr">GOP closure (default | ||
| 1282 | 1)</entry> | ||
| 1283 | </row> | ||
| 1284 | <row><entry></entry></row> | ||
| 1285 | <row> | ||
| 1286 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_PULLDOWN</constant> </entry> | ||
| 1287 | <entry>boolean</entry> | ||
| 1288 | </row><row><entry spanname="descr">Enable 3:2 pulldown | ||
| 1289 | (default 0)</entry> | ||
| 1290 | </row> | ||
| 1291 | <row><entry></entry></row> | ||
| 1292 | <row id="v4l2-mpeg-video-bitrate-mode"> | ||
| 1293 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_MODE</constant> </entry> | ||
| 1294 | <entry>enum v4l2_mpeg_video_bitrate_mode</entry> | ||
| 1295 | </row><row><entry spanname="descr">Video bitrate mode. | ||
| 1296 | Possible values are:</entry> | ||
| 1297 | </row> | ||
| 1298 | <row> | ||
| 1299 | <entrytbl spanname="descr" cols="2"> | ||
| 1300 | <tbody valign="top"> | ||
| 1301 | <row> | ||
| 1302 | <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_VBR</constant> </entry> | ||
| 1303 | <entry>Variable bitrate</entry> | ||
| 1304 | </row> | ||
| 1305 | <row> | ||
| 1306 | <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_CBR</constant> </entry> | ||
| 1307 | <entry>Constant bitrate</entry> | ||
| 1308 | </row> | ||
| 1309 | </tbody> | ||
| 1310 | </entrytbl> | ||
| 1311 | </row> | ||
| 1312 | <row><entry></entry></row> | ||
| 1313 | <row> | ||
| 1314 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE</constant> </entry> | ||
| 1315 | <entry>integer</entry> | ||
| 1316 | </row><row><entry spanname="descr">Video bitrate in bits | ||
| 1317 | per second.</entry> | ||
| 1318 | </row> | ||
| 1319 | <row><entry></entry></row> | ||
| 1320 | <row> | ||
| 1321 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_PEAK</constant> </entry> | ||
| 1322 | <entry>integer</entry> | ||
| 1323 | </row><row><entry spanname="descr">Peak video bitrate in | ||
| 1324 | bits per second. Must be larger or equal to the average video bitrate. | ||
| 1325 | It is ignored if the video bitrate mode is set to constant | ||
| 1326 | bitrate.</entry> | ||
| 1327 | </row> | ||
| 1328 | <row><entry></entry></row> | ||
| 1329 | <row> | ||
| 1330 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION</constant> </entry> | ||
| 1331 | <entry>integer</entry> | ||
| 1332 | </row><row><entry spanname="descr">For every captured | ||
| 1333 | frame, skip this many subsequent frames (default 0).</entry> | ||
| 1334 | </row> | ||
| 1335 | <row><entry></entry></row> | ||
| 1336 | <row> | ||
| 1337 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE</constant> </entry> | ||
| 1338 | <entry>boolean</entry> | ||
| 1339 | </row> | ||
| 1340 | <row><entry spanname="descr">"Mutes" the video to a | ||
| 1341 | fixed color when capturing. This is useful for testing, to produce a | ||
| 1342 | fixed video bitstream. 0 = unmuted, 1 = muted.</entry> | ||
| 1343 | </row> | ||
| 1344 | <row><entry></entry></row> | ||
| 1345 | <row> | ||
| 1346 | <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE_YUV</constant> </entry> | ||
| 1347 | <entry>integer</entry> | ||
| 1348 | </row><row><entry spanname="descr">Sets the "mute" color | ||
| 1349 | of the video. The supplied 32-bit integer is interpreted as follows (bit | ||
| 1350 | 0 = least significant bit):</entry> | ||
| 1351 | </row> | ||
| 1352 | <row> | ||
| 1353 | <entrytbl spanname="descr" cols="2"> | ||
| 1354 | <tbody valign="top"> | ||
| 1355 | <row> | ||
| 1356 | <entry>Bit 0:7</entry> | ||
| 1357 | <entry>V chrominance information</entry> | ||
| 1358 | </row> | ||
| 1359 | <row> | ||
| 1360 | <entry>Bit 8:15</entry> | ||
| 1361 | <entry>U chrominance information</entry> | ||
| 1362 | </row> | ||
| 1363 | <row> | ||
| 1364 | <entry>Bit 16:23</entry> | ||
| 1365 | <entry>Y luminance information</entry> | ||
| 1366 | </row> | ||
| 1367 | <row> | ||
| 1368 | <entry>Bit 24:31</entry> | ||
| 1369 | <entry>Must be zero.</entry> | ||
| 1370 | </row> | ||
| 1371 | </tbody> | ||
| 1372 | </entrytbl> | ||
| 1373 | </row> | ||
| 1374 | </tbody> | ||
| 1375 | </tgroup> | ||
| 1376 | </table> | ||
| 1377 | </section> | ||
| 1378 | |||
| 1379 | <section> | ||
| 1380 | <title>CX2341x MPEG Controls</title> | ||
| 1381 | |||
| 1382 | <para>The following MPEG class controls deal with MPEG | ||
| 1383 | encoding settings that are specific to the Conexant CX23415 and | ||
| 1384 | CX23416 MPEG encoding chips.</para> | ||
| 1385 | |||
| 1386 | <table pgwide="1" frame="none" id="cx2341x-control-id"> | ||
| 1387 | <title>CX2341x Control IDs</title> | ||
| 1388 | <tgroup cols="4"> | ||
| 1389 | <colspec colname="c1" colwidth="1*" /> | ||
| 1390 | <colspec colname="c2" colwidth="6*" /> | ||
| 1391 | <colspec colname="c3" colwidth="2*" /> | ||
| 1392 | <colspec colname="c4" colwidth="6*" /> | ||
| 1393 | <spanspec namest="c1" nameend="c2" spanname="id" /> | ||
| 1394 | <spanspec namest="c2" nameend="c4" spanname="descr" /> | ||
| 1395 | <thead> | ||
| 1396 | <row> | ||
| 1397 | <entry spanname="id" align="left">ID</entry> | ||
| 1398 | <entry align="left">Type</entry> | ||
| 1399 | </row><row><entry spanname="descr" align="left">Description</entry> | ||
| 1400 | </row> | ||
| 1401 | </thead> | ||
| 1402 | <tbody valign="top"> | ||
| 1403 | <row><entry></entry></row> | ||
| 1404 | <row id="v4l2-mpeg-cx2341x-video-spatial-filter-mode"> | ||
| 1405 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE</constant> </entry> | ||
| 1406 | <entry>enum v4l2_mpeg_cx2341x_video_spatial_filter_mode</entry> | ||
| 1407 | </row><row><entry spanname="descr">Sets the Spatial | ||
| 1408 | Filter mode (default <constant>MANUAL</constant>). Possible values | ||
| 1409 | are:</entry> | ||
| 1410 | </row> | ||
| 1411 | <row> | ||
| 1412 | <entrytbl spanname="descr" cols="2"> | ||
| 1413 | <tbody valign="top"> | ||
| 1414 | <row> | ||
| 1415 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL</constant> </entry> | ||
| 1416 | <entry>Choose the filter manually</entry> | ||
| 1417 | </row> | ||
| 1418 | <row> | ||
| 1419 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO</constant> </entry> | ||
| 1420 | <entry>Choose the filter automatically</entry> | ||
| 1421 | </row> | ||
| 1422 | </tbody> | ||
| 1423 | </entrytbl> | ||
| 1424 | </row> | ||
| 1425 | <row><entry></entry></row> | ||
| 1426 | <row> | ||
| 1427 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER</constant> </entry> | ||
| 1428 | <entry>integer (0-15)</entry> | ||
| 1429 | </row><row><entry spanname="descr">The setting for the | ||
| 1430 | Spatial Filter. 0 = off, 15 = maximum. (Default is 0.)</entry> | ||
| 1431 | </row> | ||
| 1432 | <row><entry></entry></row> | ||
| 1433 | <row id="luma-spatial-filter-type"> | ||
| 1434 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE</constant> </entry> | ||
| 1435 | <entry>enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</entry> | ||
| 1436 | </row><row><entry spanname="descr">Select the algorithm | ||
| 1437 | to use for the Luma Spatial Filter (default | ||
| 1438 | <constant>1D_HOR</constant>). Possible values:</entry> | ||
| 1439 | </row> | ||
| 1440 | <row> | ||
| 1441 | <entrytbl spanname="descr" cols="2"> | ||
| 1442 | <tbody valign="top"> | ||
| 1443 | <row> | ||
| 1444 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF</constant> </entry> | ||
| 1445 | <entry>No filter</entry> | ||
| 1446 | </row> | ||
| 1447 | <row> | ||
| 1448 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR</constant> </entry> | ||
| 1449 | <entry>One-dimensional horizontal</entry> | ||
| 1450 | </row> | ||
| 1451 | <row> | ||
| 1452 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT</constant> </entry> | ||
| 1453 | <entry>One-dimensional vertical</entry> | ||
| 1454 | </row> | ||
| 1455 | <row> | ||
| 1456 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE</constant> </entry> | ||
| 1457 | <entry>Two-dimensional separable</entry> | ||
| 1458 | </row> | ||
| 1459 | <row> | ||
| 1460 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE</constant> </entry> | ||
| 1461 | <entry>Two-dimensional symmetrical | ||
| 1462 | non-separable</entry> | ||
| 1463 | </row> | ||
| 1464 | </tbody> | ||
| 1465 | </entrytbl> | ||
| 1466 | </row> | ||
| 1467 | <row><entry></entry></row> | ||
| 1468 | <row id="chroma-spatial-filter-type"> | ||
| 1469 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE</constant> </entry> | ||
| 1470 | <entry>enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</entry> | ||
| 1471 | </row><row><entry spanname="descr">Select the algorithm | ||
| 1472 | for the Chroma Spatial Filter (default <constant>1D_HOR</constant>). | ||
| 1473 | Possible values are:</entry> | ||
| 1474 | </row> | ||
| 1475 | <row> | ||
| 1476 | <entrytbl spanname="descr" cols="2"> | ||
| 1477 | <tbody valign="top"> | ||
| 1478 | <row> | ||
| 1479 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF</constant> </entry> | ||
| 1480 | <entry>No filter</entry> | ||
| 1481 | </row> | ||
| 1482 | <row> | ||
| 1483 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR</constant> </entry> | ||
| 1484 | <entry>One-dimensional horizontal</entry> | ||
| 1485 | </row> | ||
| 1486 | </tbody> | ||
| 1487 | </entrytbl> | ||
| 1488 | </row> | ||
| 1489 | <row><entry></entry></row> | ||
| 1490 | <row id="v4l2-mpeg-cx2341x-video-temporal-filter-mode"> | ||
| 1491 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE</constant> </entry> | ||
| 1492 | <entry>enum v4l2_mpeg_cx2341x_video_temporal_filter_mode</entry> | ||
| 1493 | </row><row><entry spanname="descr">Sets the Temporal | ||
| 1494 | Filter mode (default <constant>MANUAL</constant>). Possible values | ||
| 1495 | are:</entry> | ||
| 1496 | </row> | ||
| 1497 | <row> | ||
| 1498 | <entrytbl spanname="descr" cols="2"> | ||
| 1499 | <tbody valign="top"> | ||
| 1500 | <row> | ||
| 1501 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL</constant> </entry> | ||
| 1502 | <entry>Choose the filter manually</entry> | ||
| 1503 | </row> | ||
| 1504 | <row> | ||
| 1505 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO</constant> </entry> | ||
| 1506 | <entry>Choose the filter automatically</entry> | ||
| 1507 | </row> | ||
| 1508 | </tbody> | ||
| 1509 | </entrytbl> | ||
| 1510 | </row> | ||
| 1511 | <row><entry></entry></row> | ||
| 1512 | <row> | ||
| 1513 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER</constant> </entry> | ||
| 1514 | <entry>integer (0-31)</entry> | ||
| 1515 | </row><row><entry spanname="descr">The setting for the | ||
| 1516 | Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for full-scale | ||
| 1517 | capturing and 0 for scaled capturing.)</entry> | ||
| 1518 | </row> | ||
| 1519 | <row><entry></entry></row> | ||
| 1520 | <row id="v4l2-mpeg-cx2341x-video-median-filter-type"> | ||
| 1521 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE</constant> </entry> | ||
| 1522 | <entry>enum v4l2_mpeg_cx2341x_video_median_filter_type</entry> | ||
| 1523 | </row><row><entry spanname="descr">Median Filter Type | ||
| 1524 | (default <constant>OFF</constant>). Possible values are:</entry> | ||
| 1525 | </row> | ||
| 1526 | <row> | ||
| 1527 | <entrytbl spanname="descr" cols="2"> | ||
| 1528 | <tbody valign="top"> | ||
| 1529 | <row> | ||
| 1530 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF</constant> </entry> | ||
| 1531 | <entry>No filter</entry> | ||
| 1532 | </row> | ||
| 1533 | <row> | ||
| 1534 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR</constant> </entry> | ||
| 1535 | <entry>Horizontal filter</entry> | ||
| 1536 | </row> | ||
| 1537 | <row> | ||
| 1538 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT</constant> </entry> | ||
| 1539 | <entry>Vertical filter</entry> | ||
| 1540 | </row> | ||
| 1541 | <row> | ||
| 1542 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT</constant> </entry> | ||
| 1543 | <entry>Horizontal and vertical filter</entry> | ||
| 1544 | </row> | ||
| 1545 | <row> | ||
| 1546 | <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG</constant> </entry> | ||
| 1547 | <entry>Diagonal filter</entry> | ||
| 1548 | </row> | ||
| 1549 | </tbody> | ||
| 1550 | </entrytbl> | ||
| 1551 | </row> | ||
| 1552 | <row><entry></entry></row> | ||
| 1553 | <row> | ||
| 1554 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM</constant> </entry> | ||
| 1555 | <entry>integer (0-255)</entry> | ||
| 1556 | </row><row><entry spanname="descr">Threshold above which | ||
| 1557 | the luminance median filter is enabled (default 0)</entry> | ||
| 1558 | </row> | ||
| 1559 | <row><entry></entry></row> | ||
| 1560 | <row> | ||
| 1561 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP</constant> </entry> | ||
| 1562 | <entry>integer (0-255)</entry> | ||
| 1563 | </row><row><entry spanname="descr">Threshold below which | ||
| 1564 | the luminance median filter is enabled (default 255)</entry> | ||
| 1565 | </row> | ||
| 1566 | <row><entry></entry></row> | ||
| 1567 | <row> | ||
| 1568 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM</constant> </entry> | ||
| 1569 | <entry>integer (0-255)</entry> | ||
| 1570 | </row><row><entry spanname="descr">Threshold above which | ||
| 1571 | the chroma median filter is enabled (default 0)</entry> | ||
| 1572 | </row> | ||
| 1573 | <row><entry></entry></row> | ||
| 1574 | <row> | ||
| 1575 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP</constant> </entry> | ||
| 1576 | <entry>integer (0-255)</entry> | ||
| 1577 | </row><row><entry spanname="descr">Threshold below which | ||
| 1578 | the chroma median filter is enabled (default 255)</entry> | ||
| 1579 | </row> | ||
| 1580 | <row><entry></entry></row> | ||
| 1581 | <row> | ||
| 1582 | <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS</constant> </entry> | ||
| 1583 | <entry>boolean</entry> | ||
| 1584 | </row> | ||
| 1585 | <row><entry spanname="descr">The CX2341X MPEG encoder | ||
| 1586 | can insert one empty MPEG-2 PES packet into the stream between every | ||
| 1587 | four video frames. The packet size is 2048 bytes, including the | ||
| 1588 | packet_start_code_prefix and stream_id fields. The stream_id is 0xBF | ||
| 1589 | (private stream 2). The payload consists of 0x00 bytes, to be filled | ||
| 1590 | in by the application. 0 = do not insert, 1 = insert packets.</entry> | ||
| 1591 | </row> | ||
| 1592 | </tbody> | ||
| 1593 | </tgroup> | ||
| 1594 | </table> | ||
| 1595 | </section> | ||
| 1596 | </section> | ||
| 1597 | |||
| 1598 | <section id="camera-controls"> | ||
| 1599 | <title>Camera Control Reference</title> | ||
| 1600 | |||
| 1601 | <para>The Camera class includes controls for mechanical (or | ||
| 1602 | equivalent digital) features of a device such as controllable lenses | ||
| 1603 | or sensors.</para> | ||
| 1604 | |||
| 1605 | <table pgwide="1" frame="none" id="camera-control-id"> | ||
| 1606 | <title>Camera Control IDs</title> | ||
| 1607 | <tgroup cols="4"> | ||
| 1608 | <colspec colname="c1" colwidth="1*" /> | ||
| 1609 | <colspec colname="c2" colwidth="6*" /> | ||
| 1610 | <colspec colname="c3" colwidth="2*" /> | ||
| 1611 | <colspec colname="c4" colwidth="6*" /> | ||
| 1612 | <spanspec namest="c1" nameend="c2" spanname="id" /> | ||
| 1613 | <spanspec namest="c2" nameend="c4" spanname="descr" /> | ||
| 1614 | <thead> | ||
| 1615 | <row> | ||
| 1616 | <entry spanname="id" align="left">ID</entry> | ||
| 1617 | <entry align="left">Type</entry> | ||
| 1618 | </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> | ||
| 1619 | </row> | ||
| 1620 | </thead> | ||
| 1621 | <tbody valign="top"> | ||
| 1622 | <row><entry></entry></row> | ||
| 1623 | <row> | ||
| 1624 | <entry spanname="id"><constant>V4L2_CID_CAMERA_CLASS</constant> </entry> | ||
| 1625 | <entry>class</entry> | ||
| 1626 | </row><row><entry spanname="descr">The Camera class | ||
| 1627 | descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a | ||
| 1628 | description of this control class.</entry> | ||
| 1629 | </row> | ||
| 1630 | <row><entry></entry></row> | ||
| 1631 | |||
| 1632 | <row id="v4l2-exposure-auto-type"> | ||
| 1633 | <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO</constant> </entry> | ||
| 1634 | <entry>enum v4l2_exposure_auto_type</entry> | ||
| 1635 | </row><row><entry spanname="descr">Enables automatic | ||
| 1636 | adjustments of the exposure time and/or iris aperture. The effect of | ||
| 1637 | manual changes of the exposure time or iris aperture while these | ||
| 1638 | features are enabled is undefined, drivers should ignore such | ||
| 1639 | requests. Possible values are:</entry> | ||
| 1640 | </row> | ||
| 1641 | <row> | ||
| 1642 | <entrytbl spanname="descr" cols="2"> | ||
| 1643 | <tbody valign="top"> | ||
| 1644 | <row> | ||
| 1645 | <entry><constant>V4L2_EXPOSURE_AUTO</constant> </entry> | ||
| 1646 | <entry>Automatic exposure time, automatic iris | ||
| 1647 | aperture.</entry> | ||
| 1648 | </row> | ||
| 1649 | <row> | ||
| 1650 | <entry><constant>V4L2_EXPOSURE_MANUAL</constant> </entry> | ||
| 1651 | <entry>Manual exposure time, manual iris.</entry> | ||
| 1652 | </row> | ||
| 1653 | <row> | ||
| 1654 | <entry><constant>V4L2_EXPOSURE_SHUTTER_PRIORITY</constant> </entry> | ||
| 1655 | <entry>Manual exposure time, auto iris.</entry> | ||
| 1656 | </row> | ||
| 1657 | <row> | ||
| 1658 | <entry><constant>V4L2_EXPOSURE_APERTURE_PRIORITY</constant> </entry> | ||
| 1659 | <entry>Auto exposure time, manual iris.</entry> | ||
| 1660 | </row> | ||
| 1661 | </tbody> | ||
| 1662 | </entrytbl> | ||
| 1663 | </row> | ||
| 1664 | <row><entry></entry></row> | ||
| 1665 | |||
| 1666 | <row> | ||
| 1667 | <entry spanname="id"><constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant> </entry> | ||
| 1668 | <entry>integer</entry> | ||
| 1669 | </row><row><entry spanname="descr">Determines the exposure | ||
| 1670 | time of the camera sensor. The exposure time is limited by the frame | ||
| 1671 | interval. Drivers should interpret the values as 100 µs units, | ||
| 1672 | where the value 1 stands for 1/10000th of a second, 10000 for 1 second | ||
| 1673 | and 100000 for 10 seconds.</entry> | ||
| 1674 | </row> | ||
| 1675 | <row><entry></entry></row> | ||
| 1676 | |||
| 1677 | <row> | ||
| 1678 | <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant> </entry> | ||
| 1679 | <entry>boolean</entry> | ||
| 1680 | </row><row><entry spanname="descr">When | ||
| 1681 | <constant>V4L2_CID_EXPOSURE_AUTO</constant> is set to | ||
| 1682 | <constant>AUTO</constant> or <constant>APERTURE_PRIORITY</constant>, | ||
| 1683 | this control determines if the device may dynamically vary the frame | ||
| 1684 | rate. By default this feature is disabled (0) and the frame rate must | ||
| 1685 | remain constant.</entry> | ||
| 1686 | </row> | ||
| 1687 | <row><entry></entry></row> | ||
| 1688 | |||
| 1689 | <row> | ||
| 1690 | <entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant> </entry> | ||
| 1691 | <entry>integer</entry> | ||
| 1692 | </row><row><entry spanname="descr">This control turns the | ||
| 1693 | camera horizontally by the specified amount. The unit is undefined. A | ||
| 1694 | positive value moves the camera to the right (clockwise when viewed | ||
| 1695 | from above), a negative value to the left. A value of zero does not | ||
| 1696 | cause motion. This is a write-only control.</entry> | ||
| 1697 | </row> | ||
| 1698 | <row><entry></entry></row> | ||
| 1699 | |||
| 1700 | <row> | ||
| 1701 | <entry spanname="id"><constant>V4L2_CID_TILT_RELATIVE</constant> </entry> | ||
| 1702 | <entry>integer</entry> | ||
| 1703 | </row><row><entry spanname="descr">This control turns the | ||
| 1704 | camera vertically by the specified amount. The unit is undefined. A | ||
| 1705 | positive value moves the camera up, a negative value down. A value of | ||
| 1706 | zero does not cause motion. This is a write-only control.</entry> | ||
| 1707 | </row> | ||
| 1708 | <row><entry></entry></row> | ||
| 1709 | |||
| 1710 | <row> | ||
| 1711 | <entry spanname="id"><constant>V4L2_CID_PAN_RESET</constant> </entry> | ||
| 1712 | <entry>button</entry> | ||
| 1713 | </row><row><entry spanname="descr">When this control is set, | ||
| 1714 | the camera moves horizontally to the default position.</entry> | ||
| 1715 | </row> | ||
| 1716 | <row><entry></entry></row> | ||
| 1717 | |||
| 1718 | <row> | ||
| 1719 | <entry spanname="id"><constant>V4L2_CID_TILT_RESET</constant> </entry> | ||
| 1720 | <entry>button</entry> | ||
| 1721 | </row><row><entry spanname="descr">When this control is set, | ||
| 1722 | the camera moves vertically to the default position.</entry> | ||
| 1723 | </row> | ||
| 1724 | <row><entry></entry></row> | ||
| 1725 | |||
| 1726 | <row> | ||
| 1727 | <entry spanname="id"><constant>V4L2_CID_PAN_ABSOLUTE</constant> </entry> | ||
| 1728 | <entry>integer</entry> | ||
| 1729 | </row><row><entry spanname="descr">This control | ||
| 1730 | turns the camera horizontally to the specified position. Positive | ||
| 1731 | values move the camera to the right (clockwise when viewed from above), | ||
| 1732 | negative values to the left. Drivers should interpret the values as arc | ||
| 1733 | seconds, with valid values between -180 * 3600 and +180 * 3600 | ||
| 1734 | inclusive.</entry> | ||
| 1735 | </row> | ||
| 1736 | <row><entry></entry></row> | ||
| 1737 | |||
| 1738 | <row> | ||
| 1739 | <entry spanname="id"><constant>V4L2_CID_TILT_ABSOLUTE</constant> </entry> | ||
| 1740 | <entry>integer</entry> | ||
| 1741 | </row><row><entry spanname="descr">This control | ||
| 1742 | turns the camera vertically to the specified position. Positive values | ||
| 1743 | move the camera up, negative values down. Drivers should interpret the | ||
| 1744 | values as arc seconds, with valid values between -180 * 3600 and +180 | ||
| 1745 | * 3600 inclusive.</entry> | ||
| 1746 | </row> | ||
| 1747 | <row><entry></entry></row> | ||
| 1748 | |||
| 1749 | <row> | ||
| 1750 | <entry spanname="id"><constant>V4L2_CID_FOCUS_ABSOLUTE</constant> </entry> | ||
| 1751 | <entry>integer</entry> | ||
| 1752 | </row><row><entry spanname="descr">This control sets the | ||
| 1753 | focal point of the camera to the specified position. The unit is | ||
| 1754 | undefined. Positive values set the focus closer to the camera, | ||
| 1755 | negative values towards infinity.</entry> | ||
| 1756 | </row> | ||
| 1757 | <row><entry></entry></row> | ||
| 1758 | |||
| 1759 | <row> | ||
| 1760 | <entry spanname="id"><constant>V4L2_CID_FOCUS_RELATIVE</constant> </entry> | ||
| 1761 | <entry>integer</entry> | ||
| 1762 | </row><row><entry spanname="descr">This control moves the | ||
| 1763 | focal point of the camera by the specified amount. The unit is | ||
| 1764 | undefined. Positive values move the focus closer to the camera, | ||
| 1765 | negative values towards infinity. This is a write-only control.</entry> | ||
| 1766 | </row> | ||
| 1767 | <row><entry></entry></row> | ||
| 1768 | |||
| 1769 | <row> | ||
| 1770 | <entry spanname="id"><constant>V4L2_CID_FOCUS_AUTO</constant> </entry> | ||
| 1771 | <entry>boolean</entry> | ||
| 1772 | </row><row><entry spanname="descr">Enables automatic focus | ||
| 1773 | adjustments. The effect of manual focus adjustments while this feature | ||
| 1774 | is enabled is undefined, drivers should ignore such requests.</entry> | ||
| 1775 | </row> | ||
| 1776 | <row><entry></entry></row> | ||
| 1777 | |||
| 1778 | <row> | ||
| 1779 | <entry spanname="id"><constant>V4L2_CID_ZOOM_ABSOLUTE</constant> </entry> | ||
| 1780 | <entry>integer</entry> | ||
| 1781 | </row><row><entry spanname="descr">Specify the objective lens | ||
| 1782 | focal length as an absolute value. The zoom unit is driver-specific and its | ||
| 1783 | value should be a positive integer.</entry> | ||
| 1784 | </row> | ||
| 1785 | <row><entry></entry></row> | ||
| 1786 | |||
| 1787 | <row> | ||
| 1788 | <entry spanname="id"><constant>V4L2_CID_ZOOM_RELATIVE</constant> </entry> | ||
| 1789 | <entry>integer</entry> | ||
| 1790 | </row><row><entry spanname="descr">Specify the objective lens | ||
| 1791 | focal length relatively to the current value. Positive values move the zoom | ||
| 1792 | lens group towards the telephoto direction, negative values towards the | ||
| 1793 | wide-angle direction. The zoom unit is driver-specific. This is a write-only control.</entry> | ||
| 1794 | </row> | ||
| 1795 | <row><entry></entry></row> | ||
| 1796 | |||
| 1797 | <row> | ||
| 1798 | <entry spanname="id"><constant>V4L2_CID_ZOOM_CONTINUOUS</constant> </entry> | ||
| 1799 | <entry>integer</entry> | ||
| 1800 | </row><row><entry spanname="descr">Move the objective lens group | ||
| 1801 | at the specified speed until it reaches physical device limits or until an | ||
| 1802 | explicit request to stop the movement. A positive value moves the zoom lens | ||
| 1803 | group towards the telephoto direction. A value of zero stops the zoom lens | ||
| 1804 | group movement. A negative value moves the zoom lens group towards the | ||
| 1805 | wide-angle direction. The zoom speed unit is driver-specific.</entry> | ||
| 1806 | </row> | ||
| 1807 | <row><entry></entry></row> | ||
| 1808 | |||
| 1809 | <row> | ||
| 1810 | <entry spanname="id"><constant>V4L2_CID_PRIVACY</constant> </entry> | ||
| 1811 | <entry>boolean</entry> | ||
| 1812 | </row><row><entry spanname="descr">Prevent video from being acquired | ||
| 1813 | by the camera. When this control is set to <constant>TRUE</constant> (1), no | ||
| 1814 | image can be captured by the camera. Common means to enforce privacy are | ||
| 1815 | mechanical obturation of the sensor and firmware image processing, but the | ||
| 1816 | device is not restricted to these methods. Devices that implement the privacy | ||
| 1817 | control must support read access and may support write access.</entry> | ||
| 1818 | </row> | ||
| 1819 | |||
| 1820 | <row> | ||
| 1821 | <entry spanname="id"><constant>V4L2_CID_BAND_STOP_FILTER</constant> </entry> | ||
| 1822 | <entry>integer</entry> | ||
| 1823 | </row><row><entry spanname="descr">Switch the band-stop filter of a | ||
| 1824 | camera sensor on or off, or specify its strength. Such band-stop filters can | ||
| 1825 | be used, for example, to filter out the fluorescent light component.</entry> | ||
| 1826 | </row> | ||
| 1827 | <row><entry></entry></row> | ||
| 1828 | </tbody> | ||
| 1829 | </tgroup> | ||
| 1830 | </table> | ||
| 1831 | </section> | ||
| 1832 | |||
| 1833 | <section id="fm-tx-controls"> | ||
| 1834 | <title>FM Transmitter Control Reference</title> | ||
| 1835 | |||
| 1836 | <para>The FM Transmitter (FM_TX) class includes controls for common features of | ||
| 1837 | FM transmissions capable devices. Currently this class includes parameters for audio | ||
| 1838 | compression, pilot tone generation, audio deviation limiter, RDS transmission and | ||
| 1839 | tuning power features.</para> | ||
| 1840 | |||
| 1841 | <table pgwide="1" frame="none" id="fm-tx-control-id"> | ||
| 1842 | <title>FM_TX Control IDs</title> | ||
| 1843 | |||
| 1844 | <tgroup cols="4"> | ||
| 1845 | <colspec colname="c1" colwidth="1*" /> | ||
| 1846 | <colspec colname="c2" colwidth="6*" /> | ||
| 1847 | <colspec colname="c3" colwidth="2*" /> | ||
| 1848 | <colspec colname="c4" colwidth="6*" /> | ||
| 1849 | <spanspec namest="c1" nameend="c2" spanname="id" /> | ||
| 1850 | <spanspec namest="c2" nameend="c4" spanname="descr" /> | ||
| 1851 | <thead> | ||
| 1852 | <row> | ||
| 1853 | <entry spanname="id" align="left">ID</entry> | ||
| 1854 | <entry align="left">Type</entry> | ||
| 1855 | </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> | ||
| 1856 | </row> | ||
| 1857 | </thead> | ||
| 1858 | <tbody valign="top"> | ||
| 1859 | <row><entry></entry></row> | ||
| 1860 | <row> | ||
| 1861 | <entry spanname="id"><constant>V4L2_CID_FM_TX_CLASS</constant> </entry> | ||
| 1862 | <entry>class</entry> | ||
| 1863 | </row><row><entry spanname="descr">The FM_TX class | ||
| 1864 | descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a | ||
| 1865 | description of this control class.</entry> | ||
| 1866 | </row> | ||
| 1867 | <row> | ||
| 1868 | <entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant> </entry> | ||
| 1869 | <entry>integer</entry> | ||
| 1870 | </row> | ||
| 1871 | <row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz. | ||
| 1872 | The range and step are driver-specific.</entry> | ||
| 1873 | </row> | ||
| 1874 | <row> | ||
| 1875 | <entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant> </entry> | ||
| 1876 | <entry>integer</entry> | ||
| 1877 | </row> | ||
| 1878 | <row><entry spanname="descr">Sets the RDS Programme Identification field | ||
| 1879 | for transmission.</entry> | ||
| 1880 | </row> | ||
| 1881 | <row> | ||
| 1882 | <entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant> </entry> | ||
| 1883 | <entry>integer</entry> | ||
| 1884 | </row> | ||
| 1885 | <row><entry spanname="descr">Sets the RDS Programme Type field for transmission. | ||
| 1886 | This encodes up to 31 pre-defined programme types.</entry> | ||
| 1887 | </row> | ||
| 1888 | <row> | ||
| 1889 | <entry spanname="id"><constant>V4L2_CID_RDS_TX_PS_NAME</constant> </entry> | ||
| 1890 | <entry>string</entry> | ||
| 1891 | </row> | ||
| 1892 | <row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission. | ||
| 1893 | It is intended for static display on a receiver. It is the primary aid to listeners in programme service | ||
| 1894 | identification and selection. In Annex E of <xref linkend="en50067" />, the RDS specification, | ||
| 1895 | there is a full description of the correct character encoding for Programme Service name strings. | ||
| 1896 | Also from RDS specification, PS is usually a single eight character text. However, it is also possible | ||
| 1897 | to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured | ||
| 1898 | with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry> | ||
| 1899 | </row> | ||
| 1900 | <row> | ||
| 1901 | <entry spanname="id"><constant>V4L2_CID_RDS_TX_RADIO_TEXT</constant> </entry> | ||
| 1902 | <entry>string</entry> | ||
| 1903 | </row> | ||
| 1904 | <row><entry spanname="descr">Sets the Radio Text info for transmission. It is a textual description of | ||
| 1905 | what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names, | ||
| 1906 | programme-related information or any other text. In these cases, RadioText should be used in addition to | ||
| 1907 | <constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described | ||
| 1908 | in Annex E of <xref linkend="en50067" />. The length of Radio Text strings depends on which RDS Block is being | ||
| 1909 | used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible | ||
| 1910 | to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured | ||
| 1911 | with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry> | ||
| 1912 | </row> | ||
| 1913 | <row> | ||
| 1914 | <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant> </entry> | ||
| 1915 | <entry>boolean</entry> | ||
| 1916 | </row> | ||
| 1917 | <row><entry spanname="descr">Enables or disables the audio deviation limiter feature. | ||
| 1918 | The limiter is useful when trying to maximize the audio volume, minimize receiver-generated | ||
| 1919 | distortion and prevent overmodulation. | ||
| 1920 | </entry> | ||
| 1921 | </row> | ||
| 1922 | <row> | ||
| 1923 | <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant> </entry> | ||
| 1924 | <entry>integer</entry> | ||
| 1925 | </row> | ||
| 1926 | <row><entry spanname="descr">Sets the audio deviation limiter feature release time. | ||
| 1927 | Unit is in useconds. Step and range are driver-specific.</entry> | ||
| 1928 | </row> | ||
| 1929 | <row> | ||
| 1930 | <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_DEVIATION</constant> </entry> | ||
| 1931 | <entry>integer</entry> | ||
| 1932 | </row> | ||
| 1933 | <row><entry spanname="descr">Configures audio frequency deviation level in Hz. | ||
| 1934 | The range and step are driver-specific.</entry> | ||
| 1935 | </row> | ||
| 1936 | <row> | ||
| 1937 | <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant> </entry> | ||
| 1938 | <entry>boolean</entry> | ||
| 1939 | </row> | ||
| 1940 | <row><entry spanname="descr">Enables or disables the audio compression feature. | ||
| 1941 | This feature amplifies signals below the threshold by a fixed gain and compresses audio | ||
| 1942 | signals above the threshold by the ratio of Threshold/(Gain + Threshold).</entry> | ||
| 1943 | </row> | ||
| 1944 | <row> | ||
| 1945 | <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_GAIN</constant> </entry> | ||
| 1946 | <entry>integer</entry> | ||
| 1947 | </row> | ||
| 1948 | <row><entry spanname="descr">Sets the gain for audio compression feature. It is | ||
| 1949 | a dB value. The range and step are driver-specific.</entry> | ||
| 1950 | </row> | ||
| 1951 | <row> | ||
| 1952 | <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_THRESHOLD</constant> </entry> | ||
| 1953 | <entry>integer</entry> | ||
| 1954 | </row> | ||
| 1955 | <row><entry spanname="descr">Sets the threshold level for audio compression freature. | ||
| 1956 | It is a dB value. The range and step are driver-specific.</entry> | ||
| 1957 | </row> | ||
| 1958 | <row> | ||
| 1959 | <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME</constant> </entry> | ||
| 1960 | <entry>integer</entry> | ||
| 1961 | </row> | ||
| 1962 | <row><entry spanname="descr">Sets the attack time for audio compression feature. | ||
| 1963 | It is a useconds value. The range and step are driver-specific.</entry> | ||
| 1964 | </row> | ||
| 1965 | <row> | ||
| 1966 | <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME</constant> </entry> | ||
| 1967 | <entry>integer</entry> | ||
| 1968 | </row> | ||
| 1969 | <row><entry spanname="descr">Sets the release time for audio compression feature. | ||
| 1970 | It is a useconds value. The range and step are driver-specific.</entry> | ||
| 1971 | </row> | ||
| 1972 | <row> | ||
| 1973 | <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_ENABLED</constant> </entry> | ||
| 1974 | <entry>boolean</entry> | ||
| 1975 | </row> | ||
| 1976 | <row><entry spanname="descr">Enables or disables the pilot tone generation feature.</entry> | ||
| 1977 | </row> | ||
| 1978 | <row> | ||
| 1979 | <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_DEVIATION</constant> </entry> | ||
| 1980 | <entry>integer</entry> | ||
| 1981 | </row> | ||
| 1982 | <row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is | ||
| 1983 | in Hz. The range and step are driver-specific.</entry> | ||
| 1984 | </row> | ||
| 1985 | <row> | ||
| 1986 | <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant> </entry> | ||
| 1987 | <entry>integer</entry> | ||
| 1988 | </row> | ||
| 1989 | <row><entry spanname="descr">Configures pilot tone frequency value. Unit is | ||
| 1990 | in Hz. The range and step are driver-specific.</entry> | ||
| 1991 | </row> | ||
| 1992 | <row> | ||
| 1993 | <entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant> </entry> | ||
| 1994 | <entry>integer</entry> | ||
| 1995 | </row> | ||
| 1996 | <row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting. | ||
| 1997 | A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies. | ||
| 1998 | Depending on the region, a time constant of either 50 or 75 useconds is used. The enum v4l2_preemphasis | ||
| 1999 | defines possible values for pre-emphasis. Here they are:</entry> | ||
| 2000 | </row><row> | ||
| 2001 | <entrytbl spanname="descr" cols="2"> | ||
| 2002 | <tbody valign="top"> | ||
| 2003 | <row> | ||
| 2004 | <entry><constant>V4L2_PREEMPHASIS_DISABLED</constant> </entry> | ||
| 2005 | <entry>No pre-emphasis is applied.</entry> | ||
| 2006 | </row> | ||
| 2007 | <row> | ||
| 2008 | <entry><constant>V4L2_PREEMPHASIS_50_uS</constant> </entry> | ||
| 2009 | <entry>A pre-emphasis of 50 uS is used.</entry> | ||
| 2010 | </row> | ||
| 2011 | <row> | ||
| 2012 | <entry><constant>V4L2_PREEMPHASIS_75_uS</constant> </entry> | ||
| 2013 | <entry>A pre-emphasis of 75 uS is used.</entry> | ||
| 2014 | </row> | ||
| 2015 | </tbody> | ||
| 2016 | </entrytbl> | ||
| 2017 | |||
| 2018 | </row> | ||
| 2019 | <row> | ||
| 2020 | <entry spanname="id"><constant>V4L2_CID_TUNE_POWER_LEVEL</constant> </entry> | ||
| 2021 | <entry>integer</entry> | ||
| 2022 | </row> | ||
| 2023 | <row><entry spanname="descr">Sets the output power level for signal transmission. | ||
| 2024 | Unit is in dBuV. Range and step are driver-specific.</entry> | ||
| 2025 | </row> | ||
| 2026 | <row> | ||
| 2027 | <entry spanname="id"><constant>V4L2_CID_TUNE_ANTENNA_CAPACITOR</constant> </entry> | ||
| 2028 | <entry>integer</entry> | ||
| 2029 | </row> | ||
| 2030 | <row><entry spanname="descr">This selects the value of antenna tuning capacitor | ||
| 2031 | manually or automatically if set to zero. Unit, range and step are driver-specific.</entry> | ||
| 2032 | </row> | ||
| 2033 | <row><entry></entry></row> | ||
| 2034 | </tbody> | ||
| 2035 | </tgroup> | ||
| 2036 | </table> | ||
| 2037 | |||
| 2038 | <para>For more details about RDS specification, refer to | ||
| 2039 | <xref linkend="en50067" /> document, from CENELEC.</para> | ||
| 2040 | </section> | ||
| 2041 | </section> | ||
| 2042 | |||
| 2043 | <!-- | ||
| 2044 | Local Variables: | ||
| 2045 | mode: sgml | ||
| 2046 | sgml-parent-document: "common.sgml" | ||
| 2047 | indent-tabs-mode: nil | ||
| 2048 | End: | ||
| 2049 | --> | ||
diff --git a/Documentation/DocBook/v4l/crop.gif b/Documentation/DocBook/v4l/crop.gif new file mode 100644 index 000000000000..3b9e7d836d4b --- /dev/null +++ b/Documentation/DocBook/v4l/crop.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/crop.pdf b/Documentation/DocBook/v4l/crop.pdf new file mode 100644 index 000000000000..c9fb81cd32f3 --- /dev/null +++ b/Documentation/DocBook/v4l/crop.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/dev-capture.xml b/Documentation/DocBook/v4l/dev-capture.xml new file mode 100644 index 000000000000..32807e43f170 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-capture.xml | |||
| @@ -0,0 +1,115 @@ | |||
| 1 | <title>Video Capture Interface</title> | ||
| 2 | |||
| 3 | <para>Video capture devices sample an analog video signal and store | ||
| 4 | the digitized images in memory. Today nearly all devices can capture | ||
| 5 | at full 25 or 30 frames/second. With this interface applications can | ||
| 6 | control the capture process and move images from the driver into user | ||
| 7 | space.</para> | ||
| 8 | |||
| 9 | <para>Conventionally V4L2 video capture devices are accessed through | ||
| 10 | character device special files named <filename>/dev/video</filename> | ||
| 11 | and <filename>/dev/video0</filename> to | ||
| 12 | <filename>/dev/video63</filename> with major number 81 and minor | ||
| 13 | numbers 0 to 63. <filename>/dev/video</filename> is typically a | ||
| 14 | symbolic link to the preferred video device. Note the same device | ||
| 15 | files are used for video output devices.</para> | ||
| 16 | |||
| 17 | <section> | ||
| 18 | <title>Querying Capabilities</title> | ||
| 19 | |||
| 20 | <para>Devices supporting the video capture interface set the | ||
| 21 | <constant>V4L2_CAP_VIDEO_CAPTURE</constant> flag in the | ||
| 22 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 23 | returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions | ||
| 24 | they may also support the <link linkend="overlay">video overlay</link> | ||
| 25 | (<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link | ||
| 26 | linkend="raw-vbi">raw VBI capture</link> | ||
| 27 | (<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of | ||
| 28 | the read/write or streaming I/O methods must be supported. Tuners and | ||
| 29 | audio inputs are optional.</para> | ||
| 30 | </section> | ||
| 31 | |||
| 32 | <section> | ||
| 33 | <title>Supplemental Functions</title> | ||
| 34 | |||
| 35 | <para>Video capture devices shall support <link | ||
| 36 | linkend="audio">audio input</link>, <link | ||
| 37 | linkend="tuner">tuner</link>, <link linkend="control">controls</link>, | ||
| 38 | <link linkend="crop">cropping and scaling</link> and <link | ||
| 39 | linkend="streaming-par">streaming parameter</link> ioctls as needed. | ||
| 40 | The <link linkend="video">video input</link> and <link | ||
| 41 | linkend="standard">video standard</link> ioctls must be supported by | ||
| 42 | all video capture devices.</para> | ||
| 43 | </section> | ||
| 44 | |||
| 45 | <section> | ||
| 46 | <title>Image Format Negotiation</title> | ||
| 47 | |||
| 48 | <para>The result of a capture operation is determined by | ||
| 49 | cropping and image format parameters. The former select an area of the | ||
| 50 | video picture to capture, the latter how images are stored in memory, | ||
| 51 | &ie; in RGB or YUV format, the number of bits per pixel or width and | ||
| 52 | height. Together they also define how images are scaled in the | ||
| 53 | process.</para> | ||
| 54 | |||
| 55 | <para>As usual these parameters are <emphasis>not</emphasis> reset | ||
| 56 | at &func-open; time to permit Unix tool chains, programming a device | ||
| 57 | and then reading from it as if it was a plain file. Well written V4L2 | ||
| 58 | applications ensure they really get what they want, including cropping | ||
| 59 | and scaling.</para> | ||
| 60 | |||
| 61 | <para>Cropping initialization at minimum requires to reset the | ||
| 62 | parameters to defaults. An example is given in <xref | ||
| 63 | linkend="crop" />.</para> | ||
| 64 | |||
| 65 | <para>To query the current image format applications set the | ||
| 66 | <structfield>type</structfield> field of a &v4l2-format; to | ||
| 67 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and call the | ||
| 68 | &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill | ||
| 69 | the &v4l2-pix-format; <structfield>pix</structfield> member of the | ||
| 70 | <structfield>fmt</structfield> union.</para> | ||
| 71 | |||
| 72 | <para>To request different parameters applications set the | ||
| 73 | <structfield>type</structfield> field of a &v4l2-format; as above and | ||
| 74 | initialize all fields of the &v4l2-pix-format; | ||
| 75 | <structfield>vbi</structfield> member of the | ||
| 76 | <structfield>fmt</structfield> union, or better just modify the | ||
| 77 | results of <constant>VIDIOC_G_FMT</constant>, and call the | ||
| 78 | &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may | ||
| 79 | adjust the parameters and finally return the actual parameters as | ||
| 80 | <constant>VIDIOC_G_FMT</constant> does.</para> | ||
| 81 | |||
| 82 | <para>Like <constant>VIDIOC_S_FMT</constant> the | ||
| 83 | &VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations | ||
| 84 | without disabling I/O or possibly time consuming hardware | ||
| 85 | preparations.</para> | ||
| 86 | |||
| 87 | <para>The contents of &v4l2-pix-format; are discussed in <xref | ||
| 88 | linkend="pixfmt" />. See also the specification of the | ||
| 89 | <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> | ||
| 90 | and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video | ||
| 91 | capture devices must implement both the | ||
| 92 | <constant>VIDIOC_G_FMT</constant> and | ||
| 93 | <constant>VIDIOC_S_FMT</constant> ioctl, even if | ||
| 94 | <constant>VIDIOC_S_FMT</constant> ignores all requests and always | ||
| 95 | returns default parameters as <constant>VIDIOC_G_FMT</constant> does. | ||
| 96 | <constant>VIDIOC_TRY_FMT</constant> is optional.</para> | ||
| 97 | </section> | ||
| 98 | |||
| 99 | <section> | ||
| 100 | <title>Reading Images</title> | ||
| 101 | |||
| 102 | <para>A video capture device may support the <link | ||
| 103 | linkend="rw">read() function</link> and/or streaming (<link | ||
| 104 | linkend="mmap">memory mapping</link> or <link | ||
| 105 | linkend="userp">user pointer</link>) I/O. See <xref | ||
| 106 | linkend="io" /> for details.</para> | ||
| 107 | </section> | ||
| 108 | |||
| 109 | <!-- | ||
| 110 | Local Variables: | ||
| 111 | mode: sgml | ||
| 112 | sgml-parent-document: "v4l2.sgml" | ||
| 113 | indent-tabs-mode: nil | ||
| 114 | End: | ||
| 115 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-codec.xml b/Documentation/DocBook/v4l/dev-codec.xml new file mode 100644 index 000000000000..6e156dc45b94 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-codec.xml | |||
| @@ -0,0 +1,26 @@ | |||
| 1 | <title>Codec Interface</title> | ||
| 2 | |||
| 3 | <note> | ||
| 4 | <title>Suspended</title> | ||
| 5 | |||
| 6 | <para>This interface has been be suspended from the V4L2 API | ||
| 7 | implemented in Linux 2.6 until we have more experience with codec | ||
| 8 | device interfaces.</para> | ||
| 9 | </note> | ||
| 10 | |||
| 11 | <para>A V4L2 codec can compress, decompress, transform, or otherwise | ||
| 12 | convert video data from one format into another format, in memory. | ||
| 13 | Applications send data to be converted to the driver through a | ||
| 14 | &func-write; call, and receive the converted data through a | ||
| 15 | &func-read; call. For efficiency a driver may also support streaming | ||
| 16 | I/O.</para> | ||
| 17 | |||
| 18 | <para>[to do]</para> | ||
| 19 | |||
| 20 | <!-- | ||
| 21 | Local Variables: | ||
| 22 | mode: sgml | ||
| 23 | sgml-parent-document: "v4l2.sgml" | ||
| 24 | indent-tabs-mode: nil | ||
| 25 | End: | ||
| 26 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-effect.xml b/Documentation/DocBook/v4l/dev-effect.xml new file mode 100644 index 000000000000..9c243beba0e6 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-effect.xml | |||
| @@ -0,0 +1,25 @@ | |||
| 1 | <title>Effect Devices Interface</title> | ||
| 2 | |||
| 3 | <note> | ||
| 4 | <title>Suspended</title> | ||
| 5 | |||
| 6 | <para>This interface has been be suspended from the V4L2 API | ||
| 7 | implemented in Linux 2.6 until we have more experience with effect | ||
| 8 | device interfaces.</para> | ||
| 9 | </note> | ||
| 10 | |||
| 11 | <para>A V4L2 video effect device can do image effects, filtering, or | ||
| 12 | combine two or more images or image streams. For example video | ||
| 13 | transitions or wipes. Applications send data to be processed and | ||
| 14 | receive the result data either with &func-read; and &func-write; | ||
| 15 | functions, or through the streaming I/O mechanism.</para> | ||
| 16 | |||
| 17 | <para>[to do]</para> | ||
| 18 | |||
| 19 | <!-- | ||
| 20 | Local Variables: | ||
| 21 | mode: sgml | ||
| 22 | sgml-parent-document: "v4l2.sgml" | ||
| 23 | indent-tabs-mode: nil | ||
| 24 | End: | ||
| 25 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-osd.xml b/Documentation/DocBook/v4l/dev-osd.xml new file mode 100644 index 000000000000..c9a68a2ccd33 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-osd.xml | |||
| @@ -0,0 +1,164 @@ | |||
| 1 | <title>Video Output Overlay Interface</title> | ||
| 2 | <subtitle>Also known as On-Screen Display (OSD)</subtitle> | ||
| 3 | |||
| 4 | <note> | ||
| 5 | <title>Experimental</title> | ||
| 6 | |||
| 7 | <para>This is an <link linkend="experimental">experimental</link> | ||
| 8 | interface and may change in the future.</para> | ||
| 9 | </note> | ||
| 10 | |||
| 11 | <para>Some video output devices can overlay a framebuffer image onto | ||
| 12 | the outgoing video signal. Applications can set up such an overlay | ||
| 13 | using this interface, which borrows structures and ioctls of the <link | ||
| 14 | linkend="overlay">Video Overlay</link> interface.</para> | ||
| 15 | |||
| 16 | <para>The OSD function is accessible through the same character | ||
| 17 | special file as the <link linkend="capture">Video Output</link> function. | ||
| 18 | Note the default function of such a <filename>/dev/video</filename> device | ||
| 19 | is video capturing or output. The OSD function is only available after | ||
| 20 | calling the &VIDIOC-S-FMT; ioctl.</para> | ||
| 21 | |||
| 22 | <section> | ||
| 23 | <title>Querying Capabilities</title> | ||
| 24 | |||
| 25 | <para>Devices supporting the <wordasword>Video Output | ||
| 26 | Overlay</wordasword> interface set the | ||
| 27 | <constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the | ||
| 28 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 29 | returned by the &VIDIOC-QUERYCAP; ioctl.</para> | ||
| 30 | </section> | ||
| 31 | |||
| 32 | <section> | ||
| 33 | <title>Framebuffer</title> | ||
| 34 | |||
| 35 | <para>Contrary to the <wordasword>Video Overlay</wordasword> | ||
| 36 | interface the framebuffer is normally implemented on the TV card and | ||
| 37 | not the graphics card. On Linux it is accessible as a framebuffer | ||
| 38 | device (<filename>/dev/fbN</filename>). Given a V4L2 device, | ||
| 39 | applications can find the corresponding framebuffer device by calling | ||
| 40 | the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the | ||
| 41 | physical address of the framebuffer in the | ||
| 42 | <structfield>base</structfield> field of &v4l2-framebuffer;. The | ||
| 43 | framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant> | ||
| 44 | returns the same address in the <structfield>smem_start</structfield> | ||
| 45 | field of struct <structname>fb_fix_screeninfo</structname>. The | ||
| 46 | <constant>FBIOGET_FSCREENINFO</constant> ioctl and struct | ||
| 47 | <structname>fb_fix_screeninfo</structname> are defined in the | ||
| 48 | <filename>linux/fb.h</filename> header file.</para> | ||
| 49 | |||
| 50 | <para>The width and height of the framebuffer depends on the | ||
| 51 | current video standard. A V4L2 driver may reject attempts to change | ||
| 52 | the video standard (or any other ioctl which would imply a framebuffer | ||
| 53 | size change) with an &EBUSY; until all applications closed the | ||
| 54 | framebuffer device.</para> | ||
| 55 | |||
| 56 | <example> | ||
| 57 | <title>Finding a framebuffer device for OSD</title> | ||
| 58 | |||
| 59 | <programlisting> | ||
| 60 | #include <linux/fb.h> | ||
| 61 | |||
| 62 | &v4l2-framebuffer; fbuf; | ||
| 63 | unsigned int i; | ||
| 64 | int fb_fd; | ||
| 65 | |||
| 66 | if (-1 == ioctl (fd, VIDIOC_G_FBUF, &fbuf)) { | ||
| 67 | perror ("VIDIOC_G_FBUF"); | ||
| 68 | exit (EXIT_FAILURE); | ||
| 69 | } | ||
| 70 | |||
| 71 | for (i = 0; i > 30; ++i) { | ||
| 72 | char dev_name[16]; | ||
| 73 | struct fb_fix_screeninfo si; | ||
| 74 | |||
| 75 | snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i); | ||
| 76 | |||
| 77 | fb_fd = open (dev_name, O_RDWR); | ||
| 78 | if (-1 == fb_fd) { | ||
| 79 | switch (errno) { | ||
| 80 | case ENOENT: /* no such file */ | ||
| 81 | case ENXIO: /* no driver */ | ||
| 82 | continue; | ||
| 83 | |||
| 84 | default: | ||
| 85 | perror ("open"); | ||
| 86 | exit (EXIT_FAILURE); | ||
| 87 | } | ||
| 88 | } | ||
| 89 | |||
| 90 | if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &si)) { | ||
| 91 | if (si.smem_start == (unsigned long) fbuf.base) | ||
| 92 | break; | ||
| 93 | } else { | ||
| 94 | /* Apparently not a framebuffer device. */ | ||
| 95 | } | ||
| 96 | |||
| 97 | close (fb_fd); | ||
| 98 | fb_fd = -1; | ||
| 99 | } | ||
| 100 | |||
| 101 | /* fb_fd is the file descriptor of the framebuffer device | ||
| 102 | for the video output overlay, or -1 if no device was found. */ | ||
| 103 | </programlisting> | ||
| 104 | </example> | ||
| 105 | </section> | ||
| 106 | |||
| 107 | <section> | ||
| 108 | <title>Overlay Window and Scaling</title> | ||
| 109 | |||
| 110 | <para>The overlay is controlled by source and target rectangles. | ||
| 111 | The source rectangle selects a subsection of the framebuffer image to | ||
| 112 | be overlaid, the target rectangle an area in the outgoing video signal | ||
| 113 | where the image will appear. Drivers may or may not support scaling, | ||
| 114 | and arbitrary sizes and positions of these rectangles. Further drivers | ||
| 115 | may support any (or none) of the clipping/blending methods defined for | ||
| 116 | the <link linkend="overlay">Video Overlay</link> interface.</para> | ||
| 117 | |||
| 118 | <para>A &v4l2-window; defines the size of the source rectangle, | ||
| 119 | its position in the framebuffer and the clipping/blending method to be | ||
| 120 | used for the overlay. To get the current parameters applications set | ||
| 121 | the <structfield>type</structfield> field of a &v4l2-format; to | ||
| 122 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the | ||
| 123 | &VIDIOC-G-FMT; ioctl. The driver fills the | ||
| 124 | <structname>v4l2_window</structname> substructure named | ||
| 125 | <structfield>win</structfield>. It is not possible to retrieve a | ||
| 126 | previously programmed clipping list or bitmap.</para> | ||
| 127 | |||
| 128 | <para>To program the source rectangle applications set the | ||
| 129 | <structfield>type</structfield> field of a &v4l2-format; to | ||
| 130 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize | ||
| 131 | the <structfield>win</structfield> substructure and call the | ||
| 132 | &VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against | ||
| 133 | hardware limits and returns the actual parameters as | ||
| 134 | <constant>VIDIOC_G_FMT</constant> does. Like | ||
| 135 | <constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be | ||
| 136 | used to learn about driver capabilities without actually changing | ||
| 137 | driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works | ||
| 138 | after the overlay has been enabled.</para> | ||
| 139 | |||
| 140 | <para>A &v4l2-crop; defines the size and position of the target | ||
| 141 | rectangle. The scaling factor of the overlay is implied by the width | ||
| 142 | and height given in &v4l2-window; and &v4l2-crop;. The cropping API | ||
| 143 | applies to <wordasword>Video Output</wordasword> and <wordasword>Video | ||
| 144 | Output Overlay</wordasword> devices in the same way as to | ||
| 145 | <wordasword>Video Capture</wordasword> and <wordasword>Video | ||
| 146 | Overlay</wordasword> devices, merely reversing the direction of the | ||
| 147 | data flow. For more information see <xref linkend="crop" />.</para> | ||
| 148 | </section> | ||
| 149 | |||
| 150 | <section> | ||
| 151 | <title>Enabling Overlay</title> | ||
| 152 | |||
| 153 | <para>There is no V4L2 ioctl to enable or disable the overlay, | ||
| 154 | however the framebuffer interface of the driver may support the | ||
| 155 | <constant>FBIOBLANK</constant> ioctl.</para> | ||
| 156 | </section> | ||
| 157 | |||
| 158 | <!-- | ||
| 159 | Local Variables: | ||
| 160 | mode: sgml | ||
| 161 | sgml-parent-document: "v4l2.sgml" | ||
| 162 | indent-tabs-mode: nil | ||
| 163 | End: | ||
| 164 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-output.xml b/Documentation/DocBook/v4l/dev-output.xml new file mode 100644 index 000000000000..63c3c20e5a72 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-output.xml | |||
| @@ -0,0 +1,111 @@ | |||
| 1 | <title>Video Output Interface</title> | ||
| 2 | |||
| 3 | <para>Video output devices encode stills or image sequences as | ||
| 4 | analog video signal. With this interface applications can | ||
| 5 | control the encoding process and move images from user space to | ||
| 6 | the driver.</para> | ||
| 7 | |||
| 8 | <para>Conventionally V4L2 video output devices are accessed through | ||
| 9 | character device special files named <filename>/dev/video</filename> | ||
| 10 | and <filename>/dev/video0</filename> to | ||
| 11 | <filename>/dev/video63</filename> with major number 81 and minor | ||
| 12 | numbers 0 to 63. <filename>/dev/video</filename> is typically a | ||
| 13 | symbolic link to the preferred video device. Note the same device | ||
| 14 | files are used for video capture devices.</para> | ||
| 15 | |||
| 16 | <section> | ||
| 17 | <title>Querying Capabilities</title> | ||
| 18 | |||
| 19 | <para>Devices supporting the video output interface set the | ||
| 20 | <constant>V4L2_CAP_VIDEO_OUTPUT</constant> flag in the | ||
| 21 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 22 | returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions | ||
| 23 | they may also support the <link linkend="raw-vbi">raw VBI | ||
| 24 | output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At | ||
| 25 | least one of the read/write or streaming I/O methods must be | ||
| 26 | supported. Modulators and audio outputs are optional.</para> | ||
| 27 | </section> | ||
| 28 | |||
| 29 | <section> | ||
| 30 | <title>Supplemental Functions</title> | ||
| 31 | |||
| 32 | <para>Video output devices shall support <link | ||
| 33 | linkend="audio">audio output</link>, <link | ||
| 34 | linkend="tuner">modulator</link>, <link linkend="control">controls</link>, | ||
| 35 | <link linkend="crop">cropping and scaling</link> and <link | ||
| 36 | linkend="streaming-par">streaming parameter</link> ioctls as needed. | ||
| 37 | The <link linkend="video">video output</link> and <link | ||
| 38 | linkend="standard">video standard</link> ioctls must be supported by | ||
| 39 | all video output devices.</para> | ||
| 40 | </section> | ||
| 41 | |||
| 42 | <section> | ||
| 43 | <title>Image Format Negotiation</title> | ||
| 44 | |||
| 45 | <para>The output is determined by cropping and image format | ||
| 46 | parameters. The former select an area of the video picture where the | ||
| 47 | image will appear, the latter how images are stored in memory, &ie; in | ||
| 48 | RGB or YUV format, the number of bits per pixel or width and height. | ||
| 49 | Together they also define how images are scaled in the process.</para> | ||
| 50 | |||
| 51 | <para>As usual these parameters are <emphasis>not</emphasis> reset | ||
| 52 | at &func-open; time to permit Unix tool chains, programming a device | ||
| 53 | and then writing to it as if it was a plain file. Well written V4L2 | ||
| 54 | applications ensure they really get what they want, including cropping | ||
| 55 | and scaling.</para> | ||
| 56 | |||
| 57 | <para>Cropping initialization at minimum requires to reset the | ||
| 58 | parameters to defaults. An example is given in <xref | ||
| 59 | linkend="crop" />.</para> | ||
| 60 | |||
| 61 | <para>To query the current image format applications set the | ||
| 62 | <structfield>type</structfield> field of a &v4l2-format; to | ||
| 63 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and call the | ||
| 64 | &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill | ||
| 65 | the &v4l2-pix-format; <structfield>pix</structfield> member of the | ||
| 66 | <structfield>fmt</structfield> union.</para> | ||
| 67 | |||
| 68 | <para>To request different parameters applications set the | ||
| 69 | <structfield>type</structfield> field of a &v4l2-format; as above and | ||
| 70 | initialize all fields of the &v4l2-pix-format; | ||
| 71 | <structfield>vbi</structfield> member of the | ||
| 72 | <structfield>fmt</structfield> union, or better just modify the | ||
| 73 | results of <constant>VIDIOC_G_FMT</constant>, and call the | ||
| 74 | &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may | ||
| 75 | adjust the parameters and finally return the actual parameters as | ||
| 76 | <constant>VIDIOC_G_FMT</constant> does.</para> | ||
| 77 | |||
| 78 | <para>Like <constant>VIDIOC_S_FMT</constant> the | ||
| 79 | &VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations | ||
| 80 | without disabling I/O or possibly time consuming hardware | ||
| 81 | preparations.</para> | ||
| 82 | |||
| 83 | <para>The contents of &v4l2-pix-format; are discussed in <xref | ||
| 84 | linkend="pixfmt" />. See also the specification of the | ||
| 85 | <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> | ||
| 86 | and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video | ||
| 87 | output devices must implement both the | ||
| 88 | <constant>VIDIOC_G_FMT</constant> and | ||
| 89 | <constant>VIDIOC_S_FMT</constant> ioctl, even if | ||
| 90 | <constant>VIDIOC_S_FMT</constant> ignores all requests and always | ||
| 91 | returns default parameters as <constant>VIDIOC_G_FMT</constant> does. | ||
| 92 | <constant>VIDIOC_TRY_FMT</constant> is optional.</para> | ||
| 93 | </section> | ||
| 94 | |||
| 95 | <section> | ||
| 96 | <title>Writing Images</title> | ||
| 97 | |||
| 98 | <para>A video output device may support the <link | ||
| 99 | linkend="rw">write() function</link> and/or streaming (<link | ||
| 100 | linkend="mmap">memory mapping</link> or <link | ||
| 101 | linkend="userp">user pointer</link>) I/O. See <xref | ||
| 102 | linkend="io" /> for details.</para> | ||
| 103 | </section> | ||
| 104 | |||
| 105 | <!-- | ||
| 106 | Local Variables: | ||
| 107 | mode: sgml | ||
| 108 | sgml-parent-document: "v4l2.sgml" | ||
| 109 | indent-tabs-mode: nil | ||
| 110 | End: | ||
| 111 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-overlay.xml b/Documentation/DocBook/v4l/dev-overlay.xml new file mode 100644 index 000000000000..92513cf79150 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-overlay.xml | |||
| @@ -0,0 +1,379 @@ | |||
| 1 | <title>Video Overlay Interface</title> | ||
| 2 | <subtitle>Also known as Framebuffer Overlay or Previewing</subtitle> | ||
| 3 | |||
| 4 | <para>Video overlay devices have the ability to genlock (TV-)video | ||
| 5 | into the (VGA-)video signal of a graphics card, or to store captured | ||
| 6 | images directly in video memory of a graphics card, typically with | ||
| 7 | clipping. This can be considerable more efficient than capturing | ||
| 8 | images and displaying them by other means. In the old days when only | ||
| 9 | nuclear power plants needed cooling towers this used to be the only | ||
| 10 | way to put live video into a window.</para> | ||
| 11 | |||
| 12 | <para>Video overlay devices are accessed through the same character | ||
| 13 | special files as <link linkend="capture">video capture</link> devices. | ||
| 14 | Note the default function of a <filename>/dev/video</filename> device | ||
| 15 | is video capturing. The overlay function is only available after | ||
| 16 | calling the &VIDIOC-S-FMT; ioctl.</para> | ||
| 17 | |||
| 18 | <para>The driver may support simultaneous overlay and capturing | ||
| 19 | using the read/write and streaming I/O methods. If so, operation at | ||
| 20 | the nominal frame rate of the video standard is not guaranteed. Frames | ||
| 21 | may be directed away from overlay to capture, or one field may be used | ||
| 22 | for overlay and the other for capture if the capture parameters permit | ||
| 23 | this.</para> | ||
| 24 | |||
| 25 | <para>Applications should use different file descriptors for | ||
| 26 | capturing and overlay. This must be supported by all drivers capable | ||
| 27 | of simultaneous capturing and overlay. Optionally these drivers may | ||
| 28 | also permit capturing and overlay with a single file descriptor for | ||
| 29 | compatibility with V4L and earlier versions of V4L2.<footnote> | ||
| 30 | <para>A common application of two file descriptors is the | ||
| 31 | XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and | ||
| 32 | a V4L2 application. While the X server controls video overlay, the | ||
| 33 | application can take advantage of memory mapping and DMA.</para> | ||
| 34 | <para>In the opinion of the designers of this API, no driver | ||
| 35 | writer taking the efforts to support simultaneous capturing and | ||
| 36 | overlay will restrict this ability by requiring a single file | ||
| 37 | descriptor, as in V4L and earlier versions of V4L2. Making this | ||
| 38 | optional means applications depending on two file descriptors need | ||
| 39 | backup routines to be compatible with all drivers, which is | ||
| 40 | considerable more work than using two fds in applications which do | ||
| 41 | not. Also two fd's fit the general concept of one file descriptor for | ||
| 42 | each logical stream. Hence as a complexity trade-off drivers | ||
| 43 | <emphasis>must</emphasis> support two file descriptors and | ||
| 44 | <emphasis>may</emphasis> support single fd operation.</para> | ||
| 45 | </footnote></para> | ||
| 46 | |||
| 47 | <section> | ||
| 48 | <title>Querying Capabilities</title> | ||
| 49 | |||
| 50 | <para>Devices supporting the video overlay interface set the | ||
| 51 | <constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag in the | ||
| 52 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 53 | returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified | ||
| 54 | below must be supported. Tuners and audio inputs are optional.</para> | ||
| 55 | </section> | ||
| 56 | |||
| 57 | <section> | ||
| 58 | <title>Supplemental Functions</title> | ||
| 59 | |||
| 60 | <para>Video overlay devices shall support <link | ||
| 61 | linkend="audio">audio input</link>, <link | ||
| 62 | linkend="tuner">tuner</link>, <link linkend="control">controls</link>, | ||
| 63 | <link linkend="crop">cropping and scaling</link> and <link | ||
| 64 | linkend="streaming-par">streaming parameter</link> ioctls as needed. | ||
| 65 | The <link linkend="video">video input</link> and <link | ||
| 66 | linkend="standard">video standard</link> ioctls must be supported by | ||
| 67 | all video overlay devices.</para> | ||
| 68 | </section> | ||
| 69 | |||
| 70 | <section> | ||
| 71 | <title>Setup</title> | ||
| 72 | |||
| 73 | <para>Before overlay can commence applications must program the | ||
| 74 | driver with frame buffer parameters, namely the address and size of | ||
| 75 | the frame buffer and the image format, for example RGB 5:6:5. The | ||
| 76 | &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF; ioctls are available to get | ||
| 77 | and set these parameters, respectively. The | ||
| 78 | <constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it | ||
| 79 | allows to set up DMA into physical memory, bypassing the memory | ||
| 80 | protection mechanisms of the kernel. Only the superuser can change the | ||
| 81 | frame buffer address and size. Users are not supposed to run TV | ||
| 82 | applications as root or with SUID bit set. A small helper application | ||
| 83 | with suitable privileges should query the graphics system and program | ||
| 84 | the V4L2 driver at the appropriate time.</para> | ||
| 85 | |||
| 86 | <para>Some devices add the video overlay to the output signal | ||
| 87 | of the graphics card. In this case the frame buffer is not modified by | ||
| 88 | the video device, and the frame buffer address and pixel format are | ||
| 89 | not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl | ||
| 90 | is not privileged. An application can check for this type of device by | ||
| 91 | calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para> | ||
| 92 | |||
| 93 | <para>A driver may support any (or none) of five clipping/blending | ||
| 94 | methods:<orderedlist> | ||
| 95 | <listitem> | ||
| 96 | <para>Chroma-keying displays the overlaid image only where | ||
| 97 | pixels in the primary graphics surface assume a certain color.</para> | ||
| 98 | </listitem> | ||
| 99 | <listitem> | ||
| 100 | <para>A bitmap can be specified where each bit corresponds | ||
| 101 | to a pixel in the overlaid image. When the bit is set, the | ||
| 102 | corresponding video pixel is displayed, otherwise a pixel of the | ||
| 103 | graphics surface.</para> | ||
| 104 | </listitem> | ||
| 105 | <listitem> | ||
| 106 | <para>A list of clipping rectangles can be specified. In | ||
| 107 | these regions <emphasis>no</emphasis> video is displayed, so the | ||
| 108 | graphics surface can be seen here.</para> | ||
| 109 | </listitem> | ||
| 110 | <listitem> | ||
| 111 | <para>The framebuffer has an alpha channel that can be used | ||
| 112 | to clip or blend the framebuffer with the video.</para> | ||
| 113 | </listitem> | ||
| 114 | <listitem> | ||
| 115 | <para>A global alpha value can be specified to blend the | ||
| 116 | framebuffer contents with video images.</para> | ||
| 117 | </listitem> | ||
| 118 | </orderedlist></para> | ||
| 119 | |||
| 120 | <para>When simultaneous capturing and overlay is supported and | ||
| 121 | the hardware prohibits different image and frame buffer formats, the | ||
| 122 | format requested first takes precedence. The attempt to capture | ||
| 123 | (&VIDIOC-S-FMT;) or overlay (&VIDIOC-S-FBUF;) may fail with an | ||
| 124 | &EBUSY; or return accordingly modified parameters..</para> | ||
| 125 | </section> | ||
| 126 | |||
| 127 | <section> | ||
| 128 | <title>Overlay Window</title> | ||
| 129 | |||
| 130 | <para>The overlaid image is determined by cropping and overlay | ||
| 131 | window parameters. The former select an area of the video picture to | ||
| 132 | capture, the latter how images are overlaid and clipped. Cropping | ||
| 133 | initialization at minimum requires to reset the parameters to | ||
| 134 | defaults. An example is given in <xref linkend="crop" />.</para> | ||
| 135 | |||
| 136 | <para>The overlay window is described by a &v4l2-window;. It | ||
| 137 | defines the size of the image, its position over the graphics surface | ||
| 138 | and the clipping to be applied. To get the current parameters | ||
| 139 | applications set the <structfield>type</structfield> field of a | ||
| 140 | &v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant> and | ||
| 141 | call the &VIDIOC-G-FMT; ioctl. The driver fills the | ||
| 142 | <structname>v4l2_window</structname> substructure named | ||
| 143 | <structfield>win</structfield>. It is not possible to retrieve a | ||
| 144 | previously programmed clipping list or bitmap.</para> | ||
| 145 | |||
| 146 | <para>To program the overlay window applications set the | ||
| 147 | <structfield>type</structfield> field of a &v4l2-format; to | ||
| 148 | <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, initialize the | ||
| 149 | <structfield>win</structfield> substructure and call the | ||
| 150 | &VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against | ||
| 151 | hardware limits and returns the actual parameters as | ||
| 152 | <constant>VIDIOC_G_FMT</constant> does. Like | ||
| 153 | <constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be | ||
| 154 | used to learn about driver capabilities without actually changing | ||
| 155 | driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works | ||
| 156 | after the overlay has been enabled.</para> | ||
| 157 | |||
| 158 | <para>The scaling factor of the overlaid image is implied by the | ||
| 159 | width and height given in &v4l2-window; and the size of the cropping | ||
| 160 | rectangle. For more information see <xref linkend="crop" />.</para> | ||
| 161 | |||
| 162 | <para>When simultaneous capturing and overlay is supported and | ||
| 163 | the hardware prohibits different image and window sizes, the size | ||
| 164 | requested first takes precedence. The attempt to capture or overlay as | ||
| 165 | well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly | ||
| 166 | modified parameters.</para> | ||
| 167 | |||
| 168 | <table pgwide="1" frame="none" id="v4l2-window"> | ||
| 169 | <title>struct <structname>v4l2_window</structname></title> | ||
| 170 | <tgroup cols="3"> | ||
| 171 | &cs-str; | ||
| 172 | <tbody valign="top"> | ||
| 173 | <row> | ||
| 174 | <entry>&v4l2-rect;</entry> | ||
| 175 | <entry><structfield>w</structfield></entry> | ||
| 176 | <entry>Size and position of the window relative to the | ||
| 177 | top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The | ||
| 178 | window can extend the frame buffer width and height, the | ||
| 179 | <structfield>x</structfield> and <structfield>y</structfield> | ||
| 180 | coordinates can be negative, and it can lie completely outside the | ||
| 181 | frame buffer. The driver clips the window accordingly, or if that is | ||
| 182 | not possible, modifies its size and/or position.</entry> | ||
| 183 | </row> | ||
| 184 | <row> | ||
| 185 | <entry>&v4l2-field;</entry> | ||
| 186 | <entry><structfield>field</structfield></entry> | ||
| 187 | <entry>Applications set this field to determine which | ||
| 188 | video field shall be overlaid, typically one of | ||
| 189 | <constant>V4L2_FIELD_ANY</constant> (0), | ||
| 190 | <constant>V4L2_FIELD_TOP</constant>, | ||
| 191 | <constant>V4L2_FIELD_BOTTOM</constant> or | ||
| 192 | <constant>V4L2_FIELD_INTERLACED</constant>. Drivers may have to choose | ||
| 193 | a different field order and return the actual setting here.</entry> | ||
| 194 | </row> | ||
| 195 | <row> | ||
| 196 | <entry>__u32</entry> | ||
| 197 | <entry><structfield>chromakey</structfield></entry> | ||
| 198 | <entry>When chroma-keying has been negotiated with | ||
| 199 | &VIDIOC-S-FBUF; applications set this field to the desired pixel value | ||
| 200 | for the chroma key. The format is the same as the pixel format of the | ||
| 201 | framebuffer (&v4l2-framebuffer; | ||
| 202 | <structfield>fmt.pixelformat</structfield> field), with bytes in host | ||
| 203 | order. E. g. for <link | ||
| 204 | linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link> | ||
| 205 | the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big | ||
| 206 | endian host.</entry> | ||
| 207 | </row> | ||
| 208 | <row> | ||
| 209 | <entry>&v4l2-clip; *</entry> | ||
| 210 | <entry><structfield>clips</structfield></entry> | ||
| 211 | <entry>When chroma-keying has <emphasis>not</emphasis> | ||
| 212 | been negotiated and &VIDIOC-G-FBUF; indicated this capability, | ||
| 213 | applications can set this field to point to an array of | ||
| 214 | clipping rectangles.</entry> | ||
| 215 | </row> | ||
| 216 | <row> | ||
| 217 | <entry></entry> | ||
| 218 | <entry></entry> | ||
| 219 | <entry>Like the window coordinates | ||
| 220 | <structfield>w</structfield>, clipping rectangles are defined relative | ||
| 221 | to the top, left corner of the frame buffer. However clipping | ||
| 222 | rectangles must not extend the frame buffer width and height, and they | ||
| 223 | must not overlap. If possible applications should merge adjacent | ||
| 224 | rectangles. Whether this must create x-y or y-x bands, or the order of | ||
| 225 | rectangles, is not defined. When clip lists are not supported the | ||
| 226 | driver ignores this field. Its contents after calling &VIDIOC-S-FMT; | ||
| 227 | are undefined.</entry> | ||
| 228 | </row> | ||
| 229 | <row> | ||
| 230 | <entry>__u32</entry> | ||
| 231 | <entry><structfield>clipcount</structfield></entry> | ||
| 232 | <entry>When the application set the | ||
| 233 | <structfield>clips</structfield> field, this field must contain the | ||
| 234 | number of clipping rectangles in the list. When clip lists are not | ||
| 235 | supported the driver ignores this field, its contents after calling | ||
| 236 | <constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are | ||
| 237 | supported but no clipping is desired this field must be set to | ||
| 238 | zero.</entry> | ||
| 239 | </row> | ||
| 240 | <row> | ||
| 241 | <entry>void *</entry> | ||
| 242 | <entry><structfield>bitmap</structfield></entry> | ||
| 243 | <entry>When chroma-keying has | ||
| 244 | <emphasis>not</emphasis> been negotiated and &VIDIOC-G-FBUF; indicated | ||
| 245 | this capability, applications can set this field to point to a | ||
| 246 | clipping bit mask.</entry> | ||
| 247 | </row> | ||
| 248 | <row> | ||
| 249 | <entry spanname="hspan"><para>It must be of the same size | ||
| 250 | as the window, <structfield>w.width</structfield> and | ||
| 251 | <structfield>w.height</structfield>. Each bit corresponds to a pixel | ||
| 252 | in the overlaid image, which is displayed only when the bit is | ||
| 253 | <emphasis>set</emphasis>. Pixel coordinates translate to bits like: | ||
| 254 | <programlisting> | ||
| 255 | ((__u8 *) <structfield>bitmap</structfield>)[<structfield>w.width</structfield> * y + x / 8] & (1 << (x & 7))</programlisting></para><para>where <structfield>0</structfield> ≤ x < | ||
| 256 | <structfield>w.width</structfield> and <structfield>0</structfield> ≤ | ||
| 257 | y <<structfield>w.height</structfield>.<footnote> | ||
| 258 | <para>Should we require | ||
| 259 | <structfield>w.width</structfield> to be a multiple of | ||
| 260 | eight?</para> | ||
| 261 | </footnote></para><para>When a clipping | ||
| 262 | bit mask is not supported the driver ignores this field, its contents | ||
| 263 | after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported | ||
| 264 | but no clipping is desired this field must be set to | ||
| 265 | <constant>NULL</constant>.</para><para>Applications need not create a | ||
| 266 | clip list or bit mask. When they pass both, or despite negotiating | ||
| 267 | chroma-keying, the results are undefined. Regardless of the chosen | ||
| 268 | method, the clipping abilities of the hardware may be limited in | ||
| 269 | quantity or quality. The results when these limits are exceeded are | ||
| 270 | undefined.<footnote> | ||
| 271 | <para>When the image is written into frame buffer | ||
| 272 | memory it will be undesirable if the driver clips out less pixels | ||
| 273 | than expected, because the application and graphics system are not | ||
| 274 | aware these regions need to be refreshed. The driver should clip out | ||
| 275 | more pixels or not write the image at all.</para> | ||
| 276 | </footnote></para></entry> | ||
| 277 | </row> | ||
| 278 | <row> | ||
| 279 | <entry>__u8</entry> | ||
| 280 | <entry><structfield>global_alpha</structfield></entry> | ||
| 281 | <entry>The global alpha value used to blend the | ||
| 282 | framebuffer with video images, if global alpha blending has been | ||
| 283 | negotiated (<constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant>, see | ||
| 284 | &VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry> | ||
| 285 | </row> | ||
| 286 | <row> | ||
| 287 | <entry></entry> | ||
| 288 | <entry></entry> | ||
| 289 | <entry>Note this field was added in Linux 2.6.23, extending the structure. However | ||
| 290 | the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, | ||
| 291 | which take a pointer to a <link | ||
| 292 | linkend="v4l2-format">v4l2_format</link> parent structure with padding | ||
| 293 | bytes at the end, are not affected.</entry> | ||
| 294 | </row> | ||
| 295 | </tbody> | ||
| 296 | </tgroup> | ||
| 297 | </table> | ||
| 298 | |||
| 299 | <table pgwide="1" frame="none" id="v4l2-clip"> | ||
| 300 | <title>struct <structname>v4l2_clip</structname><footnote> | ||
| 301 | <para>The X Window system defines "regions" which are | ||
| 302 | vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 - | ||
| 303 | x1 and height = y2 - y1, so one cannot pass X11 clip lists | ||
| 304 | directly.</para> | ||
| 305 | </footnote></title> | ||
| 306 | <tgroup cols="3"> | ||
| 307 | &cs-str; | ||
| 308 | <tbody valign="top"> | ||
| 309 | <row> | ||
| 310 | <entry>&v4l2-rect;</entry> | ||
| 311 | <entry><structfield>c</structfield></entry> | ||
| 312 | <entry>Coordinates of the clipping rectangle, relative to | ||
| 313 | the top, left corner of the frame buffer. Only window pixels | ||
| 314 | <emphasis>outside</emphasis> all clipping rectangles are | ||
| 315 | displayed.</entry> | ||
| 316 | </row> | ||
| 317 | <row> | ||
| 318 | <entry>&v4l2-clip; *</entry> | ||
| 319 | <entry><structfield>next</structfield></entry> | ||
| 320 | <entry>Pointer to the next clipping rectangle, NULL when | ||
| 321 | this is the last rectangle. Drivers ignore this field, it cannot be | ||
| 322 | used to pass a linked list of clipping rectangles.</entry> | ||
| 323 | </row> | ||
| 324 | </tbody> | ||
| 325 | </tgroup> | ||
| 326 | </table> | ||
| 327 | |||
| 328 | <!-- NB for easier reading this table is duplicated | ||
| 329 | in the vidioc-cropcap chapter.--> | ||
| 330 | |||
| 331 | <table pgwide="1" frame="none" id="v4l2-rect"> | ||
| 332 | <title>struct <structname>v4l2_rect</structname></title> | ||
| 333 | <tgroup cols="3"> | ||
| 334 | &cs-str; | ||
| 335 | <tbody valign="top"> | ||
| 336 | <row> | ||
| 337 | <entry>__s32</entry> | ||
| 338 | <entry><structfield>left</structfield></entry> | ||
| 339 | <entry>Horizontal offset of the top, left corner of the | ||
| 340 | rectangle, in pixels.</entry> | ||
| 341 | </row> | ||
| 342 | <row> | ||
| 343 | <entry>__s32</entry> | ||
| 344 | <entry><structfield>top</structfield></entry> | ||
| 345 | <entry>Vertical offset of the top, left corner of the | ||
| 346 | rectangle, in pixels. Offsets increase to the right and down.</entry> | ||
| 347 | </row> | ||
| 348 | <row> | ||
| 349 | <entry>__s32</entry> | ||
| 350 | <entry><structfield>width</structfield></entry> | ||
| 351 | <entry>Width of the rectangle, in pixels.</entry> | ||
| 352 | </row> | ||
| 353 | <row> | ||
| 354 | <entry>__s32</entry> | ||
| 355 | <entry><structfield>height</structfield></entry> | ||
| 356 | <entry>Height of the rectangle, in pixels. Width and | ||
| 357 | height cannot be negative, the fields are signed for hysterical | ||
| 358 | reasons. <!-- video4linux-list@redhat.com on 22 Oct 2002 subject | ||
| 359 | "Re:[V4L][patches!] Re:v4l2/kernel-2.5" --></entry> | ||
| 360 | </row> | ||
| 361 | </tbody> | ||
| 362 | </tgroup> | ||
| 363 | </table> | ||
| 364 | </section> | ||
| 365 | |||
| 366 | <section> | ||
| 367 | <title>Enabling Overlay</title> | ||
| 368 | |||
| 369 | <para>To start or stop the frame buffer overlay applications call | ||
| 370 | the &VIDIOC-OVERLAY; ioctl.</para> | ||
| 371 | </section> | ||
| 372 | |||
| 373 | <!-- | ||
| 374 | Local Variables: | ||
| 375 | mode: sgml | ||
| 376 | sgml-parent-document: "v4l2.sgml" | ||
| 377 | indent-tabs-mode: nil | ||
| 378 | End: | ||
| 379 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-radio.xml b/Documentation/DocBook/v4l/dev-radio.xml new file mode 100644 index 000000000000..73aa90b45b34 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-radio.xml | |||
| @@ -0,0 +1,57 @@ | |||
| 1 | <title>Radio Interface</title> | ||
| 2 | |||
| 3 | <para>This interface is intended for AM and FM (analog) radio | ||
| 4 | receivers and transmitters.</para> | ||
| 5 | |||
| 6 | <para>Conventionally V4L2 radio devices are accessed through | ||
| 7 | character device special files named <filename>/dev/radio</filename> | ||
| 8 | and <filename>/dev/radio0</filename> to | ||
| 9 | <filename>/dev/radio63</filename> with major number 81 and minor | ||
| 10 | numbers 64 to 127.</para> | ||
| 11 | |||
| 12 | <section> | ||
| 13 | <title>Querying Capabilities</title> | ||
| 14 | |||
| 15 | <para>Devices supporting the radio interface set the | ||
| 16 | <constant>V4L2_CAP_RADIO</constant> and | ||
| 17 | <constant>V4L2_CAP_TUNER</constant> or | ||
| 18 | <constant>V4L2_CAP_MODULATOR</constant> flag in the | ||
| 19 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 20 | returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of | ||
| 21 | capability flags are reserved for future extensions.</para> | ||
| 22 | </section> | ||
| 23 | |||
| 24 | <section> | ||
| 25 | <title>Supplemental Functions</title> | ||
| 26 | |||
| 27 | <para>Radio devices can support <link | ||
| 28 | linkend="control">controls</link>, and must support the <link | ||
| 29 | linkend="tuner">tuner or modulator</link> ioctls.</para> | ||
| 30 | |||
| 31 | <para>They do not support the video input or output, audio input | ||
| 32 | or output, video standard, cropping and scaling, compression and | ||
| 33 | streaming parameter, or overlay ioctls. All other ioctls and I/O | ||
| 34 | methods are reserved for future extensions.</para> | ||
| 35 | </section> | ||
| 36 | |||
| 37 | <section> | ||
| 38 | <title>Programming</title> | ||
| 39 | |||
| 40 | <para>Radio devices may have a couple audio controls (as discussed | ||
| 41 | in <xref linkend="control" />) such as a volume control, possibly custom | ||
| 42 | controls. Further all radio devices have one tuner or modulator (these are | ||
| 43 | discussed in <xref linkend="tuner" />) with index number zero to select | ||
| 44 | the radio frequency and to determine if a monaural or FM stereo | ||
| 45 | program is received/emitted. Drivers switch automatically between AM and FM | ||
| 46 | depending on the selected frequency. The &VIDIOC-G-TUNER; or | ||
| 47 | &VIDIOC-G-MODULATOR; ioctl | ||
| 48 | reports the supported frequency range.</para> | ||
| 49 | </section> | ||
| 50 | |||
| 51 | <!-- | ||
| 52 | Local Variables: | ||
| 53 | mode: sgml | ||
| 54 | sgml-parent-document: "v4l2.sgml" | ||
| 55 | indent-tabs-mode: nil | ||
| 56 | End: | ||
| 57 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-raw-vbi.xml b/Documentation/DocBook/v4l/dev-raw-vbi.xml new file mode 100644 index 000000000000..c5a70bdfaf27 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-raw-vbi.xml | |||
| @@ -0,0 +1,347 @@ | |||
| 1 | <title>Raw VBI Data Interface</title> | ||
| 2 | |||
| 3 | <para>VBI is an abbreviation of Vertical Blanking Interval, a gap | ||
| 4 | in the sequence of lines of an analog video signal. During VBI | ||
| 5 | no picture information is transmitted, allowing some time while the | ||
| 6 | electron beam of a cathode ray tube TV returns to the top of the | ||
| 7 | screen. Using an oscilloscope you will find here the vertical | ||
| 8 | synchronization pulses and short data packages ASK | ||
| 9 | modulated<footnote><para>ASK: Amplitude-Shift Keying. A high signal | ||
| 10 | level represents a '1' bit, a low level a '0' bit.</para></footnote> | ||
| 11 | onto the video signal. These are transmissions of services such as | ||
| 12 | Teletext or Closed Caption.</para> | ||
| 13 | |||
| 14 | <para>Subject of this interface type is raw VBI data, as sampled off | ||
| 15 | a video signal, or to be added to a signal for output. | ||
| 16 | The data format is similar to uncompressed video images, a number of | ||
| 17 | lines times a number of samples per line, we call this a VBI image.</para> | ||
| 18 | |||
| 19 | <para>Conventionally V4L2 VBI devices are accessed through character | ||
| 20 | device special files named <filename>/dev/vbi</filename> and | ||
| 21 | <filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> with | ||
| 22 | major number 81 and minor numbers 224 to 255. | ||
| 23 | <filename>/dev/vbi</filename> is typically a symbolic link to the | ||
| 24 | preferred VBI device. This convention applies to both input and output | ||
| 25 | devices.</para> | ||
| 26 | |||
| 27 | <para>To address the problems of finding related video and VBI | ||
| 28 | devices VBI capturing and output is also available as device function | ||
| 29 | under <filename>/dev/video</filename>. To capture or output raw VBI | ||
| 30 | data with these devices applications must call the &VIDIOC-S-FMT; | ||
| 31 | ioctl. Accessed as <filename>/dev/vbi</filename>, raw VBI capturing | ||
| 32 | or output is the default device function.</para> | ||
| 33 | |||
| 34 | <section> | ||
| 35 | <title>Querying Capabilities</title> | ||
| 36 | |||
| 37 | <para>Devices supporting the raw VBI capturing or output API set | ||
| 38 | the <constant>V4L2_CAP_VBI_CAPTURE</constant> or | ||
| 39 | <constant>V4L2_CAP_VBI_OUTPUT</constant> flags, respectively, in the | ||
| 40 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 41 | returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the | ||
| 42 | read/write, streaming or asynchronous I/O methods must be | ||
| 43 | supported. VBI devices may or may not have a tuner or modulator.</para> | ||
| 44 | </section> | ||
| 45 | |||
| 46 | <section> | ||
| 47 | <title>Supplemental Functions</title> | ||
| 48 | |||
| 49 | <para>VBI devices shall support <link linkend="video">video | ||
| 50 | input or output</link>, <link linkend="tuner">tuner or | ||
| 51 | modulator</link>, and <link linkend="control">controls</link> ioctls | ||
| 52 | as needed. The <link linkend="standard">video standard</link> ioctls provide | ||
| 53 | information vital to program a VBI device, therefore must be | ||
| 54 | supported.</para> | ||
| 55 | </section> | ||
| 56 | |||
| 57 | <section> | ||
| 58 | <title>Raw VBI Format Negotiation</title> | ||
| 59 | |||
| 60 | <para>Raw VBI sampling abilities can vary, in particular the | ||
| 61 | sampling frequency. To properly interpret the data V4L2 specifies an | ||
| 62 | ioctl to query the sampling parameters. Moreover, to allow for some | ||
| 63 | flexibility applications can also suggest different parameters.</para> | ||
| 64 | |||
| 65 | <para>As usual these parameters are <emphasis>not</emphasis> | ||
| 66 | reset at &func-open; time to permit Unix tool chains, programming a | ||
| 67 | device and then reading from it as if it was a plain file. Well | ||
| 68 | written V4L2 applications should always ensure they really get what | ||
| 69 | they want, requesting reasonable parameters and then checking if the | ||
| 70 | actual parameters are suitable.</para> | ||
| 71 | |||
| 72 | <para>To query the current raw VBI capture parameters | ||
| 73 | applications set the <structfield>type</structfield> field of a | ||
| 74 | &v4l2-format; to <constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant> or | ||
| 75 | <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>, and call the | ||
| 76 | &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill | ||
| 77 | the &v4l2-vbi-format; <structfield>vbi</structfield> member of the | ||
| 78 | <structfield>fmt</structfield> union.</para> | ||
| 79 | |||
| 80 | <para>To request different parameters applications set the | ||
| 81 | <structfield>type</structfield> field of a &v4l2-format; as above and | ||
| 82 | initialize all fields of the &v4l2-vbi-format; | ||
| 83 | <structfield>vbi</structfield> member of the | ||
| 84 | <structfield>fmt</structfield> union, or better just modify the | ||
| 85 | results of <constant>VIDIOC_G_FMT</constant>, and call the | ||
| 86 | &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers return | ||
| 87 | an &EINVAL; only when the given parameters are ambiguous, otherwise | ||
| 88 | they modify the parameters according to the hardware capabilites and | ||
| 89 | return the actual parameters. When the driver allocates resources at | ||
| 90 | this point, it may return an &EBUSY; to indicate the returned | ||
| 91 | parameters are valid but the required resources are currently not | ||
| 92 | available. That may happen for instance when the video and VBI areas | ||
| 93 | to capture would overlap, or when the driver supports multiple opens | ||
| 94 | and another process already requested VBI capturing or output. Anyway, | ||
| 95 | applications must expect other resource allocation points which may | ||
| 96 | return <errorcode>EBUSY</errorcode>, at the &VIDIOC-STREAMON; ioctl | ||
| 97 | and the first read(), write() and select() call.</para> | ||
| 98 | |||
| 99 | <para>VBI devices must implement both the | ||
| 100 | <constant>VIDIOC_G_FMT</constant> and | ||
| 101 | <constant>VIDIOC_S_FMT</constant> ioctl, even if | ||
| 102 | <constant>VIDIOC_S_FMT</constant> ignores all requests and always | ||
| 103 | returns default parameters as <constant>VIDIOC_G_FMT</constant> does. | ||
| 104 | <constant>VIDIOC_TRY_FMT</constant> is optional.</para> | ||
| 105 | |||
| 106 | <table pgwide="1" frame="none" id="v4l2-vbi-format"> | ||
| 107 | <title>struct <structname>v4l2_vbi_format</structname></title> | ||
| 108 | <tgroup cols="3"> | ||
| 109 | &cs-str; | ||
| 110 | <tbody valign="top"> | ||
| 111 | <row> | ||
| 112 | <entry>__u32</entry> | ||
| 113 | <entry><structfield>sampling_rate</structfield></entry> | ||
| 114 | <entry>Samples per second, i. e. unit 1 Hz.</entry> | ||
| 115 | </row> | ||
| 116 | <row> | ||
| 117 | <entry>__u32</entry> | ||
| 118 | <entry><structfield>offset</structfield></entry> | ||
| 119 | <entry><para>Horizontal offset of the VBI image, | ||
| 120 | relative to the leading edge of the line synchronization pulse and | ||
| 121 | counted in samples: The first sample in the VBI image will be located | ||
| 122 | <structfield>offset</structfield> / | ||
| 123 | <structfield>sampling_rate</structfield> seconds following the leading | ||
| 124 | edge. See also <xref linkend="vbi-hsync" />.</para></entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry>__u32</entry> | ||
| 128 | <entry><structfield>samples_per_line</structfield></entry> | ||
| 129 | <entry></entry> | ||
| 130 | </row> | ||
| 131 | <row> | ||
| 132 | <entry>__u32</entry> | ||
| 133 | <entry><structfield>sample_format</structfield></entry> | ||
| 134 | <entry><para>Defines the sample format as in <xref | ||
| 135 | linkend="pixfmt" />, a four-character-code.<footnote> | ||
| 136 | <para>A few devices may be unable to | ||
| 137 | sample VBI data at all but can extend the video capture window to the | ||
| 138 | VBI region.</para> | ||
| 139 | </footnote> Usually this is | ||
| 140 | <constant>V4L2_PIX_FMT_GREY</constant>, i. e. each sample | ||
| 141 | consists of 8 bits with lower values oriented towards the black level. | ||
| 142 | Do not assume any other correlation of values with the signal level. | ||
| 143 | For example, the MSB does not necessarily indicate if the signal is | ||
| 144 | 'high' or 'low' because 128 may not be the mean value of the | ||
| 145 | signal. Drivers shall not convert the sample format by software.</para></entry> | ||
| 146 | </row> | ||
| 147 | <row> | ||
| 148 | <entry>__u32</entry> | ||
| 149 | <entry><structfield>start</structfield>[2]</entry> | ||
| 150 | <entry>This is the scanning system line number | ||
| 151 | associated with the first line of the VBI image, of the first and the | ||
| 152 | second field respectively. See <xref linkend="vbi-525" /> and | ||
| 153 | <xref linkend="vbi-625" /> for valid values. VBI input drivers can | ||
| 154 | return start values 0 if the hardware cannot reliable identify | ||
| 155 | scanning lines, VBI acquisition may not require this | ||
| 156 | information.</entry> | ||
| 157 | </row> | ||
| 158 | <row> | ||
| 159 | <entry>__u32</entry> | ||
| 160 | <entry><structfield>count</structfield>[2]</entry> | ||
| 161 | <entry>The number of lines in the first and second | ||
| 162 | field image, respectively.</entry> | ||
| 163 | </row> | ||
| 164 | <row> | ||
| 165 | <entry spanname="hspan"><para>Drivers should be as | ||
| 166 | flexibility as possible. For example, it may be possible to extend or | ||
| 167 | move the VBI capture window down to the picture area, implementing a | ||
| 168 | 'full field mode' to capture data service transmissions embedded in | ||
| 169 | the picture.</para><para>An application can set the first or second | ||
| 170 | <structfield>count</structfield> value to zero if no data is required | ||
| 171 | from the respective field; <structfield>count</structfield>[1] if the | ||
| 172 | scanning system is progressive, &ie; not interlaced. The | ||
| 173 | corresponding start value shall be ignored by the application and | ||
| 174 | driver. Anyway, drivers may not support single field capturing and | ||
| 175 | return both count values non-zero.</para><para>Both | ||
| 176 | <structfield>count</structfield> values set to zero, or line numbers | ||
| 177 | outside the bounds depicted in <xref linkend="vbi-525" /> and <xref | ||
| 178 | linkend="vbi-625" />, or a field image covering | ||
| 179 | lines of two fields, are invalid and shall not be returned by the | ||
| 180 | driver.</para><para>To initialize the <structfield>start</structfield> | ||
| 181 | and <structfield>count</structfield> fields, applications must first | ||
| 182 | determine the current video standard selection. The &v4l2-std-id; or | ||
| 183 | the <structfield>framelines</structfield> field of &v4l2-standard; can | ||
| 184 | be evaluated for this purpose.</para></entry> | ||
| 185 | </row> | ||
| 186 | <row> | ||
| 187 | <entry>__u32</entry> | ||
| 188 | <entry><structfield>flags</structfield></entry> | ||
| 189 | <entry>See <xref linkend="vbifmt-flags" /> below. Currently | ||
| 190 | only drivers set flags, applications must set this field to | ||
| 191 | zero.</entry> | ||
| 192 | </row> | ||
| 193 | <row> | ||
| 194 | <entry>__u32</entry> | ||
| 195 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 196 | <entry>This array is reserved for future extensions. | ||
| 197 | Drivers and applications must set it to zero.</entry> | ||
| 198 | </row> | ||
| 199 | </tbody> | ||
| 200 | </tgroup> | ||
| 201 | </table> | ||
| 202 | |||
| 203 | <table pgwide="1" frame="none" id="vbifmt-flags"> | ||
| 204 | <title>Raw VBI Format Flags</title> | ||
| 205 | <tgroup cols="3"> | ||
| 206 | &cs-def; | ||
| 207 | <tbody valign="top"> | ||
| 208 | <row> | ||
| 209 | <entry><constant>V4L2_VBI_UNSYNC</constant></entry> | ||
| 210 | <entry>0x0001</entry> | ||
| 211 | <entry><para>This flag indicates hardware which does not | ||
| 212 | properly distinguish between fields. Normally the VBI image stores the | ||
| 213 | first field (lower scanning line numbers) first in memory. This may be | ||
| 214 | a top or bottom field depending on the video standard. When this flag | ||
| 215 | is set the first or second field may be stored first, however the | ||
| 216 | fields are still in correct temporal order with the older field first | ||
| 217 | in memory.<footnote> | ||
| 218 | <para>Most VBI services transmit on both fields, but | ||
| 219 | some have different semantics depending on the field number. These | ||
| 220 | cannot be reliable decoded or encoded when | ||
| 221 | <constant>V4L2_VBI_UNSYNC</constant> is set.</para> | ||
| 222 | </footnote></para></entry> | ||
| 223 | </row> | ||
| 224 | <row> | ||
| 225 | <entry><constant>V4L2_VBI_INTERLACED</constant></entry> | ||
| 226 | <entry>0x0002</entry> | ||
| 227 | <entry>By default the two field images will be passed | ||
| 228 | sequentially; all lines of the first field followed by all lines of | ||
| 229 | the second field (compare <xref linkend="field-order" /> | ||
| 230 | <constant>V4L2_FIELD_SEQ_TB</constant> and | ||
| 231 | <constant>V4L2_FIELD_SEQ_BT</constant>, whether the top or bottom | ||
| 232 | field is first in memory depends on the video standard). When this | ||
| 233 | flag is set, the two fields are interlaced (cf. | ||
| 234 | <constant>V4L2_FIELD_INTERLACED</constant>). The first line of the | ||
| 235 | first field followed by the first line of the second field, then the | ||
| 236 | two second lines, and so on. Such a layout may be necessary when the | ||
| 237 | hardware has been programmed to capture or output interlaced video | ||
| 238 | images and is unable to separate the fields for VBI capturing at | ||
| 239 | the same time. For simplicity setting this flag implies that both | ||
| 240 | <structfield>count</structfield> values are equal and non-zero.</entry> | ||
| 241 | </row> | ||
| 242 | </tbody> | ||
| 243 | </tgroup> | ||
| 244 | </table> | ||
| 245 | |||
| 246 | <figure id="vbi-hsync"> | ||
| 247 | <title>Line synchronization</title> | ||
| 248 | <mediaobject> | ||
| 249 | <imageobject> | ||
| 250 | <imagedata fileref="vbi_hsync.pdf" format="PS" /> | ||
| 251 | </imageobject> | ||
| 252 | <imageobject> | ||
| 253 | <imagedata fileref="vbi_hsync.gif" format="GIF" /> | ||
| 254 | </imageobject> | ||
| 255 | <textobject> | ||
| 256 | <phrase>Line synchronization diagram</phrase> | ||
| 257 | </textobject> | ||
| 258 | </mediaobject> | ||
| 259 | </figure> | ||
| 260 | |||
| 261 | <figure id="vbi-525"> | ||
| 262 | <title>ITU-R 525 line numbering (M/NTSC and M/PAL)</title> | ||
| 263 | <mediaobject> | ||
| 264 | <imageobject> | ||
| 265 | <imagedata fileref="vbi_525.pdf" format="PS" /> | ||
| 266 | </imageobject> | ||
| 267 | <imageobject> | ||
| 268 | <imagedata fileref="vbi_525.gif" format="GIF" /> | ||
| 269 | </imageobject> | ||
| 270 | <textobject> | ||
| 271 | <phrase>NTSC field synchronization diagram</phrase> | ||
| 272 | </textobject> | ||
| 273 | <caption> | ||
| 274 | <para>(1) For the purpose of this specification field 2 | ||
| 275 | starts in line 264 and not 263.5 because half line capturing is not | ||
| 276 | supported.</para> | ||
| 277 | </caption> | ||
| 278 | </mediaobject> | ||
| 279 | </figure> | ||
| 280 | |||
| 281 | <figure id="vbi-625"> | ||
| 282 | <title>ITU-R 625 line numbering</title> | ||
| 283 | <mediaobject> | ||
| 284 | <imageobject> | ||
| 285 | <imagedata fileref="vbi_625.pdf" format="PS" /> | ||
| 286 | </imageobject> | ||
| 287 | <imageobject> | ||
| 288 | <imagedata fileref="vbi_625.gif" format="GIF" /> | ||
| 289 | </imageobject> | ||
| 290 | <textobject> | ||
| 291 | <phrase>PAL/SECAM field synchronization diagram</phrase> | ||
| 292 | </textobject> | ||
| 293 | <caption> | ||
| 294 | <para>(1) For the purpose of this specification field 2 | ||
| 295 | starts in line 314 and not 313.5 because half line capturing is not | ||
| 296 | supported.</para> | ||
| 297 | </caption> | ||
| 298 | </mediaobject> | ||
| 299 | </figure> | ||
| 300 | |||
| 301 | <para>Remember the VBI image format depends on the selected | ||
| 302 | video standard, therefore the application must choose a new standard or | ||
| 303 | query the current standard first. Attempts to read or write data ahead | ||
| 304 | of format negotiation, or after switching the video standard which may | ||
| 305 | invalidate the negotiated VBI parameters, should be refused by the | ||
| 306 | driver. A format change during active I/O is not permitted.</para> | ||
| 307 | </section> | ||
| 308 | |||
| 309 | <section> | ||
| 310 | <title>Reading and writing VBI images</title> | ||
| 311 | |||
| 312 | <para>To assure synchronization with the field number and easier | ||
| 313 | implementation, the smallest unit of data passed at a time is one | ||
| 314 | frame, consisting of two fields of VBI images immediately following in | ||
| 315 | memory.</para> | ||
| 316 | |||
| 317 | <para>The total size of a frame computes as follows:</para> | ||
| 318 | |||
| 319 | <programlisting> | ||
| 320 | (<structfield>count</structfield>[0] + <structfield>count</structfield>[1]) * | ||
| 321 | <structfield>samples_per_line</structfield> * sample size in bytes</programlisting> | ||
| 322 | |||
| 323 | <para>The sample size is most likely always one byte, | ||
| 324 | applications must check the <structfield>sample_format</structfield> | ||
| 325 | field though, to function properly with other drivers.</para> | ||
| 326 | |||
| 327 | <para>A VBI device may support <link | ||
| 328 | linkend="rw">read/write</link> and/or streaming (<link | ||
| 329 | linkend="mmap">memory mapping</link> or <link | ||
| 330 | linkend="userp">user pointer</link>) I/O. The latter bears the | ||
| 331 | possibility of synchronizing video and | ||
| 332 | VBI data by using buffer timestamps.</para> | ||
| 333 | |||
| 334 | <para>Remember the &VIDIOC-STREAMON; ioctl and the first read(), | ||
| 335 | write() and select() call can be resource allocation points returning | ||
| 336 | an &EBUSY; if the required hardware resources are temporarily | ||
| 337 | unavailable, for example the device is already in use by another | ||
| 338 | process.</para> | ||
| 339 | </section> | ||
| 340 | |||
| 341 | <!-- | ||
| 342 | Local Variables: | ||
| 343 | mode: sgml | ||
| 344 | sgml-parent-document: "v4l2.sgml" | ||
| 345 | indent-tabs-mode: nil | ||
| 346 | End: | ||
| 347 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-rds.xml b/Documentation/DocBook/v4l/dev-rds.xml new file mode 100644 index 000000000000..0869d701b1e5 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-rds.xml | |||
| @@ -0,0 +1,168 @@ | |||
| 1 | <title>RDS Interface</title> | ||
| 2 | |||
| 3 | <para>The Radio Data System transmits supplementary | ||
| 4 | information in binary format, for example the station name or travel | ||
| 5 | information, on an inaudible audio subcarrier of a radio program. This | ||
| 6 | interface is aimed at devices capable of receiving and decoding RDS | ||
| 7 | information.</para> | ||
| 8 | |||
| 9 | <para>For more information see the core RDS standard <xref linkend="en50067" /> | ||
| 10 | and the RBDS standard <xref linkend="nrsc4" />.</para> | ||
| 11 | |||
| 12 | <para>Note that the RBDS standard as is used in the USA is almost identical | ||
| 13 | to the RDS standard. Any RDS decoder can also handle RBDS. Only some of the fields | ||
| 14 | have slightly different meanings. See the RBDS standard for more information.</para> | ||
| 15 | |||
| 16 | <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search). | ||
| 17 | This is a proprietary format which seems to be discontinued. The RDS interface does not | ||
| 18 | support this format. Should support for MMBS (or the so-called 'E blocks' in general) | ||
| 19 | be needed, then please contact the linux-media mailing list: &v4l-ml;.</para> | ||
| 20 | |||
| 21 | <section> | ||
| 22 | <title>Querying Capabilities</title> | ||
| 23 | |||
| 24 | <para>Devices supporting the RDS capturing API | ||
| 25 | set the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in | ||
| 26 | the <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 27 | returned by the &VIDIOC-QUERYCAP; ioctl. | ||
| 28 | Any tuner that supports RDS will set the | ||
| 29 | <constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> | ||
| 30 | field of &v4l2-tuner;. | ||
| 31 | Whether an RDS signal is present can be detected by looking at | ||
| 32 | the <structfield>rxsubchans</structfield> field of &v4l2-tuner;: the | ||
| 33 | <constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data was detected.</para> | ||
| 34 | |||
| 35 | <para>Devices supporting the RDS output API | ||
| 36 | set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in | ||
| 37 | the <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 38 | returned by the &VIDIOC-QUERYCAP; ioctl. | ||
| 39 | Any modulator that supports RDS will set the | ||
| 40 | <constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> | ||
| 41 | field of &v4l2-modulator;. | ||
| 42 | In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant> | ||
| 43 | bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.</para> | ||
| 44 | |||
| 45 | </section> | ||
| 46 | |||
| 47 | <section> | ||
| 48 | <title>Reading RDS data</title> | ||
| 49 | |||
| 50 | <para>RDS data can be read from the radio device | ||
| 51 | with the &func-read; function. The data is packed in groups of three bytes, | ||
| 52 | as follows:</para> | ||
| 53 | <table frame="none" pgwide="1" id="v4l2-rds-data"> | ||
| 54 | <title>struct | ||
| 55 | <structname>v4l2_rds_data</structname></title> | ||
| 56 | <tgroup cols="3"> | ||
| 57 | <colspec colname="c1" colwidth="1*" /> | ||
| 58 | <colspec colname="c2" colwidth="1*" /> | ||
| 59 | <colspec colname="c3" colwidth="5*" /> | ||
| 60 | <tbody valign="top"> | ||
| 61 | <row> | ||
| 62 | <entry>__u8</entry> | ||
| 63 | <entry><structfield>lsb</structfield></entry> | ||
| 64 | <entry>Least Significant Byte of RDS Block</entry> | ||
| 65 | </row> | ||
| 66 | <row> | ||
| 67 | <entry>__u8</entry> | ||
| 68 | <entry><structfield>msb</structfield></entry> | ||
| 69 | <entry>Most Significant Byte of RDS Block</entry> | ||
| 70 | </row> | ||
| 71 | <row> | ||
| 72 | <entry>__u8</entry> | ||
| 73 | <entry><structfield>block</structfield></entry> | ||
| 74 | <entry>Block description</entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </table> | ||
| 79 | <table frame="none" pgwide="1" id="v4l2-rds-block"> | ||
| 80 | <title>Block description</title> | ||
| 81 | <tgroup cols="2"> | ||
| 82 | <colspec colname="c1" colwidth="1*" /> | ||
| 83 | <colspec colname="c2" colwidth="5*" /> | ||
| 84 | <tbody valign="top"> | ||
| 85 | <row> | ||
| 86 | <entry>Bits 0-2</entry> | ||
| 87 | <entry>Block (aka offset) of the received data.</entry> | ||
| 88 | </row> | ||
| 89 | <row> | ||
| 90 | <entry>Bits 3-5</entry> | ||
| 91 | <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>Bit 6</entry> | ||
| 95 | <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry> | ||
| 96 | </row> | ||
| 97 | <row> | ||
| 98 | <entry>Bit 7</entry> | ||
| 99 | <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry> | ||
| 100 | </row> | ||
| 101 | </tbody> | ||
| 102 | </tgroup> | ||
| 103 | </table> | ||
| 104 | |||
| 105 | <table frame="none" pgwide="1" id="v4l2-rds-block-codes"> | ||
| 106 | <title>Block defines</title> | ||
| 107 | <tgroup cols="3"> | ||
| 108 | <colspec colname="c1" colwidth="1*" /> | ||
| 109 | <colspec colname="c2" colwidth="1*" /> | ||
| 110 | <colspec colname="c3" colwidth="5*" /> | ||
| 111 | <tbody valign="top"> | ||
| 112 | <row> | ||
| 113 | <entry>V4L2_RDS_BLOCK_MSK</entry> | ||
| 114 | <entry>7</entry> | ||
| 115 | <entry>Mask for bits 0-2 to get the block ID.</entry> | ||
| 116 | </row> | ||
| 117 | <row> | ||
| 118 | <entry>V4L2_RDS_BLOCK_A</entry> | ||
| 119 | <entry>0</entry> | ||
| 120 | <entry>Block A.</entry> | ||
| 121 | </row> | ||
| 122 | <row> | ||
| 123 | <entry>V4L2_RDS_BLOCK_B</entry> | ||
| 124 | <entry>1</entry> | ||
| 125 | <entry>Block B.</entry> | ||
| 126 | </row> | ||
| 127 | <row> | ||
| 128 | <entry>V4L2_RDS_BLOCK_C</entry> | ||
| 129 | <entry>2</entry> | ||
| 130 | <entry>Block C.</entry> | ||
| 131 | </row> | ||
| 132 | <row> | ||
| 133 | <entry>V4L2_RDS_BLOCK_D</entry> | ||
| 134 | <entry>3</entry> | ||
| 135 | <entry>Block D.</entry> | ||
| 136 | </row> | ||
| 137 | <row> | ||
| 138 | <entry>V4L2_RDS_BLOCK_C_ALT</entry> | ||
| 139 | <entry>4</entry> | ||
| 140 | <entry>Block C'.</entry> | ||
| 141 | </row> | ||
| 142 | <row> | ||
| 143 | <entry>V4L2_RDS_BLOCK_INVALID</entry> | ||
| 144 | <entry>7</entry> | ||
| 145 | <entry>An invalid block.</entry> | ||
| 146 | </row> | ||
| 147 | <row> | ||
| 148 | <entry>V4L2_RDS_BLOCK_CORRECTED</entry> | ||
| 149 | <entry>0x40</entry> | ||
| 150 | <entry>A bit error was detected but corrected.</entry> | ||
| 151 | </row> | ||
| 152 | <row> | ||
| 153 | <entry>V4L2_RDS_BLOCK_ERROR</entry> | ||
| 154 | <entry>0x80</entry> | ||
| 155 | <entry>An incorrectable error occurred.</entry> | ||
| 156 | </row> | ||
| 157 | </tbody> | ||
| 158 | </tgroup> | ||
| 159 | </table> | ||
| 160 | </section> | ||
| 161 | |||
| 162 | <!-- | ||
| 163 | Local Variables: | ||
| 164 | mode: sgml | ||
| 165 | sgml-parent-document: "v4l2.sgml" | ||
| 166 | indent-tabs-mode: nil | ||
| 167 | End: | ||
| 168 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/v4l/dev-sliced-vbi.xml new file mode 100644 index 000000000000..69e789fa7f7b --- /dev/null +++ b/Documentation/DocBook/v4l/dev-sliced-vbi.xml | |||
| @@ -0,0 +1,708 @@ | |||
| 1 | <title>Sliced VBI Data Interface</title> | ||
| 2 | |||
| 3 | <para>VBI stands for Vertical Blanking Interval, a gap in the | ||
| 4 | sequence of lines of an analog video signal. During VBI no picture | ||
| 5 | information is transmitted, allowing some time while the electron beam | ||
| 6 | of a cathode ray tube TV returns to the top of the screen.</para> | ||
| 7 | |||
| 8 | <para>Sliced VBI devices use hardware to demodulate data transmitted | ||
| 9 | in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by | ||
| 10 | software, see also the <link linkend="raw-vbi">raw VBI | ||
| 11 | interface</link>. The data is passed as short packets of fixed size, | ||
| 12 | covering one scan line each. The number of packets per video frame is | ||
| 13 | variable.</para> | ||
| 14 | |||
| 15 | <para>Sliced VBI capture and output devices are accessed through the | ||
| 16 | same character special files as raw VBI devices. When a driver | ||
| 17 | supports both interfaces, the default function of a | ||
| 18 | <filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI | ||
| 19 | capturing or output, and the sliced VBI function is only available | ||
| 20 | after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a | ||
| 21 | <filename>/dev/video</filename> device may support the sliced VBI API, | ||
| 22 | however the default function here is video capturing or output. | ||
| 23 | Different file descriptors must be used to pass raw and sliced VBI | ||
| 24 | data simultaneously, if this is supported by the driver.</para> | ||
| 25 | |||
| 26 | <section> | ||
| 27 | <title>Querying Capabilities</title> | ||
| 28 | |||
| 29 | <para>Devices supporting the sliced VBI capturing or output API | ||
| 30 | set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or | ||
| 31 | <constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in | ||
| 32 | the <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 33 | returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the | ||
| 34 | read/write, streaming or asynchronous <link linkend="io">I/O | ||
| 35 | methods</link> must be supported. Sliced VBI devices may have a tuner | ||
| 36 | or modulator.</para> | ||
| 37 | </section> | ||
| 38 | |||
| 39 | <section> | ||
| 40 | <title>Supplemental Functions</title> | ||
| 41 | |||
| 42 | <para>Sliced VBI devices shall support <link linkend="video">video | ||
| 43 | input or output</link> and <link linkend="tuner">tuner or | ||
| 44 | modulator</link> ioctls if they have these capabilities, and they may | ||
| 45 | support <link linkend="control">control</link> ioctls. The <link | ||
| 46 | linkend="standard">video standard</link> ioctls provide information | ||
| 47 | vital to program a sliced VBI device, therefore must be | ||
| 48 | supported.</para> | ||
| 49 | </section> | ||
| 50 | |||
| 51 | <section id="sliced-vbi-format-negotitation"> | ||
| 52 | <title>Sliced VBI Format Negotiation</title> | ||
| 53 | |||
| 54 | <para>To find out which data services are supported by the | ||
| 55 | hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl. | ||
| 56 | All drivers implementing the sliced VBI interface must support this | ||
| 57 | ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl | ||
| 58 | when the number of VBI lines the hardware can capture or output per | ||
| 59 | frame, or the number of services it can identify on a given line are | ||
| 60 | limited. For example on PAL line 16 the hardware may be able to look | ||
| 61 | for a VPS or Teletext signal, but not both at the same time.</para> | ||
| 62 | |||
| 63 | <para>To determine the currently selected services applications | ||
| 64 | set the <structfield>type </structfield> field of &v4l2-format; to | ||
| 65 | <constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant> | ||
| 66 | V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT; | ||
| 67 | ioctl fills the <structfield>fmt.sliced</structfield> member, a | ||
| 68 | &v4l2-sliced-vbi-format;.</para> | ||
| 69 | |||
| 70 | <para>Applications can request different parameters by | ||
| 71 | initializing or modifying the <structfield>fmt.sliced</structfield> | ||
| 72 | member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the | ||
| 73 | <structname>v4l2_format</structname> structure.</para> | ||
| 74 | |||
| 75 | <para>The sliced VBI API is more complicated than the raw VBI API | ||
| 76 | because the hardware must be told which VBI service to expect on each | ||
| 77 | scan line. Not all services may be supported by the hardware on all | ||
| 78 | lines (this is especially true for VBI output where Teletext is often | ||
| 79 | unsupported and other services can only be inserted in one specific | ||
| 80 | line). In many cases, however, it is sufficient to just set the | ||
| 81 | <structfield>service_set</structfield> field to the required services | ||
| 82 | and let the driver fill the <structfield>service_lines</structfield> | ||
| 83 | array according to hardware capabilities. Only if more precise control | ||
| 84 | is needed should the programmer set the | ||
| 85 | <structfield>service_lines</structfield> array explicitly.</para> | ||
| 86 | |||
| 87 | <para>The &VIDIOC-S-FMT; ioctl modifies the parameters | ||
| 88 | according to hardware capabilities. When the driver allocates | ||
| 89 | resources at this point, it may return an &EBUSY; if the required | ||
| 90 | resources are temporarily unavailable. Other resource allocation | ||
| 91 | points which may return <errorcode>EBUSY</errorcode> can be the | ||
| 92 | &VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and | ||
| 93 | &func-select; call.</para> | ||
| 94 | |||
| 95 | <table frame="none" pgwide="1" id="v4l2-sliced-vbi-format"> | ||
| 96 | <title>struct | ||
| 97 | <structname>v4l2_sliced_vbi_format</structname></title> | ||
| 98 | <tgroup cols="5"> | ||
| 99 | <colspec colname="c1" colwidth="3*" /> | ||
| 100 | <colspec colname="c2" colwidth="3*" /> | ||
| 101 | <colspec colname="c3" colwidth="2*" /> | ||
| 102 | <colspec colname="c4" colwidth="2*" /> | ||
| 103 | <colspec colname="c5" colwidth="2*" /> | ||
| 104 | <spanspec namest="c3" nameend="c5" spanname="hspan" /> | ||
| 105 | <tbody valign="top"> | ||
| 106 | <row> | ||
| 107 | <entry>__u32</entry> | ||
| 108 | <entry><structfield>service_set</structfield></entry> | ||
| 109 | <entry spanname="hspan"><para>If | ||
| 110 | <structfield>service_set</structfield> is non-zero when passed with | ||
| 111 | &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the | ||
| 112 | <structfield>service_lines</structfield> array will be filled by the | ||
| 113 | driver according to the services specified in this field. For example, | ||
| 114 | if <structfield>service_set</structfield> is initialized with | ||
| 115 | <constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a | ||
| 116 | driver for the cx25840 video decoder sets lines 7-22 of both | ||
| 117 | fields<footnote><para>According to <link | ||
| 118 | linkend="ets300706">ETS 300 706</link> lines 6-22 of the | ||
| 119 | first field and lines 5-22 of the second field may carry Teletext | ||
| 120 | data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant> | ||
| 121 | and line 23 of the first field to | ||
| 122 | <constant>V4L2_SLICED_WSS_625</constant>. If | ||
| 123 | <structfield>service_set</structfield> is set to zero, then the values | ||
| 124 | of <structfield>service_lines</structfield> will be used instead. | ||
| 125 | </para><para>On return the driver sets this field to the union of all | ||
| 126 | elements of the returned <structfield>service_lines</structfield> | ||
| 127 | array. It may contain less services than requested, perhaps just one, | ||
| 128 | if the hardware cannot handle more services simultaneously. It may be | ||
| 129 | empty (zero) if none of the requested services are supported by the | ||
| 130 | hardware.</para></entry> | ||
| 131 | </row> | ||
| 132 | <row> | ||
| 133 | <entry>__u16</entry> | ||
| 134 | <entry><structfield>service_lines</structfield>[2][24]</entry> | ||
| 135 | <entry spanname="hspan"><para>Applications initialize this | ||
| 136 | array with sets of data services the driver shall look for or insert | ||
| 137 | on the respective scan line. Subject to hardware capabilities drivers | ||
| 138 | return the requested set, a subset, which may be just a single | ||
| 139 | service, or an empty set. When the hardware cannot handle multiple | ||
| 140 | services on the same line the driver shall choose one. No assumptions | ||
| 141 | can be made on which service the driver chooses.</para><para>Data | ||
| 142 | services are defined in <xref linkend="vbi-services2" />. Array indices | ||
| 143 | map to ITU-R line numbers (see also <xref linkend="vbi-525" /> and <xref | ||
| 144 | linkend="vbi-625" />) as follows: <!-- No nested | ||
| 145 | tables, sigh. --></para></entry> | ||
| 146 | </row> | ||
| 147 | <row> | ||
| 148 | <entry></entry> | ||
| 149 | <entry></entry> | ||
| 150 | <entry>Element</entry> | ||
| 151 | <entry>525 line systems</entry> | ||
| 152 | <entry>625 line systems</entry> | ||
| 153 | </row> | ||
| 154 | <row> | ||
| 155 | <entry></entry> | ||
| 156 | <entry></entry> | ||
| 157 | <entry><structfield>service_lines</structfield>[0][1]</entry> | ||
| 158 | <entry align="center">1</entry> | ||
| 159 | <entry align="center">1</entry> | ||
| 160 | </row> | ||
| 161 | <row> | ||
| 162 | <entry></entry> | ||
| 163 | <entry></entry> | ||
| 164 | <entry><structfield>service_lines</structfield>[0][23]</entry> | ||
| 165 | <entry align="center">23</entry> | ||
| 166 | <entry align="center">23</entry> | ||
| 167 | </row> | ||
| 168 | <row> | ||
| 169 | <entry></entry> | ||
| 170 | <entry></entry> | ||
| 171 | <entry><structfield>service_lines</structfield>[1][1]</entry> | ||
| 172 | <entry align="center">264</entry> | ||
| 173 | <entry align="center">314</entry> | ||
| 174 | </row> | ||
| 175 | <row> | ||
| 176 | <entry></entry> | ||
| 177 | <entry></entry> | ||
| 178 | <entry><structfield>service_lines</structfield>[1][23]</entry> | ||
| 179 | <entry align="center">286</entry> | ||
| 180 | <entry align="center">336</entry> | ||
| 181 | </row> | ||
| 182 | <!-- End of line numbers table. --> | ||
| 183 | <row> | ||
| 184 | <entry></entry> | ||
| 185 | <entry></entry> | ||
| 186 | <entry spanname="hspan">Drivers must set | ||
| 187 | <structfield>service_lines</structfield>[0][0] and | ||
| 188 | <structfield>service_lines</structfield>[1][0] to zero.</entry> | ||
| 189 | </row> | ||
| 190 | <row> | ||
| 191 | <entry>__u32</entry> | ||
| 192 | <entry><structfield>io_size</structfield></entry> | ||
| 193 | <entry spanname="hspan">Maximum number of bytes passed by | ||
| 194 | one &func-read; or &func-write; call, and the buffer size in bytes for | ||
| 195 | the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to | ||
| 196 | the size of &v4l2-sliced-vbi-data; times the number of non-zero | ||
| 197 | elements in the returned <structfield>service_lines</structfield> | ||
| 198 | array (that is the number of lines potentially carrying data).</entry> | ||
| 199 | </row> | ||
| 200 | <row> | ||
| 201 | <entry>__u32</entry> | ||
| 202 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 203 | <entry spanname="hspan">This array is reserved for future | ||
| 204 | extensions. Applications and drivers must set it to zero.</entry> | ||
| 205 | </row> | ||
| 206 | </tbody> | ||
| 207 | </tgroup> | ||
| 208 | </table> | ||
| 209 | |||
| 210 | <!-- See also vidioc-g-sliced-vbi-cap.sgml --> | ||
| 211 | <table frame="none" pgwide="1" id="vbi-services2"> | ||
| 212 | <title>Sliced VBI services</title> | ||
| 213 | <tgroup cols="5"> | ||
| 214 | <colspec colname="c1" colwidth="2*" /> | ||
| 215 | <colspec colname="c2" colwidth="1*" /> | ||
| 216 | <colspec colname="c3" colwidth="1*" /> | ||
| 217 | <colspec colname="c4" colwidth="2*" /> | ||
| 218 | <colspec colname="c5" colwidth="2*" /> | ||
| 219 | <spanspec namest="c3" nameend="c5" spanname="rlp" /> | ||
| 220 | <thead> | ||
| 221 | <row> | ||
| 222 | <entry>Symbol</entry> | ||
| 223 | <entry>Value</entry> | ||
| 224 | <entry>Reference</entry> | ||
| 225 | <entry>Lines, usually</entry> | ||
| 226 | <entry>Payload</entry> | ||
| 227 | </row> | ||
| 228 | </thead> | ||
| 229 | <tbody valign="top"> | ||
| 230 | <row> | ||
| 231 | <entry><constant>V4L2_SLICED_TELETEXT_B</constant> | ||
| 232 | (Teletext System B)</entry> | ||
| 233 | <entry>0x0001</entry> | ||
| 234 | <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry> | ||
| 235 | <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry> | ||
| 236 | <entry>Last 42 of the 45 byte Teletext packet, that is | ||
| 237 | without clock run-in and framing code, lsb first transmitted.</entry> | ||
| 238 | </row> | ||
| 239 | <row> | ||
| 240 | <entry><constant>V4L2_SLICED_VPS</constant></entry> | ||
| 241 | <entry>0x0400</entry> | ||
| 242 | <entry><xref linkend="ets300231" /></entry> | ||
| 243 | <entry>PAL line 16</entry> | ||
| 244 | <entry>Byte number 3 to 15 according to Figure 9 of | ||
| 245 | ETS 300 231, lsb first transmitted.</entry> | ||
| 246 | </row> | ||
| 247 | <row> | ||
| 248 | <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> | ||
| 249 | <entry>0x1000</entry> | ||
| 250 | <entry><xref linkend="eia608" /></entry> | ||
| 251 | <entry>NTSC line 21, 284 (second field 21)</entry> | ||
| 252 | <entry>Two bytes in transmission order, including parity | ||
| 253 | bit, lsb first transmitted.</entry> | ||
| 254 | </row> | ||
| 255 | <row> | ||
| 256 | <entry><constant>V4L2_SLICED_WSS_625</constant></entry> | ||
| 257 | <entry>0x4000</entry> | ||
| 258 | <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry> | ||
| 259 | <entry>PAL/SECAM line 23</entry> | ||
| 260 | <entry><screen> | ||
| 261 | Byte 0 1 | ||
| 262 | msb lsb msb lsb | ||
| 263 | Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 | ||
| 264 | </screen></entry> | ||
| 265 | </row> | ||
| 266 | <row> | ||
| 267 | <entry><constant>V4L2_SLICED_VBI_525</constant></entry> | ||
| 268 | <entry>0x1000</entry> | ||
| 269 | <entry spanname="rlp">Set of services applicable to 525 | ||
| 270 | line systems.</entry> | ||
| 271 | </row> | ||
| 272 | <row> | ||
| 273 | <entry><constant>V4L2_SLICED_VBI_625</constant></entry> | ||
| 274 | <entry>0x4401</entry> | ||
| 275 | <entry spanname="rlp">Set of services applicable to 625 | ||
| 276 | line systems.</entry> | ||
| 277 | </row> | ||
| 278 | </tbody> | ||
| 279 | </tgroup> | ||
| 280 | </table> | ||
| 281 | |||
| 282 | <para>Drivers may return an &EINVAL; when applications attempt to | ||
| 283 | read or write data without prior format negotiation, after switching | ||
| 284 | the video standard (which may invalidate the negotiated VBI | ||
| 285 | parameters) and after switching the video input (which may change the | ||
| 286 | video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return | ||
| 287 | an &EBUSY; when applications attempt to change the format while i/o is | ||
| 288 | in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call, | ||
| 289 | and after the first &func-read; or &func-write; call).</para> | ||
| 290 | </section> | ||
| 291 | |||
| 292 | <section> | ||
| 293 | <title>Reading and writing sliced VBI data</title> | ||
| 294 | |||
| 295 | <para>A single &func-read; or &func-write; call must pass all data | ||
| 296 | belonging to one video frame. That is an array of | ||
| 297 | <structname>v4l2_sliced_vbi_data</structname> structures with one or | ||
| 298 | more elements and a total size not exceeding | ||
| 299 | <structfield>io_size</structfield> bytes. Likewise in streaming I/O | ||
| 300 | mode one buffer of <structfield>io_size</structfield> bytes must | ||
| 301 | contain data of one video frame. The <structfield>id</structfield> of | ||
| 302 | unused <structname>v4l2_sliced_vbi_data</structname> elements must be | ||
| 303 | zero.</para> | ||
| 304 | |||
| 305 | <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data"> | ||
| 306 | <title>struct | ||
| 307 | <structname>v4l2_sliced_vbi_data</structname></title> | ||
| 308 | <tgroup cols="3"> | ||
| 309 | &cs-def; | ||
| 310 | <tbody valign="top"> | ||
| 311 | <row> | ||
| 312 | <entry>__u32</entry> | ||
| 313 | <entry><structfield>id</structfield></entry> | ||
| 314 | <entry>A flag from <xref linkend="vbi-services" /> | ||
| 315 | identifying the type of data in this packet. Only a single bit must be | ||
| 316 | set. When the <structfield>id</structfield> of a captured packet is | ||
| 317 | zero, the packet is empty and the contents of other fields are | ||
| 318 | undefined. Applications shall ignore empty packets. When the | ||
| 319 | <structfield>id</structfield> of a packet for output is zero the | ||
| 320 | contents of the <structfield>data</structfield> field are undefined | ||
| 321 | and the driver must no longer insert data on the requested | ||
| 322 | <structfield>field</structfield> and | ||
| 323 | <structfield>line</structfield>.</entry> | ||
| 324 | </row> | ||
| 325 | <row> | ||
| 326 | <entry>__u32</entry> | ||
| 327 | <entry><structfield>field</structfield></entry> | ||
| 328 | <entry>The video field number this data has been captured | ||
| 329 | from, or shall be inserted at. <constant>0</constant> for the first | ||
| 330 | field, <constant>1</constant> for the second field.</entry> | ||
| 331 | </row> | ||
| 332 | <row> | ||
| 333 | <entry>__u32</entry> | ||
| 334 | <entry><structfield>line</structfield></entry> | ||
| 335 | <entry>The field (as opposed to frame) line number this | ||
| 336 | data has been captured from, or shall be inserted at. See <xref | ||
| 337 | linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid | ||
| 338 | values. Sliced VBI capture devices can set the line number of all | ||
| 339 | packets to <constant>0</constant> if the hardware cannot reliably | ||
| 340 | identify scan lines. The field number must always be valid.</entry> | ||
| 341 | </row> | ||
| 342 | <row> | ||
| 343 | <entry>__u32</entry> | ||
| 344 | <entry><structfield>reserved</structfield></entry> | ||
| 345 | <entry>This field is reserved for future extensions. | ||
| 346 | Applications and drivers must set it to zero.</entry> | ||
| 347 | </row> | ||
| 348 | <row> | ||
| 349 | <entry>__u8</entry> | ||
| 350 | <entry><structfield>data</structfield>[48]</entry> | ||
| 351 | <entry>The packet payload. See <xref | ||
| 352 | linkend="vbi-services" /> for the contents and number of | ||
| 353 | bytes passed for each data type. The contents of padding bytes at the | ||
| 354 | end of this array are undefined, drivers and applications shall ignore | ||
| 355 | them.</entry> | ||
| 356 | </row> | ||
| 357 | </tbody> | ||
| 358 | </tgroup> | ||
| 359 | </table> | ||
| 360 | |||
| 361 | <para>Packets are always passed in ascending line number order, | ||
| 362 | without duplicate line numbers. The &func-write; function and the | ||
| 363 | &VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate | ||
| 364 | this rule. They must also return an &EINVAL; when applications pass an | ||
| 365 | incorrect field or line number, or a combination of | ||
| 366 | <structfield>field</structfield>, <structfield>line</structfield> and | ||
| 367 | <structfield>id</structfield> which has not been negotiated with the | ||
| 368 | &VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are | ||
| 369 | unknown the driver must pass the packets in transmitted order. The | ||
| 370 | driver can insert empty packets with <structfield>id</structfield> set | ||
| 371 | to zero anywhere in the packet array.</para> | ||
| 372 | |||
| 373 | <para>To assure synchronization and to distinguish from frame | ||
| 374 | dropping, when a captured frame does not carry any of the requested | ||
| 375 | data services drivers must pass one or more empty packets. When an | ||
| 376 | application fails to pass VBI data in time for output, the driver | ||
| 377 | must output the last VPS and WSS packet again, and disable the output | ||
| 378 | of Closed Caption and Teletext data, or output data which is ignored | ||
| 379 | by Closed Caption and Teletext decoders.</para> | ||
| 380 | |||
| 381 | <para>A sliced VBI device may support <link | ||
| 382 | linkend="rw">read/write</link> and/or streaming (<link | ||
| 383 | linkend="mmap">memory mapping</link> and/or <link linkend="userp">user | ||
| 384 | pointer</link>) I/O. The latter bears the possibility of synchronizing | ||
| 385 | video and VBI data by using buffer timestamps.</para> | ||
| 386 | |||
| 387 | </section> | ||
| 388 | |||
| 389 | <section> | ||
| 390 | <title>Sliced VBI Data in MPEG Streams</title> | ||
| 391 | |||
| 392 | <para>If a device can produce an MPEG output stream, it may be | ||
| 393 | capable of providing <link | ||
| 394 | linkend="sliced-vbi-format-negotitation">negotiated sliced VBI | ||
| 395 | services</link> as data embedded in the MPEG stream. Users or | ||
| 396 | applications control this sliced VBI data insertion with the <link | ||
| 397 | linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> | ||
| 398 | control.</para> | ||
| 399 | |||
| 400 | <para>If the driver does not provide the <link | ||
| 401 | linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> | ||
| 402 | control, or only allows that control to be set to <link | ||
| 403 | linkend="v4l2-mpeg-stream-vbi-fmt"><constant> | ||
| 404 | V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device | ||
| 405 | cannot embed sliced VBI data in the MPEG stream.</para> | ||
| 406 | |||
| 407 | <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"> | ||
| 408 | V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set | ||
| 409 | the device driver to capture nor cease capturing sliced VBI data. The | ||
| 410 | control only indicates to embed sliced VBI data in the MPEG stream, if | ||
| 411 | an application has negotiated sliced VBI service be captured.</para> | ||
| 412 | |||
| 413 | <para>It may also be the case that a device can embed sliced VBI | ||
| 414 | data in only certain types of MPEG streams: for example in an MPEG-2 | ||
| 415 | PS but not an MPEG-2 TS. In this situation, if sliced VBI data | ||
| 416 | insertion is requested, the sliced VBI data will be embedded in MPEG | ||
| 417 | stream types when supported, and silently omitted from MPEG stream | ||
| 418 | types where sliced VBI data insertion is not supported by the device. | ||
| 419 | </para> | ||
| 420 | |||
| 421 | <para>The following subsections specify the format of the | ||
| 422 | embedded sliced VBI data.</para> | ||
| 423 | |||
| 424 | <section> | ||
| 425 | <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title> | ||
| 426 | <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> | ||
| 427 | V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI | ||
| 428 | format shall be interpreted by drivers as a control to cease | ||
| 429 | embedding sliced VBI data in MPEG streams. Neither the device nor | ||
| 430 | driver shall insert "empty" embedded sliced VBI data packets in the | ||
| 431 | MPEG stream when this format is set. No MPEG stream data structures | ||
| 432 | are specified for this format.</para> | ||
| 433 | </section> | ||
| 434 | |||
| 435 | <section> | ||
| 436 | <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title> | ||
| 437 | <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> | ||
| 438 | V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI | ||
| 439 | format, when supported, indicates to the driver to embed up to 36 | ||
| 440 | lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private | ||
| 441 | Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis> | ||
| 442 | Program Pack</emphasis> in the MPEG stream.</para> | ||
| 443 | |||
| 444 | <para><emphasis>Historical context</emphasis>: This format | ||
| 445 | specification originates from a custom, embedded, sliced VBI data | ||
| 446 | format used by the <filename>ivtv</filename> driver. This format | ||
| 447 | has already been informally specified in the kernel sources in the | ||
| 448 | file <filename>Documentation/video4linux/cx2341x/README.vbi</filename> | ||
| 449 | . The maximum size of the payload and other aspects of this format | ||
| 450 | are driven by the CX23415 MPEG decoder's capabilities and limitations | ||
| 451 | with respect to extracting, decoding, and displaying sliced VBI data | ||
| 452 | embedded within an MPEG stream.</para> | ||
| 453 | |||
| 454 | <para>This format's use is <emphasis>not</emphasis> exclusive to | ||
| 455 | the <filename>ivtv</filename> driver <emphasis>nor</emphasis> | ||
| 456 | exclusive to CX2341x devices, as the sliced VBI data packet insertion | ||
| 457 | into the MPEG stream is implemented in driver software. At least the | ||
| 458 | <filename>cx18</filename> driver provides sliced VBI data insertion | ||
| 459 | into an MPEG-2 PS in this format as well.</para> | ||
| 460 | |||
| 461 | <para>The following definitions specify the payload of the | ||
| 462 | MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain | ||
| 463 | sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt"> | ||
| 464 | <constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set. | ||
| 465 | (The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header | ||
| 466 | and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are | ||
| 467 | not detailed here. Please refer to the MPEG-2 specifications for | ||
| 468 | details on those packet headers.)</para> | ||
| 469 | |||
| 470 | <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES | ||
| 471 | </emphasis> packets that contain sliced VBI data is specified by | ||
| 472 | &v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable | ||
| 473 | length, depending on the actual number of lines of sliced VBI data | ||
| 474 | present in a video frame. The payload may be padded at the end with | ||
| 475 | unspecified fill bytes to align the end of the payload to a 4-byte | ||
| 476 | boundary. The payload shall never exceed 1552 bytes (2 fields with | ||
| 477 | 18 lines/field with 43 bytes of data/line and a 4 byte magic number). | ||
| 478 | </para> | ||
| 479 | |||
| 480 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv"> | ||
| 481 | <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname> | ||
| 482 | </title> | ||
| 483 | <tgroup cols="4"> | ||
| 484 | &cs-ustr; | ||
| 485 | <tbody valign="top"> | ||
| 486 | <row> | ||
| 487 | <entry>__u8</entry> | ||
| 488 | <entry><structfield>magic</structfield>[4]</entry> | ||
| 489 | <entry></entry> | ||
| 490 | <entry>A "magic" constant from <xref | ||
| 491 | linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates | ||
| 492 | this is a valid sliced VBI data payload and also indicates which | ||
| 493 | member of the anonymous union, <structfield>itv0</structfield> or | ||
| 494 | <structfield>ITV0</structfield>, to use for the payload data.</entry> | ||
| 495 | </row> | ||
| 496 | <row> | ||
| 497 | <entry>union</entry> | ||
| 498 | <entry>(anonymous)</entry> | ||
| 499 | </row> | ||
| 500 | <row> | ||
| 501 | <entry></entry> | ||
| 502 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0"> | ||
| 503 | <structname>v4l2_mpeg_vbi_itv0</structname></link> | ||
| 504 | </entry> | ||
| 505 | <entry><structfield>itv0</structfield></entry> | ||
| 506 | <entry>The primary form of the sliced VBI data payload | ||
| 507 | that contains anywhere from 1 to 35 lines of sliced VBI data. | ||
| 508 | Line masks are provided in this form of the payload indicating | ||
| 509 | which VBI lines are provided.</entry> | ||
| 510 | </row> | ||
| 511 | <row> | ||
| 512 | <entry></entry> | ||
| 513 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1"> | ||
| 514 | <structname>v4l2_mpeg_vbi_ITV0</structname></link> | ||
| 515 | </entry> | ||
| 516 | <entry><structfield>ITV0</structfield></entry> | ||
| 517 | <entry>An alternate form of the sliced VBI data payload | ||
| 518 | used when 36 lines of sliced VBI data are present. No line masks are | ||
| 519 | provided in this form of the payload; all valid line mask bits are | ||
| 520 | implcitly set.</entry> | ||
| 521 | </row> | ||
| 522 | </tbody> | ||
| 523 | </tgroup> | ||
| 524 | </table> | ||
| 525 | |||
| 526 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic"> | ||
| 527 | <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv; | ||
| 528 | <structfield>magic</structfield> field</title> | ||
| 529 | <tgroup cols="3"> | ||
| 530 | &cs-def; | ||
| 531 | <thead> | ||
| 532 | <row> | ||
| 533 | <entry align="left">Defined Symbol</entry> | ||
| 534 | <entry align="left">Value</entry> | ||
| 535 | <entry align="left">Description</entry> | ||
| 536 | </row> | ||
| 537 | </thead> | ||
| 538 | <tbody valign="top"> | ||
| 539 | <row> | ||
| 540 | <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant> | ||
| 541 | </entry> | ||
| 542 | <entry>"itv0"</entry> | ||
| 543 | <entry>Indicates the <structfield>itv0</structfield> | ||
| 544 | member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry> | ||
| 545 | </row> | ||
| 546 | <row> | ||
| 547 | <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant> | ||
| 548 | </entry> | ||
| 549 | <entry>"ITV0"</entry> | ||
| 550 | <entry>Indicates the <structfield>ITV0</structfield> | ||
| 551 | member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and | ||
| 552 | that 36 lines of sliced VBI data are present.</entry> | ||
| 553 | </row> | ||
| 554 | </tbody> | ||
| 555 | </tgroup> | ||
| 556 | </table> | ||
| 557 | |||
| 558 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0"> | ||
| 559 | <title>struct <structname>v4l2_mpeg_vbi_itv0</structname> | ||
| 560 | </title> | ||
| 561 | <tgroup cols="3"> | ||
| 562 | &cs-str; | ||
| 563 | <tbody valign="top"> | ||
| 564 | <row> | ||
| 565 | <entry>__le32</entry> | ||
| 566 | <entry><structfield>linemask</structfield>[2]</entry> | ||
| 567 | <entry><para>Bitmasks indicating the VBI service lines | ||
| 568 | present. These <structfield>linemask</structfield> values are stored | ||
| 569 | in little endian byte order in the MPEG stream. Some reference | ||
| 570 | <structfield>linemask</structfield> bit positions with their | ||
| 571 | corresponding VBI line number and video field are given below. | ||
| 572 | b<subscript>0</subscript> indicates the least significant bit of a | ||
| 573 | <structfield>linemask</structfield> value:<screen> | ||
| 574 | <structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field | ||
| 575 | <structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field | ||
| 576 | <structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field | ||
| 577 | <structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field | ||
| 578 | <structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field | ||
| 579 | <structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field | ||
| 580 | <structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry> | ||
| 581 | </row> | ||
| 582 | <row> | ||
| 583 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> | ||
| 584 | <structname>v4l2_mpeg_vbi_itv0_line</structname></link> | ||
| 585 | </entry> | ||
| 586 | <entry><structfield>line</structfield>[35]</entry> | ||
| 587 | <entry>This is a variable length array that holds from 1 | ||
| 588 | to 35 lines of sliced VBI data. The sliced VBI data lines present | ||
| 589 | correspond to the bits set in the <structfield>linemask</structfield> | ||
| 590 | array, starting from b<subscript>0</subscript> of <structfield> | ||
| 591 | linemask</structfield>[0] up through b<subscript>31</subscript> of | ||
| 592 | <structfield>linemask</structfield>[0], and from b<subscript>0 | ||
| 593 | </subscript> of <structfield>linemask</structfield>[1] up through b | ||
| 594 | <subscript>3</subscript> of <structfield>linemask</structfield>[1]. | ||
| 595 | <structfield>line</structfield>[0] corresponds to the first bit | ||
| 596 | found set in the <structfield>linemask</structfield> array, | ||
| 597 | <structfield>line</structfield>[1] corresponds to the second bit | ||
| 598 | found set in the <structfield>linemask</structfield> array, etc. | ||
| 599 | If no <structfield>linemask</structfield> array bits are set, then | ||
| 600 | <structfield>line</structfield>[0] may contain one line of | ||
| 601 | unspecified data that should be ignored by applications.</entry> | ||
| 602 | </row> | ||
| 603 | </tbody> | ||
| 604 | </tgroup> | ||
| 605 | </table> | ||
| 606 | |||
| 607 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1"> | ||
| 608 | <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname> | ||
| 609 | </title> | ||
| 610 | <tgroup cols="3"> | ||
| 611 | &cs-str; | ||
| 612 | <tbody valign="top"> | ||
| 613 | <row> | ||
| 614 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> | ||
| 615 | <structname>v4l2_mpeg_vbi_itv0_line</structname></link> | ||
| 616 | </entry> | ||
| 617 | <entry><structfield>line</structfield>[36]</entry> | ||
| 618 | <entry>A fixed length array of 36 lines of sliced VBI | ||
| 619 | data. <structfield>line</structfield>[0] through <structfield>line | ||
| 620 | </structfield>[17] correspond to lines 6 through 23 of the | ||
| 621 | first field. <structfield>line</structfield>[18] through | ||
| 622 | <structfield>line</structfield>[35] corresponds to lines 6 | ||
| 623 | through 23 of the second field.</entry> | ||
| 624 | </row> | ||
| 625 | </tbody> | ||
| 626 | </tgroup> | ||
| 627 | </table> | ||
| 628 | |||
| 629 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line"> | ||
| 630 | <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname> | ||
| 631 | </title> | ||
| 632 | <tgroup cols="3"> | ||
| 633 | &cs-str; | ||
| 634 | <tbody valign="top"> | ||
| 635 | <row> | ||
| 636 | <entry>__u8</entry> | ||
| 637 | <entry><structfield>id</structfield></entry> | ||
| 638 | <entry>A line identifier value from | ||
| 639 | <xref linkend="ITV0-Line-Identifier-Constants" /> that indicates | ||
| 640 | the type of sliced VBI data stored on this line.</entry> | ||
| 641 | </row> | ||
| 642 | <row> | ||
| 643 | <entry>__u8</entry> | ||
| 644 | <entry><structfield>data</structfield>[42]</entry> | ||
| 645 | <entry>The sliced VBI data for the line.</entry> | ||
| 646 | </row> | ||
| 647 | </tbody> | ||
| 648 | </tgroup> | ||
| 649 | </table> | ||
| 650 | |||
| 651 | <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants"> | ||
| 652 | <title>Line Identifiers for struct <link | ||
| 653 | linkend="v4l2-mpeg-vbi-itv0-line"><structname> | ||
| 654 | v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id | ||
| 655 | </structfield> field</title> | ||
| 656 | <tgroup cols="3"> | ||
| 657 | &cs-def; | ||
| 658 | <thead> | ||
| 659 | <row> | ||
| 660 | <entry align="left">Defined Symbol</entry> | ||
| 661 | <entry align="left">Value</entry> | ||
| 662 | <entry align="left">Description</entry> | ||
| 663 | </row> | ||
| 664 | </thead> | ||
| 665 | <tbody valign="top"> | ||
| 666 | <row> | ||
| 667 | <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant> | ||
| 668 | </entry> | ||
| 669 | <entry>1</entry> | ||
| 670 | <entry>Refer to <link linkend="vbi-services2"> | ||
| 671 | Sliced VBI services</link> for a description of the line payload.</entry> | ||
| 672 | </row> | ||
| 673 | <row> | ||
| 674 | <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant> | ||
| 675 | </entry> | ||
| 676 | <entry>4</entry> | ||
| 677 | <entry>Refer to <link linkend="vbi-services2"> | ||
| 678 | Sliced VBI services</link> for a description of the line payload.</entry> | ||
| 679 | </row> | ||
| 680 | <row> | ||
| 681 | <entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant> | ||
| 682 | </entry> | ||
| 683 | <entry>5</entry> | ||
| 684 | <entry>Refer to <link linkend="vbi-services2"> | ||
| 685 | Sliced VBI services</link> for a description of the line payload.</entry> | ||
| 686 | </row> | ||
| 687 | <row> | ||
| 688 | <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant> | ||
| 689 | </entry> | ||
| 690 | <entry>7</entry> | ||
| 691 | <entry>Refer to <link linkend="vbi-services2"> | ||
| 692 | Sliced VBI services</link> for a description of the line payload.</entry> | ||
| 693 | </row> | ||
| 694 | </tbody> | ||
| 695 | </tgroup> | ||
| 696 | </table> | ||
| 697 | |||
| 698 | </section> | ||
| 699 | </section> | ||
| 700 | |||
| 701 | |||
| 702 | <!-- | ||
| 703 | Local Variables: | ||
| 704 | mode: sgml | ||
| 705 | sgml-parent-document: "v4l2.sgml" | ||
| 706 | indent-tabs-mode: nil | ||
| 707 | End: | ||
| 708 | --> | ||
diff --git a/Documentation/DocBook/v4l/dev-teletext.xml b/Documentation/DocBook/v4l/dev-teletext.xml new file mode 100644 index 000000000000..76184e8ed618 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-teletext.xml | |||
| @@ -0,0 +1,40 @@ | |||
| 1 | <title>Teletext Interface</title> | ||
| 2 | |||
| 3 | <para>This interface aims at devices receiving and demodulating | ||
| 4 | Teletext data [<xref linkend="ets300706" />, <xref linkend="itu653" />], evaluating the | ||
| 5 | Teletext packages and storing formatted pages in cache memory. Such | ||
| 6 | devices are usually implemented as microcontrollers with serial | ||
| 7 | interface (I<superscript>2</superscript>C) and can be found on older | ||
| 8 | TV cards, dedicated Teletext decoding cards and home-brew devices | ||
| 9 | connected to the PC parallel port.</para> | ||
| 10 | |||
| 11 | <para>The Teletext API was designed by Martin Buck. It is defined in | ||
| 12 | the kernel header file <filename>linux/videotext.h</filename>, the | ||
| 13 | specification is available from <ulink url="ftp://ftp.gwdg.de/pub/linux/misc/videotext/"> | ||
| 14 | ftp://ftp.gwdg.de/pub/linux/misc/videotext/</ulink>. (Videotext is the name of | ||
| 15 | the German public television Teletext service.) Conventional character | ||
| 16 | device file names are <filename>/dev/vtx</filename> and | ||
| 17 | <filename>/dev/vttuner</filename>, with device number 83, 0 and 83, 16 | ||
| 18 | respectively. A similar interface exists for the Philips SAA5249 | ||
| 19 | Teletext decoder [specification?] with character device file names | ||
| 20 | <filename>/dev/tlkN</filename>, device number 102, N.</para> | ||
| 21 | |||
| 22 | <para>Eventually the Teletext API was integrated into the V4L API | ||
| 23 | with character device file names <filename>/dev/vtx0</filename> to | ||
| 24 | <filename>/dev/vtx31</filename>, device major number 81, minor numbers | ||
| 25 | 192 to 223. For reference the V4L Teletext API specification is | ||
| 26 | reproduced here in full: "Teletext interfaces talk the existing VTX | ||
| 27 | API." Teletext devices with major number 83 and 102 will be removed in | ||
| 28 | Linux 2.6.</para> | ||
| 29 | |||
| 30 | <para>There are no plans to replace the Teletext API or to integrate | ||
| 31 | it into V4L2. Please write to the linux-media mailing list: &v4l-ml; | ||
| 32 | when the need arises.</para> | ||
| 33 | |||
| 34 | <!-- | ||
| 35 | Local Variables: | ||
| 36 | mode: sgml | ||
| 37 | sgml-parent-document: "v4l2.sgml" | ||
| 38 | indent-tabs-mode: nil | ||
| 39 | End: | ||
| 40 | --> | ||
diff --git a/Documentation/DocBook/v4l/driver.xml b/Documentation/DocBook/v4l/driver.xml new file mode 100644 index 000000000000..1f7eea5c4ec3 --- /dev/null +++ b/Documentation/DocBook/v4l/driver.xml | |||
| @@ -0,0 +1,208 @@ | |||
| 1 | <title>V4L2 Driver Programming</title> | ||
| 2 | |||
| 3 | <!-- This part defines the interface between the "videodev" | ||
| 4 | module and individual drivers. --> | ||
| 5 | |||
| 6 | <para>to do</para> | ||
| 7 | <!-- | ||
| 8 | <para>V4L2 is a two-layer driver system. The top layer is the "videodev" | ||
| 9 | kernel module. When videodev initializes it registers as character device | ||
| 10 | with major number 81, and it registers a set of file operations. All V4L2 | ||
| 11 | drivers are really clients of videodev, which calls V4L2 drivers through | ||
| 12 | driver method functions. V4L2 drivers are also written as kernel modules. | ||
| 13 | After probing the hardware they register one or more devices with | ||
| 14 | videodev.</para> | ||
| 15 | |||
| 16 | <section id="driver-modules"> | ||
| 17 | <title>Driver Modules</title> | ||
| 18 | |||
| 19 | <para>V4L2 driver modules must have an initialization function which is | ||
| 20 | called after the module was loaded into kernel, an exit function whis is | ||
| 21 | called before the module is removed. When the driver is compiled into the | ||
| 22 | kernel these functions called at system boot and shutdown time.</para> | ||
| 23 | |||
| 24 | <informalexample> | ||
| 25 | <programlisting> | ||
| 26 | #include <linux/module.h> | ||
| 27 | |||
| 28 | /* Export information about this module. For details and other useful | ||
| 29 | macros see <filename>linux/module.h</filename>. */ | ||
| 30 | MODULE_DESCRIPTION("my - driver for my hardware"); | ||
| 31 | MODULE_AUTHOR("Your name here"); | ||
| 32 | MODULE_LICENSE("GPL"); | ||
| 33 | |||
| 34 | static void | ||
| 35 | my_module_exit (void) | ||
| 36 | { | ||
| 37 | /* Free all resources allocated by my_module_init(). */ | ||
| 38 | } | ||
| 39 | |||
| 40 | static int | ||
| 41 | my_module_init (void) | ||
| 42 | { | ||
| 43 | /* Bind the driver to the supported hardware, see | ||
| 44 | <link linkend="driver-pci"> and | ||
| 45 | <link linkend="driver-usb"> for examples. */ | ||
| 46 | |||
| 47 | return 0; /* a negative value on error, 0 on success. */ | ||
| 48 | } | ||
| 49 | |||
| 50 | /* Export module functions. */ | ||
| 51 | module_init (my_module_init); | ||
| 52 | module_exit (my_module_exit); | ||
| 53 | </programlisting> | ||
| 54 | </informalexample> | ||
| 55 | |||
| 56 | <para>Users can add parameters when kernel modules are inserted:</para> | ||
| 57 | |||
| 58 | <informalexample> | ||
| 59 | <programlisting> | ||
| 60 | include <linux/moduleparam.h> | ||
| 61 | |||
| 62 | static int my_option = 123; | ||
| 63 | static int my_option_array[47]; | ||
| 64 | |||
| 65 | /* Export the symbol, an int, with access permissions 0664. | ||
| 66 | See <filename>linux/moduleparam.h</filename> for other types. */ | ||
| 67 | module_param (my_option, int, 0644); | ||
| 68 | module_param_array (my_option_array, int, NULL, 0644); | ||
| 69 | |||
| 70 | MODULE_PARM_DESC (my_option, "Does magic things, default 123"); | ||
| 71 | </programlisting> | ||
| 72 | </informalexample> | ||
| 73 | |||
| 74 | <para>One parameter should be supported by all V4L2 drivers, the minor | ||
| 75 | number of the device it will register. Purpose is to predictably link V4L2 | ||
| 76 | drivers to device nodes if more than one video device is installed. Use the | ||
| 77 | name of the device node followed by a "_nr" suffix, for example "video_nr" | ||
| 78 | for <filename>/dev/video</filename>.</para> | ||
| 79 | |||
| 80 | <informalexample> | ||
| 81 | <programlisting> | ||
| 82 | /* Minor number of the device, -1 to allocate the first unused. */ | ||
| 83 | static int video_nr = -1; | ||
| 84 | |||
| 85 | module_param (video_nr, int, 0444); | ||
| 86 | </programlisting> | ||
| 87 | </informalexample> | ||
| 88 | </section> | ||
| 89 | |||
| 90 | <section id="driver-pci"> | ||
| 91 | <title>PCI Devices</title> | ||
| 92 | |||
| 93 | <para>PCI devices are initialized like this:</para> | ||
| 94 | |||
| 95 | <informalexample> | ||
| 96 | <programlisting> | ||
| 97 | typedef struct { | ||
| 98 | /* State of one physical device. */ | ||
| 99 | } my_device; | ||
| 100 | |||
| 101 | static int | ||
| 102 | my_resume (struct pci_dev * pci_dev) | ||
| 103 | { | ||
| 104 | /* Restore the suspended device to working state. */ | ||
| 105 | } | ||
| 106 | |||
| 107 | static int | ||
| 108 | my_suspend (struct pci_dev * pci_dev, | ||
| 109 | pm_message_t state) | ||
| 110 | { | ||
| 111 | /* This function is called before the system goes to sleep. | ||
| 112 | Stop all DMAs and disable interrupts, then put the device | ||
| 113 | into a low power state. For details see the kernel | ||
| 114 | sources under <filename>Documentation/power</filename>. */ | ||
| 115 | |||
| 116 | return 0; /* a negative value on error, 0 on success. */ | ||
| 117 | } | ||
| 118 | |||
| 119 | static void __devexit | ||
| 120 | my_remove (struct pci_dev * pci_dev) | ||
| 121 | { | ||
| 122 | my_device *my = pci_get_drvdata (pci_dev); | ||
| 123 | |||
| 124 | /* Describe me. */ | ||
| 125 | } | ||
| 126 | |||
| 127 | static int __devinit | ||
| 128 | my_probe (struct pci_dev * pci_dev, | ||
| 129 | const struct pci_device_id * pci_id) | ||
| 130 | { | ||
| 131 | my_device *my; | ||
| 132 | |||
| 133 | /* Describe me. */ | ||
| 134 | |||
| 135 | /* You can allocate per-device data here and store a pointer | ||
| 136 | to it in the pci_dev structure. */ | ||
| 137 | my = ...; | ||
| 138 | pci_set_drvdata (pci_dev, my); | ||
| 139 | |||
| 140 | return 0; /* a negative value on error, 0 on success. */ | ||
| 141 | } | ||
| 142 | |||
| 143 | /* A list of supported PCI devices. */ | ||
| 144 | static struct pci_device_id | ||
| 145 | my_pci_device_ids [] = { | ||
| 146 | { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, | ||
| 147 | PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0 }, | ||
| 148 | { 0 } /* end of list */ | ||
| 149 | }; | ||
| 150 | |||
| 151 | /* Load our module if supported PCI devices are installed. */ | ||
| 152 | MODULE_DEVICE_TABLE (pci, my_pci_device_ids); | ||
| 153 | |||
| 154 | static struct pci_driver | ||
| 155 | my_pci_driver = { | ||
| 156 | .name = "my", | ||
| 157 | .id_table = my_pci_device_ids, | ||
| 158 | |||
| 159 | .probe = my_probe, | ||
| 160 | .remove = __devexit_p (my_remove), | ||
| 161 | |||
| 162 | /* Power management functions. */ | ||
| 163 | .suspend = my_suspend, | ||
| 164 | .resume = my_resume, | ||
| 165 | }; | ||
| 166 | |||
| 167 | static void | ||
| 168 | my_module_exit (void) | ||
| 169 | { | ||
| 170 | pci_unregister_driver (&my_pci_driver); | ||
| 171 | } | ||
| 172 | |||
| 173 | static int | ||
| 174 | my_module_init (void) | ||
| 175 | { | ||
| 176 | return pci_register_driver (&my_pci_driver); | ||
| 177 | } | ||
| 178 | </programlisting> | ||
| 179 | </informalexample> | ||
| 180 | </section> | ||
| 181 | |||
| 182 | <section id="driver-usb"> | ||
| 183 | <title>USB Devices</title> | ||
| 184 | <para>to do</para> | ||
| 185 | </section> | ||
| 186 | <section id="driver-registering"> | ||
| 187 | <title>Registering V4L2 Drivers</title> | ||
| 188 | |||
| 189 | <para>After a V4L2 driver probed the hardware it registers one or more | ||
| 190 | devices with the videodev module.</para> | ||
| 191 | </section> | ||
| 192 | <section id="driver-file-ops"> | ||
| 193 | <title>File Operations</title> | ||
| 194 | <para>to do</para> | ||
| 195 | </section> | ||
| 196 | <section id="driver-internal-api"> | ||
| 197 | <title>Internal API</title> | ||
| 198 | <para>to do</para> | ||
| 199 | </section> | ||
| 200 | --> | ||
| 201 | |||
| 202 | <!-- | ||
| 203 | Local Variables: | ||
| 204 | mode: sgml | ||
| 205 | sgml-parent-document: "v4l2.sgml" | ||
| 206 | indent-tabs-mode: nil | ||
| 207 | End: | ||
| 208 | --> | ||
diff --git a/Documentation/DocBook/v4l/fdl-appendix.xml b/Documentation/DocBook/v4l/fdl-appendix.xml new file mode 100644 index 000000000000..b6ce50dbe492 --- /dev/null +++ b/Documentation/DocBook/v4l/fdl-appendix.xml | |||
| @@ -0,0 +1,671 @@ | |||
| 1 | <!-- | ||
| 2 | The GNU Free Documentation License 1.1 in DocBook | ||
| 3 | Markup by Eric Baudais <baudais@okstate.edu> | ||
| 4 | Maintained by the GNOME Documentation Project | ||
| 5 | http://developer.gnome.org/projects/gdp | ||
| 6 | Version: 1.0.1 | ||
| 7 | Last Modified: Nov 16, 2000 | ||
| 8 | --> | ||
| 9 | |||
| 10 | <appendix id="fdl"> | ||
| 11 | <appendixinfo> | ||
| 12 | <releaseinfo> | ||
| 13 | Version 1.1, March 2000 | ||
| 14 | </releaseinfo> | ||
| 15 | <copyright> | ||
| 16 | <year>2000</year><holder>Free Software Foundation, Inc.</holder> | ||
| 17 | </copyright> | ||
| 18 | <legalnotice id="fdl-legalnotice"> | ||
| 19 | <para> | ||
| 20 | <address>Free Software Foundation, Inc. <street>59 Temple Place, | ||
| 21 | Suite 330</street>, <city>Boston</city>, <state>MA</state> | ||
| 22 | <postcode>02111-1307</postcode> <country>USA</country></address> | ||
| 23 | Everyone is permitted to copy and distribute verbatim copies of this | ||
| 24 | license document, but changing it is not allowed. | ||
| 25 | </para> | ||
| 26 | </legalnotice> | ||
| 27 | </appendixinfo> | ||
| 28 | <title>GNU Free Documentation License</title> | ||
| 29 | |||
| 30 | <sect1 id="fdl-preamble"> | ||
| 31 | <title>0. PREAMBLE</title> | ||
| 32 | <para> | ||
| 33 | The purpose of this License is to make a manual, textbook, or | ||
| 34 | other written document <quote>free</quote> in the sense of | ||
| 35 | freedom: to assure everyone the effective freedom to copy and | ||
| 36 | redistribute it, with or without modifying it, either | ||
| 37 | commercially or noncommercially. Secondarily, this License | ||
| 38 | preserves for the author and publisher a way to get credit for | ||
| 39 | their work, while not being considered responsible for | ||
| 40 | modifications made by others. | ||
| 41 | </para> | ||
| 42 | |||
| 43 | <para> | ||
| 44 | This License is a kind of <quote>copyleft</quote>, which means | ||
| 45 | that derivative works of the document must themselves be free in | ||
| 46 | the same sense. It complements the GNU General Public License, | ||
| 47 | which is a copyleft license designed for free software. | ||
| 48 | </para> | ||
| 49 | |||
| 50 | <para> | ||
| 51 | We have designed this License in order to use it for manuals for | ||
| 52 | free software, because free software needs free documentation: a | ||
| 53 | free program should come with manuals providing the same | ||
| 54 | freedoms that the software does. But this License is not limited | ||
| 55 | to software manuals; it can be used for any textual work, | ||
| 56 | regardless of subject matter or whether it is published as a | ||
| 57 | printed book. We recommend this License principally for works | ||
| 58 | whose purpose is instruction or reference. | ||
| 59 | </para> | ||
| 60 | </sect1> | ||
| 61 | <sect1 id="fdl-section1"> | ||
| 62 | <title>1. APPLICABILITY AND DEFINITIONS</title> | ||
| 63 | <para id="fdl-document"> | ||
| 64 | This License applies to any manual or other work that contains a | ||
| 65 | notice placed by the copyright holder saying it can be | ||
| 66 | distributed under the terms of this License. The | ||
| 67 | <quote>Document</quote>, below, refers to any such manual or | ||
| 68 | work. Any member of the public is a licensee, and is addressed | ||
| 69 | as <quote>you</quote>. | ||
| 70 | </para> | ||
| 71 | |||
| 72 | <para id="fdl-modified"> | ||
| 73 | A <quote>Modified Version</quote> of the Document means any work | ||
| 74 | containing the Document or a portion of it, either copied | ||
| 75 | verbatim, or with modifications and/or translated into another | ||
| 76 | language. | ||
| 77 | </para> | ||
| 78 | |||
| 79 | <para id="fdl-secondary"> | ||
| 80 | A <quote>Secondary Section</quote> is a named appendix or a | ||
| 81 | front-matter section of the <link | ||
| 82 | linkend="fdl-document">Document</link> that deals exclusively | ||
| 83 | with the relationship of the publishers or authors of the | ||
| 84 | Document to the Document's overall subject (or to related | ||
| 85 | matters) and contains nothing that could fall directly within | ||
| 86 | that overall subject. (For example, if the Document is in part a | ||
| 87 | textbook of mathematics, a Secondary Section may not explain any | ||
| 88 | mathematics.) The relationship could be a matter of historical | ||
| 89 | connection with the subject or with related matters, or of | ||
| 90 | legal, commercial, philosophical, ethical or political position | ||
| 91 | regarding them. | ||
| 92 | </para> | ||
| 93 | |||
| 94 | <para id="fdl-invariant"> | ||
| 95 | The <quote>Invariant Sections</quote> are certain <link | ||
| 96 | linkend="fdl-secondary"> Secondary Sections</link> whose titles | ||
| 97 | are designated, as being those of Invariant Sections, in the | ||
| 98 | notice that says that the <link | ||
| 99 | linkend="fdl-document">Document</link> is released under this | ||
| 100 | License. | ||
| 101 | </para> | ||
| 102 | |||
| 103 | <para id="fdl-cover-texts"> | ||
| 104 | The <quote>Cover Texts</quote> are certain short passages of | ||
| 105 | text that are listed, as Front-Cover Texts or Back-Cover Texts, | ||
| 106 | in the notice that says that the <link | ||
| 107 | linkend="fdl-document">Document</link> is released under this | ||
| 108 | License. | ||
| 109 | </para> | ||
| 110 | |||
| 111 | <para id="fdl-transparent"> | ||
| 112 | A <quote>Transparent</quote> copy of the <link | ||
| 113 | linkend="fdl-document"> Document</link> means a machine-readable | ||
| 114 | copy, represented in a format whose specification is available | ||
| 115 | to the general public, whose contents can be viewed and edited | ||
| 116 | directly and straightforwardly with generic text editors or (for | ||
| 117 | images composed of pixels) generic paint programs or (for | ||
| 118 | drawings) some widely available drawing editor, and that is | ||
| 119 | suitable for input to text formatters or for automatic | ||
| 120 | translation to a variety of formats suitable for input to text | ||
| 121 | formatters. A copy made in an otherwise Transparent file format | ||
| 122 | whose markup has been designed to thwart or discourage | ||
| 123 | subsequent modification by readers is not Transparent. A copy | ||
| 124 | that is not <quote>Transparent</quote> is called | ||
| 125 | <quote>Opaque</quote>. | ||
| 126 | </para> | ||
| 127 | |||
| 128 | <para> | ||
| 129 | Examples of suitable formats for Transparent copies include | ||
| 130 | plain ASCII without markup, Texinfo input format, LaTeX input | ||
| 131 | format, SGML or XML using a publicly available DTD, and | ||
| 132 | standard-conforming simple HTML designed for human | ||
| 133 | modification. Opaque formats include PostScript, PDF, | ||
| 134 | proprietary formats that can be read and edited only by | ||
| 135 | proprietary word processors, SGML or XML for which the DTD | ||
| 136 | and/or processing tools are not generally available, and the | ||
| 137 | machine-generated HTML produced by some word processors for | ||
| 138 | output purposes only. | ||
| 139 | </para> | ||
| 140 | |||
| 141 | <para id="fdl-title-page"> | ||
| 142 | The <quote>Title Page</quote> means, for a printed book, the | ||
| 143 | title page itself, plus such following pages as are needed to | ||
| 144 | hold, legibly, the material this License requires to appear in | ||
| 145 | the title page. For works in formats which do not have any title | ||
| 146 | page as such, <quote>Title Page</quote> means the text near the | ||
| 147 | most prominent appearance of the work's title, preceding the | ||
| 148 | beginning of the body of the text. | ||
| 149 | </para> | ||
| 150 | </sect1> | ||
| 151 | |||
| 152 | <sect1 id="fdl-section2"> | ||
| 153 | <title>2. VERBATIM COPYING</title> | ||
| 154 | <para> | ||
| 155 | You may copy and distribute the <link | ||
| 156 | linkend="fdl-document">Document</link> in any medium, either | ||
| 157 | commercially or noncommercially, provided that this License, the | ||
| 158 | copyright notices, and the license notice saying this License | ||
| 159 | applies to the Document are reproduced in all copies, and that | ||
| 160 | you add no other conditions whatsoever to those of this | ||
| 161 | License. You may not use technical measures to obstruct or | ||
| 162 | control the reading or further copying of the copies you make or | ||
| 163 | distribute. However, you may accept compensation in exchange for | ||
| 164 | copies. If you distribute a large enough number of copies you | ||
| 165 | must also follow the conditions in <link | ||
| 166 | linkend="fdl-section3">section 3</link>. | ||
| 167 | </para> | ||
| 168 | |||
| 169 | <para> | ||
| 170 | You may also lend copies, under the same conditions stated | ||
| 171 | above, and you may publicly display copies. | ||
| 172 | </para> | ||
| 173 | </sect1> | ||
| 174 | |||
| 175 | <sect1 id="fdl-section3"> | ||
| 176 | <title>3. COPYING IN QUANTITY</title> | ||
| 177 | <para> | ||
| 178 | If you publish printed copies of the <link | ||
| 179 | linkend="fdl-document">Document</link> numbering more than 100, | ||
| 180 | and the Document's license notice requires <link | ||
| 181 | linkend="fdl-cover-texts">Cover Texts</link>, you must enclose | ||
| 182 | the copies in covers that carry, clearly and legibly, all these | ||
| 183 | Cover Texts: Front-Cover Texts on the front cover, and | ||
| 184 | Back-Cover Texts on the back cover. Both covers must also | ||
| 185 | clearly and legibly identify you as the publisher of these | ||
| 186 | copies. The front cover must present the full title with all | ||
| 187 | words of the title equally prominent and visible. You may add | ||
| 188 | other material on the covers in addition. Copying with changes | ||
| 189 | limited to the covers, as long as they preserve the title of the | ||
| 190 | <link linkend="fdl-document">Document</link> and satisfy these | ||
| 191 | conditions, can be treated as verbatim copying in other | ||
| 192 | respects. | ||
| 193 | </para> | ||
| 194 | |||
| 195 | <para> | ||
| 196 | If the required texts for either cover are too voluminous to fit | ||
| 197 | legibly, you should put the first ones listed (as many as fit | ||
| 198 | reasonably) on the actual cover, and continue the rest onto | ||
| 199 | adjacent pages. | ||
| 200 | </para> | ||
| 201 | |||
| 202 | <para> | ||
| 203 | If you publish or distribute <link | ||
| 204 | linkend="fdl-transparent">Opaque</link> copies of the <link | ||
| 205 | linkend="fdl-document">Document</link> numbering more than 100, | ||
| 206 | you must either include a machine-readable <link | ||
| 207 | linkend="fdl-transparent">Transparent</link> copy along with | ||
| 208 | each Opaque copy, or state in or with each Opaque copy a | ||
| 209 | publicly-accessible computer-network location containing a | ||
| 210 | complete Transparent copy of the Document, free of added | ||
| 211 | material, which the general network-using public has access to | ||
| 212 | download anonymously at no charge using public-standard network | ||
| 213 | protocols. If you use the latter option, you must take | ||
| 214 | reasonably prudent steps, when you begin distribution of Opaque | ||
| 215 | copies in quantity, to ensure that this Transparent copy will | ||
| 216 | remain thus accessible at the stated location until at least one | ||
| 217 | year after the last time you distribute an Opaque copy (directly | ||
| 218 | or through your agents or retailers) of that edition to the | ||
| 219 | public. | ||
| 220 | </para> | ||
| 221 | |||
| 222 | <para> | ||
| 223 | It is requested, but not required, that you contact the authors | ||
| 224 | of the <link linkend="fdl-document">Document</link> well before | ||
| 225 | redistributing any large number of copies, to give them a chance | ||
| 226 | to provide you with an updated version of the Document. | ||
| 227 | </para> | ||
| 228 | </sect1> | ||
| 229 | |||
| 230 | <sect1 id="fdl-section4"> | ||
| 231 | <title>4. MODIFICATIONS</title> | ||
| 232 | <para> | ||
| 233 | You may copy and distribute a <link | ||
| 234 | linkend="fdl-modified">Modified Version</link> of the <link | ||
| 235 | linkend="fdl-document">Document</link> under the conditions of | ||
| 236 | sections <link linkend="fdl-section2">2</link> and <link | ||
| 237 | linkend="fdl-section3">3</link> above, provided that you release | ||
| 238 | the Modified Version under precisely this License, with the | ||
| 239 | Modified Version filling the role of the Document, thus | ||
| 240 | licensing distribution and modification of the Modified Version | ||
| 241 | to whoever possesses a copy of it. In addition, you must do | ||
| 242 | these things in the Modified Version: | ||
| 243 | </para> | ||
| 244 | |||
| 245 | <itemizedlist mark="opencircle"> | ||
| 246 | <listitem> | ||
| 247 | <formalpara> | ||
| 248 | <title>A</title> | ||
| 249 | <para> | ||
| 250 | Use in the <link linkend="fdl-title-page">Title | ||
| 251 | Page</link> (and on the covers, if any) a title distinct | ||
| 252 | from that of the <link | ||
| 253 | linkend="fdl-document">Document</link>, and from those of | ||
| 254 | previous versions (which should, if there were any, be | ||
| 255 | listed in the History section of the Document). You may | ||
| 256 | use the same title as a previous version if the original | ||
| 257 | publisher of that version gives permission. | ||
| 258 | </para> | ||
| 259 | </formalpara> | ||
| 260 | </listitem> | ||
| 261 | |||
| 262 | <listitem> | ||
| 263 | <formalpara> | ||
| 264 | <title>B</title> | ||
| 265 | <para> | ||
| 266 | List on the <link linkend="fdl-title-page">Title | ||
| 267 | Page</link>, as authors, one or more persons or entities | ||
| 268 | responsible for authorship of the modifications in the | ||
| 269 | <link linkend="fdl-modified">Modified Version</link>, | ||
| 270 | together with at least five of the principal authors of | ||
| 271 | the <link linkend="fdl-document">Document</link> (all of | ||
| 272 | its principal authors, if it has less than five). | ||
| 273 | </para> | ||
| 274 | </formalpara> | ||
| 275 | </listitem> | ||
| 276 | |||
| 277 | <listitem> | ||
| 278 | <formalpara> | ||
| 279 | <title>C</title> | ||
| 280 | <para> | ||
| 281 | State on the <link linkend="fdl-title-page">Title | ||
| 282 | Page</link> the name of the publisher of the <link | ||
| 283 | linkend="fdl-modified">Modified Version</link>, as the | ||
| 284 | publisher. | ||
| 285 | </para> | ||
| 286 | </formalpara> | ||
| 287 | </listitem> | ||
| 288 | |||
| 289 | <listitem> | ||
| 290 | <formalpara> | ||
| 291 | <title>D</title> | ||
| 292 | <para> | ||
| 293 | Preserve all the copyright notices of the <link | ||
| 294 | linkend="fdl-document">Document</link>. | ||
| 295 | </para> | ||
| 296 | </formalpara> | ||
| 297 | </listitem> | ||
| 298 | |||
| 299 | <listitem> | ||
| 300 | <formalpara> | ||
| 301 | <title>E</title> | ||
| 302 | <para> | ||
| 303 | Add an appropriate copyright notice for your modifications | ||
| 304 | adjacent to the other copyright notices. | ||
| 305 | </para> | ||
| 306 | </formalpara> | ||
| 307 | </listitem> | ||
| 308 | |||
| 309 | <listitem> | ||
| 310 | <formalpara> | ||
| 311 | <title>F</title> | ||
| 312 | <para> | ||
| 313 | Include, immediately after the copyright notices, a | ||
| 314 | license notice giving the public permission to use the | ||
| 315 | <link linkend="fdl-modified">Modified Version</link> under | ||
| 316 | the terms of this License, in the form shown in the | ||
| 317 | Addendum below. | ||
| 318 | </para> | ||
| 319 | </formalpara> | ||
| 320 | </listitem> | ||
| 321 | |||
| 322 | <listitem> | ||
| 323 | <formalpara> | ||
| 324 | <title>G</title> | ||
| 325 | <para> | ||
| 326 | Preserve in that license notice the full lists of <link | ||
| 327 | linkend="fdl-invariant"> Invariant Sections</link> and | ||
| 328 | required <link linkend="fdl-cover-texts">Cover | ||
| 329 | Texts</link> given in the <link | ||
| 330 | linkend="fdl-document">Document's</link> license notice. | ||
| 331 | </para> | ||
| 332 | </formalpara> | ||
| 333 | </listitem> | ||
| 334 | |||
| 335 | <listitem> | ||
| 336 | <formalpara> | ||
| 337 | <title>H</title> | ||
| 338 | <para> | ||
| 339 | Include an unaltered copy of this License. | ||
| 340 | </para> | ||
| 341 | </formalpara> | ||
| 342 | </listitem> | ||
| 343 | |||
| 344 | <listitem> | ||
| 345 | <formalpara> | ||
| 346 | <title>I</title> | ||
| 347 | <para> | ||
| 348 | Preserve the section entitled <quote>History</quote>, and | ||
| 349 | its title, and add to it an item stating at least the | ||
| 350 | title, year, new authors, and publisher of the <link | ||
| 351 | linkend="fdl-modified">Modified Version </link>as given on | ||
| 352 | the <link linkend="fdl-title-page">Title Page</link>. If | ||
| 353 | there is no section entitled <quote>History</quote> in the | ||
| 354 | <link linkend="fdl-document">Document</link>, create one | ||
| 355 | stating the title, year, authors, and publisher of the | ||
| 356 | Document as given on its Title Page, then add an item | ||
| 357 | describing the Modified Version as stated in the previous | ||
| 358 | sentence. | ||
| 359 | </para> | ||
| 360 | </formalpara> | ||
| 361 | </listitem> | ||
| 362 | |||
| 363 | <listitem> | ||
| 364 | <formalpara> | ||
| 365 | <title>J</title> | ||
| 366 | <para> | ||
| 367 | Preserve the network location, if any, given in the <link | ||
| 368 | linkend="fdl-document">Document</link> for public access | ||
| 369 | to a <link linkend="fdl-transparent">Transparent</link> | ||
| 370 | copy of the Document, and likewise the network locations | ||
| 371 | given in the Document for previous versions it was based | ||
| 372 | on. These may be placed in the <quote>History</quote> | ||
| 373 | section. You may omit a network location for a work that | ||
| 374 | was published at least four years before the Document | ||
| 375 | itself, or if the original publisher of the version it | ||
| 376 | refers to gives permission. | ||
| 377 | </para> | ||
| 378 | </formalpara> | ||
| 379 | </listitem> | ||
| 380 | |||
| 381 | <listitem> | ||
| 382 | <formalpara> | ||
| 383 | <title>K</title> | ||
| 384 | <para> | ||
| 385 | In any section entitled <quote>Acknowledgements</quote> or | ||
| 386 | <quote>Dedications</quote>, preserve the section's title, | ||
| 387 | and preserve in the section all the substance and tone of | ||
| 388 | each of the contributor acknowledgements and/or | ||
| 389 | dedications given therein. | ||
| 390 | </para> | ||
| 391 | </formalpara> | ||
| 392 | </listitem> | ||
| 393 | |||
| 394 | <listitem> | ||
| 395 | <formalpara> | ||
| 396 | <title>L</title> | ||
| 397 | <para> | ||
| 398 | Preserve all the <link linkend="fdl-invariant">Invariant | ||
| 399 | Sections</link> of the <link | ||
| 400 | linkend="fdl-document">Document</link>, unaltered in their | ||
| 401 | text and in their titles. Section numbers or the | ||
| 402 | equivalent are not considered part of the section titles. | ||
| 403 | </para> | ||
| 404 | </formalpara> | ||
| 405 | </listitem> | ||
| 406 | |||
| 407 | <listitem> | ||
| 408 | <formalpara> | ||
| 409 | <title>M</title> | ||
| 410 | <para> | ||
| 411 | Delete any section entitled | ||
| 412 | <quote>Endorsements</quote>. Such a section may not be | ||
| 413 | included in the <link linkend="fdl-modified">Modified | ||
| 414 | Version</link>. | ||
| 415 | </para> | ||
| 416 | </formalpara> | ||
| 417 | </listitem> | ||
| 418 | |||
| 419 | <listitem> | ||
| 420 | <formalpara> | ||
| 421 | <title>N</title> | ||
| 422 | <para> | ||
| 423 | Do not retitle any existing section as | ||
| 424 | <quote>Endorsements</quote> or to conflict in title with | ||
| 425 | any <link linkend="fdl-invariant">Invariant | ||
| 426 | Section</link>. | ||
| 427 | </para> | ||
| 428 | </formalpara> | ||
| 429 | </listitem> | ||
| 430 | </itemizedlist> | ||
| 431 | |||
| 432 | <para> | ||
| 433 | If the <link linkend="fdl-modified">Modified Version</link> | ||
| 434 | includes new front-matter sections or appendices that qualify as | ||
| 435 | <link linkend="fdl-secondary">Secondary Sections</link> and | ||
| 436 | contain no material copied from the Document, you may at your | ||
| 437 | option designate some or all of these sections as invariant. To | ||
| 438 | do this, add their titles to the list of <link | ||
| 439 | linkend="fdl-invariant">Invariant Sections</link> in the | ||
| 440 | Modified Version's license notice. These titles must be | ||
| 441 | distinct from any other section titles. | ||
| 442 | </para> | ||
| 443 | |||
| 444 | <para> | ||
| 445 | You may add a section entitled <quote>Endorsements</quote>, | ||
| 446 | provided it contains nothing but endorsements of your <link | ||
| 447 | linkend="fdl-modified">Modified Version</link> by various | ||
| 448 | parties--for example, statements of peer review or that the text | ||
| 449 | has been approved by an organization as the authoritative | ||
| 450 | definition of a standard. | ||
| 451 | </para> | ||
| 452 | |||
| 453 | <para> | ||
| 454 | You may add a passage of up to five words as a <link | ||
| 455 | linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage | ||
| 456 | of up to 25 words as a <link | ||
| 457 | linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of | ||
| 458 | the list of <link linkend="fdl-cover-texts">Cover Texts</link> | ||
| 459 | in the <link linkend="fdl-modified">Modified Version</link>. | ||
| 460 | Only one passage of Front-Cover Text and one of Back-Cover Text | ||
| 461 | may be added by (or through arrangements made by) any one | ||
| 462 | entity. If the <link linkend="fdl-document">Document</link> | ||
| 463 | already includes a cover text for the same cover, previously | ||
| 464 | added by you or by arrangement made by the same entity you are | ||
| 465 | acting on behalf of, you may not add another; but you may | ||
| 466 | replace the old one, on explicit permission from the previous | ||
| 467 | publisher that added the old one. | ||
| 468 | </para> | ||
| 469 | |||
| 470 | <para> | ||
| 471 | The author(s) and publisher(s) of the <link | ||
| 472 | linkend="fdl-document">Document</link> do not by this License | ||
| 473 | give permission to use their names for publicity for or to | ||
| 474 | assert or imply endorsement of any <link | ||
| 475 | linkend="fdl-modified">Modified Version </link>. | ||
| 476 | </para> | ||
| 477 | </sect1> | ||
| 478 | |||
| 479 | <sect1 id="fdl-section5"> | ||
| 480 | <title>5. COMBINING DOCUMENTS</title> | ||
| 481 | <para> | ||
| 482 | You may combine the <link linkend="fdl-document">Document</link> | ||
| 483 | with other documents released under this License, under the | ||
| 484 | terms defined in <link linkend="fdl-section4">section 4</link> | ||
| 485 | above for modified versions, provided that you include in the | ||
| 486 | combination all of the <link linkend="fdl-invariant">Invariant | ||
| 487 | Sections</link> of all of the original documents, unmodified, | ||
| 488 | and list them all as Invariant Sections of your combined work in | ||
| 489 | its license notice. | ||
| 490 | </para> | ||
| 491 | |||
| 492 | <para> | ||
| 493 | The combined work need only contain one copy of this License, | ||
| 494 | and multiple identical <link linkend="fdl-invariant">Invariant | ||
| 495 | Sections</link> may be replaced with a single copy. If there are | ||
| 496 | multiple Invariant Sections with the same name but different | ||
| 497 | contents, make the title of each such section unique by adding | ||
| 498 | at the end of it, in parentheses, the name of the original | ||
| 499 | author or publisher of that section if known, or else a unique | ||
| 500 | number. Make the same adjustment to the section titles in the | ||
| 501 | list of Invariant Sections in the license notice of the combined | ||
| 502 | work. | ||
| 503 | </para> | ||
| 504 | |||
| 505 | <para> | ||
| 506 | In the combination, you must combine any sections entitled | ||
| 507 | <quote>History</quote> in the various original documents, | ||
| 508 | forming one section entitled <quote>History</quote>; likewise | ||
| 509 | combine any sections entitled <quote>Acknowledgements</quote>, | ||
| 510 | and any sections entitled <quote>Dedications</quote>. You must | ||
| 511 | delete all sections entitled <quote>Endorsements.</quote> | ||
| 512 | </para> | ||
| 513 | </sect1> | ||
| 514 | |||
| 515 | <sect1 id="fdl-section6"> | ||
| 516 | <title>6. COLLECTIONS OF DOCUMENTS</title> | ||
| 517 | <para> | ||
| 518 | You may make a collection consisting of the <link | ||
| 519 | linkend="fdl-document">Document</link> and other documents | ||
| 520 | released under this License, and replace the individual copies | ||
| 521 | of this License in the various documents with a single copy that | ||
| 522 | is included in the collection, provided that you follow the | ||
| 523 | rules of this License for verbatim copying of each of the | ||
| 524 | documents in all other respects. | ||
| 525 | </para> | ||
| 526 | |||
| 527 | <para> | ||
| 528 | You may extract a single document from such a collection, and | ||
| 529 | dispbibute it individually under this License, provided you | ||
| 530 | insert a copy of this License into the extracted document, and | ||
| 531 | follow this License in all other respects regarding verbatim | ||
| 532 | copying of that document. | ||
| 533 | </para> | ||
| 534 | </sect1> | ||
| 535 | |||
| 536 | <sect1 id="fdl-section7"> | ||
| 537 | <title>7. AGGREGATION WITH INDEPENDENT WORKS</title> | ||
| 538 | <para> | ||
| 539 | A compilation of the <link | ||
| 540 | linkend="fdl-document">Document</link> or its derivatives with | ||
| 541 | other separate and independent documents or works, in or on a | ||
| 542 | volume of a storage or distribution medium, does not as a whole | ||
| 543 | count as a <link linkend="fdl-modified">Modified Version</link> | ||
| 544 | of the Document, provided no compilation copyright is claimed | ||
| 545 | for the compilation. Such a compilation is called an | ||
| 546 | <quote>aggregate</quote>, and this License does not apply to the | ||
| 547 | other self-contained works thus compiled with the Document , on | ||
| 548 | account of their being thus compiled, if they are not themselves | ||
| 549 | derivative works of the Document. If the <link | ||
| 550 | linkend="fdl-cover-texts">Cover Text</link> requirement of <link | ||
| 551 | linkend="fdl-section3">section 3</link> is applicable to these | ||
| 552 | copies of the Document, then if the Document is less than one | ||
| 553 | quarter of the entire aggregate, the Document's Cover Texts may | ||
| 554 | be placed on covers that surround only the Document within the | ||
| 555 | aggregate. Otherwise they must appear on covers around the whole | ||
| 556 | aggregate. | ||
| 557 | </para> | ||
| 558 | </sect1> | ||
| 559 | |||
| 560 | <sect1 id="fdl-section8"> | ||
| 561 | <title>8. TRANSLATION</title> | ||
| 562 | <para> | ||
| 563 | Translation is considered a kind of modification, so you may | ||
| 564 | distribute translations of the <link | ||
| 565 | linkend="fdl-document">Document</link> under the terms of <link | ||
| 566 | linkend="fdl-section4">section 4</link>. Replacing <link | ||
| 567 | linkend="fdl-invariant"> Invariant Sections</link> with | ||
| 568 | translations requires special permission from their copyright | ||
| 569 | holders, but you may include translations of some or all | ||
| 570 | Invariant Sections in addition to the original versions of these | ||
| 571 | Invariant Sections. You may include a translation of this | ||
| 572 | License provided that you also include the original English | ||
| 573 | version of this License. In case of a disagreement between the | ||
| 574 | translation and the original English version of this License, | ||
| 575 | the original English version will prevail. | ||
| 576 | </para> | ||
| 577 | </sect1> | ||
| 578 | |||
| 579 | <sect1 id="fdl-section9"> | ||
| 580 | <title>9. TERMINATION</title> | ||
| 581 | <para> | ||
| 582 | You may not copy, modify, sublicense, or distribute the <link | ||
| 583 | linkend="fdl-document">Document</link> except as expressly | ||
| 584 | provided for under this License. Any other attempt to copy, | ||
| 585 | modify, sublicense or distribute the Document is void, and will | ||
| 586 | automatically terminate your rights under this License. However, | ||
| 587 | parties who have received copies, or rights, from you under this | ||
| 588 | License will not have their licenses terminated so long as such | ||
| 589 | parties remain in full compliance. | ||
| 590 | </para> | ||
| 591 | </sect1> | ||
| 592 | |||
| 593 | <sect1 id="fdl-section10"> | ||
| 594 | <title>10. FUTURE REVISIONS OF THIS LICENSE</title> | ||
| 595 | <para> | ||
| 596 | The <ulink type="http" | ||
| 597 | url="http://www.gnu.org/fsf/fsf.html">Free Software | ||
| 598 | Foundation</ulink> may publish new, revised versions of the GNU | ||
| 599 | Free Documentation License from time to time. Such new versions | ||
| 600 | will be similar in spirit to the present version, but may differ | ||
| 601 | in detail to address new problems or concerns. See <ulink | ||
| 602 | type="http" | ||
| 603 | url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>. | ||
| 604 | </para> | ||
| 605 | |||
| 606 | <para> | ||
| 607 | Each version of the License is given a distinguishing version | ||
| 608 | number. If the <link linkend="fdl-document">Document</link> | ||
| 609 | specifies that a particular numbered version of this License | ||
| 610 | <quote>or any later version</quote> applies to it, you have the | ||
| 611 | option of following the terms and conditions either of that | ||
| 612 | specified version or of any later version that has been | ||
| 613 | published (not as a draft) by the Free Software Foundation. If | ||
| 614 | the Document does not specify a version number of this License, | ||
| 615 | you may choose any version ever published (not as a draft) by | ||
| 616 | the Free Software Foundation. | ||
| 617 | </para> | ||
| 618 | </sect1> | ||
| 619 | |||
| 620 | <sect1 id="fdl-using"> | ||
| 621 | <title>Addendum</title> | ||
| 622 | <para> | ||
| 623 | To use this License in a document you have written, include a copy of | ||
| 624 | the License in the document and put the following copyright and | ||
| 625 | license notices just after the title page: | ||
| 626 | </para> | ||
| 627 | |||
| 628 | <blockquote> | ||
| 629 | <para> | ||
| 630 | Copyright © YEAR YOUR NAME. | ||
| 631 | </para> | ||
| 632 | <para> | ||
| 633 | Permission is granted to copy, distribute and/or modify this | ||
| 634 | document under the terms of the GNU Free Documentation | ||
| 635 | License, Version 1.1 or any later version published by the | ||
| 636 | Free Software Foundation; with the <link | ||
| 637 | linkend="fdl-invariant">Invariant Sections</link> being LIST | ||
| 638 | THEIR TITLES, with the <link | ||
| 639 | linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST, | ||
| 640 | and with the <link linkend="fdl-cover-texts">Back-Cover | ||
| 641 | Texts</link> being LIST. A copy of the license is included in | ||
| 642 | the section entitled <quote>GNU Free Documentation | ||
| 643 | License</quote>. | ||
| 644 | </para> | ||
| 645 | </blockquote> | ||
| 646 | |||
| 647 | <para> | ||
| 648 | If you have no <link linkend="fdl-invariant">Invariant | ||
| 649 | Sections</link>, write <quote>with no Invariant Sections</quote> | ||
| 650 | instead of saying which ones are invariant. If you have no | ||
| 651 | <link linkend="fdl-cover-texts">Front-Cover Texts</link>, write | ||
| 652 | <quote>no Front-Cover Texts</quote> instead of | ||
| 653 | <quote>Front-Cover Texts being LIST</quote>; likewise for <link | ||
| 654 | linkend="fdl-cover-texts">Back-Cover Texts</link>. | ||
| 655 | </para> | ||
| 656 | |||
| 657 | <para> | ||
| 658 | If your document contains nontrivial examples of program code, | ||
| 659 | we recommend releasing these examples in parallel under your | ||
| 660 | choice of free software license, such as the <ulink type="http" | ||
| 661 | url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public | ||
| 662 | License</ulink>, to permit their use in free software. | ||
| 663 | </para> | ||
| 664 | </sect1> | ||
| 665 | </appendix> | ||
| 666 | |||
| 667 | |||
| 668 | |||
| 669 | |||
| 670 | |||
| 671 | |||
diff --git a/Documentation/DocBook/v4l/fieldseq_bt.gif b/Documentation/DocBook/v4l/fieldseq_bt.gif new file mode 100644 index 000000000000..60e8569a76c9 --- /dev/null +++ b/Documentation/DocBook/v4l/fieldseq_bt.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/fieldseq_bt.pdf b/Documentation/DocBook/v4l/fieldseq_bt.pdf new file mode 100644 index 000000000000..26598b23f80d --- /dev/null +++ b/Documentation/DocBook/v4l/fieldseq_bt.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/fieldseq_tb.gif b/Documentation/DocBook/v4l/fieldseq_tb.gif new file mode 100644 index 000000000000..718492f1cfc7 --- /dev/null +++ b/Documentation/DocBook/v4l/fieldseq_tb.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/fieldseq_tb.pdf b/Documentation/DocBook/v4l/fieldseq_tb.pdf new file mode 100644 index 000000000000..4965b22ddb3a --- /dev/null +++ b/Documentation/DocBook/v4l/fieldseq_tb.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/func-close.xml b/Documentation/DocBook/v4l/func-close.xml new file mode 100644 index 000000000000..dfb41cbbbec3 --- /dev/null +++ b/Documentation/DocBook/v4l/func-close.xml | |||
| @@ -0,0 +1,70 @@ | |||
| 1 | <refentry id="func-close"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 close()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-close</refname> | ||
| 9 | <refpurpose>Close a V4L2 device</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>close</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | </funcprototype> | ||
| 19 | </funcsynopsis> | ||
| 20 | </refsynopsisdiv> | ||
| 21 | |||
| 22 | <refsect1> | ||
| 23 | <title>Arguments</title> | ||
| 24 | |||
| 25 | <variablelist> | ||
| 26 | <varlistentry> | ||
| 27 | <term><parameter>fd</parameter></term> | ||
| 28 | <listitem> | ||
| 29 | <para>&fd;</para> | ||
| 30 | </listitem> | ||
| 31 | </varlistentry> | ||
| 32 | </variablelist> | ||
| 33 | </refsect1> | ||
| 34 | |||
| 35 | <refsect1> | ||
| 36 | <title>Description</title> | ||
| 37 | |||
| 38 | <para>Closes the device. Any I/O in progress is terminated and | ||
| 39 | resources associated with the file descriptor are freed. However data | ||
| 40 | format parameters, current input or output, control values or other | ||
| 41 | properties remain unchanged.</para> | ||
| 42 | </refsect1> | ||
| 43 | |||
| 44 | <refsect1> | ||
| 45 | <title>Return Value</title> | ||
| 46 | |||
| 47 | <para>The function returns <returnvalue>0</returnvalue> on | ||
| 48 | success, <returnvalue>-1</returnvalue> on failure and the | ||
| 49 | <varname>errno</varname> is set appropriately. Possible error | ||
| 50 | codes:</para> | ||
| 51 | |||
| 52 | <variablelist> | ||
| 53 | <varlistentry> | ||
| 54 | <term><errorcode>EBADF</errorcode></term> | ||
| 55 | <listitem> | ||
| 56 | <para><parameter>fd</parameter> is not a valid open file | ||
| 57 | descriptor.</para> | ||
| 58 | </listitem> | ||
| 59 | </varlistentry> | ||
| 60 | </variablelist> | ||
| 61 | </refsect1> | ||
| 62 | </refentry> | ||
| 63 | |||
| 64 | <!-- | ||
| 65 | Local Variables: | ||
| 66 | mode: sgml | ||
| 67 | sgml-parent-document: "v4l2.sgml" | ||
| 68 | indent-tabs-mode: nil | ||
| 69 | End: | ||
| 70 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-ioctl.xml b/Documentation/DocBook/v4l/func-ioctl.xml new file mode 100644 index 000000000000..00f9690e1c28 --- /dev/null +++ b/Documentation/DocBook/v4l/func-ioctl.xml | |||
| @@ -0,0 +1,146 @@ | |||
| 1 | <refentry id="func-ioctl"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 ioctl()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-ioctl</refname> | ||
| 9 | <refpurpose>Program a V4L2 device</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <sys/ioctl.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>void *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>V4L2 ioctl request code as defined in the <link | ||
| 38 | linkend="videodev">videodev.h</link> header file, for example | ||
| 39 | VIDIOC_QUERYCAP.</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>argp</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>Pointer to a function parameter, usually a structure.</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | </variablelist> | ||
| 49 | </refsect1> | ||
| 50 | |||
| 51 | <refsect1> | ||
| 52 | <title>Description</title> | ||
| 53 | |||
| 54 | <para>The <function>ioctl()</function> function is used to program | ||
| 55 | V4L2 devices. The argument <parameter>fd</parameter> must be an open | ||
| 56 | file descriptor. An ioctl <parameter>request</parameter> has encoded | ||
| 57 | in it whether the argument is an input, output or read/write | ||
| 58 | parameter, and the size of the argument <parameter>argp</parameter> in | ||
| 59 | bytes. Macros and defines specifying V4L2 ioctl requests are located | ||
| 60 | in the <link linkend="videodev">videodev.h</link> header file. | ||
| 61 | Applications should use their own copy, not include the version in the | ||
| 62 | kernel sources on the system they compile on. All V4L2 ioctl requests, | ||
| 63 | their respective function and parameters are specified in <xref | ||
| 64 | linkend="user-func" />.</para> | ||
| 65 | </refsect1> | ||
| 66 | |||
| 67 | <refsect1> | ||
| 68 | <title>Return Value</title> | ||
| 69 | |||
| 70 | <para>On success the <function>ioctl()</function> function returns | ||
| 71 | <returnvalue>0</returnvalue> and does not reset the | ||
| 72 | <varname>errno</varname> variable. On failure | ||
| 73 | <returnvalue>-1</returnvalue> is returned, when the ioctl takes an | ||
| 74 | output or read/write parameter it remains unmodified, and the | ||
| 75 | <varname>errno</varname> variable is set appropriately. See below for | ||
| 76 | possible error codes. Generic errors like <errorcode>EBADF</errorcode> | ||
| 77 | or <errorcode>EFAULT</errorcode> are not listed in the sections | ||
| 78 | discussing individual ioctl requests.</para> | ||
| 79 | <para>Note ioctls may return undefined error codes. Since errors | ||
| 80 | may have side effects such as a driver reset applications should | ||
| 81 | abort on unexpected errors.</para> | ||
| 82 | |||
| 83 | <variablelist> | ||
| 84 | <varlistentry> | ||
| 85 | <term><errorcode>EBADF</errorcode></term> | ||
| 86 | <listitem> | ||
| 87 | <para><parameter>fd</parameter> is not a valid open file | ||
| 88 | descriptor.</para> | ||
| 89 | </listitem> | ||
| 90 | </varlistentry> | ||
| 91 | <varlistentry> | ||
| 92 | <term><errorcode>EBUSY</errorcode></term> | ||
| 93 | <listitem> | ||
| 94 | <para>The property cannot be changed right now. Typically | ||
| 95 | this error code is returned when I/O is in progress or the driver | ||
| 96 | supports multiple opens and another process locked the property.</para> | ||
| 97 | </listitem> | ||
| 98 | </varlistentry> | ||
| 99 | <varlistentry> | ||
| 100 | <term><errorcode>EFAULT</errorcode></term> | ||
| 101 | <listitem> | ||
| 102 | <para><parameter>argp</parameter> references an inaccessible | ||
| 103 | memory area.</para> | ||
| 104 | </listitem> | ||
| 105 | </varlistentry> | ||
| 106 | <varlistentry> | ||
| 107 | <term><errorcode>ENOTTY</errorcode></term> | ||
| 108 | <listitem> | ||
| 109 | <para><parameter>fd</parameter> is not associated with a | ||
| 110 | character special device.</para> | ||
| 111 | </listitem> | ||
| 112 | </varlistentry> | ||
| 113 | <varlistentry> | ||
| 114 | <term><errorcode>EINVAL</errorcode></term> | ||
| 115 | <listitem> | ||
| 116 | <para>The <parameter>request</parameter> or the data pointed | ||
| 117 | to by <parameter>argp</parameter> is not valid. This is a very common | ||
| 118 | error code, see the individual ioctl requests listed in <xref | ||
| 119 | linkend="user-func" /> for actual causes.</para> | ||
| 120 | </listitem> | ||
| 121 | </varlistentry> | ||
| 122 | <varlistentry> | ||
| 123 | <term><errorcode>ENOMEM</errorcode></term> | ||
| 124 | <listitem> | ||
| 125 | <para>Not enough physical or virtual memory was available to | ||
| 126 | complete the request.</para> | ||
| 127 | </listitem> | ||
| 128 | </varlistentry> | ||
| 129 | <varlistentry> | ||
| 130 | <term><errorcode>ERANGE</errorcode></term> | ||
| 131 | <listitem> | ||
| 132 | <para>The application attempted to set a control with the | ||
| 133 | &VIDIOC-S-CTRL; ioctl to a value which is out of bounds.</para> | ||
| 134 | </listitem> | ||
| 135 | </varlistentry> | ||
| 136 | </variablelist> | ||
| 137 | </refsect1> | ||
| 138 | </refentry> | ||
| 139 | |||
| 140 | <!-- | ||
| 141 | Local Variables: | ||
| 142 | mode: sgml | ||
| 143 | sgml-parent-document: "v4l2.sgml" | ||
| 144 | indent-tabs-mode: nil | ||
| 145 | End: | ||
| 146 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-mmap.xml b/Documentation/DocBook/v4l/func-mmap.xml new file mode 100644 index 000000000000..2e2fc3933aea --- /dev/null +++ b/Documentation/DocBook/v4l/func-mmap.xml | |||
| @@ -0,0 +1,185 @@ | |||
| 1 | <refentry id="func-mmap"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 mmap()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-mmap</refname> | ||
| 9 | <refpurpose>Map device memory into application address space</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo> | ||
| 15 | #include <unistd.h> | ||
| 16 | #include <sys/mman.h></funcsynopsisinfo> | ||
| 17 | <funcprototype> | ||
| 18 | <funcdef>void *<function>mmap</function></funcdef> | ||
| 19 | <paramdef>void *<parameter>start</parameter></paramdef> | ||
| 20 | <paramdef>size_t <parameter>length</parameter></paramdef> | ||
| 21 | <paramdef>int <parameter>prot</parameter></paramdef> | ||
| 22 | <paramdef>int <parameter>flags</parameter></paramdef> | ||
| 23 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 24 | <paramdef>off_t <parameter>offset</parameter></paramdef> | ||
| 25 | </funcprototype> | ||
| 26 | </funcsynopsis> | ||
| 27 | </refsynopsisdiv> | ||
| 28 | |||
| 29 | <refsect1> | ||
| 30 | <title>Arguments</title> | ||
| 31 | <variablelist> | ||
| 32 | <varlistentry> | ||
| 33 | <term><parameter>start</parameter></term> | ||
| 34 | <listitem> | ||
| 35 | <para>Map the buffer to this address in the | ||
| 36 | application's address space. When the <constant>MAP_FIXED</constant> | ||
| 37 | flag is specified, <parameter>start</parameter> must be a multiple of the | ||
| 38 | pagesize and mmap will fail when the specified address | ||
| 39 | cannot be used. Use of this option is discouraged; applications should | ||
| 40 | just specify a <constant>NULL</constant> pointer here.</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | <varlistentry> | ||
| 44 | <term><parameter>length</parameter></term> | ||
| 45 | <listitem> | ||
| 46 | <para>Length of the memory area to map. This must be the | ||
| 47 | same value as returned by the driver in the &v4l2-buffer; | ||
| 48 | <structfield>length</structfield> field.</para> | ||
| 49 | </listitem> | ||
| 50 | </varlistentry> | ||
| 51 | <varlistentry> | ||
| 52 | <term><parameter>prot</parameter></term> | ||
| 53 | <listitem> | ||
| 54 | <para>The <parameter>prot</parameter> argument describes the | ||
| 55 | desired memory protection. Regardless of the device type and the | ||
| 56 | direction of data exchange it should be set to | ||
| 57 | <constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>, | ||
| 58 | permitting read and write access to image buffers. Drivers should | ||
| 59 | support at least this combination of flags. Note the Linux | ||
| 60 | <filename>video-buf</filename> kernel module, which is used by the | ||
| 61 | bttv, saa7134, saa7146, cx88 and vivi driver supports only | ||
| 62 | <constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When | ||
| 63 | the driver does not support the desired protection the | ||
| 64 | <function>mmap()</function> function fails.</para> | ||
| 65 | <para>Note device memory accesses (⪚ the memory on a | ||
| 66 | graphics card with video capturing hardware) may incur a performance | ||
| 67 | penalty compared to main memory accesses, or reads may be | ||
| 68 | significantly slower than writes or vice versa. Other I/O methods may | ||
| 69 | be more efficient in this case.</para> | ||
| 70 | </listitem> | ||
| 71 | </varlistentry> | ||
| 72 | <varlistentry> | ||
| 73 | <term><parameter>flags</parameter></term> | ||
| 74 | <listitem> | ||
| 75 | <para>The <parameter>flags</parameter> parameter | ||
| 76 | specifies the type of the mapped object, mapping options and whether | ||
| 77 | modifications made to the mapped copy of the page are private to the | ||
| 78 | process or are to be shared with other references.</para> | ||
| 79 | <para><constant>MAP_FIXED</constant> requests that the | ||
| 80 | driver selects no other address than the one specified. If the | ||
| 81 | specified address cannot be used, <function>mmap()</function> will fail. If | ||
| 82 | <constant>MAP_FIXED</constant> is specified, | ||
| 83 | <parameter>start</parameter> must be a multiple of the pagesize. Use | ||
| 84 | of this option is discouraged.</para> | ||
| 85 | <para>One of the <constant>MAP_SHARED</constant> or | ||
| 86 | <constant>MAP_PRIVATE</constant> flags must be set. | ||
| 87 | <constant>MAP_SHARED</constant> allows applications to share the | ||
| 88 | mapped memory with other (⪚ child-) processes. Note the Linux | ||
| 89 | <filename>video-buf</filename> module which is used by the bttv, | ||
| 90 | saa7134, saa7146, cx88 and vivi driver supports only | ||
| 91 | <constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant> | ||
| 92 | requests copy-on-write semantics. V4L2 applications should not set the | ||
| 93 | <constant>MAP_PRIVATE</constant>, <constant>MAP_DENYWRITE</constant>, | ||
| 94 | <constant>MAP_EXECUTABLE</constant> or <constant>MAP_ANON</constant> | ||
| 95 | flag.</para> | ||
| 96 | </listitem> | ||
| 97 | </varlistentry> | ||
| 98 | <varlistentry> | ||
| 99 | <term><parameter>fd</parameter></term> | ||
| 100 | <listitem> | ||
| 101 | <para>&fd;</para> | ||
| 102 | </listitem> | ||
| 103 | </varlistentry> | ||
| 104 | <varlistentry> | ||
| 105 | <term><parameter>offset</parameter></term> | ||
| 106 | <listitem> | ||
| 107 | <para>Offset of the buffer in device memory. This must be the | ||
| 108 | same value as returned by the driver in the &v4l2-buffer; | ||
| 109 | <structfield>m</structfield> union <structfield>offset</structfield> field.</para> | ||
| 110 | </listitem> | ||
| 111 | </varlistentry> | ||
| 112 | </variablelist> | ||
| 113 | </refsect1> | ||
| 114 | |||
| 115 | <refsect1> | ||
| 116 | <title>Description</title> | ||
| 117 | |||
| 118 | <para>The <function>mmap()</function> function asks to map | ||
| 119 | <parameter>length</parameter> bytes starting at | ||
| 120 | <parameter>offset</parameter> in the memory of the device specified by | ||
| 121 | <parameter>fd</parameter> into the application address space, | ||
| 122 | preferably at address <parameter>start</parameter>. This latter | ||
| 123 | address is a hint only, and is usually specified as 0.</para> | ||
| 124 | |||
| 125 | <para>Suitable length and offset parameters are queried with the | ||
| 126 | &VIDIOC-QUERYBUF; ioctl. Buffers must be allocated with the | ||
| 127 | &VIDIOC-REQBUFS; ioctl before they can be queried.</para> | ||
| 128 | |||
| 129 | <para>To unmap buffers the &func-munmap; function is used.</para> | ||
| 130 | </refsect1> | ||
| 131 | |||
| 132 | <refsect1> | ||
| 133 | <title>Return Value</title> | ||
| 134 | |||
| 135 | <para>On success <function>mmap()</function> returns a pointer to | ||
| 136 | the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is | ||
| 137 | returned, and the <varname>errno</varname> variable is set | ||
| 138 | appropriately. Possible error codes are:</para> | ||
| 139 | |||
| 140 | <variablelist> | ||
| 141 | <varlistentry> | ||
| 142 | <term><errorcode>EBADF</errorcode></term> | ||
| 143 | <listitem> | ||
| 144 | <para><parameter>fd</parameter> is not a valid file | ||
| 145 | descriptor.</para> | ||
| 146 | </listitem> | ||
| 147 | </varlistentry> | ||
| 148 | <varlistentry> | ||
| 149 | <term><errorcode>EACCES</errorcode></term> | ||
| 150 | <listitem> | ||
| 151 | <para><parameter>fd</parameter> is | ||
| 152 | not open for reading and writing.</para> | ||
| 153 | </listitem> | ||
| 154 | </varlistentry> | ||
| 155 | <varlistentry> | ||
| 156 | <term><errorcode>EINVAL</errorcode></term> | ||
| 157 | <listitem> | ||
| 158 | <para>The <parameter>start</parameter> or | ||
| 159 | <parameter>length</parameter> or <parameter>offset</parameter> are not | ||
| 160 | suitable. (E. g. they are too large, or not aligned on a | ||
| 161 | <constant>PAGESIZE</constant> boundary.)</para> | ||
| 162 | <para>The <parameter>flags</parameter> or | ||
| 163 | <parameter>prot</parameter> value is not supported.</para> | ||
| 164 | <para>No buffers have been allocated with the | ||
| 165 | &VIDIOC-REQBUFS; ioctl.</para> | ||
| 166 | </listitem> | ||
| 167 | </varlistentry> | ||
| 168 | <varlistentry> | ||
| 169 | <term><errorcode>ENOMEM</errorcode></term> | ||
| 170 | <listitem> | ||
| 171 | <para>Not enough physical or virtual memory was available to | ||
| 172 | complete the request.</para> | ||
| 173 | </listitem> | ||
| 174 | </varlistentry> | ||
| 175 | </variablelist> | ||
| 176 | </refsect1> | ||
| 177 | </refentry> | ||
| 178 | |||
| 179 | <!-- | ||
| 180 | Local Variables: | ||
| 181 | mode: sgml | ||
| 182 | sgml-parent-document: "v4l2.sgml" | ||
| 183 | indent-tabs-mode: nil | ||
| 184 | End: | ||
| 185 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-munmap.xml b/Documentation/DocBook/v4l/func-munmap.xml new file mode 100644 index 000000000000..502ed49323b0 --- /dev/null +++ b/Documentation/DocBook/v4l/func-munmap.xml | |||
| @@ -0,0 +1,83 @@ | |||
| 1 | <refentry id="func-munmap"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 munmap()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-munmap</refname> | ||
| 9 | <refpurpose>Unmap device memory</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo> | ||
| 15 | #include <unistd.h> | ||
| 16 | #include <sys/mman.h></funcsynopsisinfo> | ||
| 17 | <funcprototype> | ||
| 18 | <funcdef>int <function>munmap</function></funcdef> | ||
| 19 | <paramdef>void *<parameter>start</parameter></paramdef> | ||
| 20 | <paramdef>size_t <parameter>length</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | </refsynopsisdiv> | ||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>start</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>Address of the mapped buffer as returned by the | ||
| 31 | &func-mmap; function.</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>length</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>Length of the mapped buffer. This must be the same | ||
| 38 | value as given to <function>mmap()</function> and returned by the | ||
| 39 | driver in the &v4l2-buffer; <structfield>length</structfield> | ||
| 40 | field.</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | </variablelist> | ||
| 44 | </refsect1> | ||
| 45 | |||
| 46 | <refsect1> | ||
| 47 | <title>Description</title> | ||
| 48 | |||
| 49 | <para>Unmaps a previously with the &func-mmap; function mapped | ||
| 50 | buffer and frees it, if possible. <!-- ? This function (not freeing) | ||
| 51 | has no impact on I/O in progress, specifically it does not imply | ||
| 52 | &VIDIOC-STREAMOFF; to terminate I/O. Unmapped buffers can still be | ||
| 53 | enqueued, dequeued or queried, they are just not accessible by the | ||
| 54 | application.--></para> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Return Value</title> | ||
| 59 | |||
| 60 | <para>On success <function>munmap()</function> returns 0, on | ||
| 61 | failure -1 and the <varname>errno</varname> variable is set | ||
| 62 | appropriately:</para> | ||
| 63 | |||
| 64 | <variablelist> | ||
| 65 | <varlistentry> | ||
| 66 | <term><errorcode>EINVAL</errorcode></term> | ||
| 67 | <listitem> | ||
| 68 | <para>The <parameter>start</parameter> or | ||
| 69 | <parameter>length</parameter> is incorrect, or no buffers have been | ||
| 70 | mapped yet.</para> | ||
| 71 | </listitem> | ||
| 72 | </varlistentry> | ||
| 73 | </variablelist> | ||
| 74 | </refsect1> | ||
| 75 | </refentry> | ||
| 76 | |||
| 77 | <!-- | ||
| 78 | Local Variables: | ||
| 79 | mode: sgml | ||
| 80 | sgml-parent-document: "v4l2.sgml" | ||
| 81 | indent-tabs-mode: nil | ||
| 82 | End: | ||
| 83 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-open.xml b/Documentation/DocBook/v4l/func-open.xml new file mode 100644 index 000000000000..7595d07a8c72 --- /dev/null +++ b/Documentation/DocBook/v4l/func-open.xml | |||
| @@ -0,0 +1,121 @@ | |||
| 1 | <refentry id="func-open"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 open()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-open</refname> | ||
| 9 | <refpurpose>Open a V4L2 device</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <fcntl.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>open</function></funcdef> | ||
| 17 | <paramdef>const char *<parameter>device_name</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>flags</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>device_name</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>Device to be opened.</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>flags</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>Open flags. Access mode must be | ||
| 37 | <constant>O_RDWR</constant>. This is just a technicality, input devices | ||
| 38 | still support only reading and output devices only writing.</para> | ||
| 39 | <para>When the <constant>O_NONBLOCK</constant> flag is | ||
| 40 | given, the read() function and the &VIDIOC-DQBUF; ioctl will return | ||
| 41 | the &EAGAIN; when no data is available or no buffer is in the driver | ||
| 42 | outgoing queue, otherwise these functions block until data becomes | ||
| 43 | available. All V4L2 drivers exchanging data with applications must | ||
| 44 | support the <constant>O_NONBLOCK</constant> flag.</para> | ||
| 45 | <para>Other flags have no effect.</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | </variablelist> | ||
| 49 | </refsect1> | ||
| 50 | <refsect1> | ||
| 51 | <title>Description</title> | ||
| 52 | |||
| 53 | <para>To open a V4L2 device applications call | ||
| 54 | <function>open()</function> with the desired device name. This | ||
| 55 | function has no side effects; all data format parameters, current | ||
| 56 | input or output, control values or other properties remain unchanged. | ||
| 57 | At the first <function>open()</function> call after loading the driver | ||
| 58 | they will be reset to default values, drivers are never in an | ||
| 59 | undefined state.</para> | ||
| 60 | </refsect1> | ||
| 61 | <refsect1> | ||
| 62 | <title>Return Value</title> | ||
| 63 | |||
| 64 | <para>On success <function>open</function> returns the new file | ||
| 65 | descriptor. On error -1 is returned, and the <varname>errno</varname> | ||
| 66 | variable is set appropriately. Possible error codes are:</para> | ||
| 67 | |||
| 68 | <variablelist> | ||
| 69 | <varlistentry> | ||
| 70 | <term><errorcode>EACCES</errorcode></term> | ||
| 71 | <listitem> | ||
| 72 | <para>The caller has no permission to access the | ||
| 73 | device.</para> | ||
| 74 | </listitem> | ||
| 75 | </varlistentry> | ||
| 76 | <varlistentry> | ||
| 77 | <term><errorcode>EBUSY</errorcode></term> | ||
| 78 | <listitem> | ||
| 79 | <para>The driver does not support multiple opens and the | ||
| 80 | device is already in use.</para> | ||
| 81 | </listitem> | ||
| 82 | </varlistentry> | ||
| 83 | <varlistentry> | ||
| 84 | <term><errorcode>ENXIO</errorcode></term> | ||
| 85 | <listitem> | ||
| 86 | <para>No device corresponding to this device special file | ||
| 87 | exists.</para> | ||
| 88 | </listitem> | ||
| 89 | </varlistentry> | ||
| 90 | <varlistentry> | ||
| 91 | <term><errorcode>ENOMEM</errorcode></term> | ||
| 92 | <listitem> | ||
| 93 | <para>Not enough kernel memory was available to complete the | ||
| 94 | request.</para> | ||
| 95 | </listitem> | ||
| 96 | </varlistentry> | ||
| 97 | <varlistentry> | ||
| 98 | <term><errorcode>EMFILE</errorcode></term> | ||
| 99 | <listitem> | ||
| 100 | <para>The process already has the maximum number of | ||
| 101 | files open.</para> | ||
| 102 | </listitem> | ||
| 103 | </varlistentry> | ||
| 104 | <varlistentry> | ||
| 105 | <term><errorcode>ENFILE</errorcode></term> | ||
| 106 | <listitem> | ||
| 107 | <para>The limit on the total number of files open on the | ||
| 108 | system has been reached.</para> | ||
| 109 | </listitem> | ||
| 110 | </varlistentry> | ||
| 111 | </variablelist> | ||
| 112 | </refsect1> | ||
| 113 | </refentry> | ||
| 114 | |||
| 115 | <!-- | ||
| 116 | Local Variables: | ||
| 117 | mode: sgml | ||
| 118 | sgml-parent-document: "v4l2.sgml" | ||
| 119 | indent-tabs-mode: nil | ||
| 120 | End: | ||
| 121 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-poll.xml b/Documentation/DocBook/v4l/func-poll.xml new file mode 100644 index 000000000000..ec3c718f5963 --- /dev/null +++ b/Documentation/DocBook/v4l/func-poll.xml | |||
| @@ -0,0 +1,127 @@ | |||
| 1 | <refentry id="func-poll"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 poll()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-poll</refname> | ||
| 9 | <refpurpose>Wait for some event on a file descriptor</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <sys/poll.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>poll</function></funcdef> | ||
| 17 | <paramdef>struct pollfd *<parameter>ufds</parameter></paramdef> | ||
| 18 | <paramdef>unsigned int <parameter>nfds</parameter></paramdef> | ||
| 19 | <paramdef>int <parameter>timeout</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Description</title> | ||
| 26 | |||
| 27 | <para>With the <function>poll()</function> function applications | ||
| 28 | can suspend execution until the driver has captured data or is ready | ||
| 29 | to accept data for output.</para> | ||
| 30 | |||
| 31 | <para>When streaming I/O has been negotiated this function waits | ||
| 32 | until a buffer has been filled or displayed and can be dequeued with | ||
| 33 | the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing | ||
| 34 | queue of the driver the function returns immediately.</para> | ||
| 35 | |||
| 36 | <para>On success <function>poll()</function> returns the number of | ||
| 37 | file descriptors that have been selected (that is, file descriptors | ||
| 38 | for which the <structfield>revents</structfield> field of the | ||
| 39 | respective <structname>pollfd</structname> structure is non-zero). | ||
| 40 | Capture devices set the <constant>POLLIN</constant> and | ||
| 41 | <constant>POLLRDNORM</constant> flags in the | ||
| 42 | <structfield>revents</structfield> field, output devices the | ||
| 43 | <constant>POLLOUT</constant> and <constant>POLLWRNORM</constant> | ||
| 44 | flags. When the function timed out it returns a value of zero, on | ||
| 45 | failure it returns <returnvalue>-1</returnvalue> and the | ||
| 46 | <varname>errno</varname> variable is set appropriately. When the | ||
| 47 | application did not call &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the | ||
| 48 | <function>poll()</function> function succeeds, but sets the | ||
| 49 | <constant>POLLERR</constant> flag in the | ||
| 50 | <structfield>revents</structfield> field.</para> | ||
| 51 | |||
| 52 | <para>When use of the <function>read()</function> function has | ||
| 53 | been negotiated and the driver does not capture yet, the | ||
| 54 | <function>poll</function> function starts capturing. When that fails | ||
| 55 | it returns a <constant>POLLERR</constant> as above. Otherwise it waits | ||
| 56 | until data has been captured and can be read. When the driver captures | ||
| 57 | continuously (as opposed to, for example, still images) the function | ||
| 58 | may return immediately.</para> | ||
| 59 | |||
| 60 | <para>When use of the <function>write()</function> function has | ||
| 61 | been negotiated the <function>poll</function> function just waits | ||
| 62 | until the driver is ready for a non-blocking | ||
| 63 | <function>write()</function> call.</para> | ||
| 64 | |||
| 65 | <para>All drivers implementing the <function>read()</function> or | ||
| 66 | <function>write()</function> function or streaming I/O must also | ||
| 67 | support the <function>poll()</function> function.</para> | ||
| 68 | |||
| 69 | <para>For more details see the | ||
| 70 | <function>poll()</function> manual page.</para> | ||
| 71 | </refsect1> | ||
| 72 | |||
| 73 | <refsect1> | ||
| 74 | <title>Return Value</title> | ||
| 75 | |||
| 76 | <para>On success, <function>poll()</function> returns the number | ||
| 77 | structures which have non-zero <structfield>revents</structfield> | ||
| 78 | fields, or zero if the call timed out. On error | ||
| 79 | <returnvalue>-1</returnvalue> is returned, and the | ||
| 80 | <varname>errno</varname> variable is set appropriately:</para> | ||
| 81 | |||
| 82 | <variablelist> | ||
| 83 | <varlistentry> | ||
| 84 | <term><errorcode>EBADF</errorcode></term> | ||
| 85 | <listitem> | ||
| 86 | <para>One or more of the <parameter>ufds</parameter> members | ||
| 87 | specify an invalid file descriptor.</para> | ||
| 88 | </listitem> | ||
| 89 | </varlistentry> | ||
| 90 | <varlistentry> | ||
| 91 | <term><errorcode>EBUSY</errorcode></term> | ||
| 92 | <listitem> | ||
| 93 | <para>The driver does not support multiple read or write | ||
| 94 | streams and the device is already in use.</para> | ||
| 95 | </listitem> | ||
| 96 | </varlistentry> | ||
| 97 | <varlistentry> | ||
| 98 | <term><errorcode>EFAULT</errorcode></term> | ||
| 99 | <listitem> | ||
| 100 | <para><parameter>ufds</parameter> references an inaccessible | ||
| 101 | memory area.</para> | ||
| 102 | </listitem> | ||
| 103 | </varlistentry> | ||
| 104 | <varlistentry> | ||
| 105 | <term><errorcode>EINTR</errorcode></term> | ||
| 106 | <listitem> | ||
| 107 | <para>The call was interrupted by a signal.</para> | ||
| 108 | </listitem> | ||
| 109 | </varlistentry> | ||
| 110 | <varlistentry> | ||
| 111 | <term><errorcode>EINVAL</errorcode></term> | ||
| 112 | <listitem> | ||
| 113 | <para>The <parameter>nfds</parameter> argument is greater | ||
| 114 | than <constant>OPEN_MAX</constant>.</para> | ||
| 115 | </listitem> | ||
| 116 | </varlistentry> | ||
| 117 | </variablelist> | ||
| 118 | </refsect1> | ||
| 119 | </refentry> | ||
| 120 | |||
| 121 | <!-- | ||
| 122 | Local Variables: | ||
| 123 | mode: sgml | ||
| 124 | sgml-parent-document: "v4l2.sgml" | ||
| 125 | indent-tabs-mode: nil | ||
| 126 | End: | ||
| 127 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-read.xml b/Documentation/DocBook/v4l/func-read.xml new file mode 100644 index 000000000000..a5089bf8873d --- /dev/null +++ b/Documentation/DocBook/v4l/func-read.xml | |||
| @@ -0,0 +1,189 @@ | |||
| 1 | <refentry id="func-read"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 read()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-read</refname> | ||
| 9 | <refpurpose>Read from a V4L2 device</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>ssize_t <function>read</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>void *<parameter>buf</parameter></paramdef> | ||
| 19 | <paramdef>size_t <parameter>count</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>buf</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para></para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>count</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para><function>read()</function> attempts to read up to | ||
| 53 | <parameter>count</parameter> bytes from file descriptor | ||
| 54 | <parameter>fd</parameter> into the buffer starting at | ||
| 55 | <parameter>buf</parameter>. The layout of the data in the buffer is | ||
| 56 | discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero, | ||
| 57 | <function>read()</function> returns zero and has no other results. If | ||
| 58 | <parameter>count</parameter> is greater than | ||
| 59 | <constant>SSIZE_MAX</constant>, the result is unspecified. Regardless | ||
| 60 | of the <parameter>count</parameter> value each | ||
| 61 | <function>read()</function> call will provide at most one frame (two | ||
| 62 | fields) worth of data.</para> | ||
| 63 | |||
| 64 | <para>By default <function>read()</function> blocks until data | ||
| 65 | becomes available. When the <constant>O_NONBLOCK</constant> flag was | ||
| 66 | given to the &func-open; function it | ||
| 67 | returns immediately with an &EAGAIN; when no data is available. The | ||
| 68 | &func-select; or &func-poll; functions | ||
| 69 | can always be used to suspend execution until data becomes available. All | ||
| 70 | drivers supporting the <function>read()</function> function must also | ||
| 71 | support <function>select()</function> and | ||
| 72 | <function>poll()</function>.</para> | ||
| 73 | |||
| 74 | <para>Drivers can implement read functionality in different | ||
| 75 | ways, using a single or multiple buffers and discarding the oldest or | ||
| 76 | newest frames once the internal buffers are filled.</para> | ||
| 77 | |||
| 78 | <para><function>read()</function> never returns a "snapshot" of a | ||
| 79 | buffer being filled. Using a single buffer the driver will stop | ||
| 80 | capturing when the application starts reading the buffer until the | ||
| 81 | read is finished. Thus only the period of the vertical blanking | ||
| 82 | interval is available for reading, or the capture rate must fall below | ||
| 83 | the nominal frame rate of the video standard.</para> | ||
| 84 | |||
| 85 | <para>The behavior of | ||
| 86 | <function>read()</function> when called during the active picture | ||
| 87 | period or the vertical blanking separating the top and bottom field | ||
| 88 | depends on the discarding policy. A driver discarding the oldest | ||
| 89 | frames keeps capturing into an internal buffer, continuously | ||
| 90 | overwriting the previously, not read frame, and returns the frame | ||
| 91 | being received at the time of the <function>read()</function> call as | ||
| 92 | soon as it is complete.</para> | ||
| 93 | |||
| 94 | <para>A driver discarding the newest frames stops capturing until | ||
| 95 | the next <function>read()</function> call. The frame being received at | ||
| 96 | <function>read()</function> time is discarded, returning the following | ||
| 97 | frame instead. Again this implies a reduction of the capture rate to | ||
| 98 | one half or less of the nominal frame rate. An example of this model | ||
| 99 | is the video read mode of the bttv driver, initiating a DMA to user | ||
| 100 | memory when <function>read()</function> is called and returning when | ||
| 101 | the DMA finished.</para> | ||
| 102 | |||
| 103 | <para>In the multiple buffer model drivers maintain a ring of | ||
| 104 | internal buffers, automatically advancing to the next free buffer. | ||
| 105 | This allows continuous capturing when the application can empty the | ||
| 106 | buffers fast enough. Again, the behavior when the driver runs out of | ||
| 107 | free buffers depends on the discarding policy.</para> | ||
| 108 | |||
| 109 | <para>Applications can get and set the number of buffers used | ||
| 110 | internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; | ||
| 111 | ioctls. They are optional, however. The discarding policy is not | ||
| 112 | reported and cannot be changed. For minimum requirements see <xref | ||
| 113 | linkend="devices" />.</para> | ||
| 114 | </refsect1> | ||
| 115 | |||
| 116 | <refsect1> | ||
| 117 | <title>Return Value</title> | ||
| 118 | |||
| 119 | <para>On success, the number of bytes read is returned. It is not | ||
| 120 | an error if this number is smaller than the number of bytes requested, | ||
| 121 | or the amount of data required for one frame. This may happen for | ||
| 122 | example because <function>read()</function> was interrupted by a | ||
| 123 | signal. On error, -1 is returned, and the <varname>errno</varname> | ||
| 124 | variable is set appropriately. In this case the next read will start | ||
| 125 | at the beginning of a new frame. Possible error codes are:</para> | ||
| 126 | |||
| 127 | <variablelist> | ||
| 128 | <varlistentry> | ||
| 129 | <term><errorcode>EAGAIN</errorcode></term> | ||
| 130 | <listitem> | ||
| 131 | <para>Non-blocking I/O has been selected using | ||
| 132 | O_NONBLOCK and no data was immediately available for reading.</para> | ||
| 133 | </listitem> | ||
| 134 | </varlistentry> | ||
| 135 | <varlistentry> | ||
| 136 | <term><errorcode>EBADF</errorcode></term> | ||
| 137 | <listitem> | ||
| 138 | <para><parameter>fd</parameter> is not a valid file | ||
| 139 | descriptor or is not open for reading, or the process already has the | ||
| 140 | maximum number of files open.</para> | ||
| 141 | </listitem> | ||
| 142 | </varlistentry> | ||
| 143 | <varlistentry> | ||
| 144 | <term><errorcode>EBUSY</errorcode></term> | ||
| 145 | <listitem> | ||
| 146 | <para>The driver does not support multiple read streams and the | ||
| 147 | device is already in use.</para> | ||
| 148 | </listitem> | ||
| 149 | </varlistentry> | ||
| 150 | <varlistentry> | ||
| 151 | <term><errorcode>EFAULT</errorcode></term> | ||
| 152 | <listitem> | ||
| 153 | <para><parameter>buf</parameter> references an inaccessible | ||
| 154 | memory area.</para> | ||
| 155 | </listitem> | ||
| 156 | </varlistentry> | ||
| 157 | <varlistentry> | ||
| 158 | <term><errorcode>EINTR</errorcode></term> | ||
| 159 | <listitem> | ||
| 160 | <para>The call was interrupted by a signal before any | ||
| 161 | data was read.</para> | ||
| 162 | </listitem> | ||
| 163 | </varlistentry> | ||
| 164 | <varlistentry> | ||
| 165 | <term><errorcode>EIO</errorcode></term> | ||
| 166 | <listitem> | ||
| 167 | <para>I/O error. This indicates some hardware problem or a | ||
| 168 | failure to communicate with a remote device (USB camera etc.).</para> | ||
| 169 | </listitem> | ||
| 170 | </varlistentry> | ||
| 171 | <varlistentry> | ||
| 172 | <term><errorcode>EINVAL</errorcode></term> | ||
| 173 | <listitem> | ||
| 174 | <para>The <function>read()</function> function is not | ||
| 175 | supported by this driver, not on this device, or generally not on this | ||
| 176 | type of device.</para> | ||
| 177 | </listitem> | ||
| 178 | </varlistentry> | ||
| 179 | </variablelist> | ||
| 180 | </refsect1> | ||
| 181 | </refentry> | ||
| 182 | |||
| 183 | <!-- | ||
| 184 | Local Variables: | ||
| 185 | mode: sgml | ||
| 186 | sgml-parent-document: "v4l2.sgml" | ||
| 187 | indent-tabs-mode: nil | ||
| 188 | End: | ||
| 189 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-select.xml b/Documentation/DocBook/v4l/func-select.xml new file mode 100644 index 000000000000..b6713623181f --- /dev/null +++ b/Documentation/DocBook/v4l/func-select.xml | |||
| @@ -0,0 +1,138 @@ | |||
| 1 | <refentry id="func-select"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 select()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-select</refname> | ||
| 9 | <refpurpose>Synchronous I/O multiplexing</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo> | ||
| 15 | #include <sys/time.h> | ||
| 16 | #include <sys/types.h> | ||
| 17 | #include <unistd.h></funcsynopsisinfo> | ||
| 18 | <funcprototype> | ||
| 19 | <funcdef>int <function>select</function></funcdef> | ||
| 20 | <paramdef>int <parameter>nfds</parameter></paramdef> | ||
| 21 | <paramdef>fd_set *<parameter>readfds</parameter></paramdef> | ||
| 22 | <paramdef>fd_set *<parameter>writefds</parameter></paramdef> | ||
| 23 | <paramdef>fd_set *<parameter>exceptfds</parameter></paramdef> | ||
| 24 | <paramdef>struct timeval *<parameter>timeout</parameter></paramdef> | ||
| 25 | </funcprototype> | ||
| 26 | </funcsynopsis> | ||
| 27 | </refsynopsisdiv> | ||
| 28 | |||
| 29 | <refsect1> | ||
| 30 | <title>Description</title> | ||
| 31 | |||
| 32 | <para>With the <function>select()</function> function applications | ||
| 33 | can suspend execution until the driver has captured data or is ready | ||
| 34 | to accept data for output.</para> | ||
| 35 | |||
| 36 | <para>When streaming I/O has been negotiated this function waits | ||
| 37 | until a buffer has been filled or displayed and can be dequeued with | ||
| 38 | the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing | ||
| 39 | queue of the driver the function returns immediately.</para> | ||
| 40 | |||
| 41 | <para>On success <function>select()</function> returns the total | ||
| 42 | number of bits set in the <structname>fd_set</structname>s. When the | ||
| 43 | function timed out it returns a value of zero. On failure it returns | ||
| 44 | <returnvalue>-1</returnvalue> and the <varname>errno</varname> | ||
| 45 | variable is set appropriately. When the application did not call | ||
| 46 | &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the | ||
| 47 | <function>select()</function> function succeeds, setting the bit of | ||
| 48 | the file descriptor in <parameter>readfds</parameter> or | ||
| 49 | <parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls | ||
| 50 | will fail.<footnote><para>The Linux kernel implements | ||
| 51 | <function>select()</function> like the &func-poll; function, but | ||
| 52 | <function>select()</function> cannot return a | ||
| 53 | <constant>POLLERR</constant>.</para> | ||
| 54 | </footnote></para> | ||
| 55 | |||
| 56 | <para>When use of the <function>read()</function> function has | ||
| 57 | been negotiated and the driver does not capture yet, the | ||
| 58 | <function>select()</function> function starts capturing. When that | ||
| 59 | fails, <function>select()</function> returns successful and a | ||
| 60 | subsequent <function>read()</function> call, which also attempts to | ||
| 61 | start capturing, will return an appropriate error code. When the | ||
| 62 | driver captures continuously (as opposed to, for example, still | ||
| 63 | images) and data is already available the | ||
| 64 | <function>select()</function> function returns immediately.</para> | ||
| 65 | |||
| 66 | <para>When use of the <function>write()</function> function has | ||
| 67 | been negotiated the <function>select()</function> function just waits | ||
| 68 | until the driver is ready for a non-blocking | ||
| 69 | <function>write()</function> call.</para> | ||
| 70 | |||
| 71 | <para>All drivers implementing the <function>read()</function> or | ||
| 72 | <function>write()</function> function or streaming I/O must also | ||
| 73 | support the <function>select()</function> function.</para> | ||
| 74 | |||
| 75 | <para>For more details see the <function>select()</function> | ||
| 76 | manual page.</para> | ||
| 77 | |||
| 78 | </refsect1> | ||
| 79 | |||
| 80 | <refsect1> | ||
| 81 | <title>Return Value</title> | ||
| 82 | |||
| 83 | <para>On success, <function>select()</function> returns the number | ||
| 84 | of descriptors contained in the three returned descriptor sets, which | ||
| 85 | will be zero if the timeout expired. On error | ||
| 86 | <returnvalue>-1</returnvalue> is returned, and the | ||
| 87 | <varname>errno</varname> variable is set appropriately; the sets and | ||
| 88 | <parameter>timeout</parameter> are undefined. Possible error codes | ||
| 89 | are:</para> | ||
| 90 | |||
| 91 | <variablelist> | ||
| 92 | <varlistentry> | ||
| 93 | <term><errorcode>EBADF</errorcode></term> | ||
| 94 | <listitem> | ||
| 95 | <para>One or more of the file descriptor sets specified a | ||
| 96 | file descriptor that is not open.</para> | ||
| 97 | </listitem> | ||
| 98 | </varlistentry> | ||
| 99 | <varlistentry> | ||
| 100 | <term><errorcode>EBUSY</errorcode></term> | ||
| 101 | <listitem> | ||
| 102 | <para>The driver does not support multiple read or write | ||
| 103 | streams and the device is already in use.</para> | ||
| 104 | </listitem> | ||
| 105 | </varlistentry> | ||
| 106 | <varlistentry> | ||
| 107 | <term><errorcode>EFAULT</errorcode></term> | ||
| 108 | <listitem> | ||
| 109 | <para>The <parameter>readfds</parameter>, | ||
| 110 | <parameter>writefds</parameter>, <parameter>exceptfds</parameter> or | ||
| 111 | <parameter>timeout</parameter> pointer references an inaccessible memory | ||
| 112 | area.</para> | ||
| 113 | </listitem> | ||
| 114 | </varlistentry> | ||
| 115 | <varlistentry> | ||
| 116 | <term><errorcode>EINTR</errorcode></term> | ||
| 117 | <listitem> | ||
| 118 | <para>The call was interrupted by a signal.</para> | ||
| 119 | </listitem> | ||
| 120 | </varlistentry> | ||
| 121 | <varlistentry> | ||
| 122 | <term><errorcode>EINVAL</errorcode></term> | ||
| 123 | <listitem> | ||
| 124 | <para>The <parameter>nfds</parameter> argument is less than | ||
| 125 | zero or greater than <constant>FD_SETSIZE</constant>.</para> | ||
| 126 | </listitem> | ||
| 127 | </varlistentry> | ||
| 128 | </variablelist> | ||
| 129 | </refsect1> | ||
| 130 | </refentry> | ||
| 131 | |||
| 132 | <!-- | ||
| 133 | Local Variables: | ||
| 134 | mode: sgml | ||
| 135 | sgml-parent-document: "v4l2.sgml" | ||
| 136 | indent-tabs-mode: nil | ||
| 137 | End: | ||
| 138 | --> | ||
diff --git a/Documentation/DocBook/v4l/func-write.xml b/Documentation/DocBook/v4l/func-write.xml new file mode 100644 index 000000000000..2c09c09371c3 --- /dev/null +++ b/Documentation/DocBook/v4l/func-write.xml | |||
| @@ -0,0 +1,136 @@ | |||
| 1 | <refentry id="func-write"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2 write()</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>v4l2-write</refname> | ||
| 9 | <refpurpose>Write to a V4L2 device</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>ssize_t <function>write</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>void *<parameter>buf</parameter></paramdef> | ||
| 19 | <paramdef>size_t <parameter>count</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>buf</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para></para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>count</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para><function>write()</function> writes up to | ||
| 53 | <parameter>count</parameter> bytes to the device referenced by the | ||
| 54 | file descriptor <parameter>fd</parameter> from the buffer starting at | ||
| 55 | <parameter>buf</parameter>. When the hardware outputs are not active | ||
| 56 | yet, this function enables them. When <parameter>count</parameter> is | ||
| 57 | zero, <function>write()</function> returns | ||
| 58 | <returnvalue>0</returnvalue> without any other effect.</para> | ||
| 59 | |||
| 60 | <para>When the application does not provide more data in time, the | ||
| 61 | previous video frame, raw VBI image, sliced VPS or WSS data is | ||
| 62 | displayed again. Sliced Teletext or Closed Caption data is not | ||
| 63 | repeated, the driver inserts a blank line instead.</para> | ||
| 64 | </refsect1> | ||
| 65 | |||
| 66 | <refsect1> | ||
| 67 | <title>Return Value</title> | ||
| 68 | |||
| 69 | <para>On success, the number of bytes written are returned. Zero | ||
| 70 | indicates nothing was written. On error, <returnvalue>-1</returnvalue> | ||
| 71 | is returned, and the <varname>errno</varname> variable is set | ||
| 72 | appropriately. In this case the next write will start at the beginning | ||
| 73 | of a new frame. Possible error codes are:</para> | ||
| 74 | |||
| 75 | <variablelist> | ||
| 76 | <varlistentry> | ||
| 77 | <term><errorcode>EAGAIN</errorcode></term> | ||
| 78 | <listitem> | ||
| 79 | <para>Non-blocking I/O has been selected using the <link | ||
| 80 | linkend="func-open"><constant>O_NONBLOCK</constant></link> flag and no | ||
| 81 | buffer space was available to write the data immediately.</para> | ||
| 82 | </listitem> | ||
| 83 | </varlistentry> | ||
| 84 | <varlistentry> | ||
| 85 | <term><errorcode>EBADF</errorcode></term> | ||
| 86 | <listitem> | ||
| 87 | <para><parameter>fd</parameter> is not a valid file | ||
| 88 | descriptor or is not open for writing.</para> | ||
| 89 | </listitem> | ||
| 90 | </varlistentry> | ||
| 91 | <varlistentry> | ||
| 92 | <term><errorcode>EBUSY</errorcode></term> | ||
| 93 | <listitem> | ||
| 94 | <para>The driver does not support multiple write streams and the | ||
| 95 | device is already in use.</para> | ||
| 96 | </listitem> | ||
| 97 | </varlistentry> | ||
| 98 | <varlistentry> | ||
| 99 | <term><errorcode>EFAULT</errorcode></term> | ||
| 100 | <listitem> | ||
| 101 | <para><parameter>buf</parameter> references an inaccessible | ||
| 102 | memory area.</para> | ||
| 103 | </listitem> | ||
| 104 | </varlistentry> | ||
| 105 | <varlistentry> | ||
| 106 | <term><errorcode>EINTR</errorcode></term> | ||
| 107 | <listitem> | ||
| 108 | <para>The call was interrupted by a signal before any | ||
| 109 | data was written.</para> | ||
| 110 | </listitem> | ||
| 111 | </varlistentry> | ||
| 112 | <varlistentry> | ||
| 113 | <term><errorcode>EIO</errorcode></term> | ||
| 114 | <listitem> | ||
| 115 | <para>I/O error. This indicates some hardware problem.</para> | ||
| 116 | </listitem> | ||
| 117 | </varlistentry> | ||
| 118 | <varlistentry> | ||
| 119 | <term><errorcode>EINVAL</errorcode></term> | ||
| 120 | <listitem> | ||
| 121 | <para>The <function>write()</function> function is not | ||
| 122 | supported by this driver, not on this device, or generally not on this | ||
| 123 | type of device.</para> | ||
| 124 | </listitem> | ||
| 125 | </varlistentry> | ||
| 126 | </variablelist> | ||
| 127 | </refsect1> | ||
| 128 | </refentry> | ||
| 129 | |||
| 130 | <!-- | ||
| 131 | Local Variables: | ||
| 132 | mode: sgml | ||
| 133 | sgml-parent-document: "v4l2.sgml" | ||
| 134 | indent-tabs-mode: nil | ||
| 135 | End: | ||
| 136 | --> | ||
diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml new file mode 100644 index 000000000000..f92f24323b2a --- /dev/null +++ b/Documentation/DocBook/v4l/io.xml | |||
| @@ -0,0 +1,1073 @@ | |||
| 1 | <title>Input/Output</title> | ||
| 2 | |||
| 3 | <para>The V4L2 API defines several different methods to read from or | ||
| 4 | write to a device. All drivers exchanging data with applications must | ||
| 5 | support at least one of them.</para> | ||
| 6 | |||
| 7 | <para>The classic I/O method using the <function>read()</function> | ||
| 8 | and <function>write()</function> function is automatically selected | ||
| 9 | after opening a V4L2 device. When the driver does not support this | ||
| 10 | method attempts to read or write will fail at any time.</para> | ||
| 11 | |||
| 12 | <para>Other methods must be negotiated. To select the streaming I/O | ||
| 13 | method with memory mapped or user buffers applications call the | ||
| 14 | &VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined | ||
| 15 | yet.</para> | ||
| 16 | |||
| 17 | <para>Video overlay can be considered another I/O method, although | ||
| 18 | the application does not directly receive the image data. It is | ||
| 19 | selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl. | ||
| 20 | For more information see <xref linkend="overlay" />.</para> | ||
| 21 | |||
| 22 | <para>Generally exactly one I/O method, including overlay, is | ||
| 23 | associated with each file descriptor. The only exceptions are | ||
| 24 | applications not exchanging data with a driver ("panel applications", | ||
| 25 | see <xref linkend="open" />) and drivers permitting simultaneous video capturing | ||
| 26 | and overlay using the same file descriptor, for compatibility with V4L | ||
| 27 | and earlier versions of V4L2.</para> | ||
| 28 | |||
| 29 | <para><constant>VIDIOC_S_FMT</constant> and | ||
| 30 | <constant>VIDIOC_REQBUFS</constant> would permit this to some degree, | ||
| 31 | but for simplicity drivers need not support switching the I/O method | ||
| 32 | (after first switching away from read/write) other than by closing | ||
| 33 | and reopening the device.</para> | ||
| 34 | |||
| 35 | <para>The following sections describe the various I/O methods in | ||
| 36 | more detail.</para> | ||
| 37 | |||
| 38 | <section id="rw"> | ||
| 39 | <title>Read/Write</title> | ||
| 40 | |||
| 41 | <para>Input and output devices support the | ||
| 42 | <function>read()</function> and <function>write()</function> function, | ||
| 43 | respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in | ||
| 44 | the <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 45 | returned by the &VIDIOC-QUERYCAP; ioctl is set.</para> | ||
| 46 | |||
| 47 | <para>Drivers may need the CPU to copy the data, but they may also | ||
| 48 | support DMA to or from user memory, so this I/O method is not | ||
| 49 | necessarily less efficient than other methods merely exchanging buffer | ||
| 50 | pointers. It is considered inferior though because no meta-information | ||
| 51 | like frame counters or timestamps are passed. This information is | ||
| 52 | necessary to recognize frame dropping and to synchronize with other | ||
| 53 | data streams. However this is also the simplest I/O method, requiring | ||
| 54 | little or no setup to exchange data. It permits command line stunts | ||
| 55 | like this (the <application>vidctrl</application> tool is | ||
| 56 | fictitious):</para> | ||
| 57 | |||
| 58 | <informalexample> | ||
| 59 | <screen> | ||
| 60 | > vidctrl /dev/video --input=0 --format=YUYV --size=352x288 | ||
| 61 | > dd if=/dev/video of=myimage.422 bs=202752 count=1 | ||
| 62 | </screen> | ||
| 63 | </informalexample> | ||
| 64 | |||
| 65 | <para>To read from the device applications use the | ||
| 66 | &func-read; function, to write the &func-write; function. | ||
| 67 | Drivers must implement one I/O method if they | ||
| 68 | exchange data with applications, but it need not be this.<footnote> | ||
| 69 | <para>It would be desirable if applications could depend on | ||
| 70 | drivers supporting all I/O interfaces, but as much as the complex | ||
| 71 | memory mapping I/O can be inadequate for some devices we have no | ||
| 72 | reason to require this interface, which is most useful for simple | ||
| 73 | applications capturing still images.</para> | ||
| 74 | </footnote> When reading or writing is supported, the driver | ||
| 75 | must also support the &func-select; and &func-poll; | ||
| 76 | function.<footnote> | ||
| 77 | <para>At the driver level <function>select()</function> and | ||
| 78 | <function>poll()</function> are the same, and | ||
| 79 | <function>select()</function> is too important to be optional.</para> | ||
| 80 | </footnote></para> | ||
| 81 | </section> | ||
| 82 | |||
| 83 | <section id="mmap"> | ||
| 84 | <title>Streaming I/O (Memory Mapping)</title> | ||
| 85 | |||
| 86 | <para>Input and output devices support this I/O method when the | ||
| 87 | <constant>V4L2_CAP_STREAMING</constant> flag in the | ||
| 88 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 89 | returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two | ||
| 90 | streaming methods, to determine if the memory mapping flavor is | ||
| 91 | supported applications must call the &VIDIOC-REQBUFS; ioctl.</para> | ||
| 92 | |||
| 93 | <para>Streaming is an I/O method where only pointers to buffers | ||
| 94 | are exchanged between application and driver, the data itself is not | ||
| 95 | copied. Memory mapping is primarily intended to map buffers in device | ||
| 96 | memory into the application's address space. Device memory can be for | ||
| 97 | example the video memory on a graphics card with a video capture | ||
| 98 | add-on. However, being the most efficient I/O method available for a | ||
| 99 | long time, many other drivers support streaming as well, allocating | ||
| 100 | buffers in DMA-able main memory.</para> | ||
| 101 | |||
| 102 | <para>A driver can support many sets of buffers. Each set is | ||
| 103 | identified by a unique buffer type value. The sets are independent and | ||
| 104 | each set can hold a different type of data. To access different sets | ||
| 105 | at the same time different file descriptors must be used.<footnote> | ||
| 106 | <para>One could use one file descriptor and set the buffer | ||
| 107 | type field accordingly when calling &VIDIOC-QBUF; etc., but it makes | ||
| 108 | the <function>select()</function> function ambiguous. We also like the | ||
| 109 | clean approach of one file descriptor per logical stream. Video | ||
| 110 | overlay for example is also a logical stream, although the CPU is not | ||
| 111 | needed for continuous operation.</para> | ||
| 112 | </footnote></para> | ||
| 113 | |||
| 114 | <para>To allocate device buffers applications call the | ||
| 115 | &VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer | ||
| 116 | type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. | ||
| 117 | This ioctl can also be used to change the number of buffers or to free | ||
| 118 | the allocated memory, provided none of the buffers are still | ||
| 119 | mapped.</para> | ||
| 120 | |||
| 121 | <para>Before applications can access the buffers they must map | ||
| 122 | them into their address space with the &func-mmap; function. The | ||
| 123 | location of the buffers in device memory can be determined with the | ||
| 124 | &VIDIOC-QUERYBUF; ioctl. The <structfield>m.offset</structfield> and | ||
| 125 | <structfield>length</structfield> returned in a &v4l2-buffer; are | ||
| 126 | passed as sixth and second parameter to the | ||
| 127 | <function>mmap()</function> function. The offset and length values | ||
| 128 | must not be modified. Remember the buffers are allocated in physical | ||
| 129 | memory, as opposed to virtual memory which can be swapped out to disk. | ||
| 130 | Applications should free the buffers as soon as possible with the | ||
| 131 | &func-munmap; function.</para> | ||
| 132 | |||
| 133 | <example> | ||
| 134 | <title>Mapping buffers</title> | ||
| 135 | |||
| 136 | <programlisting> | ||
| 137 | &v4l2-requestbuffers; reqbuf; | ||
| 138 | struct { | ||
| 139 | void *start; | ||
| 140 | size_t length; | ||
| 141 | } *buffers; | ||
| 142 | unsigned int i; | ||
| 143 | |||
| 144 | memset (&reqbuf, 0, sizeof (reqbuf)); | ||
| 145 | reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 146 | reqbuf.memory = V4L2_MEMORY_MMAP; | ||
| 147 | reqbuf.count = 20; | ||
| 148 | |||
| 149 | if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) { | ||
| 150 | if (errno == EINVAL) | ||
| 151 | printf ("Video capturing or mmap-streaming is not supported\n"); | ||
| 152 | else | ||
| 153 | perror ("VIDIOC_REQBUFS"); | ||
| 154 | |||
| 155 | exit (EXIT_FAILURE); | ||
| 156 | } | ||
| 157 | |||
| 158 | /* We want at least five buffers. */ | ||
| 159 | |||
| 160 | if (reqbuf.count < 5) { | ||
| 161 | /* You may need to free the buffers here. */ | ||
| 162 | printf ("Not enough buffer memory\n"); | ||
| 163 | exit (EXIT_FAILURE); | ||
| 164 | } | ||
| 165 | |||
| 166 | buffers = calloc (reqbuf.count, sizeof (*buffers)); | ||
| 167 | assert (buffers != NULL); | ||
| 168 | |||
| 169 | for (i = 0; i < reqbuf.count; i++) { | ||
| 170 | &v4l2-buffer; buffer; | ||
| 171 | |||
| 172 | memset (&buffer, 0, sizeof (buffer)); | ||
| 173 | buffer.type = reqbuf.type; | ||
| 174 | buffer.memory = V4L2_MEMORY_MMAP; | ||
| 175 | buffer.index = i; | ||
| 176 | |||
| 177 | if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &buffer)) { | ||
| 178 | perror ("VIDIOC_QUERYBUF"); | ||
| 179 | exit (EXIT_FAILURE); | ||
| 180 | } | ||
| 181 | |||
| 182 | buffers[i].length = buffer.length; /* remember for munmap() */ | ||
| 183 | |||
| 184 | buffers[i].start = mmap (NULL, buffer.length, | ||
| 185 | PROT_READ | PROT_WRITE, /* recommended */ | ||
| 186 | MAP_SHARED, /* recommended */ | ||
| 187 | fd, buffer.m.offset); | ||
| 188 | |||
| 189 | if (MAP_FAILED == buffers[i].start) { | ||
| 190 | /* If you do not exit here you should unmap() and free() | ||
| 191 | the buffers mapped so far. */ | ||
| 192 | perror ("mmap"); | ||
| 193 | exit (EXIT_FAILURE); | ||
| 194 | } | ||
| 195 | } | ||
| 196 | |||
| 197 | /* Cleanup. */ | ||
| 198 | |||
| 199 | for (i = 0; i < reqbuf.count; i++) | ||
| 200 | munmap (buffers[i].start, buffers[i].length); | ||
| 201 | </programlisting> | ||
| 202 | </example> | ||
| 203 | |||
| 204 | <para>Conceptually streaming drivers maintain two buffer queues, an incoming | ||
| 205 | and an outgoing queue. They separate the synchronous capture or output | ||
| 206 | operation locked to a video clock from the application which is | ||
| 207 | subject to random disk or network delays and preemption by | ||
| 208 | other processes, thereby reducing the probability of data loss. | ||
| 209 | The queues are organized as FIFOs, buffers will be | ||
| 210 | output in the order enqueued in the incoming FIFO, and were | ||
| 211 | captured in the order dequeued from the outgoing FIFO.</para> | ||
| 212 | |||
| 213 | <para>The driver may require a minimum number of buffers enqueued | ||
| 214 | at all times to function, apart of this no limit exists on the number | ||
| 215 | of buffers applications can enqueue in advance, or dequeue and | ||
| 216 | process. They can also enqueue in a different order than buffers have | ||
| 217 | been dequeued, and the driver can <emphasis>fill</emphasis> enqueued | ||
| 218 | <emphasis>empty</emphasis> buffers in any order. <footnote> | ||
| 219 | <para>Random enqueue order permits applications processing | ||
| 220 | images out of order (such as video codecs) to return buffers earlier, | ||
| 221 | reducing the probability of data loss. Random fill order allows | ||
| 222 | drivers to reuse buffers on a LIFO-basis, taking advantage of caches | ||
| 223 | holding scatter-gather lists and the like.</para> | ||
| 224 | </footnote> The index number of a buffer (&v4l2-buffer; | ||
| 225 | <structfield>index</structfield>) plays no role here, it only | ||
| 226 | identifies the buffer.</para> | ||
| 227 | |||
| 228 | <para>Initially all mapped buffers are in dequeued state, | ||
| 229 | inaccessible by the driver. For capturing applications it is customary | ||
| 230 | to first enqueue all mapped buffers, then to start capturing and enter | ||
| 231 | the read loop. Here the application waits until a filled buffer can be | ||
| 232 | dequeued, and re-enqueues the buffer when the data is no longer | ||
| 233 | needed. Output applications fill and enqueue buffers, when enough | ||
| 234 | buffers are stacked up the output is started with | ||
| 235 | <constant>VIDIOC_STREAMON</constant>. In the write loop, when | ||
| 236 | the application runs out of free buffers, it must wait until an empty | ||
| 237 | buffer can be dequeued and reused.</para> | ||
| 238 | |||
| 239 | <para>To enqueue and dequeue a buffer applications use the | ||
| 240 | &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being | ||
| 241 | mapped, enqueued, full or empty can be determined at any time using the | ||
| 242 | &VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the | ||
| 243 | application until one or more buffers can be dequeued. By default | ||
| 244 | <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the | ||
| 245 | outgoing queue. When the <constant>O_NONBLOCK</constant> flag was | ||
| 246 | given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> | ||
| 247 | returns immediately with an &EAGAIN; when no buffer is available. The | ||
| 248 | &func-select; or &func-poll; function are always available.</para> | ||
| 249 | |||
| 250 | <para>To start and stop capturing or output applications call the | ||
| 251 | &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note | ||
| 252 | <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both | ||
| 253 | queues as a side effect. Since there is no notion of doing anything | ||
| 254 | "now" on a multitasking system, if an application needs to synchronize | ||
| 255 | with another event it should examine the &v4l2-buffer; | ||
| 256 | <structfield>timestamp</structfield> of captured buffers, or set the | ||
| 257 | field before enqueuing buffers for output.</para> | ||
| 258 | |||
| 259 | <para>Drivers implementing memory mapping I/O must | ||
| 260 | support the <constant>VIDIOC_REQBUFS</constant>, | ||
| 261 | <constant>VIDIOC_QUERYBUF</constant>, | ||
| 262 | <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, | ||
| 263 | <constant>VIDIOC_STREAMON</constant> and | ||
| 264 | <constant>VIDIOC_STREAMOFF</constant> ioctl, the | ||
| 265 | <function>mmap()</function>, <function>munmap()</function>, | ||
| 266 | <function>select()</function> and <function>poll()</function> | ||
| 267 | function.<footnote> | ||
| 268 | <para>At the driver level <function>select()</function> and | ||
| 269 | <function>poll()</function> are the same, and | ||
| 270 | <function>select()</function> is too important to be optional. The | ||
| 271 | rest should be evident.</para> | ||
| 272 | </footnote></para> | ||
| 273 | |||
| 274 | <para>[capture example]</para> | ||
| 275 | |||
| 276 | </section> | ||
| 277 | |||
| 278 | <section id="userp"> | ||
| 279 | <title>Streaming I/O (User Pointers)</title> | ||
| 280 | |||
| 281 | <para>Input and output devices support this I/O method when the | ||
| 282 | <constant>V4L2_CAP_STREAMING</constant> flag in the | ||
| 283 | <structfield>capabilities</structfield> field of &v4l2-capability; | ||
| 284 | returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user | ||
| 285 | pointer method (not only memory mapping) is supported must be | ||
| 286 | determined by calling the &VIDIOC-REQBUFS; ioctl.</para> | ||
| 287 | |||
| 288 | <para>This I/O method combines advantages of the read/write and | ||
| 289 | memory mapping methods. Buffers are allocated by the application | ||
| 290 | itself, and can reside for example in virtual or shared memory. Only | ||
| 291 | pointers to data are exchanged, these pointers and meta-information | ||
| 292 | are passed in &v4l2-buffer;. The driver must be switched | ||
| 293 | into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the | ||
| 294 | desired buffer type. No buffers are allocated beforehands, | ||
| 295 | consequently they are not indexed and cannot be queried like mapped | ||
| 296 | buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para> | ||
| 297 | |||
| 298 | <example> | ||
| 299 | <title>Initiating streaming I/O with user pointers</title> | ||
| 300 | |||
| 301 | <programlisting> | ||
| 302 | &v4l2-requestbuffers; reqbuf; | ||
| 303 | |||
| 304 | memset (&reqbuf, 0, sizeof (reqbuf)); | ||
| 305 | reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 306 | reqbuf.memory = V4L2_MEMORY_USERPTR; | ||
| 307 | |||
| 308 | if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { | ||
| 309 | if (errno == EINVAL) | ||
| 310 | printf ("Video capturing or user pointer streaming is not supported\n"); | ||
| 311 | else | ||
| 312 | perror ("VIDIOC_REQBUFS"); | ||
| 313 | |||
| 314 | exit (EXIT_FAILURE); | ||
| 315 | } | ||
| 316 | </programlisting> | ||
| 317 | </example> | ||
| 318 | |||
| 319 | <para>Buffer addresses and sizes are passed on the fly with the | ||
| 320 | &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled, | ||
| 321 | applications can pass different addresses and sizes at each | ||
| 322 | <constant>VIDIOC_QBUF</constant> call. If required by the hardware the | ||
| 323 | driver swaps memory pages within physical memory to create a | ||
| 324 | continuous area of memory. This happens transparently to the | ||
| 325 | application in the virtual memory subsystem of the kernel. When buffer | ||
| 326 | pages have been swapped out to disk they are brought back and finally | ||
| 327 | locked in physical memory for DMA.<footnote> | ||
| 328 | <para>We expect that frequently used buffers are typically not | ||
| 329 | swapped out. Anyway, the process of swapping, locking or generating | ||
| 330 | scatter-gather lists may be time consuming. The delay can be masked by | ||
| 331 | the depth of the incoming buffer queue, and perhaps by maintaining | ||
| 332 | caches assuming a buffer will be soon enqueued again. On the other | ||
| 333 | hand, to optimize memory usage drivers can limit the number of buffers | ||
| 334 | locked in advance and recycle the most recently used buffers first. Of | ||
| 335 | course, the pages of empty buffers in the incoming queue need not be | ||
| 336 | saved to disk. Output buffers must be saved on the incoming and | ||
| 337 | outgoing queue because an application may share them with other | ||
| 338 | processes.</para> | ||
| 339 | </footnote></para> | ||
| 340 | |||
| 341 | <para>Filled or displayed buffers are dequeued with the | ||
| 342 | &VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any | ||
| 343 | time between the completion of the DMA and this ioctl. The memory is | ||
| 344 | also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or | ||
| 345 | when the device is closed. Applications must take care not to free | ||
| 346 | buffers without dequeuing. For once, the buffers remain locked until | ||
| 347 | further, wasting physical memory. Second the driver will not be | ||
| 348 | notified when the memory is returned to the application's free list | ||
| 349 | and subsequently reused for other purposes, possibly completing the | ||
| 350 | requested DMA and overwriting valuable data.</para> | ||
| 351 | |||
| 352 | <para>For capturing applications it is customary to enqueue a | ||
| 353 | number of empty buffers, to start capturing and enter the read loop. | ||
| 354 | Here the application waits until a filled buffer can be dequeued, and | ||
| 355 | re-enqueues the buffer when the data is no longer needed. Output | ||
| 356 | applications fill and enqueue buffers, when enough buffers are stacked | ||
| 357 | up output is started. In the write loop, when the application | ||
| 358 | runs out of free buffers it must wait until an empty buffer can be | ||
| 359 | dequeued and reused. Two methods exist to suspend execution of the | ||
| 360 | application until one or more buffers can be dequeued. By default | ||
| 361 | <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the | ||
| 362 | outgoing queue. When the <constant>O_NONBLOCK</constant> flag was | ||
| 363 | given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> | ||
| 364 | returns immediately with an &EAGAIN; when no buffer is available. The | ||
| 365 | &func-select; or &func-poll; function are always available.</para> | ||
| 366 | |||
| 367 | <para>To start and stop capturing or output applications call the | ||
| 368 | &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note | ||
| 369 | <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both | ||
| 370 | queues and unlocks all buffers as a side effect. Since there is no | ||
| 371 | notion of doing anything "now" on a multitasking system, if an | ||
| 372 | application needs to synchronize with another event it should examine | ||
| 373 | the &v4l2-buffer; <structfield>timestamp</structfield> of captured | ||
| 374 | buffers, or set the field before enqueuing buffers for output.</para> | ||
| 375 | |||
| 376 | <para>Drivers implementing user pointer I/O must | ||
| 377 | support the <constant>VIDIOC_REQBUFS</constant>, | ||
| 378 | <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, | ||
| 379 | <constant>VIDIOC_STREAMON</constant> and | ||
| 380 | <constant>VIDIOC_STREAMOFF</constant> ioctl, the | ||
| 381 | <function>select()</function> and <function>poll()</function> function.<footnote> | ||
| 382 | <para>At the driver level <function>select()</function> and | ||
| 383 | <function>poll()</function> are the same, and | ||
| 384 | <function>select()</function> is too important to be optional. The | ||
| 385 | rest should be evident.</para> | ||
| 386 | </footnote></para> | ||
| 387 | </section> | ||
| 388 | |||
| 389 | <section id="async"> | ||
| 390 | <title>Asynchronous I/O</title> | ||
| 391 | |||
| 392 | <para>This method is not defined yet.</para> | ||
| 393 | </section> | ||
| 394 | |||
| 395 | <section id="buffer"> | ||
| 396 | <title>Buffers</title> | ||
| 397 | |||
| 398 | <para>A buffer contains data exchanged by application and | ||
| 399 | driver using one of the Streaming I/O methods. Only pointers to | ||
| 400 | buffers are exchanged, the data itself is not copied. These pointers, | ||
| 401 | together with meta-information like timestamps or field parity, are | ||
| 402 | stored in a struct <structname>v4l2_buffer</structname>, argument to | ||
| 403 | the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.</para> | ||
| 404 | |||
| 405 | <para>Nominally timestamps refer to the first data byte transmitted. | ||
| 406 | In practice however the wide range of hardware covered by the V4L2 API | ||
| 407 | limits timestamp accuracy. Often an interrupt routine will | ||
| 408 | sample the system clock shortly after the field or frame was stored | ||
| 409 | completely in memory. So applications must expect a constant | ||
| 410 | difference up to one field or frame period plus a small (few scan | ||
| 411 | lines) random error. The delay and error can be much | ||
| 412 | larger due to compression or transmission over an external bus when | ||
| 413 | the frames are not properly stamped by the sender. This is frequently | ||
| 414 | the case with USB cameras. Here timestamps refer to the instant the | ||
| 415 | field or frame was received by the driver, not the capture time. These | ||
| 416 | devices identify by not enumerating any video standards, see <xref | ||
| 417 | linkend="standard" />.</para> | ||
| 418 | |||
| 419 | <para>Similar limitations apply to output timestamps. Typically | ||
| 420 | the video hardware locks to a clock controlling the video timing, the | ||
| 421 | horizontal and vertical synchronization pulses. At some point in the | ||
| 422 | line sequence, possibly the vertical blanking, an interrupt routine | ||
| 423 | samples the system clock, compares against the timestamp and programs | ||
| 424 | the hardware to repeat the previous field or frame, or to display the | ||
| 425 | buffer contents.</para> | ||
| 426 | |||
| 427 | <para>Apart of limitations of the video device and natural | ||
| 428 | inaccuracies of all clocks, it should be noted system time itself is | ||
| 429 | not perfectly stable. It can be affected by power saving cycles, | ||
| 430 | warped to insert leap seconds, or even turned back or forth by the | ||
| 431 | system administrator affecting long term measurements. <footnote> | ||
| 432 | <para>Since no other Linux multimedia | ||
| 433 | API supports unadjusted time it would be foolish to introduce here. We | ||
| 434 | must use a universally supported clock to synchronize different media, | ||
| 435 | hence time of day.</para> | ||
| 436 | </footnote></para> | ||
| 437 | |||
| 438 | <table frame="none" pgwide="1" id="v4l2-buffer"> | ||
| 439 | <title>struct <structname>v4l2_buffer</structname></title> | ||
| 440 | <tgroup cols="4"> | ||
| 441 | &cs-ustr; | ||
| 442 | <tbody valign="top"> | ||
| 443 | <row> | ||
| 444 | <entry>__u32</entry> | ||
| 445 | <entry><structfield>index</structfield></entry> | ||
| 446 | <entry></entry> | ||
| 447 | <entry>Number of the buffer, set by the application. This | ||
| 448 | field is only used for <link linkend="mmap">memory mapping</link> I/O | ||
| 449 | and can range from zero to the number of buffers allocated | ||
| 450 | with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry> | ||
| 451 | </row> | ||
| 452 | <row> | ||
| 453 | <entry>&v4l2-buf-type;</entry> | ||
| 454 | <entry><structfield>type</structfield></entry> | ||
| 455 | <entry></entry> | ||
| 456 | <entry>Type of the buffer, same as &v4l2-format; | ||
| 457 | <structfield>type</structfield> or &v4l2-requestbuffers; | ||
| 458 | <structfield>type</structfield>, set by the application.</entry> | ||
| 459 | </row> | ||
| 460 | <row> | ||
| 461 | <entry>__u32</entry> | ||
| 462 | <entry><structfield>bytesused</structfield></entry> | ||
| 463 | <entry></entry> | ||
| 464 | <entry>The number of bytes occupied by the data in the | ||
| 465 | buffer. It depends on the negotiated data format and may change with | ||
| 466 | each buffer for compressed variable size data like JPEG images. | ||
| 467 | Drivers must set this field when <structfield>type</structfield> | ||
| 468 | refers to an input stream, applications when an output stream.</entry> | ||
| 469 | </row> | ||
| 470 | <row> | ||
| 471 | <entry>__u32</entry> | ||
| 472 | <entry><structfield>flags</structfield></entry> | ||
| 473 | <entry></entry> | ||
| 474 | <entry>Flags set by the application or driver, see <xref | ||
| 475 | linkend="buffer-flags" />.</entry> | ||
| 476 | </row> | ||
| 477 | <row> | ||
| 478 | <entry>&v4l2-field;</entry> | ||
| 479 | <entry><structfield>field</structfield></entry> | ||
| 480 | <entry></entry> | ||
| 481 | <entry>Indicates the field order of the image in the | ||
| 482 | buffer, see <xref linkend="v4l2-field" />. This field is not used when | ||
| 483 | the buffer contains VBI data. Drivers must set it when | ||
| 484 | <structfield>type</structfield> refers to an input stream, | ||
| 485 | applications when an output stream.</entry> | ||
| 486 | </row> | ||
| 487 | <row> | ||
| 488 | <entry>struct timeval</entry> | ||
| 489 | <entry><structfield>timestamp</structfield></entry> | ||
| 490 | <entry></entry> | ||
| 491 | <entry><para>For input streams this is the | ||
| 492 | system time (as returned by the <function>gettimeofday()</function> | ||
| 493 | function) when the first data byte was captured. For output streams | ||
| 494 | the data will not be displayed before this time, secondary to the | ||
| 495 | nominal frame rate determined by the current video standard in | ||
| 496 | enqueued order. Applications can for example zero this field to | ||
| 497 | display frames as soon as possible. The driver stores the time at | ||
| 498 | which the first data byte was actually sent out in the | ||
| 499 | <structfield>timestamp</structfield> field. This permits | ||
| 500 | applications to monitor the drift between the video and system | ||
| 501 | clock.</para></entry> | ||
| 502 | </row> | ||
| 503 | <row> | ||
| 504 | <entry>&v4l2-timecode;</entry> | ||
| 505 | <entry><structfield>timecode</structfield></entry> | ||
| 506 | <entry></entry> | ||
| 507 | <entry>When <structfield>type</structfield> is | ||
| 508 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the | ||
| 509 | <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in | ||
| 510 | <structfield>flags</structfield>, this structure contains a frame | ||
| 511 | timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> | ||
| 512 | mode the top and bottom field contain the same timecode. | ||
| 513 | Timecodes are intended to help video editing and are typically recorded on | ||
| 514 | video tapes, but also embedded in compressed formats like MPEG. This | ||
| 515 | field is independent of the <structfield>timestamp</structfield> and | ||
| 516 | <structfield>sequence</structfield> fields.</entry> | ||
| 517 | </row> | ||
| 518 | <row> | ||
| 519 | <entry>__u32</entry> | ||
| 520 | <entry><structfield>sequence</structfield></entry> | ||
| 521 | <entry></entry> | ||
| 522 | <entry>Set by the driver, counting the frames in the | ||
| 523 | sequence.</entry> | ||
| 524 | </row> | ||
| 525 | <row> | ||
| 526 | <entry spanname="hspan"><para>In <link | ||
| 527 | linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and | ||
| 528 | bottom field have the same sequence number. The count starts at zero | ||
| 529 | and includes dropped or repeated frames. A dropped frame was received | ||
| 530 | by an input device but could not be stored due to lack of free buffer | ||
| 531 | space. A repeated frame was displayed again by an output device | ||
| 532 | because the application did not pass new data in | ||
| 533 | time.</para><para>Note this may count the frames received | ||
| 534 | e.g. over USB, without taking into account the frames dropped by the | ||
| 535 | remote hardware due to limited compression throughput or bus | ||
| 536 | bandwidth. These devices identify by not enumerating any video | ||
| 537 | standards, see <xref linkend="standard" />.</para></entry> | ||
| 538 | </row> | ||
| 539 | <row> | ||
| 540 | <entry>&v4l2-memory;</entry> | ||
| 541 | <entry><structfield>memory</structfield></entry> | ||
| 542 | <entry></entry> | ||
| 543 | <entry>This field must be set by applications and/or drivers | ||
| 544 | in accordance with the selected I/O method.</entry> | ||
| 545 | </row> | ||
| 546 | <row> | ||
| 547 | <entry>union</entry> | ||
| 548 | <entry><structfield>m</structfield></entry> | ||
| 549 | </row> | ||
| 550 | <row> | ||
| 551 | <entry></entry> | ||
| 552 | <entry>__u32</entry> | ||
| 553 | <entry><structfield>offset</structfield></entry> | ||
| 554 | <entry>When <structfield>memory</structfield> is | ||
| 555 | <constant>V4L2_MEMORY_MMAP</constant> this is the offset of the buffer | ||
| 556 | from the start of the device memory. The value is returned by the | ||
| 557 | driver and apart of serving as parameter to the &func-mmap; function | ||
| 558 | not useful for applications. See <xref linkend="mmap" /> for details.</entry> | ||
| 559 | </row> | ||
| 560 | <row> | ||
| 561 | <entry></entry> | ||
| 562 | <entry>unsigned long</entry> | ||
| 563 | <entry><structfield>userptr</structfield></entry> | ||
| 564 | <entry>When <structfield>memory</structfield> is | ||
| 565 | <constant>V4L2_MEMORY_USERPTR</constant> this is a pointer to the | ||
| 566 | buffer (casted to unsigned long type) in virtual memory, set by the | ||
| 567 | application. See <xref linkend="userp" /> for details.</entry> | ||
| 568 | </row> | ||
| 569 | <row> | ||
| 570 | <entry>__u32</entry> | ||
| 571 | <entry><structfield>length</structfield></entry> | ||
| 572 | <entry></entry> | ||
| 573 | <entry>Size of the buffer (not the payload) in bytes.</entry> | ||
| 574 | </row> | ||
| 575 | <row> | ||
| 576 | <entry>__u32</entry> | ||
| 577 | <entry><structfield>input</structfield></entry> | ||
| 578 | <entry></entry> | ||
| 579 | <entry>Some video capture drivers support rapid and | ||
| 580 | synchronous video input changes, a function useful for example in | ||
| 581 | video surveillance applications. For this purpose applications set the | ||
| 582 | <constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the | ||
| 583 | number of a video input as in &v4l2-input; field | ||
| 584 | <structfield>index</structfield>.</entry> | ||
| 585 | </row> | ||
| 586 | <row> | ||
| 587 | <entry>__u32</entry> | ||
| 588 | <entry><structfield>reserved</structfield></entry> | ||
| 589 | <entry></entry> | ||
| 590 | <entry>A place holder for future extensions and custom | ||
| 591 | (driver defined) buffer types | ||
| 592 | <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry> | ||
| 593 | </row> | ||
| 594 | </tbody> | ||
| 595 | </tgroup> | ||
| 596 | </table> | ||
| 597 | |||
| 598 | <table frame="none" pgwide="1" id="v4l2-buf-type"> | ||
| 599 | <title>enum v4l2_buf_type</title> | ||
| 600 | <tgroup cols="3"> | ||
| 601 | &cs-def; | ||
| 602 | <tbody valign="top"> | ||
| 603 | <row> | ||
| 604 | <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> | ||
| 605 | <entry>1</entry> | ||
| 606 | <entry>Buffer of a video capture stream, see <xref | ||
| 607 | linkend="capture" />.</entry> | ||
| 608 | </row> | ||
| 609 | <row> | ||
| 610 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> | ||
| 611 | <entry>2</entry> | ||
| 612 | <entry>Buffer of a video output stream, see <xref | ||
| 613 | linkend="output" />.</entry> | ||
| 614 | </row> | ||
| 615 | <row> | ||
| 616 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> | ||
| 617 | <entry>3</entry> | ||
| 618 | <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry> | ||
| 619 | </row> | ||
| 620 | <row> | ||
| 621 | <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> | ||
| 622 | <entry>4</entry> | ||
| 623 | <entry>Buffer of a raw VBI capture stream, see <xref | ||
| 624 | linkend="raw-vbi" />.</entry> | ||
| 625 | </row> | ||
| 626 | <row> | ||
| 627 | <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> | ||
| 628 | <entry>5</entry> | ||
| 629 | <entry>Buffer of a raw VBI output stream, see <xref | ||
| 630 | linkend="raw-vbi" />.</entry> | ||
| 631 | </row> | ||
| 632 | <row> | ||
| 633 | <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> | ||
| 634 | <entry>6</entry> | ||
| 635 | <entry>Buffer of a sliced VBI capture stream, see <xref | ||
| 636 | linkend="sliced" />.</entry> | ||
| 637 | </row> | ||
| 638 | <row> | ||
| 639 | <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> | ||
| 640 | <entry>7</entry> | ||
| 641 | <entry>Buffer of a sliced VBI output stream, see <xref | ||
| 642 | linkend="sliced" />.</entry> | ||
| 643 | </row> | ||
| 644 | <row> | ||
| 645 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry> | ||
| 646 | <entry>8</entry> | ||
| 647 | <entry>Buffer for video output overlay (OSD), see <xref | ||
| 648 | linkend="osd" />. Status: <link | ||
| 649 | linkend="experimental">Experimental</link>.</entry> | ||
| 650 | </row> | ||
| 651 | <row> | ||
| 652 | <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry> | ||
| 653 | <entry>0x80</entry> | ||
| 654 | <entry>This and higher values are reserved for custom | ||
| 655 | (driver defined) buffer types.</entry> | ||
| 656 | </row> | ||
| 657 | </tbody> | ||
| 658 | </tgroup> | ||
| 659 | </table> | ||
| 660 | |||
| 661 | <table frame="none" pgwide="1" id="buffer-flags"> | ||
| 662 | <title>Buffer Flags</title> | ||
| 663 | <tgroup cols="3"> | ||
| 664 | &cs-def; | ||
| 665 | <tbody valign="top"> | ||
| 666 | <row> | ||
| 667 | <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry> | ||
| 668 | <entry>0x0001</entry> | ||
| 669 | <entry>The buffer resides in device memory and has been mapped | ||
| 670 | into the application's address space, see <xref linkend="mmap" /> for details. | ||
| 671 | Drivers set or clear this flag when the | ||
| 672 | <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link | ||
| 673 | linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link | ||
| 674 | linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry> | ||
| 675 | </row> | ||
| 676 | <row> | ||
| 677 | <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry> | ||
| 678 | <entry>0x0002</entry> | ||
| 679 | <entry>Internally drivers maintain two buffer queues, an | ||
| 680 | incoming and outgoing queue. When this flag is set, the buffer is | ||
| 681 | currently on the incoming queue. It automatically moves to the | ||
| 682 | outgoing queue after the buffer has been filled (capture devices) or | ||
| 683 | displayed (output devices). Drivers set or clear this flag when the | ||
| 684 | <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After | ||
| 685 | (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is | ||
| 686 | always set and after <constant>VIDIOC_DQBUF</constant> always | ||
| 687 | cleared.</entry> | ||
| 688 | </row> | ||
| 689 | <row> | ||
| 690 | <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry> | ||
| 691 | <entry>0x0004</entry> | ||
| 692 | <entry>When this flag is set, the buffer is currently on | ||
| 693 | the outgoing queue, ready to be dequeued from the driver. Drivers set | ||
| 694 | or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl | ||
| 695 | is called. After calling the <constant>VIDIOC_QBUF</constant> or | ||
| 696 | <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a | ||
| 697 | buffer cannot be on both queues at the same time, the | ||
| 698 | <constant>V4L2_BUF_FLAG_QUEUED</constant> and | ||
| 699 | <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive. | ||
| 700 | They can be both cleared however, then the buffer is in "dequeued" | ||
| 701 | state, in the application domain to say so.</entry> | ||
| 702 | </row> | ||
| 703 | <row> | ||
| 704 | <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry> | ||
| 705 | <entry>0x0008</entry> | ||
| 706 | <entry>Drivers set or clear this flag when calling the | ||
| 707 | <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video | ||
| 708 | capture devices when the buffer contains a compressed image which is a | ||
| 709 | key frame (or field), &ie; can be decompressed on its own.</entry> | ||
| 710 | </row> | ||
| 711 | <row> | ||
| 712 | <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry> | ||
| 713 | <entry>0x0010</entry> | ||
| 714 | <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> | ||
| 715 | this flags predicted frames or fields which contain only differences to a | ||
| 716 | previous key frame.</entry> | ||
| 717 | </row> | ||
| 718 | <row> | ||
| 719 | <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry> | ||
| 720 | <entry>0x0020</entry> | ||
| 721 | <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant> | ||
| 722 | this is a bidirectional predicted frame or field. [ooc tbd]</entry> | ||
| 723 | </row> | ||
| 724 | <row> | ||
| 725 | <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry> | ||
| 726 | <entry>0x0100</entry> | ||
| 727 | <entry>The <structfield>timecode</structfield> field is valid. | ||
| 728 | Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> | ||
| 729 | ioctl is called.</entry> | ||
| 730 | </row> | ||
| 731 | <row> | ||
| 732 | <entry><constant>V4L2_BUF_FLAG_INPUT</constant></entry> | ||
| 733 | <entry>0x0200</entry> | ||
| 734 | <entry>The <structfield>input</structfield> field is valid. | ||
| 735 | Applications set or clear this flag before calling the | ||
| 736 | <constant>VIDIOC_QBUF</constant> ioctl.</entry> | ||
| 737 | </row> | ||
| 738 | </tbody> | ||
| 739 | </tgroup> | ||
| 740 | </table> | ||
| 741 | |||
| 742 | <table pgwide="1" frame="none" id="v4l2-memory"> | ||
| 743 | <title>enum v4l2_memory</title> | ||
| 744 | <tgroup cols="3"> | ||
| 745 | &cs-def; | ||
| 746 | <tbody valign="top"> | ||
| 747 | <row> | ||
| 748 | <entry><constant>V4L2_MEMORY_MMAP</constant></entry> | ||
| 749 | <entry>1</entry> | ||
| 750 | <entry>The buffer is used for <link linkend="mmap">memory | ||
| 751 | mapping</link> I/O.</entry> | ||
| 752 | </row> | ||
| 753 | <row> | ||
| 754 | <entry><constant>V4L2_MEMORY_USERPTR</constant></entry> | ||
| 755 | <entry>2</entry> | ||
| 756 | <entry>The buffer is used for <link linkend="userp">user | ||
| 757 | pointer</link> I/O.</entry> | ||
| 758 | </row> | ||
| 759 | <row> | ||
| 760 | <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry> | ||
| 761 | <entry>3</entry> | ||
| 762 | <entry>[to do]</entry> | ||
| 763 | </row> | ||
| 764 | </tbody> | ||
| 765 | </tgroup> | ||
| 766 | </table> | ||
| 767 | |||
| 768 | <section> | ||
| 769 | <title>Timecodes</title> | ||
| 770 | |||
| 771 | <para>The <structname>v4l2_timecode</structname> structure is | ||
| 772 | designed to hold a <xref linkend="smpte12m" /> or similar timecode. | ||
| 773 | (struct <structname>timeval</structname> timestamps are stored in | ||
| 774 | &v4l2-buffer; field <structfield>timestamp</structfield>.)</para> | ||
| 775 | |||
| 776 | <table frame="none" pgwide="1" id="v4l2-timecode"> | ||
| 777 | <title>struct <structname>v4l2_timecode</structname></title> | ||
| 778 | <tgroup cols="3"> | ||
| 779 | &cs-str; | ||
| 780 | <tbody valign="top"> | ||
| 781 | <row> | ||
| 782 | <entry>__u32</entry> | ||
| 783 | <entry><structfield>type</structfield></entry> | ||
| 784 | <entry>Frame rate the timecodes are based on, see <xref | ||
| 785 | linkend="timecode-type" />.</entry> | ||
| 786 | </row> | ||
| 787 | <row> | ||
| 788 | <entry>__u32</entry> | ||
| 789 | <entry><structfield>flags</structfield></entry> | ||
| 790 | <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry> | ||
| 791 | </row> | ||
| 792 | <row> | ||
| 793 | <entry>__u8</entry> | ||
| 794 | <entry><structfield>frames</structfield></entry> | ||
| 795 | <entry>Frame count, 0 ... 23/24/29/49/59, depending on the | ||
| 796 | type of timecode.</entry> | ||
| 797 | </row> | ||
| 798 | <row> | ||
| 799 | <entry>__u8</entry> | ||
| 800 | <entry><structfield>seconds</structfield></entry> | ||
| 801 | <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry> | ||
| 802 | </row> | ||
| 803 | <row> | ||
| 804 | <entry>__u8</entry> | ||
| 805 | <entry><structfield>minutes</structfield></entry> | ||
| 806 | <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry> | ||
| 807 | </row> | ||
| 808 | <row> | ||
| 809 | <entry>__u8</entry> | ||
| 810 | <entry><structfield>hours</structfield></entry> | ||
| 811 | <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry> | ||
| 812 | </row> | ||
| 813 | <row> | ||
| 814 | <entry>__u8</entry> | ||
| 815 | <entry><structfield>userbits</structfield>[4]</entry> | ||
| 816 | <entry>The "user group" bits from the timecode.</entry> | ||
| 817 | </row> | ||
| 818 | </tbody> | ||
| 819 | </tgroup> | ||
| 820 | </table> | ||
| 821 | |||
| 822 | <table frame="none" pgwide="1" id="timecode-type"> | ||
| 823 | <title>Timecode Types</title> | ||
| 824 | <tgroup cols="3"> | ||
| 825 | &cs-def; | ||
| 826 | <tbody valign="top"> | ||
| 827 | <row> | ||
| 828 | <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry> | ||
| 829 | <entry>1</entry> | ||
| 830 | <entry>24 frames per second, i. e. film.</entry> | ||
| 831 | </row> | ||
| 832 | <row> | ||
| 833 | <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry> | ||
| 834 | <entry>2</entry> | ||
| 835 | <entry>25 frames per second, &ie; PAL or SECAM video.</entry> | ||
| 836 | </row> | ||
| 837 | <row> | ||
| 838 | <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry> | ||
| 839 | <entry>3</entry> | ||
| 840 | <entry>30 frames per second, &ie; NTSC video.</entry> | ||
| 841 | </row> | ||
| 842 | <row> | ||
| 843 | <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry> | ||
| 844 | <entry>4</entry> | ||
| 845 | <entry></entry> | ||
| 846 | </row> | ||
| 847 | <row> | ||
| 848 | <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry> | ||
| 849 | <entry>5</entry> | ||
| 850 | <entry></entry> | ||
| 851 | </row> | ||
| 852 | </tbody> | ||
| 853 | </tgroup> | ||
| 854 | </table> | ||
| 855 | |||
| 856 | <table frame="none" pgwide="1" id="timecode-flags"> | ||
| 857 | <title>Timecode Flags</title> | ||
| 858 | <tgroup cols="3"> | ||
| 859 | &cs-def; | ||
| 860 | <tbody valign="top"> | ||
| 861 | <row> | ||
| 862 | <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry> | ||
| 863 | <entry>0x0001</entry> | ||
| 864 | <entry>Indicates "drop frame" semantics for counting frames | ||
| 865 | in 29.97 fps material. When set, frame numbers 0 and 1 at the start of | ||
| 866 | each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the | ||
| 867 | count.</entry> | ||
| 868 | </row> | ||
| 869 | <row> | ||
| 870 | <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry> | ||
| 871 | <entry>0x0002</entry> | ||
| 872 | <entry>The "color frame" flag.</entry> | ||
| 873 | </row> | ||
| 874 | <row> | ||
| 875 | <entry><constant>V4L2_TC_USERBITS_field</constant></entry> | ||
| 876 | <entry>0x000C</entry> | ||
| 877 | <entry>Field mask for the "binary group flags".</entry> | ||
| 878 | </row> | ||
| 879 | <row> | ||
| 880 | <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry> | ||
| 881 | <entry>0x0000</entry> | ||
| 882 | <entry>Unspecified format.</entry> | ||
| 883 | </row> | ||
| 884 | <row> | ||
| 885 | <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry> | ||
| 886 | <entry>0x0008</entry> | ||
| 887 | <entry>8-bit ISO characters.</entry> | ||
| 888 | </row> | ||
| 889 | </tbody> | ||
| 890 | </tgroup> | ||
| 891 | </table> | ||
| 892 | </section> | ||
| 893 | </section> | ||
| 894 | |||
| 895 | <section id="field-order"> | ||
| 896 | <title>Field Order</title> | ||
| 897 | |||
| 898 | <para>We have to distinguish between progressive and interlaced | ||
| 899 | video. Progressive video transmits all lines of a video image | ||
| 900 | sequentially. Interlaced video divides an image into two fields, | ||
| 901 | containing only the odd and even lines of the image, respectively. | ||
| 902 | Alternating the so called odd and even field are transmitted, and due | ||
| 903 | to a small delay between fields a cathode ray TV displays the lines | ||
| 904 | interleaved, yielding the original frame. This curious technique was | ||
| 905 | invented because at refresh rates similar to film the image would | ||
| 906 | fade out too quickly. Transmitting fields reduces the flicker without | ||
| 907 | the necessity of doubling the frame rate and with it the bandwidth | ||
| 908 | required for each channel.</para> | ||
| 909 | |||
| 910 | <para>It is important to understand a video camera does not expose | ||
| 911 | one frame at a time, merely transmitting the frames separated into | ||
| 912 | fields. The fields are in fact captured at two different instances in | ||
| 913 | time. An object on screen may well move between one field and the | ||
| 914 | next. For applications analysing motion it is of paramount importance | ||
| 915 | to recognize which field of a frame is older, the <emphasis>temporal | ||
| 916 | order</emphasis>.</para> | ||
| 917 | |||
| 918 | <para>When the driver provides or accepts images field by field | ||
| 919 | rather than interleaved, it is also important applications understand | ||
| 920 | how the fields combine to frames. We distinguish between top and | ||
| 921 | bottom fields, the <emphasis>spatial order</emphasis>: The first line | ||
| 922 | of the top field is the first line of an interlaced frame, the first | ||
| 923 | line of the bottom field is the second line of that frame.</para> | ||
| 924 | |||
| 925 | <para>However because fields were captured one after the other, | ||
| 926 | arguing whether a frame commences with the top or bottom field is | ||
| 927 | pointless. Any two successive top and bottom, or bottom and top fields | ||
| 928 | yield a valid frame. Only when the source was progressive to begin | ||
| 929 | with, ⪚ when transferring film to video, two fields may come from | ||
| 930 | the same frame, creating a natural order.</para> | ||
| 931 | |||
| 932 | <para>Counter to intuition the top field is not necessarily the | ||
| 933 | older field. Whether the older field contains the top or bottom lines | ||
| 934 | is a convention determined by the video standard. Hence the | ||
| 935 | distinction between temporal and spatial order of fields. The diagrams | ||
| 936 | below should make this clearer.</para> | ||
| 937 | |||
| 938 | <para>All video capture and output devices must report the current | ||
| 939 | field order. Some drivers may permit the selection of a different | ||
| 940 | order, to this end applications initialize the | ||
| 941 | <structfield>field</structfield> field of &v4l2-pix-format; before | ||
| 942 | calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should | ||
| 943 | have the value <constant>V4L2_FIELD_ANY</constant> (0).</para> | ||
| 944 | |||
| 945 | <table frame="none" pgwide="1" id="v4l2-field"> | ||
| 946 | <title>enum v4l2_field</title> | ||
| 947 | <tgroup cols="3"> | ||
| 948 | &cs-def; | ||
| 949 | <tbody valign="top"> | ||
| 950 | <row> | ||
| 951 | <entry><constant>V4L2_FIELD_ANY</constant></entry> | ||
| 952 | <entry>0</entry> | ||
| 953 | <entry>Applications request this field order when any | ||
| 954 | one of the <constant>V4L2_FIELD_NONE</constant>, | ||
| 955 | <constant>V4L2_FIELD_TOP</constant>, | ||
| 956 | <constant>V4L2_FIELD_BOTTOM</constant>, or | ||
| 957 | <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. | ||
| 958 | Drivers choose depending on hardware capabilities or e. g. the | ||
| 959 | requested image size, and return the actual field order. &v4l2-buffer; | ||
| 960 | <structfield>field</structfield> can never be | ||
| 961 | <constant>V4L2_FIELD_ANY</constant>.</entry> | ||
| 962 | </row> | ||
| 963 | <row> | ||
| 964 | <entry><constant>V4L2_FIELD_NONE</constant></entry> | ||
| 965 | <entry>1</entry> | ||
| 966 | <entry>Images are in progressive format, not interlaced. | ||
| 967 | The driver may also indicate this order when it cannot distinguish | ||
| 968 | between <constant>V4L2_FIELD_TOP</constant> and | ||
| 969 | <constant>V4L2_FIELD_BOTTOM</constant>.</entry> | ||
| 970 | </row> | ||
| 971 | <row> | ||
| 972 | <entry><constant>V4L2_FIELD_TOP</constant></entry> | ||
| 973 | <entry>2</entry> | ||
| 974 | <entry>Images consist of the top field only.</entry> | ||
| 975 | </row> | ||
| 976 | <row> | ||
| 977 | <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> | ||
| 978 | <entry>3</entry> | ||
| 979 | <entry>Images consist of the bottom field only. | ||
| 980 | Applications may wish to prevent a device from capturing interlaced | ||
| 981 | images because they will have "comb" or "feathering" artefacts around | ||
| 982 | moving objects.</entry> | ||
| 983 | </row> | ||
| 984 | <row> | ||
| 985 | <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> | ||
| 986 | <entry>4</entry> | ||
| 987 | <entry>Images contain both fields, interleaved line by | ||
| 988 | line. The temporal order of the fields (whether the top or bottom | ||
| 989 | field is first transmitted) depends on the current video standard. | ||
| 990 | M/NTSC transmits the bottom field first, all other standards the top | ||
| 991 | field first.</entry> | ||
| 992 | </row> | ||
| 993 | <row> | ||
| 994 | <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> | ||
| 995 | <entry>5</entry> | ||
| 996 | <entry>Images contain both fields, the top field lines | ||
| 997 | are stored first in memory, immediately followed by the bottom field | ||
| 998 | lines. Fields are always stored in temporal order, the older one first | ||
| 999 | in memory. Image sizes refer to the frame, not fields.</entry> | ||
| 1000 | </row> | ||
| 1001 | <row> | ||
| 1002 | <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> | ||
| 1003 | <entry>6</entry> | ||
| 1004 | <entry>Images contain both fields, the bottom field | ||
| 1005 | lines are stored first in memory, immediately followed by the top | ||
| 1006 | field lines. Fields are always stored in temporal order, the older one | ||
| 1007 | first in memory. Image sizes refer to the frame, not fields.</entry> | ||
| 1008 | </row> | ||
| 1009 | <row> | ||
| 1010 | <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> | ||
| 1011 | <entry>7</entry> | ||
| 1012 | <entry>The two fields of a frame are passed in separate | ||
| 1013 | buffers, in temporal order, &ie; the older one first. To indicate the field | ||
| 1014 | parity (whether the current field is a top or bottom field) the driver | ||
| 1015 | or application, depending on data direction, must set &v4l2-buffer; | ||
| 1016 | <structfield>field</structfield> to | ||
| 1017 | <constant>V4L2_FIELD_TOP</constant> or | ||
| 1018 | <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair | ||
| 1019 | to build a frame. If fields are successive, without any dropped fields | ||
| 1020 | between them (fields can drop individually), can be determined from | ||
| 1021 | the &v4l2-buffer; <structfield>sequence</structfield> field. Image | ||
| 1022 | sizes refer to the frame, not fields. This format cannot be selected | ||
| 1023 | when using the read/write I/O method.<!-- Where it's indistinguishable | ||
| 1024 | from V4L2_FIELD_SEQ_*. --></entry> | ||
| 1025 | </row> | ||
| 1026 | <row> | ||
| 1027 | <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry> | ||
| 1028 | <entry>8</entry> | ||
| 1029 | <entry>Images contain both fields, interleaved line by | ||
| 1030 | line, top field first. The top field is transmitted first.</entry> | ||
| 1031 | </row> | ||
| 1032 | <row> | ||
| 1033 | <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry> | ||
| 1034 | <entry>9</entry> | ||
| 1035 | <entry>Images contain both fields, interleaved line by | ||
| 1036 | line, top field first. The bottom field is transmitted first.</entry> | ||
| 1037 | </row> | ||
| 1038 | </tbody> | ||
| 1039 | </tgroup> | ||
| 1040 | </table> | ||
| 1041 | |||
| 1042 | <figure id="fieldseq-tb"> | ||
| 1043 | <title>Field Order, Top Field First Transmitted</title> | ||
| 1044 | <mediaobject> | ||
| 1045 | <imageobject> | ||
| 1046 | <imagedata fileref="fieldseq_tb.pdf" format="PS" /> | ||
| 1047 | </imageobject> | ||
| 1048 | <imageobject> | ||
| 1049 | <imagedata fileref="fieldseq_tb.gif" format="GIF" /> | ||
| 1050 | </imageobject> | ||
| 1051 | </mediaobject> | ||
| 1052 | </figure> | ||
| 1053 | |||
| 1054 | <figure id="fieldseq-bt"> | ||
| 1055 | <title>Field Order, Bottom Field First Transmitted</title> | ||
| 1056 | <mediaobject> | ||
| 1057 | <imageobject> | ||
| 1058 | <imagedata fileref="fieldseq_bt.pdf" format="PS" /> | ||
| 1059 | </imageobject> | ||
| 1060 | <imageobject> | ||
| 1061 | <imagedata fileref="fieldseq_bt.gif" format="GIF" /> | ||
| 1062 | </imageobject> | ||
| 1063 | </mediaobject> | ||
| 1064 | </figure> | ||
| 1065 | </section> | ||
| 1066 | |||
| 1067 | <!-- | ||
| 1068 | Local Variables: | ||
| 1069 | mode: sgml | ||
| 1070 | sgml-parent-document: "v4l2.sgml" | ||
| 1071 | indent-tabs-mode: nil | ||
| 1072 | End: | ||
| 1073 | --> | ||
diff --git a/Documentation/DocBook/v4l/keytable.c.xml b/Documentation/DocBook/v4l/keytable.c.xml new file mode 100644 index 000000000000..d53254a3be15 --- /dev/null +++ b/Documentation/DocBook/v4l/keytable.c.xml | |||
| @@ -0,0 +1,172 @@ | |||
| 1 | <programlisting> | ||
| 2 | /* keytable.c - This program allows checking/replacing keys at IR | ||
| 3 | |||
| 4 | Copyright (C) 2006-2009 Mauro Carvalho Chehab <mchehab@infradead.org> | ||
| 5 | |||
| 6 | This program is free software; you can redistribute it and/or modify | ||
| 7 | it under the terms of the GNU General Public License as published by | ||
| 8 | the Free Software Foundation, version 2 of the License. | ||
| 9 | |||
| 10 | This program is distributed in the hope that it will be useful, | ||
| 11 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
| 13 | GNU General Public License for more details. | ||
| 14 | */ | ||
| 15 | |||
| 16 | #include <ctype.h> | ||
| 17 | #include <errno.h> | ||
| 18 | #include <fcntl.h> | ||
| 19 | #include <stdio.h> | ||
| 20 | #include <stdlib.h> | ||
| 21 | #include <string.h> | ||
| 22 | #include <linux/input.h> | ||
| 23 | #include <sys/ioctl.h> | ||
| 24 | |||
| 25 | #include "parse.h" | ||
| 26 | |||
| 27 | void prtcode (int *codes) | ||
| 28 | { | ||
| 29 | struct parse_key *p; | ||
| 30 | |||
| 31 | for (p=keynames;p->name!=NULL;p++) { | ||
| 32 | if (p->value == (unsigned)codes[1]) { | ||
| 33 | printf("scancode 0x%04x = %s (0x%02x)\n", codes[0], p->name, codes[1]); | ||
| 34 | return; | ||
| 35 | } | ||
| 36 | } | ||
| 37 | |||
| 38 | if (isprint (codes[1])) | ||
| 39 | printf("scancode %d = '%c' (0x%02x)\n", codes[0], codes[1], codes[1]); | ||
| 40 | else | ||
| 41 | printf("scancode %d = 0x%02x\n", codes[0], codes[1]); | ||
| 42 | } | ||
| 43 | |||
| 44 | int parse_code(char *string) | ||
| 45 | { | ||
| 46 | struct parse_key *p; | ||
| 47 | |||
| 48 | for (p=keynames;p->name!=NULL;p++) { | ||
| 49 | if (!strcasecmp(p->name, string)) { | ||
| 50 | return p->value; | ||
| 51 | } | ||
| 52 | } | ||
| 53 | return -1; | ||
| 54 | } | ||
| 55 | |||
| 56 | int main (int argc, char *argv[]) | ||
| 57 | { | ||
| 58 | int fd; | ||
| 59 | unsigned int i, j; | ||
| 60 | int codes[2]; | ||
| 61 | |||
| 62 | if (argc<2 || argc>4) { | ||
| 63 | printf ("usage: %s <device> to get table; or\n" | ||
| 64 | " %s <device> <scancode> <keycode>\n" | ||
| 65 | " %s <device> <keycode_file>\n",*argv,*argv,*argv); | ||
| 66 | return -1; | ||
| 67 | } | ||
| 68 | |||
| 69 | if ((fd = open(argv[1], O_RDONLY)) < 0) { | ||
| 70 | perror("Couldn't open input device"); | ||
| 71 | return(-1); | ||
| 72 | } | ||
| 73 | |||
| 74 | if (argc==4) { | ||
| 75 | int value; | ||
| 76 | |||
| 77 | value=parse_code(argv[3]); | ||
| 78 | |||
| 79 | if (value==-1) { | ||
| 80 | value = strtol(argv[3], NULL, 0); | ||
| 81 | if (errno) | ||
| 82 | perror("value"); | ||
| 83 | } | ||
| 84 | |||
| 85 | codes [0] = (unsigned) strtol(argv[2], NULL, 0); | ||
| 86 | codes [1] = (unsigned) value; | ||
| 87 | |||
| 88 | if(ioctl(fd, EVIOCSKEYCODE, codes)) | ||
| 89 | perror ("EVIOCSKEYCODE"); | ||
| 90 | |||
| 91 | if(ioctl(fd, EVIOCGKEYCODE, codes)==0) | ||
| 92 | prtcode(codes); | ||
| 93 | return 0; | ||
| 94 | } | ||
| 95 | |||
| 96 | if (argc==3) { | ||
| 97 | FILE *fin; | ||
| 98 | int value; | ||
| 99 | char *scancode, *keycode, s[2048]; | ||
| 100 | |||
| 101 | fin=fopen(argv[2],"r"); | ||
| 102 | if (fin==NULL) { | ||
| 103 | perror ("opening keycode file"); | ||
| 104 | return -1; | ||
| 105 | } | ||
| 106 | |||
| 107 | /* Clears old table */ | ||
| 108 | for (j = 0; j < 256; j++) { | ||
| 109 | for (i = 0; i < 256; i++) { | ||
| 110 | codes[0] = (j << 8) | i; | ||
| 111 | codes[1] = KEY_RESERVED; | ||
| 112 | ioctl(fd, EVIOCSKEYCODE, codes); | ||
| 113 | } | ||
| 114 | } | ||
| 115 | |||
| 116 | while (fgets(s,sizeof(s),fin)) { | ||
| 117 | scancode=strtok(s,"\n\t =:"); | ||
| 118 | if (!scancode) { | ||
| 119 | perror ("parsing input file scancode"); | ||
| 120 | return -1; | ||
| 121 | } | ||
| 122 | if (!strcasecmp(scancode, "scancode")) { | ||
| 123 | scancode = strtok(NULL,"\n\t =:"); | ||
| 124 | if (!scancode) { | ||
| 125 | perror ("parsing input file scancode"); | ||
| 126 | return -1; | ||
| 127 | } | ||
| 128 | } | ||
| 129 | |||
| 130 | keycode=strtok(NULL,"\n\t =:("); | ||
| 131 | if (!keycode) { | ||
| 132 | perror ("parsing input file keycode"); | ||
| 133 | return -1; | ||
| 134 | } | ||
| 135 | |||
| 136 | // printf ("parsing %s=%s:", scancode, keycode); | ||
| 137 | value=parse_code(keycode); | ||
| 138 | // printf ("\tvalue=%d\n",value); | ||
| 139 | |||
| 140 | if (value==-1) { | ||
| 141 | value = strtol(keycode, NULL, 0); | ||
| 142 | if (errno) | ||
| 143 | perror("value"); | ||
| 144 | } | ||
| 145 | |||
| 146 | codes [0] = (unsigned) strtol(scancode, NULL, 0); | ||
| 147 | codes [1] = (unsigned) value; | ||
| 148 | |||
| 149 | // printf("\t%04x=%04x\n",codes[0], codes[1]); | ||
| 150 | if(ioctl(fd, EVIOCSKEYCODE, codes)) { | ||
| 151 | fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]); | ||
| 152 | perror ("EVIOCSKEYCODE"); | ||
| 153 | } | ||
| 154 | |||
| 155 | if(ioctl(fd, EVIOCGKEYCODE, codes)==0) | ||
| 156 | prtcode(codes); | ||
| 157 | } | ||
| 158 | return 0; | ||
| 159 | } | ||
| 160 | |||
| 161 | /* Get scancode table */ | ||
| 162 | for (j = 0; j < 256; j++) { | ||
| 163 | for (i = 0; i < 256; i++) { | ||
| 164 | codes[0] = (j << 8) | i; | ||
| 165 | if (!ioctl(fd, EVIOCGKEYCODE, codes) && codes[1] != KEY_RESERVED) | ||
| 166 | prtcode(codes); | ||
| 167 | } | ||
| 168 | } | ||
| 169 | return 0; | ||
| 170 | } | ||
| 171 | |||
| 172 | </programlisting> | ||
diff --git a/Documentation/DocBook/v4l/libv4l.xml b/Documentation/DocBook/v4l/libv4l.xml new file mode 100644 index 000000000000..c14fc3db2a81 --- /dev/null +++ b/Documentation/DocBook/v4l/libv4l.xml | |||
| @@ -0,0 +1,167 @@ | |||
| 1 | <title>Libv4l Userspace Library</title> | ||
| 2 | <section id="libv4l-introduction"> | ||
| 3 | <title>Introduction</title> | ||
| 4 | |||
| 5 | <para>libv4l is a collection of libraries which adds a thin abstraction | ||
| 6 | layer on top of video4linux2 devices. The purpose of this (thin) layer | ||
| 7 | is to make it easy for application writers to support a wide variety of | ||
| 8 | devices without having to write separate code for different devices in the | ||
| 9 | same class.</para> | ||
| 10 | <para>An example of using libv4l is provided by | ||
| 11 | <link linkend='v4l2grab-example'>v4l2grab</link>. | ||
| 12 | </para> | ||
| 13 | |||
| 14 | <para>libv4l consists of 3 different libraries:</para> | ||
| 15 | <section> | ||
| 16 | <title>libv4lconvert</title> | ||
| 17 | |||
| 18 | <para>libv4lconvert is a library that converts several | ||
| 19 | different pixelformats found in V4L2 drivers into a few common RGB and | ||
| 20 | YUY formats.</para> | ||
| 21 | <para>It currently accepts the following V4L2 driver formats: | ||
| 22 | <link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>, | ||
| 23 | <link linkend="V4L2-PIX-FMT-HM12"><constant>V4L2_PIX_FMT_HM12</constant></link>, | ||
| 24 | <link linkend="V4L2-PIX-FMT-JPEG"><constant>V4L2_PIX_FMT_JPEG</constant></link>, | ||
| 25 | <link linkend="V4L2-PIX-FMT-MJPEG"><constant>V4L2_PIX_FMT_MJPEG</constant></link>, | ||
| 26 | <link linkend="V4L2-PIX-FMT-MR97310A"><constant>V4L2_PIX_FMT_MR97310A</constant></link>, | ||
| 27 | <link linkend="V4L2-PIX-FMT-OV511"><constant>V4L2_PIX_FMT_OV511</constant></link>, | ||
| 28 | <link linkend="V4L2-PIX-FMT-OV518"><constant>V4L2_PIX_FMT_OV518</constant></link>, | ||
| 29 | <link linkend="V4L2-PIX-FMT-PAC207"><constant>V4L2_PIX_FMT_PAC207</constant></link>, | ||
| 30 | <link linkend="V4L2-PIX-FMT-PJPG"><constant>V4L2_PIX_FMT_PJPG</constant></link>, | ||
| 31 | <link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>, | ||
| 32 | <link linkend="V4L2-PIX-FMT-SBGGR8"><constant>V4L2_PIX_FMT_SBGGR8</constant></link>, | ||
| 33 | <link linkend="V4L2-PIX-FMT-SGBRG8"><constant>V4L2_PIX_FMT_SGBRG8</constant></link>, | ||
| 34 | <link linkend="V4L2-PIX-FMT-SGRBG8"><constant>V4L2_PIX_FMT_SGRBG8</constant></link>, | ||
| 35 | <link linkend="V4L2-PIX-FMT-SN9C10X"><constant>V4L2_PIX_FMT_SN9C10X</constant></link>, | ||
| 36 | <link linkend="V4L2-PIX-FMT-SN9C20X-I420"><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></link>, | ||
| 37 | <link linkend="V4L2-PIX-FMT-SPCA501"><constant>V4L2_PIX_FMT_SPCA501</constant></link>, | ||
| 38 | <link linkend="V4L2-PIX-FMT-SPCA505"><constant>V4L2_PIX_FMT_SPCA505</constant></link>, | ||
| 39 | <link linkend="V4L2-PIX-FMT-SPCA508"><constant>V4L2_PIX_FMT_SPCA508</constant></link>, | ||
| 40 | <link linkend="V4L2-PIX-FMT-SPCA561"><constant>V4L2_PIX_FMT_SPCA561</constant></link>, | ||
| 41 | <link linkend="V4L2-PIX-FMT-SQ905C"><constant>V4L2_PIX_FMT_SQ905C</constant></link>, | ||
| 42 | <constant>V4L2_PIX_FMT_SRGGB8</constant>, | ||
| 43 | <link linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link>, | ||
| 44 | <link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>, | ||
| 45 | <link linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link>, | ||
| 46 | <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>, | ||
| 47 | and <link linkend="V4L2-PIX-FMT-YVYU"><constant>V4L2_PIX_FMT_YVYU</constant></link>. | ||
| 48 | </para> | ||
| 49 | <para>Later on libv4lconvert was expanded to also be able to do | ||
| 50 | various video processing functions to improve webcam video quality. | ||
| 51 | The video processing is split in to 2 parts: libv4lconvert/control and | ||
| 52 | libv4lconvert/processing.</para> | ||
| 53 | |||
| 54 | <para>The control part is used to offer video controls which can | ||
| 55 | be used to control the video processing functions made available by | ||
| 56 | libv4lconvert/processing. These controls are stored application wide | ||
| 57 | (until reboot) by using a persistent shared memory object.</para> | ||
| 58 | |||
| 59 | <para>libv4lconvert/processing offers the actual video | ||
| 60 | processing functionality.</para> | ||
| 61 | </section> | ||
| 62 | <section> | ||
| 63 | <title>libv4l1</title> | ||
| 64 | <para>This library offers functions that can be used to quickly | ||
| 65 | make v4l1 applications work with v4l2 devices. These functions work exactly | ||
| 66 | like the normal open/close/etc, except that libv4l1 does full emulation of | ||
| 67 | the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it | ||
| 68 | will just pass calls through.</para> | ||
| 69 | <para>Since those functions are emulations of the old V4L1 API, | ||
| 70 | it shouldn't be used for new applications.</para> | ||
| 71 | </section> | ||
| 72 | <section> | ||
| 73 | <title>libv4l2</title> | ||
| 74 | <para>This library should be used for all modern V4L2 | ||
| 75 | applications.</para> | ||
| 76 | <para>It provides handles to call V4L2 open/ioctl/close/poll | ||
| 77 | methods. Instead of just providing the raw output of the device, it enhances | ||
| 78 | the calls in the sense that it will use libv4lconvert to provide more video | ||
| 79 | formats and to enhance the image quality.</para> | ||
| 80 | <para>In most cases, libv4l2 just passes the calls directly | ||
| 81 | through to the v4l2 driver, intercepting the calls to | ||
| 82 | <link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>, | ||
| 83 | <link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link> | ||
| 84 | <link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link> | ||
| 85 | <link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link> | ||
| 86 | and <link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link> | ||
| 87 | in order to emulate the formats | ||
| 88 | <link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>, | ||
| 89 | <link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>, | ||
| 90 | <link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>, | ||
| 91 | and <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>, | ||
| 92 | if they aren't available in the driver. | ||
| 93 | <link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link> | ||
| 94 | keeps enumerating the hardware supported formats, plus the emulated formats | ||
| 95 | offered by libv4l at the end. | ||
| 96 | </para> | ||
| 97 | <section id="libv4l-ops"> | ||
| 98 | <title>Libv4l device control functions</title> | ||
| 99 | <para>The common file operation methods are provided by | ||
| 100 | libv4l.</para> | ||
| 101 | <para>Those functions operate just like glibc | ||
| 102 | open/close/dup/ioctl/read/mmap/munmap:</para> | ||
| 103 | <itemizedlist><listitem> | ||
| 104 | <para>int v4l2_open(const char *file, int oflag, | ||
| 105 | ...) - | ||
| 106 | operates like the standard <link linkend='func-open'>open()</link> function. | ||
| 107 | </para></listitem><listitem> | ||
| 108 | <para>int v4l2_close(int fd) - | ||
| 109 | operates like the standard <link linkend='func-close'>close()</link> function. | ||
| 110 | </para></listitem><listitem> | ||
| 111 | <para>int v4l2_dup(int fd) - | ||
| 112 | operates like the standard dup() function, duplicating a file handler. | ||
| 113 | </para></listitem><listitem> | ||
| 114 | <para>int v4l2_ioctl (int fd, unsigned long int request, ...) - | ||
| 115 | operates like the standard <link linkend='func-ioctl'>ioctl()</link> function. | ||
| 116 | </para></listitem><listitem> | ||
| 117 | <para>int v4l2_read (int fd, void* buffer, size_t n) - | ||
| 118 | operates like the standard <link linkend='func-read'>read()</link> function. | ||
| 119 | </para></listitem><listitem> | ||
| 120 | <para>void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - | ||
| 121 | operates like the standard <link linkend='func-mmap'>mmap()</link> function. | ||
| 122 | </para></listitem><listitem> | ||
| 123 | <para>int v4l2_munmap(void *_start, size_t length); - | ||
| 124 | operates like the standard <link linkend='func-munmap'>munmap()</link> function. | ||
| 125 | </para></listitem> | ||
| 126 | </itemizedlist> | ||
| 127 | <para>Those functions provide additional control:</para> | ||
| 128 | <itemizedlist><listitem> | ||
| 129 | <para>int v4l2_fd_open(int fd, int v4l2_flags) - | ||
| 130 | opens an already opened fd for further use through v4l2lib and possibly | ||
| 131 | modify libv4l2's default behavior through the v4l2_flags argument. | ||
| 132 | Currently, v4l2_flags can be <constant>V4L2_DISABLE_CONVERSION</constant>, | ||
| 133 | to disable format conversion. | ||
| 134 | </para></listitem><listitem> | ||
| 135 | <para>int v4l2_set_control(int fd, int cid, int value) - | ||
| 136 | This function takes a value of 0 - 65535, and then scales that range to | ||
| 137 | the actual range of the given v4l control id, and then if the cid exists | ||
| 138 | and is not locked sets the cid to the scaled value. | ||
| 139 | </para></listitem><listitem> | ||
| 140 | <para>int v4l2_get_control(int fd, int cid) - | ||
| 141 | This function returns a value of 0 - 65535, scaled to from the actual range | ||
| 142 | of the given v4l control id. when the cid does not exist, could not be | ||
| 143 | accessed for some reason, or some error occured 0 is returned. | ||
| 144 | </para></listitem> | ||
| 145 | </itemizedlist> | ||
| 146 | </section> | ||
| 147 | </section> | ||
| 148 | <section> | ||
| 149 | |||
| 150 | <title>v4l1compat.so wrapper library</title> | ||
| 151 | |||
| 152 | <para>This library intercepts calls to | ||
| 153 | open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l | ||
| 154 | counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also | ||
| 155 | emulates V4L1 calls via V4L2 API.</para> | ||
| 156 | <para>It allows usage of binary legacy applications that | ||
| 157 | still don't use libv4l.</para> | ||
| 158 | </section> | ||
| 159 | |||
| 160 | </section> | ||
| 161 | <!-- | ||
| 162 | Local Variables: | ||
| 163 | mode: sgml | ||
| 164 | sgml-parent-document: "v4l2.sgml" | ||
| 165 | indent-tabs-mode: nil | ||
| 166 | End: | ||
| 167 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-grey.xml b/Documentation/DocBook/v4l/pixfmt-grey.xml new file mode 100644 index 000000000000..3b72bc6b2de7 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-grey.xml | |||
| @@ -0,0 +1,70 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-GREY"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_GREY ('GREY')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_GREY</constant></refname> | ||
| 8 | <refpurpose>Grey-scale image</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This is a grey-scale image. It is really a degenerate | ||
| 14 | Y'CbCr format which simply contains no Cb or Cr data.</para> | ||
| 15 | |||
| 16 | <example> | ||
| 17 | <title><constant>V4L2_PIX_FMT_GREY</constant> 4 × 4 | ||
| 18 | pixel image</title> | ||
| 19 | |||
| 20 | <formalpara> | ||
| 21 | <title>Byte Order.</title> | ||
| 22 | <para>Each cell is one byte. | ||
| 23 | <informaltable frame="none"> | ||
| 24 | <tgroup cols="5" align="center"> | ||
| 25 | <colspec align="left" colwidth="2*" /> | ||
| 26 | <tbody valign="top"> | ||
| 27 | <row> | ||
| 28 | <entry>start + 0:</entry> | ||
| 29 | <entry>Y'<subscript>00</subscript></entry> | ||
| 30 | <entry>Y'<subscript>01</subscript></entry> | ||
| 31 | <entry>Y'<subscript>02</subscript></entry> | ||
| 32 | <entry>Y'<subscript>03</subscript></entry> | ||
| 33 | </row> | ||
| 34 | <row> | ||
| 35 | <entry>start + 4:</entry> | ||
| 36 | <entry>Y'<subscript>10</subscript></entry> | ||
| 37 | <entry>Y'<subscript>11</subscript></entry> | ||
| 38 | <entry>Y'<subscript>12</subscript></entry> | ||
| 39 | <entry>Y'<subscript>13</subscript></entry> | ||
| 40 | </row> | ||
| 41 | <row> | ||
| 42 | <entry>start + 8:</entry> | ||
| 43 | <entry>Y'<subscript>20</subscript></entry> | ||
| 44 | <entry>Y'<subscript>21</subscript></entry> | ||
| 45 | <entry>Y'<subscript>22</subscript></entry> | ||
| 46 | <entry>Y'<subscript>23</subscript></entry> | ||
| 47 | </row> | ||
| 48 | <row> | ||
| 49 | <entry>start + 12:</entry> | ||
| 50 | <entry>Y'<subscript>30</subscript></entry> | ||
| 51 | <entry>Y'<subscript>31</subscript></entry> | ||
| 52 | <entry>Y'<subscript>32</subscript></entry> | ||
| 53 | <entry>Y'<subscript>33</subscript></entry> | ||
| 54 | </row> | ||
| 55 | </tbody> | ||
| 56 | </tgroup> | ||
| 57 | </informaltable> | ||
| 58 | </para> | ||
| 59 | </formalpara> | ||
| 60 | </example> | ||
| 61 | </refsect1> | ||
| 62 | </refentry> | ||
| 63 | |||
| 64 | <!-- | ||
| 65 | Local Variables: | ||
| 66 | mode: sgml | ||
| 67 | sgml-parent-document: "pixfmt.sgml" | ||
| 68 | indent-tabs-mode: nil | ||
| 69 | End: | ||
| 70 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-nv12.xml b/Documentation/DocBook/v4l/pixfmt-nv12.xml new file mode 100644 index 000000000000..873f67035181 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-nv12.xml | |||
| @@ -0,0 +1,151 @@ | |||
| 1 | <refentry> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname id="V4L2-PIX-FMT-NV12"><constant>V4L2_PIX_FMT_NV12</constant></refname> | ||
| 8 | <refname id="V4L2-PIX-FMT-NV21"><constant>V4L2_PIX_FMT_NV21</constant></refname> | ||
| 9 | <refpurpose>Formats with ½ horizontal and vertical | ||
| 10 | chroma resolution, also known as YUV 4:2:0. One luminance and one | ||
| 11 | chrominance plane with alternating chroma samples as opposed to | ||
| 12 | <constant>V4L2_PIX_FMT_YVU420</constant></refpurpose> | ||
| 13 | </refnamediv> | ||
| 14 | <refsect1> | ||
| 15 | <title>Description</title> | ||
| 16 | |||
| 17 | <para>These are two-plane versions of the YUV 4:2:0 format. | ||
| 18 | The three components are separated into two sub-images or planes. The | ||
| 19 | Y plane is first. The Y plane has one byte per pixel. For | ||
| 20 | <constant>V4L2_PIX_FMT_NV12</constant>, a combined CbCr plane | ||
| 21 | immediately follows the Y plane in memory. The CbCr plane is the same | ||
| 22 | width, in bytes, as the Y plane (and of the image), but is half as | ||
| 23 | tall in pixels. Each CbCr pair belongs to four pixels. For example, | ||
| 24 | Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to | ||
| 25 | Y'<subscript>00</subscript>, Y'<subscript>01</subscript>, | ||
| 26 | Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. | ||
| 27 | <constant>V4L2_PIX_FMT_NV21</constant> is the same except the Cb and | ||
| 28 | Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> | ||
| 29 | |||
| 30 | <para>If the Y plane has pad bytes after each row, then the | ||
| 31 | CbCr plane has as many pad bytes after its rows.</para> | ||
| 32 | |||
| 33 | <example> | ||
| 34 | <title><constant>V4L2_PIX_FMT_NV12</constant> 4 × 4 | ||
| 35 | pixel image</title> | ||
| 36 | |||
| 37 | <formalpara> | ||
| 38 | <title>Byte Order.</title> | ||
| 39 | <para>Each cell is one byte. | ||
| 40 | <informaltable frame="none"> | ||
| 41 | <tgroup cols="5" align="center"> | ||
| 42 | <colspec align="left" colwidth="2*" /> | ||
| 43 | <tbody valign="top"> | ||
| 44 | <row> | ||
| 45 | <entry>start + 0:</entry> | ||
| 46 | <entry>Y'<subscript>00</subscript></entry> | ||
| 47 | <entry>Y'<subscript>01</subscript></entry> | ||
| 48 | <entry>Y'<subscript>02</subscript></entry> | ||
| 49 | <entry>Y'<subscript>03</subscript></entry> | ||
| 50 | </row> | ||
| 51 | <row> | ||
| 52 | <entry>start + 4:</entry> | ||
| 53 | <entry>Y'<subscript>10</subscript></entry> | ||
| 54 | <entry>Y'<subscript>11</subscript></entry> | ||
| 55 | <entry>Y'<subscript>12</subscript></entry> | ||
| 56 | <entry>Y'<subscript>13</subscript></entry> | ||
| 57 | </row> | ||
| 58 | <row> | ||
| 59 | <entry>start + 8:</entry> | ||
| 60 | <entry>Y'<subscript>20</subscript></entry> | ||
| 61 | <entry>Y'<subscript>21</subscript></entry> | ||
| 62 | <entry>Y'<subscript>22</subscript></entry> | ||
| 63 | <entry>Y'<subscript>23</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 12:</entry> | ||
| 67 | <entry>Y'<subscript>30</subscript></entry> | ||
| 68 | <entry>Y'<subscript>31</subscript></entry> | ||
| 69 | <entry>Y'<subscript>32</subscript></entry> | ||
| 70 | <entry>Y'<subscript>33</subscript></entry> | ||
| 71 | </row> | ||
| 72 | <row> | ||
| 73 | <entry>start + 16:</entry> | ||
| 74 | <entry>Cb<subscript>00</subscript></entry> | ||
| 75 | <entry>Cr<subscript>00</subscript></entry> | ||
| 76 | <entry>Cb<subscript>01</subscript></entry> | ||
| 77 | <entry>Cr<subscript>01</subscript></entry> | ||
| 78 | </row> | ||
| 79 | <row> | ||
| 80 | <entry>start + 20:</entry> | ||
| 81 | <entry>Cb<subscript>10</subscript></entry> | ||
| 82 | <entry>Cr<subscript>10</subscript></entry> | ||
| 83 | <entry>Cb<subscript>11</subscript></entry> | ||
| 84 | <entry>Cr<subscript>11</subscript></entry> | ||
| 85 | </row> | ||
| 86 | </tbody> | ||
| 87 | </tgroup> | ||
| 88 | </informaltable> | ||
| 89 | </para> | ||
| 90 | </formalpara> | ||
| 91 | |||
| 92 | <formalpara> | ||
| 93 | <title>Color Sample Location.</title> | ||
| 94 | <para> | ||
| 95 | <informaltable frame="none"> | ||
| 96 | <tgroup cols="7" align="center"> | ||
| 97 | <tbody valign="top"> | ||
| 98 | <row> | ||
| 99 | <entry></entry> | ||
| 100 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 101 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>0</entry> | ||
| 105 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry></entry> | ||
| 110 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 111 | <entry></entry><entry>C</entry><entry></entry> | ||
| 112 | </row> | ||
| 113 | <row> | ||
| 114 | <entry>1</entry> | ||
| 115 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 116 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 117 | </row> | ||
| 118 | <row> | ||
| 119 | <entry></entry> | ||
| 120 | </row> | ||
| 121 | <row> | ||
| 122 | <entry>2</entry> | ||
| 123 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 124 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry></entry> | ||
| 128 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 129 | <entry></entry><entry>C</entry><entry></entry> | ||
| 130 | </row> | ||
| 131 | <row> | ||
| 132 | <entry>3</entry> | ||
| 133 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 134 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 135 | </row> | ||
| 136 | </tbody> | ||
| 137 | </tgroup> | ||
| 138 | </informaltable> | ||
| 139 | </para> | ||
| 140 | </formalpara> | ||
| 141 | </example> | ||
| 142 | </refsect1> | ||
| 143 | </refentry> | ||
| 144 | |||
| 145 | <!-- | ||
| 146 | Local Variables: | ||
| 147 | mode: sgml | ||
| 148 | sgml-parent-document: "pixfmt.sgml" | ||
| 149 | indent-tabs-mode: nil | ||
| 150 | End: | ||
| 151 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-nv16.xml b/Documentation/DocBook/v4l/pixfmt-nv16.xml new file mode 100644 index 000000000000..26094035fc04 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-nv16.xml | |||
| @@ -0,0 +1,174 @@ | |||
| 1 | <refentry> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname id="V4L2-PIX-FMT-NV16"><constant>V4L2_PIX_FMT_NV16</constant></refname> | ||
| 8 | <refname id="V4L2-PIX-FMT-NV61"><constant>V4L2_PIX_FMT_NV61</constant></refname> | ||
| 9 | <refpurpose>Formats with ½ horizontal | ||
| 10 | chroma resolution, also known as YUV 4:2:2. One luminance and one | ||
| 11 | chrominance plane with alternating chroma samples as opposed to | ||
| 12 | <constant>V4L2_PIX_FMT_YVU420</constant></refpurpose> | ||
| 13 | </refnamediv> | ||
| 14 | <refsect1> | ||
| 15 | <title>Description</title> | ||
| 16 | |||
| 17 | <para>These are two-plane versions of the YUV 4:2:2 format. | ||
| 18 | The three components are separated into two sub-images or planes. The | ||
| 19 | Y plane is first. The Y plane has one byte per pixel. For | ||
| 20 | <constant>V4L2_PIX_FMT_NV16</constant>, a combined CbCr plane | ||
| 21 | immediately follows the Y plane in memory. The CbCr plane is the same | ||
| 22 | width and height, in bytes, as the Y plane (and of the image). | ||
| 23 | Each CbCr pair belongs to two pixels. For example, | ||
| 24 | Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to | ||
| 25 | Y'<subscript>00</subscript>, Y'<subscript>01</subscript>. | ||
| 26 | <constant>V4L2_PIX_FMT_NV61</constant> is the same except the Cb and | ||
| 27 | Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> | ||
| 28 | |||
| 29 | <para>If the Y plane has pad bytes after each row, then the | ||
| 30 | CbCr plane has as many pad bytes after its rows.</para> | ||
| 31 | |||
| 32 | <example> | ||
| 33 | <title><constant>V4L2_PIX_FMT_NV16</constant> 4 × 4 | ||
| 34 | pixel image</title> | ||
| 35 | |||
| 36 | <formalpara> | ||
| 37 | <title>Byte Order.</title> | ||
| 38 | <para>Each cell is one byte. | ||
| 39 | <informaltable frame="none"> | ||
| 40 | <tgroup cols="5" align="center"> | ||
| 41 | <colspec align="left" colwidth="2*" /> | ||
| 42 | <tbody valign="top"> | ||
| 43 | <row> | ||
| 44 | <entry>start + 0:</entry> | ||
| 45 | <entry>Y'<subscript>00</subscript></entry> | ||
| 46 | <entry>Y'<subscript>01</subscript></entry> | ||
| 47 | <entry>Y'<subscript>02</subscript></entry> | ||
| 48 | <entry>Y'<subscript>03</subscript></entry> | ||
| 49 | </row> | ||
| 50 | <row> | ||
| 51 | <entry>start + 4:</entry> | ||
| 52 | <entry>Y'<subscript>10</subscript></entry> | ||
| 53 | <entry>Y'<subscript>11</subscript></entry> | ||
| 54 | <entry>Y'<subscript>12</subscript></entry> | ||
| 55 | <entry>Y'<subscript>13</subscript></entry> | ||
| 56 | </row> | ||
| 57 | <row> | ||
| 58 | <entry>start + 8:</entry> | ||
| 59 | <entry>Y'<subscript>20</subscript></entry> | ||
| 60 | <entry>Y'<subscript>21</subscript></entry> | ||
| 61 | <entry>Y'<subscript>22</subscript></entry> | ||
| 62 | <entry>Y'<subscript>23</subscript></entry> | ||
| 63 | </row> | ||
| 64 | <row> | ||
| 65 | <entry>start + 12:</entry> | ||
| 66 | <entry>Y'<subscript>30</subscript></entry> | ||
| 67 | <entry>Y'<subscript>31</subscript></entry> | ||
| 68 | <entry>Y'<subscript>32</subscript></entry> | ||
| 69 | <entry>Y'<subscript>33</subscript></entry> | ||
| 70 | </row> | ||
| 71 | <row> | ||
| 72 | <entry>start + 16:</entry> | ||
| 73 | <entry>Cb<subscript>00</subscript></entry> | ||
| 74 | <entry>Cr<subscript>00</subscript></entry> | ||
| 75 | <entry>Cb<subscript>01</subscript></entry> | ||
| 76 | <entry>Cr<subscript>01</subscript></entry> | ||
| 77 | </row> | ||
| 78 | <row> | ||
| 79 | <entry>start + 20:</entry> | ||
| 80 | <entry>Cb<subscript>10</subscript></entry> | ||
| 81 | <entry>Cr<subscript>10</subscript></entry> | ||
| 82 | <entry>Cb<subscript>11</subscript></entry> | ||
| 83 | <entry>Cr<subscript>11</subscript></entry> | ||
| 84 | </row> | ||
| 85 | <row> | ||
| 86 | <entry>start + 24:</entry> | ||
| 87 | <entry>Cb<subscript>20</subscript></entry> | ||
| 88 | <entry>Cr<subscript>20</subscript></entry> | ||
| 89 | <entry>Cb<subscript>21</subscript></entry> | ||
| 90 | <entry>Cr<subscript>21</subscript></entry> | ||
| 91 | </row> | ||
| 92 | <row> | ||
| 93 | <entry>start + 28:</entry> | ||
| 94 | <entry>Cb<subscript>30</subscript></entry> | ||
| 95 | <entry>Cr<subscript>30</subscript></entry> | ||
| 96 | <entry>Cb<subscript>31</subscript></entry> | ||
| 97 | <entry>Cr<subscript>31</subscript></entry> | ||
| 98 | </row> | ||
| 99 | </tbody> | ||
| 100 | </tgroup> | ||
| 101 | </informaltable> | ||
| 102 | </para> | ||
| 103 | </formalpara> | ||
| 104 | |||
| 105 | <formalpara> | ||
| 106 | <title>Color Sample Location.</title> | ||
| 107 | <para> | ||
| 108 | <informaltable frame="none"> | ||
| 109 | <tgroup cols="7" align="center"> | ||
| 110 | <tbody valign="top"> | ||
| 111 | <row> | ||
| 112 | <entry></entry> | ||
| 113 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 114 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 115 | </row> | ||
| 116 | <row> | ||
| 117 | <entry>0</entry> | ||
| 118 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 119 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 120 | </row> | ||
| 121 | <row> | ||
| 122 | <entry></entry> | ||
| 123 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 124 | <entry></entry><entry>C</entry><entry></entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry>1</entry> | ||
| 128 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 129 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 130 | </row> | ||
| 131 | <row> | ||
| 132 | <entry></entry> | ||
| 133 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 134 | <entry></entry><entry>C</entry><entry></entry> | ||
| 135 | </row> | ||
| 136 | <row> | ||
| 137 | <entry></entry> | ||
| 138 | </row> | ||
| 139 | <row> | ||
| 140 | <entry>2</entry> | ||
| 141 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 142 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 143 | </row> | ||
| 144 | <row> | ||
| 145 | <entry></entry> | ||
| 146 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 147 | <entry></entry><entry>C</entry><entry></entry> | ||
| 148 | </row> | ||
| 149 | <row> | ||
| 150 | <entry>3</entry> | ||
| 151 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 152 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 153 | </row> | ||
| 154 | <row> | ||
| 155 | <entry></entry> | ||
| 156 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 157 | <entry></entry><entry>C</entry><entry></entry> | ||
| 158 | </row> | ||
| 159 | </tbody> | ||
| 160 | </tgroup> | ||
| 161 | </informaltable> | ||
| 162 | </para> | ||
| 163 | </formalpara> | ||
| 164 | </example> | ||
| 165 | </refsect1> | ||
| 166 | </refentry> | ||
| 167 | |||
| 168 | <!-- | ||
| 169 | Local Variables: | ||
| 170 | mode: sgml | ||
| 171 | sgml-parent-document: "pixfmt.sgml" | ||
| 172 | indent-tabs-mode: nil | ||
| 173 | End: | ||
| 174 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml new file mode 100644 index 000000000000..d2dd697a81d8 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml | |||
| @@ -0,0 +1,862 @@ | |||
| 1 | <refentry id="packed-rgb"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>Packed RGB formats</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname>Packed RGB formats</refname> | ||
| 8 | <refpurpose>Packed RGB formats</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>These formats are designed to match the pixel formats of | ||
| 14 | typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits | ||
| 15 | per pixel. These are all packed-pixel formats, meaning all the data | ||
| 16 | for a pixel lie next to each other in memory.</para> | ||
| 17 | |||
| 18 | <para>When one of these formats is used, drivers shall report the | ||
| 19 | colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> | ||
| 20 | |||
| 21 | <table pgwide="1" frame="none" id="rgb-formats"> | ||
| 22 | <title>Packed RGB Image Formats</title> | ||
| 23 | <tgroup cols="37" align="center"> | ||
| 24 | <colspec colname="id" align="left" /> | ||
| 25 | <colspec colname="fourcc" /> | ||
| 26 | <colspec colname="bit" /> | ||
| 27 | |||
| 28 | <colspec colnum="4" colname="b07" align="center" /> | ||
| 29 | <colspec colnum="5" colname="b06" align="center" /> | ||
| 30 | <colspec colnum="6" colname="b05" align="center" /> | ||
| 31 | <colspec colnum="7" colname="b04" align="center" /> | ||
| 32 | <colspec colnum="8" colname="b03" align="center" /> | ||
| 33 | <colspec colnum="9" colname="b02" align="center" /> | ||
| 34 | <colspec colnum="10" colname="b01" align="center" /> | ||
| 35 | <colspec colnum="11" colname="b00" align="center" /> | ||
| 36 | |||
| 37 | <colspec colnum="13" colname="b17" align="center" /> | ||
| 38 | <colspec colnum="14" colname="b16" align="center" /> | ||
| 39 | <colspec colnum="15" colname="b15" align="center" /> | ||
| 40 | <colspec colnum="16" colname="b14" align="center" /> | ||
| 41 | <colspec colnum="17" colname="b13" align="center" /> | ||
| 42 | <colspec colnum="18" colname="b12" align="center" /> | ||
| 43 | <colspec colnum="19" colname="b11" align="center" /> | ||
| 44 | <colspec colnum="20" colname="b10" align="center" /> | ||
| 45 | |||
| 46 | <colspec colnum="22" colname="b27" align="center" /> | ||
| 47 | <colspec colnum="23" colname="b26" align="center" /> | ||
| 48 | <colspec colnum="24" colname="b25" align="center" /> | ||
| 49 | <colspec colnum="25" colname="b24" align="center" /> | ||
| 50 | <colspec colnum="26" colname="b23" align="center" /> | ||
| 51 | <colspec colnum="27" colname="b22" align="center" /> | ||
| 52 | <colspec colnum="28" colname="b21" align="center" /> | ||
| 53 | <colspec colnum="29" colname="b20" align="center" /> | ||
| 54 | |||
| 55 | <colspec colnum="31" colname="b37" align="center" /> | ||
| 56 | <colspec colnum="32" colname="b36" align="center" /> | ||
| 57 | <colspec colnum="33" colname="b35" align="center" /> | ||
| 58 | <colspec colnum="34" colname="b34" align="center" /> | ||
| 59 | <colspec colnum="35" colname="b33" align="center" /> | ||
| 60 | <colspec colnum="36" colname="b32" align="center" /> | ||
| 61 | <colspec colnum="37" colname="b31" align="center" /> | ||
| 62 | <colspec colnum="38" colname="b30" align="center" /> | ||
| 63 | |||
| 64 | <spanspec namest="b07" nameend="b00" spanname="b0" /> | ||
| 65 | <spanspec namest="b17" nameend="b10" spanname="b1" /> | ||
| 66 | <spanspec namest="b27" nameend="b20" spanname="b2" /> | ||
| 67 | <spanspec namest="b37" nameend="b30" spanname="b3" /> | ||
| 68 | <thead> | ||
| 69 | <row> | ||
| 70 | <entry>Identifier</entry> | ||
| 71 | <entry>Code</entry> | ||
| 72 | <entry> </entry> | ||
| 73 | <entry spanname="b0">Byte 0 in memory</entry> | ||
| 74 | <entry spanname="b1">Byte 1</entry> | ||
| 75 | <entry spanname="b2">Byte 2</entry> | ||
| 76 | <entry spanname="b3">Byte 3</entry> | ||
| 77 | </row> | ||
| 78 | <row> | ||
| 79 | <entry> </entry> | ||
| 80 | <entry> </entry> | ||
| 81 | <entry>Bit</entry> | ||
| 82 | <entry>7</entry> | ||
| 83 | <entry>6</entry> | ||
| 84 | <entry>5</entry> | ||
| 85 | <entry>4</entry> | ||
| 86 | <entry>3</entry> | ||
| 87 | <entry>2</entry> | ||
| 88 | <entry>1</entry> | ||
| 89 | <entry>0</entry> | ||
| 90 | <entry> </entry> | ||
| 91 | <entry>7</entry> | ||
| 92 | <entry>6</entry> | ||
| 93 | <entry>5</entry> | ||
| 94 | <entry>4</entry> | ||
| 95 | <entry>3</entry> | ||
| 96 | <entry>2</entry> | ||
| 97 | <entry>1</entry> | ||
| 98 | <entry>0</entry> | ||
| 99 | <entry> </entry> | ||
| 100 | <entry>7</entry> | ||
| 101 | <entry>6</entry> | ||
| 102 | <entry>5</entry> | ||
| 103 | <entry>4</entry> | ||
| 104 | <entry>3</entry> | ||
| 105 | <entry>2</entry> | ||
| 106 | <entry>1</entry> | ||
| 107 | <entry>0</entry> | ||
| 108 | <entry> </entry> | ||
| 109 | <entry>7</entry> | ||
| 110 | <entry>6</entry> | ||
| 111 | <entry>5</entry> | ||
| 112 | <entry>4</entry> | ||
| 113 | <entry>3</entry> | ||
| 114 | <entry>2</entry> | ||
| 115 | <entry>1</entry> | ||
| 116 | <entry>0</entry> | ||
| 117 | </row> | ||
| 118 | </thead> | ||
| 119 | <tbody valign="top"> | ||
| 120 | <row id="V4L2-PIX-FMT-RGB332"> | ||
| 121 | <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry> | ||
| 122 | <entry>'RGB1'</entry> | ||
| 123 | <entry></entry> | ||
| 124 | <entry>b<subscript>1</subscript></entry> | ||
| 125 | <entry>b<subscript>0</subscript></entry> | ||
| 126 | <entry>g<subscript>2</subscript></entry> | ||
| 127 | <entry>g<subscript>1</subscript></entry> | ||
| 128 | <entry>g<subscript>0</subscript></entry> | ||
| 129 | <entry>r<subscript>2</subscript></entry> | ||
| 130 | <entry>r<subscript>1</subscript></entry> | ||
| 131 | <entry>r<subscript>0</subscript></entry> | ||
| 132 | </row> | ||
| 133 | <row id="V4L2-PIX-FMT-RGB444"> | ||
| 134 | <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry> | ||
| 135 | <entry>'R444'</entry> | ||
| 136 | <entry></entry> | ||
| 137 | <entry>g<subscript>3</subscript></entry> | ||
| 138 | <entry>g<subscript>2</subscript></entry> | ||
| 139 | <entry>g<subscript>1</subscript></entry> | ||
| 140 | <entry>g<subscript>0</subscript></entry> | ||
| 141 | <entry>b<subscript>3</subscript></entry> | ||
| 142 | <entry>b<subscript>2</subscript></entry> | ||
| 143 | <entry>b<subscript>1</subscript></entry> | ||
| 144 | <entry>b<subscript>0</subscript></entry> | ||
| 145 | <entry></entry> | ||
| 146 | <entry>a<subscript>3</subscript></entry> | ||
| 147 | <entry>a<subscript>2</subscript></entry> | ||
| 148 | <entry>a<subscript>1</subscript></entry> | ||
| 149 | <entry>a<subscript>0</subscript></entry> | ||
| 150 | <entry>r<subscript>3</subscript></entry> | ||
| 151 | <entry>r<subscript>2</subscript></entry> | ||
| 152 | <entry>r<subscript>1</subscript></entry> | ||
| 153 | <entry>r<subscript>0</subscript></entry> | ||
| 154 | </row> | ||
| 155 | <row id="V4L2-PIX-FMT-RGB555"> | ||
| 156 | <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry> | ||
| 157 | <entry>'RGBO'</entry> | ||
| 158 | <entry></entry> | ||
| 159 | <entry>g<subscript>2</subscript></entry> | ||
| 160 | <entry>g<subscript>1</subscript></entry> | ||
| 161 | <entry>g<subscript>0</subscript></entry> | ||
| 162 | <entry>r<subscript>4</subscript></entry> | ||
| 163 | <entry>r<subscript>3</subscript></entry> | ||
| 164 | <entry>r<subscript>2</subscript></entry> | ||
| 165 | <entry>r<subscript>1</subscript></entry> | ||
| 166 | <entry>r<subscript>0</subscript></entry> | ||
| 167 | <entry></entry> | ||
| 168 | <entry>a</entry> | ||
| 169 | <entry>b<subscript>4</subscript></entry> | ||
| 170 | <entry>b<subscript>3</subscript></entry> | ||
| 171 | <entry>b<subscript>2</subscript></entry> | ||
| 172 | <entry>b<subscript>1</subscript></entry> | ||
| 173 | <entry>b<subscript>0</subscript></entry> | ||
| 174 | <entry>g<subscript>4</subscript></entry> | ||
| 175 | <entry>g<subscript>3</subscript></entry> | ||
| 176 | </row> | ||
| 177 | <row id="V4L2-PIX-FMT-RGB565"> | ||
| 178 | <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry> | ||
| 179 | <entry>'RGBP'</entry> | ||
| 180 | <entry></entry> | ||
| 181 | <entry>g<subscript>2</subscript></entry> | ||
| 182 | <entry>g<subscript>1</subscript></entry> | ||
| 183 | <entry>g<subscript>0</subscript></entry> | ||
| 184 | <entry>r<subscript>4</subscript></entry> | ||
| 185 | <entry>r<subscript>3</subscript></entry> | ||
| 186 | <entry>r<subscript>2</subscript></entry> | ||
| 187 | <entry>r<subscript>1</subscript></entry> | ||
| 188 | <entry>r<subscript>0</subscript></entry> | ||
| 189 | <entry></entry> | ||
| 190 | <entry>b<subscript>4</subscript></entry> | ||
| 191 | <entry>b<subscript>3</subscript></entry> | ||
| 192 | <entry>b<subscript>2</subscript></entry> | ||
| 193 | <entry>b<subscript>1</subscript></entry> | ||
| 194 | <entry>b<subscript>0</subscript></entry> | ||
| 195 | <entry>g<subscript>5</subscript></entry> | ||
| 196 | <entry>g<subscript>4</subscript></entry> | ||
| 197 | <entry>g<subscript>3</subscript></entry> | ||
| 198 | </row> | ||
| 199 | <row id="V4L2-PIX-FMT-RGB555X"> | ||
| 200 | <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry> | ||
| 201 | <entry>'RGBQ'</entry> | ||
| 202 | <entry></entry> | ||
| 203 | <entry>a</entry> | ||
| 204 | <entry>b<subscript>4</subscript></entry> | ||
| 205 | <entry>b<subscript>3</subscript></entry> | ||
| 206 | <entry>b<subscript>2</subscript></entry> | ||
| 207 | <entry>b<subscript>1</subscript></entry> | ||
| 208 | <entry>b<subscript>0</subscript></entry> | ||
| 209 | <entry>g<subscript>4</subscript></entry> | ||
| 210 | <entry>g<subscript>3</subscript></entry> | ||
| 211 | <entry></entry> | ||
| 212 | <entry>g<subscript>2</subscript></entry> | ||
| 213 | <entry>g<subscript>1</subscript></entry> | ||
| 214 | <entry>g<subscript>0</subscript></entry> | ||
| 215 | <entry>r<subscript>4</subscript></entry> | ||
| 216 | <entry>r<subscript>3</subscript></entry> | ||
| 217 | <entry>r<subscript>2</subscript></entry> | ||
| 218 | <entry>r<subscript>1</subscript></entry> | ||
| 219 | <entry>r<subscript>0</subscript></entry> | ||
| 220 | </row> | ||
| 221 | <row id="V4L2-PIX-FMT-RGB565X"> | ||
| 222 | <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry> | ||
| 223 | <entry>'RGBR'</entry> | ||
| 224 | <entry></entry> | ||
| 225 | <entry>b<subscript>4</subscript></entry> | ||
| 226 | <entry>b<subscript>3</subscript></entry> | ||
| 227 | <entry>b<subscript>2</subscript></entry> | ||
| 228 | <entry>b<subscript>1</subscript></entry> | ||
| 229 | <entry>b<subscript>0</subscript></entry> | ||
| 230 | <entry>g<subscript>5</subscript></entry> | ||
| 231 | <entry>g<subscript>4</subscript></entry> | ||
| 232 | <entry>g<subscript>3</subscript></entry> | ||
| 233 | <entry></entry> | ||
| 234 | <entry>g<subscript>2</subscript></entry> | ||
| 235 | <entry>g<subscript>1</subscript></entry> | ||
| 236 | <entry>g<subscript>0</subscript></entry> | ||
| 237 | <entry>r<subscript>4</subscript></entry> | ||
| 238 | <entry>r<subscript>3</subscript></entry> | ||
| 239 | <entry>r<subscript>2</subscript></entry> | ||
| 240 | <entry>r<subscript>1</subscript></entry> | ||
| 241 | <entry>r<subscript>0</subscript></entry> | ||
| 242 | </row> | ||
| 243 | <row id="V4L2-PIX-FMT-BGR24"> | ||
| 244 | <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> | ||
| 245 | <entry>'BGR3'</entry> | ||
| 246 | <entry></entry> | ||
| 247 | <entry>b<subscript>7</subscript></entry> | ||
| 248 | <entry>b<subscript>6</subscript></entry> | ||
| 249 | <entry>b<subscript>5</subscript></entry> | ||
| 250 | <entry>b<subscript>4</subscript></entry> | ||
| 251 | <entry>b<subscript>3</subscript></entry> | ||
| 252 | <entry>b<subscript>2</subscript></entry> | ||
| 253 | <entry>b<subscript>1</subscript></entry> | ||
| 254 | <entry>b<subscript>0</subscript></entry> | ||
| 255 | <entry></entry> | ||
| 256 | <entry>g<subscript>7</subscript></entry> | ||
| 257 | <entry>g<subscript>6</subscript></entry> | ||
| 258 | <entry>g<subscript>5</subscript></entry> | ||
| 259 | <entry>g<subscript>4</subscript></entry> | ||
| 260 | <entry>g<subscript>3</subscript></entry> | ||
| 261 | <entry>g<subscript>2</subscript></entry> | ||
| 262 | <entry>g<subscript>1</subscript></entry> | ||
| 263 | <entry>g<subscript>0</subscript></entry> | ||
| 264 | <entry></entry> | ||
| 265 | <entry>r<subscript>7</subscript></entry> | ||
| 266 | <entry>r<subscript>6</subscript></entry> | ||
| 267 | <entry>r<subscript>5</subscript></entry> | ||
| 268 | <entry>r<subscript>4</subscript></entry> | ||
| 269 | <entry>r<subscript>3</subscript></entry> | ||
| 270 | <entry>r<subscript>2</subscript></entry> | ||
| 271 | <entry>r<subscript>1</subscript></entry> | ||
| 272 | <entry>r<subscript>0</subscript></entry> | ||
| 273 | </row> | ||
| 274 | <row id="V4L2-PIX-FMT-RGB24"> | ||
| 275 | <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry> | ||
| 276 | <entry>'RGB3'</entry> | ||
| 277 | <entry></entry> | ||
| 278 | <entry>r<subscript>7</subscript></entry> | ||
| 279 | <entry>r<subscript>6</subscript></entry> | ||
| 280 | <entry>r<subscript>5</subscript></entry> | ||
| 281 | <entry>r<subscript>4</subscript></entry> | ||
| 282 | <entry>r<subscript>3</subscript></entry> | ||
| 283 | <entry>r<subscript>2</subscript></entry> | ||
| 284 | <entry>r<subscript>1</subscript></entry> | ||
| 285 | <entry>r<subscript>0</subscript></entry> | ||
| 286 | <entry></entry> | ||
| 287 | <entry>g<subscript>7</subscript></entry> | ||
| 288 | <entry>g<subscript>6</subscript></entry> | ||
| 289 | <entry>g<subscript>5</subscript></entry> | ||
| 290 | <entry>g<subscript>4</subscript></entry> | ||
| 291 | <entry>g<subscript>3</subscript></entry> | ||
| 292 | <entry>g<subscript>2</subscript></entry> | ||
| 293 | <entry>g<subscript>1</subscript></entry> | ||
| 294 | <entry>g<subscript>0</subscript></entry> | ||
| 295 | <entry></entry> | ||
| 296 | <entry>b<subscript>7</subscript></entry> | ||
| 297 | <entry>b<subscript>6</subscript></entry> | ||
| 298 | <entry>b<subscript>5</subscript></entry> | ||
| 299 | <entry>b<subscript>4</subscript></entry> | ||
| 300 | <entry>b<subscript>3</subscript></entry> | ||
| 301 | <entry>b<subscript>2</subscript></entry> | ||
| 302 | <entry>b<subscript>1</subscript></entry> | ||
| 303 | <entry>b<subscript>0</subscript></entry> | ||
| 304 | </row> | ||
| 305 | <row id="V4L2-PIX-FMT-BGR32"> | ||
| 306 | <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> | ||
| 307 | <entry>'BGR4'</entry> | ||
| 308 | <entry></entry> | ||
| 309 | <entry>b<subscript>7</subscript></entry> | ||
| 310 | <entry>b<subscript>6</subscript></entry> | ||
| 311 | <entry>b<subscript>5</subscript></entry> | ||
| 312 | <entry>b<subscript>4</subscript></entry> | ||
| 313 | <entry>b<subscript>3</subscript></entry> | ||
| 314 | <entry>b<subscript>2</subscript></entry> | ||
| 315 | <entry>b<subscript>1</subscript></entry> | ||
| 316 | <entry>b<subscript>0</subscript></entry> | ||
| 317 | <entry></entry> | ||
| 318 | <entry>g<subscript>7</subscript></entry> | ||
| 319 | <entry>g<subscript>6</subscript></entry> | ||
| 320 | <entry>g<subscript>5</subscript></entry> | ||
| 321 | <entry>g<subscript>4</subscript></entry> | ||
| 322 | <entry>g<subscript>3</subscript></entry> | ||
| 323 | <entry>g<subscript>2</subscript></entry> | ||
| 324 | <entry>g<subscript>1</subscript></entry> | ||
| 325 | <entry>g<subscript>0</subscript></entry> | ||
| 326 | <entry></entry> | ||
| 327 | <entry>r<subscript>7</subscript></entry> | ||
| 328 | <entry>r<subscript>6</subscript></entry> | ||
| 329 | <entry>r<subscript>5</subscript></entry> | ||
| 330 | <entry>r<subscript>4</subscript></entry> | ||
| 331 | <entry>r<subscript>3</subscript></entry> | ||
| 332 | <entry>r<subscript>2</subscript></entry> | ||
| 333 | <entry>r<subscript>1</subscript></entry> | ||
| 334 | <entry>r<subscript>0</subscript></entry> | ||
| 335 | <entry></entry> | ||
| 336 | <entry>a<subscript>7</subscript></entry> | ||
| 337 | <entry>a<subscript>6</subscript></entry> | ||
| 338 | <entry>a<subscript>5</subscript></entry> | ||
| 339 | <entry>a<subscript>4</subscript></entry> | ||
| 340 | <entry>a<subscript>3</subscript></entry> | ||
| 341 | <entry>a<subscript>2</subscript></entry> | ||
| 342 | <entry>a<subscript>1</subscript></entry> | ||
| 343 | <entry>a<subscript>0</subscript></entry> | ||
| 344 | </row> | ||
| 345 | <row id="V4L2-PIX-FMT-RGB32"> | ||
| 346 | <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> | ||
| 347 | <entry>'RGB4'</entry> | ||
| 348 | <entry></entry> | ||
| 349 | <entry>r<subscript>7</subscript></entry> | ||
| 350 | <entry>r<subscript>6</subscript></entry> | ||
| 351 | <entry>r<subscript>5</subscript></entry> | ||
| 352 | <entry>r<subscript>4</subscript></entry> | ||
| 353 | <entry>r<subscript>3</subscript></entry> | ||
| 354 | <entry>r<subscript>2</subscript></entry> | ||
| 355 | <entry>r<subscript>1</subscript></entry> | ||
| 356 | <entry>r<subscript>0</subscript></entry> | ||
| 357 | <entry></entry> | ||
| 358 | <entry>g<subscript>7</subscript></entry> | ||
| 359 | <entry>g<subscript>6</subscript></entry> | ||
| 360 | <entry>g<subscript>5</subscript></entry> | ||
| 361 | <entry>g<subscript>4</subscript></entry> | ||
| 362 | <entry>g<subscript>3</subscript></entry> | ||
| 363 | <entry>g<subscript>2</subscript></entry> | ||
| 364 | <entry>g<subscript>1</subscript></entry> | ||
| 365 | <entry>g<subscript>0</subscript></entry> | ||
| 366 | <entry></entry> | ||
| 367 | <entry>b<subscript>7</subscript></entry> | ||
| 368 | <entry>b<subscript>6</subscript></entry> | ||
| 369 | <entry>b<subscript>5</subscript></entry> | ||
| 370 | <entry>b<subscript>4</subscript></entry> | ||
| 371 | <entry>b<subscript>3</subscript></entry> | ||
| 372 | <entry>b<subscript>2</subscript></entry> | ||
| 373 | <entry>b<subscript>1</subscript></entry> | ||
| 374 | <entry>b<subscript>0</subscript></entry> | ||
| 375 | <entry></entry> | ||
| 376 | <entry>a<subscript>7</subscript></entry> | ||
| 377 | <entry>a<subscript>6</subscript></entry> | ||
| 378 | <entry>a<subscript>5</subscript></entry> | ||
| 379 | <entry>a<subscript>4</subscript></entry> | ||
| 380 | <entry>a<subscript>3</subscript></entry> | ||
| 381 | <entry>a<subscript>2</subscript></entry> | ||
| 382 | <entry>a<subscript>1</subscript></entry> | ||
| 383 | <entry>a<subscript>0</subscript></entry> | ||
| 384 | </row> | ||
| 385 | </tbody> | ||
| 386 | </tgroup> | ||
| 387 | </table> | ||
| 388 | |||
| 389 | <para>Bit 7 is the most significant bit. The value of a = alpha | ||
| 390 | bits is undefined when reading from the driver, ignored when writing | ||
| 391 | to the driver, except when alpha blending has been negotiated for a | ||
| 392 | <link linkend="overlay">Video Overlay</link> or <link | ||
| 393 | linkend="osd">Video Output Overlay</link>.</para> | ||
| 394 | |||
| 395 | <example> | ||
| 396 | <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 × 4 pixel | ||
| 397 | image</title> | ||
| 398 | |||
| 399 | <formalpara> | ||
| 400 | <title>Byte Order.</title> | ||
| 401 | <para>Each cell is one byte. | ||
| 402 | <informaltable frame="none"> | ||
| 403 | <tgroup cols="13" align="center"> | ||
| 404 | <colspec align="left" colwidth="2*" /> | ||
| 405 | <tbody valign="top"> | ||
| 406 | <row> | ||
| 407 | <entry>start + 0:</entry> | ||
| 408 | <entry>B<subscript>00</subscript></entry> | ||
| 409 | <entry>G<subscript>00</subscript></entry> | ||
| 410 | <entry>R<subscript>00</subscript></entry> | ||
| 411 | <entry>B<subscript>01</subscript></entry> | ||
| 412 | <entry>G<subscript>01</subscript></entry> | ||
| 413 | <entry>R<subscript>01</subscript></entry> | ||
| 414 | <entry>B<subscript>02</subscript></entry> | ||
| 415 | <entry>G<subscript>02</subscript></entry> | ||
| 416 | <entry>R<subscript>02</subscript></entry> | ||
| 417 | <entry>B<subscript>03</subscript></entry> | ||
| 418 | <entry>G<subscript>03</subscript></entry> | ||
| 419 | <entry>R<subscript>03</subscript></entry> | ||
| 420 | </row> | ||
| 421 | <row> | ||
| 422 | <entry>start + 12:</entry> | ||
| 423 | <entry>B<subscript>10</subscript></entry> | ||
| 424 | <entry>G<subscript>10</subscript></entry> | ||
| 425 | <entry>R<subscript>10</subscript></entry> | ||
| 426 | <entry>B<subscript>11</subscript></entry> | ||
| 427 | <entry>G<subscript>11</subscript></entry> | ||
| 428 | <entry>R<subscript>11</subscript></entry> | ||
| 429 | <entry>B<subscript>12</subscript></entry> | ||
| 430 | <entry>G<subscript>12</subscript></entry> | ||
| 431 | <entry>R<subscript>12</subscript></entry> | ||
| 432 | <entry>B<subscript>13</subscript></entry> | ||
| 433 | <entry>G<subscript>13</subscript></entry> | ||
| 434 | <entry>R<subscript>13</subscript></entry> | ||
| 435 | </row> | ||
| 436 | <row> | ||
| 437 | <entry>start + 24:</entry> | ||
| 438 | <entry>B<subscript>20</subscript></entry> | ||
| 439 | <entry>G<subscript>20</subscript></entry> | ||
| 440 | <entry>R<subscript>20</subscript></entry> | ||
| 441 | <entry>B<subscript>21</subscript></entry> | ||
| 442 | <entry>G<subscript>21</subscript></entry> | ||
| 443 | <entry>R<subscript>21</subscript></entry> | ||
| 444 | <entry>B<subscript>22</subscript></entry> | ||
| 445 | <entry>G<subscript>22</subscript></entry> | ||
| 446 | <entry>R<subscript>22</subscript></entry> | ||
| 447 | <entry>B<subscript>23</subscript></entry> | ||
| 448 | <entry>G<subscript>23</subscript></entry> | ||
| 449 | <entry>R<subscript>23</subscript></entry> | ||
| 450 | </row> | ||
| 451 | <row> | ||
| 452 | <entry>start + 36:</entry> | ||
| 453 | <entry>B<subscript>30</subscript></entry> | ||
| 454 | <entry>G<subscript>30</subscript></entry> | ||
| 455 | <entry>R<subscript>30</subscript></entry> | ||
| 456 | <entry>B<subscript>31</subscript></entry> | ||
| 457 | <entry>G<subscript>31</subscript></entry> | ||
| 458 | <entry>R<subscript>31</subscript></entry> | ||
| 459 | <entry>B<subscript>32</subscript></entry> | ||
| 460 | <entry>G<subscript>32</subscript></entry> | ||
| 461 | <entry>R<subscript>32</subscript></entry> | ||
| 462 | <entry>B<subscript>33</subscript></entry> | ||
| 463 | <entry>G<subscript>33</subscript></entry> | ||
| 464 | <entry>R<subscript>33</subscript></entry> | ||
| 465 | </row> | ||
| 466 | </tbody> | ||
| 467 | </tgroup> | ||
| 468 | </informaltable> | ||
| 469 | </para> | ||
| 470 | </formalpara> | ||
| 471 | </example> | ||
| 472 | |||
| 473 | <important> | ||
| 474 | <para>Drivers may interpret these formats differently.</para> | ||
| 475 | </important> | ||
| 476 | |||
| 477 | <para>Some RGB formats above are uncommon and were probably | ||
| 478 | defined in error. Drivers may interpret them as in <xref | ||
| 479 | linkend="rgb-formats-corrected" />.</para> | ||
| 480 | |||
| 481 | <table pgwide="1" frame="none" id="rgb-formats-corrected"> | ||
| 482 | <title>Packed RGB Image Formats (corrected)</title> | ||
| 483 | <tgroup cols="37" align="center"> | ||
| 484 | <colspec colname="id" align="left" /> | ||
| 485 | <colspec colname="fourcc" /> | ||
| 486 | <colspec colname="bit" /> | ||
| 487 | |||
| 488 | <colspec colnum="4" colname="b07" align="center" /> | ||
| 489 | <colspec colnum="5" colname="b06" align="center" /> | ||
| 490 | <colspec colnum="6" colname="b05" align="center" /> | ||
| 491 | <colspec colnum="7" colname="b04" align="center" /> | ||
| 492 | <colspec colnum="8" colname="b03" align="center" /> | ||
| 493 | <colspec colnum="9" colname="b02" align="center" /> | ||
| 494 | <colspec colnum="10" colname="b01" align="center" /> | ||
| 495 | <colspec colnum="11" colname="b00" align="center" /> | ||
| 496 | |||
| 497 | <colspec colnum="13" colname="b17" align="center" /> | ||
| 498 | <colspec colnum="14" colname="b16" align="center" /> | ||
| 499 | <colspec colnum="15" colname="b15" align="center" /> | ||
| 500 | <colspec colnum="16" colname="b14" align="center" /> | ||
| 501 | <colspec colnum="17" colname="b13" align="center" /> | ||
| 502 | <colspec colnum="18" colname="b12" align="center" /> | ||
| 503 | <colspec colnum="19" colname="b11" align="center" /> | ||
| 504 | <colspec colnum="20" colname="b10" align="center" /> | ||
| 505 | |||
| 506 | <colspec colnum="22" colname="b27" align="center" /> | ||
| 507 | <colspec colnum="23" colname="b26" align="center" /> | ||
| 508 | <colspec colnum="24" colname="b25" align="center" /> | ||
| 509 | <colspec colnum="25" colname="b24" align="center" /> | ||
| 510 | <colspec colnum="26" colname="b23" align="center" /> | ||
| 511 | <colspec colnum="27" colname="b22" align="center" /> | ||
| 512 | <colspec colnum="28" colname="b21" align="center" /> | ||
| 513 | <colspec colnum="29" colname="b20" align="center" /> | ||
| 514 | |||
| 515 | <colspec colnum="31" colname="b37" align="center" /> | ||
| 516 | <colspec colnum="32" colname="b36" align="center" /> | ||
| 517 | <colspec colnum="33" colname="b35" align="center" /> | ||
| 518 | <colspec colnum="34" colname="b34" align="center" /> | ||
| 519 | <colspec colnum="35" colname="b33" align="center" /> | ||
| 520 | <colspec colnum="36" colname="b32" align="center" /> | ||
| 521 | <colspec colnum="37" colname="b31" align="center" /> | ||
| 522 | <colspec colnum="38" colname="b30" align="center" /> | ||
| 523 | |||
| 524 | <spanspec namest="b07" nameend="b00" spanname="b0" /> | ||
| 525 | <spanspec namest="b17" nameend="b10" spanname="b1" /> | ||
| 526 | <spanspec namest="b27" nameend="b20" spanname="b2" /> | ||
| 527 | <spanspec namest="b37" nameend="b30" spanname="b3" /> | ||
| 528 | <thead> | ||
| 529 | <row> | ||
| 530 | <entry>Identifier</entry> | ||
| 531 | <entry>Code</entry> | ||
| 532 | <entry> </entry> | ||
| 533 | <entry spanname="b0">Byte 0 in memory</entry> | ||
| 534 | <entry spanname="b1">Byte 1</entry> | ||
| 535 | <entry spanname="b2">Byte 2</entry> | ||
| 536 | <entry spanname="b3">Byte 3</entry> | ||
| 537 | </row> | ||
| 538 | <row> | ||
| 539 | <entry> </entry> | ||
| 540 | <entry> </entry> | ||
| 541 | <entry>Bit</entry> | ||
| 542 | <entry>7</entry> | ||
| 543 | <entry>6</entry> | ||
| 544 | <entry>5</entry> | ||
| 545 | <entry>4</entry> | ||
| 546 | <entry>3</entry> | ||
| 547 | <entry>2</entry> | ||
| 548 | <entry>1</entry> | ||
| 549 | <entry>0</entry> | ||
| 550 | <entry> </entry> | ||
| 551 | <entry>7</entry> | ||
| 552 | <entry>6</entry> | ||
| 553 | <entry>5</entry> | ||
| 554 | <entry>4</entry> | ||
| 555 | <entry>3</entry> | ||
| 556 | <entry>2</entry> | ||
| 557 | <entry>1</entry> | ||
| 558 | <entry>0</entry> | ||
| 559 | <entry> </entry> | ||
| 560 | <entry>7</entry> | ||
| 561 | <entry>6</entry> | ||
| 562 | <entry>5</entry> | ||
| 563 | <entry>4</entry> | ||
| 564 | <entry>3</entry> | ||
| 565 | <entry>2</entry> | ||
| 566 | <entry>1</entry> | ||
| 567 | <entry>0</entry> | ||
| 568 | <entry> </entry> | ||
| 569 | <entry>7</entry> | ||
| 570 | <entry>6</entry> | ||
| 571 | <entry>5</entry> | ||
| 572 | <entry>4</entry> | ||
| 573 | <entry>3</entry> | ||
| 574 | <entry>2</entry> | ||
| 575 | <entry>1</entry> | ||
| 576 | <entry>0</entry> | ||
| 577 | </row> | ||
| 578 | </thead> | ||
| 579 | <tbody valign="top"> | ||
| 580 | <row><!-- id="V4L2-PIX-FMT-RGB332" --> | ||
| 581 | <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry> | ||
| 582 | <entry>'RGB1'</entry> | ||
| 583 | <entry></entry> | ||
| 584 | <entry>r<subscript>2</subscript></entry> | ||
| 585 | <entry>r<subscript>1</subscript></entry> | ||
| 586 | <entry>r<subscript>0</subscript></entry> | ||
| 587 | <entry>g<subscript>2</subscript></entry> | ||
| 588 | <entry>g<subscript>1</subscript></entry> | ||
| 589 | <entry>g<subscript>0</subscript></entry> | ||
| 590 | <entry>b<subscript>1</subscript></entry> | ||
| 591 | <entry>b<subscript>0</subscript></entry> | ||
| 592 | </row> | ||
| 593 | <row><!-- id="V4L2-PIX-FMT-RGB444" --> | ||
| 594 | <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry> | ||
| 595 | <entry>'R444'</entry> | ||
| 596 | <entry></entry> | ||
| 597 | <entry>g<subscript>3</subscript></entry> | ||
| 598 | <entry>g<subscript>2</subscript></entry> | ||
| 599 | <entry>g<subscript>1</subscript></entry> | ||
| 600 | <entry>g<subscript>0</subscript></entry> | ||
| 601 | <entry>b<subscript>3</subscript></entry> | ||
| 602 | <entry>b<subscript>2</subscript></entry> | ||
| 603 | <entry>b<subscript>1</subscript></entry> | ||
| 604 | <entry>b<subscript>0</subscript></entry> | ||
| 605 | <entry></entry> | ||
| 606 | <entry>a<subscript>3</subscript></entry> | ||
| 607 | <entry>a<subscript>2</subscript></entry> | ||
| 608 | <entry>a<subscript>1</subscript></entry> | ||
| 609 | <entry>a<subscript>0</subscript></entry> | ||
| 610 | <entry>r<subscript>3</subscript></entry> | ||
| 611 | <entry>r<subscript>2</subscript></entry> | ||
| 612 | <entry>r<subscript>1</subscript></entry> | ||
| 613 | <entry>r<subscript>0</subscript></entry> | ||
| 614 | </row> | ||
| 615 | <row><!-- id="V4L2-PIX-FMT-RGB555" --> | ||
| 616 | <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry> | ||
| 617 | <entry>'RGBO'</entry> | ||
| 618 | <entry></entry> | ||
| 619 | <entry>g<subscript>2</subscript></entry> | ||
| 620 | <entry>g<subscript>1</subscript></entry> | ||
| 621 | <entry>g<subscript>0</subscript></entry> | ||
| 622 | <entry>b<subscript>4</subscript></entry> | ||
| 623 | <entry>b<subscript>3</subscript></entry> | ||
| 624 | <entry>b<subscript>2</subscript></entry> | ||
| 625 | <entry>b<subscript>1</subscript></entry> | ||
| 626 | <entry>b<subscript>0</subscript></entry> | ||
| 627 | <entry></entry> | ||
| 628 | <entry>a</entry> | ||
| 629 | <entry>r<subscript>4</subscript></entry> | ||
| 630 | <entry>r<subscript>3</subscript></entry> | ||
| 631 | <entry>r<subscript>2</subscript></entry> | ||
| 632 | <entry>r<subscript>1</subscript></entry> | ||
| 633 | <entry>r<subscript>0</subscript></entry> | ||
| 634 | <entry>g<subscript>4</subscript></entry> | ||
| 635 | <entry>g<subscript>3</subscript></entry> | ||
| 636 | </row> | ||
| 637 | <row><!-- id="V4L2-PIX-FMT-RGB565" --> | ||
| 638 | <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry> | ||
| 639 | <entry>'RGBP'</entry> | ||
| 640 | <entry></entry> | ||
| 641 | <entry>g<subscript>2</subscript></entry> | ||
| 642 | <entry>g<subscript>1</subscript></entry> | ||
| 643 | <entry>g<subscript>0</subscript></entry> | ||
| 644 | <entry>b<subscript>4</subscript></entry> | ||
| 645 | <entry>b<subscript>3</subscript></entry> | ||
| 646 | <entry>b<subscript>2</subscript></entry> | ||
| 647 | <entry>b<subscript>1</subscript></entry> | ||
| 648 | <entry>b<subscript>0</subscript></entry> | ||
| 649 | <entry></entry> | ||
| 650 | <entry>r<subscript>4</subscript></entry> | ||
| 651 | <entry>r<subscript>3</subscript></entry> | ||
| 652 | <entry>r<subscript>2</subscript></entry> | ||
| 653 | <entry>r<subscript>1</subscript></entry> | ||
| 654 | <entry>r<subscript>0</subscript></entry> | ||
| 655 | <entry>g<subscript>5</subscript></entry> | ||
| 656 | <entry>g<subscript>4</subscript></entry> | ||
| 657 | <entry>g<subscript>3</subscript></entry> | ||
| 658 | </row> | ||
| 659 | <row><!-- id="V4L2-PIX-FMT-RGB555X" --> | ||
| 660 | <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry> | ||
| 661 | <entry>'RGBQ'</entry> | ||
| 662 | <entry></entry> | ||
| 663 | <entry>a</entry> | ||
| 664 | <entry>r<subscript>4</subscript></entry> | ||
| 665 | <entry>r<subscript>3</subscript></entry> | ||
| 666 | <entry>r<subscript>2</subscript></entry> | ||
| 667 | <entry>r<subscript>1</subscript></entry> | ||
| 668 | <entry>r<subscript>0</subscript></entry> | ||
| 669 | <entry>g<subscript>4</subscript></entry> | ||
| 670 | <entry>g<subscript>3</subscript></entry> | ||
| 671 | <entry></entry> | ||
| 672 | <entry>g<subscript>2</subscript></entry> | ||
| 673 | <entry>g<subscript>1</subscript></entry> | ||
| 674 | <entry>g<subscript>0</subscript></entry> | ||
| 675 | <entry>b<subscript>4</subscript></entry> | ||
| 676 | <entry>b<subscript>3</subscript></entry> | ||
| 677 | <entry>b<subscript>2</subscript></entry> | ||
| 678 | <entry>b<subscript>1</subscript></entry> | ||
| 679 | <entry>b<subscript>0</subscript></entry> | ||
| 680 | </row> | ||
| 681 | <row><!-- id="V4L2-PIX-FMT-RGB565X" --> | ||
| 682 | <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry> | ||
| 683 | <entry>'RGBR'</entry> | ||
| 684 | <entry></entry> | ||
| 685 | <entry>r<subscript>4</subscript></entry> | ||
| 686 | <entry>r<subscript>3</subscript></entry> | ||
| 687 | <entry>r<subscript>2</subscript></entry> | ||
| 688 | <entry>r<subscript>1</subscript></entry> | ||
| 689 | <entry>r<subscript>0</subscript></entry> | ||
| 690 | <entry>g<subscript>5</subscript></entry> | ||
| 691 | <entry>g<subscript>4</subscript></entry> | ||
| 692 | <entry>g<subscript>3</subscript></entry> | ||
| 693 | <entry></entry> | ||
| 694 | <entry>g<subscript>2</subscript></entry> | ||
| 695 | <entry>g<subscript>1</subscript></entry> | ||
| 696 | <entry>g<subscript>0</subscript></entry> | ||
| 697 | <entry>b<subscript>4</subscript></entry> | ||
| 698 | <entry>b<subscript>3</subscript></entry> | ||
| 699 | <entry>b<subscript>2</subscript></entry> | ||
| 700 | <entry>b<subscript>1</subscript></entry> | ||
| 701 | <entry>b<subscript>0</subscript></entry> | ||
| 702 | </row> | ||
| 703 | <row><!-- id="V4L2-PIX-FMT-BGR24" --> | ||
| 704 | <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> | ||
| 705 | <entry>'BGR3'</entry> | ||
| 706 | <entry></entry> | ||
| 707 | <entry>b<subscript>7</subscript></entry> | ||
| 708 | <entry>b<subscript>6</subscript></entry> | ||
| 709 | <entry>b<subscript>5</subscript></entry> | ||
| 710 | <entry>b<subscript>4</subscript></entry> | ||
| 711 | <entry>b<subscript>3</subscript></entry> | ||
| 712 | <entry>b<subscript>2</subscript></entry> | ||
| 713 | <entry>b<subscript>1</subscript></entry> | ||
| 714 | <entry>b<subscript>0</subscript></entry> | ||
| 715 | <entry></entry> | ||
| 716 | <entry>g<subscript>7</subscript></entry> | ||
| 717 | <entry>g<subscript>6</subscript></entry> | ||
| 718 | <entry>g<subscript>5</subscript></entry> | ||
| 719 | <entry>g<subscript>4</subscript></entry> | ||
| 720 | <entry>g<subscript>3</subscript></entry> | ||
| 721 | <entry>g<subscript>2</subscript></entry> | ||
| 722 | <entry>g<subscript>1</subscript></entry> | ||
| 723 | <entry>g<subscript>0</subscript></entry> | ||
| 724 | <entry></entry> | ||
| 725 | <entry>r<subscript>7</subscript></entry> | ||
| 726 | <entry>r<subscript>6</subscript></entry> | ||
| 727 | <entry>r<subscript>5</subscript></entry> | ||
| 728 | <entry>r<subscript>4</subscript></entry> | ||
| 729 | <entry>r<subscript>3</subscript></entry> | ||
| 730 | <entry>r<subscript>2</subscript></entry> | ||
| 731 | <entry>r<subscript>1</subscript></entry> | ||
| 732 | <entry>r<subscript>0</subscript></entry> | ||
| 733 | </row> | ||
| 734 | <row><!-- id="V4L2-PIX-FMT-RGB24" --> | ||
| 735 | <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry> | ||
| 736 | <entry>'RGB3'</entry> | ||
| 737 | <entry></entry> | ||
| 738 | <entry>r<subscript>7</subscript></entry> | ||
| 739 | <entry>r<subscript>6</subscript></entry> | ||
| 740 | <entry>r<subscript>5</subscript></entry> | ||
| 741 | <entry>r<subscript>4</subscript></entry> | ||
| 742 | <entry>r<subscript>3</subscript></entry> | ||
| 743 | <entry>r<subscript>2</subscript></entry> | ||
| 744 | <entry>r<subscript>1</subscript></entry> | ||
| 745 | <entry>r<subscript>0</subscript></entry> | ||
| 746 | <entry></entry> | ||
| 747 | <entry>g<subscript>7</subscript></entry> | ||
| 748 | <entry>g<subscript>6</subscript></entry> | ||
| 749 | <entry>g<subscript>5</subscript></entry> | ||
| 750 | <entry>g<subscript>4</subscript></entry> | ||
| 751 | <entry>g<subscript>3</subscript></entry> | ||
| 752 | <entry>g<subscript>2</subscript></entry> | ||
| 753 | <entry>g<subscript>1</subscript></entry> | ||
| 754 | <entry>g<subscript>0</subscript></entry> | ||
| 755 | <entry></entry> | ||
| 756 | <entry>b<subscript>7</subscript></entry> | ||
| 757 | <entry>b<subscript>6</subscript></entry> | ||
| 758 | <entry>b<subscript>5</subscript></entry> | ||
| 759 | <entry>b<subscript>4</subscript></entry> | ||
| 760 | <entry>b<subscript>3</subscript></entry> | ||
| 761 | <entry>b<subscript>2</subscript></entry> | ||
| 762 | <entry>b<subscript>1</subscript></entry> | ||
| 763 | <entry>b<subscript>0</subscript></entry> | ||
| 764 | </row> | ||
| 765 | <row><!-- id="V4L2-PIX-FMT-BGR32" --> | ||
| 766 | <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> | ||
| 767 | <entry>'BGR4'</entry> | ||
| 768 | <entry></entry> | ||
| 769 | <entry>b<subscript>7</subscript></entry> | ||
| 770 | <entry>b<subscript>6</subscript></entry> | ||
| 771 | <entry>b<subscript>5</subscript></entry> | ||
| 772 | <entry>b<subscript>4</subscript></entry> | ||
| 773 | <entry>b<subscript>3</subscript></entry> | ||
| 774 | <entry>b<subscript>2</subscript></entry> | ||
| 775 | <entry>b<subscript>1</subscript></entry> | ||
| 776 | <entry>b<subscript>0</subscript></entry> | ||
| 777 | <entry></entry> | ||
| 778 | <entry>g<subscript>7</subscript></entry> | ||
| 779 | <entry>g<subscript>6</subscript></entry> | ||
| 780 | <entry>g<subscript>5</subscript></entry> | ||
| 781 | <entry>g<subscript>4</subscript></entry> | ||
| 782 | <entry>g<subscript>3</subscript></entry> | ||
| 783 | <entry>g<subscript>2</subscript></entry> | ||
| 784 | <entry>g<subscript>1</subscript></entry> | ||
| 785 | <entry>g<subscript>0</subscript></entry> | ||
| 786 | <entry></entry> | ||
| 787 | <entry>r<subscript>7</subscript></entry> | ||
| 788 | <entry>r<subscript>6</subscript></entry> | ||
| 789 | <entry>r<subscript>5</subscript></entry> | ||
| 790 | <entry>r<subscript>4</subscript></entry> | ||
| 791 | <entry>r<subscript>3</subscript></entry> | ||
| 792 | <entry>r<subscript>2</subscript></entry> | ||
| 793 | <entry>r<subscript>1</subscript></entry> | ||
| 794 | <entry>r<subscript>0</subscript></entry> | ||
| 795 | <entry></entry> | ||
| 796 | <entry>a<subscript>7</subscript></entry> | ||
| 797 | <entry>a<subscript>6</subscript></entry> | ||
| 798 | <entry>a<subscript>5</subscript></entry> | ||
| 799 | <entry>a<subscript>4</subscript></entry> | ||
| 800 | <entry>a<subscript>3</subscript></entry> | ||
| 801 | <entry>a<subscript>2</subscript></entry> | ||
| 802 | <entry>a<subscript>1</subscript></entry> | ||
| 803 | <entry>a<subscript>0</subscript></entry> | ||
| 804 | </row> | ||
| 805 | <row><!-- id="V4L2-PIX-FMT-RGB32" --> | ||
| 806 | <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> | ||
| 807 | <entry>'RGB4'</entry> | ||
| 808 | <entry></entry> | ||
| 809 | <entry>a<subscript>7</subscript></entry> | ||
| 810 | <entry>a<subscript>6</subscript></entry> | ||
| 811 | <entry>a<subscript>5</subscript></entry> | ||
| 812 | <entry>a<subscript>4</subscript></entry> | ||
| 813 | <entry>a<subscript>3</subscript></entry> | ||
| 814 | <entry>a<subscript>2</subscript></entry> | ||
| 815 | <entry>a<subscript>1</subscript></entry> | ||
| 816 | <entry>a<subscript>0</subscript></entry> | ||
| 817 | <entry></entry> | ||
| 818 | <entry>r<subscript>7</subscript></entry> | ||
| 819 | <entry>r<subscript>6</subscript></entry> | ||
| 820 | <entry>r<subscript>5</subscript></entry> | ||
| 821 | <entry>r<subscript>4</subscript></entry> | ||
| 822 | <entry>r<subscript>3</subscript></entry> | ||
| 823 | <entry>r<subscript>2</subscript></entry> | ||
| 824 | <entry>r<subscript>1</subscript></entry> | ||
| 825 | <entry>r<subscript>0</subscript></entry> | ||
| 826 | <entry></entry> | ||
| 827 | <entry>g<subscript>7</subscript></entry> | ||
| 828 | <entry>g<subscript>6</subscript></entry> | ||
| 829 | <entry>g<subscript>5</subscript></entry> | ||
| 830 | <entry>g<subscript>4</subscript></entry> | ||
| 831 | <entry>g<subscript>3</subscript></entry> | ||
| 832 | <entry>g<subscript>2</subscript></entry> | ||
| 833 | <entry>g<subscript>1</subscript></entry> | ||
| 834 | <entry>g<subscript>0</subscript></entry> | ||
| 835 | <entry></entry> | ||
| 836 | <entry>b<subscript>7</subscript></entry> | ||
| 837 | <entry>b<subscript>6</subscript></entry> | ||
| 838 | <entry>b<subscript>5</subscript></entry> | ||
| 839 | <entry>b<subscript>4</subscript></entry> | ||
| 840 | <entry>b<subscript>3</subscript></entry> | ||
| 841 | <entry>b<subscript>2</subscript></entry> | ||
| 842 | <entry>b<subscript>1</subscript></entry> | ||
| 843 | <entry>b<subscript>0</subscript></entry> | ||
| 844 | </row> | ||
| 845 | </tbody> | ||
| 846 | </tgroup> | ||
| 847 | </table> | ||
| 848 | |||
| 849 | <para>A test utility to determine which RGB formats a driver | ||
| 850 | actually supports is available from the LinuxTV v4l-dvb repository. | ||
| 851 | See &v4l-dvb; for access instructions.</para> | ||
| 852 | |||
| 853 | </refsect1> | ||
| 854 | </refentry> | ||
| 855 | |||
| 856 | <!-- | ||
| 857 | Local Variables: | ||
| 858 | mode: sgml | ||
| 859 | sgml-parent-document: "pixfmt.sgml" | ||
| 860 | indent-tabs-mode: nil | ||
| 861 | End: | ||
| 862 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-packed-yuv.xml b/Documentation/DocBook/v4l/pixfmt-packed-yuv.xml new file mode 100644 index 000000000000..3cab5d0ca75d --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-packed-yuv.xml | |||
| @@ -0,0 +1,244 @@ | |||
| 1 | <refentry id="packed-yuv"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>Packed YUV formats</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname>Packed YUV formats</refname> | ||
| 8 | <refpurpose>Packed YUV formats</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>Similar to the packed RGB formats these formats store | ||
| 14 | the Y, Cb and Cr component of each pixel in one 16 or 32 bit | ||
| 15 | word.</para> | ||
| 16 | |||
| 17 | <table pgwide="1" frame="none"> | ||
| 18 | <title>Packed YUV Image Formats</title> | ||
| 19 | <tgroup cols="37" align="center"> | ||
| 20 | <colspec colname="id" align="left" /> | ||
| 21 | <colspec colname="fourcc" /> | ||
| 22 | <colspec colname="bit" /> | ||
| 23 | |||
| 24 | <colspec colnum="4" colname="b07" align="center" /> | ||
| 25 | <colspec colnum="5" colname="b06" align="center" /> | ||
| 26 | <colspec colnum="6" colname="b05" align="center" /> | ||
| 27 | <colspec colnum="7" colname="b04" align="center" /> | ||
| 28 | <colspec colnum="8" colname="b03" align="center" /> | ||
| 29 | <colspec colnum="9" colname="b02" align="center" /> | ||
| 30 | <colspec colnum="10" colname="b01" align="center" /> | ||
| 31 | <colspec colnum="11" colname="b00" align="center" /> | ||
| 32 | |||
| 33 | <colspec colnum="13" colname="b17" align="center" /> | ||
| 34 | <colspec colnum="14" colname="b16" align="center" /> | ||
| 35 | <colspec colnum="15" colname="b15" align="center" /> | ||
| 36 | <colspec colnum="16" colname="b14" align="center" /> | ||
| 37 | <colspec colnum="17" colname="b13" align="center" /> | ||
| 38 | <colspec colnum="18" colname="b12" align="center" /> | ||
| 39 | <colspec colnum="19" colname="b11" align="center" /> | ||
| 40 | <colspec colnum="20" colname="b10" align="center" /> | ||
| 41 | |||
| 42 | <colspec colnum="22" colname="b27" align="center" /> | ||
| 43 | <colspec colnum="23" colname="b26" align="center" /> | ||
| 44 | <colspec colnum="24" colname="b25" align="center" /> | ||
| 45 | <colspec colnum="25" colname="b24" align="center" /> | ||
| 46 | <colspec colnum="26" colname="b23" align="center" /> | ||
| 47 | <colspec colnum="27" colname="b22" align="center" /> | ||
| 48 | <colspec colnum="28" colname="b21" align="center" /> | ||
| 49 | <colspec colnum="29" colname="b20" align="center" /> | ||
| 50 | |||
| 51 | <colspec colnum="31" colname="b37" align="center" /> | ||
| 52 | <colspec colnum="32" colname="b36" align="center" /> | ||
| 53 | <colspec colnum="33" colname="b35" align="center" /> | ||
| 54 | <colspec colnum="34" colname="b34" align="center" /> | ||
| 55 | <colspec colnum="35" colname="b33" align="center" /> | ||
| 56 | <colspec colnum="36" colname="b32" align="center" /> | ||
| 57 | <colspec colnum="37" colname="b31" align="center" /> | ||
| 58 | <colspec colnum="38" colname="b30" align="center" /> | ||
| 59 | |||
| 60 | <spanspec namest="b07" nameend="b00" spanname="b0" /> | ||
| 61 | <spanspec namest="b17" nameend="b10" spanname="b1" /> | ||
| 62 | <spanspec namest="b27" nameend="b20" spanname="b2" /> | ||
| 63 | <spanspec namest="b37" nameend="b30" spanname="b3" /> | ||
| 64 | <thead> | ||
| 65 | <row> | ||
| 66 | <entry>Identifier</entry> | ||
| 67 | <entry>Code</entry> | ||
| 68 | <entry> </entry> | ||
| 69 | <entry spanname="b0">Byte 0 in memory</entry> | ||
| 70 | <entry spanname="b1">Byte 1</entry> | ||
| 71 | <entry spanname="b2">Byte 2</entry> | ||
| 72 | <entry spanname="b3">Byte 3</entry> | ||
| 73 | </row> | ||
| 74 | <row> | ||
| 75 | <entry> </entry> | ||
| 76 | <entry> </entry> | ||
| 77 | <entry>Bit</entry> | ||
| 78 | <entry>7</entry> | ||
| 79 | <entry>6</entry> | ||
| 80 | <entry>5</entry> | ||
| 81 | <entry>4</entry> | ||
| 82 | <entry>3</entry> | ||
| 83 | <entry>2</entry> | ||
| 84 | <entry>1</entry> | ||
| 85 | <entry>0</entry> | ||
| 86 | <entry> </entry> | ||
| 87 | <entry>7</entry> | ||
| 88 | <entry>6</entry> | ||
| 89 | <entry>5</entry> | ||
| 90 | <entry>4</entry> | ||
| 91 | <entry>3</entry> | ||
| 92 | <entry>2</entry> | ||
| 93 | <entry>1</entry> | ||
| 94 | <entry>0</entry> | ||
| 95 | <entry> </entry> | ||
| 96 | <entry>7</entry> | ||
| 97 | <entry>6</entry> | ||
| 98 | <entry>5</entry> | ||
| 99 | <entry>4</entry> | ||
| 100 | <entry>3</entry> | ||
| 101 | <entry>2</entry> | ||
| 102 | <entry>1</entry> | ||
| 103 | <entry>0</entry> | ||
| 104 | <entry> </entry> | ||
| 105 | <entry>7</entry> | ||
| 106 | <entry>6</entry> | ||
| 107 | <entry>5</entry> | ||
| 108 | <entry>4</entry> | ||
| 109 | <entry>3</entry> | ||
| 110 | <entry>2</entry> | ||
| 111 | <entry>1</entry> | ||
| 112 | <entry>0</entry> | ||
| 113 | </row> | ||
| 114 | </thead> | ||
| 115 | <tbody valign="top"> | ||
| 116 | <row id="V4L2-PIX-FMT-YUV444"> | ||
| 117 | <entry><constant>V4L2_PIX_FMT_YUV444</constant></entry> | ||
| 118 | <entry>'Y444'</entry> | ||
| 119 | <entry></entry> | ||
| 120 | <entry>Cb<subscript>3</subscript></entry> | ||
| 121 | <entry>Cb<subscript>2</subscript></entry> | ||
| 122 | <entry>Cb<subscript>1</subscript></entry> | ||
| 123 | <entry>Cb<subscript>0</subscript></entry> | ||
| 124 | <entry>Cr<subscript>3</subscript></entry> | ||
| 125 | <entry>Cr<subscript>2</subscript></entry> | ||
| 126 | <entry>Cr<subscript>1</subscript></entry> | ||
| 127 | <entry>Cr<subscript>0</subscript></entry> | ||
| 128 | <entry></entry> | ||
| 129 | <entry>a<subscript>3</subscript></entry> | ||
| 130 | <entry>a<subscript>2</subscript></entry> | ||
| 131 | <entry>a<subscript>1</subscript></entry> | ||
| 132 | <entry>a<subscript>0</subscript></entry> | ||
| 133 | <entry>Y'<subscript>3</subscript></entry> | ||
| 134 | <entry>Y'<subscript>2</subscript></entry> | ||
| 135 | <entry>Y'<subscript>1</subscript></entry> | ||
| 136 | <entry>Y'<subscript>0</subscript></entry> | ||
| 137 | </row> | ||
| 138 | |||
| 139 | <row id="V4L2-PIX-FMT-YUV555"> | ||
| 140 | <entry><constant>V4L2_PIX_FMT_YUV555</constant></entry> | ||
| 141 | <entry>'YUVO'</entry> | ||
| 142 | <entry></entry> | ||
| 143 | <entry>Cb<subscript>2</subscript></entry> | ||
| 144 | <entry>Cb<subscript>1</subscript></entry> | ||
| 145 | <entry>Cb<subscript>0</subscript></entry> | ||
| 146 | <entry>Cr<subscript>4</subscript></entry> | ||
| 147 | <entry>Cr<subscript>3</subscript></entry> | ||
| 148 | <entry>Cr<subscript>2</subscript></entry> | ||
| 149 | <entry>Cr<subscript>1</subscript></entry> | ||
| 150 | <entry>Cr<subscript>0</subscript></entry> | ||
| 151 | <entry></entry> | ||
| 152 | <entry>a</entry> | ||
| 153 | <entry>Y'<subscript>4</subscript></entry> | ||
| 154 | <entry>Y'<subscript>3</subscript></entry> | ||
| 155 | <entry>Y'<subscript>2</subscript></entry> | ||
| 156 | <entry>Y'<subscript>1</subscript></entry> | ||
| 157 | <entry>Y'<subscript>0</subscript></entry> | ||
| 158 | <entry>Cb<subscript>4</subscript></entry> | ||
| 159 | <entry>Cb<subscript>3</subscript></entry> | ||
| 160 | </row> | ||
| 161 | |||
| 162 | <row id="V4L2-PIX-FMT-YUV565"> | ||
| 163 | <entry><constant>V4L2_PIX_FMT_YUV565</constant></entry> | ||
| 164 | <entry>'YUVP'</entry> | ||
| 165 | <entry></entry> | ||
| 166 | <entry>Cb<subscript>2</subscript></entry> | ||
| 167 | <entry>Cb<subscript>1</subscript></entry> | ||
| 168 | <entry>Cb<subscript>0</subscript></entry> | ||
| 169 | <entry>Cr<subscript>4</subscript></entry> | ||
| 170 | <entry>Cr<subscript>3</subscript></entry> | ||
| 171 | <entry>Cr<subscript>2</subscript></entry> | ||
| 172 | <entry>Cr<subscript>1</subscript></entry> | ||
| 173 | <entry>Cr<subscript>0</subscript></entry> | ||
| 174 | <entry></entry> | ||
| 175 | <entry>Y'<subscript>4</subscript></entry> | ||
| 176 | <entry>Y'<subscript>3</subscript></entry> | ||
| 177 | <entry>Y'<subscript>2</subscript></entry> | ||
| 178 | <entry>Y'<subscript>1</subscript></entry> | ||
| 179 | <entry>Y'<subscript>0</subscript></entry> | ||
| 180 | <entry>Cb<subscript>5</subscript></entry> | ||
| 181 | <entry>Cb<subscript>4</subscript></entry> | ||
| 182 | <entry>Cb<subscript>3</subscript></entry> | ||
| 183 | </row> | ||
| 184 | |||
| 185 | <row id="V4L2-PIX-FMT-YUV32"> | ||
| 186 | <entry><constant>V4L2_PIX_FMT_YUV32</constant></entry> | ||
| 187 | <entry>'YUV4'</entry> | ||
| 188 | <entry></entry> | ||
| 189 | <entry>a<subscript>7</subscript></entry> | ||
| 190 | <entry>a<subscript>6</subscript></entry> | ||
| 191 | <entry>a<subscript>5</subscript></entry> | ||
| 192 | <entry>a<subscript>4</subscript></entry> | ||
| 193 | <entry>a<subscript>3</subscript></entry> | ||
| 194 | <entry>a<subscript>2</subscript></entry> | ||
| 195 | <entry>a<subscript>1</subscript></entry> | ||
| 196 | <entry>a<subscript>0</subscript></entry> | ||
| 197 | <entry></entry> | ||
| 198 | <entry>Y'<subscript>7</subscript></entry> | ||
| 199 | <entry>Y'<subscript>6</subscript></entry> | ||
| 200 | <entry>Y'<subscript>5</subscript></entry> | ||
| 201 | <entry>Y'<subscript>4</subscript></entry> | ||
| 202 | <entry>Y'<subscript>3</subscript></entry> | ||
| 203 | <entry>Y'<subscript>2</subscript></entry> | ||
| 204 | <entry>Y'<subscript>1</subscript></entry> | ||
| 205 | <entry>Y'<subscript>0</subscript></entry> | ||
| 206 | <entry></entry> | ||
| 207 | <entry>Cb<subscript>7</subscript></entry> | ||
| 208 | <entry>Cb<subscript>6</subscript></entry> | ||
| 209 | <entry>Cb<subscript>5</subscript></entry> | ||
| 210 | <entry>Cb<subscript>4</subscript></entry> | ||
| 211 | <entry>Cb<subscript>3</subscript></entry> | ||
| 212 | <entry>Cb<subscript>2</subscript></entry> | ||
| 213 | <entry>Cb<subscript>1</subscript></entry> | ||
| 214 | <entry>Cb<subscript>0</subscript></entry> | ||
| 215 | <entry></entry> | ||
| 216 | <entry>Cr<subscript>7</subscript></entry> | ||
| 217 | <entry>Cr<subscript>6</subscript></entry> | ||
| 218 | <entry>Cr<subscript>5</subscript></entry> | ||
| 219 | <entry>Cr<subscript>4</subscript></entry> | ||
| 220 | <entry>Cr<subscript>3</subscript></entry> | ||
| 221 | <entry>Cr<subscript>2</subscript></entry> | ||
| 222 | <entry>Cr<subscript>1</subscript></entry> | ||
| 223 | <entry>Cr<subscript>0</subscript></entry> | ||
| 224 | </row> | ||
| 225 | </tbody> | ||
| 226 | </tgroup> | ||
| 227 | </table> | ||
| 228 | |||
| 229 | <para>Bit 7 is the most significant bit. The value of a = alpha | ||
| 230 | bits is undefined when reading from the driver, ignored when writing | ||
| 231 | to the driver, except when alpha blending has been negotiated for a | ||
| 232 | <link linkend="overlay">Video Overlay</link> or <link | ||
| 233 | linkend="osd">Video Output Overlay</link>.</para> | ||
| 234 | |||
| 235 | </refsect1> | ||
| 236 | </refentry> | ||
| 237 | |||
| 238 | <!-- | ||
| 239 | Local Variables: | ||
| 240 | mode: sgml | ||
| 241 | sgml-parent-document: "pixfmt.sgml" | ||
| 242 | indent-tabs-mode: nil | ||
| 243 | End: | ||
| 244 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-sbggr16.xml b/Documentation/DocBook/v4l/pixfmt-sbggr16.xml new file mode 100644 index 000000000000..519a9efbac10 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-sbggr16.xml | |||
| @@ -0,0 +1,91 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-SBGGR16"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_SBGGR16 ('BYR2')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_SBGGR16</constant></refname> | ||
| 8 | <refpurpose>Bayer RGB format</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This format is similar to <link | ||
| 14 | linkend="V4L2-PIX-FMT-SBGGR8"> | ||
| 15 | <constant>V4L2_PIX_FMT_SBGGR8</constant></link>, except each pixel has | ||
| 16 | a depth of 16 bits. The least significant byte is stored at lower | ||
| 17 | memory addresses (little-endian). Note the actual sampling precision | ||
| 18 | may be lower than 16 bits, for example 10 bits per pixel with values | ||
| 19 | in range 0 to 1023.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_SBGGR16</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="5" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>B<subscript>00low</subscript></entry> | ||
| 35 | <entry>B<subscript>00high</subscript></entry> | ||
| 36 | <entry>G<subscript>01low</subscript></entry> | ||
| 37 | <entry>G<subscript>01high</subscript></entry> | ||
| 38 | <entry>B<subscript>02low</subscript></entry> | ||
| 39 | <entry>B<subscript>02high</subscript></entry> | ||
| 40 | <entry>G<subscript>03low</subscript></entry> | ||
| 41 | <entry>G<subscript>03high</subscript></entry> | ||
| 42 | </row> | ||
| 43 | <row> | ||
| 44 | <entry>start + 8:</entry> | ||
| 45 | <entry>G<subscript>10low</subscript></entry> | ||
| 46 | <entry>G<subscript>10high</subscript></entry> | ||
| 47 | <entry>R<subscript>11low</subscript></entry> | ||
| 48 | <entry>R<subscript>11high</subscript></entry> | ||
| 49 | <entry>G<subscript>12low</subscript></entry> | ||
| 50 | <entry>G<subscript>12high</subscript></entry> | ||
| 51 | <entry>R<subscript>13low</subscript></entry> | ||
| 52 | <entry>R<subscript>13high</subscript></entry> | ||
| 53 | </row> | ||
| 54 | <row> | ||
| 55 | <entry>start + 16:</entry> | ||
| 56 | <entry>B<subscript>20low</subscript></entry> | ||
| 57 | <entry>B<subscript>20high</subscript></entry> | ||
| 58 | <entry>G<subscript>21low</subscript></entry> | ||
| 59 | <entry>G<subscript>21high</subscript></entry> | ||
| 60 | <entry>B<subscript>22low</subscript></entry> | ||
| 61 | <entry>B<subscript>22high</subscript></entry> | ||
| 62 | <entry>G<subscript>23low</subscript></entry> | ||
| 63 | <entry>G<subscript>23high</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 24:</entry> | ||
| 67 | <entry>G<subscript>30low</subscript></entry> | ||
| 68 | <entry>G<subscript>30high</subscript></entry> | ||
| 69 | <entry>R<subscript>31low</subscript></entry> | ||
| 70 | <entry>R<subscript>31high</subscript></entry> | ||
| 71 | <entry>G<subscript>32low</subscript></entry> | ||
| 72 | <entry>G<subscript>32high</subscript></entry> | ||
| 73 | <entry>R<subscript>33low</subscript></entry> | ||
| 74 | <entry>R<subscript>33high</subscript></entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </informaltable> | ||
| 79 | </para> | ||
| 80 | </formalpara> | ||
| 81 | </example> | ||
| 82 | </refsect1> | ||
| 83 | </refentry> | ||
| 84 | |||
| 85 | <!-- | ||
| 86 | Local Variables: | ||
| 87 | mode: sgml | ||
| 88 | sgml-parent-document: "pixfmt.sgml" | ||
| 89 | indent-tabs-mode: nil | ||
| 90 | End: | ||
| 91 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-sbggr8.xml b/Documentation/DocBook/v4l/pixfmt-sbggr8.xml new file mode 100644 index 000000000000..5fe84ecc2ebe --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-sbggr8.xml | |||
| @@ -0,0 +1,75 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-SBGGR8"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_SBGGR8 ('BA81')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_SBGGR8</constant></refname> | ||
| 8 | <refpurpose>Bayer RGB format</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This is commonly the native format of digital cameras, | ||
| 14 | reflecting the arrangement of sensors on the CCD device. Only one red, | ||
| 15 | green or blue value is given for each pixel. Missing components must | ||
| 16 | be interpolated from neighbouring pixels. From left to right the first | ||
| 17 | row consists of a blue and green value, the second row of a green and | ||
| 18 | red value. This scheme repeats to the right and down for every two | ||
| 19 | columns and rows.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_SBGGR8</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="5" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>B<subscript>00</subscript></entry> | ||
| 35 | <entry>G<subscript>01</subscript></entry> | ||
| 36 | <entry>B<subscript>02</subscript></entry> | ||
| 37 | <entry>G<subscript>03</subscript></entry> | ||
| 38 | </row> | ||
| 39 | <row> | ||
| 40 | <entry>start + 4:</entry> | ||
| 41 | <entry>G<subscript>10</subscript></entry> | ||
| 42 | <entry>R<subscript>11</subscript></entry> | ||
| 43 | <entry>G<subscript>12</subscript></entry> | ||
| 44 | <entry>R<subscript>13</subscript></entry> | ||
| 45 | </row> | ||
| 46 | <row> | ||
| 47 | <entry>start + 8:</entry> | ||
| 48 | <entry>B<subscript>20</subscript></entry> | ||
| 49 | <entry>G<subscript>21</subscript></entry> | ||
| 50 | <entry>B<subscript>22</subscript></entry> | ||
| 51 | <entry>G<subscript>23</subscript></entry> | ||
| 52 | </row> | ||
| 53 | <row> | ||
| 54 | <entry>start + 12:</entry> | ||
| 55 | <entry>G<subscript>30</subscript></entry> | ||
| 56 | <entry>R<subscript>31</subscript></entry> | ||
| 57 | <entry>G<subscript>32</subscript></entry> | ||
| 58 | <entry>R<subscript>33</subscript></entry> | ||
| 59 | </row> | ||
| 60 | </tbody> | ||
| 61 | </tgroup> | ||
| 62 | </informaltable> | ||
| 63 | </para> | ||
| 64 | </formalpara> | ||
| 65 | </example> | ||
| 66 | </refsect1> | ||
| 67 | </refentry> | ||
| 68 | |||
| 69 | <!-- | ||
| 70 | Local Variables: | ||
| 71 | mode: sgml | ||
| 72 | sgml-parent-document: "pixfmt.sgml" | ||
| 73 | indent-tabs-mode: nil | ||
| 74 | End: | ||
| 75 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-sgbrg8.xml b/Documentation/DocBook/v4l/pixfmt-sgbrg8.xml new file mode 100644 index 000000000000..d67a472b0880 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-sgbrg8.xml | |||
| @@ -0,0 +1,75 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-SGBRG8"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_SGBRG8 ('GBRG')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_SGBRG8</constant></refname> | ||
| 8 | <refpurpose>Bayer RGB format</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This is commonly the native format of digital cameras, | ||
| 14 | reflecting the arrangement of sensors on the CCD device. Only one red, | ||
| 15 | green or blue value is given for each pixel. Missing components must | ||
| 16 | be interpolated from neighbouring pixels. From left to right the first | ||
| 17 | row consists of a green and blue value, the second row of a red and | ||
| 18 | green value. This scheme repeats to the right and down for every two | ||
| 19 | columns and rows.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_SGBRG8</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="5" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>G<subscript>00</subscript></entry> | ||
| 35 | <entry>B<subscript>01</subscript></entry> | ||
| 36 | <entry>G<subscript>02</subscript></entry> | ||
| 37 | <entry>B<subscript>03</subscript></entry> | ||
| 38 | </row> | ||
| 39 | <row> | ||
| 40 | <entry>start + 4:</entry> | ||
| 41 | <entry>R<subscript>10</subscript></entry> | ||
| 42 | <entry>G<subscript>11</subscript></entry> | ||
| 43 | <entry>R<subscript>12</subscript></entry> | ||
| 44 | <entry>G<subscript>13</subscript></entry> | ||
| 45 | </row> | ||
| 46 | <row> | ||
| 47 | <entry>start + 8:</entry> | ||
| 48 | <entry>G<subscript>20</subscript></entry> | ||
| 49 | <entry>B<subscript>21</subscript></entry> | ||
| 50 | <entry>G<subscript>22</subscript></entry> | ||
| 51 | <entry>B<subscript>23</subscript></entry> | ||
| 52 | </row> | ||
| 53 | <row> | ||
| 54 | <entry>start + 12:</entry> | ||
| 55 | <entry>R<subscript>30</subscript></entry> | ||
| 56 | <entry>G<subscript>31</subscript></entry> | ||
| 57 | <entry>R<subscript>32</subscript></entry> | ||
| 58 | <entry>G<subscript>33</subscript></entry> | ||
| 59 | </row> | ||
| 60 | </tbody> | ||
| 61 | </tgroup> | ||
| 62 | </informaltable> | ||
| 63 | </para> | ||
| 64 | </formalpara> | ||
| 65 | </example> | ||
| 66 | </refsect1> | ||
| 67 | </refentry> | ||
| 68 | |||
| 69 | <!-- | ||
| 70 | Local Variables: | ||
| 71 | mode: sgml | ||
| 72 | sgml-parent-document: "pixfmt.sgml" | ||
| 73 | indent-tabs-mode: nil | ||
| 74 | End: | ||
| 75 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-sgrbg8.xml b/Documentation/DocBook/v4l/pixfmt-sgrbg8.xml new file mode 100644 index 000000000000..0cdf13b8ac1c --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-sgrbg8.xml | |||
| @@ -0,0 +1,75 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-SGRBG8"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_SGRBG8 ('GRBG')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_SGRBG8</constant></refname> | ||
| 8 | <refpurpose>Bayer RGB format</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This is commonly the native format of digital cameras, | ||
| 14 | reflecting the arrangement of sensors on the CCD device. Only one red, | ||
| 15 | green or blue value is given for each pixel. Missing components must | ||
| 16 | be interpolated from neighbouring pixels. From left to right the first | ||
| 17 | row consists of a green and blue value, the second row of a red and | ||
| 18 | green value. This scheme repeats to the right and down for every two | ||
| 19 | columns and rows.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_SGRBG8</constant> 4 × | ||
| 23 | 4 pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="5" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>G<subscript>00</subscript></entry> | ||
| 35 | <entry>R<subscript>01</subscript></entry> | ||
| 36 | <entry>G<subscript>02</subscript></entry> | ||
| 37 | <entry>R<subscript>03</subscript></entry> | ||
| 38 | </row> | ||
| 39 | <row> | ||
| 40 | <entry>start + 4:</entry> | ||
| 41 | <entry>R<subscript>10</subscript></entry> | ||
| 42 | <entry>B<subscript>11</subscript></entry> | ||
| 43 | <entry>R<subscript>12</subscript></entry> | ||
| 44 | <entry>B<subscript>13</subscript></entry> | ||
| 45 | </row> | ||
| 46 | <row> | ||
| 47 | <entry>start + 8:</entry> | ||
| 48 | <entry>G<subscript>20</subscript></entry> | ||
| 49 | <entry>R<subscript>21</subscript></entry> | ||
| 50 | <entry>G<subscript>22</subscript></entry> | ||
| 51 | <entry>R<subscript>23</subscript></entry> | ||
| 52 | </row> | ||
| 53 | <row> | ||
| 54 | <entry>start + 12:</entry> | ||
| 55 | <entry>R<subscript>30</subscript></entry> | ||
| 56 | <entry>B<subscript>31</subscript></entry> | ||
| 57 | <entry>R<subscript>32</subscript></entry> | ||
| 58 | <entry>B<subscript>33</subscript></entry> | ||
| 59 | </row> | ||
| 60 | </tbody> | ||
| 61 | </tgroup> | ||
| 62 | </informaltable> | ||
| 63 | </para> | ||
| 64 | </formalpara> | ||
| 65 | </example> | ||
| 66 | </refsect1> | ||
| 67 | </refentry> | ||
| 68 | |||
| 69 | <!-- | ||
| 70 | Local Variables: | ||
| 71 | mode: sgml | ||
| 72 | sgml-parent-document: "pixfmt.sgml" | ||
| 73 | indent-tabs-mode: nil | ||
| 74 | End: | ||
| 75 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-uyvy.xml b/Documentation/DocBook/v4l/pixfmt-uyvy.xml new file mode 100644 index 000000000000..816c8d467c16 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-uyvy.xml | |||
| @@ -0,0 +1,128 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-UYVY"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_UYVY ('UYVY')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_UYVY</constant></refname> | ||
| 8 | <refpurpose>Variation of | ||
| 9 | <constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples | ||
| 10 | in memory</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>In this format each four bytes is two pixels. Each four | ||
| 16 | bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and | ||
| 17 | the Cb and Cr belong to both pixels. As you can see, the Cr and Cb | ||
| 18 | components have half the horizontal resolution of the Y | ||
| 19 | component.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_UYVY</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="9" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>Cb<subscript>00</subscript></entry> | ||
| 35 | <entry>Y'<subscript>00</subscript></entry> | ||
| 36 | <entry>Cr<subscript>00</subscript></entry> | ||
| 37 | <entry>Y'<subscript>01</subscript></entry> | ||
| 38 | <entry>Cb<subscript>01</subscript></entry> | ||
| 39 | <entry>Y'<subscript>02</subscript></entry> | ||
| 40 | <entry>Cr<subscript>01</subscript></entry> | ||
| 41 | <entry>Y'<subscript>03</subscript></entry> | ||
| 42 | </row> | ||
| 43 | <row> | ||
| 44 | <entry>start + 8:</entry> | ||
| 45 | <entry>Cb<subscript>10</subscript></entry> | ||
| 46 | <entry>Y'<subscript>10</subscript></entry> | ||
| 47 | <entry>Cr<subscript>10</subscript></entry> | ||
| 48 | <entry>Y'<subscript>11</subscript></entry> | ||
| 49 | <entry>Cb<subscript>11</subscript></entry> | ||
| 50 | <entry>Y'<subscript>12</subscript></entry> | ||
| 51 | <entry>Cr<subscript>11</subscript></entry> | ||
| 52 | <entry>Y'<subscript>13</subscript></entry> | ||
| 53 | </row> | ||
| 54 | <row> | ||
| 55 | <entry>start + 16:</entry> | ||
| 56 | <entry>Cb<subscript>20</subscript></entry> | ||
| 57 | <entry>Y'<subscript>20</subscript></entry> | ||
| 58 | <entry>Cr<subscript>20</subscript></entry> | ||
| 59 | <entry>Y'<subscript>21</subscript></entry> | ||
| 60 | <entry>Cb<subscript>21</subscript></entry> | ||
| 61 | <entry>Y'<subscript>22</subscript></entry> | ||
| 62 | <entry>Cr<subscript>21</subscript></entry> | ||
| 63 | <entry>Y'<subscript>23</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 24:</entry> | ||
| 67 | <entry>Cb<subscript>30</subscript></entry> | ||
| 68 | <entry>Y'<subscript>30</subscript></entry> | ||
| 69 | <entry>Cr<subscript>30</subscript></entry> | ||
| 70 | <entry>Y'<subscript>31</subscript></entry> | ||
| 71 | <entry>Cb<subscript>31</subscript></entry> | ||
| 72 | <entry>Y'<subscript>32</subscript></entry> | ||
| 73 | <entry>Cr<subscript>31</subscript></entry> | ||
| 74 | <entry>Y'<subscript>33</subscript></entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </informaltable> | ||
| 79 | </para> | ||
| 80 | </formalpara> | ||
| 81 | |||
| 82 | <formalpara> | ||
| 83 | <title>Color Sample Location.</title> | ||
| 84 | <para> | ||
| 85 | <informaltable frame="none"> | ||
| 86 | <tgroup cols="7" align="center"> | ||
| 87 | <tbody valign="top"> | ||
| 88 | <row> | ||
| 89 | <entry></entry> | ||
| 90 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 91 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>0</entry> | ||
| 95 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 96 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>1</entry> | ||
| 100 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 101 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>2</entry> | ||
| 105 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry>3</entry> | ||
| 110 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 111 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 112 | </row> | ||
| 113 | </tbody> | ||
| 114 | </tgroup> | ||
| 115 | </informaltable> | ||
| 116 | </para> | ||
| 117 | </formalpara> | ||
| 118 | </example> | ||
| 119 | </refsect1> | ||
| 120 | </refentry> | ||
| 121 | |||
| 122 | <!-- | ||
| 123 | Local Variables: | ||
| 124 | mode: sgml | ||
| 125 | sgml-parent-document: "pixfmt.sgml" | ||
| 126 | indent-tabs-mode: nil | ||
| 127 | End: | ||
| 128 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-vyuy.xml b/Documentation/DocBook/v4l/pixfmt-vyuy.xml new file mode 100644 index 000000000000..61f12a5e68d9 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-vyuy.xml | |||
| @@ -0,0 +1,128 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-VYUY"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_VYUY ('VYUY')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_VYUY</constant></refname> | ||
| 8 | <refpurpose>Variation of | ||
| 9 | <constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples | ||
| 10 | in memory</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>In this format each four bytes is two pixels. Each four | ||
| 16 | bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and | ||
| 17 | the Cb and Cr belong to both pixels. As you can see, the Cr and Cb | ||
| 18 | components have half the horizontal resolution of the Y | ||
| 19 | component.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_VYUY</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="9" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>Cr<subscript>00</subscript></entry> | ||
| 35 | <entry>Y'<subscript>00</subscript></entry> | ||
| 36 | <entry>Cb<subscript>00</subscript></entry> | ||
| 37 | <entry>Y'<subscript>01</subscript></entry> | ||
| 38 | <entry>Cr<subscript>01</subscript></entry> | ||
| 39 | <entry>Y'<subscript>02</subscript></entry> | ||
| 40 | <entry>Cb<subscript>01</subscript></entry> | ||
| 41 | <entry>Y'<subscript>03</subscript></entry> | ||
| 42 | </row> | ||
| 43 | <row> | ||
| 44 | <entry>start + 8:</entry> | ||
| 45 | <entry>Cr<subscript>10</subscript></entry> | ||
| 46 | <entry>Y'<subscript>10</subscript></entry> | ||
| 47 | <entry>Cb<subscript>10</subscript></entry> | ||
| 48 | <entry>Y'<subscript>11</subscript></entry> | ||
| 49 | <entry>Cr<subscript>11</subscript></entry> | ||
| 50 | <entry>Y'<subscript>12</subscript></entry> | ||
| 51 | <entry>Cb<subscript>11</subscript></entry> | ||
| 52 | <entry>Y'<subscript>13</subscript></entry> | ||
| 53 | </row> | ||
| 54 | <row> | ||
| 55 | <entry>start + 16:</entry> | ||
| 56 | <entry>Cr<subscript>20</subscript></entry> | ||
| 57 | <entry>Y'<subscript>20</subscript></entry> | ||
| 58 | <entry>Cb<subscript>20</subscript></entry> | ||
| 59 | <entry>Y'<subscript>21</subscript></entry> | ||
| 60 | <entry>Cr<subscript>21</subscript></entry> | ||
| 61 | <entry>Y'<subscript>22</subscript></entry> | ||
| 62 | <entry>Cb<subscript>21</subscript></entry> | ||
| 63 | <entry>Y'<subscript>23</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 24:</entry> | ||
| 67 | <entry>Cr<subscript>30</subscript></entry> | ||
| 68 | <entry>Y'<subscript>30</subscript></entry> | ||
| 69 | <entry>Cb<subscript>30</subscript></entry> | ||
| 70 | <entry>Y'<subscript>31</subscript></entry> | ||
| 71 | <entry>Cr<subscript>31</subscript></entry> | ||
| 72 | <entry>Y'<subscript>32</subscript></entry> | ||
| 73 | <entry>Cb<subscript>31</subscript></entry> | ||
| 74 | <entry>Y'<subscript>33</subscript></entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </informaltable> | ||
| 79 | </para> | ||
| 80 | </formalpara> | ||
| 81 | |||
| 82 | <formalpara> | ||
| 83 | <title>Color Sample Location.</title> | ||
| 84 | <para> | ||
| 85 | <informaltable frame="none"> | ||
| 86 | <tgroup cols="7" align="center"> | ||
| 87 | <tbody valign="top"> | ||
| 88 | <row> | ||
| 89 | <entry></entry> | ||
| 90 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 91 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>0</entry> | ||
| 95 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 96 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>1</entry> | ||
| 100 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 101 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>2</entry> | ||
| 105 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry>3</entry> | ||
| 110 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 111 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 112 | </row> | ||
| 113 | </tbody> | ||
| 114 | </tgroup> | ||
| 115 | </informaltable> | ||
| 116 | </para> | ||
| 117 | </formalpara> | ||
| 118 | </example> | ||
| 119 | </refsect1> | ||
| 120 | </refentry> | ||
| 121 | |||
| 122 | <!-- | ||
| 123 | Local Variables: | ||
| 124 | mode: sgml | ||
| 125 | sgml-parent-document: "pixfmt.sgml" | ||
| 126 | indent-tabs-mode: nil | ||
| 127 | End: | ||
| 128 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-y16.xml b/Documentation/DocBook/v4l/pixfmt-y16.xml new file mode 100644 index 000000000000..d58404015078 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-y16.xml | |||
| @@ -0,0 +1,89 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-Y16"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_Y16 ('Y16 ')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_Y16</constant></refname> | ||
| 8 | <refpurpose>Grey-scale image</refpurpose> | ||
| 9 | </refnamediv> | ||
| 10 | <refsect1> | ||
| 11 | <title>Description</title> | ||
| 12 | |||
| 13 | <para>This is a grey-scale image with a depth of 16 bits per | ||
| 14 | pixel. The least significant byte is stored at lower memory addresses | ||
| 15 | (little-endian). Note the actual sampling precision may be lower than | ||
| 16 | 16 bits, for example 10 bits per pixel with values in range 0 to | ||
| 17 | 1023.</para> | ||
| 18 | |||
| 19 | <example> | ||
| 20 | <title><constant>V4L2_PIX_FMT_Y16</constant> 4 × 4 | ||
| 21 | pixel image</title> | ||
| 22 | |||
| 23 | <formalpara> | ||
| 24 | <title>Byte Order.</title> | ||
| 25 | <para>Each cell is one byte. | ||
| 26 | <informaltable frame="none"> | ||
| 27 | <tgroup cols="9" align="center"> | ||
| 28 | <colspec align="left" colwidth="2*" /> | ||
| 29 | <tbody valign="top"> | ||
| 30 | <row> | ||
| 31 | <entry>start + 0:</entry> | ||
| 32 | <entry>Y'<subscript>00low</subscript></entry> | ||
| 33 | <entry>Y'<subscript>00high</subscript></entry> | ||
| 34 | <entry>Y'<subscript>01low</subscript></entry> | ||
| 35 | <entry>Y'<subscript>01high</subscript></entry> | ||
| 36 | <entry>Y'<subscript>02low</subscript></entry> | ||
| 37 | <entry>Y'<subscript>02high</subscript></entry> | ||
| 38 | <entry>Y'<subscript>03low</subscript></entry> | ||
| 39 | <entry>Y'<subscript>03high</subscript></entry> | ||
| 40 | </row> | ||
| 41 | <row> | ||
| 42 | <entry>start + 8:</entry> | ||
| 43 | <entry>Y'<subscript>10low</subscript></entry> | ||
| 44 | <entry>Y'<subscript>10high</subscript></entry> | ||
| 45 | <entry>Y'<subscript>11low</subscript></entry> | ||
| 46 | <entry>Y'<subscript>11high</subscript></entry> | ||
| 47 | <entry>Y'<subscript>12low</subscript></entry> | ||
| 48 | <entry>Y'<subscript>12high</subscript></entry> | ||
| 49 | <entry>Y'<subscript>13low</subscript></entry> | ||
| 50 | <entry>Y'<subscript>13high</subscript></entry> | ||
| 51 | </row> | ||
| 52 | <row> | ||
| 53 | <entry>start + 16:</entry> | ||
| 54 | <entry>Y'<subscript>20low</subscript></entry> | ||
| 55 | <entry>Y'<subscript>20high</subscript></entry> | ||
| 56 | <entry>Y'<subscript>21low</subscript></entry> | ||
| 57 | <entry>Y'<subscript>21high</subscript></entry> | ||
| 58 | <entry>Y'<subscript>22low</subscript></entry> | ||
| 59 | <entry>Y'<subscript>22high</subscript></entry> | ||
| 60 | <entry>Y'<subscript>23low</subscript></entry> | ||
| 61 | <entry>Y'<subscript>23high</subscript></entry> | ||
| 62 | </row> | ||
| 63 | <row> | ||
| 64 | <entry>start + 24:</entry> | ||
| 65 | <entry>Y'<subscript>30low</subscript></entry> | ||
| 66 | <entry>Y'<subscript>30high</subscript></entry> | ||
| 67 | <entry>Y'<subscript>31low</subscript></entry> | ||
| 68 | <entry>Y'<subscript>31high</subscript></entry> | ||
| 69 | <entry>Y'<subscript>32low</subscript></entry> | ||
| 70 | <entry>Y'<subscript>32high</subscript></entry> | ||
| 71 | <entry>Y'<subscript>33low</subscript></entry> | ||
| 72 | <entry>Y'<subscript>33high</subscript></entry> | ||
| 73 | </row> | ||
| 74 | </tbody> | ||
| 75 | </tgroup> | ||
| 76 | </informaltable> | ||
| 77 | </para> | ||
| 78 | </formalpara> | ||
| 79 | </example> | ||
| 80 | </refsect1> | ||
| 81 | </refentry> | ||
| 82 | |||
| 83 | <!-- | ||
| 84 | Local Variables: | ||
| 85 | mode: sgml | ||
| 86 | sgml-parent-document: "pixfmt.sgml" | ||
| 87 | indent-tabs-mode: nil | ||
| 88 | End: | ||
| 89 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-y41p.xml b/Documentation/DocBook/v4l/pixfmt-y41p.xml new file mode 100644 index 000000000000..73c8536efb05 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-y41p.xml | |||
| @@ -0,0 +1,157 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-Y41P"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_Y41P ('Y41P')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_Y41P</constant></refname> | ||
| 8 | <refpurpose>Format with ¼ horizontal chroma | ||
| 9 | resolution, also known as YUV 4:1:1</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | <refsect1> | ||
| 12 | <title>Description</title> | ||
| 13 | |||
| 14 | <para>In this format each 12 bytes is eight pixels. In the | ||
| 15 | twelve bytes are two CbCr pairs and eight Y's. The first CbCr pair | ||
| 16 | goes with the first four Y's, and the second CbCr pair goes with the | ||
| 17 | other four Y's. The Cb and Cr components have one fourth the | ||
| 18 | horizontal resolution of the Y component.</para> | ||
| 19 | |||
| 20 | <para>Do not confuse this format with <link | ||
| 21 | linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link>. | ||
| 22 | Y41P is derived from "YUV 4:1:1 <emphasis>packed</emphasis>", while | ||
| 23 | YUV411P stands for "YUV 4:1:1 <emphasis>planar</emphasis>".</para> | ||
| 24 | |||
| 25 | <example> | ||
| 26 | <title><constant>V4L2_PIX_FMT_Y41P</constant> 8 × 4 | ||
| 27 | pixel image</title> | ||
| 28 | |||
| 29 | <formalpara> | ||
| 30 | <title>Byte Order</title> | ||
| 31 | <para>Each cell is one byte. | ||
| 32 | <informaltable frame="none"> | ||
| 33 | <tgroup cols="13" align="center"> | ||
| 34 | <colspec align="left" colwidth="2*" /> | ||
| 35 | <tbody valign="top"> | ||
| 36 | <row> | ||
| 37 | <entry>start + 0:</entry> | ||
| 38 | <entry>Cb<subscript>00</subscript></entry> | ||
| 39 | <entry>Y'<subscript>00</subscript></entry> | ||
| 40 | <entry>Cr<subscript>00</subscript></entry> | ||
| 41 | <entry>Y'<subscript>01</subscript></entry> | ||
| 42 | <entry>Cb<subscript>01</subscript></entry> | ||
| 43 | <entry>Y'<subscript>02</subscript></entry> | ||
| 44 | <entry>Cr<subscript>01</subscript></entry> | ||
| 45 | <entry>Y'<subscript>03</subscript></entry> | ||
| 46 | <entry>Y'<subscript>04</subscript></entry> | ||
| 47 | <entry>Y'<subscript>05</subscript></entry> | ||
| 48 | <entry>Y'<subscript>06</subscript></entry> | ||
| 49 | <entry>Y'<subscript>07</subscript></entry> | ||
| 50 | </row> | ||
| 51 | <row> | ||
| 52 | <entry>start + 12:</entry> | ||
| 53 | <entry>Cb<subscript>10</subscript></entry> | ||
| 54 | <entry>Y'<subscript>10</subscript></entry> | ||
| 55 | <entry>Cr<subscript>10</subscript></entry> | ||
| 56 | <entry>Y'<subscript>11</subscript></entry> | ||
| 57 | <entry>Cb<subscript>11</subscript></entry> | ||
| 58 | <entry>Y'<subscript>12</subscript></entry> | ||
| 59 | <entry>Cr<subscript>11</subscript></entry> | ||
| 60 | <entry>Y'<subscript>13</subscript></entry> | ||
| 61 | <entry>Y'<subscript>14</subscript></entry> | ||
| 62 | <entry>Y'<subscript>15</subscript></entry> | ||
| 63 | <entry>Y'<subscript>16</subscript></entry> | ||
| 64 | <entry>Y'<subscript>17</subscript></entry> | ||
| 65 | </row> | ||
| 66 | <row> | ||
| 67 | <entry>start + 24:</entry> | ||
| 68 | <entry>Cb<subscript>20</subscript></entry> | ||
| 69 | <entry>Y'<subscript>20</subscript></entry> | ||
| 70 | <entry>Cr<subscript>20</subscript></entry> | ||
| 71 | <entry>Y'<subscript>21</subscript></entry> | ||
| 72 | <entry>Cb<subscript>21</subscript></entry> | ||
| 73 | <entry>Y'<subscript>22</subscript></entry> | ||
| 74 | <entry>Cr<subscript>21</subscript></entry> | ||
| 75 | <entry>Y'<subscript>23</subscript></entry> | ||
| 76 | <entry>Y'<subscript>24</subscript></entry> | ||
| 77 | <entry>Y'<subscript>25</subscript></entry> | ||
| 78 | <entry>Y'<subscript>26</subscript></entry> | ||
| 79 | <entry>Y'<subscript>27</subscript></entry> | ||
| 80 | </row> | ||
| 81 | <row> | ||
| 82 | <entry>start + 36:</entry> | ||
| 83 | <entry>Cb<subscript>30</subscript></entry> | ||
| 84 | <entry>Y'<subscript>30</subscript></entry> | ||
| 85 | <entry>Cr<subscript>30</subscript></entry> | ||
| 86 | <entry>Y'<subscript>31</subscript></entry> | ||
| 87 | <entry>Cb<subscript>31</subscript></entry> | ||
| 88 | <entry>Y'<subscript>32</subscript></entry> | ||
| 89 | <entry>Cr<subscript>31</subscript></entry> | ||
| 90 | <entry>Y'<subscript>33</subscript></entry> | ||
| 91 | <entry>Y'<subscript>34</subscript></entry> | ||
| 92 | <entry>Y'<subscript>35</subscript></entry> | ||
| 93 | <entry>Y'<subscript>36</subscript></entry> | ||
| 94 | <entry>Y'<subscript>37</subscript></entry> | ||
| 95 | </row> | ||
| 96 | </tbody> | ||
| 97 | </tgroup> | ||
| 98 | </informaltable></para> | ||
| 99 | </formalpara> | ||
| 100 | |||
| 101 | <formalpara> | ||
| 102 | <title>Color Sample Location.</title> | ||
| 103 | <para> | ||
| 104 | <informaltable frame="none"> | ||
| 105 | <tgroup cols="15" align="center"> | ||
| 106 | <tbody valign="top"> | ||
| 107 | <row> | ||
| 108 | <entry></entry> | ||
| 109 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 110 | <entry>2</entry><entry></entry><entry>3</entry><entry></entry> | ||
| 111 | <entry>4</entry><entry></entry><entry>5</entry><entry></entry> | ||
| 112 | <entry>6</entry><entry></entry><entry>7</entry> | ||
| 113 | </row> | ||
| 114 | <row> | ||
| 115 | <entry>0</entry> | ||
| 116 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 117 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 118 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 119 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 120 | </row> | ||
| 121 | <row> | ||
| 122 | <entry>1</entry> | ||
| 123 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 124 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 125 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 126 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 127 | </row> | ||
| 128 | <row> | ||
| 129 | <entry>2</entry> | ||
| 130 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 131 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 132 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 133 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry>3</entry> | ||
| 137 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 138 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 139 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 140 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 141 | </row> | ||
| 142 | </tbody> | ||
| 143 | </tgroup> | ||
| 144 | </informaltable> | ||
| 145 | </para> | ||
| 146 | </formalpara> | ||
| 147 | </example> | ||
| 148 | </refsect1> | ||
| 149 | </refentry> | ||
| 150 | |||
| 151 | <!-- | ||
| 152 | Local Variables: | ||
| 153 | mode: sgml | ||
| 154 | sgml-parent-document: "pixfmt.sgml" | ||
| 155 | indent-tabs-mode: nil | ||
| 156 | End: | ||
| 157 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yuv410.xml b/Documentation/DocBook/v4l/pixfmt-yuv410.xml new file mode 100644 index 000000000000..8eb4a193d770 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuv410.xml | |||
| @@ -0,0 +1,141 @@ | |||
| 1 | <refentry> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname id="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></refname> | ||
| 8 | <refname id="V4L2-PIX-FMT-YUV410"><constant>V4L2_PIX_FMT_YUV410</constant></refname> | ||
| 9 | <refpurpose>Planar formats with ¼ horizontal and | ||
| 10 | vertical chroma resolution, also known as YUV 4:1:0</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>These are planar formats, as opposed to a packed format. | ||
| 16 | The three components are separated into three sub-images or planes. | ||
| 17 | The Y plane is first. The Y plane has one byte per pixel. For | ||
| 18 | <constant>V4L2_PIX_FMT_YVU410</constant>, the Cr plane immediately | ||
| 19 | follows the Y plane in memory. The Cr plane is ¼ the width and | ||
| 20 | ¼ the height of the Y plane (and of the image). Each Cr belongs | ||
| 21 | to 16 pixels, a four-by-four square of the image. Following the Cr | ||
| 22 | plane is the Cb plane, just like the Cr plane. | ||
| 23 | <constant>V4L2_PIX_FMT_YUV410</constant> is the same, except the Cb | ||
| 24 | plane comes first, then the Cr plane.</para> | ||
| 25 | |||
| 26 | <para>If the Y plane has pad bytes after each row, then the Cr | ||
| 27 | and Cb planes have ¼ as many pad bytes after their rows. In | ||
| 28 | other words, four Cx rows (including padding) are exactly as long as | ||
| 29 | one Y row (including padding).</para> | ||
| 30 | |||
| 31 | <example> | ||
| 32 | <title><constant>V4L2_PIX_FMT_YVU410</constant> 4 × 4 | ||
| 33 | pixel image</title> | ||
| 34 | |||
| 35 | <formalpara> | ||
| 36 | <title>Byte Order.</title> | ||
| 37 | <para>Each cell is one byte. | ||
| 38 | <informaltable frame="none"> | ||
| 39 | <tgroup cols="5" align="center"> | ||
| 40 | <colspec align="left" colwidth="2*" /> | ||
| 41 | <tbody valign="top"> | ||
| 42 | <row> | ||
| 43 | <entry>start + 0:</entry> | ||
| 44 | <entry>Y'<subscript>00</subscript></entry> | ||
| 45 | <entry>Y'<subscript>01</subscript></entry> | ||
| 46 | <entry>Y'<subscript>02</subscript></entry> | ||
| 47 | <entry>Y'<subscript>03</subscript></entry> | ||
| 48 | </row> | ||
| 49 | <row> | ||
| 50 | <entry>start + 4:</entry> | ||
| 51 | <entry>Y'<subscript>10</subscript></entry> | ||
| 52 | <entry>Y'<subscript>11</subscript></entry> | ||
| 53 | <entry>Y'<subscript>12</subscript></entry> | ||
| 54 | <entry>Y'<subscript>13</subscript></entry> | ||
| 55 | </row> | ||
| 56 | <row> | ||
| 57 | <entry>start + 8:</entry> | ||
| 58 | <entry>Y'<subscript>20</subscript></entry> | ||
| 59 | <entry>Y'<subscript>21</subscript></entry> | ||
| 60 | <entry>Y'<subscript>22</subscript></entry> | ||
| 61 | <entry>Y'<subscript>23</subscript></entry> | ||
| 62 | </row> | ||
| 63 | <row> | ||
| 64 | <entry>start + 12:</entry> | ||
| 65 | <entry>Y'<subscript>30</subscript></entry> | ||
| 66 | <entry>Y'<subscript>31</subscript></entry> | ||
| 67 | <entry>Y'<subscript>32</subscript></entry> | ||
| 68 | <entry>Y'<subscript>33</subscript></entry> | ||
| 69 | </row> | ||
| 70 | <row> | ||
| 71 | <entry>start + 16:</entry> | ||
| 72 | <entry>Cr<subscript>00</subscript></entry> | ||
| 73 | </row> | ||
| 74 | <row> | ||
| 75 | <entry>start + 17:</entry> | ||
| 76 | <entry>Cb<subscript>00</subscript></entry> | ||
| 77 | </row> | ||
| 78 | </tbody> | ||
| 79 | </tgroup> | ||
| 80 | </informaltable> | ||
| 81 | </para> | ||
| 82 | </formalpara> | ||
| 83 | |||
| 84 | <formalpara> | ||
| 85 | <title>Color Sample Location.</title> | ||
| 86 | <para> | ||
| 87 | <informaltable frame="none"> | ||
| 88 | <tgroup cols="7" align="center"> | ||
| 89 | <tbody valign="top"> | ||
| 90 | <row> | ||
| 91 | <entry></entry> | ||
| 92 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 93 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 94 | </row> | ||
| 95 | <row> | ||
| 96 | <entry>0</entry> | ||
| 97 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 98 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 99 | </row> | ||
| 100 | <row> | ||
| 101 | <entry></entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>1</entry> | ||
| 105 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry></entry> | ||
| 110 | <entry></entry><entry></entry><entry></entry><entry>C</entry> | ||
| 111 | <entry></entry><entry></entry><entry></entry> | ||
| 112 | </row> | ||
| 113 | <row> | ||
| 114 | <entry>2</entry> | ||
| 115 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 116 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 117 | </row> | ||
| 118 | <row> | ||
| 119 | <entry></entry> | ||
| 120 | </row> | ||
| 121 | <row> | ||
| 122 | <entry>3</entry> | ||
| 123 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 124 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 125 | </row> | ||
| 126 | </tbody> | ||
| 127 | </tgroup> | ||
| 128 | </informaltable> | ||
| 129 | </para> | ||
| 130 | </formalpara> | ||
| 131 | </example> | ||
| 132 | </refsect1> | ||
| 133 | </refentry> | ||
| 134 | |||
| 135 | <!-- | ||
| 136 | Local Variables: | ||
| 137 | mode: sgml | ||
| 138 | sgml-parent-document: "pixfmt.sgml" | ||
| 139 | indent-tabs-mode: nil | ||
| 140 | End: | ||
| 141 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yuv411p.xml b/Documentation/DocBook/v4l/pixfmt-yuv411p.xml new file mode 100644 index 000000000000..00e0960a9869 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuv411p.xml | |||
| @@ -0,0 +1,155 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-YUV411P"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YUV411P ('411P')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_YUV411P</constant></refname> | ||
| 8 | <refpurpose>Format with ¼ horizontal chroma resolution, | ||
| 9 | also known as YUV 4:1:1. Planar layout as opposed to | ||
| 10 | <constant>V4L2_PIX_FMT_Y41P</constant></refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>This format is not commonly used. This is a planar | ||
| 16 | format similar to the 4:2:2 planar format except with half as many | ||
| 17 | chroma. The three components are separated into three sub-images or | ||
| 18 | planes. The Y plane is first. The Y plane has one byte per pixel. The | ||
| 19 | Cb plane immediately follows the Y plane in memory. The Cb plane is | ||
| 20 | ¼ the width of the Y plane (and of the image). Each Cb belongs | ||
| 21 | to 4 pixels all on the same row. For example, | ||
| 22 | Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, | ||
| 23 | Y'<subscript>01</subscript>, Y'<subscript>02</subscript> and | ||
| 24 | Y'<subscript>03</subscript>. Following the Cb plane is the Cr plane, | ||
| 25 | just like the Cb plane.</para> | ||
| 26 | |||
| 27 | <para>If the Y plane has pad bytes after each row, then the Cr | ||
| 28 | and Cb planes have ¼ as many pad bytes after their rows. In | ||
| 29 | other words, four C x rows (including padding) is exactly as long as | ||
| 30 | one Y row (including padding).</para> | ||
| 31 | |||
| 32 | <example> | ||
| 33 | <title><constant>V4L2_PIX_FMT_YUV411P</constant> 4 × 4 | ||
| 34 | pixel image</title> | ||
| 35 | |||
| 36 | <formalpara> | ||
| 37 | <title>Byte Order.</title> | ||
| 38 | <para>Each cell is one byte. | ||
| 39 | <informaltable frame="none"> | ||
| 40 | <tgroup cols="5" align="center"> | ||
| 41 | <colspec align="left" colwidth="2*" /> | ||
| 42 | <tbody valign="top"> | ||
| 43 | <row> | ||
| 44 | <entry>start + 0:</entry> | ||
| 45 | <entry>Y'<subscript>00</subscript></entry> | ||
| 46 | <entry>Y'<subscript>01</subscript></entry> | ||
| 47 | <entry>Y'<subscript>02</subscript></entry> | ||
| 48 | <entry>Y'<subscript>03</subscript></entry> | ||
| 49 | </row> | ||
| 50 | <row> | ||
| 51 | <entry>start + 4:</entry> | ||
| 52 | <entry>Y'<subscript>10</subscript></entry> | ||
| 53 | <entry>Y'<subscript>11</subscript></entry> | ||
| 54 | <entry>Y'<subscript>12</subscript></entry> | ||
| 55 | <entry>Y'<subscript>13</subscript></entry> | ||
| 56 | </row> | ||
| 57 | <row> | ||
| 58 | <entry>start + 8:</entry> | ||
| 59 | <entry>Y'<subscript>20</subscript></entry> | ||
| 60 | <entry>Y'<subscript>21</subscript></entry> | ||
| 61 | <entry>Y'<subscript>22</subscript></entry> | ||
| 62 | <entry>Y'<subscript>23</subscript></entry> | ||
| 63 | </row> | ||
| 64 | <row> | ||
| 65 | <entry>start + 12:</entry> | ||
| 66 | <entry>Y'<subscript>30</subscript></entry> | ||
| 67 | <entry>Y'<subscript>31</subscript></entry> | ||
| 68 | <entry>Y'<subscript>32</subscript></entry> | ||
| 69 | <entry>Y'<subscript>33</subscript></entry> | ||
| 70 | </row> | ||
| 71 | <row> | ||
| 72 | <entry>start + 16:</entry> | ||
| 73 | <entry>Cb<subscript>00</subscript></entry> | ||
| 74 | </row> | ||
| 75 | <row> | ||
| 76 | <entry>start + 17:</entry> | ||
| 77 | <entry>Cb<subscript>10</subscript></entry> | ||
| 78 | </row> | ||
| 79 | <row> | ||
| 80 | <entry>start + 18:</entry> | ||
| 81 | <entry>Cb<subscript>20</subscript></entry> | ||
| 82 | </row> | ||
| 83 | <row> | ||
| 84 | <entry>start + 19:</entry> | ||
| 85 | <entry>Cb<subscript>30</subscript></entry> | ||
| 86 | </row> | ||
| 87 | <row> | ||
| 88 | <entry>start + 20:</entry> | ||
| 89 | <entry>Cr<subscript>00</subscript></entry> | ||
| 90 | </row> | ||
| 91 | <row> | ||
| 92 | <entry>start + 21:</entry> | ||
| 93 | <entry>Cr<subscript>10</subscript></entry> | ||
| 94 | </row> | ||
| 95 | <row> | ||
| 96 | <entry>start + 22:</entry> | ||
| 97 | <entry>Cr<subscript>20</subscript></entry> | ||
| 98 | </row> | ||
| 99 | <row> | ||
| 100 | <entry>start + 23:</entry> | ||
| 101 | <entry>Cr<subscript>30</subscript></entry> | ||
| 102 | </row> | ||
| 103 | </tbody> | ||
| 104 | </tgroup> | ||
| 105 | </informaltable> | ||
| 106 | </para> | ||
| 107 | </formalpara> | ||
| 108 | |||
| 109 | <formalpara> | ||
| 110 | <title>Color Sample Location.</title> | ||
| 111 | <para> | ||
| 112 | <informaltable frame="none"> | ||
| 113 | <tgroup cols="7" align="center"> | ||
| 114 | <tbody valign="top"> | ||
| 115 | <row> | ||
| 116 | <entry></entry> | ||
| 117 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 118 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 119 | </row> | ||
| 120 | <row> | ||
| 121 | <entry>0</entry> | ||
| 122 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 123 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 124 | </row> | ||
| 125 | <row> | ||
| 126 | <entry>1</entry> | ||
| 127 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 128 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 129 | </row> | ||
| 130 | <row> | ||
| 131 | <entry>2</entry> | ||
| 132 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 133 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry>3</entry> | ||
| 137 | <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> | ||
| 138 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 139 | </row> | ||
| 140 | </tbody> | ||
| 141 | </tgroup> | ||
| 142 | </informaltable> | ||
| 143 | </para> | ||
| 144 | </formalpara> | ||
| 145 | </example> | ||
| 146 | </refsect1> | ||
| 147 | </refentry> | ||
| 148 | |||
| 149 | <!-- | ||
| 150 | Local Variables: | ||
| 151 | mode: sgml | ||
| 152 | sgml-parent-document: "v4l2.sgml" | ||
| 153 | indent-tabs-mode: nil | ||
| 154 | End: | ||
| 155 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yuv420.xml b/Documentation/DocBook/v4l/pixfmt-yuv420.xml new file mode 100644 index 000000000000..42d7de5e456d --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuv420.xml | |||
| @@ -0,0 +1,157 @@ | |||
| 1 | <refentry> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname id="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></refname> | ||
| 8 | <refname id="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></refname> | ||
| 9 | <refpurpose>Planar formats with ½ horizontal and | ||
| 10 | vertical chroma resolution, also known as YUV 4:2:0</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>These are planar formats, as opposed to a packed format. | ||
| 16 | The three components are separated into three sub- images or planes. | ||
| 17 | The Y plane is first. The Y plane has one byte per pixel. For | ||
| 18 | <constant>V4L2_PIX_FMT_YVU420</constant>, the Cr plane immediately | ||
| 19 | follows the Y plane in memory. The Cr plane is half the width and half | ||
| 20 | the height of the Y plane (and of the image). Each Cr belongs to four | ||
| 21 | pixels, a two-by-two square of the image. For example, | ||
| 22 | Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, | ||
| 23 | Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and | ||
| 24 | Y'<subscript>11</subscript>. Following the Cr plane is the Cb plane, | ||
| 25 | just like the Cr plane. <constant>V4L2_PIX_FMT_YUV420</constant> is | ||
| 26 | the same except the Cb plane comes first, then the Cr plane.</para> | ||
| 27 | |||
| 28 | <para>If the Y plane has pad bytes after each row, then the Cr | ||
| 29 | and Cb planes have half as many pad bytes after their rows. In other | ||
| 30 | words, two Cx rows (including padding) is exactly as long as one Y row | ||
| 31 | (including padding).</para> | ||
| 32 | |||
| 33 | <example> | ||
| 34 | <title><constant>V4L2_PIX_FMT_YVU420</constant> 4 × 4 | ||
| 35 | pixel image</title> | ||
| 36 | |||
| 37 | <formalpara> | ||
| 38 | <title>Byte Order.</title> | ||
| 39 | <para>Each cell is one byte. | ||
| 40 | <informaltable frame="none"> | ||
| 41 | <tgroup cols="5" align="center"> | ||
| 42 | <colspec align="left" colwidth="2*" /> | ||
| 43 | <tbody valign="top"> | ||
| 44 | <row> | ||
| 45 | <entry>start + 0:</entry> | ||
| 46 | <entry>Y'<subscript>00</subscript></entry> | ||
| 47 | <entry>Y'<subscript>01</subscript></entry> | ||
| 48 | <entry>Y'<subscript>02</subscript></entry> | ||
| 49 | <entry>Y'<subscript>03</subscript></entry> | ||
| 50 | </row> | ||
| 51 | <row> | ||
| 52 | <entry>start + 4:</entry> | ||
| 53 | <entry>Y'<subscript>10</subscript></entry> | ||
| 54 | <entry>Y'<subscript>11</subscript></entry> | ||
| 55 | <entry>Y'<subscript>12</subscript></entry> | ||
| 56 | <entry>Y'<subscript>13</subscript></entry> | ||
| 57 | </row> | ||
| 58 | <row> | ||
| 59 | <entry>start + 8:</entry> | ||
| 60 | <entry>Y'<subscript>20</subscript></entry> | ||
| 61 | <entry>Y'<subscript>21</subscript></entry> | ||
| 62 | <entry>Y'<subscript>22</subscript></entry> | ||
| 63 | <entry>Y'<subscript>23</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 12:</entry> | ||
| 67 | <entry>Y'<subscript>30</subscript></entry> | ||
| 68 | <entry>Y'<subscript>31</subscript></entry> | ||
| 69 | <entry>Y'<subscript>32</subscript></entry> | ||
| 70 | <entry>Y'<subscript>33</subscript></entry> | ||
| 71 | </row> | ||
| 72 | <row> | ||
| 73 | <entry>start + 16:</entry> | ||
| 74 | <entry>Cr<subscript>00</subscript></entry> | ||
| 75 | <entry>Cr<subscript>01</subscript></entry> | ||
| 76 | </row> | ||
| 77 | <row> | ||
| 78 | <entry>start + 18:</entry> | ||
| 79 | <entry>Cr<subscript>10</subscript></entry> | ||
| 80 | <entry>Cr<subscript>11</subscript></entry> | ||
| 81 | </row> | ||
| 82 | <row> | ||
| 83 | <entry>start + 20:</entry> | ||
| 84 | <entry>Cb<subscript>00</subscript></entry> | ||
| 85 | <entry>Cb<subscript>01</subscript></entry> | ||
| 86 | </row> | ||
| 87 | <row> | ||
| 88 | <entry>start + 22:</entry> | ||
| 89 | <entry>Cb<subscript>10</subscript></entry> | ||
| 90 | <entry>Cb<subscript>11</subscript></entry> | ||
| 91 | </row> | ||
| 92 | </tbody> | ||
| 93 | </tgroup> | ||
| 94 | </informaltable> | ||
| 95 | </para> | ||
| 96 | </formalpara> | ||
| 97 | |||
| 98 | <formalpara> | ||
| 99 | <title>Color Sample Location.</title> | ||
| 100 | <para> | ||
| 101 | <informaltable frame="none"> | ||
| 102 | <tgroup cols="7" align="center"> | ||
| 103 | <tbody valign="top"> | ||
| 104 | <row> | ||
| 105 | <entry></entry> | ||
| 106 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 107 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 108 | </row> | ||
| 109 | <row> | ||
| 110 | <entry>0</entry> | ||
| 111 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 112 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 113 | </row> | ||
| 114 | <row> | ||
| 115 | <entry></entry> | ||
| 116 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 117 | <entry></entry><entry>C</entry><entry></entry> | ||
| 118 | </row> | ||
| 119 | <row> | ||
| 120 | <entry>1</entry> | ||
| 121 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 122 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 123 | </row> | ||
| 124 | <row> | ||
| 125 | <entry></entry> | ||
| 126 | </row> | ||
| 127 | <row> | ||
| 128 | <entry>2</entry> | ||
| 129 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 130 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 131 | </row> | ||
| 132 | <row> | ||
| 133 | <entry></entry> | ||
| 134 | <entry></entry><entry>C</entry><entry></entry><entry></entry> | ||
| 135 | <entry></entry><entry>C</entry><entry></entry> | ||
| 136 | </row> | ||
| 137 | <row> | ||
| 138 | <entry>3</entry> | ||
| 139 | <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> | ||
| 140 | <entry>Y</entry><entry></entry><entry>Y</entry> | ||
| 141 | </row> | ||
| 142 | </tbody> | ||
| 143 | </tgroup> | ||
| 144 | </informaltable> | ||
| 145 | </para> | ||
| 146 | </formalpara> | ||
| 147 | </example> | ||
| 148 | </refsect1> | ||
| 149 | </refentry> | ||
| 150 | |||
| 151 | <!-- | ||
| 152 | Local Variables: | ||
| 153 | mode: sgml | ||
| 154 | sgml-parent-document: "pixfmt.sgml" | ||
| 155 | indent-tabs-mode: nil | ||
| 156 | End: | ||
| 157 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yuv422p.xml b/Documentation/DocBook/v4l/pixfmt-yuv422p.xml new file mode 100644 index 000000000000..4348bd9f0d01 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuv422p.xml | |||
| @@ -0,0 +1,161 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-YUV422P"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YUV422P ('422P')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_YUV422P</constant></refname> | ||
| 8 | <refpurpose>Format with ½ horizontal chroma resolution, | ||
| 9 | also known as YUV 4:2:2. Planar layout as opposed to | ||
| 10 | <constant>V4L2_PIX_FMT_YUYV</constant></refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>This format is not commonly used. This is a planar | ||
| 16 | version of the YUYV format. The three components are separated into | ||
| 17 | three sub-images or planes. The Y plane is first. The Y plane has one | ||
| 18 | byte per pixel. The Cb plane immediately follows the Y plane in | ||
| 19 | memory. The Cb plane is half the width of the Y plane (and of the | ||
| 20 | image). Each Cb belongs to two pixels. For example, | ||
| 21 | Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, | ||
| 22 | Y'<subscript>01</subscript>. Following the Cb plane is the Cr plane, | ||
| 23 | just like the Cb plane.</para> | ||
| 24 | |||
| 25 | <para>If the Y plane has pad bytes after each row, then the Cr | ||
| 26 | and Cb planes have half as many pad bytes after their rows. In other | ||
| 27 | words, two Cx rows (including padding) is exactly as long as one Y row | ||
| 28 | (including padding).</para> | ||
| 29 | |||
| 30 | <example> | ||
| 31 | <title><constant>V4L2_PIX_FMT_YUV422P</constant> 4 × 4 | ||
| 32 | pixel image</title> | ||
| 33 | |||
| 34 | <formalpara> | ||
| 35 | <title>Byte Order.</title> | ||
| 36 | <para>Each cell is one byte. | ||
| 37 | <informaltable frame="none"> | ||
| 38 | <tgroup cols="5" align="center"> | ||
| 39 | <colspec align="left" colwidth="2*" /> | ||
| 40 | <tbody valign="top"> | ||
| 41 | <row> | ||
| 42 | <entry>start + 0:</entry> | ||
| 43 | <entry>Y'<subscript>00</subscript></entry> | ||
| 44 | <entry>Y'<subscript>01</subscript></entry> | ||
| 45 | <entry>Y'<subscript>02</subscript></entry> | ||
| 46 | <entry>Y'<subscript>03</subscript></entry> | ||
| 47 | </row> | ||
| 48 | <row> | ||
| 49 | <entry>start + 4:</entry> | ||
| 50 | <entry>Y'<subscript>10</subscript></entry> | ||
| 51 | <entry>Y'<subscript>11</subscript></entry> | ||
| 52 | <entry>Y'<subscript>12</subscript></entry> | ||
| 53 | <entry>Y'<subscript>13</subscript></entry> | ||
| 54 | </row> | ||
| 55 | <row> | ||
| 56 | <entry>start + 8:</entry> | ||
| 57 | <entry>Y'<subscript>20</subscript></entry> | ||
| 58 | <entry>Y'<subscript>21</subscript></entry> | ||
| 59 | <entry>Y'<subscript>22</subscript></entry> | ||
| 60 | <entry>Y'<subscript>23</subscript></entry> | ||
| 61 | </row> | ||
| 62 | <row> | ||
| 63 | <entry>start + 12:</entry> | ||
| 64 | <entry>Y'<subscript>30</subscript></entry> | ||
| 65 | <entry>Y'<subscript>31</subscript></entry> | ||
| 66 | <entry>Y'<subscript>32</subscript></entry> | ||
| 67 | <entry>Y'<subscript>33</subscript></entry> | ||
| 68 | </row> | ||
| 69 | <row> | ||
| 70 | <entry>start + 16:</entry> | ||
| 71 | <entry>Cb<subscript>00</subscript></entry> | ||
| 72 | <entry>Cb<subscript>01</subscript></entry> | ||
| 73 | </row> | ||
| 74 | <row> | ||
| 75 | <entry>start + 18:</entry> | ||
| 76 | <entry>Cb<subscript>10</subscript></entry> | ||
| 77 | <entry>Cb<subscript>11</subscript></entry> | ||
| 78 | </row> | ||
| 79 | <row> | ||
| 80 | <entry>start + 20:</entry> | ||
| 81 | <entry>Cb<subscript>20</subscript></entry> | ||
| 82 | <entry>Cb<subscript>21</subscript></entry> | ||
| 83 | </row> | ||
| 84 | <row> | ||
| 85 | <entry>start + 22:</entry> | ||
| 86 | <entry>Cb<subscript>30</subscript></entry> | ||
| 87 | <entry>Cb<subscript>31</subscript></entry> | ||
| 88 | </row> | ||
| 89 | <row> | ||
| 90 | <entry>start + 24:</entry> | ||
| 91 | <entry>Cr<subscript>00</subscript></entry> | ||
| 92 | <entry>Cr<subscript>01</subscript></entry> | ||
| 93 | </row> | ||
| 94 | <row> | ||
| 95 | <entry>start + 26:</entry> | ||
| 96 | <entry>Cr<subscript>10</subscript></entry> | ||
| 97 | <entry>Cr<subscript>11</subscript></entry> | ||
| 98 | </row> | ||
| 99 | <row> | ||
| 100 | <entry>start + 28:</entry> | ||
| 101 | <entry>Cr<subscript>20</subscript></entry> | ||
| 102 | <entry>Cr<subscript>21</subscript></entry> | ||
| 103 | </row> | ||
| 104 | <row> | ||
| 105 | <entry>start + 30:</entry> | ||
| 106 | <entry>Cr<subscript>30</subscript></entry> | ||
| 107 | <entry>Cr<subscript>31</subscript></entry> | ||
| 108 | </row> | ||
| 109 | </tbody> | ||
| 110 | </tgroup> | ||
| 111 | </informaltable> | ||
| 112 | </para> | ||
| 113 | </formalpara> | ||
| 114 | |||
| 115 | <formalpara> | ||
| 116 | <title>Color Sample Location.</title> | ||
| 117 | <para> | ||
| 118 | <informaltable frame="none"> | ||
| 119 | <tgroup cols="7" align="center"> | ||
| 120 | <tbody valign="top"> | ||
| 121 | <row> | ||
| 122 | <entry></entry> | ||
| 123 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 124 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry>0</entry> | ||
| 128 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 129 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 130 | </row> | ||
| 131 | <row> | ||
| 132 | <entry>1</entry> | ||
| 133 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 134 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 135 | </row> | ||
| 136 | <row> | ||
| 137 | <entry>2</entry> | ||
| 138 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 139 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 140 | </row> | ||
| 141 | <row> | ||
| 142 | <entry>3</entry> | ||
| 143 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 144 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 145 | </row> | ||
| 146 | </tbody> | ||
| 147 | </tgroup> | ||
| 148 | </informaltable> | ||
| 149 | </para> | ||
| 150 | </formalpara> | ||
| 151 | </example> | ||
| 152 | </refsect1> | ||
| 153 | </refentry> | ||
| 154 | |||
| 155 | <!-- | ||
| 156 | Local Variables: | ||
| 157 | mode: sgml | ||
| 158 | sgml-parent-document: "pixfmt.sgml" | ||
| 159 | indent-tabs-mode: nil | ||
| 160 | End: | ||
| 161 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yuyv.xml b/Documentation/DocBook/v4l/pixfmt-yuyv.xml new file mode 100644 index 000000000000..bdb2ffacbbcc --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuyv.xml | |||
| @@ -0,0 +1,128 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-YUYV"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YUYV ('YUYV')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_YUYV</constant></refname> | ||
| 8 | <refpurpose>Packed format with ½ horizontal chroma | ||
| 9 | resolution, also known as YUV 4:2:2</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | <refsect1> | ||
| 12 | <title>Description</title> | ||
| 13 | |||
| 14 | <para>In this format each four bytes is two pixels. Each four | ||
| 15 | bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and | ||
| 16 | the Cb and Cr belong to both pixels. As you can see, the Cr and Cb | ||
| 17 | components have half the horizontal resolution of the Y component. | ||
| 18 | <constant>V4L2_PIX_FMT_YUYV </constant> is known in the Windows | ||
| 19 | environment as YUY2.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_YUYV</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="9" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>Y'<subscript>00</subscript></entry> | ||
| 35 | <entry>Cb<subscript>00</subscript></entry> | ||
| 36 | <entry>Y'<subscript>01</subscript></entry> | ||
| 37 | <entry>Cr<subscript>00</subscript></entry> | ||
| 38 | <entry>Y'<subscript>02</subscript></entry> | ||
| 39 | <entry>Cb<subscript>01</subscript></entry> | ||
| 40 | <entry>Y'<subscript>03</subscript></entry> | ||
| 41 | <entry>Cr<subscript>01</subscript></entry> | ||
| 42 | </row> | ||
| 43 | <row> | ||
| 44 | <entry>start + 8:</entry> | ||
| 45 | <entry>Y'<subscript>10</subscript></entry> | ||
| 46 | <entry>Cb<subscript>10</subscript></entry> | ||
| 47 | <entry>Y'<subscript>11</subscript></entry> | ||
| 48 | <entry>Cr<subscript>10</subscript></entry> | ||
| 49 | <entry>Y'<subscript>12</subscript></entry> | ||
| 50 | <entry>Cb<subscript>11</subscript></entry> | ||
| 51 | <entry>Y'<subscript>13</subscript></entry> | ||
| 52 | <entry>Cr<subscript>11</subscript></entry> | ||
| 53 | </row> | ||
| 54 | <row> | ||
| 55 | <entry>start + 16:</entry> | ||
| 56 | <entry>Y'<subscript>20</subscript></entry> | ||
| 57 | <entry>Cb<subscript>20</subscript></entry> | ||
| 58 | <entry>Y'<subscript>21</subscript></entry> | ||
| 59 | <entry>Cr<subscript>20</subscript></entry> | ||
| 60 | <entry>Y'<subscript>22</subscript></entry> | ||
| 61 | <entry>Cb<subscript>21</subscript></entry> | ||
| 62 | <entry>Y'<subscript>23</subscript></entry> | ||
| 63 | <entry>Cr<subscript>21</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 24:</entry> | ||
| 67 | <entry>Y'<subscript>30</subscript></entry> | ||
| 68 | <entry>Cb<subscript>30</subscript></entry> | ||
| 69 | <entry>Y'<subscript>31</subscript></entry> | ||
| 70 | <entry>Cr<subscript>30</subscript></entry> | ||
| 71 | <entry>Y'<subscript>32</subscript></entry> | ||
| 72 | <entry>Cb<subscript>31</subscript></entry> | ||
| 73 | <entry>Y'<subscript>33</subscript></entry> | ||
| 74 | <entry>Cr<subscript>31</subscript></entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </informaltable> | ||
| 79 | </para> | ||
| 80 | </formalpara> | ||
| 81 | |||
| 82 | <formalpara> | ||
| 83 | <title>Color Sample Location.</title> | ||
| 84 | <para> | ||
| 85 | <informaltable frame="none"> | ||
| 86 | <tgroup cols="7" align="center"> | ||
| 87 | <tbody valign="top"> | ||
| 88 | <row> | ||
| 89 | <entry></entry> | ||
| 90 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 91 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>0</entry> | ||
| 95 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 96 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>1</entry> | ||
| 100 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 101 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>2</entry> | ||
| 105 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry>3</entry> | ||
| 110 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 111 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 112 | </row> | ||
| 113 | </tbody> | ||
| 114 | </tgroup> | ||
| 115 | </informaltable> | ||
| 116 | </para> | ||
| 117 | </formalpara> | ||
| 118 | </example> | ||
| 119 | </refsect1> | ||
| 120 | </refentry> | ||
| 121 | |||
| 122 | <!-- | ||
| 123 | Local Variables: | ||
| 124 | mode: sgml | ||
| 125 | sgml-parent-document: "pixfmt.sgml" | ||
| 126 | indent-tabs-mode: nil | ||
| 127 | End: | ||
| 128 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt-yvyu.xml b/Documentation/DocBook/v4l/pixfmt-yvyu.xml new file mode 100644 index 000000000000..40d17ae39dde --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yvyu.xml | |||
| @@ -0,0 +1,128 @@ | |||
| 1 | <refentry id="V4L2-PIX-FMT-YVYU"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>V4L2_PIX_FMT_YVYU ('YVYU')</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | <refnamediv> | ||
| 7 | <refname><constant>V4L2_PIX_FMT_YVYU</constant></refname> | ||
| 8 | <refpurpose>Variation of | ||
| 9 | <constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples | ||
| 10 | in memory</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | <refsect1> | ||
| 13 | <title>Description</title> | ||
| 14 | |||
| 15 | <para>In this format each four bytes is two pixels. Each four | ||
| 16 | bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and | ||
| 17 | the Cb and Cr belong to both pixels. As you can see, the Cr and Cb | ||
| 18 | components have half the horizontal resolution of the Y | ||
| 19 | component.</para> | ||
| 20 | |||
| 21 | <example> | ||
| 22 | <title><constant>V4L2_PIX_FMT_YVYU</constant> 4 × 4 | ||
| 23 | pixel image</title> | ||
| 24 | |||
| 25 | <formalpara> | ||
| 26 | <title>Byte Order.</title> | ||
| 27 | <para>Each cell is one byte. | ||
| 28 | <informaltable frame="none"> | ||
| 29 | <tgroup cols="9" align="center"> | ||
| 30 | <colspec align="left" colwidth="2*" /> | ||
| 31 | <tbody valign="top"> | ||
| 32 | <row> | ||
| 33 | <entry>start + 0:</entry> | ||
| 34 | <entry>Y'<subscript>00</subscript></entry> | ||
| 35 | <entry>Cr<subscript>00</subscript></entry> | ||
| 36 | <entry>Y'<subscript>01</subscript></entry> | ||
| 37 | <entry>Cb<subscript>00</subscript></entry> | ||
| 38 | <entry>Y'<subscript>02</subscript></entry> | ||
| 39 | <entry>Cr<subscript>01</subscript></entry> | ||
| 40 | <entry>Y'<subscript>03</subscript></entry> | ||
| 41 | <entry>Cb<subscript>01</subscript></entry> | ||
| 42 | </row> | ||
| 43 | <row> | ||
| 44 | <entry>start + 8:</entry> | ||
| 45 | <entry>Y'<subscript>10</subscript></entry> | ||
| 46 | <entry>Cr<subscript>10</subscript></entry> | ||
| 47 | <entry>Y'<subscript>11</subscript></entry> | ||
| 48 | <entry>Cb<subscript>10</subscript></entry> | ||
| 49 | <entry>Y'<subscript>12</subscript></entry> | ||
| 50 | <entry>Cr<subscript>11</subscript></entry> | ||
| 51 | <entry>Y'<subscript>13</subscript></entry> | ||
| 52 | <entry>Cb<subscript>11</subscript></entry> | ||
| 53 | </row> | ||
| 54 | <row> | ||
| 55 | <entry>start + 16:</entry> | ||
| 56 | <entry>Y'<subscript>20</subscript></entry> | ||
| 57 | <entry>Cr<subscript>20</subscript></entry> | ||
| 58 | <entry>Y'<subscript>21</subscript></entry> | ||
| 59 | <entry>Cb<subscript>20</subscript></entry> | ||
| 60 | <entry>Y'<subscript>22</subscript></entry> | ||
| 61 | <entry>Cr<subscript>21</subscript></entry> | ||
| 62 | <entry>Y'<subscript>23</subscript></entry> | ||
| 63 | <entry>Cb<subscript>21</subscript></entry> | ||
| 64 | </row> | ||
| 65 | <row> | ||
| 66 | <entry>start + 24:</entry> | ||
| 67 | <entry>Y'<subscript>30</subscript></entry> | ||
| 68 | <entry>Cr<subscript>30</subscript></entry> | ||
| 69 | <entry>Y'<subscript>31</subscript></entry> | ||
| 70 | <entry>Cb<subscript>30</subscript></entry> | ||
| 71 | <entry>Y'<subscript>32</subscript></entry> | ||
| 72 | <entry>Cr<subscript>31</subscript></entry> | ||
| 73 | <entry>Y'<subscript>33</subscript></entry> | ||
| 74 | <entry>Cb<subscript>31</subscript></entry> | ||
| 75 | </row> | ||
| 76 | </tbody> | ||
| 77 | </tgroup> | ||
| 78 | </informaltable> | ||
| 79 | </para> | ||
| 80 | </formalpara> | ||
| 81 | |||
| 82 | <formalpara> | ||
| 83 | <title>Color Sample Location.</title> | ||
| 84 | <para> | ||
| 85 | <informaltable frame="none"> | ||
| 86 | <tgroup cols="7" align="center"> | ||
| 87 | <tbody valign="top"> | ||
| 88 | <row> | ||
| 89 | <entry></entry> | ||
| 90 | <entry>0</entry><entry></entry><entry>1</entry><entry></entry> | ||
| 91 | <entry>2</entry><entry></entry><entry>3</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>0</entry> | ||
| 95 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 96 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>1</entry> | ||
| 100 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 101 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>2</entry> | ||
| 105 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 106 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry>3</entry> | ||
| 110 | <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> | ||
| 111 | <entry>Y</entry><entry>C</entry><entry>Y</entry> | ||
| 112 | </row> | ||
| 113 | </tbody> | ||
| 114 | </tgroup> | ||
| 115 | </informaltable> | ||
| 116 | </para> | ||
| 117 | </formalpara> | ||
| 118 | </example> | ||
| 119 | </refsect1> | ||
| 120 | </refentry> | ||
| 121 | |||
| 122 | <!-- | ||
| 123 | Local Variables: | ||
| 124 | mode: sgml | ||
| 125 | sgml-parent-document: "pixfmt.sgml" | ||
| 126 | indent-tabs-mode: nil | ||
| 127 | End: | ||
| 128 | --> | ||
diff --git a/Documentation/DocBook/v4l/pixfmt.xml b/Documentation/DocBook/v4l/pixfmt.xml new file mode 100644 index 000000000000..7d396a3785f5 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt.xml | |||
| @@ -0,0 +1,801 @@ | |||
| 1 | <title>Image Formats</title> | ||
| 2 | |||
| 3 | <para>The V4L2 API was primarily designed for devices exchanging | ||
| 4 | image data with applications. The | ||
| 5 | <structname>v4l2_pix_format</structname> structure defines the format | ||
| 6 | and layout of an image in memory. Image formats are negotiated with | ||
| 7 | the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video | ||
| 8 | capturing and output, for overlay frame buffer formats see also | ||
| 9 | &VIDIOC-G-FBUF;.)</para> | ||
| 10 | |||
| 11 | <table pgwide="1" frame="none" id="v4l2-pix-format"> | ||
| 12 | <title>struct <structname>v4l2_pix_format</structname></title> | ||
| 13 | <tgroup cols="3"> | ||
| 14 | &cs-str; | ||
| 15 | <tbody valign="top"> | ||
| 16 | <row> | ||
| 17 | <entry>__u32</entry> | ||
| 18 | <entry><structfield>width</structfield></entry> | ||
| 19 | <entry>Image width in pixels.</entry> | ||
| 20 | </row> | ||
| 21 | <row> | ||
| 22 | <entry>__u32</entry> | ||
| 23 | <entry><structfield>height</structfield></entry> | ||
| 24 | <entry>Image height in pixels.</entry> | ||
| 25 | </row> | ||
| 26 | <row> | ||
| 27 | <entry spanname="hspan">Applications set these fields to | ||
| 28 | request an image size, drivers return the closest possible values. In | ||
| 29 | case of planar formats the <structfield>width</structfield> and | ||
| 30 | <structfield>height</structfield> applies to the largest plane. To | ||
| 31 | avoid ambiguities drivers must return values rounded up to a multiple | ||
| 32 | of the scale factor of any smaller planes. For example when the image | ||
| 33 | format is YUV 4:2:0, <structfield>width</structfield> and | ||
| 34 | <structfield>height</structfield> must be multiples of two.</entry> | ||
| 35 | </row> | ||
| 36 | <row> | ||
| 37 | <entry>__u32</entry> | ||
| 38 | <entry><structfield>pixelformat</structfield></entry> | ||
| 39 | <entry>The pixel format or type of compression, set by the | ||
| 40 | application. This is a little endian <link | ||
| 41 | linkend="v4l2-fourcc">four character code</link>. V4L2 defines | ||
| 42 | standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref | ||
| 43 | linkend="yuv-formats" />, and reserved codes in <xref | ||
| 44 | linkend="reserved-formats" /></entry> | ||
| 45 | </row> | ||
| 46 | <row> | ||
| 47 | <entry>&v4l2-field;</entry> | ||
| 48 | <entry><structfield>field</structfield></entry> | ||
| 49 | <entry>Video images are typically interlaced. Applications | ||
| 50 | can request to capture or output only the top or bottom field, or both | ||
| 51 | fields interlaced or sequentially stored in one buffer or alternating | ||
| 52 | in separate buffers. Drivers return the actual field order selected. | ||
| 53 | For details see <xref linkend="field-order" />.</entry> | ||
| 54 | </row> | ||
| 55 | <row> | ||
| 56 | <entry>__u32</entry> | ||
| 57 | <entry><structfield>bytesperline</structfield></entry> | ||
| 58 | <entry>Distance in bytes between the leftmost pixels in two | ||
| 59 | adjacent lines.</entry> | ||
| 60 | </row> | ||
| 61 | <row> | ||
| 62 | <entry spanname="hspan"><para>Both applications and drivers | ||
| 63 | can set this field to request padding bytes at the end of each line. | ||
| 64 | Drivers however may ignore the value requested by the application, | ||
| 65 | returning <structfield>width</structfield> times bytes per pixel or a | ||
| 66 | larger value required by the hardware. That implies applications can | ||
| 67 | just set this field to zero to get a reasonable | ||
| 68 | default.</para><para>Video hardware may access padding bytes, | ||
| 69 | therefore they must reside in accessible memory. Consider cases where | ||
| 70 | padding bytes after the last line of an image cross a system page | ||
| 71 | boundary. Input devices may write padding bytes, the value is | ||
| 72 | undefined. Output devices ignore the contents of padding | ||
| 73 | bytes.</para><para>When the image format is planar the | ||
| 74 | <structfield>bytesperline</structfield> value applies to the largest | ||
| 75 | plane and is divided by the same factor as the | ||
| 76 | <structfield>width</structfield> field for any smaller planes. For | ||
| 77 | example the Cb and Cr planes of a YUV 4:2:0 image have half as many | ||
| 78 | padding bytes following each line as the Y plane. To avoid ambiguities | ||
| 79 | drivers must return a <structfield>bytesperline</structfield> value | ||
| 80 | rounded up to a multiple of the scale factor.</para></entry> | ||
| 81 | </row> | ||
| 82 | <row> | ||
| 83 | <entry>__u32</entry> | ||
| 84 | <entry><structfield>sizeimage</structfield></entry> | ||
| 85 | <entry>Size in bytes of the buffer to hold a complete image, | ||
| 86 | set by the driver. Usually this is | ||
| 87 | <structfield>bytesperline</structfield> times | ||
| 88 | <structfield>height</structfield>. When the image consists of variable | ||
| 89 | length compressed data this is the maximum number of bytes required to | ||
| 90 | hold an image.</entry> | ||
| 91 | </row> | ||
| 92 | <row> | ||
| 93 | <entry>&v4l2-colorspace;</entry> | ||
| 94 | <entry><structfield>colorspace</structfield></entry> | ||
| 95 | <entry>This information supplements the | ||
| 96 | <structfield>pixelformat</structfield> and must be set by the driver, | ||
| 97 | see <xref linkend="colorspaces" />.</entry> | ||
| 98 | </row> | ||
| 99 | <row> | ||
| 100 | <entry>__u32</entry> | ||
| 101 | <entry><structfield>priv</structfield></entry> | ||
| 102 | <entry>Reserved for custom (driver defined) additional | ||
| 103 | information about formats. When not used drivers and applications must | ||
| 104 | set this field to zero.</entry> | ||
| 105 | </row> | ||
| 106 | </tbody> | ||
| 107 | </tgroup> | ||
| 108 | </table> | ||
| 109 | |||
| 110 | <section> | ||
| 111 | <title>Standard Image Formats</title> | ||
| 112 | |||
| 113 | <para>In order to exchange images between drivers and | ||
| 114 | applications, it is necessary to have standard image data formats | ||
| 115 | which both sides will interpret the same way. V4L2 includes several | ||
| 116 | such formats, and this section is intended to be an unambiguous | ||
| 117 | specification of the standard image data formats in V4L2.</para> | ||
| 118 | |||
| 119 | <para>V4L2 drivers are not limited to these formats, however. | ||
| 120 | Driver-specific formats are possible. In that case the application may | ||
| 121 | depend on a codec to convert images to one of the standard formats | ||
| 122 | when needed. But the data can still be stored and retrieved in the | ||
| 123 | proprietary format. For example, a device may support a proprietary | ||
| 124 | compressed format. Applications can still capture and save the data in | ||
| 125 | the compressed format, saving much disk space, and later use a codec | ||
| 126 | to convert the images to the X Windows screen format when the video is | ||
| 127 | to be displayed.</para> | ||
| 128 | |||
| 129 | <para>Even so, ultimately, some standard formats are needed, so | ||
| 130 | the V4L2 specification would not be complete without well-defined | ||
| 131 | standard formats.</para> | ||
| 132 | |||
| 133 | <para>The V4L2 standard formats are mainly uncompressed formats. The | ||
| 134 | pixels are always arranged in memory from left to right, and from top | ||
| 135 | to bottom. The first byte of data in the image buffer is always for | ||
| 136 | the leftmost pixel of the topmost row. Following that is the pixel | ||
| 137 | immediately to its right, and so on until the end of the top row of | ||
| 138 | pixels. Following the rightmost pixel of the row there may be zero or | ||
| 139 | more bytes of padding to guarantee that each row of pixel data has a | ||
| 140 | certain alignment. Following the pad bytes, if any, is data for the | ||
| 141 | leftmost pixel of the second row from the top, and so on. The last row | ||
| 142 | has just as many pad bytes after it as the other rows.</para> | ||
| 143 | |||
| 144 | <para>In V4L2 each format has an identifier which looks like | ||
| 145 | <constant>PIX_FMT_XXX</constant>, defined in the <link | ||
| 146 | linkend="videodev">videodev.h</link> header file. These identifiers | ||
| 147 | represent <link linkend="v4l2-fourcc">four character codes</link> | ||
| 148 | which are also listed below, however they are not the same as those | ||
| 149 | used in the Windows world.</para> | ||
| 150 | </section> | ||
| 151 | |||
| 152 | <section id="colorspaces"> | ||
| 153 | <title>Colorspaces</title> | ||
| 154 | |||
| 155 | <para>[intro]</para> | ||
| 156 | |||
| 157 | <!-- See proposal by Billy Biggs, video4linux-list@redhat.com | ||
| 158 | on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and | ||
| 159 | http://vektor.theorem.ca/graphics/ycbcr/ and | ||
| 160 | http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html --> | ||
| 161 | |||
| 162 | <para> | ||
| 163 | <variablelist> | ||
| 164 | <varlistentry> | ||
| 165 | <term>Gamma Correction</term> | ||
| 166 | <listitem> | ||
| 167 | <para>[to do]</para> | ||
| 168 | <para>E'<subscript>R</subscript> = f(R)</para> | ||
| 169 | <para>E'<subscript>G</subscript> = f(G)</para> | ||
| 170 | <para>E'<subscript>B</subscript> = f(B)</para> | ||
| 171 | </listitem> | ||
| 172 | </varlistentry> | ||
| 173 | <varlistentry> | ||
| 174 | <term>Construction of luminance and color-difference | ||
| 175 | signals</term> | ||
| 176 | <listitem> | ||
| 177 | <para>[to do]</para> | ||
| 178 | <para>E'<subscript>Y</subscript> = | ||
| 179 | Coeff<subscript>R</subscript> E'<subscript>R</subscript> | ||
| 180 | + Coeff<subscript>G</subscript> E'<subscript>G</subscript> | ||
| 181 | + Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> | ||
| 182 | <para>(E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = E'<subscript>R</subscript> | ||
| 183 | - Coeff<subscript>R</subscript> E'<subscript>R</subscript> | ||
| 184 | - Coeff<subscript>G</subscript> E'<subscript>G</subscript> | ||
| 185 | - Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> | ||
| 186 | <para>(E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = E'<subscript>B</subscript> | ||
| 187 | - Coeff<subscript>R</subscript> E'<subscript>R</subscript> | ||
| 188 | - Coeff<subscript>G</subscript> E'<subscript>G</subscript> | ||
| 189 | - Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> | ||
| 190 | </listitem> | ||
| 191 | </varlistentry> | ||
| 192 | <varlistentry> | ||
| 193 | <term>Re-normalized color-difference signals</term> | ||
| 194 | <listitem> | ||
| 195 | <para>The color-difference signals are scaled back to unity | ||
| 196 | range [-0.5;+0.5]:</para> | ||
| 197 | <para>K<subscript>B</subscript> = 0.5 / (1 - Coeff<subscript>B</subscript>)</para> | ||
| 198 | <para>K<subscript>R</subscript> = 0.5 / (1 - Coeff<subscript>R</subscript>)</para> | ||
| 199 | <para>P<subscript>B</subscript> = | ||
| 200 | K<subscript>B</subscript> (E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = | ||
| 201 | 0.5 (Coeff<subscript>R</subscript> / Coeff<subscript>B</subscript>) E'<subscript>R</subscript> | ||
| 202 | + 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>B</subscript>) E'<subscript>G</subscript> | ||
| 203 | + 0.5 E'<subscript>B</subscript></para> | ||
| 204 | <para>P<subscript>R</subscript> = | ||
| 205 | K<subscript>R</subscript> (E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = | ||
| 206 | 0.5 E'<subscript>R</subscript> | ||
| 207 | + 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>R</subscript>) E'<subscript>G</subscript> | ||
| 208 | + 0.5 (Coeff<subscript>B</subscript> / Coeff<subscript>R</subscript>) E'<subscript>B</subscript></para> | ||
| 209 | </listitem> | ||
| 210 | </varlistentry> | ||
| 211 | <varlistentry> | ||
| 212 | <term>Quantization</term> | ||
| 213 | <listitem> | ||
| 214 | <para>[to do]</para> | ||
| 215 | <para>Y' = (Lum. Levels - 1) · E'<subscript>Y</subscript> + Lum. Offset</para> | ||
| 216 | <para>C<subscript>B</subscript> = (Chrom. Levels - 1) | ||
| 217 | · P<subscript>B</subscript> + Chrom. Offset</para> | ||
| 218 | <para>C<subscript>R</subscript> = (Chrom. Levels - 1) | ||
| 219 | · P<subscript>R</subscript> + Chrom. Offset</para> | ||
| 220 | <para>Rounding to the nearest integer and clamping to the range | ||
| 221 | [0;255] finally yields the digital color components Y'CbCr | ||
| 222 | stored in YUV images.</para> | ||
| 223 | </listitem> | ||
| 224 | </varlistentry> | ||
| 225 | </variablelist> | ||
| 226 | </para> | ||
| 227 | |||
| 228 | <example> | ||
| 229 | <title>ITU-R Rec. BT.601 color conversion</title> | ||
| 230 | |||
| 231 | <para>Forward Transformation</para> | ||
| 232 | |||
| 233 | <programlisting> | ||
| 234 | int ER, EG, EB; /* gamma corrected RGB input [0;255] */ | ||
| 235 | int Y1, Cb, Cr; /* output [0;255] */ | ||
| 236 | |||
| 237 | double r, g, b; /* temporaries */ | ||
| 238 | double y1, pb, pr; | ||
| 239 | |||
| 240 | int | ||
| 241 | clamp (double x) | ||
| 242 | { | ||
| 243 | int r = x; /* round to nearest */ | ||
| 244 | |||
| 245 | if (r < 0) return 0; | ||
| 246 | else if (r > 255) return 255; | ||
| 247 | else return r; | ||
| 248 | } | ||
| 249 | |||
| 250 | r = ER / 255.0; | ||
| 251 | g = EG / 255.0; | ||
| 252 | b = EB / 255.0; | ||
| 253 | |||
| 254 | y1 = 0.299 * r + 0.587 * g + 0.114 * b; | ||
| 255 | pb = -0.169 * r - 0.331 * g + 0.5 * b; | ||
| 256 | pr = 0.5 * r - 0.419 * g - 0.081 * b; | ||
| 257 | |||
| 258 | Y1 = clamp (219 * y1 + 16); | ||
| 259 | Cb = clamp (224 * pb + 128); | ||
| 260 | Cr = clamp (224 * pr + 128); | ||
| 261 | |||
| 262 | /* or shorter */ | ||
| 263 | |||
| 264 | y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB; | ||
| 265 | |||
| 266 | Y1 = clamp ( (219 / 255.0) * y1 + 16); | ||
| 267 | Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128); | ||
| 268 | Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128); | ||
| 269 | </programlisting> | ||
| 270 | |||
| 271 | <para>Inverse Transformation</para> | ||
| 272 | |||
| 273 | <programlisting> | ||
| 274 | int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */ | ||
| 275 | int ER, EG, EB; /* output [0;255] */ | ||
| 276 | |||
| 277 | double r, g, b; /* temporaries */ | ||
| 278 | double y1, pb, pr; | ||
| 279 | |||
| 280 | int | ||
| 281 | clamp (double x) | ||
| 282 | { | ||
| 283 | int r = x; /* round to nearest */ | ||
| 284 | |||
| 285 | if (r < 0) return 0; | ||
| 286 | else if (r > 255) return 255; | ||
| 287 | else return r; | ||
| 288 | } | ||
| 289 | |||
| 290 | y1 = (255 / 219.0) * (Y1 - 16); | ||
| 291 | pb = (255 / 224.0) * (Cb - 128); | ||
| 292 | pr = (255 / 224.0) * (Cr - 128); | ||
| 293 | |||
| 294 | r = 1.0 * y1 + 0 * pb + 1.402 * pr; | ||
| 295 | g = 1.0 * y1 - 0.344 * pb - 0.714 * pr; | ||
| 296 | b = 1.0 * y1 + 1.772 * pb + 0 * pr; | ||
| 297 | |||
| 298 | ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */ | ||
| 299 | EG = clamp (g * 255); | ||
| 300 | EB = clamp (b * 255); | ||
| 301 | </programlisting> | ||
| 302 | </example> | ||
| 303 | |||
| 304 | <table pgwide="1" id="v4l2-colorspace" orient="land"> | ||
| 305 | <title>enum v4l2_colorspace</title> | ||
| 306 | <tgroup cols="11" align="center"> | ||
| 307 | <colspec align="left" /> | ||
| 308 | <colspec align="center" /> | ||
| 309 | <colspec align="left" /> | ||
| 310 | <colspec colname="cr" /> | ||
| 311 | <colspec colname="cg" /> | ||
| 312 | <colspec colname="cb" /> | ||
| 313 | <colspec colname="wp" /> | ||
| 314 | <colspec colname="gc" /> | ||
| 315 | <colspec colname="lum" /> | ||
| 316 | <colspec colname="qy" /> | ||
| 317 | <colspec colname="qc" /> | ||
| 318 | <spanspec namest="cr" nameend="cb" spanname="chrom" /> | ||
| 319 | <spanspec namest="qy" nameend="qc" spanname="quant" /> | ||
| 320 | <spanspec namest="lum" nameend="qc" spanname="spam" /> | ||
| 321 | <thead> | ||
| 322 | <row> | ||
| 323 | <entry morerows="1">Identifier</entry> | ||
| 324 | <entry morerows="1">Value</entry> | ||
| 325 | <entry morerows="1">Description</entry> | ||
| 326 | <entry spanname="chrom">Chromaticities<footnote> | ||
| 327 | <para>The coordinates of the color primaries are | ||
| 328 | given in the CIE system (1931)</para> | ||
| 329 | </footnote></entry> | ||
| 330 | <entry morerows="1">White Point</entry> | ||
| 331 | <entry morerows="1">Gamma Correction</entry> | ||
| 332 | <entry morerows="1">Luminance E'<subscript>Y</subscript></entry> | ||
| 333 | <entry spanname="quant">Quantization</entry> | ||
| 334 | </row> | ||
| 335 | <row> | ||
| 336 | <entry>Red</entry> | ||
| 337 | <entry>Green</entry> | ||
| 338 | <entry>Blue</entry> | ||
| 339 | <entry>Y'</entry> | ||
| 340 | <entry>Cb, Cr</entry> | ||
| 341 | </row> | ||
| 342 | </thead> | ||
| 343 | <tbody valign="top"> | ||
| 344 | <row> | ||
| 345 | <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> | ||
| 346 | <entry>1</entry> | ||
| 347 | <entry>NTSC/PAL according to <xref linkend="smpte170m" />, | ||
| 348 | <xref linkend="itu601" /></entry> | ||
| 349 | <entry>x = 0.630, y = 0.340</entry> | ||
| 350 | <entry>x = 0.310, y = 0.595</entry> | ||
| 351 | <entry>x = 0.155, y = 0.070</entry> | ||
| 352 | <entry>x = 0.3127, y = 0.3290, | ||
| 353 | Illuminant D<subscript>65</subscript></entry> | ||
| 354 | <entry>E' = 4.5 I for I ≤0.018, | ||
| 355 | 1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> | ||
| 356 | <entry>0.299 E'<subscript>R</subscript> | ||
| 357 | + 0.587 E'<subscript>G</subscript> | ||
| 358 | + 0.114 E'<subscript>B</subscript></entry> | ||
| 359 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | ||
| 360 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | ||
| 361 | </row> | ||
| 362 | <row> | ||
| 363 | <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> | ||
| 364 | <entry>2</entry> | ||
| 365 | <entry>1125-Line (US) HDTV, see <xref | ||
| 366 | linkend="smpte240m" /></entry> | ||
| 367 | <entry>x = 0.630, y = 0.340</entry> | ||
| 368 | <entry>x = 0.310, y = 0.595</entry> | ||
| 369 | <entry>x = 0.155, y = 0.070</entry> | ||
| 370 | <entry>x = 0.3127, y = 0.3290, | ||
| 371 | Illuminant D<subscript>65</subscript></entry> | ||
| 372 | <entry>E' = 4 I for I ≤0.0228, | ||
| 373 | 1.1115 I<superscript>0.45</superscript> - 0.1115 for 0.0228 < I</entry> | ||
| 374 | <entry>0.212 E'<subscript>R</subscript> | ||
| 375 | + 0.701 E'<subscript>G</subscript> | ||
| 376 | + 0.087 E'<subscript>B</subscript></entry> | ||
| 377 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | ||
| 378 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | ||
| 379 | </row> | ||
| 380 | <row> | ||
| 381 | <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> | ||
| 382 | <entry>3</entry> | ||
| 383 | <entry>HDTV and modern devices, see <xref | ||
| 384 | linkend="itu709" /></entry> | ||
| 385 | <entry>x = 0.640, y = 0.330</entry> | ||
| 386 | <entry>x = 0.300, y = 0.600</entry> | ||
| 387 | <entry>x = 0.150, y = 0.060</entry> | ||
| 388 | <entry>x = 0.3127, y = 0.3290, | ||
| 389 | Illuminant D<subscript>65</subscript></entry> | ||
| 390 | <entry>E' = 4.5 I for I ≤0.018, | ||
| 391 | 1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> | ||
| 392 | <entry>0.2125 E'<subscript>R</subscript> | ||
| 393 | + 0.7154 E'<subscript>G</subscript> | ||
| 394 | + 0.0721 E'<subscript>B</subscript></entry> | ||
| 395 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | ||
| 396 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | ||
| 397 | </row> | ||
| 398 | <row> | ||
| 399 | <entry><constant>V4L2_COLORSPACE_BT878</constant></entry> | ||
| 400 | <entry>4</entry> | ||
| 401 | <entry>Broken Bt878 extents<footnote> | ||
| 402 | <para>The ubiquitous Bt878 video capture chip | ||
| 403 | quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range | ||
| 404 | of Y' = 16 … 253, unlike Rec. 601 Y' = 16 … | ||
| 405 | 235. This is not a typo in the Bt878 documentation, it has been | ||
| 406 | implemented in silicon. The chroma extents are unclear.</para> | ||
| 407 | </footnote>, <xref linkend="itu601" /></entry> | ||
| 408 | <entry>?</entry> | ||
| 409 | <entry>?</entry> | ||
| 410 | <entry>?</entry> | ||
| 411 | <entry>?</entry> | ||
| 412 | <entry>?</entry> | ||
| 413 | <entry>0.299 E'<subscript>R</subscript> | ||
| 414 | + 0.587 E'<subscript>G</subscript> | ||
| 415 | + 0.114 E'<subscript>B</subscript></entry> | ||
| 416 | <entry><emphasis>237</emphasis> E'<subscript>Y</subscript> + 16</entry> | ||
| 417 | <entry>224 P<subscript>B,R</subscript> + 128 (probably)</entry> | ||
| 418 | </row> | ||
| 419 | <row> | ||
| 420 | <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry> | ||
| 421 | <entry>5</entry> | ||
| 422 | <entry>M/NTSC<footnote> | ||
| 423 | <para>No identifier exists for M/PAL which uses | ||
| 424 | the chromaticities of M/NTSC, the remaining parameters are equal to B and | ||
| 425 | G/PAL.</para> | ||
| 426 | </footnote> according to <xref linkend="itu470" />, <xref | ||
| 427 | linkend="itu601" /></entry> | ||
| 428 | <entry>x = 0.67, y = 0.33</entry> | ||
| 429 | <entry>x = 0.21, y = 0.71</entry> | ||
| 430 | <entry>x = 0.14, y = 0.08</entry> | ||
| 431 | <entry>x = 0.310, y = 0.316, Illuminant C</entry> | ||
| 432 | <entry>?</entry> | ||
| 433 | <entry>0.299 E'<subscript>R</subscript> | ||
| 434 | + 0.587 E'<subscript>G</subscript> | ||
| 435 | + 0.114 E'<subscript>B</subscript></entry> | ||
| 436 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | ||
| 437 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | ||
| 438 | </row> | ||
| 439 | <row> | ||
| 440 | <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry> | ||
| 441 | <entry>6</entry> | ||
| 442 | <entry>625-line PAL and SECAM systems according to <xref | ||
| 443 | linkend="itu470" />, <xref linkend="itu601" /></entry> | ||
| 444 | <entry>x = 0.64, y = 0.33</entry> | ||
| 445 | <entry>x = 0.29, y = 0.60</entry> | ||
| 446 | <entry>x = 0.15, y = 0.06</entry> | ||
| 447 | <entry>x = 0.313, y = 0.329, | ||
| 448 | Illuminant D<subscript>65</subscript></entry> | ||
| 449 | <entry>?</entry> | ||
| 450 | <entry>0.299 E'<subscript>R</subscript> | ||
| 451 | + 0.587 E'<subscript>G</subscript> | ||
| 452 | + 0.114 E'<subscript>B</subscript></entry> | ||
| 453 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | ||
| 454 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | ||
| 455 | </row> | ||
| 456 | <row> | ||
| 457 | <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> | ||
| 458 | <entry>7</entry> | ||
| 459 | <entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry> | ||
| 460 | <entry>?</entry> | ||
| 461 | <entry>?</entry> | ||
| 462 | <entry>?</entry> | ||
| 463 | <entry>?</entry> | ||
| 464 | <entry>?</entry> | ||
| 465 | <entry>0.299 E'<subscript>R</subscript> | ||
| 466 | + 0.587 E'<subscript>G</subscript> | ||
| 467 | + 0.114 E'<subscript>B</subscript></entry> | ||
| 468 | <entry>256 E'<subscript>Y</subscript> + 16<footnote> | ||
| 469 | <para>Note JFIF quantizes | ||
| 470 | Y'P<subscript>B</subscript>P<subscript>R</subscript> in range [0;+1] and | ||
| 471 | [-0.5;+0.5] to <emphasis>257</emphasis> levels, however Y'CbCr signals | ||
| 472 | are still clamped to [0;255].</para> | ||
| 473 | </footnote></entry> | ||
| 474 | <entry>256 P<subscript>B,R</subscript> + 128</entry> | ||
| 475 | </row> | ||
| 476 | <row> | ||
| 477 | <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> | ||
| 478 | <entry>8</entry> | ||
| 479 | <entry>[?]</entry> | ||
| 480 | <entry>x = 0.640, y = 0.330</entry> | ||
| 481 | <entry>x = 0.300, y = 0.600</entry> | ||
| 482 | <entry>x = 0.150, y = 0.060</entry> | ||
| 483 | <entry>x = 0.3127, y = 0.3290, | ||
| 484 | Illuminant D<subscript>65</subscript></entry> | ||
| 485 | <entry>E' = 4.5 I for I ≤0.018, | ||
| 486 | 1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> | ||
| 487 | <entry spanname="spam">n/a</entry> | ||
| 488 | </row> | ||
| 489 | </tbody> | ||
| 490 | </tgroup> | ||
| 491 | </table> | ||
| 492 | </section> | ||
| 493 | |||
| 494 | <section id="pixfmt-indexed"> | ||
| 495 | <title>Indexed Format</title> | ||
| 496 | |||
| 497 | <para>In this format each pixel is represented by an 8 bit index | ||
| 498 | into a 256 entry ARGB palette. It is intended for <link | ||
| 499 | linkend="osd">Video Output Overlays</link> only. There are no ioctls to | ||
| 500 | access the palette, this must be done with ioctls of the Linux framebuffer API.</para> | ||
| 501 | |||
| 502 | <table pgwide="0" frame="none"> | ||
| 503 | <title>Indexed Image Format</title> | ||
| 504 | <tgroup cols="37" align="center"> | ||
| 505 | <colspec colname="id" align="left" /> | ||
| 506 | <colspec colname="fourcc" /> | ||
| 507 | <colspec colname="bit" /> | ||
| 508 | |||
| 509 | <colspec colnum="4" colname="b07" align="center" /> | ||
| 510 | <colspec colnum="5" colname="b06" align="center" /> | ||
| 511 | <colspec colnum="6" colname="b05" align="center" /> | ||
| 512 | <colspec colnum="7" colname="b04" align="center" /> | ||
| 513 | <colspec colnum="8" colname="b03" align="center" /> | ||
| 514 | <colspec colnum="9" colname="b02" align="center" /> | ||
| 515 | <colspec colnum="10" colname="b01" align="center" /> | ||
| 516 | <colspec colnum="11" colname="b00" align="center" /> | ||
| 517 | |||
| 518 | <spanspec namest="b07" nameend="b00" spanname="b0" /> | ||
| 519 | <spanspec namest="b17" nameend="b10" spanname="b1" /> | ||
| 520 | <spanspec namest="b27" nameend="b20" spanname="b2" /> | ||
| 521 | <spanspec namest="b37" nameend="b30" spanname="b3" /> | ||
| 522 | <thead> | ||
| 523 | <row> | ||
| 524 | <entry>Identifier</entry> | ||
| 525 | <entry>Code</entry> | ||
| 526 | <entry> </entry> | ||
| 527 | <entry spanname="b0">Byte 0</entry> | ||
| 528 | </row> | ||
| 529 | <row> | ||
| 530 | <entry> </entry> | ||
| 531 | <entry> </entry> | ||
| 532 | <entry>Bit</entry> | ||
| 533 | <entry>7</entry> | ||
| 534 | <entry>6</entry> | ||
| 535 | <entry>5</entry> | ||
| 536 | <entry>4</entry> | ||
| 537 | <entry>3</entry> | ||
| 538 | <entry>2</entry> | ||
| 539 | <entry>1</entry> | ||
| 540 | <entry>0</entry> | ||
| 541 | </row> | ||
| 542 | </thead> | ||
| 543 | <tbody valign="top"> | ||
| 544 | <row id="V4L2-PIX-FMT-PAL8"> | ||
| 545 | <entry><constant>V4L2_PIX_FMT_PAL8</constant></entry> | ||
| 546 | <entry>'PAL8'</entry> | ||
| 547 | <entry></entry> | ||
| 548 | <entry>i<subscript>7</subscript></entry> | ||
| 549 | <entry>i<subscript>6</subscript></entry> | ||
| 550 | <entry>i<subscript>5</subscript></entry> | ||
| 551 | <entry>i<subscript>4</subscript></entry> | ||
| 552 | <entry>i<subscript>3</subscript></entry> | ||
| 553 | <entry>i<subscript>2</subscript></entry> | ||
| 554 | <entry>i<subscript>1</subscript></entry> | ||
| 555 | <entry>i<subscript>0</subscript></entry> | ||
| 556 | </row> | ||
| 557 | </tbody> | ||
| 558 | </tgroup> | ||
| 559 | </table> | ||
| 560 | </section> | ||
| 561 | |||
| 562 | <section id="pixfmt-rgb"> | ||
| 563 | <title>RGB Formats</title> | ||
| 564 | |||
| 565 | &sub-packed-rgb; | ||
| 566 | &sub-sbggr8; | ||
| 567 | &sub-sgbrg8; | ||
| 568 | &sub-sgrbg8; | ||
| 569 | &sub-sbggr16; | ||
| 570 | </section> | ||
| 571 | |||
| 572 | <section id="yuv-formats"> | ||
| 573 | <title>YUV Formats</title> | ||
| 574 | |||
| 575 | <para>YUV is the format native to TV broadcast and composite video | ||
| 576 | signals. It separates the brightness information (Y) from the color | ||
| 577 | information (U and V or Cb and Cr). The color information consists of | ||
| 578 | red and blue <emphasis>color difference</emphasis> signals, this way | ||
| 579 | the green component can be reconstructed by subtracting from the | ||
| 580 | brightness component. See <xref linkend="colorspaces" /> for conversion | ||
| 581 | examples. YUV was chosen because early television would only transmit | ||
| 582 | brightness information. To add color in a way compatible with existing | ||
| 583 | receivers a new signal carrier was added to transmit the color | ||
| 584 | difference signals. Secondary in the YUV format the U and V components | ||
| 585 | usually have lower resolution than the Y component. This is an analog | ||
| 586 | video compression technique taking advantage of a property of the | ||
| 587 | human visual system, being more sensitive to brightness | ||
| 588 | information.</para> | ||
| 589 | |||
| 590 | &sub-packed-yuv; | ||
| 591 | &sub-grey; | ||
| 592 | &sub-y16; | ||
| 593 | &sub-yuyv; | ||
| 594 | &sub-uyvy; | ||
| 595 | &sub-yvyu; | ||
| 596 | &sub-vyuy; | ||
| 597 | &sub-y41p; | ||
| 598 | &sub-yuv420; | ||
| 599 | &sub-yuv410; | ||
| 600 | &sub-yuv422p; | ||
| 601 | &sub-yuv411p; | ||
| 602 | &sub-nv12; | ||
| 603 | &sub-nv16; | ||
| 604 | </section> | ||
| 605 | |||
| 606 | <section> | ||
| 607 | <title>Compressed Formats</title> | ||
| 608 | |||
| 609 | <table pgwide="1" frame="none" id="compressed-formats"> | ||
| 610 | <title>Compressed Image Formats</title> | ||
| 611 | <tgroup cols="3" align="left"> | ||
| 612 | &cs-def; | ||
| 613 | <thead> | ||
| 614 | <row> | ||
| 615 | <entry>Identifier</entry> | ||
| 616 | <entry>Code</entry> | ||
| 617 | <entry>Details</entry> | ||
| 618 | </row> | ||
| 619 | </thead> | ||
| 620 | <tbody valign="top"> | ||
| 621 | <row id="V4L2-PIX-FMT-JPEG"> | ||
| 622 | <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry> | ||
| 623 | <entry>'JPEG'</entry> | ||
| 624 | <entry>TBD. See also &VIDIOC-G-JPEGCOMP;, | ||
| 625 | &VIDIOC-S-JPEGCOMP;.</entry> | ||
| 626 | </row> | ||
| 627 | <row id="V4L2-PIX-FMT-MPEG"> | ||
| 628 | <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry> | ||
| 629 | <entry>'MPEG'</entry> | ||
| 630 | <entry>MPEG stream. The actual format is determined by | ||
| 631 | extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see | ||
| 632 | <xref linkend="mpeg-control-id" />.</entry> | ||
| 633 | </row> | ||
| 634 | </tbody> | ||
| 635 | </tgroup> | ||
| 636 | </table> | ||
| 637 | </section> | ||
| 638 | |||
| 639 | <section id="pixfmt-reserved"> | ||
| 640 | <title>Reserved Format Identifiers</title> | ||
| 641 | |||
| 642 | <para>These formats are not defined by this specification, they | ||
| 643 | are just listed for reference and to avoid naming conflicts. If you | ||
| 644 | want to register your own format, send an e-mail to the linux-media mailing | ||
| 645 | list &v4l-ml; for inclusion in the <filename>videodev2.h</filename> | ||
| 646 | file. If you want to share your format with other developers add a | ||
| 647 | link to your documentation and send a copy to the linux-media mailing list | ||
| 648 | for inclusion in this section. If you think your format should be listed | ||
| 649 | in a standard format section please make a proposal on the linux-media mailing | ||
| 650 | list.</para> | ||
| 651 | |||
| 652 | <table pgwide="1" frame="none" id="reserved-formats"> | ||
| 653 | <title>Reserved Image Formats</title> | ||
| 654 | <tgroup cols="3" align="left"> | ||
| 655 | &cs-def; | ||
| 656 | <thead> | ||
| 657 | <row> | ||
| 658 | <entry>Identifier</entry> | ||
| 659 | <entry>Code</entry> | ||
| 660 | <entry>Details</entry> | ||
| 661 | </row> | ||
| 662 | </thead> | ||
| 663 | <tbody valign="top"> | ||
| 664 | <row id="V4L2-PIX-FMT-DV"> | ||
| 665 | <entry><constant>V4L2_PIX_FMT_DV</constant></entry> | ||
| 666 | <entry>'dvsd'</entry> | ||
| 667 | <entry>unknown</entry> | ||
| 668 | </row> | ||
| 669 | <row id="V4L2-PIX-FMT-ET61X251"> | ||
| 670 | <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry> | ||
| 671 | <entry>'E625'</entry> | ||
| 672 | <entry>Compressed format of the ET61X251 driver.</entry> | ||
| 673 | </row> | ||
| 674 | <row id="V4L2-PIX-FMT-HI240"> | ||
| 675 | <entry><constant>V4L2_PIX_FMT_HI240</constant></entry> | ||
| 676 | <entry>'HI24'</entry> | ||
| 677 | <entry><para>8 bit RGB format used by the BTTV driver.</para></entry> | ||
| 678 | </row> | ||
| 679 | <row id="V4L2-PIX-FMT-HM12"> | ||
| 680 | <entry><constant>V4L2_PIX_FMT_HM12</constant></entry> | ||
| 681 | <entry>'HM12'</entry> | ||
| 682 | <entry><para>YUV 4:2:0 format used by the | ||
| 683 | IVTV driver, <ulink url="http://www.ivtvdriver.org/"> | ||
| 684 | http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the | ||
| 685 | kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename> | ||
| 686 | </para></entry> | ||
| 687 | </row> | ||
| 688 | <row id="V4L2-PIX-FMT-SPCA501"> | ||
| 689 | <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry> | ||
| 690 | <entry>'S501'</entry> | ||
| 691 | <entry>YUYV per line used by the gspca driver.</entry> | ||
| 692 | </row> | ||
| 693 | <row id="V4L2-PIX-FMT-SPCA505"> | ||
| 694 | <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry> | ||
| 695 | <entry>'S505'</entry> | ||
| 696 | <entry>YYUV per line used by the gspca driver.</entry> | ||
| 697 | </row> | ||
| 698 | <row id="V4L2-PIX-FMT-SPCA508"> | ||
| 699 | <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry> | ||
| 700 | <entry>'S508'</entry> | ||
| 701 | <entry>YUVY per line used by the gspca driver.</entry> | ||
| 702 | </row> | ||
| 703 | <row id="V4L2-PIX-FMT-SPCA561"> | ||
| 704 | <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry> | ||
| 705 | <entry>'S561'</entry> | ||
| 706 | <entry>Compressed GBRG Bayer format used by the gspca driver.</entry> | ||
| 707 | </row> | ||
| 708 | <row id="V4L2-PIX-FMT-SGRBG10"> | ||
| 709 | <entry><constant>V4L2_PIX_FMT_SGRBG10</constant></entry> | ||
| 710 | <entry>'DA10'</entry> | ||
| 711 | <entry>10 bit raw Bayer, expanded to 16 bits.</entry> | ||
| 712 | </row> | ||
| 713 | <row id="V4L2-PIX-FMT-SGRBG10DPCM8"> | ||
| 714 | <entry><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></entry> | ||
| 715 | <entry>'DB10'</entry> | ||
| 716 | <entry>10 bit raw Bayer DPCM compressed to 8 bits.</entry> | ||
| 717 | </row> | ||
| 718 | <row id="V4L2-PIX-FMT-PAC207"> | ||
| 719 | <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry> | ||
| 720 | <entry>'P207'</entry> | ||
| 721 | <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> | ||
| 722 | </row> | ||
| 723 | <row id="V4L2-PIX-FMT-MR97310A"> | ||
| 724 | <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry> | ||
| 725 | <entry>'M310'</entry> | ||
| 726 | <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> | ||
| 727 | </row> | ||
| 728 | <row id="V4L2-PIX-FMT-OV511"> | ||
| 729 | <entry><constant>V4L2_PIX_FMT_OV511</constant></entry> | ||
| 730 | <entry>'O511'</entry> | ||
| 731 | <entry>OV511 JPEG format used by the gspca driver.</entry> | ||
| 732 | </row> | ||
| 733 | <row id="V4L2-PIX-FMT-OV518"> | ||
| 734 | <entry><constant>V4L2_PIX_FMT_OV518</constant></entry> | ||
| 735 | <entry>'O518'</entry> | ||
| 736 | <entry>OV518 JPEG format used by the gspca driver.</entry> | ||
| 737 | </row> | ||
| 738 | <row id="V4L2-PIX-FMT-PJPG"> | ||
| 739 | <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry> | ||
| 740 | <entry>'PJPG'</entry> | ||
| 741 | <entry>Pixart 73xx JPEG format used by the gspca driver.</entry> | ||
| 742 | </row> | ||
| 743 | <row id="V4L2-PIX-FMT-SQ905C"> | ||
| 744 | <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry> | ||
| 745 | <entry>'905C'</entry> | ||
| 746 | <entry>Compressed RGGB bayer format used by the gspca driver.</entry> | ||
| 747 | </row> | ||
| 748 | <row id="V4L2-PIX-FMT-MJPEG"> | ||
| 749 | <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry> | ||
| 750 | <entry>'MJPG'</entry> | ||
| 751 | <entry>Compressed format used by the Zoran driver</entry> | ||
| 752 | </row> | ||
| 753 | <row id="V4L2-PIX-FMT-PWC1"> | ||
| 754 | <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry> | ||
| 755 | <entry>'PWC1'</entry> | ||
| 756 | <entry>Compressed format of the PWC driver.</entry> | ||
| 757 | </row> | ||
| 758 | <row id="V4L2-PIX-FMT-PWC2"> | ||
| 759 | <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry> | ||
| 760 | <entry>'PWC2'</entry> | ||
| 761 | <entry>Compressed format of the PWC driver.</entry> | ||
| 762 | </row> | ||
| 763 | <row id="V4L2-PIX-FMT-SN9C10X"> | ||
| 764 | <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry> | ||
| 765 | <entry>'S910'</entry> | ||
| 766 | <entry>Compressed format of the SN9C102 driver.</entry> | ||
| 767 | </row> | ||
| 768 | <row id="V4L2-PIX-FMT-SN9C20X-I420"> | ||
| 769 | <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry> | ||
| 770 | <entry>'S920'</entry> | ||
| 771 | <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry> | ||
| 772 | </row> | ||
| 773 | <row id="V4L2-PIX-FMT-WNVA"> | ||
| 774 | <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry> | ||
| 775 | <entry>'WNVA'</entry> | ||
| 776 | <entry><para>Used by the Winnov Videum driver, <ulink | ||
| 777 | url="http://www.thedirks.org/winnov/"> | ||
| 778 | http://www.thedirks.org/winnov/</ulink></para></entry> | ||
| 779 | </row> | ||
| 780 | <row id="V4L2-PIX-FMT-TM6000"> | ||
| 781 | <entry><constant>V4L2_PIX_FMT_TM6000</constant></entry> | ||
| 782 | <entry>'TM60'</entry> | ||
| 783 | <entry><para>Used by Trident tm6000</para></entry> | ||
| 784 | </row> | ||
| 785 | <row id="V4L2-PIX-FMT-YYUV"> | ||
| 786 | <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry> | ||
| 787 | <entry>'YYUV'</entry> | ||
| 788 | <entry>unknown</entry> | ||
| 789 | </row> | ||
| 790 | </tbody> | ||
| 791 | </tgroup> | ||
| 792 | </table> | ||
| 793 | </section> | ||
| 794 | |||
| 795 | <!-- | ||
| 796 | Local Variables: | ||
| 797 | mode: sgml | ||
| 798 | sgml-parent-document: "v4l2.sgml" | ||
| 799 | indent-tabs-mode: nil | ||
| 800 | End: | ||
| 801 | --> | ||
diff --git a/Documentation/DocBook/v4l/remote_controllers.xml b/Documentation/DocBook/v4l/remote_controllers.xml new file mode 100644 index 000000000000..73f5eab091f4 --- /dev/null +++ b/Documentation/DocBook/v4l/remote_controllers.xml | |||
| @@ -0,0 +1,175 @@ | |||
| 1 | <title>Remote Controllers</title> | ||
| 2 | <section id="Remote_controllers_Intro"> | ||
| 3 | <title>Introduction</title> | ||
| 4 | |||
| 5 | <para>Currently, most analog and digital devices have a Infrared input for remote controllers. Each | ||
| 6 | manufacturer has their own type of control. It is not rare for the same manufacturer to ship different | ||
| 7 | types of controls, depending on the device.</para> | ||
| 8 | <para>Unfortunately, for several years, there was no effort to create uniform IR keycodes for | ||
| 9 | different devices. This caused the same IR keyname to be mapped completely differently on | ||
| 10 | different IR devices. This resulted that the same IR keyname to be mapped completely different on | ||
| 11 | different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR.</para> | ||
| 12 | <para>This standard should be used by both V4L/DVB drivers and userspace applications</para> | ||
| 13 | <para>The modules register the remote as keyboard within the linux input layer. This means that the IR key strokes will look like normal keyboard key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event devices (CONFIG_INPUT_EVDEV) it is possible for applications to access the remote via /dev/input/event devices.</para> | ||
| 14 | |||
| 15 | <table pgwide="1" frame="none" id="rc_standard_keymap"> | ||
| 16 | <title>IR default keymapping</title> | ||
| 17 | <tgroup cols="3"> | ||
| 18 | &cs-str; | ||
| 19 | <tbody valign="top"> | ||
| 20 | <row> | ||
| 21 | <entry>Key code</entry> | ||
| 22 | <entry>Meaning</entry> | ||
| 23 | <entry>Key examples on IR</entry> | ||
| 24 | </row> | ||
| 25 | |||
| 26 | <row><entry><emphasis role="bold">Numeric keys</emphasis></entry></row> | ||
| 27 | |||
| 28 | <row><entry><constant>KEY_0</constant></entry><entry>Keyboard digit 0</entry><entry>0</entry></row> | ||
| 29 | <row><entry><constant>KEY_1</constant></entry><entry>Keyboard digit 1</entry><entry>1</entry></row> | ||
| 30 | <row><entry><constant>KEY_2</constant></entry><entry>Keyboard digit 2</entry><entry>2</entry></row> | ||
| 31 | <row><entry><constant>KEY_3</constant></entry><entry>Keyboard digit 3</entry><entry>3</entry></row> | ||
| 32 | <row><entry><constant>KEY_4</constant></entry><entry>Keyboard digit 4</entry><entry>4</entry></row> | ||
| 33 | <row><entry><constant>KEY_5</constant></entry><entry>Keyboard digit 5</entry><entry>5</entry></row> | ||
| 34 | <row><entry><constant>KEY_6</constant></entry><entry>Keyboard digit 6</entry><entry>6</entry></row> | ||
| 35 | <row><entry><constant>KEY_7</constant></entry><entry>Keyboard digit 7</entry><entry>7</entry></row> | ||
| 36 | <row><entry><constant>KEY_8</constant></entry><entry>Keyboard digit 8</entry><entry>8</entry></row> | ||
| 37 | <row><entry><constant>KEY_9</constant></entry><entry>Keyboard digit 9</entry><entry>9</entry></row> | ||
| 38 | |||
| 39 | <row><entry><emphasis role="bold">Movie play control</emphasis></entry></row> | ||
| 40 | |||
| 41 | <row><entry><constant>KEY_FORWARD</constant></entry><entry>Instantly advance in time</entry><entry>>> / FORWARD</entry></row> | ||
| 42 | <row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry><<< / BACK</entry></row> | ||
| 43 | <row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>>>> / FORWARD</entry></row> | ||
| 44 | <row><entry><constant>KEY_REWIND</constant></entry><entry>Play movie back</entry><entry>REWIND / BACKWARD</entry></row> | ||
| 45 | <row><entry><constant>KEY_NEXT</constant></entry><entry>Select next chapter / sub-chapter / interval</entry><entry>NEXT / SKIP</entry></row> | ||
| 46 | <row><entry><constant>KEY_PREVIOUS</constant></entry><entry>Select previous chapter / sub-chapter / interval</entry><entry><< / PREV / PREVIOUS</entry></row> | ||
| 47 | <row><entry><constant>KEY_AGAIN</constant></entry><entry>Repeat the video or a video interval</entry><entry>REPEAT / LOOP / RECALL</entry></row> | ||
| 48 | <row><entry><constant>KEY_PAUSE</constant></entry><entry>Pause sroweam</entry><entry>PAUSE / FREEZE</entry></row> | ||
| 49 | <row><entry><constant>KEY_PLAY</constant></entry><entry>Play movie at the normal timeshift</entry><entry>NORMAL TIMESHIFT / LIVE / ></entry></row> | ||
| 50 | <row><entry><constant>KEY_PLAYPAUSE</constant></entry><entry>Alternate between play and pause</entry><entry>PLAY / PAUSE</entry></row> | ||
| 51 | <row><entry><constant>KEY_STOP</constant></entry><entry>Stop sroweam</entry><entry>STOP</entry></row> | ||
| 52 | <row><entry><constant>KEY_RECORD</constant></entry><entry>Start/stop recording sroweam</entry><entry>CAPTURE / REC / RECORD/PAUSE</entry></row> | ||
| 53 | <row><entry><constant>KEY_CAMERA</constant></entry><entry>Take a picture of the image</entry><entry>CAMERA ICON / CAPTURE / SNAPSHOT</entry></row> | ||
| 54 | <row><entry><constant>KEY_SHUFFLE</constant></entry><entry>Enable shuffle mode</entry><entry>SHUFFLE</entry></row> | ||
| 55 | <row><entry><constant>KEY_TIME</constant></entry><entry>Activate time shift mode</entry><entry>TIME SHIFT</entry></row> | ||
| 56 | <row><entry><constant>KEY_TITLE</constant></entry><entry>Allow changing the chapter</entry><entry>CHAPTER</entry></row> | ||
| 57 | <row><entry><constant>KEY_SUBTITLE</constant></entry><entry>Allow changing the subtitle</entry><entry>SUBTITLE</entry></row> | ||
| 58 | |||
| 59 | <row><entry><emphasis role="bold">Image control</emphasis></entry></row> | ||
| 60 | |||
| 61 | <row><entry><constant>KEY_BRIGHTNESSDOWN</constant></entry><entry>Decrease Brightness</entry><entry>BRIGHTNESS DECREASE</entry></row> | ||
| 62 | <row><entry><constant>KEY_BRIGHTNESSUP</constant></entry><entry>Increase Brightness</entry><entry>BRIGHTNESS INCREASE</entry></row> | ||
| 63 | |||
| 64 | <row><entry><constant>KEY_ANGLE</constant></entry><entry>Switch video camera angle (on videos with more than one angle stored)</entry><entry>ANGLE / SWAP</entry></row> | ||
| 65 | <row><entry><constant>KEY_EPG</constant></entry><entry>Open the Elecrowonic Play Guide (EPG)</entry><entry>EPG / GUIDE</entry></row> | ||
| 66 | <row><entry><constant>KEY_TEXT</constant></entry><entry>Activate/change closed caption mode</entry><entry>CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX</entry></row> | ||
| 67 | |||
| 68 | <row><entry><emphasis role="bold">Audio control</emphasis></entry></row> | ||
| 69 | |||
| 70 | <row><entry><constant>KEY_AUDIO</constant></entry><entry>Change audio source</entry><entry>AUDIO SOURCE / AUDIO / MUSIC</entry></row> | ||
| 71 | <row><entry><constant>KEY_MUTE</constant></entry><entry>Mute/unmute audio</entry><entry>MUTE / DEMUTE / UNMUTE</entry></row> | ||
| 72 | <row><entry><constant>KEY_VOLUMEDOWN</constant></entry><entry>Decrease volume</entry><entry>VOLUME- / VOLUME DOWN</entry></row> | ||
| 73 | <row><entry><constant>KEY_VOLUMEUP</constant></entry><entry>Increase volume</entry><entry>VOLUME+ / VOLUME UP</entry></row> | ||
| 74 | <row><entry><constant>KEY_MODE</constant></entry><entry>Change sound mode</entry><entry>MONO/STEREO</entry></row> | ||
| 75 | <row><entry><constant>KEY_LANGUAGE</constant></entry><entry>Select Language</entry><entry>1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL</entry></row> | ||
| 76 | |||
| 77 | <row><entry><emphasis role="bold">Channel control</emphasis></entry></row> | ||
| 78 | |||
| 79 | <row><entry><constant>KEY_CHANNEL</constant></entry><entry>Go to the next favorite channel</entry><entry>ALT / CHANNEL / CH SURFING / SURF / FAV</entry></row> | ||
| 80 | <row><entry><constant>KEY_CHANNELDOWN</constant></entry><entry>Decrease channel sequencially</entry><entry>CHANNEL - / CHANNEL DOWN / DOWN</entry></row> | ||
| 81 | <row><entry><constant>KEY_CHANNELUP</constant></entry><entry>Increase channel sequencially</entry><entry>CHANNEL + / CHANNEL UP / UP</entry></row> | ||
| 82 | <row><entry><constant>KEY_DIGITS</constant></entry><entry>Use more than one digit for channel</entry><entry>PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit</entry></row> | ||
| 83 | <row><entry><constant>KEY_SEARCH</constant></entry><entry>Start channel autoscan</entry><entry>SCAN / AUTOSCAN</entry></row> | ||
| 84 | |||
| 85 | <row><entry><emphasis role="bold">Colored keys</emphasis></entry></row> | ||
| 86 | |||
| 87 | <row><entry><constant>KEY_BLUE</constant></entry><entry>IR Blue key</entry><entry>BLUE</entry></row> | ||
| 88 | <row><entry><constant>KEY_GREEN</constant></entry><entry>IR Green Key</entry><entry>GREEN</entry></row> | ||
| 89 | <row><entry><constant>KEY_RED</constant></entry><entry>IR Red key</entry><entry>RED</entry></row> | ||
| 90 | <row><entry><constant>KEY_YELLOW</constant></entry><entry>IR Yellow key</entry><entry> YELLOW</entry></row> | ||
| 91 | |||
| 92 | <row><entry><emphasis role="bold">Media selection</emphasis></entry></row> | ||
| 93 | |||
| 94 | <row><entry><constant>KEY_CD</constant></entry><entry>Change input source to Compact Disc</entry><entry>CD</entry></row> | ||
| 95 | <row><entry><constant>KEY_DVD</constant></entry><entry>Change input to DVD</entry><entry>DVD / DVD MENU</entry></row> | ||
| 96 | <row><entry><constant>KEY_EJECTCLOSECD</constant></entry><entry>Open/close the CD/DVD player</entry><entry>-> ) / CLOSE / OPEN</entry></row> | ||
| 97 | |||
| 98 | <row><entry><constant>KEY_MEDIA</constant></entry><entry>Turn on/off Media application</entry><entry>PC/TV / TURN ON/OFF APP</entry></row> | ||
| 99 | <row><entry><constant>KEY_PC</constant></entry><entry>Selects from TV to PC</entry><entry>PC</entry></row> | ||
| 100 | <row><entry><constant>KEY_RADIO</constant></entry><entry>Put into AM/FM radio mode</entry><entry>RADIO / TV/FM / TV/RADIO / FM / FM/RADIO</entry></row> | ||
| 101 | <row><entry><constant>KEY_TV</constant></entry><entry>Select tv mode</entry><entry>TV / LIVE TV</entry></row> | ||
| 102 | <row><entry><constant>KEY_TV2</constant></entry><entry>Select Cable mode</entry><entry>AIR/CBL</entry></row> | ||
| 103 | <row><entry><constant>KEY_VCR</constant></entry><entry>Select VCR mode</entry><entry>VCR MODE / DTR</entry></row> | ||
| 104 | <row><entry><constant>KEY_VIDEO</constant></entry><entry>Alternate between input modes</entry><entry>SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO</entry></row> | ||
| 105 | |||
| 106 | <row><entry><emphasis role="bold">Power control</emphasis></entry></row> | ||
| 107 | |||
| 108 | <row><entry><constant>KEY_POWER</constant></entry><entry>Turn on/off computer</entry><entry>SYSTEM POWER / COMPUTER POWER</entry></row> | ||
| 109 | <row><entry><constant>KEY_POWER2</constant></entry><entry>Turn on/off application</entry><entry>TV ON/OFF / POWER</entry></row> | ||
| 110 | <row><entry><constant>KEY_SLEEP</constant></entry><entry>Activate sleep timer</entry><entry>SLEEP / SLEEP TIMER</entry></row> | ||
| 111 | <row><entry><constant>KEY_SUSPEND</constant></entry><entry>Put computer into suspend mode</entry><entry>STANDBY / SUSPEND</entry></row> | ||
| 112 | |||
| 113 | <row><entry><emphasis role="bold">Window control</emphasis></entry></row> | ||
| 114 | |||
| 115 | <row><entry><constant>KEY_CLEAR</constant></entry><entry>Stop sroweam and return to default input video/audio</entry><entry>CLEAR / RESET / BOSS KEY</entry></row> | ||
| 116 | <row><entry><constant>KEY_CYCLEWINDOWS</constant></entry><entry>Minimize windows and move to the next one</entry><entry>ALT-TAB / MINIMIZE / DESKTOP</entry></row> | ||
| 117 | <row><entry><constant>KEY_FAVORITES</constant></entry><entry>Open the favorites sroweam window</entry><entry>TV WALL / Favorites</entry></row> | ||
| 118 | <row><entry><constant>KEY_MENU</constant></entry><entry>Call application menu</entry><entry>2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL</entry></row> | ||
| 119 | <row><entry><constant>KEY_NEW</constant></entry><entry>Open/Close Picture in Picture</entry><entry>PIP</entry></row> | ||
| 120 | <row><entry><constant>KEY_OK</constant></entry><entry>Send a confirmation code to application</entry><entry>OK / ENTER / RETURN</entry></row> | ||
| 121 | <row><entry><constant>KEY_SCREEN</constant></entry><entry>Select screen aspect ratio</entry><entry>4:3 16:9 SELECT</entry></row> | ||
| 122 | <row><entry><constant>KEY_ZOOM</constant></entry><entry>Put device into zoom/full screen mode</entry><entry>ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH</entry></row> | ||
| 123 | |||
| 124 | <row><entry><emphasis role="bold">Navigation keys</emphasis></entry></row> | ||
| 125 | |||
| 126 | <row><entry><constant>KEY_ESC</constant></entry><entry>Cancel current operation</entry><entry>CANCEL / BACK</entry></row> | ||
| 127 | <row><entry><constant>KEY_HELP</constant></entry><entry>Open a Help window</entry><entry>HELP</entry></row> | ||
| 128 | <row><entry><constant>KEY_HOMEPAGE</constant></entry><entry>Navigate to Homepage</entry><entry>HOME</entry></row> | ||
| 129 | <row><entry><constant>KEY_INFO</constant></entry><entry>Open On Screen Display</entry><entry>DISPLAY INFORMATION / OSD</entry></row> | ||
| 130 | <row><entry><constant>KEY_WWW</constant></entry><entry>Open the default browser</entry><entry>WEB</entry></row> | ||
| 131 | <row><entry><constant>KEY_UP</constant></entry><entry>Up key</entry><entry>UP</entry></row> | ||
| 132 | <row><entry><constant>KEY_DOWN</constant></entry><entry>Down key</entry><entry>DOWN</entry></row> | ||
| 133 | <row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row> | ||
| 134 | <row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row> | ||
| 135 | |||
| 136 | <row><entry><emphasis role="bold">Miscelaneous keys</emphasis></entry></row> | ||
| 137 | |||
| 138 | <row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row> | ||
| 139 | <row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row> | ||
| 140 | |||
| 141 | </tbody> | ||
| 142 | </tgroup> | ||
| 143 | </table> | ||
| 144 | |||
| 145 | <para>It should be noticed that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to:</para> | ||
| 146 | |||
| 147 | <table pgwide="1" frame="none" id="rc_keymap_notes"> | ||
| 148 | <title>Notes</title> | ||
| 149 | <tgroup cols="1"> | ||
| 150 | &cs-str; | ||
| 151 | <tbody valign="top"> | ||
| 152 | <row> | ||
| 153 | <entry>On simpler IR's, without separate channel keys, you need to map UP as <constant>KEY_CHANNELUP</constant></entry> | ||
| 154 | </row><row> | ||
| 155 | <entry>On simpler IR's, without separate channel keys, you need to map DOWN as <constant>KEY_CHANNELDOWN</constant></entry> | ||
| 156 | </row><row> | ||
| 157 | <entry>On simpler IR's, without separate volume keys, you need to map LEFT as <constant>KEY_VOLUMEDOWN</constant></entry> | ||
| 158 | </row><row> | ||
| 159 | <entry>On simpler IR's, without separate volume keys, you need to map RIGHT as <constant>KEY_VOLUMEUP</constant></entry> | ||
| 160 | </row> | ||
| 161 | </tbody> | ||
| 162 | </tgroup> | ||
| 163 | </table> | ||
| 164 | |||
| 165 | </section> | ||
| 166 | |||
| 167 | <section id="Remote_controllers_table_change"> | ||
| 168 | <title>Changing default Remote Controller mappings</title> | ||
| 169 | <para>The event interface provides two ioctls to be used against | ||
| 170 | the /dev/input/event device, to allow changing the default | ||
| 171 | keymapping.</para> | ||
| 172 | |||
| 173 | <para>This program demonstrates how to replace the keymap tables.</para> | ||
| 174 | &sub-keytable-c; | ||
| 175 | </section> | ||
diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml new file mode 100644 index 000000000000..937b4157a5d0 --- /dev/null +++ b/Documentation/DocBook/v4l/v4l2.xml | |||
| @@ -0,0 +1,479 @@ | |||
| 1 | <partinfo> | ||
| 2 | <authorgroup> | ||
| 3 | <author> | ||
| 4 | <firstname>Michael</firstname> | ||
| 5 | <surname>Schimek</surname> | ||
| 6 | <othername role="mi">H</othername> | ||
| 7 | <affiliation> | ||
| 8 | <address> | ||
| 9 | <email>mschimek@gmx.at</email> | ||
| 10 | </address> | ||
| 11 | </affiliation> | ||
| 12 | </author> | ||
| 13 | |||
| 14 | <author> | ||
| 15 | <firstname>Bill</firstname> | ||
| 16 | <surname>Dirks</surname> | ||
| 17 | <!-- Commented until Bill opts in to be spammed. | ||
| 18 | <affiliation> | ||
| 19 | <address> | ||
| 20 | <email>bill@thedirks.org</email> | ||
| 21 | </address> | ||
| 22 | </affiliation> --> | ||
| 23 | <contrib>Original author of the V4L2 API and | ||
| 24 | documentation.</contrib> | ||
| 25 | </author> | ||
| 26 | |||
| 27 | <author> | ||
| 28 | <firstname>Hans</firstname> | ||
| 29 | <surname>Verkuil</surname> | ||
| 30 | <contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl, | ||
| 31 | the extended control ioctls and major parts of the sliced VBI | ||
| 32 | API.</contrib> | ||
| 33 | <affiliation> | ||
| 34 | <address> | ||
| 35 | <email>hverkuil@xs4all.nl</email> | ||
| 36 | </address> | ||
| 37 | </affiliation> | ||
| 38 | </author> | ||
| 39 | |||
| 40 | <author> | ||
| 41 | <firstname>Martin</firstname> | ||
| 42 | <surname>Rubli</surname> | ||
| 43 | <!-- | ||
| 44 | <affiliation> | ||
| 45 | <address> | ||
| 46 | <email>martin_rubli@logitech.com</email> | ||
| 47 | </address> | ||
| 48 | </affiliation> --> | ||
| 49 | <contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES | ||
| 50 | and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib> | ||
| 51 | </author> | ||
| 52 | |||
| 53 | <author> | ||
| 54 | <firstname>Andy</firstname> | ||
| 55 | <surname>Walls</surname> | ||
| 56 | <contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV | ||
| 57 | MPEG stream embedded, sliced VBI data format in this specification. | ||
| 58 | </contrib> | ||
| 59 | <affiliation> | ||
| 60 | <address> | ||
| 61 | <email>awalls@radix.net</email> | ||
| 62 | </address> | ||
| 63 | </affiliation> | ||
| 64 | </author> | ||
| 65 | |||
| 66 | <author> | ||
| 67 | <firstname>Mauro</firstname> | ||
| 68 | <surname>Carvalho Chehab</surname> | ||
| 69 | <contrib>Documented libv4l, designed and added v4l2grab example, | ||
| 70 | Remote Controller chapter.</contrib> | ||
| 71 | <affiliation> | ||
| 72 | <address> | ||
| 73 | <email>mchehab@redhat.com</email> | ||
| 74 | </address> | ||
| 75 | </affiliation> | ||
| 76 | </author> | ||
| 77 | </authorgroup> | ||
| 78 | |||
| 79 | <copyright> | ||
| 80 | <year>1999</year> | ||
| 81 | <year>2000</year> | ||
| 82 | <year>2001</year> | ||
| 83 | <year>2002</year> | ||
| 84 | <year>2003</year> | ||
| 85 | <year>2004</year> | ||
| 86 | <year>2005</year> | ||
| 87 | <year>2006</year> | ||
| 88 | <year>2007</year> | ||
| 89 | <year>2008</year> | ||
| 90 | <year>2009</year> | ||
| 91 | <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin | ||
| 92 | Rubli, Andy Walls, Mauro Carvalho Chehab</holder> | ||
| 93 | </copyright> | ||
| 94 | <legalnotice> | ||
| 95 | <para>Except when explicitly stated as GPL, programming examples within | ||
| 96 | this part can be used and distributed without restrictions.</para> | ||
| 97 | </legalnotice> | ||
| 98 | <revhistory> | ||
| 99 | <!-- Put document revisions here, newest first. --> | ||
| 100 | <!-- API revisions (changes and additions of defines, enums, | ||
| 101 | structs, ioctls) must be noted in more detail in the history chapter | ||
| 102 | (compat.sgml), along with the possible impact on existing drivers and | ||
| 103 | applications. --> | ||
| 104 | |||
| 105 | <revision> | ||
| 106 | <revnumber>2.6.32</revnumber> | ||
| 107 | <date>2009-08-31</date> | ||
| 108 | <authorinitials>mcc</authorinitials> | ||
| 109 | <revremark>Now, revisions will match the kernel version where | ||
| 110 | the V4L2 API changes will be used by the Linux Kernel. | ||
| 111 | Also added Remote Controller chapter.</revremark> | ||
| 112 | </revision> | ||
| 113 | |||
| 114 | <revision> | ||
| 115 | <revnumber>0.29</revnumber> | ||
| 116 | <date>2009-08-26</date> | ||
| 117 | <authorinitials>ev</authorinitials> | ||
| 118 | <revremark>Added documentation for string controls and for FM Transmitter controls.</revremark> | ||
| 119 | </revision> | ||
| 120 | |||
| 121 | <revision> | ||
| 122 | <revnumber>0.28</revnumber> | ||
| 123 | <date>2009-08-26</date> | ||
| 124 | <authorinitials>gl</authorinitials> | ||
| 125 | <revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark> | ||
| 126 | </revision> | ||
| 127 | |||
| 128 | <revision> | ||
| 129 | <revnumber>0.27</revnumber> | ||
| 130 | <date>2009-08-15</date> | ||
| 131 | <authorinitials>mcc</authorinitials> | ||
| 132 | <revremark>Added libv4l and Remote Controller documentation; | ||
| 133 | added v4l2grab and keytable application examples.</revremark> | ||
| 134 | </revision> | ||
| 135 | |||
| 136 | <revision> | ||
| 137 | <revnumber>0.26</revnumber> | ||
| 138 | <date>2009-07-23</date> | ||
| 139 | <authorinitials>hv</authorinitials> | ||
| 140 | <revremark>Finalized the RDS capture API. Added modulator and RDS encoder | ||
| 141 | capabilities. Added support for string controls.</revremark> | ||
| 142 | </revision> | ||
| 143 | |||
| 144 | <revision> | ||
| 145 | <revnumber>0.25</revnumber> | ||
| 146 | <date>2009-01-18</date> | ||
| 147 | <authorinitials>hv</authorinitials> | ||
| 148 | <revremark>Added pixel formats VYUY, NV16 and NV61, and changed | ||
| 149 | the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. | ||
| 150 | Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, | ||
| 151 | V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark> | ||
| 152 | </revision> | ||
| 153 | |||
| 154 | <revision> | ||
| 155 | <revnumber>0.24</revnumber> | ||
| 156 | <date>2008-03-04</date> | ||
| 157 | <authorinitials>mhs</authorinitials> | ||
| 158 | <revremark>Added pixel formats Y16 and SBGGR16, new controls | ||
| 159 | and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark> | ||
| 160 | </revision> | ||
| 161 | |||
| 162 | <revision> | ||
| 163 | <revnumber>0.23</revnumber> | ||
| 164 | <date>2007-08-30</date> | ||
| 165 | <authorinitials>mhs</authorinitials> | ||
| 166 | <revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER. | ||
| 167 | Clarified the byte order of packed pixel formats.</revremark> | ||
| 168 | </revision> | ||
| 169 | |||
| 170 | <revision> | ||
| 171 | <revnumber>0.22</revnumber> | ||
| 172 | <date>2007-08-29</date> | ||
| 173 | <authorinitials>mhs</authorinitials> | ||
| 174 | <revremark>Added the Video Output Overlay interface, new MPEG | ||
| 175 | controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, | ||
| 176 | VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD, | ||
| 177 | VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. | ||
| 178 | Clarifications in the cropping chapter, about RGB pixel formats, the | ||
| 179 | mmap(), poll(), select(), read() and write() functions. Typographical | ||
| 180 | fixes.</revremark> | ||
| 181 | </revision> | ||
| 182 | |||
| 183 | <revision> | ||
| 184 | <revnumber>0.21</revnumber> | ||
| 185 | <date>2006-12-19</date> | ||
| 186 | <authorinitials>mhs</authorinitials> | ||
| 187 | <revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark> | ||
| 188 | </revision> | ||
| 189 | |||
| 190 | <revision> | ||
| 191 | <revnumber>0.20</revnumber> | ||
| 192 | <date>2006-11-24</date> | ||
| 193 | <authorinitials>mhs</authorinitials> | ||
| 194 | <revremark>Clarified the purpose of the audioset field in | ||
| 195 | struct v4l2_input and v4l2_output.</revremark> | ||
| 196 | </revision> | ||
| 197 | |||
| 198 | <revision> | ||
| 199 | <revnumber>0.19</revnumber> | ||
| 200 | <date>2006-10-19</date> | ||
| 201 | <authorinitials>mhs</authorinitials> | ||
| 202 | <revremark>Documented V4L2_PIX_FMT_RGB444.</revremark> | ||
| 203 | </revision> | ||
| 204 | |||
| 205 | <revision> | ||
| 206 | <revnumber>0.18</revnumber> | ||
| 207 | <date>2006-10-18</date> | ||
| 208 | <authorinitials>mhs</authorinitials> | ||
| 209 | <revremark>Added the description of extended controls by Hans | ||
| 210 | Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark> | ||
| 211 | </revision> | ||
| 212 | |||
| 213 | <revision> | ||
| 214 | <revnumber>0.17</revnumber> | ||
| 215 | <date>2006-10-12</date> | ||
| 216 | <authorinitials>mhs</authorinitials> | ||
| 217 | <revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark> | ||
| 218 | </revision> | ||
| 219 | |||
| 220 | <revision> | ||
| 221 | <revnumber>0.16</revnumber> | ||
| 222 | <date>2006-10-08</date> | ||
| 223 | <authorinitials>mhs</authorinitials> | ||
| 224 | <revremark>VIDIOC_ENUM_FRAMESIZES and | ||
| 225 | VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark> | ||
| 226 | </revision> | ||
| 227 | |||
| 228 | <revision> | ||
| 229 | <revnumber>0.15</revnumber> | ||
| 230 | <date>2006-09-23</date> | ||
| 231 | <authorinitials>mhs</authorinitials> | ||
| 232 | <revremark>Cleaned up the bibliography, added BT.653 and | ||
| 233 | BT.1119. capture.c/start_capturing() for user pointer I/O did not | ||
| 234 | initialize the buffer index. Documented the V4L MPEG and MJPEG | ||
| 235 | VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel | ||
| 236 | formats. See the history chapter for API changes.</revremark> | ||
| 237 | </revision> | ||
| 238 | |||
| 239 | <revision> | ||
| 240 | <revnumber>0.14</revnumber> | ||
| 241 | <date>2006-09-14</date> | ||
| 242 | <authorinitials>mr</authorinitials> | ||
| 243 | <revremark>Added VIDIOC_ENUM_FRAMESIZES and | ||
| 244 | VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of | ||
| 245 | digital devices.</revremark> | ||
| 246 | </revision> | ||
| 247 | |||
| 248 | <revision> | ||
| 249 | <revnumber>0.13</revnumber> | ||
| 250 | <date>2006-04-07</date> | ||
| 251 | <authorinitials>mhs</authorinitials> | ||
| 252 | <revremark>Corrected the description of struct v4l2_window | ||
| 253 | clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2 | ||
| 254 | defines.</revremark> | ||
| 255 | </revision> | ||
| 256 | |||
| 257 | <revision> | ||
| 258 | <revnumber>0.12</revnumber> | ||
| 259 | <date>2006-02-03</date> | ||
| 260 | <authorinitials>mhs</authorinitials> | ||
| 261 | <revremark>Corrected the description of struct | ||
| 262 | v4l2_captureparm and v4l2_outputparm.</revremark> | ||
| 263 | </revision> | ||
| 264 | |||
| 265 | <revision> | ||
| 266 | <revnumber>0.11</revnumber> | ||
| 267 | <date>2006-01-27</date> | ||
| 268 | <authorinitials>mhs</authorinitials> | ||
| 269 | <revremark>Improved the description of struct | ||
| 270 | v4l2_tuner.</revremark> | ||
| 271 | </revision> | ||
| 272 | |||
| 273 | <revision> | ||
| 274 | <revnumber>0.10</revnumber> | ||
| 275 | <date>2006-01-10</date> | ||
| 276 | <authorinitials>mhs</authorinitials> | ||
| 277 | <revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM | ||
| 278 | clarifications.</revremark> | ||
| 279 | </revision> | ||
| 280 | |||
| 281 | <revision> | ||
| 282 | <revnumber>0.9</revnumber> | ||
| 283 | <date>2005-11-27</date> | ||
| 284 | <authorinitials>mhs</authorinitials> | ||
| 285 | <revremark>Improved the 525 line numbering diagram. Hans | ||
| 286 | Verkuil and I rewrote the sliced VBI section. He also contributed a | ||
| 287 | VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard | ||
| 288 | selection example. Various updates.</revremark> | ||
| 289 | </revision> | ||
| 290 | |||
| 291 | <revision> | ||
| 292 | <revnumber>0.8</revnumber> | ||
| 293 | <date>2004-10-04</date> | ||
| 294 | <authorinitials>mhs</authorinitials> | ||
| 295 | <revremark>Somehow a piece of junk slipped into the capture | ||
| 296 | example, removed.</revremark> | ||
| 297 | </revision> | ||
| 298 | |||
| 299 | <revision> | ||
| 300 | <revnumber>0.7</revnumber> | ||
| 301 | <date>2004-09-19</date> | ||
| 302 | <authorinitials>mhs</authorinitials> | ||
| 303 | <revremark>Fixed video standard selection, control | ||
| 304 | enumeration, downscaling and aspect example. Added read and user | ||
| 305 | pointer i/o to video capture example.</revremark> | ||
| 306 | </revision> | ||
| 307 | |||
| 308 | <revision> | ||
| 309 | <revnumber>0.6</revnumber> | ||
| 310 | <date>2004-08-01</date> | ||
| 311 | <authorinitials>mhs</authorinitials> | ||
| 312 | <revremark>v4l2_buffer changes, added video capture example, | ||
| 313 | various corrections.</revremark> | ||
| 314 | </revision> | ||
| 315 | |||
| 316 | <revision> | ||
| 317 | <revnumber>0.5</revnumber> | ||
| 318 | <date>2003-11-05</date> | ||
| 319 | <authorinitials>mhs</authorinitials> | ||
| 320 | <revremark>Pixel format erratum.</revremark> | ||
| 321 | </revision> | ||
| 322 | |||
| 323 | <revision> | ||
| 324 | <revnumber>0.4</revnumber> | ||
| 325 | <date>2003-09-17</date> | ||
| 326 | <authorinitials>mhs</authorinitials> | ||
| 327 | <revremark>Corrected source and Makefile to generate a PDF. | ||
| 328 | SGML fixes. Added latest API changes. Closed gaps in the history | ||
| 329 | chapter.</revremark> | ||
| 330 | </revision> | ||
| 331 | |||
| 332 | <revision> | ||
| 333 | <revnumber>0.3</revnumber> | ||
| 334 | <date>2003-02-05</date> | ||
| 335 | <authorinitials>mhs</authorinitials> | ||
| 336 | <revremark>Another draft, more corrections.</revremark> | ||
| 337 | </revision> | ||
| 338 | |||
| 339 | <revision> | ||
| 340 | <revnumber>0.2</revnumber> | ||
| 341 | <date>2003-01-15</date> | ||
| 342 | <authorinitials>mhs</authorinitials> | ||
| 343 | <revremark>Second draft, with corrections pointed out by Gerd | ||
| 344 | Knorr.</revremark> | ||
| 345 | </revision> | ||
| 346 | |||
| 347 | <revision> | ||
| 348 | <revnumber>0.1</revnumber> | ||
| 349 | <date>2002-12-01</date> | ||
| 350 | <authorinitials>mhs</authorinitials> | ||
| 351 | <revremark>First draft, based on documentation by Bill Dirks | ||
| 352 | and discussions on the V4L mailing list.</revremark> | ||
| 353 | </revision> | ||
| 354 | </revhistory> | ||
| 355 | </partinfo> | ||
| 356 | |||
| 357 | <title>Video for Linux Two API Specification</title> | ||
| 358 | <subtitle>Revision 2.6.32</subtitle> | ||
| 359 | |||
| 360 | <chapter id="common"> | ||
| 361 | &sub-common; | ||
| 362 | </chapter> | ||
| 363 | |||
| 364 | <chapter id="pixfmt"> | ||
| 365 | &sub-pixfmt; | ||
| 366 | </chapter> | ||
| 367 | |||
| 368 | <chapter id="io"> | ||
| 369 | &sub-io; | ||
| 370 | </chapter> | ||
| 371 | |||
| 372 | <chapter id="devices"> | ||
| 373 | <title>Interfaces</title> | ||
| 374 | |||
| 375 | <section id="capture"> &sub-dev-capture; </section> | ||
| 376 | <section id="overlay"> &sub-dev-overlay; </section> | ||
| 377 | <section id="output"> &sub-dev-output; </section> | ||
| 378 | <section id="osd"> &sub-dev-osd; </section> | ||
| 379 | <section id="codec"> &sub-dev-codec; </section> | ||
| 380 | <section id="effect"> &sub-dev-effect; </section> | ||
| 381 | <section id="raw-vbi"> &sub-dev-raw-vbi; </section> | ||
| 382 | <section id="sliced"> &sub-dev-sliced-vbi; </section> | ||
| 383 | <section id="ttx"> &sub-dev-teletext; </section> | ||
| 384 | <section id="radio"> &sub-dev-radio; </section> | ||
| 385 | <section id="rds"> &sub-dev-rds; </section> | ||
| 386 | </chapter> | ||
| 387 | |||
| 388 | <chapter id="driver"> | ||
| 389 | &sub-driver; | ||
| 390 | </chapter> | ||
| 391 | |||
| 392 | <chapter id="libv4l"> | ||
| 393 | &sub-libv4l; | ||
| 394 | </chapter> | ||
| 395 | |||
| 396 | <chapter id="compat"> | ||
| 397 | &sub-compat; | ||
| 398 | </chapter> | ||
| 399 | |||
| 400 | <appendix id="user-func"> | ||
| 401 | <title>Function Reference</title> | ||
| 402 | |||
| 403 | <!-- Keep this alphabetically sorted. --> | ||
| 404 | |||
| 405 | &sub-close; | ||
| 406 | &sub-ioctl; | ||
| 407 | <!-- All ioctls go here. --> | ||
| 408 | &sub-cropcap; | ||
| 409 | &sub-dbg-g-chip-ident; | ||
| 410 | &sub-dbg-g-register; | ||
| 411 | &sub-encoder-cmd; | ||
| 412 | &sub-enumaudio; | ||
| 413 | &sub-enumaudioout; | ||
| 414 | &sub-enum-fmt; | ||
| 415 | &sub-enum-framesizes; | ||
| 416 | &sub-enum-frameintervals; | ||
| 417 | &sub-enuminput; | ||
| 418 | &sub-enumoutput; | ||
| 419 | &sub-enumstd; | ||
| 420 | &sub-g-audio; | ||
| 421 | &sub-g-audioout; | ||
| 422 | &sub-g-crop; | ||
| 423 | &sub-g-ctrl; | ||
| 424 | &sub-g-enc-index; | ||
| 425 | &sub-g-ext-ctrls; | ||
| 426 | &sub-g-fbuf; | ||
| 427 | &sub-g-fmt; | ||
| 428 | &sub-g-frequency; | ||
| 429 | &sub-g-input; | ||
| 430 | &sub-g-jpegcomp; | ||
| 431 | &sub-g-modulator; | ||
| 432 | &sub-g-output; | ||
| 433 | &sub-g-parm; | ||
| 434 | &sub-g-priority; | ||
| 435 | &sub-g-sliced-vbi-cap; | ||
| 436 | &sub-g-std; | ||
| 437 | &sub-g-tuner; | ||
| 438 | &sub-log-status; | ||
| 439 | &sub-overlay; | ||
| 440 | &sub-qbuf; | ||
| 441 | &sub-querybuf; | ||
| 442 | &sub-querycap; | ||
| 443 | &sub-queryctrl; | ||
| 444 | &sub-querystd; | ||
| 445 | &sub-reqbufs; | ||
| 446 | &sub-s-hw-freq-seek; | ||
| 447 | &sub-streamon; | ||
| 448 | <!-- End of ioctls. --> | ||
| 449 | &sub-mmap; | ||
| 450 | &sub-munmap; | ||
| 451 | &sub-open; | ||
| 452 | &sub-poll; | ||
| 453 | &sub-read; | ||
| 454 | &sub-select; | ||
| 455 | &sub-write; | ||
| 456 | </appendix> | ||
| 457 | |||
| 458 | <appendix id="videodev"> | ||
| 459 | <title>Video For Linux Two Header File</title> | ||
| 460 | &sub-videodev2-h; | ||
| 461 | </appendix> | ||
| 462 | |||
| 463 | <appendix id="capture-example"> | ||
| 464 | <title>Video Capture Example</title> | ||
| 465 | &sub-capture-c; | ||
| 466 | </appendix> | ||
| 467 | |||
| 468 | <appendix id="v4l2grab-example"> | ||
| 469 | <title>Video Grabber example using libv4l</title> | ||
| 470 | <para>This program demonstrates how to grab V4L2 images in ppm format by | ||
| 471 | using libv4l handlers. The advantage is that this grabber can potentially work | ||
| 472 | with any V4L2 driver.</para> | ||
| 473 | &sub-v4l2grab-c; | ||
| 474 | </appendix> | ||
| 475 | |||
| 476 | &sub-media-indices; | ||
| 477 | |||
| 478 | &sub-biblio; | ||
| 479 | |||
diff --git a/Documentation/DocBook/v4l/v4l2grab.c.xml b/Documentation/DocBook/v4l/v4l2grab.c.xml new file mode 100644 index 000000000000..bed12e40be27 --- /dev/null +++ b/Documentation/DocBook/v4l/v4l2grab.c.xml | |||
| @@ -0,0 +1,164 @@ | |||
| 1 | <programlisting> | ||
| 2 | /* V4L2 video picture grabber | ||
| 3 | Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@infradead.org> | ||
| 4 | |||
| 5 | This program is free software; you can redistribute it and/or modify | ||
| 6 | it under the terms of the GNU General Public License as published by | ||
| 7 | the Free Software Foundation version 2 of the License. | ||
| 8 | |||
| 9 | This program is distributed in the hope that it will be useful, | ||
| 10 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
| 12 | GNU General Public License for more details. | ||
| 13 | */ | ||
| 14 | |||
| 15 | #include <stdio.h> | ||
| 16 | #include <stdlib.h> | ||
| 17 | #include <string.h> | ||
| 18 | #include <fcntl.h> | ||
| 19 | #include <errno.h> | ||
| 20 | #include <sys/ioctl.h> | ||
| 21 | #include <sys/types.h> | ||
| 22 | #include <sys/time.h> | ||
| 23 | #include <sys/mman.h> | ||
| 24 | #include <linux/videodev2.h> | ||
| 25 | #include "../libv4l/include/libv4l2.h" | ||
| 26 | |||
| 27 | #define CLEAR(x) memset(&(x), 0, sizeof(x)) | ||
| 28 | |||
| 29 | struct buffer { | ||
| 30 | void *start; | ||
| 31 | size_t length; | ||
| 32 | }; | ||
| 33 | |||
| 34 | static void xioctl(int fh, int request, void *arg) | ||
| 35 | { | ||
| 36 | int r; | ||
| 37 | |||
| 38 | do { | ||
| 39 | r = v4l2_ioctl(fh, request, arg); | ||
| 40 | } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN))); | ||
| 41 | |||
| 42 | if (r == -1) { | ||
| 43 | fprintf(stderr, "error %d, %s\n", errno, strerror(errno)); | ||
| 44 | exit(EXIT_FAILURE); | ||
| 45 | } | ||
| 46 | } | ||
| 47 | |||
| 48 | int main(int argc, char **argv) | ||
| 49 | { | ||
| 50 | struct <link linkend="v4l2-format">v4l2_format</link> fmt; | ||
| 51 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; | ||
| 52 | struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req; | ||
| 53 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 54 | fd_set fds; | ||
| 55 | struct timeval tv; | ||
| 56 | int r, fd = -1; | ||
| 57 | unsigned int i, n_buffers; | ||
| 58 | char *dev_name = "/dev/video0"; | ||
| 59 | char out_name[256]; | ||
| 60 | FILE *fout; | ||
| 61 | struct buffer *buffers; | ||
| 62 | |||
| 63 | fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0); | ||
| 64 | if (fd < 0) { | ||
| 65 | perror("Cannot open device"); | ||
| 66 | exit(EXIT_FAILURE); | ||
| 67 | } | ||
| 68 | |||
| 69 | CLEAR(fmt); | ||
| 70 | fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 71 | fmt.fmt.pix.width = 640; | ||
| 72 | fmt.fmt.pix.height = 480; | ||
| 73 | fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24; | ||
| 74 | fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; | ||
| 75 | xioctl(fd, VIDIOC_S_FMT, &fmt); | ||
| 76 | if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) { | ||
| 77 | printf("Libv4l didn't accept RGB24 format. Can't proceed.\n"); | ||
| 78 | exit(EXIT_FAILURE); | ||
| 79 | } | ||
| 80 | if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480)) | ||
| 81 | printf("Warning: driver is sending image at %dx%d\n", | ||
| 82 | fmt.fmt.pix.width, fmt.fmt.pix.height); | ||
| 83 | |||
| 84 | CLEAR(req); | ||
| 85 | req.count = 2; | ||
| 86 | req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 87 | req.memory = V4L2_MEMORY_MMAP; | ||
| 88 | xioctl(fd, VIDIOC_REQBUFS, &req); | ||
| 89 | |||
| 90 | buffers = calloc(req.count, sizeof(*buffers)); | ||
| 91 | for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { | ||
| 92 | CLEAR(buf); | ||
| 93 | |||
| 94 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 95 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 96 | buf.index = n_buffers; | ||
| 97 | |||
| 98 | xioctl(fd, VIDIOC_QUERYBUF, &buf); | ||
| 99 | |||
| 100 | buffers[n_buffers].length = buf.length; | ||
| 101 | buffers[n_buffers].start = v4l2_mmap(NULL, buf.length, | ||
| 102 | PROT_READ | PROT_WRITE, MAP_SHARED, | ||
| 103 | fd, buf.m.offset); | ||
| 104 | |||
| 105 | if (MAP_FAILED == buffers[n_buffers].start) { | ||
| 106 | perror("mmap"); | ||
| 107 | exit(EXIT_FAILURE); | ||
| 108 | } | ||
| 109 | } | ||
| 110 | |||
| 111 | for (i = 0; i < n_buffers; ++i) { | ||
| 112 | CLEAR(buf); | ||
| 113 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 114 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 115 | buf.index = i; | ||
| 116 | xioctl(fd, VIDIOC_QBUF, &buf); | ||
| 117 | } | ||
| 118 | type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 119 | |||
| 120 | xioctl(fd, VIDIOC_STREAMON, &type); | ||
| 121 | for (i = 0; i < 20; i++) { | ||
| 122 | do { | ||
| 123 | FD_ZERO(&fds); | ||
| 124 | FD_SET(fd, &fds); | ||
| 125 | |||
| 126 | /* Timeout. */ | ||
| 127 | tv.tv_sec = 2; | ||
| 128 | tv.tv_usec = 0; | ||
| 129 | |||
| 130 | r = select(fd + 1, &fds, NULL, NULL, &tv); | ||
| 131 | } while ((r == -1 && (errno = EINTR))); | ||
| 132 | if (r == -1) { | ||
| 133 | perror("select"); | ||
| 134 | return errno; | ||
| 135 | } | ||
| 136 | |||
| 137 | CLEAR(buf); | ||
| 138 | buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 139 | buf.memory = V4L2_MEMORY_MMAP; | ||
| 140 | xioctl(fd, VIDIOC_DQBUF, &buf); | ||
| 141 | |||
| 142 | sprintf(out_name, "out%03d.ppm", i); | ||
| 143 | fout = fopen(out_name, "w"); | ||
| 144 | if (!fout) { | ||
| 145 | perror("Cannot open image"); | ||
| 146 | exit(EXIT_FAILURE); | ||
| 147 | } | ||
| 148 | fprintf(fout, "P6\n%d %d 255\n", | ||
| 149 | fmt.fmt.pix.width, fmt.fmt.pix.height); | ||
| 150 | fwrite(buffers[buf.index].start, buf.bytesused, 1, fout); | ||
| 151 | fclose(fout); | ||
| 152 | |||
| 153 | xioctl(fd, VIDIOC_QBUF, &buf); | ||
| 154 | } | ||
| 155 | |||
| 156 | type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | ||
| 157 | xioctl(fd, VIDIOC_STREAMOFF, &type); | ||
| 158 | for (i = 0; i < n_buffers; ++i) | ||
| 159 | v4l2_munmap(buffers[i].start, buffers[i].length); | ||
| 160 | v4l2_close(fd); | ||
| 161 | |||
| 162 | return 0; | ||
| 163 | } | ||
| 164 | </programlisting> | ||
diff --git a/Documentation/DocBook/v4l/vbi_525.gif b/Documentation/DocBook/v4l/vbi_525.gif new file mode 100644 index 000000000000..5580b690d504 --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_525.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/vbi_525.pdf b/Documentation/DocBook/v4l/vbi_525.pdf new file mode 100644 index 000000000000..9e72c25b208d --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_525.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/vbi_625.gif b/Documentation/DocBook/v4l/vbi_625.gif new file mode 100644 index 000000000000..34e3251983c4 --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_625.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/vbi_625.pdf b/Documentation/DocBook/v4l/vbi_625.pdf new file mode 100644 index 000000000000..765235e33a4d --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_625.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/vbi_hsync.gif b/Documentation/DocBook/v4l/vbi_hsync.gif new file mode 100644 index 000000000000..b02434d3b356 --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_hsync.gif | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/vbi_hsync.pdf b/Documentation/DocBook/v4l/vbi_hsync.pdf new file mode 100644 index 000000000000..200b668189bf --- /dev/null +++ b/Documentation/DocBook/v4l/vbi_hsync.pdf | |||
| Binary files differ | |||
diff --git a/Documentation/DocBook/v4l/videodev2.h.xml b/Documentation/DocBook/v4l/videodev2.h.xml new file mode 100644 index 000000000000..97002060ac4f --- /dev/null +++ b/Documentation/DocBook/v4l/videodev2.h.xml | |||
| @@ -0,0 +1,1640 @@ | |||
| 1 | <programlisting> | ||
| 2 | /* | ||
| 3 | * Video for Linux Two header file | ||
| 4 | * | ||
| 5 | * Copyright (C) 1999-2007 the contributors | ||
| 6 | * | ||
| 7 | * This program is free software; you can redistribute it and/or modify | ||
| 8 | * it under the terms of the GNU General Public License as published by | ||
| 9 | * the Free Software Foundation; either version 2 of the License, or | ||
| 10 | * (at your option) any later version. | ||
| 11 | * | ||
| 12 | * This program is distributed in the hope that it will be useful, | ||
| 13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
| 15 | * GNU General Public License for more details. | ||
| 16 | * | ||
| 17 | * Alternatively you can redistribute this file under the terms of the | ||
| 18 | * BSD license as stated below: | ||
| 19 | * | ||
| 20 | * Redistribution and use in source and binary forms, with or without | ||
| 21 | * modification, are permitted provided that the following conditions | ||
| 22 | * are met: | ||
| 23 | * 1. Redistributions of source code must retain the above copyright | ||
| 24 | * notice, this list of conditions and the following disclaimer. | ||
| 25 | * 2. Redistributions in binary form must reproduce the above copyright | ||
| 26 | * notice, this list of conditions and the following disclaimer in | ||
| 27 | * the documentation and/or other materials provided with the | ||
| 28 | * distribution. | ||
| 29 | * 3. The names of its contributors may not be used to endorse or promote | ||
| 30 | * products derived from this software without specific prior written | ||
| 31 | * permission. | ||
| 32 | * | ||
| 33 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | ||
| 34 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | ||
| 35 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | ||
| 36 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | ||
| 37 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | ||
| 38 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED | ||
| 39 | * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR | ||
| 40 | * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF | ||
| 41 | * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING | ||
| 42 | * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS | ||
| 43 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
| 44 | * | ||
| 45 | * Header file for v4l or V4L2 drivers and applications | ||
| 46 | * with public API. | ||
| 47 | * All kernel-specific stuff were moved to media/v4l2-dev.h, so | ||
| 48 | * no #if __KERNEL tests are allowed here | ||
| 49 | * | ||
| 50 | * See http://linuxtv.org for more info | ||
| 51 | * | ||
| 52 | * Author: Bill Dirks <bill@thedirks.org> | ||
| 53 | * Justin Schoeman | ||
| 54 | * Hans Verkuil <hverkuil@xs4all.nl> | ||
| 55 | * et al. | ||
| 56 | */ | ||
| 57 | #ifndef __LINUX_VIDEODEV2_H | ||
| 58 | #define __LINUX_VIDEODEV2_H | ||
| 59 | |||
| 60 | #ifdef __KERNEL__ | ||
| 61 | #include <linux/time.h> /* need struct timeval */ | ||
| 62 | #else | ||
| 63 | #include <sys/time.h> | ||
| 64 | #endif | ||
| 65 | #include <linux/compiler.h> | ||
| 66 | #include <linux/ioctl.h> | ||
| 67 | #include <linux/types.h> | ||
| 68 | |||
| 69 | /* | ||
| 70 | * Common stuff for both V4L1 and V4L2 | ||
| 71 | * Moved from videodev.h | ||
| 72 | */ | ||
| 73 | #define VIDEO_MAX_FRAME 32 | ||
| 74 | |||
| 75 | #ifndef __KERNEL__ | ||
| 76 | |||
| 77 | /* These defines are V4L1 specific and should not be used with the V4L2 API! | ||
| 78 | They will be removed from this header in the future. */ | ||
| 79 | |||
| 80 | #define VID_TYPE_CAPTURE 1 /* Can capture */ | ||
| 81 | #define VID_TYPE_TUNER 2 /* Can tune */ | ||
| 82 | #define VID_TYPE_TELETEXT 4 /* Does teletext */ | ||
| 83 | #define VID_TYPE_OVERLAY 8 /* Overlay onto frame buffer */ | ||
| 84 | #define VID_TYPE_CHROMAKEY 16 /* Overlay by chromakey */ | ||
| 85 | #define VID_TYPE_CLIPPING 32 /* Can clip */ | ||
| 86 | #define VID_TYPE_FRAMERAM 64 /* Uses the frame buffer memory */ | ||
| 87 | #define VID_TYPE_SCALES 128 /* Scalable */ | ||
| 88 | #define VID_TYPE_MONOCHROME 256 /* Monochrome only */ | ||
| 89 | #define VID_TYPE_SUBCAPTURE 512 /* Can capture subareas of the image */ | ||
| 90 | #define VID_TYPE_MPEG_DECODER 1024 /* Can decode MPEG streams */ | ||
| 91 | #define VID_TYPE_MPEG_ENCODER 2048 /* Can encode MPEG streams */ | ||
| 92 | #define VID_TYPE_MJPEG_DECODER 4096 /* Can decode MJPEG streams */ | ||
| 93 | #define VID_TYPE_MJPEG_ENCODER 8192 /* Can encode MJPEG streams */ | ||
| 94 | #endif | ||
| 95 | |||
| 96 | /* | ||
| 97 | * M I S C E L L A N E O U S | ||
| 98 | */ | ||
| 99 | |||
| 100 | /* Four-character-code (FOURCC) */ | ||
| 101 | #define v4l2_fourcc(a, b, c, d)\ | ||
| 102 | ((__u32)(a) | ((__u32)(b) << 8) | ((__u32)(c) << 16) | ((__u32)(d) << 24)) | ||
| 103 | |||
| 104 | /* | ||
| 105 | * E N U M S | ||
| 106 | */ | ||
| 107 | enum <link linkend="v4l2-field">v4l2_field</link> { | ||
| 108 | V4L2_FIELD_ANY = 0, /* driver can choose from none, | ||
| 109 | top, bottom, interlaced | ||
| 110 | depending on whatever it thinks | ||
| 111 | is approximate ... */ | ||
| 112 | V4L2_FIELD_NONE = 1, /* this device has no fields ... */ | ||
| 113 | V4L2_FIELD_TOP = 2, /* top field only */ | ||
| 114 | V4L2_FIELD_BOTTOM = 3, /* bottom field only */ | ||
| 115 | V4L2_FIELD_INTERLACED = 4, /* both fields interlaced */ | ||
| 116 | V4L2_FIELD_SEQ_TB = 5, /* both fields sequential into one | ||
| 117 | buffer, top-bottom order */ | ||
| 118 | V4L2_FIELD_SEQ_BT = 6, /* same as above + bottom-top order */ | ||
| 119 | V4L2_FIELD_ALTERNATE = 7, /* both fields alternating into | ||
| 120 | separate buffers */ | ||
| 121 | V4L2_FIELD_INTERLACED_TB = 8, /* both fields interlaced, top field | ||
| 122 | first and the top field is | ||
| 123 | transmitted first */ | ||
| 124 | V4L2_FIELD_INTERLACED_BT = 9, /* both fields interlaced, top field | ||
| 125 | first and the bottom field is | ||
| 126 | transmitted first */ | ||
| 127 | }; | ||
| 128 | #define V4L2_FIELD_HAS_TOP(field) \ | ||
| 129 | ((field) == V4L2_FIELD_TOP ||\ | ||
| 130 | (field) == V4L2_FIELD_INTERLACED ||\ | ||
| 131 | (field) == V4L2_FIELD_INTERLACED_TB ||\ | ||
| 132 | (field) == V4L2_FIELD_INTERLACED_BT ||\ | ||
| 133 | (field) == V4L2_FIELD_SEQ_TB ||\ | ||
| 134 | (field) == V4L2_FIELD_SEQ_BT) | ||
| 135 | #define V4L2_FIELD_HAS_BOTTOM(field) \ | ||
| 136 | ((field) == V4L2_FIELD_BOTTOM ||\ | ||
| 137 | (field) == V4L2_FIELD_INTERLACED ||\ | ||
| 138 | (field) == V4L2_FIELD_INTERLACED_TB ||\ | ||
| 139 | (field) == V4L2_FIELD_INTERLACED_BT ||\ | ||
| 140 | (field) == V4L2_FIELD_SEQ_TB ||\ | ||
| 141 | (field) == V4L2_FIELD_SEQ_BT) | ||
| 142 | #define V4L2_FIELD_HAS_BOTH(field) \ | ||
| 143 | ((field) == V4L2_FIELD_INTERLACED ||\ | ||
| 144 | (field) == V4L2_FIELD_INTERLACED_TB ||\ | ||
| 145 | (field) == V4L2_FIELD_INTERLACED_BT ||\ | ||
| 146 | (field) == V4L2_FIELD_SEQ_TB ||\ | ||
| 147 | (field) == V4L2_FIELD_SEQ_BT) | ||
| 148 | |||
| 149 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> { | ||
| 150 | V4L2_BUF_TYPE_VIDEO_CAPTURE = 1, | ||
| 151 | V4L2_BUF_TYPE_VIDEO_OUTPUT = 2, | ||
| 152 | V4L2_BUF_TYPE_VIDEO_OVERLAY = 3, | ||
| 153 | V4L2_BUF_TYPE_VBI_CAPTURE = 4, | ||
| 154 | V4L2_BUF_TYPE_VBI_OUTPUT = 5, | ||
| 155 | V4L2_BUF_TYPE_SLICED_VBI_CAPTURE = 6, | ||
| 156 | V4L2_BUF_TYPE_SLICED_VBI_OUTPUT = 7, | ||
| 157 | #if 1 /*KEEP*/ | ||
| 158 | /* Experimental */ | ||
| 159 | V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8, | ||
| 160 | #endif | ||
| 161 | V4L2_BUF_TYPE_PRIVATE = 0x80, | ||
| 162 | }; | ||
| 163 | |||
| 164 | enum <link linkend="v4l2-ctrl-type">v4l2_ctrl_type</link> { | ||
| 165 | V4L2_CTRL_TYPE_INTEGER = 1, | ||
| 166 | V4L2_CTRL_TYPE_BOOLEAN = 2, | ||
| 167 | V4L2_CTRL_TYPE_MENU = 3, | ||
| 168 | V4L2_CTRL_TYPE_BUTTON = 4, | ||
| 169 | V4L2_CTRL_TYPE_INTEGER64 = 5, | ||
| 170 | V4L2_CTRL_TYPE_CTRL_CLASS = 6, | ||
| 171 | V4L2_CTRL_TYPE_STRING = 7, | ||
| 172 | }; | ||
| 173 | |||
| 174 | enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> { | ||
| 175 | V4L2_TUNER_RADIO = 1, | ||
| 176 | V4L2_TUNER_ANALOG_TV = 2, | ||
| 177 | V4L2_TUNER_DIGITAL_TV = 3, | ||
| 178 | }; | ||
| 179 | |||
| 180 | enum <link linkend="v4l2-memory">v4l2_memory</link> { | ||
| 181 | V4L2_MEMORY_MMAP = 1, | ||
| 182 | V4L2_MEMORY_USERPTR = 2, | ||
| 183 | V4L2_MEMORY_OVERLAY = 3, | ||
| 184 | }; | ||
| 185 | |||
| 186 | /* see also http://vektor.theorem.ca/graphics/ycbcr/ */ | ||
| 187 | enum <link linkend="v4l2-colorspace">v4l2_colorspace</link> { | ||
| 188 | /* ITU-R 601 -- broadcast NTSC/PAL */ | ||
| 189 | V4L2_COLORSPACE_SMPTE170M = 1, | ||
| 190 | |||
| 191 | /* 1125-Line (US) HDTV */ | ||
| 192 | V4L2_COLORSPACE_SMPTE240M = 2, | ||
| 193 | |||
| 194 | /* HD and modern captures. */ | ||
| 195 | V4L2_COLORSPACE_REC709 = 3, | ||
| 196 | |||
| 197 | /* broken BT878 extents (601, luma range 16-253 instead of 16-235) */ | ||
| 198 | V4L2_COLORSPACE_BT878 = 4, | ||
| 199 | |||
| 200 | /* These should be useful. Assume 601 extents. */ | ||
| 201 | V4L2_COLORSPACE_470_SYSTEM_M = 5, | ||
| 202 | V4L2_COLORSPACE_470_SYSTEM_BG = 6, | ||
| 203 | |||
| 204 | /* I know there will be cameras that send this. So, this is | ||
| 205 | * unspecified chromaticities and full 0-255 on each of the | ||
| 206 | * Y'CbCr components | ||
| 207 | */ | ||
| 208 | V4L2_COLORSPACE_JPEG = 7, | ||
| 209 | |||
| 210 | /* For RGB colourspaces, this is probably a good start. */ | ||
| 211 | V4L2_COLORSPACE_SRGB = 8, | ||
| 212 | }; | ||
| 213 | |||
| 214 | enum <link linkend="v4l2-priority">v4l2_priority</link> { | ||
| 215 | V4L2_PRIORITY_UNSET = 0, /* not initialized */ | ||
| 216 | V4L2_PRIORITY_BACKGROUND = 1, | ||
| 217 | V4L2_PRIORITY_INTERACTIVE = 2, | ||
| 218 | V4L2_PRIORITY_RECORD = 3, | ||
| 219 | V4L2_PRIORITY_DEFAULT = V4L2_PRIORITY_INTERACTIVE, | ||
| 220 | }; | ||
| 221 | |||
| 222 | struct <link linkend="v4l2-rect">v4l2_rect</link> { | ||
| 223 | __s32 left; | ||
| 224 | __s32 top; | ||
| 225 | __s32 width; | ||
| 226 | __s32 height; | ||
| 227 | }; | ||
| 228 | |||
| 229 | struct <link linkend="v4l2-fract">v4l2_fract</link> { | ||
| 230 | __u32 numerator; | ||
| 231 | __u32 denominator; | ||
| 232 | }; | ||
| 233 | |||
| 234 | /* | ||
| 235 | * D R I V E R C A P A B I L I T I E S | ||
| 236 | */ | ||
| 237 | struct <link linkend="v4l2-capability">v4l2_capability</link> { | ||
| 238 | __u8 driver[16]; /* i.e.ie; "bttv" */ | ||
| 239 | __u8 card[32]; /* i.e.ie; "Hauppauge WinTV" */ | ||
| 240 | __u8 bus_info[32]; /* "PCI:" + pci_name(pci_dev) */ | ||
| 241 | __u32 version; /* should use KERNEL_VERSION() */ | ||
| 242 | __u32 capabilities; /* Device capabilities */ | ||
| 243 | __u32 reserved[4]; | ||
| 244 | }; | ||
| 245 | |||
| 246 | /* Values for 'capabilities' field */ | ||
| 247 | #define V4L2_CAP_VIDEO_CAPTURE 0x00000001 /* Is a video capture device */ | ||
| 248 | #define V4L2_CAP_VIDEO_OUTPUT 0x00000002 /* Is a video output device */ | ||
| 249 | #define V4L2_CAP_VIDEO_OVERLAY 0x00000004 /* Can do video overlay */ | ||
| 250 | #define V4L2_CAP_VBI_CAPTURE 0x00000010 /* Is a raw VBI capture device */ | ||
| 251 | #define V4L2_CAP_VBI_OUTPUT 0x00000020 /* Is a raw VBI output device */ | ||
| 252 | #define V4L2_CAP_SLICED_VBI_CAPTURE 0x00000040 /* Is a sliced VBI capture device */ | ||
| 253 | #define V4L2_CAP_SLICED_VBI_OUTPUT 0x00000080 /* Is a sliced VBI output device */ | ||
| 254 | #define V4L2_CAP_RDS_CAPTURE 0x00000100 /* RDS data capture */ | ||
| 255 | #define V4L2_CAP_VIDEO_OUTPUT_OVERLAY 0x00000200 /* Can do video output overlay */ | ||
| 256 | #define V4L2_CAP_HW_FREQ_SEEK 0x00000400 /* Can do hardware frequency seek */ | ||
| 257 | #define V4L2_CAP_RDS_OUTPUT 0x00000800 /* Is an RDS encoder */ | ||
| 258 | |||
| 259 | #define V4L2_CAP_TUNER 0x00010000 /* has a tuner */ | ||
| 260 | #define V4L2_CAP_AUDIO 0x00020000 /* has audio support */ | ||
| 261 | #define V4L2_CAP_RADIO 0x00040000 /* is a radio device */ | ||
| 262 | #define V4L2_CAP_MODULATOR 0x00080000 /* has a modulator */ | ||
| 263 | |||
| 264 | #define V4L2_CAP_READWRITE 0x01000000 /* read/write systemcalls */ | ||
| 265 | #define V4L2_CAP_ASYNCIO 0x02000000 /* async I/O */ | ||
| 266 | #define V4L2_CAP_STREAMING 0x04000000 /* streaming I/O ioctls */ | ||
| 267 | |||
| 268 | /* | ||
| 269 | * V I D E O I M A G E F O R M A T | ||
| 270 | */ | ||
| 271 | struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> { | ||
| 272 | __u32 width; | ||
| 273 | __u32 height; | ||
| 274 | __u32 pixelformat; | ||
| 275 | enum <link linkend="v4l2-field">v4l2_field</link> field; | ||
| 276 | __u32 bytesperline; /* for padding, zero if unused */ | ||
| 277 | __u32 sizeimage; | ||
| 278 | enum <link linkend="v4l2-colorspace">v4l2_colorspace</link> colorspace; | ||
| 279 | __u32 priv; /* private data, depends on pixelformat */ | ||
| 280 | }; | ||
| 281 | |||
| 282 | /* Pixel format FOURCC depth Description */ | ||
| 283 | |||
| 284 | /* RGB formats */ | ||
| 285 | #define <link linkend="V4L2-PIX-FMT-RGB332">V4L2_PIX_FMT_RGB332</link> v4l2_fourcc('R', 'G', 'B', '1') /* 8 RGB-3-3-2 */ | ||
| 286 | #define <link linkend="V4L2-PIX-FMT-RGB444">V4L2_PIX_FMT_RGB444</link> v4l2_fourcc('R', '4', '4', '4') /* 16 xxxxrrrr ggggbbbb */ | ||
| 287 | #define <link linkend="V4L2-PIX-FMT-RGB555">V4L2_PIX_FMT_RGB555</link> v4l2_fourcc('R', 'G', 'B', 'O') /* 16 RGB-5-5-5 */ | ||
| 288 | #define <link linkend="V4L2-PIX-FMT-RGB565">V4L2_PIX_FMT_RGB565</link> v4l2_fourcc('R', 'G', 'B', 'P') /* 16 RGB-5-6-5 */ | ||
| 289 | #define <link linkend="V4L2-PIX-FMT-RGB555X">V4L2_PIX_FMT_RGB555X</link> v4l2_fourcc('R', 'G', 'B', 'Q') /* 16 RGB-5-5-5 BE */ | ||
| 290 | #define <link linkend="V4L2-PIX-FMT-RGB565X">V4L2_PIX_FMT_RGB565X</link> v4l2_fourcc('R', 'G', 'B', 'R') /* 16 RGB-5-6-5 BE */ | ||
| 291 | #define <link linkend="V4L2-PIX-FMT-BGR24">V4L2_PIX_FMT_BGR24</link> v4l2_fourcc('B', 'G', 'R', '3') /* 24 BGR-8-8-8 */ | ||
| 292 | #define <link linkend="V4L2-PIX-FMT-RGB24">V4L2_PIX_FMT_RGB24</link> v4l2_fourcc('R', 'G', 'B', '3') /* 24 RGB-8-8-8 */ | ||
| 293 | #define <link linkend="V4L2-PIX-FMT-BGR32">V4L2_PIX_FMT_BGR32</link> v4l2_fourcc('B', 'G', 'R', '4') /* 32 BGR-8-8-8-8 */ | ||
| 294 | #define <link linkend="V4L2-PIX-FMT-RGB32">V4L2_PIX_FMT_RGB32</link> v4l2_fourcc('R', 'G', 'B', '4') /* 32 RGB-8-8-8-8 */ | ||
| 295 | |||
| 296 | /* Grey formats */ | ||
| 297 | #define <link linkend="V4L2-PIX-FMT-GREY">V4L2_PIX_FMT_GREY</link> v4l2_fourcc('G', 'R', 'E', 'Y') /* 8 Greyscale */ | ||
| 298 | #define <link linkend="V4L2-PIX-FMT-Y16">V4L2_PIX_FMT_Y16</link> v4l2_fourcc('Y', '1', '6', ' ') /* 16 Greyscale */ | ||
| 299 | |||
| 300 | /* Palette formats */ | ||
| 301 | #define <link linkend="V4L2-PIX-FMT-PAL8">V4L2_PIX_FMT_PAL8</link> v4l2_fourcc('P', 'A', 'L', '8') /* 8 8-bit palette */ | ||
| 302 | |||
| 303 | /* Luminance+Chrominance formats */ | ||
| 304 | #define <link linkend="V4L2-PIX-FMT-YVU410">V4L2_PIX_FMT_YVU410</link> v4l2_fourcc('Y', 'V', 'U', '9') /* 9 YVU 4:1:0 */ | ||
| 305 | #define <link linkend="V4L2-PIX-FMT-YVU420">V4L2_PIX_FMT_YVU420</link> v4l2_fourcc('Y', 'V', '1', '2') /* 12 YVU 4:2:0 */ | ||
| 306 | #define <link linkend="V4L2-PIX-FMT-YUYV">V4L2_PIX_FMT_YUYV</link> v4l2_fourcc('Y', 'U', 'Y', 'V') /* 16 YUV 4:2:2 */ | ||
| 307 | #define <link linkend="V4L2-PIX-FMT-YYUV">V4L2_PIX_FMT_YYUV</link> v4l2_fourcc('Y', 'Y', 'U', 'V') /* 16 YUV 4:2:2 */ | ||
| 308 | #define <link linkend="V4L2-PIX-FMT-YVYU">V4L2_PIX_FMT_YVYU</link> v4l2_fourcc('Y', 'V', 'Y', 'U') /* 16 YVU 4:2:2 */ | ||
| 309 | #define <link linkend="V4L2-PIX-FMT-UYVY">V4L2_PIX_FMT_UYVY</link> v4l2_fourcc('U', 'Y', 'V', 'Y') /* 16 YUV 4:2:2 */ | ||
| 310 | #define <link linkend="V4L2-PIX-FMT-VYUY">V4L2_PIX_FMT_VYUY</link> v4l2_fourcc('V', 'Y', 'U', 'Y') /* 16 YUV 4:2:2 */ | ||
| 311 | #define <link linkend="V4L2-PIX-FMT-YUV422P">V4L2_PIX_FMT_YUV422P</link> v4l2_fourcc('4', '2', '2', 'P') /* 16 YVU422 planar */ | ||
| 312 | #define <link linkend="V4L2-PIX-FMT-YUV411P">V4L2_PIX_FMT_YUV411P</link> v4l2_fourcc('4', '1', '1', 'P') /* 16 YVU411 planar */ | ||
| 313 | #define <link linkend="V4L2-PIX-FMT-Y41P">V4L2_PIX_FMT_Y41P</link> v4l2_fourcc('Y', '4', '1', 'P') /* 12 YUV 4:1:1 */ | ||
| 314 | #define <link linkend="V4L2-PIX-FMT-YUV444">V4L2_PIX_FMT_YUV444</link> v4l2_fourcc('Y', '4', '4', '4') /* 16 xxxxyyyy uuuuvvvv */ | ||
| 315 | #define <link linkend="V4L2-PIX-FMT-YUV555">V4L2_PIX_FMT_YUV555</link> v4l2_fourcc('Y', 'U', 'V', 'O') /* 16 YUV-5-5-5 */ | ||
| 316 | #define <link linkend="V4L2-PIX-FMT-YUV565">V4L2_PIX_FMT_YUV565</link> v4l2_fourcc('Y', 'U', 'V', 'P') /* 16 YUV-5-6-5 */ | ||
| 317 | #define <link linkend="V4L2-PIX-FMT-YUV32">V4L2_PIX_FMT_YUV32</link> v4l2_fourcc('Y', 'U', 'V', '4') /* 32 YUV-8-8-8-8 */ | ||
| 318 | #define <link linkend="V4L2-PIX-FMT-YUV410">V4L2_PIX_FMT_YUV410</link> v4l2_fourcc('Y', 'U', 'V', '9') /* 9 YUV 4:1:0 */ | ||
| 319 | #define <link linkend="V4L2-PIX-FMT-YUV420">V4L2_PIX_FMT_YUV420</link> v4l2_fourcc('Y', 'U', '1', '2') /* 12 YUV 4:2:0 */ | ||
| 320 | #define <link linkend="V4L2-PIX-FMT-HI240">V4L2_PIX_FMT_HI240</link> v4l2_fourcc('H', 'I', '2', '4') /* 8 8-bit color */ | ||
| 321 | #define <link linkend="V4L2-PIX-FMT-HM12">V4L2_PIX_FMT_HM12</link> v4l2_fourcc('H', 'M', '1', '2') /* 8 YUV 4:2:0 16x16 macroblocks */ | ||
| 322 | |||
| 323 | /* two planes -- one Y, one Cr + Cb interleaved */ | ||
| 324 | #define <link linkend="V4L2-PIX-FMT-NV12">V4L2_PIX_FMT_NV12</link> v4l2_fourcc('N', 'V', '1', '2') /* 12 Y/CbCr 4:2:0 */ | ||
| 325 | #define <link linkend="V4L2-PIX-FMT-NV21">V4L2_PIX_FMT_NV21</link> v4l2_fourcc('N', 'V', '2', '1') /* 12 Y/CrCb 4:2:0 */ | ||
| 326 | #define <link linkend="V4L2-PIX-FMT-NV16">V4L2_PIX_FMT_NV16</link> v4l2_fourcc('N', 'V', '1', '6') /* 16 Y/CbCr 4:2:2 */ | ||
| 327 | #define <link linkend="V4L2-PIX-FMT-NV61">V4L2_PIX_FMT_NV61</link> v4l2_fourcc('N', 'V', '6', '1') /* 16 Y/CrCb 4:2:2 */ | ||
| 328 | |||
| 329 | /* Bayer formats - see http://www.siliconimaging.com/RGB%20Bayer.htm */ | ||
| 330 | #define <link linkend="V4L2-PIX-FMT-SBGGR8">V4L2_PIX_FMT_SBGGR8</link> v4l2_fourcc('B', 'A', '8', '1') /* 8 BGBG.. GRGR.. */ | ||
| 331 | #define <link linkend="V4L2-PIX-FMT-SGBRG8">V4L2_PIX_FMT_SGBRG8</link> v4l2_fourcc('G', 'B', 'R', 'G') /* 8 GBGB.. RGRG.. */ | ||
| 332 | #define <link linkend="V4L2-PIX-FMT-SGRBG8">V4L2_PIX_FMT_SGRBG8</link> v4l2_fourcc('G', 'R', 'B', 'G') /* 8 GRGR.. BGBG.. */ | ||
| 333 | #define <link linkend="V4L2-PIX-FMT-SGRBG10">V4L2_PIX_FMT_SGRBG10</link> v4l2_fourcc('B', 'A', '1', '0') /* 10bit raw bayer */ | ||
| 334 | /* 10bit raw bayer DPCM compressed to 8 bits */ | ||
| 335 | #define <link linkend="V4L2-PIX-FMT-SGRBG10DPCM8">V4L2_PIX_FMT_SGRBG10DPCM8</link> v4l2_fourcc('B', 'D', '1', '0') | ||
| 336 | /* | ||
| 337 | * 10bit raw bayer, expanded to 16 bits | ||
| 338 | * xxxxrrrrrrrrrrxxxxgggggggggg xxxxggggggggggxxxxbbbbbbbbbb... | ||
| 339 | */ | ||
| 340 | #define <link linkend="V4L2-PIX-FMT-SBGGR16">V4L2_PIX_FMT_SBGGR16</link> v4l2_fourcc('B', 'Y', 'R', '2') /* 16 BGBG.. GRGR.. */ | ||
| 341 | |||
| 342 | /* compressed formats */ | ||
| 343 | #define <link linkend="V4L2-PIX-FMT-MJPEG">V4L2_PIX_FMT_MJPEG</link> v4l2_fourcc('M', 'J', 'P', 'G') /* Motion-JPEG */ | ||
| 344 | #define <link linkend="V4L2-PIX-FMT-JPEG">V4L2_PIX_FMT_JPEG</link> v4l2_fourcc('J', 'P', 'E', 'G') /* JFIF JPEG */ | ||
| 345 | #define <link linkend="V4L2-PIX-FMT-DV">V4L2_PIX_FMT_DV</link> v4l2_fourcc('d', 'v', 's', 'd') /* 1394 */ | ||
| 346 | #define <link linkend="V4L2-PIX-FMT-MPEG">V4L2_PIX_FMT_MPEG</link> v4l2_fourcc('M', 'P', 'E', 'G') /* MPEG-1/2/4 */ | ||
| 347 | |||
| 348 | /* Vendor-specific formats */ | ||
| 349 | #define <link linkend="V4L2-PIX-FMT-WNVA">V4L2_PIX_FMT_WNVA</link> v4l2_fourcc('W', 'N', 'V', 'A') /* Winnov hw compress */ | ||
| 350 | #define <link linkend="V4L2-PIX-FMT-SN9C10X">V4L2_PIX_FMT_SN9C10X</link> v4l2_fourcc('S', '9', '1', '0') /* SN9C10x compression */ | ||
| 351 | #define <link linkend="V4L2-PIX-FMT-SN9C20X-I420">V4L2_PIX_FMT_SN9C20X_I420</link> v4l2_fourcc('S', '9', '2', '0') /* SN9C20x YUV 4:2:0 */ | ||
| 352 | #define <link linkend="V4L2-PIX-FMT-PWC1">V4L2_PIX_FMT_PWC1</link> v4l2_fourcc('P', 'W', 'C', '1') /* pwc older webcam */ | ||
| 353 | #define <link linkend="V4L2-PIX-FMT-PWC2">V4L2_PIX_FMT_PWC2</link> v4l2_fourcc('P', 'W', 'C', '2') /* pwc newer webcam */ | ||
| 354 | #define <link linkend="V4L2-PIX-FMT-ET61X251">V4L2_PIX_FMT_ET61X251</link> v4l2_fourcc('E', '6', '2', '5') /* ET61X251 compression */ | ||
| 355 | #define <link linkend="V4L2-PIX-FMT-SPCA501">V4L2_PIX_FMT_SPCA501</link> v4l2_fourcc('S', '5', '0', '1') /* YUYV per line */ | ||
| 356 | #define <link linkend="V4L2-PIX-FMT-SPCA505">V4L2_PIX_FMT_SPCA505</link> v4l2_fourcc('S', '5', '0', '5') /* YYUV per line */ | ||
| 357 | #define <link linkend="V4L2-PIX-FMT-SPCA508">V4L2_PIX_FMT_SPCA508</link> v4l2_fourcc('S', '5', '0', '8') /* YUVY per line */ | ||
| 358 | #define <link linkend="V4L2-PIX-FMT-SPCA561">V4L2_PIX_FMT_SPCA561</link> v4l2_fourcc('S', '5', '6', '1') /* compressed GBRG bayer */ | ||
| 359 | #define <link linkend="V4L2-PIX-FMT-PAC207">V4L2_PIX_FMT_PAC207</link> v4l2_fourcc('P', '2', '0', '7') /* compressed BGGR bayer */ | ||
| 360 | #define <link linkend="V4L2-PIX-FMT-MR97310A">V4L2_PIX_FMT_MR97310A</link> v4l2_fourcc('M', '3', '1', '0') /* compressed BGGR bayer */ | ||
| 361 | #define <link linkend="V4L2-PIX-FMT-SQ905C">V4L2_PIX_FMT_SQ905C</link> v4l2_fourcc('9', '0', '5', 'C') /* compressed RGGB bayer */ | ||
| 362 | #define <link linkend="V4L2-PIX-FMT-PJPG">V4L2_PIX_FMT_PJPG</link> v4l2_fourcc('P', 'J', 'P', 'G') /* Pixart 73xx JPEG */ | ||
| 363 | #define <link linkend="V4L2-PIX-FMT-OV511">V4L2_PIX_FMT_OV511</link> v4l2_fourcc('O', '5', '1', '1') /* ov511 JPEG */ | ||
| 364 | #define <link linkend="V4L2-PIX-FMT-OV518">V4L2_PIX_FMT_OV518</link> v4l2_fourcc('O', '5', '1', '8') /* ov518 JPEG */ | ||
| 365 | #define <link linkend="V4L2-PIX-FMT-TM6000">V4L2_PIX_FMT_TM6000</link> v4l2_fourcc('T', 'M', '6', '0') /* tm5600/tm60x0 */ | ||
| 366 | |||
| 367 | /* | ||
| 368 | * F O R M A T E N U M E R A T I O N | ||
| 369 | */ | ||
| 370 | struct <link linkend="v4l2-fmtdesc">v4l2_fmtdesc</link> { | ||
| 371 | __u32 index; /* Format number */ | ||
| 372 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; /* buffer type */ | ||
| 373 | __u32 flags; | ||
| 374 | __u8 description[32]; /* Description string */ | ||
| 375 | __u32 pixelformat; /* Format fourcc */ | ||
| 376 | __u32 reserved[4]; | ||
| 377 | }; | ||
| 378 | |||
| 379 | #define V4L2_FMT_FLAG_COMPRESSED 0x0001 | ||
| 380 | #define V4L2_FMT_FLAG_EMULATED 0x0002 | ||
| 381 | |||
| 382 | #if 1 /*KEEP*/ | ||
| 383 | /* Experimental Frame Size and frame rate enumeration */ | ||
| 384 | /* | ||
| 385 | * F R A M E S I Z E E N U M E R A T I O N | ||
| 386 | */ | ||
| 387 | enum <link linkend="v4l2-frmsizetypes">v4l2_frmsizetypes</link> { | ||
| 388 | V4L2_FRMSIZE_TYPE_DISCRETE = 1, | ||
| 389 | V4L2_FRMSIZE_TYPE_CONTINUOUS = 2, | ||
| 390 | V4L2_FRMSIZE_TYPE_STEPWISE = 3, | ||
| 391 | }; | ||
| 392 | |||
| 393 | struct <link linkend="v4l2-frmsize-discrete">v4l2_frmsize_discrete</link> { | ||
| 394 | __u32 width; /* Frame width [pixel] */ | ||
| 395 | __u32 height; /* Frame height [pixel] */ | ||
| 396 | }; | ||
| 397 | |||
| 398 | struct <link linkend="v4l2-frmsize-stepwise">v4l2_frmsize_stepwise</link> { | ||
| 399 | __u32 min_width; /* Minimum frame width [pixel] */ | ||
| 400 | __u32 max_width; /* Maximum frame width [pixel] */ | ||
| 401 | __u32 step_width; /* Frame width step size [pixel] */ | ||
| 402 | __u32 min_height; /* Minimum frame height [pixel] */ | ||
| 403 | __u32 max_height; /* Maximum frame height [pixel] */ | ||
| 404 | __u32 step_height; /* Frame height step size [pixel] */ | ||
| 405 | }; | ||
| 406 | |||
| 407 | struct <link linkend="v4l2-frmsizeenum">v4l2_frmsizeenum</link> { | ||
| 408 | __u32 index; /* Frame size number */ | ||
| 409 | __u32 pixel_format; /* Pixel format */ | ||
| 410 | __u32 type; /* Frame size type the device supports. */ | ||
| 411 | |||
| 412 | union { /* Frame size */ | ||
| 413 | struct <link linkend="v4l2-frmsize-discrete">v4l2_frmsize_discrete</link> discrete; | ||
| 414 | struct <link linkend="v4l2-frmsize-stepwise">v4l2_frmsize_stepwise</link> stepwise; | ||
| 415 | }; | ||
| 416 | |||
| 417 | __u32 reserved[2]; /* Reserved space for future use */ | ||
| 418 | }; | ||
| 419 | |||
| 420 | /* | ||
| 421 | * F R A M E R A T E E N U M E R A T I O N | ||
| 422 | */ | ||
| 423 | enum <link linkend="v4l2-frmivaltypes">v4l2_frmivaltypes</link> { | ||
| 424 | V4L2_FRMIVAL_TYPE_DISCRETE = 1, | ||
| 425 | V4L2_FRMIVAL_TYPE_CONTINUOUS = 2, | ||
| 426 | V4L2_FRMIVAL_TYPE_STEPWISE = 3, | ||
| 427 | }; | ||
| 428 | |||
| 429 | struct <link linkend="v4l2-frmival-stepwise">v4l2_frmival_stepwise</link> { | ||
| 430 | struct <link linkend="v4l2-fract">v4l2_fract</link> min; /* Minimum frame interval [s] */ | ||
| 431 | struct <link linkend="v4l2-fract">v4l2_fract</link> max; /* Maximum frame interval [s] */ | ||
| 432 | struct <link linkend="v4l2-fract">v4l2_fract</link> step; /* Frame interval step size [s] */ | ||
| 433 | }; | ||
| 434 | |||
| 435 | struct <link linkend="v4l2-frmivalenum">v4l2_frmivalenum</link> { | ||
| 436 | __u32 index; /* Frame format index */ | ||
| 437 | __u32 pixel_format; /* Pixel format */ | ||
| 438 | __u32 width; /* Frame width */ | ||
| 439 | __u32 height; /* Frame height */ | ||
| 440 | __u32 type; /* Frame interval type the device supports. */ | ||
| 441 | |||
| 442 | union { /* Frame interval */ | ||
| 443 | struct <link linkend="v4l2-fract">v4l2_fract</link> discrete; | ||
| 444 | struct <link linkend="v4l2-frmival-stepwise">v4l2_frmival_stepwise</link> stepwise; | ||
| 445 | }; | ||
| 446 | |||
| 447 | __u32 reserved[2]; /* Reserved space for future use */ | ||
| 448 | }; | ||
| 449 | #endif | ||
| 450 | |||
| 451 | /* | ||
| 452 | * T I M E C O D E | ||
| 453 | */ | ||
| 454 | struct <link linkend="v4l2-timecode">v4l2_timecode</link> { | ||
| 455 | __u32 type; | ||
| 456 | __u32 flags; | ||
| 457 | __u8 frames; | ||
| 458 | __u8 seconds; | ||
| 459 | __u8 minutes; | ||
| 460 | __u8 hours; | ||
| 461 | __u8 userbits[4]; | ||
| 462 | }; | ||
| 463 | |||
| 464 | /* Type */ | ||
| 465 | #define V4L2_TC_TYPE_24FPS 1 | ||
| 466 | #define V4L2_TC_TYPE_25FPS 2 | ||
| 467 | #define V4L2_TC_TYPE_30FPS 3 | ||
| 468 | #define V4L2_TC_TYPE_50FPS 4 | ||
| 469 | #define V4L2_TC_TYPE_60FPS 5 | ||
| 470 | |||
| 471 | /* Flags */ | ||
| 472 | #define V4L2_TC_FLAG_DROPFRAME 0x0001 /* "drop-frame" mode */ | ||
| 473 | #define V4L2_TC_FLAG_COLORFRAME 0x0002 | ||
| 474 | #define V4L2_TC_USERBITS_field 0x000C | ||
| 475 | #define V4L2_TC_USERBITS_USERDEFINED 0x0000 | ||
| 476 | #define V4L2_TC_USERBITS_8BITCHARS 0x0008 | ||
| 477 | /* The above is based on SMPTE timecodes */ | ||
| 478 | |||
| 479 | struct <link linkend="v4l2-jpegcompression">v4l2_jpegcompression</link> { | ||
| 480 | int quality; | ||
| 481 | |||
| 482 | int APPn; /* Number of APP segment to be written, | ||
| 483 | * must be 0..15 */ | ||
| 484 | int APP_len; /* Length of data in JPEG APPn segment */ | ||
| 485 | char APP_data[60]; /* Data in the JPEG APPn segment. */ | ||
| 486 | |||
| 487 | int COM_len; /* Length of data in JPEG COM segment */ | ||
| 488 | char COM_data[60]; /* Data in JPEG COM segment */ | ||
| 489 | |||
| 490 | __u32 jpeg_markers; /* Which markers should go into the JPEG | ||
| 491 | * output. Unless you exactly know what | ||
| 492 | * you do, leave them untouched. | ||
| 493 | * Inluding less markers will make the | ||
| 494 | * resulting code smaller, but there will | ||
| 495 | * be fewer aplications which can read it. | ||
| 496 | * The presence of the APP and COM marker | ||
| 497 | * is influenced by APP_len and COM_len | ||
| 498 | * ONLY, not by this property! */ | ||
| 499 | |||
| 500 | #define V4L2_JPEG_MARKER_DHT (1<<3) /* Define Huffman Tables */ | ||
| 501 | #define V4L2_JPEG_MARKER_DQT (1<<4) /* Define Quantization Tables */ | ||
| 502 | #define V4L2_JPEG_MARKER_DRI (1<<5) /* Define Restart Interval */ | ||
| 503 | #define V4L2_JPEG_MARKER_COM (1<<6) /* Comment segment */ | ||
| 504 | #define V4L2_JPEG_MARKER_APP (1<<7) /* App segment, driver will | ||
| 505 | * allways use APP0 */ | ||
| 506 | }; | ||
| 507 | |||
| 508 | /* | ||
| 509 | * M E M O R Y - M A P P I N G B U F F E R S | ||
| 510 | */ | ||
| 511 | struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> { | ||
| 512 | __u32 count; | ||
| 513 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 514 | enum <link linkend="v4l2-memory">v4l2_memory</link> memory; | ||
| 515 | __u32 reserved[2]; | ||
| 516 | }; | ||
| 517 | |||
| 518 | struct <link linkend="v4l2-buffer">v4l2_buffer</link> { | ||
| 519 | __u32 index; | ||
| 520 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 521 | __u32 bytesused; | ||
| 522 | __u32 flags; | ||
| 523 | enum <link linkend="v4l2-field">v4l2_field</link> field; | ||
| 524 | struct timeval timestamp; | ||
| 525 | struct <link linkend="v4l2-timecode">v4l2_timecode</link> timecode; | ||
| 526 | __u32 sequence; | ||
| 527 | |||
| 528 | /* memory location */ | ||
| 529 | enum <link linkend="v4l2-memory">v4l2_memory</link> memory; | ||
| 530 | union { | ||
| 531 | __u32 offset; | ||
| 532 | unsigned long userptr; | ||
| 533 | } m; | ||
| 534 | __u32 length; | ||
| 535 | __u32 input; | ||
| 536 | __u32 reserved; | ||
| 537 | }; | ||
| 538 | |||
| 539 | /* Flags for 'flags' field */ | ||
| 540 | #define V4L2_BUF_FLAG_MAPPED 0x0001 /* Buffer is mapped (flag) */ | ||
| 541 | #define V4L2_BUF_FLAG_QUEUED 0x0002 /* Buffer is queued for processing */ | ||
| 542 | #define V4L2_BUF_FLAG_DONE 0x0004 /* Buffer is ready */ | ||
| 543 | #define V4L2_BUF_FLAG_KEYFRAME 0x0008 /* Image is a keyframe (I-frame) */ | ||
| 544 | #define V4L2_BUF_FLAG_PFRAME 0x0010 /* Image is a P-frame */ | ||
| 545 | #define V4L2_BUF_FLAG_BFRAME 0x0020 /* Image is a B-frame */ | ||
| 546 | #define V4L2_BUF_FLAG_TIMECODE 0x0100 /* timecode field is valid */ | ||
| 547 | #define V4L2_BUF_FLAG_INPUT 0x0200 /* input field is valid */ | ||
| 548 | |||
| 549 | /* | ||
| 550 | * O V E R L A Y P R E V I E W | ||
| 551 | */ | ||
| 552 | struct <link linkend="v4l2-framebuffer">v4l2_framebuffer</link> { | ||
| 553 | __u32 capability; | ||
| 554 | __u32 flags; | ||
| 555 | /* FIXME: in theory we should pass something like PCI device + memory | ||
| 556 | * region + offset instead of some physical address */ | ||
| 557 | void *base; | ||
| 558 | struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> fmt; | ||
| 559 | }; | ||
| 560 | /* Flags for the 'capability' field. Read only */ | ||
| 561 | #define V4L2_FBUF_CAP_EXTERNOVERLAY 0x0001 | ||
| 562 | #define V4L2_FBUF_CAP_CHROMAKEY 0x0002 | ||
| 563 | #define V4L2_FBUF_CAP_LIST_CLIPPING 0x0004 | ||
| 564 | #define V4L2_FBUF_CAP_BITMAP_CLIPPING 0x0008 | ||
| 565 | #define V4L2_FBUF_CAP_LOCAL_ALPHA 0x0010 | ||
| 566 | #define V4L2_FBUF_CAP_GLOBAL_ALPHA 0x0020 | ||
| 567 | #define V4L2_FBUF_CAP_LOCAL_INV_ALPHA 0x0040 | ||
| 568 | /* Flags for the 'flags' field. */ | ||
| 569 | #define V4L2_FBUF_FLAG_PRIMARY 0x0001 | ||
| 570 | #define V4L2_FBUF_FLAG_OVERLAY 0x0002 | ||
| 571 | #define V4L2_FBUF_FLAG_CHROMAKEY 0x0004 | ||
| 572 | #define V4L2_FBUF_FLAG_LOCAL_ALPHA 0x0008 | ||
| 573 | #define V4L2_FBUF_FLAG_GLOBAL_ALPHA 0x0010 | ||
| 574 | #define V4L2_FBUF_FLAG_LOCAL_INV_ALPHA 0x0020 | ||
| 575 | |||
| 576 | struct <link linkend="v4l2-clip">v4l2_clip</link> { | ||
| 577 | struct <link linkend="v4l2-rect">v4l2_rect</link> c; | ||
| 578 | struct <link linkend="v4l2-clip">v4l2_clip</link> __user *next; | ||
| 579 | }; | ||
| 580 | |||
| 581 | struct <link linkend="v4l2-window">v4l2_window</link> { | ||
| 582 | struct <link linkend="v4l2-rect">v4l2_rect</link> w; | ||
| 583 | enum <link linkend="v4l2-field">v4l2_field</link> field; | ||
| 584 | __u32 chromakey; | ||
| 585 | struct <link linkend="v4l2-clip">v4l2_clip</link> __user *clips; | ||
| 586 | __u32 clipcount; | ||
| 587 | void __user *bitmap; | ||
| 588 | __u8 global_alpha; | ||
| 589 | }; | ||
| 590 | |||
| 591 | /* | ||
| 592 | * C A P T U R E P A R A M E T E R S | ||
| 593 | */ | ||
| 594 | struct <link linkend="v4l2-captureparm">v4l2_captureparm</link> { | ||
| 595 | __u32 capability; /* Supported modes */ | ||
| 596 | __u32 capturemode; /* Current mode */ | ||
| 597 | struct <link linkend="v4l2-fract">v4l2_fract</link> timeperframe; /* Time per frame in .1us units */ | ||
| 598 | __u32 extendedmode; /* Driver-specific extensions */ | ||
| 599 | __u32 readbuffers; /* # of buffers for read */ | ||
| 600 | __u32 reserved[4]; | ||
| 601 | }; | ||
| 602 | |||
| 603 | /* Flags for 'capability' and 'capturemode' fields */ | ||
| 604 | #define V4L2_MODE_HIGHQUALITY 0x0001 /* High quality imaging mode */ | ||
| 605 | #define V4L2_CAP_TIMEPERFRAME 0x1000 /* timeperframe field is supported */ | ||
| 606 | |||
| 607 | struct <link linkend="v4l2-outputparm">v4l2_outputparm</link> { | ||
| 608 | __u32 capability; /* Supported modes */ | ||
| 609 | __u32 outputmode; /* Current mode */ | ||
| 610 | struct <link linkend="v4l2-fract">v4l2_fract</link> timeperframe; /* Time per frame in seconds */ | ||
| 611 | __u32 extendedmode; /* Driver-specific extensions */ | ||
| 612 | __u32 writebuffers; /* # of buffers for write */ | ||
| 613 | __u32 reserved[4]; | ||
| 614 | }; | ||
| 615 | |||
| 616 | /* | ||
| 617 | * I N P U T I M A G E C R O P P I N G | ||
| 618 | */ | ||
| 619 | struct <link linkend="v4l2-cropcap">v4l2_cropcap</link> { | ||
| 620 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 621 | struct <link linkend="v4l2-rect">v4l2_rect</link> bounds; | ||
| 622 | struct <link linkend="v4l2-rect">v4l2_rect</link> defrect; | ||
| 623 | struct <link linkend="v4l2-fract">v4l2_fract</link> pixelaspect; | ||
| 624 | }; | ||
| 625 | |||
| 626 | struct <link linkend="v4l2-crop">v4l2_crop</link> { | ||
| 627 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 628 | struct <link linkend="v4l2-rect">v4l2_rect</link> c; | ||
| 629 | }; | ||
| 630 | |||
| 631 | /* | ||
| 632 | * A N A L O G V I D E O S T A N D A R D | ||
| 633 | */ | ||
| 634 | |||
| 635 | typedef __u64 v4l2_std_id; | ||
| 636 | |||
| 637 | /* one bit for each */ | ||
| 638 | #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) | ||
| 639 | #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002) | ||
| 640 | #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004) | ||
| 641 | #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008) | ||
| 642 | #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010) | ||
| 643 | #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020) | ||
| 644 | #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040) | ||
| 645 | #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080) | ||
| 646 | |||
| 647 | #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100) | ||
| 648 | #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200) | ||
| 649 | #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400) | ||
| 650 | #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800) | ||
| 651 | |||
| 652 | #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) | ||
| 653 | #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) | ||
| 654 | #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000) | ||
| 655 | #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) | ||
| 656 | |||
| 657 | #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000) | ||
| 658 | #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000) | ||
| 659 | #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000) | ||
| 660 | #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000) | ||
| 661 | #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000) | ||
| 662 | #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000) | ||
| 663 | #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000) | ||
| 664 | #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000) | ||
| 665 | |||
| 666 | /* ATSC/HDTV */ | ||
| 667 | #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000) | ||
| 668 | #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000) | ||
| 669 | |||
| 670 | /* FIXME: | ||
| 671 | Although std_id is 64 bits, there is an issue on PPC32 architecture that | ||
| 672 | makes switch(__u64) to break. So, there's a hack on v4l2-common.c rounding | ||
| 673 | this value to 32 bits. | ||
| 674 | As, currently, the max value is for V4L2_STD_ATSC_16_VSB (30 bits wide), | ||
| 675 | it should work fine. However, if needed to add more than two standards, | ||
| 676 | v4l2-common.c should be fixed. | ||
| 677 | */ | ||
| 678 | |||
| 679 | /* some merged standards */ | ||
| 680 | #define V4L2_STD_MN (V4L2_STD_PAL_M|V4L2_STD_PAL_N|V4L2_STD_PAL_Nc|V4L2_STD_NTSC) | ||
| 681 | #define V4L2_STD_B (V4L2_STD_PAL_B|V4L2_STD_PAL_B1|V4L2_STD_SECAM_B) | ||
| 682 | #define V4L2_STD_GH (V4L2_STD_PAL_G|V4L2_STD_PAL_H|V4L2_STD_SECAM_G|V4L2_STD_SECAM_H) | ||
| 683 | #define V4L2_STD_DK (V4L2_STD_PAL_DK|V4L2_STD_SECAM_DK) | ||
| 684 | |||
| 685 | /* some common needed stuff */ | ||
| 686 | #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\ | ||
| 687 | V4L2_STD_PAL_B1 |\ | ||
| 688 | V4L2_STD_PAL_G) | ||
| 689 | #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\ | ||
| 690 | V4L2_STD_PAL_D1 |\ | ||
| 691 | V4L2_STD_PAL_K) | ||
| 692 | #define V4L2_STD_PAL (V4L2_STD_PAL_BG |\ | ||
| 693 | V4L2_STD_PAL_DK |\ | ||
| 694 | V4L2_STD_PAL_H |\ | ||
| 695 | V4L2_STD_PAL_I) | ||
| 696 | #define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\ | ||
| 697 | V4L2_STD_NTSC_M_JP |\ | ||
| 698 | V4L2_STD_NTSC_M_KR) | ||
| 699 | #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |\ | ||
| 700 | V4L2_STD_SECAM_K |\ | ||
| 701 | V4L2_STD_SECAM_K1) | ||
| 702 | #define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\ | ||
| 703 | V4L2_STD_SECAM_G |\ | ||
| 704 | V4L2_STD_SECAM_H |\ | ||
| 705 | V4L2_STD_SECAM_DK |\ | ||
| 706 | V4L2_STD_SECAM_L |\ | ||
| 707 | V4L2_STD_SECAM_LC) | ||
| 708 | |||
| 709 | #define V4L2_STD_525_60 (V4L2_STD_PAL_M |\ | ||
| 710 | V4L2_STD_PAL_60 |\ | ||
| 711 | V4L2_STD_NTSC |\ | ||
| 712 | V4L2_STD_NTSC_443) | ||
| 713 | #define V4L2_STD_625_50 (V4L2_STD_PAL |\ | ||
| 714 | V4L2_STD_PAL_N |\ | ||
| 715 | V4L2_STD_PAL_Nc |\ | ||
| 716 | V4L2_STD_SECAM) | ||
| 717 | #define V4L2_STD_ATSC (V4L2_STD_ATSC_8_VSB |\ | ||
| 718 | V4L2_STD_ATSC_16_VSB) | ||
| 719 | |||
| 720 | #define V4L2_STD_UNKNOWN 0 | ||
| 721 | #define V4L2_STD_ALL (V4L2_STD_525_60 |\ | ||
| 722 | V4L2_STD_625_50) | ||
| 723 | |||
| 724 | struct <link linkend="v4l2-standard">v4l2_standard</link> { | ||
| 725 | __u32 index; | ||
| 726 | v4l2_std_id id; | ||
| 727 | __u8 name[24]; | ||
| 728 | struct <link linkend="v4l2-fract">v4l2_fract</link> frameperiod; /* Frames, not fields */ | ||
| 729 | __u32 framelines; | ||
| 730 | __u32 reserved[4]; | ||
| 731 | }; | ||
| 732 | |||
| 733 | /* | ||
| 734 | * V I D E O I N P U T S | ||
| 735 | */ | ||
| 736 | struct <link linkend="v4l2-input">v4l2_input</link> { | ||
| 737 | __u32 index; /* Which input */ | ||
| 738 | __u8 name[32]; /* Label */ | ||
| 739 | __u32 type; /* Type of input */ | ||
| 740 | __u32 audioset; /* Associated audios (bitfield) */ | ||
| 741 | __u32 tuner; /* Associated tuner */ | ||
| 742 | v4l2_std_id std; | ||
| 743 | __u32 status; | ||
| 744 | __u32 reserved[4]; | ||
| 745 | }; | ||
| 746 | |||
| 747 | /* Values for the 'type' field */ | ||
| 748 | #define V4L2_INPUT_TYPE_TUNER 1 | ||
| 749 | #define V4L2_INPUT_TYPE_CAMERA 2 | ||
| 750 | |||
| 751 | /* field 'status' - general */ | ||
| 752 | #define V4L2_IN_ST_NO_POWER 0x00000001 /* Attached device is off */ | ||
| 753 | #define V4L2_IN_ST_NO_SIGNAL 0x00000002 | ||
| 754 | #define V4L2_IN_ST_NO_COLOR 0x00000004 | ||
| 755 | |||
| 756 | /* field 'status' - sensor orientation */ | ||
| 757 | /* If sensor is mounted upside down set both bits */ | ||
| 758 | #define V4L2_IN_ST_HFLIP 0x00000010 /* Frames are flipped horizontally */ | ||
| 759 | #define V4L2_IN_ST_VFLIP 0x00000020 /* Frames are flipped vertically */ | ||
| 760 | |||
| 761 | /* field 'status' - analog */ | ||
| 762 | #define V4L2_IN_ST_NO_H_LOCK 0x00000100 /* No horizontal sync lock */ | ||
| 763 | #define V4L2_IN_ST_COLOR_KILL 0x00000200 /* Color killer is active */ | ||
| 764 | |||
| 765 | /* field 'status' - digital */ | ||
| 766 | #define V4L2_IN_ST_NO_SYNC 0x00010000 /* No synchronization lock */ | ||
| 767 | #define V4L2_IN_ST_NO_EQU 0x00020000 /* No equalizer lock */ | ||
| 768 | #define V4L2_IN_ST_NO_CARRIER 0x00040000 /* Carrier recovery failed */ | ||
| 769 | |||
| 770 | /* field 'status' - VCR and set-top box */ | ||
| 771 | #define V4L2_IN_ST_MACROVISION 0x01000000 /* Macrovision detected */ | ||
| 772 | #define V4L2_IN_ST_NO_ACCESS 0x02000000 /* Conditional access denied */ | ||
| 773 | #define V4L2_IN_ST_VTR 0x04000000 /* VTR time constant */ | ||
| 774 | |||
| 775 | /* | ||
| 776 | * V I D E O O U T P U T S | ||
| 777 | */ | ||
| 778 | struct <link linkend="v4l2-output">v4l2_output</link> { | ||
| 779 | __u32 index; /* Which output */ | ||
| 780 | __u8 name[32]; /* Label */ | ||
| 781 | __u32 type; /* Type of output */ | ||
| 782 | __u32 audioset; /* Associated audios (bitfield) */ | ||
| 783 | __u32 modulator; /* Associated modulator */ | ||
| 784 | v4l2_std_id std; | ||
| 785 | __u32 reserved[4]; | ||
| 786 | }; | ||
| 787 | /* Values for the 'type' field */ | ||
| 788 | #define V4L2_OUTPUT_TYPE_MODULATOR 1 | ||
| 789 | #define V4L2_OUTPUT_TYPE_ANALOG 2 | ||
| 790 | #define V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY 3 | ||
| 791 | |||
| 792 | /* | ||
| 793 | * C O N T R O L S | ||
| 794 | */ | ||
| 795 | struct <link linkend="v4l2-control">v4l2_control</link> { | ||
| 796 | __u32 id; | ||
| 797 | __s32 value; | ||
| 798 | }; | ||
| 799 | |||
| 800 | struct <link linkend="v4l2-ext-control">v4l2_ext_control</link> { | ||
| 801 | __u32 id; | ||
| 802 | __u32 size; | ||
| 803 | __u32 reserved2[1]; | ||
| 804 | union { | ||
| 805 | __s32 value; | ||
| 806 | __s64 value64; | ||
| 807 | char *string; | ||
| 808 | }; | ||
| 809 | } __attribute__ ((packed)); | ||
| 810 | |||
| 811 | struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link> { | ||
| 812 | __u32 ctrl_class; | ||
| 813 | __u32 count; | ||
| 814 | __u32 error_idx; | ||
| 815 | __u32 reserved[2]; | ||
| 816 | struct <link linkend="v4l2-ext-control">v4l2_ext_control</link> *controls; | ||
| 817 | }; | ||
| 818 | |||
| 819 | /* Values for ctrl_class field */ | ||
| 820 | #define V4L2_CTRL_CLASS_USER 0x00980000 /* Old-style 'user' controls */ | ||
| 821 | #define V4L2_CTRL_CLASS_MPEG 0x00990000 /* MPEG-compression controls */ | ||
| 822 | #define V4L2_CTRL_CLASS_CAMERA 0x009a0000 /* Camera class controls */ | ||
| 823 | #define V4L2_CTRL_CLASS_FM_TX 0x009b0000 /* FM Modulator control class */ | ||
| 824 | |||
| 825 | #define V4L2_CTRL_ID_MASK (0x0fffffff) | ||
| 826 | #define V4L2_CTRL_ID2CLASS(id) ((id) & 0x0fff0000UL) | ||
| 827 | #define V4L2_CTRL_DRIVER_PRIV(id) (((id) & 0xffff) >= 0x1000) | ||
| 828 | |||
| 829 | /* Used in the VIDIOC_QUERYCTRL ioctl for querying controls */ | ||
| 830 | struct <link linkend="v4l2-queryctrl">v4l2_queryctrl</link> { | ||
| 831 | __u32 id; | ||
| 832 | enum <link linkend="v4l2-ctrl-type">v4l2_ctrl_type</link> type; | ||
| 833 | __u8 name[32]; /* Whatever */ | ||
| 834 | __s32 minimum; /* Note signedness */ | ||
| 835 | __s32 maximum; | ||
| 836 | __s32 step; | ||
| 837 | __s32 default_value; | ||
| 838 | __u32 flags; | ||
| 839 | __u32 reserved[2]; | ||
| 840 | }; | ||
| 841 | |||
| 842 | /* Used in the VIDIOC_QUERYMENU ioctl for querying menu items */ | ||
| 843 | struct <link linkend="v4l2-querymenu">v4l2_querymenu</link> { | ||
| 844 | __u32 id; | ||
| 845 | __u32 index; | ||
| 846 | __u8 name[32]; /* Whatever */ | ||
| 847 | __u32 reserved; | ||
| 848 | }; | ||
| 849 | |||
| 850 | /* Control flags */ | ||
| 851 | #define V4L2_CTRL_FLAG_DISABLED 0x0001 | ||
| 852 | #define V4L2_CTRL_FLAG_GRABBED 0x0002 | ||
| 853 | #define V4L2_CTRL_FLAG_READ_ONLY 0x0004 | ||
| 854 | #define V4L2_CTRL_FLAG_UPDATE 0x0008 | ||
| 855 | #define V4L2_CTRL_FLAG_INACTIVE 0x0010 | ||
| 856 | #define V4L2_CTRL_FLAG_SLIDER 0x0020 | ||
| 857 | #define V4L2_CTRL_FLAG_WRITE_ONLY 0x0040 | ||
| 858 | |||
| 859 | /* Query flag, to be ORed with the control ID */ | ||
| 860 | #define V4L2_CTRL_FLAG_NEXT_CTRL 0x80000000 | ||
| 861 | |||
| 862 | /* User-class control IDs defined by V4L2 */ | ||
| 863 | #define V4L2_CID_BASE (V4L2_CTRL_CLASS_USER | 0x900) | ||
| 864 | #define V4L2_CID_USER_BASE V4L2_CID_BASE | ||
| 865 | /* IDs reserved for driver specific controls */ | ||
| 866 | #define V4L2_CID_PRIVATE_BASE 0x08000000 | ||
| 867 | |||
| 868 | #define V4L2_CID_USER_CLASS (V4L2_CTRL_CLASS_USER | 1) | ||
| 869 | #define V4L2_CID_BRIGHTNESS (V4L2_CID_BASE+0) | ||
| 870 | #define V4L2_CID_CONTRAST (V4L2_CID_BASE+1) | ||
| 871 | #define V4L2_CID_SATURATION (V4L2_CID_BASE+2) | ||
| 872 | #define V4L2_CID_HUE (V4L2_CID_BASE+3) | ||
| 873 | #define V4L2_CID_AUDIO_VOLUME (V4L2_CID_BASE+5) | ||
| 874 | #define V4L2_CID_AUDIO_BALANCE (V4L2_CID_BASE+6) | ||
| 875 | #define V4L2_CID_AUDIO_BASS (V4L2_CID_BASE+7) | ||
| 876 | #define V4L2_CID_AUDIO_TREBLE (V4L2_CID_BASE+8) | ||
| 877 | #define V4L2_CID_AUDIO_MUTE (V4L2_CID_BASE+9) | ||
| 878 | #define V4L2_CID_AUDIO_LOUDNESS (V4L2_CID_BASE+10) | ||
| 879 | #define V4L2_CID_BLACK_LEVEL (V4L2_CID_BASE+11) /* Deprecated */ | ||
| 880 | #define V4L2_CID_AUTO_WHITE_BALANCE (V4L2_CID_BASE+12) | ||
| 881 | #define V4L2_CID_DO_WHITE_BALANCE (V4L2_CID_BASE+13) | ||
| 882 | #define V4L2_CID_RED_BALANCE (V4L2_CID_BASE+14) | ||
| 883 | #define V4L2_CID_BLUE_BALANCE (V4L2_CID_BASE+15) | ||
| 884 | #define V4L2_CID_GAMMA (V4L2_CID_BASE+16) | ||
| 885 | #define V4L2_CID_WHITENESS (V4L2_CID_GAMMA) /* Deprecated */ | ||
| 886 | #define V4L2_CID_EXPOSURE (V4L2_CID_BASE+17) | ||
| 887 | #define V4L2_CID_AUTOGAIN (V4L2_CID_BASE+18) | ||
| 888 | #define V4L2_CID_GAIN (V4L2_CID_BASE+19) | ||
| 889 | #define V4L2_CID_HFLIP (V4L2_CID_BASE+20) | ||
| 890 | #define V4L2_CID_VFLIP (V4L2_CID_BASE+21) | ||
| 891 | |||
| 892 | /* Deprecated; use V4L2_CID_PAN_RESET and V4L2_CID_TILT_RESET */ | ||
| 893 | #define V4L2_CID_HCENTER (V4L2_CID_BASE+22) | ||
| 894 | #define V4L2_CID_VCENTER (V4L2_CID_BASE+23) | ||
| 895 | |||
| 896 | #define V4L2_CID_POWER_LINE_FREQUENCY (V4L2_CID_BASE+24) | ||
| 897 | enum <link linkend="v4l2-power-line-frequency">v4l2_power_line_frequency</link> { | ||
| 898 | V4L2_CID_POWER_LINE_FREQUENCY_DISABLED = 0, | ||
| 899 | V4L2_CID_POWER_LINE_FREQUENCY_50HZ = 1, | ||
| 900 | V4L2_CID_POWER_LINE_FREQUENCY_60HZ = 2, | ||
| 901 | }; | ||
| 902 | #define V4L2_CID_HUE_AUTO (V4L2_CID_BASE+25) | ||
| 903 | #define V4L2_CID_WHITE_BALANCE_TEMPERATURE (V4L2_CID_BASE+26) | ||
| 904 | #define V4L2_CID_SHARPNESS (V4L2_CID_BASE+27) | ||
| 905 | #define V4L2_CID_BACKLIGHT_COMPENSATION (V4L2_CID_BASE+28) | ||
| 906 | #define V4L2_CID_CHROMA_AGC (V4L2_CID_BASE+29) | ||
| 907 | #define V4L2_CID_COLOR_KILLER (V4L2_CID_BASE+30) | ||
| 908 | #define V4L2_CID_COLORFX (V4L2_CID_BASE+31) | ||
| 909 | enum <link linkend="v4l2-colorfx">v4l2_colorfx</link> { | ||
| 910 | V4L2_COLORFX_NONE = 0, | ||
| 911 | V4L2_COLORFX_BW = 1, | ||
| 912 | V4L2_COLORFX_SEPIA = 2, | ||
| 913 | }; | ||
| 914 | #define V4L2_CID_AUTOBRIGHTNESS (V4L2_CID_BASE+32) | ||
| 915 | #define V4L2_CID_BAND_STOP_FILTER (V4L2_CID_BASE+33) | ||
| 916 | |||
| 917 | /* last CID + 1 */ | ||
| 918 | #define V4L2_CID_LASTP1 (V4L2_CID_BASE+34) | ||
| 919 | |||
| 920 | /* MPEG-class control IDs defined by V4L2 */ | ||
| 921 | #define V4L2_CID_MPEG_BASE (V4L2_CTRL_CLASS_MPEG | 0x900) | ||
| 922 | #define V4L2_CID_MPEG_CLASS (V4L2_CTRL_CLASS_MPEG | 1) | ||
| 923 | |||
| 924 | /* MPEG streams */ | ||
| 925 | #define V4L2_CID_MPEG_STREAM_TYPE (V4L2_CID_MPEG_BASE+0) | ||
| 926 | enum <link linkend="v4l2-mpeg-stream-type">v4l2_mpeg_stream_type</link> { | ||
| 927 | V4L2_MPEG_STREAM_TYPE_MPEG2_PS = 0, /* MPEG-2 program stream */ | ||
| 928 | V4L2_MPEG_STREAM_TYPE_MPEG2_TS = 1, /* MPEG-2 transport stream */ | ||
| 929 | V4L2_MPEG_STREAM_TYPE_MPEG1_SS = 2, /* MPEG-1 system stream */ | ||
| 930 | V4L2_MPEG_STREAM_TYPE_MPEG2_DVD = 3, /* MPEG-2 DVD-compatible stream */ | ||
| 931 | V4L2_MPEG_STREAM_TYPE_MPEG1_VCD = 4, /* MPEG-1 VCD-compatible stream */ | ||
| 932 | V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD = 5, /* MPEG-2 SVCD-compatible stream */ | ||
| 933 | }; | ||
| 934 | #define V4L2_CID_MPEG_STREAM_PID_PMT (V4L2_CID_MPEG_BASE+1) | ||
| 935 | #define V4L2_CID_MPEG_STREAM_PID_AUDIO (V4L2_CID_MPEG_BASE+2) | ||
| 936 | #define V4L2_CID_MPEG_STREAM_PID_VIDEO (V4L2_CID_MPEG_BASE+3) | ||
| 937 | #define V4L2_CID_MPEG_STREAM_PID_PCR (V4L2_CID_MPEG_BASE+4) | ||
| 938 | #define V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (V4L2_CID_MPEG_BASE+5) | ||
| 939 | #define V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (V4L2_CID_MPEG_BASE+6) | ||
| 940 | #define V4L2_CID_MPEG_STREAM_VBI_FMT (V4L2_CID_MPEG_BASE+7) | ||
| 941 | enum <link linkend="v4l2-mpeg-stream-vbi-fmt">v4l2_mpeg_stream_vbi_fmt</link> { | ||
| 942 | V4L2_MPEG_STREAM_VBI_FMT_NONE = 0, /* No VBI in the MPEG stream */ | ||
| 943 | V4L2_MPEG_STREAM_VBI_FMT_IVTV = 1, /* VBI in private packets, IVTV format */ | ||
| 944 | }; | ||
| 945 | |||
| 946 | /* MPEG audio */ | ||
| 947 | #define V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ (V4L2_CID_MPEG_BASE+100) | ||
| 948 | enum <link linkend="v4l2-mpeg-audio-sampling-freq">v4l2_mpeg_audio_sampling_freq</link> { | ||
| 949 | V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100 = 0, | ||
| 950 | V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000 = 1, | ||
| 951 | V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000 = 2, | ||
| 952 | }; | ||
| 953 | #define V4L2_CID_MPEG_AUDIO_ENCODING (V4L2_CID_MPEG_BASE+101) | ||
| 954 | enum <link linkend="v4l2-mpeg-audio-encoding">v4l2_mpeg_audio_encoding</link> { | ||
| 955 | V4L2_MPEG_AUDIO_ENCODING_LAYER_1 = 0, | ||
| 956 | V4L2_MPEG_AUDIO_ENCODING_LAYER_2 = 1, | ||
| 957 | V4L2_MPEG_AUDIO_ENCODING_LAYER_3 = 2, | ||
| 958 | V4L2_MPEG_AUDIO_ENCODING_AAC = 3, | ||
| 959 | V4L2_MPEG_AUDIO_ENCODING_AC3 = 4, | ||
| 960 | }; | ||
| 961 | #define V4L2_CID_MPEG_AUDIO_L1_BITRATE (V4L2_CID_MPEG_BASE+102) | ||
| 962 | enum <link linkend="v4l2-mpeg-audio-l1-bitrate">v4l2_mpeg_audio_l1_bitrate</link> { | ||
| 963 | V4L2_MPEG_AUDIO_L1_BITRATE_32K = 0, | ||
| 964 | V4L2_MPEG_AUDIO_L1_BITRATE_64K = 1, | ||
| 965 | V4L2_MPEG_AUDIO_L1_BITRATE_96K = 2, | ||
| 966 | V4L2_MPEG_AUDIO_L1_BITRATE_128K = 3, | ||
| 967 | V4L2_MPEG_AUDIO_L1_BITRATE_160K = 4, | ||
| 968 | V4L2_MPEG_AUDIO_L1_BITRATE_192K = 5, | ||
| 969 | V4L2_MPEG_AUDIO_L1_BITRATE_224K = 6, | ||
| 970 | V4L2_MPEG_AUDIO_L1_BITRATE_256K = 7, | ||
| 971 | V4L2_MPEG_AUDIO_L1_BITRATE_288K = 8, | ||
| 972 | V4L2_MPEG_AUDIO_L1_BITRATE_320K = 9, | ||
| 973 | V4L2_MPEG_AUDIO_L1_BITRATE_352K = 10, | ||
| 974 | V4L2_MPEG_AUDIO_L1_BITRATE_384K = 11, | ||
| 975 | V4L2_MPEG_AUDIO_L1_BITRATE_416K = 12, | ||
| 976 | V4L2_MPEG_AUDIO_L1_BITRATE_448K = 13, | ||
| 977 | }; | ||
| 978 | #define V4L2_CID_MPEG_AUDIO_L2_BITRATE (V4L2_CID_MPEG_BASE+103) | ||
| 979 | enum <link linkend="v4l2-mpeg-audio-l2-bitrate">v4l2_mpeg_audio_l2_bitrate</link> { | ||
| 980 | V4L2_MPEG_AUDIO_L2_BITRATE_32K = 0, | ||
| 981 | V4L2_MPEG_AUDIO_L2_BITRATE_48K = 1, | ||
| 982 | V4L2_MPEG_AUDIO_L2_BITRATE_56K = 2, | ||
| 983 | V4L2_MPEG_AUDIO_L2_BITRATE_64K = 3, | ||
| 984 | V4L2_MPEG_AUDIO_L2_BITRATE_80K = 4, | ||
| 985 | V4L2_MPEG_AUDIO_L2_BITRATE_96K = 5, | ||
| 986 | V4L2_MPEG_AUDIO_L2_BITRATE_112K = 6, | ||
| 987 | V4L2_MPEG_AUDIO_L2_BITRATE_128K = 7, | ||
| 988 | V4L2_MPEG_AUDIO_L2_BITRATE_160K = 8, | ||
| 989 | V4L2_MPEG_AUDIO_L2_BITRATE_192K = 9, | ||
| 990 | V4L2_MPEG_AUDIO_L2_BITRATE_224K = 10, | ||
| 991 | V4L2_MPEG_AUDIO_L2_BITRATE_256K = 11, | ||
| 992 | V4L2_MPEG_AUDIO_L2_BITRATE_320K = 12, | ||
| 993 | V4L2_MPEG_AUDIO_L2_BITRATE_384K = 13, | ||
| 994 | }; | ||
| 995 | #define V4L2_CID_MPEG_AUDIO_L3_BITRATE (V4L2_CID_MPEG_BASE+104) | ||
| 996 | enum <link linkend="v4l2-mpeg-audio-l3-bitrate">v4l2_mpeg_audio_l3_bitrate</link> { | ||
| 997 | V4L2_MPEG_AUDIO_L3_BITRATE_32K = 0, | ||
| 998 | V4L2_MPEG_AUDIO_L3_BITRATE_40K = 1, | ||
| 999 | V4L2_MPEG_AUDIO_L3_BITRATE_48K = 2, | ||
| 1000 | V4L2_MPEG_AUDIO_L3_BITRATE_56K = 3, | ||
| 1001 | V4L2_MPEG_AUDIO_L3_BITRATE_64K = 4, | ||
| 1002 | V4L2_MPEG_AUDIO_L3_BITRATE_80K = 5, | ||
| 1003 | V4L2_MPEG_AUDIO_L3_BITRATE_96K = 6, | ||
| 1004 | V4L2_MPEG_AUDIO_L3_BITRATE_112K = 7, | ||
| 1005 | V4L2_MPEG_AUDIO_L3_BITRATE_128K = 8, | ||
| 1006 | V4L2_MPEG_AUDIO_L3_BITRATE_160K = 9, | ||
| 1007 | V4L2_MPEG_AUDIO_L3_BITRATE_192K = 10, | ||
| 1008 | V4L2_MPEG_AUDIO_L3_BITRATE_224K = 11, | ||
| 1009 | V4L2_MPEG_AUDIO_L3_BITRATE_256K = 12, | ||
| 1010 | V4L2_MPEG_AUDIO_L3_BITRATE_320K = 13, | ||
| 1011 | }; | ||
| 1012 | #define V4L2_CID_MPEG_AUDIO_MODE (V4L2_CID_MPEG_BASE+105) | ||
| 1013 | enum <link linkend="v4l2-mpeg-audio-mode">v4l2_mpeg_audio_mode</link> { | ||
| 1014 | V4L2_MPEG_AUDIO_MODE_STEREO = 0, | ||
| 1015 | V4L2_MPEG_AUDIO_MODE_JOINT_STEREO = 1, | ||
| 1016 | V4L2_MPEG_AUDIO_MODE_DUAL = 2, | ||
| 1017 | V4L2_MPEG_AUDIO_MODE_MONO = 3, | ||
| 1018 | }; | ||
| 1019 | #define V4L2_CID_MPEG_AUDIO_MODE_EXTENSION (V4L2_CID_MPEG_BASE+106) | ||
| 1020 | enum <link linkend="v4l2-mpeg-audio-mode-extension">v4l2_mpeg_audio_mode_extension</link> { | ||
| 1021 | V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4 = 0, | ||
| 1022 | V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8 = 1, | ||
| 1023 | V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12 = 2, | ||
| 1024 | V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16 = 3, | ||
| 1025 | }; | ||
| 1026 | #define V4L2_CID_MPEG_AUDIO_EMPHASIS (V4L2_CID_MPEG_BASE+107) | ||
| 1027 | enum <link linkend="v4l2-mpeg-audio-emphasis">v4l2_mpeg_audio_emphasis</link> { | ||
| 1028 | V4L2_MPEG_AUDIO_EMPHASIS_NONE = 0, | ||
| 1029 | V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS = 1, | ||
| 1030 | V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17 = 2, | ||
| 1031 | }; | ||
| 1032 | #define V4L2_CID_MPEG_AUDIO_CRC (V4L2_CID_MPEG_BASE+108) | ||
| 1033 | enum <link linkend="v4l2-mpeg-audio-crc">v4l2_mpeg_audio_crc</link> { | ||
| 1034 | V4L2_MPEG_AUDIO_CRC_NONE = 0, | ||
| 1035 | V4L2_MPEG_AUDIO_CRC_CRC16 = 1, | ||
| 1036 | }; | ||
| 1037 | #define V4L2_CID_MPEG_AUDIO_MUTE (V4L2_CID_MPEG_BASE+109) | ||
| 1038 | #define V4L2_CID_MPEG_AUDIO_AAC_BITRATE (V4L2_CID_MPEG_BASE+110) | ||
| 1039 | #define V4L2_CID_MPEG_AUDIO_AC3_BITRATE (V4L2_CID_MPEG_BASE+111) | ||
| 1040 | enum <link linkend="v4l2-mpeg-audio-ac3-bitrate">v4l2_mpeg_audio_ac3_bitrate</link> { | ||
| 1041 | V4L2_MPEG_AUDIO_AC3_BITRATE_32K = 0, | ||
| 1042 | V4L2_MPEG_AUDIO_AC3_BITRATE_40K = 1, | ||
| 1043 | V4L2_MPEG_AUDIO_AC3_BITRATE_48K = 2, | ||
| 1044 | V4L2_MPEG_AUDIO_AC3_BITRATE_56K = 3, | ||
| 1045 | V4L2_MPEG_AUDIO_AC3_BITRATE_64K = 4, | ||
| 1046 | V4L2_MPEG_AUDIO_AC3_BITRATE_80K = 5, | ||
| 1047 | V4L2_MPEG_AUDIO_AC3_BITRATE_96K = 6, | ||
| 1048 | V4L2_MPEG_AUDIO_AC3_BITRATE_112K = 7, | ||
| 1049 | V4L2_MPEG_AUDIO_AC3_BITRATE_128K = 8, | ||
| 1050 | V4L2_MPEG_AUDIO_AC3_BITRATE_160K = 9, | ||
| 1051 | V4L2_MPEG_AUDIO_AC3_BITRATE_192K = 10, | ||
| 1052 | V4L2_MPEG_AUDIO_AC3_BITRATE_224K = 11, | ||
| 1053 | V4L2_MPEG_AUDIO_AC3_BITRATE_256K = 12, | ||
| 1054 | V4L2_MPEG_AUDIO_AC3_BITRATE_320K = 13, | ||
| 1055 | V4L2_MPEG_AUDIO_AC3_BITRATE_384K = 14, | ||
| 1056 | V4L2_MPEG_AUDIO_AC3_BITRATE_448K = 15, | ||
| 1057 | V4L2_MPEG_AUDIO_AC3_BITRATE_512K = 16, | ||
| 1058 | V4L2_MPEG_AUDIO_AC3_BITRATE_576K = 17, | ||
| 1059 | V4L2_MPEG_AUDIO_AC3_BITRATE_640K = 18, | ||
| 1060 | }; | ||
| 1061 | |||
| 1062 | /* MPEG video */ | ||
| 1063 | #define V4L2_CID_MPEG_VIDEO_ENCODING (V4L2_CID_MPEG_BASE+200) | ||
| 1064 | enum <link linkend="v4l2-mpeg-video-encoding">v4l2_mpeg_video_encoding</link> { | ||
| 1065 | V4L2_MPEG_VIDEO_ENCODING_MPEG_1 = 0, | ||
| 1066 | V4L2_MPEG_VIDEO_ENCODING_MPEG_2 = 1, | ||
| 1067 | V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC = 2, | ||
| 1068 | }; | ||
| 1069 | #define V4L2_CID_MPEG_VIDEO_ASPECT (V4L2_CID_MPEG_BASE+201) | ||
| 1070 | enum <link linkend="v4l2-mpeg-video-aspect">v4l2_mpeg_video_aspect</link> { | ||
| 1071 | V4L2_MPEG_VIDEO_ASPECT_1x1 = 0, | ||
| 1072 | V4L2_MPEG_VIDEO_ASPECT_4x3 = 1, | ||
| 1073 | V4L2_MPEG_VIDEO_ASPECT_16x9 = 2, | ||
| 1074 | V4L2_MPEG_VIDEO_ASPECT_221x100 = 3, | ||
| 1075 | }; | ||
| 1076 | #define V4L2_CID_MPEG_VIDEO_B_FRAMES (V4L2_CID_MPEG_BASE+202) | ||
| 1077 | #define V4L2_CID_MPEG_VIDEO_GOP_SIZE (V4L2_CID_MPEG_BASE+203) | ||
| 1078 | #define V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (V4L2_CID_MPEG_BASE+204) | ||
| 1079 | #define V4L2_CID_MPEG_VIDEO_PULLDOWN (V4L2_CID_MPEG_BASE+205) | ||
| 1080 | #define V4L2_CID_MPEG_VIDEO_BITRATE_MODE (V4L2_CID_MPEG_BASE+206) | ||
| 1081 | enum <link linkend="v4l2-mpeg-video-bitrate-mode">v4l2_mpeg_video_bitrate_mode</link> { | ||
| 1082 | V4L2_MPEG_VIDEO_BITRATE_MODE_VBR = 0, | ||
| 1083 | V4L2_MPEG_VIDEO_BITRATE_MODE_CBR = 1, | ||
| 1084 | }; | ||
| 1085 | #define V4L2_CID_MPEG_VIDEO_BITRATE (V4L2_CID_MPEG_BASE+207) | ||
| 1086 | #define V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (V4L2_CID_MPEG_BASE+208) | ||
| 1087 | #define V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (V4L2_CID_MPEG_BASE+209) | ||
| 1088 | #define V4L2_CID_MPEG_VIDEO_MUTE (V4L2_CID_MPEG_BASE+210) | ||
| 1089 | #define V4L2_CID_MPEG_VIDEO_MUTE_YUV (V4L2_CID_MPEG_BASE+211) | ||
| 1090 | |||
| 1091 | /* MPEG-class control IDs specific to the CX2341x driver as defined by V4L2 */ | ||
| 1092 | #define V4L2_CID_MPEG_CX2341X_BASE (V4L2_CTRL_CLASS_MPEG | 0x1000) | ||
| 1093 | #define V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE (V4L2_CID_MPEG_CX2341X_BASE+0) | ||
| 1094 | enum <link linkend="v4l2-mpeg-cx2341x-video-spatial-filter-mode">v4l2_mpeg_cx2341x_video_spatial_filter_mode</link> { | ||
| 1095 | V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL = 0, | ||
| 1096 | V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO = 1, | ||
| 1097 | }; | ||
| 1098 | #define V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (V4L2_CID_MPEG_CX2341X_BASE+1) | ||
| 1099 | #define V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE (V4L2_CID_MPEG_CX2341X_BASE+2) | ||
| 1100 | enum <link linkend="luma-spatial-filter-type">v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link> { | ||
| 1101 | V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF = 0, | ||
| 1102 | V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR = 1, | ||
| 1103 | V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT = 2, | ||
| 1104 | V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE = 3, | ||
| 1105 | V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE = 4, | ||
| 1106 | }; | ||
| 1107 | #define V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE (V4L2_CID_MPEG_CX2341X_BASE+3) | ||
| 1108 | enum <link linkend="chroma-spatial-filter-type">v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link> { | ||
| 1109 | V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF = 0, | ||
| 1110 | V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR = 1, | ||
| 1111 | }; | ||
| 1112 | #define V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE (V4L2_CID_MPEG_CX2341X_BASE+4) | ||
| 1113 | enum <link linkend="v4l2-mpeg-cx2341x-video-temporal-filter-mode">v4l2_mpeg_cx2341x_video_temporal_filter_mode</link> { | ||
| 1114 | V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL = 0, | ||
| 1115 | V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO = 1, | ||
| 1116 | }; | ||
| 1117 | #define V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (V4L2_CID_MPEG_CX2341X_BASE+5) | ||
| 1118 | #define V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE (V4L2_CID_MPEG_CX2341X_BASE+6) | ||
| 1119 | enum <link linkend="v4l2-mpeg-cx2341x-video-median-filter-type">v4l2_mpeg_cx2341x_video_median_filter_type</link> { | ||
| 1120 | V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF = 0, | ||
| 1121 | V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR = 1, | ||
| 1122 | V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT = 2, | ||
| 1123 | V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT = 3, | ||
| 1124 | V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG = 4, | ||
| 1125 | }; | ||
| 1126 | #define V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (V4L2_CID_MPEG_CX2341X_BASE+7) | ||
| 1127 | #define V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (V4L2_CID_MPEG_CX2341X_BASE+8) | ||
| 1128 | #define V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (V4L2_CID_MPEG_CX2341X_BASE+9) | ||
| 1129 | #define V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (V4L2_CID_MPEG_CX2341X_BASE+10) | ||
| 1130 | #define V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (V4L2_CID_MPEG_CX2341X_BASE+11) | ||
| 1131 | |||
| 1132 | /* Camera class control IDs */ | ||
| 1133 | #define V4L2_CID_CAMERA_CLASS_BASE (V4L2_CTRL_CLASS_CAMERA | 0x900) | ||
| 1134 | #define V4L2_CID_CAMERA_CLASS (V4L2_CTRL_CLASS_CAMERA | 1) | ||
| 1135 | |||
| 1136 | #define V4L2_CID_EXPOSURE_AUTO (V4L2_CID_CAMERA_CLASS_BASE+1) | ||
| 1137 | enum <link linkend="v4l2-exposure-auto-type">v4l2_exposure_auto_type</link> { | ||
| 1138 | V4L2_EXPOSURE_AUTO = 0, | ||
| 1139 | V4L2_EXPOSURE_MANUAL = 1, | ||
| 1140 | V4L2_EXPOSURE_SHUTTER_PRIORITY = 2, | ||
| 1141 | V4L2_EXPOSURE_APERTURE_PRIORITY = 3 | ||
| 1142 | }; | ||
| 1143 | #define V4L2_CID_EXPOSURE_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+2) | ||
| 1144 | #define V4L2_CID_EXPOSURE_AUTO_PRIORITY (V4L2_CID_CAMERA_CLASS_BASE+3) | ||
| 1145 | |||
| 1146 | #define V4L2_CID_PAN_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+4) | ||
| 1147 | #define V4L2_CID_TILT_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+5) | ||
| 1148 | #define V4L2_CID_PAN_RESET (V4L2_CID_CAMERA_CLASS_BASE+6) | ||
| 1149 | #define V4L2_CID_TILT_RESET (V4L2_CID_CAMERA_CLASS_BASE+7) | ||
| 1150 | |||
| 1151 | #define V4L2_CID_PAN_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+8) | ||
| 1152 | #define V4L2_CID_TILT_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+9) | ||
| 1153 | |||
| 1154 | #define V4L2_CID_FOCUS_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+10) | ||
| 1155 | #define V4L2_CID_FOCUS_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+11) | ||
| 1156 | #define V4L2_CID_FOCUS_AUTO (V4L2_CID_CAMERA_CLASS_BASE+12) | ||
| 1157 | |||
| 1158 | #define V4L2_CID_ZOOM_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+13) | ||
| 1159 | #define V4L2_CID_ZOOM_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+14) | ||
| 1160 | #define V4L2_CID_ZOOM_CONTINUOUS (V4L2_CID_CAMERA_CLASS_BASE+15) | ||
| 1161 | |||
| 1162 | #define V4L2_CID_PRIVACY (V4L2_CID_CAMERA_CLASS_BASE+16) | ||
| 1163 | |||
| 1164 | /* FM Modulator class control IDs */ | ||
| 1165 | #define V4L2_CID_FM_TX_CLASS_BASE (V4L2_CTRL_CLASS_FM_TX | 0x900) | ||
| 1166 | #define V4L2_CID_FM_TX_CLASS (V4L2_CTRL_CLASS_FM_TX | 1) | ||
| 1167 | |||
| 1168 | #define V4L2_CID_RDS_TX_DEVIATION (V4L2_CID_FM_TX_CLASS_BASE + 1) | ||
| 1169 | #define V4L2_CID_RDS_TX_PI (V4L2_CID_FM_TX_CLASS_BASE + 2) | ||
| 1170 | #define V4L2_CID_RDS_TX_PTY (V4L2_CID_FM_TX_CLASS_BASE + 3) | ||
| 1171 | #define V4L2_CID_RDS_TX_PS_NAME (V4L2_CID_FM_TX_CLASS_BASE + 5) | ||
| 1172 | #define V4L2_CID_RDS_TX_RADIO_TEXT (V4L2_CID_FM_TX_CLASS_BASE + 6) | ||
| 1173 | |||
| 1174 | #define V4L2_CID_AUDIO_LIMITER_ENABLED (V4L2_CID_FM_TX_CLASS_BASE + 64) | ||
| 1175 | #define V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (V4L2_CID_FM_TX_CLASS_BASE + 65) | ||
| 1176 | #define V4L2_CID_AUDIO_LIMITER_DEVIATION (V4L2_CID_FM_TX_CLASS_BASE + 66) | ||
| 1177 | |||
| 1178 | #define V4L2_CID_AUDIO_COMPRESSION_ENABLED (V4L2_CID_FM_TX_CLASS_BASE + 80) | ||
| 1179 | #define V4L2_CID_AUDIO_COMPRESSION_GAIN (V4L2_CID_FM_TX_CLASS_BASE + 81) | ||
| 1180 | #define V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (V4L2_CID_FM_TX_CLASS_BASE + 82) | ||
| 1181 | #define V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (V4L2_CID_FM_TX_CLASS_BASE + 83) | ||
| 1182 | #define V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (V4L2_CID_FM_TX_CLASS_BASE + 84) | ||
| 1183 | |||
| 1184 | #define V4L2_CID_PILOT_TONE_ENABLED (V4L2_CID_FM_TX_CLASS_BASE + 96) | ||
| 1185 | #define V4L2_CID_PILOT_TONE_DEVIATION (V4L2_CID_FM_TX_CLASS_BASE + 97) | ||
| 1186 | #define V4L2_CID_PILOT_TONE_FREQUENCY (V4L2_CID_FM_TX_CLASS_BASE + 98) | ||
| 1187 | |||
| 1188 | #define V4L2_CID_TUNE_PREEMPHASIS (V4L2_CID_FM_TX_CLASS_BASE + 112) | ||
| 1189 | enum <link linkend="v4l2-preemphasis">v4l2_preemphasis</link> { | ||
| 1190 | V4L2_PREEMPHASIS_DISABLED = 0, | ||
| 1191 | V4L2_PREEMPHASIS_50_uS = 1, | ||
| 1192 | V4L2_PREEMPHASIS_75_uS = 2, | ||
| 1193 | }; | ||
| 1194 | #define V4L2_CID_TUNE_POWER_LEVEL (V4L2_CID_FM_TX_CLASS_BASE + 113) | ||
| 1195 | #define V4L2_CID_TUNE_ANTENNA_CAPACITOR (V4L2_CID_FM_TX_CLASS_BASE + 114) | ||
| 1196 | |||
| 1197 | /* | ||
| 1198 | * T U N I N G | ||
| 1199 | */ | ||
| 1200 | struct <link linkend="v4l2-tuner">v4l2_tuner</link> { | ||
| 1201 | __u32 index; | ||
| 1202 | __u8 name[32]; | ||
| 1203 | enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> type; | ||
| 1204 | __u32 capability; | ||
| 1205 | __u32 rangelow; | ||
| 1206 | __u32 rangehigh; | ||
| 1207 | __u32 rxsubchans; | ||
| 1208 | __u32 audmode; | ||
| 1209 | __s32 signal; | ||
| 1210 | __s32 afc; | ||
| 1211 | __u32 reserved[4]; | ||
| 1212 | }; | ||
| 1213 | |||
| 1214 | struct <link linkend="v4l2-modulator">v4l2_modulator</link> { | ||
| 1215 | __u32 index; | ||
| 1216 | __u8 name[32]; | ||
| 1217 | __u32 capability; | ||
| 1218 | __u32 rangelow; | ||
| 1219 | __u32 rangehigh; | ||
| 1220 | __u32 txsubchans; | ||
| 1221 | __u32 reserved[4]; | ||
| 1222 | }; | ||
| 1223 | |||
| 1224 | /* Flags for the 'capability' field */ | ||
| 1225 | #define V4L2_TUNER_CAP_LOW 0x0001 | ||
| 1226 | #define V4L2_TUNER_CAP_NORM 0x0002 | ||
| 1227 | #define V4L2_TUNER_CAP_STEREO 0x0010 | ||
| 1228 | #define V4L2_TUNER_CAP_LANG2 0x0020 | ||
| 1229 | #define V4L2_TUNER_CAP_SAP 0x0020 | ||
| 1230 | #define V4L2_TUNER_CAP_LANG1 0x0040 | ||
| 1231 | #define V4L2_TUNER_CAP_RDS 0x0080 | ||
| 1232 | |||
| 1233 | /* Flags for the 'rxsubchans' field */ | ||
| 1234 | #define V4L2_TUNER_SUB_MONO 0x0001 | ||
| 1235 | #define V4L2_TUNER_SUB_STEREO 0x0002 | ||
| 1236 | #define V4L2_TUNER_SUB_LANG2 0x0004 | ||
| 1237 | #define V4L2_TUNER_SUB_SAP 0x0004 | ||
| 1238 | #define V4L2_TUNER_SUB_LANG1 0x0008 | ||
| 1239 | #define V4L2_TUNER_SUB_RDS 0x0010 | ||
| 1240 | |||
| 1241 | /* Values for the 'audmode' field */ | ||
| 1242 | #define V4L2_TUNER_MODE_MONO 0x0000 | ||
| 1243 | #define V4L2_TUNER_MODE_STEREO 0x0001 | ||
| 1244 | #define V4L2_TUNER_MODE_LANG2 0x0002 | ||
| 1245 | #define V4L2_TUNER_MODE_SAP 0x0002 | ||
| 1246 | #define V4L2_TUNER_MODE_LANG1 0x0003 | ||
| 1247 | #define V4L2_TUNER_MODE_LANG1_LANG2 0x0004 | ||
| 1248 | |||
| 1249 | struct <link linkend="v4l2-frequency">v4l2_frequency</link> { | ||
| 1250 | __u32 tuner; | ||
| 1251 | enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> type; | ||
| 1252 | __u32 frequency; | ||
| 1253 | __u32 reserved[8]; | ||
| 1254 | }; | ||
| 1255 | |||
| 1256 | struct <link linkend="v4l2-hw-freq-seek">v4l2_hw_freq_seek</link> { | ||
| 1257 | __u32 tuner; | ||
| 1258 | enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> type; | ||
| 1259 | __u32 seek_upward; | ||
| 1260 | __u32 wrap_around; | ||
| 1261 | __u32 reserved[8]; | ||
| 1262 | }; | ||
| 1263 | |||
| 1264 | /* | ||
| 1265 | * R D S | ||
| 1266 | */ | ||
| 1267 | |||
| 1268 | struct <link linkend="v4l2-rds-data">v4l2_rds_data</link> { | ||
| 1269 | __u8 lsb; | ||
| 1270 | __u8 msb; | ||
| 1271 | __u8 block; | ||
| 1272 | } __attribute__ ((packed)); | ||
| 1273 | |||
| 1274 | #define V4L2_RDS_BLOCK_MSK 0x7 | ||
| 1275 | #define V4L2_RDS_BLOCK_A 0 | ||
| 1276 | #define V4L2_RDS_BLOCK_B 1 | ||
| 1277 | #define V4L2_RDS_BLOCK_C 2 | ||
| 1278 | #define V4L2_RDS_BLOCK_D 3 | ||
| 1279 | #define V4L2_RDS_BLOCK_C_ALT 4 | ||
| 1280 | #define V4L2_RDS_BLOCK_INVALID 7 | ||
| 1281 | |||
| 1282 | #define V4L2_RDS_BLOCK_CORRECTED 0x40 | ||
| 1283 | #define V4L2_RDS_BLOCK_ERROR 0x80 | ||
| 1284 | |||
| 1285 | /* | ||
| 1286 | * A U D I O | ||
| 1287 | */ | ||
| 1288 | struct <link linkend="v4l2-audio">v4l2_audio</link> { | ||
| 1289 | __u32 index; | ||
| 1290 | __u8 name[32]; | ||
| 1291 | __u32 capability; | ||
| 1292 | __u32 mode; | ||
| 1293 | __u32 reserved[2]; | ||
| 1294 | }; | ||
| 1295 | |||
| 1296 | /* Flags for the 'capability' field */ | ||
| 1297 | #define V4L2_AUDCAP_STEREO 0x00001 | ||
| 1298 | #define V4L2_AUDCAP_AVL 0x00002 | ||
| 1299 | |||
| 1300 | /* Flags for the 'mode' field */ | ||
| 1301 | #define V4L2_AUDMODE_AVL 0x00001 | ||
| 1302 | |||
| 1303 | struct <link linkend="v4l2-audioout">v4l2_audioout</link> { | ||
| 1304 | __u32 index; | ||
| 1305 | __u8 name[32]; | ||
| 1306 | __u32 capability; | ||
| 1307 | __u32 mode; | ||
| 1308 | __u32 reserved[2]; | ||
| 1309 | }; | ||
| 1310 | |||
| 1311 | /* | ||
| 1312 | * M P E G S E R V I C E S | ||
| 1313 | * | ||
| 1314 | * NOTE: EXPERIMENTAL API | ||
| 1315 | */ | ||
| 1316 | #if 1 /*KEEP*/ | ||
| 1317 | #define V4L2_ENC_IDX_FRAME_I (0) | ||
| 1318 | #define V4L2_ENC_IDX_FRAME_P (1) | ||
| 1319 | #define V4L2_ENC_IDX_FRAME_B (2) | ||
| 1320 | #define V4L2_ENC_IDX_FRAME_MASK (0xf) | ||
| 1321 | |||
| 1322 | struct <link linkend="v4l2-enc-idx-entry">v4l2_enc_idx_entry</link> { | ||
| 1323 | __u64 offset; | ||
| 1324 | __u64 pts; | ||
| 1325 | __u32 length; | ||
| 1326 | __u32 flags; | ||
| 1327 | __u32 reserved[2]; | ||
| 1328 | }; | ||
| 1329 | |||
| 1330 | #define V4L2_ENC_IDX_ENTRIES (64) | ||
| 1331 | struct <link linkend="v4l2-enc-idx">v4l2_enc_idx</link> { | ||
| 1332 | __u32 entries; | ||
| 1333 | __u32 entries_cap; | ||
| 1334 | __u32 reserved[4]; | ||
| 1335 | struct <link linkend="v4l2-enc-idx-entry">v4l2_enc_idx_entry</link> entry[V4L2_ENC_IDX_ENTRIES]; | ||
| 1336 | }; | ||
| 1337 | |||
| 1338 | |||
| 1339 | #define V4L2_ENC_CMD_START (0) | ||
| 1340 | #define V4L2_ENC_CMD_STOP (1) | ||
| 1341 | #define V4L2_ENC_CMD_PAUSE (2) | ||
| 1342 | #define V4L2_ENC_CMD_RESUME (3) | ||
| 1343 | |||
| 1344 | /* Flags for V4L2_ENC_CMD_STOP */ | ||
| 1345 | #define V4L2_ENC_CMD_STOP_AT_GOP_END (1 << 0) | ||
| 1346 | |||
| 1347 | struct <link linkend="v4l2-encoder-cmd">v4l2_encoder_cmd</link> { | ||
| 1348 | __u32 cmd; | ||
| 1349 | __u32 flags; | ||
| 1350 | union { | ||
| 1351 | struct { | ||
| 1352 | __u32 data[8]; | ||
| 1353 | } raw; | ||
| 1354 | }; | ||
| 1355 | }; | ||
| 1356 | |||
| 1357 | #endif | ||
| 1358 | |||
| 1359 | |||
| 1360 | /* | ||
| 1361 | * D A T A S E R V I C E S ( V B I ) | ||
| 1362 | * | ||
| 1363 | * Data services API by Michael Schimek | ||
| 1364 | */ | ||
| 1365 | |||
| 1366 | /* Raw VBI */ | ||
| 1367 | struct <link linkend="v4l2-vbi-format">v4l2_vbi_format</link> { | ||
| 1368 | __u32 sampling_rate; /* in 1 Hz */ | ||
| 1369 | __u32 offset; | ||
| 1370 | __u32 samples_per_line; | ||
| 1371 | __u32 sample_format; /* V4L2_PIX_FMT_* */ | ||
| 1372 | __s32 start[2]; | ||
| 1373 | __u32 count[2]; | ||
| 1374 | __u32 flags; /* V4L2_VBI_* */ | ||
| 1375 | __u32 reserved[2]; /* must be zero */ | ||
| 1376 | }; | ||
| 1377 | |||
| 1378 | /* VBI flags */ | ||
| 1379 | #define V4L2_VBI_UNSYNC (1 << 0) | ||
| 1380 | #define V4L2_VBI_INTERLACED (1 << 1) | ||
| 1381 | |||
| 1382 | /* Sliced VBI | ||
| 1383 | * | ||
| 1384 | * This implements is a proposal V4L2 API to allow SLICED VBI | ||
| 1385 | * required for some hardware encoders. It should change without | ||
| 1386 | * notice in the definitive implementation. | ||
| 1387 | */ | ||
| 1388 | |||
| 1389 | struct <link linkend="v4l2-sliced-vbi-format">v4l2_sliced_vbi_format</link> { | ||
| 1390 | __u16 service_set; | ||
| 1391 | /* service_lines[0][...] specifies lines 0-23 (1-23 used) of the first field | ||
| 1392 | service_lines[1][...] specifies lines 0-23 (1-23 used) of the second field | ||
| 1393 | (equals frame lines 313-336 for 625 line video | ||
| 1394 | standards, 263-286 for 525 line standards) */ | ||
| 1395 | __u16 service_lines[2][24]; | ||
| 1396 | __u32 io_size; | ||
| 1397 | __u32 reserved[2]; /* must be zero */ | ||
| 1398 | }; | ||
| 1399 | |||
| 1400 | /* Teletext World System Teletext | ||
| 1401 | (WST), defined on ITU-R BT.653-2 */ | ||
| 1402 | #define V4L2_SLICED_TELETEXT_B (0x0001) | ||
| 1403 | /* Video Program System, defined on ETS 300 231*/ | ||
| 1404 | #define V4L2_SLICED_VPS (0x0400) | ||
| 1405 | /* Closed Caption, defined on EIA-608 */ | ||
| 1406 | #define V4L2_SLICED_CAPTION_525 (0x1000) | ||
| 1407 | /* Wide Screen System, defined on ITU-R BT1119.1 */ | ||
| 1408 | #define V4L2_SLICED_WSS_625 (0x4000) | ||
| 1409 | |||
| 1410 | #define V4L2_SLICED_VBI_525 (V4L2_SLICED_CAPTION_525) | ||
| 1411 | #define V4L2_SLICED_VBI_625 (V4L2_SLICED_TELETEXT_B | V4L2_SLICED_VPS | V4L2_SLICED_WSS_625) | ||
| 1412 | |||
| 1413 | struct <link linkend="v4l2-sliced-vbi-cap">v4l2_sliced_vbi_cap</link> { | ||
| 1414 | __u16 service_set; | ||
| 1415 | /* service_lines[0][...] specifies lines 0-23 (1-23 used) of the first field | ||
| 1416 | service_lines[1][...] specifies lines 0-23 (1-23 used) of the second field | ||
| 1417 | (equals frame lines 313-336 for 625 line video | ||
| 1418 | standards, 263-286 for 525 line standards) */ | ||
| 1419 | __u16 service_lines[2][24]; | ||
| 1420 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 1421 | __u32 reserved[3]; /* must be 0 */ | ||
| 1422 | }; | ||
| 1423 | |||
| 1424 | struct <link linkend="v4l2-sliced-vbi-data">v4l2_sliced_vbi_data</link> { | ||
| 1425 | __u32 id; | ||
| 1426 | __u32 field; /* 0: first field, 1: second field */ | ||
| 1427 | __u32 line; /* 1-23 */ | ||
| 1428 | __u32 reserved; /* must be 0 */ | ||
| 1429 | __u8 data[48]; | ||
| 1430 | }; | ||
| 1431 | |||
| 1432 | /* | ||
| 1433 | * Sliced VBI data inserted into MPEG Streams | ||
| 1434 | */ | ||
| 1435 | |||
| 1436 | /* | ||
| 1437 | * V4L2_MPEG_STREAM_VBI_FMT_IVTV: | ||
| 1438 | * | ||
| 1439 | * Structure of payload contained in an MPEG 2 Private Stream 1 PES Packet in an | ||
| 1440 | * MPEG-2 Program Pack that contains V4L2_MPEG_STREAM_VBI_FMT_IVTV Sliced VBI | ||
| 1441 | * data | ||
| 1442 | * | ||
| 1443 | * Note, the MPEG-2 Program Pack and Private Stream 1 PES packet header | ||
| 1444 | * definitions are not included here. See the MPEG-2 specifications for details | ||
| 1445 | * on these headers. | ||
| 1446 | */ | ||
| 1447 | |||
| 1448 | /* Line type IDs */ | ||
| 1449 | #define V4L2_MPEG_VBI_IVTV_TELETEXT_B (1) | ||
| 1450 | #define V4L2_MPEG_VBI_IVTV_CAPTION_525 (4) | ||
| 1451 | #define V4L2_MPEG_VBI_IVTV_WSS_625 (5) | ||
| 1452 | #define V4L2_MPEG_VBI_IVTV_VPS (7) | ||
| 1453 | |||
| 1454 | struct <link linkend="v4l2-mpeg-vbi-itv0-line">v4l2_mpeg_vbi_itv0_line</link> { | ||
| 1455 | __u8 id; /* One of V4L2_MPEG_VBI_IVTV_* above */ | ||
| 1456 | __u8 data[42]; /* Sliced VBI data for the line */ | ||
| 1457 | } __attribute__ ((packed)); | ||
| 1458 | |||
| 1459 | struct <link linkend="v4l2-mpeg-vbi-itv0">v4l2_mpeg_vbi_itv0</link> { | ||
| 1460 | __le32 linemask[2]; /* Bitmasks of VBI service lines present */ | ||
| 1461 | struct <link linkend="v4l2-mpeg-vbi-itv0-line">v4l2_mpeg_vbi_itv0_line</link> line[35]; | ||
| 1462 | } __attribute__ ((packed)); | ||
| 1463 | |||
| 1464 | struct <link linkend="v4l2-mpeg-vbi-itv0-1">v4l2_mpeg_vbi_ITV0</link> { | ||
| 1465 | struct <link linkend="v4l2-mpeg-vbi-itv0-line">v4l2_mpeg_vbi_itv0_line</link> line[36]; | ||
| 1466 | } __attribute__ ((packed)); | ||
| 1467 | |||
| 1468 | #define V4L2_MPEG_VBI_IVTV_MAGIC0 "itv0" | ||
| 1469 | #define V4L2_MPEG_VBI_IVTV_MAGIC1 "ITV0" | ||
| 1470 | |||
| 1471 | struct <link linkend="v4l2-mpeg-vbi-fmt-ivtv">v4l2_mpeg_vbi_fmt_ivtv</link> { | ||
| 1472 | __u8 magic[4]; | ||
| 1473 | union { | ||
| 1474 | struct <link linkend="v4l2-mpeg-vbi-itv0">v4l2_mpeg_vbi_itv0</link> itv0; | ||
| 1475 | struct <link linkend="v4l2-mpeg-vbi-itv0-1">v4l2_mpeg_vbi_ITV0</link> ITV0; | ||
| 1476 | }; | ||
| 1477 | } __attribute__ ((packed)); | ||
| 1478 | |||
| 1479 | /* | ||
| 1480 | * A G G R E G A T E S T R U C T U R E S | ||
| 1481 | */ | ||
| 1482 | |||
| 1483 | /* Stream data format | ||
| 1484 | */ | ||
| 1485 | struct <link linkend="v4l2-format">v4l2_format</link> { | ||
| 1486 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 1487 | union { | ||
| 1488 | struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> pix; /* V4L2_BUF_TYPE_VIDEO_CAPTURE */ | ||
| 1489 | struct <link linkend="v4l2-window">v4l2_window</link> win; /* V4L2_BUF_TYPE_VIDEO_OVERLAY */ | ||
| 1490 | struct <link linkend="v4l2-vbi-format">v4l2_vbi_format</link> vbi; /* V4L2_BUF_TYPE_VBI_CAPTURE */ | ||
| 1491 | struct <link linkend="v4l2-sliced-vbi-format">v4l2_sliced_vbi_format</link> sliced; /* V4L2_BUF_TYPE_SLICED_VBI_CAPTURE */ | ||
| 1492 | __u8 raw_data[200]; /* user-defined */ | ||
| 1493 | } fmt; | ||
| 1494 | }; | ||
| 1495 | |||
| 1496 | |||
| 1497 | /* Stream type-dependent parameters | ||
| 1498 | */ | ||
| 1499 | struct <link linkend="v4l2-streamparm">v4l2_streamparm</link> { | ||
| 1500 | enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; | ||
| 1501 | union { | ||
| 1502 | struct <link linkend="v4l2-captureparm">v4l2_captureparm</link> capture; | ||
| 1503 | struct <link linkend="v4l2-outputparm">v4l2_outputparm</link> output; | ||
| 1504 | __u8 raw_data[200]; /* user-defined */ | ||
| 1505 | } parm; | ||
| 1506 | }; | ||
| 1507 | |||
| 1508 | /* | ||
| 1509 | * A D V A N C E D D E B U G G I N G | ||
| 1510 | * | ||
| 1511 | * NOTE: EXPERIMENTAL API, NEVER RELY ON THIS IN APPLICATIONS! | ||
| 1512 | * FOR DEBUGGING, TESTING AND INTERNAL USE ONLY! | ||
| 1513 | */ | ||
| 1514 | |||
| 1515 | /* VIDIOC_DBG_G_REGISTER and VIDIOC_DBG_S_REGISTER */ | ||
| 1516 | |||
| 1517 | #define V4L2_CHIP_MATCH_HOST 0 /* Match against chip ID on host (0 for the host) */ | ||
| 1518 | #define V4L2_CHIP_MATCH_I2C_DRIVER 1 /* Match against I2C driver name */ | ||
| 1519 | #define V4L2_CHIP_MATCH_I2C_ADDR 2 /* Match against I2C 7-bit address */ | ||
| 1520 | #define V4L2_CHIP_MATCH_AC97 3 /* Match against anciliary AC97 chip */ | ||
| 1521 | |||
| 1522 | struct <link linkend="v4l2-dbg-match">v4l2_dbg_match</link> { | ||
| 1523 | __u32 type; /* Match type */ | ||
| 1524 | union { /* Match this chip, meaning determined by type */ | ||
| 1525 | __u32 addr; | ||
| 1526 | char name[32]; | ||
| 1527 | }; | ||
| 1528 | } __attribute__ ((packed)); | ||
| 1529 | |||
| 1530 | struct <link linkend="v4l2-dbg-register">v4l2_dbg_register</link> { | ||
| 1531 | struct <link linkend="v4l2-dbg-match">v4l2_dbg_match</link> match; | ||
| 1532 | __u32 size; /* register size in bytes */ | ||
| 1533 | __u64 reg; | ||
| 1534 | __u64 val; | ||
| 1535 | } __attribute__ ((packed)); | ||
| 1536 | |||
| 1537 | /* VIDIOC_DBG_G_CHIP_IDENT */ | ||
| 1538 | struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link> { | ||
| 1539 | struct <link linkend="v4l2-dbg-match">v4l2_dbg_match</link> match; | ||
| 1540 | __u32 ident; /* chip identifier as specified in <media/v4l2-chip-ident.h> */ | ||
| 1541 | __u32 revision; /* chip revision, chip specific */ | ||
| 1542 | } __attribute__ ((packed)); | ||
| 1543 | |||
| 1544 | /* | ||
| 1545 | * I O C T L C O D E S F O R V I D E O D E V I C E S | ||
| 1546 | * | ||
| 1547 | */ | ||
| 1548 | #define VIDIOC_QUERYCAP _IOR('V', 0, struct <link linkend="v4l2-capability">v4l2_capability</link>) | ||
| 1549 | #define VIDIOC_RESERVED _IO('V', 1) | ||
| 1550 | #define VIDIOC_ENUM_FMT _IOWR('V', 2, struct <link linkend="v4l2-fmtdesc">v4l2_fmtdesc</link>) | ||
| 1551 | #define VIDIOC_G_FMT _IOWR('V', 4, struct <link linkend="v4l2-format">v4l2_format</link>) | ||
| 1552 | #define VIDIOC_S_FMT _IOWR('V', 5, struct <link linkend="v4l2-format">v4l2_format</link>) | ||
| 1553 | #define VIDIOC_REQBUFS _IOWR('V', 8, struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link>) | ||
| 1554 | #define VIDIOC_QUERYBUF _IOWR('V', 9, struct <link linkend="v4l2-buffer">v4l2_buffer</link>) | ||
| 1555 | #define VIDIOC_G_FBUF _IOR('V', 10, struct <link linkend="v4l2-framebuffer">v4l2_framebuffer</link>) | ||
| 1556 | #define VIDIOC_S_FBUF _IOW('V', 11, struct <link linkend="v4l2-framebuffer">v4l2_framebuffer</link>) | ||
| 1557 | #define VIDIOC_OVERLAY _IOW('V', 14, int) | ||
| 1558 | #define VIDIOC_QBUF _IOWR('V', 15, struct <link linkend="v4l2-buffer">v4l2_buffer</link>) | ||
| 1559 | #define VIDIOC_DQBUF _IOWR('V', 17, struct <link linkend="v4l2-buffer">v4l2_buffer</link>) | ||
| 1560 | #define VIDIOC_STREAMON _IOW('V', 18, int) | ||
| 1561 | #define VIDIOC_STREAMOFF _IOW('V', 19, int) | ||
| 1562 | #define VIDIOC_G_PARM _IOWR('V', 21, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>) | ||
| 1563 | #define VIDIOC_S_PARM _IOWR('V', 22, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>) | ||
| 1564 | #define VIDIOC_G_STD _IOR('V', 23, v4l2_std_id) | ||
| 1565 | #define VIDIOC_S_STD _IOW('V', 24, v4l2_std_id) | ||
| 1566 | #define VIDIOC_ENUMSTD _IOWR('V', 25, struct <link linkend="v4l2-standard">v4l2_standard</link>) | ||
| 1567 | #define VIDIOC_ENUMINPUT _IOWR('V', 26, struct <link linkend="v4l2-input">v4l2_input</link>) | ||
| 1568 | #define VIDIOC_G_CTRL _IOWR('V', 27, struct <link linkend="v4l2-control">v4l2_control</link>) | ||
| 1569 | #define VIDIOC_S_CTRL _IOWR('V', 28, struct <link linkend="v4l2-control">v4l2_control</link>) | ||
| 1570 | #define VIDIOC_G_TUNER _IOWR('V', 29, struct <link linkend="v4l2-tuner">v4l2_tuner</link>) | ||
| 1571 | #define VIDIOC_S_TUNER _IOW('V', 30, struct <link linkend="v4l2-tuner">v4l2_tuner</link>) | ||
| 1572 | #define VIDIOC_G_AUDIO _IOR('V', 33, struct <link linkend="v4l2-audio">v4l2_audio</link>) | ||
| 1573 | #define VIDIOC_S_AUDIO _IOW('V', 34, struct <link linkend="v4l2-audio">v4l2_audio</link>) | ||
| 1574 | #define VIDIOC_QUERYCTRL _IOWR('V', 36, struct <link linkend="v4l2-queryctrl">v4l2_queryctrl</link>) | ||
| 1575 | #define VIDIOC_QUERYMENU _IOWR('V', 37, struct <link linkend="v4l2-querymenu">v4l2_querymenu</link>) | ||
| 1576 | #define VIDIOC_G_INPUT _IOR('V', 38, int) | ||
| 1577 | #define VIDIOC_S_INPUT _IOWR('V', 39, int) | ||
| 1578 | #define VIDIOC_G_OUTPUT _IOR('V', 46, int) | ||
| 1579 | #define VIDIOC_S_OUTPUT _IOWR('V', 47, int) | ||
| 1580 | #define VIDIOC_ENUMOUTPUT _IOWR('V', 48, struct <link linkend="v4l2-output">v4l2_output</link>) | ||
| 1581 | #define VIDIOC_G_AUDOUT _IOR('V', 49, struct <link linkend="v4l2-audioout">v4l2_audioout</link>) | ||
| 1582 | #define VIDIOC_S_AUDOUT _IOW('V', 50, struct <link linkend="v4l2-audioout">v4l2_audioout</link>) | ||
| 1583 | #define VIDIOC_G_MODULATOR _IOWR('V', 54, struct <link linkend="v4l2-modulator">v4l2_modulator</link>) | ||
| 1584 | #define VIDIOC_S_MODULATOR _IOW('V', 55, struct <link linkend="v4l2-modulator">v4l2_modulator</link>) | ||
| 1585 | #define VIDIOC_G_FREQUENCY _IOWR('V', 56, struct <link linkend="v4l2-frequency">v4l2_frequency</link>) | ||
| 1586 | #define VIDIOC_S_FREQUENCY _IOW('V', 57, struct <link linkend="v4l2-frequency">v4l2_frequency</link>) | ||
| 1587 | #define VIDIOC_CROPCAP _IOWR('V', 58, struct <link linkend="v4l2-cropcap">v4l2_cropcap</link>) | ||
| 1588 | #define VIDIOC_G_CROP _IOWR('V', 59, struct <link linkend="v4l2-crop">v4l2_crop</link>) | ||
| 1589 | #define VIDIOC_S_CROP _IOW('V', 60, struct <link linkend="v4l2-crop">v4l2_crop</link>) | ||
| 1590 | #define VIDIOC_G_JPEGCOMP _IOR('V', 61, struct <link linkend="v4l2-jpegcompression">v4l2_jpegcompression</link>) | ||
| 1591 | #define VIDIOC_S_JPEGCOMP _IOW('V', 62, struct <link linkend="v4l2-jpegcompression">v4l2_jpegcompression</link>) | ||
| 1592 | #define VIDIOC_QUERYSTD _IOR('V', 63, v4l2_std_id) | ||
| 1593 | #define VIDIOC_TRY_FMT _IOWR('V', 64, struct <link linkend="v4l2-format">v4l2_format</link>) | ||
| 1594 | #define VIDIOC_ENUMAUDIO _IOWR('V', 65, struct <link linkend="v4l2-audio">v4l2_audio</link>) | ||
| 1595 | #define VIDIOC_ENUMAUDOUT _IOWR('V', 66, struct <link linkend="v4l2-audioout">v4l2_audioout</link>) | ||
| 1596 | #define VIDIOC_G_PRIORITY _IOR('V', 67, enum <link linkend="v4l2-priority">v4l2_priority</link>) | ||
| 1597 | #define VIDIOC_S_PRIORITY _IOW('V', 68, enum <link linkend="v4l2-priority">v4l2_priority</link>) | ||
| 1598 | #define VIDIOC_G_SLICED_VBI_CAP _IOWR('V', 69, struct <link linkend="v4l2-sliced-vbi-cap">v4l2_sliced_vbi_cap</link>) | ||
| 1599 | #define VIDIOC_LOG_STATUS _IO('V', 70) | ||
| 1600 | #define VIDIOC_G_EXT_CTRLS _IOWR('V', 71, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>) | ||
| 1601 | #define VIDIOC_S_EXT_CTRLS _IOWR('V', 72, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>) | ||
| 1602 | #define VIDIOC_TRY_EXT_CTRLS _IOWR('V', 73, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>) | ||
| 1603 | #if 1 /*KEEP*/ | ||
| 1604 | #define VIDIOC_ENUM_FRAMESIZES _IOWR('V', 74, struct <link linkend="v4l2-frmsizeenum">v4l2_frmsizeenum</link>) | ||
| 1605 | #define VIDIOC_ENUM_FRAMEINTERVALS _IOWR('V', 75, struct <link linkend="v4l2-frmivalenum">v4l2_frmivalenum</link>) | ||
| 1606 | #define VIDIOC_G_ENC_INDEX _IOR('V', 76, struct <link linkend="v4l2-enc-idx">v4l2_enc_idx</link>) | ||
| 1607 | #define VIDIOC_ENCODER_CMD _IOWR('V', 77, struct <link linkend="v4l2-encoder-cmd">v4l2_encoder_cmd</link>) | ||
| 1608 | #define VIDIOC_TRY_ENCODER_CMD _IOWR('V', 78, struct <link linkend="v4l2-encoder-cmd">v4l2_encoder_cmd</link>) | ||
| 1609 | #endif | ||
| 1610 | |||
| 1611 | #if 1 /*KEEP*/ | ||
| 1612 | /* Experimental, meant for debugging, testing and internal use. | ||
| 1613 | Only implemented if CONFIG_VIDEO_ADV_DEBUG is defined. | ||
| 1614 | You must be root to use these ioctls. Never use these in applications! */ | ||
| 1615 | #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct <link linkend="v4l2-dbg-register">v4l2_dbg_register</link>) | ||
| 1616 | #define VIDIOC_DBG_G_REGISTER _IOWR('V', 80, struct <link linkend="v4l2-dbg-register">v4l2_dbg_register</link>) | ||
| 1617 | |||
| 1618 | /* Experimental, meant for debugging, testing and internal use. | ||
| 1619 | Never use this ioctl in applications! */ | ||
| 1620 | #define VIDIOC_DBG_G_CHIP_IDENT _IOWR('V', 81, struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link>) | ||
| 1621 | #endif | ||
| 1622 | |||
| 1623 | #define VIDIOC_S_HW_FREQ_SEEK _IOW('V', 82, struct <link linkend="v4l2-hw-freq-seek">v4l2_hw_freq_seek</link>) | ||
| 1624 | /* Reminder: when adding new ioctls please add support for them to | ||
| 1625 | drivers/media/video/v4l2-compat-ioctl32.c as well! */ | ||
| 1626 | |||
| 1627 | #ifdef __OLD_VIDIOC_ | ||
| 1628 | /* for compatibility, will go away some day */ | ||
| 1629 | #define VIDIOC_OVERLAY_OLD _IOWR('V', 14, int) | ||
| 1630 | #define VIDIOC_S_PARM_OLD _IOW('V', 22, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>) | ||
| 1631 | #define VIDIOC_S_CTRL_OLD _IOW('V', 28, struct <link linkend="v4l2-control">v4l2_control</link>) | ||
| 1632 | #define VIDIOC_G_AUDIO_OLD _IOWR('V', 33, struct <link linkend="v4l2-audio">v4l2_audio</link>) | ||
| 1633 | #define VIDIOC_G_AUDOUT_OLD _IOWR('V', 49, struct <link linkend="v4l2-audioout">v4l2_audioout</link>) | ||
| 1634 | #define VIDIOC_CROPCAP_OLD _IOR('V', 58, struct <link linkend="v4l2-cropcap">v4l2_cropcap</link>) | ||
| 1635 | #endif | ||
| 1636 | |||
| 1637 | #define BASE_VIDIOC_PRIVATE 192 /* 192-255 are private */ | ||
| 1638 | |||
| 1639 | #endif /* __LINUX_VIDEODEV2_H */ | ||
| 1640 | </programlisting> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-cropcap.xml b/Documentation/DocBook/v4l/vidioc-cropcap.xml new file mode 100644 index 000000000000..816e90e283c5 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-cropcap.xml | |||
| @@ -0,0 +1,174 @@ | |||
| 1 | <refentry id="vidioc-cropcap"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_CROPCAP</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_CROPCAP</refname> | ||
| 9 | <refpurpose>Information about the video cropping and scaling abilities</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_cropcap | ||
| 19 | *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_CROPCAP</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>Applications use this function to query the cropping | ||
| 53 | limits, the pixel aspect of images and to calculate scale factors. | ||
| 54 | They set the <structfield>type</structfield> field of a v4l2_cropcap | ||
| 55 | structure to the respective buffer (stream) type and call the | ||
| 56 | <constant>VIDIOC_CROPCAP</constant> ioctl with a pointer to this | ||
| 57 | structure. Drivers fill the rest of the structure. The results are | ||
| 58 | constant except when switching the video standard. Remember this | ||
| 59 | switch can occur implicit when switching the video input or | ||
| 60 | output.</para> | ||
| 61 | |||
| 62 | <table pgwide="1" frame="none" id="v4l2-cropcap"> | ||
| 63 | <title>struct <structname>v4l2_cropcap</structname></title> | ||
| 64 | <tgroup cols="3"> | ||
| 65 | &cs-str; | ||
| 66 | <tbody valign="top"> | ||
| 67 | <row> | ||
| 68 | <entry>&v4l2-buf-type;</entry> | ||
| 69 | <entry><structfield>type</structfield></entry> | ||
| 70 | <entry>Type of the data stream, set by the application. | ||
| 71 | Only these types are valid here: | ||
| 72 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, | ||
| 73 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, | ||
| 74 | <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver | ||
| 75 | defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> | ||
| 76 | and higher.</entry> | ||
| 77 | </row> | ||
| 78 | <row> | ||
| 79 | <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry> | ||
| 80 | <entry><structfield>bounds</structfield></entry> | ||
| 81 | <entry>Defines the window within capturing or output is | ||
| 82 | possible, this may exclude for example the horizontal and vertical | ||
| 83 | blanking areas. The cropping rectangle cannot exceed these limits. | ||
| 84 | Width and height are defined in pixels, the driver writer is free to | ||
| 85 | choose origin and units of the coordinate system in the analog | ||
| 86 | domain.</entry> | ||
| 87 | </row> | ||
| 88 | <row> | ||
| 89 | <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry> | ||
| 90 | <entry><structfield>defrect</structfield></entry> | ||
| 91 | <entry>Default cropping rectangle, it shall cover the | ||
| 92 | "whole picture". Assuming pixel aspect 1/1 this could be for example a | ||
| 93 | 640 × 480 rectangle for NTSC, a | ||
| 94 | 768 × 576 rectangle for PAL and SECAM centered over | ||
| 95 | the active picture area. The same co-ordinate system as for | ||
| 96 | <structfield>bounds</structfield> is used.</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>&v4l2-fract;</entry> | ||
| 100 | <entry><structfield>pixelaspect</structfield></entry> | ||
| 101 | <entry><para>This is the pixel aspect (y / x) when no | ||
| 102 | scaling is applied, the ratio of the actual sampling | ||
| 103 | frequency and the frequency required to get square | ||
| 104 | pixels.</para><para>When cropping coordinates refer to square pixels, | ||
| 105 | the driver sets <structfield>pixelaspect</structfield> to 1/1. Other | ||
| 106 | common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled | ||
| 107 | according to [<xref linkend="itu601" />].</para></entry> | ||
| 108 | </row> | ||
| 109 | </tbody> | ||
| 110 | </tgroup> | ||
| 111 | </table> | ||
| 112 | |||
| 113 | <!-- NB this table is duplicated in the overlay chapter. --> | ||
| 114 | |||
| 115 | <table pgwide="1" frame="none" id="v4l2-rect-crop"> | ||
| 116 | <title>struct <structname>v4l2_rect</structname></title> | ||
| 117 | <tgroup cols="3"> | ||
| 118 | &cs-str; | ||
| 119 | <tbody valign="top"> | ||
| 120 | <row> | ||
| 121 | <entry>__s32</entry> | ||
| 122 | <entry><structfield>left</structfield></entry> | ||
| 123 | <entry>Horizontal offset of the top, left corner of the | ||
| 124 | rectangle, in pixels.</entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry>__s32</entry> | ||
| 128 | <entry><structfield>top</structfield></entry> | ||
| 129 | <entry>Vertical offset of the top, left corner of the | ||
| 130 | rectangle, in pixels.</entry> | ||
| 131 | </row> | ||
| 132 | <row> | ||
| 133 | <entry>__s32</entry> | ||
| 134 | <entry><structfield>width</structfield></entry> | ||
| 135 | <entry>Width of the rectangle, in pixels.</entry> | ||
| 136 | </row> | ||
| 137 | <row> | ||
| 138 | <entry>__s32</entry> | ||
| 139 | <entry><structfield>height</structfield></entry> | ||
| 140 | <entry>Height of the rectangle, in pixels. Width | ||
| 141 | and height cannot be negative, the fields are signed for | ||
| 142 | hysterical reasons. <!-- video4linux-list@redhat.com | ||
| 143 | on 22 Oct 2002 subject "Re:[V4L][patches!] Re:v4l2/kernel-2.5" --> | ||
| 144 | </entry> | ||
| 145 | </row> | ||
| 146 | </tbody> | ||
| 147 | </tgroup> | ||
| 148 | </table> | ||
| 149 | </refsect1> | ||
| 150 | |||
| 151 | <refsect1> | ||
| 152 | &return-value; | ||
| 153 | |||
| 154 | <variablelist> | ||
| 155 | <varlistentry> | ||
| 156 | <term><errorcode>EINVAL</errorcode></term> | ||
| 157 | <listitem> | ||
| 158 | <para>The &v4l2-cropcap; <structfield>type</structfield> is | ||
| 159 | invalid or the ioctl is not supported. This is not permitted for | ||
| 160 | video capture, output and overlay devices, which must support | ||
| 161 | <constant>VIDIOC_CROPCAP</constant>.</para> | ||
| 162 | </listitem> | ||
| 163 | </varlistentry> | ||
| 164 | </variablelist> | ||
| 165 | </refsect1> | ||
| 166 | </refentry> | ||
| 167 | |||
| 168 | <!-- | ||
| 169 | Local Variables: | ||
| 170 | mode: sgml | ||
| 171 | sgml-parent-document: "v4l2.sgml" | ||
| 172 | indent-tabs-mode: nil | ||
| 173 | End: | ||
| 174 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-dbg-g-chip-ident.xml b/Documentation/DocBook/v4l/vidioc-dbg-g-chip-ident.xml new file mode 100644 index 000000000000..4a09e203af0f --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-dbg-g-chip-ident.xml | |||
| @@ -0,0 +1,275 @@ | |||
| 1 | <refentry id="vidioc-dbg-g-chip-ident"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_DBG_G_CHIP_IDENT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_DBG_G_CHIP_IDENT</refname> | ||
| 9 | <refpurpose>Identify the chips on a TV card</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_dbg_chip_ident | ||
| 19 | *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_DBG_G_CHIP_IDENT</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <note> | ||
| 53 | <title>Experimental</title> | ||
| 54 | |||
| 55 | <para>This is an <link | ||
| 56 | linkend="experimental">experimental</link> interface and may change in | ||
| 57 | the future.</para> | ||
| 58 | </note> | ||
| 59 | |||
| 60 | <para>For driver debugging purposes this ioctl allows test | ||
| 61 | applications to query the driver about the chips present on the TV | ||
| 62 | card. Regular applications must not use it. When you found a chip | ||
| 63 | specific bug, please contact the linux-media mailing list (&v4l-ml;) | ||
| 64 | so it can be fixed.</para> | ||
| 65 | |||
| 66 | <para>To query the driver applications must initialize the | ||
| 67 | <structfield>match.type</structfield> and | ||
| 68 | <structfield>match.addr</structfield> or <structfield>match.name</structfield> | ||
| 69 | fields of a &v4l2-dbg-chip-ident; | ||
| 70 | and call <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> with a pointer to | ||
| 71 | this structure. On success the driver stores information about the | ||
| 72 | selected chip in the <structfield>ident</structfield> and | ||
| 73 | <structfield>revision</structfield> fields. On failure the structure | ||
| 74 | remains unchanged.</para> | ||
| 75 | |||
| 76 | <para>When <structfield>match.type</structfield> is | ||
| 77 | <constant>V4L2_CHIP_MATCH_HOST</constant>, | ||
| 78 | <structfield>match.addr</structfield> selects the nth non-&i2c; chip | ||
| 79 | on the TV card. You can enumerate all chips by starting at zero and | ||
| 80 | incrementing <structfield>match.addr</structfield> by one until | ||
| 81 | <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;. | ||
| 82 | The number zero always selects the host chip, ⪚ the chip connected | ||
| 83 | to the PCI or USB bus.</para> | ||
| 84 | |||
| 85 | <para>When <structfield>match.type</structfield> is | ||
| 86 | <constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant>, | ||
| 87 | <structfield>match.name</structfield> contains the I2C driver name. | ||
| 88 | For instance | ||
| 89 | <constant>"saa7127"</constant> will match any chip | ||
| 90 | supported by the saa7127 driver, regardless of its &i2c; bus address. | ||
| 91 | When multiple chips supported by the same driver are present, the | ||
| 92 | ioctl will return <constant>V4L2_IDENT_AMBIGUOUS</constant> in the | ||
| 93 | <structfield>ident</structfield> field.</para> | ||
| 94 | |||
| 95 | <para>When <structfield>match.type</structfield> is | ||
| 96 | <constant>V4L2_CHIP_MATCH_I2C_ADDR</constant>, | ||
| 97 | <structfield>match.addr</structfield> selects a chip by its 7 bit | ||
| 98 | &i2c; bus address.</para> | ||
| 99 | |||
| 100 | <para>When <structfield>match.type</structfield> is | ||
| 101 | <constant>V4L2_CHIP_MATCH_AC97</constant>, | ||
| 102 | <structfield>match.addr</structfield> selects the nth AC97 chip | ||
| 103 | on the TV card. You can enumerate all chips by starting at zero and | ||
| 104 | incrementing <structfield>match.addr</structfield> by one until | ||
| 105 | <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;.</para> | ||
| 106 | |||
| 107 | <para>On success, the <structfield>ident</structfield> field will | ||
| 108 | contain a chip ID from the Linux | ||
| 109 | <filename>media/v4l2-chip-ident.h</filename> header file, and the | ||
| 110 | <structfield>revision</structfield> field will contain a driver | ||
| 111 | specific value, or zero if no particular revision is associated with | ||
| 112 | this chip.</para> | ||
| 113 | |||
| 114 | <para>When the driver could not identify the selected chip, | ||
| 115 | <structfield>ident</structfield> will contain | ||
| 116 | <constant>V4L2_IDENT_UNKNOWN</constant>. When no chip matched | ||
| 117 | the ioctl will succeed but the | ||
| 118 | <structfield>ident</structfield> field will contain | ||
| 119 | <constant>V4L2_IDENT_NONE</constant>. If multiple chips matched, | ||
| 120 | <structfield>ident</structfield> will contain | ||
| 121 | <constant>V4L2_IDENT_AMBIGUOUS</constant>. In all these cases the | ||
| 122 | <structfield>revision</structfield> field remains unchanged.</para> | ||
| 123 | |||
| 124 | <para>This ioctl is optional, not all drivers may support it. It | ||
| 125 | was introduced in Linux 2.6.21, but the API was changed to the | ||
| 126 | one described here in 2.6.29.</para> | ||
| 127 | |||
| 128 | <para>We recommended the <application>v4l2-dbg</application> | ||
| 129 | utility over calling this ioctl directly. It is available from the | ||
| 130 | LinuxTV v4l-dvb repository; see <ulink | ||
| 131 | url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for | ||
| 132 | access instructions.</para> | ||
| 133 | |||
| 134 | <!-- Note for convenience vidioc-dbg-g-register.sgml | ||
| 135 | contains a duplicate of this table. --> | ||
| 136 | <table pgwide="1" frame="none" id="ident-v4l2-dbg-match"> | ||
| 137 | <title>struct <structname>v4l2_dbg_match</structname></title> | ||
| 138 | <tgroup cols="4"> | ||
| 139 | &cs-ustr; | ||
| 140 | <tbody valign="top"> | ||
| 141 | <row> | ||
| 142 | <entry>__u32</entry> | ||
| 143 | <entry><structfield>type</structfield></entry> | ||
| 144 | <entry>See <xref linkend="ident-chip-match-types" /> for a list of | ||
| 145 | possible types.</entry> | ||
| 146 | </row> | ||
| 147 | <row> | ||
| 148 | <entry>union</entry> | ||
| 149 | <entry>(anonymous)</entry> | ||
| 150 | </row> | ||
| 151 | <row> | ||
| 152 | <entry></entry> | ||
| 153 | <entry>__u32</entry> | ||
| 154 | <entry><structfield>addr</structfield></entry> | ||
| 155 | <entry>Match a chip by this number, interpreted according | ||
| 156 | to the <structfield>type</structfield> field.</entry> | ||
| 157 | </row> | ||
| 158 | <row> | ||
| 159 | <entry></entry> | ||
| 160 | <entry>char</entry> | ||
| 161 | <entry><structfield>name[32]</structfield></entry> | ||
| 162 | <entry>Match a chip by this name, interpreted according | ||
| 163 | to the <structfield>type</structfield> field.</entry> | ||
| 164 | </row> | ||
| 165 | </tbody> | ||
| 166 | </tgroup> | ||
| 167 | </table> | ||
| 168 | |||
| 169 | <table pgwide="1" frame="none" id="v4l2-dbg-chip-ident"> | ||
| 170 | <title>struct <structname>v4l2_dbg_chip_ident</structname></title> | ||
| 171 | <tgroup cols="3"> | ||
| 172 | &cs-str; | ||
| 173 | <tbody valign="top"> | ||
| 174 | <row> | ||
| 175 | <entry>struct v4l2_dbg_match</entry> | ||
| 176 | <entry><structfield>match</structfield></entry> | ||
| 177 | <entry>How to match the chip, see <xref linkend="ident-v4l2-dbg-match" />.</entry> | ||
| 178 | </row> | ||
| 179 | <row> | ||
| 180 | <entry>__u32</entry> | ||
| 181 | <entry><structfield>ident</structfield></entry> | ||
| 182 | <entry>A chip identifier as defined in the Linux | ||
| 183 | <filename>media/v4l2-chip-ident.h</filename> header file, or one of | ||
| 184 | the values from <xref linkend="chip-ids" />.</entry> | ||
| 185 | </row> | ||
| 186 | <row> | ||
| 187 | <entry>__u32</entry> | ||
| 188 | <entry><structfield>revision</structfield></entry> | ||
| 189 | <entry>A chip revision, chip and driver specific.</entry> | ||
| 190 | </row> | ||
| 191 | </tbody> | ||
| 192 | </tgroup> | ||
| 193 | </table> | ||
| 194 | |||
| 195 | <!-- Note for convenience vidioc-dbg-g-register.sgml | ||
| 196 | contains a duplicate of this table. --> | ||
| 197 | <table pgwide="1" frame="none" id="ident-chip-match-types"> | ||
| 198 | <title>Chip Match Types</title> | ||
| 199 | <tgroup cols="3"> | ||
| 200 | &cs-def; | ||
| 201 | <tbody valign="top"> | ||
| 202 | <row> | ||
| 203 | <entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry> | ||
| 204 | <entry>0</entry> | ||
| 205 | <entry>Match the nth chip on the card, zero for the | ||
| 206 | host chip. Does not match &i2c; chips.</entry> | ||
| 207 | </row> | ||
| 208 | <row> | ||
| 209 | <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry> | ||
| 210 | <entry>1</entry> | ||
| 211 | <entry>Match an &i2c; chip by its driver name.</entry> | ||
| 212 | </row> | ||
| 213 | <row> | ||
| 214 | <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry> | ||
| 215 | <entry>2</entry> | ||
| 216 | <entry>Match a chip by its 7 bit &i2c; bus address.</entry> | ||
| 217 | </row> | ||
| 218 | <row> | ||
| 219 | <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry> | ||
| 220 | <entry>3</entry> | ||
| 221 | <entry>Match the nth anciliary AC97 chip.</entry> | ||
| 222 | </row> | ||
| 223 | </tbody> | ||
| 224 | </tgroup> | ||
| 225 | </table> | ||
| 226 | |||
| 227 | <!-- This is an anonymous enum in media/v4l2-chip-ident.h. --> | ||
| 228 | <table pgwide="1" frame="none" id="chip-ids"> | ||
| 229 | <title>Chip Identifiers</title> | ||
| 230 | <tgroup cols="3"> | ||
| 231 | &cs-def; | ||
| 232 | <tbody valign="top"> | ||
| 233 | <row> | ||
| 234 | <entry><constant>V4L2_IDENT_NONE</constant></entry> | ||
| 235 | <entry>0</entry> | ||
| 236 | <entry>No chip matched.</entry> | ||
| 237 | </row> | ||
| 238 | <row> | ||
| 239 | <entry><constant>V4L2_IDENT_AMBIGUOUS</constant></entry> | ||
| 240 | <entry>1</entry> | ||
| 241 | <entry>Multiple chips matched.</entry> | ||
| 242 | </row> | ||
| 243 | <row> | ||
| 244 | <entry><constant>V4L2_IDENT_UNKNOWN</constant></entry> | ||
| 245 | <entry>2</entry> | ||
| 246 | <entry>A chip is present at this address, but the driver | ||
| 247 | could not identify it.</entry> | ||
| 248 | </row> | ||
| 249 | </tbody> | ||
| 250 | </tgroup> | ||
| 251 | </table> | ||
| 252 | </refsect1> | ||
| 253 | |||
| 254 | <refsect1> | ||
| 255 | &return-value; | ||
| 256 | |||
| 257 | <variablelist> | ||
| 258 | <varlistentry> | ||
| 259 | <term><errorcode>EINVAL</errorcode></term> | ||
| 260 | <listitem> | ||
| 261 | <para>The driver does not support this ioctl, or the | ||
| 262 | <structfield>match_type</structfield> is invalid.</para> | ||
| 263 | </listitem> | ||
| 264 | </varlistentry> | ||
| 265 | </variablelist> | ||
| 266 | </refsect1> | ||
| 267 | </refentry> | ||
| 268 | |||
| 269 | <!-- | ||
| 270 | Local Variables: | ||
| 271 | mode: sgml | ||
| 272 | sgml-parent-document: "v4l2.sgml" | ||
| 273 | indent-tabs-mode: nil | ||
| 274 | End: | ||
| 275 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-dbg-g-register.xml b/Documentation/DocBook/v4l/vidioc-dbg-g-register.xml new file mode 100644 index 000000000000..980c7f3e2fd6 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-dbg-g-register.xml | |||
| @@ -0,0 +1,275 @@ | |||
| 1 | <refentry id="vidioc-dbg-g-register"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_DBG_G_REGISTER</refname> | ||
| 9 | <refname>VIDIOC_DBG_S_REGISTER</refname> | ||
| 10 | <refpurpose>Read or write hardware registers</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_dbg_register *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>const struct v4l2_dbg_register | ||
| 28 | *<parameter>argp</parameter></paramdef> | ||
| 29 | </funcprototype> | ||
| 30 | </funcsynopsis> | ||
| 31 | </refsynopsisdiv> | ||
| 32 | |||
| 33 | <refsect1> | ||
| 34 | <title>Arguments</title> | ||
| 35 | |||
| 36 | <variablelist> | ||
| 37 | <varlistentry> | ||
| 38 | <term><parameter>fd</parameter></term> | ||
| 39 | <listitem> | ||
| 40 | <para>&fd;</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | <varlistentry> | ||
| 44 | <term><parameter>request</parameter></term> | ||
| 45 | <listitem> | ||
| 46 | <para>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</para> | ||
| 47 | </listitem> | ||
| 48 | </varlistentry> | ||
| 49 | <varlistentry> | ||
| 50 | <term><parameter>argp</parameter></term> | ||
| 51 | <listitem> | ||
| 52 | <para></para> | ||
| 53 | </listitem> | ||
| 54 | </varlistentry> | ||
| 55 | </variablelist> | ||
| 56 | </refsect1> | ||
| 57 | |||
| 58 | <refsect1> | ||
| 59 | <title>Description</title> | ||
| 60 | |||
| 61 | <note> | ||
| 62 | <title>Experimental</title> | ||
| 63 | |||
| 64 | <para>This is an <link linkend="experimental">experimental</link> | ||
| 65 | interface and may change in the future.</para> | ||
| 66 | </note> | ||
| 67 | |||
| 68 | <para>For driver debugging purposes these ioctls allow test | ||
| 69 | applications to access hardware registers directly. Regular | ||
| 70 | applications must not use them.</para> | ||
| 71 | |||
| 72 | <para>Since writing or even reading registers can jeopardize the | ||
| 73 | system security, its stability and damage the hardware, both ioctls | ||
| 74 | require superuser privileges. Additionally the Linux kernel must be | ||
| 75 | compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option | ||
| 76 | to enable these ioctls.</para> | ||
| 77 | |||
| 78 | <para>To write a register applications must initialize all fields | ||
| 79 | of a &v4l2-dbg-register; and call | ||
| 80 | <constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this | ||
| 81 | structure. The <structfield>match.type</structfield> and | ||
| 82 | <structfield>match.addr</structfield> or <structfield>match.name</structfield> | ||
| 83 | fields select a chip on the TV | ||
| 84 | card, the <structfield>reg</structfield> field specifies a register | ||
| 85 | number and the <structfield>val</structfield> field the value to be | ||
| 86 | written into the register.</para> | ||
| 87 | |||
| 88 | <para>To read a register applications must initialize the | ||
| 89 | <structfield>match.type</structfield>, | ||
| 90 | <structfield>match.chip</structfield> or <structfield>match.name</structfield> and | ||
| 91 | <structfield>reg</structfield> fields, and call | ||
| 92 | <constant>VIDIOC_DBG_G_REGISTER</constant> with a pointer to this | ||
| 93 | structure. On success the driver stores the register value in the | ||
| 94 | <structfield>val</structfield> field. On failure the structure remains | ||
| 95 | unchanged.</para> | ||
| 96 | |||
| 97 | <para>When <structfield>match.type</structfield> is | ||
| 98 | <constant>V4L2_CHIP_MATCH_HOST</constant>, | ||
| 99 | <structfield>match.addr</structfield> selects the nth non-&i2c; chip | ||
| 100 | on the TV card. The number zero always selects the host chip, ⪚ the | ||
| 101 | chip connected to the PCI or USB bus. You can find out which chips are | ||
| 102 | present with the &VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para> | ||
| 103 | |||
| 104 | <para>When <structfield>match.type</structfield> is | ||
| 105 | <constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant>, | ||
| 106 | <structfield>match.name</structfield> contains the I2C driver name. | ||
| 107 | For instance | ||
| 108 | <constant>"saa7127"</constant> will match any chip | ||
| 109 | supported by the saa7127 driver, regardless of its &i2c; bus address. | ||
| 110 | When multiple chips supported by the same driver are present, the | ||
| 111 | effect of these ioctls is undefined. Again with the | ||
| 112 | &VIDIOC-DBG-G-CHIP-IDENT; ioctl you can find out which &i2c; chips are | ||
| 113 | present.</para> | ||
| 114 | |||
| 115 | <para>When <structfield>match.type</structfield> is | ||
| 116 | <constant>V4L2_CHIP_MATCH_I2C_ADDR</constant>, | ||
| 117 | <structfield>match.addr</structfield> selects a chip by its 7 bit &i2c; | ||
| 118 | bus address.</para> | ||
| 119 | |||
| 120 | <para>When <structfield>match.type</structfield> is | ||
| 121 | <constant>V4L2_CHIP_MATCH_AC97</constant>, | ||
| 122 | <structfield>match.addr</structfield> selects the nth AC97 chip | ||
| 123 | on the TV card.</para> | ||
| 124 | |||
| 125 | <note> | ||
| 126 | <title>Success not guaranteed</title> | ||
| 127 | |||
| 128 | <para>Due to a flaw in the Linux &i2c; bus driver these ioctls may | ||
| 129 | return successfully without actually reading or writing a register. To | ||
| 130 | catch the most likely failure we recommend a &VIDIOC-DBG-G-CHIP-IDENT; | ||
| 131 | call confirming the presence of the selected &i2c; chip.</para> | ||
| 132 | </note> | ||
| 133 | |||
| 134 | <para>These ioctls are optional, not all drivers may support them. | ||
| 135 | However when a driver supports these ioctls it must also support | ||
| 136 | &VIDIOC-DBG-G-CHIP-IDENT;. Conversely it may support | ||
| 137 | <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> but not these ioctls.</para> | ||
| 138 | |||
| 139 | <para><constant>VIDIOC_DBG_G_REGISTER</constant> and | ||
| 140 | <constant>VIDIOC_DBG_S_REGISTER</constant> were introduced in Linux | ||
| 141 | 2.6.21, but their API was changed to the one described here in kernel 2.6.29.</para> | ||
| 142 | |||
| 143 | <para>We recommended the <application>v4l2-dbg</application> | ||
| 144 | utility over calling these ioctls directly. It is available from the | ||
| 145 | LinuxTV v4l-dvb repository; see <ulink | ||
| 146 | url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for | ||
| 147 | access instructions.</para> | ||
| 148 | |||
| 149 | <!-- Note for convenience vidioc-dbg-g-chip-ident.sgml | ||
| 150 | contains a duplicate of this table. --> | ||
| 151 | <table pgwide="1" frame="none" id="v4l2-dbg-match"> | ||
| 152 | <title>struct <structname>v4l2_dbg_match</structname></title> | ||
| 153 | <tgroup cols="4"> | ||
| 154 | &cs-ustr; | ||
| 155 | <tbody valign="top"> | ||
| 156 | <row> | ||
| 157 | <entry>__u32</entry> | ||
| 158 | <entry><structfield>type</structfield></entry> | ||
| 159 | <entry>See <xref linkend="ident-chip-match-types" /> for a list of | ||
| 160 | possible types.</entry> | ||
| 161 | </row> | ||
| 162 | <row> | ||
| 163 | <entry>union</entry> | ||
| 164 | <entry>(anonymous)</entry> | ||
| 165 | </row> | ||
| 166 | <row> | ||
| 167 | <entry></entry> | ||
| 168 | <entry>__u32</entry> | ||
| 169 | <entry><structfield>addr</structfield></entry> | ||
| 170 | <entry>Match a chip by this number, interpreted according | ||
| 171 | to the <structfield>type</structfield> field.</entry> | ||
| 172 | </row> | ||
| 173 | <row> | ||
| 174 | <entry></entry> | ||
| 175 | <entry>char</entry> | ||
| 176 | <entry><structfield>name[32]</structfield></entry> | ||
| 177 | <entry>Match a chip by this name, interpreted according | ||
| 178 | to the <structfield>type</structfield> field.</entry> | ||
| 179 | </row> | ||
| 180 | </tbody> | ||
| 181 | </tgroup> | ||
| 182 | </table> | ||
| 183 | |||
| 184 | |||
| 185 | <table pgwide="1" frame="none" id="v4l2-dbg-register"> | ||
| 186 | <title>struct <structname>v4l2_dbg_register</structname></title> | ||
| 187 | <tgroup cols="4"> | ||
| 188 | <colspec colname="c1" /> | ||
| 189 | <colspec colname="c2" /> | ||
| 190 | <colspec colname="c4" /> | ||
| 191 | <tbody valign="top"> | ||
| 192 | <row> | ||
| 193 | <entry>struct v4l2_dbg_match</entry> | ||
| 194 | <entry><structfield>match</structfield></entry> | ||
| 195 | <entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry> | ||
| 196 | </row> | ||
| 197 | <row> | ||
| 198 | <entry>__u64</entry> | ||
| 199 | <entry><structfield>reg</structfield></entry> | ||
| 200 | <entry>A register number.</entry> | ||
| 201 | </row> | ||
| 202 | <row> | ||
| 203 | <entry>__u64</entry> | ||
| 204 | <entry><structfield>val</structfield></entry> | ||
| 205 | <entry>The value read from, or to be written into the | ||
| 206 | register.</entry> | ||
| 207 | </row> | ||
| 208 | </tbody> | ||
| 209 | </tgroup> | ||
| 210 | </table> | ||
| 211 | |||
| 212 | <!-- Note for convenience vidioc-dbg-g-chip-ident.sgml | ||
| 213 | contains a duplicate of this table. --> | ||
| 214 | <table pgwide="1" frame="none" id="chip-match-types"> | ||
| 215 | <title>Chip Match Types</title> | ||
| 216 | <tgroup cols="3"> | ||
| 217 | &cs-def; | ||
| 218 | <tbody valign="top"> | ||
| 219 | <row> | ||
| 220 | <entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry> | ||
| 221 | <entry>0</entry> | ||
| 222 | <entry>Match the nth chip on the card, zero for the | ||
| 223 | host chip. Does not match &i2c; chips.</entry> | ||
| 224 | </row> | ||
| 225 | <row> | ||
| 226 | <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry> | ||
| 227 | <entry>1</entry> | ||
| 228 | <entry>Match an &i2c; chip by its driver name.</entry> | ||
| 229 | </row> | ||
| 230 | <row> | ||
| 231 | <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry> | ||
| 232 | <entry>2</entry> | ||
| 233 | <entry>Match a chip by its 7 bit &i2c; bus address.</entry> | ||
| 234 | </row> | ||
| 235 | <row> | ||
| 236 | <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry> | ||
| 237 | <entry>3</entry> | ||
| 238 | <entry>Match the nth anciliary AC97 chip.</entry> | ||
| 239 | </row> | ||
| 240 | </tbody> | ||
| 241 | </tgroup> | ||
| 242 | </table> | ||
| 243 | </refsect1> | ||
| 244 | |||
| 245 | <refsect1> | ||
| 246 | &return-value; | ||
| 247 | |||
| 248 | <variablelist> | ||
| 249 | <varlistentry> | ||
| 250 | <term><errorcode>EINVAL</errorcode></term> | ||
| 251 | <listitem> | ||
| 252 | <para>The driver does not support this ioctl, or the kernel | ||
| 253 | was not compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> | ||
| 254 | option, or the <structfield>match_type</structfield> is invalid, or the | ||
| 255 | selected chip or register does not exist.</para> | ||
| 256 | </listitem> | ||
| 257 | </varlistentry> | ||
| 258 | <varlistentry> | ||
| 259 | <term><errorcode>EPERM</errorcode></term> | ||
| 260 | <listitem> | ||
| 261 | <para>Insufficient permissions. Root privileges are required | ||
| 262 | to execute these ioctls.</para> | ||
| 263 | </listitem> | ||
| 264 | </varlistentry> | ||
| 265 | </variablelist> | ||
| 266 | </refsect1> | ||
| 267 | </refentry> | ||
| 268 | |||
| 269 | <!-- | ||
| 270 | Local Variables: | ||
| 271 | mode: sgml | ||
| 272 | sgml-parent-document: "v4l2.sgml" | ||
| 273 | indent-tabs-mode: nil | ||
| 274 | End: | ||
| 275 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/v4l/vidioc-encoder-cmd.xml new file mode 100644 index 000000000000..b0dde943825c --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-encoder-cmd.xml | |||
| @@ -0,0 +1,204 @@ | |||
| 1 | <refentry id="vidioc-encoder-cmd"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENCODER_CMD</refname> | ||
| 9 | <refname>VIDIOC_TRY_ENCODER_CMD</refname> | ||
| 10 | <refpurpose>Execute an encoder command</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_encoder_cmd *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <note> | ||
| 53 | <title>Experimental</title> | ||
| 54 | |||
| 55 | <para>This is an <link linkend="experimental">experimental</link> | ||
| 56 | interface and may change in the future.</para> | ||
| 57 | </note> | ||
| 58 | |||
| 59 | <para>These ioctls control an audio/video (usually MPEG-) encoder. | ||
| 60 | <constant>VIDIOC_ENCODER_CMD</constant> sends a command to the | ||
| 61 | encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to | ||
| 62 | try a command without actually executing it.</para> | ||
| 63 | |||
| 64 | <para>To send a command applications must initialize all fields of a | ||
| 65 | &v4l2-encoder-cmd; and call | ||
| 66 | <constant>VIDIOC_ENCODER_CMD</constant> or | ||
| 67 | <constant>VIDIOC_TRY_ENCODER_CMD</constant> with a pointer to this | ||
| 68 | structure.</para> | ||
| 69 | |||
| 70 | <para>The <structfield>cmd</structfield> field must contain the | ||
| 71 | command code. The <structfield>flags</structfield> field is currently | ||
| 72 | only used by the STOP command and contains one bit: If the | ||
| 73 | <constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set, | ||
| 74 | encoding will continue until the end of the current <wordasword>Group | ||
| 75 | Of Pictures</wordasword>, otherwise it will stop immediately.</para> | ||
| 76 | |||
| 77 | <para>A <function>read</function>() call sends a START command to | ||
| 78 | the encoder if it has not been started yet. After a STOP command, | ||
| 79 | <function>read</function>() calls will read the remaining data | ||
| 80 | buffered by the driver. When the buffer is empty, | ||
| 81 | <function>read</function>() will return zero and the next | ||
| 82 | <function>read</function>() call will restart the encoder.</para> | ||
| 83 | |||
| 84 | <para>A <function>close</function>() call sends an immediate STOP | ||
| 85 | to the encoder, and all buffered data is discarded.</para> | ||
| 86 | |||
| 87 | <para>These ioctls are optional, not all drivers may support | ||
| 88 | them. They were introduced in Linux 2.6.21.</para> | ||
| 89 | |||
| 90 | <table pgwide="1" frame="none" id="v4l2-encoder-cmd"> | ||
| 91 | <title>struct <structname>v4l2_encoder_cmd</structname></title> | ||
| 92 | <tgroup cols="3"> | ||
| 93 | &cs-str; | ||
| 94 | <tbody valign="top"> | ||
| 95 | <row> | ||
| 96 | <entry>__u32</entry> | ||
| 97 | <entry><structfield>cmd</structfield></entry> | ||
| 98 | <entry>The encoder command, see <xref linkend="encoder-cmds" />.</entry> | ||
| 99 | </row> | ||
| 100 | <row> | ||
| 101 | <entry>__u32</entry> | ||
| 102 | <entry><structfield>flags</structfield></entry> | ||
| 103 | <entry>Flags to go with the command, see <xref | ||
| 104 | linkend="encoder-flags" />. If no flags are defined for | ||
| 105 | this command, drivers and applications must set this field to | ||
| 106 | zero.</entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry>__u32</entry> | ||
| 110 | <entry><structfield>data</structfield>[8]</entry> | ||
| 111 | <entry>Reserved for future extensions. Drivers and | ||
| 112 | applications must set the array to zero.</entry> | ||
| 113 | </row> | ||
| 114 | </tbody> | ||
| 115 | </tgroup> | ||
| 116 | </table> | ||
| 117 | |||
| 118 | <table pgwide="1" frame="none" id="encoder-cmds"> | ||
| 119 | <title>Encoder Commands</title> | ||
| 120 | <tgroup cols="3"> | ||
| 121 | &cs-def; | ||
| 122 | <tbody valign="top"> | ||
| 123 | <row> | ||
| 124 | <entry><constant>V4L2_ENC_CMD_START</constant></entry> | ||
| 125 | <entry>0</entry> | ||
| 126 | <entry>Start the encoder. When the encoder is already | ||
| 127 | running or paused, this command does nothing. No flags are defined for | ||
| 128 | this command.</entry> | ||
| 129 | </row> | ||
| 130 | <row> | ||
| 131 | <entry><constant>V4L2_ENC_CMD_STOP</constant></entry> | ||
| 132 | <entry>1</entry> | ||
| 133 | <entry>Stop the encoder. When the | ||
| 134 | <constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set, | ||
| 135 | encoding will continue until the end of the current <wordasword>Group | ||
| 136 | Of Pictures</wordasword>, otherwise encoding will stop immediately. | ||
| 137 | When the encoder is already stopped, this command does | ||
| 138 | nothing.</entry> | ||
| 139 | </row> | ||
| 140 | <row> | ||
| 141 | <entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry> | ||
| 142 | <entry>2</entry> | ||
| 143 | <entry>Pause the encoder. When the encoder has not been | ||
| 144 | started yet, the driver will return an &EPERM;. When the encoder is | ||
| 145 | already paused, this command does nothing. No flags are defined for | ||
| 146 | this command.</entry> | ||
| 147 | </row> | ||
| 148 | <row> | ||
| 149 | <entry><constant>V4L2_ENC_CMD_RESUME</constant></entry> | ||
| 150 | <entry>3</entry> | ||
| 151 | <entry>Resume encoding after a PAUSE command. When the | ||
| 152 | encoder has not been started yet, the driver will return an &EPERM;. | ||
| 153 | When the encoder is already running, this command does nothing. No | ||
| 154 | flags are defined for this command.</entry> | ||
| 155 | </row> | ||
| 156 | </tbody> | ||
| 157 | </tgroup> | ||
| 158 | </table> | ||
| 159 | |||
| 160 | <table pgwide="1" frame="none" id="encoder-flags"> | ||
| 161 | <title>Encoder Command Flags</title> | ||
| 162 | <tgroup cols="3"> | ||
| 163 | &cs-def; | ||
| 164 | <tbody valign="top"> | ||
| 165 | <row> | ||
| 166 | <entry><constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant></entry> | ||
| 167 | <entry>0x0001</entry> | ||
| 168 | <entry>Stop encoding at the end of the current <wordasword>Group Of | ||
| 169 | Pictures</wordasword>, rather than immediately.</entry> | ||
| 170 | </row> | ||
| 171 | </tbody> | ||
| 172 | </tgroup> | ||
| 173 | </table> | ||
| 174 | </refsect1> | ||
| 175 | |||
| 176 | <refsect1> | ||
| 177 | &return-value; | ||
| 178 | |||
| 179 | <variablelist> | ||
| 180 | <varlistentry> | ||
| 181 | <term><errorcode>EINVAL</errorcode></term> | ||
| 182 | <listitem> | ||
| 183 | <para>The driver does not support this ioctl, or the | ||
| 184 | <structfield>cmd</structfield> field is invalid.</para> | ||
| 185 | </listitem> | ||
| 186 | </varlistentry> | ||
| 187 | <varlistentry> | ||
| 188 | <term><errorcode>EPERM</errorcode></term> | ||
| 189 | <listitem> | ||
| 190 | <para>The application sent a PAUSE or RESUME command when | ||
| 191 | the encoder was not running.</para> | ||
| 192 | </listitem> | ||
| 193 | </varlistentry> | ||
| 194 | </variablelist> | ||
| 195 | </refsect1> | ||
| 196 | </refentry> | ||
| 197 | |||
| 198 | <!-- | ||
| 199 | Local Variables: | ||
| 200 | mode: sgml | ||
| 201 | sgml-parent-document: "v4l2.sgml" | ||
| 202 | indent-tabs-mode: nil | ||
| 203 | End: | ||
| 204 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml new file mode 100644 index 000000000000..960d44615ca6 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml | |||
| @@ -0,0 +1,164 @@ | |||
| 1 | <refentry id="vidioc-enum-fmt"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUM_FMT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUM_FMT</refname> | ||
| 9 | <refpurpose>Enumerate image formats</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_fmtdesc | ||
| 19 | *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_ENUM_FMT</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>To enumerate image formats applications initialize the | ||
| 53 | <structfield>type</structfield> and <structfield>index</structfield> | ||
| 54 | field of &v4l2-fmtdesc; and call the | ||
| 55 | <constant>VIDIOC_ENUM_FMT</constant> ioctl with a pointer to this | ||
| 56 | structure. Drivers fill the rest of the structure or return an | ||
| 57 | &EINVAL;. All formats are enumerable by beginning at index zero and | ||
| 58 | incrementing by one until <errorcode>EINVAL</errorcode> is | ||
| 59 | returned.</para> | ||
| 60 | |||
| 61 | <table pgwide="1" frame="none" id="v4l2-fmtdesc"> | ||
| 62 | <title>struct <structname>v4l2_fmtdesc</structname></title> | ||
| 63 | <tgroup cols="3"> | ||
| 64 | &cs-str; | ||
| 65 | <tbody valign="top"> | ||
| 66 | <row> | ||
| 67 | <entry>__u32</entry> | ||
| 68 | <entry><structfield>index</structfield></entry> | ||
| 69 | <entry>Number of the format in the enumeration, set by | ||
| 70 | the application. This is in no way related to the <structfield> | ||
| 71 | pixelformat</structfield> field.</entry> | ||
| 72 | </row> | ||
| 73 | <row> | ||
| 74 | <entry>&v4l2-buf-type;</entry> | ||
| 75 | <entry><structfield>type</structfield></entry> | ||
| 76 | <entry>Type of the data stream, set by the application. | ||
| 77 | Only these types are valid here: | ||
| 78 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, | ||
| 79 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, | ||
| 80 | <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver | ||
| 81 | defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> | ||
| 82 | and higher.</entry> | ||
| 83 | </row> | ||
| 84 | <row> | ||
| 85 | <entry>__u32</entry> | ||
| 86 | <entry><structfield>flags</structfield></entry> | ||
| 87 | <entry>See <xref linkend="fmtdesc-flags" /></entry> | ||
| 88 | </row> | ||
| 89 | <row> | ||
| 90 | <entry>__u8</entry> | ||
| 91 | <entry><structfield>description</structfield>[32]</entry> | ||
| 92 | <entry>Description of the format, a NUL-terminated ASCII | ||
| 93 | string. This information is intended for the user, for example: "YUV | ||
| 94 | 4:2:2".</entry> | ||
| 95 | </row> | ||
| 96 | <row> | ||
| 97 | <entry>__u32</entry> | ||
| 98 | <entry><structfield>pixelformat</structfield></entry> | ||
| 99 | <entry>The image format identifier. This is a | ||
| 100 | four character code as computed by the v4l2_fourcc() | ||
| 101 | macro:</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry spanname="hspan"><para><programlisting id="v4l2-fourcc"> | ||
| 105 | #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) | ||
| 106 | </programlisting></para><para>Several image formats are already | ||
| 107 | defined by this specification in <xref linkend="pixfmt" />. Note these | ||
| 108 | codes are not the same as those used in the Windows world.</para></entry> | ||
| 109 | </row> | ||
| 110 | <row> | ||
| 111 | <entry>__u32</entry> | ||
| 112 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 113 | <entry>Reserved for future extensions. Drivers must set | ||
| 114 | the array to zero.</entry> | ||
| 115 | </row> | ||
| 116 | </tbody> | ||
| 117 | </tgroup> | ||
| 118 | </table> | ||
| 119 | |||
| 120 | <table pgwide="1" frame="none" id="fmtdesc-flags"> | ||
| 121 | <title>Image Format Description Flags</title> | ||
| 122 | <tgroup cols="3"> | ||
| 123 | &cs-def; | ||
| 124 | <tbody valign="top"> | ||
| 125 | <row> | ||
| 126 | <entry><constant>V4L2_FMT_FLAG_COMPRESSED</constant></entry> | ||
| 127 | <entry>0x0001</entry> | ||
| 128 | <entry>This is a compressed format.</entry> | ||
| 129 | </row> | ||
| 130 | <row> | ||
| 131 | <entry><constant>V4L2_FMT_FLAG_EMULATED</constant></entry> | ||
| 132 | <entry>0x0002</entry> | ||
| 133 | <entry>This format is not native to the device but emulated | ||
| 134 | through software (usually libv4l2), where possible try to use a native format | ||
| 135 | instead for better performance.</entry> | ||
| 136 | </row> | ||
| 137 | </tbody> | ||
| 138 | </tgroup> | ||
| 139 | </table> | ||
| 140 | </refsect1> | ||
| 141 | |||
| 142 | <refsect1> | ||
| 143 | &return-value; | ||
| 144 | |||
| 145 | <variablelist> | ||
| 146 | <varlistentry> | ||
| 147 | <term><errorcode>EINVAL</errorcode></term> | ||
| 148 | <listitem> | ||
| 149 | <para>The &v4l2-fmtdesc; <structfield>type</structfield> | ||
| 150 | is not supported or the <structfield>index</structfield> is out of | ||
| 151 | bounds.</para> | ||
| 152 | </listitem> | ||
| 153 | </varlistentry> | ||
| 154 | </variablelist> | ||
| 155 | </refsect1> | ||
| 156 | </refentry> | ||
| 157 | |||
| 158 | <!-- | ||
| 159 | Local Variables: | ||
| 160 | mode: sgml | ||
| 161 | sgml-parent-document: "v4l2.sgml" | ||
| 162 | indent-tabs-mode: nil | ||
| 163 | End: | ||
| 164 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml b/Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml new file mode 100644 index 000000000000..3c216e113a54 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml | |||
| @@ -0,0 +1,270 @@ | |||
| 1 | <refentry id="vidioc-enum-frameintervals"> | ||
| 2 | |||
| 3 | <refmeta> | ||
| 4 | <refentrytitle>ioctl VIDIOC_ENUM_FRAMEINTERVALS</refentrytitle> | ||
| 5 | &manvol; | ||
| 6 | </refmeta> | ||
| 7 | |||
| 8 | <refnamediv> | ||
| 9 | <refname>VIDIOC_ENUM_FRAMEINTERVALS</refname> | ||
| 10 | <refpurpose>Enumerate frame intervals</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_frmivalenum *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_ENUM_FRAMEINTERVALS</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para>Pointer to a &v4l2-frmivalenum; structure that | ||
| 44 | contains a pixel format and size and receives a frame interval.</para> | ||
| 45 | </listitem> | ||
| 46 | </varlistentry> | ||
| 47 | </variablelist> | ||
| 48 | </refsect1> | ||
| 49 | |||
| 50 | <refsect1> | ||
| 51 | <title>Description</title> | ||
| 52 | |||
| 53 | <para>This ioctl allows applications to enumerate all frame | ||
| 54 | intervals that the device supports for the given pixel format and | ||
| 55 | frame size.</para> | ||
| 56 | <para>The supported pixel formats and frame sizes can be obtained | ||
| 57 | by using the &VIDIOC-ENUM-FMT; and &VIDIOC-ENUM-FRAMESIZES; | ||
| 58 | functions.</para> | ||
| 59 | <para>The return value and the content of the | ||
| 60 | <structfield>v4l2_frmivalenum.type</structfield> field depend on the | ||
| 61 | type of frame intervals the device supports. Here are the semantics of | ||
| 62 | the function for the different cases:</para> | ||
| 63 | <itemizedlist> | ||
| 64 | <listitem> | ||
| 65 | <para><emphasis role="bold">Discrete:</emphasis> The function | ||
| 66 | returns success if the given index value (zero-based) is valid. The | ||
| 67 | application should increase the index by one for each call until | ||
| 68 | <constant>EINVAL</constant> is returned. The `v4l2_frmivalenum.type` | ||
| 69 | field is set to `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the | ||
| 70 | union only the `discrete` member is valid.</para> | ||
| 71 | </listitem> | ||
| 72 | <listitem> | ||
| 73 | <para><emphasis role="bold">Step-wise:</emphasis> The function | ||
| 74 | returns success if the given index value is zero and | ||
| 75 | <constant>EINVAL</constant> for any other index value. The | ||
| 76 | <structfield>v4l2_frmivalenum.type</structfield> field is set to | ||
| 77 | <constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant> by the driver. Of the | ||
| 78 | union only the <structfield>stepwise</structfield> member is | ||
| 79 | valid.</para> | ||
| 80 | </listitem> | ||
| 81 | <listitem> | ||
| 82 | <para><emphasis role="bold">Continuous:</emphasis> This is a | ||
| 83 | special case of the step-wise type above. The function returns success | ||
| 84 | if the given index value is zero and <constant>EINVAL</constant> for | ||
| 85 | any other index value. The | ||
| 86 | <structfield>v4l2_frmivalenum.type</structfield> field is set to | ||
| 87 | <constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant> by the driver. Of | ||
| 88 | the union only the <structfield>stepwise</structfield> member is valid | ||
| 89 | and the <structfield>step</structfield> value is set to 1.</para> | ||
| 90 | </listitem> | ||
| 91 | </itemizedlist> | ||
| 92 | |||
| 93 | <para>When the application calls the function with index zero, it | ||
| 94 | must check the <structfield>type</structfield> field to determine the | ||
| 95 | type of frame interval enumeration the device supports. Only for the | ||
| 96 | <constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant> type does it make | ||
| 97 | sense to increase the index value to receive more frame | ||
| 98 | intervals.</para> | ||
| 99 | <para>Note that the order in which the frame intervals are | ||
| 100 | returned has no special meaning. In particular does it not say | ||
| 101 | anything about potential default frame intervals.</para> | ||
| 102 | <para>Applications can assume that the enumeration data does not | ||
| 103 | change without any interaction from the application itself. This means | ||
| 104 | that the enumeration data is consistent if the application does not | ||
| 105 | perform any other ioctl calls while it runs the frame interval | ||
| 106 | enumeration.</para> | ||
| 107 | </refsect1> | ||
| 108 | |||
| 109 | <refsect1> | ||
| 110 | <title>Notes</title> | ||
| 111 | |||
| 112 | <itemizedlist> | ||
| 113 | <listitem> | ||
| 114 | <para><emphasis role="bold">Frame intervals and frame | ||
| 115 | rates:</emphasis> The V4L2 API uses frame intervals instead of frame | ||
| 116 | rates. Given the frame interval the frame rate can be computed as | ||
| 117 | follows:<screen>frame_rate = 1 / frame_interval</screen></para> | ||
| 118 | </listitem> | ||
| 119 | </itemizedlist> | ||
| 120 | |||
| 121 | </refsect1> | ||
| 122 | |||
| 123 | <refsect1> | ||
| 124 | <title>Structs</title> | ||
| 125 | |||
| 126 | <para>In the structs below, <emphasis>IN</emphasis> denotes a | ||
| 127 | value that has to be filled in by the application, | ||
| 128 | <emphasis>OUT</emphasis> denotes values that the driver fills in. The | ||
| 129 | application should zero out all members except for the | ||
| 130 | <emphasis>IN</emphasis> fields.</para> | ||
| 131 | |||
| 132 | <table pgwide="1" frame="none" id="v4l2-frmival-stepwise"> | ||
| 133 | <title>struct <structname>v4l2_frmival_stepwise</structname></title> | ||
| 134 | <tgroup cols="3"> | ||
| 135 | &cs-str; | ||
| 136 | <tbody valign="top"> | ||
| 137 | <row> | ||
| 138 | <entry>&v4l2-fract;</entry> | ||
| 139 | <entry><structfield>min</structfield></entry> | ||
| 140 | <entry>Minimum frame interval [s].</entry> | ||
| 141 | </row> | ||
| 142 | <row> | ||
| 143 | <entry>&v4l2-fract;</entry> | ||
| 144 | <entry><structfield>max</structfield></entry> | ||
| 145 | <entry>Maximum frame interval [s].</entry> | ||
| 146 | </row> | ||
| 147 | <row> | ||
| 148 | <entry>&v4l2-fract;</entry> | ||
| 149 | <entry><structfield>step</structfield></entry> | ||
| 150 | <entry>Frame interval step size [s].</entry> | ||
| 151 | </row> | ||
| 152 | </tbody> | ||
| 153 | </tgroup> | ||
| 154 | </table> | ||
| 155 | |||
| 156 | <table pgwide="1" frame="none" id="v4l2-frmivalenum"> | ||
| 157 | <title>struct <structname>v4l2_frmivalenum</structname></title> | ||
| 158 | <tgroup cols="4"> | ||
| 159 | <colspec colname="c1" /> | ||
| 160 | <colspec colname="c2" /> | ||
| 161 | <colspec colname="c3" /> | ||
| 162 | <colspec colname="c4" /> | ||
| 163 | <tbody valign="top"> | ||
| 164 | <row> | ||
| 165 | <entry>__u32</entry> | ||
| 166 | <entry><structfield>index</structfield></entry> | ||
| 167 | <entry></entry> | ||
| 168 | <entry>IN: Index of the given frame interval in the | ||
| 169 | enumeration.</entry> | ||
| 170 | </row> | ||
| 171 | <row> | ||
| 172 | <entry>__u32</entry> | ||
| 173 | <entry><structfield>pixel_format</structfield></entry> | ||
| 174 | <entry></entry> | ||
| 175 | <entry>IN: Pixel format for which the frame intervals are | ||
| 176 | enumerated.</entry> | ||
| 177 | </row> | ||
| 178 | <row> | ||
| 179 | <entry>__u32</entry> | ||
| 180 | <entry><structfield>width</structfield></entry> | ||
| 181 | <entry></entry> | ||
| 182 | <entry>IN: Frame width for which the frame intervals are | ||
| 183 | enumerated.</entry> | ||
| 184 | </row> | ||
| 185 | <row> | ||
| 186 | <entry>__u32</entry> | ||
| 187 | <entry><structfield>height</structfield></entry> | ||
| 188 | <entry></entry> | ||
| 189 | <entry>IN: Frame height for which the frame intervals are | ||
| 190 | enumerated.</entry> | ||
| 191 | </row> | ||
| 192 | <row> | ||
| 193 | <entry>__u32</entry> | ||
| 194 | <entry><structfield>type</structfield></entry> | ||
| 195 | <entry></entry> | ||
| 196 | <entry>OUT: Frame interval type the device supports.</entry> | ||
| 197 | </row> | ||
| 198 | <row> | ||
| 199 | <entry>union</entry> | ||
| 200 | <entry></entry> | ||
| 201 | <entry></entry> | ||
| 202 | <entry>OUT: Frame interval with the given index.</entry> | ||
| 203 | </row> | ||
| 204 | <row> | ||
| 205 | <entry></entry> | ||
| 206 | <entry>&v4l2-fract;</entry> | ||
| 207 | <entry><structfield>discrete</structfield></entry> | ||
| 208 | <entry>Frame interval [s].</entry> | ||
| 209 | </row> | ||
| 210 | <row> | ||
| 211 | <entry></entry> | ||
| 212 | <entry>&v4l2-frmival-stepwise;</entry> | ||
| 213 | <entry><structfield>stepwise</structfield></entry> | ||
| 214 | <entry></entry> | ||
| 215 | </row> | ||
| 216 | <row> | ||
| 217 | <entry>__u32</entry> | ||
| 218 | <entry><structfield>reserved[2]</structfield></entry> | ||
| 219 | <entry></entry> | ||
| 220 | <entry>Reserved space for future use.</entry> | ||
| 221 | </row> | ||
| 222 | </tbody> | ||
| 223 | </tgroup> | ||
| 224 | </table> | ||
| 225 | </refsect1> | ||
| 226 | |||
| 227 | <refsect1> | ||
| 228 | <title>Enums</title> | ||
| 229 | |||
| 230 | <table pgwide="1" frame="none" id="v4l2-frmivaltypes"> | ||
| 231 | <title>enum <structname>v4l2_frmivaltypes</structname></title> | ||
| 232 | <tgroup cols="3"> | ||
| 233 | &cs-def; | ||
| 234 | <tbody valign="top"> | ||
| 235 | <row> | ||
| 236 | <entry><constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant></entry> | ||
| 237 | <entry>1</entry> | ||
| 238 | <entry>Discrete frame interval.</entry> | ||
| 239 | </row> | ||
| 240 | <row> | ||
| 241 | <entry><constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant></entry> | ||
| 242 | <entry>2</entry> | ||
| 243 | <entry>Continuous frame interval.</entry> | ||
| 244 | </row> | ||
| 245 | <row> | ||
| 246 | <entry><constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant></entry> | ||
| 247 | <entry>3</entry> | ||
| 248 | <entry>Step-wise defined frame interval.</entry> | ||
| 249 | </row> | ||
| 250 | </tbody> | ||
| 251 | </tgroup> | ||
| 252 | </table> | ||
| 253 | </refsect1> | ||
| 254 | |||
| 255 | <refsect1> | ||
| 256 | &return-value; | ||
| 257 | |||
| 258 | <para>See the description section above for a list of return | ||
| 259 | values that <varname>errno</varname> can have.</para> | ||
| 260 | </refsect1> | ||
| 261 | |||
| 262 | </refentry> | ||
| 263 | |||
| 264 | <!-- | ||
| 265 | Local Variables: | ||
| 266 | mode: sgml | ||
| 267 | sgml-parent-document: "v4l2.sgml" | ||
| 268 | indent-tabs-mode: nil | ||
| 269 | End: | ||
| 270 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enum-framesizes.xml b/Documentation/DocBook/v4l/vidioc-enum-framesizes.xml new file mode 100644 index 000000000000..6afa4542c818 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enum-framesizes.xml | |||
| @@ -0,0 +1,282 @@ | |||
| 1 | <refentry id="vidioc-enum-framesizes"> | ||
| 2 | |||
| 3 | <refmeta> | ||
| 4 | <refentrytitle>ioctl VIDIOC_ENUM_FRAMESIZES</refentrytitle> | ||
| 5 | &manvol; | ||
| 6 | </refmeta> | ||
| 7 | |||
| 8 | <refnamediv> | ||
| 9 | <refname>VIDIOC_ENUM_FRAMESIZES</refname> | ||
| 10 | <refpurpose>Enumerate frame sizes</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_frmsizeenum *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_ENUM_FRAMESIZES</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para>Pointer to a &v4l2-frmsizeenum; that contains an index | ||
| 44 | and pixel format and receives a frame width and height.</para> | ||
| 45 | </listitem> | ||
| 46 | </varlistentry> | ||
| 47 | </variablelist> | ||
| 48 | </refsect1> | ||
| 49 | |||
| 50 | <refsect1> | ||
| 51 | <title>Description</title> | ||
| 52 | |||
| 53 | <note> | ||
| 54 | <title>Experimental</title> | ||
| 55 | |||
| 56 | <para>This is an <link linkend="experimental">experimental</link> | ||
| 57 | interface and may change in the future.</para> | ||
| 58 | </note> | ||
| 59 | |||
| 60 | <para>This ioctl allows applications to enumerate all frame sizes | ||
| 61 | (&ie; width and height in pixels) that the device supports for the | ||
| 62 | given pixel format.</para> | ||
| 63 | <para>The supported pixel formats can be obtained by using the | ||
| 64 | &VIDIOC-ENUM-FMT; function.</para> | ||
| 65 | <para>The return value and the content of the | ||
| 66 | <structfield>v4l2_frmsizeenum.type</structfield> field depend on the | ||
| 67 | type of frame sizes the device supports. Here are the semantics of the | ||
| 68 | function for the different cases:</para> | ||
| 69 | |||
| 70 | <itemizedlist> | ||
| 71 | <listitem> | ||
| 72 | <para><emphasis role="bold">Discrete:</emphasis> The function | ||
| 73 | returns success if the given index value (zero-based) is valid. The | ||
| 74 | application should increase the index by one for each call until | ||
| 75 | <constant>EINVAL</constant> is returned. The | ||
| 76 | <structfield>v4l2_frmsizeenum.type</structfield> field is set to | ||
| 77 | <constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> by the driver. Of the | ||
| 78 | union only the <structfield>discrete</structfield> member is | ||
| 79 | valid.</para> | ||
| 80 | </listitem> | ||
| 81 | <listitem> | ||
| 82 | <para><emphasis role="bold">Step-wise:</emphasis> The function | ||
| 83 | returns success if the given index value is zero and | ||
| 84 | <constant>EINVAL</constant> for any other index value. The | ||
| 85 | <structfield>v4l2_frmsizeenum.type</structfield> field is set to | ||
| 86 | <constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant> by the driver. Of the | ||
| 87 | union only the <structfield>stepwise</structfield> member is | ||
| 88 | valid.</para> | ||
| 89 | </listitem> | ||
| 90 | <listitem> | ||
| 91 | <para><emphasis role="bold">Continuous:</emphasis> This is a | ||
| 92 | special case of the step-wise type above. The function returns success | ||
| 93 | if the given index value is zero and <constant>EINVAL</constant> for | ||
| 94 | any other index value. The | ||
| 95 | <structfield>v4l2_frmsizeenum.type</structfield> field is set to | ||
| 96 | <constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant> by the driver. Of | ||
| 97 | the union only the <structfield>stepwise</structfield> member is valid | ||
| 98 | and the <structfield>step_width</structfield> and | ||
| 99 | <structfield>step_height</structfield> values are set to 1.</para> | ||
| 100 | </listitem> | ||
| 101 | </itemizedlist> | ||
| 102 | |||
| 103 | <para>When the application calls the function with index zero, it | ||
| 104 | must check the <structfield>type</structfield> field to determine the | ||
| 105 | type of frame size enumeration the device supports. Only for the | ||
| 106 | <constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> type does it make | ||
| 107 | sense to increase the index value to receive more frame sizes.</para> | ||
| 108 | <para>Note that the order in which the frame sizes are returned | ||
| 109 | has no special meaning. In particular does it not say anything about | ||
| 110 | potential default format sizes.</para> | ||
| 111 | <para>Applications can assume that the enumeration data does not | ||
| 112 | change without any interaction from the application itself. This means | ||
| 113 | that the enumeration data is consistent if the application does not | ||
| 114 | perform any other ioctl calls while it runs the frame size | ||
| 115 | enumeration.</para> | ||
| 116 | </refsect1> | ||
| 117 | |||
| 118 | <refsect1> | ||
| 119 | <title>Structs</title> | ||
| 120 | |||
| 121 | <para>In the structs below, <emphasis>IN</emphasis> denotes a | ||
| 122 | value that has to be filled in by the application, | ||
| 123 | <emphasis>OUT</emphasis> denotes values that the driver fills in. The | ||
| 124 | application should zero out all members except for the | ||
| 125 | <emphasis>IN</emphasis> fields.</para> | ||
| 126 | |||
| 127 | <table pgwide="1" frame="none" id="v4l2-frmsize-discrete"> | ||
| 128 | <title>struct <structname>v4l2_frmsize_discrete</structname></title> | ||
| 129 | <tgroup cols="3"> | ||
| 130 | &cs-str; | ||
| 131 | <tbody valign="top"> | ||
| 132 | <row> | ||
| 133 | <entry>__u32</entry> | ||
| 134 | <entry><structfield>width</structfield></entry> | ||
| 135 | <entry>Width of the frame [pixel].</entry> | ||
| 136 | </row> | ||
| 137 | <row> | ||
| 138 | <entry>__u32</entry> | ||
| 139 | <entry><structfield>height</structfield></entry> | ||
| 140 | <entry>Height of the frame [pixel].</entry> | ||
| 141 | </row> | ||
| 142 | </tbody> | ||
| 143 | </tgroup> | ||
| 144 | </table> | ||
| 145 | |||
| 146 | <table pgwide="1" frame="none" id="v4l2-frmsize-stepwise"> | ||
| 147 | <title>struct <structname>v4l2_frmsize_stepwise</structname></title> | ||
| 148 | <tgroup cols="3"> | ||
| 149 | &cs-str; | ||
| 150 | <tbody valign="top"> | ||
| 151 | <row> | ||
| 152 | <entry>__u32</entry> | ||
| 153 | <entry><structfield>min_width</structfield></entry> | ||
| 154 | <entry>Minimum frame width [pixel].</entry> | ||
| 155 | </row> | ||
| 156 | <row> | ||
| 157 | <entry>__u32</entry> | ||
| 158 | <entry><structfield>max_width</structfield></entry> | ||
| 159 | <entry>Maximum frame width [pixel].</entry> | ||
| 160 | </row> | ||
| 161 | <row> | ||
| 162 | <entry>__u32</entry> | ||
| 163 | <entry><structfield>step_width</structfield></entry> | ||
| 164 | <entry>Frame width step size [pixel].</entry> | ||
| 165 | </row> | ||
| 166 | <row> | ||
| 167 | <entry>__u32</entry> | ||
| 168 | <entry><structfield>min_height</structfield></entry> | ||
| 169 | <entry>Minimum frame height [pixel].</entry> | ||
| 170 | </row> | ||
| 171 | <row> | ||
| 172 | <entry>__u32</entry> | ||
| 173 | <entry><structfield>max_height</structfield></entry> | ||
| 174 | <entry>Maximum frame height [pixel].</entry> | ||
| 175 | </row> | ||
| 176 | <row> | ||
| 177 | <entry>__u32</entry> | ||
| 178 | <entry><structfield>step_height</structfield></entry> | ||
| 179 | <entry>Frame height step size [pixel].</entry> | ||
| 180 | </row> | ||
| 181 | </tbody> | ||
| 182 | </tgroup> | ||
| 183 | </table> | ||
| 184 | |||
| 185 | <table pgwide="1" frame="none" id="v4l2-frmsizeenum"> | ||
| 186 | <title>struct <structname>v4l2_frmsizeenum</structname></title> | ||
| 187 | <tgroup cols="4"> | ||
| 188 | <colspec colname="c1" /> | ||
| 189 | <colspec colname="c2" /> | ||
| 190 | <colspec colname="c3" /> | ||
| 191 | <colspec colname="c4" /> | ||
| 192 | <tbody valign="top"> | ||
| 193 | <row> | ||
| 194 | <entry>__u32</entry> | ||
| 195 | <entry><structfield>index</structfield></entry> | ||
| 196 | <entry></entry> | ||
| 197 | <entry>IN: Index of the given frame size in the enumeration.</entry> | ||
| 198 | </row> | ||
| 199 | <row> | ||
| 200 | <entry>__u32</entry> | ||
| 201 | <entry><structfield>pixel_format</structfield></entry> | ||
| 202 | <entry></entry> | ||
| 203 | <entry>IN: Pixel format for which the frame sizes are enumerated.</entry> | ||
| 204 | </row> | ||
| 205 | <row> | ||
| 206 | <entry>__u32</entry> | ||
| 207 | <entry><structfield>type</structfield></entry> | ||
| 208 | <entry></entry> | ||
| 209 | <entry>OUT: Frame size type the device supports.</entry> | ||
| 210 | </row> | ||
| 211 | <row> | ||
| 212 | <entry>union</entry> | ||
| 213 | <entry></entry> | ||
| 214 | <entry></entry> | ||
| 215 | <entry>OUT: Frame size with the given index.</entry> | ||
| 216 | </row> | ||
| 217 | <row> | ||
| 218 | <entry></entry> | ||
| 219 | <entry>&v4l2-frmsize-discrete;</entry> | ||
| 220 | <entry><structfield>discrete</structfield></entry> | ||
| 221 | <entry></entry> | ||
| 222 | </row> | ||
| 223 | <row> | ||
| 224 | <entry></entry> | ||
| 225 | <entry>&v4l2-frmsize-stepwise;</entry> | ||
| 226 | <entry><structfield>stepwise</structfield></entry> | ||
| 227 | <entry></entry> | ||
| 228 | </row> | ||
| 229 | <row> | ||
| 230 | <entry>__u32</entry> | ||
| 231 | <entry><structfield>reserved[2]</structfield></entry> | ||
| 232 | <entry></entry> | ||
| 233 | <entry>Reserved space for future use.</entry> | ||
| 234 | </row> | ||
| 235 | </tbody> | ||
| 236 | </tgroup> | ||
| 237 | </table> | ||
| 238 | </refsect1> | ||
| 239 | |||
| 240 | <refsect1> | ||
| 241 | <title>Enums</title> | ||
| 242 | |||
| 243 | <table pgwide="1" frame="none" id="v4l2-frmsizetypes"> | ||
| 244 | <title>enum <structname>v4l2_frmsizetypes</structname></title> | ||
| 245 | <tgroup cols="3"> | ||
| 246 | &cs-def; | ||
| 247 | <tbody valign="top"> | ||
| 248 | <row> | ||
| 249 | <entry><constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant></entry> | ||
| 250 | <entry>1</entry> | ||
| 251 | <entry>Discrete frame size.</entry> | ||
| 252 | </row> | ||
| 253 | <row> | ||
| 254 | <entry><constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant></entry> | ||
| 255 | <entry>2</entry> | ||
| 256 | <entry>Continuous frame size.</entry> | ||
| 257 | </row> | ||
| 258 | <row> | ||
| 259 | <entry><constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant></entry> | ||
| 260 | <entry>3</entry> | ||
| 261 | <entry>Step-wise defined frame size.</entry> | ||
| 262 | </row> | ||
| 263 | </tbody> | ||
| 264 | </tgroup> | ||
| 265 | </table> | ||
| 266 | </refsect1> | ||
| 267 | |||
| 268 | <refsect1> | ||
| 269 | &return-value; | ||
| 270 | |||
| 271 | <para>See the description section above for a list of return | ||
| 272 | values that <varname>errno</varname> can have.</para> | ||
| 273 | </refsect1> | ||
| 274 | </refentry> | ||
| 275 | |||
| 276 | <!-- | ||
| 277 | Local Variables: | ||
| 278 | mode: sgml | ||
| 279 | sgml-parent-document: "v4l2.sgml" | ||
| 280 | indent-tabs-mode: nil | ||
| 281 | End: | ||
| 282 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enumaudio.xml b/Documentation/DocBook/v4l/vidioc-enumaudio.xml new file mode 100644 index 000000000000..9ae8f2d3a96f --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enumaudio.xml | |||
| @@ -0,0 +1,86 @@ | |||
| 1 | <refentry id="vidioc-enumaudio"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUMAUDIO</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUMAUDIO</refname> | ||
| 9 | <refpurpose>Enumerate audio inputs</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_ENUMAUDIO</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>To query the attributes of an audio input applications | ||
| 52 | initialize the <structfield>index</structfield> field and zero out the | ||
| 53 | <structfield>reserved</structfield> array of a &v4l2-audio; | ||
| 54 | and call the <constant>VIDIOC_ENUMAUDIO</constant> ioctl with a pointer | ||
| 55 | to this structure. Drivers fill the rest of the structure or return an | ||
| 56 | &EINVAL; when the index is out of bounds. To enumerate all audio | ||
| 57 | inputs applications shall begin at index zero, incrementing by one | ||
| 58 | until the driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 59 | |||
| 60 | <para>See <xref linkend="vidioc-g-audio" /> for a description of | ||
| 61 | &v4l2-audio;.</para> | ||
| 62 | </refsect1> | ||
| 63 | |||
| 64 | <refsect1> | ||
| 65 | &return-value; | ||
| 66 | |||
| 67 | <variablelist> | ||
| 68 | <varlistentry> | ||
| 69 | <term><errorcode>EINVAL</errorcode></term> | ||
| 70 | <listitem> | ||
| 71 | <para>The number of the audio input is out of bounds, or | ||
| 72 | there are no audio inputs at all and this ioctl is not | ||
| 73 | supported.</para> | ||
| 74 | </listitem> | ||
| 75 | </varlistentry> | ||
| 76 | </variablelist> | ||
| 77 | </refsect1> | ||
| 78 | </refentry> | ||
| 79 | |||
| 80 | <!-- | ||
| 81 | Local Variables: | ||
| 82 | mode: sgml | ||
| 83 | sgml-parent-document: "v4l2.sgml" | ||
| 84 | indent-tabs-mode: nil | ||
| 85 | End: | ||
| 86 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enumaudioout.xml b/Documentation/DocBook/v4l/vidioc-enumaudioout.xml new file mode 100644 index 000000000000..d3d7c0ab17b8 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enumaudioout.xml | |||
| @@ -0,0 +1,89 @@ | |||
| 1 | <refentry id="vidioc-enumaudioout"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUMAUDOUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUMAUDOUT</refname> | ||
| 9 | <refpurpose>Enumerate audio outputs</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_ENUMAUDOUT</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>To query the attributes of an audio output applications | ||
| 52 | initialize the <structfield>index</structfield> field and zero out the | ||
| 53 | <structfield>reserved</structfield> array of a &v4l2-audioout; and | ||
| 54 | call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer | ||
| 55 | to this structure. Drivers fill the rest of the structure or return an | ||
| 56 | &EINVAL; when the index is out of bounds. To enumerate all audio | ||
| 57 | outputs applications shall begin at index zero, incrementing by one | ||
| 58 | until the driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 59 | |||
| 60 | <para>Note connectors on a TV card to loop back the received audio | ||
| 61 | signal to a sound card are not audio outputs in this sense.</para> | ||
| 62 | |||
| 63 | <para>See <xref linkend="vidioc-g-audioout" /> for a description of | ||
| 64 | &v4l2-audioout;.</para> | ||
| 65 | </refsect1> | ||
| 66 | |||
| 67 | <refsect1> | ||
| 68 | &return-value; | ||
| 69 | |||
| 70 | <variablelist> | ||
| 71 | <varlistentry> | ||
| 72 | <term><errorcode>EINVAL</errorcode></term> | ||
| 73 | <listitem> | ||
| 74 | <para>The number of the audio output is out of bounds, or | ||
| 75 | there are no audio outputs at all and this ioctl is not | ||
| 76 | supported.</para> | ||
| 77 | </listitem> | ||
| 78 | </varlistentry> | ||
| 79 | </variablelist> | ||
| 80 | </refsect1> | ||
| 81 | </refentry> | ||
| 82 | |||
| 83 | <!-- | ||
| 84 | Local Variables: | ||
| 85 | mode: sgml | ||
| 86 | sgml-parent-document: "v4l2.sgml" | ||
| 87 | indent-tabs-mode: nil | ||
| 88 | End: | ||
| 89 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enuminput.xml b/Documentation/DocBook/v4l/vidioc-enuminput.xml new file mode 100644 index 000000000000..414856b82473 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enuminput.xml | |||
| @@ -0,0 +1,287 @@ | |||
| 1 | <refentry id="vidioc-enuminput"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUMINPUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUMINPUT</refname> | ||
| 9 | <refpurpose>Enumerate video inputs</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_input | ||
| 19 | *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_ENUMINPUT</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>To query the attributes of a video input applications | ||
| 53 | initialize the <structfield>index</structfield> field of &v4l2-input; | ||
| 54 | and call the <constant>VIDIOC_ENUMINPUT</constant> ioctl with a | ||
| 55 | pointer to this structure. Drivers fill the rest of the structure or | ||
| 56 | return an &EINVAL; when the index is out of bounds. To enumerate all | ||
| 57 | inputs applications shall begin at index zero, incrementing by one | ||
| 58 | until the driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 59 | |||
| 60 | <table frame="none" pgwide="1" id="v4l2-input"> | ||
| 61 | <title>struct <structname>v4l2_input</structname></title> | ||
| 62 | <tgroup cols="3"> | ||
| 63 | &cs-str; | ||
| 64 | <tbody valign="top"> | ||
| 65 | <row> | ||
| 66 | <entry>__u32</entry> | ||
| 67 | <entry><structfield>index</structfield></entry> | ||
| 68 | <entry>Identifies the input, set by the | ||
| 69 | application.</entry> | ||
| 70 | </row> | ||
| 71 | <row> | ||
| 72 | <entry>__u8</entry> | ||
| 73 | <entry><structfield>name</structfield>[32]</entry> | ||
| 74 | <entry>Name of the video input, a NUL-terminated ASCII | ||
| 75 | string, for example: "Vin (Composite 2)". This information is intended | ||
| 76 | for the user, preferably the connector label on the device itself.</entry> | ||
| 77 | </row> | ||
| 78 | <row> | ||
| 79 | <entry>__u32</entry> | ||
| 80 | <entry><structfield>type</structfield></entry> | ||
| 81 | <entry>Type of the input, see <xref | ||
| 82 | linkend="input-type" />.</entry> | ||
| 83 | </row> | ||
| 84 | <row> | ||
| 85 | <entry>__u32</entry> | ||
| 86 | <entry><structfield>audioset</structfield></entry> | ||
| 87 | <entry><para>Drivers can enumerate up to 32 video and | ||
| 88 | audio inputs. This field shows which audio inputs were selectable as | ||
| 89 | audio source if this was the currently selected video input. It is a | ||
| 90 | bit mask. The LSB corresponds to audio input 0, the MSB to input 31. | ||
| 91 | Any number of bits can be set, or none.</para><para>When the driver | ||
| 92 | does not enumerate audio inputs no bits must be set. Applications | ||
| 93 | shall not interpret this as lack of audio support. Some drivers | ||
| 94 | automatically select audio sources and do not enumerate them since | ||
| 95 | there is no choice anyway.</para><para>For details on audio inputs and | ||
| 96 | how to select the current input see <xref | ||
| 97 | linkend="audio" />.</para></entry> | ||
| 98 | </row> | ||
| 99 | <row> | ||
| 100 | <entry>__u32</entry> | ||
| 101 | <entry><structfield>tuner</structfield></entry> | ||
| 102 | <entry>Capture devices can have zero or more tuners (RF | ||
| 103 | demodulators). When the <structfield>type</structfield> is set to | ||
| 104 | <constant>V4L2_INPUT_TYPE_TUNER</constant> this is an RF connector and | ||
| 105 | this field identifies the tuner. It corresponds to | ||
| 106 | &v4l2-tuner; field <structfield>index</structfield>. For details on | ||
| 107 | tuners see <xref linkend="tuner" />.</entry> | ||
| 108 | </row> | ||
| 109 | <row> | ||
| 110 | <entry>&v4l2-std-id;</entry> | ||
| 111 | <entry><structfield>std</structfield></entry> | ||
| 112 | <entry>Every video input supports one or more different | ||
| 113 | video standards. This field is a set of all supported standards. For | ||
| 114 | details on video standards and how to switch see <xref | ||
| 115 | linkend="standard" />.</entry> | ||
| 116 | </row> | ||
| 117 | <row> | ||
| 118 | <entry>__u32</entry> | ||
| 119 | <entry><structfield>status</structfield></entry> | ||
| 120 | <entry>This field provides status information about the | ||
| 121 | input. See <xref linkend="input-status" /> for flags. | ||
| 122 | With the exception of the sensor orientation bits <structfield>status</structfield> is only valid when this is the | ||
| 123 | current input.</entry> | ||
| 124 | </row> | ||
| 125 | <row> | ||
| 126 | <entry>__u32</entry> | ||
| 127 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 128 | <entry>Reserved for future extensions. Drivers must set | ||
| 129 | the array to zero.</entry> | ||
| 130 | </row> | ||
| 131 | </tbody> | ||
| 132 | </tgroup> | ||
| 133 | </table> | ||
| 134 | |||
| 135 | <table frame="none" pgwide="1" id="input-type"> | ||
| 136 | <title>Input Types</title> | ||
| 137 | <tgroup cols="3"> | ||
| 138 | &cs-def; | ||
| 139 | <tbody valign="top"> | ||
| 140 | <row> | ||
| 141 | <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry> | ||
| 142 | <entry>1</entry> | ||
| 143 | <entry>This input uses a tuner (RF demodulator).</entry> | ||
| 144 | </row> | ||
| 145 | <row> | ||
| 146 | <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry> | ||
| 147 | <entry>2</entry> | ||
| 148 | <entry>Analog baseband input, for example CVBS / | ||
| 149 | Composite Video, S-Video, RGB.</entry> | ||
| 150 | </row> | ||
| 151 | </tbody> | ||
| 152 | </tgroup> | ||
| 153 | </table> | ||
| 154 | |||
| 155 | <!-- Status flags based on proposal by Mark McClelland, | ||
| 156 | video4linux-list@redhat.com on 18 Oct 2002, subject "Re: [V4L] Re: | ||
| 157 | v4l2 api". "Why are some of them inverted? So that the driver doesn't | ||
| 158 | have to lie about the status in cases where it can't tell one way or | ||
| 159 | the other. Plus, a status of zero would generally mean that everything | ||
| 160 | is OK." --> | ||
| 161 | |||
| 162 | <table frame="none" pgwide="1" id="input-status"> | ||
| 163 | <title>Input Status Flags</title> | ||
| 164 | <tgroup cols="3"> | ||
| 165 | <colspec colname="c1" /> | ||
| 166 | <colspec colname="c2" align="center" /> | ||
| 167 | <colspec colname="c3" /> | ||
| 168 | <spanspec namest="c1" nameend="c3" spanname="hspan" | ||
| 169 | align="left" /> | ||
| 170 | <tbody valign="top"> | ||
| 171 | <row> | ||
| 172 | <entry spanname="hspan">General</entry> | ||
| 173 | </row> | ||
| 174 | <row> | ||
| 175 | <entry><constant>V4L2_IN_ST_NO_POWER</constant></entry> | ||
| 176 | <entry>0x00000001</entry> | ||
| 177 | <entry>Attached device is off.</entry> | ||
| 178 | </row> | ||
| 179 | <row> | ||
| 180 | <entry><constant>V4L2_IN_ST_NO_SIGNAL</constant></entry> | ||
| 181 | <entry>0x00000002</entry> | ||
| 182 | <entry></entry> | ||
| 183 | </row> | ||
| 184 | <row> | ||
| 185 | <entry><constant>V4L2_IN_ST_NO_COLOR</constant></entry> | ||
| 186 | <entry>0x00000004</entry> | ||
| 187 | <entry>The hardware supports color decoding, but does not | ||
| 188 | detect color modulation in the signal.</entry> | ||
| 189 | </row> | ||
| 190 | <row> | ||
| 191 | <entry spanname="hspan">Sensor Orientation</entry> | ||
| 192 | </row> | ||
| 193 | <row> | ||
| 194 | <entry><constant>V4L2_IN_ST_HFLIP</constant></entry> | ||
| 195 | <entry>0x00000010</entry> | ||
| 196 | <entry>The input is connected to a device that produces a signal | ||
| 197 | that is flipped horizontally and does not correct this before passing the | ||
| 198 | signal to userspace.</entry> | ||
| 199 | </row> | ||
| 200 | <row> | ||
| 201 | <entry><constant>V4L2_IN_ST_VFLIP</constant></entry> | ||
| 202 | <entry>0x00000020</entry> | ||
| 203 | <entry>The input is connected to a device that produces a signal | ||
| 204 | that is flipped vertically and does not correct this before passing the | ||
| 205 | signal to userspace. Note that a 180 degree rotation is the same as HFLIP | VFLIP</entry> | ||
| 206 | </row> | ||
| 207 | <row> | ||
| 208 | <entry spanname="hspan">Analog Video</entry> | ||
| 209 | </row> | ||
| 210 | <row> | ||
| 211 | <entry><constant>V4L2_IN_ST_NO_H_LOCK</constant></entry> | ||
| 212 | <entry>0x00000100</entry> | ||
| 213 | <entry>No horizontal sync lock.</entry> | ||
| 214 | </row> | ||
| 215 | <row> | ||
| 216 | <entry><constant>V4L2_IN_ST_COLOR_KILL</constant></entry> | ||
| 217 | <entry>0x00000200</entry> | ||
| 218 | <entry>A color killer circuit automatically disables color | ||
| 219 | decoding when it detects no color modulation. When this flag is set | ||
| 220 | the color killer is enabled <emphasis>and</emphasis> has shut off | ||
| 221 | color decoding.</entry> | ||
| 222 | </row> | ||
| 223 | <row> | ||
| 224 | <entry spanname="hspan">Digital Video</entry> | ||
| 225 | </row> | ||
| 226 | <row> | ||
| 227 | <entry><constant>V4L2_IN_ST_NO_SYNC</constant></entry> | ||
| 228 | <entry>0x00010000</entry> | ||
| 229 | <entry>No synchronization lock.</entry> | ||
| 230 | </row> | ||
| 231 | <row> | ||
| 232 | <entry><constant>V4L2_IN_ST_NO_EQU</constant></entry> | ||
| 233 | <entry>0x00020000</entry> | ||
| 234 | <entry>No equalizer lock.</entry> | ||
| 235 | </row> | ||
| 236 | <row> | ||
| 237 | <entry><constant>V4L2_IN_ST_NO_CARRIER</constant></entry> | ||
| 238 | <entry>0x00040000</entry> | ||
| 239 | <entry>Carrier recovery failed.</entry> | ||
| 240 | </row> | ||
| 241 | <row> | ||
| 242 | <entry spanname="hspan">VCR and Set-Top Box</entry> | ||
| 243 | </row> | ||
| 244 | <row> | ||
| 245 | <entry><constant>V4L2_IN_ST_MACROVISION</constant></entry> | ||
| 246 | <entry>0x01000000</entry> | ||
| 247 | <entry>Macrovision is an analog copy prevention system | ||
| 248 | mangling the video signal to confuse video recorders. When this | ||
| 249 | flag is set Macrovision has been detected.</entry> | ||
| 250 | </row> | ||
| 251 | <row> | ||
| 252 | <entry><constant>V4L2_IN_ST_NO_ACCESS</constant></entry> | ||
| 253 | <entry>0x02000000</entry> | ||
| 254 | <entry>Conditional access denied.</entry> | ||
| 255 | </row> | ||
| 256 | <row> | ||
| 257 | <entry><constant>V4L2_IN_ST_VTR</constant></entry> | ||
| 258 | <entry>0x04000000</entry> | ||
| 259 | <entry>VTR time constant. [?]</entry> | ||
| 260 | </row> | ||
| 261 | </tbody> | ||
| 262 | </tgroup> | ||
| 263 | </table> | ||
| 264 | </refsect1> | ||
| 265 | |||
| 266 | <refsect1> | ||
| 267 | &return-value; | ||
| 268 | |||
| 269 | <variablelist> | ||
| 270 | <varlistentry> | ||
| 271 | <term><errorcode>EINVAL</errorcode></term> | ||
| 272 | <listitem> | ||
| 273 | <para>The &v4l2-input; <structfield>index</structfield> is | ||
| 274 | out of bounds.</para> | ||
| 275 | </listitem> | ||
| 276 | </varlistentry> | ||
| 277 | </variablelist> | ||
| 278 | </refsect1> | ||
| 279 | </refentry> | ||
| 280 | |||
| 281 | <!-- | ||
| 282 | Local Variables: | ||
| 283 | mode: sgml | ||
| 284 | sgml-parent-document: "v4l2.sgml" | ||
| 285 | indent-tabs-mode: nil | ||
| 286 | End: | ||
| 287 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/v4l/vidioc-enumoutput.xml new file mode 100644 index 000000000000..e8d16dcd50cf --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enumoutput.xml | |||
| @@ -0,0 +1,172 @@ | |||
| 1 | <refentry id="vidioc-enumoutput"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUMOUTPUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUMOUTPUT</refname> | ||
| 9 | <refpurpose>Enumerate video outputs</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_output *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_ENUMOUTPUT</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>To query the attributes of a video outputs applications | ||
| 52 | initialize the <structfield>index</structfield> field of &v4l2-output; | ||
| 53 | and call the <constant>VIDIOC_ENUMOUTPUT</constant> ioctl with a | ||
| 54 | pointer to this structure. Drivers fill the rest of the structure or | ||
| 55 | return an &EINVAL; when the index is out of bounds. To enumerate all | ||
| 56 | outputs applications shall begin at index zero, incrementing by one | ||
| 57 | until the driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 58 | |||
| 59 | <table frame="none" pgwide="1" id="v4l2-output"> | ||
| 60 | <title>struct <structname>v4l2_output</structname></title> | ||
| 61 | <tgroup cols="3"> | ||
| 62 | &cs-str; | ||
| 63 | <tbody valign="top"> | ||
| 64 | <row> | ||
| 65 | <entry>__u32</entry> | ||
| 66 | <entry><structfield>index</structfield></entry> | ||
| 67 | <entry>Identifies the output, set by the | ||
| 68 | application.</entry> | ||
| 69 | </row> | ||
| 70 | <row> | ||
| 71 | <entry>__u8</entry> | ||
| 72 | <entry><structfield>name</structfield>[32]</entry> | ||
| 73 | <entry>Name of the video output, a NUL-terminated ASCII | ||
| 74 | string, for example: "Vout". This information is intended for the | ||
| 75 | user, preferably the connector label on the device itself.</entry> | ||
| 76 | </row> | ||
| 77 | <row> | ||
| 78 | <entry>__u32</entry> | ||
| 79 | <entry><structfield>type</structfield></entry> | ||
| 80 | <entry>Type of the output, see <xref | ||
| 81 | linkend="output-type" />.</entry> | ||
| 82 | </row> | ||
| 83 | <row> | ||
| 84 | <entry>__u32</entry> | ||
| 85 | <entry><structfield>audioset</structfield></entry> | ||
| 86 | <entry><para>Drivers can enumerate up to 32 video and | ||
| 87 | audio outputs. This field shows which audio outputs were | ||
| 88 | selectable as the current output if this was the currently selected | ||
| 89 | video output. It is a bit mask. The LSB corresponds to audio output 0, | ||
| 90 | the MSB to output 31. Any number of bits can be set, or | ||
| 91 | none.</para><para>When the driver does not enumerate audio outputs no | ||
| 92 | bits must be set. Applications shall not interpret this as lack of | ||
| 93 | audio support. Drivers may automatically select audio outputs without | ||
| 94 | enumerating them.</para><para>For details on audio outputs and how to | ||
| 95 | select the current output see <xref linkend="audio" />.</para></entry> | ||
| 96 | </row> | ||
| 97 | <row> | ||
| 98 | <entry>__u32</entry> | ||
| 99 | <entry><structfield>modulator</structfield></entry> | ||
| 100 | <entry>Output devices can have zero or more RF modulators. | ||
| 101 | When the <structfield>type</structfield> is | ||
| 102 | <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> this is an RF | ||
| 103 | connector and this field identifies the modulator. It corresponds to | ||
| 104 | &v4l2-modulator; field <structfield>index</structfield>. For details | ||
| 105 | on modulators see <xref linkend="tuner" />.</entry> | ||
| 106 | </row> | ||
| 107 | <row> | ||
| 108 | <entry>&v4l2-std-id;</entry> | ||
| 109 | <entry><structfield>std</structfield></entry> | ||
| 110 | <entry>Every video output supports one or more different | ||
| 111 | video standards. This field is a set of all supported standards. For | ||
| 112 | details on video standards and how to switch see <xref | ||
| 113 | linkend="standard" />.</entry> | ||
| 114 | </row> | ||
| 115 | <row> | ||
| 116 | <entry>__u32</entry> | ||
| 117 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 118 | <entry>Reserved for future extensions. Drivers must set | ||
| 119 | the array to zero.</entry> | ||
| 120 | </row> | ||
| 121 | </tbody> | ||
| 122 | </tgroup> | ||
| 123 | </table> | ||
| 124 | |||
| 125 | <table frame="none" pgwide="1" id="output-type"> | ||
| 126 | <title>Output Type</title> | ||
| 127 | <tgroup cols="3"> | ||
| 128 | &cs-def; | ||
| 129 | <tbody valign="top"> | ||
| 130 | <row> | ||
| 131 | <entry><constant>V4L2_OUTPUT_TYPE_MODULATOR</constant></entry> | ||
| 132 | <entry>1</entry> | ||
| 133 | <entry>This output is an analog TV modulator.</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry><constant>V4L2_OUTPUT_TYPE_ANALOG</constant></entry> | ||
| 137 | <entry>2</entry> | ||
| 138 | <entry>Analog baseband output, for example Composite / | ||
| 139 | CVBS, S-Video, RGB.</entry> | ||
| 140 | </row> | ||
| 141 | <row> | ||
| 142 | <entry><constant>V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY</constant></entry> | ||
| 143 | <entry>3</entry> | ||
| 144 | <entry>[?]</entry> | ||
| 145 | </row> | ||
| 146 | </tbody> | ||
| 147 | </tgroup> | ||
| 148 | </table> | ||
| 149 | |||
| 150 | </refsect1> | ||
| 151 | <refsect1> | ||
| 152 | &return-value; | ||
| 153 | |||
| 154 | <variablelist> | ||
| 155 | <varlistentry> | ||
| 156 | <term><errorcode>EINVAL</errorcode></term> | ||
| 157 | <listitem> | ||
| 158 | <para>The &v4l2-output; <structfield>index</structfield> | ||
| 159 | is out of bounds.</para> | ||
| 160 | </listitem> | ||
| 161 | </varlistentry> | ||
| 162 | </variablelist> | ||
| 163 | </refsect1> | ||
| 164 | </refentry> | ||
| 165 | |||
| 166 | <!-- | ||
| 167 | Local Variables: | ||
| 168 | mode: sgml | ||
| 169 | sgml-parent-document: "v4l2.sgml" | ||
| 170 | indent-tabs-mode: nil | ||
| 171 | End: | ||
| 172 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-enumstd.xml b/Documentation/DocBook/v4l/vidioc-enumstd.xml new file mode 100644 index 000000000000..95803fe2c8e4 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-enumstd.xml | |||
| @@ -0,0 +1,391 @@ | |||
| 1 | <refentry id="vidioc-enumstd"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_ENUMSTD</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_ENUMSTD</refname> | ||
| 9 | <refpurpose>Enumerate supported video standards</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_standard *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_ENUMSTD</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>To query the attributes of a video standard, | ||
| 52 | especially a custom (driver defined) one, applications initialize the | ||
| 53 | <structfield>index</structfield> field of &v4l2-standard; and call the | ||
| 54 | <constant>VIDIOC_ENUMSTD</constant> ioctl with a pointer to this | ||
| 55 | structure. Drivers fill the rest of the structure or return an | ||
| 56 | &EINVAL; when the index is out of bounds. To enumerate all standards | ||
| 57 | applications shall begin at index zero, incrementing by one until the | ||
| 58 | driver returns <errorcode>EINVAL</errorcode>. Drivers may enumerate a | ||
| 59 | different set of standards after switching the video input or | ||
| 60 | output.<footnote> | ||
| 61 | <para>The supported standards may overlap and we need an | ||
| 62 | unambiguous set to find the current standard returned by | ||
| 63 | <constant>VIDIOC_G_STD</constant>.</para> | ||
| 64 | </footnote></para> | ||
| 65 | |||
| 66 | <table pgwide="1" frame="none" id="v4l2-standard"> | ||
| 67 | <title>struct <structname>v4l2_standard</structname></title> | ||
| 68 | <tgroup cols="3"> | ||
| 69 | &cs-str; | ||
| 70 | <tbody valign="top"> | ||
| 71 | <row> | ||
| 72 | <entry>__u32</entry> | ||
| 73 | <entry><structfield>index</structfield></entry> | ||
| 74 | <entry>Number of the video standard, set by the | ||
| 75 | application.</entry> | ||
| 76 | </row> | ||
| 77 | <row> | ||
| 78 | <entry>&v4l2-std-id;</entry> | ||
| 79 | <entry><structfield>id</structfield></entry> | ||
| 80 | <entry>The bits in this field identify the standard as | ||
| 81 | one of the common standards listed in <xref linkend="v4l2-std-id" />, | ||
| 82 | or if bits 32 to 63 are set as custom standards. Multiple bits can be | ||
| 83 | set if the hardware does not distinguish between these standards, | ||
| 84 | however separate indices do not indicate the opposite. The | ||
| 85 | <structfield>id</structfield> must be unique. No other enumerated | ||
| 86 | <structname>v4l2_standard</structname> structure, for this input or | ||
| 87 | output anyway, can contain the same set of bits.</entry> | ||
| 88 | </row> | ||
| 89 | <row> | ||
| 90 | <entry>__u8</entry> | ||
| 91 | <entry><structfield>name</structfield>[24]</entry> | ||
| 92 | <entry>Name of the standard, a NUL-terminated ASCII | ||
| 93 | string, for example: "PAL-B/G", "NTSC Japan". This information is | ||
| 94 | intended for the user.</entry> | ||
| 95 | </row> | ||
| 96 | <row> | ||
| 97 | <entry>&v4l2-fract;</entry> | ||
| 98 | <entry><structfield>frameperiod</structfield></entry> | ||
| 99 | <entry>The frame period (not field period) is numerator | ||
| 100 | / denominator. For example M/NTSC has a frame period of 1001 / | ||
| 101 | 30000 seconds.</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry>__u32</entry> | ||
| 105 | <entry><structfield>framelines</structfield></entry> | ||
| 106 | <entry>Total lines per frame including blanking, | ||
| 107 | e. g. 625 for B/PAL.</entry> | ||
| 108 | </row> | ||
| 109 | <row> | ||
| 110 | <entry>__u32</entry> | ||
| 111 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 112 | <entry>Reserved for future extensions. Drivers must set | ||
| 113 | the array to zero.</entry> | ||
| 114 | </row> | ||
| 115 | </tbody> | ||
| 116 | </tgroup> | ||
| 117 | </table> | ||
| 118 | |||
| 119 | <table pgwide="1" frame="none" id="v4l2-fract"> | ||
| 120 | <title>struct <structname>v4l2_fract</structname></title> | ||
| 121 | <tgroup cols="3"> | ||
| 122 | &cs-str; | ||
| 123 | <tbody valign="top"> | ||
| 124 | <row> | ||
| 125 | <entry>__u32</entry> | ||
| 126 | <entry><structfield>numerator</structfield></entry> | ||
| 127 | <entry></entry> | ||
| 128 | </row> | ||
| 129 | <row> | ||
| 130 | <entry>__u32</entry> | ||
| 131 | <entry><structfield>denominator</structfield></entry> | ||
| 132 | <entry></entry> | ||
| 133 | </row> | ||
| 134 | </tbody> | ||
| 135 | </tgroup> | ||
| 136 | </table> | ||
| 137 | |||
| 138 | <table pgwide="1" frame="none" id="v4l2-std-id"> | ||
| 139 | <title>typedef <structname>v4l2_std_id</structname></title> | ||
| 140 | <tgroup cols="3"> | ||
| 141 | &cs-str; | ||
| 142 | <tbody valign="top"> | ||
| 143 | <row> | ||
| 144 | <entry>__u64</entry> | ||
| 145 | <entry><structfield>v4l2_std_id</structfield></entry> | ||
| 146 | <entry>This type is a set, each bit representing another | ||
| 147 | video standard as listed below and in <xref | ||
| 148 | linkend="video-standards" />. The 32 most significant bits are reserved | ||
| 149 | for custom (driver defined) video standards.</entry> | ||
| 150 | </row> | ||
| 151 | </tbody> | ||
| 152 | </tgroup> | ||
| 153 | </table> | ||
| 154 | |||
| 155 | <para><programlisting> | ||
| 156 | #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) | ||
| 157 | #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002) | ||
| 158 | #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004) | ||
| 159 | #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008) | ||
| 160 | #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010) | ||
| 161 | #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020) | ||
| 162 | #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040) | ||
| 163 | #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080) | ||
| 164 | |||
| 165 | #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100) | ||
| 166 | #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200) | ||
| 167 | #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400) | ||
| 168 | #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800) | ||
| 169 | </programlisting></para><para><constant>V4L2_STD_PAL_60</constant> is | ||
| 170 | a hybrid standard with 525 lines, 60 Hz refresh rate, and PAL color | ||
| 171 | modulation with a 4.43 MHz color subcarrier. Some PAL video recorders | ||
| 172 | can play back NTSC tapes in this mode for display on a 50/60 Hz agnostic | ||
| 173 | PAL TV.</para><para><programlisting> | ||
| 174 | #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) | ||
| 175 | #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) | ||
| 176 | #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000) | ||
| 177 | </programlisting></para><para><constant>V4L2_STD_NTSC_443</constant> | ||
| 178 | is a hybrid standard with 525 lines, 60 Hz refresh rate, and NTSC | ||
| 179 | color modulation with a 4.43 MHz color | ||
| 180 | subcarrier.</para><para><programlisting> | ||
| 181 | #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) | ||
| 182 | |||
| 183 | #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000) | ||
| 184 | #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000) | ||
| 185 | #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000) | ||
| 186 | #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000) | ||
| 187 | #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000) | ||
| 188 | #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000) | ||
| 189 | #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000) | ||
| 190 | #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000) | ||
| 191 | |||
| 192 | /* ATSC/HDTV */ | ||
| 193 | #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000) | ||
| 194 | #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000) | ||
| 195 | </programlisting></para><para><!-- ATSC proposal by Mark McClelland, | ||
| 196 | video4linux-list@redhat.com on 17 Oct 2002 | ||
| 197 | --><constant>V4L2_STD_ATSC_8_VSB</constant> and | ||
| 198 | <constant>V4L2_STD_ATSC_16_VSB</constant> are U.S. terrestrial digital | ||
| 199 | TV standards. Presently the V4L2 API does not support digital TV. See | ||
| 200 | also the Linux DVB API at <ulink | ||
| 201 | url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> | ||
| 202 | <para><programlisting> | ||
| 203 | #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\ | ||
| 204 | V4L2_STD_PAL_B1 |\ | ||
| 205 | V4L2_STD_PAL_G) | ||
| 206 | #define V4L2_STD_B (V4L2_STD_PAL_B |\ | ||
| 207 | V4L2_STD_PAL_B1 |\ | ||
| 208 | V4L2_STD_SECAM_B) | ||
| 209 | #define V4L2_STD_GH (V4L2_STD_PAL_G |\ | ||
| 210 | V4L2_STD_PAL_H |\ | ||
| 211 | V4L2_STD_SECAM_G |\ | ||
| 212 | V4L2_STD_SECAM_H) | ||
| 213 | #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\ | ||
| 214 | V4L2_STD_PAL_D1 |\ | ||
| 215 | V4L2_STD_PAL_K) | ||
| 216 | #define V4L2_STD_PAL (V4L2_STD_PAL_BG |\ | ||
| 217 | V4L2_STD_PAL_DK |\ | ||
| 218 | V4L2_STD_PAL_H |\ | ||
| 219 | V4L2_STD_PAL_I) | ||
| 220 | #define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\ | ||
| 221 | V4L2_STD_NTSC_M_JP |\ | ||
| 222 | V4L2_STD_NTSC_M_KR) | ||
| 223 | #define V4L2_STD_MN (V4L2_STD_PAL_M |\ | ||
| 224 | V4L2_STD_PAL_N |\ | ||
| 225 | V4L2_STD_PAL_Nc |\ | ||
| 226 | V4L2_STD_NTSC) | ||
| 227 | #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |\ | ||
| 228 | V4L2_STD_SECAM_K |\ | ||
| 229 | V4L2_STD_SECAM_K1) | ||
| 230 | #define V4L2_STD_DK (V4L2_STD_PAL_DK |\ | ||
| 231 | V4L2_STD_SECAM_DK) | ||
| 232 | |||
| 233 | #define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\ | ||
| 234 | V4L2_STD_SECAM_G |\ | ||
| 235 | V4L2_STD_SECAM_H |\ | ||
| 236 | V4L2_STD_SECAM_DK |\ | ||
| 237 | V4L2_STD_SECAM_L |\ | ||
| 238 | V4L2_STD_SECAM_LC) | ||
| 239 | |||
| 240 | #define V4L2_STD_525_60 (V4L2_STD_PAL_M |\ | ||
| 241 | V4L2_STD_PAL_60 |\ | ||
| 242 | V4L2_STD_NTSC |\ | ||
| 243 | V4L2_STD_NTSC_443) | ||
| 244 | #define V4L2_STD_625_50 (V4L2_STD_PAL |\ | ||
| 245 | V4L2_STD_PAL_N |\ | ||
| 246 | V4L2_STD_PAL_Nc |\ | ||
| 247 | V4L2_STD_SECAM) | ||
| 248 | |||
| 249 | #define V4L2_STD_UNKNOWN 0 | ||
| 250 | #define V4L2_STD_ALL (V4L2_STD_525_60 |\ | ||
| 251 | V4L2_STD_625_50) | ||
| 252 | </programlisting></para> | ||
| 253 | |||
| 254 | <table pgwide="1" id="video-standards" orient="land"> | ||
| 255 | <title>Video Standards (based on [<xref linkend="itu470" />])</title> | ||
| 256 | <tgroup cols="12" colsep="1" rowsep="1" align="center"> | ||
| 257 | <colspec colname="c1" align="left" /> | ||
| 258 | <colspec colname="c2" /> | ||
| 259 | <colspec colname="c3" /> | ||
| 260 | <colspec colname="c4" /> | ||
| 261 | <colspec colname="c5" /> | ||
| 262 | <colspec colnum="7" colname="c7" /> | ||
| 263 | <colspec colnum="9" colname="c9" /> | ||
| 264 | <colspec colnum="12" colname="c12" /> | ||
| 265 | <spanspec namest="c2" nameend="c3" spanname="m" align="center" /> | ||
| 266 | <spanspec namest="c4" nameend="c12" spanname="x" align="center" /> | ||
| 267 | <spanspec namest="c5" nameend="c7" spanname="b" align="center" /> | ||
| 268 | <spanspec namest="c9" nameend="c12" spanname="s" align="center" /> | ||
| 269 | <thead> | ||
| 270 | <row> | ||
| 271 | <entry>Characteristics</entry> | ||
| 272 | <entry><para>M/NTSC<footnote><para>Japan uses a standard | ||
| 273 | similar to M/NTSC | ||
| 274 | (V4L2_STD_NTSC_M_JP).</para></footnote></para></entry> | ||
| 275 | <entry>M/PAL</entry> | ||
| 276 | <entry><para>N/PAL<footnote><para> The values in | ||
| 277 | brackets apply to the combination N/PAL a.k.a. | ||
| 278 | N<subscript>C</subscript> used in Argentina | ||
| 279 | (V4L2_STD_PAL_Nc).</para></footnote></para></entry> | ||
| 280 | <entry align="center">B, B1, G/PAL</entry> | ||
| 281 | <entry align="center">D, D1, K/PAL</entry> | ||
| 282 | <entry align="center">H/PAL</entry> | ||
| 283 | <entry align="center">I/PAL</entry> | ||
| 284 | <entry align="center">B, G/SECAM</entry> | ||
| 285 | <entry align="center">D, K/SECAM</entry> | ||
| 286 | <entry align="center">K1/SECAM</entry> | ||
| 287 | <entry align="center">L/SECAM</entry> | ||
| 288 | </row> | ||
| 289 | </thead> | ||
| 290 | <tbody valign="top"> | ||
| 291 | <row> | ||
| 292 | <entry>Frame lines</entry> | ||
| 293 | <entry spanname="m">525</entry> | ||
| 294 | <entry spanname="x">625</entry> | ||
| 295 | </row> | ||
| 296 | <row> | ||
| 297 | <entry>Frame period (s)</entry> | ||
| 298 | <entry spanname="m">1001/30000</entry> | ||
| 299 | <entry spanname="x">1/25</entry> | ||
| 300 | </row> | ||
| 301 | <row> | ||
| 302 | <entry>Chrominance sub-carrier frequency (Hz)</entry> | ||
| 303 | <entry>3579545 ± 10</entry> | ||
| 304 | <entry>3579611.49 ± 10</entry> | ||
| 305 | <entry>4433618.75 ± 5 (3582056.25 | ||
| 306 | ± 5)</entry> | ||
| 307 | <entry spanname="b">4433618.75 ± 5</entry> | ||
| 308 | <entry>4433618.75 ± 1</entry> | ||
| 309 | <entry spanname="s">f<subscript>OR</subscript> = | ||
| 310 | 4406250 ± 2000, f<subscript>OB</subscript> = 4250000 | ||
| 311 | ± 2000</entry> | ||
| 312 | </row> | ||
| 313 | <row> | ||
| 314 | <entry>Nominal radio-frequency channel bandwidth | ||
| 315 | (MHz)</entry> | ||
| 316 | <entry>6</entry> | ||
| 317 | <entry>6</entry> | ||
| 318 | <entry>6</entry> | ||
| 319 | <entry>B: 7; B1, G: 8</entry> | ||
| 320 | <entry>8</entry> | ||
| 321 | <entry>8</entry> | ||
| 322 | <entry>8</entry> | ||
| 323 | <entry>8</entry> | ||
| 324 | <entry>8</entry> | ||
| 325 | <entry>8</entry> | ||
| 326 | <entry>8</entry> | ||
| 327 | </row> | ||
| 328 | <row> | ||
| 329 | <entry>Sound carrier relative to vision carrier | ||
| 330 | (MHz)</entry> | ||
| 331 | <entry>+ 4.5</entry> | ||
| 332 | <entry>+ 4.5</entry> | ||
| 333 | <entry>+ 4.5</entry> | ||
| 334 | <entry><para>+ 5.5 ± 0.001 | ||
| 335 | <footnote><para>In the Federal Republic of Germany, Austria, Italy, | ||
| 336 | the Netherlands, Slovakia and Switzerland a system of two sound | ||
| 337 | carriers is used, the frequency of the second carrier being | ||
| 338 | 242.1875 kHz above the frequency of the first sound carrier. For | ||
| 339 | stereophonic sound transmissions a similar system is used in | ||
| 340 | Australia.</para></footnote> <footnote><para>New Zealand uses a sound | ||
| 341 | carrier displaced 5.4996 ± 0.0005 MHz from the vision | ||
| 342 | carrier.</para></footnote> <footnote><para>In Denmark, Finland, New | ||
| 343 | Zealand, Sweden and Spain a system of two sound carriers is used. In | ||
| 344 | Iceland, Norway and Poland the same system is being introduced. The | ||
| 345 | second carrier is 5.85 MHz above the vision carrier and is DQPSK | ||
| 346 | modulated with 728 kbit/s sound and data multiplex. (NICAM | ||
| 347 | system)</para></footnote> <footnote><para>In the United Kingdom, a | ||
| 348 | system of two sound carriers is used. The second sound carrier is | ||
| 349 | 6.552 MHz above the vision carrier and is DQPSK modulated with a | ||
| 350 | 728 kbit/s sound and data multiplex able to carry two sound | ||
| 351 | channels. (NICAM system)</para></footnote></para></entry> | ||
| 352 | <entry>+ 6.5 ± 0.001</entry> | ||
| 353 | <entry>+ 5.5</entry> | ||
| 354 | <entry>+ 5.9996 ± 0.0005</entry> | ||
| 355 | <entry>+ 5.5 ± 0.001</entry> | ||
| 356 | <entry>+ 6.5 ± 0.001</entry> | ||
| 357 | <entry>+ 6.5</entry> | ||
| 358 | <entry><para>+ 6.5 <footnote><para>In France, a | ||
| 359 | digital carrier 5.85 MHz away from the vision carrier may be used in | ||
| 360 | addition to the main sound carrier. It is modulated in differentially | ||
| 361 | encoded QPSK with a 728 kbit/s sound and data multiplexer capable of | ||
| 362 | carrying two sound channels. (NICAM | ||
| 363 | system)</para></footnote></para></entry> | ||
| 364 | </row> | ||
| 365 | </tbody> | ||
| 366 | </tgroup> | ||
| 367 | </table> | ||
| 368 | </refsect1> | ||
| 369 | |||
| 370 | <refsect1> | ||
| 371 | &return-value; | ||
| 372 | |||
| 373 | <variablelist> | ||
| 374 | <varlistentry> | ||
| 375 | <term><errorcode>EINVAL</errorcode></term> | ||
| 376 | <listitem> | ||
| 377 | <para>The &v4l2-standard; <structfield>index</structfield> | ||
| 378 | is out of bounds.</para> | ||
| 379 | </listitem> | ||
| 380 | </varlistentry> | ||
| 381 | </variablelist> | ||
| 382 | </refsect1> | ||
| 383 | </refentry> | ||
| 384 | |||
| 385 | <!-- | ||
| 386 | Local Variables: | ||
| 387 | mode: sgml | ||
| 388 | sgml-parent-document: "v4l2.sgml" | ||
| 389 | indent-tabs-mode: nil | ||
| 390 | End: | ||
| 391 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-audio.xml b/Documentation/DocBook/v4l/vidioc-g-audio.xml new file mode 100644 index 000000000000..65361a8c2b05 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-audio.xml | |||
| @@ -0,0 +1,188 @@ | |||
| 1 | <refentry id="vidioc-g-audio"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_AUDIO</refname> | ||
| 9 | <refname>VIDIOC_S_AUDIO</refname> | ||
| 10 | <refpurpose>Query or select the current audio input and its | ||
| 11 | attributes</refpurpose> | ||
| 12 | </refnamediv> | ||
| 13 | |||
| 14 | <refsynopsisdiv> | ||
| 15 | <funcsynopsis> | ||
| 16 | <funcprototype> | ||
| 17 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 18 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 19 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 20 | <paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | <funcsynopsis> | ||
| 24 | <funcprototype> | ||
| 25 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 28 | <paramdef>const struct v4l2_audio *<parameter>argp</parameter></paramdef> | ||
| 29 | </funcprototype> | ||
| 30 | </funcsynopsis> | ||
| 31 | </refsynopsisdiv> | ||
| 32 | |||
| 33 | <refsect1> | ||
| 34 | <title>Arguments</title> | ||
| 35 | |||
| 36 | <variablelist> | ||
| 37 | <varlistentry> | ||
| 38 | <term><parameter>fd</parameter></term> | ||
| 39 | <listitem> | ||
| 40 | <para>&fd;</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | <varlistentry> | ||
| 44 | <term><parameter>request</parameter></term> | ||
| 45 | <listitem> | ||
| 46 | <para>VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</para> | ||
| 47 | </listitem> | ||
| 48 | </varlistentry> | ||
| 49 | <varlistentry> | ||
| 50 | <term><parameter>argp</parameter></term> | ||
| 51 | <listitem> | ||
| 52 | <para></para> | ||
| 53 | </listitem> | ||
| 54 | </varlistentry> | ||
| 55 | </variablelist> | ||
| 56 | </refsect1> | ||
| 57 | |||
| 58 | <refsect1> | ||
| 59 | <title>Description</title> | ||
| 60 | |||
| 61 | <para>To query the current audio input applications zero out the | ||
| 62 | <structfield>reserved</structfield> array of a &v4l2-audio; | ||
| 63 | and call the <constant>VIDIOC_G_AUDIO</constant> ioctl with a pointer | ||
| 64 | to this structure. Drivers fill the rest of the structure or return an | ||
| 65 | &EINVAL; when the device has no audio inputs, or none which combine | ||
| 66 | with the current video input.</para> | ||
| 67 | |||
| 68 | <para>Audio inputs have one writable property, the audio mode. To | ||
| 69 | select the current audio input <emphasis>and</emphasis> change the | ||
| 70 | audio mode, applications initialize the | ||
| 71 | <structfield>index</structfield> and <structfield>mode</structfield> | ||
| 72 | fields, and the | ||
| 73 | <structfield>reserved</structfield> array of a | ||
| 74 | <structname>v4l2_audio</structname> structure and call the | ||
| 75 | <constant>VIDIOC_S_AUDIO</constant> ioctl. Drivers may switch to a | ||
| 76 | different audio mode if the request cannot be satisfied. However, this | ||
| 77 | is a write-only ioctl, it does not return the actual new audio | ||
| 78 | mode.</para> | ||
| 79 | |||
| 80 | <table pgwide="1" frame="none" id="v4l2-audio"> | ||
| 81 | <title>struct <structname>v4l2_audio</structname></title> | ||
| 82 | <tgroup cols="3"> | ||
| 83 | &cs-str; | ||
| 84 | <tbody valign="top"> | ||
| 85 | <row> | ||
| 86 | <entry>__u32</entry> | ||
| 87 | <entry><structfield>index</structfield></entry> | ||
| 88 | <entry>Identifies the audio input, set by the | ||
| 89 | driver or application.</entry> | ||
| 90 | </row> | ||
| 91 | <row> | ||
| 92 | <entry>__u8</entry> | ||
| 93 | <entry><structfield>name</structfield>[32]</entry> | ||
| 94 | <entry>Name of the audio input, a NUL-terminated ASCII | ||
| 95 | string, for example: "Line In". This information is intended for the | ||
| 96 | user, preferably the connector label on the device itself.</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry>__u32</entry> | ||
| 100 | <entry><structfield>capability</structfield></entry> | ||
| 101 | <entry>Audio capability flags, see <xref | ||
| 102 | linkend="audio-capability" />.</entry> | ||
| 103 | </row> | ||
| 104 | <row> | ||
| 105 | <entry>__u32</entry> | ||
| 106 | <entry><structfield>mode</structfield></entry> | ||
| 107 | <entry>Audio mode flags set by drivers and applications (on | ||
| 108 | <constant>VIDIOC_S_AUDIO</constant> ioctl), see <xref linkend="audio-mode" />.</entry> | ||
| 109 | </row> | ||
| 110 | <row> | ||
| 111 | <entry>__u32</entry> | ||
| 112 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 113 | <entry>Reserved for future extensions. Drivers and | ||
| 114 | applications must set the array to zero.</entry> | ||
| 115 | </row> | ||
| 116 | </tbody> | ||
| 117 | </tgroup> | ||
| 118 | </table> | ||
| 119 | |||
| 120 | <table pgwide="1" frame="none" id="audio-capability"> | ||
| 121 | <title>Audio Capability Flags</title> | ||
| 122 | <tgroup cols="3"> | ||
| 123 | &cs-def; | ||
| 124 | <tbody valign="top"> | ||
| 125 | <row> | ||
| 126 | <entry><constant>V4L2_AUDCAP_STEREO</constant></entry> | ||
| 127 | <entry>0x00001</entry> | ||
| 128 | <entry>This is a stereo input. The flag is intended to | ||
| 129 | automatically disable stereo recording etc. when the signal is always | ||
| 130 | monaural. The API provides no means to detect if stereo is | ||
| 131 | <emphasis>received</emphasis>, unless the audio input belongs to a | ||
| 132 | tuner.</entry> | ||
| 133 | </row> | ||
| 134 | <row> | ||
| 135 | <entry><constant>V4L2_AUDCAP_AVL</constant></entry> | ||
| 136 | <entry>0x00002</entry> | ||
| 137 | <entry>Automatic Volume Level mode is supported.</entry> | ||
| 138 | </row> | ||
| 139 | </tbody> | ||
| 140 | </tgroup> | ||
| 141 | </table> | ||
| 142 | |||
| 143 | <table pgwide="1" frame="none" id="audio-mode"> | ||
| 144 | <title>Audio Mode Flags</title> | ||
| 145 | <tgroup cols="3"> | ||
| 146 | &cs-def; | ||
| 147 | <tbody valign="top"> | ||
| 148 | <row> | ||
| 149 | <entry><constant>V4L2_AUDMODE_AVL</constant></entry> | ||
| 150 | <entry>0x00001</entry> | ||
| 151 | <entry>AVL mode is on.</entry> | ||
| 152 | </row> | ||
| 153 | </tbody> | ||
| 154 | </tgroup> | ||
| 155 | </table> | ||
| 156 | </refsect1> | ||
| 157 | |||
| 158 | <refsect1> | ||
| 159 | &return-value; | ||
| 160 | |||
| 161 | <variablelist> | ||
| 162 | <varlistentry> | ||
| 163 | <term><errorcode>EINVAL</errorcode></term> | ||
| 164 | <listitem> | ||
| 165 | <para>No audio inputs combine with the current video input, | ||
| 166 | or the number of the selected audio input is out of bounds or it does | ||
| 167 | not combine, or there are no audio inputs at all and the ioctl is not | ||
| 168 | supported.</para> | ||
| 169 | </listitem> | ||
| 170 | </varlistentry> | ||
| 171 | <varlistentry> | ||
| 172 | <term><errorcode>EBUSY</errorcode></term> | ||
| 173 | <listitem> | ||
| 174 | <para>I/O is in progress, the input cannot be | ||
| 175 | switched.</para> | ||
| 176 | </listitem> | ||
| 177 | </varlistentry> | ||
| 178 | </variablelist> | ||
| 179 | </refsect1> | ||
| 180 | </refentry> | ||
| 181 | |||
| 182 | <!-- | ||
| 183 | Local Variables: | ||
| 184 | mode: sgml | ||
| 185 | sgml-parent-document: "v4l2.sgml" | ||
| 186 | indent-tabs-mode: nil | ||
| 187 | End: | ||
| 188 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-audioout.xml b/Documentation/DocBook/v4l/vidioc-g-audioout.xml new file mode 100644 index 000000000000..3632730c5c6e --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-audioout.xml | |||
| @@ -0,0 +1,154 @@ | |||
| 1 | <refentry id="vidioc-g-audioout"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_AUDOUT</refname> | ||
| 9 | <refname>VIDIOC_S_AUDOUT</refname> | ||
| 10 | <refpurpose>Query or select the current audio output</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>const struct v4l2_audioout *<parameter>argp</parameter></paramdef> | ||
| 28 | </funcprototype> | ||
| 29 | </funcsynopsis> | ||
| 30 | </refsynopsisdiv> | ||
| 31 | |||
| 32 | <refsect1> | ||
| 33 | <title>Arguments</title> | ||
| 34 | |||
| 35 | <variablelist> | ||
| 36 | <varlistentry> | ||
| 37 | <term><parameter>fd</parameter></term> | ||
| 38 | <listitem> | ||
| 39 | <para>&fd;</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>request</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | <varlistentry> | ||
| 49 | <term><parameter>argp</parameter></term> | ||
| 50 | <listitem> | ||
| 51 | <para></para> | ||
| 52 | </listitem> | ||
| 53 | </varlistentry> | ||
| 54 | </variablelist> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Description</title> | ||
| 59 | |||
| 60 | <para>To query the current audio output applications zero out the | ||
| 61 | <structfield>reserved</structfield> array of a &v4l2-audioout; and | ||
| 62 | call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer | ||
| 63 | to this structure. Drivers fill the rest of the structure or return an | ||
| 64 | &EINVAL; when the device has no audio inputs, or none which combine | ||
| 65 | with the current video output.</para> | ||
| 66 | |||
| 67 | <para>Audio outputs have no writable properties. Nevertheless, to | ||
| 68 | select the current audio output applications can initialize the | ||
| 69 | <structfield>index</structfield> field and | ||
| 70 | <structfield>reserved</structfield> array (which in the future may | ||
| 71 | contain writable properties) of a | ||
| 72 | <structname>v4l2_audioout</structname> structure and call the | ||
| 73 | <constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the | ||
| 74 | requested output or return the &EINVAL; when the index is out of | ||
| 75 | bounds. This is a write-only ioctl, it does not return the current | ||
| 76 | audio output attributes as <constant>VIDIOC_G_AUDOUT</constant> | ||
| 77 | does.</para> | ||
| 78 | |||
| 79 | <para>Note connectors on a TV card to loop back the received audio | ||
| 80 | signal to a sound card are not audio outputs in this sense.</para> | ||
| 81 | |||
| 82 | <table pgwide="1" frame="none" id="v4l2-audioout"> | ||
| 83 | <title>struct <structname>v4l2_audioout</structname></title> | ||
| 84 | <tgroup cols="3"> | ||
| 85 | &cs-str; | ||
| 86 | <tbody valign="top"> | ||
| 87 | <row> | ||
| 88 | <entry>__u32</entry> | ||
| 89 | <entry><structfield>index</structfield></entry> | ||
| 90 | <entry>Identifies the audio output, set by the | ||
| 91 | driver or application.</entry> | ||
| 92 | </row> | ||
| 93 | <row> | ||
| 94 | <entry>__u8</entry> | ||
| 95 | <entry><structfield>name</structfield>[32]</entry> | ||
| 96 | <entry>Name of the audio output, a NUL-terminated ASCII | ||
| 97 | string, for example: "Line Out". This information is intended for the | ||
| 98 | user, preferably the connector label on the device itself.</entry> | ||
| 99 | </row> | ||
| 100 | <row> | ||
| 101 | <entry>__u32</entry> | ||
| 102 | <entry><structfield>capability</structfield></entry> | ||
| 103 | <entry>Audio capability flags, none defined yet. Drivers | ||
| 104 | must set this field to zero.</entry> | ||
| 105 | </row> | ||
| 106 | <row> | ||
| 107 | <entry>__u32</entry> | ||
| 108 | <entry><structfield>mode</structfield></entry> | ||
| 109 | <entry>Audio mode, none defined yet. Drivers and | ||
| 110 | applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this | ||
| 111 | field to zero.</entry> | ||
| 112 | </row> | ||
| 113 | <row> | ||
| 114 | <entry>__u32</entry> | ||
| 115 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 116 | <entry>Reserved for future extensions. Drivers and | ||
| 117 | applications must set the array to zero.</entry> | ||
| 118 | </row> | ||
| 119 | </tbody> | ||
| 120 | </tgroup> | ||
| 121 | </table> | ||
| 122 | </refsect1> | ||
| 123 | |||
| 124 | <refsect1> | ||
| 125 | &return-value; | ||
| 126 | |||
| 127 | <variablelist> | ||
| 128 | <varlistentry> | ||
| 129 | <term><errorcode>EINVAL</errorcode></term> | ||
| 130 | <listitem> | ||
| 131 | <para>No audio outputs combine with the current video | ||
| 132 | output, or the number of the selected audio output is out of bounds or | ||
| 133 | it does not combine, or there are no audio outputs at all and the | ||
| 134 | ioctl is not supported.</para> | ||
| 135 | </listitem> | ||
| 136 | </varlistentry> | ||
| 137 | <varlistentry> | ||
| 138 | <term><errorcode>EBUSY</errorcode></term> | ||
| 139 | <listitem> | ||
| 140 | <para>I/O is in progress, the output cannot be | ||
| 141 | switched.</para> | ||
| 142 | </listitem> | ||
| 143 | </varlistentry> | ||
| 144 | </variablelist> | ||
| 145 | </refsect1> | ||
| 146 | </refentry> | ||
| 147 | |||
| 148 | <!-- | ||
| 149 | Local Variables: | ||
| 150 | mode: sgml | ||
| 151 | sgml-parent-document: "v4l2.sgml" | ||
| 152 | indent-tabs-mode: nil | ||
| 153 | End: | ||
| 154 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-crop.xml b/Documentation/DocBook/v4l/vidioc-g-crop.xml new file mode 100644 index 000000000000..d235b1dedbed --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-crop.xml | |||
| @@ -0,0 +1,143 @@ | |||
| 1 | <refentry id="vidioc-g-crop"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_CROP</refname> | ||
| 9 | <refname>VIDIOC_S_CROP</refname> | ||
| 10 | <refpurpose>Get or set the current cropping rectangle</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_crop *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>const struct v4l2_crop *<parameter>argp</parameter></paramdef> | ||
| 28 | </funcprototype> | ||
| 29 | </funcsynopsis> | ||
| 30 | </refsynopsisdiv> | ||
| 31 | |||
| 32 | <refsect1> | ||
| 33 | <title>Arguments</title> | ||
| 34 | |||
| 35 | <variablelist> | ||
| 36 | <varlistentry> | ||
| 37 | <term><parameter>fd</parameter></term> | ||
| 38 | <listitem> | ||
| 39 | <para>&fd;</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>request</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>VIDIOC_G_CROP, VIDIOC_S_CROP</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | <varlistentry> | ||
| 49 | <term><parameter>argp</parameter></term> | ||
| 50 | <listitem> | ||
| 51 | <para></para> | ||
| 52 | </listitem> | ||
| 53 | </varlistentry> | ||
| 54 | </variablelist> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Description</title> | ||
| 59 | |||
| 60 | <para>To query the cropping rectangle size and position | ||
| 61 | applications set the <structfield>type</structfield> field of a | ||
| 62 | <structname>v4l2_crop</structname> structure to the respective buffer | ||
| 63 | (stream) type and call the <constant>VIDIOC_G_CROP</constant> ioctl | ||
| 64 | with a pointer to this structure. The driver fills the rest of the | ||
| 65 | structure or returns the &EINVAL; if cropping is not supported.</para> | ||
| 66 | |||
| 67 | <para>To change the cropping rectangle applications initialize the | ||
| 68 | <structfield>type</structfield> and &v4l2-rect; substructure named | ||
| 69 | <structfield>c</structfield> of a v4l2_crop structure and call the | ||
| 70 | <constant>VIDIOC_S_CROP</constant> ioctl with a pointer to this | ||
| 71 | structure.</para> | ||
| 72 | |||
| 73 | <para>The driver first adjusts the requested dimensions against | ||
| 74 | hardware limits, &ie; the bounds given by the capture/output window, | ||
| 75 | and it rounds to the closest possible values of horizontal and | ||
| 76 | vertical offset, width and height. In particular the driver must round | ||
| 77 | the vertical offset of the cropping rectangle to frame lines modulo | ||
| 78 | two, such that the field order cannot be confused.</para> | ||
| 79 | |||
| 80 | <para>Second the driver adjusts the image size (the opposite | ||
| 81 | rectangle of the scaling process, source or target depending on the | ||
| 82 | data direction) to the closest size possible while maintaining the | ||
| 83 | current horizontal and vertical scaling factor.</para> | ||
| 84 | |||
| 85 | <para>Finally the driver programs the hardware with the actual | ||
| 86 | cropping and image parameters. <constant>VIDIOC_S_CROP</constant> is a | ||
| 87 | write-only ioctl, it does not return the actual parameters. To query | ||
| 88 | them applications must call <constant>VIDIOC_G_CROP</constant> and | ||
| 89 | &VIDIOC-G-FMT;. When the parameters are unsuitable the application may | ||
| 90 | modify the cropping or image parameters and repeat the cycle until | ||
| 91 | satisfactory parameters have been negotiated.</para> | ||
| 92 | |||
| 93 | <para>When cropping is not supported then no parameters are | ||
| 94 | changed and <constant>VIDIOC_S_CROP</constant> returns the | ||
| 95 | &EINVAL;.</para> | ||
| 96 | |||
| 97 | <table pgwide="1" frame="none" id="v4l2-crop"> | ||
| 98 | <title>struct <structname>v4l2_crop</structname></title> | ||
| 99 | <tgroup cols="3"> | ||
| 100 | &cs-str; | ||
| 101 | <tbody valign="top"> | ||
| 102 | <row> | ||
| 103 | <entry>&v4l2-buf-type;</entry> | ||
| 104 | <entry><structfield>type</structfield></entry> | ||
| 105 | <entry>Type of the data stream, set by the application. | ||
| 106 | Only these types are valid here: <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, | ||
| 107 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, | ||
| 108 | <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver | ||
| 109 | defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> | ||
| 110 | and higher.</entry> | ||
| 111 | </row> | ||
| 112 | <row> | ||
| 113 | <entry>&v4l2-rect;</entry> | ||
| 114 | <entry><structfield>c</structfield></entry> | ||
| 115 | <entry>Cropping rectangle. The same co-ordinate system as | ||
| 116 | for &v4l2-cropcap; <structfield>bounds</structfield> is used.</entry> | ||
| 117 | </row> | ||
| 118 | </tbody> | ||
| 119 | </tgroup> | ||
| 120 | </table> | ||
| 121 | </refsect1> | ||
| 122 | |||
| 123 | <refsect1> | ||
| 124 | &return-value; | ||
| 125 | |||
| 126 | <variablelist> | ||
| 127 | <varlistentry> | ||
| 128 | <term><errorcode>EINVAL</errorcode></term> | ||
| 129 | <listitem> | ||
| 130 | <para>Cropping is not supported.</para> | ||
| 131 | </listitem> | ||
| 132 | </varlistentry> | ||
| 133 | </variablelist> | ||
| 134 | </refsect1> | ||
| 135 | </refentry> | ||
| 136 | |||
| 137 | <!-- | ||
| 138 | Local Variables: | ||
| 139 | mode: sgml | ||
| 140 | sgml-parent-document: "v4l2.sgml" | ||
| 141 | indent-tabs-mode: nil | ||
| 142 | End: | ||
| 143 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-ctrl.xml b/Documentation/DocBook/v4l/vidioc-g-ctrl.xml new file mode 100644 index 000000000000..8b5e6ff7f3df --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-ctrl.xml | |||
| @@ -0,0 +1,130 @@ | |||
| 1 | <refentry id="vidioc-g-ctrl"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_CTRL</refname> | ||
| 9 | <refname>VIDIOC_S_CTRL</refname> | ||
| 10 | <refpurpose>Get or set the value of a control</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_control | ||
| 20 | *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | </refsynopsisdiv> | ||
| 24 | |||
| 25 | <refsect1> | ||
| 26 | <title>Arguments</title> | ||
| 27 | |||
| 28 | <variablelist> | ||
| 29 | <varlistentry> | ||
| 30 | <term><parameter>fd</parameter></term> | ||
| 31 | <listitem> | ||
| 32 | <para>&fd;</para> | ||
| 33 | </listitem> | ||
| 34 | </varlistentry> | ||
| 35 | <varlistentry> | ||
| 36 | <term><parameter>request</parameter></term> | ||
| 37 | <listitem> | ||
| 38 | <para>VIDIOC_G_CTRL, VIDIOC_S_CTRL</para> | ||
| 39 | </listitem> | ||
| 40 | </varlistentry> | ||
| 41 | <varlistentry> | ||
| 42 | <term><parameter>argp</parameter></term> | ||
| 43 | <listitem> | ||
| 44 | <para></para> | ||
| 45 | </listitem> | ||
| 46 | </varlistentry> | ||
| 47 | </variablelist> | ||
| 48 | </refsect1> | ||
| 49 | |||
| 50 | <refsect1> | ||
| 51 | <title>Description</title> | ||
| 52 | |||
| 53 | <para>To get the current value of a control applications | ||
| 54 | initialize the <structfield>id</structfield> field of a struct | ||
| 55 | <structname>v4l2_control</structname> and call the | ||
| 56 | <constant>VIDIOC_G_CTRL</constant> ioctl with a pointer to this | ||
| 57 | structure. To change the value of a control applications initialize | ||
| 58 | the <structfield>id</structfield> and <structfield>value</structfield> | ||
| 59 | fields of a struct <structname>v4l2_control</structname> and call the | ||
| 60 | <constant>VIDIOC_S_CTRL</constant> ioctl.</para> | ||
| 61 | |||
| 62 | <para>When the <structfield>id</structfield> is invalid drivers | ||
| 63 | return an &EINVAL;. When the <structfield>value</structfield> is out | ||
| 64 | of bounds drivers can choose to take the closest valid value or return | ||
| 65 | an &ERANGE;, whatever seems more appropriate. However, | ||
| 66 | <constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not | ||
| 67 | return the actual new value.</para> | ||
| 68 | |||
| 69 | <para>These ioctls work only with user controls. For other | ||
| 70 | control classes the &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; or | ||
| 71 | &VIDIOC-TRY-EXT-CTRLS; must be used.</para> | ||
| 72 | |||
| 73 | <table pgwide="1" frame="none" id="v4l2-control"> | ||
| 74 | <title>struct <structname>v4l2_control</structname></title> | ||
| 75 | <tgroup cols="3"> | ||
| 76 | &cs-str; | ||
| 77 | <tbody valign="top"> | ||
| 78 | <row> | ||
| 79 | <entry>__u32</entry> | ||
| 80 | <entry><structfield>id</structfield></entry> | ||
| 81 | <entry>Identifies the control, set by the | ||
| 82 | application.</entry> | ||
| 83 | </row> | ||
| 84 | <row> | ||
| 85 | <entry>__s32</entry> | ||
| 86 | <entry><structfield>value</structfield></entry> | ||
| 87 | <entry>New value or current value.</entry> | ||
| 88 | </row> | ||
| 89 | </tbody> | ||
| 90 | </tgroup> | ||
| 91 | </table> | ||
| 92 | </refsect1> | ||
| 93 | |||
| 94 | <refsect1> | ||
| 95 | &return-value; | ||
| 96 | |||
| 97 | <variablelist> | ||
| 98 | <varlistentry> | ||
| 99 | <term><errorcode>EINVAL</errorcode></term> | ||
| 100 | <listitem> | ||
| 101 | <para>The &v4l2-control; <structfield>id</structfield> is | ||
| 102 | invalid.</para> | ||
| 103 | </listitem> | ||
| 104 | </varlistentry> | ||
| 105 | <varlistentry> | ||
| 106 | <term><errorcode>ERANGE</errorcode></term> | ||
| 107 | <listitem> | ||
| 108 | <para>The &v4l2-control; <structfield>value</structfield> | ||
| 109 | is out of bounds.</para> | ||
| 110 | </listitem> | ||
| 111 | </varlistentry> | ||
| 112 | <varlistentry> | ||
| 113 | <term><errorcode>EBUSY</errorcode></term> | ||
| 114 | <listitem> | ||
| 115 | <para>The control is temporarily not changeable, possibly | ||
| 116 | because another applications took over control of the device function | ||
| 117 | this control belongs to.</para> | ||
| 118 | </listitem> | ||
| 119 | </varlistentry> | ||
| 120 | </variablelist> | ||
| 121 | </refsect1> | ||
| 122 | </refentry> | ||
| 123 | |||
| 124 | <!-- | ||
| 125 | Local Variables: | ||
| 126 | mode: sgml | ||
| 127 | sgml-parent-document: "v4l2.sgml" | ||
| 128 | indent-tabs-mode: nil | ||
| 129 | End: | ||
| 130 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-enc-index.xml b/Documentation/DocBook/v4l/vidioc-g-enc-index.xml new file mode 100644 index 000000000000..9f242e4b2948 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-enc-index.xml | |||
| @@ -0,0 +1,213 @@ | |||
| 1 | <refentry id="vidioc-g-enc-index"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_ENC_INDEX</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_ENC_INDEX</refname> | ||
| 9 | <refpurpose>Get meta data about a compressed video stream</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_enc_idx *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_G_ENC_INDEX</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <note> | ||
| 52 | <title>Experimental</title> | ||
| 53 | |||
| 54 | <para>This is an <link linkend="experimental">experimental</link> | ||
| 55 | interface and may change in the future.</para> | ||
| 56 | </note> | ||
| 57 | |||
| 58 | <para>The <constant>VIDIOC_G_ENC_INDEX</constant> ioctl provides | ||
| 59 | meta data about a compressed video stream the same or another | ||
| 60 | application currently reads from the driver, which is useful for | ||
| 61 | random access into the stream without decoding it.</para> | ||
| 62 | |||
| 63 | <para>To read the data applications must call | ||
| 64 | <constant>VIDIOC_G_ENC_INDEX</constant> with a pointer to a | ||
| 65 | &v4l2-enc-idx;. On success the driver fills the | ||
| 66 | <structfield>entry</structfield> array, stores the number of elements | ||
| 67 | written in the <structfield>entries</structfield> field, and | ||
| 68 | initializes the <structfield>entries_cap</structfield> field.</para> | ||
| 69 | |||
| 70 | <para>Each element of the <structfield>entry</structfield> array | ||
| 71 | contains meta data about one picture. A | ||
| 72 | <constant>VIDIOC_G_ENC_INDEX</constant> call reads up to | ||
| 73 | <constant>V4L2_ENC_IDX_ENTRIES</constant> entries from a driver | ||
| 74 | buffer, which can hold up to <structfield>entries_cap</structfield> | ||
| 75 | entries. This number can be lower or higher than | ||
| 76 | <constant>V4L2_ENC_IDX_ENTRIES</constant>, but not zero. When the | ||
| 77 | application fails to read the meta data in time the oldest entries | ||
| 78 | will be lost. When the buffer is empty or no capturing/encoding is in | ||
| 79 | progress, <structfield>entries</structfield> will be zero.</para> | ||
| 80 | |||
| 81 | <para>Currently this ioctl is only defined for MPEG-2 program | ||
| 82 | streams and video elementary streams.</para> | ||
| 83 | |||
| 84 | <table pgwide="1" frame="none" id="v4l2-enc-idx"> | ||
| 85 | <title>struct <structname>v4l2_enc_idx</structname></title> | ||
| 86 | <tgroup cols="3"> | ||
| 87 | &cs-str; | ||
| 88 | <tbody valign="top"> | ||
| 89 | <row> | ||
| 90 | <entry>__u32</entry> | ||
| 91 | <entry><structfield>entries</structfield></entry> | ||
| 92 | <entry>The number of entries the driver stored in the | ||
| 93 | <structfield>entry</structfield> array.</entry> | ||
| 94 | </row> | ||
| 95 | <row> | ||
| 96 | <entry>__u32</entry> | ||
| 97 | <entry><structfield>entries_cap</structfield></entry> | ||
| 98 | <entry>The number of entries the driver can | ||
| 99 | buffer. Must be greater than zero.</entry> | ||
| 100 | </row> | ||
| 101 | <row> | ||
| 102 | <entry>__u32</entry> | ||
| 103 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 104 | <entry spanname="hspan">Reserved for future extensions. | ||
| 105 | Drivers must set the array to zero.</entry> | ||
| 106 | </row> | ||
| 107 | <row> | ||
| 108 | <entry>&v4l2-enc-idx-entry;</entry> | ||
| 109 | <entry><structfield>entry</structfield>[<constant>V4L2_ENC_IDX_ENTRIES</constant>]</entry> | ||
| 110 | <entry>Meta data about a compressed video stream. Each | ||
| 111 | element of the array corresponds to one picture, sorted in ascending | ||
| 112 | order by their <structfield>offset</structfield>.</entry> | ||
| 113 | </row> | ||
| 114 | </tbody> | ||
| 115 | </tgroup> | ||
| 116 | </table> | ||
| 117 | |||
| 118 | <table pgwide="1" frame="none" id="v4l2-enc-idx-entry"> | ||
| 119 | <title>struct <structname>v4l2_enc_idx_entry</structname></title> | ||
| 120 | <tgroup cols="3"> | ||
| 121 | &cs-str; | ||
| 122 | <tbody valign="top"> | ||
| 123 | <row> | ||
| 124 | <entry>__u64</entry> | ||
| 125 | <entry><structfield>offset</structfield></entry> | ||
| 126 | <entry>The offset in bytes from the beginning of the | ||
| 127 | compressed video stream to the beginning of this picture, that is a | ||
| 128 | <wordasword>PES packet header</wordasword> as defined in <xref | ||
| 129 | linkend="mpeg2part1" /> or a <wordasword>picture | ||
| 130 | header</wordasword> as defined in <xref linkend="mpeg2part2" />. When | ||
| 131 | the encoder is stopped, the driver resets the offset to zero.</entry> | ||
| 132 | </row> | ||
| 133 | <row> | ||
| 134 | <entry>__u64</entry> | ||
| 135 | <entry><structfield>pts</structfield></entry> | ||
| 136 | <entry>The 33 bit <wordasword>Presentation Time | ||
| 137 | Stamp</wordasword> of this picture as defined in <xref | ||
| 138 | linkend="mpeg2part1" />.</entry> | ||
| 139 | </row> | ||
| 140 | <row> | ||
| 141 | <entry>__u32</entry> | ||
| 142 | <entry><structfield>length</structfield></entry> | ||
| 143 | <entry>The length of this picture in bytes.</entry> | ||
| 144 | </row> | ||
| 145 | <row> | ||
| 146 | <entry>__u32</entry> | ||
| 147 | <entry><structfield>flags</structfield></entry> | ||
| 148 | <entry>Flags containing the coding type of this picture, see <xref | ||
| 149 | linkend="enc-idx-flags" />.</entry> | ||
| 150 | </row> | ||
| 151 | <row> | ||
| 152 | <entry>__u32</entry> | ||
| 153 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 154 | <entry>Reserved for future extensions. | ||
| 155 | Drivers must set the array to zero.</entry> | ||
| 156 | </row> | ||
| 157 | </tbody> | ||
| 158 | </tgroup> | ||
| 159 | </table> | ||
| 160 | |||
| 161 | <table pgwide="1" frame="none" id="enc-idx-flags"> | ||
| 162 | <title>Index Entry Flags</title> | ||
| 163 | <tgroup cols="3"> | ||
| 164 | &cs-def; | ||
| 165 | <tbody valign="top"> | ||
| 166 | <row> | ||
| 167 | <entry><constant>V4L2_ENC_IDX_FRAME_I</constant></entry> | ||
| 168 | <entry>0x00</entry> | ||
| 169 | <entry>This is an Intra-coded picture.</entry> | ||
| 170 | </row> | ||
| 171 | <row> | ||
| 172 | <entry><constant>V4L2_ENC_IDX_FRAME_P</constant></entry> | ||
| 173 | <entry>0x01</entry> | ||
| 174 | <entry>This is a Predictive-coded picture.</entry> | ||
| 175 | </row> | ||
| 176 | <row> | ||
| 177 | <entry><constant>V4L2_ENC_IDX_FRAME_B</constant></entry> | ||
| 178 | <entry>0x02</entry> | ||
| 179 | <entry>This is a Bidirectionally predictive-coded | ||
| 180 | picture.</entry> | ||
| 181 | </row> | ||
| 182 | <row> | ||
| 183 | <entry><constant>V4L2_ENC_IDX_FRAME_MASK</constant></entry> | ||
| 184 | <entry>0x0F</entry> | ||
| 185 | <entry><wordasword>AND</wordasword> the flags field with | ||
| 186 | this mask to obtain the picture coding type.</entry> | ||
| 187 | </row> | ||
| 188 | </tbody> | ||
| 189 | </tgroup> | ||
| 190 | </table> | ||
| 191 | </refsect1> | ||
| 192 | |||
| 193 | <refsect1> | ||
| 194 | &return-value; | ||
| 195 | |||
| 196 | <variablelist> | ||
| 197 | <varlistentry> | ||
| 198 | <term><errorcode>EINVAL</errorcode></term> | ||
| 199 | <listitem> | ||
| 200 | <para>The driver does not support this ioctl.</para> | ||
| 201 | </listitem> | ||
| 202 | </varlistentry> | ||
| 203 | </variablelist> | ||
| 204 | </refsect1> | ||
| 205 | </refentry> | ||
| 206 | |||
| 207 | <!-- | ||
| 208 | Local Variables: | ||
| 209 | mode: sgml | ||
| 210 | sgml-parent-document: "v4l2.sgml" | ||
| 211 | indent-tabs-mode: nil | ||
| 212 | End: | ||
| 213 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml new file mode 100644 index 000000000000..3aa7f8f9ff0c --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml | |||
| @@ -0,0 +1,307 @@ | |||
| 1 | <refentry id="vidioc-g-ext-ctrls"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, | ||
| 4 | VIDIOC_TRY_EXT_CTRLS</refentrytitle> | ||
| 5 | &manvol; | ||
| 6 | </refmeta> | ||
| 7 | |||
| 8 | <refnamediv> | ||
| 9 | <refname>VIDIOC_G_EXT_CTRLS</refname> | ||
| 10 | <refname>VIDIOC_S_EXT_CTRLS</refname> | ||
| 11 | <refname>VIDIOC_TRY_EXT_CTRLS</refname> | ||
| 12 | <refpurpose>Get or set the value of several controls, try control | ||
| 13 | values</refpurpose> | ||
| 14 | </refnamediv> | ||
| 15 | |||
| 16 | <refsynopsisdiv> | ||
| 17 | <funcsynopsis> | ||
| 18 | <funcprototype> | ||
| 19 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 20 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 21 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 22 | <paramdef>struct v4l2_ext_controls | ||
| 23 | *<parameter>argp</parameter></paramdef> | ||
| 24 | </funcprototype> | ||
| 25 | </funcsynopsis> | ||
| 26 | </refsynopsisdiv> | ||
| 27 | |||
| 28 | <refsect1> | ||
| 29 | <title>Arguments</title> | ||
| 30 | |||
| 31 | <variablelist> | ||
| 32 | <varlistentry> | ||
| 33 | <term><parameter>fd</parameter></term> | ||
| 34 | <listitem> | ||
| 35 | <para>&fd;</para> | ||
| 36 | </listitem> | ||
| 37 | </varlistentry> | ||
| 38 | <varlistentry> | ||
| 39 | <term><parameter>request</parameter></term> | ||
| 40 | <listitem> | ||
| 41 | <para>VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, | ||
| 42 | VIDIOC_TRY_EXT_CTRLS</para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | <varlistentry> | ||
| 46 | <term><parameter>argp</parameter></term> | ||
| 47 | <listitem> | ||
| 48 | <para></para> | ||
| 49 | </listitem> | ||
| 50 | </varlistentry> | ||
| 51 | </variablelist> | ||
| 52 | </refsect1> | ||
| 53 | |||
| 54 | <refsect1> | ||
| 55 | <title>Description</title> | ||
| 56 | |||
| 57 | <para>These ioctls allow the caller to get or set multiple | ||
| 58 | controls atomically. Control IDs are grouped into control classes (see | ||
| 59 | <xref linkend="ctrl-class" />) and all controls in the control array | ||
| 60 | must belong to the same control class.</para> | ||
| 61 | |||
| 62 | <para>Applications must always fill in the | ||
| 63 | <structfield>count</structfield>, | ||
| 64 | <structfield>ctrl_class</structfield>, | ||
| 65 | <structfield>controls</structfield> and | ||
| 66 | <structfield>reserved</structfield> fields of &v4l2-ext-controls;, and | ||
| 67 | initialize the &v4l2-ext-control; array pointed to by the | ||
| 68 | <structfield>controls</structfield> fields.</para> | ||
| 69 | |||
| 70 | <para>To get the current value of a set of controls applications | ||
| 71 | initialize the <structfield>id</structfield>, | ||
| 72 | <structfield>size</structfield> and <structfield>reserved2</structfield> fields | ||
| 73 | of each &v4l2-ext-control; and call the | ||
| 74 | <constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls | ||
| 75 | must also set the <structfield>string</structfield> field.</para> | ||
| 76 | |||
| 77 | <para>If the <structfield>size</structfield> is too small to | ||
| 78 | receive the control result (only relevant for pointer-type controls | ||
| 79 | like strings), then the driver will set <structfield>size</structfield> | ||
| 80 | to a valid value and return an &ENOSPC;. You should re-allocate the | ||
| 81 | string memory to this new size and try again. It is possible that the | ||
| 82 | same issue occurs again if the string has grown in the meantime. It is | ||
| 83 | recommended to call &VIDIOC-QUERYCTRL; first and use | ||
| 84 | <structfield>maximum</structfield>+1 as the new <structfield>size</structfield> | ||
| 85 | value. It is guaranteed that that is sufficient memory. | ||
| 86 | </para> | ||
| 87 | |||
| 88 | <para>To change the value of a set of controls applications | ||
| 89 | initialize the <structfield>id</structfield>, <structfield>size</structfield>, | ||
| 90 | <structfield>reserved2</structfield> and | ||
| 91 | <structfield>value/string</structfield> fields of each &v4l2-ext-control; and | ||
| 92 | call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls | ||
| 93 | will only be set if <emphasis>all</emphasis> control values are | ||
| 94 | valid.</para> | ||
| 95 | |||
| 96 | <para>To check if a set of controls have correct values applications | ||
| 97 | initialize the <structfield>id</structfield>, <structfield>size</structfield>, | ||
| 98 | <structfield>reserved2</structfield> and | ||
| 99 | <structfield>value/string</structfield> fields of each &v4l2-ext-control; and | ||
| 100 | call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to | ||
| 101 | the driver whether wrong values are automatically adjusted to a valid | ||
| 102 | value or if an error is returned.</para> | ||
| 103 | |||
| 104 | <para>When the <structfield>id</structfield> or | ||
| 105 | <structfield>ctrl_class</structfield> is invalid drivers return an | ||
| 106 | &EINVAL;. When the value is out of bounds drivers can choose to take | ||
| 107 | the closest valid value or return an &ERANGE;, whatever seems more | ||
| 108 | appropriate. In the first case the new value is set in | ||
| 109 | &v4l2-ext-control;.</para> | ||
| 110 | |||
| 111 | <para>The driver will only set/get these controls if all control | ||
| 112 | values are correct. This prevents the situation where only some of the | ||
| 113 | controls were set/get. Only low-level errors (⪚ a failed i2c | ||
| 114 | command) can still cause this situation.</para> | ||
| 115 | |||
| 116 | <table pgwide="1" frame="none" id="v4l2-ext-control"> | ||
| 117 | <title>struct <structname>v4l2_ext_control</structname></title> | ||
| 118 | <tgroup cols="4"> | ||
| 119 | &cs-ustr; | ||
| 120 | <tbody valign="top"> | ||
| 121 | <row> | ||
| 122 | <entry>__u32</entry> | ||
| 123 | <entry><structfield>id</structfield></entry> | ||
| 124 | <entry></entry> | ||
| 125 | <entry>Identifies the control, set by the | ||
| 126 | application.</entry> | ||
| 127 | </row> | ||
| 128 | <row> | ||
| 129 | <entry>__u32</entry> | ||
| 130 | <entry><structfield>size</structfield></entry> | ||
| 131 | <entry></entry> | ||
| 132 | <entry>The total size in bytes of the payload of this | ||
| 133 | control. This is normally 0, but for pointer controls this should be | ||
| 134 | set to the size of the memory containing the payload, or that will | ||
| 135 | receive the payload. If <constant>VIDIOC_G_EXT_CTRLS</constant> finds | ||
| 136 | that this value is less than is required to store | ||
| 137 | the payload result, then it is set to a value large enough to store the | ||
| 138 | payload result and ENOSPC is returned. Note that for string controls | ||
| 139 | this <structfield>size</structfield> field should not be confused with the length of the string. | ||
| 140 | This field refers to the size of the memory that contains the string. | ||
| 141 | The actual <emphasis>length</emphasis> of the string may well be much smaller. | ||
| 142 | </entry> | ||
| 143 | </row> | ||
| 144 | <row> | ||
| 145 | <entry>__u32</entry> | ||
| 146 | <entry><structfield>reserved2</structfield>[1]</entry> | ||
| 147 | <entry></entry> | ||
| 148 | <entry>Reserved for future extensions. Drivers and | ||
| 149 | applications must set the array to zero.</entry> | ||
| 150 | </row> | ||
| 151 | <row> | ||
| 152 | <entry>union</entry> | ||
| 153 | <entry>(anonymous)</entry> | ||
| 154 | </row> | ||
| 155 | <row> | ||
| 156 | <entry></entry> | ||
| 157 | <entry>__s32</entry> | ||
| 158 | <entry><structfield>value</structfield></entry> | ||
| 159 | <entry>New value or current value.</entry> | ||
| 160 | </row> | ||
| 161 | <row> | ||
| 162 | <entry></entry> | ||
| 163 | <entry>__s64</entry> | ||
| 164 | <entry><structfield>value64</structfield></entry> | ||
| 165 | <entry>New value or current value.</entry> | ||
| 166 | </row> | ||
| 167 | <row> | ||
| 168 | <entry></entry> | ||
| 169 | <entry>char *</entry> | ||
| 170 | <entry><structfield>string</structfield></entry> | ||
| 171 | <entry>A pointer to a string.</entry> | ||
| 172 | </row> | ||
| 173 | </tbody> | ||
| 174 | </tgroup> | ||
| 175 | </table> | ||
| 176 | |||
| 177 | <table pgwide="1" frame="none" id="v4l2-ext-controls"> | ||
| 178 | <title>struct <structname>v4l2_ext_controls</structname></title> | ||
| 179 | <tgroup cols="3"> | ||
| 180 | &cs-str; | ||
| 181 | <tbody valign="top"> | ||
| 182 | <row> | ||
| 183 | <entry>__u32</entry> | ||
| 184 | <entry><structfield>ctrl_class</structfield></entry> | ||
| 185 | <entry>The control class to which all controls belong, see | ||
| 186 | <xref linkend="ctrl-class" />.</entry> | ||
| 187 | </row> | ||
| 188 | <row> | ||
| 189 | <entry>__u32</entry> | ||
| 190 | <entry><structfield>count</structfield></entry> | ||
| 191 | <entry>The number of controls in the controls array. May | ||
| 192 | also be zero.</entry> | ||
| 193 | </row> | ||
| 194 | <row> | ||
| 195 | <entry>__u32</entry> | ||
| 196 | <entry><structfield>error_idx</structfield></entry> | ||
| 197 | <entry>Set by the driver in case of an error. It is the | ||
| 198 | index of the control causing the error or equal to 'count' when the | ||
| 199 | error is not associated with a particular control. Undefined when the | ||
| 200 | ioctl returns 0 (success).</entry> | ||
| 201 | </row> | ||
| 202 | <row> | ||
| 203 | <entry>__u32</entry> | ||
| 204 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 205 | <entry>Reserved for future extensions. Drivers and | ||
| 206 | applications must set the array to zero.</entry> | ||
| 207 | </row> | ||
| 208 | <row> | ||
| 209 | <entry>&v4l2-ext-control; *</entry> | ||
| 210 | <entry><structfield>controls</structfield></entry> | ||
| 211 | <entry>Pointer to an array of | ||
| 212 | <structfield>count</structfield> v4l2_ext_control structures. Ignored | ||
| 213 | if <structfield>count</structfield> equals zero.</entry> | ||
| 214 | </row> | ||
| 215 | </tbody> | ||
| 216 | </tgroup> | ||
| 217 | </table> | ||
| 218 | |||
| 219 | <table pgwide="1" frame="none" id="ctrl-class"> | ||
| 220 | <title>Control classes</title> | ||
| 221 | <tgroup cols="3"> | ||
| 222 | &cs-def; | ||
| 223 | <tbody valign="top"> | ||
| 224 | <row> | ||
| 225 | <entry><constant>V4L2_CTRL_CLASS_USER</constant></entry> | ||
| 226 | <entry>0x980000</entry> | ||
| 227 | <entry>The class containing user controls. These controls | ||
| 228 | are described in <xref linkend="control" />. All controls that can be set | ||
| 229 | using the &VIDIOC-S-CTRL; and &VIDIOC-G-CTRL; ioctl belong to this | ||
| 230 | class.</entry> | ||
| 231 | </row> | ||
| 232 | <row> | ||
| 233 | <entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry> | ||
| 234 | <entry>0x990000</entry> | ||
| 235 | <entry>The class containing MPEG compression controls. | ||
| 236 | These controls are described in <xref | ||
| 237 | linkend="mpeg-controls" />.</entry> | ||
| 238 | </row> | ||
| 239 | <row> | ||
| 240 | <entry><constant>V4L2_CTRL_CLASS_CAMERA</constant></entry> | ||
| 241 | <entry>0x9a0000</entry> | ||
| 242 | <entry>The class containing camera controls. | ||
| 243 | These controls are described in <xref | ||
| 244 | linkend="camera-controls" />.</entry> | ||
| 245 | </row> | ||
| 246 | <row> | ||
| 247 | <entry><constant>V4L2_CTRL_CLASS_FM_TX</constant></entry> | ||
| 248 | <entry>0x9b0000</entry> | ||
| 249 | <entry>The class containing FM Transmitter (FM TX) controls. | ||
| 250 | These controls are described in <xref | ||
| 251 | linkend="fm-tx-controls" />.</entry> | ||
| 252 | </row> | ||
| 253 | </tbody> | ||
| 254 | </tgroup> | ||
| 255 | </table> | ||
| 256 | |||
| 257 | </refsect1> | ||
| 258 | |||
| 259 | <refsect1> | ||
| 260 | &return-value; | ||
| 261 | |||
| 262 | <variablelist> | ||
| 263 | <varlistentry> | ||
| 264 | <term><errorcode>EINVAL</errorcode></term> | ||
| 265 | <listitem> | ||
| 266 | <para>The &v4l2-ext-control; <structfield>id</structfield> | ||
| 267 | is invalid or the &v4l2-ext-controls; | ||
| 268 | <structfield>ctrl_class</structfield> is invalid. This error code is | ||
| 269 | also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and | ||
| 270 | <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctls if two or more | ||
| 271 | control values are in conflict.</para> | ||
| 272 | </listitem> | ||
| 273 | </varlistentry> | ||
| 274 | <varlistentry> | ||
| 275 | <term><errorcode>ERANGE</errorcode></term> | ||
| 276 | <listitem> | ||
| 277 | <para>The &v4l2-ext-control; <structfield>value</structfield> | ||
| 278 | is out of bounds.</para> | ||
| 279 | </listitem> | ||
| 280 | </varlistentry> | ||
| 281 | <varlistentry> | ||
| 282 | <term><errorcode>EBUSY</errorcode></term> | ||
| 283 | <listitem> | ||
| 284 | <para>The control is temporarily not changeable, possibly | ||
| 285 | because another applications took over control of the device function | ||
| 286 | this control belongs to.</para> | ||
| 287 | </listitem> | ||
| 288 | </varlistentry> | ||
| 289 | <varlistentry> | ||
| 290 | <term><errorcode>ENOSPC</errorcode></term> | ||
| 291 | <listitem> | ||
| 292 | <para>The space reserved for the control's payload is insufficient. | ||
| 293 | The field <structfield>size</structfield> is set to a value that is enough | ||
| 294 | to store the payload and this error code is returned.</para> | ||
| 295 | </listitem> | ||
| 296 | </varlistentry> | ||
| 297 | </variablelist> | ||
| 298 | </refsect1> | ||
| 299 | </refentry> | ||
| 300 | |||
| 301 | <!-- | ||
| 302 | Local Variables: | ||
| 303 | mode: sgml | ||
| 304 | sgml-parent-document: "v4l2.sgml" | ||
| 305 | indent-tabs-mode: nil | ||
| 306 | End: | ||
| 307 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/v4l/vidioc-g-fbuf.xml new file mode 100644 index 000000000000..f7017062656e --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-fbuf.xml | |||
| @@ -0,0 +1,456 @@ | |||
| 1 | <refentry id="vidioc-g-fbuf"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_FBUF</refname> | ||
| 9 | <refname>VIDIOC_S_FBUF</refname> | ||
| 10 | <refpurpose>Get or set frame buffer overlay parameters</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_framebuffer *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>const struct v4l2_framebuffer *<parameter>argp</parameter></paramdef> | ||
| 28 | </funcprototype> | ||
| 29 | </funcsynopsis> | ||
| 30 | </refsynopsisdiv> | ||
| 31 | |||
| 32 | <refsect1> | ||
| 33 | <title>Arguments</title> | ||
| 34 | |||
| 35 | <variablelist> | ||
| 36 | <varlistentry> | ||
| 37 | <term><parameter>fd</parameter></term> | ||
| 38 | <listitem> | ||
| 39 | <para>&fd;</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>request</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>VIDIOC_G_FBUF, VIDIOC_S_FBUF</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | <varlistentry> | ||
| 49 | <term><parameter>argp</parameter></term> | ||
| 50 | <listitem> | ||
| 51 | <para></para> | ||
| 52 | </listitem> | ||
| 53 | </varlistentry> | ||
| 54 | </variablelist> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Description</title> | ||
| 59 | |||
| 60 | <para>Applications can use the <constant>VIDIOC_G_FBUF</constant> and | ||
| 61 | <constant>VIDIOC_S_FBUF</constant> ioctl to get and set the | ||
| 62 | framebuffer parameters for a <link linkend="overlay">Video | ||
| 63 | Overlay</link> or <link linkend="osd">Video Output Overlay</link> | ||
| 64 | (OSD). The type of overlay is implied by the device type (capture or | ||
| 65 | output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl. | ||
| 66 | One <filename>/dev/videoN</filename> device must not support both | ||
| 67 | kinds of overlay.</para> | ||
| 68 | |||
| 69 | <para>The V4L2 API distinguishes destructive and non-destructive | ||
| 70 | overlays. A destructive overlay copies captured video images into the | ||
| 71 | video memory of a graphics card. A non-destructive overlay blends | ||
| 72 | video images into a VGA signal or graphics into a video signal. | ||
| 73 | <wordasword>Video Output Overlays</wordasword> are always | ||
| 74 | non-destructive.</para> | ||
| 75 | |||
| 76 | <para>To get the current parameters applications call the | ||
| 77 | <constant>VIDIOC_G_FBUF</constant> ioctl with a pointer to a | ||
| 78 | <structname>v4l2_framebuffer</structname> structure. The driver fills | ||
| 79 | all fields of the structure or returns an &EINVAL; when overlays are | ||
| 80 | not supported.</para> | ||
| 81 | |||
| 82 | <para>To set the parameters for a <wordasword>Video Output | ||
| 83 | Overlay</wordasword>, applications must initialize the | ||
| 84 | <structfield>flags</structfield> field of a struct | ||
| 85 | <structname>v4l2_framebuffer</structname>. Since the framebuffer is | ||
| 86 | implemented on the TV card all other parameters are determined by the | ||
| 87 | driver. When an application calls <constant>VIDIOC_S_FBUF</constant> | ||
| 88 | with a pointer to this structure, the driver prepares for the overlay | ||
| 89 | and returns the framebuffer parameters as | ||
| 90 | <constant>VIDIOC_G_FBUF</constant> does, or it returns an error | ||
| 91 | code.</para> | ||
| 92 | |||
| 93 | <para>To set the parameters for a <wordasword>non-destructive | ||
| 94 | Video Overlay</wordasword>, applications must initialize the | ||
| 95 | <structfield>flags</structfield> field, the | ||
| 96 | <structfield>fmt</structfield> substructure, and call | ||
| 97 | <constant>VIDIOC_S_FBUF</constant>. Again the driver prepares for the | ||
| 98 | overlay and returns the framebuffer parameters as | ||
| 99 | <constant>VIDIOC_G_FBUF</constant> does, or it returns an error | ||
| 100 | code.</para> | ||
| 101 | |||
| 102 | <para>For a <wordasword>destructive Video Overlay</wordasword> | ||
| 103 | applications must additionally provide a | ||
| 104 | <structfield>base</structfield> address. Setting up a DMA to a | ||
| 105 | random memory location can jeopardize the system security, its | ||
| 106 | stability or even damage the hardware, therefore only the superuser | ||
| 107 | can set the parameters for a destructive video overlay.</para> | ||
| 108 | |||
| 109 | <!-- NB v4l2_pix_format is also specified in pixfmt.sgml.--> | ||
| 110 | |||
| 111 | <table pgwide="1" frame="none" id="v4l2-framebuffer"> | ||
| 112 | <title>struct <structname>v4l2_framebuffer</structname></title> | ||
| 113 | <tgroup cols="4"> | ||
| 114 | &cs-ustr; | ||
| 115 | <tbody valign="top"> | ||
| 116 | <row> | ||
| 117 | <entry>__u32</entry> | ||
| 118 | <entry><structfield>capability</structfield></entry> | ||
| 119 | <entry></entry> | ||
| 120 | <entry>Overlay capability flags set by the driver, see | ||
| 121 | <xref linkend="framebuffer-cap" />.</entry> | ||
| 122 | </row> | ||
| 123 | <row> | ||
| 124 | <entry>__u32</entry> | ||
| 125 | <entry><structfield>flags</structfield></entry> | ||
| 126 | <entry></entry> | ||
| 127 | <entry>Overlay control flags set by application and | ||
| 128 | driver, see <xref linkend="framebuffer-flags" /></entry> | ||
| 129 | </row> | ||
| 130 | <row> | ||
| 131 | <entry>void *</entry> | ||
| 132 | <entry><structfield>base</structfield></entry> | ||
| 133 | <entry></entry> | ||
| 134 | <entry>Physical base address of the framebuffer, | ||
| 135 | that is the address of the pixel in the top left corner of the | ||
| 136 | framebuffer.<footnote><para>A physical base address may not suit all | ||
| 137 | platforms. GK notes in theory we should pass something like PCI device | ||
| 138 | + memory region + offset instead. If you encounter problems please | ||
| 139 | discuss on the linux-media mailing list: &v4l-ml;.</para></footnote></entry> | ||
| 140 | </row> | ||
| 141 | <row> | ||
| 142 | <entry></entry> | ||
| 143 | <entry></entry> | ||
| 144 | <entry></entry> | ||
| 145 | <entry>This field is irrelevant to | ||
| 146 | <wordasword>non-destructive Video Overlays</wordasword>. For | ||
| 147 | <wordasword>destructive Video Overlays</wordasword> applications must | ||
| 148 | provide a base address. The driver may accept only base addresses | ||
| 149 | which are a multiple of two, four or eight bytes. For | ||
| 150 | <wordasword>Video Output Overlays</wordasword> the driver must return | ||
| 151 | a valid base address, so applications can find the corresponding Linux | ||
| 152 | framebuffer device (see <xref linkend="osd" />).</entry> | ||
| 153 | </row> | ||
| 154 | <row> | ||
| 155 | <entry>&v4l2-pix-format;</entry> | ||
| 156 | <entry><structfield>fmt</structfield></entry> | ||
| 157 | <entry></entry> | ||
| 158 | <entry>Layout of the frame buffer. The | ||
| 159 | <structname>v4l2_pix_format</structname> structure is defined in <xref | ||
| 160 | linkend="pixfmt" />, for clarification the fields and acceptable values | ||
| 161 | are listed below:</entry> | ||
| 162 | </row> | ||
| 163 | <row> | ||
| 164 | <entry></entry> | ||
| 165 | <entry>__u32</entry> | ||
| 166 | <entry><structfield>width</structfield></entry> | ||
| 167 | <entry>Width of the frame buffer in pixels.</entry> | ||
| 168 | </row> | ||
| 169 | <row> | ||
| 170 | <entry></entry> | ||
| 171 | <entry>__u32</entry> | ||
| 172 | <entry><structfield>height</structfield></entry> | ||
| 173 | <entry>Height of the frame buffer in pixels.</entry> | ||
| 174 | </row> | ||
| 175 | <row> | ||
| 176 | <entry></entry> | ||
| 177 | <entry>__u32</entry> | ||
| 178 | <entry><structfield>pixelformat</structfield></entry> | ||
| 179 | <entry>The pixel format of the | ||
| 180 | framebuffer.</entry> | ||
| 181 | </row> | ||
| 182 | <row> | ||
| 183 | <entry></entry> | ||
| 184 | <entry></entry> | ||
| 185 | <entry></entry> | ||
| 186 | <entry>For <wordasword>non-destructive Video | ||
| 187 | Overlays</wordasword> this field only defines a format for the | ||
| 188 | &v4l2-window; <structfield>chromakey</structfield> field.</entry> | ||
| 189 | </row> | ||
| 190 | <row> | ||
| 191 | <entry></entry> | ||
| 192 | <entry></entry> | ||
| 193 | <entry></entry> | ||
| 194 | <entry>For <wordasword>destructive Video | ||
| 195 | Overlays</wordasword> applications must initialize this field. For | ||
| 196 | <wordasword>Video Output Overlays</wordasword> the driver must return | ||
| 197 | a valid format.</entry> | ||
| 198 | </row> | ||
| 199 | <row> | ||
| 200 | <entry></entry> | ||
| 201 | <entry></entry> | ||
| 202 | <entry></entry> | ||
| 203 | <entry>Usually this is an RGB format (for example | ||
| 204 | <link linkend="V4L2-PIX-FMT-RGB565"><constant>V4L2_PIX_FMT_RGB565</constant></link>) | ||
| 205 | but YUV formats (only packed YUV formats when chroma keying is used, | ||
| 206 | not including <constant>V4L2_PIX_FMT_YUYV</constant> and | ||
| 207 | <constant>V4L2_PIX_FMT_UYVY</constant>) and the | ||
| 208 | <constant>V4L2_PIX_FMT_PAL8</constant> format are also permitted. The | ||
| 209 | behavior of the driver when an application requests a compressed | ||
| 210 | format is undefined. See <xref linkend="pixfmt" /> for information on | ||
| 211 | pixel formats.</entry> | ||
| 212 | </row> | ||
| 213 | <row> | ||
| 214 | <entry></entry> | ||
| 215 | <entry>&v4l2-field;</entry> | ||
| 216 | <entry><structfield>field</structfield></entry> | ||
| 217 | <entry>Drivers and applications shall ignore this field. | ||
| 218 | If applicable, the field order is selected with the &VIDIOC-S-FMT; | ||
| 219 | ioctl, using the <structfield>field</structfield> field of | ||
| 220 | &v4l2-window;.</entry> | ||
| 221 | </row> | ||
| 222 | <row> | ||
| 223 | <entry></entry> | ||
| 224 | <entry>__u32</entry> | ||
| 225 | <entry><structfield>bytesperline</structfield></entry> | ||
| 226 | <entry>Distance in bytes between the leftmost pixels in | ||
| 227 | two adjacent lines.</entry> | ||
| 228 | </row> | ||
| 229 | <row> | ||
| 230 | <entry spanname="hspan"><para>This field is irrelevant to | ||
| 231 | <wordasword>non-destructive Video | ||
| 232 | Overlays</wordasword>.</para><para>For <wordasword>destructive Video | ||
| 233 | Overlays</wordasword> both applications and drivers can set this field | ||
| 234 | to request padding bytes at the end of each line. Drivers however may | ||
| 235 | ignore the requested value, returning <structfield>width</structfield> | ||
| 236 | times bytes-per-pixel or a larger value required by the hardware. That | ||
| 237 | implies applications can just set this field to zero to get a | ||
| 238 | reasonable default.</para><para>For <wordasword>Video Output | ||
| 239 | Overlays</wordasword> the driver must return a valid | ||
| 240 | value.</para><para>Video hardware may access padding bytes, therefore | ||
| 241 | they must reside in accessible memory. Consider for example the case | ||
| 242 | where padding bytes after the last line of an image cross a system | ||
| 243 | page boundary. Capture devices may write padding bytes, the value is | ||
| 244 | undefined. Output devices ignore the contents of padding | ||
| 245 | bytes.</para><para>When the image format is planar the | ||
| 246 | <structfield>bytesperline</structfield> value applies to the largest | ||
| 247 | plane and is divided by the same factor as the | ||
| 248 | <structfield>width</structfield> field for any smaller planes. For | ||
| 249 | example the Cb and Cr planes of a YUV 4:2:0 image have half as many | ||
| 250 | padding bytes following each line as the Y plane. To avoid ambiguities | ||
| 251 | drivers must return a <structfield>bytesperline</structfield> value | ||
| 252 | rounded up to a multiple of the scale factor.</para></entry> | ||
| 253 | </row> | ||
| 254 | <row> | ||
| 255 | <entry></entry> | ||
| 256 | <entry>__u32</entry> | ||
| 257 | <entry><structfield>sizeimage</structfield></entry> | ||
| 258 | <entry><para>This field is irrelevant to | ||
| 259 | <wordasword>non-destructive Video Overlays</wordasword>. For | ||
| 260 | <wordasword>destructive Video Overlays</wordasword> applications must | ||
| 261 | initialize this field. For <wordasword>Video Output | ||
| 262 | Overlays</wordasword> the driver must return a valid | ||
| 263 | format.</para><para>Together with <structfield>base</structfield> it | ||
| 264 | defines the framebuffer memory accessible by the | ||
| 265 | driver.</para></entry> | ||
| 266 | </row> | ||
| 267 | <row> | ||
| 268 | <entry></entry> | ||
| 269 | <entry>&v4l2-colorspace;</entry> | ||
| 270 | <entry><structfield>colorspace</structfield></entry> | ||
| 271 | <entry>This information supplements the | ||
| 272 | <structfield>pixelformat</structfield> and must be set by the driver, | ||
| 273 | see <xref linkend="colorspaces" />.</entry> | ||
| 274 | </row> | ||
| 275 | <row> | ||
| 276 | <entry></entry> | ||
| 277 | <entry>__u32</entry> | ||
| 278 | <entry><structfield>priv</structfield></entry> | ||
| 279 | <entry>Reserved for additional information about custom | ||
| 280 | (driver defined) formats. When not used drivers and applications must | ||
| 281 | set this field to zero.</entry> | ||
| 282 | </row> | ||
| 283 | </tbody> | ||
| 284 | </tgroup> | ||
| 285 | </table> | ||
| 286 | |||
| 287 | <table pgwide="1" frame="none" id="framebuffer-cap"> | ||
| 288 | <title>Frame Buffer Capability Flags</title> | ||
| 289 | <tgroup cols="3"> | ||
| 290 | &cs-def; | ||
| 291 | <tbody valign="top"> | ||
| 292 | <row> | ||
| 293 | <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant></entry> | ||
| 294 | <entry>0x0001</entry> | ||
| 295 | <entry>The device is capable of non-destructive overlays. | ||
| 296 | When the driver clears this flag, only destructive overlays are | ||
| 297 | supported. There are no drivers yet which support both destructive and | ||
| 298 | non-destructive overlays.</entry> | ||
| 299 | </row> | ||
| 300 | <row> | ||
| 301 | <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry> | ||
| 302 | <entry>0x0002</entry> | ||
| 303 | <entry>The device supports clipping by chroma-keying the | ||
| 304 | images. That is, image pixels replace pixels in the VGA or video | ||
| 305 | signal only where the latter assume a certain color. Chroma-keying | ||
| 306 | makes no sense for destructive overlays.</entry> | ||
| 307 | </row> | ||
| 308 | <row> | ||
| 309 | <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant></entry> | ||
| 310 | <entry>0x0004</entry> | ||
| 311 | <entry>The device supports clipping using a list of clip | ||
| 312 | rectangles.</entry> | ||
| 313 | </row> | ||
| 314 | <row> | ||
| 315 | <entry><constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant></entry> | ||
| 316 | <entry>0x0008</entry> | ||
| 317 | <entry>The device supports clipping using a bit mask.</entry> | ||
| 318 | </row> | ||
| 319 | <row> | ||
| 320 | <entry><constant>V4L2_FBUF_CAP_LOCAL_ALPHA</constant></entry> | ||
| 321 | <entry>0x0010</entry> | ||
| 322 | <entry>The device supports clipping/blending using the | ||
| 323 | alpha channel of the framebuffer or VGA signal. Alpha blending makes | ||
| 324 | no sense for destructive overlays.</entry> | ||
| 325 | </row> | ||
| 326 | <row> | ||
| 327 | <entry><constant>V4L2_FBUF_CAP_GLOBAL_ALPHA</constant></entry> | ||
| 328 | <entry>0x0020</entry> | ||
| 329 | <entry>The device supports alpha blending using a global | ||
| 330 | alpha value. Alpha blending makes no sense for destructive overlays.</entry> | ||
| 331 | </row> | ||
| 332 | <row> | ||
| 333 | <entry><constant>V4L2_FBUF_CAP_LOCAL_INV_ALPHA</constant></entry> | ||
| 334 | <entry>0x0040</entry> | ||
| 335 | <entry>The device supports clipping/blending using the | ||
| 336 | inverted alpha channel of the framebuffer or VGA signal. Alpha | ||
| 337 | blending makes no sense for destructive overlays.</entry> | ||
| 338 | </row> | ||
| 339 | </tbody> | ||
| 340 | </tgroup> | ||
| 341 | </table> | ||
| 342 | |||
| 343 | <table pgwide="1" frame="none" id="framebuffer-flags"> | ||
| 344 | <title>Frame Buffer Flags</title> | ||
| 345 | <tgroup cols="3"> | ||
| 346 | &cs-def; | ||
| 347 | <tbody valign="top"> | ||
| 348 | <row> | ||
| 349 | <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry> | ||
| 350 | <entry>0x0001</entry> | ||
| 351 | <entry>The framebuffer is the primary graphics surface. | ||
| 352 | In other words, the overlay is destructive. [?]</entry> | ||
| 353 | </row> | ||
| 354 | <row> | ||
| 355 | <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry> | ||
| 356 | <entry>0x0002</entry> | ||
| 357 | <entry>The frame buffer is an overlay surface the same | ||
| 358 | size as the capture. [?]</entry> | ||
| 359 | </row> | ||
| 360 | <row> | ||
| 361 | <entry spanname="hspan">The purpose of | ||
| 362 | <constant>V4L2_FBUF_FLAG_PRIMARY</constant> and | ||
| 363 | <constant>V4L2_FBUF_FLAG_OVERLAY</constant> was never quite clear. | ||
| 364 | Most drivers seem to ignore these flags. For compatibility with the | ||
| 365 | <wordasword>bttv</wordasword> driver applications should set the | ||
| 366 | <constant>V4L2_FBUF_FLAG_OVERLAY</constant> flag.</entry> | ||
| 367 | </row> | ||
| 368 | <row> | ||
| 369 | <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry> | ||
| 370 | <entry>0x0004</entry> | ||
| 371 | <entry>Use chroma-keying. The chroma-key color is | ||
| 372 | determined by the <structfield>chromakey</structfield> field of | ||
| 373 | &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref | ||
| 374 | linkend="overlay" /> | ||
| 375 | and | ||
| 376 | <xref linkend="osd" />.</entry> | ||
| 377 | </row> | ||
| 378 | <row> | ||
| 379 | <entry spanname="hspan">There are no flags to enable | ||
| 380 | clipping using a list of clip rectangles or a bitmap. These methods | ||
| 381 | are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref | ||
| 382 | linkend="overlay" /> and <xref linkend="osd" />.</entry> | ||
| 383 | </row> | ||
| 384 | <row> | ||
| 385 | <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry> | ||
| 386 | <entry>0x0008</entry> | ||
| 387 | <entry>Use the alpha channel of the framebuffer to clip or | ||
| 388 | blend framebuffer pixels with video images. The blend | ||
| 389 | function is: output = framebuffer pixel * alpha + video pixel * (1 - | ||
| 390 | alpha). The actual alpha depth depends on the framebuffer pixel | ||
| 391 | format.</entry> | ||
| 392 | </row> | ||
| 393 | <row> | ||
| 394 | <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry> | ||
| 395 | <entry>0x0010</entry> | ||
| 396 | <entry>Use a global alpha value to blend the framebuffer | ||
| 397 | with video images. The blend function is: output = (framebuffer pixel | ||
| 398 | * alpha + video pixel * (255 - alpha)) / 255. The alpha value is | ||
| 399 | determined by the <structfield>global_alpha</structfield> field of | ||
| 400 | &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref | ||
| 401 | linkend="overlay" /> | ||
| 402 | and <xref linkend="osd" />.</entry> | ||
| 403 | </row> | ||
| 404 | <row> | ||
| 405 | <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry> | ||
| 406 | <entry>0x0020</entry> | ||
| 407 | <entry>Like | ||
| 408 | <constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, use the alpha channel | ||
| 409 | of the framebuffer to clip or blend framebuffer pixels with video | ||
| 410 | images, but with an inverted alpha value. The blend function is: | ||
| 411 | output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The | ||
| 412 | actual alpha depth depends on the framebuffer pixel format.</entry> | ||
| 413 | </row> | ||
| 414 | </tbody> | ||
| 415 | </tgroup> | ||
| 416 | </table> | ||
| 417 | </refsect1> | ||
| 418 | |||
| 419 | <refsect1> | ||
| 420 | &return-value; | ||
| 421 | |||
| 422 | <variablelist> | ||
| 423 | <varlistentry> | ||
| 424 | <term><errorcode>EPERM</errorcode></term> | ||
| 425 | <listitem> | ||
| 426 | <para><constant>VIDIOC_S_FBUF</constant> can only be called | ||
| 427 | by a privileged user to negotiate the parameters for a destructive | ||
| 428 | overlay.</para> | ||
| 429 | </listitem> | ||
| 430 | </varlistentry> | ||
| 431 | <varlistentry> | ||
| 432 | <term><errorcode>EBUSY</errorcode></term> | ||
| 433 | <listitem> | ||
| 434 | <para>The framebuffer parameters cannot be changed at this | ||
| 435 | time because overlay is already enabled, or capturing is enabled | ||
| 436 | and the hardware cannot capture and overlay simultaneously.</para> | ||
| 437 | </listitem> | ||
| 438 | </varlistentry> | ||
| 439 | <varlistentry> | ||
| 440 | <term><errorcode>EINVAL</errorcode></term> | ||
| 441 | <listitem> | ||
| 442 | <para>The ioctl is not supported or the | ||
| 443 | <constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para> | ||
| 444 | </listitem> | ||
| 445 | </varlistentry> | ||
| 446 | </variablelist> | ||
| 447 | </refsect1> | ||
| 448 | </refentry> | ||
| 449 | |||
| 450 | <!-- | ||
| 451 | Local Variables: | ||
| 452 | mode: sgml | ||
| 453 | sgml-parent-document: "v4l2.sgml" | ||
| 454 | indent-tabs-mode: nil | ||
| 455 | End: | ||
| 456 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/v4l/vidioc-g-fmt.xml new file mode 100644 index 000000000000..7c7d1b72c40d --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-fmt.xml | |||
| @@ -0,0 +1,201 @@ | |||
| 1 | <refentry id="vidioc-g-fmt"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, | ||
| 4 | VIDIOC_TRY_FMT</refentrytitle> | ||
| 5 | &manvol; | ||
| 6 | </refmeta> | ||
| 7 | |||
| 8 | <refnamediv> | ||
| 9 | <refname>VIDIOC_G_FMT</refname> | ||
| 10 | <refname>VIDIOC_S_FMT</refname> | ||
| 11 | <refname>VIDIOC_TRY_FMT</refname> | ||
| 12 | <refpurpose>Get or set the data format, try a format</refpurpose> | ||
| 13 | </refnamediv> | ||
| 14 | |||
| 15 | <refsynopsisdiv> | ||
| 16 | <funcsynopsis> | ||
| 17 | <funcprototype> | ||
| 18 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 19 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 20 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 21 | <paramdef>struct v4l2_format | ||
| 22 | *<parameter>argp</parameter></paramdef> | ||
| 23 | </funcprototype> | ||
| 24 | </funcsynopsis> | ||
| 25 | </refsynopsisdiv> | ||
| 26 | |||
| 27 | <refsect1> | ||
| 28 | <title>Arguments</title> | ||
| 29 | |||
| 30 | <variablelist> | ||
| 31 | <varlistentry> | ||
| 32 | <term><parameter>fd</parameter></term> | ||
| 33 | <listitem> | ||
| 34 | <para>&fd;</para> | ||
| 35 | </listitem> | ||
| 36 | </varlistentry> | ||
| 37 | <varlistentry> | ||
| 38 | <term><parameter>request</parameter></term> | ||
| 39 | <listitem> | ||
| 40 | <para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | <varlistentry> | ||
| 44 | <term><parameter>argp</parameter></term> | ||
| 45 | <listitem> | ||
| 46 | <para></para> | ||
| 47 | </listitem> | ||
| 48 | </varlistentry> | ||
| 49 | </variablelist> | ||
| 50 | </refsect1> | ||
| 51 | |||
| 52 | <refsect1> | ||
| 53 | <title>Description</title> | ||
| 54 | |||
| 55 | <para>These ioctls are used to negotiate the format of data | ||
| 56 | (typically image format) exchanged between driver and | ||
| 57 | application.</para> | ||
| 58 | |||
| 59 | <para>To query the current parameters applications set the | ||
| 60 | <structfield>type</structfield> field of a struct | ||
| 61 | <structname>v4l2_format</structname> to the respective buffer (stream) | ||
| 62 | type. For example video capture devices use | ||
| 63 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. When the application | ||
| 64 | calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to | ||
| 65 | this structure the driver fills the respective member of the | ||
| 66 | <structfield>fmt</structfield> union. In case of video capture devices | ||
| 67 | that is the &v4l2-pix-format; <structfield>pix</structfield> member. | ||
| 68 | When the requested buffer type is not supported drivers return an | ||
| 69 | &EINVAL;.</para> | ||
| 70 | |||
| 71 | <para>To change the current format parameters applications | ||
| 72 | initialize the <structfield>type</structfield> field and all | ||
| 73 | fields of the respective <structfield>fmt</structfield> | ||
| 74 | union member. For details see the documentation of the various devices | ||
| 75 | types in <xref linkend="devices" />. Good practice is to query the | ||
| 76 | current parameters first, and to | ||
| 77 | modify only those parameters not suitable for the application. When | ||
| 78 | the application calls the <constant>VIDIOC_S_FMT</constant> ioctl | ||
| 79 | with a pointer to a <structname>v4l2_format</structname> structure | ||
| 80 | the driver checks | ||
| 81 | and adjusts the parameters against hardware abilities. Drivers | ||
| 82 | should not return an error code unless the input is ambiguous, this is | ||
| 83 | a mechanism to fathom device capabilities and to approach parameters | ||
| 84 | acceptable for both the application and driver. On success the driver | ||
| 85 | may program the hardware, allocate resources and generally prepare for | ||
| 86 | data exchange. | ||
| 87 | Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the | ||
| 88 | current format parameters as <constant>VIDIOC_G_FMT</constant> does. | ||
| 89 | Very simple, inflexible devices may even ignore all input and always | ||
| 90 | return the default parameters. However all V4L2 devices exchanging | ||
| 91 | data with the application must implement the | ||
| 92 | <constant>VIDIOC_G_FMT</constant> and | ||
| 93 | <constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer | ||
| 94 | type is not supported drivers return an &EINVAL; on a | ||
| 95 | <constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in | ||
| 96 | progress or the resource is not available for other reasons drivers | ||
| 97 | return the &EBUSY;.</para> | ||
| 98 | |||
| 99 | <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent | ||
| 100 | to <constant>VIDIOC_S_FMT</constant> with one exception: it does not | ||
| 101 | change driver state. It can also be called at any time, never | ||
| 102 | returning <errorcode>EBUSY</errorcode>. This function is provided to | ||
| 103 | negotiate parameters, to learn about hardware limitations, without | ||
| 104 | disabling I/O or possibly time consuming hardware preparations. | ||
| 105 | Although strongly recommended drivers are not required to implement | ||
| 106 | this ioctl.</para> | ||
| 107 | |||
| 108 | <table pgwide="1" frame="none" id="v4l2-format"> | ||
| 109 | <title>struct <structname>v4l2_format</structname></title> | ||
| 110 | <tgroup cols="4"> | ||
| 111 | <colspec colname="c1" /> | ||
| 112 | <colspec colname="c2" /> | ||
| 113 | <colspec colname="c3" /> | ||
| 114 | <colspec colname="c4" /> | ||
| 115 | <tbody valign="top"> | ||
| 116 | <row> | ||
| 117 | <entry>&v4l2-buf-type;</entry> | ||
| 118 | <entry><structfield>type</structfield></entry> | ||
| 119 | <entry></entry> | ||
| 120 | <entry>Type of the data stream, see <xref | ||
| 121 | linkend="v4l2-buf-type" />.</entry> | ||
| 122 | </row> | ||
| 123 | <row> | ||
| 124 | <entry>union</entry> | ||
| 125 | <entry><structfield>fmt</structfield></entry> | ||
| 126 | </row> | ||
| 127 | <row> | ||
| 128 | <entry></entry> | ||
| 129 | <entry>&v4l2-pix-format;</entry> | ||
| 130 | <entry><structfield>pix</structfield></entry> | ||
| 131 | <entry>Definition of an image format, see <xref | ||
| 132 | linkend="pixfmt" />, used by video capture and output | ||
| 133 | devices.</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry></entry> | ||
| 137 | <entry>&v4l2-window;</entry> | ||
| 138 | <entry><structfield>win</structfield></entry> | ||
| 139 | <entry>Definition of an overlaid image, see <xref | ||
| 140 | linkend="overlay" />, used by video overlay devices.</entry> | ||
| 141 | </row> | ||
| 142 | <row> | ||
| 143 | <entry></entry> | ||
| 144 | <entry>&v4l2-vbi-format;</entry> | ||
| 145 | <entry><structfield>vbi</structfield></entry> | ||
| 146 | <entry>Raw VBI capture or output parameters. This is | ||
| 147 | discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI | ||
| 148 | capture and output devices.</entry> | ||
| 149 | </row> | ||
| 150 | <row> | ||
| 151 | <entry></entry> | ||
| 152 | <entry>&v4l2-sliced-vbi-format;</entry> | ||
| 153 | <entry><structfield>sliced</structfield></entry> | ||
| 154 | <entry>Sliced VBI capture or output parameters. See | ||
| 155 | <xref linkend="sliced" /> for details. Used by sliced VBI | ||
| 156 | capture and output devices.</entry> | ||
| 157 | </row> | ||
| 158 | <row> | ||
| 159 | <entry></entry> | ||
| 160 | <entry>__u8</entry> | ||
| 161 | <entry><structfield>raw_data</structfield>[200]</entry> | ||
| 162 | <entry>Place holder for future extensions and custom | ||
| 163 | (driver defined) formats with <structfield>type</structfield> | ||
| 164 | <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry> | ||
| 165 | </row> | ||
| 166 | </tbody> | ||
| 167 | </tgroup> | ||
| 168 | </table> | ||
| 169 | </refsect1> | ||
| 170 | |||
| 171 | <refsect1> | ||
| 172 | &return-value; | ||
| 173 | |||
| 174 | <variablelist> | ||
| 175 | <varlistentry> | ||
| 176 | <term><errorcode>EBUSY</errorcode></term> | ||
| 177 | <listitem> | ||
| 178 | <para>The data format cannot be changed at this | ||
| 179 | time, for example because I/O is already in progress.</para> | ||
| 180 | </listitem> | ||
| 181 | </varlistentry> | ||
| 182 | <varlistentry> | ||
| 183 | <term><errorcode>EINVAL</errorcode></term> | ||
| 184 | <listitem> | ||
| 185 | <para>The &v4l2-format; <structfield>type</structfield> | ||
| 186 | field is invalid, the requested buffer type not supported, or | ||
| 187 | <constant>VIDIOC_TRY_FMT</constant> was called and is not | ||
| 188 | supported with this buffer type.</para> | ||
| 189 | </listitem> | ||
| 190 | </varlistentry> | ||
| 191 | </variablelist> | ||
| 192 | </refsect1> | ||
| 193 | </refentry> | ||
| 194 | |||
| 195 | <!-- | ||
| 196 | Local Variables: | ||
| 197 | mode: sgml | ||
| 198 | sgml-parent-document: "v4l2.sgml" | ||
| 199 | indent-tabs-mode: nil | ||
| 200 | End: | ||
| 201 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/v4l/vidioc-g-frequency.xml new file mode 100644 index 000000000000..062d72069090 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-frequency.xml | |||
| @@ -0,0 +1,145 @@ | |||
| 1 | <refentry id="vidioc-g-frequency"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_FREQUENCY</refname> | ||
| 9 | <refname>VIDIOC_S_FREQUENCY</refname> | ||
| 10 | <refpurpose>Get or set tuner or modulator radio | ||
| 11 | frequency</refpurpose> | ||
| 12 | </refnamediv> | ||
| 13 | |||
| 14 | <refsynopsisdiv> | ||
| 15 | <funcsynopsis> | ||
| 16 | <funcprototype> | ||
| 17 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 18 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 19 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 20 | <paramdef>struct v4l2_frequency | ||
| 21 | *<parameter>argp</parameter></paramdef> | ||
| 22 | </funcprototype> | ||
| 23 | </funcsynopsis> | ||
| 24 | <funcsynopsis> | ||
| 25 | <funcprototype> | ||
| 26 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 27 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 28 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 29 | <paramdef>const struct v4l2_frequency | ||
| 30 | *<parameter>argp</parameter></paramdef> | ||
| 31 | </funcprototype> | ||
| 32 | </funcsynopsis> | ||
| 33 | </refsynopsisdiv> | ||
| 34 | |||
| 35 | <refsect1> | ||
| 36 | <title>Arguments</title> | ||
| 37 | |||
| 38 | <variablelist> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>fd</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para>&fd;</para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | <varlistentry> | ||
| 46 | <term><parameter>request</parameter></term> | ||
| 47 | <listitem> | ||
| 48 | <para>VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</para> | ||
| 49 | </listitem> | ||
| 50 | </varlistentry> | ||
| 51 | <varlistentry> | ||
| 52 | <term><parameter>argp</parameter></term> | ||
| 53 | <listitem> | ||
| 54 | <para></para> | ||
| 55 | </listitem> | ||
| 56 | </varlistentry> | ||
| 57 | </variablelist> | ||
| 58 | </refsect1> | ||
| 59 | |||
| 60 | <refsect1> | ||
| 61 | <title>Description</title> | ||
| 62 | |||
| 63 | <para>To get the current tuner or modulator radio frequency | ||
| 64 | applications set the <structfield>tuner</structfield> field of a | ||
| 65 | &v4l2-frequency; to the respective tuner or modulator number (only | ||
| 66 | input devices have tuners, only output devices have modulators), zero | ||
| 67 | out the <structfield>reserved</structfield> array and | ||
| 68 | call the <constant>VIDIOC_G_FREQUENCY</constant> ioctl with a pointer | ||
| 69 | to this structure. The driver stores the current frequency in the | ||
| 70 | <structfield>frequency</structfield> field.</para> | ||
| 71 | |||
| 72 | <para>To change the current tuner or modulator radio frequency | ||
| 73 | applications initialize the <structfield>tuner</structfield>, | ||
| 74 | <structfield>type</structfield> and | ||
| 75 | <structfield>frequency</structfield> fields, and the | ||
| 76 | <structfield>reserved</structfield> array of a &v4l2-frequency; and | ||
| 77 | call the <constant>VIDIOC_S_FREQUENCY</constant> ioctl with a pointer | ||
| 78 | to this structure. When the requested frequency is not possible the | ||
| 79 | driver assumes the closest possible value. However | ||
| 80 | <constant>VIDIOC_S_FREQUENCY</constant> is a write-only ioctl, it does | ||
| 81 | not return the actual new frequency.</para> | ||
| 82 | |||
| 83 | <table pgwide="1" frame="none" id="v4l2-frequency"> | ||
| 84 | <title>struct <structname>v4l2_frequency</structname></title> | ||
| 85 | <tgroup cols="3"> | ||
| 86 | &cs-str; | ||
| 87 | <tbody valign="top"> | ||
| 88 | <row> | ||
| 89 | <entry>__u32</entry> | ||
| 90 | <entry><structfield>tuner</structfield></entry> | ||
| 91 | <entry>The tuner or modulator index number. This is the | ||
| 92 | same value as in the &v4l2-input; <structfield>tuner</structfield> | ||
| 93 | field and the &v4l2-tuner; <structfield>index</structfield> field, or | ||
| 94 | the &v4l2-output; <structfield>modulator</structfield> field and the | ||
| 95 | &v4l2-modulator; <structfield>index</structfield> field.</entry> | ||
| 96 | </row> | ||
| 97 | <row> | ||
| 98 | <entry>&v4l2-tuner-type;</entry> | ||
| 99 | <entry><structfield>type</structfield></entry> | ||
| 100 | <entry>The tuner type. This is the same value as in the | ||
| 101 | &v4l2-tuner; <structfield>type</structfield> field. The field is not | ||
| 102 | applicable to modulators, &ie; ignored by drivers.</entry> | ||
| 103 | </row> | ||
| 104 | <row> | ||
| 105 | <entry>__u32</entry> | ||
| 106 | <entry><structfield>frequency</structfield></entry> | ||
| 107 | <entry>Tuning frequency in units of 62.5 kHz, or if the | ||
| 108 | &v4l2-tuner; or &v4l2-modulator; <structfield>capabilities</structfield> flag | ||
| 109 | <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
| 110 | Hz.</entry> | ||
| 111 | </row> | ||
| 112 | <row> | ||
| 113 | <entry>__u32</entry> | ||
| 114 | <entry><structfield>reserved</structfield>[8]</entry> | ||
| 115 | <entry>Reserved for future extensions. Drivers and | ||
| 116 | applications must set the array to zero.</entry> | ||
| 117 | </row> | ||
| 118 | </tbody> | ||
| 119 | </tgroup> | ||
| 120 | </table> | ||
| 121 | </refsect1> | ||
| 122 | |||
| 123 | <refsect1> | ||
| 124 | &return-value; | ||
| 125 | |||
| 126 | <variablelist> | ||
| 127 | <varlistentry> | ||
| 128 | <term><errorcode>EINVAL</errorcode></term> | ||
| 129 | <listitem> | ||
| 130 | <para>The <structfield>tuner</structfield> index is out of | ||
| 131 | bounds or the value in the <structfield>type</structfield> field is | ||
| 132 | wrong.</para> | ||
| 133 | </listitem> | ||
| 134 | </varlistentry> | ||
| 135 | </variablelist> | ||
| 136 | </refsect1> | ||
| 137 | </refentry> | ||
| 138 | |||
| 139 | <!-- | ||
| 140 | Local Variables: | ||
| 141 | mode: sgml | ||
| 142 | sgml-parent-document: "v4l2.sgml" | ||
| 143 | indent-tabs-mode: nil | ||
| 144 | End: | ||
| 145 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-input.xml b/Documentation/DocBook/v4l/vidioc-g-input.xml new file mode 100644 index 000000000000..ed076e92760d --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-input.xml | |||
| @@ -0,0 +1,100 @@ | |||
| 1 | <refentry id="vidioc-g-input"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_INPUT</refname> | ||
| 9 | <refname>VIDIOC_S_INPUT</refname> | ||
| 10 | <refpurpose>Query or select the current video input</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>int *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_G_INPUT, VIDIOC_S_INPUT</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>To query the current video input applications call the | ||
| 53 | <constant>VIDIOC_G_INPUT</constant> ioctl with a pointer to an integer | ||
| 54 | where the driver stores the number of the input, as in the | ||
| 55 | &v4l2-input; <structfield>index</structfield> field. This ioctl will | ||
| 56 | fail only when there are no video inputs, returning | ||
| 57 | <errorcode>EINVAL</errorcode>.</para> | ||
| 58 | |||
| 59 | <para>To select a video input applications store the number of the | ||
| 60 | desired input in an integer and call the | ||
| 61 | <constant>VIDIOC_S_INPUT</constant> ioctl with a pointer to this | ||
| 62 | integer. Side effects are possible. For example inputs may support | ||
| 63 | different video standards, so the driver may implicitly switch the | ||
| 64 | current standard. It is good practice to select an input before | ||
| 65 | querying or negotiating any other parameters.</para> | ||
| 66 | |||
| 67 | <para>Information about video inputs is available using the | ||
| 68 | &VIDIOC-ENUMINPUT; ioctl.</para> | ||
| 69 | </refsect1> | ||
| 70 | |||
| 71 | <refsect1> | ||
| 72 | &return-value; | ||
| 73 | |||
| 74 | <variablelist> | ||
| 75 | <varlistentry> | ||
| 76 | <term><errorcode>EINVAL</errorcode></term> | ||
| 77 | <listitem> | ||
| 78 | <para>The number of the video input is out of bounds, or | ||
| 79 | there are no video inputs at all and this ioctl is not | ||
| 80 | supported.</para> | ||
| 81 | </listitem> | ||
| 82 | </varlistentry> | ||
| 83 | <varlistentry> | ||
| 84 | <term><errorcode>EBUSY</errorcode></term> | ||
| 85 | <listitem> | ||
| 86 | <para>I/O is in progress, the input cannot be | ||
| 87 | switched.</para> | ||
| 88 | </listitem> | ||
| 89 | </varlistentry> | ||
| 90 | </variablelist> | ||
| 91 | </refsect1> | ||
| 92 | </refentry> | ||
| 93 | |||
| 94 | <!-- | ||
| 95 | Local Variables: | ||
| 96 | mode: sgml | ||
| 97 | sgml-parent-document: "v4l2.sgml" | ||
| 98 | indent-tabs-mode: nil | ||
| 99 | End: | ||
| 100 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-jpegcomp.xml b/Documentation/DocBook/v4l/vidioc-g-jpegcomp.xml new file mode 100644 index 000000000000..77394b287411 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-jpegcomp.xml | |||
| @@ -0,0 +1,180 @@ | |||
| 1 | <refentry id="vidioc-g-jpegcomp"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_JPEGCOMP</refname> | ||
| 9 | <refname>VIDIOC_S_JPEGCOMP</refname> | ||
| 10 | <refpurpose></refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>v4l2_jpegcompression *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>const v4l2_jpegcompression *<parameter>argp</parameter></paramdef> | ||
| 28 | </funcprototype> | ||
| 29 | </funcsynopsis> | ||
| 30 | </refsynopsisdiv> | ||
| 31 | |||
| 32 | <refsect1> | ||
| 33 | <title>Arguments</title> | ||
| 34 | |||
| 35 | <variablelist> | ||
| 36 | <varlistentry> | ||
| 37 | <term><parameter>fd</parameter></term> | ||
| 38 | <listitem> | ||
| 39 | <para>&fd;</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>request</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | <varlistentry> | ||
| 49 | <term><parameter>argp</parameter></term> | ||
| 50 | <listitem> | ||
| 51 | <para></para> | ||
| 52 | </listitem> | ||
| 53 | </varlistentry> | ||
| 54 | </variablelist> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Description</title> | ||
| 59 | |||
| 60 | <para>[to do]</para> | ||
| 61 | |||
| 62 | <para>Ronald Bultje elaborates:</para> | ||
| 63 | |||
| 64 | <!-- See video4linux-list@redhat.com on 16 Oct 2002, subject | ||
| 65 | "Re: [V4L] Re: v4l2 api / Zoran v4l2_jpegcompression" --> | ||
| 66 | |||
| 67 | <para>APP is some application-specific information. The | ||
| 68 | application can set it itself, and it'll be stored in the JPEG-encoded | ||
| 69 | fields (eg; interlacing information for in an AVI or so). COM is the | ||
| 70 | same, but it's comments, like 'encoded by me' or so.</para> | ||
| 71 | |||
| 72 | <para>jpeg_markers describes whether the huffman tables, | ||
| 73 | quantization tables and the restart interval information (all | ||
| 74 | JPEG-specific stuff) should be stored in the JPEG-encoded fields. | ||
| 75 | These define how the JPEG field is encoded. If you omit them, | ||
| 76 | applications assume you've used standard encoding. You usually do want | ||
| 77 | to add them.</para> | ||
| 78 | |||
| 79 | <!-- NB VIDIOC_S_JPEGCOMP is w/o. --> | ||
| 80 | |||
| 81 | <table pgwide="1" frame="none" id="v4l2-jpegcompression"> | ||
| 82 | <title>struct <structname>v4l2_jpegcompression</structname></title> | ||
| 83 | <tgroup cols="3"> | ||
| 84 | &cs-str; | ||
| 85 | <tbody valign="top"> | ||
| 86 | <row> | ||
| 87 | <entry>int</entry> | ||
| 88 | <entry><structfield>quality</structfield></entry> | ||
| 89 | <entry></entry> | ||
| 90 | </row> | ||
| 91 | <row> | ||
| 92 | <entry>int</entry> | ||
| 93 | <entry><structfield>APPn</structfield></entry> | ||
| 94 | <entry></entry> | ||
| 95 | </row> | ||
| 96 | <row> | ||
| 97 | <entry>int</entry> | ||
| 98 | <entry><structfield>APP_len</structfield></entry> | ||
| 99 | <entry></entry> | ||
| 100 | </row> | ||
| 101 | <row> | ||
| 102 | <entry>char</entry> | ||
| 103 | <entry><structfield>APP_data</structfield>[60]</entry> | ||
| 104 | <entry></entry> | ||
| 105 | </row> | ||
| 106 | <row> | ||
| 107 | <entry>int</entry> | ||
| 108 | <entry><structfield>COM_len</structfield></entry> | ||
| 109 | <entry></entry> | ||
| 110 | </row> | ||
| 111 | <row> | ||
| 112 | <entry>char</entry> | ||
| 113 | <entry><structfield>COM_data</structfield>[60]</entry> | ||
| 114 | <entry></entry> | ||
| 115 | </row> | ||
| 116 | <row> | ||
| 117 | <entry>__u32</entry> | ||
| 118 | <entry><structfield>jpeg_markers</structfield></entry> | ||
| 119 | <entry>See <xref linkend="jpeg-markers" />.</entry> | ||
| 120 | </row> | ||
| 121 | </tbody> | ||
| 122 | </tgroup> | ||
| 123 | </table> | ||
| 124 | |||
| 125 | <table pgwide="1" frame="none" id="jpeg-markers"> | ||
| 126 | <title>JPEG Markers Flags</title> | ||
| 127 | <tgroup cols="3"> | ||
| 128 | &cs-def; | ||
| 129 | <tbody valign="top"> | ||
| 130 | <row> | ||
| 131 | <entry><constant>V4L2_JPEG_MARKER_DHT</constant></entry> | ||
| 132 | <entry>(1<<3)</entry> | ||
| 133 | <entry>Define Huffman Tables</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry><constant>V4L2_JPEG_MARKER_DQT</constant></entry> | ||
| 137 | <entry>(1<<4)</entry> | ||
| 138 | <entry>Define Quantization Tables</entry> | ||
| 139 | </row> | ||
| 140 | <row> | ||
| 141 | <entry><constant>V4L2_JPEG_MARKER_DRI</constant></entry> | ||
| 142 | <entry>(1<<5)</entry> | ||
| 143 | <entry>Define Restart Interval</entry> | ||
| 144 | </row> | ||
| 145 | <row> | ||
| 146 | <entry><constant>V4L2_JPEG_MARKER_COM</constant></entry> | ||
| 147 | <entry>(1<<6)</entry> | ||
| 148 | <entry>Comment segment</entry> | ||
| 149 | </row> | ||
| 150 | <row> | ||
| 151 | <entry><constant>V4L2_JPEG_MARKER_APP</constant></entry> | ||
| 152 | <entry>(1<<7)</entry> | ||
| 153 | <entry>App segment, driver will always use APP0</entry> | ||
| 154 | </row> | ||
| 155 | </tbody> | ||
| 156 | </tgroup> | ||
| 157 | </table> | ||
| 158 | </refsect1> | ||
| 159 | |||
| 160 | <refsect1> | ||
| 161 | &return-value; | ||
| 162 | |||
| 163 | <variablelist> | ||
| 164 | <varlistentry> | ||
| 165 | <term><errorcode>EINVAL</errorcode></term> | ||
| 166 | <listitem> | ||
| 167 | <para>This ioctl is not supported.</para> | ||
| 168 | </listitem> | ||
| 169 | </varlistentry> | ||
| 170 | </variablelist> | ||
| 171 | </refsect1> | ||
| 172 | </refentry> | ||
| 173 | |||
| 174 | <!-- | ||
| 175 | Local Variables: | ||
| 176 | mode: sgml | ||
| 177 | sgml-parent-document: "v4l2.sgml" | ||
| 178 | indent-tabs-mode: nil | ||
| 179 | End: | ||
| 180 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/v4l/vidioc-g-modulator.xml new file mode 100644 index 000000000000..15ce660f0f5a --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-modulator.xml | |||
| @@ -0,0 +1,246 @@ | |||
| 1 | <refentry id="vidioc-g-modulator"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_MODULATOR</refname> | ||
| 9 | <refname>VIDIOC_S_MODULATOR</refname> | ||
| 10 | <refpurpose>Get or set modulator attributes</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_modulator | ||
| 20 | *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | <funcsynopsis> | ||
| 24 | <funcprototype> | ||
| 25 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 28 | <paramdef>const struct v4l2_modulator | ||
| 29 | *<parameter>argp</parameter></paramdef> | ||
| 30 | </funcprototype> | ||
| 31 | </funcsynopsis> | ||
| 32 | </refsynopsisdiv> | ||
| 33 | |||
| 34 | <refsect1> | ||
| 35 | <title>Arguments</title> | ||
| 36 | |||
| 37 | <variablelist> | ||
| 38 | <varlistentry> | ||
| 39 | <term><parameter>fd</parameter></term> | ||
| 40 | <listitem> | ||
| 41 | <para>&fd;</para> | ||
| 42 | </listitem> | ||
| 43 | </varlistentry> | ||
| 44 | <varlistentry> | ||
| 45 | <term><parameter>request</parameter></term> | ||
| 46 | <listitem> | ||
| 47 | <para>VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</para> | ||
| 48 | </listitem> | ||
| 49 | </varlistentry> | ||
| 50 | <varlistentry> | ||
| 51 | <term><parameter>argp</parameter></term> | ||
| 52 | <listitem> | ||
| 53 | <para></para> | ||
| 54 | </listitem> | ||
| 55 | </varlistentry> | ||
| 56 | </variablelist> | ||
| 57 | </refsect1> | ||
| 58 | |||
| 59 | <refsect1> | ||
| 60 | <title>Description</title> | ||
| 61 | |||
| 62 | <para>To query the attributes of a modulator applications initialize | ||
| 63 | the <structfield>index</structfield> field and zero out the | ||
| 64 | <structfield>reserved</structfield> array of a &v4l2-modulator; and | ||
| 65 | call the <constant>VIDIOC_G_MODULATOR</constant> ioctl with a pointer | ||
| 66 | to this structure. Drivers fill the rest of the structure or return an | ||
| 67 | &EINVAL; when the index is out of bounds. To enumerate all modulators | ||
| 68 | applications shall begin at index zero, incrementing by one until the | ||
| 69 | driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 70 | |||
| 71 | <para>Modulators have two writable properties, an audio | ||
| 72 | modulation set and the radio frequency. To change the modulated audio | ||
| 73 | subprograms, applications initialize the <structfield>index | ||
| 74 | </structfield> and <structfield>txsubchans</structfield> fields and the | ||
| 75 | <structfield>reserved</structfield> array and call the | ||
| 76 | <constant>VIDIOC_S_MODULATOR</constant> ioctl. Drivers may choose a | ||
| 77 | different audio modulation if the request cannot be satisfied. However | ||
| 78 | this is a write-only ioctl, it does not return the actual audio | ||
| 79 | modulation selected.</para> | ||
| 80 | |||
| 81 | <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl | ||
| 82 | is available.</para> | ||
| 83 | |||
| 84 | <table pgwide="1" frame="none" id="v4l2-modulator"> | ||
| 85 | <title>struct <structname>v4l2_modulator</structname></title> | ||
| 86 | <tgroup cols="3"> | ||
| 87 | &cs-str; | ||
| 88 | <tbody valign="top"> | ||
| 89 | <row> | ||
| 90 | <entry>__u32</entry> | ||
| 91 | <entry><structfield>index</structfield></entry> | ||
| 92 | <entry>Identifies the modulator, set by the | ||
| 93 | application.</entry> | ||
| 94 | </row> | ||
| 95 | <row> | ||
| 96 | <entry>__u8</entry> | ||
| 97 | <entry><structfield>name</structfield>[32]</entry> | ||
| 98 | <entry>Name of the modulator, a NUL-terminated ASCII | ||
| 99 | string. This information is intended for the user.</entry> | ||
| 100 | </row> | ||
| 101 | <row> | ||
| 102 | <entry>__u32</entry> | ||
| 103 | <entry><structfield>capability</structfield></entry> | ||
| 104 | <entry>Modulator capability flags. No flags are defined | ||
| 105 | for this field, the tuner flags in &v4l2-tuner; | ||
| 106 | are used accordingly. The audio flags indicate the ability | ||
| 107 | to encode audio subprograms. They will <emphasis>not</emphasis> | ||
| 108 | change for example with the current video standard.</entry> | ||
| 109 | </row> | ||
| 110 | <row> | ||
| 111 | <entry>__u32</entry> | ||
| 112 | <entry><structfield>rangelow</structfield></entry> | ||
| 113 | <entry>The lowest tunable frequency in units of 62.5 | ||
| 114 | KHz, or if the <structfield>capability</structfield> flag | ||
| 115 | <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
| 116 | Hz.</entry> | ||
| 117 | </row> | ||
| 118 | <row> | ||
| 119 | <entry>__u32</entry> | ||
| 120 | <entry><structfield>rangehigh</structfield></entry> | ||
| 121 | <entry>The highest tunable frequency in units of 62.5 | ||
| 122 | KHz, or if the <structfield>capability</structfield> flag | ||
| 123 | <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
| 124 | Hz.</entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry>__u32</entry> | ||
| 128 | <entry><structfield>txsubchans</structfield></entry> | ||
| 129 | <entry>With this field applications can determine how | ||
| 130 | audio sub-carriers shall be modulated. It contains a set of flags as | ||
| 131 | defined in <xref linkend="modulator-txsubchans" />. Note the tuner | ||
| 132 | <structfield>rxsubchans</structfield> flags are reused, but the | ||
| 133 | semantics are different. Video output devices are assumed to have an | ||
| 134 | analog or PCM audio input with 1-3 channels. The | ||
| 135 | <structfield>txsubchans</structfield> flags select one or more | ||
| 136 | channels for modulation, together with some audio subprogram | ||
| 137 | indicator, for example a stereo pilot tone.</entry> | ||
| 138 | </row> | ||
| 139 | <row> | ||
| 140 | <entry>__u32</entry> | ||
| 141 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 142 | <entry>Reserved for future extensions. Drivers and | ||
| 143 | applications must set the array to zero.</entry> | ||
| 144 | </row> | ||
| 145 | </tbody> | ||
| 146 | </tgroup> | ||
| 147 | </table> | ||
| 148 | |||
| 149 | <table pgwide="1" frame="none" id="modulator-txsubchans"> | ||
| 150 | <title>Modulator Audio Transmission Flags</title> | ||
| 151 | <tgroup cols="3"> | ||
| 152 | &cs-def; | ||
| 153 | <tbody valign="top"> | ||
| 154 | <row> | ||
| 155 | <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> | ||
| 156 | <entry>0x0001</entry> | ||
| 157 | <entry>Modulate channel 1 as mono audio, when the input | ||
| 158 | has more channels, a down-mix of channel 1 and 2. This flag does not | ||
| 159 | combine with <constant>V4L2_TUNER_SUB_STEREO</constant> or | ||
| 160 | <constant>V4L2_TUNER_SUB_LANG1</constant>.</entry> | ||
| 161 | </row> | ||
| 162 | <row> | ||
| 163 | <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry> | ||
| 164 | <entry>0x0002</entry> | ||
| 165 | <entry>Modulate channel 1 and 2 as left and right | ||
| 166 | channel of a stereo audio signal. When the input has only one channel | ||
| 167 | or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also | ||
| 168 | set, channel 1 is encoded as left and right channel. This flag does | ||
| 169 | not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or | ||
| 170 | <constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not | ||
| 171 | support stereo audio it shall fall back to mono.</entry> | ||
| 172 | </row> | ||
| 173 | <row> | ||
| 174 | <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry> | ||
| 175 | <entry>0x0008</entry> | ||
| 176 | <entry>Modulate channel 1 and 2 as primary and secondary | ||
| 177 | language of a bilingual audio signal. When the input has only one | ||
| 178 | channel it is used for both languages. It is not possible to encode | ||
| 179 | the primary or secondary language only. This flag does not combine | ||
| 180 | with <constant>V4L2_TUNER_SUB_MONO</constant>, | ||
| 181 | <constant>V4L2_TUNER_SUB_STEREO</constant> or | ||
| 182 | <constant>V4L2_TUNER_SUB_SAP</constant>. If the hardware does not | ||
| 183 | support the respective audio matrix, or the current video standard | ||
| 184 | does not permit bilingual audio the | ||
| 185 | <constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL; | ||
| 186 | and the driver shall fall back to mono or stereo mode.</entry> | ||
| 187 | </row> | ||
| 188 | <row> | ||
| 189 | <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> | ||
| 190 | <entry>0x0004</entry> | ||
| 191 | <entry>Same effect as | ||
| 192 | <constant>V4L2_TUNER_SUB_SAP</constant>.</entry> | ||
| 193 | </row> | ||
| 194 | <row> | ||
| 195 | <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> | ||
| 196 | <entry>0x0004</entry> | ||
| 197 | <entry>When combined with <constant>V4L2_TUNER_SUB_MONO | ||
| 198 | </constant> the first channel is encoded as mono audio, the last | ||
| 199 | channel as Second Audio Program. When the input has only one channel | ||
| 200 | it is used for both audio tracks. When the input has three channels | ||
| 201 | the mono track is a down-mix of channel 1 and 2. When combined with | ||
| 202 | <constant>V4L2_TUNER_SUB_STEREO</constant> channel 1 and 2 are | ||
| 203 | encoded as left and right stereo audio, channel 3 as Second Audio | ||
| 204 | Program. When the input has only two channels, the first is encoded as | ||
| 205 | left and right channel and the second as SAP. When the input has only | ||
| 206 | one channel it is used for all audio tracks. It is not possible to | ||
| 207 | encode a Second Audio Program only. This flag must combine with | ||
| 208 | <constant>V4L2_TUNER_SUB_MONO</constant> or | ||
| 209 | <constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not | ||
| 210 | support the respective audio matrix, or the current video standard | ||
| 211 | does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl | ||
| 212 | shall return an &EINVAL; and driver shall fall back to mono or stereo | ||
| 213 | mode.</entry> | ||
| 214 | </row> | ||
| 215 | <row> | ||
| 216 | <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> | ||
| 217 | <entry>0x0010</entry> | ||
| 218 | <entry>Enable the RDS encoder for a radio FM transmitter.</entry> | ||
| 219 | </row> | ||
| 220 | </tbody> | ||
| 221 | </tgroup> | ||
| 222 | </table> | ||
| 223 | </refsect1> | ||
| 224 | |||
| 225 | <refsect1> | ||
| 226 | &return-value; | ||
| 227 | |||
| 228 | <variablelist> | ||
| 229 | <varlistentry> | ||
| 230 | <term><errorcode>EINVAL</errorcode></term> | ||
| 231 | <listitem> | ||
| 232 | <para>The &v4l2-modulator; | ||
| 233 | <structfield>index</structfield> is out of bounds.</para> | ||
| 234 | </listitem> | ||
| 235 | </varlistentry> | ||
| 236 | </variablelist> | ||
| 237 | </refsect1> | ||
| 238 | </refentry> | ||
| 239 | |||
| 240 | <!-- | ||
| 241 | Local Variables: | ||
| 242 | mode: sgml | ||
| 243 | sgml-parent-document: "v4l2.sgml" | ||
| 244 | indent-tabs-mode: nil | ||
| 245 | End: | ||
| 246 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-output.xml b/Documentation/DocBook/v4l/vidioc-g-output.xml new file mode 100644 index 000000000000..3ea8c0ed812e --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-output.xml | |||
| @@ -0,0 +1,100 @@ | |||
| 1 | <refentry id="vidioc-g-output"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_OUTPUT</refname> | ||
| 9 | <refname>VIDIOC_S_OUTPUT</refname> | ||
| 10 | <refpurpose>Query or select the current video output</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>int *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>To query the current video output applications call the | ||
| 53 | <constant>VIDIOC_G_OUTPUT</constant> ioctl with a pointer to an integer | ||
| 54 | where the driver stores the number of the output, as in the | ||
| 55 | &v4l2-output; <structfield>index</structfield> field. This ioctl | ||
| 56 | will fail only when there are no video outputs, returning the | ||
| 57 | &EINVAL;.</para> | ||
| 58 | |||
| 59 | <para>To select a video output applications store the number of the | ||
| 60 | desired output in an integer and call the | ||
| 61 | <constant>VIDIOC_S_OUTPUT</constant> ioctl with a pointer to this integer. | ||
| 62 | Side effects are possible. For example outputs may support different | ||
| 63 | video standards, so the driver may implicitly switch the current | ||
| 64 | standard. It is good practice to select an output before querying or | ||
| 65 | negotiating any other parameters.</para> | ||
| 66 | |||
| 67 | <para>Information about video outputs is available using the | ||
| 68 | &VIDIOC-ENUMOUTPUT; ioctl.</para> | ||
| 69 | </refsect1> | ||
| 70 | |||
| 71 | <refsect1> | ||
| 72 | &return-value; | ||
| 73 | |||
| 74 | <variablelist> | ||
| 75 | <varlistentry> | ||
| 76 | <term><errorcode>EINVAL</errorcode></term> | ||
| 77 | <listitem> | ||
| 78 | <para>The number of the video output is out of bounds, or | ||
| 79 | there are no video outputs at all and this ioctl is not | ||
| 80 | supported.</para> | ||
| 81 | </listitem> | ||
| 82 | </varlistentry> | ||
| 83 | <varlistentry> | ||
| 84 | <term><errorcode>EBUSY</errorcode></term> | ||
| 85 | <listitem> | ||
| 86 | <para>I/O is in progress, the output cannot be | ||
| 87 | switched.</para> | ||
| 88 | </listitem> | ||
| 89 | </varlistentry> | ||
| 90 | </variablelist> | ||
| 91 | </refsect1> | ||
| 92 | </refentry> | ||
| 93 | |||
| 94 | <!-- | ||
| 95 | Local Variables: | ||
| 96 | mode: sgml | ||
| 97 | sgml-parent-document: "v4l2.sgml" | ||
| 98 | indent-tabs-mode: nil | ||
| 99 | End: | ||
| 100 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-parm.xml b/Documentation/DocBook/v4l/vidioc-g-parm.xml new file mode 100644 index 000000000000..78332d365ce9 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-parm.xml | |||
| @@ -0,0 +1,332 @@ | |||
| 1 | <refentry id="vidioc-g-parm"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_PARM</refname> | ||
| 9 | <refname>VIDIOC_S_PARM</refname> | ||
| 10 | <refpurpose>Get or set streaming parameters</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>v4l2_streamparm *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_G_PARM, VIDIOC_S_PARM</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>The current video standard determines a nominal number of | ||
| 53 | frames per second. If less than this number of frames is to be | ||
| 54 | captured or output, applications can request frame skipping or | ||
| 55 | duplicating on the driver side. This is especially useful when using | ||
| 56 | the <function>read()</function> or <function>write()</function>, which | ||
| 57 | are not augmented by timestamps or sequence counters, and to avoid | ||
| 58 | unneccessary data copying.</para> | ||
| 59 | |||
| 60 | <para>Further these ioctls can be used to determine the number of | ||
| 61 | buffers used internally by a driver in read/write mode. For | ||
| 62 | implications see the section discussing the &func-read; | ||
| 63 | function.</para> | ||
| 64 | |||
| 65 | <para>To get and set the streaming parameters applications call | ||
| 66 | the <constant>VIDIOC_G_PARM</constant> and | ||
| 67 | <constant>VIDIOC_S_PARM</constant> ioctl, respectively. They take a | ||
| 68 | pointer to a struct <structname>v4l2_streamparm</structname> which | ||
| 69 | contains a union holding separate parameters for input and output | ||
| 70 | devices.</para> | ||
| 71 | |||
| 72 | <table pgwide="1" frame="none" id="v4l2-streamparm"> | ||
| 73 | <title>struct <structname>v4l2_streamparm</structname></title> | ||
| 74 | <tgroup cols="4"> | ||
| 75 | &cs-ustr; | ||
| 76 | <tbody valign="top"> | ||
| 77 | <row> | ||
| 78 | <entry>&v4l2-buf-type;</entry> | ||
| 79 | <entry><structfield>type</structfield></entry> | ||
| 80 | <entry></entry> | ||
| 81 | <entry>The buffer (stream) type, same as &v4l2-format; | ||
| 82 | <structfield>type</structfield>, set by the application.</entry> | ||
| 83 | </row> | ||
| 84 | <row> | ||
| 85 | <entry>union</entry> | ||
| 86 | <entry><structfield>parm</structfield></entry> | ||
| 87 | <entry></entry> | ||
| 88 | <entry></entry> | ||
| 89 | </row> | ||
| 90 | <row> | ||
| 91 | <entry></entry> | ||
| 92 | <entry>&v4l2-captureparm;</entry> | ||
| 93 | <entry><structfield>capture</structfield></entry> | ||
| 94 | <entry>Parameters for capture devices, used when | ||
| 95 | <structfield>type</structfield> is | ||
| 96 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry></entry> | ||
| 100 | <entry>&v4l2-outputparm;</entry> | ||
| 101 | <entry><structfield>output</structfield></entry> | ||
| 102 | <entry>Parameters for output devices, used when | ||
| 103 | <structfield>type</structfield> is | ||
| 104 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>.</entry> | ||
| 105 | </row> | ||
| 106 | <row> | ||
| 107 | <entry></entry> | ||
| 108 | <entry>__u8</entry> | ||
| 109 | <entry><structfield>raw_data</structfield>[200]</entry> | ||
| 110 | <entry>A place holder for future extensions and custom | ||
| 111 | (driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and | ||
| 112 | higher.</entry> | ||
| 113 | </row> | ||
| 114 | </tbody> | ||
| 115 | </tgroup> | ||
| 116 | </table> | ||
| 117 | |||
| 118 | <table pgwide="1" frame="none" id="v4l2-captureparm"> | ||
| 119 | <title>struct <structname>v4l2_captureparm</structname></title> | ||
| 120 | <tgroup cols="3"> | ||
| 121 | &cs-str; | ||
| 122 | <tbody valign="top"> | ||
| 123 | <row> | ||
| 124 | <entry>__u32</entry> | ||
| 125 | <entry><structfield>capability</structfield></entry> | ||
| 126 | <entry>See <xref linkend="parm-caps" />.</entry> | ||
| 127 | </row> | ||
| 128 | <row> | ||
| 129 | <entry>__u32</entry> | ||
| 130 | <entry><structfield>capturemode</structfield></entry> | ||
| 131 | <entry>Set by drivers and applications, see <xref linkend="parm-flags" />.</entry> | ||
| 132 | </row> | ||
| 133 | <row> | ||
| 134 | <entry>&v4l2-fract;</entry> | ||
| 135 | <entry><structfield>timeperframe</structfield></entry> | ||
| 136 | <entry><para>This is is the desired period between | ||
| 137 | successive frames captured by the driver, in seconds. The | ||
| 138 | field is intended to skip frames on the driver side, saving I/O | ||
| 139 | bandwidth.</para><para>Applications store here the desired frame | ||
| 140 | period, drivers return the actual frame period, which must be greater | ||
| 141 | or equal to the nominal frame period determined by the current video | ||
| 142 | standard (&v4l2-standard; <structfield>frameperiod</structfield> | ||
| 143 | field). Changing the video standard (also implicitly by switching the | ||
| 144 | video input) may reset this parameter to the nominal frame period. To | ||
| 145 | reset manually applications can just set this field to | ||
| 146 | zero.</para><para>Drivers support this function only when they set the | ||
| 147 | <constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the | ||
| 148 | <structfield>capability</structfield> field.</para></entry> | ||
| 149 | </row> | ||
| 150 | <row> | ||
| 151 | <entry>__u32</entry> | ||
| 152 | <entry><structfield>extendedmode</structfield></entry> | ||
| 153 | <entry>Custom (driver specific) streaming parameters. When | ||
| 154 | unused, applications and drivers must set this field to zero. | ||
| 155 | Applications using this field should check the driver name and | ||
| 156 | version, see <xref linkend="querycap" />.</entry> | ||
| 157 | </row> | ||
| 158 | <row> | ||
| 159 | <entry>__u32</entry> | ||
| 160 | <entry><structfield>readbuffers</structfield></entry> | ||
| 161 | <entry>Applications set this field to the desired number | ||
| 162 | of buffers used internally by the driver in &func-read; mode. Drivers | ||
| 163 | return the actual number of buffers. When an application requests zero | ||
| 164 | buffers, drivers should just return the current setting rather than | ||
| 165 | the minimum or an error code. For details see <xref | ||
| 166 | linkend="rw" />.</entry> | ||
| 167 | </row> | ||
| 168 | <row> | ||
| 169 | <entry>__u32</entry> | ||
| 170 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 171 | <entry>Reserved for future extensions. Drivers and | ||
| 172 | applications must set the array to zero.</entry> | ||
| 173 | </row> | ||
| 174 | </tbody> | ||
| 175 | </tgroup> | ||
| 176 | </table> | ||
| 177 | |||
| 178 | <table pgwide="1" frame="none" id="v4l2-outputparm"> | ||
| 179 | <title>struct <structname>v4l2_outputparm</structname></title> | ||
| 180 | <tgroup cols="3"> | ||
| 181 | &cs-str; | ||
| 182 | <tbody valign="top"> | ||
| 183 | <row> | ||
| 184 | <entry>__u32</entry> | ||
| 185 | <entry><structfield>capability</structfield></entry> | ||
| 186 | <entry>See <xref linkend="parm-caps" />.</entry> | ||
| 187 | </row> | ||
| 188 | <row> | ||
| 189 | <entry>__u32</entry> | ||
| 190 | <entry><structfield>outputmode</structfield></entry> | ||
| 191 | <entry>Set by drivers and applications, see <xref | ||
| 192 | linkend="parm-flags" />.</entry> | ||
| 193 | </row> | ||
| 194 | <row> | ||
| 195 | <entry>&v4l2-fract;</entry> | ||
| 196 | <entry><structfield>timeperframe</structfield></entry> | ||
| 197 | <entry>This is is the desired period between | ||
| 198 | successive frames output by the driver, in seconds.</entry> | ||
| 199 | </row> | ||
| 200 | <row> | ||
| 201 | <entry spanname="hspan"><para>The field is intended to | ||
| 202 | repeat frames on the driver side in &func-write; mode (in streaming | ||
| 203 | mode timestamps can be used to throttle the output), saving I/O | ||
| 204 | bandwidth.</para><para>Applications store here the desired frame | ||
| 205 | period, drivers return the actual frame period, which must be greater | ||
| 206 | or equal to the nominal frame period determined by the current video | ||
| 207 | standard (&v4l2-standard; <structfield>frameperiod</structfield> | ||
| 208 | field). Changing the video standard (also implicitly by switching the | ||
| 209 | video output) may reset this parameter to the nominal frame period. To | ||
| 210 | reset manually applications can just set this field to | ||
| 211 | zero.</para><para>Drivers support this function only when they set the | ||
| 212 | <constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the | ||
| 213 | <structfield>capability</structfield> field.</para></entry> | ||
| 214 | </row> | ||
| 215 | <row> | ||
| 216 | <entry>__u32</entry> | ||
| 217 | <entry><structfield>extendedmode</structfield></entry> | ||
| 218 | <entry>Custom (driver specific) streaming parameters. When | ||
| 219 | unused, applications and drivers must set this field to zero. | ||
| 220 | Applications using this field should check the driver name and | ||
| 221 | version, see <xref linkend="querycap" />.</entry> | ||
| 222 | </row> | ||
| 223 | <row> | ||
| 224 | <entry>__u32</entry> | ||
| 225 | <entry><structfield>writebuffers</structfield></entry> | ||
| 226 | <entry>Applications set this field to the desired number | ||
| 227 | of buffers used internally by the driver in | ||
| 228 | <function>write()</function> mode. Drivers return the actual number of | ||
| 229 | buffers. When an application requests zero buffers, drivers should | ||
| 230 | just return the current setting rather than the minimum or an error | ||
| 231 | code. For details see <xref linkend="rw" />.</entry> | ||
| 232 | </row> | ||
| 233 | <row> | ||
| 234 | <entry>__u32</entry> | ||
| 235 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 236 | <entry>Reserved for future extensions. Drivers and | ||
| 237 | applications must set the array to zero.</entry> | ||
| 238 | </row> | ||
| 239 | </tbody> | ||
| 240 | </tgroup> | ||
| 241 | </table> | ||
| 242 | |||
| 243 | <table pgwide="1" frame="none" id="parm-caps"> | ||
| 244 | <title>Streaming Parameters Capabilites</title> | ||
| 245 | <tgroup cols="3"> | ||
| 246 | &cs-def; | ||
| 247 | <tbody valign="top"> | ||
| 248 | <row> | ||
| 249 | <entry><constant>V4L2_CAP_TIMEPERFRAME</constant></entry> | ||
| 250 | <entry>0x1000</entry> | ||
| 251 | <entry>The frame skipping/repeating controlled by the | ||
| 252 | <structfield>timeperframe</structfield> field is supported.</entry> | ||
| 253 | </row> | ||
| 254 | </tbody> | ||
| 255 | </tgroup> | ||
| 256 | </table> | ||
| 257 | |||
| 258 | <table pgwide="1" frame="none" id="parm-flags"> | ||
| 259 | <title>Capture Parameters Flags</title> | ||
| 260 | <tgroup cols="3"> | ||
| 261 | &cs-def; | ||
| 262 | <tbody valign="top"> | ||
| 263 | <row> | ||
| 264 | <entry><constant>V4L2_MODE_HIGHQUALITY</constant></entry> | ||
| 265 | <entry>0x0001</entry> | ||
| 266 | <entry><para>High quality imaging mode. High quality mode | ||
| 267 | is intended for still imaging applications. The idea is to get the | ||
| 268 | best possible image quality that the hardware can deliver. It is not | ||
| 269 | defined how the driver writer may achieve that; it will depend on the | ||
| 270 | hardware and the ingenuity of the driver writer. High quality mode is | ||
| 271 | a different mode from the the regular motion video capture modes. In | ||
| 272 | high quality mode:<itemizedlist> | ||
| 273 | <listitem> | ||
| 274 | <para>The driver may be able to capture higher | ||
| 275 | resolutions than for motion capture.</para> | ||
| 276 | </listitem> | ||
| 277 | <listitem> | ||
| 278 | <para>The driver may support fewer pixel formats | ||
| 279 | than motion capture (eg; true color).</para> | ||
| 280 | </listitem> | ||
| 281 | <listitem> | ||
| 282 | <para>The driver may capture and arithmetically | ||
| 283 | combine multiple successive fields or frames to remove color edge | ||
| 284 | artifacts and reduce the noise in the video data. | ||
| 285 | </para> | ||
| 286 | </listitem> | ||
| 287 | <listitem> | ||
| 288 | <para>The driver may capture images in slices like | ||
| 289 | a scanner in order to handle larger format images than would otherwise | ||
| 290 | be possible. </para> | ||
| 291 | </listitem> | ||
| 292 | <listitem> | ||
| 293 | <para>An image capture operation may be | ||
| 294 | significantly slower than motion capture. </para> | ||
| 295 | </listitem> | ||
| 296 | <listitem> | ||
| 297 | <para>Moving objects in the image might have | ||
| 298 | excessive motion blur. </para> | ||
| 299 | </listitem> | ||
| 300 | <listitem> | ||
| 301 | <para>Capture might only work through the | ||
| 302 | <function>read()</function> call.</para> | ||
| 303 | </listitem> | ||
| 304 | </itemizedlist></para></entry> | ||
| 305 | </row> | ||
| 306 | </tbody> | ||
| 307 | </tgroup> | ||
| 308 | </table> | ||
| 309 | |||
| 310 | </refsect1> | ||
| 311 | |||
| 312 | <refsect1> | ||
| 313 | &return-value; | ||
| 314 | |||
| 315 | <variablelist> | ||
| 316 | <varlistentry> | ||
| 317 | <term><errorcode>EINVAL</errorcode></term> | ||
| 318 | <listitem> | ||
| 319 | <para>This ioctl is not supported.</para> | ||
| 320 | </listitem> | ||
| 321 | </varlistentry> | ||
| 322 | </variablelist> | ||
| 323 | </refsect1> | ||
| 324 | </refentry> | ||
| 325 | |||
| 326 | <!-- | ||
| 327 | Local Variables: | ||
| 328 | mode: sgml | ||
| 329 | sgml-parent-document: "v4l2.sgml" | ||
| 330 | indent-tabs-mode: nil | ||
| 331 | End: | ||
| 332 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-priority.xml b/Documentation/DocBook/v4l/vidioc-g-priority.xml new file mode 100644 index 000000000000..5fb001978645 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-priority.xml | |||
| @@ -0,0 +1,144 @@ | |||
| 1 | <refentry id="vidioc-g-priority"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_PRIORITY</refname> | ||
| 9 | <refname>VIDIOC_S_PRIORITY</refname> | ||
| 10 | <refpurpose>Query or request the access priority associated with a | ||
| 11 | file descriptor</refpurpose> | ||
| 12 | </refnamediv> | ||
| 13 | |||
| 14 | <refsynopsisdiv> | ||
| 15 | <funcsynopsis> | ||
| 16 | <funcprototype> | ||
| 17 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 18 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 19 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 20 | <paramdef>enum v4l2_priority *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | <funcsynopsis> | ||
| 24 | <funcprototype> | ||
| 25 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 28 | <paramdef>const enum v4l2_priority *<parameter>argp</parameter></paramdef> | ||
| 29 | </funcprototype> | ||
| 30 | </funcsynopsis> | ||
| 31 | </refsynopsisdiv> | ||
| 32 | |||
| 33 | <refsect1> | ||
| 34 | <title>Arguments</title> | ||
| 35 | |||
| 36 | <variablelist> | ||
| 37 | <varlistentry> | ||
| 38 | <term><parameter>fd</parameter></term> | ||
| 39 | <listitem> | ||
| 40 | <para>&fd;</para> | ||
| 41 | </listitem> | ||
| 42 | </varlistentry> | ||
| 43 | <varlistentry> | ||
| 44 | <term><parameter>request</parameter></term> | ||
| 45 | <listitem> | ||
| 46 | <para>VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</para> | ||
| 47 | </listitem> | ||
| 48 | </varlistentry> | ||
| 49 | <varlistentry> | ||
| 50 | <term><parameter>argp</parameter></term> | ||
| 51 | <listitem> | ||
| 52 | <para>Pointer to an enum v4l2_priority type.</para> | ||
| 53 | </listitem> | ||
| 54 | </varlistentry> | ||
| 55 | </variablelist> | ||
| 56 | </refsect1> | ||
| 57 | |||
| 58 | <refsect1> | ||
| 59 | <title>Description</title> | ||
| 60 | |||
| 61 | <para>To query the current access priority | ||
| 62 | applications call the <constant>VIDIOC_G_PRIORITY</constant> ioctl | ||
| 63 | with a pointer to an enum v4l2_priority variable where the driver stores | ||
| 64 | the current priority.</para> | ||
| 65 | |||
| 66 | <para>To request an access priority applications store the | ||
| 67 | desired priority in an enum v4l2_priority variable and call | ||
| 68 | <constant>VIDIOC_S_PRIORITY</constant> ioctl with a pointer to this | ||
| 69 | variable.</para> | ||
| 70 | |||
| 71 | <table frame="none" pgwide="1" id="v4l2-priority"> | ||
| 72 | <title>enum v4l2_priority</title> | ||
| 73 | <tgroup cols="3"> | ||
| 74 | &cs-def; | ||
| 75 | <tbody valign="top"> | ||
| 76 | <row> | ||
| 77 | <entry><constant>V4L2_PRIORITY_UNSET</constant></entry> | ||
| 78 | <entry>0</entry> | ||
| 79 | <entry></entry> | ||
| 80 | </row> | ||
| 81 | <row> | ||
| 82 | <entry><constant>V4L2_PRIORITY_BACKGROUND</constant></entry> | ||
| 83 | <entry>1</entry> | ||
| 84 | <entry>Lowest priority, usually applications running in | ||
| 85 | background, for example monitoring VBI transmissions. A proxy | ||
| 86 | application running in user space will be necessary if multiple | ||
| 87 | applications want to read from a device at this priority.</entry> | ||
| 88 | </row> | ||
| 89 | <row> | ||
| 90 | <entry><constant>V4L2_PRIORITY_INTERACTIVE</constant></entry> | ||
| 91 | <entry>2</entry> | ||
| 92 | <entry></entry> | ||
| 93 | </row> | ||
| 94 | <row> | ||
| 95 | <entry><constant>V4L2_PRIORITY_DEFAULT</constant></entry> | ||
| 96 | <entry>2</entry> | ||
| 97 | <entry>Medium priority, usually applications started and | ||
| 98 | interactively controlled by the user. For example TV viewers, Teletext | ||
| 99 | browsers, or just "panel" applications to change the channel or video | ||
| 100 | controls. This is the default priority unless an application requests | ||
| 101 | another.</entry> | ||
| 102 | </row> | ||
| 103 | <row> | ||
| 104 | <entry><constant>V4L2_PRIORITY_RECORD</constant></entry> | ||
| 105 | <entry>3</entry> | ||
| 106 | <entry>Highest priority. Only one file descriptor can have | ||
| 107 | this priority, it blocks any other fd from changing device properties. | ||
| 108 | Usually applications which must not be interrupted, like video | ||
| 109 | recording.</entry> | ||
| 110 | </row> | ||
| 111 | </tbody> | ||
| 112 | </tgroup> | ||
| 113 | </table> | ||
| 114 | </refsect1> | ||
| 115 | |||
| 116 | <refsect1> | ||
| 117 | &return-value; | ||
| 118 | |||
| 119 | <variablelist> | ||
| 120 | <varlistentry> | ||
| 121 | <term><errorcode>EINVAL</errorcode></term> | ||
| 122 | <listitem> | ||
| 123 | <para>The requested priority value is invalid, or the | ||
| 124 | driver does not support access priorities.</para> | ||
| 125 | </listitem> | ||
| 126 | </varlistentry> | ||
| 127 | <varlistentry> | ||
| 128 | <term><errorcode>EBUSY</errorcode></term> | ||
| 129 | <listitem> | ||
| 130 | <para>Another application already requested higher | ||
| 131 | priority.</para> | ||
| 132 | </listitem> | ||
| 133 | </varlistentry> | ||
| 134 | </variablelist> | ||
| 135 | </refsect1> | ||
| 136 | </refentry> | ||
| 137 | |||
| 138 | <!-- | ||
| 139 | Local Variables: | ||
| 140 | mode: sgml | ||
| 141 | sgml-parent-document: "v4l2.sgml" | ||
| 142 | indent-tabs-mode: nil | ||
| 143 | End: | ||
| 144 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-sliced-vbi-cap.xml b/Documentation/DocBook/v4l/vidioc-g-sliced-vbi-cap.xml new file mode 100644 index 000000000000..10e721b17374 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-sliced-vbi-cap.xml | |||
| @@ -0,0 +1,264 @@ | |||
| 1 | <refentry id="vidioc-g-sliced-vbi-cap"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_SLICED_VBI_CAP</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_SLICED_VBI_CAP</refname> | ||
| 9 | <refpurpose>Query sliced VBI capabilities</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_sliced_vbi_cap *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_G_SLICED_VBI_CAP</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>To find out which data services are supported by a sliced | ||
| 52 | VBI capture or output device, applications initialize the | ||
| 53 | <structfield>type</structfield> field of a &v4l2-sliced-vbi-cap;, | ||
| 54 | clear the <structfield>reserved</structfield> array and | ||
| 55 | call the <constant>VIDIOC_G_SLICED_VBI_CAP</constant> ioctl. The | ||
| 56 | driver fills in the remaining fields or returns an &EINVAL; if the | ||
| 57 | sliced VBI API is unsupported or <structfield>type</structfield> | ||
| 58 | is invalid.</para> | ||
| 59 | |||
| 60 | <para>Note the <structfield>type</structfield> field was added, | ||
| 61 | and the ioctl changed from read-only to write-read, in Linux 2.6.19.</para> | ||
| 62 | |||
| 63 | <table pgwide="1" frame="none" id="v4l2-sliced-vbi-cap"> | ||
| 64 | <title>struct <structname>v4l2_sliced_vbi_cap</structname></title> | ||
| 65 | <tgroup cols="5"> | ||
| 66 | <colspec colname="c1" colwidth="3*" /> | ||
| 67 | <colspec colname="c2" colwidth="3*" /> | ||
| 68 | <colspec colname="c3" colwidth="2*" /> | ||
| 69 | <colspec colname="c4" colwidth="2*" /> | ||
| 70 | <colspec colname="c5" colwidth="2*" /> | ||
| 71 | <spanspec spanname="hspan" namest="c3" nameend="c5" /> | ||
| 72 | <tbody valign="top"> | ||
| 73 | <row> | ||
| 74 | <entry>__u16</entry> | ||
| 75 | <entry><structfield>service_set</structfield></entry> | ||
| 76 | <entry spanname="hspan">A set of all data services | ||
| 77 | supported by the driver. Equal to the union of all elements of the | ||
| 78 | <structfield>service_lines </structfield> array.</entry> | ||
| 79 | </row> | ||
| 80 | <row> | ||
| 81 | <entry>__u16</entry> | ||
| 82 | <entry><structfield>service_lines</structfield>[2][24]</entry> | ||
| 83 | <entry spanname="hspan">Each element of this array | ||
| 84 | contains a set of data services the hardware can look for or insert | ||
| 85 | into a particular scan line. Data services are defined in <xref | ||
| 86 | linkend="vbi-services" />. Array indices map to ITU-R | ||
| 87 | line numbers (see also <xref | ||
| 88 | linkend="vbi-525" /> and <xref | ||
| 89 | linkend="vbi-625" />) as follows:</entry> | ||
| 90 | </row> | ||
| 91 | <row> | ||
| 92 | <entry></entry> | ||
| 93 | <entry></entry> | ||
| 94 | <entry>Element</entry> | ||
| 95 | <entry>525 line systems</entry> | ||
| 96 | <entry>625 line systems</entry> | ||
| 97 | </row> | ||
| 98 | <row> | ||
| 99 | <entry></entry> | ||
| 100 | <entry></entry> | ||
| 101 | <entry><structfield>service_lines</structfield>[0][1]</entry> | ||
| 102 | <entry align="center">1</entry> | ||
| 103 | <entry align="center">1</entry> | ||
| 104 | </row> | ||
| 105 | <row> | ||
| 106 | <entry></entry> | ||
| 107 | <entry></entry> | ||
| 108 | <entry><structfield>service_lines</structfield>[0][23]</entry> | ||
| 109 | <entry align="center">23</entry> | ||
| 110 | <entry align="center">23</entry> | ||
| 111 | </row> | ||
| 112 | <row> | ||
| 113 | <entry></entry> | ||
| 114 | <entry></entry> | ||
| 115 | <entry><structfield>service_lines</structfield>[1][1]</entry> | ||
| 116 | <entry align="center">264</entry> | ||
| 117 | <entry align="center">314</entry> | ||
| 118 | </row> | ||
| 119 | <row> | ||
| 120 | <entry></entry> | ||
| 121 | <entry></entry> | ||
| 122 | <entry><structfield>service_lines</structfield>[1][23]</entry> | ||
| 123 | <entry align="center">286</entry> | ||
| 124 | <entry align="center">336</entry> | ||
| 125 | </row> | ||
| 126 | <row> | ||
| 127 | <entry></entry> | ||
| 128 | </row> | ||
| 129 | <row> | ||
| 130 | <entry></entry> | ||
| 131 | <entry></entry> | ||
| 132 | <entry spanname="hspan">The number of VBI lines the | ||
| 133 | hardware can capture or output per frame, or the number of services it | ||
| 134 | can identify on a given line may be limited. For example on PAL line | ||
| 135 | 16 the hardware may be able to look for a VPS or Teletext signal, but | ||
| 136 | not both at the same time. Applications can learn about these limits | ||
| 137 | using the &VIDIOC-S-FMT; ioctl as described in <xref | ||
| 138 | linkend="sliced" />.</entry> | ||
| 139 | </row> | ||
| 140 | <row> | ||
| 141 | <entry></entry> | ||
| 142 | </row> | ||
| 143 | <row> | ||
| 144 | <entry></entry> | ||
| 145 | <entry></entry> | ||
| 146 | <entry spanname="hspan">Drivers must set | ||
| 147 | <structfield>service_lines</structfield>[0][0] and | ||
| 148 | <structfield>service_lines</structfield>[1][0] to zero.</entry> | ||
| 149 | </row> | ||
| 150 | <row> | ||
| 151 | <entry>&v4l2-buf-type;</entry> | ||
| 152 | <entry><structfield>type</structfield></entry> | ||
| 153 | <entry>Type of the data stream, see <xref | ||
| 154 | linkend="v4l2-buf-type" />. Should be | ||
| 155 | <constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or | ||
| 156 | <constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>.</entry> | ||
| 157 | </row> | ||
| 158 | <row> | ||
| 159 | <entry>__u32</entry> | ||
| 160 | <entry><structfield>reserved</structfield>[3]</entry> | ||
| 161 | <entry spanname="hspan">This array is reserved for future | ||
| 162 | extensions. Applications and drivers must set it to zero.</entry> | ||
| 163 | </row> | ||
| 164 | </tbody> | ||
| 165 | </tgroup> | ||
| 166 | </table> | ||
| 167 | |||
| 168 | <!-- See also dev-sliced-vbi.sgml --> | ||
| 169 | <table pgwide="1" frame="none" id="vbi-services"> | ||
| 170 | <title>Sliced VBI services</title> | ||
| 171 | <tgroup cols="5"> | ||
| 172 | <colspec colname="c1" colwidth="2*" /> | ||
| 173 | <colspec colname="c2" colwidth="1*" /> | ||
| 174 | <colspec colname="c3" colwidth="1*" /> | ||
| 175 | <colspec colname="c4" colwidth="2*" /> | ||
| 176 | <colspec colname="c5" colwidth="2*" /> | ||
| 177 | <spanspec spanname='rlp' namest='c3' nameend='c5' /> | ||
| 178 | <thead> | ||
| 179 | <row> | ||
| 180 | <entry>Symbol</entry> | ||
| 181 | <entry>Value</entry> | ||
| 182 | <entry>Reference</entry> | ||
| 183 | <entry>Lines, usually</entry> | ||
| 184 | <entry>Payload</entry> | ||
| 185 | </row> | ||
| 186 | </thead> | ||
| 187 | <tbody valign="top"> | ||
| 188 | <row> | ||
| 189 | <entry><constant>V4L2_SLICED_TELETEXT_B</constant> (Teletext | ||
| 190 | System B)</entry> | ||
| 191 | <entry>0x0001</entry> | ||
| 192 | <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry> | ||
| 193 | <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry> | ||
| 194 | <entry>Last 42 of the 45 byte Teletext packet, that is | ||
| 195 | without clock run-in and framing code, lsb first transmitted.</entry> | ||
| 196 | </row> | ||
| 197 | <row> | ||
| 198 | <entry><constant>V4L2_SLICED_VPS</constant></entry> | ||
| 199 | <entry>0x0400</entry> | ||
| 200 | <entry><xref linkend="ets300231" /></entry> | ||
| 201 | <entry>PAL line 16</entry> | ||
| 202 | <entry>Byte number 3 to 15 according to Figure 9 of | ||
| 203 | ETS 300 231, lsb first transmitted.</entry> | ||
| 204 | </row> | ||
| 205 | <row> | ||
| 206 | <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> | ||
| 207 | <entry>0x1000</entry> | ||
| 208 | <entry><xref linkend="eia608" /></entry> | ||
| 209 | <entry>NTSC line 21, 284 (second field 21)</entry> | ||
| 210 | <entry>Two bytes in transmission order, including parity | ||
| 211 | bit, lsb first transmitted.</entry> | ||
| 212 | </row> | ||
| 213 | <row> | ||
| 214 | <entry><constant>V4L2_SLICED_WSS_625</constant></entry> | ||
| 215 | <entry>0x4000</entry> | ||
| 216 | <entry><xref linkend="en300294" />, <xref linkend="itu1119" /></entry> | ||
| 217 | <entry>PAL/SECAM line 23</entry> | ||
| 218 | <entry><screen> | ||
| 219 | Byte 0 1 | ||
| 220 | msb lsb msb lsb | ||
| 221 | Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 | ||
| 222 | </screen></entry> | ||
| 223 | </row> | ||
| 224 | <row> | ||
| 225 | <entry><constant>V4L2_SLICED_VBI_525</constant></entry> | ||
| 226 | <entry>0x1000</entry> | ||
| 227 | <entry spanname="rlp">Set of services applicable to 525 | ||
| 228 | line systems.</entry> | ||
| 229 | </row> | ||
| 230 | <row> | ||
| 231 | <entry><constant>V4L2_SLICED_VBI_625</constant></entry> | ||
| 232 | <entry>0x4401</entry> | ||
| 233 | <entry spanname="rlp">Set of services applicable to 625 | ||
| 234 | line systems.</entry> | ||
| 235 | </row> | ||
| 236 | </tbody> | ||
| 237 | </tgroup> | ||
| 238 | </table> | ||
| 239 | |||
| 240 | </refsect1> | ||
| 241 | |||
| 242 | <refsect1> | ||
| 243 | &return-value; | ||
| 244 | |||
| 245 | <variablelist> | ||
| 246 | <varlistentry> | ||
| 247 | <term><errorcode>EINVAL</errorcode></term> | ||
| 248 | <listitem> | ||
| 249 | <para>The device does not support sliced VBI capturing or | ||
| 250 | output, or the value in the <structfield>type</structfield> field is | ||
| 251 | wrong.</para> | ||
| 252 | </listitem> | ||
| 253 | </varlistentry> | ||
| 254 | </variablelist> | ||
| 255 | </refsect1> | ||
| 256 | </refentry> | ||
| 257 | |||
| 258 | <!-- | ||
| 259 | Local Variables: | ||
| 260 | mode: sgml | ||
| 261 | sgml-parent-document: "v4l2.sgml" | ||
| 262 | indent-tabs-mode: nil | ||
| 263 | End: | ||
| 264 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-std.xml b/Documentation/DocBook/v4l/vidioc-g-std.xml new file mode 100644 index 000000000000..b6f5d267e856 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-std.xml | |||
| @@ -0,0 +1,99 @@ | |||
| 1 | <refentry id="vidioc-g-std"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_STD, VIDIOC_S_STD</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_STD</refname> | ||
| 9 | <refname>VIDIOC_S_STD</refname> | ||
| 10 | <refpurpose>Query or select the video standard of the current input</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>v4l2_std_id | ||
| 20 | *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | <funcsynopsis> | ||
| 24 | <funcprototype> | ||
| 25 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 28 | <paramdef>const v4l2_std_id | ||
| 29 | *<parameter>argp</parameter></paramdef> | ||
| 30 | </funcprototype> | ||
| 31 | </funcsynopsis> | ||
| 32 | </refsynopsisdiv> | ||
| 33 | |||
| 34 | <refsect1> | ||
| 35 | <title>Arguments</title> | ||
| 36 | |||
| 37 | <variablelist> | ||
| 38 | <varlistentry> | ||
| 39 | <term><parameter>fd</parameter></term> | ||
| 40 | <listitem> | ||
| 41 | <para>&fd;</para> | ||
| 42 | </listitem> | ||
| 43 | </varlistentry> | ||
| 44 | <varlistentry> | ||
| 45 | <term><parameter>request</parameter></term> | ||
| 46 | <listitem> | ||
| 47 | <para>VIDIOC_G_STD, VIDIOC_S_STD</para> | ||
| 48 | </listitem> | ||
| 49 | </varlistentry> | ||
| 50 | <varlistentry> | ||
| 51 | <term><parameter>argp</parameter></term> | ||
| 52 | <listitem> | ||
| 53 | <para></para> | ||
| 54 | </listitem> | ||
| 55 | </varlistentry> | ||
| 56 | </variablelist> | ||
| 57 | </refsect1> | ||
| 58 | |||
| 59 | <refsect1> | ||
| 60 | <title>Description</title> | ||
| 61 | |||
| 62 | <para>To query and select the current video standard applications | ||
| 63 | use the <constant>VIDIOC_G_STD</constant> and <constant>VIDIOC_S_STD</constant> ioctls which take a pointer to a | ||
| 64 | &v4l2-std-id; type as argument. <constant>VIDIOC_G_STD</constant> can | ||
| 65 | return a single flag or a set of flags as in &v4l2-standard; field | ||
| 66 | <structfield>id</structfield>. The flags must be unambiguous such | ||
| 67 | that they appear in only one enumerated <structname>v4l2_standard</structname> structure.</para> | ||
| 68 | |||
| 69 | <para><constant>VIDIOC_S_STD</constant> accepts one or more | ||
| 70 | flags, being a write-only ioctl it does not return the actual new standard as | ||
| 71 | <constant>VIDIOC_G_STD</constant> does. When no flags are given or | ||
| 72 | the current input does not support the requested standard the driver | ||
| 73 | returns an &EINVAL;. When the standard set is ambiguous drivers may | ||
| 74 | return <errorcode>EINVAL</errorcode> or choose any of the requested | ||
| 75 | standards.</para> | ||
| 76 | </refsect1> | ||
| 77 | |||
| 78 | <refsect1> | ||
| 79 | &return-value; | ||
| 80 | |||
| 81 | <variablelist> | ||
| 82 | <varlistentry> | ||
| 83 | <term><errorcode>EINVAL</errorcode></term> | ||
| 84 | <listitem> | ||
| 85 | <para>This ioctl is not supported, or the | ||
| 86 | <constant>VIDIOC_S_STD</constant> parameter was unsuitable.</para> | ||
| 87 | </listitem> | ||
| 88 | </varlistentry> | ||
| 89 | </variablelist> | ||
| 90 | </refsect1> | ||
| 91 | </refentry> | ||
| 92 | |||
| 93 | <!-- | ||
| 94 | Local Variables: | ||
| 95 | mode: sgml | ||
| 96 | sgml-parent-document: "v4l2.sgml" | ||
| 97 | indent-tabs-mode: nil | ||
| 98 | End: | ||
| 99 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/v4l/vidioc-g-tuner.xml new file mode 100644 index 000000000000..bd98c734c06b --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-tuner.xml | |||
| @@ -0,0 +1,535 @@ | |||
| 1 | <refentry id="vidioc-g-tuner"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_G_TUNER</refname> | ||
| 9 | <refname>VIDIOC_S_TUNER</refname> | ||
| 10 | <refpurpose>Get or set tuner attributes</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_tuner | ||
| 20 | *<parameter>argp</parameter></paramdef> | ||
| 21 | </funcprototype> | ||
| 22 | </funcsynopsis> | ||
| 23 | <funcsynopsis> | ||
| 24 | <funcprototype> | ||
| 25 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 28 | <paramdef>const struct v4l2_tuner | ||
| 29 | *<parameter>argp</parameter></paramdef> | ||
| 30 | </funcprototype> | ||
| 31 | </funcsynopsis> | ||
| 32 | </refsynopsisdiv> | ||
| 33 | |||
| 34 | <refsect1> | ||
| 35 | <title>Arguments</title> | ||
| 36 | |||
| 37 | <variablelist> | ||
| 38 | <varlistentry> | ||
| 39 | <term><parameter>fd</parameter></term> | ||
| 40 | <listitem> | ||
| 41 | <para>&fd;</para> | ||
| 42 | </listitem> | ||
| 43 | </varlistentry> | ||
| 44 | <varlistentry> | ||
| 45 | <term><parameter>request</parameter></term> | ||
| 46 | <listitem> | ||
| 47 | <para>VIDIOC_G_TUNER, VIDIOC_S_TUNER</para> | ||
| 48 | </listitem> | ||
| 49 | </varlistentry> | ||
| 50 | <varlistentry> | ||
| 51 | <term><parameter>argp</parameter></term> | ||
| 52 | <listitem> | ||
| 53 | <para></para> | ||
| 54 | </listitem> | ||
| 55 | </varlistentry> | ||
| 56 | </variablelist> | ||
| 57 | </refsect1> | ||
| 58 | |||
| 59 | <refsect1> | ||
| 60 | <title>Description</title> | ||
| 61 | |||
| 62 | <para>To query the attributes of a tuner applications initialize the | ||
| 63 | <structfield>index</structfield> field and zero out the | ||
| 64 | <structfield>reserved</structfield> array of a &v4l2-tuner; and call the | ||
| 65 | <constant>VIDIOC_G_TUNER</constant> ioctl with a pointer to this | ||
| 66 | structure. Drivers fill the rest of the structure or return an | ||
| 67 | &EINVAL; when the index is out of bounds. To enumerate all tuners | ||
| 68 | applications shall begin at index zero, incrementing by one until the | ||
| 69 | driver returns <errorcode>EINVAL</errorcode>.</para> | ||
| 70 | |||
| 71 | <para>Tuners have two writable properties, the audio mode and | ||
| 72 | the radio frequency. To change the audio mode, applications initialize | ||
| 73 | the <structfield>index</structfield>, | ||
| 74 | <structfield>audmode</structfield> and | ||
| 75 | <structfield>reserved</structfield> fields and call the | ||
| 76 | <constant>VIDIOC_S_TUNER</constant> ioctl. This will | ||
| 77 | <emphasis>not</emphasis> change the current tuner, which is determined | ||
| 78 | by the current video input. Drivers may choose a different audio mode | ||
| 79 | if the requested mode is invalid or unsupported. Since this is a | ||
| 80 | <!-- FIXME -->write-only ioctl, it does not return the actually | ||
| 81 | selected audio mode.</para> | ||
| 82 | |||
| 83 | <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl | ||
| 84 | is available.</para> | ||
| 85 | |||
| 86 | <table pgwide="1" frame="none" id="v4l2-tuner"> | ||
| 87 | <title>struct <structname>v4l2_tuner</structname></title> | ||
| 88 | <tgroup cols="3"> | ||
| 89 | <colspec colname="c1" colwidth="1*" /> | ||
| 90 | <colspec colname="c2" colwidth="1*" /> | ||
| 91 | <colspec colname="c3" colwidth="1*" /> | ||
| 92 | <colspec colname="c4" colwidth="1*" /> | ||
| 93 | <spanspec spanname="hspan" namest="c3" nameend="c4" /> | ||
| 94 | <tbody valign="top"> | ||
| 95 | <row> | ||
| 96 | <entry>__u32</entry> | ||
| 97 | <entry><structfield>index</structfield></entry> | ||
| 98 | <entry spanname="hspan">Identifies the tuner, set by the | ||
| 99 | application.</entry> | ||
| 100 | </row> | ||
| 101 | <row> | ||
| 102 | <entry>__u8</entry> | ||
| 103 | <entry><structfield>name</structfield>[32]</entry> | ||
| 104 | <entry spanname="hspan"><para>Name of the tuner, a | ||
| 105 | NUL-terminated ASCII string. This information is intended for the | ||
| 106 | user.<!-- FIXME Video inputs already have a name, the purpose of this | ||
| 107 | field is not quite clear.--></para></entry> | ||
| 108 | </row> | ||
| 109 | <row> | ||
| 110 | <entry>&v4l2-tuner-type;</entry> | ||
| 111 | <entry><structfield>type</structfield></entry> | ||
| 112 | <entry spanname="hspan">Type of the tuner, see <xref | ||
| 113 | linkend="v4l2-tuner-type" />.</entry> | ||
| 114 | </row> | ||
| 115 | <row> | ||
| 116 | <entry>__u32</entry> | ||
| 117 | <entry><structfield>capability</structfield></entry> | ||
| 118 | <entry spanname="hspan"><para>Tuner capability flags, see | ||
| 119 | <xref linkend="tuner-capability" />. Audio flags indicate the ability | ||
| 120 | to decode audio subprograms. They will <emphasis>not</emphasis> | ||
| 121 | change, for example with the current video standard.</para><para>When | ||
| 122 | the structure refers to a radio tuner only the | ||
| 123 | <constant>V4L2_TUNER_CAP_LOW</constant>, | ||
| 124 | <constant>V4L2_TUNER_CAP_STEREO</constant> and | ||
| 125 | <constant>V4L2_TUNER_CAP_RDS</constant> flags can be set.</para></entry> | ||
| 126 | </row> | ||
| 127 | <row> | ||
| 128 | <entry>__u32</entry> | ||
| 129 | <entry><structfield>rangelow</structfield></entry> | ||
| 130 | <entry spanname="hspan">The lowest tunable frequency in | ||
| 131 | units of 62.5 kHz, or if the <structfield>capability</structfield> | ||
| 132 | flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
| 133 | Hz.</entry> | ||
| 134 | </row> | ||
| 135 | <row> | ||
| 136 | <entry>__u32</entry> | ||
| 137 | <entry><structfield>rangehigh</structfield></entry> | ||
| 138 | <entry spanname="hspan">The highest tunable frequency in | ||
| 139 | units of 62.5 kHz, or if the <structfield>capability</structfield> | ||
| 140 | flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
| 141 | Hz.</entry> | ||
| 142 | </row> | ||
| 143 | <row> | ||
| 144 | <entry>__u32</entry> | ||
| 145 | <entry><structfield>rxsubchans</structfield></entry> | ||
| 146 | <entry spanname="hspan"><para>Some tuners or audio | ||
| 147 | decoders can determine the received audio subprograms by analyzing | ||
| 148 | audio carriers, pilot tones or other indicators. To pass this | ||
| 149 | information drivers set flags defined in <xref | ||
| 150 | linkend="tuner-rxsubchans" /> in this field. For | ||
| 151 | example:</para></entry> | ||
| 152 | </row> | ||
| 153 | <row> | ||
| 154 | <entry></entry> | ||
| 155 | <entry></entry> | ||
| 156 | <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> | ||
| 157 | <entry>receiving mono audio</entry> | ||
| 158 | </row> | ||
| 159 | <row> | ||
| 160 | <entry></entry> | ||
| 161 | <entry></entry> | ||
| 162 | <entry><constant>STEREO | SAP</constant></entry> | ||
| 163 | <entry>receiving stereo audio and a secondary audio | ||
| 164 | program</entry> | ||
| 165 | </row> | ||
| 166 | <row> | ||
| 167 | <entry></entry> | ||
| 168 | <entry></entry> | ||
| 169 | <entry><constant>MONO | STEREO</constant></entry> | ||
| 170 | <entry>receiving mono or stereo audio, the hardware cannot | ||
| 171 | distinguish</entry> | ||
| 172 | </row> | ||
| 173 | <row> | ||
| 174 | <entry></entry> | ||
| 175 | <entry></entry> | ||
| 176 | <entry><constant>LANG1 | LANG2</constant></entry> | ||
| 177 | <entry>receiving bilingual audio</entry> | ||
| 178 | </row> | ||
| 179 | <row> | ||
| 180 | <entry></entry> | ||
| 181 | <entry></entry> | ||
| 182 | <entry><constant>MONO | STEREO | LANG1 | LANG2</constant></entry> | ||
| 183 | <entry>receiving mono, stereo or bilingual | ||
| 184 | audio</entry> | ||
| 185 | </row> | ||
| 186 | <row> | ||
| 187 | <entry></entry> | ||
| 188 | <entry></entry> | ||
| 189 | <entry spanname="hspan"><para>When the | ||
| 190 | <constant>V4L2_TUNER_CAP_STEREO</constant>, | ||
| 191 | <constant>_LANG1</constant>, <constant>_LANG2</constant> or | ||
| 192 | <constant>_SAP</constant> flag is cleared in the | ||
| 193 | <structfield>capability</structfield> field, the corresponding | ||
| 194 | <constant>V4L2_TUNER_SUB_</constant> flag must not be set | ||
| 195 | here.</para><para>This field is valid only if this is the tuner of the | ||
| 196 | current video input, or when the structure refers to a radio | ||
| 197 | tuner.</para></entry> | ||
| 198 | </row> | ||
| 199 | <row> | ||
| 200 | <entry>__u32</entry> | ||
| 201 | <entry><structfield>audmode</structfield></entry> | ||
| 202 | <entry spanname="hspan"><para>The selected audio mode, see | ||
| 203 | <xref linkend="tuner-audmode" /> for valid values. The audio mode does | ||
| 204 | not affect audio subprogram detection, and like a <link | ||
| 205 | linkend="control">control</link> it does not automatically change | ||
| 206 | unless the requested mode is invalid or unsupported. See <xref | ||
| 207 | linkend="tuner-matrix" /> for possible results when | ||
| 208 | the selected and received audio programs do not | ||
| 209 | match.</para><para>Currently this is the only field of struct | ||
| 210 | <structname>v4l2_tuner</structname> applications can | ||
| 211 | change.</para></entry> | ||
| 212 | </row> | ||
| 213 | <row> | ||
| 214 | <entry>__u32</entry> | ||
| 215 | <entry><structfield>signal</structfield></entry> | ||
| 216 | <entry spanname="hspan">The signal strength if known, ranging | ||
| 217 | from 0 to 65535. Higher values indicate a better signal.</entry> | ||
| 218 | </row> | ||
| 219 | <row> | ||
| 220 | <entry>__s32</entry> | ||
| 221 | <entry><structfield>afc</structfield></entry> | ||
| 222 | <entry spanname="hspan">Automatic frequency control: When the | ||
| 223 | <structfield>afc</structfield> value is negative, the frequency is too | ||
| 224 | low, when positive too high.<!-- FIXME need example what to do when it never | ||
| 225 | settles at zero, &ie; range is what? --></entry> | ||
| 226 | </row> | ||
| 227 | <row> | ||
| 228 | <entry>__u32</entry> | ||
| 229 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 230 | <entry spanname="hspan">Reserved for future extensions. Drivers and | ||
| 231 | applications must set the array to zero.</entry> | ||
| 232 | </row> | ||
| 233 | </tbody> | ||
| 234 | </tgroup> | ||
| 235 | </table> | ||
| 236 | |||
| 237 | <table pgwide="1" frame="none" id="v4l2-tuner-type"> | ||
| 238 | <title>enum v4l2_tuner_type</title> | ||
| 239 | <tgroup cols="3"> | ||
| 240 | &cs-def; | ||
| 241 | <tbody valign="top"> | ||
| 242 | <row> | ||
| 243 | <entry><constant>V4L2_TUNER_RADIO</constant></entry> | ||
| 244 | <entry>1</entry> | ||
| 245 | <entry></entry> | ||
| 246 | </row> | ||
| 247 | <row> | ||
| 248 | <entry><constant>V4L2_TUNER_ANALOG_TV</constant></entry> | ||
| 249 | <entry>2</entry> | ||
| 250 | <entry></entry> | ||
| 251 | </row> | ||
| 252 | </tbody> | ||
| 253 | </tgroup> | ||
| 254 | </table> | ||
| 255 | |||
| 256 | <table pgwide="1" frame="none" id="tuner-capability"> | ||
| 257 | <title>Tuner and Modulator Capability Flags</title> | ||
| 258 | <tgroup cols="3"> | ||
| 259 | &cs-def; | ||
| 260 | <tbody valign="top"> | ||
| 261 | <row> | ||
| 262 | <entry><constant>V4L2_TUNER_CAP_LOW</constant></entry> | ||
| 263 | <entry>0x0001</entry> | ||
| 264 | <entry>When set, tuning frequencies are expressed in units of | ||
| 265 | 62.5 Hz, otherwise in units of 62.5 kHz.</entry> | ||
| 266 | </row> | ||
| 267 | <row> | ||
| 268 | <entry><constant>V4L2_TUNER_CAP_NORM</constant></entry> | ||
| 269 | <entry>0x0002</entry> | ||
| 270 | <entry>This is a multi-standard tuner; the video standard | ||
| 271 | can or must be switched. (B/G PAL tuners for example are typically not | ||
| 272 | considered multi-standard because the video standard is automatically | ||
| 273 | determined from the frequency band.) The set of supported video | ||
| 274 | standards is available from the &v4l2-input; pointing to this tuner, | ||
| 275 | see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only | ||
| 276 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> | ||
| 277 | </row> | ||
| 278 | <row> | ||
| 279 | <entry><constant>V4L2_TUNER_CAP_STEREO</constant></entry> | ||
| 280 | <entry>0x0010</entry> | ||
| 281 | <entry>Stereo audio reception is supported.</entry> | ||
| 282 | </row> | ||
| 283 | <row> | ||
| 284 | <entry><constant>V4L2_TUNER_CAP_LANG1</constant></entry> | ||
| 285 | <entry>0x0040</entry> | ||
| 286 | <entry>Reception of the primary language of a bilingual | ||
| 287 | audio program is supported. Bilingual audio is a feature of | ||
| 288 | two-channel systems, transmitting the primary language monaural on the | ||
| 289 | main audio carrier and a secondary language monaural on a second | ||
| 290 | carrier. Only | ||
| 291 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> | ||
| 292 | </row> | ||
| 293 | <row> | ||
| 294 | <entry><constant>V4L2_TUNER_CAP_LANG2</constant></entry> | ||
| 295 | <entry>0x0020</entry> | ||
| 296 | <entry>Reception of the secondary language of a bilingual | ||
| 297 | audio program is supported. Only | ||
| 298 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> | ||
| 299 | </row> | ||
| 300 | <row> | ||
| 301 | <entry><constant>V4L2_TUNER_CAP_SAP</constant></entry> | ||
| 302 | <entry>0x0020</entry> | ||
| 303 | <entry><para>Reception of a secondary audio program is | ||
| 304 | supported. This is a feature of the BTSC system which accompanies the | ||
| 305 | NTSC video standard. Two audio carriers are available for mono or | ||
| 306 | stereo transmissions of a primary language, and an independent third | ||
| 307 | carrier for a monaural secondary language. Only | ||
| 308 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</para><para>Note the | ||
| 309 | <constant>V4L2_TUNER_CAP_LANG2</constant> and | ||
| 310 | <constant>V4L2_TUNER_CAP_SAP</constant> flags are synonyms. | ||
| 311 | <constant>V4L2_TUNER_CAP_SAP</constant> applies when the tuner | ||
| 312 | supports the <constant>V4L2_STD_NTSC_M</constant> video | ||
| 313 | standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry> | ||
| 314 | </row> | ||
| 315 | <row> | ||
| 316 | <entry><constant>V4L2_TUNER_CAP_RDS</constant></entry> | ||
| 317 | <entry>0x0080</entry> | ||
| 318 | <entry>RDS capture is supported. This capability is only valid for | ||
| 319 | radio tuners.</entry> | ||
| 320 | </row> | ||
| 321 | </tbody> | ||
| 322 | </tgroup> | ||
| 323 | </table> | ||
| 324 | |||
| 325 | <table pgwide="1" frame="none" id="tuner-rxsubchans"> | ||
| 326 | <title>Tuner Audio Reception Flags</title> | ||
| 327 | <tgroup cols="3"> | ||
| 328 | &cs-def; | ||
| 329 | <tbody valign="top"> | ||
| 330 | <row> | ||
| 331 | <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> | ||
| 332 | <entry>0x0001</entry> | ||
| 333 | <entry>The tuner receives a mono audio signal.</entry> | ||
| 334 | </row> | ||
| 335 | <row> | ||
| 336 | <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry> | ||
| 337 | <entry>0x0002</entry> | ||
| 338 | <entry>The tuner receives a stereo audio signal.</entry> | ||
| 339 | </row> | ||
| 340 | <row> | ||
| 341 | <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry> | ||
| 342 | <entry>0x0008</entry> | ||
| 343 | <entry>The tuner receives the primary language of a | ||
| 344 | bilingual audio signal. Drivers must clear this flag when the current | ||
| 345 | video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry> | ||
| 346 | </row> | ||
| 347 | <row> | ||
| 348 | <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> | ||
| 349 | <entry>0x0004</entry> | ||
| 350 | <entry>The tuner receives the secondary language of a | ||
| 351 | bilingual audio signal (or a second audio program).</entry> | ||
| 352 | </row> | ||
| 353 | <row> | ||
| 354 | <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> | ||
| 355 | <entry>0x0004</entry> | ||
| 356 | <entry>The tuner receives a Second Audio Program. Note the | ||
| 357 | <constant>V4L2_TUNER_SUB_LANG2</constant> and | ||
| 358 | <constant>V4L2_TUNER_SUB_SAP</constant> flags are synonyms. The | ||
| 359 | <constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the | ||
| 360 | current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry> | ||
| 361 | </row> | ||
| 362 | <row> | ||
| 363 | <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> | ||
| 364 | <entry>0x0010</entry> | ||
| 365 | <entry>The tuner receives an RDS channel.</entry> | ||
| 366 | </row> | ||
| 367 | </tbody> | ||
| 368 | </tgroup> | ||
| 369 | </table> | ||
| 370 | |||
| 371 | <table pgwide="1" frame="none" id="tuner-audmode"> | ||
| 372 | <title>Tuner Audio Modes</title> | ||
| 373 | <tgroup cols="3"> | ||
| 374 | &cs-def; | ||
| 375 | <tbody valign="top"> | ||
| 376 | <row> | ||
| 377 | <entry><constant>V4L2_TUNER_MODE_MONO</constant></entry> | ||
| 378 | <entry>0</entry> | ||
| 379 | <entry>Play mono audio. When the tuner receives a stereo | ||
| 380 | signal this a down-mix of the left and right channel. When the tuner | ||
| 381 | receives a bilingual or SAP signal this mode selects the primary | ||
| 382 | language.</entry> | ||
| 383 | </row> | ||
| 384 | <row> | ||
| 385 | <entry><constant>V4L2_TUNER_MODE_STEREO</constant></entry> | ||
| 386 | <entry>1</entry> | ||
| 387 | <entry><para>Play stereo audio. When the tuner receives | ||
| 388 | bilingual audio it may play different languages on the left and right | ||
| 389 | channel or the primary language is played on both channels.</para><para>Playing | ||
| 390 | different languages in this mode is | ||
| 391 | deprecated. New drivers should do this only in | ||
| 392 | <constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner | ||
| 393 | receives no stereo signal or does not support stereo reception the | ||
| 394 | driver shall fall back to <constant>MODE_MONO</constant>.</para></entry> | ||
| 395 | </row> | ||
| 396 | <row> | ||
| 397 | <entry><constant>V4L2_TUNER_MODE_LANG1</constant></entry> | ||
| 398 | <entry>3</entry> | ||
| 399 | <entry>Play the primary language, mono or stereo. Only | ||
| 400 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this | ||
| 401 | mode.</entry> | ||
| 402 | </row> | ||
| 403 | <row> | ||
| 404 | <entry><constant>V4L2_TUNER_MODE_LANG2</constant></entry> | ||
| 405 | <entry>2</entry> | ||
| 406 | <entry>Play the secondary language, mono. When the tuner | ||
| 407 | receives no bilingual audio or SAP, or their reception is not | ||
| 408 | supported the driver shall fall back to mono or stereo mode. Only | ||
| 409 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this | ||
| 410 | mode.</entry> | ||
| 411 | </row> | ||
| 412 | <row> | ||
| 413 | <entry><constant>V4L2_TUNER_MODE_SAP</constant></entry> | ||
| 414 | <entry>2</entry> | ||
| 415 | <entry>Play the Second Audio Program. When the tuner | ||
| 416 | receives no bilingual audio or SAP, or their reception is not | ||
| 417 | supported the driver shall fall back to mono or stereo mode. Only | ||
| 418 | <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode. | ||
| 419 | Note the <constant>V4L2_TUNER_MODE_LANG2</constant> and | ||
| 420 | <constant>V4L2_TUNER_MODE_SAP</constant> are synonyms.</entry> | ||
| 421 | </row> | ||
| 422 | <row> | ||
| 423 | <entry><constant>V4L2_TUNER_MODE_LANG1_LANG2</constant></entry> | ||
| 424 | <entry>4</entry> | ||
| 425 | <entry>Play the primary language on the left channel, the | ||
| 426 | secondary language on the right channel. When the tuner receives no | ||
| 427 | bilingual audio or SAP, it shall fall back to | ||
| 428 | <constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>. | ||
| 429 | Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this | ||
| 430 | mode.</entry> | ||
| 431 | </row> | ||
| 432 | </tbody> | ||
| 433 | </tgroup> | ||
| 434 | </table> | ||
| 435 | |||
| 436 | <table pgwide="1" frame="all" id="tuner-matrix"> | ||
| 437 | <title>Tuner Audio Matrix</title> | ||
| 438 | <tgroup cols="6" align="center"> | ||
| 439 | <colspec align="left" /> | ||
| 440 | <colspec colname="c2" colwidth="1*" /> | ||
| 441 | <colspec colwidth="1*" /> | ||
| 442 | <colspec colwidth="1*" /> | ||
| 443 | <colspec colnum="6" colname="c6" colwidth="1*" /> | ||
| 444 | <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" /> | ||
| 445 | <thead> | ||
| 446 | <row> | ||
| 447 | <entry></entry> | ||
| 448 | <entry spanname="hspan">Selected | ||
| 449 | <constant>V4L2_TUNER_MODE_</constant></entry> | ||
| 450 | </row> | ||
| 451 | <row> | ||
| 452 | <entry>Received <constant>V4L2_TUNER_SUB_</constant></entry> | ||
| 453 | <entry><constant>MONO</constant></entry> | ||
| 454 | <entry><constant>STEREO</constant></entry> | ||
| 455 | <entry><constant>LANG1</constant></entry> | ||
| 456 | <entry><constant>LANG2 = SAP</constant></entry> | ||
| 457 | <entry><constant>LANG1_LANG2</constant><footnote><para>This | ||
| 458 | mode has been added in Linux 2.6.17 and may not be supported by older | ||
| 459 | drivers.</para></footnote></entry> | ||
| 460 | </row> | ||
| 461 | </thead> | ||
| 462 | <tbody valign="top"> | ||
| 463 | <row> | ||
| 464 | <entry><constant>MONO</constant></entry> | ||
| 465 | <entry>Mono</entry> | ||
| 466 | <entry>Mono/Mono</entry> | ||
| 467 | <entry>Mono</entry> | ||
| 468 | <entry>Mono</entry> | ||
| 469 | <entry>Mono/Mono</entry> | ||
| 470 | </row> | ||
| 471 | <row> | ||
| 472 | <entry><constant>MONO | SAP</constant></entry> | ||
| 473 | <entry>Mono</entry> | ||
| 474 | <entry>Mono/Mono</entry> | ||
| 475 | <entry>Mono</entry> | ||
| 476 | <entry>SAP</entry> | ||
| 477 | <entry>Mono/SAP (preferred) or Mono/Mono</entry> | ||
| 478 | </row> | ||
| 479 | <row> | ||
| 480 | <entry><constant>STEREO</constant></entry> | ||
| 481 | <entry>L+R</entry> | ||
| 482 | <entry>L/R</entry> | ||
| 483 | <entry>Stereo L/R (preferred) or Mono L+R</entry> | ||
| 484 | <entry>Stereo L/R (preferred) or Mono L+R</entry> | ||
| 485 | <entry>L/R (preferred) or L+R/L+R</entry> | ||
| 486 | </row> | ||
| 487 | <row> | ||
| 488 | <entry><constant>STEREO | SAP</constant></entry> | ||
| 489 | <entry>L+R</entry> | ||
| 490 | <entry>L/R</entry> | ||
| 491 | <entry>Stereo L/R (preferred) or Mono L+R</entry> | ||
| 492 | <entry>SAP</entry> | ||
| 493 | <entry>L+R/SAP (preferred) or L/R or L+R/L+R</entry> | ||
| 494 | </row> | ||
| 495 | <row> | ||
| 496 | <entry><constant>LANG1 | LANG2</constant></entry> | ||
| 497 | <entry>Language 1</entry> | ||
| 498 | <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of | ||
| 499 | both languages in <constant>MODE_STEREO</constant> is deprecated. In | ||
| 500 | the future drivers should produce only the primary language in this | ||
| 501 | mode. Applications should request | ||
| 502 | <constant>MODE_LANG1_LANG2</constant> to record both languages or a | ||
| 503 | stereo signal.</para></footnote>) or | ||
| 504 | Lang1/Lang1</entry> | ||
| 505 | <entry>Language 1</entry> | ||
| 506 | <entry>Language 2</entry> | ||
| 507 | <entry>Lang1/Lang2 (preferred) or Lang1/Lang1</entry> | ||
| 508 | </row> | ||
| 509 | </tbody> | ||
| 510 | </tgroup> | ||
| 511 | </table> | ||
| 512 | </refsect1> | ||
| 513 | |||
| 514 | <refsect1> | ||
| 515 | &return-value; | ||
| 516 | |||
| 517 | <variablelist> | ||
| 518 | <varlistentry> | ||
| 519 | <term><errorcode>EINVAL</errorcode></term> | ||
| 520 | <listitem> | ||
| 521 | <para>The &v4l2-tuner; <structfield>index</structfield> is | ||
| 522 | out of bounds.</para> | ||
| 523 | </listitem> | ||
| 524 | </varlistentry> | ||
| 525 | </variablelist> | ||
| 526 | </refsect1> | ||
| 527 | </refentry> | ||
| 528 | |||
| 529 | <!-- | ||
| 530 | Local Variables: | ||
| 531 | mode: sgml | ||
| 532 | sgml-parent-document: "v4l2.sgml" | ||
| 533 | indent-tabs-mode: nil | ||
| 534 | End: | ||
| 535 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-log-status.xml b/Documentation/DocBook/v4l/vidioc-log-status.xml new file mode 100644 index 000000000000..2634b7c88b58 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-log-status.xml | |||
| @@ -0,0 +1,58 @@ | |||
| 1 | <refentry id="vidioc-log-status"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_LOG_STATUS</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_LOG_STATUS</refname> | ||
| 9 | <refpurpose>Log driver status information</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | </funcprototype> | ||
| 19 | </funcsynopsis> | ||
| 20 | </refsynopsisdiv> | ||
| 21 | |||
| 22 | <refsect1> | ||
| 23 | <title>Description</title> | ||
| 24 | |||
| 25 | <para>As the video/audio devices become more complicated it | ||
| 26 | becomes harder to debug problems. When this ioctl is called the driver | ||
| 27 | will output the current device status to the kernel log. This is | ||
| 28 | particular useful when dealing with problems like no sound, no video | ||
| 29 | and incorrectly tuned channels. Also many modern devices autodetect | ||
| 30 | video and audio standards and this ioctl will report what the device | ||
| 31 | thinks what the standard is. Mismatches may give an indication where | ||
| 32 | the problem is.</para> | ||
| 33 | |||
| 34 | <para>This ioctl is optional and not all drivers support it. It | ||
| 35 | was introduced in Linux 2.6.15.</para> | ||
| 36 | </refsect1> | ||
| 37 | |||
| 38 | <refsect1> | ||
| 39 | &return-value; | ||
| 40 | |||
| 41 | <variablelist> | ||
| 42 | <varlistentry> | ||
| 43 | <term><errorcode>EINVAL</errorcode></term> | ||
| 44 | <listitem> | ||
| 45 | <para>The driver does not support this ioctl.</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | </variablelist> | ||
| 49 | </refsect1> | ||
| 50 | </refentry> | ||
| 51 | |||
| 52 | <!-- | ||
| 53 | Local Variables: | ||
| 54 | mode: sgml | ||
| 55 | sgml-parent-document: "v4l2.sgml" | ||
| 56 | indent-tabs-mode: nil | ||
| 57 | End: | ||
| 58 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-overlay.xml b/Documentation/DocBook/v4l/vidioc-overlay.xml new file mode 100644 index 000000000000..1036c582cc15 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-overlay.xml | |||
| @@ -0,0 +1,83 @@ | |||
| 1 | <refentry id="vidioc-overlay"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_OVERLAY</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_OVERLAY</refname> | ||
| 9 | <refpurpose>Start or stop video overlay</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>const int *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_OVERLAY</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>This ioctl is part of the <link linkend="overlay">video | ||
| 52 | overlay</link> I/O method. Applications call | ||
| 53 | <constant>VIDIOC_OVERLAY</constant> to start or stop the | ||
| 54 | overlay. It takes a pointer to an integer which must be set to | ||
| 55 | zero by the application to stop overlay, to one to start.</para> | ||
| 56 | |||
| 57 | <para>Drivers do not support &VIDIOC-STREAMON; or | ||
| 58 | &VIDIOC-STREAMOFF; with <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para> | ||
| 59 | </refsect1> | ||
| 60 | |||
| 61 | <refsect1> | ||
| 62 | &return-value; | ||
| 63 | |||
| 64 | <variablelist> | ||
| 65 | <varlistentry> | ||
| 66 | <term><errorcode>EINVAL</errorcode></term> | ||
| 67 | <listitem> | ||
| 68 | <para>Video overlay is not supported, or the | ||
| 69 | parameters have not been set up. See <xref | ||
| 70 | linkend="overlay" /> for the necessary steps.</para> | ||
| 71 | </listitem> | ||
| 72 | </varlistentry> | ||
| 73 | </variablelist> | ||
| 74 | </refsect1> | ||
| 75 | </refentry> | ||
| 76 | |||
| 77 | <!-- | ||
| 78 | Local Variables: | ||
| 79 | mode: sgml | ||
| 80 | sgml-parent-document: "v4l2.sgml" | ||
| 81 | indent-tabs-mode: nil | ||
| 82 | End: | ||
| 83 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml new file mode 100644 index 000000000000..187081778154 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml | |||
| @@ -0,0 +1,168 @@ | |||
| 1 | <refentry id="vidioc-qbuf"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_QBUF</refname> | ||
| 9 | <refname>VIDIOC_DQBUF</refname> | ||
| 10 | <refpurpose>Exchange a buffer with the driver</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_QBUF, VIDIOC_DQBUF</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>Applications call the <constant>VIDIOC_QBUF</constant> ioctl | ||
| 53 | to enqueue an empty (capturing) or filled (output) buffer in the | ||
| 54 | driver's incoming queue. The semantics depend on the selected I/O | ||
| 55 | method.</para> | ||
| 56 | |||
| 57 | <para>To enqueue a <link linkend="mmap">memory mapped</link> | ||
| 58 | buffer applications set the <structfield>type</structfield> field of a | ||
| 59 | &v4l2-buffer; to the same buffer type as previously &v4l2-format; | ||
| 60 | <structfield>type</structfield> and &v4l2-requestbuffers; | ||
| 61 | <structfield>type</structfield>, the <structfield>memory</structfield> | ||
| 62 | field to <constant>V4L2_MEMORY_MMAP</constant> and the | ||
| 63 | <structfield>index</structfield> field. Valid index numbers range from | ||
| 64 | zero to the number of buffers allocated with &VIDIOC-REQBUFS; | ||
| 65 | (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The | ||
| 66 | contents of the struct <structname>v4l2_buffer</structname> returned | ||
| 67 | by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is | ||
| 68 | intended for output (<structfield>type</structfield> is | ||
| 69 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or | ||
| 70 | <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also | ||
| 71 | initialize the <structfield>bytesused</structfield>, | ||
| 72 | <structfield>field</structfield> and | ||
| 73 | <structfield>timestamp</structfield> fields. See <xref | ||
| 74 | linkend="buffer" /> for details. When | ||
| 75 | <constant>VIDIOC_QBUF</constant> is called with a pointer to this | ||
| 76 | structure the driver sets the | ||
| 77 | <constant>V4L2_BUF_FLAG_MAPPED</constant> and | ||
| 78 | <constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the | ||
| 79 | <constant>V4L2_BUF_FLAG_DONE</constant> flag in the | ||
| 80 | <structfield>flags</structfield> field, or it returns an | ||
| 81 | &EINVAL;.</para> | ||
| 82 | |||
| 83 | <para>To enqueue a <link linkend="userp">user pointer</link> | ||
| 84 | buffer applications set the <structfield>type</structfield> field of a | ||
| 85 | &v4l2-buffer; to the same buffer type as previously &v4l2-format; | ||
| 86 | <structfield>type</structfield> and &v4l2-requestbuffers; | ||
| 87 | <structfield>type</structfield>, the <structfield>memory</structfield> | ||
| 88 | field to <constant>V4L2_MEMORY_USERPTR</constant> and the | ||
| 89 | <structfield>m.userptr</structfield> field to the address of the | ||
| 90 | buffer and <structfield>length</structfield> to its size. When the | ||
| 91 | buffer is intended for output additional fields must be set as above. | ||
| 92 | When <constant>VIDIOC_QBUF</constant> is called with a pointer to this | ||
| 93 | structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> | ||
| 94 | flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and | ||
| 95 | <constant>V4L2_BUF_FLAG_DONE</constant> flags in the | ||
| 96 | <structfield>flags</structfield> field, or it returns an error code. | ||
| 97 | This ioctl locks the memory pages of the buffer in physical memory, | ||
| 98 | they cannot be swapped out to disk. Buffers remain locked until | ||
| 99 | dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl are | ||
| 100 | called, or until the device is closed.</para> | ||
| 101 | |||
| 102 | <para>Applications call the <constant>VIDIOC_DQBUF</constant> | ||
| 103 | ioctl to dequeue a filled (capturing) or displayed (output) buffer | ||
| 104 | from the driver's outgoing queue. They just set the | ||
| 105 | <structfield>type</structfield> and <structfield>memory</structfield> | ||
| 106 | fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant> | ||
| 107 | is called with a pointer to this structure the driver fills the | ||
| 108 | remaining fields or returns an error code.</para> | ||
| 109 | |||
| 110 | <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no | ||
| 111 | buffer is in the outgoing queue. When the | ||
| 112 | <constant>O_NONBLOCK</constant> flag was given to the &func-open; | ||
| 113 | function, <constant>VIDIOC_DQBUF</constant> returns immediately | ||
| 114 | with an &EAGAIN; when no buffer is available.</para> | ||
| 115 | |||
| 116 | <para>The <structname>v4l2_buffer</structname> structure is | ||
| 117 | specified in <xref linkend="buffer" />.</para> | ||
| 118 | </refsect1> | ||
| 119 | |||
| 120 | <refsect1> | ||
| 121 | &return-value; | ||
| 122 | |||
| 123 | <variablelist> | ||
| 124 | <varlistentry> | ||
| 125 | <term><errorcode>EAGAIN</errorcode></term> | ||
| 126 | <listitem> | ||
| 127 | <para>Non-blocking I/O has been selected using | ||
| 128 | <constant>O_NONBLOCK</constant> and no buffer was in the outgoing | ||
| 129 | queue.</para> | ||
| 130 | </listitem> | ||
| 131 | </varlistentry> | ||
| 132 | <varlistentry> | ||
| 133 | <term><errorcode>EINVAL</errorcode></term> | ||
| 134 | <listitem> | ||
| 135 | <para>The buffer <structfield>type</structfield> is not | ||
| 136 | supported, or the <structfield>index</structfield> is out of bounds, | ||
| 137 | or no buffers have been allocated yet, or the | ||
| 138 | <structfield>userptr</structfield> or | ||
| 139 | <structfield>length</structfield> are invalid.</para> | ||
| 140 | </listitem> | ||
| 141 | </varlistentry> | ||
| 142 | <varlistentry> | ||
| 143 | <term><errorcode>ENOMEM</errorcode></term> | ||
| 144 | <listitem> | ||
| 145 | <para>Not enough physical or virtual memory was available to | ||
| 146 | enqueue a user pointer buffer.</para> | ||
| 147 | </listitem> | ||
| 148 | </varlistentry> | ||
| 149 | <varlistentry> | ||
| 150 | <term><errorcode>EIO</errorcode></term> | ||
| 151 | <listitem> | ||
| 152 | <para><constant>VIDIOC_DQBUF</constant> failed due to an | ||
| 153 | internal error. Can also indicate temporary problems like signal | ||
| 154 | loss. Note the driver might dequeue an (empty) buffer despite | ||
| 155 | returning an error, or even stop capturing.</para> | ||
| 156 | </listitem> | ||
| 157 | </varlistentry> | ||
| 158 | </variablelist> | ||
| 159 | </refsect1> | ||
| 160 | </refentry> | ||
| 161 | |||
| 162 | <!-- | ||
| 163 | Local Variables: | ||
| 164 | mode: sgml | ||
| 165 | sgml-parent-document: "v4l2.sgml" | ||
| 166 | indent-tabs-mode: nil | ||
| 167 | End: | ||
| 168 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-querybuf.xml b/Documentation/DocBook/v4l/vidioc-querybuf.xml new file mode 100644 index 000000000000..d834993e6191 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-querybuf.xml | |||
| @@ -0,0 +1,103 @@ | |||
| 1 | <refentry id="vidioc-querybuf"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_QUERYBUF</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_QUERYBUF</refname> | ||
| 9 | <refpurpose>Query the status of a buffer</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_QUERYBUF</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>This ioctl is part of the <link linkend="mmap">memory | ||
| 52 | mapping</link> I/O method. It can be used to query the status of a | ||
| 53 | buffer at any time after buffers have been allocated with the | ||
| 54 | &VIDIOC-REQBUFS; ioctl.</para> | ||
| 55 | |||
| 56 | <para>Applications set the <structfield>type</structfield> field | ||
| 57 | of a &v4l2-buffer; to the same buffer type as previously | ||
| 58 | &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers; | ||
| 59 | <structfield>type</structfield>, and the <structfield>index</structfield> | ||
| 60 | field. Valid index numbers range from zero | ||
| 61 | to the number of buffers allocated with &VIDIOC-REQBUFS; | ||
| 62 | (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. | ||
| 63 | After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to | ||
| 64 | this structure drivers return an error code or fill the rest of | ||
| 65 | the structure.</para> | ||
| 66 | |||
| 67 | <para>In the <structfield>flags</structfield> field the | ||
| 68 | <constant>V4L2_BUF_FLAG_MAPPED</constant>, | ||
| 69 | <constant>V4L2_BUF_FLAG_QUEUED</constant> and | ||
| 70 | <constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The | ||
| 71 | <structfield>memory</structfield> field will be set to | ||
| 72 | <constant>V4L2_MEMORY_MMAP</constant>, the <structfield>m.offset</structfield> | ||
| 73 | contains the offset of the buffer from the start of the device memory, | ||
| 74 | the <structfield>length</structfield> field its size. The driver may | ||
| 75 | or may not set the remaining fields and flags, they are meaningless in | ||
| 76 | this context.</para> | ||
| 77 | |||
| 78 | <para>The <structname>v4l2_buffer</structname> structure is | ||
| 79 | specified in <xref linkend="buffer" />.</para> | ||
| 80 | </refsect1> | ||
| 81 | |||
| 82 | <refsect1> | ||
| 83 | &return-value; | ||
| 84 | |||
| 85 | <variablelist> | ||
| 86 | <varlistentry> | ||
| 87 | <term><errorcode>EINVAL</errorcode></term> | ||
| 88 | <listitem> | ||
| 89 | <para>The buffer <structfield>type</structfield> is not | ||
| 90 | supported, or the <structfield>index</structfield> is out of bounds.</para> | ||
| 91 | </listitem> | ||
| 92 | </varlistentry> | ||
| 93 | </variablelist> | ||
| 94 | </refsect1> | ||
| 95 | </refentry> | ||
| 96 | |||
| 97 | <!-- | ||
| 98 | Local Variables: | ||
| 99 | mode: sgml | ||
| 100 | sgml-parent-document: "v4l2.sgml" | ||
| 101 | indent-tabs-mode: nil | ||
| 102 | End: | ||
| 103 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-querycap.xml b/Documentation/DocBook/v4l/vidioc-querycap.xml new file mode 100644 index 000000000000..6ab7e25b31b6 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-querycap.xml | |||
| @@ -0,0 +1,284 @@ | |||
| 1 | <refentry id="vidioc-querycap"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_QUERYCAP</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_QUERYCAP</refname> | ||
| 9 | <refpurpose>Query device capabilities</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_capability *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_QUERYCAP</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>All V4L2 devices support the | ||
| 52 | <constant>VIDIOC_QUERYCAP</constant> ioctl. It is used to identify | ||
| 53 | kernel devices compatible with this specification and to obtain | ||
| 54 | information about driver and hardware capabilities. The ioctl takes a | ||
| 55 | pointer to a &v4l2-capability; which is filled by the driver. When the | ||
| 56 | driver is not compatible with this specification the ioctl returns an | ||
| 57 | &EINVAL;.</para> | ||
| 58 | |||
| 59 | <table pgwide="1" frame="none" id="v4l2-capability"> | ||
| 60 | <title>struct <structname>v4l2_capability</structname></title> | ||
| 61 | <tgroup cols="3"> | ||
| 62 | &cs-str; | ||
| 63 | <tbody valign="top"> | ||
| 64 | <row> | ||
| 65 | <entry>__u8</entry> | ||
| 66 | <entry><structfield>driver</structfield>[16]</entry> | ||
| 67 | <entry><para>Name of the driver, a unique NUL-terminated | ||
| 68 | ASCII string. For example: "bttv". Driver specific applications can | ||
| 69 | use this information to verify the driver identity. It is also useful | ||
| 70 | to work around known bugs, or to identify drivers in error reports. | ||
| 71 | The driver version is stored in the <structfield>version</structfield> | ||
| 72 | field.</para><para>Storing strings in fixed sized arrays is bad | ||
| 73 | practice but unavoidable here. Drivers and applications should take | ||
| 74 | precautions to never read or write beyond the end of the array and to | ||
| 75 | make sure the strings are properly NUL-terminated.</para></entry> | ||
| 76 | </row> | ||
| 77 | <row> | ||
| 78 | <entry>__u8</entry> | ||
| 79 | <entry><structfield>card</structfield>[32]</entry> | ||
| 80 | <entry>Name of the device, a NUL-terminated ASCII string. | ||
| 81 | For example: "Yoyodyne TV/FM". One driver may support different brands | ||
| 82 | or models of video hardware. This information is intended for users, | ||
| 83 | for example in a menu of available devices. Since multiple TV cards of | ||
| 84 | the same brand may be installed which are supported by the same | ||
| 85 | driver, this name should be combined with the character device file | ||
| 86 | name (⪚ <filename>/dev/video2</filename>) or the | ||
| 87 | <structfield>bus_info</structfield> string to avoid | ||
| 88 | ambiguities.</entry> | ||
| 89 | </row> | ||
| 90 | <row> | ||
| 91 | <entry>__u8</entry> | ||
| 92 | <entry><structfield>bus_info</structfield>[32]</entry> | ||
| 93 | <entry>Location of the device in the system, a | ||
| 94 | NUL-terminated ASCII string. For example: "PCI Slot 4". This | ||
| 95 | information is intended for users, to distinguish multiple | ||
| 96 | identical devices. If no such information is available the field may | ||
| 97 | simply count the devices controlled by the driver, or contain the | ||
| 98 | empty string (<structfield>bus_info</structfield>[0] = 0).<!-- XXX pci_dev->slot_name example --></entry> | ||
| 99 | </row> | ||
| 100 | <row> | ||
| 101 | <entry>__u32</entry> | ||
| 102 | <entry><structfield>version</structfield></entry> | ||
| 103 | <entry><para>Version number of the driver. Together with | ||
| 104 | the <structfield>driver</structfield> field this identifies a | ||
| 105 | particular driver. The version number is formatted using the | ||
| 106 | <constant>KERNEL_VERSION()</constant> macro:</para></entry> | ||
| 107 | </row> | ||
| 108 | <row> | ||
| 109 | <entry spanname="hspan"><para> | ||
| 110 | <programlisting> | ||
| 111 | #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) | ||
| 112 | |||
| 113 | __u32 version = KERNEL_VERSION(0, 8, 1); | ||
| 114 | |||
| 115 | printf ("Version: %u.%u.%u\n", | ||
| 116 | (version >> 16) & 0xFF, | ||
| 117 | (version >> 8) & 0xFF, | ||
| 118 | version & 0xFF); | ||
| 119 | </programlisting></para></entry> | ||
| 120 | </row> | ||
| 121 | <row> | ||
| 122 | <entry>__u32</entry> | ||
| 123 | <entry><structfield>capabilities</structfield></entry> | ||
| 124 | <entry>Device capabilities, see <xref | ||
| 125 | linkend="device-capabilities" />.</entry> | ||
| 126 | </row> | ||
| 127 | <row> | ||
| 128 | <entry>__u32</entry> | ||
| 129 | <entry><structfield>reserved</structfield>[4]</entry> | ||
| 130 | <entry>Reserved for future extensions. Drivers must set | ||
| 131 | this array to zero.</entry> | ||
| 132 | </row> | ||
| 133 | </tbody> | ||
| 134 | </tgroup> | ||
| 135 | </table> | ||
| 136 | |||
| 137 | <table pgwide="1" frame="none" id="device-capabilities"> | ||
| 138 | <title>Device Capabilities Flags</title> | ||
| 139 | <tgroup cols="3"> | ||
| 140 | &cs-def; | ||
| 141 | <tbody valign="top"> | ||
| 142 | <row> | ||
| 143 | <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry> | ||
| 144 | <entry>0x00000001</entry> | ||
| 145 | <entry>The device supports the <link | ||
| 146 | linkend="capture">Video Capture</link> interface.</entry> | ||
| 147 | </row> | ||
| 148 | <row> | ||
| 149 | <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry> | ||
| 150 | <entry>0x00000002</entry> | ||
| 151 | <entry>The device supports the <link | ||
| 152 | linkend="output">Video Output</link> interface.</entry> | ||
| 153 | </row> | ||
| 154 | <row> | ||
| 155 | <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry> | ||
| 156 | <entry>0x00000004</entry> | ||
| 157 | <entry>The device supports the <link | ||
| 158 | linkend="overlay">Video Overlay</link> interface. A video overlay device | ||
| 159 | typically stores captured images directly in the video memory of a | ||
| 160 | graphics card, with hardware clipping and scaling.</entry> | ||
| 161 | </row> | ||
| 162 | <row> | ||
| 163 | <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry> | ||
| 164 | <entry>0x00000010</entry> | ||
| 165 | <entry>The device supports the <link linkend="raw-vbi">Raw | ||
| 166 | VBI Capture</link> interface, providing Teletext and Closed Caption | ||
| 167 | data.</entry> | ||
| 168 | </row> | ||
| 169 | <row> | ||
| 170 | <entry><constant>V4L2_CAP_VBI_OUTPUT</constant></entry> | ||
| 171 | <entry>0x00000020</entry> | ||
| 172 | <entry>The device supports the <link linkend="raw-vbi">Raw VBI Output</link> interface.</entry> | ||
| 173 | </row> | ||
| 174 | <row> | ||
| 175 | <entry><constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant></entry> | ||
| 176 | <entry>0x00000040</entry> | ||
| 177 | <entry>The device supports the <link linkend="sliced">Sliced VBI Capture</link> interface.</entry> | ||
| 178 | </row> | ||
| 179 | <row> | ||
| 180 | <entry><constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant></entry> | ||
| 181 | <entry>0x00000080</entry> | ||
| 182 | <entry>The device supports the <link linkend="sliced">Sliced VBI Output</link> interface.</entry> | ||
| 183 | </row> | ||
| 184 | <row> | ||
| 185 | <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry> | ||
| 186 | <entry>0x00000100</entry> | ||
| 187 | <entry>The device supports the <link linkend="rds">RDS</link> interface.</entry> | ||
| 188 | </row> | ||
| 189 | <row> | ||
| 190 | <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry> | ||
| 191 | <entry>0x00000200</entry> | ||
| 192 | <entry>The device supports the <link linkend="osd">Video | ||
| 193 | Output Overlay</link> (OSD) interface. Unlike the <wordasword>Video | ||
| 194 | Overlay</wordasword> interface, this is a secondary function of video | ||
| 195 | output devices and overlays an image onto an outgoing video signal. | ||
| 196 | When the driver sets this flag, it must clear the | ||
| 197 | <constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag and vice | ||
| 198 | versa.<footnote><para>The &v4l2-framebuffer; lacks an | ||
| 199 | &v4l2-buf-type; field, therefore the type of overlay is implied by the | ||
| 200 | driver capabilities.</para></footnote></entry> | ||
| 201 | </row> | ||
| 202 | <row> | ||
| 203 | <entry><constant>V4L2_CAP_HW_FREQ_SEEK</constant></entry> | ||
| 204 | <entry>0x00000400</entry> | ||
| 205 | <entry>The device supports the &VIDIOC-S-HW-FREQ-SEEK; ioctl for | ||
| 206 | hardware frequency seeking.</entry> | ||
| 207 | </row> | ||
| 208 | <row> | ||
| 209 | <entry><constant>V4L2_CAP_TUNER</constant></entry> | ||
| 210 | <entry>0x00010000</entry> | ||
| 211 | <entry>The device has some sort of tuner to | ||
| 212 | receive RF-modulated video signals. For more information about | ||
| 213 | tuner programming see | ||
| 214 | <xref linkend="tuner" />.</entry> | ||
| 215 | </row> | ||
| 216 | <row> | ||
| 217 | <entry><constant>V4L2_CAP_AUDIO</constant></entry> | ||
| 218 | <entry>0x00020000</entry> | ||
| 219 | <entry>The device has audio inputs or outputs. It may or | ||
| 220 | may not support audio recording or playback, in PCM or compressed | ||
| 221 | formats. PCM audio support must be implemented as ALSA or OSS | ||
| 222 | interface. For more information on audio inputs and outputs see <xref | ||
| 223 | linkend="audio" />.</entry> | ||
| 224 | </row> | ||
| 225 | <row> | ||
| 226 | <entry><constant>V4L2_CAP_RADIO</constant></entry> | ||
| 227 | <entry>0x00040000</entry> | ||
| 228 | <entry>This is a radio receiver.</entry> | ||
| 229 | </row> | ||
| 230 | <row> | ||
| 231 | <entry><constant>V4L2_CAP_MODULATOR</constant></entry> | ||
| 232 | <entry>0x00080000</entry> | ||
| 233 | <entry>The device has some sort of modulator to | ||
| 234 | emit RF-modulated video/audio signals. For more information about | ||
| 235 | modulator programming see | ||
| 236 | <xref linkend="tuner" />.</entry> | ||
| 237 | </row> | ||
| 238 | <row> | ||
| 239 | <entry><constant>V4L2_CAP_READWRITE</constant></entry> | ||
| 240 | <entry>0x01000000</entry> | ||
| 241 | <entry>The device supports the <link | ||
| 242 | linkend="rw">read()</link> and/or <link linkend="rw">write()</link> | ||
| 243 | I/O methods.</entry> | ||
| 244 | </row> | ||
| 245 | <row> | ||
| 246 | <entry><constant>V4L2_CAP_ASYNCIO</constant></entry> | ||
| 247 | <entry>0x02000000</entry> | ||
| 248 | <entry>The device supports the <link | ||
| 249 | linkend="async">asynchronous</link> I/O methods.</entry> | ||
| 250 | </row> | ||
| 251 | <row> | ||
| 252 | <entry><constant>V4L2_CAP_STREAMING</constant></entry> | ||
| 253 | <entry>0x04000000</entry> | ||
| 254 | <entry>The device supports the <link | ||
| 255 | linkend="mmap">streaming</link> I/O method.</entry> | ||
| 256 | </row> | ||
| 257 | </tbody> | ||
| 258 | </tgroup> | ||
| 259 | </table> | ||
| 260 | </refsect1> | ||
| 261 | |||
| 262 | <refsect1> | ||
| 263 | &return-value; | ||
| 264 | |||
| 265 | <variablelist> | ||
| 266 | <varlistentry> | ||
| 267 | <term><errorcode>EINVAL</errorcode></term> | ||
| 268 | <listitem> | ||
| 269 | <para>The device is not compatible with this | ||
| 270 | specification.</para> | ||
| 271 | </listitem> | ||
| 272 | </varlistentry> | ||
| 273 | </variablelist> | ||
| 274 | </refsect1> | ||
| 275 | </refentry> | ||
| 276 | |||
| 277 | <!-- | ||
| 278 | Local Variables: | ||
| 279 | mode: sgml | ||
| 280 | sgml-parent-document: "v4l2.sgml" | ||
| 281 | indent-tabs-mode: nil | ||
| 282 | End: | ||
| 283 | --> | ||
| 284 | |||
diff --git a/Documentation/DocBook/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/v4l/vidioc-queryctrl.xml new file mode 100644 index 000000000000..4876ff1a1a04 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-queryctrl.xml | |||
| @@ -0,0 +1,428 @@ | |||
| 1 | <refentry id="vidioc-queryctrl"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_QUERYCTRL</refname> | ||
| 9 | <refname>VIDIOC_QUERYMENU</refname> | ||
| 10 | <refpurpose>Enumerate controls and menu control items</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>struct v4l2_queryctrl *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | <funcsynopsis> | ||
| 23 | <funcprototype> | ||
| 24 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 25 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 26 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 27 | <paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef> | ||
| 28 | </funcprototype> | ||
| 29 | </funcsynopsis> | ||
| 30 | </refsynopsisdiv> | ||
| 31 | |||
| 32 | <refsect1> | ||
| 33 | <title>Arguments</title> | ||
| 34 | |||
| 35 | <variablelist> | ||
| 36 | <varlistentry> | ||
| 37 | <term><parameter>fd</parameter></term> | ||
| 38 | <listitem> | ||
| 39 | <para>&fd;</para> | ||
| 40 | </listitem> | ||
| 41 | </varlistentry> | ||
| 42 | <varlistentry> | ||
| 43 | <term><parameter>request</parameter></term> | ||
| 44 | <listitem> | ||
| 45 | <para>VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</para> | ||
| 46 | </listitem> | ||
| 47 | </varlistentry> | ||
| 48 | <varlistentry> | ||
| 49 | <term><parameter>argp</parameter></term> | ||
| 50 | <listitem> | ||
| 51 | <para></para> | ||
| 52 | </listitem> | ||
| 53 | </varlistentry> | ||
| 54 | </variablelist> | ||
| 55 | </refsect1> | ||
| 56 | |||
| 57 | <refsect1> | ||
| 58 | <title>Description</title> | ||
| 59 | |||
| 60 | <para>To query the attributes of a control applications set the | ||
| 61 | <structfield>id</structfield> field of a &v4l2-queryctrl; and call the | ||
| 62 | <constant>VIDIOC_QUERYCTRL</constant> ioctl with a pointer to this | ||
| 63 | structure. The driver fills the rest of the structure or returns an | ||
| 64 | &EINVAL; when the <structfield>id</structfield> is invalid.</para> | ||
| 65 | |||
| 66 | <para>It is possible to enumerate controls by calling | ||
| 67 | <constant>VIDIOC_QUERYCTRL</constant> with successive | ||
| 68 | <structfield>id</structfield> values starting from | ||
| 69 | <constant>V4L2_CID_BASE</constant> up to and exclusive | ||
| 70 | <constant>V4L2_CID_BASE_LASTP1</constant>. Drivers may return | ||
| 71 | <errorcode>EINVAL</errorcode> if a control in this range is not | ||
| 72 | supported. Further applications can enumerate private controls, which | ||
| 73 | are not defined in this specification, by starting at | ||
| 74 | <constant>V4L2_CID_PRIVATE_BASE</constant> and incrementing | ||
| 75 | <structfield>id</structfield> until the driver returns | ||
| 76 | <errorcode>EINVAL</errorcode>.</para> | ||
| 77 | |||
| 78 | <para>In both cases, when the driver sets the | ||
| 79 | <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag in the | ||
| 80 | <structfield>flags</structfield> field this control is permanently | ||
| 81 | disabled and should be ignored by the application.<footnote> | ||
| 82 | <para><constant>V4L2_CTRL_FLAG_DISABLED</constant> was | ||
| 83 | intended for two purposes: Drivers can skip predefined controls not | ||
| 84 | supported by the hardware (although returning EINVAL would do as | ||
| 85 | well), or disable predefined and private controls after hardware | ||
| 86 | detection without the trouble of reordering control arrays and indices | ||
| 87 | (EINVAL cannot be used to skip private controls because it would | ||
| 88 | prematurely end the enumeration).</para></footnote></para> | ||
| 89 | |||
| 90 | <para>When the application ORs <structfield>id</structfield> with | ||
| 91 | <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the | ||
| 92 | next supported control, or <errorcode>EINVAL</errorcode> if there is | ||
| 93 | none. Drivers which do not support this flag yet always return | ||
| 94 | <errorcode>EINVAL</errorcode>.</para> | ||
| 95 | |||
| 96 | <para>Additional information is required for menu controls: the | ||
| 97 | names of the menu items. To query them applications set the | ||
| 98 | <structfield>id</structfield> and <structfield>index</structfield> | ||
| 99 | fields of &v4l2-querymenu; and call the | ||
| 100 | <constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this | ||
| 101 | structure. The driver fills the rest of the structure or returns an | ||
| 102 | &EINVAL; when the <structfield>id</structfield> or | ||
| 103 | <structfield>index</structfield> is invalid. Menu items are enumerated | ||
| 104 | by calling <constant>VIDIOC_QUERYMENU</constant> with successive | ||
| 105 | <structfield>index</structfield> values from &v4l2-queryctrl; | ||
| 106 | <structfield>minimum</structfield> (0) to | ||
| 107 | <structfield>maximum</structfield>, inclusive.</para> | ||
| 108 | |||
| 109 | <para>See also the examples in <xref linkend="control" />.</para> | ||
| 110 | |||
| 111 | <table pgwide="1" frame="none" id="v4l2-queryctrl"> | ||
| 112 | <title>struct <structname>v4l2_queryctrl</structname></title> | ||
| 113 | <tgroup cols="3"> | ||
| 114 | &cs-str; | ||
| 115 | <tbody valign="top"> | ||
| 116 | <row> | ||
| 117 | <entry>__u32</entry> | ||
| 118 | <entry><structfield>id</structfield></entry> | ||
| 119 | <entry>Identifies the control, set by the application. See | ||
| 120 | <xref linkend="control-id" /> for predefined IDs. When the ID is ORed | ||
| 121 | with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns | ||
| 122 | the first control with a higher ID. Drivers which do not support this | ||
| 123 | flag yet always return an &EINVAL;.</entry> | ||
| 124 | </row> | ||
| 125 | <row> | ||
| 126 | <entry>&v4l2-ctrl-type;</entry> | ||
| 127 | <entry><structfield>type</structfield></entry> | ||
| 128 | <entry>Type of control, see <xref | ||
| 129 | linkend="v4l2-ctrl-type" />.</entry> | ||
| 130 | </row> | ||
| 131 | <row> | ||
| 132 | <entry>__u8</entry> | ||
| 133 | <entry><structfield>name</structfield>[32]</entry> | ||
| 134 | <entry>Name of the control, a NUL-terminated ASCII | ||
| 135 | string. This information is intended for the user.</entry> | ||
| 136 | </row> | ||
| 137 | <row> | ||
| 138 | <entry>__s32</entry> | ||
| 139 | <entry><structfield>minimum</structfield></entry> | ||
| 140 | <entry>Minimum value, inclusive. This field gives a lower | ||
| 141 | bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the | ||
| 142 | lowest valid index (always 0) for <constant>V4L2_CTRL_TYPE_MENU</constant> controls. | ||
| 143 | For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value | ||
| 144 | gives the minimum length of the string. This length <emphasis>does not include the terminating | ||
| 145 | zero</emphasis>. It may not be valid for any other type of control, including | ||
| 146 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a | ||
| 147 | signed value.</entry> | ||
| 148 | </row> | ||
| 149 | <row> | ||
| 150 | <entry>__s32</entry> | ||
| 151 | <entry><structfield>maximum</structfield></entry> | ||
| 152 | <entry>Maximum value, inclusive. This field gives an upper | ||
| 153 | bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the | ||
| 154 | highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> | ||
| 155 | controls. | ||
| 156 | For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value | ||
| 157 | gives the maximum length of the string. This length <emphasis>does not include the terminating | ||
| 158 | zero</emphasis>. It may not be valid for any other type of control, including | ||
| 159 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a | ||
| 160 | signed value.</entry> | ||
| 161 | </row> | ||
| 162 | <row> | ||
| 163 | <entry>__s32</entry> | ||
| 164 | <entry><structfield>step</structfield></entry> | ||
| 165 | <entry><para>This field gives a step size for | ||
| 166 | <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For | ||
| 167 | <constant>V4L2_CTRL_TYPE_STRING</constant> controls this field refers to | ||
| 168 | the string length that has to be a multiple of this step size. | ||
| 169 | It may not be valid for any other type of control, including | ||
| 170 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> | ||
| 171 | controls.</para><para>Generally drivers should not scale hardware | ||
| 172 | control values. It may be necessary for example when the | ||
| 173 | <structfield>name</structfield> or <structfield>id</structfield> imply | ||
| 174 | a particular unit and the hardware actually accepts only multiples of | ||
| 175 | said unit. If so, drivers must take care values are properly rounded | ||
| 176 | when scaling, such that errors will not accumulate on repeated | ||
| 177 | read-write cycles.</para><para>This field gives the smallest change of | ||
| 178 | an integer control actually affecting hardware. Often the information | ||
| 179 | is needed when the user can change controls by keyboard or GUI | ||
| 180 | buttons, rather than a slider. When for example a hardware register | ||
| 181 | accepts values 0-511 and the driver reports 0-65535, step should be | ||
| 182 | 128.</para><para>Note that although signed, the step value is supposed to | ||
| 183 | be always positive.</para></entry> | ||
| 184 | </row> | ||
| 185 | <row> | ||
| 186 | <entry>__s32</entry> | ||
| 187 | <entry><structfield>default_value</structfield></entry> | ||
| 188 | <entry>The default value of a | ||
| 189 | <constant>V4L2_CTRL_TYPE_INTEGER</constant>, | ||
| 190 | <constant>_BOOLEAN</constant> or <constant>_MENU</constant> control. | ||
| 191 | Not valid for other types of controls. Drivers reset controls only | ||
| 192 | when the driver is loaded, not later, in particular not when the | ||
| 193 | func-open; is called.</entry> | ||
| 194 | </row> | ||
| 195 | <row> | ||
| 196 | <entry>__u32</entry> | ||
| 197 | <entry><structfield>flags</structfield></entry> | ||
| 198 | <entry>Control flags, see <xref | ||
| 199 | linkend="control-flags" />.</entry> | ||
| 200 | </row> | ||
| 201 | <row> | ||
| 202 | <entry>__u32</entry> | ||
| 203 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 204 | <entry>Reserved for future extensions. Drivers must set | ||
| 205 | the array to zero.</entry> | ||
| 206 | </row> | ||
| 207 | </tbody> | ||
| 208 | </tgroup> | ||
| 209 | </table> | ||
| 210 | |||
| 211 | <table pgwide="1" frame="none" id="v4l2-querymenu"> | ||
| 212 | <title>struct <structname>v4l2_querymenu</structname></title> | ||
| 213 | <tgroup cols="3"> | ||
| 214 | &cs-str; | ||
| 215 | <tbody valign="top"> | ||
| 216 | <row> | ||
| 217 | <entry>__u32</entry> | ||
| 218 | <entry><structfield>id</structfield></entry> | ||
| 219 | <entry>Identifies the control, set by the application | ||
| 220 | from the respective &v4l2-queryctrl; | ||
| 221 | <structfield>id</structfield>.</entry> | ||
| 222 | </row> | ||
| 223 | <row> | ||
| 224 | <entry>__u32</entry> | ||
| 225 | <entry><structfield>index</structfield></entry> | ||
| 226 | <entry>Index of the menu item, starting at zero, set by | ||
| 227 | the application.</entry> | ||
| 228 | </row> | ||
| 229 | <row> | ||
| 230 | <entry>__u8</entry> | ||
| 231 | <entry><structfield>name</structfield>[32]</entry> | ||
| 232 | <entry>Name of the menu item, a NUL-terminated ASCII | ||
| 233 | string. This information is intended for the user.</entry> | ||
| 234 | </row> | ||
| 235 | <row> | ||
| 236 | <entry>__u32</entry> | ||
| 237 | <entry><structfield>reserved</structfield></entry> | ||
| 238 | <entry>Reserved for future extensions. Drivers must set | ||
| 239 | the array to zero.</entry> | ||
| 240 | </row> | ||
| 241 | </tbody> | ||
| 242 | </tgroup> | ||
| 243 | </table> | ||
| 244 | |||
| 245 | <table pgwide="1" frame="none" id="v4l2-ctrl-type"> | ||
| 246 | <title>enum v4l2_ctrl_type</title> | ||
| 247 | <tgroup cols="5" align="left"> | ||
| 248 | <colspec colwidth="30*" /> | ||
| 249 | <colspec colwidth="5*" align="center" /> | ||
| 250 | <colspec colwidth="5*" align="center" /> | ||
| 251 | <colspec colwidth="5*" align="center" /> | ||
| 252 | <colspec colwidth="55*" /> | ||
| 253 | <thead> | ||
| 254 | <row> | ||
| 255 | <entry>Type</entry> | ||
| 256 | <entry><structfield>minimum</structfield></entry> | ||
| 257 | <entry><structfield>step</structfield></entry> | ||
| 258 | <entry><structfield>maximum</structfield></entry> | ||
| 259 | <entry>Description</entry> | ||
| 260 | </row> | ||
| 261 | </thead> | ||
| 262 | <tbody valign="top"> | ||
| 263 | <row> | ||
| 264 | <entry><constant>V4L2_CTRL_TYPE_INTEGER</constant></entry> | ||
| 265 | <entry>any</entry> | ||
| 266 | <entry>any</entry> | ||
| 267 | <entry>any</entry> | ||
| 268 | <entry>An integer-valued control ranging from minimum to | ||
| 269 | maximum inclusive. The step value indicates the increment between | ||
| 270 | values which are actually different on the hardware.</entry> | ||
| 271 | </row> | ||
| 272 | <row> | ||
| 273 | <entry><constant>V4L2_CTRL_TYPE_BOOLEAN</constant></entry> | ||
| 274 | <entry>0</entry> | ||
| 275 | <entry>1</entry> | ||
| 276 | <entry>1</entry> | ||
| 277 | <entry>A boolean-valued control. Zero corresponds to | ||
| 278 | "disabled", and one means "enabled".</entry> | ||
| 279 | </row> | ||
| 280 | <row> | ||
| 281 | <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry> | ||
| 282 | <entry>0</entry> | ||
| 283 | <entry>1</entry> | ||
| 284 | <entry>N-1</entry> | ||
| 285 | <entry>The control has a menu of N choices. The names of | ||
| 286 | the menu items can be enumerated with the | ||
| 287 | <constant>VIDIOC_QUERYMENU</constant> ioctl.</entry> | ||
| 288 | </row> | ||
| 289 | <row> | ||
| 290 | <entry><constant>V4L2_CTRL_TYPE_BUTTON</constant></entry> | ||
| 291 | <entry>0</entry> | ||
| 292 | <entry>0</entry> | ||
| 293 | <entry>0</entry> | ||
| 294 | <entry>A control which performs an action when set. | ||
| 295 | Drivers must ignore the value passed with | ||
| 296 | <constant>VIDIOC_S_CTRL</constant> and return an &EINVAL; on a | ||
| 297 | <constant>VIDIOC_G_CTRL</constant> attempt.</entry> | ||
| 298 | </row> | ||
| 299 | <row> | ||
| 300 | <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry> | ||
| 301 | <entry>n/a</entry> | ||
| 302 | <entry>n/a</entry> | ||
| 303 | <entry>n/a</entry> | ||
| 304 | <entry>A 64-bit integer valued control. Minimum, maximum | ||
| 305 | and step size cannot be queried.</entry> | ||
| 306 | </row> | ||
| 307 | <row> | ||
| 308 | <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry> | ||
| 309 | <entry>≥ 0</entry> | ||
| 310 | <entry>≥ 1</entry> | ||
| 311 | <entry>≥ 0</entry> | ||
| 312 | <entry>The minimum and maximum string lengths. The step size | ||
| 313 | means that the string must be (minimum + N * step) characters long for | ||
| 314 | N ≥ 0. These lengths do not include the terminating zero, so in order to | ||
| 315 | pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the | ||
| 316 | <structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can | ||
| 317 | set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1. | ||
| 318 | Which character encoding is used will depend on the string control itself and | ||
| 319 | should be part of the control documentation.</entry> | ||
| 320 | </row> | ||
| 321 | <row> | ||
| 322 | <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry> | ||
| 323 | <entry>n/a</entry> | ||
| 324 | <entry>n/a</entry> | ||
| 325 | <entry>n/a</entry> | ||
| 326 | <entry>This is not a control. When | ||
| 327 | <constant>VIDIOC_QUERYCTRL</constant> is called with a control ID | ||
| 328 | equal to a control class code (see <xref linkend="ctrl-class" />), the | ||
| 329 | ioctl returns the name of the control class and this control type. | ||
| 330 | Older drivers which do not support this feature return an | ||
| 331 | &EINVAL;.</entry> | ||
| 332 | </row> | ||
| 333 | </tbody> | ||
| 334 | </tgroup> | ||
| 335 | </table> | ||
| 336 | |||
| 337 | <table pgwide="1" frame="none" id="control-flags"> | ||
| 338 | <title>Control Flags</title> | ||
| 339 | <tgroup cols="3"> | ||
| 340 | &cs-def; | ||
| 341 | <tbody valign="top"> | ||
| 342 | <row> | ||
| 343 | <entry><constant>V4L2_CTRL_FLAG_DISABLED</constant></entry> | ||
| 344 | <entry>0x0001</entry> | ||
| 345 | <entry>This control is permanently disabled and should be | ||
| 346 | ignored by the application. Any attempt to change the control will | ||
| 347 | result in an &EINVAL;.</entry> | ||
| 348 | </row> | ||
| 349 | <row> | ||
| 350 | <entry><constant>V4L2_CTRL_FLAG_GRABBED</constant></entry> | ||
| 351 | <entry>0x0002</entry> | ||
| 352 | <entry>This control is temporarily unchangeable, for | ||
| 353 | example because another application took over control of the | ||
| 354 | respective resource. Such controls may be displayed specially in a | ||
| 355 | user interface. Attempts to change the control may result in an | ||
| 356 | &EBUSY;.</entry> | ||
| 357 | </row> | ||
| 358 | <row> | ||
| 359 | <entry><constant>V4L2_CTRL_FLAG_READ_ONLY</constant></entry> | ||
| 360 | <entry>0x0004</entry> | ||
| 361 | <entry>This control is permanently readable only. Any | ||
| 362 | attempt to change the control will result in an &EINVAL;.</entry> | ||
| 363 | </row> | ||
| 364 | <row> | ||
| 365 | <entry><constant>V4L2_CTRL_FLAG_UPDATE</constant></entry> | ||
| 366 | <entry>0x0008</entry> | ||
| 367 | <entry>A hint that changing this control may affect the | ||
| 368 | value of other controls within the same control class. Applications | ||
| 369 | should update their user interface accordingly.</entry> | ||
| 370 | </row> | ||
| 371 | <row> | ||
| 372 | <entry><constant>V4L2_CTRL_FLAG_INACTIVE</constant></entry> | ||
| 373 | <entry>0x0010</entry> | ||
| 374 | <entry>This control is not applicable to the current | ||
| 375 | configuration and should be displayed accordingly in a user interface. | ||
| 376 | For example the flag may be set on a MPEG audio level 2 bitrate | ||
| 377 | control when MPEG audio encoding level 1 was selected with another | ||
| 378 | control.</entry> | ||
| 379 | </row> | ||
| 380 | <row> | ||
| 381 | <entry><constant>V4L2_CTRL_FLAG_SLIDER</constant></entry> | ||
| 382 | <entry>0x0020</entry> | ||
| 383 | <entry>A hint that this control is best represented as a | ||
| 384 | slider-like element in a user interface.</entry> | ||
| 385 | </row> | ||
| 386 | <row> | ||
| 387 | <entry><constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant></entry> | ||
| 388 | <entry>0x0040</entry> | ||
| 389 | <entry>This control is permanently writable only. Any | ||
| 390 | attempt to read the control will result in an &EACCES; error code. This | ||
| 391 | flag is typically present for relative controls or action controls where | ||
| 392 | writing a value will cause the device to carry out a given action | ||
| 393 | (⪚ motor control) but no meaningful value can be returned.</entry> | ||
| 394 | </row> | ||
| 395 | </tbody> | ||
| 396 | </tgroup> | ||
| 397 | </table> | ||
| 398 | </refsect1> | ||
| 399 | |||
| 400 | <refsect1> | ||
| 401 | &return-value; | ||
| 402 | |||
| 403 | <variablelist> | ||
| 404 | <varlistentry> | ||
| 405 | <term><errorcode>EINVAL</errorcode></term> | ||
| 406 | <listitem> | ||
| 407 | <para>The &v4l2-queryctrl; <structfield>id</structfield> | ||
| 408 | is invalid. The &v4l2-querymenu; <structfield>id</structfield> or | ||
| 409 | <structfield>index</structfield> is invalid.</para> | ||
| 410 | </listitem> | ||
| 411 | </varlistentry> | ||
| 412 | <varlistentry> | ||
| 413 | <term><errorcode>EACCES</errorcode></term> | ||
| 414 | <listitem> | ||
| 415 | <para>An attempt was made to read a write-only control.</para> | ||
| 416 | </listitem> | ||
| 417 | </varlistentry> | ||
| 418 | </variablelist> | ||
| 419 | </refsect1> | ||
| 420 | </refentry> | ||
| 421 | |||
| 422 | <!-- | ||
| 423 | Local Variables: | ||
| 424 | mode: sgml | ||
| 425 | sgml-parent-document: "v4l2.sgml" | ||
| 426 | indent-tabs-mode: nil | ||
| 427 | End: | ||
| 428 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-querystd.xml b/Documentation/DocBook/v4l/vidioc-querystd.xml new file mode 100644 index 000000000000..b5a7ff934486 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-querystd.xml | |||
| @@ -0,0 +1,83 @@ | |||
| 1 | <refentry id="vidioc-querystd"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_QUERYSTD</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_QUERYSTD</refname> | ||
| 9 | <refpurpose>Sense the video standard received by the current | ||
| 10 | input</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>v4l2_std_id *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_QUERYSTD</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>The hardware may be able to detect the current video | ||
| 53 | standard automatically. To do so, applications call <constant> | ||
| 54 | VIDIOC_QUERYSTD</constant> with a pointer to a &v4l2-std-id; type. The | ||
| 55 | driver stores here a set of candidates, this can be a single flag or a | ||
| 56 | set of supported standards if for example the hardware can only | ||
| 57 | distinguish between 50 and 60 Hz systems. When detection is not | ||
| 58 | possible or fails, the set must contain all standards supported by the | ||
| 59 | current video input or output.</para> | ||
| 60 | |||
| 61 | </refsect1> | ||
| 62 | |||
| 63 | <refsect1> | ||
| 64 | &return-value; | ||
| 65 | |||
| 66 | <variablelist> | ||
| 67 | <varlistentry> | ||
| 68 | <term><errorcode>EINVAL</errorcode></term> | ||
| 69 | <listitem> | ||
| 70 | <para>This ioctl is not supported.</para> | ||
| 71 | </listitem> | ||
| 72 | </varlistentry> | ||
| 73 | </variablelist> | ||
| 74 | </refsect1> | ||
| 75 | </refentry> | ||
| 76 | |||
| 77 | <!-- | ||
| 78 | Local Variables: | ||
| 79 | mode: sgml | ||
| 80 | sgml-parent-document: "v4l2.sgml" | ||
| 81 | indent-tabs-mode: nil | ||
| 82 | End: | ||
| 83 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/v4l/vidioc-reqbufs.xml new file mode 100644 index 000000000000..bab38084454f --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-reqbufs.xml | |||
| @@ -0,0 +1,160 @@ | |||
| 1 | <refentry id="vidioc-reqbufs"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_REQBUFS</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_REQBUFS</refname> | ||
| 9 | <refpurpose>Initiate Memory Mapping or User Pointer I/O</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_requestbuffers *<parameter>argp</parameter></paramdef> | ||
| 19 | </funcprototype> | ||
| 20 | </funcsynopsis> | ||
| 21 | </refsynopsisdiv> | ||
| 22 | |||
| 23 | <refsect1> | ||
| 24 | <title>Arguments</title> | ||
| 25 | |||
| 26 | <variablelist> | ||
| 27 | <varlistentry> | ||
| 28 | <term><parameter>fd</parameter></term> | ||
| 29 | <listitem> | ||
| 30 | <para>&fd;</para> | ||
| 31 | </listitem> | ||
| 32 | </varlistentry> | ||
| 33 | <varlistentry> | ||
| 34 | <term><parameter>request</parameter></term> | ||
| 35 | <listitem> | ||
| 36 | <para>VIDIOC_REQBUFS</para> | ||
| 37 | </listitem> | ||
| 38 | </varlistentry> | ||
| 39 | <varlistentry> | ||
| 40 | <term><parameter>argp</parameter></term> | ||
| 41 | <listitem> | ||
| 42 | <para></para> | ||
| 43 | </listitem> | ||
| 44 | </varlistentry> | ||
| 45 | </variablelist> | ||
| 46 | </refsect1> | ||
| 47 | |||
| 48 | <refsect1> | ||
| 49 | <title>Description</title> | ||
| 50 | |||
| 51 | <para>This ioctl is used to initiate <link linkend="mmap">memory | ||
| 52 | mapped</link> or <link linkend="userp">user pointer</link> | ||
| 53 | I/O. Memory mapped buffers are located in device memory and must be | ||
| 54 | allocated with this ioctl before they can be mapped into the | ||
| 55 | application's address space. User buffers are allocated by | ||
| 56 | applications themselves, and this ioctl is merely used to switch the | ||
| 57 | driver into user pointer I/O mode.</para> | ||
| 58 | |||
| 59 | <para>To allocate device buffers applications initialize three | ||
| 60 | fields of a <structname>v4l2_requestbuffers</structname> structure. | ||
| 61 | They set the <structfield>type</structfield> field to the respective | ||
| 62 | stream or buffer type, the <structfield>count</structfield> field to | ||
| 63 | the desired number of buffers, and <structfield>memory</structfield> | ||
| 64 | must be set to <constant>V4L2_MEMORY_MMAP</constant>. When the ioctl | ||
| 65 | is called with a pointer to this structure the driver attempts to | ||
| 66 | allocate the requested number of buffers and stores the actual number | ||
| 67 | allocated in the <structfield>count</structfield> field. It can be | ||
| 68 | smaller than the number requested, even zero, when the driver runs out | ||
| 69 | of free memory. A larger number is possible when the driver requires | ||
| 70 | more buffers to function correctly.<footnote> | ||
| 71 | <para>For example video output requires at least two buffers, | ||
| 72 | one displayed and one filled by the application.</para> | ||
| 73 | </footnote> When memory mapping I/O is not supported the ioctl | ||
| 74 | returns an &EINVAL;.</para> | ||
| 75 | |||
| 76 | <para>Applications can call <constant>VIDIOC_REQBUFS</constant> | ||
| 77 | again to change the number of buffers, however this cannot succeed | ||
| 78 | when any buffers are still mapped. A <structfield>count</structfield> | ||
| 79 | value of zero frees all buffers, after aborting or finishing any DMA | ||
| 80 | in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no | ||
| 81 | reason why munmap()ping one or even all buffers must imply | ||
| 82 | streamoff.--></para> | ||
| 83 | |||
| 84 | <para>To negotiate user pointer I/O, applications initialize only | ||
| 85 | the <structfield>type</structfield> field and set | ||
| 86 | <structfield>memory</structfield> to | ||
| 87 | <constant>V4L2_MEMORY_USERPTR</constant>. When the ioctl is called | ||
| 88 | with a pointer to this structure the driver prepares for user pointer | ||
| 89 | I/O, when this I/O method is not supported the ioctl returns an | ||
| 90 | &EINVAL;.</para> | ||
| 91 | |||
| 92 | <table pgwide="1" frame="none" id="v4l2-requestbuffers"> | ||
| 93 | <title>struct <structname>v4l2_requestbuffers</structname></title> | ||
| 94 | <tgroup cols="3"> | ||
| 95 | &cs-str; | ||
| 96 | <tbody valign="top"> | ||
| 97 | <row> | ||
| 98 | <entry>__u32</entry> | ||
| 99 | <entry><structfield>count</structfield></entry> | ||
| 100 | <entry>The number of buffers requested or granted. This | ||
| 101 | field is only used when <structfield>memory</structfield> is set to | ||
| 102 | <constant>V4L2_MEMORY_MMAP</constant>.</entry> | ||
| 103 | </row> | ||
| 104 | <row> | ||
| 105 | <entry>&v4l2-buf-type;</entry> | ||
| 106 | <entry><structfield>type</structfield></entry> | ||
| 107 | <entry>Type of the stream or buffers, this is the same | ||
| 108 | as the &v4l2-format; <structfield>type</structfield> field. See <xref | ||
| 109 | linkend="v4l2-buf-type" /> for valid values.</entry> | ||
| 110 | </row> | ||
| 111 | <row> | ||
| 112 | <entry>&v4l2-memory;</entry> | ||
| 113 | <entry><structfield>memory</structfield></entry> | ||
| 114 | <entry>Applications set this field to | ||
| 115 | <constant>V4L2_MEMORY_MMAP</constant> or | ||
| 116 | <constant>V4L2_MEMORY_USERPTR</constant>.</entry> | ||
| 117 | </row> | ||
| 118 | <row> | ||
| 119 | <entry>__u32</entry> | ||
| 120 | <entry><structfield>reserved</structfield>[2]</entry> | ||
| 121 | <entry>A place holder for future extensions and custom | ||
| 122 | (driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and | ||
| 123 | higher.</entry> | ||
| 124 | </row> | ||
| 125 | </tbody> | ||
| 126 | </tgroup> | ||
| 127 | </table> | ||
| 128 | </refsect1> | ||
| 129 | |||
| 130 | <refsect1> | ||
| 131 | &return-value; | ||
| 132 | |||
| 133 | <variablelist> | ||
| 134 | <varlistentry> | ||
| 135 | <term><errorcode>EBUSY</errorcode></term> | ||
| 136 | <listitem> | ||
| 137 | <para>The driver supports multiple opens and I/O is already | ||
| 138 | in progress, or reallocation of buffers was attempted although one or | ||
| 139 | more are still mapped.</para> | ||
| 140 | </listitem> | ||
| 141 | </varlistentry> | ||
| 142 | <varlistentry> | ||
| 143 | <term><errorcode>EINVAL</errorcode></term> | ||
| 144 | <listitem> | ||
| 145 | <para>The buffer type (<structfield>type</structfield> field) or the | ||
| 146 | requested I/O method (<structfield>memory</structfield>) is not | ||
| 147 | supported.</para> | ||
| 148 | </listitem> | ||
| 149 | </varlistentry> | ||
| 150 | </variablelist> | ||
| 151 | </refsect1> | ||
| 152 | </refentry> | ||
| 153 | |||
| 154 | <!-- | ||
| 155 | Local Variables: | ||
| 156 | mode: sgml | ||
| 157 | sgml-parent-document: "v4l2.sgml" | ||
| 158 | indent-tabs-mode: nil | ||
| 159 | End: | ||
| 160 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml new file mode 100644 index 000000000000..14b3ec7ed75b --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml | |||
| @@ -0,0 +1,129 @@ | |||
| 1 | <refentry id="vidioc-s-hw-freq-seek"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_S_HW_FREQ_SEEK</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_S_HW_FREQ_SEEK</refname> | ||
| 9 | <refpurpose>Perform a hardware frequency seek</refpurpose> | ||
| 10 | </refnamediv> | ||
| 11 | |||
| 12 | <refsynopsisdiv> | ||
| 13 | <funcsynopsis> | ||
| 14 | <funcprototype> | ||
| 15 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 16 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 17 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 18 | <paramdef>struct v4l2_hw_freq_seek | ||
| 19 | *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_S_HW_FREQ_SEEK</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>Start a hardware frequency seek from the current frequency. | ||
| 53 | To do this applications initialize the <structfield>tuner</structfield>, | ||
| 54 | <structfield>type</structfield>, <structfield>seek_upward</structfield> and | ||
| 55 | <structfield>wrap_around</structfield> fields, and zero out the | ||
| 56 | <structfield>reserved</structfield> array of a &v4l2-hw-freq-seek; and | ||
| 57 | call the <constant>VIDIOC_S_HW_FREQ_SEEK</constant> ioctl with a pointer | ||
| 58 | to this structure.</para> | ||
| 59 | |||
| 60 | <para>This ioctl is supported if the <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability is set.</para> | ||
| 61 | |||
| 62 | <table pgwide="1" frame="none" id="v4l2-hw-freq-seek"> | ||
| 63 | <title>struct <structname>v4l2_hw_freq_seek</structname></title> | ||
| 64 | <tgroup cols="3"> | ||
| 65 | &cs-str; | ||
| 66 | <tbody valign="top"> | ||
| 67 | <row> | ||
| 68 | <entry>__u32</entry> | ||
| 69 | <entry><structfield>tuner</structfield></entry> | ||
| 70 | <entry>The tuner index number. This is the | ||
| 71 | same value as in the &v4l2-input; <structfield>tuner</structfield> | ||
| 72 | field and the &v4l2-tuner; <structfield>index</structfield> field.</entry> | ||
| 73 | </row> | ||
| 74 | <row> | ||
| 75 | <entry>&v4l2-tuner-type;</entry> | ||
| 76 | <entry><structfield>type</structfield></entry> | ||
| 77 | <entry>The tuner type. This is the same value as in the | ||
| 78 | &v4l2-tuner; <structfield>type</structfield> field.</entry> | ||
| 79 | </row> | ||
| 80 | <row> | ||
| 81 | <entry>__u32</entry> | ||
| 82 | <entry><structfield>seek_upward</structfield></entry> | ||
| 83 | <entry>If non-zero, seek upward from the current frequency, else seek downward.</entry> | ||
| 84 | </row> | ||
| 85 | <row> | ||
| 86 | <entry>__u32</entry> | ||
| 87 | <entry><structfield>wrap_around</structfield></entry> | ||
| 88 | <entry>If non-zero, wrap around when at the end of the frequency range, else stop seeking.</entry> | ||
| 89 | </row> | ||
| 90 | <row> | ||
| 91 | <entry>__u32</entry> | ||
| 92 | <entry><structfield>reserved</structfield>[8]</entry> | ||
| 93 | <entry>Reserved for future extensions. Drivers and | ||
| 94 | applications must set the array to zero.</entry> | ||
| 95 | </row> | ||
| 96 | </tbody> | ||
| 97 | </tgroup> | ||
| 98 | </table> | ||
| 99 | </refsect1> | ||
| 100 | |||
| 101 | <refsect1> | ||
| 102 | &return-value; | ||
| 103 | |||
| 104 | <variablelist> | ||
| 105 | <varlistentry> | ||
| 106 | <term><errorcode>EINVAL</errorcode></term> | ||
| 107 | <listitem> | ||
| 108 | <para>The <structfield>tuner</structfield> index is out of | ||
| 109 | bounds or the value in the <structfield>type</structfield> field is | ||
| 110 | wrong.</para> | ||
| 111 | </listitem> | ||
| 112 | </varlistentry> | ||
| 113 | <varlistentry> | ||
| 114 | <term><errorcode>EAGAIN</errorcode></term> | ||
| 115 | <listitem> | ||
| 116 | <para>The ioctl timed-out. Try again.</para> | ||
| 117 | </listitem> | ||
| 118 | </varlistentry> | ||
| 119 | </variablelist> | ||
| 120 | </refsect1> | ||
| 121 | </refentry> | ||
| 122 | |||
| 123 | <!-- | ||
| 124 | Local Variables: | ||
| 125 | mode: sgml | ||
| 126 | sgml-parent-document: "v4l2.sgml" | ||
| 127 | indent-tabs-mode: nil | ||
| 128 | End: | ||
| 129 | --> | ||
diff --git a/Documentation/DocBook/v4l/vidioc-streamon.xml b/Documentation/DocBook/v4l/vidioc-streamon.xml new file mode 100644 index 000000000000..e42bff1f2c0a --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-streamon.xml | |||
| @@ -0,0 +1,106 @@ | |||
| 1 | <refentry id="vidioc-streamon"> | ||
| 2 | <refmeta> | ||
| 3 | <refentrytitle>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</refentrytitle> | ||
| 4 | &manvol; | ||
| 5 | </refmeta> | ||
| 6 | |||
| 7 | <refnamediv> | ||
| 8 | <refname>VIDIOC_STREAMON</refname> | ||
| 9 | <refname>VIDIOC_STREAMOFF</refname> | ||
| 10 | <refpurpose>Start or stop streaming I/O</refpurpose> | ||
| 11 | </refnamediv> | ||
| 12 | |||
| 13 | <refsynopsisdiv> | ||
| 14 | <funcsynopsis> | ||
| 15 | <funcprototype> | ||
| 16 | <funcdef>int <function>ioctl</function></funcdef> | ||
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
| 18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
| 19 | <paramdef>const int *<parameter>argp</parameter></paramdef> | ||
| 20 | </funcprototype> | ||
| 21 | </funcsynopsis> | ||
| 22 | </refsynopsisdiv> | ||
| 23 | |||
| 24 | <refsect1> | ||
| 25 | <title>Arguments</title> | ||
| 26 | |||
| 27 | <variablelist> | ||
| 28 | <varlistentry> | ||
| 29 | <term><parameter>fd</parameter></term> | ||
| 30 | <listitem> | ||
| 31 | <para>&fd;</para> | ||
| 32 | </listitem> | ||
| 33 | </varlistentry> | ||
| 34 | <varlistentry> | ||
| 35 | <term><parameter>request</parameter></term> | ||
| 36 | <listitem> | ||
| 37 | <para>VIDIOC_STREAMON, VIDIOC_STREAMOFF</para> | ||
| 38 | </listitem> | ||
| 39 | </varlistentry> | ||
| 40 | <varlistentry> | ||
| 41 | <term><parameter>argp</parameter></term> | ||
| 42 | <listitem> | ||
| 43 | <para></para> | ||
| 44 | </listitem> | ||
| 45 | </varlistentry> | ||
| 46 | </variablelist> | ||
| 47 | </refsect1> | ||
| 48 | |||
| 49 | <refsect1> | ||
| 50 | <title>Description</title> | ||
| 51 | |||
| 52 | <para>The <constant>VIDIOC_STREAMON</constant> and | ||
| 53 | <constant>VIDIOC_STREAMOFF</constant> ioctl start and stop the capture | ||
| 54 | or output process during streaming (<link linkend="mmap">memory | ||
| 55 | mapping</link> or <link linkend="userp">user pointer</link>) I/O.</para> | ||
| 56 | |||
| 57 | <para>Specifically the capture hardware is disabled and no input | ||
| 58 | buffers are filled (if there are any empty buffers in the incoming | ||
| 59 | queue) until <constant>VIDIOC_STREAMON</constant> has been called. | ||
| 60 | Accordingly the output hardware is disabled, no video signal is | ||
| 61 | produced until <constant>VIDIOC_STREAMON</constant> has been called. | ||
| 62 | The ioctl will succeed only when at least one output buffer is in the | ||
| 63 | incoming queue.</para> | ||
| 64 | |||
| 65 | <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of | ||
| 66 | aborting or finishing any DMA in progress, unlocks any user pointer | ||
| 67 | buffers locked in physical memory, and it removes all buffers from the | ||
| 68 | incoming and outgoing queues. That means all images captured but not | ||
| 69 | dequeued yet will be lost, likewise all images enqueued for output but | ||
| 70 | not transmitted yet. I/O returns to the same state as after calling | ||
| 71 | &VIDIOC-REQBUFS; and can be restarted accordingly.</para> | ||
| 72 | |||
| 73 | <para>Both ioctls take a pointer to an integer, the desired buffer or | ||
| 74 | stream type. This is the same as &v4l2-requestbuffers; | ||
| 75 | <structfield>type</structfield>.</para> | ||
| 76 | |||
| 77 | <para>Note applications can be preempted for unknown periods right | ||
| 78 | before or after the <constant>VIDIOC_STREAMON</constant> or | ||
| 79 | <constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of | ||
| 80 | starting or stopping "now". Buffer timestamps can be used to | ||
| 81 | synchronize with other events.</para> | ||
| 82 | </refsect1> | ||
| 83 | |||
| 84 | <refsect1> | ||
| 85 | &return-value; | ||
| 86 | |||
| 87 | <variablelist> | ||
| 88 | <varlistentry> | ||
| 89 | <term><errorcode>EINVAL</errorcode></term> | ||
| 90 | <listitem> | ||
| 91 | <para>Streaming I/O is not supported, the buffer | ||
| 92 | <structfield>type</structfield> is not supported, or no buffers have | ||
| 93 | been allocated (memory mapping) or enqueued (output) yet.</para> | ||
| 94 | </listitem> | ||
| 95 | </varlistentry> | ||
| 96 | </variablelist> | ||
| 97 | </refsect1> | ||
| 98 | </refentry> | ||
| 99 | |||
| 100 | <!-- | ||
| 101 | Local Variables: | ||
| 102 | mode: sgml | ||
| 103 | sgml-parent-document: "v4l2.sgml" | ||
| 104 | indent-tabs-mode: nil | ||
| 105 | End: | ||
| 106 | --> | ||
diff --git a/Documentation/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 | ------------------ |
| 57 | If you encounter issues with graphics devices, you can try adding | 57 | If you encounter issues with graphics devices, you can try adding |
| 58 | option intel_iommu=igfx_off to turn off the integrated graphics engine. | 58 | option intel_iommu=igfx_off to turn off the integrated graphics engine. |
| 59 | 59 | If this fixes anything, please ensure you file a bug reporting the problem. | |
| 60 | If it happens to be a PCI device included in the INCLUDE_ALL Engine, | ||
| 61 | then try enabling CONFIG_DMAR_GFX_WA to setup a 1-1 map. We hear | ||
| 62 | graphics drivers may be in process of using DMA api's in the near | ||
| 63 | future and at that time this option can be yanked out. | ||
| 64 | 60 | ||
| 65 | Some exceptions to IOVA | 61 | Some 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 | ||
| 10 | Many PCI bus controllers are able to detect a variety of hardware | 12 | Many PCI bus controllers are able to detect a variety of hardware |
| 11 | PCI errors on the bus, such as parity errors on the data and address | 13 | PCI errors on the bus, such as parity errors on the data and address |
| 12 | busses, as well as SERR and PERR errors. Some of the more advanced | 14 | busses, as well as SERR and PERR errors. Some of the more advanced |
| 13 | chipsets are able to deal with these errors; these include PCI-E chipsets, | 15 | chipsets are able to deal with these errors; these include PCI-E chipsets, |
| 14 | and the PCI-host bridges found on IBM Power4 and Power5-based pSeries | 16 | and the PCI-host bridges found on IBM Power4, Power5 and Power6-based |
| 15 | boxes. A typical action taken is to disconnect the affected device, | 17 | pSeries boxes. A typical action taken is to disconnect the affected device, |
| 16 | halting all I/O to it. The goal of a disconnection is to avoid system | 18 | halting all I/O to it. The goal of a disconnection is to avoid system |
| 17 | corruption; for example, to halt system memory corruption due to DMA's | 19 | corruption; for example, to halt system memory corruption due to DMA's |
| 18 | to "wild" addresses. Typically, a reconnection mechanism is also | 20 | to "wild" addresses. Typically, a reconnection mechanism is also |
| @@ -37,10 +39,11 @@ is forced by the need to handle multi-function devices, that is, | |||
| 37 | devices that have multiple device drivers associated with them. | 39 | devices that have multiple device drivers associated with them. |
| 38 | In the first stage, each driver is allowed to indicate what type | 40 | In the first stage, each driver is allowed to indicate what type |
| 39 | of reset it desires, the choices being a simple re-enabling of I/O | 41 | of reset it desires, the choices being a simple re-enabling of I/O |
| 40 | or requesting a hard reset (a full electrical #RST of the PCI card). | 42 | or requesting a slot reset. |
| 41 | If any driver requests a full reset, that is what will be done. | ||
| 42 | 43 | ||
| 43 | After a full reset and/or a re-enabling of I/O, all drivers are | 44 | If any driver requests a slot reset, that is what will be done. |
| 45 | |||
| 46 | After a reset and/or a re-enabling of I/O, all drivers are | ||
| 44 | again notified, so that they may then perform any device setup/config | 47 | again notified, so that they may then perform any device setup/config |
| 45 | that may be required. After these have all completed, a final | 48 | that may be required. After these have all completed, a final |
| 46 | "resume normal operations" event is sent out. | 49 | "resume normal operations" event is sent out. |
| @@ -101,7 +104,7 @@ if it implements any, it must implement error_detected(). If a callback | |||
| 101 | is not implemented, the corresponding feature is considered unsupported. | 104 | is not implemented, the corresponding feature is considered unsupported. |
| 102 | For example, if mmio_enabled() and resume() aren't there, then it | 105 | For example, if mmio_enabled() and resume() aren't there, then it |
| 103 | is assumed that the driver is not doing any direct recovery and requires | 106 | is assumed that the driver is not doing any direct recovery and requires |
| 104 | a reset. If link_reset() is not implemented, the card is assumed as | 107 | a slot reset. If link_reset() is not implemented, the card is assumed to |
| 105 | not care about link resets. Typically a driver will want to know about | 108 | not care about link resets. Typically a driver will want to know about |
| 106 | a slot_reset(). | 109 | a slot_reset(). |
| 107 | 110 | ||
| @@ -111,7 +114,7 @@ sequence described below. | |||
| 111 | 114 | ||
| 112 | STEP 0: Error Event | 115 | STEP 0: Error Event |
| 113 | ------------------- | 116 | ------------------- |
| 114 | PCI bus error is detect by the PCI hardware. On powerpc, the slot | 117 | A PCI bus error is detected by the PCI hardware. On powerpc, the slot |
| 115 | is isolated, in that all I/O is blocked: all reads return 0xffffffff, | 118 | is isolated, in that all I/O is blocked: all reads return 0xffffffff, |
| 116 | all writes are ignored. | 119 | all writes are ignored. |
| 117 | 120 | ||
| @@ -139,7 +142,7 @@ The driver must return one of the following result codes: | |||
| 139 | a chance to extract some diagnostic information (see | 142 | a chance to extract some diagnostic information (see |
| 140 | mmio_enable, below). | 143 | mmio_enable, below). |
| 141 | - PCI_ERS_RESULT_NEED_RESET: | 144 | - PCI_ERS_RESULT_NEED_RESET: |
| 142 | Driver returns this if it can't recover without a hard | 145 | Driver returns this if it can't recover without a |
| 143 | slot reset. | 146 | slot reset. |
| 144 | - PCI_ERS_RESULT_DISCONNECT: | 147 | - PCI_ERS_RESULT_DISCONNECT: |
| 145 | Driver returns this if it doesn't want to recover at all. | 148 | Driver returns this if it doesn't want to recover at all. |
| @@ -169,11 +172,11 @@ is STEP 6 (Permanent Failure). | |||
| 169 | 172 | ||
| 170 | >>> The current powerpc implementation doesn't much care if the device | 173 | >>> The current powerpc implementation doesn't much care if the device |
| 171 | >>> attempts I/O at this point, or not. I/O's will fail, returning | 174 | >>> attempts I/O at this point, or not. I/O's will fail, returning |
| 172 | >>> a value of 0xff on read, and writes will be dropped. If the device | 175 | >>> a value of 0xff on read, and writes will be dropped. If more than |
| 173 | >>> driver attempts more than 10K I/O's to a frozen adapter, it will | 176 | >>> EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH |
| 174 | >>> assume that the device driver has gone into an infinite loop, and | 177 | >>> assumes that the device driver has gone into an infinite loop |
| 175 | >>> it will panic the kernel. There doesn't seem to be any other | 178 | >>> and prints an error to syslog. A reboot is then required to |
| 176 | >>> way of stopping a device driver that insists on spinning on I/O. | 179 | >>> get the device working again. |
| 177 | 180 | ||
| 178 | STEP 2: MMIO Enabled | 181 | STEP 2: MMIO Enabled |
| 179 | ------------------- | 182 | ------------------- |
| @@ -182,15 +185,14 @@ DMA), and then calls the mmio_enabled() callback on all affected | |||
| 182 | device drivers. | 185 | device drivers. |
| 183 | 186 | ||
| 184 | This is the "early recovery" call. IOs are allowed again, but DMA is | 187 | This is the "early recovery" call. IOs are allowed again, but DMA is |
| 185 | not (hrm... to be discussed, I prefer not), with some restrictions. This | 188 | not, with some restrictions. This is NOT a callback for the driver to |
| 186 | is NOT a callback for the driver to start operations again, only to | 189 | start operations again, only to peek/poke at the device, extract diagnostic |
| 187 | peek/poke at the device, extract diagnostic information, if any, and | 190 | information, if any, and eventually do things like trigger a device local |
| 188 | eventually do things like trigger a device local reset or some such, | 191 | reset or some such, but not restart operations. This callback is made if |
| 189 | but not restart operations. This is callback is made if all drivers on | 192 | all drivers on a segment agree that they can try to recover and if no automatic |
| 190 | a segment agree that they can try to recover and if no automatic link reset | 193 | link reset was performed by the HW. If the platform can't just re-enable IOs |
| 191 | was performed by the HW. If the platform can't just re-enable IOs without | 194 | without a slot reset or a link reset, it will not call this callback, and |
| 192 | a slot reset or a link reset, it wont call this callback, and instead | 195 | instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset) |
| 193 | will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset) | ||
| 194 | 196 | ||
| 195 | >>> The following is proposed; no platform implements this yet: | 197 | >>> The following is proposed; no platform implements this yet: |
| 196 | >>> Proposal: All I/O's should be done _synchronously_ from within | 198 | >>> Proposal: All I/O's should be done _synchronously_ from within |
| @@ -228,9 +230,6 @@ proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations). | |||
| 228 | If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform | 230 | If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform |
| 229 | proceeds to STEP 4 (Slot Reset) | 231 | proceeds to STEP 4 (Slot Reset) |
| 230 | 232 | ||
| 231 | >>> The current powerpc implementation does not implement this callback. | ||
| 232 | |||
| 233 | |||
| 234 | STEP 3: Link Reset | 233 | STEP 3: Link Reset |
| 235 | ------------------ | 234 | ------------------ |
| 236 | The platform resets the link, and then calls the link_reset() callback | 235 | The platform resets the link, and then calls the link_reset() callback |
| @@ -253,16 +252,33 @@ The platform then proceeds to either STEP 4 (Slot Reset) or STEP 5 | |||
| 253 | 252 | ||
| 254 | >>> The current powerpc implementation does not implement this callback. | 253 | >>> The current powerpc implementation does not implement this callback. |
| 255 | 254 | ||
| 256 | |||
| 257 | STEP 4: Slot Reset | 255 | STEP 4: Slot Reset |
| 258 | ------------------ | 256 | ------------------ |
| 259 | The platform performs a soft or hard reset of the device, and then | ||
| 260 | calls the slot_reset() callback. | ||
| 261 | 257 | ||
| 262 | A soft reset consists of asserting the adapter #RST line and then | 258 | In response to a return value of PCI_ERS_RESULT_NEED_RESET, the |
| 259 | the platform will peform a slot reset on the requesting PCI device(s). | ||
| 260 | The actual steps taken by a platform to perform a slot reset | ||
| 261 | will be platform-dependent. Upon completion of slot reset, the | ||
| 262 | platform will call the device slot_reset() callback. | ||
| 263 | |||
| 264 | Powerpc platforms implement two levels of slot reset: | ||
| 265 | soft reset(default) and fundamental(optional) reset. | ||
| 266 | |||
| 267 | Powerpc soft reset consists of asserting the adapter #RST line and then | ||
| 263 | restoring the PCI BAR's and PCI configuration header to a state | 268 | restoring the PCI BAR's and PCI configuration header to a state |
| 264 | that is equivalent to what it would be after a fresh system | 269 | that is equivalent to what it would be after a fresh system |
| 265 | power-on followed by power-on BIOS/system firmware initialization. | 270 | power-on followed by power-on BIOS/system firmware initialization. |
| 271 | Soft reset is also known as hot-reset. | ||
| 272 | |||
| 273 | Powerpc fundamental reset is supported by PCI Express cards only | ||
| 274 | and results in device's state machines, hardware logic, port states and | ||
| 275 | configuration registers to initialize to their default conditions. | ||
| 276 | |||
| 277 | For most PCI devices, a soft reset will be sufficient for recovery. | ||
| 278 | Optional fundamental reset is provided to support a limited number | ||
| 279 | of PCI Express PCI devices for which a soft reset is not sufficient | ||
| 280 | for recovery. | ||
| 281 | |||
| 266 | If the platform supports PCI hotplug, then the reset might be | 282 | If the platform supports PCI hotplug, then the reset might be |
| 267 | performed by toggling the slot electrical power off/on. | 283 | performed by toggling the slot electrical power off/on. |
| 268 | 284 | ||
| @@ -274,10 +290,12 @@ may result in hung devices, kernel panics, or silent data corruption. | |||
| 274 | 290 | ||
| 275 | This call gives drivers the chance to re-initialize the hardware | 291 | This call gives drivers the chance to re-initialize the hardware |
| 276 | (re-download firmware, etc.). At this point, the driver may assume | 292 | (re-download firmware, etc.). At this point, the driver may assume |
| 277 | that he card is in a fresh state and is fully functional. In | 293 | that the card is in a fresh state and is fully functional. The slot |
| 278 | particular, interrupt generation should work normally. | 294 | is unfrozen and the driver has full access to PCI config space, |
| 295 | memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X) | ||
| 296 | will also be available. | ||
| 279 | 297 | ||
| 280 | Drivers should not yet restart normal I/O processing operations | 298 | Drivers should not restart normal I/O processing operations |
| 281 | at this point. If all device drivers report success on this | 299 | at this point. If all device drivers report success on this |
| 282 | callback, the platform will call resume() to complete the sequence, | 300 | callback, the platform will call resume() to complete the sequence, |
| 283 | and let the driver restart normal I/O processing. | 301 | and let the driver restart normal I/O processing. |
| @@ -302,11 +320,21 @@ driver performs device init only from PCI function 0: | |||
| 302 | - PCI_ERS_RESULT_DISCONNECT | 320 | - PCI_ERS_RESULT_DISCONNECT |
| 303 | Same as above. | 321 | Same as above. |
| 304 | 322 | ||
| 323 | Drivers for PCI Express cards that require a fundamental reset must | ||
| 324 | set the needs_freset bit in the pci_dev structure in their probe function. | ||
| 325 | For example, the QLogic qla2xxx driver sets the needs_freset bit for certain | ||
| 326 | PCI card types: | ||
| 327 | |||
| 328 | + /* Set EEH reset type to fundamental if required by hba */ | ||
| 329 | + if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha)) | ||
| 330 | + pdev->needs_freset = 1; | ||
| 331 | + | ||
| 332 | |||
| 305 | Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent | 333 | Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent |
| 306 | Failure). | 334 | Failure). |
| 307 | 335 | ||
| 308 | >>> The current powerpc implementation does not currently try a | 336 | >>> The current powerpc implementation does not try a power-cycle |
| 309 | >>> power-cycle reset if the driver returned PCI_ERS_RESULT_DISCONNECT. | 337 | >>> reset if the driver returned PCI_ERS_RESULT_DISCONNECT. |
| 310 | >>> However, it probably should. | 338 | >>> However, it probably should. |
| 311 | 339 | ||
| 312 | 340 | ||
| @@ -348,7 +376,7 @@ software errors. | |||
| 348 | 376 | ||
| 349 | Conclusion; General Remarks | 377 | Conclusion; General Remarks |
| 350 | --------------------------- | 378 | --------------------------- |
| 351 | The way those callbacks are called is platform policy. A platform with | 379 | The way the callbacks are called is platform policy. A platform with |
| 352 | no slot reset capability may want to just "ignore" drivers that can't | 380 | no slot reset capability may want to just "ignore" drivers that can't |
| 353 | recover (disconnect them) and try to let other cards on the same segment | 381 | recover (disconnect them) and try to let other cards on the same segment |
| 354 | recover. Keep in mind that in most real life cases, though, there will | 382 | recover. Keep in mind that in most real life cases, though, there will |
| @@ -361,8 +389,8 @@ That is, the recovery API only requires that: | |||
| 361 | 389 | ||
| 362 | - There is no guarantee that interrupt delivery can proceed from any | 390 | - There is no guarantee that interrupt delivery can proceed from any |
| 363 | device on the segment starting from the error detection and until the | 391 | device on the segment starting from the error detection and until the |
| 364 | resume callback is sent, at which point interrupts are expected to be | 392 | slot_reset callback is called, at which point interrupts are expected |
| 365 | fully operational. | 393 | to be fully operational. |
| 366 | 394 | ||
| 367 | - There is no guarantee that interrupt delivery is stopped, that is, | 395 | - There is no guarantee that interrupt delivery is stopped, that is, |
| 368 | a driver that gets an interrupt after detecting an error, or that detects | 396 | a driver that gets an interrupt after detecting an error, or that detects |
| @@ -381,16 +409,23 @@ anyway :) | |||
| 381 | >>> Implementation details for the powerpc platform are discussed in | 409 | >>> Implementation details for the powerpc platform are discussed in |
| 382 | >>> the file Documentation/powerpc/eeh-pci-error-recovery.txt | 410 | >>> the file Documentation/powerpc/eeh-pci-error-recovery.txt |
| 383 | 411 | ||
| 384 | >>> As of this writing, there are six device drivers with patches | 412 | >>> As of this writing, there is a growing list of device drivers with |
| 385 | >>> implementing error recovery. Not all of these patches are in | 413 | >>> patches implementing error recovery. Not all of these patches are in |
| 386 | >>> mainline yet. These may be used as "examples": | 414 | >>> mainline yet. These may be used as "examples": |
| 387 | >>> | 415 | >>> |
| 388 | >>> drivers/scsi/ipr.c | 416 | >>> drivers/scsi/ipr |
| 389 | >>> drivers/scsi/sym53cxx_2 | 417 | >>> drivers/scsi/sym53c8xx_2 |
| 418 | >>> drivers/scsi/qla2xxx | ||
| 419 | >>> drivers/scsi/lpfc | ||
| 420 | >>> drivers/next/bnx2.c | ||
| 390 | >>> drivers/next/e100.c | 421 | >>> drivers/next/e100.c |
| 391 | >>> drivers/net/e1000 | 422 | >>> drivers/net/e1000 |
| 423 | >>> drivers/net/e1000e | ||
| 392 | >>> drivers/net/ixgb | 424 | >>> drivers/net/ixgb |
| 425 | >>> drivers/net/ixgbe | ||
| 426 | >>> drivers/net/cxgb3 | ||
| 393 | >>> drivers/net/s2io.c | 427 | >>> drivers/net/s2io.c |
| 428 | >>> drivers/net/qlge | ||
| 394 | 429 | ||
| 395 | The End | 430 | The End |
| 396 | ------- | 431 | ------- |
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 5c555a8b39e5..b7f9d3b4bbf6 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches | |||
| @@ -183,7 +183,7 @@ the MAN-PAGES maintainer (as listed in the MAINTAINERS file) | |||
| 183 | a man-pages patch, or at least a notification of the change, | 183 | a man-pages patch, or at least a notification of the change, |
| 184 | so that some information makes its way into the manual pages. | 184 | so that some information makes its way into the manual pages. |
| 185 | 185 | ||
| 186 | Even if the maintainer did not respond in step #4, make sure to ALWAYS | 186 | Even if the maintainer did not respond in step #5, make sure to ALWAYS |
| 187 | copy the maintainer when you change their code. | 187 | copy the maintainer when you change their code. |
| 188 | 188 | ||
| 189 | For small patches you may want to CC the Trivial Patch Monkey | 189 | For small patches you may want to CC the Trivial Patch Monkey |
diff --git a/Documentation/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 | ||
| 119 | int send_cmd(int sd, __u16 nlmsg_type, __u32 nlmsg_pid, | 119 | static 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 | */ |
| 163 | int get_family_id(int sd) | 163 | static 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 | ||
| 193 | void print_delayacct(struct taskstats *t) | 193 | static 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 | ||
| 219 | void task_context_switch_counts(struct taskstats *t) | 219 | static 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 | ||
| 227 | void print_cgroupstats(struct cgroupstats *c) | 227 | static 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 | ||
| 238 | void print_ioacct(struct taskstats *t) | 238 | static 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 | |||
| 2 | The OMAP PM interface | ||
| 3 | ===================== | ||
| 4 | |||
| 5 | This document describes the temporary OMAP PM interface. Driver | ||
| 6 | authors use these functions to communicate minimum latency or | ||
| 7 | throughput constraints to the kernel power management code. | ||
| 8 | Over time, the intention is to merge features from the OMAP PM | ||
| 9 | interface into the Linux PM QoS code. | ||
| 10 | |||
| 11 | Drivers need to express PM parameters which: | ||
| 12 | |||
| 13 | - support the range of power management parameters present in the TI SRF; | ||
| 14 | |||
| 15 | - separate the drivers from the underlying PM parameter | ||
| 16 | implementation, whether it is the TI SRF or Linux PM QoS or Linux | ||
| 17 | latency framework or something else; | ||
| 18 | |||
| 19 | - specify PM parameters in terms of fundamental units, such as | ||
| 20 | latency and throughput, rather than units which are specific to OMAP | ||
| 21 | or to particular OMAP variants; | ||
| 22 | |||
| 23 | - allow drivers which are shared with other architectures (e.g., | ||
| 24 | DaVinci) to add these constraints in a way which won't affect non-OMAP | ||
| 25 | systems, | ||
| 26 | |||
| 27 | - can be implemented immediately with minimal disruption of other | ||
| 28 | architectures. | ||
| 29 | |||
| 30 | |||
| 31 | This document proposes the OMAP PM interface, including the following | ||
| 32 | five power management functions for driver code: | ||
| 33 | |||
| 34 | 1. Set the maximum MPU wakeup latency: | ||
| 35 | (*pdata->set_max_mpu_wakeup_lat)(struct device *dev, unsigned long t) | ||
| 36 | |||
| 37 | 2. Set the maximum device wakeup latency: | ||
| 38 | (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t) | ||
| 39 | |||
| 40 | 3. Set the maximum system DMA transfer start latency (CORE pwrdm): | ||
| 41 | (*pdata->set_max_sdma_lat)(struct device *dev, long t) | ||
| 42 | |||
| 43 | 4. Set the minimum bus throughput needed by a device: | ||
| 44 | (*pdata->set_min_bus_tput)(struct device *dev, u8 agent_id, unsigned long r) | ||
| 45 | |||
| 46 | 5. Return the number of times the device has lost context | ||
| 47 | (*pdata->get_dev_context_loss_count)(struct device *dev) | ||
| 48 | |||
| 49 | |||
| 50 | Further documentation for all OMAP PM interface functions can be | ||
| 51 | found in arch/arm/plat-omap/include/mach/omap-pm.h. | ||
| 52 | |||
| 53 | |||
| 54 | The OMAP PM layer is intended to be temporary | ||
| 55 | --------------------------------------------- | ||
| 56 | |||
| 57 | The intention is that eventually the Linux PM QoS layer should support | ||
| 58 | the range of power management features present in OMAP3. As this | ||
| 59 | happens, existing drivers using the OMAP PM interface can be modified | ||
| 60 | to use the Linux PM QoS code; and the OMAP PM interface can disappear. | ||
| 61 | |||
| 62 | |||
| 63 | Driver usage of the OMAP PM functions | ||
| 64 | ------------------------------------- | ||
| 65 | |||
| 66 | As the 'pdata' in the above examples indicates, these functions are | ||
| 67 | exposed to drivers through function pointers in driver .platform_data | ||
| 68 | structures. The function pointers are initialized by the board-*.c | ||
| 69 | files to point to the corresponding OMAP PM functions: | ||
| 70 | .set_max_dev_wakeup_lat will point to | ||
| 71 | omap_pm_set_max_dev_wakeup_lat(), etc. Other architectures which do | ||
| 72 | not support these functions should leave these function pointers set | ||
| 73 | to NULL. Drivers should use the following idiom: | ||
| 74 | |||
| 75 | if (pdata->set_max_dev_wakeup_lat) | ||
| 76 | (*pdata->set_max_dev_wakeup_lat)(dev, t); | ||
| 77 | |||
| 78 | The most common usage of these functions will probably be to specify | ||
| 79 | the maximum time from when an interrupt occurs, to when the device | ||
| 80 | becomes accessible. To accomplish this, driver writers should use the | ||
| 81 | set_max_mpu_wakeup_lat() function to to constrain the MPU wakeup | ||
| 82 | latency, and the set_max_dev_wakeup_lat() function to constrain the | ||
| 83 | device wakeup latency (from clk_enable() to accessibility). For | ||
| 84 | example, | ||
| 85 | |||
| 86 | /* Limit MPU wakeup latency */ | ||
| 87 | if (pdata->set_max_mpu_wakeup_lat) | ||
| 88 | (*pdata->set_max_mpu_wakeup_lat)(dev, tc); | ||
| 89 | |||
| 90 | /* Limit device powerdomain wakeup latency */ | ||
| 91 | if (pdata->set_max_dev_wakeup_lat) | ||
| 92 | (*pdata->set_max_dev_wakeup_lat)(dev, td); | ||
| 93 | |||
| 94 | /* total wakeup latency in this example: (tc + td) */ | ||
| 95 | |||
| 96 | The PM parameters can be overwritten by calling the function again | ||
| 97 | with the new value. The settings can be removed by calling the | ||
| 98 | function with a t argument of -1 (except in the case of | ||
| 99 | set_max_bus_tput(), which should be called with an r argument of 0). | ||
| 100 | |||
| 101 | The fifth function above, omap_pm_get_dev_context_loss_count(), | ||
| 102 | is intended as an optimization to allow drivers to determine whether the | ||
| 103 | device has lost its internal context. If context has been lost, the | ||
| 104 | driver must restore its internal context before proceeding. | ||
| 105 | |||
| 106 | |||
| 107 | Other specialized interface functions | ||
| 108 | ------------------------------------- | ||
| 109 | |||
| 110 | The five functions listed above are intended to be usable by any | ||
| 111 | device driver. DSPBridge and CPUFreq have a few special requirements. | ||
| 112 | DSPBridge expresses target DSP performance levels in terms of OPP IDs. | ||
| 113 | CPUFreq expresses target MPU performance levels in terms of MPU | ||
| 114 | frequency. The OMAP PM interface contains functions for these | ||
| 115 | specialized cases to convert that input information (OPPs/MPU | ||
| 116 | frequency) into the form that the underlying power management | ||
| 117 | implementation needs: | ||
| 118 | |||
| 119 | 6. (*pdata->dsp_get_opp_table)(void) | ||
| 120 | |||
| 121 | 7. (*pdata->dsp_set_min_opp)(u8 opp_id) | ||
| 122 | |||
| 123 | 8. (*pdata->dsp_get_opp)(void) | ||
| 124 | |||
| 125 | 9. (*pdata->cpu_get_freq_table)(void) | ||
| 126 | |||
| 127 | 10. (*pdata->cpu_set_freq)(unsigned long f) | ||
| 128 | |||
| 129 | 11. (*pdata->cpu_get_freq)(void) | ||
diff --git a/Documentation/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 | */ |
| 65 | int cfag12864b_init(char *path) | 65 | static 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 | */ |
| 84 | void cfag12864b_exit(void) | 84 | static 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 | */ |
| 93 | void cfag12864b_set(unsigned char x, unsigned char y) | 93 | static 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 | */ |
| 103 | void cfag12864b_unset(unsigned char x, unsigned char y) | 103 | static 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 | */ |
| 116 | unsigned char cfag12864b_isset(unsigned char x, unsigned char y) | 116 | static 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 | */ |
| 129 | void cfag12864b_not(unsigned char x, unsigned char y) | 129 | static 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 | */ |
| 140 | void cfag12864b_fill(void) | 140 | static 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 | */ |
| 151 | void cfag12864b_clear(void) | 151 | static 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 | */ |
| 165 | void cfag12864b_format(unsigned char * matrix) | 165 | static 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 | */ |
| 185 | void cfag12864b_blit(void) | 185 | static 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 | ||
| 201 | void example(unsigned char n) | 200 | static 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 | ||
| 411 | 2.3 Mounting hierarchies by name | ||
| 412 | -------------------------------- | ||
| 413 | |||
| 414 | Passing the name=<x> option when mounting a cgroups hierarchy | ||
| 415 | associates the given name with the hierarchy. This can be used when | ||
| 416 | mounting a pre-existing hierarchy, in order to refer to it by name | ||
| 417 | rather than by its set of active subsystems. Each hierarchy is either | ||
| 418 | nameless, or has a unique name. | ||
| 419 | |||
| 420 | The name should match [\w.-]+ | ||
| 421 | |||
| 422 | When passing a name=<x> option for a new hierarchy, you need to | ||
| 423 | specify subsystems manually; the legacy behaviour of mounting all | ||
| 424 | subsystems when none are explicitly specified is not supported when | ||
| 425 | you give a subsystem a name. | ||
| 426 | |||
| 427 | The name of the subsystem appears as part of the hierarchy description | ||
| 428 | in /proc/mounts and /proc/<pid>/cgroups. | ||
| 429 | |||
| 430 | |||
| 411 | 3. Kernel API | 431 | 3. Kernel API |
| 412 | ============= | 432 | ============= |
| 413 | 433 | ||
| @@ -501,7 +521,7 @@ rmdir() will fail with it. From this behavior, pre_destroy() can be | |||
| 501 | called multiple times against a cgroup. | 521 | called multiple times against a cgroup. |
| 502 | 522 | ||
| 503 | int can_attach(struct cgroup_subsys *ss, struct cgroup *cgrp, | 523 | int 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 | ||
| 507 | Called prior to moving a task into a cgroup; if the subsystem | 527 | Called 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 | |||
| 509 | task is passed, then a successful result indicates that *any* | 529 | task is passed, then a successful result indicates that *any* |
| 510 | unspecified task can be moved into the cgroup. Note that this isn't | 530 | unspecified task can be moved into the cgroup. Note that this isn't |
| 511 | called on a fork. If this method returns 0 (success) then this should | 531 | called on a fork. If this method returns 0 (success) then this should |
| 512 | remain valid while the caller holds cgroup_mutex. | 532 | remain valid while the caller holds cgroup_mutex. If threadgroup is |
| 533 | true, then a successful result indicates that all threads in the given | ||
| 534 | thread's threadgroup can be moved together. | ||
| 513 | 535 | ||
| 514 | void attach(struct cgroup_subsys *ss, struct cgroup *cgrp, | 536 | void 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 | ||
| 518 | Called after the task has been attached to the cgroup, to allow any | 541 | Called after the task has been attached to the cgroup, to allow any |
| 519 | post-attachment activity that requires memory allocations or blocking. | 542 | post-attachment activity that requires memory allocations or blocking. |
| 543 | If threadgroup is true, the subsystem should take care of all threads | ||
| 544 | in the specified thread's threadgroup. Currently does not support any | ||
| 545 | subsystem that might need the old_cgrp for every thread in the group. | ||
| 520 | 546 | ||
| 521 | void fork(struct cgroup_subsy *ss, struct task_struct *task) | 547 | void 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 | |||
| 179 | pages that are selected for reclaiming come from the per cgroup LRU | 179 | pages that are selected for reclaiming come from the per cgroup LRU |
| 180 | list. | 180 | list. |
| 181 | 181 | ||
| 182 | NOTE: Reclaim does not work for the root cgroup, since we cannot set any | ||
| 183 | limits on the root cgroup. | ||
| 184 | |||
| 182 | 2. Locking | 185 | 2. Locking |
| 183 | 186 | ||
| 184 | The memory controller uses the following hierarchy | 187 | The memory controller uses the following hierarchy |
| @@ -210,6 +213,7 @@ We can alter the memory limit: | |||
| 210 | NOTE: We can use a suffix (k, K, m, M, g or G) to indicate values in kilo, | 213 | NOTE: We can use a suffix (k, K, m, M, g or G) to indicate values in kilo, |
| 211 | mega or gigabytes. | 214 | mega or gigabytes. |
| 212 | NOTE: We can write "-1" to reset the *.limit_in_bytes(unlimited). | 215 | NOTE: We can write "-1" to reset the *.limit_in_bytes(unlimited). |
| 216 | NOTE: 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 |
| 215 | 4194304 | 219 | 4194304 |
| @@ -375,7 +379,42 @@ cgroups created below it. | |||
| 375 | 379 | ||
| 376 | NOTE2: This feature can be enabled/disabled per subtree. | 380 | NOTE2: This feature can be enabled/disabled per subtree. |
| 377 | 381 | ||
| 378 | 7. TODO | 382 | 7. Soft limits |
| 383 | |||
| 384 | Soft limits allow for greater sharing of memory. The idea behind soft limits | ||
| 385 | is to allow control groups to use as much of the memory as needed, provided | ||
| 386 | |||
| 387 | a. There is no memory contention | ||
| 388 | b. They do not exceed their hard limit | ||
| 389 | |||
| 390 | When the system detects memory contention or low memory control groups | ||
| 391 | are pushed back to their soft limits. If the soft limit of each control | ||
| 392 | group is very high, they are pushed back as much as possible to make | ||
| 393 | sure that one control group does not starve the others of memory. | ||
| 394 | |||
| 395 | Please note that soft limits is a best effort feature, it comes with | ||
| 396 | no guarantees, but it does its best to make sure that when memory is | ||
| 397 | heavily contended for, memory is allocated based on the soft limit | ||
| 398 | hints/setup. Currently soft limit based reclaim is setup such that | ||
| 399 | it gets invoked from balance_pgdat (kswapd). | ||
| 400 | |||
| 401 | 7.1 Interface | ||
| 402 | |||
| 403 | Soft limits can be setup by using the following commands (in this example we | ||
| 404 | assume a soft limit of 256 megabytes) | ||
| 405 | |||
| 406 | # echo 256M > memory.soft_limit_in_bytes | ||
| 407 | |||
| 408 | If we want to change this to 1G, we can at any time use | ||
| 409 | |||
| 410 | # echo 1G > memory.soft_limit_in_bytes | ||
| 411 | |||
| 412 | NOTE1: Soft limits take effect over a long period of time, since they involve | ||
| 413 | reclaiming memory for balancing between memory cgroups | ||
| 414 | NOTE2: It is recommended to set the soft limit always below the hard limit, | ||
| 415 | otherwise the hard limit will take precedence. | ||
| 416 | |||
| 417 | 8. TODO | ||
| 379 | 418 | ||
| 380 | 1. Add support for accounting huge pages (as a separate controller) | 419 | 1. Add support for accounting huge pages (as a separate controller) |
| 381 | 2. Make per-cgroup scanner reclaim not-shared pages first | 420 | 2. 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 | ||
| 179 | cpuinfo_cur_freq : Current speed of the CPU, in KHz. | 179 | cpuinfo_cur_freq : Current frequency of the CPU as obtained from |
| 180 | the hardware, in KHz. This is the frequency | ||
| 181 | the CPU actually runs at. | ||
| 180 | 182 | ||
| 181 | scaling_available_frequencies : List of available frequencies, in KHz. | 183 | scaling_available_frequencies : List of available frequencies, in KHz. |
| 182 | 184 | ||
| @@ -196,7 +198,10 @@ related_cpus : List of CPUs that need some sort of frequency | |||
| 196 | 198 | ||
| 197 | scaling_driver : Hardware driver for cpufreq. | 199 | scaling_driver : Hardware driver for cpufreq. |
| 198 | 200 | ||
| 199 | scaling_cur_freq : Current frequency of the CPU, in KHz. | 201 | scaling_cur_freq : Current frequency of the CPU as determined by |
| 202 | the governor and cpufreq core, in KHz. This is | ||
| 203 | the frequency the kernel thinks the CPU runs | ||
| 204 | at. | ||
| 200 | 205 | ||
| 201 | If you have selected the "userspace" governor which allows you to | 206 | If you have selected the "userspace" governor which allows you to |
| 202 | set the CPU operating frequency to a specific value, you can read out | 207 | set the CPU operating frequency to a specific value, you can read out |
diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 88519daab6e9..e1efc400bed6 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff | |||
| @@ -152,7 +152,6 @@ piggy.gz | |||
| 152 | piggyback | 152 | piggyback |
| 153 | pnmtologo | 153 | pnmtologo |
| 154 | ppc_defs.h* | 154 | ppc_defs.h* |
| 155 | promcon_tbl.c | ||
| 156 | pss_boot.h | 155 | pss_boot.h |
| 157 | qconf | 156 | qconf |
| 158 | raid6altivec*.c | 157 | raid6altivec*.c |
diff --git a/Documentation/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 |
| 31 | syntax() if (scalar(@ARGV) != 1); | 32 | syntax() if (scalar(@ARGV) != 1); |
| @@ -514,6 +515,40 @@ sub bluebird { | |||
| 514 | $outfile; | 515 | $outfile; |
| 515 | } | 516 | } |
| 516 | 517 | ||
| 518 | sub af9015 { | ||
| 519 | my $sourcefile = "download.ashx?file=57"; | ||
| 520 | my $url = "http://www.ite.com.tw/EN/Services/$sourcefile"; | ||
| 521 | my $hash = "ff5b096ed47c080870eacdab2de33ad6"; | ||
| 522 | my $outfile = "dvb-usb-af9015.fw"; | ||
| 523 | my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); | ||
| 524 | my $fwoffset = 0x22708; | ||
| 525 | my $fwlength = 18225; | ||
| 526 | my ($chunklength, $buf, $rcount); | ||
| 527 | |||
| 528 | checkstandard(); | ||
| 529 | |||
| 530 | wgetfile($sourcefile, $url); | ||
| 531 | unzip($sourcefile, $tmpdir); | ||
| 532 | verify("$tmpdir/Driver/Files/AF15BDA.sys", $hash); | ||
| 533 | |||
| 534 | open INFILE, '<', "$tmpdir/Driver/Files/AF15BDA.sys"; | ||
| 535 | open OUTFILE, '>', $outfile; | ||
| 536 | |||
| 537 | sysseek(INFILE, $fwoffset, SEEK_SET); | ||
| 538 | while($fwlength > 0) { | ||
| 539 | $chunklength = 55; | ||
| 540 | $chunklength = $fwlength if ($chunklength > $fwlength); | ||
| 541 | $rcount = sysread(INFILE, $buf, $chunklength); | ||
| 542 | die "Ran out of data\n" if ($rcount != $chunklength); | ||
| 543 | syswrite(OUTFILE, $buf); | ||
| 544 | sysread(INFILE, $buf, 8); | ||
| 545 | $fwlength -= $rcount + 8; | ||
| 546 | } | ||
| 547 | |||
| 548 | close OUTFILE; | ||
| 549 | close INFILE; | ||
| 550 | } | ||
| 551 | |||
| 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 | |||
| 4 | 1) Find out what device you have | 4 | 1) Find out what device you have |
| 5 | ================================ | 5 | ================================ |
| 6 | 6 | ||
| 7 | Important Notice: The driver does NOT support Technisat USB 2 devices! | ||
| 8 | |||
| 7 | First start your linux box with a shipped kernel: | 9 | First start your linux box with a shipped kernel: |
| 8 | lspci -vvv for a PCI device (lsusb -vvv for an USB device) will show you for example: | 10 | lspci -vvv for a PCI device (lsusb -vvv for an USB device) will show you for example: |
| 9 | 02:0b.0 Network controller: Techsan Electronics Co Ltd B2C2 FlexCopII DVB chip / Technisat SkyStar2 DVB card (rev 02) | 11 | 02:0b.0 Network controller: Techsan Electronics Co Ltd B2C2 FlexCopII DVB chip / |
| 12 | Technisat SkyStar2 DVB card (rev 02) | ||
| 10 | 13 | ||
| 11 | dmesg | grep frontend may show you for example: | 14 | dmesg | grep frontend may show you for example: |
| 12 | DVB: registering frontend 0 (Conexant CX24123/CX24109)... | 15 | DVB: registering frontend 0 (Conexant CX24123/CX24109)... |
| @@ -14,62 +17,62 @@ DVB: registering frontend 0 (Conexant CX24123/CX24109)... | |||
| 14 | 2) Kernel compilation: | 17 | 2) Kernel compilation: |
| 15 | ====================== | 18 | ====================== |
| 16 | 19 | ||
| 17 | If the Technisat is the only TV device in your box get rid of unnecessary modules and check this one: | 20 | If the Flexcop / Technisat is the only DVB / TV / Radio device in your box |
| 18 | "Multimedia devices" => "Customise analog and hybrid tuner modules to build" | 21 | get rid of unnecessary modules and check this one: |
| 19 | In this directory uncheck every driver which is activated there (except "Simple tuner support" for case 9 only). | 22 | "Multimedia support" => "Customise analog and hybrid tuner modules to build" |
| 23 | In this directory uncheck every driver which is activated there | ||
| 24 | (except "Simple tuner support" for ATSC 3rd generation only -> see case 9 please). | ||
| 20 | 25 | ||
| 21 | Then please activate: | 26 | Then please activate: |
| 22 | 2a) Main module part: | 27 | 2a) Main module part: |
| 28 | "Multimedia support" => "DVB/ATSC adapters" | ||
| 29 | => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" | ||
| 23 | 30 | ||
| 24 | a.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" | 31 | a.) => "Technisat/B2C2 Air/Sky/Cable2PC PCI" (PCI card) or |
| 25 | b.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Technisat/B2C2 Air/Sky/Cable2PC PCI" in case of a PCI card | 32 | b.) => "Technisat/B2C2 Air/Sky/Cable2PC USB" (USB 1.1 adapter) |
| 26 | OR | 33 | and for troubleshooting purposes: |
| 27 | c.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Technisat/B2C2 Air/Sky/Cable2PC USB" in case of an USB 1.1 adapter | 34 | c.) => "Enable debug for the B2C2 FlexCop drivers" |
| 28 | d.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Enable debug for the B2C2 FlexCop drivers" | ||
| 29 | Notice: d.) is helpful for troubleshooting | ||
| 30 | 35 | ||
| 31 | 2b) Frontend module part: | 36 | 2b) Frontend / Tuner / Demodulator module part: |
| 37 | "Multimedia support" => "DVB/ATSC adapters" | ||
| 38 | => "Customise the frontend modules to build" "Customise DVB frontends" => | ||
| 32 | 39 | ||
| 33 | 1.) SkyStar DVB-S Revision 2.3: | 40 | 1.) SkyStar DVB-S Revision 2.3: |
| 34 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 41 | a.) => "Zarlink VP310/MT312/ZL10313 based" |
| 35 | b.)"Multimedia devices" => "Customise DVB frontends" => "Zarlink VP310/MT312/ZL10313 based" | 42 | b.) => "Generic I2C PLL based tuners" |
| 36 | 43 | ||
| 37 | 2.) SkyStar DVB-S Revision 2.6: | 44 | 2.) SkyStar DVB-S Revision 2.6: |
| 38 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 45 | a.) => "ST STV0299 based" |
| 39 | b.)"Multimedia devices" => "Customise DVB frontends" => "ST STV0299 based" | 46 | b.) => "Generic I2C PLL based tuners" |
| 40 | 47 | ||
| 41 | 3.) SkyStar DVB-S Revision 2.7: | 48 | 3.) SkyStar DVB-S Revision 2.7: |
| 42 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 49 | a.) => "Samsung S5H1420 based" |
| 43 | b.)"Multimedia devices" => "Customise DVB frontends" => "Samsung S5H1420 based" | 50 | b.) => "Integrant ITD1000 Zero IF tuner for DVB-S/DSS" |
| 44 | c.)"Multimedia devices" => "Customise DVB frontends" => "Integrant ITD1000 Zero IF tuner for DVB-S/DSS" | 51 | c.) => "ISL6421 SEC controller" |
| 45 | d.)"Multimedia devices" => "Customise DVB frontends" => "ISL6421 SEC controller" | ||
| 46 | 52 | ||
| 47 | 4.) SkyStar DVB-S Revision 2.8: | 53 | 4.) SkyStar DVB-S Revision 2.8: |
| 48 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 54 | a.) => "Conexant CX24123 based" |
| 49 | b.)"Multimedia devices" => "Customise DVB frontends" => "Conexant CX24113/CX24128 tuner for DVB-S/DSS" | 55 | b.) => "Conexant CX24113/CX24128 tuner for DVB-S/DSS" |
| 50 | c.)"Multimedia devices" => "Customise DVB frontends" => "Conexant CX24123 based" | 56 | c.) => "ISL6421 SEC controller" |
| 51 | d.)"Multimedia devices" => "Customise DVB frontends" => "ISL6421 SEC controller" | ||
| 52 | 57 | ||
| 53 | 5.) AirStar DVB-T card: | 58 | 5.) AirStar DVB-T card: |
| 54 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 59 | a.) => "Zarlink MT352 based" |
| 55 | b.)"Multimedia devices" => "Customise DVB frontends" => "Zarlink MT352 based" | 60 | b.) => "Generic I2C PLL based tuners" |
| 56 | 61 | ||
| 57 | 6.) CableStar DVB-C card: | 62 | 6.) CableStar DVB-C card: |
| 58 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 63 | a.) => "ST STV0297 based" |
| 59 | b.)"Multimedia devices" => "Customise DVB frontends" => "ST STV0297 based" | 64 | b.) => "Generic I2C PLL based tuners" |
| 60 | 65 | ||
| 61 | 7.) AirStar ATSC card 1st generation: | 66 | 7.) AirStar ATSC card 1st generation: |
| 62 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 67 | a.) => "Broadcom BCM3510" |
| 63 | b.)"Multimedia devices" => "Customise DVB frontends" => "Broadcom BCM3510" | ||
| 64 | 68 | ||
| 65 | 8.) AirStar ATSC card 2nd generation: | 69 | 8.) AirStar ATSC card 2nd generation: |
| 66 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 70 | a.) => "NxtWave Communications NXT2002/NXT2004 based" |
| 67 | b.)"Multimedia devices" => "Customise DVB frontends" => "NxtWave Communications NXT2002/NXT2004 based" | 71 | b.) => "Generic I2C PLL based tuners" |
| 68 | c.)"Multimedia devices" => "Customise DVB frontends" => "Generic I2C PLL based tuners" | ||
| 69 | 72 | ||
| 70 | 9.) AirStar ATSC card 3rd generation: | 73 | 9.) AirStar ATSC card 3rd generation: |
| 71 | a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" | 74 | a.) => "LG Electronics LGDT3302/LGDT3303 based" |
| 72 | b.)"Multimedia devices" => "Customise DVB frontends" => "LG Electronics LGDT3302/LGDT3303 based" | 75 | b.) "Multimedia support" => "Customise analog and hybrid tuner modules to build" |
| 73 | c.)"Multimedia devices" => "Customise analog and hybrid tuner modules to build" => "Simple tuner support" | 76 | => "Simple tuner support" |
| 74 | 77 | ||
| 75 | Author: Uwe Bugla <uwe.bugla@gmx.de> February 2009 | 78 | Author: Uwe Bugla <uwe.bugla@gmx.de> August 2009 |
diff --git a/Documentation/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 | ================================ | ||
| 2 | Driver for EP93xx LCD controller | ||
| 3 | ================================ | ||
| 4 | |||
| 5 | The EP93xx LCD controller can drive both standard desktop monitors and | ||
| 6 | embedded LCD displays. If you have a standard desktop monitor then you | ||
| 7 | can 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 | |||
| 14 | If you have an embedded LCD display then you need to define a video | ||
| 15 | mode 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 | |||
| 24 | Note that the pixel clock value is in pico-seconds. You can use the | ||
| 25 | KHZ2PICOS macro to convert the pixel clock value. Most other values | ||
| 26 | are in pixel clocks. See Documentation/fb/framebuffer.txt for further | ||
| 27 | details. | ||
| 28 | |||
| 29 | The ep93xxfb_mach_info structure for your board should look like the | ||
| 30 | following: | ||
| 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 | |||
| 39 | The framebuffer device can be registered by adding the following to | ||
| 40 | your board initialisation function: | ||
| 41 | |||
| 42 | ep93xx_register_fb(&some_board_fb_info); | ||
| 43 | |||
| 44 | ===================== | ||
| 45 | Video Attribute Flags | ||
| 46 | ===================== | ||
| 47 | |||
| 48 | The ep93xxfb_mach_info structure has a flags field which can be used | ||
| 49 | to configure the controller. The video attributes flags are fully | ||
| 50 | documented in section 7 of the EP93xx users' guide. The following | ||
| 51 | flags are available: | ||
| 52 | |||
| 53 | EP93XXFB_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 | |||
| 57 | EP93XXFB_SYNC_BLANK_HIGH Blank signal is active high. By | ||
| 58 | default the blank signal is active low. | ||
| 59 | |||
| 60 | EP93XXFB_SYNC_HORIZ_HIGH Horizontal sync is active high. By | ||
| 61 | default the horizontal sync is active low. | ||
| 62 | |||
| 63 | EP93XXFB_SYNC_VERT_HIGH Vertical sync is active high. By | ||
| 64 | default the vertical sync is active high. | ||
| 65 | |||
| 66 | The physical address of the framebuffer can be controlled using the | ||
| 67 | following flags: | ||
| 68 | |||
| 69 | EP93XXFB_USE_SDCSN0 Use SDCSn[0] for the framebuffer. This | ||
| 70 | is the default setting. | ||
| 71 | |||
| 72 | EP93XXFB_USE_SDCSN1 Use SDCSn[1] for the framebuffer. | ||
| 73 | |||
| 74 | EP93XXFB_USE_SDCSN2 Use SDCSn[2] for the framebuffer. | ||
| 75 | |||
| 76 | EP93XXFB_USE_SDCSN3 Use SDCSn[3] for the framebuffer. | ||
| 77 | |||
| 78 | ================== | ||
| 79 | Platform callbacks | ||
| 80 | ================== | ||
| 81 | |||
| 82 | The EP93xx framebuffer driver supports three optional platform | ||
| 83 | callbacks: setup, teardown and blank. The setup and teardown functions | ||
| 84 | are called when the framebuffer driver is installed and removed | ||
| 85 | respectively. The blank function is called whenever the display is | ||
| 86 | blanked or unblanked. | ||
| 87 | |||
| 88 | The setup and teardown devices pass the platform_device structure as | ||
| 89 | an argument. The fb_info and ep93xxfb_mach_info structures can be | ||
| 90 | obtained 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 | ====================== | ||
| 101 | Setting the video mode | ||
| 102 | ====================== | ||
| 103 | |||
| 104 | The video mode is set using the following syntax: | ||
| 105 | |||
| 106 | video=XRESxYRES[-BPP][@REFRESH] | ||
| 107 | |||
| 108 | If the EP93xx video driver is built-in then the video mode is set on | ||
| 109 | the Linux kernel command line, for example: | ||
| 110 | |||
| 111 | video=ep93xx-fb:800x600-16@60 | ||
| 112 | |||
| 113 | If the EP93xx video driver is built as a module then the video mode is | ||
| 114 | set when the module is installed: | ||
| 115 | |||
| 116 | modprobe ep93xx-fb video=320x240 | ||
| 117 | |||
| 118 | ============== | ||
| 119 | Screenpage bug | ||
| 120 | ============== | ||
| 121 | |||
| 122 | At least on the EP9315 there is a silicon bug which causes bit 27 of | ||
| 123 | the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is | ||
| 124 | an unofficial errata for this bug at: | ||
| 125 | http://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2 | ||
| 126 | |||
| 127 | By default the EP93xx framebuffer driver checks if the allocated physical | ||
| 128 | address has bit 27 set. If it does, then the memory is freed and an | ||
| 129 | error is returned. The check can be disabled by adding the following | ||
| 130 | option when loading the driver: | ||
| 131 | |||
| 132 | ep93xx-fb.check_screenpage_bug=0 | ||
| 133 | |||
| 134 | In some cases it may be possible to reconfigure your SDRAM layout to | ||
| 135 | avoid 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. | |||
| 186 | dev:X - bind driver to device X. Driver numbers device from 0 up to N, | 186 | dev: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. | ||
| 192 | nohwcursor - disables hardware cursor (use software cursor instead). | 190 | nohwcursor - disables hardware cursor (use software cursor instead). |
| 193 | hwcursor - enables hardware cursor. It is default. If you are using | 191 | hwcursor - 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 | ||
| 357 | What: fscher and fscpos drivers | ||
| 358 | When: June 2009 | ||
| 359 | Why: Deprecated by the new fschmd driver. | ||
| 360 | Who: Hans de Goede <hdegoede@redhat.com> | ||
| 361 | Jean Delvare <khali@linux-fr.org> | ||
| 362 | |||
| 363 | --------------------------- | ||
| 364 | |||
| 365 | What: sysfs ui for changing p4-clockmod parameters | 357 | What: sysfs ui for changing p4-clockmod parameters |
| 366 | When: September 2009 | 358 | When: September 2009 |
| 367 | Why: See commits 129f8ae9b1b5be94517da76009ea956e89104ce8 and | 359 | Why: See commits 129f8ae9b1b5be94517da76009ea956e89104ce8 and |
| @@ -428,16 +420,6 @@ Who: Johannes Berg <johannes@sipsolutions.net> | |||
| 428 | 420 | ||
| 429 | ---------------------------- | 421 | ---------------------------- |
| 430 | 422 | ||
| 431 | What: CONFIG_X86_OLD_MCE | ||
| 432 | When: 2.6.32 | ||
| 433 | Why: 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. | ||
| 437 | Who: Andi Kleen <andi@firstfloor.org> | ||
| 438 | |||
| 439 | ---------------------------- | ||
| 440 | |||
| 441 | What: lock_policy_rwsem_* and unlock_policy_rwsem_* will not be | 423 | What: lock_policy_rwsem_* and unlock_policy_rwsem_* will not be |
| 442 | exported interface anymore. | 424 | exported interface anymore. |
| 443 | When: 2.6.33 | 425 | When: 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 | ||
| 19 | Other applications are described in the following papers: | 19 | Other 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 | |||
| 103 | RESOURCES | 114 | RESOURCES |
| 104 | ========= | 115 | ========= |
| 105 | 116 | ||
| @@ -118,7 +129,7 @@ and export. | |||
| 118 | A Linux version of the 9p server is now maintained under the npfs project | 129 | A Linux version of the 9p server is now maintained under the npfs project |
| 119 | on sourceforge (http://sourceforge.net/projects/npfs). The currently | 130 | on sourceforge (http://sourceforge.net/projects/npfs). The currently |
| 120 | maintained version is the single-threaded version of the server (named spfs) | 131 | maintained version is the single-threaded version of the server (named spfs) |
| 121 | available from the same CVS repository. | 132 | available from the same SVN repository. |
| 122 | 133 | ||
| 123 | There are user and developer mailing lists available through the v9fs project | 134 | There are user and developer mailing lists available through the v9fs project |
| 124 | on sourceforge (http://sourceforge.net/projects/v9fs). | 135 | on sourceforge (http://sourceforge.net/projects/v9fs). |
| @@ -126,7 +137,8 @@ on sourceforge (http://sourceforge.net/projects/v9fs). | |||
| 126 | A stand-alone version of the module (which should build for any 2.6 kernel) | 137 | A stand-alone version of the module (which should build for any 2.6 kernel) |
| 127 | is available via (http://github.com/ericvh/9p-sac/tree/master) | 138 | is available via (http://github.com/ericvh/9p-sac/tree/master) |
| 128 | 139 | ||
| 129 | News and other information is maintained on SWiK (http://swik.net/v9fs). | 140 | News and other information is maintained on SWiK (http://swik.net/v9fs) |
| 141 | and the Wiki (http://sf.net/apps/mediawiki/v9fs/index.php). | ||
| 130 | 142 | ||
| 131 | Bug reports may be issued through the kernel.org bugzilla | 143 | Bug 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 | ||
| 137 | journal_checksum Enable checksumming of the journal transactions. | ||
| 138 | This will allow the recovery code in e2fsck and the | ||
| 139 | kernel to detect corruption in the kernel. It is a | ||
| 140 | compatible change and will be ignored by older kernels. | ||
| 141 | |||
| 142 | journal_async_commit Commit block can be written to disk without waiting | 137 | journal_async_commit Commit block can be written to disk without waiting |
| 143 | for descriptor blocks. If enabled older kernels cannot | 138 | for descriptor blocks. If enabled older kernels cannot |
| 144 | mount the device. This will enable 'journal_checksum' | 139 | mount the device. |
| 145 | internally. | ||
| 146 | 140 | ||
| 147 | journal=update Update the ext4 file system's journal to the current | 141 | journal=update Update the ext4 file system's journal to the current |
| 148 | format. | 142 | format. |
| @@ -263,10 +257,18 @@ resuid=n The user ID which may use the reserved blocks. | |||
| 263 | 257 | ||
| 264 | sb=n Use alternate superblock at this location. | 258 | sb=n Use alternate superblock at this location. |
| 265 | 259 | ||
| 266 | quota | 260 | quota These options are ignored by the filesystem. They |
| 267 | noquota | 261 | noquota are used only by quota tools to recognize volumes |
| 268 | grpquota | 262 | grpquota where quota should be turned on. See documentation |
| 269 | usrquota | 263 | usrquota in the quota-tools package for more details |
| 264 | (http://sourceforge.net/projects/linuxquota). | ||
| 265 | |||
| 266 | jqfmt=<quota type> These options tell filesystem details about quota | ||
| 267 | usrjquota=<file> so that quota information can be properly updated | ||
| 268 | grpjquota=<file> during journal replay. They replace the above | ||
| 269 | quota options. See documentation in the quota-tools | ||
| 270 | package for more details | ||
| 271 | (http://sourceforge.net/projects/linuxquota). | ||
| 270 | 272 | ||
| 271 | bh (*) ext4 associates buffer heads to data pages to | 273 | bh (*) ext4 associates buffer heads to data pages to |
| 272 | nobh (a) cache disk block mapping information | 274 | nobh (a) cache disk block mapping information |
diff --git a/Documentation/filesystems/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 | |||
| 7 | will have it as well. | 7 | will have it as well. |
| 8 | 8 | ||
| 9 | Related products are linware and mars_nwe, which will give Linux partial | 9 | Related products are linware and mars_nwe, which will give Linux partial |
| 10 | NetWare server functionality. Linware's home site is | 10 | NetWare server functionality. |
| 11 | klokan.sh.cvut.cz/pub/linux/linware; mars_nwe can be found on | 11 | |
| 12 | ftp.gwdg.de/pub/linux/misc/ncpfs. | 12 | mars_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 | |||
| 11 | control file, the nfsd service must be taken down. Use your user-mode | 11 | control file, the nfsd service must be taken down. Use your user-mode |
| 12 | nfs-utils to set this up; see rpc.nfsd(8) | 12 | nfs-utils to set this up; see rpc.nfsd(8) |
| 13 | 13 | ||
| 14 | (Warning: older servers will interpret "+4.1" and "-4.1" as "+4" and | ||
| 15 | "-4", respectively. Therefore, code meant to work on both new and old | ||
| 16 | kernels must turn 4.1 on or off *before* turning support for version 4 | ||
| 17 | on or off; rpc.nfsd does this correctly.) | ||
| 18 | |||
| 14 | The NFSv4 minorversion 1 (NFSv4.1) implementation in nfsd is based | 19 | The NFSv4 minorversion 1 (NFSv4.1) implementation in nfsd is based |
| 15 | on the latest NFSv4.1 Internet Draft: | 20 | on the latest NFSv4.1 Internet Draft: |
| 16 | http://tools.ietf.org/html/draft-ietf-nfsv4-minorversion1-29 | 21 | http://tools.ietf.org/html/draft-ietf-nfsv4-minorversion1-29 |
| @@ -25,6 +30,49 @@ are still under development out of tree. | |||
| 25 | See http://wiki.linux-nfs.org/wiki/index.php/PNFS_prototype_design | 30 | See http://wiki.linux-nfs.org/wiki/index.php/PNFS_prototype_design |
| 26 | for more information. | 31 | for more information. |
| 27 | 32 | ||
| 33 | The current implementation is intended for developers only: while it | ||
| 34 | does support ordinary file operations on clients we have tested against | ||
| 35 | (including the linux client), it is incomplete in ways which may limit | ||
| 36 | features unexpectedly, cause known bugs in rare cases, or cause | ||
| 37 | interoperability problems with future clients. Known issues: | ||
| 38 | |||
| 39 | - gss support is questionable: currently mounts with kerberos | ||
| 40 | from a linux client are possible, but we aren't really | ||
| 41 | conformant with the spec (for example, we don't use kerberos | ||
| 42 | on the backchannel correctly). | ||
| 43 | - no trunking support: no clients currently take advantage of | ||
| 44 | trunking, but this is a mandatory failure, and its use is | ||
| 45 | recommended to clients in a number of places. (E.g. to ensure | ||
| 46 | timely renewal in case an existing connection's retry timeouts | ||
| 47 | have gotten too long; see section 8.3 of the draft.) | ||
| 48 | Therefore, lack of this feature may cause future clients to | ||
| 49 | fail. | ||
| 50 | - Incomplete backchannel support: incomplete backchannel gss | ||
| 51 | support and no support for BACKCHANNEL_CTL mean that | ||
| 52 | callbacks (hence delegations and layouts) may not be | ||
| 53 | available and clients confused by the incomplete | ||
| 54 | implementation may fail. | ||
| 55 | - Server reboot recovery is unsupported; if the server reboots, | ||
| 56 | clients may fail. | ||
| 57 | - We do not support SSV, which provides security for shared | ||
| 58 | client-server state (thus preventing unauthorized tampering | ||
| 59 | with locks and opens, for example). It is mandatory for | ||
| 60 | servers to support this, though no clients use it yet. | ||
| 61 | - Mandatory operations which we do not support, such as | ||
| 62 | DESTROY_CLIENTID, FREE_STATEID, SECINFO_NO_NAME, and | ||
| 63 | TEST_STATEID, are not currently used by clients, but will be | ||
| 64 | (and the spec recommends their uses in common cases), and | ||
| 65 | clients should not be expected to know how to recover from the | ||
| 66 | case where they are not supported. This will eventually cause | ||
| 67 | interoperability failures. | ||
| 68 | |||
| 69 | In addition, some limitations are inherited from the current NFSv4 | ||
| 70 | implementation: | ||
| 71 | |||
| 72 | - Incomplete delegation enforcement: if a file is renamed or | ||
| 73 | unlinked, a client holding a delegation may continue to | ||
| 74 | indefinitely allow opens of the file under the old name. | ||
| 75 | |||
| 28 | The table below, taken from the NFSv4.1 document, lists | 76 | The table below, taken from the NFSv4.1 document, lists |
| 29 | the operations that are mandatory to implement (REQ), optional | 77 | the operations that are mandatory to implement (REQ), optional |
| 30 | (OPT), and NFSv4.0 operations that are required not to implement (MNI) | 78 | (OPT), and NFSv4.0 operations that are required not to implement (MNI) |
| @@ -142,6 +190,12 @@ NS*| CB_WANTS_CANCELLED | OPT | FDELG, | Section 20.10 | | |||
| 142 | 190 | ||
| 143 | Implementation notes: | 191 | Implementation notes: |
| 144 | 192 | ||
| 193 | DELEGPURGE: | ||
| 194 | * mandatory only for servers that support CLAIM_DELEGATE_PREV and/or | ||
| 195 | CLAIM_DELEG_PREV_FH (which allows clients to keep delegations that | ||
| 196 | persist across client reboots). Thus we need not implement this for | ||
| 197 | now. | ||
| 198 | |||
| 145 | EXCHANGE_ID: | 199 | EXCHANGE_ID: |
| 146 | * only SP4_NONE state protection supported | 200 | * only SP4_NONE state protection supported |
| 147 | * implementation ids are ignored | 201 | * implementation ids are ignored |
diff --git a/Documentation/filesystems/nfsroot.txt b/Documentation/filesystems/nfsroot.txt index 68baddf3c3e0..3ba0b945aaf8 100644 --- a/Documentation/filesystems/nfsroot.txt +++ b/Documentation/filesystems/nfsroot.txt | |||
| @@ -105,7 +105,7 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> | |||
| 105 | the client address and this parameter is NOT empty only | 105 | the client address and this parameter is NOT empty only |
| 106 | replies from the specified server are accepted. | 106 | replies from the specified server are accepted. |
| 107 | 107 | ||
| 108 | Only required for for NFS root. That is autoconfiguration | 108 | Only required for NFS root. That is autoconfiguration |
| 109 | will not be triggered if it is missing and NFS root is not | 109 | will not be triggered if it is missing and NFS root is not |
| 110 | in operation. | 110 | in operation. |
| 111 | 111 | ||
diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 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 | ||
| 180 | This shows you nearly the same information you would get if you viewed it with | 181 | This shows you nearly the same information you would get if you viewed it with |
| 181 | the ps command. In fact, ps uses the proc file system to obtain its | 182 | the 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 | ||
| 234 | Table 1-3: Contents of the statm files (as of 2.6.8-rc3) | 236 | Table 1-3: Contents of the statm files (as of 2.6.8-rc3) |
| @@ -307,7 +309,7 @@ address perms offset dev inode pathname | |||
| 307 | 08049000-0804a000 rw-p 00001000 03:00 8312 /opt/test | 309 | 08049000-0804a000 rw-p 00001000 03:00 8312 /opt/test |
| 308 | 0804a000-0806b000 rw-p 00000000 00:00 0 [heap] | 310 | 0804a000-0806b000 rw-p 00000000 00:00 0 [heap] |
| 309 | a7cb1000-a7cb2000 ---p 00000000 00:00 0 | 311 | a7cb1000-a7cb2000 ---p 00000000 00:00 0 |
| 310 | a7cb2000-a7eb2000 rw-p 00000000 00:00 0 | 312 | a7cb2000-a7eb2000 rw-p 00000000 00:00 0 [threadstack:001ff4b4] |
| 311 | a7eb2000-a7eb3000 ---p 00000000 00:00 0 | 313 | a7eb2000-a7eb3000 ---p 00000000 00:00 0 |
| 312 | a7eb3000-a7ed5000 rw-p 00000000 00:00 0 | 314 | a7eb3000-a7ed5000 rw-p 00000000 00:00 0 |
| 313 | a7ed5000-a8008000 r-xp 00000000 03:00 4222 /lib/libc.so.6 | 315 | a7ed5000-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. | |||
| 375 | This file is only present if the CONFIG_MMU kernel configuration option is | 378 | This file is only present if the CONFIG_MMU kernel configuration option is |
| 376 | enabled. | 379 | enabled. |
| 377 | 380 | ||
| 381 | The /proc/PID/clear_refs is used to reset the PG_Referenced and ACCESSED/YOUNG | ||
| 382 | bits on both physical and virtual pages associated with a process. | ||
| 383 | To clear the bits for all the pages associated with the process | ||
| 384 | > echo 1 > /proc/PID/clear_refs | ||
| 385 | |||
| 386 | To clear the bits for the anonymous pages associated with the process | ||
| 387 | > echo 2 > /proc/PID/clear_refs | ||
| 388 | |||
| 389 | To clear the bits for the file mapped pages associated with the process | ||
| 390 | > echo 3 > /proc/PID/clear_refs | ||
| 391 | Any other value written to /proc/PID/clear_refs will have no effect. | ||
| 392 | |||
| 393 | |||
| 378 | 1.2 Kernel data | 394 | 1.2 Kernel data |
| 379 | --------------- | 395 | --------------- |
| 380 | 396 | ||
| @@ -1032,9 +1048,9 @@ Various pieces of information about kernel activity are available in the | |||
| 1032 | since the system first booted. For a quick look, simply cat the file: | 1048 | since 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 | ||
| 1060 | The "intr" line gives counts of interrupts serviced since boot time, for each | 1077 | The "intr" line gives counts of interrupts serviced since boot time, for each |
| 1061 | of the possible system interrupts. The first column is the total of all | 1078 | of 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 | |||
| 4 | Contents: | 4 | Contents: |
| 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 | ||
| 125 | 2d) A unbindable mount is a unbindable private mount | 124 | 2d) 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 | ||
| 140 | 3) smount command | 138 | 3) 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 | ||
| 285 | 4) Use cases | 149 | 4) 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 | ||
| 48 | Configure the kernel with: | 48 | Configure the kernel with: |
| 49 | 49 | ||
| 50 | CONFIG_DEBUGFS=y | 50 | CONFIG_DEBUG_FS=y |
| 51 | CONFIG_GCOV_KERNEL=y | 51 | CONFIG_GCOV_KERNEL=y |
| 52 | 52 | ||
| 53 | and to get coverage data for the entire kernel: | 53 | and to get coverage data for the entire kernel: |
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 | |||
| 527 | GPIO controllers have paths like /sys/class/gpio/chipchip42/ (for the | 534 | GPIO controllers have paths like /sys/class/gpio/chipchip42/ (for the |
| 528 | controller implementing GPIOs starting at #42) and have the following | 535 | controller implementing GPIOs starting at #42) and have the following |
| 529 | read-only attributes: | 536 | read-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 | |||
| 558 | After a kernel driver requests a GPIO, it may only be made available in | 570 | After a kernel driver requests a GPIO, it may only be made available in |
| 559 | the sysfs interface by gpio_export(). The driver can control whether the | 571 | the sysfs interface by gpio_export(). The driver can control whether the |
| 560 | signal direction may change. This helps drivers prevent userspace code | 572 | signal direction may change. This helps drivers prevent userspace code |
| @@ -563,3 +575,8 @@ from accidentally clobbering important system state. | |||
| 563 | This explicit exporting can help with debugging (by making some kinds | 575 | This explicit exporting can help with debugging (by making some kinds |
| 564 | of experiments easier), or can provide an always-there interface that's | 576 | of experiments easier), or can provide an always-there interface that's |
| 565 | suitable for documenting as part of a board support package. | 577 | suitable for documenting as part of a board support package. |
| 578 | |||
| 579 | After the GPIO has been exported, gpio_export_link() allows creating | ||
| 580 | symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can | ||
| 581 | use this to provide the interface under their own device in sysfs with | ||
| 582 | a 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 @@ | |||
| 1 | Kernel driver power_meter | ||
| 2 | ========================= | ||
| 3 | |||
| 4 | This driver talks to ACPI 4.0 power meters. | ||
| 5 | |||
| 6 | Supported systems: | ||
| 7 | * Any recent system with ACPI 4.0. | ||
| 8 | Prefix: 'power_meter' | ||
| 9 | Datasheet: http://acpi.info/, section 10.4. | ||
| 10 | |||
| 11 | Author: Darrick J. Wong | ||
| 12 | |||
| 13 | Description | ||
| 14 | ----------- | ||
| 15 | |||
| 16 | This driver implements sensor reading support for the power meters exposed in | ||
| 17 | the ACPI 4.0 spec (Chapter 10.4). These devices have a simple set of | ||
| 18 | features--a power meter that returns average power use over a configurable | ||
| 19 | interval, an optional capping mechanism, and a couple of trip points. The | ||
| 20 | sysfs interface conforms with the specification outlined in the "Power" section | ||
| 21 | of Documentation/hwmon/sysfs-interface. | ||
| 22 | |||
| 23 | Special Features | ||
| 24 | ---------------- | ||
| 25 | |||
| 26 | The power[1-*]_is_battery knob indicates if the power supply is a battery. | ||
| 27 | Both power[1-*]_average_{min,max} must be set before the trip points will work. | ||
| 28 | When both of them are set, an ACPI event will be broadcast on the ACPI netlink | ||
| 29 | socket and a poll notification will be sent to the appropriate | ||
| 30 | power[1-*]_average sysfs file. | ||
| 31 | |||
| 32 | The power[1-*]_{model_number, serial_number, oem_info} fields display arbitrary | ||
| 33 | strings that ACPI provides with the meter. The measures/ directory contains | ||
| 34 | symlinks to the devices that this meter measures. | ||
| 35 | |||
| 36 | Some computers have the ability to enforce a power cap in hardware. If this is | ||
| 37 | the case, the power[1-*]_cap and related sysfs files will appear. When the | ||
| 38 | average power consumption exceeds the cap, an ACPI event will be broadcast on | ||
| 39 | the netlink event socket and a poll notification will be sent to the | ||
| 40 | appropriate power[1-*]_alarm file to indicate that capping has begun, and the | ||
| 41 | hardware has taken action to reduce power consumption. Most likely this will | ||
| 42 | result in reduced performance. | ||
| 43 | |||
| 44 | There are a few other ACPI notifications that can be sent by the firmware. In | ||
| 45 | all cases the ACPI event will be broadcast on the ACPI netlink event socket as | ||
| 46 | well as sent as a poll notification to a sysfs file. The events are as | ||
| 47 | follows: | ||
| 48 | |||
| 49 | power[1-*]_cap will be notified if the firmware changes the power cap. | ||
| 50 | power[1-*]_interval will be notified if the firmware changes the averaging | ||
| 51 | interval. | ||
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 | |||
| 4 | Supported chips: | 4 | Supported 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 @@ | |||
| 1 | Kernel driver fscher | ||
| 2 | ==================== | ||
| 3 | |||
| 4 | Supported chips: | ||
| 5 | * Fujitsu-Siemens Hermes chip | ||
| 6 | Prefix: 'fscher' | ||
| 7 | Addresses scanned: I2C 0x73 | ||
| 8 | |||
| 9 | Authors: | ||
| 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 | |||
| 15 | Description | ||
| 16 | ----------- | ||
| 17 | |||
| 18 | This driver implements support for the Fujitsu-Siemens Hermes chip. It is | ||
| 19 | described in the 'Register Set Specification BMC Hermes based Systemboard' | ||
| 20 | from Fujitsu-Siemens. | ||
| 21 | |||
| 22 | The Hermes chip implements a hardware-based system management, e.g. for | ||
| 23 | controlling fan speed and core voltage. There is also a watchdog counter on | ||
| 24 | the chip which can trigger an alarm and even shut the system down. | ||
| 25 | |||
| 26 | The chip provides three temperature values (CPU, motherboard and | ||
| 27 | auxiliary), three voltage values (+12V, +5V and battery) and three fans | ||
| 28 | (power supply, CPU and auxiliary). | ||
| 29 | |||
| 30 | Temperatures are measured in degrees Celsius. The resolution is 1 degree. | ||
| 31 | |||
| 32 | Fan rotation speeds are reported in RPM (rotations per minute). The value | ||
| 33 | can be divided by a programmable divider (1, 2 or 4) which is stored on | ||
| 34 | the chip. | ||
| 35 | |||
| 36 | Voltage sensors (also known as "in" sensors) report their values in volts. | ||
| 37 | |||
| 38 | All values are reported as final values from the driver. There is no need | ||
| 39 | for further calculations. | ||
| 40 | |||
| 41 | |||
| 42 | Detailed description | ||
| 43 | -------------------- | ||
| 44 | |||
| 45 | Below you'll find a single line description of all the bit values. With | ||
| 46 | this information, you're able to decode e. g. alarms, wdog, etc. To make | ||
| 47 | use of the watchdog, you'll need to set the watchdog time and enable the | ||
| 48 | watchdog. After that it is necessary to restart the watchdog time within | ||
| 49 | the 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 | |||
| 149 | Limitations | ||
| 150 | ----------- | ||
| 151 | |||
| 152 | * Measuring fan speed | ||
| 153 | It seems that the chip counts "ripples" (typical fans produce 2 ripples per | ||
| 154 | rotation while VERAX fans produce 18) in a 9-bit register. This register is | ||
| 155 | read out every second, then the ripple prescaler (2, 4 or 8) is applied and | ||
| 156 | the result is stored in the 8 bit output register. Due to the limitation of | ||
| 157 | the counting register to 9 bits, it is impossible to measure a VERAX fan | ||
| 158 | properly (even with a prescaler of 8). At its maximum speed of 3500 RPM the | ||
| 159 | fan produces 1080 ripples per second which causes the counting register to | ||
| 160 | overflow twice, leading to only 186 RPM. | ||
| 161 | |||
| 162 | * Measuring input voltages | ||
| 163 | in2 ("battery") reports the voltage of the onboard lithium battery and not | ||
| 164 | +3.3V from the power supply. | ||
| 165 | |||
| 166 | * Undocumented features | ||
| 167 | Fujitsu-Siemens Computers has not documented all features of the chip so | ||
| 168 | far. Their software, System Guard, shows that there are a still some | ||
| 169 | features 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 | |||
| 22 | char unload_heads_path[64]; | ||
| 23 | |||
| 24 | int set_unload_heads_path(char *device) | ||
| 25 | { | ||
| 26 | char devname[64]; | ||
| 27 | |||
| 28 | if (strlen(device) <= 5 || strncmp(device, "/dev/", 5) != 0) | ||
| 29 | return -EINVAL; | ||
| 30 | strncpy(devname, device + 5, sizeof(devname)); | ||
| 31 | |||
| 32 | snprintf(unload_heads_path, sizeof(unload_heads_path), | ||
| 33 | "/sys/block/%s/device/unload_heads", devname); | ||
| 34 | return 0; | ||
| 35 | } | ||
| 36 | int valid_disk(void) | ||
| 37 | { | ||
| 38 | int fd = open(unload_heads_path, O_RDONLY); | ||
| 39 | if (fd < 0) { | ||
| 40 | perror(unload_heads_path); | ||
| 41 | return 0; | ||
| 42 | } | ||
| 43 | |||
| 44 | close(fd); | ||
| 45 | return 1; | ||
| 46 | } | ||
| 19 | 47 | ||
| 20 | void write_int(char *path, int i) | 48 | void write_int(char *path, int i) |
| 21 | { | 49 | { |
| @@ -40,7 +68,7 @@ void set_led(int on) | |||
| 40 | 68 | ||
| 41 | void protect(int seconds) | 69 | void protect(int seconds) |
| 42 | { | 70 | { |
| 43 | write_int("/sys/block/sda/device/unload_heads", seconds*1000); | 71 | write_int(unload_heads_path, seconds*1000); |
| 44 | } | 72 | } |
| 45 | 73 | ||
| 46 | int on_ac(void) | 74 | int on_ac(void) |
| @@ -57,45 +85,62 @@ void ignore_me(void) | |||
| 57 | { | 85 | { |
| 58 | protect(0); | 86 | protect(0); |
| 59 | set_led(0); | 87 | set_led(0); |
| 60 | |||
| 61 | } | 88 | } |
| 62 | 89 | ||
| 63 | int main(int argc, char* argv[]) | 90 | int main(int argc, char **argv) |
| 64 | { | 91 | { |
| 65 | int fd, ret; | 92 | int fd, ret; |
| 93 | struct sched_param param; | ||
| 94 | |||
| 95 | if (argc == 1) | ||
| 96 | ret = set_unload_heads_path("/dev/sda"); | ||
| 97 | else if (argc == 2) | ||
| 98 | ret = set_unload_heads_path(argv[1]); | ||
| 99 | else | ||
| 100 | ret = -EINVAL; | ||
| 101 | |||
| 102 | if (ret || !valid_disk()) { | ||
| 103 | fprintf(stderr, "usage: %s <device> (default: /dev/sda)\n", | ||
| 104 | argv[0]); | ||
| 105 | exit(1); | ||
| 106 | } | ||
| 107 | |||
| 108 | fd = open("/dev/freefall", O_RDONLY); | ||
| 109 | if (fd < 0) { | ||
| 110 | perror("/dev/freefall"); | ||
| 111 | return EXIT_FAILURE; | ||
| 112 | } | ||
| 66 | 113 | ||
| 67 | fd = open("/dev/freefall", O_RDONLY); | 114 | daemon(0, 0); |
| 68 | if (fd < 0) { | 115 | param.sched_priority = sched_get_priority_max(SCHED_FIFO); |
| 69 | perror("open"); | 116 | sched_setscheduler(0, SCHED_FIFO, ¶m); |
| 70 | return EXIT_FAILURE; | 117 | mlockall(MCL_CURRENT|MCL_FUTURE); |
| 71 | } | ||
| 72 | 118 | ||
| 73 | signal(SIGALRM, ignore_me); | 119 | signal(SIGALRM, ignore_me); |
| 74 | 120 | ||
| 75 | for (;;) { | 121 | for (;;) { |
| 76 | unsigned char count; | 122 | unsigned char count; |
| 77 | 123 | ||
| 78 | ret = read(fd, &count, sizeof(count)); | 124 | ret = read(fd, &count, sizeof(count)); |
| 79 | alarm(0); | 125 | alarm(0); |
| 80 | if ((ret == -1) && (errno == EINTR)) { | 126 | if ((ret == -1) && (errno == EINTR)) { |
| 81 | /* Alarm expired, time to unpark the heads */ | 127 | /* Alarm expired, time to unpark the heads */ |
| 82 | continue; | 128 | continue; |
| 83 | } | 129 | } |
| 84 | 130 | ||
| 85 | if (ret != sizeof(count)) { | 131 | if (ret != sizeof(count)) { |
| 86 | perror("read"); | 132 | perror("read"); |
| 87 | break; | 133 | break; |
| 88 | } | 134 | } |
| 89 | 135 | ||
| 90 | protect(21); | 136 | protect(21); |
| 91 | set_led(1); | 137 | set_led(1); |
| 92 | if (1 || on_ac() || lid_open()) { | 138 | if (1 || on_ac() || lid_open()) |
| 93 | alarm(2); | 139 | alarm(2); |
| 94 | } else { | 140 | else |
| 95 | alarm(20); | 141 | alarm(20); |
| 96 | } | 142 | } |
| 97 | } | 143 | |
| 98 | 144 | close(fd); | |
| 99 | close(fd); | 145 | return EXIT_SUCCESS; |
| 100 | return EXIT_SUCCESS; | ||
| 101 | } | 146 | } |
diff --git a/Documentation/hwmon/pc87427 b/Documentation/hwmon/pc87427 index d1ebbe510f35..db5cc1227a83 100644 --- a/Documentation/hwmon/pc87427 +++ b/Documentation/hwmon/pc87427 | |||
| @@ -34,5 +34,5 @@ Fan rotation speeds are reported as 14-bit values from a gated clock | |||
| 34 | signal. Speeds down to 83 RPM can be measured. | 34 | signal. Speeds down to 83 RPM can be measured. |
| 35 | 35 | ||
| 36 | An alarm is triggered if the rotation speed drops below a programmable | 36 | An alarm is triggered if the rotation speed drops below a programmable |
| 37 | limit. Another alarm is triggered if the speed is too low to to be measured | 37 | limit. Another alarm is triggered if the speed is too low to be measured |
| 38 | (including stalled or missing fan). | 38 | (including stalled or missing fan). |
diff --git a/Documentation/hwmon/pcf8591 b/Documentation/hwmon/pcf8591 index 5628fcf4207f..e76a7892f68e 100644 --- a/Documentation/hwmon/pcf8591 +++ b/Documentation/hwmon/pcf8591 | |||
| @@ -2,11 +2,11 @@ Kernel driver pcf8591 | |||
| 2 | ===================== | 2 | ===================== |
| 3 | 3 | ||
| 4 | Supported chips: | 4 | Supported chips: |
| 5 | * Philips PCF8591 | 5 | * Philips/NXP PCF8591 |
| 6 | Prefix: 'pcf8591' | 6 | Prefix: 'pcf8591' |
| 7 | Addresses scanned: I2C 0x48 - 0x4f | 7 | Addresses scanned: I2C 0x48 - 0x4f |
| 8 | Datasheet: Publicly available at the Philips Semiconductor website | 8 | Datasheet: Publicly available at the NXP website |
| 9 | http://www.semiconductors.philips.com/pip/PCF8591P.html | 9 | http://www.nxp.com/pip/PCF8591_6.html |
| 10 | 10 | ||
| 11 | Authors: | 11 | Authors: |
| 12 | Aurelien Jarno <aurelien@aurel32.net> | 12 | Aurelien Jarno <aurelien@aurel32.net> |
| @@ -16,9 +16,10 @@ Authors: | |||
| 16 | 16 | ||
| 17 | Description | 17 | Description |
| 18 | ----------- | 18 | ----------- |
| 19 | |||
| 19 | The PCF8591 is an 8-bit A/D and D/A converter (4 analog inputs and one | 20 | The PCF8591 is an 8-bit A/D and D/A converter (4 analog inputs and one |
| 20 | analog output) for the I2C bus produced by Philips Semiconductors. It | 21 | analog output) for the I2C bus produced by Philips Semiconductors (now NXP). |
| 21 | is designed to provide a byte I2C interface to up to 4 separate devices. | 22 | It is designed to provide a byte I2C interface to up to 4 separate devices. |
| 22 | 23 | ||
| 23 | The PCF8591 has 4 analog inputs programmable as single-ended or | 24 | The PCF8591 has 4 analog inputs programmable as single-ended or |
| 24 | differential inputs : | 25 | differential inputs : |
| @@ -58,8 +59,8 @@ Accessing PCF8591 via /sys interface | |||
| 58 | ------------------------------------- | 59 | ------------------------------------- |
| 59 | 60 | ||
| 60 | ! Be careful ! | 61 | ! Be careful ! |
| 61 | The PCF8591 is plainly impossible to detect ! Stupid chip. | 62 | The PCF8591 is plainly impossible to detect! Stupid chip. |
| 62 | So every chip with address in the interval [48..4f] is | 63 | So every chip with address in the interval [0x48..0x4f] is |
| 63 | detected as PCF8591. If you have other chips in this address | 64 | detected as PCF8591. If you have other chips in this address |
| 64 | range, the workaround is to load this module after the one | 65 | range, the workaround is to load this module after the one |
| 65 | for your others chips. | 66 | for your others chips. |
| @@ -67,19 +68,20 @@ for your others chips. | |||
| 67 | On detection (i.e. insmod, modprobe et al.), directories are being | 68 | On detection (i.e. insmod, modprobe et al.), directories are being |
| 68 | created for each detected PCF8591: | 69 | created for each detected PCF8591: |
| 69 | 70 | ||
| 70 | /sys/bus/devices/<0>-<1>/ | 71 | /sys/bus/i2c/devices/<0>-<1>/ |
| 71 | where <0> is the bus the chip was detected on (e. g. i2c-0) | 72 | where <0> is the bus the chip was detected on (e. g. i2c-0) |
| 72 | and <1> the chip address ([48..4f]) | 73 | and <1> the chip address ([48..4f]) |
| 73 | 74 | ||
| 74 | Inside these directories, there are such files: | 75 | Inside these directories, there are such files: |
| 75 | in0, in1, in2, in3, out0_enable, out0_output, name | 76 | in0_input, in1_input, in2_input, in3_input, out0_enable, out0_output, name |
| 76 | 77 | ||
| 77 | Name contains chip name. | 78 | Name contains chip name. |
| 78 | 79 | ||
| 79 | The in0, in1, in2 and in3 files are RO. Reading gives the value of the | 80 | The in0_input, in1_input, in2_input and in3_input files are RO. Reading gives |
| 80 | corresponding channel. Depending on the current analog inputs configuration, | 81 | the value of the corresponding channel. Depending on the current analog inputs |
| 81 | files in2 and/or in3 do not exist. Values range are from 0 to 255 for single | 82 | configuration, files in2_input and in3_input may not exist. Values range |
| 82 | ended inputs and -128 to +127 for differential inputs (8-bit ADC). | 83 | from 0 to 255 for single ended inputs and -128 to +127 for differential inputs |
| 84 | (8-bit ADC). | ||
| 83 | 85 | ||
| 84 | The out0_enable file is RW. Reading gives "1" for analog output enabled and | 86 | The out0_enable file is RW. Reading gives "1" for analog output enabled and |
| 85 | "0" for analog output disabled. Writing accepts "0" and "1" accordingly. | 87 | "0" for analog output disabled. Writing accepts "0" and "1" accordingly. |
diff --git a/Documentation/hwmon/tmp421 b/Documentation/hwmon/tmp421 new file mode 100644 index 000000000000..0cf07f824741 --- /dev/null +++ b/Documentation/hwmon/tmp421 | |||
| @@ -0,0 +1,36 @@ | |||
| 1 | Kernel driver tmp421 | ||
| 2 | ==================== | ||
| 3 | |||
| 4 | Supported chips: | ||
| 5 | * Texas Instruments TMP421 | ||
| 6 | Prefix: 'tmp421' | ||
| 7 | Addresses scanned: I2C 0x2a, 0x4c, 0x4d, 0x4e and 0x4f | ||
| 8 | Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp421.html | ||
| 9 | * Texas Instruments TMP422 | ||
| 10 | Prefix: 'tmp422' | ||
| 11 | Addresses scanned: I2C 0x2a, 0x4c, 0x4d, 0x4e and 0x4f | ||
| 12 | Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp421.html | ||
| 13 | * Texas Instruments TMP423 | ||
| 14 | Prefix: 'tmp423' | ||
| 15 | Addresses scanned: I2C 0x2a, 0x4c, 0x4d, 0x4e and 0x4f | ||
| 16 | Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp421.html | ||
| 17 | |||
| 18 | Authors: | ||
| 19 | Andre Prendel <andre.prendel@gmx.de> | ||
| 20 | |||
| 21 | Description | ||
| 22 | ----------- | ||
| 23 | |||
| 24 | This driver implements support for Texas Instruments TMP421, TMP422 | ||
| 25 | and TMP423 temperature sensor chips. These chips implement one local | ||
| 26 | and up to one (TMP421), up to two (TMP422) or up to three (TMP423) | ||
| 27 | remote sensors. Temperature is measured in degrees Celsius. The chips | ||
| 28 | are wired over I2C/SMBus and specified over a temperature range of -40 | ||
| 29 | to +125 degrees Celsius. Resolution for both the local and remote | ||
| 30 | channels is 0.0625 degree C. | ||
| 31 | |||
| 32 | The chips support only temperature measurement. The driver exports | ||
| 33 | the temperature values via the following sysfs files: | ||
| 34 | |||
| 35 | temp[1-4]_input | ||
| 36 | temp[2-4]_fault | ||
diff --git a/Documentation/hwmon/wm831x b/Documentation/hwmon/wm831x new file mode 100644 index 000000000000..24f47d8f6a42 --- /dev/null +++ b/Documentation/hwmon/wm831x | |||
| @@ -0,0 +1,37 @@ | |||
| 1 | Kernel driver wm831x-hwmon | ||
| 2 | ========================== | ||
| 3 | |||
| 4 | Supported chips: | ||
| 5 | * Wolfson Microelectronics WM831x PMICs | ||
| 6 | Prefix: 'wm831x' | ||
| 7 | Datasheet: | ||
| 8 | http://www.wolfsonmicro.com/products/WM8310 | ||
| 9 | http://www.wolfsonmicro.com/products/WM8311 | ||
| 10 | http://www.wolfsonmicro.com/products/WM8312 | ||
| 11 | |||
| 12 | Authors: Mark Brown <broonie@opensource.wolfsonmicro.com> | ||
| 13 | |||
| 14 | Description | ||
| 15 | ----------- | ||
| 16 | |||
| 17 | The WM831x series of PMICs include an AUXADC which can be used to | ||
| 18 | monitor a range of system operating parameters, including the voltages | ||
| 19 | of the major supplies within the system. Currently the driver provides | ||
| 20 | reporting of all the input values but does not provide any alarms. | ||
| 21 | |||
| 22 | Voltage Monitoring | ||
| 23 | ------------------ | ||
| 24 | |||
| 25 | Voltages are sampled by a 12 bit ADC. Voltages in milivolts are 1.465 | ||
| 26 | times the ADC value. | ||
| 27 | |||
| 28 | Temperature Monitoring | ||
| 29 | ---------------------- | ||
| 30 | |||
| 31 | Temperatures are sampled by a 12 bit ADC. Chip and battery temperatures | ||
| 32 | are available. The chip temperature is calculated as: | ||
| 33 | |||
| 34 | Degrees celsius = (512.18 - data) / 1.0983 | ||
| 35 | |||
| 36 | while the battery temperature calculation will depend on the NTC | ||
| 37 | thermistor component. | ||
diff --git a/Documentation/hwmon/wm8350 b/Documentation/hwmon/wm8350 new file mode 100644 index 000000000000..98f923bd2e92 --- /dev/null +++ b/Documentation/hwmon/wm8350 | |||
| @@ -0,0 +1,26 @@ | |||
| 1 | Kernel driver wm8350-hwmon | ||
| 2 | ========================== | ||
| 3 | |||
| 4 | Supported chips: | ||
| 5 | * Wolfson Microelectronics WM835x PMICs | ||
| 6 | Prefix: 'wm8350' | ||
| 7 | Datasheet: | ||
| 8 | http://www.wolfsonmicro.com/products/WM8350 | ||
| 9 | http://www.wolfsonmicro.com/products/WM8351 | ||
| 10 | http://www.wolfsonmicro.com/products/WM8352 | ||
| 11 | |||
| 12 | Authors: Mark Brown <broonie@opensource.wolfsonmicro.com> | ||
| 13 | |||
| 14 | Description | ||
| 15 | ----------- | ||
| 16 | |||
| 17 | The WM835x series of PMICs include an AUXADC which can be used to | ||
| 18 | monitor a range of system operating parameters, including the voltages | ||
| 19 | of the major supplies within the system. Currently the driver provides | ||
| 20 | simple access to these major supplies. | ||
| 21 | |||
| 22 | Voltage Monitoring | ||
| 23 | ------------------ | ||
| 24 | |||
| 25 | Voltages are sampled by a 12 bit ADC. For the internal supplies the ADC | ||
| 26 | is referenced to the system VRTC. | ||
diff --git a/Documentation/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 @@ | |||
| 1 | Kernel driver pca9539 | ||
| 2 | ===================== | ||
| 3 | |||
| 4 | NOTE: this driver is deprecated and will be dropped soon, use | ||
| 5 | drivers/gpio/pca9539.c instead. | ||
| 6 | |||
| 7 | Supported 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 | |||
| 14 | Author: Ben Gardner <bgardner@wabtec.com> | ||
| 15 | |||
| 16 | |||
| 17 | Description | ||
| 18 | ----------- | ||
| 19 | |||
| 20 | The Philips PCA9539 is a 16 bit low power I/O device. | ||
| 21 | All 16 lines can be individually configured as an input or output. | ||
| 22 | The input sense can also be inverted. | ||
| 23 | The 16 lines are split between two bytes. | ||
| 24 | |||
| 25 | |||
| 26 | Detection | ||
| 27 | --------- | ||
| 28 | |||
| 29 | The PCA9539 is difficult to detect and not commonly found in PC machines, | ||
| 30 | so you have to pass the I2C bus and address of the installed PCA9539 | ||
| 31 | devices explicitly to the driver at load time via the force=... parameter. | ||
| 32 | |||
| 33 | |||
| 34 | Sysfs entries | ||
| 35 | ------------- | ||
| 36 | |||
| 37 | Each is a byte that maps to the 8 I/O bits. | ||
| 38 | A '0' suffix is for bits 0-7, while '1' is for bits 8-15. | ||
| 39 | |||
| 40 | input[01] - read the current value | ||
| 41 | output[01] - sets the output value | ||
| 42 | direction[01] - direction of each bit: 1=input, 0=output | ||
| 43 | invert[01] - toggle the input bit sense | ||
| 44 | |||
| 45 | input reads the actual state of the line and is always available. | ||
| 46 | The direction defaults to input for all channels. | ||
| 47 | |||
| 48 | |||
| 49 | General Remarks | ||
| 50 | --------------- | ||
| 51 | |||
| 52 | Note that each output, direction, and invert entry controls 8 lines. | ||
| 53 | You should use the read, modify, write sequence. | ||
| 54 | For 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 @@ | |||
| 1 | Kernel driver pcf8574 | ||
| 2 | ===================== | ||
| 3 | |||
| 4 | Supported 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 | |||
| 17 | Authors: | ||
| 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 | |||
| 25 | Description | ||
| 26 | ----------- | ||
| 27 | The PCF8574(A) is an 8-bit I/O expander for the I2C bus produced by Philips | ||
| 28 | Semiconductors. It is designed to provide a byte I2C interface to up to 16 | ||
| 29 | separate devices (8 x PCF8574 and 8 x PCF8574A). | ||
| 30 | |||
| 31 | This device consists of a quasi-bidirectional port. Each of the eight I/Os | ||
| 32 | can be independently used as an input or output. To setup an I/O as an | ||
| 33 | input, you have to write a 1 to the corresponding output. | ||
| 34 | |||
| 35 | For more informations see the datasheet. | ||
| 36 | |||
| 37 | |||
| 38 | Accessing PCF8574(A) via /sys interface | ||
| 39 | ------------------------------------- | ||
| 40 | |||
| 41 | The PCF8574(A) is plainly impossible to detect ! Stupid chip. | ||
| 42 | So, you have to pass the I2C bus and address of the installed PCF857A | ||
| 43 | and PCF8574A devices explicitly to the driver at load time via the | ||
| 44 | force=... parameter. | ||
| 45 | |||
| 46 | On detection (i.e. insmod, modprobe et al.), directories are being | ||
| 47 | created for each detected PCF8574(A): | ||
| 48 | |||
| 49 | /sys/bus/i2c/devices/<0>-<1>/ | ||
| 50 | where <0> is the bus the chip was detected on (e. g. i2c-0) | ||
| 51 | and <1> the chip address ([20..27] or [38..3f]): | ||
| 52 | |||
| 53 | (example: /sys/bus/i2c/devices/1-0020/) | ||
| 54 | |||
| 55 | Inside these directories, there are two files each: | ||
| 56 | read and write (and one file with chip name). | ||
| 57 | |||
| 58 | The read file is read-only. Reading gives you the current I/O input | ||
| 59 | if the corresponding output is set as 1, otherwise the current output | ||
| 60 | value, that is to say 0. | ||
| 61 | |||
| 62 | The write file is read/write. Writing a value outputs it on the I/O | ||
| 63 | port. Reading returns the last written value. As it is not possible | ||
| 64 | to read this value from the chip, you need to write at least once to | ||
| 65 | this 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 @@ | |||
| 1 | About the PCF8575 chip and the pcf8575 kernel driver | ||
| 2 | ==================================================== | ||
| 3 | |||
| 4 | The 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 | |||
| 13 | Some vendors sell small PCB's with the PCF8575 mounted on it. You can connect | ||
| 14 | such a board to a Linux host via e.g. an USB to I2C interface. Examples of | ||
| 15 | PCB 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 | |||
| 24 | Description | ||
| 25 | ----------- | ||
| 26 | The PCF8575 chip is a 16-bit I/O expander for the I2C bus. Up to eight of | ||
| 27 | these chips can be connected to the same I2C bus. You can find this | ||
| 28 | chip on some custom designed hardware, but you won't find it on PC | ||
| 29 | motherboards. | ||
| 30 | |||
| 31 | The PCF8575 chip consists of a 16-bit quasi-bidirectional port and an I2C-bus | ||
| 32 | interface. Each of the sixteen I/O's can be independently used as an input or | ||
| 33 | an output. To set up an I/O pin as an input, you have to write a 1 to the | ||
| 34 | corresponding output. | ||
| 35 | |||
| 36 | For more information please see the datasheet. | ||
| 37 | |||
| 38 | |||
| 39 | Detection | ||
| 40 | --------- | ||
| 41 | |||
| 42 | There is no method known to detect whether a chip on a given I2C address is | ||
| 43 | a PCF8575 or whether it is any other I2C device, so you have to pass the I2C | ||
| 44 | bus and address of the installed PCF8575 devices explicitly to the driver at | ||
| 45 | load time via the force=... parameter. | ||
| 46 | |||
| 47 | /sys interface | ||
| 48 | -------------- | ||
| 49 | |||
| 50 | For each address on which a PCF8575 chip was found or forced the following | ||
| 51 | files will be created under /sys: | ||
| 52 | * /sys/bus/i2c/devices/<bus>-<address>/read | ||
| 53 | * /sys/bus/i2c/devices/<bus>-<address>/write | ||
| 54 | where bus is the I2C bus number (0, 1, ...) and address is the four-digit | ||
| 55 | hexadecimal representation of the 7-bit I2C address of the PCF8575 | ||
| 56 | (0020 .. 0027). | ||
| 57 | |||
| 58 | The read file is read-only. Reading it will trigger an I2C read and will hence | ||
| 59 | report the current input state for the pins configured as inputs, and the | ||
| 60 | current output value for the pins configured as outputs. | ||
| 61 | |||
| 62 | The write file is read-write. Writing a value to it will configure all pins | ||
| 63 | as output for which the corresponding bit is zero. Reading the write file will | ||
| 64 | return the value last written, or -EAGAIN if no value has yet been written to | ||
| 65 | the write file. | ||
| 66 | |||
| 67 | On module initialization the configuration of the chip is not changed -- the | ||
| 68 | chip is left in the state it was already configured in through either power-up | ||
| 69 | or 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 | ||
| 25 | int sum; | 25 | int sum; |
| 26 | 26 | ||
| 27 | int map_mem(char *path, off_t offset, size_t length, int touch) | 27 | static 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 | ||
| 65 | int scan_tree(char *path, char *file, off_t offset, size_t length, int touch) | 65 | static 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 | ||
| 120 | char buf[1024]; | 120 | char buf[1024]; |
| 121 | 121 | ||
| 122 | int read_rom(char *path) | 122 | static 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 | ||
| 149 | int scan_rom(char *path, char *file) | 149 | static 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 | |||
| 65 | INSTALL_PATH specifies where to place the updated kernel and system map | 65 | INSTALL_PATH specifies where to place the updated kernel and system map |
| 66 | images. Default is /boot, but you can set it to other values. | 66 | images. Default is /boot, but you can set it to other values. |
| 67 | 67 | ||
| 68 | INSTALLKERNEL | ||
| 69 | -------------------------------------------------- | ||
| 70 | Install script called when using "make install". | ||
| 71 | The default name is "installkernel". | ||
| 72 | |||
| 73 | The 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 | |||
| 79 | The implmentation of "make install" is architecture specific | ||
| 80 | and it may differ from the above. | ||
| 81 | |||
| 82 | INSTALLKERNEL is provided to enable the possibility to | ||
| 83 | specify a custom installer when cross compiling a kernel. | ||
| 68 | 84 | ||
| 69 | MODLIB | 85 | MODLIB |
| 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 | ||
| 575 | Kbuild supports building executables on the host for use during the | 589 | Kbuild 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 | ||
| 69 | The first line, with the short description, must be on a single line. | 69 | The short description following the subject can span multiple lines |
| 70 | and ends with an @argument description, an empty line or the end of | ||
| 71 | the comment block. | ||
| 70 | 72 | ||
| 71 | The @argument descriptions must begin on the very next line following | 73 | The @argument descriptions must begin on the very next line following |
| 72 | this opening short function description line, with no intervening | 74 | this opening short function description line, with no intervening |
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 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. | |||
| 43 | 1. Downloading | 43 | 1. Downloading |
| 44 | ============== | 44 | ============== |
| 45 | 45 | ||
| 46 | kmemcheck can only be downloaded using git. If you want to write patches | 46 | As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel. |
| 47 | against the current code, you should use the kmemcheck development branch of | ||
| 48 | the tip tree. It is also possible to use the linux-next tree, which also | ||
| 49 | includes the latest version of kmemcheck. | ||
| 50 | |||
| 51 | Assuming that you've already cloned the linux-2.6.git repository, all you | ||
| 52 | have to do is add the -tip tree as a remote, like this: | ||
| 53 | |||
| 54 | $ git remote add tip git://git.kernel.org/pub/scm/linux/kernel/git/tip/linux-2.6-tip.git | ||
| 55 | |||
| 56 | To actually download the tree, fetch the remote: | ||
| 57 | |||
| 58 | $ git fetch tip | ||
| 59 | |||
| 60 | And to check out a new local branch with the kmemcheck code: | ||
| 61 | |||
| 62 | $ git checkout -b kmemcheck tip/kmemcheck | ||
| 63 | |||
| 64 | General instructions for the -tip tree can be found here: | ||
| 65 | http://people.redhat.com/mingo/tip.git/readme.txt | ||
| 66 | 47 | ||
| 67 | 48 | ||
| 68 | 2. Configuring and compiling | 49 | 2. Configuring and compiling |
diff --git a/Documentation/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 @@ | |||
| 1 | Asus Laptop Extras | ||
| 2 | |||
| 3 | Version 0.1 | ||
| 4 | August 6, 2009 | ||
| 5 | |||
| 6 | Corentin Chary <corentincj@iksaif.net> | ||
| 7 | http://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 | |||
| 17 | This driver supercedes the old asus_acpi driver. | ||
| 18 | |||
| 19 | Requirements | ||
| 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 | |||
| 25 | Status | ||
| 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 | |||
| 45 | Usage | ||
| 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 | |||
| 68 | LEDs | ||
| 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 | |||
| 77 | Backlight | ||
| 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 | |||
| 83 | Wireless 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 | |||
| 90 | Display 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 | |||
| 177 | LED 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 | |||
| 212 | Driver 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 | |||
| 230 | Unsupported 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 | |||
| 241 | Patches, 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 | ||
| 224 | The following commands have been deprecated and will cause the kernel | 224 | The following commands have been deprecated and will cause the kernel |
| 225 | to log a warning: | 225 | to 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 | |||
| 1 | LED handling under Linux | 2 | LED handling under Linux |
| 2 | ======================== | 3 | ======================== |
| 3 | 4 | ||
| @@ -5,10 +6,10 @@ If you're reading this and thinking about keyboard leds, these are | |||
| 5 | handled by the input subsystem and the led class is *not* needed. | 6 | handled by the input subsystem and the led class is *not* needed. |
| 6 | 7 | ||
| 7 | In its simplest form, the LED class just allows control of LEDs from | 8 | In its simplest form, the LED class just allows control of LEDs from |
| 8 | userspace. LEDs appear in /sys/class/leds/. The brightness file will | 9 | userspace. LEDs appear in /sys/class/leds/. The maximum brightness of the |
| 9 | set the brightness of the LED (taking a value 0-255). Most LEDs don't | 10 | LED is defined in max_brightness file. The brightness file will set the brightness |
| 10 | have hardware brightness support so will just be turned on for non-zero | 11 | of the LED (taking a value 0-max_brightness). Most LEDs don't have hardware |
| 11 | brightness settings. | 12 | brightness support so will just be turned on for non-zero brightness settings. |
| 12 | 13 | ||
| 13 | The class also introduces the optional concept of an LED trigger. A trigger | 14 | The class also introduces the optional concept of an LED trigger. A trigger |
| 14 | is a kernel based source of led events. Triggers can either be simple or | 15 | is 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 | ||
| 1052 | static 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 | |||
| 1045 | static void start_device(struct device *dev) | 1061 | static 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 | |||
| 6 | This document introduces Linux Kernel Markers and their use. It provides | ||
| 7 | examples of how to insert markers in the kernel and connect probe functions to | ||
| 8 | them and provides some examples of probe functions. | ||
| 9 | |||
| 10 | |||
| 11 | * Purpose of markers | ||
| 12 | |||
| 13 | A marker placed in code provides a hook to call a function (probe) that you can | ||
| 14 | provide at runtime. A marker can be "on" (a probe is connected to it) or "off" | ||
| 15 | (no probe is attached). When a marker is "off" it has no effect, except for | ||
| 16 | adding a tiny time penalty (checking a condition for a branch) and space | ||
| 17 | penalty (adding a few bytes for the function call at the end of the | ||
| 18 | instrumented function and adds a data structure in a separate section). When a | ||
| 19 | marker is "on", the function you provide is called each time the marker is | ||
| 20 | executed, in the execution context of the caller. When the function provided | ||
| 21 | ends its execution, it returns to the caller (continuing from the marker site). | ||
| 22 | |||
| 23 | You can put markers at important locations in the code. Markers are | ||
| 24 | lightweight hooks that can pass an arbitrary number of parameters, | ||
| 25 | described in a printk-like format string, to the attached probe function. | ||
| 26 | |||
| 27 | They can be used for tracing and performance accounting. | ||
| 28 | |||
| 29 | |||
| 30 | * Usage | ||
| 31 | |||
| 32 | In order to use the macro trace_mark, you should include linux/marker.h. | ||
| 33 | |||
| 34 | #include <linux/marker.h> | ||
| 35 | |||
| 36 | And, | ||
| 37 | |||
| 38 | trace_mark(subsystem_event, "myint %d mystring %s", someint, somestring); | ||
| 39 | Where : | ||
| 40 | - subsystem_event is an identifier unique to your event | ||
| 41 | - subsystem is the name of your subsystem. | ||
| 42 | - event is the name of the event to mark. | ||
| 43 | - "myint %d mystring %s" is the formatted string for the serializer. "myint" and | ||
| 44 | "mystring" are repectively the field names associated with the first and | ||
| 45 | second parameter. | ||
| 46 | - someint is an integer. | ||
| 47 | - somestring is a char pointer. | ||
| 48 | |||
| 49 | Connecting a function (probe) to a marker is done by providing a probe (function | ||
| 50 | to call) for the specific marker through marker_probe_register() and can be | ||
| 51 | activated by calling marker_arm(). Marker deactivation can be done by calling | ||
| 52 | marker_disarm() as many times as marker_arm() has been called. Removing a probe | ||
| 53 | is done through marker_probe_unregister(); it will disarm the probe. | ||
| 54 | |||
| 55 | marker_synchronize_unregister() must be called between probe unregistration and | ||
| 56 | the first occurrence of | ||
| 57 | - the end of module exit function, | ||
| 58 | to make sure there is no caller left using the probe; | ||
| 59 | - the free of any resource used by the probes, | ||
| 60 | to make sure the probes wont be accessing invalid data. | ||
| 61 | This, and the fact that preemption is disabled around the probe call, make sure | ||
| 62 | that probe removal and module unload are safe. See the "Probe example" section | ||
| 63 | below for a sample probe module. | ||
| 64 | |||
| 65 | The marker mechanism supports inserting multiple instances of the same marker. | ||
| 66 | Markers can be put in inline functions, inlined static functions, and | ||
| 67 | unrolled loops as well as regular functions. | ||
| 68 | |||
| 69 | The naming scheme "subsystem_event" is suggested here as a convention intended | ||
| 70 | to limit collisions. Marker names are global to the kernel: they are considered | ||
| 71 | as being the same whether they are in the core kernel image or in modules. | ||
| 72 | Conflicting format strings for markers with the same name will cause the markers | ||
| 73 | to be detected to have a different format string not to be armed and will output | ||
| 74 | a printk warning which identifies the inconsistency: | ||
| 75 | |||
| 76 | "Format mismatch for probe probe_name (format), marker (format)" | ||
| 77 | |||
| 78 | Another way to use markers is to simply define the marker without generating any | ||
| 79 | function call to actually call into the marker. This is useful in combination | ||
| 80 | with tracepoint probes in a scheme like this : | ||
| 81 | |||
| 82 | void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk); | ||
| 83 | |||
| 84 | DEFINE_MARKER_TP(marker_eventname, tracepoint_name, probe_tracepoint_name, | ||
| 85 | "arg1 %u pid %d"); | ||
| 86 | |||
| 87 | notrace void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk) | ||
| 88 | { | ||
| 89 | struct marker *marker = &GET_MARKER(kernel_irq_entry); | ||
| 90 | /* write data to trace buffers ... */ | ||
| 91 | } | ||
| 92 | |||
| 93 | * Probe / marker example | ||
| 94 | |||
| 95 | See the example provided in samples/markers/src | ||
| 96 | |||
| 97 | Compile them with your kernel. | ||
| 98 | |||
| 99 | Run, as root : | ||
| 100 | modprobe marker-example (insmod order is not important) | ||
| 101 | modprobe probe-example | ||
| 102 | cat /proc/marker-example (returns an expected error) | ||
| 103 | rmmod marker-example probe-example | ||
| 104 | dmesg | ||
diff --git a/Documentation/memory.txt b/Documentation/memory.txt index 2b3dedd39538..802efe58647c 100644 --- a/Documentation/memory.txt +++ b/Documentation/memory.txt | |||
| @@ -1,18 +1,7 @@ | |||
| 1 | There are several classic problems related to memory on Linux | 1 | There are several classic problems related to memory on Linux |
| 2 | systems. | 2 | systems. |
| 3 | 3 | ||
| 4 | 1) There are some buggy motherboards which cannot properly | 4 | 1) There are some motherboards that will not cache above |
| 5 | deal with the memory above 16MB. Consider exchanging | ||
| 6 | your motherboard. | ||
| 7 | |||
| 8 | 2) You cannot do DMA on the ISA bus to addresses above | ||
| 9 | 16M. Most device drivers under Linux allow the use | ||
| 10 | of bounce buffers which work around this problem. Drivers | ||
| 11 | that don't use bounce buffers will be unstable with | ||
| 12 | more than 16M installed. Drivers that use bounce buffers | ||
| 13 | will be OK, but may have slightly higher overhead. | ||
| 14 | |||
| 15 | 3) There are some motherboards that will not cache above | ||
| 16 | a certain quantity of memory. If you have one of these | 5 | a certain quantity of memory. If you have one of these |
| 17 | motherboards, your system will be SLOWER, not faster | 6 | motherboards, your system will be SLOWER, not faster |
| 18 | as you add more memory. Consider exchanging your | 7 | as you add more memory. Consider exchanging your |
| @@ -24,7 +13,7 @@ It can also tell Linux to use less memory than is actually installed. | |||
| 24 | If you use "mem=" on a machine with PCI, consider using "memmap=" to avoid | 13 | If you use "mem=" on a machine with PCI, consider using "memmap=" to avoid |
| 25 | physical address space collisions. | 14 | physical address space collisions. |
| 26 | 15 | ||
| 27 | See the documentation of your boot loader (LILO, loadlin, etc.) about | 16 | See the documentation of your boot loader (LILO, grub, loadlin, etc.) about |
| 28 | how to pass options to the kernel. | 17 | how to pass options to the kernel. |
| 29 | 18 | ||
| 30 | There are other memory problems which Linux cannot deal with. Random | 19 | There are other memory problems which Linux cannot deal with. Random |
| @@ -42,19 +31,3 @@ Try: | |||
| 42 | with the vendor. Consider testing it with memtest86 yourself. | 31 | with the vendor. Consider testing it with memtest86 yourself. |
| 43 | 32 | ||
| 44 | * Exchanging your CPU, cache, or motherboard for one that works. | 33 | * Exchanging your CPU, cache, or motherboard for one that works. |
| 45 | |||
| 46 | * Disabling the cache from the BIOS. | ||
| 47 | |||
| 48 | * Try passing the "mem=4M" option to the kernel to limit | ||
| 49 | Linux to using a very small amount of memory. Use "memmap="-option | ||
| 50 | together with "mem=" on systems with PCI to avoid physical address | ||
| 51 | space collisions. | ||
| 52 | |||
| 53 | |||
| 54 | Other tricks: | ||
| 55 | |||
| 56 | * Try passing the "no-387" option to the kernel to ignore | ||
| 57 | a buggy FPU. | ||
| 58 | |||
| 59 | * Try passing the "no-hlt" option to disable the potentially | ||
| 60 | buggy HLT instruction in your CPU. | ||
diff --git a/Documentation/networking/regulatory.txt b/Documentation/networking/regulatory.txt index eaa1a25946c1..ee31369e9e5b 100644 --- a/Documentation/networking/regulatory.txt +++ b/Documentation/networking/regulatory.txt | |||
| @@ -96,7 +96,7 @@ Example code - drivers hinting an alpha2: | |||
| 96 | 96 | ||
| 97 | This example comes from the zd1211rw device driver. You can start | 97 | This example comes from the zd1211rw device driver. You can start |
| 98 | by having a mapping of your device's EEPROM country/regulatory | 98 | by having a mapping of your device's EEPROM country/regulatory |
| 99 | domain value to to a specific alpha2 as follows: | 99 | domain value to a specific alpha2 as follows: |
| 100 | 100 | ||
| 101 | static struct zd_reg_alpha2_map reg_alpha2_map[] = { | 101 | static struct zd_reg_alpha2_map reg_alpha2_map[] = { |
| 102 | { ZD_REGDOMAIN_FCC, "US" }, | 102 | { ZD_REGDOMAIN_FCC, "US" }, |
diff --git a/Documentation/numastat.txt b/Documentation/numastat.txt index 80133ace1eb2..9fcc9a608dc0 100644 --- a/Documentation/numastat.txt +++ b/Documentation/numastat.txt | |||
| @@ -7,10 +7,10 @@ All units are pages. Hugepages have separate counters. | |||
| 7 | 7 | ||
| 8 | numa_hit A process wanted to allocate memory from this node, | 8 | numa_hit A process wanted to allocate memory from this node, |
| 9 | and succeeded. | 9 | and succeeded. |
| 10 | numa_miss A process wanted to allocate memory from this node, | 10 | numa_miss A process wanted to allocate memory from another node, |
| 11 | but ended up with memory from another. | 11 | but ended up with memory from this node. |
| 12 | numa_foreign A process wanted to allocate on another node, | 12 | numa_foreign A process wanted to allocate on this node, |
| 13 | but ended up with memory from this one. | 13 | but ended up with memory from another one. |
| 14 | local_node A process ran on this node and got memory from it. | 14 | local_node A process ran on this node and got memory from it. |
| 15 | other_node A process ran on this node and got memory from another node. | 15 | other_node A process ran on this node and got memory from another node. |
| 16 | interleave_hit Interleaving wanted to allocate from this node | 16 | interleave_hit Interleaving wanted to allocate from this node |
diff --git a/Documentation/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 | ||
| 11 | unsigned int crc32(unsigned char const *p, unsigned int len) | 11 | static 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, | |||
| 76 | discharging (i.e. powering a load), etc.). This corresponds to | 76 | discharging (i.e. powering a load), etc.). This corresponds to |
| 77 | BATTERY_STATUS_* values, as defined in battery.h. | 77 | BATTERY_STATUS_* values, as defined in battery.h. |
| 78 | 78 | ||
| 79 | CHARGE_TYPE - batteries can typically charge at different rates. | ||
| 80 | This defines trickle and fast charges. For batteries that | ||
| 81 | are already charged or discharging, 'n/a' can be displayed (or | ||
| 82 | 'unknown', if the status is not known). | ||
| 83 | |||
| 79 | HEALTH - represents health of the battery, values corresponds to | 84 | HEALTH - represents health of the battery, values corresponds to |
| 80 | POWER_SUPPLY_HEALTH_*, defined in battery.h. | 85 | POWER_SUPPLY_HEALTH_*, defined in battery.h. |
| 81 | 86 | ||
| @@ -108,6 +113,8 @@ relative, time-based measurements. | |||
| 108 | ENERGY_FULL, ENERGY_EMPTY - same as above but for energy. | 113 | ENERGY_FULL, ENERGY_EMPTY - same as above but for energy. |
| 109 | 114 | ||
| 110 | CAPACITY - capacity in percents. | 115 | CAPACITY - capacity in percents. |
| 116 | CAPACITY_LEVEL - capacity level. This corresponds to | ||
| 117 | POWER_SUPPLY_CAPACITY_LEVEL_*. | ||
| 111 | 118 | ||
| 112 | TEMP - temperature of the power supply. | 119 | TEMP - temperature of the power supply. |
| 113 | TEMP_AMBIENT - ambient temperature. | 120 | TEMP_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 @@ | |||
| 1 | Regulator API design notes | ||
| 2 | ========================== | ||
| 3 | |||
| 4 | This document provides a brief, partially structured, overview of some | ||
| 5 | of the design considerations which impact the regulator API design. | ||
| 6 | |||
| 7 | Safety | ||
| 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 | |||
| 21 | Consumer 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 */ |
| 90 | platform_device_register(&wm8350_regulator_devices[0]); | 90 | platform_device_register(®ulator_devices[0]); |
| 91 | 91 | ||
| 92 | /* register regulator 2 device */ | 92 | /* register regulator 2 device */ |
| 93 | platform_device_register(&wm8350_regulator_devices[1]); | 93 | platform_device_register(®ulator_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 | ||
| 11 | Drivers can register a regulator by calling :- | 11 | Drivers can register a regulator by calling :- |
| 12 | 12 | ||
| 13 | struct regulator_dev *regulator_register(struct device *dev, | 13 | struct 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 | ||
| 16 | This will register the regulators capabilities and operations to the regulator | 17 | This will register the regulators capabilities and operations to the regulator |
| 17 | core. | 18 | core. |
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 @@ | |||
| 1 | CFI or JEDEC memory-mapped NOR flash | 1 | CFI or JEDEC memory-mapped NOR flash, MTD-RAM (NVRAM...) |
| 2 | 2 | ||
| 3 | Flash chips (Memory Technology Devices) are often used for solid state | 3 | Flash chips (Memory Technology Devices) are often used for solid state |
| 4 | file systems on embedded devices. | 4 | file 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 | ||
| 25 | In addition to the information on the flash bank itself, the | 26 | In addition to the information on the mtd bank itself, the |
| 26 | device tree may optionally contain additional information | 27 | device tree may optionally contain additional information |
| 27 | describing partitions of the flash address space. This can be | 28 | describing partitions of the address space. This can be |
| 28 | used on platforms which have strong conventions about which | 29 | used on platforms which have strong conventions about which |
| 29 | portions of the flash are used for what purposes, but which don't | 30 | portions of a flash are used for what purposes, but which don't |
| 30 | use an on-flash partition table such as RedBoot. | 31 | use an on-flash partition table such as RedBoot. |
| 31 | 32 | ||
| 32 | Each partition is represented as a sub-node of the flash device. | 33 | Each partition is represented as a sub-node of the mtd device. |
| 33 | Each node's name represents the name of the corresponding | 34 | Each node's name represents the name of the corresponding |
| 34 | partition of the flash device. | 35 | partition of the mtd device. |
| 35 | 36 | ||
| 36 | Flash partitions | 37 | Flash 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 | |||
| 83 | An 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 | |||
| 135 | the system clock from the discrete RTC, but use the integrated one for all | 135 | the system clock from the discrete RTC, but use the integrated one for all |
| 136 | other tasks, because of its greater functionality. | 136 | other tasks, because of its greater functionality. |
| 137 | 137 | ||
| 138 | SYSFS INTERFACE | ||
| 139 | --------------- | ||
| 140 | |||
| 141 | The sysfs interface under /sys/class/rtc/rtcN provides access to various | ||
| 142 | rtc attributes without requiring the use of ioctls. All dates and times | ||
| 143 | are in the RTC's timezone, rather than in system time. | ||
| 144 | |||
| 145 | date: RTC-provided date | ||
| 146 | hctosys: 1 if the RTC provided the system time at boot via the | ||
| 147 | CONFIG_RTC_HCTOSYS kernel option, 0 otherwise | ||
| 148 | max_user_freq: The maximum interrupt rate an unprivileged user may request | ||
| 149 | from this RTC. | ||
| 150 | name: The name of the RTC corresponding to this sysfs directory | ||
| 151 | since_epoch: The number of seconds since the epoch according to the RTC | ||
| 152 | time: RTC-provided time | ||
| 153 | wakealarm: 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 | |||
| 159 | IOCTL INTERFACE | ||
| 160 | --------------- | ||
| 161 | |||
| 138 | The ioctl() calls supported by /dev/rtc are also supported by the RTC class | 162 | The ioctl() calls supported by /dev/rtc are also supported by the RTC class |
| 139 | framework. However, because the chips and systems are not standardized, | 163 | framework. However, because the chips and systems are not standardized, |
| 140 | some PC/AT functionality might not be provided. And in the same way, some | 164 | some 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 | |||
| 188 | If all else fails, check out the rtc-test.c driver! | 214 | If 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 | ||
| 515 | v. Remove redundant __megaraid_busywait_mbox routine | 515 | v. Remove redundant __megaraid_busywait_mbox routine |
| 516 | 516 | ||
| 517 | vi. Fix bug in the managment module, which causes a system lockup when the | 517 | vi. Fix bug in the management module, which causes a system lockup when the |
| 518 | IO module is loaded and then unloaded, followed by executing any | 518 | IO module is loaded and then unloaded, followed by executing any |
| 519 | management utility. The current version of management module does not | 519 | management utility. The current version of management module does not |
| 520 | handle the adapter unregister properly. | 520 | handle the adapter unregister properly. |
diff --git a/Documentation/scsi/scsi_fc_transport.txt b/Documentation/scsi/scsi_fc_transport.txt index d7f181701dc2..aec6549ab097 100644 --- a/Documentation/scsi/scsi_fc_transport.txt +++ b/Documentation/scsi/scsi_fc_transport.txt | |||
| @@ -378,7 +378,7 @@ Vport Disable/Enable: | |||
| 378 | int vport_disable(struct fc_vport *vport, bool disable) | 378 | int vport_disable(struct fc_vport *vport, bool disable) |
| 379 | 379 | ||
| 380 | where: | 380 | where: |
| 381 | vport: Is vport to to be enabled or disabled | 381 | vport: Is vport to be enabled or disabled |
| 382 | disable: If "true", the vport is to be disabled. | 382 | disable: If "true", the vport is to be disabled. |
| 383 | If "false", the vport is to be enabled. | 383 | If "false", the vport is to be enabled. |
| 384 | 384 | ||
diff --git a/Documentation/sound/alsa/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* | |||
| 387 | STAC92HD83* | 387 | STAC92HD83* |
| 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 | ||
| 353 | The driver core will autmatically attempt to bind this driver to any SPI | 353 | The driver core will automatically attempt to bind this driver to any SPI |
| 354 | device whose board_info gave a modalias of "CHIP". Your probe() code | 354 | device whose board_info gave a modalias of "CHIP". Your probe() code |
| 355 | might look like this unless you're creating a device which is managing | 355 | might look like this unless you're creating a device which is managing |
| 356 | a bus (appearing under /sys/class/spi_master). | 356 | a 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 | ||
| 72 | void print_usage(const char *prog) | 72 | static 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 | ||
| 88 | void parse_opts(int argc, char *argv[]) | 88 | static 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 | |||
| 96 | of error messages about running out of file handles, you might | 96 | of error messages about running out of file handles, you might |
| 97 | want to increase this limit. | 97 | want to increase this limit. |
| 98 | 98 | ||
| 99 | The three values in file-nr denote the number of allocated | 99 | Historically, the three values in file-nr denoted the number of |
| 100 | file handles, the number of unused file handles and the maximum | 100 | allocated file handles, the number of allocated but unused file |
| 101 | number of file handles. When the allocated file handles come | 101 | handles, and the maximum number of file handles. Linux 2.6 always |
| 102 | close to the maximum, but the number of unused file handles is | 102 | reports 0 as the number of free file handles -- this is not an |
| 103 | significantly greater than 0, you've encountered a peak in your | 103 | error, it just means that the number of allocated file handles |
| 104 | usage of file handles and you don't need to increase the maximum. | 104 | exactly matches the number of used file handles. |
| 105 | 105 | ||
| 106 | Attempts to allocate more file descriptors than file-max are | ||
| 107 | reported with printk, look for "VFS: file-max limit <number> | ||
| 108 | reached". | ||
| 106 | ============================================================== | 109 | ============================================================== |
| 107 | 110 | ||
| 108 | nr_open: | 111 | nr_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 | ||
| 139 | core_pipe_limit: | ||
| 140 | |||
| 141 | This sysctl is only applicable when core_pattern is configured to pipe core | ||
| 142 | files to user space helper a (when the first character of core_pattern is a '|', | ||
| 143 | see above). When collecting cores via a pipe to an application, it is | ||
| 144 | occasionally usefull for the collecting application to gather data about the | ||
| 145 | crashing process from its /proc/pid directory. In order to do this safely, the | ||
| 146 | kernel must wait for the collecting process to exit, so as not to remove the | ||
| 147 | crashing processes proc files prematurely. This in turn creates the possibility | ||
| 148 | that a misbehaving userspace collecting process can block the reaping of a | ||
| 149 | crashed process simply by never exiting. This sysctl defends against that. It | ||
| 150 | defines how many concurrent crashing processes may be piped to user space | ||
| 151 | applications in parallel. If this value is exceeded, then those crashing | ||
| 152 | processes above that value are noted via the kernel log and their cores are | ||
| 153 | skipped. 0 is a special value, indicating that unlimited processes may be | ||
| 154 | captured in parallel, but that no waiting will take place (i.e. the collecting | ||
| 155 | process is not guaranteed access to /proc/<crahing pid>/). This value defaults | ||
| 156 | to 0. | ||
| 157 | |||
| 158 | ============================================================== | ||
| 159 | |||
| 138 | core_uses_pid: | 160 | core_uses_pid: |
| 139 | 161 | ||
| 140 | The default coredump filename is "core". By setting | 162 | The default coredump filename is "core". By setting |
| @@ -313,31 +335,43 @@ send before ratelimiting kicks in. | |||
| 313 | 335 | ||
| 314 | ============================================================== | 336 | ============================================================== |
| 315 | 337 | ||
| 338 | printk_delay: | ||
| 339 | |||
| 340 | Delay each printk message in printk_delay milliseconds | ||
| 341 | |||
| 342 | Value from 0 - 10000 is allowed. | ||
| 343 | |||
| 344 | ============================================================== | ||
| 345 | |||
| 316 | randomize-va-space: | 346 | randomize-va-space: |
| 317 | 347 | ||
| 318 | This option can be used to select the type of process address | 348 | This option can be used to select the type of process address |
| 319 | space randomization that is used in the system, for architectures | 349 | space randomization that is used in the system, for architectures |
| 320 | that support this feature. | 350 | that support this feature. |
| 321 | 351 | ||
| 322 | 0 - Turn the process address space randomization off by default. | 352 | 0 - 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 | ||
| 324 | 1 - Make the addresses of mmap base, stack and VDSO page randomized. | 356 | 1 - 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 | 362 | 2 - 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. | |||
| 624 | At the default value of vfs_cache_pressure=100 the kernel will attempt to | 624 | At the default value of vfs_cache_pressure=100 the kernel will attempt to |
| 625 | reclaim dentries and inodes at a "fair" rate with respect to pagecache and | 625 | reclaim dentries and inodes at a "fair" rate with respect to pagecache and |
| 626 | swapcache reclaim. Decreasing vfs_cache_pressure causes the kernel to prefer | 626 | swapcache reclaim. Decreasing vfs_cache_pressure causes the kernel to prefer |
| 627 | to retain dentry and inode caches. Increasing vfs_cache_pressure beyond 100 | 627 | to retain dentry and inode caches. When vfs_cache_pressure=0, the kernel will |
| 628 | never reclaim dentries and inodes due to memory pressure and this can easily | ||
| 629 | lead to out-of-memory conditions. Increasing vfs_cache_pressure beyond 100 | ||
| 628 | causes the kernel to prefer to reclaim dentries and inodes. | 630 | causes 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 | |||
| 3 | The tracing system kmem captures events related to object and page allocation | ||
| 4 | within the kernel. Broadly speaking there are four major subheadings. | ||
| 5 | |||
| 6 | o Slab allocation of small objects of unknown type (kmalloc) | ||
| 7 | o Slab allocation of small objects of known type | ||
| 8 | o Page allocation | ||
| 9 | o Per-CPU Allocator Activity | ||
| 10 | o External Fragmentation | ||
| 11 | |||
| 12 | This document will describe what each of the tracepoints are and why they | ||
| 13 | might be useful. | ||
| 14 | |||
| 15 | 1. Slab allocation of small objects of unknown type | ||
| 16 | =================================================== | ||
| 17 | kmalloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s | ||
| 18 | kmalloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d | ||
| 19 | kfree call_site=%lx ptr=%p | ||
| 20 | |||
| 21 | Heavy activity for these events may indicate that a specific cache is | ||
| 22 | justified, particularly if kmalloc slab pages are getting significantly | ||
| 23 | internal fragmented as a result of the allocation pattern. By correlating | ||
| 24 | kmalloc with kfree, it may be possible to identify memory leaks and where | ||
| 25 | the allocation sites were. | ||
| 26 | |||
| 27 | |||
| 28 | 2. Slab allocation of small objects of known type | ||
| 29 | ================================================= | ||
| 30 | kmem_cache_alloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s | ||
| 31 | kmem_cache_alloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d | ||
| 32 | kmem_cache_free call_site=%lx ptr=%p | ||
| 33 | |||
| 34 | These events are similar in usage to the kmalloc-related events except that | ||
| 35 | it is likely easier to pin the event down to a specific cache. At the time | ||
| 36 | of writing, no information is available on what slab is being allocated from, | ||
| 37 | but the call_site can usually be used to extrapolate that information | ||
| 38 | |||
| 39 | 3. Page allocation | ||
| 40 | ================== | ||
| 41 | mm_page_alloc page=%p pfn=%lu order=%d migratetype=%d gfp_flags=%s | ||
| 42 | mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d | ||
| 43 | mm_page_free_direct page=%p pfn=%lu order=%d | ||
| 44 | mm_pagevec_free page=%p pfn=%lu order=%d cold=%d | ||
| 45 | |||
| 46 | These four events deal with page allocation and freeing. mm_page_alloc is | ||
| 47 | a simple indicator of page allocator activity. Pages may be allocated from | ||
| 48 | the per-CPU allocator (high performance) or the buddy allocator. | ||
| 49 | |||
| 50 | If pages are allocated directly from the buddy allocator, the | ||
| 51 | mm_page_alloc_zone_locked event is triggered. This event is important as high | ||
| 52 | amounts of activity imply high activity on the zone->lock. Taking this lock | ||
| 53 | impairs performance by disabling interrupts, dirtying cache lines between | ||
| 54 | CPUs and serialising many CPUs. | ||
| 55 | |||
| 56 | When a page is freed directly by the caller, the mm_page_free_direct event | ||
| 57 | is triggered. Significant amounts of activity here could indicate that the | ||
| 58 | callers should be batching their activities. | ||
| 59 | |||
| 60 | When pages are freed using a pagevec, the mm_pagevec_free is | ||
| 61 | triggered. Broadly speaking, pages are taken off the LRU lock in bulk and | ||
| 62 | freed in batch with a pagevec. Significant amounts of activity here could | ||
| 63 | indicate that the system is under memory pressure and can also indicate | ||
| 64 | contention on the zone->lru_lock. | ||
| 65 | |||
| 66 | 4. Per-CPU Allocator Activity | ||
| 67 | ============================= | ||
| 68 | mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d | ||
| 69 | mm_page_pcpu_drain page=%p pfn=%lu order=%d cpu=%d migratetype=%d | ||
| 70 | |||
| 71 | In front of the page allocator is a per-cpu page allocator. It exists only | ||
| 72 | for order-0 pages, reduces contention on the zone->lock and reduces the | ||
| 73 | amount of writing on struct page. | ||
| 74 | |||
| 75 | When a per-CPU list is empty or pages of the wrong type are allocated, | ||
| 76 | the zone->lock will be taken once and the per-CPU list refilled. The event | ||
| 77 | triggered is mm_page_alloc_zone_locked for each page allocated with the | ||
| 78 | event indicating whether it is for a percpu_refill or not. | ||
| 79 | |||
| 80 | When the per-CPU list is too full, a number of pages are freed, each one | ||
| 81 | which triggers a mm_page_pcpu_drain event. | ||
| 82 | |||
| 83 | The individual nature of the events are so that pages can be tracked | ||
| 84 | between allocation and freeing. A number of drain or refill pages that occur | ||
| 85 | consecutively imply the zone->lock being taken once. Large amounts of PCP | ||
| 86 | refills and drains could imply an imbalance between CPUs where too much work | ||
| 87 | is being concentrated in one place. It could also indicate that the per-CPU | ||
| 88 | lists should be a larger size. Finally, large amounts of refills on one CPU | ||
| 89 | and drains on another could be a factor in causing large amounts of cache | ||
| 90 | line bounces due to writes between CPUs and worth investigating if pages | ||
| 91 | can be allocated and freed on the same CPU through some algorithm change. | ||
| 92 | |||
| 93 | 5. External Fragmentation | ||
| 94 | ========================= | ||
| 95 | mm_page_alloc_extfrag page=%p pfn=%lu alloc_order=%d fallback_order=%d pageblock_order=%d alloc_migratetype=%d fallback_migratetype=%d fragmenting=%d change_ownership=%d | ||
| 96 | |||
| 97 | External fragmentation affects whether a high-order allocation will be | ||
| 98 | successful or not. For some types of hardware, this is important although | ||
| 99 | it is avoided where possible. If the system is using huge pages and needs | ||
| 100 | to be able to resize the pool over the lifetime of the system, this value | ||
| 101 | is important. | ||
| 102 | |||
| 103 | Large numbers of this event implies that memory is fragmenting and | ||
| 104 | high-order allocations will start failing at some time in the future. One | ||
| 105 | means of reducing the occurange of this event is to increase the size of | ||
| 106 | min_free_kbytes in increments of 3*pageblock_size*nr_online_nodes where | ||
| 107 | pageblock_size is usually the size of the default hugepage size. | ||
diff --git a/Documentation/trace/events.txt b/Documentation/trace/events.txt index 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 | ||
| 6 | 1. Introduction | 6 | 1. Introduction |
| 7 | =============== | 7 | =============== |
| @@ -22,12 +22,12 @@ tracing information should be printed. | |||
| 22 | --------------------------------- | 22 | --------------------------------- |
| 23 | 23 | ||
| 24 | The events which are available for tracing can be found in the file | 24 | The events which are available for tracing can be found in the file |
| 25 | /debug/tracing/available_events. | 25 | /sys/kernel/debug/tracing/available_events. |
| 26 | 26 | ||
| 27 | To enable a particular event, such as 'sched_wakeup', simply echo it | 27 | To enable a particular event, such as 'sched_wakeup', simply echo it |
| 28 | to /debug/tracing/set_event. For example: | 28 | to /sys/kernel/debug/tracing/set_event. For example: |
| 29 | 29 | ||
| 30 | # echo sched_wakeup >> /debug/tracing/set_event | 30 | # echo sched_wakeup >> /sys/kernel/debug/tracing/set_event |
| 31 | 31 | ||
| 32 | [ Note: '>>' is necessary, otherwise it will firstly disable | 32 | [ Note: '>>' is necessary, otherwise it will firstly disable |
| 33 | all the events. ] | 33 | all the events. ] |
| @@ -35,15 +35,15 @@ to /debug/tracing/set_event. For example: | |||
| 35 | To disable an event, echo the event name to the set_event file prefixed | 35 | To disable an event, echo the event name to the set_event file prefixed |
| 36 | with an exclamation point: | 36 | with an exclamation point: |
| 37 | 37 | ||
| 38 | # echo '!sched_wakeup' >> /debug/tracing/set_event | 38 | # echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event |
| 39 | 39 | ||
| 40 | To disable all events, echo an empty line to the set_event file: | 40 | To disable all events, echo an empty line to the set_event file: |
| 41 | 41 | ||
| 42 | # echo > /debug/tracing/set_event | 42 | # echo > /sys/kernel/debug/tracing/set_event |
| 43 | 43 | ||
| 44 | To enable all events, echo '*:*' or '*:' to the set_event file: | 44 | To enable all events, echo '*:*' or '*:' to the set_event file: |
| 45 | 45 | ||
| 46 | # echo *:* > /debug/tracing/set_event | 46 | # echo *:* > /sys/kernel/debug/tracing/set_event |
| 47 | 47 | ||
| 48 | The events are organized into subsystems, such as ext4, irq, sched, | 48 | The events are organized into subsystems, such as ext4, irq, sched, |
| 49 | etc., and a full event name looks like this: <subsystem>:<event>. The | 49 | etc., and a full event name looks like this: <subsystem>:<event>. The |
| @@ -52,29 +52,29 @@ file. All of the events in a subsystem can be specified via the syntax | |||
| 52 | "<subsystem>:*"; for example, to enable all irq events, you can use the | 52 | "<subsystem>:*"; for example, to enable all irq events, you can use the |
| 53 | command: | 53 | command: |
| 54 | 54 | ||
| 55 | # echo 'irq:*' > /debug/tracing/set_event | 55 | # echo 'irq:*' > /sys/kernel/debug/tracing/set_event |
| 56 | 56 | ||
| 57 | 2.2 Via the 'enable' toggle | 57 | 2.2 Via the 'enable' toggle |
| 58 | --------------------------- | 58 | --------------------------- |
| 59 | 59 | ||
| 60 | The events available are also listed in /debug/tracing/events/ hierarchy | 60 | The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy |
| 61 | of directories. | 61 | of directories. |
| 62 | 62 | ||
| 63 | To enable event 'sched_wakeup': | 63 | To enable event 'sched_wakeup': |
| 64 | 64 | ||
| 65 | # echo 1 > /debug/tracing/events/sched/sched_wakeup/enable | 65 | # echo 1 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable |
| 66 | 66 | ||
| 67 | To disable it: | 67 | To disable it: |
| 68 | 68 | ||
| 69 | # echo 0 > /debug/tracing/events/sched/sched_wakeup/enable | 69 | # echo 0 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable |
| 70 | 70 | ||
| 71 | To enable all events in sched subsystem: | 71 | To enable all events in sched subsystem: |
| 72 | 72 | ||
| 73 | # echo 1 > /debug/tracing/events/sched/enable | 73 | # echo 1 > /sys/kernel/debug/tracing/events/sched/enable |
| 74 | 74 | ||
| 75 | To eanble all events: | 75 | To enable all events: |
| 76 | 76 | ||
| 77 | # echo 1 > /debug/tracing/events/enable | 77 | # echo 1 > /sys/kernel/debug/tracing/events/enable |
| 78 | 78 | ||
| 79 | When reading one of these enable files, there are four results: | 79 | When reading one of these enable files, there are four results: |
| 80 | 80 | ||
| @@ -97,3 +97,185 @@ The format of this boot option is the same as described in section 2.1. | |||
| 97 | 97 | ||
| 98 | See The example provided in samples/trace_events | 98 | See The example provided in samples/trace_events |
| 99 | 99 | ||
| 100 | 4. Event formats | ||
| 101 | ================ | ||
| 102 | |||
| 103 | Each trace event has a 'format' file associated with it that contains | ||
| 104 | a description of each field in a logged event. This information can | ||
| 105 | be used to parse the binary trace stream, and is also the place to | ||
| 106 | find the field names that can be used in event filters (see section 5). | ||
| 107 | |||
| 108 | It also displays the format string that will be used to print the | ||
| 109 | event in text mode, along with the event name and ID used for | ||
| 110 | profiling. | ||
| 111 | |||
| 112 | Every event has a set of 'common' fields associated with it; these are | ||
| 113 | the fields prefixed with 'common_'. The other fields vary between | ||
| 114 | events and correspond to the fields defined in the TRACE_EVENT | ||
| 115 | definition for that event. | ||
| 116 | |||
| 117 | Each field in the format has the form: | ||
| 118 | |||
| 119 | field:field-type field-name; offset:N; size:N; | ||
| 120 | |||
| 121 | where offset is the offset of the field in the trace record and size | ||
| 122 | is the size of the data item, in bytes. | ||
| 123 | |||
| 124 | For example, here's the information displayed for the 'sched_wakeup' | ||
| 125 | event: | ||
| 126 | |||
| 127 | # cat /debug/tracing/events/sched/sched_wakeup/format | ||
| 128 | |||
| 129 | name: sched_wakeup | ||
| 130 | ID: 60 | ||
| 131 | format: | ||
| 132 | field:unsigned short common_type; offset:0; size:2; | ||
| 133 | field:unsigned char common_flags; offset:2; size:1; | ||
| 134 | field:unsigned char common_preempt_count; offset:3; size:1; | ||
| 135 | field:int common_pid; offset:4; size:4; | ||
| 136 | field:int common_tgid; offset:8; size:4; | ||
| 137 | |||
| 138 | field:char comm[TASK_COMM_LEN]; offset:12; size:16; | ||
| 139 | field:pid_t pid; offset:28; size:4; | ||
| 140 | field:int prio; offset:32; size:4; | ||
| 141 | field:int success; offset:36; size:4; | ||
| 142 | field:int cpu; offset:40; size:4; | ||
| 143 | |||
| 144 | print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid, | ||
| 145 | REC->prio, REC->success, REC->cpu | ||
| 146 | |||
| 147 | This event contains 10 fields, the first 5 common and the remaining 5 | ||
| 148 | event-specific. All the fields for this event are numeric, except for | ||
| 149 | 'comm' which is a string, a distinction important for event filtering. | ||
| 150 | |||
| 151 | 5. Event filtering | ||
| 152 | ================== | ||
| 153 | |||
| 154 | Trace events can be filtered in the kernel by associating boolean | ||
| 155 | 'filter expressions' with them. As soon as an event is logged into | ||
| 156 | the trace buffer, its fields are checked against the filter expression | ||
| 157 | associated with that event type. An event with field values that | ||
| 158 | 'match' the filter will appear in the trace output, and an event whose | ||
| 159 | values don't match will be discarded. An event with no filter | ||
| 160 | associated with it matches everything, and is the default when no | ||
| 161 | filter has been set for an event. | ||
| 162 | |||
| 163 | 5.1 Expression syntax | ||
| 164 | --------------------- | ||
| 165 | |||
| 166 | A filter expression consists of one or more 'predicates' that can be | ||
| 167 | combined using the logical operators '&&' and '||'. A predicate is | ||
| 168 | simply a clause that compares the value of a field contained within a | ||
| 169 | logged event with a constant value and returns either 0 or 1 depending | ||
| 170 | on whether the field value matched (1) or didn't match (0): | ||
| 171 | |||
| 172 | field-name relational-operator value | ||
| 173 | |||
| 174 | Parentheses can be used to provide arbitrary logical groupings and | ||
| 175 | double-quotes can be used to prevent the shell from interpreting | ||
| 176 | operators as shell metacharacters. | ||
| 177 | |||
| 178 | The field-names available for use in filters can be found in the | ||
| 179 | 'format' files for trace events (see section 4). | ||
| 180 | |||
| 181 | The relational-operators depend on the type of the field being tested: | ||
| 182 | |||
| 183 | The operators available for numeric fields are: | ||
| 184 | |||
| 185 | ==, !=, <, <=, >, >= | ||
| 186 | |||
| 187 | And for string fields they are: | ||
| 188 | |||
| 189 | ==, != | ||
| 190 | |||
| 191 | Currently, only exact string matches are supported. | ||
| 192 | |||
| 193 | Currently, the maximum number of predicates in a filter is 16. | ||
| 194 | |||
| 195 | 5.2 Setting filters | ||
| 196 | ------------------- | ||
| 197 | |||
| 198 | A filter for an individual event is set by writing a filter expression | ||
| 199 | to the 'filter' file for the given event. | ||
| 200 | |||
| 201 | For example: | ||
| 202 | |||
| 203 | # cd /debug/tracing/events/sched/sched_wakeup | ||
| 204 | # echo "common_preempt_count > 4" > filter | ||
| 205 | |||
| 206 | A slightly more involved example: | ||
| 207 | |||
| 208 | # cd /debug/tracing/events/sched/sched_signal_send | ||
| 209 | # echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter | ||
| 210 | |||
| 211 | If there is an error in the expression, you'll get an 'Invalid | ||
| 212 | argument' error when setting it, and the erroneous string along with | ||
| 213 | an error message can be seen by looking at the filter e.g.: | ||
| 214 | |||
| 215 | # cd /debug/tracing/events/sched/sched_signal_send | ||
| 216 | # echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter | ||
| 217 | -bash: echo: write error: Invalid argument | ||
| 218 | # cat filter | ||
| 219 | ((sig >= 10 && sig < 15) || dsig == 17) && comm != bash | ||
| 220 | ^ | ||
| 221 | parse_error: Field not found | ||
| 222 | |||
| 223 | Currently the caret ('^') for an error always appears at the beginning of | ||
| 224 | the filter string; the error message should still be useful though | ||
| 225 | even without more accurate position info. | ||
| 226 | |||
| 227 | 5.3 Clearing filters | ||
| 228 | -------------------- | ||
| 229 | |||
| 230 | To clear the filter for an event, write a '0' to the event's filter | ||
| 231 | file. | ||
| 232 | |||
| 233 | To clear the filters for all events in a subsystem, write a '0' to the | ||
| 234 | subsystem's filter file. | ||
| 235 | |||
| 236 | 5.3 Subsystem filters | ||
| 237 | --------------------- | ||
| 238 | |||
| 239 | For convenience, filters for every event in a subsystem can be set or | ||
| 240 | cleared as a group by writing a filter expression into the filter file | ||
| 241 | at the root of the subsytem. Note however, that if a filter for any | ||
| 242 | event within the subsystem lacks a field specified in the subsystem | ||
| 243 | filter, or if the filter can't be applied for any other reason, the | ||
| 244 | filter for that event will retain its previous setting. This can | ||
| 245 | result in an unintended mixture of filters which could lead to | ||
| 246 | confusing (to the user who might think different filters are in | ||
| 247 | effect) trace output. Only filters that reference just the common | ||
| 248 | fields can be guaranteed to propagate successfully to all events. | ||
| 249 | |||
| 250 | Here are a few subsystem filter examples that also illustrate the | ||
| 251 | above points: | ||
| 252 | |||
| 253 | Clear the filters on all events in the sched subsytem: | ||
| 254 | |||
| 255 | # cd /sys/kernel/debug/tracing/events/sched | ||
| 256 | # echo 0 > filter | ||
| 257 | # cat sched_switch/filter | ||
| 258 | none | ||
| 259 | # cat sched_wakeup/filter | ||
| 260 | none | ||
| 261 | |||
| 262 | Set a filter using only common fields for all events in the sched | ||
| 263 | subsytem (all events end up with the same filter): | ||
| 264 | |||
| 265 | # cd /sys/kernel/debug/tracing/events/sched | ||
| 266 | # echo common_pid == 0 > filter | ||
| 267 | # cat sched_switch/filter | ||
| 268 | common_pid == 0 | ||
| 269 | # cat sched_wakeup/filter | ||
| 270 | common_pid == 0 | ||
| 271 | |||
| 272 | Attempt to set a filter using a non-common field for all events in the | ||
| 273 | sched subsytem (all events but those that have a prev_pid field retain | ||
| 274 | their old filters): | ||
| 275 | |||
| 276 | # cd /sys/kernel/debug/tracing/events/sched | ||
| 277 | # echo prev_pid == 0 > filter | ||
| 278 | # cat sched_switch/filter | ||
| 279 | prev_pid == 0 | ||
| 280 | # cat sched_wakeup/filter | ||
| 281 | common_pid == 0 | ||
diff --git a/Documentation/trace/ftrace-design.txt b/Documentation/trace/ftrace-design.txt new file mode 100644 index 000000000000..7003e10f10f5 --- /dev/null +++ b/Documentation/trace/ftrace-design.txt | |||
| @@ -0,0 +1,233 @@ | |||
| 1 | function tracer guts | ||
| 2 | ==================== | ||
| 3 | |||
| 4 | Introduction | ||
| 5 | ------------ | ||
| 6 | |||
| 7 | Here we will cover the architecture pieces that the common function tracing | ||
| 8 | code relies on for proper functioning. Things are broken down into increasing | ||
| 9 | complexity so that you can start simple and at least get basic functionality. | ||
| 10 | |||
| 11 | Note that this focuses on architecture implementation details only. If you | ||
| 12 | want more explanation of a feature in terms of common code, review the common | ||
| 13 | ftrace.txt file. | ||
| 14 | |||
| 15 | |||
| 16 | Prerequisites | ||
| 17 | ------------- | ||
| 18 | |||
| 19 | Ftrace relies on these features being implemented: | ||
| 20 | STACKTRACE_SUPPORT - implement save_stack_trace() | ||
| 21 | TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h | ||
| 22 | |||
| 23 | |||
| 24 | HAVE_FUNCTION_TRACER | ||
| 25 | -------------------- | ||
| 26 | |||
| 27 | You will need to implement the mcount and the ftrace_stub functions. | ||
| 28 | |||
| 29 | The exact mcount symbol name will depend on your toolchain. Some call it | ||
| 30 | "mcount", "_mcount", or even "__mcount". You can probably figure it out by | ||
| 31 | running something like: | ||
| 32 | $ echo 'main(){}' | gcc -x c -S -o - - -pg | grep mcount | ||
| 33 | call mcount | ||
| 34 | We'll make the assumption below that the symbol is "mcount" just to keep things | ||
| 35 | nice and simple in the examples. | ||
| 36 | |||
| 37 | Keep in mind that the ABI that is in effect inside of the mcount function is | ||
| 38 | *highly* architecture/toolchain specific. We cannot help you in this regard, | ||
| 39 | sorry. Dig up some old documentation and/or find someone more familiar than | ||
| 40 | you to bang ideas off of. Typically, register usage (argument/scratch/etc...) | ||
| 41 | is a major issue at this point, especially in relation to the location of the | ||
| 42 | mcount call (before/after function prologue). You might also want to look at | ||
| 43 | how glibc has implemented the mcount function for your architecture. It might | ||
| 44 | be (semi-)relevant. | ||
| 45 | |||
| 46 | The mcount function should check the function pointer ftrace_trace_function | ||
| 47 | to see if it is set to ftrace_stub. If it is, there is nothing for you to do, | ||
| 48 | so return immediately. If it isn't, then call that function in the same way | ||
| 49 | the mcount function normally calls __mcount_internal -- the first argument is | ||
| 50 | the "frompc" while the second argument is the "selfpc" (adjusted to remove the | ||
| 51 | size of the mcount call that is embedded in the function). | ||
| 52 | |||
| 53 | For example, if the function foo() calls bar(), when the bar() function calls | ||
| 54 | mcount(), the arguments mcount() will pass to the tracer are: | ||
| 55 | "frompc" - the address bar() will use to return to foo() | ||
| 56 | "selfpc" - the address bar() (with _mcount() size adjustment) | ||
| 57 | |||
| 58 | Also keep in mind that this mcount function will be called *a lot*, so | ||
| 59 | optimizing for the default case of no tracer will help the smooth running of | ||
| 60 | your system when tracing is disabled. So the start of the mcount function is | ||
| 61 | typically the bare min with checking things before returning. That also means | ||
| 62 | the code flow should usually kept linear (i.e. no branching in the nop case). | ||
| 63 | This is of course an optimization and not a hard requirement. | ||
| 64 | |||
| 65 | Here is some pseudo code that should help (these functions should actually be | ||
| 66 | implemented in assembly): | ||
| 67 | |||
| 68 | void ftrace_stub(void) | ||
| 69 | { | ||
| 70 | return; | ||
| 71 | } | ||
| 72 | |||
| 73 | void mcount(void) | ||
| 74 | { | ||
| 75 | /* save any bare state needed in order to do initial checking */ | ||
| 76 | |||
| 77 | extern void (*ftrace_trace_function)(unsigned long, unsigned long); | ||
| 78 | if (ftrace_trace_function != ftrace_stub) | ||
| 79 | goto do_trace; | ||
| 80 | |||
| 81 | /* restore any bare state */ | ||
| 82 | |||
| 83 | return; | ||
| 84 | |||
| 85 | do_trace: | ||
| 86 | |||
| 87 | /* save all state needed by the ABI (see paragraph above) */ | ||
| 88 | |||
| 89 | unsigned long frompc = ...; | ||
| 90 | unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; | ||
| 91 | ftrace_trace_function(frompc, selfpc); | ||
| 92 | |||
| 93 | /* restore all state needed by the ABI */ | ||
| 94 | } | ||
| 95 | |||
| 96 | Don't forget to export mcount for modules ! | ||
| 97 | extern void mcount(void); | ||
| 98 | EXPORT_SYMBOL(mcount); | ||
| 99 | |||
| 100 | |||
| 101 | HAVE_FUNCTION_TRACE_MCOUNT_TEST | ||
| 102 | ------------------------------- | ||
| 103 | |||
| 104 | This is an optional optimization for the normal case when tracing is turned off | ||
| 105 | in the system. If you do not enable this Kconfig option, the common ftrace | ||
| 106 | code will take care of doing the checking for you. | ||
| 107 | |||
| 108 | To support this feature, you only need to check the function_trace_stop | ||
| 109 | variable in the mcount function. If it is non-zero, there is no tracing to be | ||
| 110 | done at all, so you can return. | ||
| 111 | |||
| 112 | This additional pseudo code would simply be: | ||
| 113 | void mcount(void) | ||
| 114 | { | ||
| 115 | /* save any bare state needed in order to do initial checking */ | ||
| 116 | |||
| 117 | + if (function_trace_stop) | ||
| 118 | + return; | ||
| 119 | |||
| 120 | extern void (*ftrace_trace_function)(unsigned long, unsigned long); | ||
| 121 | if (ftrace_trace_function != ftrace_stub) | ||
| 122 | ... | ||
| 123 | |||
| 124 | |||
| 125 | HAVE_FUNCTION_GRAPH_TRACER | ||
| 126 | -------------------------- | ||
| 127 | |||
| 128 | Deep breath ... time to do some real work. Here you will need to update the | ||
| 129 | mcount function to check ftrace graph function pointers, as well as implement | ||
| 130 | some functions to save (hijack) and restore the return address. | ||
| 131 | |||
| 132 | The mcount function should check the function pointers ftrace_graph_return | ||
| 133 | (compare to ftrace_stub) and ftrace_graph_entry (compare to | ||
| 134 | ftrace_graph_entry_stub). If either of those are not set to the relevant stub | ||
| 135 | function, call the arch-specific function ftrace_graph_caller which in turn | ||
| 136 | calls the arch-specific function prepare_ftrace_return. Neither of these | ||
| 137 | function names are strictly required, but you should use them anyways to stay | ||
| 138 | consistent across the architecture ports -- easier to compare & contrast | ||
| 139 | things. | ||
| 140 | |||
| 141 | The arguments to prepare_ftrace_return are slightly different than what are | ||
| 142 | passed to ftrace_trace_function. The second argument "selfpc" is the same, | ||
| 143 | but the first argument should be a pointer to the "frompc". Typically this is | ||
| 144 | located on the stack. This allows the function to hijack the return address | ||
| 145 | temporarily to have it point to the arch-specific function return_to_handler. | ||
| 146 | That function will simply call the common ftrace_return_to_handler function and | ||
| 147 | that will return the original return address with which, you can return to the | ||
| 148 | original call site. | ||
| 149 | |||
| 150 | Here is the updated mcount pseudo code: | ||
| 151 | void mcount(void) | ||
| 152 | { | ||
| 153 | ... | ||
| 154 | if (ftrace_trace_function != ftrace_stub) | ||
| 155 | goto do_trace; | ||
| 156 | |||
| 157 | +#ifdef CONFIG_FUNCTION_GRAPH_TRACER | ||
| 158 | + extern void (*ftrace_graph_return)(...); | ||
| 159 | + extern void (*ftrace_graph_entry)(...); | ||
| 160 | + if (ftrace_graph_return != ftrace_stub || | ||
| 161 | + ftrace_graph_entry != ftrace_graph_entry_stub) | ||
| 162 | + ftrace_graph_caller(); | ||
| 163 | +#endif | ||
| 164 | |||
| 165 | /* restore any bare state */ | ||
| 166 | ... | ||
| 167 | |||
| 168 | Here is the pseudo code for the new ftrace_graph_caller assembly function: | ||
| 169 | #ifdef CONFIG_FUNCTION_GRAPH_TRACER | ||
| 170 | void ftrace_graph_caller(void) | ||
| 171 | { | ||
| 172 | /* save all state needed by the ABI */ | ||
| 173 | |||
| 174 | unsigned long *frompc = &...; | ||
| 175 | unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; | ||
| 176 | prepare_ftrace_return(frompc, selfpc); | ||
| 177 | |||
| 178 | /* restore all state needed by the ABI */ | ||
| 179 | } | ||
| 180 | #endif | ||
| 181 | |||
| 182 | For information on how to implement prepare_ftrace_return(), simply look at | ||
| 183 | the x86 version. The only architecture-specific piece in it is the setup of | ||
| 184 | the fault recovery table (the asm(...) code). The rest should be the same | ||
| 185 | across architectures. | ||
| 186 | |||
| 187 | Here is the pseudo code for the new return_to_handler assembly function. Note | ||
| 188 | that the ABI that applies here is different from what applies to the mcount | ||
| 189 | code. Since you are returning from a function (after the epilogue), you might | ||
| 190 | be able to skimp on things saved/restored (usually just registers used to pass | ||
| 191 | return values). | ||
| 192 | |||
| 193 | #ifdef CONFIG_FUNCTION_GRAPH_TRACER | ||
| 194 | void return_to_handler(void) | ||
| 195 | { | ||
| 196 | /* save all state needed by the ABI (see paragraph above) */ | ||
| 197 | |||
| 198 | void (*original_return_point)(void) = ftrace_return_to_handler(); | ||
| 199 | |||
| 200 | /* restore all state needed by the ABI */ | ||
| 201 | |||
| 202 | /* this is usually either a return or a jump */ | ||
| 203 | original_return_point(); | ||
| 204 | } | ||
| 205 | #endif | ||
| 206 | |||
| 207 | |||
| 208 | HAVE_FTRACE_NMI_ENTER | ||
| 209 | --------------------- | ||
| 210 | |||
| 211 | If you can't trace NMI functions, then skip this option. | ||
| 212 | |||
| 213 | <details to be filled> | ||
| 214 | |||
| 215 | |||
| 216 | HAVE_FTRACE_SYSCALLS | ||
| 217 | --------------------- | ||
| 218 | |||
| 219 | <details to be filled> | ||
| 220 | |||
| 221 | |||
| 222 | HAVE_FTRACE_MCOUNT_RECORD | ||
| 223 | ------------------------- | ||
| 224 | |||
| 225 | See scripts/recordmcount.pl for more info. | ||
| 226 | |||
| 227 | <details to be filled> | ||
| 228 | |||
| 229 | |||
| 230 | HAVE_DYNAMIC_FTRACE | ||
| 231 | --------------------- | ||
| 232 | |||
| 233 | <details to be filled> | ||
diff --git a/Documentation/trace/ftrace.txt b/Documentation/trace/ftrace.txt index 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 | |||
| 26 | means that the list of tracers can always grow). | 26 | means that the list of tracers can always grow). |
| 27 | 27 | ||
| 28 | 28 | ||
| 29 | Implementation Details | ||
| 30 | ---------------------- | ||
| 31 | |||
| 32 | See ftrace-design.txt for details for arch porters and such. | ||
| 33 | |||
| 34 | |||
| 29 | The File System | 35 | The File System |
| 30 | --------------- | 36 | --------------- |
| 31 | 37 | ||
| @@ -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> | ||
| 15 | use strict; | ||
| 16 | use Getopt::Long; | ||
| 17 | |||
| 18 | # Tracepoint events | ||
| 19 | use constant MM_PAGE_ALLOC => 1; | ||
| 20 | use constant MM_PAGE_FREE_DIRECT => 2; | ||
| 21 | use constant MM_PAGEVEC_FREE => 3; | ||
| 22 | use constant MM_PAGE_PCPU_DRAIN => 4; | ||
| 23 | use constant MM_PAGE_ALLOC_ZONE_LOCKED => 5; | ||
| 24 | use constant MM_PAGE_ALLOC_EXTFRAG => 6; | ||
| 25 | use constant EVENT_UNKNOWN => 7; | ||
| 26 | |||
| 27 | # Constants used to track state | ||
| 28 | use constant STATE_PCPU_PAGES_DRAINED => 8; | ||
| 29 | use constant STATE_PCPU_PAGES_REFILLED => 9; | ||
| 30 | |||
| 31 | # High-level events extrapolated from tracepoints | ||
| 32 | use constant HIGH_PCPU_DRAINS => 10; | ||
| 33 | use constant HIGH_PCPU_REFILLS => 11; | ||
| 34 | use constant HIGH_EXT_FRAGMENT => 12; | ||
| 35 | use constant HIGH_EXT_FRAGMENT_SEVERE => 13; | ||
| 36 | use constant HIGH_EXT_FRAGMENT_MODERATE => 14; | ||
| 37 | use constant HIGH_EXT_FRAGMENT_CHANGED => 15; | ||
| 38 | |||
| 39 | my %perprocesspid; | ||
| 40 | my %perprocess; | ||
| 41 | my $opt_ignorepid; | ||
| 42 | my $opt_read_procstat; | ||
| 43 | my $opt_prepend_parent; | ||
| 44 | |||
| 45 | # Catch sigint and exit on request | ||
| 46 | my $sigint_report = 0; | ||
| 47 | my $sigint_exit = 0; | ||
| 48 | my $sigint_pending = 0; | ||
| 49 | my $sigint_received = 0; | ||
| 50 | sub sigint_handler { | ||
| 51 | my $current_time = time; | ||
| 52 | if ($current_time - 2 > $sigint_received) { | ||
| 53 | print "SIGINT received, report pending. Hit ctrl-c again to exit\n"; | ||
| 54 | $sigint_report = 1; | ||
| 55 | } else { | ||
| 56 | if (!$sigint_exit) { | ||
| 57 | print "Second SIGINT received quickly, exiting\n"; | ||
| 58 | } | ||
| 59 | $sigint_exit++; | ||
| 60 | } | ||
| 61 | |||
| 62 | if ($sigint_exit > 3) { | ||
| 63 | print "Many SIGINTs received, exiting now without report\n"; | ||
| 64 | exit; | ||
| 65 | } | ||
| 66 | |||
| 67 | $sigint_received = $current_time; | ||
| 68 | $sigint_pending = 1; | ||
| 69 | } | ||
| 70 | $SIG{INT} = "sigint_handler"; | ||
| 71 | |||
| 72 | # Parse command line options | ||
| 73 | GetOptions( | ||
| 74 | 'ignore-pid' => \$opt_ignorepid, | ||
| 75 | 'read-procstat' => \$opt_read_procstat, | ||
| 76 | 'prepend-parent' => \$opt_prepend_parent, | ||
| 77 | ); | ||
| 78 | |||
| 79 | # Defaults for dynamically discovered regex's | ||
| 80 | my $regex_fragdetails_default = 'page=([0-9a-f]*) pfn=([0-9]*) alloc_order=([-0-9]*) fallback_order=([-0-9]*) pageblock_order=([-0-9]*) alloc_migratetype=([-0-9]*) fallback_migratetype=([-0-9]*) fragmenting=([-0-9]) change_ownership=([-0-9])'; | ||
| 81 | |||
| 82 | # Dyanically discovered regex | ||
| 83 | my $regex_fragdetails; | ||
| 84 | |||
| 85 | # Static regex used. Specified like this for readability and for use with /o | ||
| 86 | # (process_pid) (cpus ) ( time ) (tpoint ) (details) | ||
| 87 | my $regex_traceevent = '\s*([a-zA-Z0-9-]*)\s*(\[[0-9]*\])\s*([0-9.]*):\s*([a-zA-Z_]*):\s*(.*)'; | ||
| 88 | my $regex_statname = '[-0-9]*\s\((.*)\).*'; | ||
| 89 | my $regex_statppid = '[-0-9]*\s\(.*\)\s[A-Za-z]\s([0-9]*).*'; | ||
| 90 | |||
| 91 | sub generate_traceevent_regex { | ||
| 92 | my $event = shift; | ||
| 93 | my $default = shift; | ||
| 94 | my $regex; | ||
| 95 | |||
| 96 | # Read the event format or use the default | ||
| 97 | if (!open (FORMAT, "/sys/kernel/debug/tracing/events/$event/format")) { | ||
| 98 | $regex = $default; | ||
| 99 | } else { | ||
| 100 | my $line; | ||
| 101 | while (!eof(FORMAT)) { | ||
| 102 | $line = <FORMAT>; | ||
| 103 | if ($line =~ /^print fmt:\s"(.*)",.*/) { | ||
| 104 | $regex = $1; | ||
| 105 | $regex =~ s/%p/\([0-9a-f]*\)/g; | ||
| 106 | $regex =~ s/%d/\([-0-9]*\)/g; | ||
| 107 | $regex =~ s/%lu/\([0-9]*\)/g; | ||
| 108 | } | ||
| 109 | } | ||
| 110 | } | ||
| 111 | |||
| 112 | # Verify fields are in the right order | ||
| 113 | my $tuple; | ||
| 114 | foreach $tuple (split /\s/, $regex) { | ||
| 115 | my ($key, $value) = split(/=/, $tuple); | ||
| 116 | my $expected = shift; | ||
| 117 | if ($key ne $expected) { | ||
| 118 | print("WARNING: Format not as expected '$key' != '$expected'"); | ||
| 119 | $regex =~ s/$key=\((.*)\)/$key=$1/; | ||
| 120 | } | ||
| 121 | } | ||
| 122 | |||
| 123 | if (defined shift) { | ||
| 124 | die("Fewer fields than expected in format"); | ||
| 125 | } | ||
| 126 | |||
| 127 | return $regex; | ||
| 128 | } | ||
| 129 | $regex_fragdetails = generate_traceevent_regex("kmem/mm_page_alloc_extfrag", | ||
| 130 | $regex_fragdetails_default, | ||
| 131 | "page", "pfn", | ||
| 132 | "alloc_order", "fallback_order", "pageblock_order", | ||
| 133 | "alloc_migratetype", "fallback_migratetype", | ||
| 134 | "fragmenting", "change_ownership"); | ||
| 135 | |||
| 136 | sub read_statline($) { | ||
| 137 | my $pid = $_[0]; | ||
| 138 | my $statline; | ||
| 139 | |||
| 140 | if (open(STAT, "/proc/$pid/stat")) { | ||
| 141 | $statline = <STAT>; | ||
| 142 | close(STAT); | ||
| 143 | } | ||
| 144 | |||
| 145 | if ($statline eq '') { | ||
| 146 | $statline = "-1 (UNKNOWN_PROCESS_NAME) R 0"; | ||
| 147 | } | ||
| 148 | |||
| 149 | return $statline; | ||
| 150 | } | ||
| 151 | |||
| 152 | sub guess_process_pid($$) { | ||
| 153 | my $pid = $_[0]; | ||
| 154 | my $statline = $_[1]; | ||
| 155 | |||
| 156 | if ($pid == 0) { | ||
| 157 | return "swapper-0"; | ||
| 158 | } | ||
| 159 | |||
| 160 | if ($statline !~ /$regex_statname/o) { | ||
| 161 | die("Failed to math stat line for process name :: $statline"); | ||
| 162 | } | ||
| 163 | return "$1-$pid"; | ||
| 164 | } | ||
| 165 | |||
| 166 | sub parent_info($$) { | ||
| 167 | my $pid = $_[0]; | ||
| 168 | my $statline = $_[1]; | ||
| 169 | my $ppid; | ||
| 170 | |||
| 171 | if ($pid == 0) { | ||
| 172 | return "NOPARENT-0"; | ||
| 173 | } | ||
| 174 | |||
| 175 | if ($statline !~ /$regex_statppid/o) { | ||
| 176 | die("Failed to match stat line process ppid:: $statline"); | ||
| 177 | } | ||
| 178 | |||
| 179 | # Read the ppid stat line | ||
| 180 | $ppid = $1; | ||
| 181 | return guess_process_pid($ppid, read_statline($ppid)); | ||
| 182 | } | ||
| 183 | |||
| 184 | sub process_events { | ||
| 185 | my $traceevent; | ||
| 186 | my $process_pid; | ||
| 187 | my $cpus; | ||
| 188 | my $timestamp; | ||
| 189 | my $tracepoint; | ||
| 190 | my $details; | ||
| 191 | my $statline; | ||
| 192 | |||
| 193 | # Read each line of the event log | ||
| 194 | EVENT_PROCESS: | ||
| 195 | while ($traceevent = <STDIN>) { | ||
| 196 | if ($traceevent =~ /$regex_traceevent/o) { | ||
| 197 | $process_pid = $1; | ||
| 198 | $tracepoint = $4; | ||
| 199 | |||
| 200 | if ($opt_read_procstat || $opt_prepend_parent) { | ||
| 201 | $process_pid =~ /(.*)-([0-9]*)$/; | ||
| 202 | my $process = $1; | ||
| 203 | my $pid = $2; | ||
| 204 | |||
| 205 | $statline = read_statline($pid); | ||
| 206 | |||
| 207 | if ($opt_read_procstat && $process eq '') { | ||
| 208 | $process_pid = guess_process_pid($pid, $statline); | ||
| 209 | } | ||
| 210 | |||
| 211 | if ($opt_prepend_parent) { | ||
| 212 | $process_pid = parent_info($pid, $statline) . " :: $process_pid"; | ||
| 213 | } | ||
| 214 | } | ||
| 215 | |||
| 216 | # Unnecessary in this script. Uncomment if required | ||
| 217 | # $cpus = $2; | ||
| 218 | # $timestamp = $3; | ||
| 219 | } else { | ||
| 220 | next; | ||
| 221 | } | ||
| 222 | |||
| 223 | # Perl Switch() sucks majorly | ||
| 224 | if ($tracepoint eq "mm_page_alloc") { | ||
| 225 | $perprocesspid{$process_pid}->{MM_PAGE_ALLOC}++; | ||
| 226 | } elsif ($tracepoint eq "mm_page_free_direct") { | ||
| 227 | $perprocesspid{$process_pid}->{MM_PAGE_FREE_DIRECT}++; | ||
| 228 | } elsif ($tracepoint eq "mm_pagevec_free") { | ||
| 229 | $perprocesspid{$process_pid}->{MM_PAGEVEC_FREE}++; | ||
| 230 | } elsif ($tracepoint eq "mm_page_pcpu_drain") { | ||
| 231 | $perprocesspid{$process_pid}->{MM_PAGE_PCPU_DRAIN}++; | ||
| 232 | $perprocesspid{$process_pid}->{STATE_PCPU_PAGES_DRAINED}++; | ||
| 233 | } elsif ($tracepoint eq "mm_page_alloc_zone_locked") { | ||
| 234 | $perprocesspid{$process_pid}->{MM_PAGE_ALLOC_ZONE_LOCKED}++; | ||
| 235 | $perprocesspid{$process_pid}->{STATE_PCPU_PAGES_REFILLED}++; | ||
| 236 | } elsif ($tracepoint eq "mm_page_alloc_extfrag") { | ||
| 237 | |||
| 238 | # Extract the details of the event now | ||
| 239 | $details = $5; | ||
| 240 | |||
| 241 | my ($page, $pfn); | ||
| 242 | my ($alloc_order, $fallback_order, $pageblock_order); | ||
| 243 | my ($alloc_migratetype, $fallback_migratetype); | ||
| 244 | my ($fragmenting, $change_ownership); | ||
| 245 | |||
| 246 | if ($details !~ /$regex_fragdetails/o) { | ||
| 247 | print "WARNING: Failed to parse mm_page_alloc_extfrag as expected\n"; | ||
| 248 | next; | ||
| 249 | } | ||
| 250 | |||
| 251 | $perprocesspid{$process_pid}->{MM_PAGE_ALLOC_EXTFRAG}++; | ||
| 252 | $page = $1; | ||
| 253 | $pfn = $2; | ||
| 254 | $alloc_order = $3; | ||
| 255 | $fallback_order = $4; | ||
| 256 | $pageblock_order = $5; | ||
| 257 | $alloc_migratetype = $6; | ||
| 258 | $fallback_migratetype = $7; | ||
| 259 | $fragmenting = $8; | ||
| 260 | $change_ownership = $9; | ||
| 261 | |||
| 262 | if ($fragmenting) { | ||
| 263 | $perprocesspid{$process_pid}->{HIGH_EXT_FRAG}++; | ||
| 264 | if ($fallback_order <= 3) { | ||
| 265 | $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_SEVERE}++; | ||
| 266 | } else { | ||
| 267 | $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_MODERATE}++; | ||
| 268 | } | ||
| 269 | } | ||
| 270 | if ($change_ownership) { | ||
| 271 | $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_CHANGED}++; | ||
| 272 | } | ||
| 273 | } else { | ||
| 274 | $perprocesspid{$process_pid}->{EVENT_UNKNOWN}++; | ||
| 275 | } | ||
| 276 | |||
| 277 | # Catch a full pcpu drain event | ||
| 278 | if ($perprocesspid{$process_pid}->{STATE_PCPU_PAGES_DRAINED} && | ||
| 279 | $tracepoint ne "mm_page_pcpu_drain") { | ||
| 280 | |||
| 281 | $perprocesspid{$process_pid}->{HIGH_PCPU_DRAINS}++; | ||
| 282 | $perprocesspid{$process_pid}->{STATE_PCPU_PAGES_DRAINED} = 0; | ||
| 283 | } | ||
| 284 | |||
| 285 | # Catch a full pcpu refill event | ||
| 286 | if ($perprocesspid{$process_pid}->{STATE_PCPU_PAGES_REFILLED} && | ||
| 287 | $tracepoint ne "mm_page_alloc_zone_locked") { | ||
| 288 | $perprocesspid{$process_pid}->{HIGH_PCPU_REFILLS}++; | ||
| 289 | $perprocesspid{$process_pid}->{STATE_PCPU_PAGES_REFILLED} = 0; | ||
| 290 | } | ||
| 291 | |||
| 292 | if ($sigint_pending) { | ||
| 293 | last EVENT_PROCESS; | ||
| 294 | } | ||
| 295 | } | ||
| 296 | } | ||
| 297 | |||
| 298 | sub dump_stats { | ||
| 299 | my $hashref = shift; | ||
| 300 | my %stats = %$hashref; | ||
| 301 | |||
| 302 | # Dump per-process stats | ||
| 303 | my $process_pid; | ||
| 304 | my $max_strlen = 0; | ||
| 305 | |||
| 306 | # Get the maximum process name | ||
| 307 | foreach $process_pid (keys %perprocesspid) { | ||
| 308 | my $len = length($process_pid); | ||
| 309 | if ($len > $max_strlen) { | ||
| 310 | $max_strlen = $len; | ||
| 311 | } | ||
| 312 | } | ||
| 313 | $max_strlen += 2; | ||
| 314 | |||
| 315 | printf("\n"); | ||
| 316 | printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s\n", | ||
| 317 | "Process", "Pages", "Pages", "Pages", "Pages", "PCPU", "PCPU", "PCPU", "Fragment", "Fragment", "MigType", "Fragment", "Fragment", "Unknown"); | ||
| 318 | printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s\n", | ||
| 319 | "details", "allocd", "allocd", "freed", "freed", "pages", "drains", "refills", "Fallback", "Causing", "Changed", "Severe", "Moderate", ""); | ||
| 320 | |||
| 321 | printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s %8s\n", | ||
| 322 | "", "", "under lock", "direct", "pagevec", "drain", "", "", "", "", "", "", "", ""); | ||
| 323 | |||
| 324 | foreach $process_pid (keys %stats) { | ||
| 325 | # Dump final aggregates | ||
| 326 | if ($stats{$process_pid}->{STATE_PCPU_PAGES_DRAINED}) { | ||
| 327 | $stats{$process_pid}->{HIGH_PCPU_DRAINS}++; | ||
| 328 | $stats{$process_pid}->{STATE_PCPU_PAGES_DRAINED} = 0; | ||
| 329 | } | ||
| 330 | if ($stats{$process_pid}->{STATE_PCPU_PAGES_REFILLED}) { | ||
| 331 | $stats{$process_pid}->{HIGH_PCPU_REFILLS}++; | ||
| 332 | $stats{$process_pid}->{STATE_PCPU_PAGES_REFILLED} = 0; | ||
| 333 | } | ||
| 334 | |||
| 335 | printf("%-" . $max_strlen . "s %8d %10d %8d %8d %8d %8d %8d %8d %8d %8d %8d %8d %8d\n", | ||
| 336 | $process_pid, | ||
| 337 | $stats{$process_pid}->{MM_PAGE_ALLOC}, | ||
| 338 | $stats{$process_pid}->{MM_PAGE_ALLOC_ZONE_LOCKED}, | ||
| 339 | $stats{$process_pid}->{MM_PAGE_FREE_DIRECT}, | ||
| 340 | $stats{$process_pid}->{MM_PAGEVEC_FREE}, | ||
| 341 | $stats{$process_pid}->{MM_PAGE_PCPU_DRAIN}, | ||
| 342 | $stats{$process_pid}->{HIGH_PCPU_DRAINS}, | ||
| 343 | $stats{$process_pid}->{HIGH_PCPU_REFILLS}, | ||
| 344 | $stats{$process_pid}->{MM_PAGE_ALLOC_EXTFRAG}, | ||
| 345 | $stats{$process_pid}->{HIGH_EXT_FRAG}, | ||
| 346 | $stats{$process_pid}->{HIGH_EXT_FRAGMENT_CHANGED}, | ||
| 347 | $stats{$process_pid}->{HIGH_EXT_FRAGMENT_SEVERE}, | ||
| 348 | $stats{$process_pid}->{HIGH_EXT_FRAGMENT_MODERATE}, | ||
| 349 | $stats{$process_pid}->{EVENT_UNKNOWN}); | ||
| 350 | } | ||
| 351 | } | ||
| 352 | |||
| 353 | sub aggregate_perprocesspid() { | ||
| 354 | my $process_pid; | ||
| 355 | my $process; | ||
| 356 | undef %perprocess; | ||
| 357 | |||
| 358 | foreach $process_pid (keys %perprocesspid) { | ||
| 359 | $process = $process_pid; | ||
| 360 | $process =~ s/-([0-9])*$//; | ||
| 361 | if ($process eq '') { | ||
| 362 | $process = "NO_PROCESS_NAME"; | ||
| 363 | } | ||
| 364 | |||
| 365 | $perprocess{$process}->{MM_PAGE_ALLOC} += $perprocesspid{$process_pid}->{MM_PAGE_ALLOC}; | ||
| 366 | $perprocess{$process}->{MM_PAGE_ALLOC_ZONE_LOCKED} += $perprocesspid{$process_pid}->{MM_PAGE_ALLOC_ZONE_LOCKED}; | ||
| 367 | $perprocess{$process}->{MM_PAGE_FREE_DIRECT} += $perprocesspid{$process_pid}->{MM_PAGE_FREE_DIRECT}; | ||
| 368 | $perprocess{$process}->{MM_PAGEVEC_FREE} += $perprocesspid{$process_pid}->{MM_PAGEVEC_FREE}; | ||
| 369 | $perprocess{$process}->{MM_PAGE_PCPU_DRAIN} += $perprocesspid{$process_pid}->{MM_PAGE_PCPU_DRAIN}; | ||
| 370 | $perprocess{$process}->{HIGH_PCPU_DRAINS} += $perprocesspid{$process_pid}->{HIGH_PCPU_DRAINS}; | ||
| 371 | $perprocess{$process}->{HIGH_PCPU_REFILLS} += $perprocesspid{$process_pid}->{HIGH_PCPU_REFILLS}; | ||
| 372 | $perprocess{$process}->{MM_PAGE_ALLOC_EXTFRAG} += $perprocesspid{$process_pid}->{MM_PAGE_ALLOC_EXTFRAG}; | ||
| 373 | $perprocess{$process}->{HIGH_EXT_FRAG} += $perprocesspid{$process_pid}->{HIGH_EXT_FRAG}; | ||
| 374 | $perprocess{$process}->{HIGH_EXT_FRAGMENT_CHANGED} += $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_CHANGED}; | ||
| 375 | $perprocess{$process}->{HIGH_EXT_FRAGMENT_SEVERE} += $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_SEVERE}; | ||
| 376 | $perprocess{$process}->{HIGH_EXT_FRAGMENT_MODERATE} += $perprocesspid{$process_pid}->{HIGH_EXT_FRAGMENT_MODERATE}; | ||
| 377 | $perprocess{$process}->{EVENT_UNKNOWN} += $perprocesspid{$process_pid}->{EVENT_UNKNOWN}; | ||
| 378 | } | ||
| 379 | } | ||
| 380 | |||
| 381 | sub report() { | ||
| 382 | if (!$opt_ignorepid) { | ||
| 383 | dump_stats(\%perprocesspid); | ||
| 384 | } else { | ||
| 385 | aggregate_perprocesspid(); | ||
| 386 | dump_stats(\%perprocess); | ||
| 387 | } | ||
| 388 | } | ||
| 389 | |||
| 390 | # Process events or signals until neither is available | ||
| 391 | sub signal_loop() { | ||
| 392 | my $sigint_processed; | ||
| 393 | do { | ||
| 394 | $sigint_processed = 0; | ||
| 395 | process_events(); | ||
| 396 | |||
| 397 | # Handle pending signals if any | ||
| 398 | if ($sigint_pending) { | ||
| 399 | my $current_time = time; | ||
| 400 | |||
| 401 | if ($sigint_exit) { | ||
| 402 | print "Received exit signal\n"; | ||
| 403 | $sigint_pending = 0; | ||
| 404 | } | ||
| 405 | if ($sigint_report) { | ||
| 406 | if ($current_time >= $sigint_received + 2) { | ||
| 407 | report(); | ||
| 408 | $sigint_report = 0; | ||
| 409 | $sigint_pending = 0; | ||
| 410 | $sigint_processed = 1; | ||
| 411 | } | ||
| 412 | } | ||
| 413 | } | ||
| 414 | } while ($sigint_pending || $sigint_processed); | ||
| 415 | } | ||
| 416 | |||
| 417 | signal_loop(); | ||
| 418 | report(); | ||
diff --git a/Documentation/trace/power.txt b/Documentation/trace/power.txt deleted file mode 100644 index cd805e16dc27..000000000000 --- a/Documentation/trace/power.txt +++ /dev/null | |||
| @@ -1,17 +0,0 @@ | |||
| 1 | The power tracer collects detailed information about C-state and P-state | ||
| 2 | transitions, instead of just looking at the high-level "average" | ||
| 3 | information. | ||
| 4 | |||
| 5 | There is a helper script found in scrips/tracing/power.pl in the kernel | ||
| 6 | sources which can be used to parse this information and create a | ||
| 7 | Scalable Vector Graphics (SVG) picture from the trace data. | ||
| 8 | |||
| 9 | To use this tracer: | ||
| 10 | |||
| 11 | echo 0 > /sys/kernel/debug/tracing/tracing_enabled | ||
| 12 | echo power > /sys/kernel/debug/tracing/current_tracer | ||
| 13 | echo 1 > /sys/kernel/debug/tracing/tracing_enabled | ||
| 14 | sleep 1 | ||
| 15 | echo 0 > /sys/kernel/debug/tracing/tracing_enabled | ||
| 16 | cat /sys/kernel/debug/tracing/trace | \ | ||
| 17 | perl scripts/tracing/power.pl > out.sv | ||
diff --git a/Documentation/trace/tracepoint-analysis.txt b/Documentation/trace/tracepoint-analysis.txt new file mode 100644 index 000000000000..5eb4e487e667 --- /dev/null +++ b/Documentation/trace/tracepoint-analysis.txt | |||
| @@ -0,0 +1,327 @@ | |||
| 1 | Notes on Analysing Behaviour Using Events and Tracepoints | ||
| 2 | |||
| 3 | Documentation written by Mel Gorman | ||
| 4 | PCL information heavily based on email from Ingo Molnar | ||
| 5 | |||
| 6 | 1. Introduction | ||
| 7 | =============== | ||
| 8 | |||
| 9 | Tracepoints (see Documentation/trace/tracepoints.txt) can be used without | ||
| 10 | creating custom kernel modules to register probe functions using the event | ||
| 11 | tracing infrastructure. | ||
| 12 | |||
| 13 | Simplistically, tracepoints will represent an important event that when can | ||
| 14 | be taken in conjunction with other tracepoints to build a "Big Picture" of | ||
| 15 | what is going on within the system. There are a large number of methods for | ||
| 16 | gathering and interpreting these events. Lacking any current Best Practises, | ||
| 17 | this document describes some of the methods that can be used. | ||
| 18 | |||
| 19 | This document assumes that debugfs is mounted on /sys/kernel/debug and that | ||
| 20 | the appropriate tracing options have been configured into the kernel. It is | ||
| 21 | assumed that the PCL tool tools/perf has been installed and is in your path. | ||
| 22 | |||
| 23 | 2. Listing Available Events | ||
| 24 | =========================== | ||
| 25 | |||
| 26 | 2.1 Standard Utilities | ||
| 27 | ---------------------- | ||
| 28 | |||
| 29 | All possible events are visible from /sys/kernel/debug/tracing/events. Simply | ||
| 30 | calling | ||
| 31 | |||
| 32 | $ find /sys/kernel/debug/tracing/events -type d | ||
| 33 | |||
| 34 | will give a fair indication of the number of events available. | ||
| 35 | |||
| 36 | 2.2 PCL | ||
| 37 | ------- | ||
| 38 | |||
| 39 | Discovery and enumeration of all counters and events, including tracepoints | ||
| 40 | are available with the perf tool. Getting a list of available events is a | ||
| 41 | simple case of | ||
| 42 | |||
| 43 | $ perf list 2>&1 | grep Tracepoint | ||
| 44 | ext4:ext4_free_inode [Tracepoint event] | ||
| 45 | ext4:ext4_request_inode [Tracepoint event] | ||
| 46 | ext4:ext4_allocate_inode [Tracepoint event] | ||
| 47 | ext4:ext4_write_begin [Tracepoint event] | ||
| 48 | ext4:ext4_ordered_write_end [Tracepoint event] | ||
| 49 | [ .... remaining output snipped .... ] | ||
| 50 | |||
| 51 | |||
| 52 | 2. Enabling Events | ||
| 53 | ================== | ||
| 54 | |||
| 55 | 2.1 System-Wide Event Enabling | ||
| 56 | ------------------------------ | ||
| 57 | |||
| 58 | See Documentation/trace/events.txt for a proper description on how events | ||
| 59 | can be enabled system-wide. A short example of enabling all events related | ||
| 60 | to page allocation would look something like | ||
| 61 | |||
| 62 | $ for i in `find /sys/kernel/debug/tracing/events -name "enable" | grep mm_`; do echo 1 > $i; done | ||
| 63 | |||
| 64 | 2.2 System-Wide Event Enabling with SystemTap | ||
| 65 | --------------------------------------------- | ||
| 66 | |||
| 67 | In SystemTap, tracepoints are accessible using the kernel.trace() function | ||
| 68 | call. The following is an example that reports every 5 seconds what processes | ||
| 69 | were allocating the pages. | ||
| 70 | |||
| 71 | global page_allocs | ||
| 72 | |||
| 73 | probe kernel.trace("mm_page_alloc") { | ||
| 74 | page_allocs[execname()]++ | ||
| 75 | } | ||
| 76 | |||
| 77 | function print_count() { | ||
| 78 | printf ("%-25s %-s\n", "#Pages Allocated", "Process Name") | ||
| 79 | foreach (proc in page_allocs-) | ||
| 80 | printf("%-25d %s\n", page_allocs[proc], proc) | ||
| 81 | printf ("\n") | ||
| 82 | delete page_allocs | ||
| 83 | } | ||
| 84 | |||
| 85 | probe timer.s(5) { | ||
| 86 | print_count() | ||
| 87 | } | ||
| 88 | |||
| 89 | 2.3 System-Wide Event Enabling with PCL | ||
| 90 | --------------------------------------- | ||
| 91 | |||
| 92 | By specifying the -a switch and analysing sleep, the system-wide events | ||
| 93 | for a duration of time can be examined. | ||
| 94 | |||
| 95 | $ perf stat -a \ | ||
| 96 | -e kmem:mm_page_alloc -e kmem:mm_page_free_direct \ | ||
| 97 | -e kmem:mm_pagevec_free \ | ||
| 98 | sleep 10 | ||
| 99 | Performance counter stats for 'sleep 10': | ||
| 100 | |||
| 101 | 9630 kmem:mm_page_alloc | ||
| 102 | 2143 kmem:mm_page_free_direct | ||
| 103 | 7424 kmem:mm_pagevec_free | ||
| 104 | |||
| 105 | 10.002577764 seconds time elapsed | ||
| 106 | |||
| 107 | Similarly, one could execute a shell and exit it as desired to get a report | ||
| 108 | at that point. | ||
| 109 | |||
| 110 | 2.4 Local Event Enabling | ||
| 111 | ------------------------ | ||
| 112 | |||
| 113 | Documentation/trace/ftrace.txt describes how to enable events on a per-thread | ||
| 114 | basis using set_ftrace_pid. | ||
| 115 | |||
| 116 | 2.5 Local Event Enablement with PCL | ||
| 117 | ----------------------------------- | ||
| 118 | |||
| 119 | Events can be activate and tracked for the duration of a process on a local | ||
| 120 | basis using PCL such as follows. | ||
| 121 | |||
| 122 | $ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free_direct \ | ||
| 123 | -e kmem:mm_pagevec_free ./hackbench 10 | ||
| 124 | Time: 0.909 | ||
| 125 | |||
| 126 | Performance counter stats for './hackbench 10': | ||
| 127 | |||
| 128 | 17803 kmem:mm_page_alloc | ||
| 129 | 12398 kmem:mm_page_free_direct | ||
| 130 | 4827 kmem:mm_pagevec_free | ||
| 131 | |||
| 132 | 0.973913387 seconds time elapsed | ||
| 133 | |||
| 134 | 3. Event Filtering | ||
| 135 | ================== | ||
| 136 | |||
| 137 | Documentation/trace/ftrace.txt covers in-depth how to filter events in | ||
| 138 | ftrace. Obviously using grep and awk of trace_pipe is an option as well | ||
| 139 | as any script reading trace_pipe. | ||
| 140 | |||
| 141 | 4. Analysing Event Variances with PCL | ||
| 142 | ===================================== | ||
| 143 | |||
| 144 | Any workload can exhibit variances between runs and it can be important | ||
| 145 | to know what the standard deviation in. By and large, this is left to the | ||
| 146 | performance analyst to do it by hand. In the event that the discrete event | ||
| 147 | occurrences are useful to the performance analyst, then perf can be used. | ||
| 148 | |||
| 149 | $ perf stat --repeat 5 -e kmem:mm_page_alloc -e kmem:mm_page_free_direct | ||
| 150 | -e kmem:mm_pagevec_free ./hackbench 10 | ||
| 151 | Time: 0.890 | ||
| 152 | Time: 0.895 | ||
| 153 | Time: 0.915 | ||
| 154 | Time: 1.001 | ||
| 155 | Time: 0.899 | ||
| 156 | |||
| 157 | Performance counter stats for './hackbench 10' (5 runs): | ||
| 158 | |||
| 159 | 16630 kmem:mm_page_alloc ( +- 3.542% ) | ||
| 160 | 11486 kmem:mm_page_free_direct ( +- 4.771% ) | ||
| 161 | 4730 kmem:mm_pagevec_free ( +- 2.325% ) | ||
| 162 | |||
| 163 | 0.982653002 seconds time elapsed ( +- 1.448% ) | ||
| 164 | |||
| 165 | In the event that some higher-level event is required that depends on some | ||
| 166 | aggregation of discrete events, then a script would need to be developed. | ||
| 167 | |||
| 168 | Using --repeat, it is also possible to view how events are fluctuating over | ||
| 169 | time on a system wide basis using -a and sleep. | ||
| 170 | |||
| 171 | $ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free_direct \ | ||
| 172 | -e kmem:mm_pagevec_free \ | ||
| 173 | -a --repeat 10 \ | ||
| 174 | sleep 1 | ||
| 175 | Performance counter stats for 'sleep 1' (10 runs): | ||
| 176 | |||
| 177 | 1066 kmem:mm_page_alloc ( +- 26.148% ) | ||
| 178 | 182 kmem:mm_page_free_direct ( +- 5.464% ) | ||
| 179 | 890 kmem:mm_pagevec_free ( +- 30.079% ) | ||
| 180 | |||
| 181 | 1.002251757 seconds time elapsed ( +- 0.005% ) | ||
| 182 | |||
| 183 | 5. Higher-Level Analysis with Helper Scripts | ||
| 184 | ============================================ | ||
| 185 | |||
| 186 | When events are enabled the events that are triggering can be read from | ||
| 187 | /sys/kernel/debug/tracing/trace_pipe in human-readable format although binary | ||
| 188 | options exist as well. By post-processing the output, further information can | ||
| 189 | be gathered on-line as appropriate. Examples of post-processing might include | ||
| 190 | |||
| 191 | o Reading information from /proc for the PID that triggered the event | ||
| 192 | o Deriving a higher-level event from a series of lower-level events. | ||
| 193 | o Calculate latencies between two events | ||
| 194 | |||
| 195 | Documentation/trace/postprocess/trace-pagealloc-postprocess.pl is an example | ||
| 196 | script that can read trace_pipe from STDIN or a copy of a trace. When used | ||
| 197 | on-line, it can be interrupted once to generate a report without existing | ||
| 198 | and twice to exit. | ||
| 199 | |||
| 200 | Simplistically, the script just reads STDIN and counts up events but it | ||
| 201 | also can do more such as | ||
| 202 | |||
| 203 | o Derive high-level events from many low-level events. If a number of pages | ||
| 204 | are freed to the main allocator from the per-CPU lists, it recognises | ||
| 205 | that as one per-CPU drain even though there is no specific tracepoint | ||
| 206 | for that event | ||
| 207 | o It can aggregate based on PID or individual process number | ||
| 208 | o In the event memory is getting externally fragmented, it reports | ||
| 209 | on whether the fragmentation event was severe or moderate. | ||
| 210 | o When receiving an event about a PID, it can record who the parent was so | ||
| 211 | that if large numbers of events are coming from very short-lived | ||
| 212 | processes, the parent process responsible for creating all the helpers | ||
| 213 | can be identified | ||
| 214 | |||
| 215 | 6. Lower-Level Analysis with PCL | ||
| 216 | ================================ | ||
| 217 | |||
| 218 | There may also be a requirement to identify what functions with a program | ||
| 219 | were generating events within the kernel. To begin this sort of analysis, the | ||
| 220 | data must be recorded. At the time of writing, this required root | ||
| 221 | |||
| 222 | $ perf record -c 1 \ | ||
| 223 | -e kmem:mm_page_alloc -e kmem:mm_page_free_direct \ | ||
| 224 | -e kmem:mm_pagevec_free \ | ||
| 225 | ./hackbench 10 | ||
| 226 | Time: 0.894 | ||
| 227 | [ perf record: Captured and wrote 0.733 MB perf.data (~32010 samples) ] | ||
| 228 | |||
| 229 | Note the use of '-c 1' to set the event period to sample. The default sample | ||
| 230 | period is quite high to minimise overhead but the information collected can be | ||
| 231 | very coarse as a result. | ||
| 232 | |||
| 233 | This record outputted a file called perf.data which can be analysed using | ||
| 234 | perf report. | ||
| 235 | |||
| 236 | $ perf report | ||
| 237 | # Samples: 30922 | ||
| 238 | # | ||
| 239 | # Overhead Command Shared Object | ||
| 240 | # ........ ......... ................................ | ||
| 241 | # | ||
| 242 | 87.27% hackbench [vdso] | ||
| 243 | 6.85% hackbench /lib/i686/cmov/libc-2.9.so | ||
| 244 | 2.62% hackbench /lib/ld-2.9.so | ||
| 245 | 1.52% perf [vdso] | ||
| 246 | 1.22% hackbench ./hackbench | ||
| 247 | 0.48% hackbench [kernel] | ||
| 248 | 0.02% perf /lib/i686/cmov/libc-2.9.so | ||
| 249 | 0.01% perf /usr/bin/perf | ||
| 250 | 0.01% perf /lib/ld-2.9.so | ||
| 251 | 0.00% hackbench /lib/i686/cmov/libpthread-2.9.so | ||
| 252 | # | ||
| 253 | # (For more details, try: perf report --sort comm,dso,symbol) | ||
| 254 | # | ||
| 255 | |||
| 256 | According to this, the vast majority of events occured triggered on events | ||
| 257 | within the VDSO. With simple binaries, this will often be the case so lets | ||
| 258 | take a slightly different example. In the course of writing this, it was | ||
| 259 | noticed that X was generating an insane amount of page allocations so lets look | ||
| 260 | at it | ||
| 261 | |||
| 262 | $ perf record -c 1 -f \ | ||
| 263 | -e kmem:mm_page_alloc -e kmem:mm_page_free_direct \ | ||
| 264 | -e kmem:mm_pagevec_free \ | ||
| 265 | -p `pidof X` | ||
| 266 | |||
| 267 | This was interrupted after a few seconds and | ||
| 268 | |||
| 269 | $ perf report | ||
| 270 | # Samples: 27666 | ||
| 271 | # | ||
| 272 | # Overhead Command Shared Object | ||
| 273 | # ........ ....... ....................................... | ||
| 274 | # | ||
| 275 | 51.95% Xorg [vdso] | ||
| 276 | 47.95% Xorg /opt/gfx-test/lib/libpixman-1.so.0.13.1 | ||
| 277 | 0.09% Xorg /lib/i686/cmov/libc-2.9.so | ||
| 278 | 0.01% Xorg [kernel] | ||
| 279 | # | ||
| 280 | # (For more details, try: perf report --sort comm,dso,symbol) | ||
| 281 | # | ||
| 282 | |||
| 283 | So, almost half of the events are occuring in a library. To get an idea which | ||
| 284 | symbol. | ||
| 285 | |||
| 286 | $ perf report --sort comm,dso,symbol | ||
| 287 | # Samples: 27666 | ||
| 288 | # | ||
| 289 | # Overhead Command Shared Object Symbol | ||
| 290 | # ........ ....... ....................................... ...... | ||
| 291 | # | ||
| 292 | 51.95% Xorg [vdso] [.] 0x000000ffffe424 | ||
| 293 | 47.93% Xorg /opt/gfx-test/lib/libpixman-1.so.0.13.1 [.] pixmanFillsse2 | ||
| 294 | 0.09% Xorg /lib/i686/cmov/libc-2.9.so [.] _int_malloc | ||
| 295 | 0.01% Xorg /opt/gfx-test/lib/libpixman-1.so.0.13.1 [.] pixman_region32_copy_f | ||
| 296 | 0.01% Xorg [kernel] [k] read_hpet | ||
| 297 | 0.01% Xorg /opt/gfx-test/lib/libpixman-1.so.0.13.1 [.] get_fast_path | ||
| 298 | 0.00% Xorg [kernel] [k] ftrace_trace_userstack | ||
| 299 | |||
| 300 | To see where within the function pixmanFillsse2 things are going wrong | ||
| 301 | |||
| 302 | $ perf annotate pixmanFillsse2 | ||
| 303 | [ ... ] | ||
| 304 | 0.00 : 34eeb: 0f 18 08 prefetcht0 (%eax) | ||
| 305 | : } | ||
| 306 | : | ||
| 307 | : extern __inline void __attribute__((__gnu_inline__, __always_inline__, _ | ||
| 308 | : _mm_store_si128 (__m128i *__P, __m128i __B) : { | ||
| 309 | : *__P = __B; | ||
| 310 | 12.40 : 34eee: 66 0f 7f 80 40 ff ff movdqa %xmm0,-0xc0(%eax) | ||
| 311 | 0.00 : 34ef5: ff | ||
| 312 | 12.40 : 34ef6: 66 0f 7f 80 50 ff ff movdqa %xmm0,-0xb0(%eax) | ||
| 313 | 0.00 : 34efd: ff | ||
| 314 | 12.39 : 34efe: 66 0f 7f 80 60 ff ff movdqa %xmm0,-0xa0(%eax) | ||
| 315 | 0.00 : 34f05: ff | ||
| 316 | 12.67 : 34f06: 66 0f 7f 80 70 ff ff movdqa %xmm0,-0x90(%eax) | ||
| 317 | 0.00 : 34f0d: ff | ||
| 318 | 12.58 : 34f0e: 66 0f 7f 40 80 movdqa %xmm0,-0x80(%eax) | ||
| 319 | 12.31 : 34f13: 66 0f 7f 40 90 movdqa %xmm0,-0x70(%eax) | ||
| 320 | 12.40 : 34f18: 66 0f 7f 40 a0 movdqa %xmm0,-0x60(%eax) | ||
| 321 | 12.31 : 34f1d: 66 0f 7f 40 b0 movdqa %xmm0,-0x50(%eax) | ||
| 322 | |||
| 323 | At a glance, it looks like the time is being spent copying pixmaps to | ||
| 324 | the card. Further investigation would be needed to determine why pixmaps | ||
| 325 | are being copied around so much but a starting point would be to take an | ||
| 326 | ancient build of libpixmap out of the library path where it was totally | ||
| 327 | forgotten about from months ago! | ||
diff --git a/Documentation/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 | ||
| 17 | Authorize a device to connect: | 17 | Authorize 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 | ||
| 21 | Deauthorize a device: | 21 | Deauthorize a device: |
| 22 | 22 | ||
| 23 | $ echo 0 > /sys/usb/devices/DEVICE/authorized | 23 | $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized |
| 24 | 24 | ||
| 25 | Set new devices connected to hostX to be deauthorized by default (ie: | 25 | Set new devices connected to hostX to be deauthorized by default (ie: |
| 26 | lock down): | 26 | lock down): |
| 27 | 27 | ||
| 28 | $ echo 0 > /sys/bus/devices/usbX/authorized_default | 28 | $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default |
| 29 | 29 | ||
| 30 | Remove the lock down: | 30 | Remove 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 | ||
| 34 | By default, Wired USB devices are authorized by default to | 34 | By default, Wired USB devices are authorized by default to |
| 35 | connect. Wireless USB hosts deauthorize by default all new connected | 35 | connect. Wireless USB hosts deauthorize by default all new connected |
| @@ -47,7 +47,7 @@ USB port): | |||
| 47 | boot up | 47 | boot up |
| 48 | rc.local -> | 48 | rc.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 | ||
| 34 | Verify that bus sockets are present. | 34 | Verify that bus sockets are present. |
| 35 | 35 | ||
| 36 | # ls /sys/kernel/debug/usbmon | 36 | # ls /sys/kernel/debug/usb/usbmon |
| 37 | 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u | 37 | 0s 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 | ||
| 59 | 3. Start 'cat' | 59 | 3. 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 | ||
| 63 | to listen on a single bus, otherwise, to listen on all buses, type: | 63 | to 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 | ||
| 67 | This process will be reading until killed. Naturally, the output can be | 67 | This process will be reading until killed. Naturally, the output can be |
| 68 | redirected to a desirable location. This is preferred, because it is going | 68 | redirected 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 | |||
| 305 | pointed by hdr contains the next event structure, and the data buffer contains | 305 | pointed by hdr contains the next event structure, and the data buffer contains |
| 306 | the data, if any. The event is removed from the kernel buffer. | 306 | the data, if any. The event is removed from the kernel buffer. |
| 307 | 307 | ||
| 308 | The MON_IOCX_GET copies 48 bytes, MON_IOCX_GETX copies 64 bytes. | 308 | The 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 | |||
| 2 | VGA Arbiter | ||
| 3 | =========== | ||
| 4 | |||
| 5 | Graphic devices are accessed through ranges in I/O or memory space. While most | ||
| 6 | modern devices allow relocation of such ranges, some "Legacy" VGA devices | ||
| 7 | implemented on PCI will typically have the same "hard-decoded" addresses as | ||
| 8 | they did on ISA. For more details see "PCI Bus Binding to IEEE Std 1275-1994 | ||
| 9 | Standard for Boot (Initialization Configuration) Firmware Revision 2.1" | ||
| 10 | Section 7, Legacy Devices. | ||
| 11 | |||
| 12 | The Resource Access Control (RAC) module inside the X server [0] existed for | ||
| 13 | the legacy VGA arbitration task (besides other bus management tasks) when more | ||
| 14 | than one legacy device co-exists on the same machine. But the problem happens | ||
| 15 | when these devices are trying to be accessed by different userspace clients | ||
| 16 | (e.g. two server in parallel). Their address assignments conflict. Moreover, | ||
| 17 | ideally, being an userspace application, it is not the role of the the X | ||
| 18 | server to control bus resources. Therefore an arbitration scheme outside of | ||
| 19 | the X server is needed to control the sharing of these resources. This | ||
| 20 | document introduces the operation of the VGA arbiter implemented for Linux | ||
| 21 | kernel. | ||
| 22 | |||
| 23 | ---------------------------------------------------------------------------- | ||
| 24 | |||
| 25 | I. Details and Theory of Operation | ||
| 26 | I.1 vgaarb | ||
| 27 | I.2 libpciaccess | ||
| 28 | I.3 xf86VGAArbiter (X server implementation) | ||
| 29 | II. Credits | ||
| 30 | III.References | ||
| 31 | |||
| 32 | |||
| 33 | I. Details and Theory of Operation | ||
| 34 | ================================== | ||
| 35 | |||
| 36 | I.1 vgaarb | ||
| 37 | ---------- | ||
| 38 | |||
| 39 | The vgaarb is a module of the Linux Kernel. When it is initially loaded, it | ||
| 40 | scans all PCI devices and adds the VGA ones inside the arbitration. The | ||
| 41 | arbiter then enables/disables the decoding on different devices of the VGA | ||
| 42 | legacy instructions. Device which do not want/need to use the arbiter may | ||
| 43 | explicitly tell it by calling vga_set_legacy_decoding(). | ||
| 44 | |||
| 45 | The kernel exports a char device interface (/dev/vga_arbiter) to the clients, | ||
| 46 | which has the following semantics: | ||
| 47 | |||
| 48 | open : open user instance of the arbiter. By default, it's attached to | ||
| 49 | the default VGA device of the system. | ||
| 50 | |||
| 51 | close : close user instance. Release locks made by the user | ||
| 52 | |||
| 53 | read : return a string indicating the status of the target like: | ||
| 54 | |||
| 55 | "<card_ID>,decodes=<io_state>,owns=<io_state>,locks=<io_state> (ic,mc)" | ||
| 56 | |||
| 57 | An IO state string is of the form {io,mem,io+mem,none}, mc and | ||
| 58 | ic are respectively mem and io lock counts (for debugging/ | ||
| 59 | diagnostic only). "decodes" indicate what the card currently | ||
| 60 | decodes, "owns" indicates what is currently enabled on it, and | ||
| 61 | "locks" indicates what is locked by this card. If the card is | ||
| 62 | unplugged, we get "invalid" then for card_ID and an -ENODEV | ||
| 63 | error is returned for any command until a new card is targeted. | ||
| 64 | |||
| 65 | |||
| 66 | write : write a command to the arbiter. List of commands: | ||
| 67 | |||
| 68 | target <card_ID> : switch target to card <card_ID> (see below) | ||
| 69 | lock <io_state> : acquires locks on target ("none" is an invalid io_state) | ||
| 70 | trylock <io_state> : non-blocking acquire locks on target (returns EBUSY if | ||
| 71 | unsuccessful) | ||
| 72 | unlock <io_state> : release locks on target | ||
| 73 | unlock all : release all locks on target held by this user (not | ||
| 74 | implemented yet) | ||
| 75 | decodes <io_state> : set the legacy decoding attributes for the card | ||
| 76 | |||
| 77 | poll : event if something changes on any card (not just the | ||
| 78 | target) | ||
| 79 | |||
| 80 | card_ID is of the form "PCI:domain:bus:dev.fn". It can be set to "default" | ||
| 81 | to go back to the system default card (TODO: not implemented yet). Currently, | ||
| 82 | only PCI is supported as a prefix, but the userland API may support other bus | ||
| 83 | types in the future, even if the current kernel implementation doesn't. | ||
| 84 | |||
| 85 | Note about locks: | ||
| 86 | |||
| 87 | The driver keeps track of which user has which locks on which card. It | ||
| 88 | supports stacking, like the kernel one. This complexifies the implementation | ||
| 89 | a bit, but makes the arbiter more tolerant to user space problems and able | ||
| 90 | to properly cleanup in all cases when a process dies. | ||
| 91 | Currently, a max of 16 cards can have locks simultaneously issued from | ||
| 92 | user space for a given user (file descriptor instance) of the arbiter. | ||
| 93 | |||
| 94 | In the case of devices hot-{un,}plugged, there is a hook - pci_notify() - to | ||
| 95 | notify them being added/removed in the system and automatically added/removed | ||
| 96 | in the arbiter. | ||
| 97 | |||
| 98 | There's also a in-kernel API of the arbiter in the case of DRM, vgacon and | ||
| 99 | others which may use the arbiter. | ||
| 100 | |||
| 101 | |||
| 102 | I.2 libpciaccess | ||
| 103 | ---------------- | ||
| 104 | |||
| 105 | To use the vga arbiter char device it was implemented an API inside the | ||
| 106 | libpciaccess library. One fieldd was added to struct pci_device (each device | ||
| 107 | on the system): | ||
| 108 | |||
| 109 | /* the type of resource decoded by the device */ | ||
| 110 | int vgaarb_rsrc; | ||
| 111 | |||
| 112 | Besides it, in pci_system were added: | ||
| 113 | |||
| 114 | int vgaarb_fd; | ||
| 115 | int vga_count; | ||
| 116 | struct pci_device *vga_target; | ||
| 117 | struct pci_device *vga_default_dev; | ||
| 118 | |||
| 119 | |||
| 120 | The vga_count is usually need to keep informed how many cards are being | ||
| 121 | arbitrated, so for instance if there's only one then it can totally escape the | ||
| 122 | scheme. | ||
| 123 | |||
| 124 | |||
| 125 | These functions below acquire VGA resources for the given card and mark those | ||
| 126 | resources as locked. If the resources requested are "normal" (and not legacy) | ||
| 127 | resources, the arbiter will first check whether the card is doing legacy | ||
| 128 | decoding for that type of resource. If yes, the lock is "converted" into a | ||
| 129 | legacy resource lock. The arbiter will first look for all VGA cards that | ||
| 130 | might conflict and disable their IOs and/or Memory access, including VGA | ||
| 131 | forwarding on P2P bridges if necessary, so that the requested resources can | ||
| 132 | be used. Then, the card is marked as locking these resources and the IO and/or | ||
| 133 | Memory access is enabled on the card (including VGA forwarding on parent | ||
| 134 | P2P bridges if any). In the case of vga_arb_lock(), the function will block | ||
| 135 | if some conflicting card is already locking one of the required resources (or | ||
| 136 | any resource on a different bus segment, since P2P bridges don't differentiate | ||
| 137 | VGA memory and IO afaik). If the card already owns the resources, the function | ||
| 138 | succeeds. vga_arb_trylock() will return (-EBUSY) instead of blocking. Nested | ||
| 139 | calls are supported (a per-resource counter is maintained). | ||
| 140 | |||
| 141 | |||
| 142 | Set the target device of this client. | ||
| 143 | int pci_device_vgaarb_set_target (struct pci_device *dev); | ||
| 144 | |||
| 145 | |||
| 146 | For instance, in x86 if two devices on the same bus want to lock different | ||
| 147 | resources, both will succeed (lock). If devices are in different buses and | ||
| 148 | trying to lock different resources, only the first who tried succeeds. | ||
| 149 | int pci_device_vgaarb_lock (void); | ||
| 150 | int pci_device_vgaarb_trylock (void); | ||
| 151 | |||
| 152 | Unlock resources of device. | ||
| 153 | int pci_device_vgaarb_unlock (void); | ||
| 154 | |||
| 155 | Indicates to the arbiter if the card decodes legacy VGA IOs, legacy VGA | ||
| 156 | Memory, both, or none. All cards default to both, the card driver (fbdev for | ||
| 157 | example) should tell the arbiter if it has disabled legacy decoding, so the | ||
| 158 | card can be left out of the arbitration process (and can be safe to take | ||
| 159 | interrupts at any time. | ||
| 160 | int pci_device_vgaarb_decodes (int new_vgaarb_rsrc); | ||
| 161 | |||
| 162 | Connects to the arbiter device, allocates the struct | ||
| 163 | int pci_device_vgaarb_init (void); | ||
| 164 | |||
| 165 | Close the connection | ||
| 166 | void pci_device_vgaarb_fini (void); | ||
| 167 | |||
| 168 | |||
| 169 | I.3 xf86VGAArbiter (X server implementation) | ||
| 170 | -------------------------------------------- | ||
| 171 | |||
| 172 | (TODO) | ||
| 173 | |||
| 174 | X server basically wraps all the functions that touch VGA registers somehow. | ||
| 175 | |||
| 176 | |||
| 177 | II. Credits | ||
| 178 | =========== | ||
| 179 | |||
| 180 | Benjamin Herrenschmidt (IBM?) started this work when he discussed such design | ||
| 181 | with the Xorg community in 2005 [1, 2]. In the end of 2007, Paulo Zanoni and | ||
| 182 | Tiago Vignatti (both of C3SL/Federal University of Paraná) proceeded his work | ||
| 183 | enhancing the kernel code to adapt as a kernel module and also did the | ||
| 184 | implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave | ||
| 185 | Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree. | ||
| 186 | |||
| 187 | |||
| 188 | III. References | ||
| 189 | ============== | ||
| 190 | |||
| 191 | [0] http://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347 | ||
| 192 | [1] http://lists.freedesktop.org/archives/xorg/2005-March/006663.html | ||
| 193 | [2] http://lists.freedesktop.org/archives/xorg/2005-March/006745.html | ||
| 194 | [3] http://lists.freedesktop.org/archives/xorg/2007-October/029507.html | ||
diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885 index 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 @@ | |||
| 171 | 170 -> AverMedia AverTV Studio 505 [1461:a115] | 171 | 170 -> AverMedia AverTV Studio 505 [1461:a115] |
| 172 | 171 -> Beholder BeholdTV X7 [5ace:7595] | 172 | 171 -> Beholder BeholdTV X7 [5ace:7595] |
| 173 | 172 -> RoverMedia TV Link Pro FM [19d1:0138] | 173 | 172 -> RoverMedia TV Link Pro FM [19d1:0138] |
| 174 | 173 -> Zolid Hybrid TV Tuner PCI [1131:2004] | ||
diff --git a/Documentation/video4linux/CARDLIST.saa7164 b/Documentation/video4linux/CARDLIST.saa7164 new file mode 100644 index 000000000000..152bd7b781ca --- /dev/null +++ b/Documentation/video4linux/CARDLIST.saa7164 | |||
| @@ -0,0 +1,9 @@ | |||
| 1 | 0 -> Unknown | ||
| 2 | 1 -> Generic Rev2 | ||
| 3 | 2 -> Generic Rev3 | ||
| 4 | 3 -> Hauppauge WinTV-HVR2250 [0070:8880,0070:8810] | ||
| 5 | 4 -> Hauppauge WinTV-HVR2200 [0070:8980] | ||
| 6 | 5 -> Hauppauge WinTV-HVR2200 [0070:8900] | ||
| 7 | 6 -> Hauppauge WinTV-HVR2200 [0070:8901] | ||
| 8 | 7 -> Hauppauge WinTV-HVR2250 [0070:8891,0070:8851] | ||
| 9 | 8 -> Hauppauge WinTV-HVR2250 [0070:88A1] | ||
diff --git a/Documentation/video4linux/CARDLIST.tuner b/Documentation/video4linux/CARDLIST.tuner index ba9fa679e2d3..e0d298fe8830 100644 --- a/Documentation/video4linux/CARDLIST.tuner +++ b/Documentation/video4linux/CARDLIST.tuner | |||
| @@ -79,3 +79,5 @@ tuner=78 - Philips FMD1216MEX MK3 Hybrid Tuner | |||
| 79 | tuner=79 - Philips PAL/SECAM multi (FM1216 MK5) | 79 | tuner=79 - Philips PAL/SECAM multi (FM1216 MK5) |
| 80 | tuner=80 - Philips FQ1216LME MK3 PAL/SECAM w/active loopthrough | 80 | tuner=80 - Philips FQ1216LME MK3 PAL/SECAM w/active loopthrough |
| 81 | tuner=81 - Partsnic (Daewoo) PTI-5NF05 | 81 | tuner=81 - Partsnic (Daewoo) PTI-5NF05 |
| 82 | tuner=82 - Philips CU1216L | ||
| 83 | tuner=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 | |||
| 173 | ov519 05a9:a518 D-Link DSB-C310 Webcam | 173 | ov519 05a9:a518 D-Link DSB-C310 Webcam |
| 174 | sunplus 05da:1018 Digital Dream Enigma 1.3 | 174 | sunplus 05da:1018 Digital Dream Enigma 1.3 |
| 175 | stk014 05e1:0893 Syntek DV4000 | 175 | stk014 05e1:0893 Syntek DV4000 |
| 176 | gl860 05e3:0503 Genesys Logic PC Camera | ||
| 177 | gl860 05e3:f191 Genesys Logic PC Camera | ||
| 176 | spca561 060b:a001 Maxell Compact Pc PM3 | 178 | spca561 060b:a001 Maxell Compact Pc PM3 |
| 177 | zc3xx 0698:2003 CTX M730V built in | 179 | zc3xx 0698:2003 CTX M730V built in |
| 178 | spca500 06bd:0404 Agfa CL20 | 180 | spca500 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. | |||
| 116 | struct soc_camera_device also links to an array of struct soc_camera_data_format, | 116 | struct soc_camera_device also links to an array of struct soc_camera_data_format, |
| 117 | listing pixel formats, supported by the camera. | 117 | listing pixel formats, supported by the camera. |
| 118 | 118 | ||
| 119 | VIDIOC_S_CROP and VIDIOC_S_FMT behaviour | ||
| 120 | ---------------------------------------- | ||
| 121 | |||
| 122 | Above user ioctls modify image geometry as follows: | ||
| 123 | |||
| 124 | VIDIOC_S_CROP: sets location and sizes of the sensor window. Unit is one sensor | ||
| 125 | pixel. Changing sensor window sizes preserves any scaling factors, therefore | ||
| 126 | user window sizes change as well. | ||
| 127 | |||
| 128 | VIDIOC_S_FMT: sets user window. Should preserve previously set sensor window as | ||
| 129 | much as possible by modifying scaling factors. If the sensor window cannot be | ||
| 130 | preserved precisely, it may be changed too. | ||
| 131 | |||
| 132 | In soc-camera there are two locations, where scaling and cropping can taks | ||
| 133 | place: in the camera driver and in the host driver. User ioctls are first passed | ||
| 134 | to the host driver, which then generally passes them down to the camera driver. | ||
| 135 | It is more efficient to perform scaling and cropping in the camera driver to | ||
| 136 | save camera bus bandwidth and maximise the framerate. However, if the camera | ||
| 137 | driver failed to set the required parameters with sufficient precision, the host | ||
| 138 | driver may decide to also use its own scaling and cropping to fulfill the user's | ||
| 139 | request. | ||
| 140 | |||
| 141 | Camera drivers are interfaced to the soc-camera core and to host drivers over | ||
| 142 | the v4l2-subdev API, which is completely functional, it doesn't pass any data. | ||
| 143 | Therefore all camera drivers shall reply to .g_fmt() requests with their current | ||
| 144 | output geometry. This is necessary to correctly configure the camera bus. | ||
| 145 | .s_fmt() and .try_fmt() have to be implemented too. Sensor window and scaling | ||
| 146 | factors have to be maintained by camera drivers internally. According to the | ||
| 147 | V4L2 API all capture drivers must support the VIDIOC_CROPCAP ioctl, hence we | ||
| 148 | rely on camera drivers implementing .cropcap(). If the camera driver does not | ||
| 149 | support cropping, it may choose to not implement .s_crop(), but to enable | ||
| 150 | cropping support by the camera host driver at least the .g_crop method must be | ||
| 151 | implemented. | ||
| 152 | |||
| 153 | User window geometry is kept in .user_width and .user_height fields in struct | ||
| 154 | soc_camera_device and used by the soc-camera core and host drivers. The core | ||
| 155 | updates these fields upon successful completion of a .s_fmt() call, but if these | ||
| 156 | fields change elsewhere, e.g., during .s_crop() processing, the host driver is | ||
| 157 | responsible for updating them. | ||
| 158 | |||
| 119 | -- | 159 | -- |
| 120 | Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de> | 160 | Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de> |
diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index ba4706afc5fb..b806edaf3e75 100644 --- a/Documentation/video4linux/v4l2-framework.txt +++ b/Documentation/video4linux/v4l2-framework.txt | |||
| @@ -370,19 +370,20 @@ from the remove() callback ensures that this is always done correctly. | |||
| 370 | The bridge driver also has some helper functions it can use: | 370 | The bridge driver also has some helper functions it can use: |
| 371 | 371 | ||
| 372 | struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter, | 372 | struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter, |
| 373 | "module_foo", "chipid", 0x36); | 373 | "module_foo", "chipid", 0x36, NULL); |
| 374 | 374 | ||
| 375 | This loads the given module (can be NULL if no module needs to be loaded) and | 375 | This loads the given module (can be NULL if no module needs to be loaded) and |
| 376 | calls i2c_new_device() with the given i2c_adapter and chip/address arguments. | 376 | calls i2c_new_device() with the given i2c_adapter and chip/address arguments. |
| 377 | If all goes well, then it registers the subdev with the v4l2_device. | 377 | If all goes well, then it registers the subdev with the v4l2_device. |
| 378 | 378 | ||
| 379 | You can also use v4l2_i2c_new_probed_subdev() which is very similar to | 379 | You can also use the last argument of v4l2_i2c_new_subdev() to pass an array |
| 380 | v4l2_i2c_new_subdev(), except that it has an array of possible I2C addresses | 380 | of possible I2C addresses that it should probe. These probe addresses are |
| 381 | that it should probe. Internally it calls i2c_new_probed_device(). | 381 | only used if the previous argument is 0. A non-zero argument means that you |
| 382 | know the exact i2c address so in that case no probing will take place. | ||
| 382 | 383 | ||
| 383 | Both functions return NULL if something went wrong. | 384 | Both functions return NULL if something went wrong. |
| 384 | 385 | ||
| 385 | Note that the chipid you pass to v4l2_i2c_new_(probed_)subdev() is usually | 386 | Note that the chipid you pass to v4l2_i2c_new_subdev() is usually |
| 386 | the same as the module name. It allows you to specify a chip variant, e.g. | 387 | the same as the module name. It allows you to specify a chip variant, e.g. |
| 387 | "saa7114" or "saa7115". In general though the i2c driver autodetects this. | 388 | "saa7114" or "saa7115". In general though the i2c driver autodetects this. |
| 388 | The use of chipid is something that needs to be looked at more closely at a | 389 | The use of chipid is something that needs to be looked at more closely at a |
| @@ -410,11 +411,6 @@ the irq and platform_data arguments after the subdev was setup. The older | |||
| 410 | v4l2_i2c_new_(probed_)subdev functions will call s_config as well, but with | 411 | v4l2_i2c_new_(probed_)subdev functions will call s_config as well, but with |
| 411 | irq set to 0 and platform_data set to NULL. | 412 | irq set to 0 and platform_data set to NULL. |
| 412 | 413 | ||
| 413 | Note that in the next kernel release the functions v4l2_i2c_new_subdev, | ||
| 414 | v4l2_i2c_new_probed_subdev and v4l2_i2c_new_probed_subdev_addr will all be | ||
| 415 | replaced by a single v4l2_i2c_new_subdev that is identical to | ||
| 416 | v4l2_i2c_new_subdev_cfg but without the irq and platform_data arguments. | ||
| 417 | |||
| 418 | struct video_device | 414 | struct video_device |
| 419 | ------------------- | 415 | ------------------- |
| 420 | 416 | ||
| @@ -490,31 +486,35 @@ VFL_TYPE_RADIO: radioX for radio tuners | |||
| 490 | VFL_TYPE_VTX: vtxX for teletext devices (deprecated, don't use) | 486 | VFL_TYPE_VTX: vtxX for teletext devices (deprecated, don't use) |
| 491 | 487 | ||
| 492 | The last argument gives you a certain amount of control over the device | 488 | The last argument gives you a certain amount of control over the device |
| 493 | kernel number used (i.e. the X in videoX). Normally you will pass -1 to | 489 | device node number used (i.e. the X in videoX). Normally you will pass -1 |
| 494 | let the v4l2 framework pick the first free number. But if a driver creates | 490 | to let the v4l2 framework pick the first free number. But sometimes users |
| 495 | many devices, then it can be useful to have different video devices in | 491 | want to select a specific node number. It is common that drivers allow |
| 496 | separate ranges. For example, video capture devices start at 0, video | 492 | the user to select a specific device node number through a driver module |
| 497 | output devices start at 16. | 493 | option. That number is then passed to this function and video_register_device |
| 498 | 494 | will attempt to select that device node number. If that number was already | |
| 499 | So you can use the last argument to specify a minimum kernel number and | 495 | in use, then the next free device node number will be selected and it |
| 500 | the v4l2 framework will try to pick the first free number that is equal | 496 | will send a warning to the kernel log. |
| 497 | |||
| 498 | Another use-case is if a driver creates many devices. In that case it can | ||
| 499 | be useful to place different video devices in separate ranges. For example, | ||
| 500 | video capture devices start at 0, video output devices start at 16. | ||
| 501 | So you can use the last argument to specify a minimum device node number | ||
| 502 | and the v4l2 framework will try to pick the first free number that is equal | ||
| 501 | or higher to what you passed. If that fails, then it will just pick the | 503 | or higher to what you passed. If that fails, then it will just pick the |
| 502 | first free number. | 504 | first free number. |
| 503 | 505 | ||
| 506 | Since in this case you do not care about a warning about not being able | ||
| 507 | to select the specified device node number, you can call the function | ||
| 508 | video_register_device_no_warn() instead. | ||
| 509 | |||
| 504 | Whenever a device node is created some attributes are also created for you. | 510 | Whenever a device node is created some attributes are also created for you. |
| 505 | If you look in /sys/class/video4linux you see the devices. Go into e.g. | 511 | If you look in /sys/class/video4linux you see the devices. Go into e.g. |
| 506 | video0 and you will see 'name' and 'index' attributes. The 'name' attribute | 512 | video0 and you will see 'name' and 'index' attributes. The 'name' attribute |
| 507 | is the 'name' field of the video_device struct. The 'index' attribute is | 513 | is the 'name' field of the video_device struct. |
| 508 | a device node index that can be assigned by the driver, or that is calculated | ||
| 509 | for you. | ||
| 510 | |||
| 511 | If you call video_register_device(), then the index is just increased by | ||
| 512 | 1 for each device node you register. The first video device node you register | ||
| 513 | always starts off with 0. | ||
| 514 | 514 | ||
| 515 | Alternatively you can call video_register_device_index() which is identical | 515 | The 'index' attribute is the index of the device node: for each call to |
| 516 | to video_register_device(), but with an extra index argument. Here you can | 516 | video_register_device() the index is just increased by 1. The first video |
| 517 | pass a specific index value (between 0 and 31) that should be used. | 517 | device node you register always starts with index 0. |
| 518 | 518 | ||
| 519 | Users can setup udev rules that utilize the index attribute to make fancy | 519 | Users can setup udev rules that utilize the index attribute to make fancy |
| 520 | device names (e.g. 'mpegX' for MPEG video capture device nodes). | 520 | device names (e.g. 'mpegX' for MPEG video capture device nodes). |
| @@ -523,9 +523,8 @@ After the device was successfully registered, then you can use these fields: | |||
| 523 | 523 | ||
| 524 | - vfl_type: the device type passed to video_register_device. | 524 | - vfl_type: the device type passed to video_register_device. |
| 525 | - minor: the assigned device minor number. | 525 | - minor: the assigned device minor number. |
| 526 | - num: the device kernel number (i.e. the X in videoX). | 526 | - num: the device node number (i.e. the X in videoX). |
| 527 | - index: the device index number (calculated or set explicitly using | 527 | - index: the device index number. |
| 528 | video_register_device_index). | ||
| 529 | 528 | ||
| 530 | If the registration failed, then you need to call video_device_release() | 529 | If the registration failed, then you need to call video_device_release() |
| 531 | to free the allocated video_device struct, or free your own struct if the | 530 | to free the allocated video_device struct, or free your own struct if the |
diff --git a/Documentation/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 | ||
| 92 | int get_brightness_adj(unsigned char *image, long size, int *brightness) { | 92 | static 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 @@ | |||
| 1 | page-types | ||
| 1 | slabinfo | 2 | slabinfo |
diff --git a/Documentation/vm/00-INDEX b/Documentation/vm/00-INDEX index 2f77ced35df7..e57d6a9dd32b 100644 --- a/Documentation/vm/00-INDEX +++ b/Documentation/vm/00-INDEX | |||
| @@ -6,6 +6,8 @@ balance | |||
| 6 | - various information on memory balancing. | 6 | - various information on memory balancing. |
| 7 | hugetlbpage.txt | 7 | hugetlbpage.txt |
| 8 | - a brief summary of hugetlbpage support in the Linux kernel. | 8 | - a brief summary of hugetlbpage support in the Linux kernel. |
| 9 | ksm.txt | ||
| 10 | - how to use the Kernel Samepage Merging feature. | ||
| 9 | locking | 11 | locking |
| 10 | - info on how locking and synchronization is done in the Linux vm code. | 12 | - info on how locking and synchronization is done in the Linux vm code. |
| 11 | numa | 13 | numa |
| @@ -20,3 +22,5 @@ slabinfo.c | |||
| 20 | - source code for a tool to get reports about slabs. | 22 | - source code for a tool to get reports about slabs. |
| 21 | slub.txt | 23 | slub.txt |
| 22 | - a short users guide for SLUB. | 24 | - a short users guide for SLUB. |
| 25 | map_hugetlb.c | ||
| 26 | - an example program that uses the MAP_HUGETLB mmap flag. | ||
diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index ea8714fcc3ad..82a7bd1800b2 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt | |||
| @@ -18,13 +18,13 @@ First the Linux kernel needs to be built with the CONFIG_HUGETLBFS | |||
| 18 | automatically when CONFIG_HUGETLBFS is selected) configuration | 18 | automatically when CONFIG_HUGETLBFS is selected) configuration |
| 19 | options. | 19 | options. |
| 20 | 20 | ||
| 21 | The kernel built with hugepage support should show the number of configured | 21 | The kernel built with huge page support should show the number of configured |
| 22 | hugepages in the system by running the "cat /proc/meminfo" command. | 22 | huge pages in the system by running the "cat /proc/meminfo" command. |
| 23 | 23 | ||
| 24 | /proc/meminfo also provides information about the total number of hugetlb | 24 | /proc/meminfo also provides information about the total number of hugetlb |
| 25 | pages configured in the kernel. It also displays information about the | 25 | pages configured in the kernel. It also displays information about the |
| 26 | number of free hugetlb pages at any time. It also displays information about | 26 | number of free hugetlb pages at any time. It also displays information about |
| 27 | the configured hugepage size - this is needed for generating the proper | 27 | the configured huge page size - this is needed for generating the proper |
| 28 | alignment and size of the arguments to the above system calls. | 28 | alignment and size of the arguments to the above system calls. |
| 29 | 29 | ||
| 30 | The output of "cat /proc/meminfo" will have lines like: | 30 | The output of "cat /proc/meminfo" will have lines like: |
| @@ -37,25 +37,27 @@ HugePages_Surp: yyy | |||
| 37 | Hugepagesize: zzz kB | 37 | Hugepagesize: zzz kB |
| 38 | 38 | ||
| 39 | where: | 39 | where: |
| 40 | HugePages_Total is the size of the pool of hugepages. | 40 | HugePages_Total is the size of the pool of huge pages. |
| 41 | HugePages_Free is the number of hugepages in the pool that are not yet | 41 | HugePages_Free is the number of huge pages in the pool that are not yet |
| 42 | allocated. | 42 | allocated. |
| 43 | HugePages_Rsvd is short for "reserved," and is the number of hugepages | 43 | HugePages_Rsvd is short for "reserved," and is the number of huge pages for |
| 44 | for which a commitment to allocate from the pool has been made, but no | 44 | which a commitment to allocate from the pool has been made, |
| 45 | allocation has yet been made. It's vaguely analogous to overcommit. | 45 | but no allocation has yet been made. Reserved huge pages |
| 46 | HugePages_Surp is short for "surplus," and is the number of hugepages in | 46 | guarantee that an application will be able to allocate a |
| 47 | the pool above the value in /proc/sys/vm/nr_hugepages. The maximum | 47 | huge page from the pool of huge pages at fault time. |
| 48 | number of surplus hugepages is controlled by | 48 | HugePages_Surp is short for "surplus," and is the number of huge pages in |
| 49 | /proc/sys/vm/nr_overcommit_hugepages. | 49 | the pool above the value in /proc/sys/vm/nr_hugepages. The |
| 50 | maximum number of surplus huge pages is controlled by | ||
| 51 | /proc/sys/vm/nr_overcommit_hugepages. | ||
| 50 | 52 | ||
| 51 | /proc/filesystems should also show a filesystem of type "hugetlbfs" configured | 53 | /proc/filesystems should also show a filesystem of type "hugetlbfs" configured |
| 52 | in the kernel. | 54 | in the kernel. |
| 53 | 55 | ||
| 54 | /proc/sys/vm/nr_hugepages indicates the current number of configured hugetlb | 56 | /proc/sys/vm/nr_hugepages indicates the current number of configured hugetlb |
| 55 | pages in the kernel. Super user can dynamically request more (or free some | 57 | pages in the kernel. Super user can dynamically request more (or free some |
| 56 | pre-configured) hugepages. | 58 | pre-configured) huge pages. |
| 57 | The allocation (or deallocation) of hugetlb pages is possible only if there are | 59 | The allocation (or deallocation) of hugetlb pages is possible only if there are |
| 58 | enough physically contiguous free pages in system (freeing of hugepages is | 60 | enough physically contiguous free pages in system (freeing of huge pages is |
| 59 | possible only if there are enough hugetlb pages free that can be transferred | 61 | possible only if there are enough hugetlb pages free that can be transferred |
| 60 | back to regular memory pool). | 62 | back to regular memory pool). |
| 61 | 63 | ||
| @@ -67,43 +69,82 @@ use either the mmap system call or shared memory system calls to start using | |||
| 67 | the huge pages. It is required that the system administrator preallocate | 69 | the huge pages. It is required that the system administrator preallocate |
| 68 | enough memory for huge page purposes. | 70 | enough memory for huge page purposes. |
| 69 | 71 | ||
| 70 | Use the following command to dynamically allocate/deallocate hugepages: | 72 | The administrator can preallocate huge pages on the kernel boot command line by |
| 73 | specifying the "hugepages=N" parameter, where 'N' = the number of huge pages | ||
| 74 | requested. This is the most reliable method for preallocating huge pages as | ||
| 75 | memory has not yet become fragmented. | ||
| 76 | |||
| 77 | Some platforms support multiple huge page sizes. To preallocate huge pages | ||
| 78 | of a specific size, one must preceed the huge pages boot command parameters | ||
| 79 | with a huge page size selection parameter "hugepagesz=<size>". <size> must | ||
| 80 | be specified in bytes with optional scale suffix [kKmMgG]. The default huge | ||
| 81 | page size may be selected with the "default_hugepagesz=<size>" boot parameter. | ||
| 82 | |||
| 83 | /proc/sys/vm/nr_hugepages indicates the current number of configured [default | ||
| 84 | size] hugetlb pages in the kernel. Super user can dynamically request more | ||
| 85 | (or free some pre-configured) huge pages. | ||
| 86 | |||
| 87 | Use the following command to dynamically allocate/deallocate default sized | ||
| 88 | huge pages: | ||
| 71 | 89 | ||
| 72 | echo 20 > /proc/sys/vm/nr_hugepages | 90 | echo 20 > /proc/sys/vm/nr_hugepages |
| 73 | 91 | ||
| 74 | This command will try to configure 20 hugepages in the system. The success | 92 | This command will try to configure 20 default sized huge pages in the system. |
| 75 | or failure of allocation depends on the amount of physically contiguous | 93 | On a NUMA platform, the kernel will attempt to distribute the huge page pool |
| 76 | memory that is preset in system at this time. System administrators may want | 94 | over the all on-line nodes. These huge pages, allocated when nr_hugepages |
| 77 | to put this command in one of the local rc init files. This will enable the | 95 | is increased, are called "persistent huge pages". |
| 78 | kernel to request huge pages early in the boot process (when the possibility | 96 | |
| 79 | of getting physical contiguous pages is still very high). In either | 97 | The success or failure of huge page allocation depends on the amount of |
| 80 | case, administrators will want to verify the number of hugepages actually | 98 | physically contiguous memory that is preset in system at the time of the |
| 81 | allocated by checking the sysctl or meminfo. | 99 | allocation attempt. If the kernel is unable to allocate huge pages from |
| 82 | 100 | some nodes in a NUMA system, it will attempt to make up the difference by | |
| 83 | /proc/sys/vm/nr_overcommit_hugepages indicates how large the pool of | 101 | allocating extra pages on other nodes with sufficient available contiguous |
| 84 | hugepages can grow, if more hugepages than /proc/sys/vm/nr_hugepages are | 102 | memory, if any. |
| 85 | requested by applications. echo'ing any non-zero value into this file | 103 | |
| 86 | indicates that the hugetlb subsystem is allowed to try to obtain | 104 | System administrators may want to put this command in one of the local rc init |
| 87 | hugepages from the buddy allocator, if the normal pool is exhausted. As | 105 | files. This will enable the kernel to request huge pages early in the boot |
| 88 | these surplus hugepages go out of use, they are freed back to the buddy | 106 | process when the possibility of getting physical contiguous pages is still |
| 107 | very high. Administrators can verify the number of huge pages actually | ||
| 108 | allocated by checking the sysctl or meminfo. To check the per node | ||
| 109 | distribution of huge pages in a NUMA system, use: | ||
| 110 | |||
| 111 | cat /sys/devices/system/node/node*/meminfo | fgrep Huge | ||
| 112 | |||
| 113 | /proc/sys/vm/nr_overcommit_hugepages specifies how large the pool of | ||
| 114 | huge pages can grow, if more huge pages than /proc/sys/vm/nr_hugepages are | ||
| 115 | requested by applications. Writing any non-zero value into this file | ||
| 116 | indicates that the hugetlb subsystem is allowed to try to obtain "surplus" | ||
| 117 | huge pages from the buddy allocator, when the normal pool is exhausted. As | ||
| 118 | these surplus huge pages go out of use, they are freed back to the buddy | ||
| 89 | allocator. | 119 | allocator. |
| 90 | 120 | ||
| 121 | When increasing the huge page pool size via nr_hugepages, any surplus | ||
| 122 | pages will first be promoted to persistent huge pages. Then, additional | ||
| 123 | huge pages will be allocated, if necessary and if possible, to fulfill | ||
| 124 | the new huge page pool size. | ||
| 125 | |||
| 126 | The administrator may shrink the pool of preallocated huge pages for | ||
| 127 | the default huge page size by setting the nr_hugepages sysctl to a | ||
| 128 | smaller value. The kernel will attempt to balance the freeing of huge pages | ||
| 129 | across all on-line nodes. Any free huge pages on the selected nodes will | ||
| 130 | be freed back to the buddy allocator. | ||
| 131 | |||
| 91 | Caveat: Shrinking the pool via nr_hugepages such that it becomes less | 132 | Caveat: Shrinking the pool via nr_hugepages such that it becomes less |
| 92 | than the number of hugepages in use will convert the balance to surplus | 133 | than the number of huge pages in use will convert the balance to surplus |
| 93 | huge pages even if it would exceed the overcommit value. As long as | 134 | huge pages even if it would exceed the overcommit value. As long as |
| 94 | this condition holds, however, no more surplus huge pages will be | 135 | this condition holds, however, no more surplus huge pages will be |
| 95 | allowed on the system until one of the two sysctls are increased | 136 | allowed on the system until one of the two sysctls are increased |
| 96 | sufficiently, or the surplus huge pages go out of use and are freed. | 137 | sufficiently, or the surplus huge pages go out of use and are freed. |
| 97 | 138 | ||
| 98 | With support for multiple hugepage pools at run-time available, much of | 139 | With support for multiple huge page pools at run-time available, much of |
| 99 | the hugepage userspace interface has been duplicated in sysfs. The above | 140 | the huge page userspace interface has been duplicated in sysfs. The above |
| 100 | information applies to the default hugepage size (which will be | 141 | information applies to the default huge page size which will be |
| 101 | controlled by the proc interfaces for backwards compatibility). The root | 142 | controlled by the /proc interfaces for backwards compatibility. The root |
| 102 | hugepage control directory is | 143 | huge page control directory in sysfs is: |
| 103 | 144 | ||
| 104 | /sys/kernel/mm/hugepages | 145 | /sys/kernel/mm/hugepages |
| 105 | 146 | ||
| 106 | For each hugepage size supported by the running kernel, a subdirectory | 147 | For each huge page size supported by the running kernel, a subdirectory |
| 107 | will exist, of the form | 148 | will exist, of the form |
| 108 | 149 | ||
| 109 | hugepages-${size}kB | 150 | hugepages-${size}kB |
| @@ -116,9 +157,9 @@ Inside each of these directories, the same set of files will exist: | |||
| 116 | resv_hugepages | 157 | resv_hugepages |
| 117 | surplus_hugepages | 158 | surplus_hugepages |
| 118 | 159 | ||
| 119 | which function as described above for the default hugepage-sized case. | 160 | which function as described above for the default huge page-sized case. |
| 120 | 161 | ||
| 121 | If the user applications are going to request hugepages using mmap system | 162 | If the user applications are going to request huge pages using mmap system |
| 122 | call, then it is required that system administrator mount a file system of | 163 | call, then it is required that system administrator mount a file system of |
| 123 | type hugetlbfs: | 164 | type hugetlbfs: |
| 124 | 165 | ||
| @@ -127,7 +168,7 @@ type hugetlbfs: | |||
| 127 | none /mnt/huge | 168 | none /mnt/huge |
| 128 | 169 | ||
| 129 | This command mounts a (pseudo) filesystem of type hugetlbfs on the directory | 170 | This command mounts a (pseudo) filesystem of type hugetlbfs on the directory |
| 130 | /mnt/huge. Any files created on /mnt/huge uses hugepages. The uid and gid | 171 | /mnt/huge. Any files created on /mnt/huge uses huge pages. The uid and gid |
| 131 | options sets the owner and group of the root of the file system. By default | 172 | options sets the owner and group of the root of the file system. By default |
| 132 | the uid and gid of the current process are taken. The mode option sets the | 173 | the uid and gid of the current process are taken. The mode option sets the |
| 133 | mode of root of file system to value & 0777. This value is given in octal. | 174 | mode of root of file system to value & 0777. This value is given in octal. |
| @@ -146,24 +187,26 @@ Regular chown, chgrp, and chmod commands (with right permissions) could be | |||
| 146 | used to change the file attributes on hugetlbfs. | 187 | used to change the file attributes on hugetlbfs. |
| 147 | 188 | ||
| 148 | Also, it is important to note that no such mount command is required if the | 189 | Also, it is important to note that no such mount command is required if the |
| 149 | applications are going to use only shmat/shmget system calls. Users who | 190 | applications are going to use only shmat/shmget system calls or mmap with |
| 150 | wish to use hugetlb page via shared memory segment should be a member of | 191 | MAP_HUGETLB. Users who wish to use hugetlb page via shared memory segment |
| 151 | a supplementary group and system admin needs to configure that gid into | 192 | should be a member of a supplementary group and system admin needs to |
| 152 | /proc/sys/vm/hugetlb_shm_group. It is possible for same or different | 193 | configure that gid into /proc/sys/vm/hugetlb_shm_group. It is possible for |
| 153 | applications to use any combination of mmaps and shm* calls, though the | 194 | same or different applications to use any combination of mmaps and shm* |
| 154 | mount of filesystem will be required for using mmap calls. | 195 | calls, though the mount of filesystem will be required for using mmap calls |
| 196 | without MAP_HUGETLB. For an example of how to use mmap with MAP_HUGETLB see | ||
| 197 | map_hugetlb.c. | ||
| 155 | 198 | ||
| 156 | ******************************************************************* | 199 | ******************************************************************* |
| 157 | 200 | ||
| 158 | /* | 201 | /* |
| 159 | * Example of using hugepage memory in a user application using Sys V shared | 202 | * Example of using huge page memory in a user application using Sys V shared |
| 160 | * memory system calls. In this example the app is requesting 256MB of | 203 | * memory system calls. In this example the app is requesting 256MB of |
| 161 | * memory that is backed by huge pages. The application uses the flag | 204 | * memory that is backed by huge pages. The application uses the flag |
| 162 | * SHM_HUGETLB in the shmget system call to inform the kernel that it is | 205 | * SHM_HUGETLB in the shmget system call to inform the kernel that it is |
| 163 | * requesting hugepages. | 206 | * requesting huge pages. |
| 164 | * | 207 | * |
| 165 | * For the ia64 architecture, the Linux kernel reserves Region number 4 for | 208 | * For the ia64 architecture, the Linux kernel reserves Region number 4 for |
| 166 | * hugepages. That means the addresses starting with 0x800000... will need | 209 | * huge pages. That means the addresses starting with 0x800000... will need |
| 167 | * to be specified. Specifying a fixed address is not required on ppc64, | 210 | * to be specified. Specifying a fixed address is not required on ppc64, |
| 168 | * i386 or x86_64. | 211 | * i386 or x86_64. |
| 169 | * | 212 | * |
| @@ -252,14 +295,14 @@ int main(void) | |||
| 252 | ******************************************************************* | 295 | ******************************************************************* |
| 253 | 296 | ||
| 254 | /* | 297 | /* |
| 255 | * Example of using hugepage memory in a user application using the mmap | 298 | * Example of using huge page memory in a user application using the mmap |
| 256 | * system call. Before running this application, make sure that the | 299 | * system call. Before running this application, make sure that the |
| 257 | * administrator has mounted the hugetlbfs filesystem (on some directory | 300 | * administrator has mounted the hugetlbfs filesystem (on some directory |
| 258 | * like /mnt) using the command mount -t hugetlbfs nodev /mnt. In this | 301 | * like /mnt) using the command mount -t hugetlbfs nodev /mnt. In this |
| 259 | * example, the app is requesting memory of size 256MB that is backed by | 302 | * example, the app is requesting memory of size 256MB that is backed by |
| 260 | * huge pages. | 303 | * huge pages. |
| 261 | * | 304 | * |
| 262 | * For ia64 architecture, Linux kernel reserves Region number 4 for hugepages. | 305 | * For ia64 architecture, Linux kernel reserves Region number 4 for huge pages. |
| 263 | * That means the addresses starting with 0x800000... will need to be | 306 | * That means the addresses starting with 0x800000... will need to be |
| 264 | * specified. Specifying a fixed address is not required on ppc64, i386 | 307 | * specified. Specifying a fixed address is not required on ppc64, i386 |
| 265 | * or x86_64. | 308 | * or x86_64. |
diff --git a/Documentation/vm/ksm.txt b/Documentation/vm/ksm.txt new file mode 100644 index 000000000000..72a22f65960e --- /dev/null +++ b/Documentation/vm/ksm.txt | |||
| @@ -0,0 +1,89 @@ | |||
| 1 | How to use the Kernel Samepage Merging feature | ||
| 2 | ---------------------------------------------- | ||
| 3 | |||
| 4 | KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, | ||
| 5 | added to the Linux kernel in 2.6.32. See mm/ksm.c for its implementation, | ||
| 6 | and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/ | ||
| 7 | |||
| 8 | The KSM daemon ksmd periodically scans those areas of user memory which | ||
| 9 | have been registered with it, looking for pages of identical content which | ||
| 10 | can be replaced by a single write-protected page (which is automatically | ||
| 11 | copied if a process later wants to update its content). | ||
| 12 | |||
| 13 | KSM was originally developed for use with KVM (where it was known as | ||
| 14 | Kernel Shared Memory), to fit more virtual machines into physical memory, | ||
| 15 | by sharing the data common between them. But it can be useful to any | ||
| 16 | application which generates many instances of the same data. | ||
| 17 | |||
| 18 | KSM only merges anonymous (private) pages, never pagecache (file) pages. | ||
| 19 | KSM's merged pages are at present locked into kernel memory for as long | ||
| 20 | as they are shared: so cannot be swapped out like the user pages they | ||
| 21 | replace (but swapping KSM pages should follow soon in a later release). | ||
| 22 | |||
| 23 | KSM only operates on those areas of address space which an application | ||
| 24 | has advised to be likely candidates for merging, by using the madvise(2) | ||
| 25 | system call: int madvise(addr, length, MADV_MERGEABLE). | ||
| 26 | |||
| 27 | The app may call int madvise(addr, length, MADV_UNMERGEABLE) to cancel | ||
| 28 | that advice and restore unshared pages: whereupon KSM unmerges whatever | ||
| 29 | it merged in that range. Note: this unmerging call may suddenly require | ||
| 30 | more memory than is available - possibly failing with EAGAIN, but more | ||
| 31 | probably arousing the Out-Of-Memory killer. | ||
| 32 | |||
| 33 | If KSM is not configured into the running kernel, madvise MADV_MERGEABLE | ||
| 34 | and MADV_UNMERGEABLE simply fail with EINVAL. If the running kernel was | ||
| 35 | built with CONFIG_KSM=y, those calls will normally succeed: even if the | ||
| 36 | the KSM daemon is not currently running, MADV_MERGEABLE still registers | ||
| 37 | the range for whenever the KSM daemon is started; even if the range | ||
| 38 | cannot contain any pages which KSM could actually merge; even if | ||
| 39 | MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE. | ||
| 40 | |||
| 41 | Like other madvise calls, they are intended for use on mapped areas of | ||
| 42 | the user address space: they will report ENOMEM if the specified range | ||
| 43 | includes unmapped gaps (though working on the intervening mapped areas), | ||
| 44 | and might fail with EAGAIN if not enough memory for internal structures. | ||
| 45 | |||
| 46 | Applications should be considerate in their use of MADV_MERGEABLE, | ||
| 47 | restricting its use to areas likely to benefit. KSM's scans may use | ||
| 48 | a lot of processing power, and its kernel-resident pages are a limited | ||
| 49 | resource. Some installations will disable KSM for these reasons. | ||
| 50 | |||
| 51 | The KSM daemon is controlled by sysfs files in /sys/kernel/mm/ksm/, | ||
| 52 | readable by all but writable only by root: | ||
| 53 | |||
| 54 | max_kernel_pages - set to maximum number of kernel pages that KSM may use | ||
| 55 | e.g. "echo 2000 > /sys/kernel/mm/ksm/max_kernel_pages" | ||
| 56 | Value 0 imposes no limit on the kernel pages KSM may use; | ||
| 57 | but note that any process using MADV_MERGEABLE can cause | ||
| 58 | KSM to allocate these pages, unswappable until it exits. | ||
| 59 | Default: 2000 (chosen for demonstration purposes) | ||
| 60 | |||
| 61 | pages_to_scan - how many present pages to scan before ksmd goes to sleep | ||
| 62 | e.g. "echo 200 > /sys/kernel/mm/ksm/pages_to_scan" | ||
| 63 | Default: 200 (chosen for demonstration purposes) | ||
| 64 | |||
| 65 | sleep_millisecs - how many milliseconds ksmd should sleep before next scan | ||
| 66 | e.g. "echo 20 > /sys/kernel/mm/ksm/sleep_millisecs" | ||
| 67 | Default: 20 (chosen for demonstration purposes) | ||
| 68 | |||
| 69 | run - set 0 to stop ksmd from running but keep merged pages, | ||
| 70 | set 1 to run ksmd e.g. "echo 1 > /sys/kernel/mm/ksm/run", | ||
| 71 | set 2 to stop ksmd and unmerge all pages currently merged, | ||
| 72 | but leave mergeable areas registered for next run | ||
| 73 | Default: 1 (for immediate use by apps which register) | ||
| 74 | |||
| 75 | The effectiveness of KSM and MADV_MERGEABLE is shown in /sys/kernel/mm/ksm/: | ||
| 76 | |||
| 77 | pages_shared - how many shared unswappable kernel pages KSM is using | ||
| 78 | pages_sharing - how many more sites are sharing them i.e. how much saved | ||
| 79 | pages_unshared - how many pages unique but repeatedly checked for merging | ||
| 80 | pages_volatile - how many pages changing too fast to be placed in a tree | ||
| 81 | full_scans - how many times all mergeable areas have been scanned | ||
| 82 | |||
| 83 | A high ratio of pages_sharing to pages_shared indicates good sharing, but | ||
| 84 | a high ratio of pages_unshared to pages_sharing indicates wasted effort. | ||
| 85 | pages_volatile embraces several different kinds of activity, but a high | ||
| 86 | proportion there would also indicate poor use of madvise MADV_MERGEABLE. | ||
| 87 | |||
| 88 | Izik Eidus, | ||
| 89 | Hugh Dickins, 30 July 2009 | ||
diff --git a/Documentation/vm/map_hugetlb.c b/Documentation/vm/map_hugetlb.c new file mode 100644 index 000000000000..e2bdae37f499 --- /dev/null +++ b/Documentation/vm/map_hugetlb.c | |||
| @@ -0,0 +1,77 @@ | |||
| 1 | /* | ||
| 2 | * Example of using hugepage memory in a user application using the mmap | ||
| 3 | * system call with MAP_HUGETLB flag. Before running this program make | ||
| 4 | * sure the administrator has allocated enough default sized huge pages | ||
| 5 | * to cover the 256 MB allocation. | ||
| 6 | * | ||
| 7 | * For ia64 architecture, Linux kernel reserves Region number 4 for hugepages. | ||
| 8 | * That means the addresses starting with 0x800000... will need to be | ||
| 9 | * specified. Specifying a fixed address is not required on ppc64, i386 | ||
| 10 | * or x86_64. | ||
| 11 | */ | ||
| 12 | #include <stdlib.h> | ||
| 13 | #include <stdio.h> | ||
| 14 | #include <unistd.h> | ||
| 15 | #include <sys/mman.h> | ||
| 16 | #include <fcntl.h> | ||
| 17 | |||
| 18 | #define LENGTH (256UL*1024*1024) | ||
| 19 | #define PROTECTION (PROT_READ | PROT_WRITE) | ||
| 20 | |||
| 21 | #ifndef MAP_HUGETLB | ||
| 22 | #define MAP_HUGETLB 0x40 | ||
| 23 | #endif | ||
| 24 | |||
| 25 | /* Only ia64 requires this */ | ||
| 26 | #ifdef __ia64__ | ||
| 27 | #define ADDR (void *)(0x8000000000000000UL) | ||
| 28 | #define FLAGS (MAP_PRIVATE | MAP_ANONYMOUS | MAP_HUGETLB | MAP_FIXED) | ||
| 29 | #else | ||
| 30 | #define ADDR (void *)(0x0UL) | ||
| 31 | #define FLAGS (MAP_PRIVATE | MAP_ANONYMOUS | MAP_HUGETLB) | ||
| 32 | #endif | ||
| 33 | |||
| 34 | void check_bytes(char *addr) | ||
| 35 | { | ||
| 36 | printf("First hex is %x\n", *((unsigned int *)addr)); | ||
| 37 | } | ||
| 38 | |||
| 39 | void write_bytes(char *addr) | ||
| 40 | { | ||
| 41 | unsigned long i; | ||
| 42 | |||
| 43 | for (i = 0; i < LENGTH; i++) | ||
| 44 | *(addr + i) = (char)i; | ||
| 45 | } | ||
| 46 | |||
| 47 | void read_bytes(char *addr) | ||
| 48 | { | ||
| 49 | unsigned long i; | ||
| 50 | |||
| 51 | check_bytes(addr); | ||
| 52 | for (i = 0; i < LENGTH; i++) | ||
| 53 | if (*(addr + i) != (char)i) { | ||
| 54 | printf("Mismatch at %lu\n", i); | ||
| 55 | break; | ||
| 56 | } | ||
| 57 | } | ||
| 58 | |||
| 59 | int main(void) | ||
| 60 | { | ||
| 61 | void *addr; | ||
| 62 | |||
| 63 | addr = mmap(ADDR, LENGTH, PROTECTION, FLAGS, 0, 0); | ||
| 64 | if (addr == MAP_FAILED) { | ||
| 65 | perror("mmap"); | ||
| 66 | exit(1); | ||
| 67 | } | ||
| 68 | |||
| 69 | printf("Returned address is %p\n", addr); | ||
| 70 | check_bytes(addr); | ||
| 71 | write_bytes(addr); | ||
| 72 | read_bytes(addr); | ||
| 73 | |||
| 74 | munmap(addr, LENGTH); | ||
| 75 | |||
| 76 | return 0; | ||
| 77 | } | ||
diff --git a/Documentation/vm/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; | |||
| 126 | static unsigned long opt_offset[MAX_ADDR_RANGES]; | 148 | static unsigned long opt_offset[MAX_ADDR_RANGES]; |
| 127 | static unsigned long opt_size[MAX_ADDR_RANGES]; | 149 | static unsigned long opt_size[MAX_ADDR_RANGES]; |
| 128 | 150 | ||
| 151 | #define MAX_VMAS 10240 | ||
| 152 | static int nr_vmas; | ||
| 153 | static unsigned long pg_start[MAX_VMAS]; | ||
| 154 | static unsigned long pg_end[MAX_VMAS]; | ||
| 155 | static unsigned long voffset; | ||
| 156 | |||
| 157 | static int pagemap_fd; | ||
| 158 | |||
| 129 | #define MAX_BIT_FILTERS 64 | 159 | #define MAX_BIT_FILTERS 64 |
| 130 | static int nr_bit_filters; | 160 | static int nr_bit_filters; |
| 131 | static uint64_t opt_mask[MAX_BIT_FILTERS]; | 161 | static 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 */ |
| 137 | static int kpageflags_fd; | 167 | static int kpageflags_fd; |
| 138 | static 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 | ||
| 161 | unsigned 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 | |||
| 195 | static unsigned long pages2mb(unsigned long pages) | ||
| 162 | { | 196 | { |
| 163 | return (pages * page_size) >> 20; | 197 | return (pages * page_size) >> 20; |
| 164 | } | 198 | } |
| 165 | 199 | ||
| 166 | void fatal(const char *x, ...) | 200 | static 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 | ||
| 181 | char *page_flag_name(uint64_t flags) | 215 | static 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 | ||
| 200 | char *page_flag_longname(uint64_t flags) | 234 | static 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 | ||
| 224 | void show_page_range(unsigned long offset, uint64_t flags) | 258 | static 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 | ||
| 244 | void show_page(unsigned long offset, uint64_t flags) | 284 | static 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 | ||
| 249 | void show_summary(void) | 291 | static 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 | ||
| 275 | int bit_mask_ok(uint64_t flags) | 317 | static 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 | ||
| 292 | uint64_t expand_overloaded_flags(uint64_t flags) | 334 | static 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 | ||
| 311 | uint64_t well_known_flags(uint64_t flags) | 353 | static 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 | ||
| 328 | int hash_slot(uint64_t flags) | 370 | static 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 | ||
| 355 | void add_page(unsigned long offset, uint64_t flags) | 397 | static 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 | ||
| 374 | void walk_pfn(unsigned long index, unsigned long count) | 416 | static 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 | ||
| 407 | void walk_addr_ranges(void) | 451 | |
| 452 | #define PAGEMAP_BATCH 4096 | ||
| 453 | static 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 | |||
| 491 | static 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 | |||
| 516 | static 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 | |||
| 526 | static 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 | ||
| 431 | const char *page_flag_type(uint64_t flag) | 553 | static 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 | ||
| 440 | void usage(void) | 562 | static 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 | ||
| 485 | unsigned long long parse_number(const char *str) | 607 | static 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 | ||
| 497 | void parse_pid(const char *str) | 619 | static 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 | ||
| 502 | void 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 | ||
| 506 | void add_addr_range(unsigned long offset, unsigned long size) | 670 | static 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 | ||
| 516 | void parse_addr_range(const char *optarg) | 674 | static 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 | ||
| 550 | void add_bits_filter(uint64_t mask, uint64_t bits) | 708 | static 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 | ||
| 560 | uint64_t parse_flag_name(const char *str, int len) | 718 | static 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 | ||
| 580 | uint64_t parse_flag_names(const char *str, int all) | 738 | static 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 | ||
| 599 | void parse_bits_mask(const char *optarg) | 757 | static 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 | ||
| 624 | struct option opts[] = { | 782 | static 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 | ||
| 88 | regex_t pattern; | 88 | regex_t pattern; |
| 89 | 89 | ||
| 90 | void fatal(const char *x, ...) | 90 | static 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 | ||
| 100 | void usage(void) | 100 | static 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 | ||
| 134 | unsigned long read_obj(const char *name) | 134 | static 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 | */ |
| 154 | unsigned long get_obj(const char *name) | 154 | static 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 | ||
| 162 | unsigned long get_obj_and_str(const char *name, char **x) | 162 | static 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 | ||
| 181 | void set_obj(struct slabinfo *s, const char *name, int n) | 181 | static 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 | ||
| 195 | unsigned long read_slab_obj(struct slabinfo *s, const char *name) | 195 | static 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 | */ |
| 218 | int store_size(char *buffer, unsigned long value) | 218 | static 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 | ||
| 250 | void decode_numa_list(int *numa, char *t) | 250 | static 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 | ||
| 275 | void slab_validate(struct slabinfo *s) | 275 | static 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 | ||
| 283 | void slab_shrink(struct slabinfo *s) | 283 | static 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 | ||
| 291 | int line = 0; | 291 | int line = 0; |
| 292 | 292 | ||
| 293 | void first_line(void) | 293 | static 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 | */ |
| 305 | struct aliasinfo *find_one_alias(struct slabinfo *find) | 305 | static 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 | ||
| 321 | unsigned long slab_size(struct slabinfo *s) | 321 | static 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 | ||
| 326 | unsigned long slab_activity(struct slabinfo *s) | 326 | static 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 | ||
| 332 | void slab_numa(struct slabinfo *s, int mode) | 332 | static 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 | ||
| 377 | void show_tracking(struct slabinfo *s) | 377 | static 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 | ||
| 395 | void ops(struct slabinfo *s) | 395 | static 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 | ||
| 408 | const char *onoff(int x) | 408 | static 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 | ||
| 415 | void slab_stats(struct slabinfo *s) | 415 | static 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 | ||
| 480 | void report(struct slabinfo *s) | 480 | static 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 | ||
| 521 | void slabcache(struct slabinfo *s) | 521 | static 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 | */ |
| 596 | int debug_opt_scan(char *opt) | 596 | static 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 | ||
| 645 | int slab_empty(struct slabinfo *s) | 645 | static 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 | ||
| 660 | void slab_debug(struct slabinfo *s) | 660 | static 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 | ||
| 720 | void totals(void) | 720 | static 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 | ||
| 979 | void sort_slabs(void) | 979 | static 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 | ||
| 1008 | void sort_aliases(void) | 1008 | static 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 | ||
| 1033 | void link_slabs(void) | 1033 | static 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 | ||
| 1051 | void alias(void) | 1051 | static 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 | ||
| 1082 | void rename_slabs(void) | 1082 | static 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 | ||
| 1105 | int slab_mismatch(char *slab) | 1105 | static 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 | ||
| 1110 | void read_slab_dir(void) | 1110 | static 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 | ||
| 1212 | void output_slabs(void) | 1212 | static 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 | */ |
| 21 | void keep_alive(void) | 21 | static 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 | ||
| 603 | Field name: hardware_subarch_data | 604 | Field name: hardware_subarch_data |
| 604 | Type: write (subarch-dependent) | 605 | Type: write (subarch-dependent) |
diff --git a/Documentation/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 | ||
| 10 | 1. There are three specific hardware requirements: | 10 | 1. 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 | ||
| 47 | 2. Software requirements: | 75 | 2. 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 |
