aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorDavid S. Miller <davem@davemloft.net>2010-02-28 22:23:06 -0500
committerDavid S. Miller <davem@davemloft.net>2010-02-28 22:23:06 -0500
commit47871889c601d8199c51a4086f77eebd77c29b0b (patch)
tree40cdcac3bff0ee40cc33dcca61d0577cdf965f77 /Documentation/DocBook
parentc16cc0b464b8876cfd57ce1c1dbcb6f9a6a0bce3 (diff)
parent30ff056c42c665b9ea535d8515890857ae382540 (diff)
Merge branch 'master' of /home/davem/src/GIT/linux-2.6/
Conflicts: drivers/firmware/iscsi_ibft.c
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/v4l/io.xml3
-rw-r--r--Documentation/DocBook/v4l/vidioc-qbuf.xml40
-rw-r--r--Documentation/DocBook/v4l/vidioc-querybuf.xml7
-rw-r--r--Documentation/DocBook/v4l/vidioc-reqbufs.xml36
4 files changed, 42 insertions, 44 deletions
diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml
index f92f24323b2..e870330cbf7 100644
--- a/Documentation/DocBook/v4l/io.xml
+++ b/Documentation/DocBook/v4l/io.xml
@@ -589,7 +589,8 @@ number of a video input as in &v4l2-input; field
589 <entry></entry> 589 <entry></entry>
590 <entry>A place holder for future extensions and custom 590 <entry>A place holder for future extensions and custom
591(driver defined) buffer types 591(driver defined) buffer types
592<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry> 592<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications
593should set this to 0.</entry>
593 </row> 594 </row>
594 </tbody> 595 </tbody>
595 </tgroup> 596 </tgroup>
diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml
index 18708177815..b843bd7b389 100644
--- a/Documentation/DocBook/v4l/vidioc-qbuf.xml
+++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml
@@ -54,12 +54,10 @@ to enqueue an empty (capturing) or filled (output) buffer in the
54driver's incoming queue. The semantics depend on the selected I/O 54driver's incoming queue. The semantics depend on the selected I/O
55method.</para> 55method.</para>
56 56
57 <para>To enqueue a <link linkend="mmap">memory mapped</link> 57 <para>To enqueue a buffer applications set the <structfield>type</structfield>
58buffer applications set the <structfield>type</structfield> field of a 58field of a &v4l2-buffer; to the same buffer type as was previously used
59&v4l2-buffer; to the same buffer type as previously &v4l2-format; 59with &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers;
60<structfield>type</structfield> and &v4l2-requestbuffers; 60<structfield>type</structfield>. Applications must also set the
61<structfield>type</structfield>, the <structfield>memory</structfield>
62field to <constant>V4L2_MEMORY_MMAP</constant> and the
63<structfield>index</structfield> field. Valid index numbers range from 61<structfield>index</structfield> field. Valid index numbers range from
64zero to the number of buffers allocated with &VIDIOC-REQBUFS; 62zero to the number of buffers allocated with &VIDIOC-REQBUFS;
65(&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The 63(&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The
@@ -70,8 +68,19 @@ intended for output (<structfield>type</structfield> is
70<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also 68<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
71initialize the <structfield>bytesused</structfield>, 69initialize the <structfield>bytesused</structfield>,
72<structfield>field</structfield> and 70<structfield>field</structfield> and
73<structfield>timestamp</structfield> fields. See <xref 71<structfield>timestamp</structfield> fields, see <xref
74 linkend="buffer" /> for details. When 72linkend="buffer" /> for details.
73Applications must also set <structfield>flags</structfield> to 0. If a driver
74supports capturing from specific video inputs and you want to specify a video
75input, then <structfield>flags</structfield> should be set to
76<constant>V4L2_BUF_FLAG_INPUT</constant> and the field
77<structfield>input</structfield> must be initialized to the desired input.
78The <structfield>reserved</structfield> field must be set to 0.
79</para>
80
81 <para>To enqueue a <link linkend="mmap">memory mapped</link>
82buffer applications set the <structfield>memory</structfield>
83field to <constant>V4L2_MEMORY_MMAP</constant>. When
75<constant>VIDIOC_QBUF</constant> is called with a pointer to this 84<constant>VIDIOC_QBUF</constant> is called with a pointer to this
76structure the driver sets the 85structure the driver sets the
77<constant>V4L2_BUF_FLAG_MAPPED</constant> and 86<constant>V4L2_BUF_FLAG_MAPPED</constant> and
@@ -81,14 +90,10 @@ structure the driver sets the
81&EINVAL;.</para> 90&EINVAL;.</para>
82 91
83 <para>To enqueue a <link linkend="userp">user pointer</link> 92 <para>To enqueue a <link linkend="userp">user pointer</link>
84buffer applications set the <structfield>type</structfield> field of a 93buffer applications set the <structfield>memory</structfield>
85&v4l2-buffer; to the same buffer type as previously &v4l2-format; 94field to <constant>V4L2_MEMORY_USERPTR</constant>, the
86<structfield>type</structfield> and &v4l2-requestbuffers;
87<structfield>type</structfield>, the <structfield>memory</structfield>
88field to <constant>V4L2_MEMORY_USERPTR</constant> and the
89<structfield>m.userptr</structfield> field to the address of the 95<structfield>m.userptr</structfield> field to the address of the
90buffer and <structfield>length</structfield> to its size. When the 96buffer and <structfield>length</structfield> to its size.
91buffer is intended for output additional fields must be set as above.
92When <constant>VIDIOC_QBUF</constant> is called with a pointer to this 97When <constant>VIDIOC_QBUF</constant> is called with a pointer to this
93structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> 98structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant>
94flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and 99flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and
@@ -96,13 +101,14 @@ flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and
96<structfield>flags</structfield> field, or it returns an error code. 101<structfield>flags</structfield> field, or it returns an error code.
97This ioctl locks the memory pages of the buffer in physical memory, 102This ioctl locks the memory pages of the buffer in physical memory,
98they cannot be swapped out to disk. Buffers remain locked until 103they cannot be swapped out to disk. Buffers remain locked until
99dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl are 104dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is
100called, or until the device is closed.</para> 105called, or until the device is closed.</para>
101 106
102 <para>Applications call the <constant>VIDIOC_DQBUF</constant> 107 <para>Applications call the <constant>VIDIOC_DQBUF</constant>
103ioctl to dequeue a filled (capturing) or displayed (output) buffer 108ioctl to dequeue a filled (capturing) or displayed (output) buffer
104from the driver's outgoing queue. They just set the 109from the driver's outgoing queue. They just set the
105<structfield>type</structfield> and <structfield>memory</structfield> 110<structfield>type</structfield>, <structfield>memory</structfield>
111and <structfield>reserved</structfield>
106fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant> 112fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
107is called with a pointer to this structure the driver fills the 113is called with a pointer to this structure the driver fills the
108remaining fields or returns an error code.</para> 114remaining fields or returns an error code.</para>
diff --git a/Documentation/DocBook/v4l/vidioc-querybuf.xml b/Documentation/DocBook/v4l/vidioc-querybuf.xml
index d834993e619..e649805a490 100644
--- a/Documentation/DocBook/v4l/vidioc-querybuf.xml
+++ b/Documentation/DocBook/v4l/vidioc-querybuf.xml
@@ -54,12 +54,13 @@ buffer at any time after buffers have been allocated with the
54&VIDIOC-REQBUFS; ioctl.</para> 54&VIDIOC-REQBUFS; ioctl.</para>
55 55
56 <para>Applications set the <structfield>type</structfield> field 56 <para>Applications set the <structfield>type</structfield> field
57 of a &v4l2-buffer; to the same buffer type as previously 57 of a &v4l2-buffer; to the same buffer type as was previously used with
58&v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers; 58&v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers;
59<structfield>type</structfield>, and the <structfield>index</structfield> 59<structfield>type</structfield>, and the <structfield>index</structfield>
60 field. Valid index numbers range from zero 60 field. Valid index numbers range from zero
61to the number of buffers allocated with &VIDIOC-REQBUFS; 61to the number of buffers allocated with &VIDIOC-REQBUFS;
62 (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. 62 (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.
63The <structfield>reserved</structfield> field should to set to 0.
63After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to 64After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to
64 this structure drivers return an error code or fill the rest of 65 this structure drivers return an error code or fill the rest of
65the structure.</para> 66the structure.</para>
@@ -68,8 +69,8 @@ the structure.</para>
68<constant>V4L2_BUF_FLAG_MAPPED</constant>, 69<constant>V4L2_BUF_FLAG_MAPPED</constant>,
69<constant>V4L2_BUF_FLAG_QUEUED</constant> and 70<constant>V4L2_BUF_FLAG_QUEUED</constant> and
70<constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The 71<constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The
71<structfield>memory</structfield> field will be set to 72<structfield>memory</structfield> field will be set to the current
72<constant>V4L2_MEMORY_MMAP</constant>, the <structfield>m.offset</structfield> 73I/O method, the <structfield>m.offset</structfield>
73contains the offset of the buffer from the start of the device memory, 74contains the offset of the buffer from the start of the device memory,
74the <structfield>length</structfield> field its size. The driver may 75the <structfield>length</structfield> field its size. The driver may
75or may not set the remaining fields and flags, they are meaningless in 76or may not set the remaining fields and flags, they are meaningless in
diff --git a/Documentation/DocBook/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/v4l/vidioc-reqbufs.xml
index bab38084454..1c081637207 100644
--- a/Documentation/DocBook/v4l/vidioc-reqbufs.xml
+++ b/Documentation/DocBook/v4l/vidioc-reqbufs.xml
@@ -54,23 +54,23 @@ I/O. Memory mapped buffers are located in device memory and must be
54allocated with this ioctl before they can be mapped into the 54allocated with this ioctl before they can be mapped into the
55application's address space. User buffers are allocated by 55application's address space. User buffers are allocated by
56applications themselves, and this ioctl is merely used to switch the 56applications themselves, and this ioctl is merely used to switch the
57driver into user pointer I/O mode.</para> 57driver into user pointer I/O mode and to setup some internal structures.</para>
58 58
59 <para>To allocate device buffers applications initialize three 59 <para>To allocate device buffers applications initialize all
60fields of a <structname>v4l2_requestbuffers</structname> structure. 60fields of the <structname>v4l2_requestbuffers</structname> structure.
61They set the <structfield>type</structfield> field to the respective 61They set the <structfield>type</structfield> field to the respective
62stream or buffer type, the <structfield>count</structfield> field to 62stream or buffer type, the <structfield>count</structfield> field to
63the desired number of buffers, and <structfield>memory</structfield> 63the desired number of buffers, <structfield>memory</structfield>
64must be set to <constant>V4L2_MEMORY_MMAP</constant>. When the ioctl 64must be set to the requested I/O method and the reserved array
65is called with a pointer to this structure the driver attempts to 65must be zeroed. When the ioctl
66allocate the requested number of buffers and stores the actual number 66is called with a pointer to this structure the driver will attempt to allocate
67the requested number of buffers and it stores the actual number
67allocated in the <structfield>count</structfield> field. It can be 68allocated in the <structfield>count</structfield> field. It can be
68smaller than the number requested, even zero, when the driver runs out 69smaller than the number requested, even zero, when the driver runs out
69of free memory. A larger number is possible when the driver requires 70of free memory. A larger number is also possible when the driver requires
70more buffers to function correctly.<footnote> 71more buffers to function correctly. For example video output requires at least two buffers,
71 <para>For example video output requires at least two buffers,
72one displayed and one filled by the application.</para> 72one displayed and one filled by the application.</para>
73 </footnote> When memory mapping I/O is not supported the ioctl 73 <para>When the I/O method is not supported the ioctl
74returns an &EINVAL;.</para> 74returns an &EINVAL;.</para>
75 75
76 <para>Applications can call <constant>VIDIOC_REQBUFS</constant> 76 <para>Applications can call <constant>VIDIOC_REQBUFS</constant>
@@ -81,14 +81,6 @@ in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no
81reason why munmap()ping one or even all buffers must imply 81reason why munmap()ping one or even all buffers must imply
82streamoff.--></para> 82streamoff.--></para>
83 83
84 <para>To negotiate user pointer I/O, applications initialize only
85the <structfield>type</structfield> field and set
86<structfield>memory</structfield> to
87<constant>V4L2_MEMORY_USERPTR</constant>. When the ioctl is called
88with a pointer to this structure the driver prepares for user pointer
89I/O, when this I/O method is not supported the ioctl returns an
90&EINVAL;.</para>
91
92 <table pgwide="1" frame="none" id="v4l2-requestbuffers"> 84 <table pgwide="1" frame="none" id="v4l2-requestbuffers">
93 <title>struct <structname>v4l2_requestbuffers</structname></title> 85 <title>struct <structname>v4l2_requestbuffers</structname></title>
94 <tgroup cols="3"> 86 <tgroup cols="3">
@@ -97,9 +89,7 @@ I/O, when this I/O method is not supported the ioctl returns an
97 <row> 89 <row>
98 <entry>__u32</entry> 90 <entry>__u32</entry>
99 <entry><structfield>count</structfield></entry> 91 <entry><structfield>count</structfield></entry>
100 <entry>The number of buffers requested or granted. This 92 <entry>The number of buffers requested or granted.</entry>
101field is only used when <structfield>memory</structfield> is set to
102<constant>V4L2_MEMORY_MMAP</constant>.</entry>
103 </row> 93 </row>
104 <row> 94 <row>
105 <entry>&v4l2-buf-type;</entry> 95 <entry>&v4l2-buf-type;</entry>
@@ -120,7 +110,7 @@ as the &v4l2-format; <structfield>type</structfield> field. See <xref
120 <entry><structfield>reserved</structfield>[2]</entry> 110 <entry><structfield>reserved</structfield>[2]</entry>
121 <entry>A place holder for future extensions and custom 111 <entry>A place holder for future extensions and custom
122(driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and 112(driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and
123higher.</entry> 113higher. This array should be zeroed by applications.</entry>
124 </row> 114 </row>
125 </tbody> 115 </tbody>
126 </tgroup> 116 </tgroup>