From 1668be71ccae5a9610fc8a224bd80fbe852f93ae Mon Sep 17 00:00:00 2001 From: David Brownell Date: Wed, 11 Apr 2007 23:28:42 -0700 Subject: [PATCH] doc: gpio.txt describes open-drain emulation Update the GPIO docs to describe the idiom whereby open drain signals are emulated by toggling the GPIO direction. Signed-off-by: David Brownell Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/gpio.txt | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt index 989f1130f4f..f8528db967f 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio.txt @@ -27,7 +27,7 @@ The exact capabilities of GPIOs vary between systems. Common options: - Output values are writable (high=1, low=0). Some chips also have options about how that value is driven, so that for example only one value might be driven ... supporting "wire-OR" and similar schemes - for the other value. + for the other value (notably, "open drain" signaling). - Input values are likewise readable (1, 0). Some chips support readback of pins configured as "output", which is very useful in such "wire-OR" @@ -247,6 +247,35 @@ with gpio_get_value(), for example to initialize or update driver state when the IRQ is edge-triggered. +Emulating Open Drain Signals +---------------------------- +Sometimes shared signals need to use "open drain" signaling, where only the +low signal level is actually driven. (That term applies to CMOS transistors; +"open collector" is used for TTL.) A pullup resistor causes the high signal +level. This is sometimes called a "wire-AND"; or more practically, from the +negative logic (low=true) perspective this is a "wire-OR". + +One common example of an open drain signal is a shared active-low IRQ line. +Also, bidirectional data bus signals sometimes use open drain signals. + +Some GPIO controllers directly support open drain outputs; many don't. When +you need open drain signaling but your hardware doesn't directly support it, +there's a common idiom you can use to emulate it with any GPIO pin that can +be used as either an input or an output: + + LOW: gpio_direction_output(gpio, 0) ... this drives the signal + and overrides the pullup. + + HIGH: gpio_direction_input(gpio) ... this turns off the output, + so the pullup (or some other device) controls the signal. + +If you are "driving" the signal high but gpio_get_value(gpio) reports a low +value (after the appropriate rise time passes), you know some other component +is driving the shared signal low. That's not necessarily an error. As one +common example, that's how I2C clocks are stretched: a slave that needs a +slower clock delays the rising edge of SCK, and the I2C master adjusts its +signaling rate accordingly. + What do these conventions omit? =============================== -- cgit v1.2.3 From 9ce883becb83190061369940de9c415595836c9b Mon Sep 17 00:00:00 2001 From: Andi Kleen Date: Tue, 24 Apr 2007 13:05:37 +0200 Subject: [PATCH] x86: Remove noreplacement option noreplacement is dangerous on modern systems because it will not replace the context switch FNSAVE with SSE aware FXSAVE. But other places in the kernel still assume SSE and do FXSAVE and the CPU will then access FXSAVE information with FNSAVE and cause corruption. Easiest way to avoid this is to remove the option. It was mostly for paranoia reasons anyways and alternative()s have been stable for some time. Thanks to Jeremy F. for reporting and helping debug it. Signed-off-by: Andi Kleen --- Documentation/x86_64/boot-options.txt | 4 ---- 1 file changed, 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/x86_64/boot-options.txt b/Documentation/x86_64/boot-options.txt index 625a21db0c2..85f51e5a749 100644 --- a/Documentation/x86_64/boot-options.txt +++ b/Documentation/x86_64/boot-options.txt @@ -293,7 +293,3 @@ Debugging stuck (default) Miscellaneous - - noreplacement Don't replace instructions with more appropriate ones - for the CPU. This may be useful on asymmetric MP systems - where some CPUs have less capabilities than others. -- cgit v1.2.3 From 0bcbc92629044b5403719f77fb015e9005b1f504 Mon Sep 17 00:00:00 2001 From: YOSHIFUJI Hideaki Date: Tue, 24 Apr 2007 14:58:30 -0700 Subject: [IPV6]: Disallow RH0 by default. A security issue is emerging. Disallow Routing Header Type 0 by default as we have been doing for IPv4. Note: We allow RH2 by default because it is harmless. Signed-off-by: YOSHIFUJI Hideaki Signed-off-by: David S. Miller --- Documentation/networking/ip-sysctl.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation') diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index d3aae1f9b4c..702d1d8dd04 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -851,6 +851,15 @@ accept_redirects - BOOLEAN Functional default: enabled if local forwarding is disabled. disabled if local forwarding is enabled. +accept_source_route - INTEGER + Accept source routing (routing extension header). + + > 0: Accept routing header. + = 0: Accept only routing header type 2. + < 0: Do not accept routing header. + + Default: 0 + autoconf - BOOLEAN Autoconfigure addresses using Prefix Information in Router Advertisements. -- cgit v1.2.3 From bd8031b49a9b05933fb1ec1c36620ed4e1e67793 Mon Sep 17 00:00:00 2001 From: Hal Rosenstock Date: Tue, 24 Apr 2007 21:30:38 -0700 Subject: IB/umad: Clarify documentation of transaction ID Signed-off-by: Hal Rosenstock Signed-off-by: Roland Dreier --- Documentation/infiniband/user_mad.txt | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'Documentation') diff --git a/Documentation/infiniband/user_mad.txt b/Documentation/infiniband/user_mad.txt index 750fe5e80eb..8ec54b974b6 100644 --- a/Documentation/infiniband/user_mad.txt +++ b/Documentation/infiniband/user_mad.txt @@ -91,6 +91,14 @@ Sending MADs if (ret != sizeof *mad + mad_length) perror("write"); +Transaction IDs + + Users of the umad devices can use the lower 32 bits of the + transaction ID field (that is, the least significant half of the + field in network byte order) in MADs being sent to match + request/response pairs. The upper 32 bits are reserved for use by + the kernel and will be overwritten before a MAD is sent. + Setting IsSM Capability Bit To set the IsSM capability bit for a port, simply open the -- cgit v1.2.3 From 127af0c44fc916908abd145914d65b9fe598bcd7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilpo=20J=C3=A4rvinen?= Date: Wed, 21 Feb 2007 23:16:38 -0800 Subject: [TCP] FRTO: Sysctl documentation for SACK enhanced version MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The description is overly verbose to avoid ambiguity between "SACK enabled" and "SACK enhanced FRTO" Signed-off-by: Ilpo Järvinen Signed-off-by: David S. Miller --- Documentation/networking/ip-sysctl.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 702d1d8dd04..719b4290731 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -183,7 +183,10 @@ tcp_frto - BOOLEAN Enables F-RTO, an enhanced recovery algorithm for TCP retransmission timeouts. It is particularly beneficial in wireless environments where packet loss is typically due to random radio interference - rather than intermediate router congestion. + rather than intermediate router congestion. If set to 1, basic + version is enabled. 2 enables SACK enhanced FRTO, which is + EXPERIMENTAL. The basic version can be used also when SACK is + enabled for a flow through tcp_sack sysctl. tcp_keepalive_time - INTEGER How often TCP sends out keepalive messages when keepalive is enabled. -- cgit v1.2.3 From 89808060b7a71376cc2ba8092d43b2010da465b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilpo=20J=C3=A4rvinen?= Date: Tue, 27 Feb 2007 10:10:55 -0800 Subject: [TCP] Sysctl documentation: tcp_frto_response MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In addition, fixed minor things in tcp_frto sysctl. Signed-off-by: Ilpo Järvinen Signed-off-by: David S. Miller --- Documentation/networking/ip-sysctl.txt | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 719b4290731..054c515bd72 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -179,15 +179,32 @@ tcp_fin_timeout - INTEGER because they eat maximum 1.5K of memory, but they tend to live longer. Cf. tcp_max_orphans. -tcp_frto - BOOLEAN +tcp_frto - INTEGER Enables F-RTO, an enhanced recovery algorithm for TCP retransmission timeouts. It is particularly beneficial in wireless environments where packet loss is typically due to random radio interference rather than intermediate router congestion. If set to 1, basic - version is enabled. 2 enables SACK enhanced FRTO, which is + version is enabled. 2 enables SACK enhanced F-RTO, which is EXPERIMENTAL. The basic version can be used also when SACK is enabled for a flow through tcp_sack sysctl. +tcp_frto_response - INTEGER + When F-RTO has detected that a TCP retransmission timeout was + spurious (i.e, the timeout would have been avoided had TCP set a + longer retransmission timeout), TCP has several options what to do + next. Possible values are: + 0 Rate halving based; a smooth and conservative response, + results in halved cwnd and ssthresh after one RTT + 1 Very conservative response; not recommended because even + though being valid, it interacts poorly with the rest of + Linux TCP, halves cwnd and ssthresh immediately + 2 Aggressive response; undoes congestion control measures + that are now known to be unnecessary (ignoring the + possibility of a lost retransmission that would require + TCP to be more cautious), cwnd and ssthresh are restored + to the values prior timeout + Default: 0 (rate halving based) + tcp_keepalive_time - INTEGER How often TCP sends out keepalive messages when keepalive is enabled. Default: 2hours. -- cgit v1.2.3 From a2a316fd068c455c609ecc155dcfaa7e208d29fe Mon Sep 17 00:00:00 2001 From: Stephen Hemminger Date: Thu, 8 Mar 2007 20:41:08 -0800 Subject: [NET]: Replace CONFIG_NET_DEBUG with sysctl. Covert network warning messages from a compile time to runtime choice. Removes kernel config option and replaces it with new /proc/sys/net/core/warnings. Signed-off-by: Stephen Hemminger Signed-off-by: David S. Miller --- Documentation/filesystems/proc.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation') diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 5484ab5efd4..7aaf09b86a5 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -1421,6 +1421,15 @@ fewer messages that will be written. Message_burst controls when messages will be dropped. The default settings limit warning messages to one every five seconds. +warnings +-------- + +This controls console messages from the networking stack that can occur because +of problems on the network like duplicate address or bad checksums. Normally, +this should be enabled, but if the problem persists the messages can be +disabled. + + netdev_max_backlog ------------------ -- cgit v1.2.3 From 587aa64163bb14f70098f450abab9410787fce9d Mon Sep 17 00:00:00 2001 From: Patrick McHardy Date: Wed, 14 Mar 2007 16:37:25 -0700 Subject: [NETFILTER]: Remove IPv4 only connection tracking/NAT Remove the obsolete IPv4 only connection tracking/NAT as scheduled in feature-removal-schedule. Signed-off-by: Patrick McHardy Signed-off-by: David S. Miller --- Documentation/feature-removal-schedule.txt | 9 --------- 1 file changed, 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 19b4c96b2a4..9817b60e70a 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -211,15 +211,6 @@ Who: Adrian Bunk --------------------------- -What: IPv4 only connection tracking/NAT/helpers -When: 2.6.22 -Why: The new layer 3 independant connection tracking replaces the old - IPv4 only version. After some stabilization of the new code the - old one will be removed. -Who: Patrick McHardy - ---------------------------- - What: ACPI hooks (X86_SPEEDSTEP_CENTRINO_ACPI) in speedstep-centrino driver When: December 2006 Why: Speedstep-centrino driver with ACPI hooks and acpi-cpufreq driver are -- cgit v1.2.3 From f2645101350c6db66f0a1e72648909cc411f2b38 Mon Sep 17 00:00:00 2001 From: Gerrit Renker Date: Tue, 20 Mar 2007 15:01:14 -0300 Subject: [CCID3]: Add documentation for socket options This updates the documentation on CCID3-specific options. Signed-off-by: Gerrit Renker Acked-by: Ian McDonald Signed-off-by: Arnaldo Carvalho de Melo Signed-off-by: David S. Miller --- Documentation/networking/dccp.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'Documentation') diff --git a/Documentation/networking/dccp.txt b/Documentation/networking/dccp.txt index 387482e46c4..4504cc59e40 100644 --- a/Documentation/networking/dccp.txt +++ b/Documentation/networking/dccp.txt @@ -57,6 +57,16 @@ DCCP_SOCKOPT_SEND_CSCOV is for the receiver and has a different meaning: it coverage value are also acceptable. The higher the number, the more restrictive this setting (see [RFC 4340, sec. 9.2.1]). +The following two options apply to CCID 3 exclusively and are getsockopt()-only. +In either case, a TFRC info struct (defined in ) is returned. +DCCP_SOCKOPT_CCID_RX_INFO + Returns a `struct tfrc_rx_info' in optval; the buffer for optval and + optlen must be set to at least sizeof(struct tfrc_rx_info). +DCCP_SOCKOPT_CCID_TX_INFO + Returns a `struct tfrc_tx_info' in optval; the buffer for optval and + optlen must be set to at least sizeof(struct tfrc_tx_info). + + Sysctl variables ================ Several DCCP default parameters can be managed by the following sysctls -- cgit v1.2.3 From 516299d2f5b6f9703b9b388faf91898dc636a678 Mon Sep 17 00:00:00 2001 From: Michael Milner Date: Thu, 12 Apr 2007 22:14:23 -0700 Subject: [NETFILTER]: bridge-nf: filter bridged IPv4/IPv6 encapsulated in pppoe traffic The attached patch by Michael Milner adds support for using iptables and ip6tables on bridged traffic encapsulated in ppoe frames, similar to what's already supported for vlan. Signed-off-by: Michael Milner Signed-off-by: Bart De Schuymer Signed-off-by: Patrick McHardy Signed-off-by: David S. Miller --- Documentation/networking/ip-sysctl.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 054c515bd72..af6a63ab902 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -1015,7 +1015,12 @@ bridge-nf-call-ip6tables - BOOLEAN Default: 1 bridge-nf-filter-vlan-tagged - BOOLEAN - 1 : pass bridged vlan-tagged ARP/IP traffic to arptables/iptables. + 1 : pass bridged vlan-tagged ARP/IP/IPv6 traffic to {arp,ip,ip6}tables. + 0 : disable this. + Default: 1 + +bridge-nf-filter-pppoe-tagged - BOOLEAN + 1 : pass bridged pppoe-tagged IP/IPv6 traffic to {ip,ip6}tables. 0 : disable this. Default: 1 -- cgit v1.2.3 From 9e101eab153073d8a1fc7ea22b20af65de8ab44b Mon Sep 17 00:00:00 2001 From: Johannes Berg Date: Mon, 23 Apr 2007 12:20:55 -0700 Subject: [WIRELESS]: Remove wext over netlink. As scheduled, this patch removes the pointless wext over netlink code. Signed-off-by: Johannes Berg Signed-off-by: John W. Linville Signed-off-by: David S. Miller --- Documentation/feature-removal-schedule.txt | 12 ------------ 1 file changed, 12 deletions(-) (limited to 'Documentation') diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 9817b60e70a..976c8a1bd7c 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -285,18 +285,6 @@ Who: Richard Purdie --------------------------- -What: Wireless extensions over netlink (CONFIG_NET_WIRELESS_RTNETLINK) -When: with the merge of wireless-dev, 2.6.22 or later -Why: The option/code is - * not enabled on most kernels - * not required by any userspace tools (except an experimental one, - and even there only for some parts, others use ioctl) - * pointless since wext is no longer evolving and the ioctl - interface needs to be kept -Who: Johannes Berg - ---------------------------- - What: i8xx_tco watchdog driver When: in 2.6.22 Why: the i8xx_tco watchdog driver has been replaced by the iTCO_wdt -- cgit v1.2.3 From 48491e6bdb8fa73751cc95f740175ec799db5d55 Mon Sep 17 00:00:00 2001 From: "Robert P. J. Day" Date: Thu, 26 Apr 2007 00:59:27 -0700 Subject: [NET]: Delete unused header file linux/if_wanpipe_common.h Delete the unreferenced header file include/linux/if_wanpipe_common.h, as well as the reference to it in the Doc file. Signed-off-by: Robert P. J. Day Signed-off-by: Andrew Morton Signed-off-by: David S. Miller --- Documentation/networking/wan-router.txt | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/networking/wan-router.txt b/Documentation/networking/wan-router.txt index 653978dcea7..07dd6d9930a 100644 --- a/Documentation/networking/wan-router.txt +++ b/Documentation/networking/wan-router.txt @@ -250,7 +250,6 @@ PRODUCT COMPONENTS AND RELATED FILES sdladrv.h SDLA support module API definitions sdlasfm.h SDLA firmware module definitions if_wanpipe.h WANPIPE Socket definitions - if_wanpipe_common.h WANPIPE Socket/Driver common definitions. sdlapci.h WANPIPE PCI definitions -- cgit v1.2.3 From 9198d2220d29b87ac3a05a3b791c50bb8a014d63 Mon Sep 17 00:00:00 2001 From: "Alexandra N. Kossovsky" Date: Thu, 26 Apr 2007 01:40:13 -0700 Subject: [NET]: bonding documentation fix for multiple bonding interfaces Fix bonding driver documentation for the case of multiple bonding interfaces. Signed-off-by: "Alexandra N. Kossovsky" Acked-by: Jay Vosburgh Signed-off-by: Andrew Morton Signed-off-by: David S. Miller --- Documentation/networking/bonding.txt | 35 ++--------------------------------- 1 file changed, 2 insertions(+), 33 deletions(-) (limited to 'Documentation') diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt index de809e58092..1da56663083 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.txt @@ -920,40 +920,9 @@ options, you may wish to use the "max_bonds" module parameter, documented above. To create multiple bonding devices with differing options, it -is necessary to load the bonding driver multiple times. Note that -current versions of the sysconfig network initialization scripts -handle this automatically; if your distro uses these scripts, no -special action is needed. See the section Configuring Bonding -Devices, above, if you're not sure about your network initialization -scripts. - - To load multiple instances of the module, it is necessary to -specify a different name for each instance (the module loading system -requires that every loaded module, even multiple instances of the same -module, have a unique name). This is accomplished by supplying -multiple sets of bonding options in /etc/modprobe.conf, for example: - -alias bond0 bonding -options bond0 -o bond0 mode=balance-rr miimon=100 - -alias bond1 bonding -options bond1 -o bond1 mode=balance-alb miimon=50 - - will load the bonding module two times. The first instance is -named "bond0" and creates the bond0 device in balance-rr mode with an -miimon of 100. The second instance is named "bond1" and creates the -bond1 device in balance-alb mode with an miimon of 50. - - In some circumstances (typically with older distributions), -the above does not work, and the second bonding instance never sees -its options. In that case, the second options line can be substituted -as follows: - -install bond1 /sbin/modprobe --ignore-install bonding -o bond1 \ - mode=balance-alb miimon=50 +is necessary to use bonding parameters exported by sysfs, documented +in the section below. - This may be repeated any number of times, specifying a new and -unique name in place of bond1 for each subsequent instance. 3.4 Configuring Bonding Manually via Sysfs ------------------------------------------ -- cgit v1.2.3 From 7318226ea2931a627f3572e5f4804c91ca19ecbc Mon Sep 17 00:00:00 2001 From: David Howells Date: Thu, 26 Apr 2007 15:46:23 -0700 Subject: [AF_RXRPC]: Key facility changes for AF_RXRPC Export the keyring key type definition and document its availability. Add alternative types into the key's type_data union to make it more useful. Not all users necessarily want to use it as a list_head (AF_RXRPC doesn't, for example), so make it clear that it can be used in other ways. Signed-off-by: David Howells Signed-off-by: David S. Miller --- Documentation/keys.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'Documentation') diff --git a/Documentation/keys.txt b/Documentation/keys.txt index 60c665d9cfa..81d9aa09729 100644 --- a/Documentation/keys.txt +++ b/Documentation/keys.txt @@ -859,6 +859,18 @@ payload contents" for more information. void unregister_key_type(struct key_type *type); +Under some circumstances, it may be desirable to desirable to deal with a +bundle of keys. The facility provides access to the keyring type for managing +such a bundle: + + struct key_type key_type_keyring; + +This can be used with a function such as request_key() to find a specific +keyring in a process's keyrings. A keyring thus found can then be searched +with keyring_search(). Note that it is not possible to use request_key() to +search a specific keyring, so using keyrings in this way is of limited utility. + + =================================== NOTES ON ACCESSING PAYLOAD CONTENTS =================================== -- cgit v1.2.3 From 17926a79320afa9b95df6b977b40cca6d8713cea Mon Sep 17 00:00:00 2001 From: David Howells Date: Thu, 26 Apr 2007 15:48:28 -0700 Subject: [AF_RXRPC]: Provide secure RxRPC sockets for use by userspace and kernel both Provide AF_RXRPC sockets that can be used to talk to AFS servers, or serve answers to AFS clients. KerberosIV security is fully supported. The patches and some example test programs can be found in: http://people.redhat.com/~dhowells/rxrpc/ This will eventually replace the old implementation of kernel-only RxRPC currently resident in net/rxrpc/. Signed-off-by: David Howells Signed-off-by: David S. Miller --- Documentation/networking/rxrpc.txt | 663 +++++++++++++++++++++++++++++++++++++ 1 file changed, 663 insertions(+) create mode 100644 Documentation/networking/rxrpc.txt (limited to 'Documentation') diff --git a/Documentation/networking/rxrpc.txt b/Documentation/networking/rxrpc.txt new file mode 100644 index 00000000000..fb809b738a0 --- /dev/null +++ b/Documentation/networking/rxrpc.txt @@ -0,0 +1,663 @@ + ====================== + RxRPC NETWORK PROTOCOL + ====================== + +The RxRPC protocol driver provides a reliable two-phase transport on top of UDP +that can be used to perform RxRPC remote operations. This is done over sockets +of AF_RXRPC family, using sendmsg() and recvmsg() with control data to send and +receive data, aborts and errors. + +Contents of this document: + + (*) Overview. + + (*) RxRPC protocol summary. + + (*) AF_RXRPC driver model. + + (*) Control messages. + + (*) Socket options. + + (*) Security. + + (*) Example client usage. + + (*) Example server usage. + + +======== +OVERVIEW +======== + +RxRPC is a two-layer protocol. There is a session layer which provides +reliable virtual connections using UDP over IPv4 (or IPv6) as the transport +layer, but implements a real network protocol; and there's the presentation +layer which renders structured data to binary blobs and back again using XDR +(as does SunRPC): + + +-------------+ + | Application | + +-------------+ + | XDR | Presentation + +-------------+ + | RxRPC | Session + +-------------+ + | UDP | Transport + +-------------+ + + +AF_RXRPC provides: + + (1) Part of an RxRPC facility for both kernel and userspace applications by + making the session part of it a Linux network protocol (AF_RXRPC). + + (2) A two-phase protocol. The client transmits a blob (the request) and then + receives a blob (the reply), and the server receives the request and then + transmits the reply. + + (3) Retention of the reusable bits of the transport system set up for one call + to speed up subsequent calls. + + (4) A secure protocol, using the Linux kernel's key retention facility to + manage security on the client end. The server end must of necessity be + more active in security negotiations. + +AF_RXRPC does not provide XDR marshalling/presentation facilities. That is +left to the application. AF_RXRPC only deals in blobs. Even the operation ID +is just the first four bytes of the request blob, and as such is beyond the +kernel's interest. + + +Sockets of AF_RXRPC family are: + + (1) created as type SOCK_DGRAM; + + (2) provided with a protocol of the type of underlying transport they're going + to use - currently only PF_INET is supported. + + +The Andrew File System (AFS) is an example of an application that uses this and +that has both kernel (filesystem) and userspace (utility) components. + + +====================== +RXRPC PROTOCOL SUMMARY +====================== + +An overview of the RxRPC protocol: + + (*) RxRPC sits on top of another networking protocol (UDP is the only option + currently), and uses this to provide network transport. UDP ports, for + example, provide transport endpoints. + + (*) RxRPC supports multiple virtual "connections" from any given transport + endpoint, thus allowing the endpoints to be shared, even to the same + remote endpoint. + + (*) Each connection goes to a particular "service". A connection may not go + to multiple services. A service may be considered the RxRPC equivalent of + a port number. AF_RXRPC permits multiple services to share an endpoint. + + (*) Client-originating packets are marked, thus a transport endpoint can be + shared between client and server connections (connections have a + direction). + + (*) Up to a billion connections may be supported concurrently between one + local transport endpoint and one service on one remote endpoint. An RxRPC + connection is described by seven numbers: + + Local address } + Local port } Transport (UDP) address + Remote address } + Remote port } + Direction + Connection ID + Service ID + + (*) Each RxRPC operation is a "call". A connection may make up to four + billion calls, but only up to four calls may be in progress on a + connection at any one time. + + (*) Calls are two-phase and asymmetric: the client sends its request data, + which the service receives; then the service transmits the reply data + which the client receives. + + (*) The data blobs are of indefinite size, the end of a phase is marked with a + flag in the packet. The number of packets of data making up one blob may + not exceed 4 billion, however, as this would cause the sequence number to + wrap. + + (*) The first four bytes of the request data are the service operation ID. + + (*) Security is negotiated on a per-connection basis. The connection is + initiated by the first data packet on it arriving. If security is + requested, the server then issues a "challenge" and then the client + replies with a "response". If the response is successful, the security is + set for the lifetime of that connection, and all subsequent calls made + upon it use that same security. In the event that the server lets a + connection lapse before the client, the security will be renegotiated if + the client uses the connection again. + + (*) Calls use ACK packets to handle reliability. Data packets are also + explicitly sequenced per call. + + (*) There are two types of positive acknowledgement: hard-ACKs and soft-ACKs. + A hard-ACK indicates to the far side that all the data received to a point + has been received and processed; a soft-ACK indicates that the data has + been received but may yet be discarded and re-requested. The sender may + not discard any transmittable packets until they've been hard-ACK'd. + + (*) Reception of a reply data packet implicitly hard-ACK's all the data + packets that make up the request. + + (*) An call is complete when the request has been sent, the reply has been + received and the final hard-ACK on the last packet of the reply has + reached the server. + + (*) An call may be aborted by either end at any time up to its completion. + + +===================== +AF_RXRPC DRIVER MODEL +===================== + +About the AF_RXRPC driver: + + (*) The AF_RXRPC protocol transparently uses internal sockets of the transport + protocol to represent transport endpoints. + + (*) AF_RXRPC sockets map onto RxRPC connection bundles. Actual RxRPC + connections are handled transparently. One client socket may be used to + make multiple simultaneous calls to the same service. One server socket + may handle calls from many clients. + + (*) Additional parallel client connections will be initiated to support extra + concurrent calls, up to a tunable limit. + + (*) Each connection is retained for a certain amount of time [tunable] after + the last call currently using it has completed in case a new call is made + that could reuse it. + + (*) Each internal UDP socket is retained [tunable] for a certain amount of + time [tunable] after the last connection using it discarded, in case a new + connection is made that could use it. + + (*) A client-side connection is only shared between calls if they have have + the same key struct describing their security (and assuming the calls + would otherwise share the connection). Non-secured calls would also be + able to share connections with each other. + + (*) A server-side connection is shared if the client says it is. + + (*) ACK'ing is handled by the protocol driver automatically, including ping + replying. + + (*) SO_KEEPALIVE automatically pings the other side to keep the connection + alive [TODO]. + + (*) If an ICMP error is received, all calls affected by that error will be + aborted with an appropriate network error passed through recvmsg(). + + +Interaction with the user of the RxRPC socket: + + (*) A socket is made into a server socket by binding an address with a + non-zero service ID. + + (*) In the client, sending a request is achieved with one or more sendmsgs, + followed by the reply being received with one or more recvmsgs. + + (*) The first sendmsg for a request to be sent from a client contains a tag to + be used in all other sendmsgs or recvmsgs associated with that call. The + tag is carried in the control data. + + (*) connect() is used to supply a default destination address for a client + socket. This may be overridden by supplying an alternate address to the + first sendmsg() of a call (struct msghdr::msg_name). + + (*) If connect() is called on an unbound client, a random local port will + bound before the operation takes place. + + (*) A server socket may also be used to make client calls. To do this, the + first sendmsg() of the call must specify the target address. The server's + transport endpoint is used to send the packets. + + (*) Once the application has received the last message associated with a call, + the tag is guaranteed not to be seen again, and so it can be used to pin + client resources. A new call can then be initiated with the same tag + without fear of interference. + + (*) In the server, a request is received with one or more recvmsgs, then the + the reply is transmitted with one or more sendmsgs, and then the final ACK + is received with a last recvmsg. + + (*) When sending data for a call, sendmsg is given MSG_MORE if there's more + data to come on that call. + + (*) When receiving data for a call, recvmsg flags MSG_MORE if there's more + data to come for that call. + + (*) When receiving data or messages for a call, MSG_EOR is flagged by recvmsg + to indicate the terminal message for that call. + + (*) A call may be aborted by adding an abort control message to the control + data. Issuing an abort terminates the kernel's use of that call's tag. + Any messages waiting in the receive queue for that call will be discarded. + + (*) Aborts, busy notifications and challenge packets are delivered by recvmsg, + and control data messages will be set to indicate the context. Receiving + an abort or a busy message terminates the kernel's use of that call's tag. + + (*) The control data part of the msghdr struct is used for a number of things: + + (*) The tag of the intended or affected call. + + (*) Sending or receiving errors, aborts and busy notifications. + + (*) Notifications of incoming calls. + + (*) Sending debug requests and receiving debug replies [TODO]. + + (*) When the kernel has received and set up an incoming call, it sends a + message to server application to let it know there's a new call awaiting + its acceptance [recvmsg reports a special control message]. The server + application then uses sendmsg to assign a tag to the new call. Once that + is done, the first part of the request data will be delivered by recvmsg. + + (*) The server application has to provide the server socket with a keyring of + secret keys corresponding to the security types it permits. When a secure + connection is being set up, the kernel looks up the appropriate secret key + in the keyring and then sends a challenge packet to the client and + receives a response packet. The kernel then checks the authorisation of + the packet and either aborts the connection or sets up the security. + + (*) The name of the key a client will use to secure its communications is + nominated by a socket option. + + +Notes on recvmsg: + + (*) If there's a sequence of data messages belonging to a particular call on + the receive queue, then recvmsg will keep working through them until: + + (a) it meets the end of that call's received data, + + (b) it meets a non-data message, + + (c) it meets a message belonging to a different call, or + + (d) it fills the user buffer. + + If recvmsg is called in blocking mode, it will keep sleeping, awaiting the + reception of further data, until one of the above four conditions is met. + + (2) MSG_PEEK operates similarly, but will return immediately if it has put any + data in the buffer rather than sleeping until it can fill the buffer. + + (3) If a data message is only partially consumed in filling a user buffer, + then the remainder of that message will be left on the front of the queue + for the next taker. MSG_TRUNC will never be flagged. + + (4) If there is more data to be had on a call (it hasn't copied the last byte + of the last data message in that phase yet), then MSG_MORE will be + flagged. + + +================ +CONTROL MESSAGES +================ + +AF_RXRPC makes use of control messages in sendmsg() and recvmsg() to multiplex +calls, to invoke certain actions and to report certain conditions. These are: + + MESSAGE ID SRT DATA MEANING + ======================= === =========== =============================== + RXRPC_USER_CALL_ID sr- User ID App's call specifier + RXRPC_ABORT srt Abort code Abort code to issue/received + RXRPC_ACK -rt n/a Final ACK received + RXRPC_NET_ERROR -rt error num Network error on call + RXRPC_BUSY -rt n/a Call rejected (server busy) + RXRPC_LOCAL_ERROR -rt error num Local error encountered + RXRPC_NEW_CALL -r- n/a New call received + RXRPC_ACCEPT s-- n/a Accept new call + + (SRT = usable in Sendmsg / delivered by Recvmsg / Terminal message) + + (*) RXRPC_USER_CALL_ID + + This is used to indicate the application's call ID. It's an unsigned long + that the app specifies in the client by attaching it to the first data + message or in the server by passing it in association with an RXRPC_ACCEPT + message. recvmsg() passes it in conjunction with all messages except + those of the RXRPC_NEW_CALL message. + + (*) RXRPC_ABORT + + This is can be used by an application to abort a call by passing it to + sendmsg, or it can be delivered by recvmsg to indicate a remote abort was + received. Either way, it must be associated with an RXRPC_USER_CALL_ID to + specify the call affected. If an abort is being sent, then error EBADSLT + will be returned if there is no call with that user ID. + + (*) RXRPC_ACK + + This is delivered to a server application to indicate that the final ACK + of a call was received from the client. It will be associated with an + RXRPC_USER_CALL_ID to indicate the call that's now complete. + + (*) RXRPC_NET_ERROR + + This is delivered to an application to indicate that an ICMP error message + was encountered in the process of trying to talk to the peer. An + errno-class integer value will be included in the control message data + indicating the problem, and an RXRPC_USER_CALL_ID will indicate the call + affected. + + (*) RXRPC_BUSY + + This is delivered to a client application to indicate that a call was + rejected by the server due to the server being busy. It will be + associated with an RXRPC_USER_CALL_ID to indicate the rejected call. + + (*) RXRPC_LOCAL_ERROR + + This is delivered to an application to indicate that a local error was + encountered and that a call has been aborted because of it. An + errno-class integer value will be included in the control message data + indicating the problem, and an RXRPC_USER_CALL_ID will indicate the call + affected. + + (*) RXRPC_NEW_CALL + + This is delivered to indicate to a server application that a new call has + arrived and is awaiting acceptance. No user ID is associated with this, + as a user ID must subsequently be assigned by doing an RXRPC_ACCEPT. + + (*) RXRPC_ACCEPT + + This is used by a server application to attempt to accept a call and + assign it a user ID. It should be associated with an RXRPC_USER_CALL_ID + to indicate the user ID to be assigned. If there is no call to be + accepted (it may have timed out, been aborted, etc.), then sendmsg will + return error ENODATA. If the user ID is already in use by another call, + then error EBADSLT will be returned. + + +============== +SOCKET OPTIONS +============== + +AF_RXRPC sockets support a few socket options at the SOL_RXRPC level: + + (*) RXRPC_SECURITY_KEY + + This is used to specify the description of the key to be used. The key is + extracted from the calling process's keyrings with request_key() and + should be of "rxrpc" type. + + The optval pointer points to the description string, and optlen indicates + how long the string is, without the NUL terminator. + + (*) RXRPC_SECURITY_KEYRING + + Similar to above but specifies a keyring of server secret keys to use (key + type "keyring"). See the "Security" section. + + (*) RXRPC_EXCLUSIVE_CONNECTION + + This is used to request that new connections should be used for each call + made subsequently on this socket. optval should be NULL and optlen 0. + + (*) RXRPC_MIN_SECURITY_LEVEL + + This is used to specify the minimum security level required for calls on + this socket. optval must point to an int containing one of the following + values: + + (a) RXRPC_SECURITY_PLAIN + + Encrypted checksum only. + + (b) RXRPC_SECURITY_AUTH + + Encrypted checksum plus packet padded and first eight bytes of packet + encrypted - which includes the actual packet length. + + (c) RXRPC_SECURITY_ENCRYPTED + + Encrypted checksum plus entire packet padded and encrypted, including + actual packet length. + + +======== +SECURITY +======== + +Currently, only the kerberos 4 equivalent protocol has been implemented +(security index 2 - rxkad). This requires the rxkad module to be loaded and, +on the client, tickets of the appropriate type to be obtained from the AFS +kaserver or the kerberos server and installed as "rxrpc" type keys. This is +normally done using the klog program. An example simple klog program can be +found at: + + http://people.redhat.com/~dhowells/rxrpc/klog.c + +The payload provided to add_key() on the client should be of the following +form: + + struct rxrpc_key_sec2_v1 { + uint16_t security_index; /* 2 */ + uint16_t ticket_length; /* length of ticket[] */ + uint32_t expiry; /* time at which expires */ + uint8_t kvno; /* key version number */ + uint8_t __pad[3]; + uint8_t session_key[8]; /* DES session key */ + uint8_t ticket[0]; /* the encrypted ticket */ + }; + +Where the ticket blob is just appended to the above structure. + + +For the server, keys of type "rxrpc_s" must be made available to the server. +They have a description of ":" (eg: "52:2" for an +rxkad key for the AFS VL service). When such a key is created, it should be +given the server's secret key as the instantiation data (see the example +below). + + add_key("rxrpc_s", "52:2", secret_key, 8, keyring); + +A keyring is passed to the server socket by naming it in a sockopt. The server +socket then looks the server secret keys up in this keyring when secure +incoming connections are made. This can be seen in an example program that can +be found at: + + http://people.redhat.com/~dhowells/rxrpc/listen.c + + +==================== +EXAMPLE CLIENT USAGE +==================== + +A client would issue an operation by: + + (1) An RxRPC socket is set up by: + + client = socket(AF_RXRPC, SOCK_DGRAM, PF_INET); + + Where the third parameter indicates the protocol family of the transport + socket used - usually IPv4 but it can also be IPv6 [TODO]. + + (2) A local address can optionally be bound: + + struct sockaddr_rxrpc srx = { + .srx_family = AF_RXRPC, + .srx_service = 0, /* we're a client */ + .transport_type = SOCK_DGRAM, /* type of transport socket */ + .transport.sin_family = AF_INET, + .transport.sin_port = htons(7000), /* AFS callback */ + .transport.sin_address = 0, /* all local interfaces */ + }; + bind(client, &srx, sizeof(srx)); + + This specifies the local UDP port to be used. If not given, a random + non-privileged port will be used. A UDP port may be shared between + several unrelated RxRPC sockets. Security is handled on a basis of + per-RxRPC virtual connection. + + (3) The security is set: + + const char *key = "AFS:cambridge.redhat.com"; + setsockopt(client, SOL_RXRPC, RXRPC_SECURITY_KEY, key, strlen(key)); + + This issues a request_key() to get the key representing the security + context. The minimum security level can be set: + + unsigned int sec = RXRPC_SECURITY_ENCRYPTED; + setsockopt(client, SOL_RXRPC, RXRPC_MIN_SECURITY_LEVEL, + &sec, sizeof(sec)); + + (4) The server to be contacted can then be specified (alternatively this can + be done through sendmsg): + + struct sockaddr_rxrpc srx = { + .srx_family = AF_RXRPC, + .srx_service = VL_SERVICE_ID, + .transport_type = SOCK_DGRAM, /* type of transport socket */ + .transport.sin_family = AF_INET, + .transport.sin_port = htons(7005), /* AFS volume manager */ + .transport.sin_address = ..., + }; + connect(client, &srx, sizeof(srx)); + + (5) The request data should then be posted to the server socket using a series + of sendmsg() calls, each with the following control message attached: + + RXRPC_USER_CALL_ID - specifies the user ID for this call + + MSG_MORE should be set in msghdr::msg_flags on all but the last part of + the request. Multiple requests may be made simultaneously. + + If a call is intended to go to a destination other then the default + specified through connect(), then msghdr::msg_name should be set on the + first request message of that call. + + (6) The reply data will then be posted to the server socket for recvmsg() to + pick up. MSG_MORE will be flagged by recvmsg() if there's more reply data + for a particular call to be read. MSG_EOR will be set on the terminal + read for a call. + + All data will be delivered with the following control message attached: + + RXRPC_USER_CALL_ID - specifies the user ID for this call + + If an abort or error occurred, this will be returned in the control data + buffer instead, and MSG_EOR will be flagged to indicate the end of that + call. + + +==================== +EXAMPLE SERVER USAGE +==================== + +A server would be set up to accept operations in the following manner: + + (1) An RxRPC socket is created by: + + server = socket(AF_RXRPC, SOCK_DGRAM, PF_INET); + + Where the third parameter indicates the address type of the transport + socket used - usually IPv4. + + (2) Security is set up if desired by giving the socket a keyring with server + secret keys in it: + + keyring = add_key("keyring", "AFSkeys", NULL, 0, + KEY_SPEC_PROCESS_KEYRING); + + const char secret_key[8] = { + 0xa7, 0x83, 0x8a, 0xcb, 0xc7, 0x83, 0xec, 0x94 }; + add_key("rxrpc_s", "52:2", secret_key, 8, keyring); + + setsockopt(server, SOL_RXRPC, RXRPC_SECURITY_KEYRING, "AFSkeys", 7); + + The keyring can be manipulated after it has been given to the socket. This + permits the server to add more keys, replace keys, etc. whilst it is live. + + (2) A local address must then be bound: + + struct sockaddr_rxrpc srx = { + .srx_family = AF_RXRPC, + .srx_service = VL_SERVICE_ID, /* RxRPC service ID */ + .transport_type = SOCK_DGRAM, /* type of transport socket */ + .transport.sin_family = AF_INET, + .transport.sin_port = htons(7000), /* AFS callback */ + .transport.sin_address = 0, /* all local interfaces */ + }; + bind(server, &srx, sizeof(srx)); + + (3) The server is then set to listen out for incoming calls: + + listen(server, 100); + + (4) The kernel notifies the server of pending incoming connections by sending + it a message for each. This is received with recvmsg() on the server + socket. It has no data, and has a single dataless control message + attached: + + RXRPC_NEW_CALL + + The address that can be passed back by recvmsg() at this point should be + ignored since the call for which the message was posted may have gone by + the time it is accepted - in which case the first call still on the queue + will be accepted. + + (5) The server then accepts the new call by issuing a sendmsg() with two + pieces of control data and no actual data: + + RXRPC_ACCEPT - indicate connection acceptance + RXRPC_USER_CALL_ID - specify user ID for this call + + (6) The first request data packet will then be posted to the server socket for + recvmsg() to pick up. At that point, the RxRPC address for the call can + be read from the address fields in the msghdr struct. + + Subsequent request data will be posted to the server socket for recvmsg() + to collect as it arrives. All but the last piece of the request data will + be delivered with MSG_MORE flagged. + + All data will be delivered with the following control message attached: + + RXRPC_USER_CALL_ID - specifies the user ID for this call + + (8) The reply data should then be posted to the server socket using a series + of sendmsg() calls, each with the following control messages attached: + + RXRPC_USER_CALL_ID - specifies the user ID for this call + + MSG_MORE should be set in msghdr::msg_flags on all but the last message + for a particular call. + + (9) The final ACK from the client will be posted for retrieval by recvmsg() + when it is received. It will take the form of a dataless message with two + control messages attached: + + RXRPC_USER_CALL_ID - specifies the user ID for this call + RXRPC_ACK - indicates final ACK (no data) + + MSG_EOR will be flagged to indicate that this is the final message for + this call. + +(10) Up to the point the final packet of reply data is sent, the call can be + aborted by calling sendmsg() with a dataless message with the following + control messages attached: + + RXRPC_USER_CALL_ID - specifies the user ID for this call + RXRPC_ABORT - indicates abort code (4 byte data) + + Any packets waiting in the socket's receive queue will be discarded if + this is issued. + +Note that all the communications for a particular service take place through +the one server socket, using control messages on sendmsg() and recvmsg() to +determine the call affected. -- cgit v1.2.3 From 651350d10f93bed7003c9a66e24cf25e0f8eed3d Mon Sep 17 00:00:00 2001 From: David Howells Date: Thu, 26 Apr 2007 15:50:17 -0700 Subject: [AF_RXRPC]: Add an interface to the AF_RXRPC module for the AFS filesystem to use Add an interface to the AF_RXRPC module so that the AFS filesystem module can more easily make use of the services available. AFS still opens a socket but then uses the action functions in lieu of sendmsg() and registers an intercept functions to grab messages before they're queued on the socket Rx queue. This permits AFS (or whatever) to: (1) Avoid the overhead of using the recvmsg() call. (2) Use different keys directly on individual client calls on one socket rather than having to open a whole slew of sockets, one for each key it might want to use. (3) Avoid calling request_key() at the point of issue of a call or opening of a socket. This is done instead by AFS at the point of open(), unlink() or other VFS operation and the key handed through. (4) Request the use of something other than GFP_KERNEL to allocate memory. Furthermore: (*) The socket buffer markings used by RxRPC are made available for AFS so that it can interpret the cooked RxRPC messages itself. (*) rxgen (un)marshalling abort codes are made available. The following documentation for the kernel interface is added to Documentation/networking/rxrpc.txt: ========================= AF_RXRPC KERNEL INTERFACE ========================= The AF_RXRPC module also provides an interface for use by in-kernel utilities such as the AFS filesystem. This permits such a utility to: (1) Use different keys directly on individual client calls on one socket rather than having to open a whole slew of sockets, one for each key it might want to use. (2) Avoid having RxRPC call request_key() at the point of issue of a call or opening of a socket. Instead the utility is responsible for requesting a key at the appropriate point. AFS, for instance, would do this during VFS operations such as open() or unlink(). The key is then handed through when the call is initiated. (3) Request the use of something other than GFP_KERNEL to allocate memory. (4) Avoid the overhead of using the recvmsg() call. RxRPC messages can be intercepted before they get put into the socket Rx queue and the socket buffers manipulated directly. To use the RxRPC facility, a kernel utility must still open an AF_RXRPC socket, bind an addess as appropriate and listen if it's to be a server socket, but then it passes this to the kernel interface functions. The kernel interface functions are as follows: (*) Begin a new client call. struct rxrpc_call * rxrpc_kernel_begin_call(struct socket *sock, struct sockaddr_rxrpc *srx, struct key *key, unsigned long user_call_ID, gfp_t gfp); This allocates the infrastructure to make a new RxRPC call and assigns call and connection numbers. The call will be made on the UDP port that the socket is bound to. The call will go to the destination address of a connected client socket unless an alternative is supplied (srx is non-NULL). If a key is supplied then this will be used to secure the call instead of the key bound to the socket with the RXRPC_SECURITY_KEY sockopt. Calls secured in this way will still share connections if at all possible. The user_call_ID is equivalent to that supplied to sendmsg() in the control data buffer. It is entirely feasible to use this to point to a kernel data structure. If this function is successful, an opaque reference to the RxRPC call is returned. The caller now holds a reference on this and it must be properly ended. (*) End a client call. void rxrpc_kernel_end_call(struct rxrpc_call *call); This is used to end a previously begun call. The user_call_ID is expunged from AF_RXRPC's knowledge and will not be seen again in association with the specified call. (*) Send data through a call. int rxrpc_kernel_send_data(struct rxrpc_call *call, struct msghdr *msg, size_t len); This is used to supply either the request part of a client call or the reply part of a server call. msg.msg_iovlen and msg.msg_iov specify the data buffers to be used. msg_iov may not be NULL and must point exclusively to in-kernel virtual addresses. msg.msg_flags may be given MSG_MORE if there will be subsequent data sends for this call. The msg must not specify a destination address, control data or any flags other than MSG_MORE. len is the total amount of data to transmit. (*) Abort a call. void rxrpc_kernel_abort_call(struct rxrpc_call *call, u32 abort_code); This is used to abort a call if it's still in an abortable state. The abort code specified will be placed in the ABORT message sent. (*) Intercept received RxRPC messages. typedef void (*rxrpc_interceptor_t)(struct sock *sk, unsigned long user_call_ID, struct sk_buff *skb); void rxrpc_kernel_intercept_rx_messages(struct socket *sock, rxrpc_interceptor_t interceptor); This installs an interceptor function on the specified AF_RXRPC socket. All messages that would otherwise wind up in the socket's Rx queue are then diverted to this function. Note that care must be taken to process the messages in the right order to maintain DATA message sequentiality. The interceptor function itself is provided with the address of the socket and handling the incoming message, the ID assigned by the kernel utility to the call and the socket buffer containing the message. The skb->mark field indicates the type of message: MARK MEANING =============================== ======================================= RXRPC_SKB_MARK_DATA Data message RXRPC_SKB_MARK_FINAL_ACK Final ACK received for an incoming call RXRPC_SKB_MARK_BUSY Client call rejected as server busy RXRPC_SKB_MARK_REMOTE_ABORT Call aborted by peer RXRPC_SKB_MARK_NET_ERROR Network error detected RXRPC_SKB_MARK_LOCAL_ERROR Local error encountered RXRPC_SKB_MARK_NEW_CALL New incoming call awaiting acceptance The remote abort message can be probed with rxrpc_kernel_get_abort_code(). The two error messages can be probed with rxrpc_kernel_get_error_number(). A new call can be accepted with rxrpc_kernel_accept_call(). Data messages can have their contents extracted with the usual bunch of socket buffer manipulation functions. A data message can be determined to be the last one in a sequence with rxrpc_kernel_is_data_last(). When a data message has been used up, rxrpc_kernel_data_delivered() should be called on it.. Non-data messages should be handled to rxrpc_kernel_free_skb() to dispose of. It is possible to get extra refs on all types of message for later freeing, but this may pin the state of a call until the message is finally freed. (*) Accept an incoming call. struct rxrpc_call * rxrpc_kernel_accept_call(struct socket *sock, unsigned long user_call_ID); This is used to accept an incoming call and to assign it a call ID. This function is similar to rxrpc_kernel_begin_call() and calls accepted must be ended in the same way. If this function is successful, an opaque reference to the RxRPC call is returned. The caller now holds a reference on this and it must be properly ended. (*) Reject an incoming call. int rxrpc_kernel_reject_call(struct socket *sock); This is used to reject the first incoming call on the socket's queue with a BUSY message. -ENODATA is returned if there were no incoming calls. Other errors may be returned if the call had been aborted (-ECONNABORTED) or had timed out (-ETIME). (*) Record the delivery of a data message and free it. void rxrpc_kernel_data_delivered(struct sk_buff *skb); This is used to record a data message as having been delivered and to update the ACK state for the call. The socket buffer will be freed. (*) Free a message. void rxrpc_kernel_free_skb(struct sk_buff *skb); This is used to free a non-DATA socket buffer intercepted from an AF_RXRPC socket. (*) Determine if a data message is the last one on a call. bool rxrpc_kernel_is_data_last(struct sk_buff *skb); This is used to determine if a socket buffer holds the last data message to be received for a call (true will be returned if it does, false if not). The data message will be part of the reply on a client call and the request on an incoming call. In the latter case there will be more messages, but in the former case there will not. (*) Get the abort code from an abort message. u32 rxrpc_kernel_get_abort_code(struct sk_buff *skb); This is used to extract the abort code from a remote abort message. (*) Get the error number from a local or network error message. int rxrpc_kernel_get_error_number(struct sk_buff *skb); This is used to extract the error number from a message indicating either a local error occurred or a network error occurred. Signed-off-by: David Howells Signed-off-by: David S. Miller --- Documentation/networking/rxrpc.txt | 196 +++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) (limited to 'Documentation') diff --git a/Documentation/networking/rxrpc.txt b/Documentation/networking/rxrpc.txt index fb809b738a0..cae231b1c13 100644 --- a/Documentation/networking/rxrpc.txt +++ b/Documentation/networking/rxrpc.txt @@ -25,6 +25,8 @@ Contents of this document: (*) Example server usage. + (*) AF_RXRPC kernel interface. + ======== OVERVIEW @@ -661,3 +663,197 @@ A server would be set up to accept operations in the following manner: Note that all the communications for a particular service take place through the one server socket, using control messages on sendmsg() and recvmsg() to determine the call affected. + + +========================= +AF_RXRPC KERNEL INTERFACE +========================= + +The AF_RXRPC module also provides an interface for use by in-kernel utilities +such as the AFS filesystem. This permits such a utility to: + + (1) Use different keys directly on individual client calls on one socket + rather than having to open a whole slew of sockets, one for each key it + might want to use. + + (2) Avoid having RxRPC call request_key() at the point of issue of a call or + opening of a socket. Instead the utility is responsible for requesting a + key at the appropriate point. AFS, for instance, would do this during VFS + operations such as open() or unlink(). The key is then handed through + when the call is initiated. + + (3) Request the use of something other than GFP_KERNEL to allocate memory. + + (4) Avoid the overhead of using the recvmsg() call. RxRPC messages can be + intercepted before they get put into the socket Rx queue and the socket + buffers manipulated directly. + +To use the RxRPC facility, a kernel utility must still open an AF_RXRPC socket, +bind an addess as appropriate and listen if it's to be a server socket, but +then it passes this to the kernel interface functions. + +The kernel interface functions are as follows: + + (*) Begin a new client call. + + struct rxrpc_call * + rxrpc_kernel_begin_call(struct socket *sock, + struct sockaddr_rxrpc *srx, + struct key *key, + unsigned long user_call_ID, + gfp_t gfp); + + This allocates the infrastructure to make a new RxRPC call and assigns + call and connection numbers. The call will be made on the UDP port that + the socket is bound to. The call will go to the destination address of a + connected client socket unless an alternative is supplied (srx is + non-NULL). + + If a key is supplied then this will be used to secure the call instead of + the key bound to the socket with the RXRPC_SECURITY_KEY sockopt. Calls + secured in this way will still share connections if at all possible. + + The user_call_ID is equivalent to that supplied to sendmsg() in the + control data buffer. It is entirely feasible to use this to point to a + kernel data structure. + + If this function is successful, an opaque reference to the RxRPC call is + returned. The caller now holds a reference on this and it must be + properly ended. + + (*) End a client call. + + void rxrpc_kernel_end_call(struct rxrpc_call *call); + + This is used to end a previously begun call. The user_call_ID is expunged + from AF_RXRPC's knowledge and will not be seen again in association with + the specified call. + + (*) Send data through a call. + + int rxrpc_kernel_send_data(struct rxrpc_call *call, struct msghdr *msg, + size_t len); + + This is used to supply either the request part of a client call or the + reply part of a server call. msg.msg_iovlen and msg.msg_iov specify the + data buffers to be used. msg_iov may not be NULL and must point + exclusively to in-kernel virtual addresses. msg.msg_flags may be given + MSG_MORE if there will be subsequent data sends for this call. + + The msg must not specify a destination address, control data or any flags + other than MSG_MORE. len is the total amount of data to transmit. + + (*) Abort a call. + + void rxrpc_kernel_abort_call(struct rxrpc_call *call, u32 abort_code); + + This is used to abort a call if it's still in an abortable state. The + abort code specified will be placed in the ABORT message sent. + + (*) Intercept received RxRPC messages. + + typedef void (*rxrpc_interceptor_t)(struct sock *sk, + unsigned long user_call_ID, + struct sk_buff *skb); + + void + rxrpc_kernel_intercept_rx_messages(struct socket *sock, + rxrpc_interceptor_t interceptor); + + This installs an interceptor function on the specified AF_RXRPC socket. + All messages that would otherwise wind up in the socket's Rx queue are + then diverted to this function. Note that care must be taken to process + the messages in the right order to maintain DATA message sequentiality. + + The interceptor function itself is provided with the address of the socket + and handling the incoming message, the ID assigned by the kernel utility + to the call and the socket buffer containing the message. + + The skb->mark field indicates the type of message: + + MARK MEANING + =============================== ======================================= + RXRPC_SKB_MARK_DATA Data message + RXRPC_SKB_MARK_FINAL_ACK Final ACK received for an incoming call + RXRPC_SKB_MARK_BUSY Client call rejected as server busy + RXRPC_SKB_MARK_REMOTE_ABORT Call aborted by peer + RXRPC_SKB_MARK_NET_ERROR Network error detected + RXRPC_SKB_MARK_LOCAL_ERROR Local error encountered + RXRPC_SKB_MARK_NEW_CALL New incoming call awaiting acceptance + + The remote abort message can be probed with rxrpc_kernel_get_abort_code(). + The two error messages can be probed with rxrpc_kernel_get_error_number(). + A new call can be accepted with rxrpc_kernel_accept_call(). + + Data messages can have their contents extracted with the usual bunch of + socket buffer manipulation functions. A data message can be determined to + be the last one in a sequence with rxrpc_kernel_is_data_last(). When a + data message has been used up, rxrpc_kernel_data_delivered() should be + called on it.. + + Non-data messages should be handled to rxrpc_kernel_free_skb() to dispose + of. It is possible to get extra refs on all types of message for later + freeing, but this may pin the state of a call until the message is finally + freed. + + (*) Accept an incoming call. + + struct rxrpc_call * + rxrpc_kernel_accept_call(struct socket *sock, + unsigned long user_call_ID); + + This is used to accept an incoming call and to assign it a call ID. This + function is similar to rxrpc_kernel_begin_call() and calls accepted must + be ended in the same way. + + If this function is successful, an opaque reference to the RxRPC call is + returned. The caller now holds a reference on this and it must be + properly ended. + + (*) Reject an incoming call. + + int rxrpc_kernel_reject_call(struct socket *sock); + + This is used to reject the first incoming call on the socket's queue with + a BUSY message. -ENODATA is returned if there were no incoming calls. + Other errors may be returned if the call had been aborted (-ECONNABORTED) + or had timed out (-ETIME). + + (*) Record the delivery of a data message and free it. + + void rxrpc_kernel_data_delivered(struct sk_buff *skb); + + This is used to record a data message as having been delivered and to + update the ACK state for the call. The socket buffer will be freed. + + (*) Free a message. + + void rxrpc_kernel_free_skb(struct sk_buff *skb); + + This is used to free a non-DATA socket buffer intercepted from an AF_RXRPC + socket. + + (*) Determine if a data message is the last one on a call. + + bool rxrpc_kernel_is_data_last(struct sk_buff *skb); + + This is used to determine if a socket buffer holds the last data message + to be received for a call (true will be returned if it does, false + if not). + + The data message will be part of the reply on a client call and the + request on an incoming call. In the latter case there will be more + messages, but in the former case there will not. + + (*) Get the abort code from an abort message. + + u32 rxrpc_kernel_get_abort_code(struct sk_buff *skb); + + This is used to extract the abort code from a remote abort message. + + (*) Get the error number from a local or network error message. + + int rxrpc_kernel_get_error_number(struct sk_buff *skb); + + This is used to extract the error number from a message indicating either + a local error occurred or a network error occurred. -- cgit v1.2.3 From 0795e7c031c4bda46fbdde678adf29de19bef7f4 Mon Sep 17 00:00:00 2001 From: David Howells Date: Thu, 26 Apr 2007 15:57:43 -0700 Subject: [AFS]: Update the AFS fs documentation. Update the AFS fs documentation. Signed-off-by: David Howells Signed-off-by: David S. Miller --- Documentation/filesystems/afs.txt | 214 +++++++++++++++++++++++++++----------- 1 file changed, 154 insertions(+), 60 deletions(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/afs.txt b/Documentation/filesystems/afs.txt index 2f4237dfb8c..12ad6c7f4e5 100644 --- a/Documentation/filesystems/afs.txt +++ b/Documentation/filesystems/afs.txt @@ -1,31 +1,82 @@ + ==================== kAFS: AFS FILESYSTEM ==================== -ABOUT -===== +Contents: + + - Overview. + - Usage. + - Mountpoints. + - Proc filesystem. + - The cell database. + - Security. + - Examples. + + +======== +OVERVIEW +======== -This filesystem provides a fairly simple AFS filesystem driver. It is under -development and only provides very basic facilities. It does not yet support -the following AFS features: +This filesystem provides a fairly simple secure AFS filesystem driver. It is +under development and does not yet provide the full feature set. The features +it does support include: - (*) Write support. - (*) Communications security. - (*) Local caching. - (*) pioctl() system call. - (*) Automatic mounting of embedded mountpoints. + (*) Security (currently only AFS kaserver and KerberosIV tickets). + (*) File reading. + (*) Automounting. + +It does not yet support the following AFS features: + + (*) Write support. + + (*) Local caching. + + (*) pioctl() system call. + + +=========== +COMPILATION +=========== + +The filesystem should be enabled by turning on the kernel configuration +options: + + CONFIG_AF_RXRPC - The RxRPC protocol transport + CONFIG_RXKAD - The RxRPC Kerberos security handler + CONFIG_AFS - The AFS filesystem + +Additionally, the following can be turned on to aid debugging: + + CONFIG_AF_RXRPC_DEBUG - Permit AF_RXRPC debugging to be enabled + CONFIG_AFS_DEBUG - Permit AFS debugging to be enabled + +They permit the debugging messages to be turned on dynamically by manipulating +the masks in the following files: + + /sys/module/af_rxrpc/parameters/debug + /sys/module/afs/parameters/debug + + +===== USAGE ===== When inserting the driver modules the root cell must be specified along with a list of volume location server IP addresses: - insmod rxrpc.o + insmod af_rxrpc.o + insmod rxkad.o insmod kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91 -The first module is a driver for the RxRPC remote operation protocol, and the -second is the actual filesystem driver for the AFS filesystem. +The first module is the AF_RXRPC network protocol driver. This provides the +RxRPC remote operation protocol and may also be accessed from userspace. See: + + Documentation/networking/rxrpc.txt + +The second module is the kerberos RxRPC security driver, and the third module +is the actual filesystem driver for the AFS filesystem. Once the module has been loaded, more modules can be added by the following procedure: @@ -33,7 +84,7 @@ procedure: echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells Where the parameters to the "add" command are the name of a cell and a list of -volume location servers within that cell. +volume location servers within that cell, with the latter separated by colons. Filesystems can be mounted anywhere by commands similar to the following: @@ -42,11 +93,6 @@ Filesystems can be mounted anywhere by commands similar to the following: mount -t afs "#root.afs." /afs mount -t afs "#root.cell." /afs/cambridge - NB: When using this on Linux 2.4, the mount command has to be different, - since the filesystem doesn't have access to the device name argument: - - mount -t afs none /afs -ovol="#root.afs." - Where the initial character is either a hash or a percent symbol depending on whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O volume, but are willing to use a R/W volume instead (percent). @@ -60,55 +106,66 @@ named volume will be looked up in the cell specified during insmod. Additional cells can be added through /proc (see later section). +=========== MOUNTPOINTS =========== -AFS has a concept of mountpoints. These are specially formatted symbolic links -(of the same form as the "device name" passed to mount). kAFS presents these -to the user as directories that have special properties: +AFS has a concept of mountpoints. In AFS terms, these are specially formatted +symbolic links (of the same form as the "device name" passed to mount). kAFS +presents these to the user as directories that have a follow-link capability +(ie: symbolic link semantics). If anyone attempts to access them, they will +automatically cause the target volume to be mounted (if possible) on that site. - (*) They cannot be listed. Running a program like "ls" on them will incur an - EREMOTE error (Object is remote). +Automatically mounted filesystems will be automatically unmounted approximately +twenty minutes after they were last used. Alternatively they can be unmounted +directly with the umount() system call. - (*) Other objects can't be looked up inside of them. This also incurs an - EREMOTE error. +Manually unmounting an AFS volume will cause any idle submounts upon it to be +culled first. If all are culled, then the requested volume will also be +unmounted, otherwise error EBUSY will be returned. - (*) They can be queried with the readlink() system call, which will return - the name of the mountpoint to which they point. The "readlink" program - will also work. +This can be used by the administrator to attempt to unmount the whole AFS tree +mounted on /afs in one go by doing: - (*) They can be mounted on (which symbolic links can't). + umount /afs +=============== PROC FILESYSTEM =============== -The rxrpc module creates a number of files in various places in the /proc -filesystem: - - (*) Firstly, some information files are made available in a directory called - "/proc/net/rxrpc/". These list the extant transport endpoint, peer, - connection and call records. - - (*) Secondly, some control files are made available in a directory called - "/proc/sys/rxrpc/". Currently, all these files can be used for is to - turn on various levels of tracing. - The AFS modules creates a "/proc/fs/afs/" directory and populates it: - (*) A "cells" file that lists cells currently known to the afs module. + (*) A "cells" file that lists cells currently known to the afs module and + their usage counts: + + [root@andromeda ~]# cat /proc/fs/afs/cells + USE NAME + 3 cambridge.redhat.com (*) A directory per cell that contains files that list volume location servers, volumes, and active servers known within that cell. + [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers + USE ADDR STATE + 4 172.16.18.91 0 + [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers + ADDRESS + 172.16.18.91 + [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes + USE STT VLID[0] VLID[1] VLID[2] NAME + 1 Val 20000000 20000001 20000002 root.afs + +================= THE CELL DATABASE ================= -The filesystem maintains an internal database of all the cells it knows and -the IP addresses of the volume location servers for those cells. The cell to -which the computer belongs is added to the database when insmod is performed -by the "rootcell=" argument. +The filesystem maintains an internal database of all the cells it knows and the +IP addresses of the volume location servers for those cells. The cell to which +the system belongs is added to the database when insmod is performed by the +"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on +the kernel command line. Further cells can be added by commands similar to the following: @@ -118,20 +175,65 @@ Further cells can be added by commands similar to the following: No other cell database operations are available at this time. +======== +SECURITY +======== + +Secure operations are initiated by acquiring a key using the klog program. A +very primitive klog program is available at: + + http://people.redhat.com/~dhowells/rxrpc/klog.c + +This should be compiled by: + + make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils" + +And then run as: + + ./klog + +Assuming it's successful, this adds a key of type RxRPC, named for the service +and cell, eg: "afs@". This can be viewed with the keyctl program or +by cat'ing /proc/keys: + + [root@andromeda ~]# keyctl show + Session Keyring + -3 --alswrv 0 0 keyring: _ses.3268 + 2 --alswrv 0 0 \_ keyring: _uid.0 + 111416553 --als--v 0 0 \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM + +Currently the username, realm, password and proposed ticket lifetime are +compiled in to the program. + +It is not required to acquire a key before using AFS facilities, but if one is +not acquired then all operations will be governed by the anonymous user parts +of the ACLs. + +If a key is acquired, then all AFS operations, including mounts and automounts, +made by a possessor of that key will be secured with that key. + +If a file is opened with a particular key and then the file descriptor is +passed to a process that doesn't have that key (perhaps over an AF_UNIX +socket), then the operations on the file will be made with key that was used to +open the file. + + +======== EXAMPLES ======== -Here's what I use to test this. Some of the names and IP addresses are local -to my internal DNS. My "root.afs" partition has a mount point within it for +Here's what I use to test this. Some of the names and IP addresses are local +to my internal DNS. My "root.afs" partition has a mount point within it for some public volumes volumes. -insmod -S /tmp/rxrpc.o -insmod -S /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91 +insmod /tmp/rxrpc.o +insmod /tmp/rxkad.o +insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91 mount -t afs \%root.afs. /afs mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/ -echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells +echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/ mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib @@ -141,15 +243,7 @@ mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user -umount /afs/grand.central.org/user -umount /afs/grand.central.org/software -umount /afs/grand.central.org/service -umount /afs/grand.central.org/project -umount /afs/grand.central.org/doc -umount /afs/grand.central.org/contrib -umount /afs/grand.central.org/archive -umount /afs/grand.central.org -umount /afs/cambridge.redhat.com umount /afs rmmod kafs +rmmod rxkad rmmod rxrpc -- cgit v1.2.3 From 49e9f70f8e7a4df00a5185e7f5c91e3c583847db Mon Sep 17 00:00:00 2001 From: "David S. Miller" Date: Fri, 27 Apr 2007 01:04:23 -0700 Subject: [IPV4]: Add multipath cached to feature-removal-schedule.txt Signed-off-by: David S. Miller --- Documentation/feature-removal-schedule.txt | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'Documentation') diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 976c8a1bd7c..6da663607f7 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -292,3 +292,22 @@ Why: the i8xx_tco watchdog driver has been replaced by the iTCO_wdt Who: Wim Van Sebroeck --------------------------- + +What: Multipath cached routing support in ipv4 +When: in 2.6.23 +Why: Code was merged, then submitter immediately disappeared leaving + us with no maintainer and lots of bugs. The code should not have + been merged in the first place, and many aspects of it's + implementation are blocking more critical core networking + development. It's marked EXPERIMENTAL and no distribution + enables it because it cause obscure crashes due to unfixable bugs + (interfaces don't return errors so memory allocation can't be + handled, calling contexts of these interfaces make handling + errors impossible too because they get called after we've + totally commited to creating a route object, for example). + This problem has existed for years and no forward progress + has ever been made, and nobody steps up to try and salvage + this code, so we're going to finally just get rid of it. +Who: David S. Miller + +--------------------------- -- cgit v1.2.3 From 411ed3225733dbd83b4cbaaa992ef80d6ec1534e Mon Sep 17 00:00:00 2001 From: Michael Holzheu Date: Fri, 27 Apr 2007 16:01:49 +0200 Subject: [S390] zfcpdump support. s390 machines provide hardware support for creating Linux dumps on SCSI disks. For creating a dump a special purpose dump Linux is used. The first 32 MB of memory are saved by the hardware before the dump Linux is booted. Via an SCLP interface, the saved memory can be accessed from Linux. This patch exports memory and registers of the crashed Linux to userspace via a debugfs file. For more information refer to Documentation/s390/zfcpdump.txt, which is included in this patch. Signed-off-by: Michael Holzheu Signed-off-by: Martin Schwidefsky Signed-off-by: Heiko Carstens --- Documentation/s390/zfcpdump.txt | 87 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 Documentation/s390/zfcpdump.txt (limited to 'Documentation') diff --git a/Documentation/s390/zfcpdump.txt b/Documentation/s390/zfcpdump.txt new file mode 100644 index 00000000000..cf45d27c460 --- /dev/null +++ b/Documentation/s390/zfcpdump.txt @@ -0,0 +1,87 @@ +s390 SCSI dump tool (zfcpdump) + +System z machines (z900 or higher) provide hardware support for creating system +dumps on SCSI disks. The dump process is initiated by booting a dump tool, which +has to create a dump of the current (probably crashed) Linux image. In order to +not overwrite memory of the crashed Linux with data of the dump tool, the +hardware saves some memory plus the register sets of the boot cpu before the +dump tool is loaded. There exists an SCLP hardware interface to obtain the saved +memory afterwards. Currently 32 MB are saved. + +This zfcpdump implementation consists of a Linux dump kernel together with +a userspace dump tool, which are loaded together into the saved memory region +below 32 MB. zfcpdump is installed on a SCSI disk using zipl (as contained in +the s390-tools package) to make the device bootable. The operator of a Linux +system can then trigger a SCSI dump by booting the SCSI disk, where zfcpdump +resides on. + +The kernel part of zfcpdump is implemented as a debugfs file under "zcore/mem", +which exports memory and registers of the crashed Linux in an s390 +standalone dump format. It can be used in the same way as e.g. /dev/mem. The +dump format defines a 4K header followed by plain uncompressed memory. The +register sets are stored in the prefix pages of the respective cpus. To build a +dump enabled kernel with the zcore driver, the kernel config option +CONFIG_ZFCPDUMP has to be set. When reading from "zcore/mem", the part of +memory, which has been saved by hardware is read by the driver via the SCLP +hardware interface. The second part is just copied from the non overwritten real +memory. + +The userspace application of zfcpdump can reside e.g. in an intitramfs or an +initrd. It reads from zcore/mem and writes the system dump to a file on a +SCSI disk. + +To build a zfcpdump kernel use the following settings in your kernel +configuration: + * CONFIG_ZFCPDUMP=y + * Enable ZFCP driver + * Enable SCSI driver + * Enable ext2 and ext3 filesystems + * Disable as many features as possible to keep the kernel small. + E.g. network support is not needed at all. + +To use the zfcpdump userspace application in an initramfs you have to do the +following: + + * Copy the zfcpdump executable somewhere into your Linux tree. + E.g. to "arch/s390/boot/zfcpdump. If you do not want to include + shared libraries, compile the tool with the "-static" gcc option. + * If you want to include e2fsck, add it to your source tree, too. The zfcpdump + application attempts to start /sbin/e2fsck from the ramdisk. + * Use an initramfs config file like the following: + + dir /dev 755 0 0 + nod /dev/console 644 0 0 c 5 1 + nod /dev/null 644 0 0 c 1 3 + nod /dev/sda1 644 0 0 b 8 1 + nod /dev/sda2 644 0 0 b 8 2 + nod /dev/sda3 644 0 0 b 8 3 + nod /dev/sda4 644 0 0 b 8 4 + nod /dev/sda5 644 0 0 b 8 5 + nod /dev/sda6 644 0 0 b 8 6 + nod /dev/sda7 644 0 0 b 8 7 + nod /dev/sda8 644 0 0 b 8 8 + nod /dev/sda9 644 0 0 b 8 9 + nod /dev/sda10 644 0 0 b 8 10 + nod /dev/sda11 644 0 0 b 8 11 + nod /dev/sda12 644 0 0 b 8 12 + nod /dev/sda13 644 0 0 b 8 13 + nod /dev/sda14 644 0 0 b 8 14 + nod /dev/sda15 644 0 0 b 8 15 + file /init arch/s390/boot/zfcpdump 755 0 0 + file /sbin/e2fsck arch/s390/boot/e2fsck 755 0 0 + dir /proc 755 0 0 + dir /sys 755 0 0 + dir /mnt 755 0 0 + dir /sbin 755 0 0 + + * Issue "make image" to build the zfcpdump image with initramfs. + +In a Linux distribution the zfcpdump enabled kernel image must be copied to +/usr/share/zfcpdump/zfcpdump.image, where the s390 zipl tool is looking for the +dump kernel when preparing a SCSI dump disk. + +If you use a ramdisk copy it to "/usr/share/zfcpdump/zfcpdump.rd". + +For more information on how to use zfcpdump refer to the s390 'Using the Dump +Tools book', which is available from +http://www.ibm.com/developerworks/linux/linux390. -- cgit v1.2.3 From 131a395c18af43d824841642038e5cc0d48f0bd2 Mon Sep 17 00:00:00 2001 From: Jan Glauber Date: Fri, 27 Apr 2007 16:01:54 +0200 Subject: [S390] crypto: cleanup. Cleanup code and remove obsolete documentation. Signed-off-by: Jan Glauber Signed-off-by: Heiko Carstens Signed-off-by: Martin Schwidefsky --- Documentation/s390/crypto/crypto-API.txt | 83 -------------------------------- 1 file changed, 83 deletions(-) delete mode 100644 Documentation/s390/crypto/crypto-API.txt (limited to 'Documentation') diff --git a/Documentation/s390/crypto/crypto-API.txt b/Documentation/s390/crypto/crypto-API.txt deleted file mode 100644 index 71ae6ca9f2c..00000000000 --- a/Documentation/s390/crypto/crypto-API.txt +++ /dev/null @@ -1,83 +0,0 @@ -crypto-API support for z990 Message Security Assist (MSA) instructions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -AUTHOR: Thomas Spatzier (tspat@de.ibm.com) - - -1. Introduction crypto-API -~~~~~~~~~~~~~~~~~~~~~~~~~~ -See Documentation/crypto/api-intro.txt for an introduction/description of the -kernel crypto API. -According to api-intro.txt support for z990 crypto instructions has been added -in the algorithm api layer of the crypto API. Several files containing z990 -optimized implementations of crypto algorithms are placed in the -arch/s390/crypto directory. - - -2. Probing for availability of MSA -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It should be possible to use Kernels with the z990 crypto implementations both -on machines with MSA available and on those without MSA (pre z990 or z990 -without MSA). Therefore a simple probing mechanism has been implemented: -In the init function of each crypto module the availability of MSA and of the -respective crypto algorithm in particular will be tested. If the algorithm is -available the module will load and register its algorithm with the crypto API. - -If the respective crypto algorithm is not available, the init function will -return -ENOSYS. In that case a fallback to the standard software implementation -of the crypto algorithm must be taken ( -> the standard crypto modules are -also built when compiling the kernel). - - -3. Ensuring z990 crypto module preference -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If z990 crypto instructions are available the optimized modules should be -preferred instead of standard modules. - -3.1. compiled-in modules -~~~~~~~~~~~~~~~~~~~~~~~~ -For compiled-in modules it has to be ensured that the z990 modules are linked -before the standard crypto modules. Then, on system startup the init functions -of z990 crypto modules will be called first and query for availability of z990 -crypto instructions. If instruction is available, the z990 module will register -its crypto algorithm implementation -> the load of the standard module will fail -since the algorithm is already registered. -If z990 crypto instruction is not available the load of the z990 module will -fail -> the standard module will load and register its algorithm. - -3.2. dynamic modules -~~~~~~~~~~~~~~~~~~~~ -A system administrator has to take care of giving preference to z990 crypto -modules. If MSA is available appropriate lines have to be added to -/etc/modprobe.conf. - -Example: z990 crypto instruction for SHA1 algorithm is available - - add the following line to /etc/modprobe.conf (assuming the - z990 crypto modules for SHA1 is called sha1_z990): - - alias sha1 sha1_z990 - - -> when the sha1 algorithm is requested through the crypto API - (which has a module autoloader) the z990 module will be loaded. - -TBD: a userspace module probing mechanism - something like 'probe sha1 sha1_z990 sha1' in modprobe.conf - -> try module sha1_z990, if it fails to load standard module sha1 - the 'probe' statement is currently not supported in modprobe.conf - - -4. Currently implemented z990 crypto algorithms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following crypto algorithms with z990 MSA support are currently implemented. -The name of each algorithm under which it is registered in crypto API and the -name of the respective module is given in square brackets. - -- SHA1 Digest Algorithm [sha1 -> sha1_z990] -- DES Encrypt/Decrypt Algorithm (64bit key) [des -> des_z990] -- Triple DES Encrypt/Decrypt Algorithm (128bit key) [des3_ede128 -> des_z990] -- Triple DES Encrypt/Decrypt Algorithm (192bit key) [des3_ede -> des_z990] - -In order to load, for example, the sha1_z990 module when the sha1 algorithm is -requested (see 3.2.) add 'alias sha1 sha1_z990' to /etc/modprobe.conf. - -- cgit v1.2.3 From 3106d46f51a1a72fdbf071ebc0800a9bcfcbc544 Mon Sep 17 00:00:00 2001 From: Adrian Bunk Date: Fri, 6 Apr 2007 12:21:45 +0200 Subject: the overdue removal of the mount/umount uevents This patch contains the overdue removal of the mount/umount uevents. Signed-off-by: Adrian Bunk Signed-off-by: Greg Kroah-Hartman --- Documentation/feature-removal-schedule.txt | 9 --------- 1 file changed, 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 6da663607f7..ec0b4843b1c 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -134,15 +134,6 @@ Who: Arjan van de Ven --------------------------- -What: mount/umount uevents -When: February 2007 -Why: These events are not correct, and do not properly let userspace know - when a file system has been mounted or unmounted. Userspace should - poll the /proc/mounts file instead to detect this properly. -Who: Greg Kroah-Hartman - ---------------------------- - What: USB driver API moves to EXPORT_SYMBOL_GPL When: February 2008 Files: include/linux/usb.h, drivers/usb/core/driver.c -- cgit v1.2.3 From b7eee616ad8db5db5441a7d82083003df3ab6d3b Mon Sep 17 00:00:00 2001 From: Antoine Jacquet Date: Fri, 27 Apr 2007 12:30:59 -0300 Subject: V4L/DVB (5257): USB: add zr364xx V4L2 driver This patch adds a V4L2 driver giving support for USB webcams based on the zr364xx chipsets. Signed-off-by: Antoine Jacquet Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/zr364xx.txt | 65 +++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 Documentation/video4linux/zr364xx.txt (limited to 'Documentation') diff --git a/Documentation/video4linux/zr364xx.txt b/Documentation/video4linux/zr364xx.txt new file mode 100644 index 00000000000..c76992d0ff4 --- /dev/null +++ b/Documentation/video4linux/zr364xx.txt @@ -0,0 +1,65 @@ +Zoran 364xx based USB webcam module version 0.72 +site: http://royale.zerezo.com/zr364xx/ +mail: royale@zerezo.com + +introduction: +This brings support under Linux for the Aiptek PocketDV 3300 in webcam mode. +If you just want to get on your PC the pictures and movies on the camera, you should use the usb-storage module instead. +The driver works with several other cameras in webcam mode (see the list below). +Maybe this code can work for other JPEG/USB cams based on the Coach chips from Zoran? +Possible chipsets are : ZR36430 (ZR36430BGC) and maybe ZR36431, ZR36440, ZR36442... +You can try the experience changing the vendor/product ID values (look at the source code). +You can get these values by looking at /var/log/messages when you plug your camera, or by typing : cat /proc/bus/usb/devices. +If you manage to use your cam with this code, you can send me a mail (royale@zerezo.com) with the name of your cam and a patch if needed. +This is a beta release of the driver. +Since version 0.70, this driver is only compatible with V4L2 API and 2.6.x kernels. +If you need V4L1 or 2.4x kernels support, please use an older version, but the code is not maintained anymore. +Good luck! + +install: +In order to use this driver, you must compile it with your kernel. +Location: Device Drivers -> Multimedia devices -> Video For Linux -> Video Capture Adapters -> V4L USB devices + +usage: +modprobe zr364xx debug=X mode=Y + - debug : set to 1 to enable verbose debug messages + - mode : 0 = 320x240, 1 = 160x120, 2 = 640x480 +You can then use the camera with V4L2 compatible applications, for example Ekiga. +To capture a single image, try this: dd if=/dev/video0 of=test.jpg bs=1 count=1 + +links : +http://mxhaard.free.fr/ (support for many others cams including some Aiptek PocketDV) +http://www.harmwal.nl/pccam880/ (this project also supports cameras based on this chipset) + +supported devices: +------ ------- ----------- ----- +Vendor Product Distributor Model +------ ------- ----------- ----- +0x08ca 0x0109 Aiptek PocketDV 3300 +0x08ca 0x0109 Maxell Maxcam PRO DV3 +0x041e 0x4024 Creative PC-CAM 880 +0x0d64 0x0108 Aiptek Fidelity 3200 +0x0d64 0x0108 Praktica DCZ 1.3 S +0x0d64 0x0108 Genius Digital Camera (?) +0x0d64 0x0108 DXG Technology Fashion Cam +0x0546 0x3187 Polaroid iON 230 +0x0d64 0x3108 Praktica Exakta DC 2200 +0x0d64 0x3108 Genius G-Shot D211 +0x0595 0x4343 Concord Eye-Q Duo 1300 +0x0595 0x4343 Concord Eye-Q Duo 2000 +0x0595 0x4343 Fujifilm EX-10 +0x0595 0x4343 Ricoh RDC-6000 +0x0595 0x4343 Digitrex DSC 1300 +0x0595 0x4343 Firstline FDC 2000 +0x0bb0 0x500d Concord EyeQ Go Wireless +0x0feb 0x2004 CRS Electronic 3.3 Digital Camera +0x0feb 0x2004 Packard Bell DSC-300 +0x055f 0xb500 Mustek MDC 3000 +0x08ca 0x2062 Aiptek PocketDV 5700 +0x052b 0x1a18 Chiphead Megapix V12 +0x04c8 0x0729 Konica Revio 2 +0x04f2 0xa208 Creative PC-CAM 850 +0x0784 0x0040 Traveler Slimline X5 +0x06d6 0x0034 Trust Powerc@m 750 +0x0a17 0x0062 Pentax Optio 50L + -- cgit v1.2.3 From 58ef4f924cf2824ae198b1fec3eea1e4059a021c Mon Sep 17 00:00:00 2001 From: Hartmut Hackmann Date: Fri, 27 Apr 2007 12:31:12 -0300 Subject: V4L/DVB (5314): Added support for tda827x tuners with preamlifiers This patch contains - new tuning code for the tda827xa silicon tuner. - controls the preamplifier of some boards with this tuner. - support for the Philips Tiger S hybrid DVB-T reference design. - reworked the saa7134-dvb modulue to get rid of most of the small board specific functions. Signed-off-by: Hartmut Hackmann Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.saa7134 | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index a12246a9bf2..f18533f28e0 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -107,3 +107,4 @@ 106 -> Encore ENLTV [1131:2342,1131:2341,3016:2344] 107 -> Encore ENLTV-FM [1131:230f] 108 -> Terratec Cinergy HT PCI [153b:1175] +109 -> Philips Tiger - S Reference design -- cgit v1.2.3 From e95d317da2de7116ef66fa16bd9664cd39f1c11c Mon Sep 17 00:00:00 2001 From: Markus Rechberger Date: Fri, 27 Apr 2007 12:31:19 -0300 Subject: V4L/DVB (5330): Added card definition for AverMedia M102 miniPCI Signed-off-by: Markus Rechberger Signed-off-by: Hartmut Hackmann Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.saa7134 | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index f18533f28e0..51f8a3fd66d 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -108,3 +108,4 @@ 107 -> Encore ENLTV-FM [1131:230f] 108 -> Terratec Cinergy HT PCI [153b:1175] 109 -> Philips Tiger - S Reference design +110 -> Avermedia M102 [1461:f31e] -- cgit v1.2.3 From db4836791dc578f0f6e9573468cffeee00fa7ebc Mon Sep 17 00:00:00 2001 From: Peter Missel Date: Fri, 27 Apr 2007 12:31:20 -0300 Subject: V4L/DVB (5331): Identify MSI TV@nywhere Duo It is a Lifeview Duo with a different ID Signed-off-by: Peter Missel Signed-off-by: Hartmut Hackmann Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.saa7134 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 51f8a3fd66d..9cbb048f4eb 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -53,7 +53,7 @@ 52 -> AverMedia AverTV/305 [1461:2108] 53 -> ASUS TV-FM 7135 [1043:4845] 54 -> LifeView FlyTV Platinum FM / Gold [5168:0214,1489:0214,5168:0304] - 55 -> LifeView FlyDVB-T DUO [5168:0306] + 55 -> LifeView FlyDVB-T DUO / MSI TV@nywhere Duo [5168:0306,4E42:0306] 56 -> Avermedia AVerTV 307 [1461:a70a] 57 -> Avermedia AVerTV GO 007 FM [1461:f31f] 58 -> ADS Tech Instant TV (saa7135) [1421:0350,1421:0351,1421:0370,1421:1370] -- cgit v1.2.3 From 0b20060f6c2cc69c5394cf9782513e7b526e87b9 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 27 Apr 2007 12:31:22 -0300 Subject: V4L/DVB (5336): Cx23416 doc updates + rename CX2341X_ENC_UNKNOWN The documentation of Several miscellaneous commands was updated. As a result of which the CX2341X_ENC_UNKNOWN command was renamed to CX2341X_ENC_SET_VERT_CROP_LINE. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/cx2341x/fw-encoder-api.txt | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/cx2341x/fw-encoder-api.txt b/Documentation/video4linux/cx2341x/fw-encoder-api.txt index 242104ce5b6..5dd3109a8b3 100644 --- a/Documentation/video4linux/cx2341x/fw-encoder-api.txt +++ b/Documentation/video4linux/cx2341x/fw-encoder-api.txt @@ -663,12 +663,13 @@ Param[0] ------------------------------------------------------------------------------- -Name CX2341X_ENC_UNKNOWN +Name CX2341X_ENC_SET_VERT_CROP_LINE Enum 219/0xDB Description - Unknown API, it's used by Hauppauge though. + Something to do with 'Vertical Crop Line' Param[0] - 0 This is the value Hauppauge uses, Unknown what it means. + If saa7114 and raw VBI capture and 60 Hz, then set to 10001. + Else 0. ------------------------------------------------------------------------------- @@ -682,11 +683,9 @@ Param[0] Command number: 1=set initial SCR value when starting encoding (works). 2=set quality mode (apparently some test setting). - 3=setup advanced VIM protection handling (supposedly only for the cx23416 - for raw YUV). - Actually it looks like this should be 0 for saa7114/5 based card and 1 - for cx25840 based cards. - 4=generate artificial PTS timestamps + 3=setup advanced VIM protection handling. + Always 1 for the cx23416 and 0 for cx23415. + 4=generate DVD compatible PTS timestamps 5=USB flush mode 6=something to do with the quantization matrix 7=set navigation pack insertion for DVD: adds 0xbf (private stream 2) @@ -698,7 +697,9 @@ Param[0] 9=set history parameters of the video input module 10=set input field order of VIM 11=set quantization matrix - 12=reset audio interface + 12=reset audio interface after channel change or input switch (has no argument). + Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to + do any harm calling it regardless. 13=set audio volume delay 14=set audio delay -- cgit v1.2.3 From 3f3f6a5958ffc651227df671704467654b71c09d Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 10 Mar 2007 08:10:11 -0300 Subject: V4L/DVB (5407a): Update feature-removal-schedule.txt: remove VIDIOC_S/G_MPEGCOMP Those two experimental APIs never worked fine nor, afaik, were implemented at the apps. Their functionalities were implemented by other means. So, let's remove those obsolete stuff. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/feature-removal-schedule.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'Documentation') diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 6da663607f7..67485630365 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -6,6 +6,18 @@ be removed from this file. --------------------------- +What: V4L2 VIDIOC_G_MPEGCOMP and VIDIOC_S_MPEGCOMP +When: October 2007 +Why: Broken attempt to set MPEG compression parameters. These ioctls are + not able to implement the wide variety of parameters that can be set + by hardware MPEG encoders. A new MPEG control mechanism was created + in kernel 2.6.18 that replaces these ioctls. See the V4L2 specification + (section 1.9: Extended controls) for more information on this topic. +Who: Hans Verkuil and + Mauro Carvalho Chehab + +--------------------------- + What: /sys/devices/.../power/state dev->power.power_state dpm_runtime_{suspend,resume)() -- cgit v1.2.3 From a542fe47fe3f758e47d71640e7ca328c032a13e1 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 10 Mar 2007 13:56:56 -0300 Subject: V4L/DVB (5409): Add CARDLIST.ivtv and README.ivtv Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.ivtv | 18 +++ Documentation/video4linux/README.ivtv | 187 ++++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 Documentation/video4linux/CARDLIST.ivtv create mode 100644 Documentation/video4linux/README.ivtv (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.ivtv b/Documentation/video4linux/CARDLIST.ivtv new file mode 100644 index 00000000000..ddd76a0eb10 --- /dev/null +++ b/Documentation/video4linux/CARDLIST.ivtv @@ -0,0 +1,18 @@ + 1 -> Hauppauge WinTV PVR-250 + 2 -> Hauppauge WinTV PVR-350 + 3 -> Hauppauge WinTV PVR-150 or PVR-500 + 4 -> AVerMedia M179 [1461:a3ce,1461:a3cf] + 5 -> Yuan MPG600/Kuroutoshikou iTVC16-STVLP [12ab:fff3,12ab:ffff] + 6 -> Yuan MPG160/Kuroutoshikou iTVC15-STVLP [12ab:0000,10fc:40a0] + 7 -> Yuan PG600/DiamondMM PVR-550 [ff92:0070,ffab:0600] + 8 -> Adaptec AVC-2410 [9005:0093] + 9 -> Adaptec AVC-2010 [9005:0092] +10 -> NAGASE TRANSGEAR 5000TV [1461:bfff] +11 -> AOpen VA2000MAX-STN6 [0000:ff5f] +12 -> YUAN MPG600GR/Kuroutoshikou CX23416GYC-STVLP [12ab:0600,fbab:0600,1154:0523] +13 -> I/O Data GV-MVP/RX [10fc:d01e,10fc:d038,10fc:d039] +14 -> I/O Data GV-MVP/RX2E [10fc:d025] +15 -> GOTVIEW PCI DVD (partial support only) [12ab:0600] +16 -> GOTVIEW PCI DVD2 Deluxe [ffac:0600] +17 -> Yuan MPC622 [ff01:d998] +18 -> Digital Cowboy DCT-MTVP1 [1461:bfff] diff --git a/Documentation/video4linux/README.ivtv b/Documentation/video4linux/README.ivtv new file mode 100644 index 00000000000..73df22c40bf --- /dev/null +++ b/Documentation/video4linux/README.ivtv @@ -0,0 +1,187 @@ + +ivtv release notes +================== + +This is a v4l2 device driver for the Conexant cx23415/6 MPEG encoder/decoder. +The cx23415 can do both encoding and decoding, the cx23416 can only do MPEG +encoding. Currently the only card featuring full decoding support is the +Hauppauge PVR-350. + +NOTE: this driver requires the latest encoder firmware (version 2.06.039, size +376836 bytes). Get the firmware from here: + +http://dl.ivtvdriver.org/ivtv/firmware/firmware.tar.gz + +NOTE: 'normal' TV applications do not work with this driver, you need +an application that can handle MPEG input such as mplayer, xine, MythTV, +etc. + +The primary goal of the IVTV project is to provide a "clean room" Linux +Open Source driver implementation for video capture cards based on the +iCompression iTVC15 or Conexant CX23415/CX23416 MPEG Codec. + +Features: + * Hardware mpeg2 capture of broadcast video (and sound) via the tuner or + S-Video/Composite and audio line-in. + * Hardware mpeg2 capture of FM radio where hardware support exists + * Supports NTSC, PAL, SECAM with stereo sound + * Supports SAP and bilingual transmissions. + * Supports raw VBI (closed captions and teletext). + * Supports sliced VBI (closed captions and teletext) and is able to insert + this into the captured MPEG stream. + * Supports raw YUV and PCM input. + +Additional features for the PVR-350 (CX23415 based): + * Provides hardware mpeg2 playback + * Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the + video signal) + * Provides a framebuffer (allowing X applications to appear on the video + device) (this framebuffer is not yet part of the kernel. In the meantime it + is available from www.ivtvdriver.org). + * Supports raw YUV output. + +IMPORTANT: In case of problems first read this page: + http://www.ivtvdriver.org/index.php/Troubleshooting + +See also: + +Homepage + Wiki +http://www.ivtvdriver.org + +IRC +irc://irc.freenode.net/ivtv-dev + +---------------------------------------------------------- + +Devices +======= + +A maximum of 12 ivtv boards are allowed at the moment. + +Cards that don't have a video output capability (i.e. non PVR350 cards) +lack the vbi8, vbi16, video16 and video48 devices. They also do not +support the framebuffer device /dev/fbx for OSD. + +The radio0 device may or may not be present, depending on whether the +card has a radio tuner or not. + +Here is a list of the base v4l devices: +crw-rw---- 1 root video 81, 0 Jun 19 22:22 /dev/video0 +crw-rw---- 1 root video 81, 16 Jun 19 22:22 /dev/video16 +crw-rw---- 1 root video 81, 24 Jun 19 22:22 /dev/video24 +crw-rw---- 1 root video 81, 32 Jun 19 22:22 /dev/video32 +crw-rw---- 1 root video 81, 48 Jun 19 22:22 /dev/video48 +crw-rw---- 1 root video 81, 64 Jun 19 22:22 /dev/radio0 +crw-rw---- 1 root video 81, 224 Jun 19 22:22 /dev/vbi0 +crw-rw---- 1 root video 81, 228 Jun 19 22:22 /dev/vbi8 +crw-rw---- 1 root video 81, 232 Jun 19 22:22 /dev/vbi16 + +Base devices +============ + +For every extra card you have the numbers increased by one. For example, +/dev/video0 is listed as the 'base' encoding capture device so we have: + + /dev/video0 is the encoding capture device for the first card (card 0) + /dev/video1 is the encoding capture device for the second card (card 1) + /dev/video2 is the encoding capture device for the third card (card 2) + +Note that if the first card doesn't have a feature (eg no decoder, so no +video16, the second card will still use video17. The simple rule is 'add +the card number to the base device number'. If you have other capture +cards (e.g. WinTV PCI) that are detected first, then you have to tell +the ivtv module about it so that it will start counting at 1 (or 2, or +whatever). Otherwise the device numbers can get confusing. The ivtv +'ivtv_first_minor' module option can be used for that. + + +/dev/video0 +The encoding capture device(s). +Read-only. + +Reading from this device gets you the MPEG1/2 program stream. +Example: + +cat /dev/video0 > my.mpg (you need to hit ctrl-c to exit) + + +/dev/video16 +The decoder output device(s) +Write-only. Only present if the MPEG decoder (i.e. CX23415) exists. + +An mpeg2 stream sent to this device will appear on the selected video +display, audio will appear on the line-out/audio out. It is only +available for cards that support video out. Example: + +cat my.mpg >/dev/video16 + + +/dev/video24 +The raw audio capture device(s). +Read-only + +The raw audio PCM stereo stream from the currently selected +tuner or audio line-in. Reading from this device results in a raw +(signed 16 bit Little Endian, 48000 Hz, stereo pcm) capture. +This device only captures audio. This should be replaced by an ALSA +device in the future. +Note that there is no corresponding raw audio output device, this is +not supported in the decoder firmware. + + +/dev/video32 +The raw video capture device(s) +Read-only + +The raw YUV video output from the current video input. The YUV format +is non-standard (V4L2_PIX_FMT_HM12). + +Note that the YUV and PCM streams are not synchronized, so they are of +limited use. + + +/dev/video48 +The raw video display device(s) +Write-only. Only present if the MPEG decoder (i.e. CX23415) exists. + +Writes a YUV stream to the decoder of the card. + + +/dev/radio0 +The radio tuner device(s) +Cannot be read or written. + +Used to enable the radio tuner and tune to a frequency. You cannot +read or write audio streams with this device. Once you use this +device to tune the radio, use /dev/video24 to read the raw pcm stream +or /dev/video0 to get an mpeg2 stream with black video. + + +/dev/vbi0 +The 'vertical blank interval' (Teletext, CC, WSS etc) capture device(s) +Read-only + +Captures the raw (or sliced) video data sent during the Vertical Blank +Interval. This data is used to encode teletext, closed captions, VPS, +widescreen signalling, electronic program guide information, and other +services. + + +/dev/vbi8 +Processed vbi feedback device(s) +Read-only. Only present if the MPEG decoder (i.e. CX23415) exists. + +The sliced VBI data embedded in an MPEG stream is reproduced on this +device. So while playing back a recording on /dev/video16, you can +read the embedded VBI data from /dev/vbi8. + + +/dev/vbi16 +The vbi 'display' device(s) +Write-only. Only present if the MPEG decoder (i.e. CX23415) exists. + +Can be used to send sliced VBI data to the video-out connector. + +--------------------------------- + +Hans Verkuil -- cgit v1.2.3 From 733aeaf4c006353b1ed8c54b707c03a6385c30ed Mon Sep 17 00:00:00 2001 From: Michael Krufky Date: Sun, 11 Mar 2007 12:48:04 -0300 Subject: V4L/DVB (5431): Cx88: autodetect ADS Tech InstantTV DVB-S The ADS Tech InstantTV DVB-S is a clone of the KWorld DVB-S 100. This patch adds autodetection support for this card based on pci subsystem id. Signed-off-by: Michael Krufky Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.cx88 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88 index 62e32b49cec..60f838beb9c 100644 --- a/Documentation/video4linux/CARDLIST.cx88 +++ b/Documentation/video4linux/CARDLIST.cx88 @@ -37,7 +37,7 @@ 36 -> AVerTV 303 (M126) [1461:000a] 37 -> Hauppauge Nova-S-Plus DVB-S [0070:9201,0070:9202] 38 -> Hauppauge Nova-SE2 DVB-S [0070:9200] - 39 -> KWorld DVB-S 100 [17de:08b2] + 39 -> KWorld DVB-S 100 [17de:08b2,1421:0341] 40 -> Hauppauge WinTV-HVR1100 DVB-T/Hybrid [0070:9400,0070:9402] 41 -> Hauppauge WinTV-HVR1100 DVB-T/Hybrid (Low Profile) [0070:9800,0070:9802] 42 -> digitalnow DNTV Live! DVB-T Pro [1822:0025,1822:0019] -- cgit v1.2.3 From 59fc7f52898fb35eb053bc7b54430d81629b5966 Mon Sep 17 00:00:00 2001 From: Ian Armstrong Date: Fri, 16 Mar 2007 07:40:48 -0300 Subject: V4L/DVB (5437): Update cx23415 documentation Adds more osd mode switching information. Corrects some information regarding mode selection & local alpha operation for 16 bit modes. Signed-off-by: Ian Armstrong Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/cx2341x/fw-decoder-regs.txt | 12 +++++++----- Documentation/video4linux/cx2341x/fw-osd-api.txt | 12 ++++++++++-- 2 files changed, 17 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/cx2341x/fw-decoder-regs.txt b/Documentation/video4linux/cx2341x/fw-decoder-regs.txt index db2366c634e..cf52c8f20b9 100644 --- a/Documentation/video4linux/cx2341x/fw-decoder-regs.txt +++ b/Documentation/video4linux/cx2341x/fw-decoder-regs.txt @@ -624,11 +624,11 @@ out what values are bad when it hangs. 2A00 bits 0:2 osd colour mode + 000 = 8 bit indexed 001 = 16 bit (565) 010 = 15 bit (555) 011 = 12 bit (444) 100 = 32 bit (8888) - 101 = 8 bit indexed bits 4:5 osd display bpp @@ -676,9 +676,11 @@ out what values are bad when it hangs. completely transparent. When using 565, 555 or 444 colour modes, the colour key is always 16 bits wide. The colour to key on is set in Reg 2A18. - Local alpha is a per-pixel 256 step transparency, with 0 being transparent - and 255 being solid. This is only available in 32 bit & 8 bit indexed - colour modes. + Local alpha works differently depending on the colour mode. For 32bpp & 8 + bit indexed, local alpha is a per-pixel 256 step transparency, with 0 being + transparent and 255 being solid. For the 16bpp modes 555 & 444, the unused + bit(s) act as a simple transparency switch, with 0 being solid & 1 being + fully transparent. There is no local alpha support for 16bit 565. Global alpha is a 256 step transparency that applies to the entire osd, with 0 being transparent & 255 being solid. @@ -811,5 +813,5 @@ out what values are bad when it hangs. -------------------------------------------------------------------------------- -v0.3 - 2 February 2007 - Ian Armstrong (ian@iarmst.demon.co.uk) +v0.4 - 12 March 2007 - Ian Armstrong (ian@iarmst.demon.co.uk) diff --git a/Documentation/video4linux/cx2341x/fw-osd-api.txt b/Documentation/video4linux/cx2341x/fw-osd-api.txt index 0a602f3e601..89c4601042c 100644 --- a/Documentation/video4linux/cx2341x/fw-osd-api.txt +++ b/Documentation/video4linux/cx2341x/fw-osd-api.txt @@ -21,7 +21,11 @@ Enum 66/0x42 Description Query OSD format Result[0] - 0=8bit index, 4=AlphaRGB 8:8:8:8 + 0=8bit index + 1=16bit RGB 5:6:5 + 2=16bit ARGB 1:5:5:5 + 3=16bit ARGB 1:4:4:4 + 4=32bit ARGB 8:8:8:8 ------------------------------------------------------------------------------- @@ -30,7 +34,11 @@ Enum 67/0x43 Description Assign pixel format Param[0] - 0=8bit index, 4=AlphaRGB 8:8:8:8 + 0=8bit index + 1=16bit RGB 5:6:5 + 2=16bit ARGB 1:5:5:5 + 3=16bit ARGB 1:4:4:4 + 4=32bit ARGB 8:8:8:8 ------------------------------------------------------------------------------- -- cgit v1.2.3 From e06cea4cb4a16076dfca4863b12e1c4aeb781c8d Mon Sep 17 00:00:00 2001 From: Hartmut Hackmann Date: Tue, 13 Mar 2007 20:58:29 -0300 Subject: V4L/DVB (5445): Added / corrected support for some ASUS hybrid boards There are 2 new entries for p7131 boards and one correction for a board with LNA. Signed-off-by: Hartmut Hackmann Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.saa7134 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 9cbb048f4eb..1210b8bf6ad 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -76,7 +76,7 @@ 75 -> AVerMedia AVerTVHD MCE A180 [1461:1044] 76 -> SKNet MonsterTV Mobile [1131:4ee9] 77 -> Pinnacle PCTV 40i/50i/110i (saa7133) [11bd:002e] - 78 -> ASUSTeK P7131 Dual [1043:4862,1043:4876] + 78 -> ASUSTeK P7131 Dual [1043:4862,1043:4857] 79 -> Sedna/MuchTV PC TV Cardbus TV/Radio (ITO25 Rev:2B) 80 -> ASUS Digimatrix TV [1043:0210] 81 -> Philips Tiger reference design [1131:2018] @@ -109,3 +109,5 @@ 108 -> Terratec Cinergy HT PCI [153b:1175] 109 -> Philips Tiger - S Reference design 110 -> Avermedia M102 [1461:f31e] +111 -> ASUS P7131 4871 [1043:4871] +112 -> ASUSTeK P7131 Dual LNA [1043:4876] -- cgit v1.2.3 From f3eec0c001a6781224d39912d41b58eaf2126586 Mon Sep 17 00:00:00 2001 From: Hartmut Hackmann Date: Wed, 14 Mar 2007 20:33:55 -0300 Subject: V4L/DVB (5446): Renamed ASUStek P7131 card [1043:4876] The new name fits to what it is and what is on the box. Signed-off-by: Hartmut Hackmann Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.saa7134 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 1210b8bf6ad..d7bb2e2e4d9 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -110,4 +110,4 @@ 109 -> Philips Tiger - S Reference design 110 -> Avermedia M102 [1461:f31e] 111 -> ASUS P7131 4871 [1043:4871] -112 -> ASUSTeK P7131 Dual LNA [1043:4876] +112 -> ASUSTeK P7131 Hybrid [1043:4876] -- cgit v1.2.3 From f423b9a86a6dd3d2bc08d78f4d21525a14c40a6b Mon Sep 17 00:00:00 2001 From: Luca Risolia Date: Mon, 26 Mar 2007 16:12:04 -0300 Subject: V4L/DVB (5474): SN9C1xx driver updates @ Don't assume that SOF headers can't cross packets boundaries @ Fix compression quality selection + Add support for MI-0360 image sensor * Documentation updates @ Fix sysfs @ MI0343 rewritten * HV7131R color fixes and add new ABLC control * Rename the archive from "sn9c102" to "sn9c1xx" * fix typos * better support for TAS5110D @ fix OV7630 wrong colors @ Don't return an error if no input buffers are enqueued yet on VIDIOC_STREAMON * Add informations about colorspaces * More appropriate error codes in case of failure of some system calls * More precise hardware detection * Add more informations about supported hardware in the documentation + More supported devices + Add support for HV7131R image sensor Signed-off-by: Luca Risolia Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/sn9c102.txt | 64 +++++++++++++++++++++-------------- 1 file changed, 38 insertions(+), 26 deletions(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/sn9c102.txt b/Documentation/video4linux/sn9c102.txt index 2913da3d087..5fe0ad7dfc2 100644 --- a/Documentation/video4linux/sn9c102.txt +++ b/Documentation/video4linux/sn9c102.txt @@ -25,7 +25,7 @@ Index 1. Copyright ============ -Copyright (C) 2004-2006 by Luca Risolia +Copyright (C) 2004-2007 by Luca Risolia 2. Disclaimer @@ -216,10 +216,10 @@ Description: Debugging information level, from 0 to 3: 1 = critical errors 2 = significant informations 3 = more verbose messages - Level 3 is useful for testing only, when only one device - is used. It also shows some more informations about the - hardware being detected. This parameter can be changed at - runtime thanks to the /sys filesystem interface. + Level 3 is useful for testing only. It also shows some more + informations about the hardware being detected. + This parameter can be changed at runtime thanks to the /sys + filesystem interface. Default: 2 ------------------------------------------------------------------------------- @@ -235,7 +235,7 @@ created in the /sys/class/video4linux/videoX directory. You can set the green channel's gain by writing the desired value to it. The value may range from 0 to 15 for the SN9C101 or SN9C102 bridges, from 0 to 127 for the SN9C103, SN9C105 and SN9C120 bridges. -Similarly, only for the SN9C103, SN9C105 and SN9120 controllers, blue and red +Similarly, only for the SN9C103, SN9C105 and SN9C120 controllers, blue and red gain control files are available in the same directory, for which accepted values may range from 0 to 127. @@ -402,38 +402,49 @@ Vendor ID Product ID 0x0c45 0x60bc 0x0c45 0x60be 0x0c45 0x60c0 +0x0c45 0x60c2 0x0c45 0x60c8 0x0c45 0x60cc 0x0c45 0x60ea 0x0c45 0x60ec +0x0c45 0x60ef 0x0c45 0x60fa 0x0c45 0x60fb 0x0c45 0x60fc 0x0c45 0x60fe +0x0c45 0x6102 +0x0c45 0x6108 +0x0c45 0x610f 0x0c45 0x6130 +0x0c45 0x6138 0x0c45 0x613a 0x0c45 0x613b 0x0c45 0x613c 0x0c45 0x613e The list above does not imply that all those devices work with this driver: up -until now only the ones that assemble the following image sensors are -supported; kernel messages will always tell you whether this is the case (see -"Module loading" paragraph): - -Model Manufacturer ------ ------------ -HV7131D Hynix Semiconductor, Inc. -MI-0343 Micron Technology, Inc. -OV7630 OmniVision Technologies, Inc. -OV7660 OmniVision Technologies, Inc. -PAS106B PixArt Imaging, Inc. -PAS202BCA PixArt Imaging, Inc. -PAS202BCB PixArt Imaging, Inc. -TAS5110C1B Taiwan Advanced Sensor Corporation -TAS5130D1B Taiwan Advanced Sensor Corporation - -Some of the available control settings of each image sensor are supported +until now only the ones that assemble the following pairs of SN9C1xx bridges +and image sensors are supported; kernel messages will always tell you whether +this is the case (see "Module loading" paragraph): + +Image sensor / SN9C1xx bridge | SN9C10[12] SN9C103 SN9C105 SN9C120 +------------------------------------------------------------------------------- +HV7131D Hynix Semiconductor | Yes No No No +HV7131R Hynix Semiconductor | No Yes Yes Yes +MI-0343 Micron Technology | Yes No No No +MI-0360 Micron Technology | No Yes No No +OV7630 OmniVision Technologies | Yes Yes No No +OV7660 OmniVision Technologies | No No Yes Yes +PAS106B PixArt Imaging | Yes No No No +PAS202B PixArt Imaging | Yes Yes No No +TAS5110C1B Taiwan Advanced Sensor | Yes No No No +TAS5110D Taiwan Advanced Sensor | Yes No No No +TAS5130D1B Taiwan Advanced Sensor | Yes No No No + +"Yes" means that the pair is supported by the driver, while "No" means that the +pair does not exist or is not supported by the driver. + +Only some of the available control settings of each image sensor are supported through the V4L2 interface. Donations of new models for further testing and support would be much @@ -482,8 +493,8 @@ The SN9C1xx PC Camera Controllers can send images in two possible video formats over the USB: either native "Sequential RGB Bayer" or compressed. The compression is used to achieve high frame rates. With regard to the SN9C101, SN9C102 and SN9C103, the compression is based on the Huffman encoding -algorithm described below, while the SN9C105 and SN9C120 the compression is -based on the JPEG standard. +algorithm described below, while with regard to the SN9C105 and SN9C120 the +compression is based on the JPEG standard. The current video format may be selected or queried from the user application by calling the VIDIOC_S_FMT or VIDIOC_G_FMT ioctl's, as described in the V4L2 API specifications. @@ -573,4 +584,5 @@ order): - Mizuno Takafumi for the donation of a webcam; - an "anonymous" donator (who didn't want his name to be revealed) for the donation of a webcam. -- an anonymous donator for the donation of four webcams. +- an anonymous donator for the donation of four webcams and two boards with ten + image sensors. -- cgit v1.2.3 From 1ebba670edac28d4ea37579453417ced71fd9128 Mon Sep 17 00:00:00 2001 From: Scott Alfter Date: Mon, 2 Apr 2007 14:22:39 -0300 Subject: V4L/DVB (5497): Additional card support for bttv driver SSAI (www.ssai.us) makes several Bt878-based capture cards that get used in our surveillance, conferencing, and medical imaging systems. The attached relatively small patch adds support for these cards, which fall into two broad * boards with one or more Bt878s, one or more composite inputs, and no S-video or tuner inputs * boards with one Bt878, one composite input, one S-video input, and no tuner input Signed-off-by: Scott Alfter Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.bttv | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.bttv b/Documentation/video4linux/CARDLIST.bttv index fc2fe9bc671..b60639130a5 100644 --- a/Documentation/video4linux/CARDLIST.bttv +++ b/Documentation/video4linux/CARDLIST.bttv @@ -143,3 +143,5 @@ 142 -> Sabrent TV-FM (bttv version) 143 -> Hauppauge ImpactVCB (bt878) [0070:13eb] 144 -> MagicTV +145 -> SSAI Security Video Interface [4149:5353] +146 -> SSAI Ultrasound Video Interface [414a:5353] -- cgit v1.2.3 From 0ee32871c18a3662d8958a8e9998eb4d2ae94159 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 3 Apr 2007 18:08:19 -0300 Subject: V4L/DVB (5500): Add a CARDLIST for the supported devices by usbvision driver Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.usbvision | 65 ++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 Documentation/video4linux/CARDLIST.usbvision (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.usbvision b/Documentation/video4linux/CARDLIST.usbvision new file mode 100644 index 00000000000..9f03e86e9ce --- /dev/null +++ b/Documentation/video4linux/CARDLIST.usbvision @@ -0,0 +1,65 @@ + 0 -> Custom Dummy USBVision Device [fff0:fff0] + 1 -> Xanboo [0a6f:0400] + 2 -> Belkin USB VideoBus II Adapter [050d:0106] + 3 -> Belkin Components USB VideoBus [050d:0207] + 4 -> Belkin USB VideoBus II [050d:0208] + 5 -> echoFX InterView Lite [0571:0002] + 6 -> USBGear USBG-V1 resp. HAMA USB [0573:0003] + 7 -> D-Link V100 [0573:0400] + 8 -> X10 USB Camera [0573:2000] + 9 -> Hauppauge WinTV USB Live (PAL B/G) [0573:2d00] + 10 -> Hauppauge WinTV USB Live Pro (NTSC M/N) [0573:2d01] + 11 -> Zoran Co. PMD (Nogatech) AV-grabber Manhattan [0573:2101] + 12 -> Nogatech USB-TV (NTSC) FM [0573:4100] + 13 -> PNY USB-TV (NTSC) FM [0573:4110] + 14 -> PixelView PlayTv-USB PRO (PAL) FM [0573:4450] + 15 -> ZTV ZT-721 2.4GHz USB A/V Receiver [0573:4550] + 16 -> Hauppauge WinTV USB (NTSC M/N) [0573:4d00] + 17 -> Hauppauge WinTV USB (PAL B/G) [0573:4d01] + 18 -> Hauppauge WinTV USB (PAL I) [0573:4d02] + 19 -> Hauppauge WinTV USB (PAL/SECAM L) [0573:4d03] + 20 -> Hauppauge WinTV USB (PAL D/K) [0573:4d04] + 21 -> Hauppauge WinTV USB (NTSC FM) [0573:4d10] + 22 -> Hauppauge WinTV USB (PAL B/G FM) [0573:4d11] + 23 -> Hauppauge WinTV USB (PAL I FM) [0573:4d12] + 24 -> Hauppauge WinTV USB (PAL D/K FM) [0573:4d14] + 25 -> Hauppauge WinTV USB Pro (NTSC M/N) [0573:4d2a] + 26 -> Hauppauge WinTV USB Pro (NTSC M/N) [0573:4d2b] + 27 -> Hauppauge WinTV USB Pro (PAL/SECAM B/G/I/D/K/L) [0573:4d2c] + 28 -> Hauppauge WinTV USB Pro (NTSC M/N) [0573:4d20] + 29 -> Hauppauge WinTV USB Pro (PAL B/G) [0573:4d21] + 30 -> Hauppauge WinTV USB Pro (PAL I) [0573:4d22] + 31 -> Hauppauge WinTV USB Pro (PAL/SECAM L) [0573:4d23] + 32 -> Hauppauge WinTV USB Pro (PAL D/K) [0573:4d24] + 33 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) [0573:4d25] + 34 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) [0573:4d26] + 35 -> Hauppauge WinTV USB Pro (PAL B/G) [0573:4d27] + 36 -> Hauppauge WinTV USB Pro (PAL B/G,D/K) [0573:4d28] + 37 -> Hauppauge WinTV USB Pro (PAL I,D/K) [0573:4d29] + 38 -> Hauppauge WinTV USB Pro (NTSC M/N FM) [0573:4d30] + 39 -> Hauppauge WinTV USB Pro (PAL B/G FM) [0573:4d31] + 40 -> Hauppauge WinTV USB Pro (PAL I FM) [0573:4d32] + 41 -> Hauppauge WinTV USB Pro (PAL D/K FM) [0573:4d34] + 42 -> Hauppauge WinTV USB Pro (Temic PAL/SECAM B/G/I/D/K/L FM) [0573:4d35] + 43 -> Hauppauge WinTV USB Pro (Temic PAL B/G FM) [0573:4d36] + 44 -> Hauppauge WinTV USB Pro (PAL/SECAM B/G/I/D/K/L FM) [0573:4d37] + 45 -> Hauppauge WinTV USB Pro (NTSC M/N FM) [0573:4d38] + 46 -> Camtel Technology USB TV Genie Pro FM Model TVB330 [0768:0006] + 47 -> Digital Video Creator I [07d0:0001] + 48 -> Global Village GV-007 (NTSC) [07d0:0002] + 49 -> Dazzle Fusion Model DVC-50 Rev 1 (NTSC) [07d0:0003] + 50 -> Dazzle Fusion Model DVC-80 Rev 1 (PAL) [07d0:0004] + 51 -> Dazzle Fusion Model DVC-90 Rev 1 (SECAM) [07d0:0005] + 52 -> Eskape Labs MyTV2Go [07f8:9104] + 53 -> Pinnacle Studio PCTV USB (PAL) [2304:010d] + 54 -> Pinnacle Studio PCTV USB (SECAM) [2304:0109] + 55 -> Pinnacle Studio PCTV USB (PAL) FM [2304:0110] + 56 -> Miro PCTV USB [2304:0111] + 57 -> Pinnacle Studio PCTV USB (NTSC) FM [2304:0112] + 58 -> Pinnacle Studio PCTV USB (PAL) FM [2304:0210] + 59 -> Pinnacle Studio PCTV USB (NTSC) FM [2304:0212] + 60 -> Pinnacle Studio PCTV USB (PAL) FM [2304:0214] + 61 -> Pinnacle Studio Linx Video input cable (NTSC) [2304:0300] + 62 -> Pinnacle Studio Linx Video input cable (PAL) [2304:0301] + 63 -> Pinnacle PCTV Bungee USB (PAL) FM [2304:0419] + 64 -> Hauppauge WinTv-USB [2400:4200] -- cgit v1.2.3 From 659ae56dcd5a50e4560cb526a0e0dc881418dad4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 14 Apr 2007 15:09:59 -0300 Subject: V4L/DVB (5515): Use a better format to represent usbvision supported boards Changed usbvision cards table to allow: 1) Not repeat USB ID on two structs; 2) Not need to specify both usb and card description tables at the same order, removing some magic; Some cards had duplicated names. Fixed. A test for an specific board were doing by using a string comparation. The comparation were wrong. Also, it is not a good practice to recognize a board based on his string name. Acked-by: Thierry MERLE Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.usbvision | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.usbvision b/Documentation/video4linux/CARDLIST.usbvision index 9f03e86e9ce..ab110b7b5b9 100644 --- a/Documentation/video4linux/CARDLIST.usbvision +++ b/Documentation/video4linux/CARDLIST.usbvision @@ -24,16 +24,16 @@ 23 -> Hauppauge WinTV USB (PAL I FM) [0573:4d12] 24 -> Hauppauge WinTV USB (PAL D/K FM) [0573:4d14] 25 -> Hauppauge WinTV USB Pro (NTSC M/N) [0573:4d2a] - 26 -> Hauppauge WinTV USB Pro (NTSC M/N) [0573:4d2b] + 26 -> Hauppauge WinTV USB Pro (NTSC M/N) V2 [0573:4d2b] 27 -> Hauppauge WinTV USB Pro (PAL/SECAM B/G/I/D/K/L) [0573:4d2c] - 28 -> Hauppauge WinTV USB Pro (NTSC M/N) [0573:4d20] + 28 -> Hauppauge WinTV USB Pro (NTSC M/N) V3 [0573:4d20] 29 -> Hauppauge WinTV USB Pro (PAL B/G) [0573:4d21] 30 -> Hauppauge WinTV USB Pro (PAL I) [0573:4d22] 31 -> Hauppauge WinTV USB Pro (PAL/SECAM L) [0573:4d23] 32 -> Hauppauge WinTV USB Pro (PAL D/K) [0573:4d24] 33 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) [0573:4d25] - 34 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) [0573:4d26] - 35 -> Hauppauge WinTV USB Pro (PAL B/G) [0573:4d27] + 34 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) V2 [0573:4d26] + 35 -> Hauppauge WinTV USB Pro (PAL B/G) V2 [0573:4d27] 36 -> Hauppauge WinTV USB Pro (PAL B/G,D/K) [0573:4d28] 37 -> Hauppauge WinTV USB Pro (PAL I,D/K) [0573:4d29] 38 -> Hauppauge WinTV USB Pro (NTSC M/N FM) [0573:4d30] @@ -43,7 +43,7 @@ 42 -> Hauppauge WinTV USB Pro (Temic PAL/SECAM B/G/I/D/K/L FM) [0573:4d35] 43 -> Hauppauge WinTV USB Pro (Temic PAL B/G FM) [0573:4d36] 44 -> Hauppauge WinTV USB Pro (PAL/SECAM B/G/I/D/K/L FM) [0573:4d37] - 45 -> Hauppauge WinTV USB Pro (NTSC M/N FM) [0573:4d38] + 45 -> Hauppauge WinTV USB Pro (NTSC M/N FM) V2 [0573:4d38] 46 -> Camtel Technology USB TV Genie Pro FM Model TVB330 [0768:0006] 47 -> Digital Video Creator I [07d0:0001] 48 -> Global Village GV-007 (NTSC) [07d0:0002] @@ -56,9 +56,9 @@ 55 -> Pinnacle Studio PCTV USB (PAL) FM [2304:0110] 56 -> Miro PCTV USB [2304:0111] 57 -> Pinnacle Studio PCTV USB (NTSC) FM [2304:0112] - 58 -> Pinnacle Studio PCTV USB (PAL) FM [2304:0210] - 59 -> Pinnacle Studio PCTV USB (NTSC) FM [2304:0212] - 60 -> Pinnacle Studio PCTV USB (PAL) FM [2304:0214] + 58 -> Pinnacle Studio PCTV USB (PAL) FM V2 [2304:0210] + 59 -> Pinnacle Studio PCTV USB (NTSC) FM V2 [2304:0212] + 60 -> Pinnacle Studio PCTV USB (PAL) FM V3 [2304:0214] 61 -> Pinnacle Studio Linx Video input cable (NTSC) [2304:0300] 62 -> Pinnacle Studio Linx Video input cable (PAL) [2304:0301] 63 -> Pinnacle PCTV Bungee USB (PAL) FM [2304:0419] -- cgit v1.2.3 From ec709bb801a98dcac0a95c060c431eda73e31587 Mon Sep 17 00:00:00 2001 From: Thierry MERLE Date: Tue, 17 Apr 2007 02:28:32 -0300 Subject: V4L/DVB (5530): Usbvision: remove CustomDevice facility usbvision has a module parameter that ables the user to add a new USB entry at driver load. This functionality is useless by experience (adding statically the entry is easy). Furthermore, the USB_DEVICE(0xfff0, 0xfff0) USB entry caused usbvision_probe to be called for all unclaimed devices. Signed-off-by: Thierry MERLE Acked-by: Dwaine Garden Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/CARDLIST.usbvision | 129 +++++++++++++-------------- 1 file changed, 64 insertions(+), 65 deletions(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.usbvision b/Documentation/video4linux/CARDLIST.usbvision index ab110b7b5b9..3d6850ef024 100644 --- a/Documentation/video4linux/CARDLIST.usbvision +++ b/Documentation/video4linux/CARDLIST.usbvision @@ -1,65 +1,64 @@ - 0 -> Custom Dummy USBVision Device [fff0:fff0] - 1 -> Xanboo [0a6f:0400] - 2 -> Belkin USB VideoBus II Adapter [050d:0106] - 3 -> Belkin Components USB VideoBus [050d:0207] - 4 -> Belkin USB VideoBus II [050d:0208] - 5 -> echoFX InterView Lite [0571:0002] - 6 -> USBGear USBG-V1 resp. HAMA USB [0573:0003] - 7 -> D-Link V100 [0573:0400] - 8 -> X10 USB Camera [0573:2000] - 9 -> Hauppauge WinTV USB Live (PAL B/G) [0573:2d00] - 10 -> Hauppauge WinTV USB Live Pro (NTSC M/N) [0573:2d01] - 11 -> Zoran Co. PMD (Nogatech) AV-grabber Manhattan [0573:2101] - 12 -> Nogatech USB-TV (NTSC) FM [0573:4100] - 13 -> PNY USB-TV (NTSC) FM [0573:4110] - 14 -> PixelView PlayTv-USB PRO (PAL) FM [0573:4450] - 15 -> ZTV ZT-721 2.4GHz USB A/V Receiver [0573:4550] - 16 -> Hauppauge WinTV USB (NTSC M/N) [0573:4d00] - 17 -> Hauppauge WinTV USB (PAL B/G) [0573:4d01] - 18 -> Hauppauge WinTV USB (PAL I) [0573:4d02] - 19 -> Hauppauge WinTV USB (PAL/SECAM L) [0573:4d03] - 20 -> Hauppauge WinTV USB (PAL D/K) [0573:4d04] - 21 -> Hauppauge WinTV USB (NTSC FM) [0573:4d10] - 22 -> Hauppauge WinTV USB (PAL B/G FM) [0573:4d11] - 23 -> Hauppauge WinTV USB (PAL I FM) [0573:4d12] - 24 -> Hauppauge WinTV USB (PAL D/K FM) [0573:4d14] - 25 -> Hauppauge WinTV USB Pro (NTSC M/N) [0573:4d2a] - 26 -> Hauppauge WinTV USB Pro (NTSC M/N) V2 [0573:4d2b] - 27 -> Hauppauge WinTV USB Pro (PAL/SECAM B/G/I/D/K/L) [0573:4d2c] - 28 -> Hauppauge WinTV USB Pro (NTSC M/N) V3 [0573:4d20] - 29 -> Hauppauge WinTV USB Pro (PAL B/G) [0573:4d21] - 30 -> Hauppauge WinTV USB Pro (PAL I) [0573:4d22] - 31 -> Hauppauge WinTV USB Pro (PAL/SECAM L) [0573:4d23] - 32 -> Hauppauge WinTV USB Pro (PAL D/K) [0573:4d24] - 33 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) [0573:4d25] - 34 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) V2 [0573:4d26] - 35 -> Hauppauge WinTV USB Pro (PAL B/G) V2 [0573:4d27] - 36 -> Hauppauge WinTV USB Pro (PAL B/G,D/K) [0573:4d28] - 37 -> Hauppauge WinTV USB Pro (PAL I,D/K) [0573:4d29] - 38 -> Hauppauge WinTV USB Pro (NTSC M/N FM) [0573:4d30] - 39 -> Hauppauge WinTV USB Pro (PAL B/G FM) [0573:4d31] - 40 -> Hauppauge WinTV USB Pro (PAL I FM) [0573:4d32] - 41 -> Hauppauge WinTV USB Pro (PAL D/K FM) [0573:4d34] - 42 -> Hauppauge WinTV USB Pro (Temic PAL/SECAM B/G/I/D/K/L FM) [0573:4d35] - 43 -> Hauppauge WinTV USB Pro (Temic PAL B/G FM) [0573:4d36] - 44 -> Hauppauge WinTV USB Pro (PAL/SECAM B/G/I/D/K/L FM) [0573:4d37] - 45 -> Hauppauge WinTV USB Pro (NTSC M/N FM) V2 [0573:4d38] - 46 -> Camtel Technology USB TV Genie Pro FM Model TVB330 [0768:0006] - 47 -> Digital Video Creator I [07d0:0001] - 48 -> Global Village GV-007 (NTSC) [07d0:0002] - 49 -> Dazzle Fusion Model DVC-50 Rev 1 (NTSC) [07d0:0003] - 50 -> Dazzle Fusion Model DVC-80 Rev 1 (PAL) [07d0:0004] - 51 -> Dazzle Fusion Model DVC-90 Rev 1 (SECAM) [07d0:0005] - 52 -> Eskape Labs MyTV2Go [07f8:9104] - 53 -> Pinnacle Studio PCTV USB (PAL) [2304:010d] - 54 -> Pinnacle Studio PCTV USB (SECAM) [2304:0109] - 55 -> Pinnacle Studio PCTV USB (PAL) FM [2304:0110] - 56 -> Miro PCTV USB [2304:0111] - 57 -> Pinnacle Studio PCTV USB (NTSC) FM [2304:0112] - 58 -> Pinnacle Studio PCTV USB (PAL) FM V2 [2304:0210] - 59 -> Pinnacle Studio PCTV USB (NTSC) FM V2 [2304:0212] - 60 -> Pinnacle Studio PCTV USB (PAL) FM V3 [2304:0214] - 61 -> Pinnacle Studio Linx Video input cable (NTSC) [2304:0300] - 62 -> Pinnacle Studio Linx Video input cable (PAL) [2304:0301] - 63 -> Pinnacle PCTV Bungee USB (PAL) FM [2304:0419] - 64 -> Hauppauge WinTv-USB [2400:4200] + 0 -> Xanboo [0a6f:0400] + 1 -> Belkin USB VideoBus II Adapter [050d:0106] + 2 -> Belkin Components USB VideoBus [050d:0207] + 3 -> Belkin USB VideoBus II [050d:0208] + 4 -> echoFX InterView Lite [0571:0002] + 5 -> USBGear USBG-V1 resp. HAMA USB [0573:0003] + 6 -> D-Link V100 [0573:0400] + 7 -> X10 USB Camera [0573:2000] + 8 -> Hauppauge WinTV USB Live (PAL B/G) [0573:2d00] + 9 -> Hauppauge WinTV USB Live Pro (NTSC M/N) [0573:2d01] + 10 -> Zoran Co. PMD (Nogatech) AV-grabber Manhattan [0573:2101] + 11 -> Nogatech USB-TV (NTSC) FM [0573:4100] + 12 -> PNY USB-TV (NTSC) FM [0573:4110] + 13 -> PixelView PlayTv-USB PRO (PAL) FM [0573:4450] + 14 -> ZTV ZT-721 2.4GHz USB A/V Receiver [0573:4550] + 15 -> Hauppauge WinTV USB (NTSC M/N) [0573:4d00] + 16 -> Hauppauge WinTV USB (PAL B/G) [0573:4d01] + 17 -> Hauppauge WinTV USB (PAL I) [0573:4d02] + 18 -> Hauppauge WinTV USB (PAL/SECAM L) [0573:4d03] + 19 -> Hauppauge WinTV USB (PAL D/K) [0573:4d04] + 20 -> Hauppauge WinTV USB (NTSC FM) [0573:4d10] + 21 -> Hauppauge WinTV USB (PAL B/G FM) [0573:4d11] + 22 -> Hauppauge WinTV USB (PAL I FM) [0573:4d12] + 23 -> Hauppauge WinTV USB (PAL D/K FM) [0573:4d14] + 24 -> Hauppauge WinTV USB Pro (NTSC M/N) [0573:4d2a] + 25 -> Hauppauge WinTV USB Pro (NTSC M/N) V2 [0573:4d2b] + 26 -> Hauppauge WinTV USB Pro (PAL/SECAM B/G/I/D/K/L) [0573:4d2c] + 27 -> Hauppauge WinTV USB Pro (NTSC M/N) V3 [0573:4d20] + 28 -> Hauppauge WinTV USB Pro (PAL B/G) [0573:4d21] + 29 -> Hauppauge WinTV USB Pro (PAL I) [0573:4d22] + 30 -> Hauppauge WinTV USB Pro (PAL/SECAM L) [0573:4d23] + 31 -> Hauppauge WinTV USB Pro (PAL D/K) [0573:4d24] + 32 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) [0573:4d25] + 33 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) V2 [0573:4d26] + 34 -> Hauppauge WinTV USB Pro (PAL B/G) V2 [0573:4d27] + 35 -> Hauppauge WinTV USB Pro (PAL B/G,D/K) [0573:4d28] + 36 -> Hauppauge WinTV USB Pro (PAL I,D/K) [0573:4d29] + 37 -> Hauppauge WinTV USB Pro (NTSC M/N FM) [0573:4d30] + 38 -> Hauppauge WinTV USB Pro (PAL B/G FM) [0573:4d31] + 39 -> Hauppauge WinTV USB Pro (PAL I FM) [0573:4d32] + 40 -> Hauppauge WinTV USB Pro (PAL D/K FM) [0573:4d34] + 41 -> Hauppauge WinTV USB Pro (Temic PAL/SECAM B/G/I/D/K/L FM) [0573:4d35] + 42 -> Hauppauge WinTV USB Pro (Temic PAL B/G FM) [0573:4d36] + 43 -> Hauppauge WinTV USB Pro (PAL/SECAM B/G/I/D/K/L FM) [0573:4d37] + 44 -> Hauppauge WinTV USB Pro (NTSC M/N FM) V2 [0573:4d38] + 45 -> Camtel Technology USB TV Genie Pro FM Model TVB330 [0768:0006] + 46 -> Digital Video Creator I [07d0:0001] + 47 -> Global Village GV-007 (NTSC) [07d0:0002] + 48 -> Dazzle Fusion Model DVC-50 Rev 1 (NTSC) [07d0:0003] + 49 -> Dazzle Fusion Model DVC-80 Rev 1 (PAL) [07d0:0004] + 50 -> Dazzle Fusion Model DVC-90 Rev 1 (SECAM) [07d0:0005] + 51 -> Eskape Labs MyTV2Go [07f8:9104] + 52 -> Pinnacle Studio PCTV USB (PAL) [2304:010d] + 53 -> Pinnacle Studio PCTV USB (SECAM) [2304:0109] + 54 -> Pinnacle Studio PCTV USB (PAL) FM [2304:0110] + 55 -> Miro PCTV USB [2304:0111] + 56 -> Pinnacle Studio PCTV USB (NTSC) FM [2304:0112] + 57 -> Pinnacle Studio PCTV USB (PAL) FM V2 [2304:0210] + 58 -> Pinnacle Studio PCTV USB (NTSC) FM V2 [2304:0212] + 59 -> Pinnacle Studio PCTV USB (PAL) FM V3 [2304:0214] + 60 -> Pinnacle Studio Linx Video input cable (NTSC) [2304:0300] + 61 -> Pinnacle Studio Linx Video input cable (PAL) [2304:0301] + 62 -> Pinnacle PCTV Bungee USB (PAL) FM [2304:0419] + 63 -> Hauppauge WinTv-USB [2400:4200] -- cgit v1.2.3 From f1c9e30b5e4cdd8aae5f0ea87004b1b61ec41881 Mon Sep 17 00:00:00 2001 From: Pete Zaitcev Date: Sat, 24 Feb 2007 19:27:33 -0800 Subject: usbmon: Extended text API This patch adds a new text API, codenamed '1u', which captures more URB fields than old '1t' interface did. Also the '1u' text API is compatible with the future "bus zero" extension. Signed-off-by: Pete Zaitcev Acked-by: Alan Stern Signed-off-by: Greg Kroah-Hartman --- Documentation/usb/usbmon.txt | 80 +++++++++++++++++++++++++++++++------------- 1 file changed, 56 insertions(+), 24 deletions(-) (limited to 'Documentation') diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index 0f6808abd61..53ae866ae37 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -16,7 +16,7 @@ situation as with tcpdump. Unlike the packet socket, usbmon has an interface which provides traces in a text format. This is used for two purposes. First, it serves as a -common trace exchange format for tools while most sophisticated formats +common trace exchange format for tools while more sophisticated formats are finalized. Second, humans can read it in case tools are not available. To collect a raw text trace, execute following steps. @@ -34,7 +34,7 @@ if usbmon is built into the kernel. Verify that bus sockets are present. # ls /sys/kernel/debug/usbmon -1s 1t 2s 2t 3s 3t 4s 4t +1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u # 2. Find which bus connects to the desired device @@ -54,7 +54,7 @@ Bus=03 means it's bus 3. 3. Start 'cat' -# cat /sys/kernel/debug/usbmon/3t > /tmp/1.mon.out +# cat /sys/kernel/debug/usbmon/3u > /tmp/1.mon.out This process will be reading until killed. Naturally, the output can be redirected to a desirable location. This is preferred, because it is going @@ -75,46 +75,80 @@ that the file size is not excessive for your favourite editor. * Raw text data format -The '1t' type data consists of a stream of events, such as URB submission, +Two formats are supported currently: the original, or '1t' format, and +the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u' +format adds a few fields, such as ISO frame descriptors, interval, etc. +It produces slightly longer lines, but otherwise is a perfect superset +of '1t' format. + +If it is desired to recognize one from the other in a program, look at the +"address" word (see below), where '1u' format adds a bus number. If 2 colons +are present, it's the '1t' format, otherwise '1u'. + +Any text format data consists of a stream of events, such as URB submission, URB callback, submission error. Every event is a text line, which consists of whitespace separated words. The number or position of words may depend on the event type, but there is a set of words, common for all types. Here is the list of words, from left to right: + - URB Tag. This is used to identify URBs is normally a kernel mode address of the URB structure in hexadecimal. + - Timestamp in microseconds, a decimal number. The timestamp's resolution depends on available clock, and so it can be much worse than a microsecond (if the implementation uses jiffies, for example). + - Event Type. This type refers to the format of the event, not URB type. Available types are: S - submission, C - callback, E - submission error. -- "Pipe". The pipe concept is deprecated. This is a composite word, used to - be derived from information in pipes. It consists of three fields, separated - by colons: URB type and direction, Device address, Endpoint number. + +- "Address" word (formerly a "pipe"). It consists of four fields, separated by + colons: URB type and direction, Bus number, Device address, Endpoint number. Type and direction are encoded with two bytes in the following manner: Ci Co Control input and output Zi Zo Isochronous input and output Ii Io Interrupt input and output Bi Bo Bulk input and output - Device address and Endpoint number are 3-digit and 2-digit (respectively) - decimal numbers, with leading zeroes. -- URB Status. In most cases, this field contains a number, sometimes negative, - which represents a "status" field of the URB. This field makes no sense for - submissions, but is present anyway to help scripts with parsing. When an - error occurs, the field contains the error code. In case of a submission of - a Control packet, this field contains a Setup Tag instead of an error code. - It is easy to tell whether the Setup Tag is present because it is never a - number. Thus if scripts find a number in this field, they proceed to read - Data Length. If they find something else, like a letter, they read the setup - packet before reading the Data Length. + Bus number, Device address, and Endpoint are decimal numbers, but they may + have leading zeros, for the sake of human readers. + +- URB Status word. This is either a letter, or several numbers separated + by colons: URB status, interval, start frame, and error count. Unlike the + "address" word, all fields save the status are optional. Interval is printed + only for interrupt and isochronous URBs. Start frame is printed only for + isochronous URBs. Error count is printed only for isochronous callback + events. + + The status field is a decimal number, sometimes negative, which represents + a "status" field of the URB. This field makes no sense for submissions, but + is present anyway to help scripts with parsing. When an error occurs, the + field contains the error code. + + In case of a submission of a Control packet, this field contains a Setup Tag + instead of an group of numbers. It is easy to tell whether the Setup Tag is + present because it is never a number. Thus if scripts find a set of numbers + in this word, they proceed to read Data Length (except for isochronous URBs). + If they find something else, like a letter, they read the setup packet before + reading the Data Length or isochronous descriptors. + - Setup packet, if present, consists of 5 words: one of each for bmRequestType, bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0. These words are safe to decode if Setup Tag was 's'. Otherwise, the setup packet was present, but not captured, and the fields contain filler. + +- Number of isochronous frame descriptors and descriptors themselves. + If an Isochronous transfer event has a set of descriptors, a total number + of them in an URB is printed first, then a word per descriptor, up to a + total of 5. The word consists of 3 colon-separated decimal numbers for + status, offset, and length respectively. For submissions, initial length + is reported. For callbacks, actual length is reported. + - Data Length. For submissions, this is the requested length. For callbacks, this is the actual length. + - Data tag. The usbmon may not always capture data, even if length is nonzero. The data words are present only if this tag is '='. + - Data words follow, in big endian hexadecimal format. Notice that they are not machine words, but really just a byte stream split into words to make it easier to read. Thus, the last word may contain from one to four bytes. @@ -153,20 +187,18 @@ class ParsedLine { } } -This format may be changed in the future. - Examples: An input control transfer to get a port status. -d5ea89a0 3575914555 S Ci:001:00 s a3 00 0000 0003 0004 4 < -d5ea89a0 3575914560 C Ci:001:00 0 4 = 01050000 +d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 < +d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000 An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper to a storage device at address 5: -dd65f0e8 4128379752 S Bo:005:02 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000 -dd65f0e8 4128379808 C Bo:005:02 0 31 > +dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000 +dd65f0e8 4128379808 C Bo:1:005:2 0 31 > * Raw binary format and API -- cgit v1.2.3 From eaafbc3a8adab16babe2c20e54ad3ba40d1fbbc9 Mon Sep 17 00:00:00 2001 From: Alan Stern Date: Tue, 13 Mar 2007 16:39:15 -0400 Subject: USB: Allow autosuspend delay to equal 0 This patch (as867) adds an entry for the new power/autosuspend attribute in Documentation/ABI/testing, and it changes the behavior of the delay value. Now a delay of 0 means to autosuspend as soon as possible, and negative values will prevent autosuspend. Signed-off-by: Alan Stern Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/testing/sysfs-bus-usb | 15 +++++++++++++++ Documentation/kernel-parameters.txt | 2 +- 2 files changed, 16 insertions(+), 1 deletion(-) create mode 100644 Documentation/ABI/testing/sysfs-bus-usb (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb new file mode 100644 index 00000000000..00a84326325 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -0,0 +1,15 @@ +What: /sys/bus/usb/devices/.../power/autosuspend +Date: March 2007 +KernelVersion: 2.6.21 +Contact: Alan Stern +Description: + Each USB device directory will contain a file named + power/autosuspend. This file holds the time (in seconds) + the device must be idle before it will be autosuspended. + 0 means the device will be autosuspended as soon as + possible. Negative values will prevent the device from + being autosuspended at all, and writing a negative value + will resume the device if it is already suspended. + + The autosuspend delay for newly-created devices is set to + the value of the usbcore.autosuspend module parameter. diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 12533a958c5..2017942e096 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -1792,7 +1792,7 @@ and is between 256 and 4096 characters. It is defined in the file for newly-detected USB devices (default 2). This is the time required before an idle device will be autosuspended. Devices for which the delay is set - to 0 won't be autosuspended at all. + to a negative value won't be autosuspended at all. usbhid.mousepoll= [USBHID] The interval which mice are to be polled at. -- cgit v1.2.3 From 2add5229d77a3de08015feef437653e02372162f Mon Sep 17 00:00:00 2001 From: Alan Stern Date: Tue, 20 Mar 2007 14:59:39 -0400 Subject: USB: add power/level sysfs attribute This patch (as874) adds another piece to the user-visible part of the USB autosuspend interface. The new power/level sysfs attribute allows users to force the device on (with autosuspend off), force the device to sleep (with autoresume off), or return to normal automatic operation. Signed-off-by: Alan Stern Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/testing/sysfs-bus-usb | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 00a84326325..f9937add033 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -13,3 +13,29 @@ Description: The autosuspend delay for newly-created devices is set to the value of the usbcore.autosuspend module parameter. + +What: /sys/bus/usb/devices/.../power/level +Date: March 2007 +KernelVersion: 2.6.21 +Contact: Alan Stern +Description: + Each USB device directory will contain a file named + power/level. This file holds a power-level setting for + the device, one of "on", "auto", or "suspend". + + "on" means that the device is not allowed to autosuspend, + although normal suspends for system sleep will still + be honored. "auto" means the device will autosuspend + and autoresume in the usual manner, according to the + capabilities of its driver. "suspend" means the device + is forced into a suspended state and it will not autoresume + in response to I/O requests. However remote-wakeup requests + from the device may still be enabled (the remote-wakeup + setting is controlled separately by the power/wakeup + attribute). + + During normal use, devices should be left in the "auto" + level. The other levels are meant for administrative uses. + If you want to suspend a device immediately but leave it + free to wake up in response to I/O requests, you should + write "0" to power/autosuspend. -- cgit v1.2.3