diff --git a/[refs] b/[refs] index 553f5ec24eb6..83be4e19ddc9 100644 --- a/[refs] +++ b/[refs] @@ -1,2 +1,2 @@ --- -refs/heads/master: aaebf4332018980fef4e601d1b5a6e52dd9e9ae4 +refs/heads/master: ef88b7dba2b47c70037a34a599d383462bb74bd3 diff --git a/trunk/CREDITS b/trunk/CREDITS index 3b7a1548aaf9..f553f8cfaa62 100644 --- a/trunk/CREDITS +++ b/trunk/CREDITS @@ -1624,10 +1624,10 @@ E: ajoshi@shell.unixbox.com D: fbdev hacking N: Jesper Juhl -E: juhl-lkml@dif.dk -D: Various small janitor fixes, cleanups etc. +E: jesper.juhl@gmail.com +D: Various fixes, cleanups and minor features. S: Lemnosvej 1, 3.tv -S: 2300 Copenhagen S +S: 2300 Copenhagen S. S: Denmark N: Jozsef Kadlecsik @@ -2380,8 +2380,8 @@ E: tmolina@cablespeed.com D: bug fixes, documentation, minor hackery N: James Morris -E: jmorris@redhat.com -W: http://www.intercode.com.au/jmorris/ +E: jmorris@namei.org +W: http://namei.org/ D: Netfilter, Linux Security Modules (LSM), SELinux, IPSec, D: Crypto API, general networking, miscellaneous. S: PO Box 707 @@ -2423,8 +2423,7 @@ S: Toronto, Ontario S: Canada N: Zwane Mwaikambo -E: zwane@linuxpower.ca -W: http://function.linuxpower.ca +E: zwane@arm.linux.org.uk D: Various driver hacking D: Lowlevel x86 kernel hacking D: General debugging diff --git a/trunk/Documentation/Changes b/trunk/Documentation/Changes index dfec7569d450..5eaab0441d76 100644 --- a/trunk/Documentation/Changes +++ b/trunk/Documentation/Changes @@ -65,6 +65,7 @@ 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.9 # oprofiled --version +o udev 058 # udevinfo -V Kernel compilation ================== diff --git a/trunk/Documentation/SubmittingPatches b/trunk/Documentation/SubmittingPatches index 6761a7b241a5..7f43b040311e 100644 --- a/trunk/Documentation/SubmittingPatches +++ b/trunk/Documentation/SubmittingPatches @@ -149,6 +149,11 @@ USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the MAINTAINERS file for a mailing list that relates specifically to your change. +If changes affect userland-kernel interfaces, please send +the MAN-PAGES maintainer (as listed in the MAINTAINERS file) +a man-pages patch, or at least a notification of the change, +so that some information makes its way into the manual pages. + Even if the maintainer did not respond in step #4, make sure to ALWAYS copy the maintainer when you change their code. diff --git a/trunk/Documentation/acpi-hotkey.txt b/trunk/Documentation/acpi-hotkey.txt new file mode 100644 index 000000000000..0acdc80c30c2 --- /dev/null +++ b/trunk/Documentation/acpi-hotkey.txt @@ -0,0 +1,38 @@ +driver/acpi/hotkey.c implement: +1. /proc/acpi/hotkey/event_config +(event based hotkey or event config interface): +a. add a event based hotkey(event) : +echo "0:bus::action:method:num:num" > event_config + +b. delete a event based hotkey(event): +echo "1:::::num:num" > event_config + +c. modify a event based hotkey(event): +echo "2:bus::action:method:num:num" > event_config + +2. /proc/acpi/hotkey/poll_config +(polling based hotkey or event config interface): +a.add a polling based hotkey(event) : +echo "0:bus:method:action:method:num" > poll_config +this adding command will create a proc file +/proc/acpi/hotkey/method, which is used to get +result of polling. + +b.delete a polling based hotkey(event): +echo "1:::::num" > event_config + +c.modify a polling based hotkey(event): +echo "2:bus:method:action:method:num" > poll_config + +3./proc/acpi/hotkey/action +(interface to call aml method associated with a +specific hotkey(event)) +echo "event_num:event_type:event_argument" > + /proc/acpi/hotkey/action. +The result of the execution of this aml method is +attached to /proc/acpi/hotkey/poll_method, which is dnyamically +created. Please use command "cat /proc/acpi/hotkey/polling_method" +to retrieve it. + +Note: Use cmdline "acpi_generic_hotkey" to over-ride +loading any platform specific drivers. diff --git a/trunk/Documentation/arm/Samsung-S3C24XX/USB-Host.txt b/trunk/Documentation/arm/Samsung-S3C24XX/USB-Host.txt new file mode 100644 index 000000000000..b93b68e2b143 --- /dev/null +++ b/trunk/Documentation/arm/Samsung-S3C24XX/USB-Host.txt @@ -0,0 +1,93 @@ + S3C24XX USB Host support + ======================== + + + +Introduction +------------ + + This document details the S3C2410/S3C2440 in-built OHCI USB host support. + +Configuration +------------- + + Enable at least the following kernel options: + + menuconfig: + + Device Drivers ---> + USB support ---> + <*> Support for Host-side USB + <*> OHCI HCD support + + + .config: + CONFIG_USB + CONFIG_USB_OHCI_HCD + + + Once these options are configured, the standard set of USB device + drivers can be configured and used. + + +Board Support +------------- + + The driver attaches to a platform device, which will need to be + added by the board specific support file in linux/arch/arm/mach-s3c2410, + such as mach-bast.c or mach-smdk2410.c + + The platform device's platform_data field is only needed if the + board implements extra power control or over-current monitoring. + + The OHCI driver does not ensure the state of the S3C2410's MISCCTRL + register, so if both ports are to be used for the host, then it is + the board support file's responsibility to ensure that the second + port is configured to be connected to the OHCI core. + + +Platform Data +------------- + + See linux/include/asm-arm/arch-s3c2410/usb-control.h for the + descriptions of the platform device data. An implementation + can be found in linux/arch/arm/mach-s3c2410/usb-simtec.c . + + The `struct s3c2410_hcd_info` contains a pair of functions + that get called to enable over-current detection, and to + control the port power status. + + The ports are numbered 0 and 1. + + power_control: + + Called to enable or disable the power on the port. + + enable_oc: + + Called to enable or disable the over-current monitoring. + This should claim or release the resources being used to + check the power condition on the port, such as an IRQ. + + report_oc: + + The OHCI driver fills this field in for the over-current code + to call when there is a change to the over-current state on + an port. The ports argument is a bitmask of 1 bit per port, + with bit X being 1 for an over-current on port X. + + The function s3c2410_usb_report_oc() has been provided to + ensure this is called correctly. + + port[x]: + + This is struct describes each port, 0 or 1. The platform driver + should set the flags field of each port to S3C_HCDFLG_USED if + the port is enabled. + + + +Document Author +--------------- + +Ben Dooks, (c) 2005 Simtec Electronics diff --git a/trunk/Documentation/crypto/api-intro.txt b/trunk/Documentation/crypto/api-intro.txt index a2d5b4900772..74dffc68ff9f 100644 --- a/trunk/Documentation/crypto/api-intro.txt +++ b/trunk/Documentation/crypto/api-intro.txt @@ -223,6 +223,7 @@ CAST5 algorithm contributors: TEA/XTEA algorithm contributors: Aaron Grothe + Michael Ringe Khazad algorithm contributors: Aaron Grothe diff --git a/trunk/Documentation/dontdiff b/trunk/Documentation/dontdiff index d4fda25db868..96bea278bbf6 100644 --- a/trunk/Documentation/dontdiff +++ b/trunk/Documentation/dontdiff @@ -41,6 +41,7 @@ COPYING CREDITS CVS ChangeSet +Image Kerntypes MODS.txt Module.symvers @@ -103,6 +104,8 @@ logo_*.c logo_*_clut224.c logo_*_mono.c lxdialog +mach-types +mach-types.h make_times_h map maui_boot.h diff --git a/trunk/Documentation/fb/vesafb.txt b/trunk/Documentation/fb/vesafb.txt index 814e2f56a6ad..62db6758d1c1 100644 --- a/trunk/Documentation/fb/vesafb.txt +++ b/trunk/Documentation/fb/vesafb.txt @@ -144,7 +144,21 @@ vgapal Use the standard vga registers for palette changes. This is the default. pmipal Use the protected mode interface for palette changes. -mtrr setup memory type range registers for the vesafb framebuffer. +mtrr:n setup memory type range registers for the vesafb framebuffer + where n: + 0 - disabled (equivalent to nomtrr) + 1 - uncachable + 2 - write-back + 3 - write-combining (default) + 4 - write-through + + If you see the following in dmesg, choose the type that matches the + old one. In this example, use "mtrr:2". +... +mtrr: type mismatch for e0000000,8000000 old: write-back new: write-combining +... + +nomtrr disable mtrr vremap:n remap 'n' MiB of video RAM. If 0 or not specified, remap memory diff --git a/trunk/Documentation/feature-removal-schedule.txt b/trunk/Documentation/feature-removal-schedule.txt index 12dde43fe657..363909056e46 100644 --- a/trunk/Documentation/feature-removal-schedule.txt +++ b/trunk/Documentation/feature-removal-schedule.txt @@ -102,16 +102,6 @@ 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 @@ -135,3 +125,15 @@ Why: With the 16-bit PCMCIA subsystem now behaving (almost) like a pcmciautils package available at http://kernel.org/pub/linux/utils/kernel/pcmcia/ Who: Dominik Brodowski + +--------------------------- + +What: ip_queue and ip6_queue (old ipv4-only and ipv6-only netfilter queue) +When: December 2005 +Why: This interface has been obsoleted by the new layer3-independent + "nfnetlink_queue". The Kernel interface is compatible, so the old + ip[6]tables "QUEUE" targets still work and will transparently handle + all packets into nfnetlink queue number 0. Userspace users will have + to link against API-compatible library on top of libnfnetlink_queue + instead of the current 'libipq'. +Who: Harald Welte diff --git a/trunk/Documentation/filesystems/inotify.txt b/trunk/Documentation/filesystems/inotify.txt new file mode 100644 index 000000000000..6d501903f68e --- /dev/null +++ b/trunk/Documentation/filesystems/inotify.txt @@ -0,0 +1,151 @@ + inotify + a powerful yet simple file change notification system + + + +Document started 15 Mar 2005 by Robert Love + + +(i) User Interface + +Inotify is controlled by a set of three system calls and normal file I/O on a +returned file descriptor. + +First step in using inotify is to initialise an inotify instance: + + int fd = inotify_init (); + +Each instance is associated with a unique, ordered queue. + +Change events are managed by "watches". A watch is an (object,mask) pair where +the object is a file or directory and the mask is a bit mask of one or more +inotify events that the application wishes to receive. See +for valid events. A watch is referenced by a watch descriptor, or wd. + +Watches are added via a path to the file. + +Watches on a directory will return events on any files inside of the directory. + +Adding a watch is simple: + + int wd = inotify_add_watch (fd, path, mask); + +Where "fd" is the return value from inotify_init(), path is the path to the +object to watch, and mask is the watch mask (see ). + +You can update an existing watch in the same manner, by passing in a new mask. + +An existing watch is removed via + + int ret = inotify_rm_watch (fd, wd); + +Events are provided in the form of an inotify_event structure that is read(2) +from a given inotify instance. The filename is of dynamic length and follows +the struct. It is of size len. The filename is padded with null bytes to +ensure proper alignment. This padding is reflected in len. + +You can slurp multiple events by passing a large buffer, for example + + size_t len = read (fd, buf, BUF_LEN); + +Where "buf" is a pointer to an array of "inotify_event" structures at least +BUF_LEN bytes in size. The above example will return as many events as are +available and fit in BUF_LEN. + +Each inotify instance fd is also select()- and poll()-able. + +You can find the size of the current event queue via the standard FIONREAD +ioctl on the fd returned by inotify_init(). + +All watches are destroyed and cleaned up on close. + + +(ii) + +Prototypes: + + int inotify_init (void); + int inotify_add_watch (int fd, const char *path, __u32 mask); + int inotify_rm_watch (int fd, __u32 mask); + + +(iii) Internal Kernel Implementation + +Each inotify instance is associated with an inotify_device structure. + +Each watch is associated with an inotify_watch structure. Watches are chained +off of each associated device and each associated inode. + +See fs/inotify.c for the locking and lifetime rules. + + +(iv) Rationale + +Q: What is the design decision behind not tying the watch to the open fd of + the watched object? + +A: Watches are associated with an open inotify device, not an open file. + This solves the primary problem with dnotify: keeping the file open pins + the file and thus, worse, pins the mount. Dnotify is therefore infeasible + for use on a desktop system with removable media as the media cannot be + unmounted. Watching a file should not require that it be open. + +Q: What is the design decision behind using an-fd-per-instance as opposed to + an fd-per-watch? + +A: An fd-per-watch quickly consumes more file descriptors than are allowed, + more fd's than are feasible to manage, and more fd's than are optimally + select()-able. Yes, root can bump the per-process fd limit and yes, users + can use epoll, but requiring both is a silly and extraneous requirement. + A watch consumes less memory than an open file, separating the number + spaces is thus sensible. The current design is what user-space developers + want: Users initialize inotify, once, and add n watches, requiring but one + fd and no twiddling with fd limits. Initializing an inotify instance two + thousand times is silly. If we can implement user-space's preferences + cleanly--and we can, the idr layer makes stuff like this trivial--then we + should. + + There are other good arguments. With a single fd, there is a single + item to block on, which is mapped to a single queue of events. The single + fd returns all watch events and also any potential out-of-band data. If + every fd was a separate watch, + + - There would be no way to get event ordering. Events on file foo and + file bar would pop poll() on both fd's, but there would be no way to tell + which happened first. A single queue trivially gives you ordering. Such + ordering is crucial to existing applications such as Beagle. Imagine + "mv a b ; mv b a" events without ordering. + + - We'd have to maintain n fd's and n internal queues with state, + versus just one. It is a lot messier in the kernel. A single, linear + queue is the data structure that makes sense. + + - User-space developers prefer the current API. The Beagle guys, for + example, love it. Trust me, I asked. It is not a surprise: Who'd want + to manage and block on 1000 fd's via select? + + - No way to get out of band data. + + - 1024 is still too low. ;-) + + When you talk about designing a file change notification system that + scales to 1000s of directories, juggling 1000s of fd's just does not seem + the right interface. It is too heavy. + + Additionally, it _is_ possible to more than one instance and + juggle more than one queue and thus more than one associated fd. There + need not be a one-fd-per-process mapping; it is one-fd-per-queue and a + process can easily want more than one queue. + +Q: Why the system call approach? + +A: The poor user-space interface is the second biggest problem with dnotify. + Signals are a terrible, terrible interface for file notification. Or for + anything, for that matter. The ideal solution, from all perspectives, is a + file descriptor-based one that allows basic file I/O and poll/select. + Obtaining the fd and managing the watches could have been done either via a + device file or a family of new system calls. We decided to implement a + family of system calls because that is the preffered approach for new kernel + interfaces. The only real difference was whether we wanted to use open(2) + and ioctl(2) or a couple of new system calls. System calls beat ioctls. + diff --git a/trunk/Documentation/filesystems/ntfs.txt b/trunk/Documentation/filesystems/ntfs.txt index f89b440fad1d..eef4aca0c753 100644 --- a/trunk/Documentation/filesystems/ntfs.txt +++ b/trunk/Documentation/filesystems/ntfs.txt @@ -21,7 +21,7 @@ Overview ======== Linux-NTFS comes with a number of user-space programs known as ntfsprogs. -These include mkntfs, a full-featured ntfs file system format utility, +These include mkntfs, a full-featured ntfs filesystem format utility, ntfsundelete used for recovering files that were unintentionally deleted from an NTFS volume and ntfsresize which is used to resize an NTFS partition. See the web site for more information. @@ -149,7 +149,14 @@ case_sensitive= If case_sensitive is specified, treat all file names as name, if it exists. If case_sensitive, you will need to provide the correct case of the short file name. -errors=opt What to do when critical file system errors are found. +disable_sparse= If disable_sparse is specified, creation of sparse + regions, i.e. holes, inside files is disabled for the + volume (for the duration of this mount only). By + default, creation of sparse regions is enabled, which + is consistent with the behaviour of traditional Unix + filesystems. + +errors=opt What to do when critical filesystem errors are found. Following values can be used for "opt": continue: DEFAULT, try to clean-up as much as possible, e.g. marking a corrupt inode as @@ -432,6 +439,24 @@ ChangeLog Note, a technical ChangeLog aimed at kernel hackers is in fs/ntfs/ChangeLog. +2.1.23: + - Stamp the user space journal, aka transaction log, aka $UsnJrnl, if + it is present and active thus telling Windows and applications using + the transaction log that changes can have happened on the volume + which are not recorded in $UsnJrnl. + - Detect the case when Windows has been hibernated (suspended to disk) + and if this is the case do not allow (re)mounting read-write to + prevent data corruption when you boot back into the suspended + Windows session. + - Implement extension of resident files using the normal file write + code paths, i.e. most very small files can be extended to be a little + bit bigger but not by much. + - Add new mount option "disable_sparse". (See list of mount options + above for details.) + - Improve handling of ntfs volumes with errors and strange boot sectors + in particular. + - Fix various bugs including a nasty deadlock that appeared in recent + kernels (around 2.6.11-2.6.12 timeframe). 2.1.22: - Improve handling of ntfs volumes with errors. - Fix various bugs and race conditions. diff --git a/trunk/Documentation/filesystems/proc.txt b/trunk/Documentation/filesystems/proc.txt index 6c98f2bd421e..5024ba7a592c 100644 --- a/trunk/Documentation/filesystems/proc.txt +++ b/trunk/Documentation/filesystems/proc.txt @@ -133,6 +133,7 @@ Table 1-1: Process specific entries in /proc statm Process memory status information status Process status in human readable form wchan If CONFIG_KALLSYMS is set, a pre-decoded wchan + smaps Extension based on maps, presenting the rss size for each mapped file .............................................................................. For example, to get the status information of a process, all you have to do is diff --git a/trunk/Documentation/filesystems/sysfs.txt b/trunk/Documentation/filesystems/sysfs.txt index dc276598a65a..c8bce82ddcac 100644 --- a/trunk/Documentation/filesystems/sysfs.txt +++ b/trunk/Documentation/filesystems/sysfs.txt @@ -90,7 +90,7 @@ void device_remove_file(struct device *, struct device_attribute *); It also defines this helper for defining device attributes: -#define DEVICE_ATTR(_name,_mode,_show,_store) \ +#define DEVICE_ATTR(_name, _mode, _show, _store) \ struct device_attribute dev_attr_##_name = { \ .attr = {.name = __stringify(_name) , .mode = _mode }, \ .show = _show, \ @@ -99,14 +99,14 @@ struct device_attribute dev_attr_##_name = { \ For example, declaring -static DEVICE_ATTR(foo,0644,show_foo,store_foo); +static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo); is equivalent to doing: static struct device_attribute dev_attr_foo = { .attr = { .name = "foo", - .mode = 0644, + .mode = S_IWUSR | S_IRUGO, }, .show = show_foo, .store = store_foo, @@ -121,8 +121,8 @@ set of sysfs operations for forwarding read and write calls to the show and store methods of the attribute owners. struct sysfs_ops { - ssize_t (*show)(struct kobject *, struct attribute *,char *); - ssize_t (*store)(struct kobject *,struct attribute *,const char *); + ssize_t (*show)(struct kobject *, struct attribute *, char *); + ssize_t (*store)(struct kobject *, struct attribute *, const char *); }; [ Subsystems should have already defined a struct kobj_type as a @@ -137,7 +137,7 @@ calls the associated methods. To illustrate: -#define to_dev_attr(_attr) container_of(_attr,struct device_attribute,attr) +#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) #define to_dev(d) container_of(d, struct device, kobj) static ssize_t @@ -148,7 +148,7 @@ dev_attr_show(struct kobject * kobj, struct attribute * attr, char * buf) ssize_t ret = 0; if (dev_attr->show) - ret = dev_attr->show(dev,buf); + ret = dev_attr->show(dev, buf); return ret; } @@ -216,16 +216,16 @@ A very simple (and naive) implementation of a device attribute is: static ssize_t show_name(struct device *dev, struct device_attribute *attr, char *buf) { - return sprintf(buf,"%s\n",dev->name); + return snprintf(buf, PAGE_SIZE, "%s\n", dev->name); } static ssize_t store_name(struct device * dev, const char * buf) { - sscanf(buf,"%20s",dev->name); - return strlen(buf); + sscanf(buf, "%20s", dev->name); + return strnlen(buf, PAGE_SIZE); } -static DEVICE_ATTR(name,S_IRUGO,show_name,store_name); +static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); (Note that the real implementation doesn't allow userspace to set the @@ -290,7 +290,7 @@ struct device_attribute { Declaring: -DEVICE_ATTR(_name,_str,_mode,_show,_store); +DEVICE_ATTR(_name, _str, _mode, _show, _store); Creation/Removal: @@ -310,7 +310,7 @@ struct bus_attribute { Declaring: -BUS_ATTR(_name,_mode,_show,_store) +BUS_ATTR(_name, _mode, _show, _store) Creation/Removal: @@ -331,7 +331,7 @@ struct driver_attribute { Declaring: -DRIVER_ATTR(_name,_mode,_show,_store) +DRIVER_ATTR(_name, _mode, _show, _store) Creation/Removal: diff --git a/trunk/Documentation/i2c/chips/adm1021 b/trunk/Documentation/hwmon/adm1021 similarity index 100% rename from trunk/Documentation/i2c/chips/adm1021 rename to trunk/Documentation/hwmon/adm1021 diff --git a/trunk/Documentation/i2c/chips/adm1025 b/trunk/Documentation/hwmon/adm1025 similarity index 100% rename from trunk/Documentation/i2c/chips/adm1025 rename to trunk/Documentation/hwmon/adm1025 diff --git a/trunk/Documentation/i2c/chips/adm1026 b/trunk/Documentation/hwmon/adm1026 similarity index 100% rename from trunk/Documentation/i2c/chips/adm1026 rename to trunk/Documentation/hwmon/adm1026 diff --git a/trunk/Documentation/i2c/chips/adm1031 b/trunk/Documentation/hwmon/adm1031 similarity index 100% rename from trunk/Documentation/i2c/chips/adm1031 rename to trunk/Documentation/hwmon/adm1031 diff --git a/trunk/Documentation/i2c/chips/adm9240 b/trunk/Documentation/hwmon/adm9240 similarity index 100% rename from trunk/Documentation/i2c/chips/adm9240 rename to trunk/Documentation/hwmon/adm9240 diff --git a/trunk/Documentation/i2c/chips/asb100 b/trunk/Documentation/hwmon/asb100 similarity index 100% rename from trunk/Documentation/i2c/chips/asb100 rename to trunk/Documentation/hwmon/asb100 diff --git a/trunk/Documentation/i2c/chips/ds1621 b/trunk/Documentation/hwmon/ds1621 similarity index 100% rename from trunk/Documentation/i2c/chips/ds1621 rename to trunk/Documentation/hwmon/ds1621 diff --git a/trunk/Documentation/i2c/chips/fscher b/trunk/Documentation/hwmon/fscher similarity index 100% rename from trunk/Documentation/i2c/chips/fscher rename to trunk/Documentation/hwmon/fscher diff --git a/trunk/Documentation/i2c/chips/gl518sm b/trunk/Documentation/hwmon/gl518sm similarity index 100% rename from trunk/Documentation/i2c/chips/gl518sm rename to trunk/Documentation/hwmon/gl518sm diff --git a/trunk/Documentation/i2c/chips/it87 b/trunk/Documentation/hwmon/it87 similarity index 100% rename from trunk/Documentation/i2c/chips/it87 rename to trunk/Documentation/hwmon/it87 diff --git a/trunk/Documentation/i2c/chips/lm63 b/trunk/Documentation/hwmon/lm63 similarity index 100% rename from trunk/Documentation/i2c/chips/lm63 rename to trunk/Documentation/hwmon/lm63 diff --git a/trunk/Documentation/i2c/chips/lm75 b/trunk/Documentation/hwmon/lm75 similarity index 100% rename from trunk/Documentation/i2c/chips/lm75 rename to trunk/Documentation/hwmon/lm75 diff --git a/trunk/Documentation/i2c/chips/lm77 b/trunk/Documentation/hwmon/lm77 similarity index 100% rename from trunk/Documentation/i2c/chips/lm77 rename to trunk/Documentation/hwmon/lm77 diff --git a/trunk/Documentation/i2c/chips/lm78 b/trunk/Documentation/hwmon/lm78 similarity index 93% rename from trunk/Documentation/i2c/chips/lm78 rename to trunk/Documentation/hwmon/lm78 index 357086ed7f64..fd5dc7a19f0e 100644 --- a/trunk/Documentation/i2c/chips/lm78 +++ b/trunk/Documentation/hwmon/lm78 @@ -2,16 +2,11 @@ Kernel driver lm78 ================== Supported chips: - * National Semiconductor LM78 + * National Semiconductor LM78 / LM78-J Prefix: 'lm78' Addresses scanned: I2C 0x20 - 0x2f, ISA 0x290 (8 I/O ports) Datasheet: Publicly available at the National Semiconductor website http://www.national.com/ - * National Semiconductor LM78-J - Prefix: 'lm78-j' - Addresses scanned: I2C 0x20 - 0x2f, ISA 0x290 (8 I/O ports) - Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/ * National Semiconductor LM79 Prefix: 'lm79' Addresses scanned: I2C 0x20 - 0x2f, ISA 0x290 (8 I/O ports) diff --git a/trunk/Documentation/i2c/chips/lm80 b/trunk/Documentation/hwmon/lm80 similarity index 100% rename from trunk/Documentation/i2c/chips/lm80 rename to trunk/Documentation/hwmon/lm80 diff --git a/trunk/Documentation/i2c/chips/lm83 b/trunk/Documentation/hwmon/lm83 similarity index 100% rename from trunk/Documentation/i2c/chips/lm83 rename to trunk/Documentation/hwmon/lm83 diff --git a/trunk/Documentation/i2c/chips/lm85 b/trunk/Documentation/hwmon/lm85 similarity index 100% rename from trunk/Documentation/i2c/chips/lm85 rename to trunk/Documentation/hwmon/lm85 diff --git a/trunk/Documentation/i2c/chips/lm87 b/trunk/Documentation/hwmon/lm87 similarity index 100% rename from trunk/Documentation/i2c/chips/lm87 rename to trunk/Documentation/hwmon/lm87 diff --git a/trunk/Documentation/i2c/chips/lm90 b/trunk/Documentation/hwmon/lm90 similarity index 100% rename from trunk/Documentation/i2c/chips/lm90 rename to trunk/Documentation/hwmon/lm90 diff --git a/trunk/Documentation/i2c/chips/lm92 b/trunk/Documentation/hwmon/lm92 similarity index 100% rename from trunk/Documentation/i2c/chips/lm92 rename to trunk/Documentation/hwmon/lm92 diff --git a/trunk/Documentation/i2c/chips/max1619 b/trunk/Documentation/hwmon/max1619 similarity index 100% rename from trunk/Documentation/i2c/chips/max1619 rename to trunk/Documentation/hwmon/max1619 diff --git a/trunk/Documentation/i2c/chips/pc87360 b/trunk/Documentation/hwmon/pc87360 similarity index 100% rename from trunk/Documentation/i2c/chips/pc87360 rename to trunk/Documentation/hwmon/pc87360 diff --git a/trunk/Documentation/i2c/chips/sis5595 b/trunk/Documentation/hwmon/sis5595 similarity index 100% rename from trunk/Documentation/i2c/chips/sis5595 rename to trunk/Documentation/hwmon/sis5595 diff --git a/trunk/Documentation/i2c/chips/smsc47b397 b/trunk/Documentation/hwmon/smsc47b397 similarity index 100% rename from trunk/Documentation/i2c/chips/smsc47b397 rename to trunk/Documentation/hwmon/smsc47b397 diff --git a/trunk/Documentation/i2c/chips/smsc47m1 b/trunk/Documentation/hwmon/smsc47m1 similarity index 100% rename from trunk/Documentation/i2c/chips/smsc47m1 rename to trunk/Documentation/hwmon/smsc47m1 diff --git a/trunk/Documentation/i2c/sysfs-interface b/trunk/Documentation/hwmon/sysfs-interface similarity index 100% rename from trunk/Documentation/i2c/sysfs-interface rename to trunk/Documentation/hwmon/sysfs-interface diff --git a/trunk/Documentation/i2c/userspace-tools b/trunk/Documentation/hwmon/userspace-tools similarity index 100% rename from trunk/Documentation/i2c/userspace-tools rename to trunk/Documentation/hwmon/userspace-tools diff --git a/trunk/Documentation/i2c/chips/via686a b/trunk/Documentation/hwmon/via686a similarity index 100% rename from trunk/Documentation/i2c/chips/via686a rename to trunk/Documentation/hwmon/via686a diff --git a/trunk/Documentation/i2c/chips/w83627hf b/trunk/Documentation/hwmon/w83627hf similarity index 100% rename from trunk/Documentation/i2c/chips/w83627hf rename to trunk/Documentation/hwmon/w83627hf diff --git a/trunk/Documentation/i2c/chips/w83781d b/trunk/Documentation/hwmon/w83781d similarity index 100% rename from trunk/Documentation/i2c/chips/w83781d rename to trunk/Documentation/hwmon/w83781d diff --git a/trunk/Documentation/hwmon/w83792d b/trunk/Documentation/hwmon/w83792d new file mode 100644 index 000000000000..8171c285bb55 --- /dev/null +++ b/trunk/Documentation/hwmon/w83792d @@ -0,0 +1,174 @@ +Kernel driver w83792d +===================== + +Supported chips: + * Winbond W83792D + Prefix: 'w83792d' + Addresses scanned: I2C 0x2c - 0x2f + Datasheet: http://www.winbond.com.tw/E-WINBONDHTM/partner/PDFresult.asp?Pname=1035 + +Author: Chunhao Huang +Contact: DZShen + + +Module Parameters +----------------- + +* init int + (default 1) + Use 'init=0' to bypass initializing the chip. + Try this if your computer crashes when you load the module. + +* force_subclients=bus,caddr,saddr,saddr + This is used to force the i2c addresses for subclients of + a certain chip. Example usage is `force_subclients=0,0x2f,0x4a,0x4b' + to force the subclients of chip 0x2f on bus 0 to i2c addresses + 0x4a and 0x4b. + + +Description +----------- + +This driver implements support for the Winbond W83792AD/D. + +Detection of the chip can sometimes be foiled because it can be in an +internal state that allows no clean access (Bank with ID register is not +currently selected). If you know the address of the chip, use a 'force' +parameter; this will put it into a more well-behaved state first. + +The driver implements three temperature sensors, seven fan rotation speed +sensors, nine voltage sensors, and two automatic fan regulation +strategies called: Smart Fan I (Thermal Cruise mode) and Smart Fan II. +Automatic fan control mode is possible only for fan1-fan3. Fan4-fan7 can run +synchronized with selected fan (fan1-fan3). This functionality and manual PWM +control for fan4-fan7 is not yet implemented. + +Temperatures are measured in degrees Celsius and measurement resolution is 1 +degC for temp1 and 0.5 degC for temp2 and temp3. An alarm is triggered when +the temperature gets higher than the Overtemperature Shutdown value; it stays +on until the temperature falls below the Hysteresis value. + +Fan rotation speeds are reported in RPM (rotations per minute). An alarm is +triggered if the rotation speed has dropped below a programmable limit. Fan +readings can be divided by a programmable divider (1, 2, 4, 8, 16, 32, 64 or +128) to give the readings more range or accuracy. + +Voltage sensors (also known as IN sensors) report their values in millivolts. +An alarm is triggered if the voltage has crossed a programmable minimum +or maximum limit. + +Alarms are provided as output from "realtime status register". Following bits +are defined: + +bit - alarm on: +0 - in0 +1 - in1 +2 - temp1 +3 - temp2 +4 - temp3 +5 - fan1 +6 - fan2 +7 - fan3 +8 - in2 +9 - in3 +10 - in4 +11 - in5 +12 - in6 +13 - VID change +14 - chassis +15 - fan7 +16 - tart1 +17 - tart2 +18 - tart3 +19 - in7 +20 - in8 +21 - fan4 +22 - fan5 +23 - fan6 + +Tart will be asserted while target temperature cannot be achieved after 3 minutes +of full speed rotation of corresponding fan. + +In addition to the alarms described above, there is a CHAS alarm on the chips +which triggers if your computer case is open (This one is latched, contrary +to realtime alarms). + +The chips only update values each 3 seconds; reading them more often will +do no harm, but will return 'old' values. + + +W83792D PROBLEMS +---------------- +Known problems: + - This driver is only for Winbond W83792D C version device, there + are also some motherboards with B version W83792D device. The + calculation method to in6-in7(measured value, limits) is a little + different between C and B version. C or B version can be identified + by CR[0x49h]. + - The function of vid and vrm has not been finished, because I'm NOT + very familiar with them. Adding support is welcome. +  - The function of chassis open detection needs more tests. + - If you have ASUS server board and chip was not found: Then you will + need to upgrade to latest (or beta) BIOS. If it does not help please + contact us. + +Fan control +----------- + +Manual mode +----------- + +Works as expected. You just need to specify desired PWM/DC value (fan speed) +in appropriate pwm# file. + +Thermal cruise +-------------- + +In this mode, W83792D provides the Smart Fan system to automatically control +fan speed to keep the temperatures of CPU and the system within specific +range. At first a wanted temperature and interval must be set. This is done +via thermal_cruise# file. The tolerance# file serves to create T +- tolerance +interval. The fan speed will be lowered as long as the current temperature +remains below the thermal_cruise# +- tolerance# value. Once the temperature +exceeds the high limit (T+tolerance), the fan will be turned on with a +specific speed set by pwm# and automatically controlled its PWM duty cycle +with the temperature varying. Three conditions may occur: + +(1) If the temperature still exceeds the high limit, PWM duty +cycle will increase slowly. + +(2) If the temperature goes below the high limit, but still above the low +limit (T-tolerance), the fan speed will be fixed at the current speed because +the temperature is in the target range. + +(3) If the temperature goes below the low limit, PWM duty cycle will decrease +slowly to 0 or a preset stop value until the temperature exceeds the low +limit. (The preset stop value handling is not yet implemented in driver) + +Smart Fan II +------------ + +W83792D also provides a special mode for fan. Four temperature points are +available. When related temperature sensors detects the temperature in preset +temperature region (sf2_point@_fan# +- tolerance#) it will cause fans to run +on programmed value from sf2_level@_fan#. You need to set four temperatures +for each fan. + + +/sys files +---------- + +pwm[1-3] - this file stores PWM duty cycle or DC value (fan speed) in range: + 0 (stop) to 255 (full) +pwm[1-3]_enable - this file controls mode of fan/temperature control: + * 0 Disabled + * 1 Manual mode + * 2 Smart Fan II + * 3 Thermal Cruise +pwm[1-3]_mode - Select PWM of DC mode + * 0 DC + * 1 PWM +thermal_cruise[1-3] - Selects the desired temperature for cruise (degC) +tolerance[1-3] - Value in degrees of Celsius (degC) for +- T +sf2_point[1-4]_fan[1-3] - four temperature points for each fan for Smart Fan II +sf2_level[1-3]_fan[1-3] - three PWM/DC levels for each fan for Smart Fan II diff --git a/trunk/Documentation/i2c/chips/w83l785ts b/trunk/Documentation/hwmon/w83l785ts similarity index 100% rename from trunk/Documentation/i2c/chips/w83l785ts rename to trunk/Documentation/hwmon/w83l785ts diff --git a/trunk/Documentation/i2c/chips/max6875 b/trunk/Documentation/i2c/chips/max6875 index b4fb49b41813..96fec562a8e9 100644 --- a/trunk/Documentation/i2c/chips/max6875 +++ b/trunk/Documentation/i2c/chips/max6875 @@ -2,53 +2,107 @@ Kernel driver max6875 ===================== Supported chips: - * Maxim max6874, max6875 - Prefixes: 'max6875' - Addresses scanned: 0x50, 0x52 - Datasheets: + * Maxim MAX6874, MAX6875 + Prefix: 'max6875' + Addresses scanned: None (see below) + Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6874-MAX6875.pdf Author: Ben Gardner -Module Parameters ------------------ - -* allow_write int - Set to non-zero to enable write permission: - *0: Read only - 1: Read and write - - Description ----------- -The MAXIM max6875 is a EEPROM-programmable power-supply sequencer/supervisor. +The Maxim MAX6875 is an EEPROM-programmable power-supply sequencer/supervisor. It provides timed outputs that can be used as a watchdog, if properly wired. It also provides 512 bytes of user EEPROM. -At reset, the max6875 reads the configuration eeprom into its configuration +At reset, the MAX6875 reads the configuration EEPROM into its configuration registers. The chip then begins to operate according to the values in the registers. -See the datasheet for details on how to program the EEPROM. +The Maxim MAX6874 is a similar, mostly compatible device, with more intputs +and outputs: + vin gpi vout +MAX6874 6 4 8 +MAX6875 4 3 5 + +See the datasheet for more information. Sysfs entries ------------- -eeprom_user - 512 bytes of user-defined EEPROM space. Only writable if - allow_write was set and register 0x43 is 0. - -eeprom_config - 70 bytes of config EEPROM. Note that changes will not get - loaded into register space until a power cycle or device reset. - -reg_config - 70 bytes of register space. Any changes take affect immediately. +eeprom - 512 bytes of user-defined EEPROM space. General Remarks --------------- -A typical application will require that the EEPROMs be programmed once and -never altered afterwards. +Valid addresses for the MAX6875 are 0x50 and 0x52. +Valid addresses for the MAX6874 are 0x50, 0x52, 0x54 and 0x56. +The driver does not probe any address, so you must force the address. + +Example: +$ modprobe max6875 force=0,0x50 + +The MAX6874/MAX6875 ignores address bit 0, so this driver attaches to multiple +addresses. For example, for address 0x50, it also reserves 0x51. +The even-address instance is called 'max6875', the odd one is 'max6875 subclient'. + + +Programming the chip using i2c-dev +---------------------------------- + +Use the i2c-dev interface to access and program the chips. +Reads and writes are performed differently depending on the address range. + +The configuration registers are at addresses 0x00 - 0x45. +Use i2c_smbus_write_byte_data() to write a register and +i2c_smbus_read_byte_data() to read a register. +The command is the register number. + +Examples: +To write a 1 to register 0x45: + i2c_smbus_write_byte_data(fd, 0x45, 1); + +To read register 0x45: + value = i2c_smbus_read_byte_data(fd, 0x45); + + +The configuration EEPROM is at addresses 0x8000 - 0x8045. +The user EEPROM is at addresses 0x8100 - 0x82ff. + +Use i2c_smbus_write_word_data() to write a byte to EEPROM. + +The command is the upper byte of the address: 0x80, 0x81, or 0x82. +The data word is the lower part of the address or'd with data << 8. + cmd = address >> 8; + val = (address & 0xff) | (data << 8); + +Example: +To write 0x5a to address 0x8003: + i2c_smbus_write_word_data(fd, 0x80, 0x5a03); + + +Reading data from the EEPROM is a little more complicated. +Use i2c_smbus_write_byte_data() to set the read address and then +i2c_smbus_read_byte() or i2c_smbus_read_i2c_block_data() to read the data. + +Example: +To read data starting at offset 0x8100, first set the address: + i2c_smbus_write_byte_data(fd, 0x81, 0x00); + +And then read the data + value = i2c_smbus_read_byte(fd); + + or + + count = i2c_smbus_read_i2c_block_data(fd, 0x84, buffer); + +The block read should read 16 bytes. +0x84 is the block read command. + +See the datasheet for more details. diff --git a/trunk/Documentation/i2c/dev-interface b/trunk/Documentation/i2c/dev-interface index 09d6cda2a1fb..b849ad636583 100644 --- a/trunk/Documentation/i2c/dev-interface +++ b/trunk/Documentation/i2c/dev-interface @@ -14,9 +14,12 @@ C example ========= So let's say you want to access an i2c adapter from a C program. The -first thing to do is `#include " and "#include . -Yes, I know, you should never include kernel header files, but until glibc -knows about i2c, there is not much choice. +first thing to do is "#include ". Please note that +there are two files named "i2c-dev.h" out there, one is distributed +with the Linux kernel and is meant to be included from kernel +driver code, the other one is distributed with lm_sensors and is +meant to be included from user-space programs. You obviously want +the second one here. Now, you have to decide which adapter you want to access. You should inspect /sys/class/i2c-dev/ to decide this. Adapter numbers are assigned @@ -78,7 +81,7 @@ Full interface description ========================== The following IOCTLs are defined and fully supported -(see also i2c-dev.h and i2c.h): +(see also i2c-dev.h): ioctl(file,I2C_SLAVE,long addr) Change slave address. The address is passed in the 7 lower bits of the @@ -97,10 +100,10 @@ ioctl(file,I2C_PEC,long select) ioctl(file,I2C_FUNCS,unsigned long *funcs) Gets the adapter functionality and puts it in *funcs. -ioctl(file,I2C_RDWR,struct i2c_ioctl_rdwr_data *msgset) +ioctl(file,I2C_RDWR,struct i2c_rdwr_ioctl_data *msgset) Do combined read/write transaction without stop in between. - The argument is a pointer to a struct i2c_ioctl_rdwr_data { + The argument is a pointer to a struct i2c_rdwr_ioctl_data { struct i2c_msg *msgs; /* ptr to array of simple messages */ int nmsgs; /* number of messages to exchange */ diff --git a/trunk/Documentation/i2c/functionality b/trunk/Documentation/i2c/functionality index 8a78a95ae04e..41ffefbdc60c 100644 --- a/trunk/Documentation/i2c/functionality +++ b/trunk/Documentation/i2c/functionality @@ -115,7 +115,7 @@ CHECKING THROUGH /DEV If you try to access an adapter from a userspace program, you will have to use the /dev interface. You will still have to check whether the functionality you need is supported, of course. This is done using -the I2C_FUNCS ioctl. An example, adapted from the lm_sensors i2c_detect +the I2C_FUNCS ioctl. An example, adapted from the lm_sensors i2cdetect program, is below: int file; diff --git a/trunk/Documentation/i2c/porting-clients b/trunk/Documentation/i2c/porting-clients index a7adbdd9ea8a..4849dfd6961c 100644 --- a/trunk/Documentation/i2c/porting-clients +++ b/trunk/Documentation/i2c/porting-clients @@ -1,4 +1,4 @@ -Revision 4, 2004-03-30 +Revision 5, 2005-07-29 Jean Delvare Greg KH @@ -17,20 +17,22 @@ yours for best results. Technical changes: -* [Includes] Get rid of "version.h". Replace with - . Includes typically look like that: +* [Includes] Get rid of "version.h" and . + Includes typically look like that: #include #include #include #include - #include - #include /* if you need VRM support */ + #include /* for hardware monitoring drivers */ + #include + #include /* if you need VRM support */ #include /* if you have I/O operations */ Please respect this inclusion order. Some extra headers may be required for a given driver (e.g. "lm75.h"). -* [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, SENSORS_ISA_END - becomes I2C_CLIENT_ISA_END. +* [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, ISA addresses + are no more handled by the i2c core. + SENSORS_INSMOD_ becomes I2C_CLIENT_INSMOD_. * [Client data] Get rid of sysctl_id. Try using standard names for register values (for example, temp_os becomes temp_max). You're @@ -66,13 +68,15 @@ Technical changes: if (!(adapter->class & I2C_CLASS_HWMON)) return 0; ISA-only drivers of course don't need this. + Call i2c_probe() instead of i2c_detect(). * [Detect] As mentioned earlier, the flags parameter is gone. The type_name and client_name strings are replaced by a single name string, which will be filled with a lowercase, short string (typically the driver name, e.g. "lm75"). In i2c-only drivers, drop the i2c_is_isa_adapter check, it's - useless. + useless. Same for isa-only drivers, as the test would always be + true. Only hybrid drivers (which are quite rare) still need it. The errorN labels are reduced to the number needed. If that number is 2 (i2c-only drivers), it is advised that the labels are named exit and exit_free. For i2c+isa drivers, labels should be named @@ -86,6 +90,8 @@ Technical changes: device_create_file. Move the driver initialization before any sysfs file creation. Drop client->id. + Drop any 24RF08 corruption prevention you find, as this is now done + at the i2c-core level, and doing it twice voids it. * [Init] Limits must not be set by the driver (can be done later in user-space). Chip should not be reset default (although a module @@ -93,7 +99,8 @@ Technical changes: limited to the strictly necessary steps. * [Detach] Get rid of data, remove the call to - i2c_deregister_entry. + i2c_deregister_entry. Do not log an error message if + i2c_detach_client fails, as i2c-core will now do it for you. * [Update] Don't access client->data directly, use i2c_get_clientdata(client) instead. diff --git a/trunk/Documentation/i2c/writing-clients b/trunk/Documentation/i2c/writing-clients index f482dae81de3..077275722a7c 100644 --- a/trunk/Documentation/i2c/writing-clients +++ b/trunk/Documentation/i2c/writing-clients @@ -27,7 +27,6 @@ address. static struct i2c_driver foo_driver = { .owner = THIS_MODULE, .name = "Foo version 2.3 driver", - .id = I2C_DRIVERID_FOO, /* from i2c-id.h, optional */ .flags = I2C_DF_NOTIFY, .attach_adapter = &foo_attach_adapter, .detach_client = &foo_detach_client, @@ -37,12 +36,6 @@ static struct i2c_driver foo_driver = { The name can be chosen freely, and may be upto 40 characters long. Please use something descriptive here. -If used, the id should be a unique ID. The range 0xf000 to 0xffff is -reserved for local use, and you can use one of those until you start -distributing the driver, at which time you should contact the i2c authors -to get your own ID(s). Note that most of the time you don't need an ID -at all so you can just omit it. - Don't worry about the flags field; just put I2C_DF_NOTIFY into it. This means that your driver will be notified when new adapters are found. This is almost always what you want. @@ -155,15 +148,15 @@ are defined in i2c.h to help you support them, as well as a generic detection algorithm. You do not have to use this parameter interface; but don't try to use -function i2c_probe() (or i2c_detect()) if you don't. +function i2c_probe() if you don't. NOTE: If you want to write a `sensors' driver, the interface is slightly different! See below. -Probing classes (i2c) ---------------------- +Probing classes +--------------- All parameters are given as lists of unsigned 16-bit integers. Lists are terminated by I2C_CLIENT_END. @@ -178,12 +171,18 @@ The following lists are used internally: ignore: insmod parameter. A list of pairs. The first value is a bus number (-1 for any I2C bus), the second is the I2C address. These addresses are never probed. - This parameter overrules 'normal' and 'probe', but not the 'force' lists. + This parameter overrules the 'normal_i2c' list only. force: insmod parameter. A list of pairs. The first value is a bus number (-1 for any I2C bus), the second is the I2C address. A device is blindly assumed to be on the given address, no probing is done. +Additionally, kind-specific force lists may optionally be defined if +the driver supports several chip kinds. They are grouped in a +NULL-terminated list of pointers named forces, those first element if the +generic force list mentioned above. Each additional list correspond to an +insmod parameter of the form force_. + Fortunately, as a module writer, you just have to define the `normal_i2c' parameter. The complete declaration could look like this: @@ -193,66 +192,17 @@ parameter. The complete declaration could look like this: /* Magic definition of all other variables and things */ I2C_CLIENT_INSMOD; + /* Or, if your driver supports, say, 2 kind of devices: */ + I2C_CLIENT_INSMOD_2(foo, bar); + +If you use the multi-kind form, an enum will be defined for you: + enum chips { any_chip, foo, bar, ... } +You can then (and certainly should) use it in the driver code. Note that you *have* to call the defined variable `normal_i2c', without any prefix! -Probing classes (sensors) -------------------------- - -If you write a `sensors' driver, you use a slightly different interface. -As well as I2C addresses, we have to cope with ISA addresses. Also, we -use a enum of chip types. Don't forget to include `sensors.h'. - -The following lists are used internally. They are all lists of integers. - - normal_i2c: filled in by the module writer. Terminated by SENSORS_I2C_END. - A list of I2C addresses which should normally be examined. - normal_isa: filled in by the module writer. Terminated by SENSORS_ISA_END. - A list of ISA addresses which should normally be examined. - probe: insmod parameter. Initialize this list with SENSORS_I2C_END values. - A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for - the ISA bus, -1 for any I2C bus), the second is the address. These - addresses are also probed, as if they were in the 'normal' list. - ignore: insmod parameter. Initialize this list with SENSORS_I2C_END values. - A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for - the ISA bus, -1 for any I2C bus), the second is the I2C address. These - addresses are never probed. This parameter overrules 'normal' and - 'probe', but not the 'force' lists. - -Also used is a list of pointers to sensors_force_data structures: - force_data: insmod parameters. A list, ending with an element of which - the force field is NULL. - Each element contains the type of chip and a list of pairs. - The first value is a bus number (SENSORS_ISA_BUS for the ISA bus, - -1 for any I2C bus), the second is the address. - These are automatically translated to insmod variables of the form - force_foo. - -So we have a generic insmod variabled `force', and chip-specific variables -`force_CHIPNAME'. - -Fortunately, as a module writer, you just have to define the `normal_i2c' -and `normal_isa' parameters, and define what chip names are used. -The complete declaration could look like this: - /* Scan i2c addresses 0x37, and 0x48 to 0x4f */ - static unsigned short normal_i2c[] = { 0x37, 0x48, 0x49, 0x4a, 0x4b, 0x4c, - 0x4d, 0x4e, 0x4f, I2C_CLIENT_END }; - /* Scan ISA address 0x290 */ - static unsigned int normal_isa[] = {0x0290,SENSORS_ISA_END}; - - /* Define chips foo and bar, as well as all module parameters and things */ - SENSORS_INSMOD_2(foo,bar); - -If you have one chip, you use macro SENSORS_INSMOD_1(chip), if you have 2 -you use macro SENSORS_INSMOD_2(chip1,chip2), etc. If you do not want to -bother with chip types, you can use SENSORS_INSMOD_0. - -A enum is automatically defined as follows: - enum chips { any_chip, chip1, chip2, ... } - - Attaching to an adapter ----------------------- @@ -271,17 +221,10 @@ detected at a specific address, another callback is called. return i2c_probe(adapter,&addr_data,&foo_detect_client); } -For `sensors' drivers, use the i2c_detect function instead: - - int foo_attach_adapter(struct i2c_adapter *adapter) - { - return i2c_detect(adapter,&addr_data,&foo_detect_client); - } - Remember, structure `addr_data' is defined by the macros explained above, so you do not have to define it yourself. -The i2c_probe or i2c_detect function will call the foo_detect_client +The i2c_probe function will call the foo_detect_client function only for those i2c addresses that actually have a device on them (unless a `force' parameter was used). In addition, addresses that are already in use (by some other registered client) are skipped. @@ -290,19 +233,18 @@ are already in use (by some other registered client) are skipped. The detect client function -------------------------- -The detect client function is called by i2c_probe or i2c_detect. -The `kind' parameter contains 0 if this call is due to a `force' -parameter, and -1 otherwise (for i2c_detect, it contains 0 if -this call is due to the generic `force' parameter, and the chip type -number if it is due to a specific `force' parameter). +The detect client function is called by i2c_probe. The `kind' parameter +contains -1 for a probed detection, 0 for a forced detection, or a positive +number for a forced detection with a chip type forced. Below, some things are only needed if this is a `sensors' driver. Those parts are between /* SENSORS ONLY START */ and /* SENSORS ONLY END */ markers. -This function should only return an error (any value != 0) if there is -some reason why no more detection should be done anymore. If the -detection just fails for this address, return 0. +Returning an error different from -ENODEV in a detect function will cause +the detection to stop: other addresses and adapters won't be scanned. +This should only be done on fatal or internal errors, such as a memory +shortage or i2c_attach_client failing. For now, you can ignore the `flags' parameter. It is there for future use. @@ -327,11 +269,10 @@ For now, you can ignore the `flags' parameter. It is there for future use. const char *type_name = ""; int is_isa = i2c_is_isa_adapter(adapter); - if (is_isa) { + /* Do this only if the chip can additionally be found on the ISA bus + (hybrid chip). */ - /* If this client can't be on the ISA bus at all, we can stop now - (call `goto ERROR0'). But for kicks, we will assume it is all - right. */ + if (is_isa) { /* Discard immediately if this ISA range is already used */ if (check_region(address,FOO_EXTENT)) @@ -502,15 +443,13 @@ much simpler than the attachment code, fortunately! /* SENSORS ONLY END */ /* Try to detach the client from i2c space */ - if ((err = i2c_detach_client(client))) { - printk("foo.o: Client deregistration failed, client not detached.\n"); + if ((err = i2c_detach_client(client))) return err; - } - /* SENSORS ONLY START */ + /* HYBRID SENSORS CHIP ONLY START */ if i2c_is_isa_client(client) release_region(client->addr,LM78_EXTENT); - /* SENSORS ONLY END */ + /* HYBRID SENSORS CHIP ONLY END */ kfree(client); /* Frees client data too, if allocated at the same time */ return 0; diff --git a/trunk/Documentation/infiniband/core_locking.txt b/trunk/Documentation/infiniband/core_locking.txt new file mode 100644 index 000000000000..e1678542279a --- /dev/null +++ b/trunk/Documentation/infiniband/core_locking.txt @@ -0,0 +1,114 @@ +INFINIBAND MIDLAYER LOCKING + + This guide is an attempt to make explicit the locking assumptions + made by the InfiniBand midlayer. It describes the requirements on + both low-level drivers that sit below the midlayer and upper level + protocols that use the midlayer. + +Sleeping and interrupt context + + With the following exceptions, a low-level driver implementation of + all of the methods in struct ib_device may sleep. The exceptions + are any methods from the list: + + create_ah + modify_ah + query_ah + destroy_ah + bind_mw + post_send + post_recv + poll_cq + req_notify_cq + map_phys_fmr + + which may not sleep and must be callable from any context. + + The corresponding functions exported to upper level protocol + consumers: + + ib_create_ah + ib_modify_ah + ib_query_ah + ib_destroy_ah + ib_bind_mw + ib_post_send + ib_post_recv + ib_req_notify_cq + ib_map_phys_fmr + + are therefore safe to call from any context. + + In addition, the function + + ib_dispatch_event + + used by low-level drivers to dispatch asynchronous events through + the midlayer is also safe to call from any context. + +Reentrancy + + All of the methods in struct ib_device exported by a low-level + driver must be fully reentrant. The low-level driver is required to + perform all synchronization necessary to maintain consistency, even + if multiple function calls using the same object are run + simultaneously. + + The IB midlayer does not perform any serialization of function calls. + + Because low-level drivers are reentrant, upper level protocol + consumers are not required to perform any serialization. However, + some serialization may be required to get sensible results. For + example, a consumer may safely call ib_poll_cq() on multiple CPUs + simultaneously. However, the ordering of the work completion + information between different calls of ib_poll_cq() is not defined. + +Callbacks + + A low-level driver must not perform a callback directly from the + same callchain as an ib_device method call. For example, it is not + allowed for a low-level driver to call a consumer's completion event + handler directly from its post_send method. Instead, the low-level + driver should defer this callback by, for example, scheduling a + tasklet to perform the callback. + + The low-level driver is responsible for ensuring that multiple + completion event handlers for the same CQ are not called + simultaneously. The driver must guarantee that only one CQ event + handler for a given CQ is running at a time. In other words, the + following situation is not allowed: + + CPU1 CPU2 + + low-level driver -> + consumer CQ event callback: + /* ... */ + ib_req_notify_cq(cq, ...); + low-level driver -> + /* ... */ consumer CQ event callback: + /* ... */ + return from CQ event handler + + The context in which completion event and asynchronous event + callbacks run is not defined. Depending on the low-level driver, it + may be process context, softirq context, or interrupt context. + Upper level protocol consumers may not sleep in a callback. + +Hot-plug + + A low-level driver announces that a device is ready for use by + consumers when it calls ib_register_device(), all initialization + must be complete before this call. The device must remain usable + until the driver's call to ib_unregister_device() has returned. + + A low-level driver must call ib_register_device() and + ib_unregister_device() from process context. It must not hold any + semaphores that could cause deadlock if a consumer calls back into + the driver across these calls. + + An upper level protocol consumer may begin using an IB device as + soon as the add method of its struct ib_client is called for that + device. A consumer must finish all cleanup and free all resources + relating to a device before returning from the remove method. + + A consumer is permitted to sleep in its add and remove methods. diff --git a/trunk/Documentation/infiniband/user_mad.txt b/trunk/Documentation/infiniband/user_mad.txt index cae0c83f1ee9..750fe5e80ebc 100644 --- a/trunk/Documentation/infiniband/user_mad.txt +++ b/trunk/Documentation/infiniband/user_mad.txt @@ -28,13 +28,37 @@ Creating MAD agents Receiving MADs - MADs are received using read(). The buffer passed to read() must be - large enough to hold at least one struct ib_user_mad. For example: - - struct ib_user_mad mad; - ret = read(fd, &mad, sizeof mad); - if (ret != sizeof mad) + MADs are received using read(). The receive side now supports + RMPP. The buffer passed to read() must be at least one + struct ib_user_mad + 256 bytes. For example: + + If the buffer passed is not large enough to hold the received + MAD (RMPP), the errno is set to ENOSPC and the length of the + buffer needed is set in mad.length. + + Example for normal MAD (non RMPP) reads: + struct ib_user_mad *mad; + mad = malloc(sizeof *mad + 256); + ret = read(fd, mad, sizeof *mad + 256); + if (ret != sizeof mad + 256) { + perror("read"); + free(mad); + } + + Example for RMPP reads: + struct ib_user_mad *mad; + mad = malloc(sizeof *mad + 256); + ret = read(fd, mad, sizeof *mad + 256); + if (ret == -ENOSPC)) { + length = mad.length; + free(mad); + mad = malloc(sizeof *mad + length); + ret = read(fd, mad, sizeof *mad + length); + } + if (ret < 0) { perror("read"); + free(mad); + } In addition to the actual MAD contents, the other struct ib_user_mad fields will be filled in with information on the received MAD. For @@ -50,18 +74,21 @@ Sending MADs MADs are sent using write(). The agent ID for sending should be filled into the id field of the MAD, the destination LID should be - filled into the lid field, and so on. For example: + filled into the lid field, and so on. The send side does support + RMPP so arbitrary length MAD can be sent. For example: + + struct ib_user_mad *mad; - struct ib_user_mad mad; + mad = malloc(sizeof *mad + mad_length); - /* fill in mad.data */ + /* fill in mad->data */ - mad.id = my_agent; /* req.id from agent registration */ - mad.lid = my_dest; /* in network byte order... */ + mad->hdr.id = my_agent; /* req.id from agent registration */ + mad->hdr.lid = my_dest; /* in network byte order... */ /* etc. */ - ret = write(fd, &mad, sizeof mad); - if (ret != sizeof mad) + ret = write(fd, &mad, sizeof *mad + mad_length); + if (ret != sizeof *mad + mad_length) perror("write"); Setting IsSM Capability Bit diff --git a/trunk/Documentation/kernel-parameters.txt b/trunk/Documentation/kernel-parameters.txt index 753db6d8b745..3d5cd7a09b2f 100644 --- a/trunk/Documentation/kernel-parameters.txt +++ b/trunk/Documentation/kernel-parameters.txt @@ -37,7 +37,7 @@ restrictions referred to are that the relevant option is valid if: IA-32 IA-32 aka i386 architecture is enabled. IA-64 IA-64 architecture is enabled. IOSCHED More than one I/O scheduler is enabled. - IP_PNP IP DCHP, BOOTP, or RARP is enabled. + IP_PNP IP DHCP, BOOTP, or RARP is enabled. ISAPNP ISA PnP code is enabled. ISDN Appropriate ISDN support is enabled. JOY Appropriate joystick support is enabled. @@ -159,6 +159,11 @@ running once the system is up. acpi_fake_ecdt [HW,ACPI] Workaround failure due to BIOS lacking ECDT + acpi_generic_hotkey [HW,ACPI] + Allow consolidated generic hotkey driver to + over-ride platform specific driver. + See also Documentation/acpi-hotkey.txt. + ad1816= [HW,OSS] Format: ,,, See also Documentation/sound/oss/AD1816. diff --git a/trunk/Documentation/kprobes.txt b/trunk/Documentation/kprobes.txt new file mode 100644 index 000000000000..0541fe1de704 --- /dev/null +++ b/trunk/Documentation/kprobes.txt @@ -0,0 +1,588 @@ +Title : Kernel Probes (Kprobes) +Authors : Jim Keniston + : Prasanna S Panchamukhi + +CONTENTS + +1. Concepts: Kprobes, Jprobes, Return Probes +2. Architectures Supported +3. Configuring Kprobes +4. API Reference +5. Kprobes Features and Limitations +6. Probe Overhead +7. TODO +8. Kprobes Example +9. Jprobes Example +10. Kretprobes Example + +1. Concepts: Kprobes, Jprobes, Return Probes + +Kprobes enables you to dynamically break into any kernel routine and +collect debugging and performance information non-disruptively. You +can trap at almost any kernel code address, specifying a handler +routine to be invoked when the breakpoint is hit. + +There are currently three types of probes: kprobes, jprobes, and +kretprobes (also called return probes). A kprobe can be inserted +on virtually any instruction in the kernel. A jprobe is inserted at +the entry to a kernel function, and provides convenient access to the +function's arguments. A return probe fires when a specified function +returns. + +In the typical case, Kprobes-based instrumentation is packaged as +a kernel module. The module's init function installs ("registers") +one or more probes, and the exit function unregisters them. A +registration function such as register_kprobe() specifies where +the probe is to be inserted and what handler is to be called when +the probe is hit. + +The next three subsections explain how the different types of +probes work. They explain certain things that you'll need to +know in order to make the best use of Kprobes -- e.g., the +difference between a pre_handler and a post_handler, and how +to use the maxactive and nmissed fields of a kretprobe. But +if you're in a hurry to start using Kprobes, you can skip ahead +to section 2. + +1.1 How Does a Kprobe Work? + +When a kprobe is registered, Kprobes makes a copy of the probed +instruction and replaces the first byte(s) of the probed instruction +with a breakpoint instruction (e.g., int3 on i386 and x86_64). + +When a CPU hits the breakpoint instruction, a trap occurs, the CPU's +registers are saved, and control passes to Kprobes via the +notifier_call_chain mechanism. Kprobes executes the "pre_handler" +associated with the kprobe, passing the handler the addresses of the +kprobe struct and the saved registers. + +Next, Kprobes single-steps its copy of the probed instruction. +(It would be simpler to single-step the actual instruction in place, +but then Kprobes would have to temporarily remove the breakpoint +instruction. This would open a small time window when another CPU +could sail right past the probepoint.) + +After the instruction is single-stepped, Kprobes executes the +"post_handler," if any, that is associated with the kprobe. +Execution then continues with the instruction following the probepoint. + +1.2 How Does a Jprobe Work? + +A jprobe is implemented using a kprobe that is placed on a function's +entry point. It employs a simple mirroring principle to allow +seamless access to the probed function's arguments. The jprobe +handler routine should have the same signature (arg list and return +type) as the function being probed, and must always end by calling +the Kprobes function jprobe_return(). + +Here's how it works. When the probe is hit, Kprobes makes a copy of +the saved registers and a generous portion of the stack (see below). +Kprobes then points the saved instruction pointer at the jprobe's +handler routine, and returns from the trap. As a result, control +passes to the handler, which is presented with the same register and +stack contents as the probed function. When it is done, the handler +calls jprobe_return(), which traps again to restore the original stack +contents and processor state and switch to the probed function. + +By convention, the callee owns its arguments, so gcc may produce code +that unexpectedly modifies that portion of the stack. This is why +Kprobes saves a copy of the stack and restores it after the jprobe +handler has run. Up to MAX_STACK_SIZE bytes are copied -- e.g., +64 bytes on i386. + +Note that the probed function's args may be passed on the stack +or in registers (e.g., for x86_64 or for an i386 fastcall function). +The jprobe will work in either case, so long as the handler's +prototype matches that of the probed function. + +1.3 How Does a Return Probe Work? + +When you call register_kretprobe(), Kprobes establishes a kprobe at +the entry to the function. When the probed function is called and this +probe is hit, Kprobes saves a copy of the return address, and replaces +the return address with the address of a "trampoline." The trampoline +is an arbitrary piece of code -- typically just a nop instruction. +At boot time, Kprobes registers a kprobe at the trampoline. + +When the probed function executes its return instruction, control +passes to the trampoline and that probe is hit. Kprobes' trampoline +handler calls the user-specified handler associated with the kretprobe, +then sets the saved instruction pointer to the saved return address, +and that's where execution resumes upon return from the trap. + +While the probed function is executing, its return address is +stored in an object of type kretprobe_instance. Before calling +register_kretprobe(), the user sets the maxactive field of the +kretprobe struct to specify how many instances of the specified +function can be probed simultaneously. register_kretprobe() +pre-allocates the indicated number of kretprobe_instance objects. + +For example, if the function is non-recursive and is called with a +spinlock held, maxactive = 1 should be enough. If the function is +non-recursive and can never relinquish the CPU (e.g., via a semaphore +or preemption), NR_CPUS should be enough. If maxactive <= 0, it is +set to a default value. If CONFIG_PREEMPT is enabled, the default +is max(10, 2*NR_CPUS). Otherwise, the default is NR_CPUS. + +It's not a disaster if you set maxactive too low; you'll just miss +some probes. In the kretprobe struct, the nmissed field is set to +zero when the return probe is registered, and is incremented every +time the probed function is entered but there is no kretprobe_instance +object available for establishing the return probe. + +2. Architectures Supported + +Kprobes, jprobes, and return probes are implemented on the following +architectures: + +- i386 +- x86_64 (AMD-64, E64MT) +- ppc64 +- ia64 (Support for probes on certain instruction types is still in progress.) +- sparc64 (Return probes not yet implemented.) + +3. Configuring Kprobes + +When configuring the kernel using make menuconfig/xconfig/oldconfig, +ensure that CONFIG_KPROBES is set to "y". Under "Kernel hacking", +look for "Kprobes". You may have to enable "Kernel debugging" +(CONFIG_DEBUG_KERNEL) before you can enable Kprobes. + +You may also want to ensure that CONFIG_KALLSYMS and perhaps even +CONFIG_KALLSYMS_ALL are set to "y", since kallsyms_lookup_name() +is a handy, version-independent way to find a function's address. + +If you need to insert a probe in the middle of a function, you may find +it useful to "Compile the kernel with debug info" (CONFIG_DEBUG_INFO), +so you can use "objdump -d -l vmlinux" to see the source-to-object +code mapping. + +4. API Reference + +The Kprobes API includes a "register" function and an "unregister" +function for each type of probe. Here are terse, mini-man-page +specifications for these functions and the associated probe handlers +that you'll write. See the latter half of this document for examples. + +4.1 register_kprobe + +#include +int register_kprobe(struct kprobe *kp); + +Sets a breakpoint at the address kp->addr. When the breakpoint is +hit, Kprobes calls kp->pre_handler. After the probed instruction +is single-stepped, Kprobe calls kp->post_handler. If a fault +occurs during execution of kp->pre_handler or kp->post_handler, +or during single-stepping of the probed instruction, Kprobes calls +kp->fault_handler. Any or all handlers can be NULL. + +register_kprobe() returns 0 on success, or a negative errno otherwise. + +User's pre-handler (kp->pre_handler): +#include +#include +int pre_handler(struct kprobe *p, struct pt_regs *regs); + +Called with p pointing to the kprobe associated with the breakpoint, +and regs pointing to the struct containing the registers saved when +the breakpoint was hit. Return 0 here unless you're a Kprobes geek. + +User's post-handler (kp->post_handler): +#include +#include +void post_handler(struct kprobe *p, struct pt_regs *regs, + unsigned long flags); + +p and regs are as described for the pre_handler. flags always seems +to be zero. + +User's fault-handler (kp->fault_handler): +#include +#include +int fault_handler(struct kprobe *p, struct pt_regs *regs, int trapnr); + +p and regs are as described for the pre_handler. trapnr is the +architecture-specific trap number associated with the fault (e.g., +on i386, 13 for a general protection fault or 14 for a page fault). +Returns 1 if it successfully handled the exception. + +4.2 register_jprobe + +#include +int register_jprobe(struct jprobe *jp) + +Sets a breakpoint at the address jp->kp.addr, which must be the address +of the first instruction of a function. When the breakpoint is hit, +Kprobes runs the handler whose address is jp->entry. + +The handler should have the same arg list and return type as the probed +function; and just before it returns, it must call jprobe_return(). +(The handler never actually returns, since jprobe_return() returns +control to Kprobes.) If the probed function is declared asmlinkage, +fastcall, or anything else that affects how args are passed, the +handler's declaration must match. + +register_jprobe() returns 0 on success, or a negative errno otherwise. + +4.3 register_kretprobe + +#include +int register_kretprobe(struct kretprobe *rp); + +Establishes a return probe for the function whose address is +rp->kp.addr. When that function returns, Kprobes calls rp->handler. +You must set rp->maxactive appropriately before you call +register_kretprobe(); see "How Does a Return Probe Work?" for details. + +register_kretprobe() returns 0 on success, or a negative errno +otherwise. + +User's return-probe handler (rp->handler): +#include +#include +int kretprobe_handler(struct kretprobe_instance *ri, struct pt_regs *regs); + +regs is as described for kprobe.pre_handler. ri points to the +kretprobe_instance object, of which the following fields may be +of interest: +- ret_addr: the return address +- rp: points to the corresponding kretprobe object +- task: points to the corresponding task struct +The handler's return value is currently ignored. + +4.4 unregister_*probe + +#include +void unregister_kprobe(struct kprobe *kp); +void unregister_jprobe(struct jprobe *jp); +void unregister_kretprobe(struct kretprobe *rp); + +Removes the specified probe. The unregister function can be called +at any time after the probe has been registered. + +5. Kprobes Features and Limitations + +As of Linux v2.6.12, Kprobes allows multiple probes at the same +address. Currently, however, there cannot be multiple jprobes on +the same function at the same time. + +In general, you can install a probe anywhere in the kernel. +In particular, you can probe interrupt handlers. Known exceptions +are discussed in this section. + +For obvious reasons, it's a bad idea to install a probe in +the code that implements Kprobes (mostly kernel/kprobes.c and +arch/*/kernel/kprobes.c). A patch in the v2.6.13 timeframe instructs +Kprobes to reject such requests. + +If you install a probe in an inline-able function, Kprobes makes +no attempt to chase down all inline instances of the function and +install probes there. gcc may inline a function without being asked, +so keep this in mind if you're not seeing the probe hits you expect. + +A probe handler can modify the environment of the probed function +-- e.g., by modifying kernel data structures, or by modifying the +contents of the pt_regs struct (which are restored to the registers +upon return from the breakpoint). So Kprobes can be used, for example, +to install a bug fix or to inject faults for testing. Kprobes, of +course, has no way to distinguish the deliberately injected faults +from the accidental ones. Don't drink and probe. + +Kprobes makes no attempt to prevent probe handlers from stepping on +each other -- e.g., probing printk() and then calling printk() from a +probe handler. As of Linux v2.6.12, if a probe handler hits a probe, +that second probe's handlers won't be run in that instance. + +In Linux v2.6.12 and previous versions, Kprobes' data structures are +protected by a single lock that is held during probe registration and +unregistration and while handlers are run. Thus, no two handlers +can run simultaneously. To improve scalability on SMP systems, +this restriction will probably be removed soon, in which case +multiple handlers (or multiple instances of the same handler) may +run concurrently on different CPUs. Code your handlers accordingly. + +Kprobes does not use semaphores or allocate memory except during +registration and unregistration. + +Probe handlers are run with preemption disabled. Depending on the +architecture, handlers may also run with interrupts disabled. In any +case, your handler should not yield the CPU (e.g., by attempting to +acquire a semaphore). + +Since a return probe is implemented by replacing the return +address with the trampoline's address, stack backtraces and calls +to __builtin_return_address() will typically yield the trampoline's +address instead of the real return address for kretprobed functions. +(As far as we can tell, __builtin_return_address() is used only +for instrumentation and error reporting.) + +If the number of times a function is called does not match the +number of times it returns, registering a return probe on that +function may produce undesirable results. We have the do_exit() +and do_execve() cases covered. do_fork() is not an issue. We're +unaware of other specific cases where this could be a problem. + +6. Probe Overhead + +On a typical CPU in use in 2005, a kprobe hit takes 0.5 to 1.0 +microseconds to process. Specifically, a benchmark that hits the same +probepoint repeatedly, firing a simple handler each time, reports 1-2 +million hits per second, depending on the architecture. A jprobe or +return-probe hit typically takes 50-75% longer than a kprobe hit. +When you have a return probe set on a function, adding a kprobe at +the entry to that function adds essentially no overhead. + +Here are sample overhead figures (in usec) for different architectures. +k = kprobe; j = jprobe; r = return probe; kr = kprobe + return probe +on same function; jr = jprobe + return probe on same function + +i386: Intel Pentium M, 1495 MHz, 2957.31 bogomips +k = 0.57 usec; j = 1.00; r = 0.92; kr = 0.99; jr = 1.40 + +x86_64: AMD Opteron 246, 1994 MHz, 3971.48 bogomips +k = 0.49 usec; j = 0.76; r = 0.80; kr = 0.82; jr = 1.07 + +ppc64: POWER5 (gr), 1656 MHz (SMT disabled, 1 virtual CPU per physical CPU) +k = 0.77 usec; j = 1.31; r = 1.26; kr = 1.45; jr = 1.99 + +7. TODO + +a. SystemTap (http://sourceware.org/systemtap): Work in progress +to provide a simplified programming interface for probe-based +instrumentation. +b. Improved SMP scalability: Currently, work is in progress to handle +multiple kprobes in parallel. +c. Kernel return probes for sparc64. +d. Support for other architectures. +e. User-space probes. + +8. Kprobes Example + +Here's a sample kernel module showing the use of kprobes to dump a +stack trace and selected i386 registers when do_fork() is called. +----- cut here ----- +/*kprobe_example.c*/ +#include +#include +#include +#include +#include + +/*For each probe you need to allocate a kprobe structure*/ +static struct kprobe kp; + +/*kprobe pre_handler: called just before the probed instruction is executed*/ +int handler_pre(struct kprobe *p, struct pt_regs *regs) +{ + printk("pre_handler: p->addr=0x%p, eip=%lx, eflags=0x%lx\n", + p->addr, regs->eip, regs->eflags); + dump_stack(); + return 0; +} + +/*kprobe post_handler: called after the probed instruction is executed*/ +void handler_post(struct kprobe *p, struct pt_regs *regs, unsigned long flags) +{ + printk("post_handler: p->addr=0x%p, eflags=0x%lx\n", + p->addr, regs->eflags); +} + +/* fault_handler: this is called if an exception is generated for any + * instruction within the pre- or post-handler, or when Kprobes + * single-steps the probed instruction. + */ +int handler_fault(struct kprobe *p, struct pt_regs *regs, int trapnr) +{ + printk("fault_handler: p->addr=0x%p, trap #%dn", + p->addr, trapnr); + /* Return 0 because we don't handle the fault. */ + return 0; +} + +int init_module(void) +{ + int ret; + kp.pre_handler = handler_pre; + kp.post_handler = handler_post; + kp.fault_handler = handler_fault; + kp.addr = (kprobe_opcode_t*) kallsyms_lookup_name("do_fork"); + /* register the kprobe now */ + if (!kp.addr) { + printk("Couldn't find %s to plant kprobe\n", "do_fork"); + return -1; + } + if ((ret = register_kprobe(&kp) < 0)) { + printk("register_kprobe failed, returned %d\n", ret); + return -1; + } + printk("kprobe registered\n"); + return 0; +} + +void cleanup_module(void) +{ + unregister_kprobe(&kp); + printk("kprobe unregistered\n"); +} + +MODULE_LICENSE("GPL"); +----- cut here ----- + +You can build the kernel module, kprobe-example.ko, using the following +Makefile: +----- cut here ----- +obj-m := kprobe-example.o +KDIR := /lib/modules/$(shell uname -r)/build +PWD := $(shell pwd) +default: + $(MAKE) -C $(KDIR) SUBDIRS=$(PWD) modules +clean: + rm -f *.mod.c *.ko *.o +----- cut here ----- + +$ make +$ su - +... +# insmod kprobe-example.ko + +You will see the trace data in /var/log/messages and on the console +whenever do_fork() is invoked to create a new process. + +9. Jprobes Example + +Here's a sample kernel module showing the use of jprobes to dump +the arguments of do_fork(). +----- cut here ----- +/*jprobe-example.c */ +#include +#include +#include +#include +#include +#include + +/* + * Jumper probe for do_fork. + * Mirror principle enables access to arguments of the probed routine + * from the probe handler. + */ + +/* Proxy routine having the same arguments as actual do_fork() routine */ +long jdo_fork(unsigned long clone_flags, unsigned long stack_start, + struct pt_regs *regs, unsigned long stack_size, + int __user * parent_tidptr, int __user * child_tidptr) +{ + printk("jprobe: clone_flags=0x%lx, stack_size=0x%lx, regs=0x%p\n", + clone_flags, stack_size, regs); + /* Always end with a call to jprobe_return(). */ + jprobe_return(); + /*NOTREACHED*/ + return 0; +} + +static struct jprobe my_jprobe = { + .entry = (kprobe_opcode_t *) jdo_fork +}; + +int init_module(void) +{ + int ret; + my_jprobe.kp.addr = (kprobe_opcode_t *) kallsyms_lookup_name("do_fork"); + if (!my_jprobe.kp.addr) { + printk("Couldn't find %s to plant jprobe\n", "do_fork"); + return -1; + } + + if ((ret = register_jprobe(&my_jprobe)) <0) { + printk("register_jprobe failed, returned %d\n", ret); + return -1; + } + printk("Planted jprobe at %p, handler addr %p\n", + my_jprobe.kp.addr, my_jprobe.entry); + return 0; +} + +void cleanup_module(void) +{ + unregister_jprobe(&my_jprobe); + printk("jprobe unregistered\n"); +} + +MODULE_LICENSE("GPL"); +----- cut here ----- + +Build and insert the kernel module as shown in the above kprobe +example. You will see the trace data in /var/log/messages and on +the console whenever do_fork() is invoked to create a new process. +(Some messages may be suppressed if syslogd is configured to +eliminate duplicate messages.) + +10. Kretprobes Example + +Here's a sample kernel module showing the use of return probes to +report failed calls to sys_open(). +----- cut here ----- +/*kretprobe-example.c*/ +#include +#include +#include +#include + +static const char *probed_func = "sys_open"; + +/* Return-probe handler: If the probed function fails, log the return value. */ +static int ret_handler(struct kretprobe_instance *ri, struct pt_regs *regs) +{ + // Substitute the appropriate register name for your architecture -- + // e.g., regs->rax for x86_64, regs->gpr[3] for ppc64. + int retval = (int) regs->eax; + if (retval < 0) { + printk("%s returns %d\n", probed_func, retval); + } + return 0; +} + +static struct kretprobe my_kretprobe = { + .handler = ret_handler, + /* Probe up to 20 instances concurrently. */ + .maxactive = 20 +}; + +int init_module(void) +{ + int ret; + my_kretprobe.kp.addr = + (kprobe_opcode_t *) kallsyms_lookup_name(probed_func); + if (!my_kretprobe.kp.addr) { + printk("Couldn't find %s to plant return probe\n", probed_func); + return -1; + } + if ((ret = register_kretprobe(&my_kretprobe)) < 0) { + printk("register_kretprobe failed, returned %d\n", ret); + return -1; + } + printk("Planted return probe at %p\n", my_kretprobe.kp.addr); + return 0; +} + +void cleanup_module(void) +{ + unregister_kretprobe(&my_kretprobe); + printk("kretprobe unregistered\n"); + /* nmissed > 0 suggests that maxactive was set too low. */ + printk("Missed probing %d instances of %s\n", + my_kretprobe.nmissed, probed_func); +} + +MODULE_LICENSE("GPL"); +----- cut here ----- + +Build and insert the kernel module as shown in the above kprobe +example. You will see the trace data in /var/log/messages and on the +console whenever sys_open() returns a negative value. (Some messages +may be suppressed if syslogd is configured to eliminate duplicate +messages.) + +For additional information on Kprobes, refer to the following URLs: +http://www-106.ibm.com/developerworks/library/l-kprobes.html?ca=dgr-lnxw42Kprobe +http://www.redhat.com/magazine/005mar05/features/kprobes/ diff --git a/trunk/Documentation/networking/README.ipw2100 b/trunk/Documentation/networking/README.ipw2100 new file mode 100644 index 000000000000..2046948b020d --- /dev/null +++ b/trunk/Documentation/networking/README.ipw2100 @@ -0,0 +1,246 @@ + +=========================== +Intel(R) PRO/Wireless 2100 Network Connection Driver for Linux +README.ipw2100 + +March 14, 2005 + +=========================== +Index +--------------------------- +0. Introduction +1. Release 1.1.0 Current Features +2. Command Line Parameters +3. Sysfs Helper Files +4. Radio Kill Switch +5. Dynamic Firmware +6. Power Management +7. Support +8. License + + +=========================== +0. Introduction +------------ ----- ----- ---- --- -- - + +This document provides a brief overview of the features supported by the +IPW2100 driver project. The main project website, where the latest +development version of the driver can be found, is: + + http://ipw2100.sourceforge.net + +There you can find the not only the latest releases, but also information about +potential fixes and patches, as well as links to the development mailing list +for the driver project. + + +=========================== +1. Release 1.1.0 Current Supported Features +--------------------------- +- Managed (BSS) and Ad-Hoc (IBSS) +- WEP (shared key and open) +- Wireless Tools support +- 802.1x (tested with XSupplicant 1.0.1) + +Enabled (but not supported) features: +- Monitor/RFMon mode +- WPA/WPA2 + +The distinction between officially supported and enabled is a reflection +on the amount of validation and interoperability testing that has been +performed on a given feature. + + +=========================== +2. Command Line Parameters +--------------------------- + +If the driver is built as a module, the following optional parameters are used +by entering them on the command line with the modprobe command using this +syntax: + + modprobe ipw2100 [