README.cpia
1This is a driver for the CPiA PPC2 driven parallel connected
2Camera. For example the Creative WebcamII is CPiA driven.
3
4 ) [1]Peter Pregler, Linz 2000, published under the [2]GNU GPL
5
6---------------------------------------------------------------------------
7
8USAGE:
9
10General:
11========
12
131) Make sure you have created the video devices (/dev/video*):
14
15- if you have a recent MAKEDEV do a 'cd /dev;./MAKEDEV video'
16- otherwise do a:
17
18cd /dev
19mknod video0 c 81 0
20ln -s video0 video
21
222) Compile the kernel (see below for the list of options to use),
23 configure your parport and reboot.
24
253) If all worked well you should get messages similar
26 to the following (your versions may be different) on the console:
27
28V4L-Driver for Vision CPiA based cameras v0.7.4
29parport0: read2 timeout.
30parport0: Multimedia device, VLSI Vision Ltd PPC2
31Parallel port driver for Vision CPiA based camera
32 CPIA Version: 1.20 (2.0)
33 CPIA PnP-ID: 0553:0002:0100
34 VP-Version: 1.0 0100
35 1 camera(s) found
36
37
38As modules:
39===========
40
41Make sure you have selected the following kernel options (you can
42select all stuff as modules):
43
44The cpia-stuff is in the section 'Character devices -> Video For Linux'.
45
46CONFIG_PARPORT=m
47CONFIG_PARPORT_PC=m
48CONFIG_PARPORT_PC_FIFO=y
49CONFIG_PARPORT_1284=y
50CONFIG_VIDEO_DEV=m
51CONFIG_VIDEO_CPIA=m
52CONFIG_VIDEO_CPIA_PP=m
53
54For autoloading of all those modules you need to tell module-init-tools
55some stuff. Add the following line to your module-init-tools config-file
56(e.g. /etc/modprobe.conf or wherever your distribution does store that
57stuff):
58
59options parport_pc io=0x378 irq=7 dma=3
60alias char-major-81 cpia_pp
61
62The first line tells the dma/irq channels to use. Those _must_ match
63the settings of your BIOS. Do NOT simply use the values above. See
64Documentation/parport.txt for more information about this. The second
65line associates the video-device file with the driver. Of cause you
66can also load the modules once upon boot (usually done in /etc/modules).
67
68Linked into the kernel:
69=======================
70
71Make sure you have selected the following kernel options. Note that
72you cannot compile the parport-stuff as modules and the cpia-driver
73statically (the other way round is okay though).
74
75The cpia-stuff is in the section 'Character devices -> Video For Linux'.
76
77CONFIG_PARPORT=y
78CONFIG_PARPORT_PC=y
79CONFIG_PARPORT_PC_FIFO=y
80CONFIG_PARPORT_1284=y
81CONFIG_VIDEO_DEV=y
82CONFIG_VIDEO_CPIA=y
83CONFIG_VIDEO_CPIA_PP=y
84
85To use DMA/irq you will need to tell the kernel upon boot time the
86hardware configuration of the parport. You can give the boot-parameter
87at the LILO-prompt or specify it in lilo.conf. I use the following
88append-line in lilo.conf:
89
90 append="parport=0x378,7,3"
91
92See Documentation/parport.txt for more information about the
93configuration of the parport and the values given above. Do not simply
94use the values given above.
95
96---------------------------------------------------------------------------
97FEATURES:
98
99- mmap/read v4l-interface (but no overlay)
100- image formats: CIF/QCIF, SIF/QSIF, various others used by isabel;
101 note: all sizes except CIF/QCIF are implemented by clipping, i.e.
102 pixels are not uploaded from the camera
103- palettes: VIDEO_PALETTE_GRAY, VIDEO_PALETTE_RGB565, VIDEO_PALETTE_RGB555,
104 VIDEO_PALETTE_RGB24, VIDEO_PALETTE_RGB32, VIDEO_PALETTE_YUYV,
105 VIDEO_PALETTE_UYVY, VIDEO_PALETTE_YUV422
106- state information (color balance, exposure, ...) is preserved between
107 device opens
108- complete control over camera via proc-interface (_all_ camera settings are
109 supported), there is also a python-gtk application available for this [3]
110- works under SMP (but the driver is completely serialized and synchronous)
111 so you get no benefit from SMP, but at least it does not crash your box
112- might work for non-Intel architecture, let us know about this
113
114---------------------------------------------------------------------------
115TESTED APPLICATIONS:
116
117- a simple test application based on Xt is available at [3]
118- another test-application based on gqcam-0.4 (uses GTK)
119- gqcam-0.6 should work
120- xawtv-3.x (also the webcam software)
121- xawtv-2.46
122- w3cam (cgi-interface and vidcat, e.g. you may try out 'vidcat |xv
123 -maxpect -root -quit +noresetroot -rmode 5 -')
124- vic, the MBONE video conferencing tool (version 2.8ucl4-1)
125- isabel 3R4beta (barely working, but AFAICT all the problems are on
126 their side)
127- camserv-0.40
128
129See [3] for pointers to v4l-applications.
130
131---------------------------------------------------------------------------
132KNOWN PROBLEMS:
133
134- some applications do not handle the image format correctly, you will
135 see strange horizontal stripes instead of a nice picture -> make sure
136 your application does use a supported image size or queries the driver
137 for the actually used size (reason behind this: the camera cannot
138 provide any image format, so if size NxM is requested the driver will
139 use a format to the closest fitting N1xM1, the application should now
140 query for this granted size, most applications do not).
141- all the todo ;)
142- if there is not enough light and the picture is too dark try to
143 adjust the SetSensorFPS setting, automatic frame rate adjustment
144 has its price
145- do not try out isabel 3R4beta (built 135), you will be disappointed
146
147---------------------------------------------------------------------------
148TODO:
149
150- multiple camera support (struct camera or something) - This should work,
151 but hasn't been tested yet.
152- architecture independence?
153- SMP-safe asynchronous mmap interface
154- nibble mode for old parport interfaces
155- streaming capture, this should give a performance gain
156
157---------------------------------------------------------------------------
158IMPLEMENTATION NOTES:
159
160The camera can act in two modes, streaming or grabbing. Right now a
161polling grab-scheme is used. Maybe interrupt driven streaming will be
162used for a asynchronous mmap interface in the next major release of the
163driver. This might give a better frame rate.
164
165---------------------------------------------------------------------------
166THANKS (in no particular order):
167
168- Scott J. Bertin <sbertin@mindspring.com> for cleanups, the proc-filesystem
169 and much more
170- Henry Bruce <whb@vvl.co.uk> for providing developers information about
171 the CPiA chip, I wish all companies would treat Linux as seriously
172- Karoly Erdei <Karoly.Erdei@risc.uni-linz.ac.at> and RISC-Linz for being
173 my boss ;) resp. my employer and for providing me the hardware and
174 allow me to devote some working time to this project
175- Manuel J. Petit de Gabriel <mpetit@dit.upm.es> for providing help
176 with Isabel (http://isabel.dit.upm.es/)
177- Bas Huisman <bhuism@cs.utwente.nl> for writing the initial parport code
178- Jarl Totland <Jarl.Totland@bdc.no> for setting up the mailing list
179 and maintaining the web-server[3]
180- Chris Whiteford <Chris@informinteractive.com> for fixes related to the
181 1.02 firmware
182- special kudos to all the tester whose machines crashed and/or
183 will crash. :)
184
185---------------------------------------------------------------------------
186REFERENCES
187
188 1. http://www.risc.uni-linz.ac.at/people/ppregler
189 mailto:Peter_Pregler@email.com
190 2. see the file COPYING in the top directory of the kernel tree
191 3. http://webcam.sourceforge.net/
192
README.cpia2
1$Id: README,v 1.7 2005/08/29 23:39:57 sbertin Exp $
2
31. Introduction
4
5 This is a driver for STMicroelectronics's CPiA2 (second generation
6Colour Processor Interface ASIC) based cameras. This camera outputs an MJPEG
7stream at up to vga size. It implements the Video4Linux interface as much as
8possible. Since the V4L interface does not support compressed formats, only
9an mjpeg enabled application can be used with the camera. We have modified the
10gqcam application to view this stream.
11
12 The driver is implemented as two kernel modules. The cpia2 module
13contains the camera functions and the V4L interface. The cpia2_usb module
14contains usb specific functions. The main reason for this was the size of the
15module was getting out of hand, so I separted them. It is not likely that
16there will be a parallel port version.
17
18FEATURES:
19 - Supports cameras with the Vision stv6410 (CIF) and stv6500 (VGA) cmos
20 sensors. I only have the vga sensor, so can't test the other.
21 - Image formats: VGA, QVGA, CIF, QCIF, and a number of sizes in between.
22 VGA and QVGA are the native image sizes for the VGA camera. CIF is done
23 in the coprocessor by scaling QVGA. All other sizes are done by clipping.
24 - Palette: YCrCb, compressed with MJPEG.
25 - Some compression parameters are settable.
26 - Sensor framerate is adjustable (up to 30 fps CIF, 15 fps VGA).
27 - Adjust brightness, color, contrast while streaming.
28 - Flicker control settable for 50 or 60 Hz mains frequency.
29
302. Making and installing the stv672 driver modules:
31
32 Requirements:
33 -------------
34 This should work with 2.4 (2.4.23 and later) and 2.6 kernels, but has
35only been tested on 2.6. Video4Linux must be either compiled into the kernel or
36available as a module. Video4Linux2 is automatically detected and made
37available at compile time.
38
39 Compiling:
40 ----------
41 As root, do a make install. This will compile and install the modules
42into the media/video directory in the module tree. For 2.4 kernels, use
43Makefile_2.4 (aka do make -f Makefile_2.4 install).
44
45 Setup:
46 ------
47 Use 'modprobe cpia2' to load and 'modprobe -r cpia2' to unload. This
48may be done automatically by your distribution.
49
503. Driver options
51
52 Option Description
53 ------ -----------
54 video_nr video device to register (0=/dev/video0, etc)
55 range -1 to 64. default is -1 (first available)
56 If you have more than 1 camera, this MUST be -1.
57 buffer_size Size for each frame buffer in bytes (default 68k)
58 num_buffers Number of frame buffers (1-32, default 3)
59 alternate USB Alternate (2-7, default 7)
60 flicker_freq Frequency for flicker reduction(50 or 60, default 60)
61 flicker_mode 0 to disable, or 1 to enable flicker reduction.
62 (default 0). This is only effective if the camera
63 uses a stv0672 coprocessor.
64
65 Setting the options:
66 --------------------
67 If you are using modules, edit /etc/modules.conf and add an options
68line like this:
69 options cpia2 num_buffers=3 buffer_size=65535
70
71 If the driver is compiled into the kernel, at boot time specify them
72like this:
73 cpia2.num_buffers=3 cpia2.buffer_size=65535
74
75 What buffer size should I use?
76 ------------------------------
77 The maximum image size depends on the alternate you choose, and the
78frame rate achieved by the camera. If the compression engine is able to
79keep up with the frame rate, the maximum image size is given by the table
80below.
81 The compression engine starts out at maximum compression, and will
82increase image quality until it is close to the size in the table. As long
83as the compression engine can keep up with the frame rate, after a short time
84the images will all be about the size in the table, regardless of resolution.
85 At low alternate settings, the compression engine may not be able to
86compress the image enough and will reduce the frame rate by producing larger
87images.
88 The default of 68k should be good for most users. This will handle
89any alternate at frame rates down to 15fps. For lower frame rates, it may
90be necessary to increase the buffer size to avoid having frames dropped due
91to insufficient space.
92
93 Image size(bytes)
94 Alternate bytes/ms 15fps 30fps
95 2 128 8533 4267
96 3 384 25600 12800
97 4 640 42667 21333
98 5 768 51200 25600
99 6 896 59733 29867
100 7 1023 68200 34100
101
102 How many buffers should I use?
103 ------------------------------
104 For normal streaming, 3 should give the best results. With only 2,
105it is possible for the camera to finish sending one image just after a
106program has started reading the other. If this happens, the driver must drop
107a frame. The exception to this is if you have a heavily loaded machine. In
108this case use 2 buffers. You are probably not reading at the full frame rate.
109If the camera can send multiple images before a read finishes, it could
110overwrite the third buffer before the read finishes, leading to a corrupt
111image. Single and double buffering have extra checks to avoid overwriting.
112
1134. Using the camera
114
115 We are providing a modified gqcam application to view the output. In
116order to avoid confusion, here it is called mview. There is also the qx5view
117program which can also control the lights on the qx5 microscope. MJPEG Tools
118(http://mjpeg.sourceforge.net) can also be used to record from the camera.
119
1205. Notes to developers:
121
122 - This is a driver version stripped of the 2.4 back compatibility
123 and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support.
124
1256. Thanks:
126
127 - Peter Pregler <Peter_Pregler@email.com>,
128 Scott J. Bertin <scottbertin@yahoo.com>, and
129 Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which
130 this one was modelled from.
131
README.cx88
1cx8800 release notes
2====================
3
4This is a v4l2 device driver for the cx2388x chip.
5
6
7current status
8==============
9
10video
11 - Basically works.
12 - For now, only capture and read(). Overlay isn't supported.
13
14audio
15 - The chip specs for the on-chip TV sound decoder are next
16 to useless :-/
17 - Neverless the builtin TV sound decoder starts working now,
18 at least for some standards.
19 FOR ANY REPORTS ON THIS PLEASE MENTION THE TV NORM YOU ARE
20 USING.
21 - Most tuner chips do provide mono sound, which may or may not
22 be useable depending on the board design. With the Hauppauge
23 cards it works, so there is mono sound available as fallback.
24 - audio data dma (i.e. recording without loopback cable to the
25 sound card) is supported via cx88-alsa.
26
27vbi
28 - Code present. Works for NTSC closed caption. PAL and other
29 TV norms may or may not work.
30
31
32how to add support for new cards
33================================
34
35The driver needs some config info for the TV cards. This stuff is in
36cx88-cards.c. If the driver doesn't work well you likely need a new
37entry for your card in that file. Check the kernel log (using dmesg)
38to see whenever the driver knows your card or not. There is a line
39like this one:
40
41 cx8800[0]: subsystem: 0070:3400, board: Hauppauge WinTV \
42 34xxx models [card=1,autodetected]
43
44If your card is listed as "board: UNKNOWN/GENERIC" it is unknown to
45the driver. What to do then?
46
47 (1) Try upgrading to the latest snapshot, maybe it has been added
48 meanwhile.
49 (2) You can try to create a new entry yourself, have a look at
50 cx88-cards.c. If that worked, mail me your changes as unified
51 diff ("diff -u").
52 (3) Or you can mail me the config information. I need at least the
53 following informations to add the card:
54
55 * the PCI Subsystem ID ("0070:3400" from the line above,
56 "lspci -v" output is fine too).
57 * the tuner type used by the card. You can try to find one by
58 trial-and-error using the tuner=<n> insmod option. If you
59 know which one the card has you can also have a look at the
60 list in CARDLIST.tuner
61
62Have fun,
63
64 Gerd
65
66--
67Gerd Knorr <kraxel@bytesex.org> [SuSE Labs]
68
README.ir
1
2infrared remote control support in video4linux drivers
3======================================================
4
5
6basics
7------
8
9Current versions use the linux input layer to support infrared
10remote controls. I suggest to download my input layer tools
11from http://bytesex.org/snapshot/input-<date>.tar.gz
12
13Modules you have to load:
14
15 saa7134 statically built in, i.e. just the driver :)
16 bttv ir-kbd-gpio or ir-kbd-i2c depending on your
17 card.
18
19ir-kbd-gpio and ir-kbd-i2c don't support all cards lirc supports
20(yet), mainly for the reason that the code of lirc_i2c and lirc_gpio
21was very confusing and I decided to basically start over from scratch.
22Feel free to contact me in case of trouble. Note that the ir-kbd-*
23modules work on 2.6.x kernels only through ...
24
25
26how it works
27------------
28
29The modules register the remote as keyboard within the linux input
30layer, i.e. you'll see the keys of the remote as normal key strokes
31(if CONFIG_INPUT_KEYBOARD is enabled).
32
33Using the event devices (CONFIG_INPUT_EVDEV) it is possible for
34applications to access the remote via /dev/input/event<n> devices.
35You might have to create the special files using "/sbin/MAKEDEV
36input". The input layer tools mentioned above use the event device.
37
38The input layer tools are nice for trouble shooting, i.e. to check
39whenever the input device is really present, which of the devices it
40is, check whenever pressing keys on the remote actually generates
41events and the like. You can also use the kbd utility to change the
42keymaps (2.6.x kernels only through).
43
44
45using with lircd
46================
47
48The cvs version of the lircd daemon supports reading events from the
49linux input layer (via event device). The input layer tools tarball
50comes with a lircd config file.
51
52
53using without lircd
54===================
55
56XFree86 likely can be configured to recognise the remote keys. Once I
57simply tried to configure one of the multimedia keyboards as input
58device, which had the effect that XFree86 recognised some of the keys
59of my remote control and passed volume up/down key presses as
60XF86AudioRaiseVolume and XF86AudioLowerVolume key events to the X11
61clients.
62
63It likely is possible to make that fly with a nice xkb config file,
64I know next to nothing about that through.
65
66
67Have fun,
68
69 Gerd
70
71--
72Gerd Knorr <kraxel@bytesex.org>
73
README.ivtv
1
2ivtv release notes
3==================
4
5This is a v4l2 device driver for the Conexant cx23415/6 MPEG encoder/decoder.
6The cx23415 can do both encoding and decoding, the cx23416 can only do MPEG
7encoding. Currently the only card featuring full decoding support is the
8Hauppauge PVR-350.
9
10NOTE: this driver requires the latest encoder firmware (version 2.06.039, size
11376836 bytes). Get the firmware from here:
12
13http://dl.ivtvdriver.org/ivtv/firmware/firmware.tar.gz
14
15NOTE: 'normal' TV applications do not work with this driver, you need
16an application that can handle MPEG input such as mplayer, xine, MythTV,
17etc.
18
19The primary goal of the IVTV project is to provide a "clean room" Linux
20Open Source driver implementation for video capture cards based on the
21iCompression iTVC15 or Conexant CX23415/CX23416 MPEG Codec.
22
23Features:
24 * Hardware mpeg2 capture of broadcast video (and sound) via the tuner or
25 S-Video/Composite and audio line-in.
26 * Hardware mpeg2 capture of FM radio where hardware support exists
27 * Supports NTSC, PAL, SECAM with stereo sound
28 * Supports SAP and bilingual transmissions.
29 * Supports raw VBI (closed captions and teletext).
30 * Supports sliced VBI (closed captions and teletext) and is able to insert
31 this into the captured MPEG stream.
32 * Supports raw YUV and PCM input.
33
34Additional features for the PVR-350 (CX23415 based):
35 * Provides hardware mpeg2 playback
36 * Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the
37 video signal)
38 * Provides a framebuffer (allowing X applications to appear on the video
39 device) (this framebuffer is not yet part of the kernel. In the meantime it
40 is available from www.ivtvdriver.org).
41 * Supports raw YUV output.
42
43IMPORTANT: In case of problems first read this page:
44 http://www.ivtvdriver.org/index.php/Troubleshooting
45
46See also:
47
48Homepage + Wiki
49http://www.ivtvdriver.org
50
51IRC
52irc://irc.freenode.net/ivtv-dev
53
54----------------------------------------------------------
55
56Devices
57=======
58
59A maximum of 12 ivtv boards are allowed at the moment.
60
61Cards that don't have a video output capability (i.e. non PVR350 cards)
62lack the vbi8, vbi16, video16 and video48 devices. They also do not
63support the framebuffer device /dev/fbx for OSD.
64
65The radio0 device may or may not be present, depending on whether the
66card has a radio tuner or not.
67
68Here is a list of the base v4l devices:
69crw-rw---- 1 root video 81, 0 Jun 19 22:22 /dev/video0
70crw-rw---- 1 root video 81, 16 Jun 19 22:22 /dev/video16
71crw-rw---- 1 root video 81, 24 Jun 19 22:22 /dev/video24
72crw-rw---- 1 root video 81, 32 Jun 19 22:22 /dev/video32
73crw-rw---- 1 root video 81, 48 Jun 19 22:22 /dev/video48
74crw-rw---- 1 root video 81, 64 Jun 19 22:22 /dev/radio0
75crw-rw---- 1 root video 81, 224 Jun 19 22:22 /dev/vbi0
76crw-rw---- 1 root video 81, 228 Jun 19 22:22 /dev/vbi8
77crw-rw---- 1 root video 81, 232 Jun 19 22:22 /dev/vbi16
78
79Base devices
80============
81
82For every extra card you have the numbers increased by one. For example,
83/dev/video0 is listed as the 'base' encoding capture device so we have:
84
85 /dev/video0 is the encoding capture device for the first card (card 0)
86 /dev/video1 is the encoding capture device for the second card (card 1)
87 /dev/video2 is the encoding capture device for the third card (card 2)
88
89Note that if the first card doesn't have a feature (eg no decoder, so no
90video16, the second card will still use video17. The simple rule is 'add
91the card number to the base device number'. If you have other capture
92cards (e.g. WinTV PCI) that are detected first, then you have to tell
93the ivtv module about it so that it will start counting at 1 (or 2, or
94whatever). Otherwise the device numbers can get confusing. The ivtv
95'ivtv_first_minor' module option can be used for that.
96
97
98/dev/video0
99The encoding capture device(s).
100Read-only.
101
102Reading from this device gets you the MPEG1/2 program stream.
103Example:
104
105cat /dev/video0 > my.mpg (you need to hit ctrl-c to exit)
106
107
108/dev/video16
109The decoder output device(s)
110Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
111
112An mpeg2 stream sent to this device will appear on the selected video
113display, audio will appear on the line-out/audio out. It is only
114available for cards that support video out. Example:
115
116cat my.mpg >/dev/video16
117
118
119/dev/video24
120The raw audio capture device(s).
121Read-only
122
123The raw audio PCM stereo stream from the currently selected
124tuner or audio line-in. Reading from this device results in a raw
125(signed 16 bit Little Endian, 48000 Hz, stereo pcm) capture.
126This device only captures audio. This should be replaced by an ALSA
127device in the future.
128Note that there is no corresponding raw audio output device, this is
129not supported in the decoder firmware.
130
131
132/dev/video32
133The raw video capture device(s)
134Read-only
135
136The raw YUV video output from the current video input. The YUV format
137is non-standard (V4L2_PIX_FMT_HM12).
138
139Note that the YUV and PCM streams are not synchronized, so they are of
140limited use.
141
142
143/dev/video48
144The raw video display device(s)
145Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
146
147Writes a YUV stream to the decoder of the card.
148
149
150/dev/radio0
151The radio tuner device(s)
152Cannot be read or written.
153
154Used to enable the radio tuner and tune to a frequency. You cannot
155read or write audio streams with this device. Once you use this
156device to tune the radio, use /dev/video24 to read the raw pcm stream
157or /dev/video0 to get an mpeg2 stream with black video.
158
159
160/dev/vbi0
161The 'vertical blank interval' (Teletext, CC, WSS etc) capture device(s)
162Read-only
163
164Captures the raw (or sliced) video data sent during the Vertical Blank
165Interval. This data is used to encode teletext, closed captions, VPS,
166widescreen signalling, electronic program guide information, and other
167services.
168
169
170/dev/vbi8
171Processed vbi feedback device(s)
172Read-only. Only present if the MPEG decoder (i.e. CX23415) exists.
173
174The sliced VBI data embedded in an MPEG stream is reproduced on this
175device. So while playing back a recording on /dev/video16, you can
176read the embedded VBI data from /dev/vbi8.
177
178
179/dev/vbi16
180The vbi 'display' device(s)
181Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
182
183Can be used to send sliced VBI data to the video-out connector.
184
185---------------------------------
186
187Hans Verkuil <hverkuil@xs4all.nl>
188
README.pvrusb2
1
2$Id$
3Mike Isely <isely@pobox.com>
4
5 pvrusb2 driver
6
7Background:
8
9 This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which
10 is a USB 2.0 hosted TV Tuner. This driver is a work in progress.
11 Its history started with the reverse-engineering effort by Björn
12 Danielsson <pvrusb2@dax.nu> whose web page can be found here:
13
14 http://pvrusb2.dax.nu/
15
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
21 More information on this driver can be found at:
22
23 http://www.isely.net/pvrusb2.html
24
25
26 This driver has a strong separation of layers. They are very
27 roughly:
28
29 1a. Low level wire-protocol implementation with the device.
30
31 1b. I2C adaptor implementation and corresponding I2C client drivers
32 implemented elsewhere in V4L.
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
65
66Building
67
68 To build these modules essentially amounts to just running "Make",
69 but you need the kernel source tree nearby and you will likely also
70 want to set a few controlling environment variables first in order
71 to link things up with that source tree. Please see the Makefile
72 here for comments that explain how to do that.
73
74
75Source file list / functional overview:
76
77 (Note: The term "module" used below generally refers to loosely
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
83 elsewhere in V4L).
84
85 pvrusb2-context.[ch] - This module implements the context for an
86 instance of the driver. Everything else eventually ties back to
87 or is otherwise instanced within the data structures implemented
88 here. Hotplugging is ultimately coordinated here. All high level
89 interfaces tie into the driver through this module. This module
90 helps arbitrate each interface's access to the actual driver core,
91 and is designed to allow concurrent access through multiple
92 instances of multiple interfaces (thus you can for example change
93 the tuner's frequency through sysfs while simultaneously streaming
94 video through V4L out to an instance of mplayer).
95
96 pvrusb2-debug.h - This header defines a printk() wrapper and a mask
97 of debugging bit definitions for the various kinds of debug
98 messages that can be enabled within the driver.
99
100 pvrusb2-debugifc.[ch] - This module implements a crude command line
101 oriented debug interface into the driver. Aside from being part
102 of the process for implementing manual firmware extraction (see
103 the pvrusb2 web site mentioned earlier), probably I'm the only one
104 who has ever used this. It is mainly a debugging aid.
105
106 pvrusb2-eeprom.[ch] - This is glue logic that resides between this
107 driver the tveeprom.ko module, which is itself implemented
108 elsewhere in V4L.
109
110 pvrusb2-encoder.[ch] - This module implements all protocol needed to
111 interact with the Conexant mpeg2 encoder chip within the pvrusb2
112 device. It is a crude echo of corresponding logic in ivtv,
113 however the design goals (strict isolation) and physical layer
114 (proxy through USB instead of PCI) are enough different that this
115 implementation had to be completely different.
116
117 pvrusb2-hdw-internal.h - This header defines the core data structure
118 in the driver used to track ALL internal state related to control
119 of the hardware. Nobody outside of the core hardware-handling
120 modules should have any business using this header. All external
121 access to the driver should be through one of the high level
122 interfaces (e.g. V4L, sysfs, etc), and in fact even those high
123 level interfaces are restricted to the API defined in
124 pvrusb2-hdw.h and NOT this header.
125
126 pvrusb2-hdw.h - This header defines the full internal API for
127 controlling the hardware. High level interfaces (e.g. V4L, sysfs)
128 will work through here.
129
130 pvrusb2-hdw.c - This module implements all the various bits of logic
131 that handle overall control of a specific pvrusb2 device.
132 (Policy, instantiation, and arbitration of pvrusb2 devices fall
133 within the jurisdiction of pvrusb-context not here).
134
135 pvrusb2-i2c-chips-*.c - These modules implement the glue logic to
136 tie together and configure various I2C modules as they attach to
137 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
139 implement just the logic that makes sense for a pure V4L
140 environment. The "all" version is intended for use outside of
141 V4L, where we might encounter other possibly "challenging" modules
142 from ivtv or older kernel snapshots (or even the support modules
143 in the standalone snapshot).
144
145 pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1
146 compatible commands to the I2C modules. It is here where state
147 changes inside the pvrusb2 driver are translated into V4L1
148 commands that are in turn send to the various I2C modules.
149
150 pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2
151 compatible commands to the I2C modules. It is here where state
152 changes inside the pvrusb2 driver are translated into V4L2
153 commands that are in turn send to the various I2C modules.
154
155 pvrusb2-i2c-core.[ch] - This module provides an implementation of a
156 kernel-friendly I2C adaptor driver, through which other external
157 I2C client drivers (e.g. msp3400, tuner, lirc) may connect and
158 operate corresponding chips within the pvrusb2 device. It is
159 through here that other V4L modules can reach into this driver to
160 operate specific pieces (and those modules are in turn driven by
161 glue logic which is coordinated by pvrusb2-hdw, doled out by
162 pvrusb2-context, and then ultimately made available to users
163 through one of the high level interfaces).
164
165 pvrusb2-io.[ch] - This module implements a very low level ring of
166 transfer buffers, required in order to stream data from the
167 device. This module is *very* low level. It only operates the
168 buffers and makes no attempt to define any policy or mechanism for
169 how such buffers might be used.
170
171 pvrusb2-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
173 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
175 other styles of I/O to be implemented with additonal modules, like
176 mmap()'ed buffers or something even more exotic.
177
178 pvrusb2-main.c - This is the top level of the driver. Module level
179 and USB core entry points are here. This is our "main".
180
181 pvrusb2-sysfs.[ch] - This is the high level interface which ties the
182 pvrusb2 driver into sysfs. Through this interface you can do
183 everything with the driver except actually stream data.
184
185 pvrusb2-tuner.[ch] - This is glue logic that resides between this
186 driver and the tuner.ko I2C client driver (which is found
187 elsewhere in V4L).
188
189 pvrusb2-util.h - This header defines some common macros used
190 throughout the driver. These macros are not really specific to
191 the driver, but they had to go somewhere.
192
193 pvrusb2-v4l2.[ch] - This is the high level interface which ties the
194 pvrusb2 driver into video4linux. It is through here that V4L
195 applications can open and operate the driver in the usual V4L
196 ways. Note that **ALL** V4L functionality is published only
197 through here and nowhere else.
198
199 pvrusb2-video-*.[ch] - This is glue logic that resides between this
200 driver and the saa711x.ko I2C client driver (which is found
201 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
203 selected depending on the particular saa711[5x].ko that is found.
204
205 pvrusb2.h - This header contains compile time tunable parameters
206 (and at the moment the driver has very little that needs to be
207 tuned).
208
209
210 -Mike Isely
211 isely@pobox.com
212
213
README.saa7134
1
2
3What is it?
4===========
5
6This is a v4l2/oss device driver for saa7130/33/34/35 based capture / TV
7boards. See http://www.semiconductors.philips.com/pip/saa7134hl for a
8description.
9
10
11Status
12======
13
14Almost everything is working. video, sound, tuner, radio, mpeg ts, ...
15
16As with bttv, card-specific tweaks are needed. Check CARDLIST for a
17list of known TV cards and saa7134-cards.c for the drivers card
18configuration info.
19
20
21Build
22=====
23
24Pick up videodev + v4l2 patches from http://bytesex.org/patches/.
25Configure, build, install + boot the new kernel. You'll need at least
26these config options:
27
28 CONFIG_I2C=m
29 CONFIG_VIDEO_DEV=m
30
31Type "make" to build the driver now. "make install" installs the
32driver. "modprobe saa7134" should load it. Depending on the card you
33might have to pass card=<nr> as insmod option, check CARDLIST for
34valid choices.
35
36
37Changes / Fixes
38===============
39
40Please mail me unified diffs ("diff -u") with your changes, and don't
41forget to tell me what it changes / which problem it fixes / whatever
42it is good for ...
43
44
45Known Problems
46==============
47
48* The tuner for the flyvideos isn't detected automatically and the
49 default might not work for you depending on which version you have.
50 There is a tuner= insmod option to override the driver's default.
51
52Card Variations:
53================
54
55Cards can use either of these two crystals (xtal):
56 - 32.11 MHz -> .audio_clock=0x187de7
57 - 24.576MHz -> .audio_clock=0x200000
58(xtal * .audio_clock = 51539600)
59
60Some details about 30/34/35:
61
62 - saa7130 - low-price chip, doesn't have mute, that is why all those
63 cards should have .mute field defined in their tuner structure.
64
65 - saa7134 - usual chip
66
67 - saa7133/35 - saa7135 is probably a marketing decision, since all those
68 chips identifies itself as 33 on pci.
69
70Credits
71=======
72
73andrew.stevens@philips.com + werner.leeb@philips.com for providing
74saa7134 hardware specs and sample board.
75
76
77Have fun,
78
79 Gerd
80
81--
82Gerd Knorr <kraxel@bytesex.org> [SuSE Labs]
83