aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorDavid S. Miller <davem@davemloft.net>2008-11-11 18:43:02 -0500
committerDavid S. Miller <davem@davemloft.net>2008-11-11 18:43:02 -0500
commit7e452baf6b96b5aeba097afd91501d33d390cc97 (patch)
tree9b0e062d3677d50d731ffd0fba47423bfdee9253 /Documentation
parent3ac38c3a2e7dac3f8f35a56eb85c27881a4c3833 (diff)
parentf21f237cf55494c3a4209de323281a3b0528da10 (diff)
Merge branch 'master' of master.kernel.org:/pub/scm/linux/kernel/git/davem/net-2.6
Conflicts: drivers/message/fusion/mptlan.c drivers/net/sfc/ethtool.c net/mac80211/debugfs_sta.c
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/feature-removal-schedule.txt24
-rw-r--r--Documentation/ftrace.txt171
-rw-r--r--Documentation/powerpc/booting-without-of.txt65
-rw-r--r--Documentation/video4linux/README.cx884
-rw-r--r--Documentation/video4linux/si470x.txt118
5 files changed, 203 insertions, 179 deletions
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt
index 6ecd4f0a24f0..77eb6b129dde 100644
--- a/Documentation/feature-removal-schedule.txt
+++ b/Documentation/feature-removal-schedule.txt
@@ -56,30 +56,6 @@ Who: Mauro Carvalho Chehab <mchehab@infradead.org>
56 56
57--------------------------- 57---------------------------
58 58
59What: old tuner-3036 i2c driver
60When: 2.6.28
61Why: This driver is for VERY old i2c-over-parallel port teletext receiver
62 boxes. Rather then spending effort on converting this driver to V4L2,
63 and since it is extremely unlikely that anyone still uses one of these
64 devices, it was decided to drop it.
65Who: Hans Verkuil <hverkuil@xs4all.nl>
66 Mauro Carvalho Chehab <mchehab@infradead.org>
67
68 ---------------------------
69
70What: V4L2 dpc7146 driver
71When: 2.6.28
72Why: Old driver for the dpc7146 demonstration board that is no longer
73 relevant. The last time this was tested on actual hardware was
74 probably around 2002. Since this is a driver for a demonstration
75 board the decision was made to remove it rather than spending a
76 lot of effort continually updating this driver to stay in sync
77 with the latest internal V4L2 or I2C API.
78Who: Hans Verkuil <hverkuil@xs4all.nl>
79 Mauro Carvalho Chehab <mchehab@infradead.org>
80
81---------------------------
82
83What: PCMCIA control ioctl (needed for pcmcia-cs [cardmgr, cardctl]) 59What: PCMCIA control ioctl (needed for pcmcia-cs [cardmgr, cardctl])
84When: November 2005 60When: November 2005
85Files: drivers/pcmcia/: pcmcia_ioctl.c 61Files: drivers/pcmcia/: pcmcia_ioctl.c
diff --git a/Documentation/ftrace.txt b/Documentation/ftrace.txt
index ea5a827395dd..9cc4d685dde5 100644
--- a/Documentation/ftrace.txt
+++ b/Documentation/ftrace.txt
@@ -8,7 +8,7 @@ Copyright 2008 Red Hat Inc.
8Reviewers: Elias Oltmanns, Randy Dunlap, Andrew Morton, 8Reviewers: Elias Oltmanns, Randy Dunlap, Andrew Morton,
9 John Kacur, and David Teigland. 9 John Kacur, and David Teigland.
10 10
11Written for: 2.6.27-rc1 11Written for: 2.6.28-rc2
12 12
13Introduction 13Introduction
14------------ 14------------
@@ -50,26 +50,26 @@ of ftrace. Here is a list of some of the key files:
50 50
51 Note: all time values are in microseconds. 51 Note: all time values are in microseconds.
52 52
53 current_tracer : This is used to set or display the current tracer 53 current_tracer: This is used to set or display the current tracer
54 that is configured. 54 that is configured.
55 55
56 available_tracers : This holds the different types of tracers that 56 available_tracers: This holds the different types of tracers that
57 have been compiled into the kernel. The tracers 57 have been compiled into the kernel. The tracers
58 listed here can be configured by echoing their name 58 listed here can be configured by echoing their name
59 into current_tracer. 59 into current_tracer.
60 60
61 tracing_enabled : This sets or displays whether the current_tracer 61 tracing_enabled: This sets or displays whether the current_tracer
62 is activated and tracing or not. Echo 0 into this 62 is activated and tracing or not. Echo 0 into this
63 file to disable the tracer or 1 to enable it. 63 file to disable the tracer or 1 to enable it.
64 64
65 trace : This file holds the output of the trace in a human readable 65 trace: This file holds the output of the trace in a human readable
66 format (described below). 66 format (described below).
67 67
68 latency_trace : This file shows the same trace but the information 68 latency_trace: This file shows the same trace but the information
69 is organized more to display possible latencies 69 is organized more to display possible latencies
70 in the system (described below). 70 in the system (described below).
71 71
72 trace_pipe : The output is the same as the "trace" file but this 72 trace_pipe: The output is the same as the "trace" file but this
73 file is meant to be streamed with live tracing. 73 file is meant to be streamed with live tracing.
74 Reads from this file will block until new data 74 Reads from this file will block until new data
75 is retrieved. Unlike the "trace" and "latency_trace" 75 is retrieved. Unlike the "trace" and "latency_trace"
@@ -82,11 +82,11 @@ of ftrace. Here is a list of some of the key files:
82 tracer is not adding more data, they will display 82 tracer is not adding more data, they will display
83 the same information every time they are read. 83 the same information every time they are read.
84 84
85 iter_ctrl : This file lets the user control the amount of data 85 iter_ctrl: This file lets the user control the amount of data
86 that is displayed in one of the above output 86 that is displayed in one of the above output
87 files. 87 files.
88 88
89 trace_max_latency : Some of the tracers record the max latency. 89 trace_max_latency: Some of the tracers record the max latency.
90 For example, the time interrupts are disabled. 90 For example, the time interrupts are disabled.
91 This time is saved in this file. The max trace 91 This time is saved in this file. The max trace
92 will also be stored, and displayed by either 92 will also be stored, and displayed by either
@@ -94,29 +94,26 @@ of ftrace. Here is a list of some of the key files:
94 only be recorded if the latency is greater than 94 only be recorded if the latency is greater than
95 the value in this file. (in microseconds) 95 the value in this file. (in microseconds)
96 96
97 trace_entries : This sets or displays the number of trace 97 trace_entries: This sets or displays the number of bytes each CPU
98 entries each CPU buffer can hold. The tracer buffers 98 buffer can hold. The tracer buffers are the same size
99 are the same size for each CPU. The displayed number 99 for each CPU. The displayed number is the size of the
100 is the size of the CPU buffer and not total size. The 100 CPU buffer and not total size of all buffers. The
101 trace buffers are allocated in pages (blocks of memory 101 trace buffers are allocated in pages (blocks of memory
102 that the kernel uses for allocation, usually 4 KB in size). 102 that the kernel uses for allocation, usually 4 KB in size).
103 Since each entry is smaller than a page, if the last 103 If the last page allocated has room for more bytes
104 allocated page has room for more entries than were 104 than requested, the rest of the page will be used,
105 requested, the rest of the page is used to allocate 105 making the actual allocation bigger than requested.
106 entries. 106 (Note, the size may not be a multiple of the page size due
107 to buffer managment overhead.)
107 108
108 This can only be updated when the current_tracer 109 This can only be updated when the current_tracer
109 is set to "none". 110 is set to "nop".
110 111
111 NOTE: It is planned on changing the allocated buffers 112 tracing_cpumask: This is a mask that lets the user only trace
112 from being the number of possible CPUS to
113 the number of online CPUS.
114
115 tracing_cpumask : This is a mask that lets the user only trace
116 on specified CPUS. The format is a hex string 113 on specified CPUS. The format is a hex string
117 representing the CPUS. 114 representing the CPUS.
118 115
119 set_ftrace_filter : When dynamic ftrace is configured in (see the 116 set_ftrace_filter: When dynamic ftrace is configured in (see the
120 section below "dynamic ftrace"), the code is dynamically 117 section below "dynamic ftrace"), the code is dynamically
121 modified (code text rewrite) to disable calling of the 118 modified (code text rewrite) to disable calling of the
122 function profiler (mcount). This lets tracing be configured 119 function profiler (mcount). This lets tracing be configured
@@ -130,14 +127,11 @@ of ftrace. Here is a list of some of the key files:
130 be traced. If a function exists in both set_ftrace_filter 127 be traced. If a function exists in both set_ftrace_filter
131 and set_ftrace_notrace, the function will _not_ be traced. 128 and set_ftrace_notrace, the function will _not_ be traced.
132 129
133 available_filter_functions : When a function is encountered the first 130 available_filter_functions: This lists the functions that ftrace
134 time by the dynamic tracer, it is recorded and 131 has processed and can trace. These are the function
135 later the call is converted into a nop. This file 132 names that you can pass to "set_ftrace_filter" or
136 lists the functions that have been recorded 133 "set_ftrace_notrace". (See the section "dynamic ftrace"
137 by the dynamic tracer and these functions can 134 below for more details.)
138 be used to set the ftrace filter by the above
139 "set_ftrace_filter" file. (See the section "dynamic ftrace"
140 below for more details).
141 135
142 136
143The Tracers 137The Tracers
@@ -145,7 +139,7 @@ The Tracers
145 139
146Here is the list of current tracers that may be configured. 140Here is the list of current tracers that may be configured.
147 141
148 ftrace - function tracer that uses mcount to trace all functions. 142 function - function tracer that uses mcount to trace all functions.
149 143
150 sched_switch - traces the context switches between tasks. 144 sched_switch - traces the context switches between tasks.
151 145
@@ -166,8 +160,8 @@ Here is the list of current tracers that may be configured.
166 the highest priority task to get scheduled after 160 the highest priority task to get scheduled after
167 it has been woken up. 161 it has been woken up.
168 162
169 none - This is not a tracer. To remove all tracers from tracing 163 nop - This is not a tracer. To remove all tracers from tracing
170 simply echo "none" into current_tracer. 164 simply echo "nop" into current_tracer.
171 165
172 166
173Examples of using the tracer 167Examples of using the tracer
@@ -182,7 +176,7 @@ Output format:
182Here is an example of the output format of the file "trace" 176Here is an example of the output format of the file "trace"
183 177
184 -------- 178 --------
185# tracer: ftrace 179# tracer: function
186# 180#
187# TASK-PID CPU# TIMESTAMP FUNCTION 181# TASK-PID CPU# TIMESTAMP FUNCTION
188# | | | | | 182# | | | | |
@@ -192,7 +186,7 @@ Here is an example of the output format of the file "trace"
192 -------- 186 --------
193 187
194A header is printed with the tracer name that is represented by the trace. 188A header is printed with the tracer name that is represented by the trace.
195In this case the tracer is "ftrace". Then a header showing the format. Task 189In this case the tracer is "function". Then a header showing the format. Task
196name "bash", the task PID "4251", the CPU that it was running on 190name "bash", the task PID "4251", the CPU that it was running on
197"01", the timestamp in <secs>.<usecs> format, the function name that was 191"01", the timestamp in <secs>.<usecs> format, the function name that was
198traced "path_put" and the parent function that called this function 192traced "path_put" and the parent function that called this function
@@ -1003,22 +997,20 @@ is the stack for the hard interrupt. This hides the fact that NEED_RESCHED
1003has been set. We do not see the 'N' until we switch back to the task's 997has been set. We do not see the 'N' until we switch back to the task's
1004assigned stack. 998assigned stack.
1005 999
1006ftrace 1000function
1007------ 1001--------
1008 1002
1009ftrace is not only the name of the tracing infrastructure, but it 1003This tracer is the function tracer. Enabling the function tracer
1010is also a name of one of the tracers. The tracer is the function 1004can be done from the debug file system. Make sure the ftrace_enabled is
1011tracer. Enabling the function tracer can be done from the 1005set; otherwise this tracer is a nop.
1012debug file system. Make sure the ftrace_enabled is set otherwise
1013this tracer is a nop.
1014 1006
1015 # sysctl kernel.ftrace_enabled=1 1007 # sysctl kernel.ftrace_enabled=1
1016 # echo ftrace > /debug/tracing/current_tracer 1008 # echo function > /debug/tracing/current_tracer
1017 # echo 1 > /debug/tracing/tracing_enabled 1009 # echo 1 > /debug/tracing/tracing_enabled
1018 # usleep 1 1010 # usleep 1
1019 # echo 0 > /debug/tracing/tracing_enabled 1011 # echo 0 > /debug/tracing/tracing_enabled
1020 # cat /debug/tracing/trace 1012 # cat /debug/tracing/trace
1021# tracer: ftrace 1013# tracer: function
1022# 1014#
1023# TASK-PID CPU# TIMESTAMP FUNCTION 1015# TASK-PID CPU# TIMESTAMP FUNCTION
1024# | | | | | 1016# | | | | |
@@ -1040,10 +1032,10 @@ this tracer is a nop.
1040[...] 1032[...]
1041 1033
1042 1034
1043Note: ftrace uses ring buffers to store the above entries. The newest data 1035Note: function tracer uses ring buffers to store the above entries.
1044may overwrite the oldest data. Sometimes using echo to stop the trace 1036The newest data may overwrite the oldest data. Sometimes using echo to
1045is not sufficient because the tracing could have overwritten the data 1037stop the trace is not sufficient because the tracing could have overwritten
1046that you wanted to record. For this reason, it is sometimes better to 1038the data that you wanted to record. For this reason, it is sometimes better to
1047disable tracing directly from a program. This allows you to stop the 1039disable tracing directly from a program. This allows you to stop the
1048tracing at the point that you hit the part that you are interested in. 1040tracing at the point that you hit the part that you are interested in.
1049To disable the tracing directly from a C program, something like following 1041To disable the tracing directly from a C program, something like following
@@ -1077,18 +1069,31 @@ every kernel function, produced by the -pg switch in gcc), starts
1077of pointing to a simple return. (Enabling FTRACE will include the 1069of pointing to a simple return. (Enabling FTRACE will include the
1078-pg switch in the compiling of the kernel.) 1070-pg switch in the compiling of the kernel.)
1079 1071
1080When dynamic ftrace is initialized, it calls kstop_machine to make 1072At compile time every C file object is run through the
1081the machine act like a uniprocessor so that it can freely modify code 1073recordmcount.pl script (located in the scripts directory). This
1082without worrying about other processors executing that same code. At 1074script will process the C object using objdump to find all the
1083initialization, the mcount calls are changed to call a "record_ip" 1075locations in the .text section that call mcount. (Note, only
1084function. After this, the first time a kernel function is called, 1076the .text section is processed, since processing other sections
1085it has the calling address saved in a hash table. 1077like .init.text may cause races due to those sections being freed).
1086 1078
1087Later on the ftraced kernel thread is awoken and will again call 1079A new section called "__mcount_loc" is created that holds references
1088kstop_machine if new functions have been recorded. The ftraced thread 1080to all the mcount call sites in the .text section. This section is
1089will change all calls to mcount to "nop". Just calling mcount 1081compiled back into the original object. The final linker will add
1090and having mcount return has shown a 10% overhead. By converting 1082all these references into a single table.
1091it to a nop, there is no measurable overhead to the system. 1083
1084On boot up, before SMP is initialized, the dynamic ftrace code
1085scans this table and updates all the locations into nops. It also
1086records the locations, which are added to the available_filter_functions
1087list. Modules are processed as they are loaded and before they are
1088executed. When a module is unloaded, it also removes its functions from
1089the ftrace function list. This is automatic in the module unload
1090code, and the module author does not need to worry about it.
1091
1092When tracing is enabled, kstop_machine is called to prevent races
1093with the CPUS executing code being modified (which can cause the
1094CPU to do undesireable things), and the nops are patched back
1095to calls. But this time, they do not call mcount (which is just
1096a function stub). They now call into the ftrace infrastructure.
1092 1097
1093One special side-effect to the recording of the functions being 1098One special side-effect to the recording of the functions being
1094traced is that we can now selectively choose which functions we 1099traced is that we can now selectively choose which functions we
@@ -1251,36 +1256,6 @@ Produces:
1251 1256
1252We can see that there's no more lock or preempt tracing. 1257We can see that there's no more lock or preempt tracing.
1253 1258
1254ftraced
1255-------
1256
1257As mentioned above, when dynamic ftrace is configured in, a kernel
1258thread wakes up once a second and checks to see if there are mcount
1259calls that need to be converted into nops. If there are not any, then
1260it simply goes back to sleep. But if there are some, it will call
1261kstop_machine to convert the calls to nops.
1262
1263There may be a case in which you do not want this added latency.
1264Perhaps you are doing some audio recording and this activity might
1265cause skips in the playback. There is an interface to disable
1266and enable the "ftraced" kernel thread.
1267
1268 # echo 0 > /debug/tracing/ftraced_enabled
1269
1270This will disable the calling of kstop_machine to update the
1271mcount calls to nops. Remember that there is a large overhead
1272to calling mcount. Without this kernel thread, that overhead will
1273exist.
1274
1275If there are recorded calls to mcount, any write to the ftraced_enabled
1276file will cause the kstop_machine to run. This means that a
1277user can manually perform the updates when they want to by simply
1278echoing a '0' into the ftraced_enabled file.
1279
1280The updates are also done at the beginning of enabling a tracer
1281that uses ftrace function recording.
1282
1283
1284trace_pipe 1259trace_pipe
1285---------- 1260----------
1286 1261
@@ -1289,14 +1264,14 @@ on the tracing is different. Every read from trace_pipe is consumed.
1289This means that subsequent reads will be different. The trace 1264This means that subsequent reads will be different. The trace
1290is live. 1265is live.
1291 1266
1292 # echo ftrace > /debug/tracing/current_tracer 1267 # echo function > /debug/tracing/current_tracer
1293 # cat /debug/tracing/trace_pipe > /tmp/trace.out & 1268 # cat /debug/tracing/trace_pipe > /tmp/trace.out &
1294[1] 4153 1269[1] 4153
1295 # echo 1 > /debug/tracing/tracing_enabled 1270 # echo 1 > /debug/tracing/tracing_enabled
1296 # usleep 1 1271 # usleep 1
1297 # echo 0 > /debug/tracing/tracing_enabled 1272 # echo 0 > /debug/tracing/tracing_enabled
1298 # cat /debug/tracing/trace 1273 # cat /debug/tracing/trace
1299# tracer: ftrace 1274# tracer: function
1300# 1275#
1301# TASK-PID CPU# TIMESTAMP FUNCTION 1276# TASK-PID CPU# TIMESTAMP FUNCTION
1302# | | | | | 1277# | | | | |
@@ -1317,7 +1292,7 @@ is live.
1317 1292
1318Note, reading the trace_pipe file will block until more input is added. 1293Note, reading the trace_pipe file will block until more input is added.
1319By changing the tracer, trace_pipe will issue an EOF. We needed 1294By changing the tracer, trace_pipe will issue an EOF. We needed
1320to set the ftrace tracer _before_ cating the trace_pipe file. 1295to set the function tracer _before_ we "cat" the trace_pipe file.
1321 1296
1322 1297
1323trace entries 1298trace entries
@@ -1334,10 +1309,10 @@ number of entries.
133465620 130965620
1335 1310
1336Note, to modify this, you must have tracing completely disabled. To do that, 1311Note, to modify this, you must have tracing completely disabled. To do that,
1337echo "none" into the current_tracer. If the current_tracer is not set 1312echo "nop" into the current_tracer. If the current_tracer is not set
1338to "none", an EINVAL error will be returned. 1313to "nop", an EINVAL error will be returned.
1339 1314
1340 # echo none > /debug/tracing/current_tracer 1315 # echo nop > /debug/tracing/current_tracer
1341 # echo 100000 > /debug/tracing/trace_entries 1316 # echo 100000 > /debug/tracing/trace_entries
1342 # cat /debug/tracing/trace_entries 1317 # cat /debug/tracing/trace_entries
1343100045 1318100045
diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt
index 02ea9a971b8e..0ab0230cbcb0 100644
--- a/Documentation/powerpc/booting-without-of.txt
+++ b/Documentation/powerpc/booting-without-of.txt
@@ -41,25 +41,14 @@ Table of Contents
41 VI - System-on-a-chip devices and nodes 41 VI - System-on-a-chip devices and nodes
42 1) Defining child nodes of an SOC 42 1) Defining child nodes of an SOC
43 2) Representing devices without a current OF specification 43 2) Representing devices without a current OF specification
44 a) MDIO IO device 44 a) PHY nodes
45 b) Gianfar-compatible ethernet nodes 45 b) Interrupt controllers
46 c) PHY nodes 46 c) CFI or JEDEC memory-mapped NOR flash
47 d) Interrupt controllers 47 d) 4xx/Axon EMAC ethernet nodes
48 e) I2C 48 e) Xilinx IP cores
49 f) Freescale SOC USB controllers 49 f) USB EHCI controllers
50 g) Freescale SOC SEC Security Engines 50 g) MDIO on GPIOs
51 h) Board Control and Status (BCSR) 51 h) SPI busses
52 i) Freescale QUICC Engine module (QE)
53 j) CFI or JEDEC memory-mapped NOR flash
54 k) Global Utilities Block
55 l) Freescale Communications Processor Module
56 m) Chipselect/Local Bus
57 n) 4xx/Axon EMAC ethernet nodes
58 o) Xilinx IP cores
59 p) Freescale Synchronous Serial Interface
60 q) USB EHCI controllers
61 r) MDIO on GPIOs
62 s) SPI busses
63 52
64 VII - Marvell Discovery mv64[345]6x System Controller chips 53 VII - Marvell Discovery mv64[345]6x System Controller chips
65 1) The /system-controller node 54 1) The /system-controller node
@@ -1830,41 +1819,7 @@ platforms are moved over to use the flattened-device-tree model.
1830 big-endian; 1819 big-endian;
1831 }; 1820 };
1832 1821
1833 r) Freescale Display Interface Unit 1822 g) MDIO on GPIOs
1834
1835 The Freescale DIU is a LCD controller, with proper hardware, it can also
1836 drive DVI monitors.
1837
1838 Required properties:
1839 - compatible : should be "fsl-diu".
1840 - reg : should contain at least address and length of the DIU register
1841 set.
1842 - Interrupts : one DIU interrupt should be describe here.
1843
1844 Example (MPC8610HPCD)
1845 display@2c000 {
1846 compatible = "fsl,diu";
1847 reg = <0x2c000 100>;
1848 interrupts = <72 2>;
1849 interrupt-parent = <&mpic>;
1850 };
1851
1852 s) Freescale on board FPGA
1853
1854 This is the memory-mapped registers for on board FPGA.
1855
1856 Required properities:
1857 - compatible : should be "fsl,fpga-pixis".
1858 - reg : should contain the address and the lenght of the FPPGA register
1859 set.
1860
1861 Example (MPC8610HPCD)
1862 board-control@e8000000 {
1863 compatible = "fsl,fpga-pixis";
1864 reg = <0xe8000000 32>;
1865 };
1866
1867 r) MDIO on GPIOs
1868 1823
1869 Currently defined compatibles: 1824 Currently defined compatibles:
1870 - virtual,gpio-mdio 1825 - virtual,gpio-mdio
@@ -1884,7 +1839,7 @@ platforms are moved over to use the flattened-device-tree model.
1884 &qe_pio_c 6>; 1839 &qe_pio_c 6>;
1885 }; 1840 };
1886 1841
1887 s) SPI (Serial Peripheral Interface) busses 1842 h) SPI (Serial Peripheral Interface) busses
1888 1843
1889 SPI busses can be described with a node for the SPI master device 1844 SPI busses can be described with a node for the SPI master device
1890 and a set of child nodes for each SPI slave on the bus. For this 1845 and a set of child nodes for each SPI slave on the bus. For this
diff --git a/Documentation/video4linux/README.cx88 b/Documentation/video4linux/README.cx88
index 06a33a4f52fd..166d5960b1a9 100644
--- a/Documentation/video4linux/README.cx88
+++ b/Documentation/video4linux/README.cx88
@@ -27,8 +27,8 @@ audio
27 sound card) should be possible, but there is no code yet ... 27 sound card) should be possible, but there is no code yet ...
28 28
29vbi 29vbi
30 - some code present. Doesn't crash any more, but also doesn't 30 - Code present. Works for NTSC closed caption. PAL and other
31 work yet ... 31 TV norms may or may not work.
32 32
33 33
34how to add support for new cards 34how to add support for new cards
diff --git a/Documentation/video4linux/si470x.txt b/Documentation/video4linux/si470x.txt
new file mode 100644
index 000000000000..11c5fd22a332
--- /dev/null
+++ b/Documentation/video4linux/si470x.txt
@@ -0,0 +1,118 @@
1Driver for USB radios for the Silicon Labs Si470x FM Radio Receivers
2
3Copyright (c) 2008 Tobias Lorenz <tobias.lorenz@gmx.net>
4
5
6Information from Silicon Labs
7=============================
8Silicon Laboratories is the manufacturer of the radio ICs, that nowadays are the
9most often used radio receivers in cell phones. Usually they are connected with
10I2C. But SiLabs also provides a reference design, which integrates this IC,
11together with a small microcontroller C8051F321, to form a USB radio.
12Part of this reference design is also a radio application in binary and source
13code. The software also contains an automatic firmware upgrade to the most
14current version. Information on these can be downloaded here:
15http://www.silabs.com/usbradio
16
17
18Supported ICs
19=============
20The following ICs have a very similar register set, so that they are or will be
21supported somewhen by the driver:
22- Si4700: FM radio receiver
23- Si4701: FM radio receiver, RDS Support
24- Si4702: FM radio receiver
25- Si4703: FM radio receiver, RDS Support
26- Si4704: FM radio receiver, no external antenna required
27- Si4705: FM radio receiver, no external antenna required, RDS support, Dig I/O
28- Si4706: Enhanced FM RDS/TMC radio receiver, no external antenna required, RDS
29 Support
30- Si4707: Dedicated weather band radio receiver with SAME decoder, RDS Support
31- Si4708: Smallest FM receivers
32- Si4709: Smallest FM receivers, RDS Support
33More information on these can be downloaded here:
34http://www.silabs.com/products/mcu/Pages/USBFMRadioRD.aspx
35
36
37Supported USB devices
38=====================
39Currently the following USB radios (vendor:product) with the Silicon Labs si470x
40chips are known to work:
41- 10c4:818a: Silicon Labs USB FM Radio Reference Design
42- 06e1:a155: ADS/Tech FM Radio Receiver (formerly Instant FM Music) (RDX-155-EF)
43- 1b80:d700: KWorld USB FM Radio SnapMusic Mobile 700 (FM700)
44
45
46Software
47========
48Testing is usually done with most application under Debian/testing:
49- fmtools - Utility for managing FM tuner cards
50- gnomeradio - FM-radio tuner for the GNOME desktop
51- gradio - GTK FM radio tuner
52- kradio - Comfortable Radio Application for KDE
53- radio - ncurses-based radio application
54
55There is also a library libv4l, which can be used. It's going to have a function
56for frequency seeking, either by using hardware functionality as in radio-si470x
57or by implementing a function as we currently have in every of the mentioned
58programs. Somewhen the radio programs should make use of libv4l.
59
60For processing RDS information, there is a project ongoing at:
61http://rdsd.berlios.de/
62
63There is currently no project for making TMC sentences human readable.
64
65
66Audio Listing
67=============
68USB Audio is provided by the ALSA snd_usb_audio module. It is recommended to
69also select SND_USB_AUDIO, as this is required to get sound from the radio. For
70listing you have to redirect the sound, for example using one of the following
71commands.
72
73If you just want to test audio (very poor quality):
74cat /dev/dsp1 > /dev/dsp
75
76If you use OSS try:
77sox -2 --endian little -r 96000 -t oss /dev/dsp1 -t oss /dev/dsp
78
79If you use arts try:
80arecord -D hw:1,0 -r96000 -c2 -f S16_LE | artsdsp aplay -B -
81
82
83Module Parameters
84=================
85After loading the module, you still have access to some of them in the sysfs
86mount under /sys/module/radio_si470x/parameters. The contents of read-only files
87(0444) are not updated, even if space, band and de are changed using private
88video controls. The others are runtime changeable.
89
90
91Errors
92======
93Increase tune_timeout, if you often get -EIO errors.
94
95When timed out or band limit is reached, hw_freq_seek returns -EAGAIN.
96
97If you get any errors from snd_usb_audio, please report them to the ALSA people.
98
99
100Open Issues
101===========
102V4L minor device allocation and parameter setting is not perfect. A solution is
103currently under discussion.
104
105There is an USB interface for downloading/uploading new firmware images. Support
106for it can be implemented using the request_firmware interface.
107
108There is a RDS interrupt mode. The driver is already using the same interface
109for polling RDS information, but is currently not using the interrupt mode.
110
111There is a LED interface, which can be used to override the LED control
112programmed in the firmware. This can be made available using the LED support
113functions in the kernel.
114
115
116Other useful information and links
117==================================
118http://www.silabs.com/usbradio