From d6e711448137ca3301512cec41a2c2ce852b3d0a Mon Sep 17 00:00:00 2001 From: Alan Cox Date: Thu, 23 Jun 2005 00:09:43 -0700 Subject: [PATCH] setuid core dump Add a new `suid_dumpable' sysctl: This value can be used to query and set the core dump mode for setuid or otherwise protected/tainted binaries. The modes are 0 - (default) - traditional behaviour. Any process which has changed privilege levels or is execute only will not be dumped 1 - (debug) - all processes dump core when possible. The core dump is owned by the current user and no security is applied. This is intended for system debugging situations only. Ptrace is unchecked. 2 - (suidsafe) - any binary which normally would not be dumped is dumped readable by root only. This allows the end user to remove such a dump but not access it directly. For security reasons core dumps in this mode will not overwrite one another or other files. This mode is appropriate when adminstrators are attempting to debug problems in a normal environment. (akpm: > > +EXPORT_SYMBOL(suid_dumpable); > > EXPORT_SYMBOL_GPL? No problem to me. > > if (current->euid == current->uid && current->egid == current->gid) > > current->mm->dumpable = 1; > > Should this be SUID_DUMP_USER? Actually the feedback I had from last time was that the SUID_ defines should go because its clearer to follow the numbers. They can go everywhere (and there are lots of places where dumpable is tested/used as a bool in untouched code) > Maybe this should be renamed to `dump_policy' or something. Doing that > would help us catch any code which isn't using the #defines, too. Fair comment. The patch was designed to be easy to maintain for Red Hat rather than for merging. Changing that field would create a gigantic diff because it is used all over the place. ) Signed-off-by: Alan Cox Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/sysctl/kernel.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'Documentation') diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 35159176997b..9f11d36a8c10 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -49,6 +49,7 @@ show up in /proc/sys/kernel: - shmmax [ sysv ipc ] - shmmni - stop-a [ SPARC only ] +- suid_dumpable - sysrq ==> Documentation/sysrq.txt - tainted - threads-max @@ -300,6 +301,25 @@ kernel. This value defaults to SHMMAX. ============================================================== +suid_dumpable: + +This value can be used to query and set the core dump mode for setuid +or otherwise protected/tainted binaries. The modes are + +0 - (default) - traditional behaviour. Any process which has changed + privilege levels or is execute only will not be dumped +1 - (debug) - all processes dump core when possible. The core dump is + owned by the current user and no security is applied. This is + intended for system debugging situations only. Ptrace is unchecked. +2 - (suidsafe) - any binary which normally would not be dumped is dumped + readable by root only. This allows the end user to remove + such a dump but not access it directly. For security reasons + core dumps in this mode will not overwrite one another or + other files. This mode is appropriate when adminstrators are + attempting to debug problems in a normal environment. + +============================================================== + tainted: Non-zero if the kernel has been tainted. Numeric values, which -- cgit v1.2.2 From 7007cab53176dc906e67b4efa62f20ff1432805a Mon Sep 17 00:00:00 2001 From: Michal Schmidt Date: Thu, 23 Jun 2005 00:10:09 -0700 Subject: [PATCH] Add offset.h to dontdiff include/asm/offset.h is a generated file on x86_64 and mips. Let's add it to Documentation/dontdiff. Signed-off-by: Michal Schmidt Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/dontdiff | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 9a33bb94f74f..d4fda25db868 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -111,6 +111,7 @@ mkdep mktables modpost modversions.h* +offset.h offsets.h oui.c* parse.c* -- cgit v1.2.2 From 451512f3aed64573e912e68c94f240fec0e44438 Mon Sep 17 00:00:00 2001 From: Jesper Juhl Date: Thu, 23 Jun 2005 00:10:28 -0700 Subject: [PATCH] add note about verify_area removal to feature-removal-schedule.txt Add note about the soon-to-come removal of verify_area() to Documentation/feature-removal-schedule.txt. Signed-off-by: Jesper Juhl Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/feature-removal-schedule.txt | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'Documentation') diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 26414bc87c65..e67c90d4ee17 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -66,6 +66,14 @@ Who: Paul E. McKenney --------------------------- +What: remove verify_area() +When: July 2006 +Files: Various uaccess.h headers. +Why: Deprecated and redundant. access_ok() should be used instead. +Who: Jesper Juhl + +--------------------------- + What: IEEE1394 Audio and Music Data Transmission Protocol driver, Connection Management Procedures driver When: November 2005 -- cgit v1.2.2 From bfb07599da289881d3bcbb601a110e997fc7444b Mon Sep 17 00:00:00 2001 From: Alexey Dobriyan Date: Thu, 23 Jun 2005 00:10:32 -0700 Subject: [PATCH] Introduce tty_unregister_ldisc() It's a bit strange to see tty_register_ldisc call in modules' exit functions. Signed-off-by: Alexey Dobriyan Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/tty.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/tty.txt b/Documentation/tty.txt index 3958cf746dde..8ff7bc2a0811 100644 --- a/Documentation/tty.txt +++ b/Documentation/tty.txt @@ -22,7 +22,7 @@ copy of the structure. You must not re-register over the top of the line discipline even with the same data or your computer again will be eaten by demons. -In order to remove a line discipline call tty_register_ldisc passing NULL. +In order to remove a line discipline call tty_unregister_ldisc(). In ancient times this always worked. In modern times the function will return -EBUSY if the ldisc is currently in use. Since the ldisc referencing code manages the module counts this should not usually be a concern. -- cgit v1.2.2 From a8ad86f2dc46356f87be1327dabc18bdbda32f50 Mon Sep 17 00:00:00 2001 From: Russell King Date: Thu, 23 Jun 2005 14:23:35 +0100 Subject: [PATCH] Add removal schedule of register_serial/unregister_serial to appropriate file --- Documentation/feature-removal-schedule.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'Documentation') diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index e67c90d4ee17..77511af45362 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -94,6 +94,16 @@ Who: Jody McIntyre --------------------------- +What: register_serial/unregister_serial +When: December 2005 +Why: This interface does not allow serial ports to be registered against + a struct device, and as such does not allow correct power management + of such ports. 8250-based ports should use serial8250_register_port + and serial8250_unregister_port instead. +Who: Russell King + +--------------------------- + What: i2c sysfs name change: in1_ref, vid deprecated in favour of cpu0_vid When: November 2005 Files: drivers/i2c/chips/adm1025.c, drivers/i2c/chips/adm1026.c -- cgit v1.2.2 From 9d7bcfc6b8586ee5a52043f061e0411965e71b88 Mon Sep 17 00:00:00 2001 From: Stephen Hemminger Date: Thu, 23 Jun 2005 12:22:36 -0700 Subject: [TCP]: Update sysctl and congestion control documentation. Update the documentation to remove the old sysctl values and include the new congestion control infrastructure. Includes changes to tcp.txt by Ian McDonald. Signed-off-by: Stephen Hemminger Signed-off-by: David S. Miller --- Documentation/networking/ip-sysctl.txt | 56 +++------------------------ Documentation/networking/tcp.txt | 69 +++++++++++++++++++++++++++++++++- 2 files changed, 73 insertions(+), 52 deletions(-) (limited to 'Documentation') diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index a2c893a7475d..ab65714d95fc 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -304,57 +304,6 @@ tcp_low_latency - BOOLEAN changed would be a Beowulf compute cluster. Default: 0 -tcp_westwood - BOOLEAN - Enable TCP Westwood+ congestion control algorithm. - TCP Westwood+ is a sender-side only modification of the TCP Reno - protocol stack that optimizes the performance of TCP congestion - control. It is based on end-to-end bandwidth estimation to set - congestion window and slow start threshold after a congestion - episode. Using this estimation, TCP Westwood+ adaptively sets a - slow start threshold and a congestion window which takes into - account the bandwidth used at the time congestion is experienced. - TCP Westwood+ significantly increases fairness wrt TCP Reno in - wired networks and throughput over wireless links. - Default: 0 - -tcp_vegas_cong_avoid - BOOLEAN - Enable TCP Vegas congestion avoidance algorithm. - TCP Vegas is a sender-side only change to TCP that anticipates - the onset of congestion by estimating the bandwidth. TCP Vegas - adjusts the sending rate by modifying the congestion - window. TCP Vegas should provide less packet loss, but it is - not as aggressive as TCP Reno. - Default:0 - -tcp_bic - BOOLEAN - Enable BIC TCP congestion control algorithm. - BIC-TCP is a sender-side only change that ensures a linear RTT - fairness under large windows while offering both scalability and - bounded TCP-friendliness. The protocol combines two schemes - called additive increase and binary search increase. When the - congestion window is large, additive increase with a large - increment ensures linear RTT fairness as well as good - scalability. Under small congestion windows, binary search - increase provides TCP friendliness. - Default: 0 - -tcp_bic_low_window - INTEGER - Sets the threshold window (in packets) where BIC TCP starts to - adjust the congestion window. Below this threshold BIC TCP behaves - the same as the default TCP Reno. - Default: 14 - -tcp_bic_fast_convergence - BOOLEAN - Forces BIC TCP to more quickly respond to changes in congestion - window. Allows two flows sharing the same connection to converge - more rapidly. - Default: 1 - -tcp_default_win_scale - INTEGER - Sets the minimum window scale TCP will negotiate for on all - conections. - Default: 7 - tcp_tso_win_divisor - INTEGER This allows control over what percentage of the congestion window can be consumed by a single TSO frame. @@ -368,6 +317,11 @@ tcp_frto - BOOLEAN where packet loss is typically due to random radio interference rather than intermediate router congestion. +tcp_congestion_control - STRING + Set the congestion control algorithm to be used for new + connections. The algorithm "reno" is always available, but + additional choices may be available based on kernel configuration. + somaxconn - INTEGER Limit of socket listen() backlog, known in userspace as SOMAXCONN. Defaults to 128. See also tcp_max_syn_backlog for additional tuning diff --git a/Documentation/networking/tcp.txt b/Documentation/networking/tcp.txt index 71749007091e..0fa300425575 100644 --- a/Documentation/networking/tcp.txt +++ b/Documentation/networking/tcp.txt @@ -1,5 +1,72 @@ -How the new TCP output machine [nyi] works. +TCP protocol +============ + +Last updated: 21 June 2005 + +Contents +======== + +- Congestion control +- How the new TCP output machine [nyi] works + +Congestion control +================== + +The following variables are used in the tcp_sock for congestion control: +snd_cwnd The size of the congestion window +snd_ssthresh Slow start threshold. We are in slow start if + snd_cwnd is less than this. +snd_cwnd_cnt A counter used to slow down the rate of increase + once we exceed slow start threshold. +snd_cwnd_clamp This is the maximum size that snd_cwnd can grow to. +snd_cwnd_stamp Timestamp for when congestion window last validated. +snd_cwnd_used Used as a highwater mark for how much of the + congestion window is in use. It is used to adjust + snd_cwnd down when the link is limited by the + application rather than the network. + +As of 2.6.13, Linux supports pluggable congestion control algorithms. +A congestion control mechanism can be registered through functions in +tcp_cong.c. The functions used by the congestion control mechanism are +registered via passing a tcp_congestion_ops struct to +tcp_register_congestion_control. As a minimum name, ssthresh, +cong_avoid, min_cwnd must be valid. +Private data for a congestion control mechanism is stored in tp->ca_priv. +tcp_ca(tp) returns a pointer to this space. This is preallocated space - it +is important to check the size of your private data will fit this space, or +alternatively space could be allocated elsewhere and a pointer to it could +be stored here. + +There are three kinds of congestion control algorithms currently: The +simplest ones are derived from TCP reno (highspeed, scalable) and just +provide an alternative the congestion window calculation. More complex +ones like BIC try to look at other events to provide better +heuristics. There are also round trip time based algorithms like +Vegas and Westwood+. + +Good TCP congestion control is a complex problem because the algorithm +needs to maintain fairness and performance. Please review current +research and RFC's before developing new modules. + +The method that is used to determine which congestion control mechanism is +determined by the setting of the sysctl net.ipv4.tcp_congestion_control. +The default congestion control will be the last one registered (LIFO); +so if you built everything as modules. the default will be reno. If you +build with the default's from Kconfig, then BIC will be builtin (not a module) +and it will end up the default. + +If you really want a particular default value then you will need +to set it with the sysctl. If you use a sysctl, the module will be autoloaded +if needed and you will get the expected protocol. If you ask for an +unknown congestion method, then the sysctl attempt will fail. + +If you remove a tcp congestion control module, then you will get the next +available one. Since reno can not be built as a module, and can not be +deleted, it will always be available. + +How the new TCP output machine [nyi] works. +=========================================== Data is kept on a single queue. The skb->users flag tells us if the frame is one that has been queued already. To add a frame we throw it on the end. Ack -- cgit v1.2.2 From 76d8aeabfeb1c42641a81c44280177b9a08670d8 Mon Sep 17 00:00:00 2001 From: David Howells Date: Thu, 23 Jun 2005 22:00:49 -0700 Subject: [PATCH] keys: Discard key spinlock and use RCU for key payload The attached patch changes the key implementation in a number of ways: (1) It removes the spinlock from the key structure. (2) The key flags are now accessed using atomic bitops instead of write-locking the key spinlock and using C bitwise operators. The three instantiation flags are dealt with with the construction semaphore held during the request_key/instantiate/negate sequence, thus rendering the spinlock superfluous. The key flags are also now bit numbers not bit masks. (3) The key payload is now accessed using RCU. This permits the recursive keyring search algorithm to be simplified greatly since no locks need be taken other than the usual RCU preemption disablement. Searching now does not require any locks or semaphores to be held; merely that the starting keyring be pinned. (4) The keyring payload now includes an RCU head so that it can be disposed of by call_rcu(). This requires that the payload be copied on unlink to prevent introducing races in copy-down vs search-up. (5) The user key payload is now a structure with the data following it. It includes an RCU head like the keyring payload and for the same reason. It also contains a data length because the data length in the key may be changed on another CPU whilst an RCU protected read is in progress on the payload. This would then see the supposed RCU payload and the on-key data length getting out of sync. I'm tempted to drop the key's datalen entirely, except that it's used in conjunction with quota management and so is a little tricky to get rid of. (6) Update the keys documentation. Signed-Off-By: David Howells Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/keys.txt | 285 +++++++++++++++++++++++++++++-------------------- 1 file changed, 172 insertions(+), 113 deletions(-) (limited to 'Documentation') diff --git a/Documentation/keys.txt b/Documentation/keys.txt index 36d80aeeaf28..3df40c1fe15a 100644 --- a/Documentation/keys.txt +++ b/Documentation/keys.txt @@ -22,6 +22,7 @@ This document has the following sections: - New procfs files - Userspace system call interface - Kernel services + - Notes on accessing payload contents - Defining a key type - Request-key callback service - Key access filesystem @@ -45,27 +46,26 @@ Each key has a number of attributes: - State. - (*) Each key is issued a serial number of type key_serial_t that is unique - for the lifetime of that key. All serial numbers are positive non-zero - 32-bit integers. + (*) Each key is issued a serial number of type key_serial_t that is unique for + the lifetime of that key. All serial numbers are positive non-zero 32-bit + integers. Userspace programs can use a key's serial numbers as a way to gain access to it, subject to permission checking. (*) Each key is of a defined "type". Types must be registered inside the - kernel by a kernel service (such as a filesystem) before keys of that - type can be added or used. Userspace programs cannot define new types - directly. + kernel by a kernel service (such as a filesystem) before keys of that type + can be added or used. Userspace programs cannot define new types directly. - Key types are represented in the kernel by struct key_type. This defines - a number of operations that can be performed on a key of that type. + Key types are represented in the kernel by struct key_type. This defines a + number of operations that can be performed on a key of that type. Should a type be removed from the system, all the keys of that type will be invalidated. (*) Each key has a description. This should be a printable string. The key - type provides an operation to perform a match between the description on - a key and a criterion string. + type provides an operation to perform a match between the description on a + key and a criterion string. (*) Each key has an owner user ID, a group ID and a permissions mask. These are used to control what a process may do to a key from userspace, and @@ -74,10 +74,10 @@ Each key has a number of attributes: (*) Each key can be set to expire at a specific time by the key type's instantiation function. Keys can also be immortal. - (*) Each key can have a payload. This is a quantity of data that represent - the actual "key". In the case of a keyring, this is a list of keys to - which the keyring links; in the case of a user-defined key, it's an - arbitrary blob of data. + (*) Each key can have a payload. This is a quantity of data that represent the + actual "key". In the case of a keyring, this is a list of keys to which + the keyring links; in the case of a user-defined key, it's an arbitrary + blob of data. Having a payload is not required; and the payload can, in fact, just be a value stored in the struct key itself. @@ -92,8 +92,8 @@ Each key has a number of attributes: (*) Each key can be in one of a number of basic states: - (*) Uninstantiated. The key exists, but does not have any data - attached. Keys being requested from userspace will be in this state. + (*) Uninstantiated. The key exists, but does not have any data attached. + Keys being requested from userspace will be in this state. (*) Instantiated. This is the normal state. The key is fully formed, and has data attached. @@ -140,10 +140,10 @@ The key service provides a number of features besides keys: clone, fork, vfork or execve occurs. A new keyring is created only when required. - The process-specific keyring is replaced with an empty one in the child - on clone, fork, vfork unless CLONE_THREAD is supplied, in which case it - is shared. execve also discards the process's process keyring and creates - a new one. + The process-specific keyring is replaced with an empty one in the child on + clone, fork, vfork unless CLONE_THREAD is supplied, in which case it is + shared. execve also discards the process's process keyring and creates a + new one. The session-specific keyring is persistent across clone, fork, vfork and execve, even when the latter executes a set-UID or set-GID binary. A @@ -177,11 +177,11 @@ The key service provides a number of features besides keys: If a system call that modifies a key or keyring in some way would put the user over quota, the operation is refused and error EDQUOT is returned. - (*) There's a system call interface by which userspace programs can create - and manipulate keys and keyrings. + (*) There's a system call interface by which userspace programs can create and + manipulate keys and keyrings. - (*) There's a kernel interface by which services can register types and - search for keys. + (*) There's a kernel interface by which services can register types and search + for keys. (*) There's a way for the a search done from the kernel to call back to userspace to request a key that can't be found in a process's keyrings. @@ -194,9 +194,9 @@ The key service provides a number of features besides keys: KEY ACCESS PERMISSIONS ====================== -Keys have an owner user ID, a group access ID, and a permissions mask. The -mask has up to eight bits each for user, group and other access. Only five of -each set of eight bits are defined. These permissions granted are: +Keys have an owner user ID, a group access ID, and a permissions mask. The mask +has up to eight bits each for user, group and other access. Only five of each +set of eight bits are defined. These permissions granted are: (*) View @@ -210,8 +210,8 @@ each set of eight bits are defined. These permissions granted are: (*) Write - This permits a key's payload to be instantiated or updated, or it allows - a link to be added to or removed from a keyring. + This permits a key's payload to be instantiated or updated, or it allows a + link to be added to or removed from a keyring. (*) Search @@ -238,8 +238,8 @@ about the status of the key service: (*) /proc/keys This lists all the keys on the system, giving information about their - type, description and permissions. The payload of the key is not - available this way: + type, description and permissions. The payload of the key is not available + this way: SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY 00000001 I----- 39 perm 1f0000 0 0 keyring _uid_ses.0: 1/4 @@ -318,21 +318,21 @@ The main syscalls are: If a key of the same type and description as that proposed already exists in the keyring, this will try to update it with the given payload, or it will return error EEXIST if that function is not supported by the key - type. The process must also have permission to write to the key to be - able to update it. The new key will have all user permissions granted and - no group or third party permissions. + type. The process must also have permission to write to the key to be able + to update it. The new key will have all user permissions granted and no + group or third party permissions. - Otherwise, this will attempt to create a new key of the specified type - and description, and to instantiate it with the supplied payload and - attach it to the keyring. In this case, an error will be generated if the - process does not have permission to write to the keyring. + Otherwise, this will attempt to create a new key of the specified type and + description, and to instantiate it with the supplied payload and attach it + to the keyring. In this case, an error will be generated if the process + does not have permission to write to the keyring. The payload is optional, and the pointer can be NULL if not required by the type. The payload is plen in size, and plen can be zero for an empty payload. - A new keyring can be generated by setting type "keyring", the keyring - name as the description (or NULL) and setting the payload to NULL. + A new keyring can be generated by setting type "keyring", the keyring name + as the description (or NULL) and setting the payload to NULL. User defined keys can be created by specifying type "user". It is recommended that a user defined key's description by prefixed with a type @@ -369,9 +369,9 @@ The keyctl syscall functions are: key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id, int create); - The special key specified by "id" is looked up (with the key being - created if necessary) and the ID of the key or keyring thus found is - returned if it exists. + The special key specified by "id" is looked up (with the key being created + if necessary) and the ID of the key or keyring thus found is returned if + it exists. If the key does not yet exist, the key will be created if "create" is non-zero; and the error ENOKEY will be returned if "create" is zero. @@ -402,8 +402,8 @@ The keyctl syscall functions are: This will try to update the specified key with the given payload, or it will return error EOPNOTSUPP if that function is not supported by the key - type. The process must also have permission to write to the key to be - able to update it. + type. The process must also have permission to write to the key to be able + to update it. The payload is of length plen, and may be absent or empty as for add_key(). @@ -422,8 +422,8 @@ The keyctl syscall functions are: long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid); - This function permits a key's owner and group ID to be changed. Either - one of uid or gid can be set to -1 to suppress that change. + This function permits a key's owner and group ID to be changed. Either one + of uid or gid can be set to -1 to suppress that change. Only the superuser can change a key's owner to something other than the key's current owner. Similarly, only the superuser can change a key's @@ -484,12 +484,12 @@ The keyctl syscall functions are: long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key); - This function creates a link from the keyring to the key. The process - must have write permission on the keyring and must have link permission - on the key. + This function creates a link from the keyring to the key. The process must + have write permission on the keyring and must have link permission on the + key. - Should the keyring not be a keyring, error ENOTDIR will result; and if - the keyring is full, error ENFILE will result. + Should the keyring not be a keyring, error ENOTDIR will result; and if the + keyring is full, error ENFILE will result. The link procedure checks the nesting of the keyrings, returning ELOOP if it appears to deep or EDEADLK if the link would introduce a cycle. @@ -503,8 +503,8 @@ The keyctl syscall functions are: specified key, and removes it if found. Subsequent links to that key are ignored. The process must have write permission on the keyring. - If the keyring is not a keyring, error ENOTDIR will result; and if the - key is not present, error ENOENT will be the result. + If the keyring is not a keyring, error ENOTDIR will result; and if the key + is not present, error ENOENT will be the result. (*) Search a keyring tree for a key: @@ -513,9 +513,9 @@ The keyctl syscall functions are: const char *type, const char *description, key_serial_t dest_keyring); - This searches the keyring tree headed by the specified keyring until a - key is found that matches the type and description criteria. Each keyring - is checked for keys before recursion into its children occurs. + This searches the keyring tree headed by the specified keyring until a key + is found that matches the type and description criteria. Each keyring is + checked for keys before recursion into its children occurs. The process must have search permission on the top level keyring, or else error EACCES will result. Only keyrings that the process has search @@ -549,8 +549,8 @@ The keyctl syscall functions are: As much of the data as can be fitted into the buffer will be copied to userspace if the buffer pointer is not NULL. - On a successful return, the function will always return the amount of - data available rather than the amount copied. + On a successful return, the function will always return the amount of data + available rather than the amount copied. (*) Instantiate a partially constructed key. @@ -568,8 +568,8 @@ The keyctl syscall functions are: it, and the key must be uninstantiated. If a keyring is specified (non-zero), the key will also be linked into - that keyring, however all the constraints applying in KEYCTL_LINK apply - in this case too. + that keyring, however all the constraints applying in KEYCTL_LINK apply in + this case too. The payload and plen arguments describe the payload data as for add_key(). @@ -587,8 +587,8 @@ The keyctl syscall functions are: it, and the key must be uninstantiated. If a keyring is specified (non-zero), the key will also be linked into - that keyring, however all the constraints applying in KEYCTL_LINK apply - in this case too. + that keyring, however all the constraints applying in KEYCTL_LINK apply in + this case too. =============== @@ -601,17 +601,14 @@ be broken down into two areas: keys and key types. Dealing with keys is fairly straightforward. Firstly, the kernel service registers its type, then it searches for a key of that type. It should retain the key as long as it has need of it, and then it should release it. For a -filesystem or device file, a search would probably be performed during the -open call, and the key released upon close. How to deal with conflicting keys -due to two different users opening the same file is left to the filesystem -author to solve. - -When accessing a key's payload data, key->lock should be at least read locked, -or else the data may be changed by an update being performed from userspace -whilst the driver or filesystem is trying to access it. If no update method is -supplied, then the key's payload may be accessed without holding a lock as -there is no way to change it, provided it can be guaranteed that the key's -type definition won't go away. +filesystem or device file, a search would probably be performed during the open +call, and the key released upon close. How to deal with conflicting keys due to +two different users opening the same file is left to the filesystem author to +solve. + +When accessing a key's payload contents, certain precautions must be taken to +prevent access vs modification races. See the section "Notes on accessing +payload contents" for more information. (*) To search for a key, call: @@ -690,6 +687,54 @@ type definition won't go away. void unregister_key_type(struct key_type *type); +=================================== +NOTES ON ACCESSING PAYLOAD CONTENTS +=================================== + +The simplest payload is just a number in key->payload.value. In this case, +there's no need to indulge in RCU or locking when accessing the payload. + +More complex payload contents must be allocated and a pointer to them set in +key->payload.data. One of the following ways must be selected to access the +data: + + (1) Unmodifyable key type. + + If the key type does not have a modify method, then the key's payload can + be accessed without any form of locking, provided that it's known to be + instantiated (uninstantiated keys cannot be "found"). + + (2) The key's semaphore. + + The semaphore could be used to govern access to the payload and to control + the payload pointer. It must be write-locked for modifications and would + have to be read-locked for general access. The disadvantage of doing this + is that the accessor may be required to sleep. + + (3) RCU. + + RCU must be used when the semaphore isn't already held; if the semaphore + is held then the contents can't change under you unexpectedly as the + semaphore must still be used to serialise modifications to the key. The + key management code takes care of this for the key type. + + However, this means using: + + rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock() + + to read the pointer, and: + + rcu_dereference() ... rcu_assign_pointer() ... call_rcu() + + to set the pointer and dispose of the old contents after a grace period. + Note that only the key type should ever modify a key's payload. + + Furthermore, an RCU controlled payload must hold a struct rcu_head for the + use of call_rcu() and, if the payload is of variable size, the length of + the payload. key->datalen cannot be relied upon to be consistent with the + payload just dereferenced if the key's semaphore is not held. + + =================== DEFINING A KEY TYPE =================== @@ -717,15 +762,15 @@ The structure has a number of fields, some of which are mandatory: int key_payload_reserve(struct key *key, size_t datalen); - With the revised data length. Error EDQUOT will be returned if this is - not viable. + With the revised data length. Error EDQUOT will be returned if this is not + viable. (*) int (*instantiate)(struct key *key, const void *data, size_t datalen); This method is called to attach a payload to a key during construction. - The payload attached need not bear any relation to the data passed to - this function. + The payload attached need not bear any relation to the data passed to this + function. If the amount of data attached to the key differs from the size in keytype->def_datalen, then key_payload_reserve() should be called. @@ -734,38 +779,47 @@ The structure has a number of fields, some of which are mandatory: The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents anything else from gaining access to the key. - This method may sleep if it wishes. + It is safe to sleep in this method. (*) int (*duplicate)(struct key *key, const struct key *source); If this type of key can be duplicated, then this method should be - provided. It is called to copy the payload attached to the source into - the new key. The data length on the new key will have been updated and - the quota adjusted already. + provided. It is called to copy the payload attached to the source into the + new key. The data length on the new key will have been updated and the + quota adjusted already. This method will be called with the source key's semaphore read-locked to - prevent its payload from being changed. It is safe to sleep here. + prevent its payload from being changed, thus RCU constraints need not be + applied to the source key. + + This method does not have to lock the destination key in order to attach a + payload. The fact that KEY_FLAG_INSTANTIATED is not set in key->flags + prevents anything else from gaining access to the key. + + It is safe to sleep in this method. (*) int (*update)(struct key *key, const void *data, size_t datalen); - If this type of key can be updated, then this method should be - provided. It is called to update a key's payload from the blob of data - provided. + If this type of key can be updated, then this method should be provided. + It is called to update a key's payload from the blob of data provided. key_payload_reserve() should be called if the data length might change - before any changes are actually made. Note that if this succeeds, the - type is committed to changing the key because it's already been altered, - so all memory allocation must be done first. + before any changes are actually made. Note that if this succeeds, the type + is committed to changing the key because it's already been altered, so all + memory allocation must be done first. + + The key will have its semaphore write-locked before this method is called, + but this only deters other writers; any changes to the key's payload must + be made under RCU conditions, and call_rcu() must be used to dispose of + the old payload. - key_payload_reserve() should be called with the key->lock write locked, - and the changes to the key's attached payload should be made before the - key is locked. + key_payload_reserve() should be called before the changes are made, but + after all allocations and other potentially failing function calls are + made. - The key will have its semaphore write-locked before this method is - called. Any changes to the key should be made with the key's rwlock - write-locked also. It is safe to sleep here. + It is safe to sleep in this method. (*) int (*match)(const struct key *key, const void *desc); @@ -782,12 +836,12 @@ The structure has a number of fields, some of which are mandatory: (*) void (*destroy)(struct key *key); - This method is optional. It is called to discard the payload data on a - key when it is being destroyed. + This method is optional. It is called to discard the payload data on a key + when it is being destroyed. - This method does not need to lock the key; it can consider the key as - being inaccessible. Note that the key's type may have changed before this - function is called. + This method does not need to lock the key to access the payload; it can + consider the key as being inaccessible at this time. Note that the key's + type may have been changed before this function is called. It is not safe to sleep in this method; the caller may hold spinlocks. @@ -797,26 +851,31 @@ The structure has a number of fields, some of which are mandatory: This method is optional. It is called during /proc/keys reading to summarise a key's description and payload in text form. - This method will be called with the key's rwlock read-locked. This will - prevent the key's payload and state changing; also the description should - not change. This also means it is not safe to sleep in this method. + This method will be called with the RCU read lock held. rcu_dereference() + should be used to read the payload pointer if the payload is to be + accessed. key->datalen cannot be trusted to stay consistent with the + contents of the payload. + + The description will not change, though the key's state may. + + It is not safe to sleep in this method; the RCU read lock is held by the + caller. (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen); This method is optional. It is called by KEYCTL_READ to translate the - key's payload into something a blob of data for userspace to deal - with. Ideally, the blob should be in the same format as that passed in to - the instantiate and update methods. + key's payload into something a blob of data for userspace to deal with. + Ideally, the blob should be in the same format as that passed in to the + instantiate and update methods. If successful, the blob size that could be produced should be returned rather than the size copied. - This method will be called with the key's semaphore read-locked. This - will prevent the key's payload changing. It is not necessary to also - read-lock key->lock when accessing the key's payload. It is safe to sleep - in this method, such as might happen when the userspace buffer is - accessed. + This method will be called with the key's semaphore read-locked. This will + prevent the key's payload changing. It is not necessary to use RCU locking + when accessing the key's payload. It is safe to sleep in this method, such + as might happen when the userspace buffer is accessed. ============================ @@ -853,8 +912,8 @@ If it returns with the key remaining in the unconstructed state, the key will be marked as being negative, it will be added to the session keyring, and an error will be returned to the key requestor. -Supplementary information may be provided from whoever or whatever invoked -this service. This will be passed as the parameter. If no such +Supplementary information may be provided from whoever or whatever invoked this +service. This will be passed as the parameter. If no such information was made available, then "-" will be passed as this parameter instead. -- cgit v1.2.2 From 3e30148c3d524a9c1c63ca28261bc24c457eb07a Mon Sep 17 00:00:00 2001 From: David Howells Date: Thu, 23 Jun 2005 22:00:56 -0700 Subject: [PATCH] Keys: Make request-key create an authorisation key The attached patch makes the following changes: (1) There's a new special key type called ".request_key_auth". This is an authorisation key for when one process requests a key and another process is started to construct it. This type of key cannot be created by the user; nor can it be requested by kernel services. Authorisation keys hold two references: (a) Each refers to a key being constructed. When the key being constructed is instantiated the authorisation key is revoked, rendering it of no further use. (b) The "authorising process". This is either: (i) the process that called request_key(), or: (ii) if the process that called request_key() itself had an authorisation key in its session keyring, then the authorising process referred to by that authorisation key will also be referred to by the new authorisation key. This means that the process that initiated a chain of key requests will authorise the lot of them, and will, by default, wind up with the keys obtained from them in its keyrings. (2) request_key() creates an authorisation key which is then passed to /sbin/request-key in as part of a new session keyring. (3) When request_key() is searching for a key to hand back to the caller, if it comes across an authorisation key in the session keyring of the calling process, it will also search the keyrings of the process specified therein and it will use the specified process's credentials (fsuid, fsgid, groups) to do that rather than the calling process's credentials. This allows a process started by /sbin/request-key to find keys belonging to the authorising process. (4) A key can be read, even if the process executing KEYCTL_READ doesn't have direct read or search permission if that key is contained within the keyrings of a process specified by an authorisation key found within the calling process's session keyring, and is searchable using the credentials of the authorising process. This allows a process started by /sbin/request-key to read keys belonging to the authorising process. (5) The magic KEY_SPEC_*_KEYRING key IDs when passed to KEYCTL_INSTANTIATE or KEYCTL_NEGATE will specify a keyring of the authorising process, rather than the process doing the instantiation. (6) One of the process keyrings can be nominated as the default to which request_key() should attach new keys if not otherwise specified. This is done with KEYCTL_SET_REQKEY_KEYRING and one of the KEY_REQKEY_DEFL_* constants. The current setting can also be read using this call. (7) request_key() is partially interruptible. If it is waiting for another process to finish constructing a key, it can be interrupted. This permits a request-key cycle to be broken without recourse to rebooting. Signed-Off-By: David Howells Signed-Off-By: Benoit Boissinot Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/keys.txt | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'Documentation') diff --git a/Documentation/keys.txt b/Documentation/keys.txt index 3df40c1fe15a..0321ded4b9ae 100644 --- a/Documentation/keys.txt +++ b/Documentation/keys.txt @@ -591,6 +591,37 @@ The keyctl syscall functions are: this case too. + (*) Set the default request-key destination keyring. + + long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl); + + This sets the default keyring to which implicitly requested keys will be + attached for this thread. reqkey_defl should be one of these constants: + + CONSTANT VALUE NEW DEFAULT KEYRING + ====================================== ====== ======================= + KEY_REQKEY_DEFL_NO_CHANGE -1 No change + KEY_REQKEY_DEFL_DEFAULT 0 Default[1] + KEY_REQKEY_DEFL_THREAD_KEYRING 1 Thread keyring + KEY_REQKEY_DEFL_PROCESS_KEYRING 2 Process keyring + KEY_REQKEY_DEFL_SESSION_KEYRING 3 Session keyring + KEY_REQKEY_DEFL_USER_KEYRING 4 User keyring + KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 User session keyring + KEY_REQKEY_DEFL_GROUP_KEYRING 6 Group keyring + + The old default will be returned if successful and error EINVAL will be + returned if reqkey_defl is not one of the above values. + + The default keyring can be overridden by the keyring indicated to the + request_key() system call. + + Note that this setting is inherited across fork/exec. + + [1] The default default is: the thread keyring if there is one, otherwise + the process keyring if there is one, otherwise the session keyring if + there is one, otherwise the user default session keyring. + + =============== KERNEL SERVICES =============== @@ -626,6 +657,9 @@ payload contents" for more information. Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be returned. + If successful, the key will have been attached to the default keyring for + implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING. + (*) When it is no longer required, the key should be released using: -- cgit v1.2.2 From 845e78a15726f238fe1398b8c07754726cd726a7 Mon Sep 17 00:00:00 2001 From: Corey Minyard Date: Thu, 23 Jun 2005 22:01:39 -0700 Subject: [PATCH] ipmi: doc updates This cleans up the IPMI documentation to fix some problems and make it more accurate for the current drivers. Signed-off-by: Corey Minyard Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/IPMI.txt | 126 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 94 insertions(+), 32 deletions(-) (limited to 'Documentation') diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt index 90d10e708ca3..2f99fe6299ab 100644 --- a/Documentation/IPMI.txt +++ b/Documentation/IPMI.txt @@ -25,9 +25,10 @@ subject and I can't cover it all here! Configuration ------------- -The LinuxIPMI driver is modular, which means you have to pick several +The Linux IPMI driver is modular, which means you have to pick several things to have it work right depending on your hardware. Most of -these are available in the 'Character Devices' menu. +these are available in the 'Character Devices' menu then the IPMI +menu. No matter what, you must pick 'IPMI top-level message handler' to use IPMI. What you do beyond that depends on your needs and hardware. @@ -35,33 +36,30 @@ IPMI. What you do beyond that depends on your needs and hardware. The message handler does not provide any user-level interfaces. Kernel code (like the watchdog) can still use it. If you need access from userland, you need to select 'Device interface for IPMI' if you -want access through a device driver. Another interface is also -available, you may select 'IPMI sockets' in the 'Networking Support' -main menu. This provides a socket interface to IPMI. You may select -both of these at the same time, they will both work together. - -The driver interface depends on your hardware. If you have a board -with a standard interface (These will generally be either "KCS", -"SMIC", or "BT", consult your hardware manual), choose the 'IPMI SI -handler' option. A driver also exists for direct I2C access to the -IPMI management controller. Some boards support this, but it is -unknown if it will work on every board. For this, choose 'IPMI SMBus -handler', but be ready to try to do some figuring to see if it will -work. - -There is also a KCS-only driver interface supplied, but it is -depracated in favor of the SI interface. +want access through a device driver. + +The driver interface depends on your hardware. If your system +properly provides the SMBIOS info for IPMI, the driver will detect it +and just work. If you have a board with a standard interface (These +will generally be either "KCS", "SMIC", or "BT", consult your hardware +manual), choose the 'IPMI SI handler' option. A driver also exists +for direct I2C access to the IPMI management controller. Some boards +support this, but it is unknown if it will work on every board. For +this, choose 'IPMI SMBus handler', but be ready to try to do some +figuring to see if it will work on your system if the SMBIOS/APCI +information is wrong or not present. It is fairly safe to have both +these enabled and let the drivers auto-detect what is present. You should generally enable ACPI on your system, as systems with IPMI -should have ACPI tables describing them. +can have ACPI tables describing them. If you have a standard interface and the board manufacturer has done their job correctly, the IPMI controller should be automatically -detect (via ACPI or SMBIOS tables) and should just work. Sadly, many -boards do not have this information. The driver attempts standard -defaults, but they may not work. If you fall into this situation, you -need to read the section below named 'The SI Driver' on how to -hand-configure your system. +detected (via ACPI or SMBIOS tables) and should just work. Sadly, +many boards do not have this information. The driver attempts +standard defaults, but they may not work. If you fall into this +situation, you need to read the section below named 'The SI Driver' or +"The SMBus Driver" on how to hand-configure your system. IPMI defines a standard watchdog timer. You can enable this with the 'IPMI Watchdog Timer' config option. If you compile the driver into @@ -73,6 +71,18 @@ closed (by default it is disabled on close). Go into the 'Watchdog Cards' menu, enable 'Watchdog Timer Support', and enable the option 'Disable watchdog shutdown on close'. +IPMI systems can often be powered off using IPMI commands. Select +'IPMI Poweroff' to do this. The driver will auto-detect if the system +can be powered off by IPMI. It is safe to enable this even if your +system doesn't support this option. This works on ATCA systems, the +Radisys CPI1 card, and any IPMI system that supports standard chassis +management commands. + +If you want the driver to put an event into the event log on a panic, +enable the 'Generate a panic event to all BMCs on a panic' option. If +you want the whole panic string put into the event log using OEM +events, enable the 'Generate OEM events containing the panic string' +option. Basic Design ------------ @@ -80,7 +90,7 @@ Basic Design The Linux IPMI driver is designed to be very modular and flexible, you only need to take the pieces you need and you can use it in many different ways. Because of that, it's broken into many chunks of -code. These chunks are: +code. These chunks (by module name) are: ipmi_msghandler - This is the central piece of software for the IPMI system. It handles all messages, message timing, and responses. The @@ -93,18 +103,26 @@ ipmi_devintf - This provides a userland IOCTL interface for the IPMI driver, each open file for this device ties in to the message handler as an IPMI user. -ipmi_si - A driver for various system interfaces. This supports -KCS, SMIC, and may support BT in the future. Unless you have your own -custom interface, you probably need to use this. +ipmi_si - A driver for various system interfaces. This supports KCS, +SMIC, and BT interfaces. Unless you have an SMBus interface or your +own custom interface, you probably need to use this. ipmi_smb - A driver for accessing BMCs on the SMBus. It uses the I2C kernel driver's SMBus interfaces to send and receive IPMI messages over the SMBus. -af_ipmi - A network socket interface to IPMI. This doesn't take up -a character device in your system. +ipmi_watchdog - IPMI requires systems to have a very capable watchdog +timer. This driver implements the standard Linux watchdog timer +interface on top of the IPMI message handler. + +ipmi_poweroff - Some systems support the ability to be turned off via +IPMI commands. + +These are all individually selectable via configuration options. -Note that the KCS-only interface ahs been removed. +Note that the KCS-only interface has been removed. The af_ipmi driver +is no longer supported and has been removed because it was impossible +to do 32 bit emulation on 64-bit kernels with it. Much documentation for the interface is in the include files. The IPMI include files are: @@ -424,7 +442,7 @@ at module load time (for a module) with: modprobe ipmi_smb.o addr=,[,,[,...]] dbg=,... - [defaultprobe=0] [dbg_probe=1] + [defaultprobe=1] [dbg_probe=1] The addresses are specified in pairs, the first is the adapter ID and the second is the I2C address on that adapter. @@ -532,3 +550,47 @@ Once you open the watchdog timer, you must write a 'V' character to the device to close it, or the timer will not stop. This is a new semantic for the driver, but makes it consistent with the rest of the watchdog drivers in Linux. + + +Panic Timeouts +-------------- + +The OpenIPMI driver supports the ability to put semi-custom and custom +events in the system event log if a panic occurs. if you enable the +'Generate a panic event to all BMCs on a panic' option, you will get +one event on a panic in a standard IPMI event format. If you enable +the 'Generate OEM events containing the panic string' option, you will +also get a bunch of OEM events holding the panic string. + + +The field settings of the events are: +* Generator ID: 0x21 (kernel) +* EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format) +* Sensor Type: 0x20 (OS critical stop sensor) +* Sensor #: The first byte of the panic string (0 if no panic string) +* Event Dir | Event Type: 0x6f (Assertion, sensor-specific event info) +* Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3) +* Event data 2: second byte of panic string +* Event data 3: third byte of panic string +See the IPMI spec for the details of the event layout. This event is +always sent to the local management controller. It will handle routing +the message to the right place + +Other OEM events have the following format: +Record ID (bytes 0-1): Set by the SEL. +Record type (byte 2): 0xf0 (OEM non-timestamped) +byte 3: The slave address of the card saving the panic +byte 4: A sequence number (starting at zero) +The rest of the bytes (11 bytes) are the panic string. If the panic string +is longer than 11 bytes, multiple messages will be sent with increasing +sequence numbers. + +Because you cannot send OEM events using the standard interface, this +function will attempt to find an SEL and add the events there. It +will first query the capabilities of the local management controller. +If it has an SEL, then they will be stored in the SEL of the local +management controller. If not, and the local management controller is +an event generator, the event receiver from the local management +controller will be queried and the events sent to the SEL on that +device. Otherwise, the events go nowhere since there is nowhere to +send them. -- cgit v1.2.2 From 3b6259432dee81f928c22c48c080d5f6325ed92e Mon Sep 17 00:00:00 2001 From: Corey Minyard Date: Thu, 23 Jun 2005 22:01:42 -0700 Subject: [PATCH] ipmi: add power cycle capability This patch to adds "power cycle" functionality to the IPMI power off module ipmi_poweroff. It also contains changes to support procfs control of the feature. The power cycle action is considered an optional chassis control in the IPMI specification. However, it is definitely useful when the hardware supports it. A power cycle is usually required in order to reset a firmware in a bad state. This action is critical to allow remote management of servers. The implementation adds power cycle as optional to the ipmi_poweroff module. It can be modified dynamically through the proc entry mentioned above. During a power down and enabled, the power cycle command is sent to the BMC firmware. If it fails either due to non-support or some error, it will retry to send the command as power off. Signed-off-by: Christopher A. Poblete Signed-off-by: Corey Minyard Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/IPMI.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'Documentation') diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt index 2f99fe6299ab..84d3d4d10c17 100644 --- a/Documentation/IPMI.txt +++ b/Documentation/IPMI.txt @@ -594,3 +594,23 @@ an event generator, the event receiver from the local management controller will be queried and the events sent to the SEL on that device. Otherwise, the events go nowhere since there is nowhere to send them. + + +Poweroff +-------- + +If the poweroff capability is selected, the IPMI driver will install +a shutdown function into the standard poweroff function pointer. This +is in the ipmi_poweroff module. When the system requests a powerdown, +it will send the proper IPMI commands to do this. This is supported on +several platforms. + +There is a module parameter named "poweroff_control" that may either be zero +(do a power down) or 2 (do a power cycle, power the system off, then power +it on in a few seconds). Setting ipmi_poweroff.poweroff_control=x will do +the same thing on the kernel command line. The parameter is also available +via the proc filesystem in /proc/ipmi/poweroff_control. Note that if the +system does not support power cycling, it will always to the power off. + +Note that if you have ACPI enabled, the system will prefer using ACPI to +power off. -- cgit v1.2.2 From b6a235b1186dda0800c8bedc2526830a4a36b44e Mon Sep 17 00:00:00 2001 From: Johannes Stezenbach Date: Thu, 23 Jun 2005 22:02:29 -0700 Subject: [PATCH] dvb: drop obsolete dibusb driver Remove the dibusb driver which has been obsoleted by the generalized dvb-usb driver. Signed-off-by: Patrick Boettcher Signed-off-by: Johannes Stezenbach Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/dvb/README.dibusb | 285 ---------------------------------------- 1 file changed, 285 deletions(-) delete mode 100644 Documentation/dvb/README.dibusb (limited to 'Documentation') diff --git a/Documentation/dvb/README.dibusb b/Documentation/dvb/README.dibusb deleted file mode 100644 index 7a9e958513f3..000000000000 --- a/Documentation/dvb/README.dibusb +++ /dev/null @@ -1,285 +0,0 @@ -Documentation for dib3000* frontend drivers and dibusb device driver -==================================================================== - -Copyright (C) 2004-5 Patrick Boettcher (patrick.boettcher@desy.de), - -dibusb and dib3000mb/mc drivers based on GPL code, which has - -Copyright (C) 2004 Amaury Demol for DiBcom (ademol@dibcom.fr) - -This program is free software; you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, version 2. - - -Supported devices USB1.1 -======================== - -Produced and reselled by Twinhan: ---------------------------------- -- TwinhanDTV USB-Ter DVB-T Device (VP7041) - http://www.twinhan.com/product_terrestrial_3.asp - -- TwinhanDTV Magic Box (VP7041e) - http://www.twinhan.com/product_terrestrial_4.asp - -- HAMA DVB-T USB device - http://www.hama.de/portal/articleId*110620/action*2598 - -- CTS Portable (Chinese Television System) (2) - http://www.2cts.tv/ctsportable/ - -- Unknown USB DVB-T device with vendor ID Hyper-Paltek - - -Produced and reselled by KWorld: --------------------------------- -- KWorld V-Stream XPERT DTV DVB-T USB - http://www.kworld.com.tw/en/product/DVBT-USB/DVBT-USB.html - -- JetWay DTV DVB-T USB - http://www.jetway.com.tw/evisn/product/lcd-tv/DVT-USB/dtv-usb.htm - -- ADSTech Instant TV DVB-T USB - http://www.adstech.com/products/PTV-333/intro/PTV-333_intro.asp?pid=PTV-333 - - -Others: -------- -- Ultima Electronic/Artec T1 USB TVBOX (AN2135, AN2235, AN2235 with Panasonic Tuner) - http://82.161.246.249/products-tvbox.html - -- Compro Videomate DVB-U2000 - DVB-T USB (2) - http://www.comprousa.com/products/vmu2000.htm - -- Grandtec USB DVB-T - http://www.grand.com.tw/ - -- Avermedia AverTV DVBT USB (2) - http://www.avermedia.com/ - -- DiBcom USB DVB-T reference device (non-public) - - -Supported devices USB2.0 -======================== -- Twinhan MagicBox II (2) - http://www.twinhan.com/product_terrestrial_7.asp - -- Hanftek UMT-010 (1) - http://www.globalsources.com/si/6008819757082/ProductDetail/Digital-TV/product_id-100046529 - -- Typhoon/Yakumo/HAMA DVB-T mobile USB2.0 (1) - http://www.yakumo.de/produkte/index.php?pid=1&ag=DVB-T - -- Artec T1 USB TVBOX (FX2) (2) - -- Hauppauge WinTV NOVA-T USB2 - http://www.hauppauge.com/ - -- KWorld/ADSTech Instant DVB-T USB2.0 (DiB3000M-B) - -- DiBcom USB2.0 DVB-T reference device (non-public) - -1) It is working almost. -2) No test reports received yet. - - -0. NEWS: - 2005-02-11 - added support for the KWorld/ADSTech Instant DVB-T USB2.0. Thanks a lot to Joachim von Caron - 2005-02-02 - added support for the Hauppauge Win-TV Nova-T USB2 - 2005-01-31 - distorted streaming is finally gone for USB1.1 devices - 2005-01-13 - moved the mirrored pid_filter_table back to dvb-dibusb - - first almost working version for HanfTek UMT-010 - - found out, that Yakumo/HAMA/Typhoon are predessors of the HanfTek UMT-010 - 2005-01-10 - refactoring completed, now everything is very delightful - - tuner quirks for some weird devices (Artec T1 AN2235 device has sometimes a - Panasonic Tuner assembled). Tunerprobing implemented. Thanks a lot to Gunnar Wittich. - 2004-12-29 - after several days of struggling around bug of no returning URBs fixed. - 2004-12-26 - refactored the dibusb-driver, splitted into separate files - - i2c-probing enabled - 2004-12-06 - possibility for demod i2c-address probing - - new usb IDs (Compro,Artec) - 2004-11-23 - merged changes from DiB3000MC_ver2.1 - - revised the debugging - - possibility to deliver the complete TS for USB2.0 - 2004-11-21 - first working version of the dib3000mc/p frontend driver. - 2004-11-12 - added additional remote control keys. Thanks to Uwe Hanke. - 2004-11-07 - added remote control support. Thanks to David Matthews. - 2004-11-05 - added support for a new devices (Grandtec/Avermedia/Artec) - - merged my changes (for dib3000mb/dibusb) to the FE_REFACTORING, because it became HEAD - - moved transfer control (pid filter, fifo control) from usb driver to frontend, it seems - better settled there (added xfer_ops-struct) - - created a common files for frontends (mc/p/mb) - 2004-09-28 - added support for a new device (Unkown, vendor ID is Hyper-Paltek) - 2004-09-20 - added support for a new device (Compro DVB-U2000), thanks - to Amaury Demol for reporting - - changed usb TS transfer method (several urbs, stopping transfer - before setting a new pid) - 2004-09-13 - added support for a new device (Artec T1 USB TVBOX), thanks - to Christian Motschke for reporting - 2004-09-05 - released the dibusb device and dib3000mb-frontend driver - - (old news for vp7041.c) - 2004-07-15 - found out, by accident, that the device has a TUA6010XS for - PLL - 2004-07-12 - figured out, that the driver should also work with the - CTS Portable (Chinese Television System) - 2004-07-08 - firmware-extraction-2.422-problem solved, driver is now working - properly with firmware extracted from 2.422 - - #if for 2.6.4 (dvb), compile issue - - changed firmware handling, see vp7041.txt sec 1.1 - 2004-07-02 - some tuner modifications, v0.1, cleanups, first public - 2004-06-28 - now using the dvb_dmx_swfilter_packets, everything - runs fine now - 2004-06-27 - able to watch and switching channels (pre-alpha) - - no section filtering yet - 2004-06-06 - first TS received, but kernel oops :/ - 2004-05-14 - firmware loader is working - 2004-05-11 - start writing the driver - -1. How to use? -NOTE: This driver was developed using Linux 2.6.6., -it is working with 2.6.7 and above. - -Linux 2.4.x support is not planned, but patches are very welcome. - -NOTE: I'm using Debian testing, so the following explaination (especially -the hotplug-path) needn't match your system, but probably it will :). - -The driver is included in the kernel since Linux 2.6.10. - -1.1. Firmware - -The USB driver needs to download a firmware to start working. - -You can either use "get_dvb_firmware dibusb" to download the firmware or you -can get it directly via - -for USB1.1 (AN2135) -http://www.linuxtv.org/downloads/firmware/dvb-dibusb-5.0.0.11.fw - -for USB1.1 (AN2235) (a few Artec T1 devices) -http://www.linuxtv.org/downloads/firmware/dvb-dibusb-an2235-1.fw - -for USB2.0 (FX2) Hauppauge, DiBcom -http://www.linuxtv.org/downloads/firmware/dvb-dibusb-6.0.0.5.fw - -for USB2.0 ADSTech/Kworld USB2.0 -http://www.linuxtv.org/downloads/firmware/dvb-dibusb-adstech-usb2-1.fw - -for USB2.0 HanfTek -http://www.linuxtv.org/downloads/firmware/dvb-dibusb-an2235-1.fw - - -1.2. Compiling - -Since the driver is in the linux kernel, activating the driver in -your favorite config-environment should sufficient. I recommend -to compile the driver as module. Hotplug does the rest. - -1.3. Loading the drivers - -Hotplug is able to load the driver, when it is needed (because you plugged -in the device). - -If you want to enable debug output, you have to load the driver manually and -from withing the dvb-kernel cvs repository. - -first have a look, which debug level are available: - -modinfo dib3000mb -modinfo dib3000-common -modinfo dib3000mc -modinfo dvb-dibusb - -modprobe dib3000-common debug= -modprobe dib3000mb debug= -modprobe dib3000mc debug= -modprobe dvb-dibusb debug= - -should do the trick. - -When the driver is loaded successfully, the firmware file was in -the right place and the device is connected, the "Power"-LED should be -turned on. - -At this point you should be able to start a dvb-capable application. For myself -I used mplayer, dvbscan, tzap and kaxtv, they are working. Using the device -in vdr is working now also. - -2. Known problems and bugs - -- Don't remove the USB device while running an DVB application, your system will die. - -2.1. Adding support for devices - -It is not possible to determine the range of devices based on the DiBcom -reference designs. This is because the reference design of DiBcom can be sold -to thirds, without telling DiBcom (so done with the Twinhan VP7041 and -the HAMA device). - -When you think you have a device like this and the driver does not recognizes it, -please send the ****load*.inf and the ****cap*.inf of the Windows driver to me. - -Sometimes the Vendor or Product ID is identical to the ones of Twinhan, even -though it is not a Twinhan device (e.g. HAMA), then please send me the name -of the device. I will add it to this list in order to make this clear to -others. - -If you are familar with C you can also add the VID and PID of the device to -the dvb-dibusb-core.c-file and create a patch and send it over to me or to -the linux-dvb mailing list, _after_ you have tried compiling and modprobing -it. - -2.2. USB1.1 Bandwidth limitation - -Most of the currently supported devices are USB1.1 and thus they have a -maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub. -This is not enough for receiving the complete transport stream of a -DVB-T channel (which can be about 16 MBit/s). Normally this is not a -problem, if you only want to watch TV (this does not apply for HDTV), -but watching a channel while recording another channel on the same -frequency simply does not work very well. This applies to all USB1.1 -DVB-T devices, not just dibusb) - -Update: For the USB1.1 and VDR some work has been done (patches and comments -are still very welcome). Maybe the problem is solved in the meantime because I -now use the dmx_sw_filter function instead of dmx_sw_filter_packet. I hope the -linux-dvb software filter is able to get the best of the garbled TS. - -The bug, where the TS is distorted by a heavy usage of the device is gone -definitely. All dibusb-devices I was using (Twinhan, Kworld, DiBcom) are -working like charm now with VDR. Sometimes I even was able to record a channel -and watch another one. - -2.3. Comments - -Patches, comments and suggestions are very very welcome. - -3. Acknowledgements - Amaury Demol (ademol@dibcom.fr) and Francois Kanounnikoff from DiBcom for - providing specs, code and help, on which the dvb-dibusb, dib3000mb and - dib3000mc are based. - - David Matthews for identifying a new device type (Artec T1 with AN2235) - and for extending dibusb with remote control event handling. Thank you. - - Alex Woods for frequently answering question about usb and dvb - stuff, a big thank you. - - Bernd Wagner for helping with huge bug reports and discussions. - - Gunnar Wittich and Joachim von Caron for their trust for giving me - root-shells on their machines to implement support for new devices. - - Some guys on the linux-dvb mailing list for encouraging me - - Peter Schildmann >peter.schildmann-nospam-at-web.de< for his - user-level firmware loader, which saves a lot of time - (when writing the vp7041 driver) - - Ulf Hermenau for helping me out with traditional chinese. - - André Smoktun and Christian Frömmel for supporting me with - hardware and listening to my problems very patient -- cgit v1.2.2 From 776338e121b9db3156bfb4e21622a0219bbab9d4 Mon Sep 17 00:00:00 2001 From: Johannes Stezenbach Date: Thu, 23 Jun 2005 22:02:35 -0700 Subject: [PATCH] dvb: Add generalized dvb-usb driver Add generalized dvb-usb driver which supports a wide variety of devices. Signed-off-by: Patrick Boettcher Signed-off-by: Johannes Stezenbach Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/dvb/README.dvb-usb | 308 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 Documentation/dvb/README.dvb-usb (limited to 'Documentation') diff --git a/Documentation/dvb/README.dvb-usb b/Documentation/dvb/README.dvb-usb new file mode 100644 index 000000000000..c7ed01b9f8f4 --- /dev/null +++ b/Documentation/dvb/README.dvb-usb @@ -0,0 +1,308 @@ +Documentation for dvb-usb-framework module and its devices + +Idea behind the dvb-usb-framework +================================= + +In March 2005 I got the new Twinhan USB2.0 DVB-T device. They provided specs and a firmware. + +Quite keen I wanted to put the driver (with some quirks of course) into dibusb. +After reading some specs and doing some USB snooping, it realized, that the +dibusb-driver would be a complete mess afterwards. So I decided to do it in a +different way: With the help of a dvb-usb-framework. + +The framework provides generic functions (mostly kernel API calls), such as: + +- Transport Stream URB handling in conjunction with dvb-demux-feed-control + (bulk and isoc (TODO) are supported) +- registering the device for the DVB-API +- registering an I2C-adapter if applicable +- remote-control/input-device handling +- firmware requesting and loading (currently just for the Cypress USB + controller) +- other functions/methods which can be shared by several drivers (such as + functions for bulk-control-commands) + +The source code of the particular DVB USB devices does just the communication +with the device via the bus. The connection between the DVB-API-functionality +is done via callbacks, assigned in a static device-description (struct +dvb_usb_device) each device-driver has to have. + +For an example have a look in drivers/media/dvb/dvb-usb/vp7045*. + +Objective is to migrate all the usb-devices (dibusb, cinergyT2, maybe the +ttusb; flexcop-usb already benefits from the generic flexcop-device) to use +the dvb-usb-lib. + +TODO: dynamic enabling and disabling of the pid-filter in regard to number of +feeds requested. + +Supported devices USB1.1 +======================== + +Produced and reselled by Twinhan: +--------------------------------- +- TwinhanDTV USB-Ter DVB-T Device (VP7041) + http://www.twinhan.com/product_terrestrial_3.asp + +- TwinhanDTV Magic Box (VP7041e) + http://www.twinhan.com/product_terrestrial_4.asp + +- HAMA DVB-T USB device + http://www.hama.de/portal/articleId*110620/action*2598 + +- CTS Portable (Chinese Television System) (2) + http://www.2cts.tv/ctsportable/ + +- Unknown USB DVB-T device with vendor ID Hyper-Paltek + + +Produced and reselled by KWorld: +-------------------------------- +- KWorld V-Stream XPERT DTV DVB-T USB + http://www.kworld.com.tw/en/product/DVBT-USB/DVBT-USB.html + +- JetWay DTV DVB-T USB + http://www.jetway.com.tw/evisn/product/lcd-tv/DVT-USB/dtv-usb.htm + +- ADSTech Instant TV DVB-T USB + http://www.adstech.com/products/PTV-333/intro/PTV-333_intro.asp?pid=PTV-333 + + +Others: +------- +- Ultima Electronic/Artec T1 USB TVBOX (AN2135, AN2235, AN2235 with Panasonic Tuner) + http://82.161.246.249/products-tvbox.html + +- Compro Videomate DVB-U2000 - DVB-T USB (2) + http://www.comprousa.com/products/vmu2000.htm + +- Grandtec USB DVB-T + http://www.grand.com.tw/ + +- AVerMedia AverTV DVBT USB + http://www.avermedia.com/ + +- DiBcom USB DVB-T reference device (non-public) + + +Supported devices USB2.0-only +============================= +- Twinhan MagicBox II + http://www.twinhan.com/product_terrestrial_7.asp + +- TwinhanDTV Alpha + http://www.twinhan.com/product_terrestrial_8.asp + +- DigitalNow TinyUSB 2 DVB-t Receiver + http://www.digitalnow.com.au/DigitalNow%20tinyUSB2%20Specifications.html + +- Hanftek UMT-010 + http://www.globalsources.com/si/6008819757082/ProductDetail/Digital-TV/product_id-100046529 + + +Supported devices USB2.0 and USB1.1 +============================= +- Typhoon/Yakumo/HAMA/Yuan DVB-T mobile USB2.0 + http://www.yakumo.de/produkte/index.php?pid=1&ag=DVB-T + http://www.yuan.com.tw/en/products/vdo_ub300.html + http://www.hama.de/portal/articleId*114663/action*2563 + http://www.anubisline.com/english/articlec.asp?id=50502&catid=002 + +- Artec T1 USB TVBOX (FX2) (2) + +- Hauppauge WinTV NOVA-T USB2 + http://www.hauppauge.com/ + +- KWorld/ADSTech Instant DVB-T USB2.0 (DiB3000M-B) + +- DiBcom USB2.0 DVB-T reference device (non-public) + +- AVerMedia AverTV A800 DVB-T USB2.0 + +1) It is working almost - work-in-progress. +2) No test reports received yet. + +0. History & News: + 2005-04-17 - all dibusb devices ported to make use of the dvb-usb-framework + 2005-04-02 - re-enabled and improved remote control code. + 2005-03-31 - ported the Yakumo/Hama/Typhoon DVB-T USB2.0 device to dvb-usb. + 2005-03-30 - first commit of the dvb-usb-module based on the dibusb-source. First device is a new driver for the + TwinhanDTV Alpha / MagicBox II USB2.0-only DVB-T device. + + (change from dvb-dibusb to dvb-usb) + 2005-03-28 - added support for the AVerMedia AverTV DVB-T USB2.0 device (Thanks to Glen Harris and Jiun-Kuei Jung, AVerMedia) + 2005-03-14 - added support for the Typhoon/Yakumo/HAMA DVB-T mobile USB2.0 + 2005-02-11 - added support for the KWorld/ADSTech Instant DVB-T USB2.0. Thanks a lot to Joachim von Caron + 2005-02-02 - added support for the Hauppauge Win-TV Nova-T USB2 + 2005-01-31 - distorted streaming is gone for USB1.1 devices + 2005-01-13 - moved the mirrored pid_filter_table back to dvb-dibusb + - first almost working version for HanfTek UMT-010 + - found out, that Yakumo/HAMA/Typhoon are predessors of the HanfTek UMT-010 + 2005-01-10 - refactoring completed, now everything is very delightful + - tuner quirks for some weird devices (Artec T1 AN2235 device has sometimes a + Panasonic Tuner assembled). Tunerprobing implemented. Thanks a lot to Gunnar Wittich. + 2004-12-29 - after several days of struggling around bug of no returning URBs fixed. + 2004-12-26 - refactored the dibusb-driver, splitted into separate files + - i2c-probing enabled + 2004-12-06 - possibility for demod i2c-address probing + - new usb IDs (Compro, Artec) + 2004-11-23 - merged changes from DiB3000MC_ver2.1 + - revised the debugging + - possibility to deliver the complete TS for USB2.0 + 2004-11-21 - first working version of the dib3000mc/p frontend driver. + 2004-11-12 - added additional remote control keys. Thanks to Uwe Hanke. + 2004-11-07 - added remote control support. Thanks to David Matthews. + 2004-11-05 - added support for a new devices (Grandtec/Avermedia/Artec) + - merged my changes (for dib3000mb/dibusb) to the FE_REFACTORING, because it became HEAD + - moved transfer control (pid filter, fifo control) from usb driver to frontend, it seems + better settled there (added xfer_ops-struct) + - created a common files for frontends (mc/p/mb) + 2004-09-28 - added support for a new device (Unkown, vendor ID is Hyper-Paltek) + 2004-09-20 - added support for a new device (Compro DVB-U2000), thanks + to Amaury Demol for reporting + - changed usb TS transfer method (several urbs, stopping transfer + before setting a new pid) + 2004-09-13 - added support for a new device (Artec T1 USB TVBOX), thanks + to Christian Motschke for reporting + 2004-09-05 - released the dibusb device and dib3000mb-frontend driver + + (old news for vp7041.c) + 2004-07-15 - found out, by accident, that the device has a TUA6010XS for + PLL + 2004-07-12 - figured out, that the driver should also work with the + CTS Portable (Chinese Television System) + 2004-07-08 - firmware-extraction-2.422-problem solved, driver is now working + properly with firmware extracted from 2.422 + - #if for 2.6.4 (dvb), compile issue + - changed firmware handling, see vp7041.txt sec 1.1 + 2004-07-02 - some tuner modifications, v0.1, cleanups, first public + 2004-06-28 - now using the dvb_dmx_swfilter_packets, everything + runs fine now + 2004-06-27 - able to watch and switching channels (pre-alpha) + - no section filtering yet + 2004-06-06 - first TS received, but kernel oops :/ + 2004-05-14 - firmware loader is working + 2004-05-11 - start writing the driver + +1. How to use? +1.1. Firmware + +Most of the USB drivers need to download a firmware to start working. + +for USB1.1 (AN2135) you need: dvb-usb-dibusb-5.0.0.11.fw +for USB2.0 HanfTek: dvb-usb-umt-010-02.fw +for USB2.0 DiBcom: dvb-usb-dibusb-6.0.0.8.fw +for USB2.0 AVerMedia AverTV DVB-T USB2: dvb-usb-avertv-a800-01.fw +for USB2.0 TwinhanDTV Alpha/MagicBox II: dvb-usb-vp7045-01.fw + +The files can be found on http://www.linuxtv.org/download/firmware/ . + +We do not have the permission (yet) to publish the following firmware-files. +You'll need to extract them from the windows drivers. + +You should be able to use "get_dvb_firmware dvb-usb" to get the firmware: + +for USB1.1 (AN2235) (a few Artec T1 devices): dvb-usb-dibusb-an2235-01.fw +for USB2.0 Hauppauge: dvb-usb-nova-t-usb2-01.fw +for USB2.0 ADSTech/Kworld USB2.0: dvb-usb-adstech-usb2-01.fw +for USB2.0 Yakumo/Typhoon/Hama: dvb-usb-dtt200u-01.fw + +1.2. Compiling + +Since the driver is in the linux kernel, activating the driver in +your favorite config-environment should sufficient. I recommend +to compile the driver as module. Hotplug does the rest. + +If you use dvb-kernel enter the build-2.6 directory run 'make' and 'insmod.sh +load' afterwards. + +1.3. Loading the drivers + +Hotplug is able to load the driver, when it is needed (because you plugged +in the device). + +If you want to enable debug output, you have to load the driver manually and +from withing the dvb-kernel cvs repository. + +first have a look, which debug level are available: + +modinfo dvb-usb +modinfo dvb-usb-vp7045 +etc. + +modprobe dvb-usb debug= +modprobe dvb-usb-vp7045 debug= +etc. + +should do the trick. + +When the driver is loaded successfully, the firmware file was in +the right place and the device is connected, the "Power"-LED should be +turned on. + +At this point you should be able to start a dvb-capable application. I'm use +(t|s)zap, mplayer and dvbscan to test the basics. VDR-xine provides the +long-term test scenario. + +2. Known problems and bugs + +- Don't remove the USB device while running an DVB application, your system + will go crazy or die most likely. + +2.1. Adding support for devices + +TODO + +2.2. USB1.1 Bandwidth limitation + +A lot of the currently supported devices are USB1.1 and thus they have a +maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub. +This is not enough for receiving the complete transport stream of a +DVB-T channel (which is about 16 MBit/s). Normally this is not a +problem, if you only want to watch TV (this does not apply for HDTV), +but watching a channel while recording another channel on the same +frequency simply does not work very well. This applies to all USB1.1 +DVB-T devices, not just the dvb-usb-devices) + +The bug, where the TS is distorted by a heavy usage of the device is gone +definitely. All dvb-usb-devices I was using (Twinhan, Kworld, DiBcom) are +working like charm now with VDR. Sometimes I even was able to record a channel +and watch another one. + +2.3. Comments + +Patches, comments and suggestions are very very welcome. + +3. Acknowledgements + Amaury Demol (ademol@dibcom.fr) and Francois Kanounnikoff from DiBcom for + providing specs, code and help, on which the dvb-dibusb, dib3000mb and + dib3000mc are based. + + David Matthews for identifying a new device type (Artec T1 with AN2235) + and for extending dibusb with remote control event handling. Thank you. + + Alex Woods for frequently answering question about usb and dvb + stuff, a big thank you. + + Bernd Wagner for helping with huge bug reports and discussions. + + Gunnar Wittich and Joachim von Caron for their trust for providing + root-shells on their machines to implement support for new devices. + + Glen Harris for bringing up, that there is a new dibusb-device and Jiun-Kuei + Jung from AVerMedia who kindly provided a special firmware to get the device + up and running in Linux. + + Jennifer Chen, Jeff and Jack from Twinhan for kindly supporting by + writing the vp7045-driver. + + Some guys on the linux-dvb mailing list for encouraging me + + Peter Schildmann >peter.schildmann-nospam-at-web.de< for his + user-level firmware loader, which saves a lot of time + (when writing the vp7041 driver) + + Ulf Hermenau for helping me out with traditional chinese. + + André Smoktun and Christian Frömmel for supporting me with + hardware and listening to my problems very patient. -- cgit v1.2.2 From 0c0a400d1debb172c596b24ab82efab4975990a9 Mon Sep 17 00:00:00 2001 From: John Levon Date: Thu, 23 Jun 2005 22:02:47 -0700 Subject: [PATCH] oprofile: report anonymous region samples The below patch passes samples from anonymous regions to userspace instead of just dropping them. This provides the support needed for reporting anonymous-region code samples (today: basic accumulated results; later: Java and other dynamically compiled code). As this changes the format, an upgrade to the just-released 0.9 release of the userspace tools is required. This patch is based upon an earlier one by Will Cohen Signed-off-by: John Levon Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/Changes | 2 +- Documentation/basic_profiling.txt | 10 +++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/Changes b/Documentation/Changes index 57542bc25edd..b37600754762 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -63,7 +63,7 @@ o PPP 2.4.0 # pppd --version o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version o nfs-utils 1.0.5 # showmount --version o procps 3.2.0 # ps --version -o oprofile 0.5.3 # oprofiled --version +o oprofile 0.9 # oprofiled --version Kernel compilation ================== diff --git a/Documentation/basic_profiling.txt b/Documentation/basic_profiling.txt index 65e3dc2d4437..8764e9f70821 100644 --- a/Documentation/basic_profiling.txt +++ b/Documentation/basic_profiling.txt @@ -27,9 +27,13 @@ dump output readprofile -m /boot/System.map > captured_profile Oprofile -------- -Get the source (I use 0.8) from http://oprofile.sourceforge.net/ -and add "idle=poll" to the kernel command line + +Get the source (see Changes for required version) from +http://oprofile.sourceforge.net/ and add "idle=poll" to the kernel command +line. + Configure with CONFIG_PROFILING=y and CONFIG_OPROFILE=y & reboot on new kernel + ./configure --with-kernel-support make install @@ -46,7 +50,7 @@ start opcontrol --start stop opcontrol --stop dump output opreport > output_file -To only report on the kernel, run opreport /boot/vmlinux > output_file +To only report on the kernel, run opreport -l /boot/vmlinux > output_file A reset is needed to clear old statistics, which survive a reboot. -- cgit v1.2.2 From d81ef559daf2a8afa9292035d58b00e7cb23dd1a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 23 Jun 2005 22:04:51 -0700 Subject: [PATCH] Video for Linux Documentation This patch synchronizes documentation from V4L CVS with current kernel release. Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/video4linux/CARDLIST.bttv | 14 ++++++ Documentation/video4linux/CARDLIST.cx88 | 29 ++++++++++++ Documentation/video4linux/CARDLIST.saa7134 | 29 ++++++++++-- Documentation/video4linux/CARDLIST.tuner | 15 ++++++ .../video4linux/hauppauge-wintv-cx88-ir.txt | 54 ++++++++++++++++++++++ Documentation/video4linux/lifeview.txt | 42 +++++++++++++++++ .../video4linux/not-in-cx2388x-datasheet.txt | 37 +++++++++++++++ 7 files changed, 216 insertions(+), 4 deletions(-) create mode 100644 Documentation/video4linux/CARDLIST.cx88 create mode 100644 Documentation/video4linux/hauppauge-wintv-cx88-ir.txt create mode 100644 Documentation/video4linux/lifeview.txt create mode 100644 Documentation/video4linux/not-in-cx2388x-datasheet.txt (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.bttv b/Documentation/video4linux/CARDLIST.bttv index e46761c39e3f..aeeafec0594c 100644 --- a/Documentation/video4linux/CARDLIST.bttv +++ b/Documentation/video4linux/CARDLIST.bttv @@ -119,3 +119,17 @@ card=117 - NGS NGSTV+ card=118 - LMLBT4 card=119 - Tekram M205 PRO card=120 - Conceptronic CONTVFMi +card=121 - Euresys Picolo Tetra +card=122 - Spirit TV Tuner +card=123 - AVerMedia AVerTV DVB-T 771 +card=124 - AverMedia AverTV DVB-T 761 +card=125 - MATRIX Vision Sigma-SQ +card=126 - MATRIX Vision Sigma-SLC +card=127 - APAC Viewcomp 878(AMAX) +card=128 - DVICO FusionHDTV DVB-T Lite +card=129 - V-Gear MyVCD +card=130 - Super TV Tuner +card=131 - Tibet Systems 'Progress DVR' CS16 +card=132 - Kodicom 4400R (master) +card=133 - Kodicom 4400R (slave) +card=134 - Adlink RTV24 diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88 new file mode 100644 index 000000000000..a87f752e5411 --- /dev/null +++ b/Documentation/video4linux/CARDLIST.cx88 @@ -0,0 +1,29 @@ +card=0 - UNKNOWN/GENERIC +card=1 - Hauppauge WinTV 34xxx models +card=2 - GDI Black Gold +card=3 - PixelView +card=4 - ATI TV Wonder Pro +card=5 - Leadtek Winfast 2000XP Expert +card=6 - AverTV Studio 303 (M126) +card=7 - MSI TV-@nywhere Master +card=8 - Leadtek Winfast DV2000 +card=9 - Leadtek PVR 2000 +card=10 - IODATA GV-VCP3/PCI +card=11 - Prolink PlayTV PVR +card=12 - ASUS PVR-416 +card=13 - MSI TV-@nywhere +card=14 - KWorld/VStream XPert DVB-T +card=15 - DVICO FusionHDTV DVB-T1 +card=16 - KWorld LTV883RF +card=17 - DViCO - FusionHDTV 3 Gold +card=18 - Hauppauge Nova-T DVB-T +card=19 - Conexant DVB-T reference design +card=20 - Provideo PV259 +card=21 - DVICO FusionHDTV DVB-T Plus +card=22 - digitalnow DNTV Live! DVB-T +card=23 - pcHDTV HD3000 HDTV +card=24 - Hauppauge WinTV 28xxx (Roslyn) models +card=25 - Digital-Logic MICROSPACE Entertainment Center (MEC) +card=26 - IODATA GV/BCTV7E +card=27 - PixelView PlayTV Ultra Pro (Stereo) +card=28 - DViCO - FusionHDTV 3 Gold-Q diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index a6c82fa4de02..d5ed95d28500 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -20,16 +20,37 @@ 19 -> Compro VideoMate TV [185b:c100] 20 -> Matrox CronosPlus [102B:48d0] 21 -> 10MOONS PCI TV CAPTURE CARD [1131:2001] - 22 -> Medion 2819/ AverMedia M156 [1461:a70b,1461:2115] + 22 -> AverMedia M156 / Medion 2819 [1461:a70b] 23 -> BMK MPEX Tuner 24 -> KNC One TV-Station DVR [1894:a006] 25 -> ASUS TV-FM 7133 [1043:4843] 26 -> Pinnacle PCTV Stereo (saa7134) [11bd:002b] - 27 -> Manli MuchTV M-TV002 - 28 -> Manli MuchTV M-TV001 + 27 -> Manli MuchTV M-TV002/Behold TV 403 FM + 28 -> Manli MuchTV M-TV001/Behold TV 401 29 -> Nagase Sangyo TransGear 3000TV [1461:050c] 30 -> Elitegroup ECS TVP3XP FM1216 Tuner Card(PAL-BG,FM) [1019:4cb4] 31 -> Elitegroup ECS TVP3XP FM1236 Tuner Card (NTSC,FM) [1019:4cb5] 32 -> AVACS SmartTV 33 -> AVerMedia DVD EZMaker [1461:10ff] - 34 -> LifeView FlyTV Platinum33 mini [5168:0212] + 34 -> Noval Prime TV 7133 + 35 -> AverMedia AverTV Studio 305 [1461:2115] + 37 -> Items MuchTV Plus / IT-005 + 38 -> Terratec Cinergy 200 TV [153B:1152] + 39 -> LifeView FlyTV Platinum Mini [5168:0212] + 40 -> Compro VideoMate TV PVR/FM [185b:c100] + 41 -> Compro VideoMate TV Gold+ [185b:c100] + 42 -> Sabrent SBT-TVFM (saa7130) + 43 -> :Zolid Xpert TV7134 + 44 -> Empire PCI TV-Radio LE + 45 -> Avermedia AVerTV Studio 307 [1461:9715] + 46 -> AVerMedia Cardbus TV/Radio [1461:d6ee] + 47 -> Terratec Cinergy 400 mobile [153b:1162] + 48 -> Terratec Cinergy 600 TV MK3 [153B:1158] + 49 -> Compro VideoMate Gold+ Pal [185b:c200] + 50 -> Pinnacle PCTV 300i DVB-T + PAL [11bd:002d] + 51 -> ProVideo PV952 [1540:9524] + 52 -> AverMedia AverTV/305 [1461:2108] + 54 -> LifeView FlyTV Platinum FM [5168:0214,1489:0214] + 55 -> LifeView FlyDVB-T DUO [5168:0306] + 56 -> Avermedia AVerTV 307 [1461:a70a] + 57 -> Avermedia AVerTV GO 007 FM [1461:f31f] diff --git a/Documentation/video4linux/CARDLIST.tuner b/Documentation/video4linux/CARDLIST.tuner index f7bafe862ba0..7f4fd0de4412 100644 --- a/Documentation/video4linux/CARDLIST.tuner +++ b/Documentation/video4linux/CARDLIST.tuner @@ -44,3 +44,18 @@ tuner=42 - Philips 1236D ATSC/NTSC daul in tuner=43 - Philips NTSC MK3 (FM1236MK3 or FM1236/F) tuner=44 - Philips 4 in 1 (ATI TV Wonder Pro/Conexant) tuner=45 - Microtune 4049 FM5 +tuner=46 - Panasonic VP27s/ENGE4324D +tuner=47 - LG NTSC (TAPE series) +tuner=48 - Tenna TNF 8831 BGFF) +tuner=49 - Microtune 4042 FI5 ATSC/NTSC dual in +tuner=50 - TCL 2002N +tuner=51 - Philips PAL/SECAM_D (FM 1256 I-H3) +tuner=52 - Thomson DDT 7610 (ATSC/NTSC) +tuner=53 - Philips FQ1286 +tuner=54 - tda8290+75 +tuner=55 - LG PAL (TAPE series) +tuner=56 - Philips PAL/SECAM multi (FQ1216AME MK4) +tuner=57 - Philips FQ1236A MK4 +tuner=58 - Ymec TVision TVF-8531MF +tuner=59 - Ymec TVision TVF-5533MF +tuner=60 - Thomson DDT 7611 diff --git a/Documentation/video4linux/hauppauge-wintv-cx88-ir.txt b/Documentation/video4linux/hauppauge-wintv-cx88-ir.txt new file mode 100644 index 000000000000..93fec32a1188 --- /dev/null +++ b/Documentation/video4linux/hauppauge-wintv-cx88-ir.txt @@ -0,0 +1,54 @@ +The controls for the mux are GPIO [0,1] for source, and GPIO 2 for muting. + +GPIO0 GPIO1 + 0 0 TV Audio + 1 0 FM radio + 0 1 Line-In + 1 1 Mono tuner bypass or CD passthru (tuner specific) + +GPIO 16(i believe) is tied to the IR port (if present). + +------------------------------------------------------------------------------------ + +>From the data sheet: + Register 24'h20004 PCI Interrupt Status + bit [18] IR_SMP_INT Set when 32 input samples have been collected over + gpio[16] pin into GP_SAMPLE register. + +What's missing from the data sheet: + +Setup 4KHz sampling rate (roughly 2x oversampled; good enough for our RC5 +compat remote) +set register 0x35C050 to 0xa80a80 + +enable sampling +set register 0x35C054 to 0x5 + +Of course, enable the IRQ bit 18 in the interrupt mask register .(and +provide for a handler) + +GP_SAMPLE register is at 0x35C058 + +Bits are then right shifted into the GP_SAMPLE register at the specified +rate; you get an interrupt when a full DWORD is recieved. +You need to recover the actual RC5 bits out of the (oversampled) IR sensor +bits. (Hint: look for the 0/1and 1/0 crossings of the RC5 bi-phase data) An +actual raw RC5 code will span 2-3 DWORDS, depending on the actual alignment. + +I'm pretty sure when no IR signal is present the receiver is always in a +marking state(1); but stray light, etc can cause intermittent noise values +as well. Remember, this is a free running sample of the IR receiver state +over time, so don't assume any sample starts at any particular place. + +http://www.atmel.com/dyn/resources/prod_documents/doc2817.pdf +This data sheet (google search) seems to have a lovely description of the +RC5 basics + +http://users.pandora.be/nenya/electronics/rc5/ and more data + +http://www.ee.washington.edu/circuit_archive/text/ir_decode.txt +and even a reference to how to decode a bi-phase data stream. + +http://www.xs4all.nl/~sbp/knowledge/ir/rc5.htm +still more info + diff --git a/Documentation/video4linux/lifeview.txt b/Documentation/video4linux/lifeview.txt new file mode 100644 index 000000000000..b07ea79c2b7e --- /dev/null +++ b/Documentation/video4linux/lifeview.txt @@ -0,0 +1,42 @@ +collecting data about the lifeview models and the config coding on +gpio pins 0-9 ... +================================================================== + +bt878: + LR50 rev. Q ("PARTS: 7031505116), Tuner wurde als Nr. 5 erkannt, Eingänge + SVideo, TV, Composite, Audio, Remote. CP9..1=100001001 (1: 0-Ohm-Widerstand + gegen GND unbestückt; 0: bestückt) + +------------------------------------------------------------------------------ + +saa7134: + /* LifeView FlyTV Platinum FM (LR214WF) */ + /* "Peter Missel */ + .name = "LifeView FlyTV Platinum FM", + /* GP27 MDT2005 PB4 pin 10 */ + /* GP26 MDT2005 PB3 pin 9 */ + /* GP25 MDT2005 PB2 pin 8 */ + /* GP23 MDT2005 PB1 pin 7 */ + /* GP22 MDT2005 PB0 pin 6 */ + /* GP21 MDT2005 PB5 pin 11 */ + /* GP20 MDT2005 PB6 pin 12 */ + /* GP19 MDT2005 PB7 pin 13 */ + /* nc MDT2005 PA3 pin 2 */ + /* Remote MDT2005 PA2 pin 1 */ + /* GP18 MDT2005 PA1 pin 18 */ + /* nc MDT2005 PA0 pin 17 strap low */ + + /* GP17 Strap "GP7"=High */ + /* GP16 Strap "GP6"=High + 0=Radio 1=TV + Drives SA630D ENCH1 and HEF4052 A1 pins + to do FM radio through SIF input */ + /* GP15 nc */ + /* GP14 nc */ + /* GP13 nc */ + /* GP12 Strap "GP5" = High */ + /* GP11 Strap "GP4" = High */ + /* GP10 Strap "GP3" = High */ + /* GP09 Strap "GP2" = Low */ + /* GP08 Strap "GP1" = Low */ + /* GP07.00 nc */ diff --git a/Documentation/video4linux/not-in-cx2388x-datasheet.txt b/Documentation/video4linux/not-in-cx2388x-datasheet.txt new file mode 100644 index 000000000000..96b638b5ba1d --- /dev/null +++ b/Documentation/video4linux/not-in-cx2388x-datasheet.txt @@ -0,0 +1,37 @@ +================================================================================= +MO_OUTPUT_FORMAT (0x310164) + + Previous default from DScaler: 0x1c1f0008 + Digit 8: 31-28 + 28: PREVREMOD = 1 + + Digit 7: 27-24 (0xc = 12 = b1100 ) + 27: COMBALT = 1 + 26: PAL_INV_PHASE + (DScaler apparently set this to 1, resulted in sucky picture) + + Digits 6,5: 23-16 + 25-16: COMB_RANGE = 0x1f [default] (9 bits -> max 512) + + Digit 4: 15-12 + 15: DISIFX = 0 + 14: INVCBF = 0 + 13: DISADAPT = 0 + 12: NARROWADAPT = 0 + + Digit 3: 11-8 + 11: FORCE2H + 10: FORCEREMD + 9: NCHROMAEN + 8: NREMODEN + + Digit 2: 7-4 + 7-6: YCORE + 5-4: CCORE + + Digit 1: 3-0 + 3: RANGE = 1 + 2: HACTEXT + 1: HSFMT + +================================================================================= -- cgit v1.2.2 From 80d34362f391840dcb10c0ec261f765871a586f7 Mon Sep 17 00:00:00 2001 From: Michael Krufky Date: Thu, 23 Jun 2005 22:04:55 -0700 Subject: [PATCH] DViCO FusionHDTV3 Gold-T documentation fix Even though it says DViCO FusionHDTV3 Gold-Q on the box, Gold-T is printed on the card. This fix corrects the error in all places, and corrects the tuner name Thomson DDT 7611 (ATSC/NTSC) in the documentation. This applies against 2.6.12-rc5-mm2 after applying Manueal Capinha's patch "Add support for PixelView Ultra Pro in v4l" (because of the change from card=27 to card=28) Signed-off-by: Michael Krufky Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/video4linux/CARDLIST.cx88 | 2 +- Documentation/video4linux/CARDLIST.tuner | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88 index a87f752e5411..216f705495cc 100644 --- a/Documentation/video4linux/CARDLIST.cx88 +++ b/Documentation/video4linux/CARDLIST.cx88 @@ -26,4 +26,4 @@ card=24 - Hauppauge WinTV 28xxx (Roslyn) models card=25 - Digital-Logic MICROSPACE Entertainment Center (MEC) card=26 - IODATA GV/BCTV7E card=27 - PixelView PlayTV Ultra Pro (Stereo) -card=28 - DViCO - FusionHDTV 3 Gold-Q +card=28 - DViCO - FusionHDTV 3 Gold-T diff --git a/Documentation/video4linux/CARDLIST.tuner b/Documentation/video4linux/CARDLIST.tuner index 7f4fd0de4412..aeb8df8ce890 100644 --- a/Documentation/video4linux/CARDLIST.tuner +++ b/Documentation/video4linux/CARDLIST.tuner @@ -58,4 +58,4 @@ tuner=56 - Philips PAL/SECAM multi (FQ1216AME MK4) tuner=57 - Philips FQ1236A MK4 tuner=58 - Ymec TVision TVF-8531MF tuner=59 - Ymec TVision TVF-5533MF -tuner=60 - Thomson DDT 7611 +tuner=60 - Thomson DDT 7611 (ATSC/NTSC) -- cgit v1.2.2 From 597f6eea75ff3d089e6a627c07e1bf28923b8e7e Mon Sep 17 00:00:00 2001 From: Jiri Slaby Date: Thu, 23 Jun 2005 22:05:18 -0700 Subject: [PATCH] docbook build fix Fix documentation build with `make O=' Cc: Martin Waitz Cc: Sam Ravnborg Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/DocBook/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 87da3478fada..fa3e29ad8a46 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -49,7 +49,7 @@ installmandocs: mandocs KERNELDOC = scripts/kernel-doc DOCPROC = scripts/basic/docproc -XMLTOFLAGS = -m Documentation/DocBook/stylesheet.xsl +XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl #XMLTOFLAGS += --skip-validation ### -- cgit v1.2.2 From 363412b4f70a2ba19c76a01da7580472399312d4 Mon Sep 17 00:00:00 2001 From: Martin Waitz Date: Thu, 23 Jun 2005 22:05:20 -0700 Subject: [PATCH] DocBook: only use tabular style for long synopsis There was a complaint that function declarations are shown tabular in the documentation since switching to xmlto. This patch disables tabular mode when the function fits in one line. Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/DocBook/stylesheet.xsl | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl index e14c21dda403..64be9f7ee3bb 100644 --- a/Documentation/DocBook/stylesheet.xsl +++ b/Documentation/DocBook/stylesheet.xsl @@ -2,4 +2,5 @@ 1 ansi +80 -- cgit v1.2.2 From 3d41088fa327782b14b5659dbcfff62ec704c23c Mon Sep 17 00:00:00 2001 From: Martin Waitz Date: Thu, 23 Jun 2005 22:05:21 -0700 Subject: [PATCH] DocBook: update comments This patch updates some comments to match code changes. Signed-off-by: Martin Waitz Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/DocBook/kernel-api.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index bb6a0106be11..d650ce36485f 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -266,7 +266,7 @@ X!Ekernel/module.c Hardware Interfaces Interrupt Handling -!Iarch/i386/kernel/irq.c +!Ikernel/irq/manage.c Resources Management -- cgit v1.2.2 From d763b7a4736e219528f77bf6bc75dd78b1d75c03 Mon Sep 17 00:00:00 2001 From: Carsten Otte Date: Thu, 23 Jun 2005 22:05:31 -0700 Subject: [PATCH] xip: description Signed-off-by: Carsten Otte Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/filesystems/ext2.txt | 2 ++ Documentation/filesystems/xip.txt | 67 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+) create mode 100644 Documentation/filesystems/xip.txt (limited to 'Documentation') diff --git a/Documentation/filesystems/ext2.txt b/Documentation/filesystems/ext2.txt index b5cb9110cc6b..d16334ec48ba 100644 --- a/Documentation/filesystems/ext2.txt +++ b/Documentation/filesystems/ext2.txt @@ -58,6 +58,8 @@ noacl Don't support POSIX ACLs. nobh Do not attach buffer_heads to file pagecache. +xip Use execute in place (no caching) if possible + grpquota,noquota,quota,usrquota Quota options are silently ignored by ext2. diff --git a/Documentation/filesystems/xip.txt b/Documentation/filesystems/xip.txt new file mode 100644 index 000000000000..6c0cef10eb4d --- /dev/null +++ b/Documentation/filesystems/xip.txt @@ -0,0 +1,67 @@ +Execute-in-place for file mappings +---------------------------------- + +Motivation +---------- +File mappings are performed by mapping page cache pages to userspace. In +addition, read&write type file operations also transfer data from/to the page +cache. + +For memory backed storage devices that use the block device interface, the page +cache pages are in fact copies of the original storage. Various approaches +exist to work around the need for an extra copy. The ramdisk driver for example +does read the data into the page cache, keeps a reference, and discards the +original data behind later on. + +Execute-in-place solves this issue the other way around: instead of keeping +data in the page cache, the need to have a page cache copy is eliminated +completely. With execute-in-place, read&write type operations are performed +directly from/to the memory backed storage device. For file mappings, the +storage device itself is mapped directly into userspace. + +This implementation was initialy written for shared memory segments between +different virtual machines on s390 hardware to allow multiple machines to +share the same binaries and libraries. + +Implementation +-------------- +Execute-in-place is implemented in three steps: block device operation, +address space operation, and file operations. + +A block device operation named direct_access is used to retrieve a +reference (pointer) to a block on-disk. The reference is supposed to be +cpu-addressable, physical address and remain valid until the release operation +is performed. A struct block_device reference is used to address the device, +and a sector_t argument is used to identify the individual block. As an +alternative, memory technology devices can be used for this. + +The block device operation is optional, these block devices support it as of +today: +- dcssblk: s390 dcss block device driver + +An address space operation named get_xip_page is used to retrieve reference +to a struct page. To address the target page, a reference to an address_space, +and a sector number is provided. A 3rd argument indicates whether the +function should allocate blocks if needed. + +This address space operation is mutually exclusive with readpage&writepage that +do page cache read/write operations. +The following filesystems support it as of today: +- ext2: the second extended filesystem, see Documentation/filesystems/ext2.txt + +A set of file operations that do utilize get_xip_page can be found in +mm/filemap_xip.c . The following file operation implementations are provided: +- aio_read/aio_write +- readv/writev +- sendfile + +The generic file operations do_sync_read/do_sync_write can be used to implement +classic synchronous IO calls. + +Shortcomings +------------ +This implementation is limited to storage devices that are cpu addressable at +all times (no highmem or such). It works well on rom/ram, but enhancements are +needed to make it work with flash in read+write mode. +Putting the Linux kernel and/or its modules on a xip filesystem does not mean +they are not copied. -- cgit v1.2.2