aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2016-07-17 17:45:25 -0400
committerMauro Carvalho Chehab <mchehab@s-opensource.com>2016-07-17 21:50:01 -0400
commit1bb6f32af74e33f082685e866eaef828d7e4abdd (patch)
tree738465c3cccc1815817ad34916c2e5300988e90f
parent93db50d6eca773b977598da1f5a2c2382efd61a6 (diff)
[media] doc-rst: add documentation for pvrusb2
Convert pvrusb2 documentation to ReST file and removed the note about an html version of the documentation, as it is not shipped inside the Kernel. Add it to media/v4l-drivers book. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
-rw-r--r--Documentation/media/v4l-drivers/index.rst1
-rw-r--r--Documentation/media/v4l-drivers/pvrusb2.rst164
2 files changed, 77 insertions, 88 deletions
diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst
index cb85bca0a077..e88ce12074ae 100644
--- a/Documentation/media/v4l-drivers/index.rst
+++ b/Documentation/media/v4l-drivers/index.rst
@@ -30,4 +30,5 @@ License".
30 meye 30 meye
31 omap3isp 31 omap3isp
32 omap4_camera 32 omap4_camera
33 pvrusb2
33 zr364xx 34 zr364xx
diff --git a/Documentation/media/v4l-drivers/pvrusb2.rst b/Documentation/media/v4l-drivers/pvrusb2.rst
index 2137b589276b..dc0e72d94b1a 100644
--- a/Documentation/media/v4l-drivers/pvrusb2.rst
+++ b/Documentation/media/v4l-drivers/pvrusb2.rst
@@ -1,88 +1,81 @@
1The pvrusb2 driver
2==================
1 3
2$Id$ 4Author: Mike Isely <isely@pobox.com>
3Mike Isely <isely@pobox.com>
4 5
5 pvrusb2 driver 6Background
7----------
6 8
7Background: 9This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which
10is a USB 2.0 hosted TV Tuner. This driver is a work in progress.
11Its history started with the reverse-engineering effort by Björn
12Danielsson <pvrusb2@dax.nu> whose web page can be found here:
13http://pvrusb2.dax.nu/
8 14
9 This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which 15From there Aurelien Alleaume <slts@free.fr> began an effort to
10 is a USB 2.0 hosted TV Tuner. This driver is a work in progress. 16create a video4linux compatible driver. I began with Aurelien's
11 Its history started with the reverse-engineering effort by Björn 17last known snapshot and evolved the driver to the state it is in
12 Danielsson <pvrusb2@dax.nu> whose web page can be found here: 18here.
13 19
14 http://pvrusb2.dax.nu/ 20More information on this driver can be found at:
21http://www.isely.net/pvrusb2.html
15 22
16 From there Aurelien Alleaume <slts@free.fr> began an effort to
17 create a video4linux compatible driver. I began with Aurelien's
18 last known snapshot and evolved the driver to the state it is in
19 here.
20 23
21 More information on this driver can be found at: 24This driver has a strong separation of layers. They are very
25roughly:
22 26
23 http://www.isely.net/pvrusb2.html 271. Low level wire-protocol implementation with the device.
24 28
292. I2C adaptor implementation and corresponding I2C client drivers
30 implemented elsewhere in V4L.
25 31
26 This driver has a strong separation of layers. They are very 323. High level hardware driver implementation which coordinates all
27 roughly: 33 activities that ensure correct operation of the device.
28 34
29 1a. Low level wire-protocol implementation with the device. 354. A "context" layer which manages instancing of driver, setup,
36 tear-down, arbitration, and interaction with high level
37 interfaces appropriately as devices are hotplugged in the
38 system.
30 39
31 1b. I2C adaptor implementation and corresponding I2C client drivers 405. High level interfaces which glue the driver to various published
32 implemented elsewhere in V4L. 41 Linux APIs (V4L, sysfs, maybe DVB in the future).
33
34 1c. High level hardware driver implementation which coordinates all
35 activities that ensure correct operation of the device.
36
37 2. A "context" layer which manages instancing of driver, setup,
38 tear-down, arbitration, and interaction with high level
39 interfaces appropriately as devices are hotplugged in the
40 system.
41
42 3. High level interfaces which glue the driver to various published
43 Linux APIs (V4L, sysfs, maybe DVB in the future).
44
45 The most important shearing layer is between the top 2 layers. A
46 lot of work went into the driver to ensure that any kind of
47 conceivable API can be laid on top of the core driver. (Yes, the
48 driver internally leverages V4L to do its work but that really has
49 nothing to do with the API published by the driver to the outside
50 world.) The architecture allows for different APIs to
51 simultaneously access the driver. I have a strong sense of fairness
52 about APIs and also feel that it is a good design principle to keep
53 implementation and interface isolated from each other. Thus while
54 right now the V4L high level interface is the most complete, the
55 sysfs high level interface will work equally well for similar
56 functions, and there's no reason I see right now why it shouldn't be
57 possible to produce a DVB high level interface that can sit right
58 alongside V4L.
59
60 NOTE: Complete documentation on the pvrusb2 driver is contained in
61 the html files within the doc directory; these are exactly the same
62 as what is on the web site at the time. Browse those files
63 (especially the FAQ) before asking questions.
64 42
43The most important shearing layer is between the top 2 layers. A
44lot of work went into the driver to ensure that any kind of
45conceivable API can be laid on top of the core driver. (Yes, the
46driver internally leverages V4L to do its work but that really has
47nothing to do with the API published by the driver to the outside
48world.) The architecture allows for different APIs to
49simultaneously access the driver. I have a strong sense of fairness
50about APIs and also feel that it is a good design principle to keep
51implementation and interface isolated from each other. Thus while
52right now the V4L high level interface is the most complete, the
53sysfs high level interface will work equally well for similar
54functions, and there's no reason I see right now why it shouldn't be
55possible to produce a DVB high level interface that can sit right
56alongside V4L.
65 57
66Building 58Building
59--------
67 60
68 To build these modules essentially amounts to just running "Make", 61To build these modules essentially amounts to just running "Make",
69 but you need the kernel source tree nearby and you will likely also 62but you need the kernel source tree nearby and you will likely also
70 want to set a few controlling environment variables first in order 63want to set a few controlling environment variables first in order
71 to link things up with that source tree. Please see the Makefile 64to link things up with that source tree. Please see the Makefile
72 here for comments that explain how to do that. 65here for comments that explain how to do that.
73 66
67Source file list / functional overview
68--------------------------------------
74 69
75Source file list / functional overview: 70(Note: The term "module" used below generally refers to loosely
71defined functional units within the pvrusb2 driver and bears no
72relation to the Linux kernel's concept of a loadable module.)
76 73
77 (Note: The term "module" used below generally refers to loosely 74pvrusb2-audio.[ch] - This is glue logic that resides between this
78 defined functional units within the pvrusb2 driver and bears no
79 relation to the Linux kernel's concept of a loadable module.)
80
81 pvrusb2-audio.[ch] - This is glue logic that resides between this
82 driver and the msp3400.ko I2C client driver (which is found 75 driver and the msp3400.ko I2C client driver (which is found
83 elsewhere in V4L). 76 elsewhere in V4L).
84 77
85 pvrusb2-context.[ch] - This module implements the context for an 78pvrusb2-context.[ch] - This module implements the context for an
86 instance of the driver. Everything else eventually ties back to 79 instance of the driver. Everything else eventually ties back to
87 or is otherwise instanced within the data structures implemented 80 or is otherwise instanced within the data structures implemented
88 here. Hotplugging is ultimately coordinated here. All high level 81 here. Hotplugging is ultimately coordinated here. All high level
@@ -93,28 +86,28 @@ Source file list / functional overview:
93 the tuner's frequency through sysfs while simultaneously streaming 86 the tuner's frequency through sysfs while simultaneously streaming
94 video through V4L out to an instance of mplayer). 87 video through V4L out to an instance of mplayer).
95 88
96 pvrusb2-debug.h - This header defines a printk() wrapper and a mask 89pvrusb2-debug.h - This header defines a printk() wrapper and a mask
97 of debugging bit definitions for the various kinds of debug 90 of debugging bit definitions for the various kinds of debug
98 messages that can be enabled within the driver. 91 messages that can be enabled within the driver.
99 92
100 pvrusb2-debugifc.[ch] - This module implements a crude command line 93pvrusb2-debugifc.[ch] - This module implements a crude command line
101 oriented debug interface into the driver. Aside from being part 94 oriented debug interface into the driver. Aside from being part
102 of the process for implementing manual firmware extraction (see 95 of the process for implementing manual firmware extraction (see
103 the pvrusb2 web site mentioned earlier), probably I'm the only one 96 the pvrusb2 web site mentioned earlier), probably I'm the only one
104 who has ever used this. It is mainly a debugging aid. 97 who has ever used this. It is mainly a debugging aid.
105 98
106 pvrusb2-eeprom.[ch] - This is glue logic that resides between this 99pvrusb2-eeprom.[ch] - This is glue logic that resides between this
107 driver the tveeprom.ko module, which is itself implemented 100 driver the tveeprom.ko module, which is itself implemented
108 elsewhere in V4L. 101 elsewhere in V4L.
109 102
110 pvrusb2-encoder.[ch] - This module implements all protocol needed to 103pvrusb2-encoder.[ch] - This module implements all protocol needed to
111 interact with the Conexant mpeg2 encoder chip within the pvrusb2 104 interact with the Conexant mpeg2 encoder chip within the pvrusb2
112 device. It is a crude echo of corresponding logic in ivtv, 105 device. It is a crude echo of corresponding logic in ivtv,
113 however the design goals (strict isolation) and physical layer 106 however the design goals (strict isolation) and physical layer
114 (proxy through USB instead of PCI) are enough different that this 107 (proxy through USB instead of PCI) are enough different that this
115 implementation had to be completely different. 108 implementation had to be completely different.
116 109
117 pvrusb2-hdw-internal.h - This header defines the core data structure 110pvrusb2-hdw-internal.h - This header defines the core data structure
118 in the driver used to track ALL internal state related to control 111 in the driver used to track ALL internal state related to control
119 of the hardware. Nobody outside of the core hardware-handling 112 of the hardware. Nobody outside of the core hardware-handling
120 modules should have any business using this header. All external 113 modules should have any business using this header. All external
@@ -123,16 +116,16 @@ Source file list / functional overview:
123 level interfaces are restricted to the API defined in 116 level interfaces are restricted to the API defined in
124 pvrusb2-hdw.h and NOT this header. 117 pvrusb2-hdw.h and NOT this header.
125 118
126 pvrusb2-hdw.h - This header defines the full internal API for 119pvrusb2-hdw.h - This header defines the full internal API for
127 controlling the hardware. High level interfaces (e.g. V4L, sysfs) 120 controlling the hardware. High level interfaces (e.g. V4L, sysfs)
128 will work through here. 121 will work through here.
129 122
130 pvrusb2-hdw.c - This module implements all the various bits of logic 123pvrusb2-hdw.c - This module implements all the various bits of logic
131 that handle overall control of a specific pvrusb2 device. 124 that handle overall control of a specific pvrusb2 device.
132 (Policy, instantiation, and arbitration of pvrusb2 devices fall 125 (Policy, instantiation, and arbitration of pvrusb2 devices fall
133 within the jurisdiction of pvrusb-context not here). 126 within the jurisdiction of pvrusb-context not here).
134 127
135 pvrusb2-i2c-chips-*.c - These modules implement the glue logic to 128pvrusb2-i2c-chips-\*.c - These modules implement the glue logic to
136 tie together and configure various I2C modules as they attach to 129 tie together and configure various I2C modules as they attach to
137 the I2C bus. There are two versions of this file. The "v4l2" 130 the I2C bus. There are two versions of this file. The "v4l2"
138 version is intended to be used in-tree alongside V4L, where we 131 version is intended to be used in-tree alongside V4L, where we
@@ -142,17 +135,17 @@ Source file list / functional overview:
142 from ivtv or older kernel snapshots (or even the support modules 135 from ivtv or older kernel snapshots (or even the support modules
143 in the standalone snapshot). 136 in the standalone snapshot).
144 137
145 pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1 138pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1
146 compatible commands to the I2C modules. It is here where state 139 compatible commands to the I2C modules. It is here where state
147 changes inside the pvrusb2 driver are translated into V4L1 140 changes inside the pvrusb2 driver are translated into V4L1
148 commands that are in turn send to the various I2C modules. 141 commands that are in turn send to the various I2C modules.
149 142
150 pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2 143pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2
151 compatible commands to the I2C modules. It is here where state 144 compatible commands to the I2C modules. It is here where state
152 changes inside the pvrusb2 driver are translated into V4L2 145 changes inside the pvrusb2 driver are translated into V4L2
153 commands that are in turn send to the various I2C modules. 146 commands that are in turn send to the various I2C modules.
154 147
155 pvrusb2-i2c-core.[ch] - This module provides an implementation of a 148pvrusb2-i2c-core.[ch] - This module provides an implementation of a
156 kernel-friendly I2C adaptor driver, through which other external 149 kernel-friendly I2C adaptor driver, through which other external
157 I2C client drivers (e.g. msp3400, tuner, lirc) may connect and 150 I2C client drivers (e.g. msp3400, tuner, lirc) may connect and
158 operate corresponding chips within the pvrusb2 device. It is 151 operate corresponding chips within the pvrusb2 device. It is
@@ -162,51 +155,46 @@ Source file list / functional overview:
162 pvrusb2-context, and then ultimately made available to users 155 pvrusb2-context, and then ultimately made available to users
163 through one of the high level interfaces). 156 through one of the high level interfaces).
164 157
165 pvrusb2-io.[ch] - This module implements a very low level ring of 158pvrusb2-io.[ch] - This module implements a very low level ring of
166 transfer buffers, required in order to stream data from the 159 transfer buffers, required in order to stream data from the
167 device. This module is *very* low level. It only operates the 160 device. This module is *very* low level. It only operates the
168 buffers and makes no attempt to define any policy or mechanism for 161 buffers and makes no attempt to define any policy or mechanism for
169 how such buffers might be used. 162 how such buffers might be used.
170 163
171 pvrusb2-ioread.[ch] - This module layers on top of pvrusb2-io.[ch] 164pvrusb2-ioread.[ch] - This module layers on top of pvrusb2-io.[ch]
172 to provide a streaming API usable by a read() system call style of 165 to provide a streaming API usable by a read() system call style of
173 I/O. Right now this is the only layer on top of pvrusb2-io.[ch], 166 I/O. Right now this is the only layer on top of pvrusb2-io.[ch],
174 however the underlying architecture here was intended to allow for 167 however the underlying architecture here was intended to allow for
175 other styles of I/O to be implemented with additional modules, like 168 other styles of I/O to be implemented with additional modules, like
176 mmap()'ed buffers or something even more exotic. 169 mmap()'ed buffers or something even more exotic.
177 170
178 pvrusb2-main.c - This is the top level of the driver. Module level 171pvrusb2-main.c - This is the top level of the driver. Module level
179 and USB core entry points are here. This is our "main". 172 and USB core entry points are here. This is our "main".
180 173
181 pvrusb2-sysfs.[ch] - This is the high level interface which ties the 174pvrusb2-sysfs.[ch] - This is the high level interface which ties the
182 pvrusb2 driver into sysfs. Through this interface you can do 175 pvrusb2 driver into sysfs. Through this interface you can do
183 everything with the driver except actually stream data. 176 everything with the driver except actually stream data.
184 177
185 pvrusb2-tuner.[ch] - This is glue logic that resides between this 178pvrusb2-tuner.[ch] - This is glue logic that resides between this
186 driver and the tuner.ko I2C client driver (which is found 179 driver and the tuner.ko I2C client driver (which is found
187 elsewhere in V4L). 180 elsewhere in V4L).
188 181
189 pvrusb2-util.h - This header defines some common macros used 182pvrusb2-util.h - This header defines some common macros used
190 throughout the driver. These macros are not really specific to 183 throughout the driver. These macros are not really specific to
191 the driver, but they had to go somewhere. 184 the driver, but they had to go somewhere.
192 185
193 pvrusb2-v4l2.[ch] - This is the high level interface which ties the 186pvrusb2-v4l2.[ch] - This is the high level interface which ties the
194 pvrusb2 driver into video4linux. It is through here that V4L 187 pvrusb2 driver into video4linux. It is through here that V4L
195 applications can open and operate the driver in the usual V4L 188 applications can open and operate the driver in the usual V4L
196 ways. Note that **ALL** V4L functionality is published only 189 ways. Note that **ALL** V4L functionality is published only
197 through here and nowhere else. 190 through here and nowhere else.
198 191
199 pvrusb2-video-*.[ch] - This is glue logic that resides between this 192pvrusb2-video-\*.[ch] - This is glue logic that resides between this
200 driver and the saa711x.ko I2C client driver (which is found 193 driver and the saa711x.ko I2C client driver (which is found
201 elsewhere in V4L). Note that saa711x.ko used to be known as 194 elsewhere in V4L). Note that saa711x.ko used to be known as
202 saa7115.ko in ivtv. There are two versions of this; one is 195 saa7115.ko in ivtv. There are two versions of this; one is
203 selected depending on the particular saa711[5x].ko that is found. 196 selected depending on the particular saa711[5x].ko that is found.
204 197
205 pvrusb2.h - This header contains compile time tunable parameters 198pvrusb2.h - This header contains compile time tunable parameters
206 (and at the moment the driver has very little that needs to be 199 (and at the moment the driver has very little that needs to be
207 tuned). 200 tuned).
208
209
210 -Mike Isely
211 isely@pobox.com
212