diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/ABI/stable/sysfs-class-ubi | 212 | ||||
| -rw-r--r-- | Documentation/DocBook/Makefile | 5 | ||||
| -rw-r--r-- | Documentation/HOWTO | 30 | ||||
| -rw-r--r-- | Documentation/arm/Samsung-S3C24XX/NAND.txt | 30 | ||||
| -rw-r--r-- | Documentation/arm/Samsung-S3C24XX/Overview.txt | 2 | ||||
| -rw-r--r-- | Documentation/device-mapper/dm-crypt.txt | 52 | ||||
| -rw-r--r-- | Documentation/filesystems/nfs-rdma.txt | 14 | ||||
| -rw-r--r-- | Documentation/filesystems/seq_file.txt | 19 | ||||
| -rw-r--r-- | Documentation/kbuild/modules.txt | 9 | ||||
| -rw-r--r-- | Documentation/networking/phy.txt | 38 | ||||
| -rw-r--r-- | Documentation/usb/anchors.txt | 50 | ||||
| -rw-r--r-- | Documentation/usb/callbacks.txt | 132 | ||||
| -rw-r--r-- | Documentation/usb/persist.txt | 43 | ||||
| -rw-r--r-- | Documentation/usb/usb-serial.txt | 7 |
14 files changed, 595 insertions, 48 deletions
diff --git a/Documentation/ABI/stable/sysfs-class-ubi b/Documentation/ABI/stable/sysfs-class-ubi new file mode 100644 index 00000000000..18d471d9fae --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-ubi @@ -0,0 +1,212 @@ +What: /sys/class/ubi/ +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + The ubi/ class sub-directory belongs to the UBI subsystem and + provides general UBI information, per-UBI device information + and per-UBI volume information. + +What: /sys/class/ubi/version +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + This file contains version of the latest supported UBI on-media + format. Currently it is 1, and there is no plan to change this. + However, if in the future UBI needs on-flash format changes + which cannot be done in a compatible manner, a new format + version will be added. So this is a mechanism for possible + future backward-compatible (but forward-incompatible) + improvements. + +What: /sys/class/ubiX/ +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + The /sys/class/ubi0, /sys/class/ubi1, etc directories describe + UBI devices (UBI device 0, 1, etc). They contain general UBI + device information and per UBI volume information (each UBI + device may have many UBI volumes) + +What: /sys/class/ubi/ubiX/avail_eraseblocks +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Amount of available logical eraseblock. For example, one may + create a new UBI volume which has this amount of logical + eraseblocks. + +What: /sys/class/ubi/ubiX/bad_peb_count +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Count of bad physical eraseblocks on the underlying MTD device. + +What: /sys/class/ubi/ubiX/bgt_enabled +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Contains ASCII "0\n" if the UBI background thread is disabled, + and ASCII "1\n" if it is enabled. + +What: /sys/class/ubi/ubiX/dev +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Major and minor numbers of the character device corresponding + to this UBI device (in <major>:<minor> format). + +What: /sys/class/ubi/ubiX/eraseblock_size +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Maximum logical eraseblock size this UBI device may provide. UBI + volumes may have smaller logical eraseblock size because of their + alignment. + +What: /sys/class/ubi/ubiX/max_ec +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Maximum physical eraseblock erase counter value. + +What: /sys/class/ubi/ubiX/max_vol_count +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Maximum number of volumes which this UBI device may have. + +What: /sys/class/ubi/ubiX/min_io_size +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Minimum input/output unit size. All the I/O may only be done + in fractions of the contained number. + +What: /sys/class/ubi/ubiX/mtd_num +Date: January 2008 +KernelVersion: 2.6.25 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Number of the underlying MTD device. + +What: /sys/class/ubi/ubiX/reserved_for_bad +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Number of physical eraseblocks reserved for bad block handling. + +What: /sys/class/ubi/ubiX/total_eraseblocks +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Total number of good (not marked as bad) physical eraseblocks on + the underlying MTD device. + +What: /sys/class/ubi/ubiX/volumes_count +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Count of volumes on this UBI device. + +What: /sys/class/ubi/ubiX/ubiX_Y/ +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + The /sys/class/ubi/ubiX/ubiX_0/, /sys/class/ubi/ubiX/ubiX_1/, + etc directories describe UBI volumes on UBI device X (volumes + 0, 1, etc). + +What: /sys/class/ubi/ubiX/ubiX_Y/alignment +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Volume alignment - the value the logical eraseblock size of + this volume has to be aligned on. For example, 2048 means that + logical eraseblock size is multiple of 2048. In other words, + volume logical eraseblock size is UBI device logical eraseblock + size aligned to the alignment value. + +What: /sys/class/ubi/ubiX/ubiX_Y/corrupted +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Contains ASCII "0\n" if the UBI volume is OK, and ASCII "1\n" + if it is corrupted (e.g., due to an interrupted volume update). + +What: /sys/class/ubi/ubiX/ubiX_Y/data_bytes +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + The amount of data this volume contains. This value makes sense + only for static volumes, and for dynamic volume it equivalent + to the total volume size in bytes. + +What: /sys/class/ubi/ubiX/ubiX_Y/dev +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Major and minor numbers of the character device corresponding + to this UBI volume (in <major>:<minor> format). + +What: /sys/class/ubi/ubiX/ubiX_Y/name +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Volume name. + +What: /sys/class/ubi/ubiX/ubiX_Y/reserved_ebs +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Count of physical eraseblock reserved for this volume. + Equivalent to the volume size in logical eraseblocks. + +What: /sys/class/ubi/ubiX/ubiX_Y/type +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Volume type. Contains ASCII "dynamic\n" for dynamic volumes and + "static\n" for static volumes. + +What: /sys/class/ubi/ubiX/ubiX_Y/upd_marker +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Contains ASCII "0\n" if the update marker is not set for this + volume, and "1\n" if it is set. The update marker is set when + volume update starts, and cleaned when it ends. So the presence + of the update marker indicates that the volume is being updated + at the moment of the update was interrupted. The later may be + checked using the "corrupted" sysfs file. + +What: /sys/class/ubi/ubiX/ubiX_Y/usable_eb_size +Date: July 2006 +KernelVersion: 2.6.22 +Contact: Artem Bityutskiy <dedekind@infradead.org> +Description: + Logical eraseblock size of this volume. Equivalent to logical + eraseblock size of the device aligned on the volume alignment + value. diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index b2b6366bba5..83966e94cc3 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -187,8 +187,11 @@ quiet_cmd_fig2png = FIG2PNG $@ ### # Rule to convert a .c file to inline XML documentation + gen_xml = : + quiet_gen_xml = echo ' GEN $@' +silent_gen_xml = : %.xml: %.c - @echo ' GEN $@' + @$($(quiet)gen_xml) @( \ echo "<programlisting>"; \ expand --tabs=8 < $< | \ diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 54835610b3d..0291ade44c1 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -249,9 +249,11 @@ process is as follows: release a new -rc kernel every week. - Process continues until the kernel is considered "ready", the process should last around 6 weeks. - - A list of known regressions present in each -rc release is - tracked at the following URI: - http://kernelnewbies.org/known_regressions + - Known regressions in each release are periodically posted to the + linux-kernel mailing list. The goal is to reduce the length of + that list to zero before declaring the kernel to be "ready," but, in + the real world, a small number of regressions often remain at + release time. It is worth mentioning what Andrew Morton wrote on the linux-kernel mailing list about kernel releases: @@ -261,7 +263,7 @@ mailing list about kernel releases: 2.6.x.y -stable kernel tree --------------------------- -Kernels with 4 digit versions are -stable kernels. They contain +Kernels with 4-part versions are -stable kernels. They contain relatively small and critical fixes for security problems or significant regressions discovered in a given 2.6.x kernel. @@ -273,7 +275,10 @@ If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is the current stable kernel. 2.6.x.y are maintained by the "stable" team <stable@kernel.org>, and are -released almost every other week. +released as needs dictate. The normal release period is approximately +two weeks, but it can be longer if there are no pressing problems. A +security-related problem, instead, can cause a release to happen almost +instantly. The file Documentation/stable_kernel_rules.txt in the kernel tree documents what kinds of changes are acceptable for the -stable tree, and @@ -298,7 +303,9 @@ a while Andrew or the subsystem maintainer pushes it on to Linus for inclusion in mainline. It is heavily encouraged that all new patches get tested in the -mm tree -before they are sent to Linus for inclusion in the main kernel tree. +before they are sent to Linus for inclusion in the main kernel tree. Code +which does not make an appearance in -mm before the opening of the merge +window will prove hard to merge into the mainline. These kernels are not appropriate for use on systems that are supposed to be stable and they are more risky to run than any of the other @@ -354,11 +361,12 @@ Here is a list of some of the different kernel trees available: - SCSI, James Bottomley <James.Bottomley@SteelEye.com> git.kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git + - x86, Ingo Molnar <mingo@elte.hu> + git://git.kernel.org/pub/scm/linux/kernel/git/x86/linux-2.6-x86.git + quilt trees: - - USB, PCI, Driver Core, and I2C, Greg Kroah-Hartman <gregkh@suse.de> + - USB, Driver Core, and I2C, Greg Kroah-Hartman <gregkh@suse.de> kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/ - - x86-64, partly i386, Andi Kleen <ak@suse.de> - ftp.firstfloor.org:/pub/ak/x86_64/quilt/ Other kernel trees can be found listed at http://git.kernel.org/ and in the MAINTAINERS file. @@ -392,8 +400,8 @@ If you want to be advised of the future bug reports, you can subscribe to the bugme-new mailing list (only new bug reports are mailed here) or to the bugme-janitor mailing list (every change in the bugzilla is mailed here) - http://lists.osdl.org/mailman/listinfo/bugme-new - http://lists.osdl.org/mailman/listinfo/bugme-janitors + http://lists.linux-foundation.org/mailman/listinfo/bugme-new + http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors diff --git a/Documentation/arm/Samsung-S3C24XX/NAND.txt b/Documentation/arm/Samsung-S3C24XX/NAND.txt new file mode 100644 index 00000000000..bc478a3409b --- /dev/null +++ b/Documentation/arm/Samsung-S3C24XX/NAND.txt @@ -0,0 +1,30 @@ + S3C24XX NAND Support + ==================== + +Introduction +------------ + +Small Page NAND +--------------- + +The driver uses a 512 byte (1 page) ECC code for this setup. The +ECC code is not directly compatible with the default kernel ECC +code, so the driver enforces its own OOB layout and ECC parameters + +Large Page NAND +--------------- + +The driver is capable of handling NAND flash with a 2KiB page +size, with support for hardware ECC generation and correction. + +Unlike the 512byte page mode, the driver generates ECC data for +each 256 byte block in an 2KiB page. This means that more than +one error in a page can be rectified. It also means that the +OOB layout remains the default kernel layout for these flashes. + + +Document Author +--------------- + +Ben Dooks, Copyright 2007 Simtec Electronics + diff --git a/Documentation/arm/Samsung-S3C24XX/Overview.txt b/Documentation/arm/Samsung-S3C24XX/Overview.txt index c31b76fa66c..d04e1e30c47 100644 --- a/Documentation/arm/Samsung-S3C24XX/Overview.txt +++ b/Documentation/arm/Samsung-S3C24XX/Overview.txt @@ -156,6 +156,8 @@ NAND controller. If there are any problems the latest linux-mtd code can be found from http://www.linux-mtd.infradead.org/ + For more information see Documentation/arm/Samsung-S3C24XX/NAND.txt + Serial ------ diff --git a/Documentation/device-mapper/dm-crypt.txt b/Documentation/device-mapper/dm-crypt.txt new file mode 100644 index 00000000000..6680cab2c70 --- /dev/null +++ b/Documentation/device-mapper/dm-crypt.txt @@ -0,0 +1,52 @@ +dm-crypt +========= + +Device-Mapper's "crypt" target provides transparent encryption of block devices +using the kernel crypto API. + +Parameters: <cipher> <key> <iv_offset> <device path> <offset> + +<cipher> + Encryption cipher and an optional IV generation mode. + (In format cipher-chainmode-ivopts:ivmode). + Examples: + des + aes-cbc-essiv:sha256 + twofish-ecb + + /proc/crypto contains supported crypto modes + +<key> + Key used for encryption. It is encoded as a hexadecimal number. + You can only use key sizes that are valid for the selected cipher. + +<iv_offset> + The IV offset is a sector count that is added to the sector number + before creating the IV. + +<device path> + This is the device that is going to be used as backend and contains the + encrypted data. You can specify it as a path like /dev/xxx or a device + number <major>:<minor>. + +<offset> + Starting sector within the device where the encrypted data begins. + +Example scripts +=============== +LUKS (Linux Unified Key Setup) is now the preferred way to set up disk +encryption with dm-crypt using the 'cryptsetup' utility, see +http://luks.endorphin.org/ + +[[ +#!/bin/sh +# Create a crypt device using dmsetup +dmsetup create crypt1 --table "0 `blockdev --getsize $1` crypt aes-cbc-essiv:sha256 babebabebabebabebabebabebabebabe 0 $1 0" +]] + +[[ +#!/bin/sh +# Create a crypt device using cryptsetup and LUKS header with default cipher +cryptsetup luksFormat $1 +cryptsetup luksOpen $1 crypt1 +]] diff --git a/Documentation/filesystems/nfs-rdma.txt b/Documentation/filesystems/nfs-rdma.txt index 1ae34879574..d0ec45ae4e7 100644 --- a/Documentation/filesystems/nfs-rdma.txt +++ b/Documentation/filesystems/nfs-rdma.txt @@ -5,7 +5,7 @@ ################################################################################ Author: NetApp and Open Grid Computing - Date: February 25, 2008 + Date: April 15, 2008 Table of Contents ~~~~~~~~~~~~~~~~~ @@ -197,12 +197,16 @@ NFS/RDMA Setup - On the server system, configure the /etc/exports file and start the NFS/RDMA server. - Exports entries with the following format have been tested: + Exports entries with the following formats have been tested: - /vol0 10.97.103.47(rw,async) 192.168.0.47(rw,async,insecure,no_root_squash) + /vol0 192.168.0.47(fsid=0,rw,async,insecure,no_root_squash) + /vol0 192.168.0.0/255.255.255.0(fsid=0,rw,async,insecure,no_root_squash) - Here the first IP address is the client's Ethernet address and the second - IP address is the clients IPoIB address. + The IP address(es) is(are) the client's IPoIB address for an InfiniBand HCA or the + cleint's iWARP address(es) for an RNIC. + + NOTE: The "insecure" option must be used because the NFS/RDMA client does not + use a reserved port. Each time a machine boots: diff --git a/Documentation/filesystems/seq_file.txt b/Documentation/filesystems/seq_file.txt index 7fb8e6dc62b..b843743aa0b 100644 --- a/Documentation/filesystems/seq_file.txt +++ b/Documentation/filesystems/seq_file.txt @@ -122,8 +122,7 @@ stop() is the place to free it. } Finally, the show() function should format the object currently pointed to -by the iterator for output. It should return zero, or an error code if -something goes wrong. The example module's show() function is: +by the iterator for output. The example module's show() function is: static int ct_seq_show(struct seq_file *s, void *v) { @@ -132,6 +131,12 @@ something goes wrong. The example module's show() function is: return 0; } +If all is well, the show() function should return zero. A negative error +code in the usual manner indicates that something went wrong; it will be +passed back to user space. This function can also return SEQ_SKIP, which +causes the current item to be skipped; if the show() function has already +generated output before returning SEQ_SKIP, that output will be dropped. + We will look at seq_printf() in a moment. But first, the definition of the seq_file iterator is finished by creating a seq_operations structure with the four functions we have just defined: @@ -182,12 +187,18 @@ The first two output a single character and a string, just like one would expect. seq_escape() is like seq_puts(), except that any character in s which is in the string esc will be represented in octal form in the output. -There is also a function for printing filenames: +There is also a pair of functions for printing filenames: int seq_path(struct seq_file *m, struct path *path, char *esc); + int seq_path_root(struct seq_file *m, struct path *path, + struct path *root, char *esc) Here, path indicates the file of interest, and esc is a set of characters -which should be escaped in the output. +which should be escaped in the output. A call to seq_path() will output +the path relative to the current process's filesystem root. If a different +root is desired, it can be used with seq_path_root(). Note that, if it +turns out that path cannot be reached from root, the value of root will be +changed in seq_file_root() to a root which *does* work. Making it all work diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.txt index 1d247d59ad5..1821c077b43 100644 --- a/Documentation/kbuild/modules.txt +++ b/Documentation/kbuild/modules.txt @@ -486,7 +486,7 @@ Module.symvers contains a list of all exported symbols from a kernel build. Sometimes, an external module uses exported symbols from another external module. Kbuild needs to have full knowledge on all symbols to avoid spitting out warnings about undefined symbols. - Two solutions exist to let kbuild know all symbols of more than + Three solutions exist to let kbuild know all symbols of more than one external module. The method with a top-level kbuild file is recommended but may be impractical in certain situations. @@ -523,6 +523,13 @@ Module.symvers contains a list of all exported symbols from a kernel build. containing the sum of all symbols defined and not part of the kernel. + Use make variable KBUILD_EXTRA_SYMBOLS in the Makefile + If it is impractical to copy Module.symvers from another + module, you can assign a space separated list of files to + KBUILD_EXTRA_SYMBOLS in your Makfile. These files will be + loaded by modpost during the initialisation of its symbol + tables. + === 8. Tips & Tricks --- 8.1 Testing for CONFIG_FOO_BAR diff --git a/Documentation/networking/phy.txt b/Documentation/networking/phy.txt index 0bc95eab151..8df6a7b0e66 100644 --- a/Documentation/networking/phy.txt +++ b/Documentation/networking/phy.txt @@ -1,7 +1,7 @@ ------- PHY Abstraction Layer -(Updated 2006-11-30) +(Updated 2008-04-08) Purpose @@ -291,3 +291,39 @@ Writing a PHY driver Feel free to look at the Marvell, Cicada, and Davicom drivers in drivers/net/phy/ for examples (the lxt and qsemi drivers have not been tested as of this writing) + +Board Fixups + + Sometimes the specific interaction between the platform and the PHY requires + special handling. For instance, to change where the PHY's clock input is, + or to add a delay to account for latency issues in the data path. In order + to support such contingencies, the PHY Layer allows platform code to register + fixups to be run when the PHY is brought up (or subsequently reset). + + When the PHY Layer brings up a PHY it checks to see if there are any fixups + registered for it, matching based on UID (contained in the PHY device's phy_id + field) and the bus identifier (contained in phydev->dev.bus_id). Both must + match, however two constants, PHY_ANY_ID and PHY_ANY_UID, are provided as + wildcards for the bus ID and UID, respectively. + + When a match is found, the PHY layer will invoke the run function associated + with the fixup. This function is passed a pointer to the phy_device of + interest. It should therefore only operate on that PHY. + + The platform code can either register the fixup using phy_register_fixup(): + + int phy_register_fixup(const char *phy_id, + u32 phy_uid, u32 phy_uid_mask, + int (*run)(struct phy_device *)); + + Or using one of the two stubs, phy_register_fixup_for_uid() and + phy_register_fixup_for_id(): + + int phy_register_fixup_for_uid(u32 phy_uid, u32 phy_uid_mask, + int (*run)(struct phy_device *)); + int phy_register_fixup_for_id(const char *phy_id, + int (*run)(struct phy_device *)); + + The stubs set one of the two matching criteria, and set the other one to + match anything. + diff --git a/Documentation/usb/anchors.txt b/Documentation/usb/anchors.txt new file mode 100644 index 00000000000..7304bcf5a30 --- /dev/null +++ b/Documentation/usb/anchors.txt @@ -0,0 +1,50 @@ +What is anchor? +=============== + +A USB driver needs to support some callbacks requiring +a driver to cease all IO to an interface. To do so, a +driver has to keep track of the URBs it has submitted +to know they've all completed or to call usb_kill_urb +for them. The anchor is a data structure takes care of +keeping track of URBs and provides methods to deal with +multiple URBs. + +Allocation and Initialisation +============================= + +There's no API to allocate an anchor. It is simply declared +as struct usb_anchor. init_usb_anchor() must be called to +initialise the data structure. + +Deallocation +============ + +Once it has no more URBs associated with it, the anchor can be +freed with normal memory management operations. + +Association and disassociation of URBs with anchors +=================================================== + +An association of URBs to an anchor is made by an explicit +call to usb_anchor_urb(). The association is maintained until +an URB is finished by (successfull) completion. Thus disassociation +is automatic. A function is provided to forcibly finish (kill) +all URBs associated with an anchor. +Furthermore, disassociation can be made with usb_unanchor_urb() + +Operations on multitudes of URBs +================================ + +usb_kill_anchored_urbs() +------------------------ + +This function kills all URBs associated with an anchor. The URBs +are called in the reverse temporal order they were submitted. +This way no data can be reordered. + +usb_wait_anchor_empty_timeout() +------------------------------- + +This function waits for all URBs associated with an anchor to finish +or a timeout, whichever comes first. Its return value will tell you +whether the timeout was reached. diff --git a/Documentation/usb/callbacks.txt b/Documentation/usb/callbacks.txt new file mode 100644 index 00000000000..7c812411945 --- /dev/null +++ b/Documentation/usb/callbacks.txt @@ -0,0 +1,132 @@ +What callbacks will usbcore do? +=============================== + +Usbcore will call into a driver through callbacks defined in the driver +structure and through the completion handler of URBs a driver submits. +Only the former are in the scope of this document. These two kinds of +callbacks are completely independent of each other. Information on the +completion callback can be found in Documentation/usb/URB.txt. + +The callbacks defined in the driver structure are: + +1. Hotplugging callbacks: + + * @probe: Called to see if the driver is willing to manage a particular + * interface on a device. + * @disconnect: Called when the interface is no longer accessible, usually + * because its device has been (or is being) disconnected or the + * driver module is being unloaded. + +2. Odd backdoor through usbfs: + + * @ioctl: Used for drivers that want to talk to userspace through + * the "usbfs" filesystem. This lets devices provide ways to + * expose information to user space regardless of where they + * do (or don't) show up otherwise in the filesystem. + +3. Power management (PM) callbacks: + + * @suspend: Called when the device is going to be suspended. + * @resume: Called when the device is being resumed. + * @reset_resume: Called when the suspended device has been reset instead + * of being resumed. + +4. Device level operations: + + * @pre_reset: Called when the device is about to be reset. + * @post_reset: Called after the device has been reset + +The ioctl interface (2) should be used only if you have a very good +reason. Sysfs is preferred these days. The PM callbacks are covered +separately in Documentation/usb/power-management.txt. + +Calling conventions +=================== + +All callbacks are mutually exclusive. There's no need for locking +against other USB callbacks. All callbacks are called from a task +context. You may sleep. However, it is important that all sleeps have a +small fixed upper limit in time. In particular you must not call out to +user space and await results. + +Hotplugging callbacks +===================== + +These callbacks are intended to associate and disassociate a driver with +an interface. A driver's bond to an interface is exclusive. + +The probe() callback +-------------------- + +int (*probe) (struct usb_interface *intf, + const struct usb_device_id *id); + +Accept or decline an interface. If you accept the device return 0, +otherwise -ENODEV or -ENXIO. Other error codes should be used only if a +genuine error occurred during initialisation which prevented a driver +from accepting a device that would else have been accepted. +You are strongly encouraged to use usbcore'sfacility, +usb_set_intfdata(), to associate a data structure with an interface, so +that you know which internal state and identity you associate with a +particular interface. The device will not be suspended and you may do IO +to the interface you are called for and endpoint 0 of the device. Device +initialisation that doesn't take too long is a good idea here. + +The disconnect() callback +------------------------- + +void (*disconnect) (struct usb_interface *intf); + +This callback is a signal to break any connection with an interface. +You are not allowed any IO to a device after returning from this +callback. You also may not do any other operation that may interfere +with another driver bound the interface, eg. a power management +operation. +If you are called due to a physical disconnection, all your URBs will be +killed by usbcore. Note that in this case disconnect will be called some +time after the physical disconnection. Thus your driver must be prepared +to deal with failing IO even prior to the callback. + +Device level callbacks +====================== + +pre_reset +--------- + +int (*pre_reset)(struct usb_interface *intf); + +Another driver or user space is triggering a reset on the device which +contains the interface passed as an argument. Cease IO and save any +device state you need to restore. + +If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you +are in atomic context. + +post_reset +---------- + +int (*post_reset)(struct usb_interface *intf); + +The reset has completed. Restore any saved device state and begin +using the device again. + +If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you +are in atomic context. + +Call sequences +============== + +No callbacks other than probe will be invoked for an interface +that isn't bound to your driver. + +Probe will never be called for an interface bound to a driver. +Hence following a successful probe, disconnect will be called +before there is another probe for the same interface. + +Once your driver is bound to an interface, disconnect can be +called at any time except in between pre_reset and post_reset. +pre_reset is always followed by post_reset, even if the reset +failed or the device has been unplugged. + +suspend is always followed by one of: resume, reset_resume, or +disconnect. diff --git a/Documentation/usb/persist.txt b/Documentation/usb/persist.txt index df54d645cbb..d56cb1a1155 100644 --- a/Documentation/usb/persist.txt +++ b/Documentation/usb/persist.txt @@ -2,7 +2,7 @@ Alan Stern <stern@rowland.harvard.edu> - September 2, 2006 (Updated May 29, 2007) + September 2, 2006 (Updated February 25, 2008) What is the problem? @@ -65,9 +65,10 @@ much better.) What is the solution? -Setting CONFIG_USB_PERSIST will cause the kernel to work around these -issues. It enables a mode in which the core USB device data -structures are allowed to persist across a power-session disruption. +The kernel includes a feature called USB-persist. It tries to work +around these issues by allowing the core USB device data structures to +persist across a power-session disruption. + It works like this. If the kernel sees that a USB host controller is not in the expected state during resume (i.e., if the controller was reset or otherwise had lost power) then it applies a persistence check @@ -80,28 +81,30 @@ re-enumeration shows that the device now attached to that port has the same descriptors as before, including the Vendor and Product IDs, then the kernel continues to use the same device structure. In effect, the kernel treats the device as though it had merely been reset instead of -unplugged. +unplugged. The same thing happens if the host controller is in the +expected state but a USB device was unplugged and then replugged. If no device is now attached to the port, or if the descriptors are different from what the kernel remembers, then the treatment is what you would expect. The kernel destroys the old device structure and behaves as though the old device had been unplugged and a new device -plugged in, just as it would without the CONFIG_USB_PERSIST option. +plugged in. The end result is that the USB device remains available and usable. Filesystem mounts and memory mappings are unaffected, and the world is now a good and happy place. -Note that even when CONFIG_USB_PERSIST is set, the "persist" feature -will be applied only to those devices for which it is enabled. You -can enable the feature by doing (as root): +Note that the "USB-persist" feature will be applied only to those +devices for which it is enabled. You can enable the feature by doing +(as root): echo 1 >/sys/bus/usb/devices/.../power/persist where the "..." should be filled in the with the device's ID. Disable the feature by writing 0 instead of 1. For hubs the feature is -automatically and permanently enabled, so you only have to worry about -setting it for devices where it really matters. +automatically and permanently enabled and the power/persist file +doesn't even exist, so you only have to worry about setting it for +devices where it really matters. Is this the best solution? @@ -112,19 +115,19 @@ centralized Logical Volume Manager. Such a solution would allow you to plug in a USB flash device, create a persistent volume associated with it, unplug the flash device, plug it back in later, and still have the same persistent volume associated with the device. As such -it would be more far-reaching than CONFIG_USB_PERSIST. +it would be more far-reaching than USB-persist. On the other hand, writing a persistent volume manager would be a big job and using it would require significant input from the user. This solution is much quicker and easier -- and it exists now, a giant point in its favor! -Furthermore, the USB_PERSIST option applies to _all_ USB devices, not +Furthermore, the USB-persist feature applies to _all_ USB devices, not just mass-storage devices. It might turn out to be equally useful for other device types, such as network interfaces. - WARNING: Using CONFIG_USB_PERSIST can be dangerous!! + WARNING: USB-persist can be dangerous!! When recovering an interrupted power session the kernel does its best to make sure the USB device hasn't been changed; that is, the same @@ -133,10 +136,10 @@ aren't guaranteed to be 100% accurate. If you replace one USB device with another of the same type (same manufacturer, same IDs, and so on) there's an excellent chance the -kernel won't detect the change. Serial numbers and other strings are -not compared. In many cases it wouldn't help if they were, because -manufacturers frequently omit serial numbers entirely in their -devices. +kernel won't detect the change. The serial number string and other +descriptors are compared with the kernel's stored values, but this +might not help since manufacturers frequently omit serial numbers +entirely in their devices. Furthermore it's quite possible to leave a USB device exactly the same while changing its media. If you replace the flash memory card in a @@ -152,5 +155,5 @@ but yourself. YOU HAVE BEEN WARNED! USE AT YOUR OWN RISK! That having been said, most of the time there shouldn't be any trouble -at all. The "persist" feature can be extremely useful. Make the most -of it. +at all. The USB-persist feature can be extremely useful. Make the +most of it. diff --git a/Documentation/usb/usb-serial.txt b/Documentation/usb/usb-serial.txt index 8b077e43eee..ff2c1ff57ba 100644 --- a/Documentation/usb/usb-serial.txt +++ b/Documentation/usb/usb-serial.txt @@ -192,12 +192,9 @@ Keyspan USA-series Serial Adapters FTDI Single Port Serial Driver - This is a single port DB-25 serial adapter. More information about this - device and the Linux driver can be found at: - http://reality.sgi.com/bryder_wellington/ftdi_sio/ + This is a single port DB-25 serial adapter. - For any questions or problems with this driver, please contact Bill Ryder - at bryder@sgi.com + For any questions or problems with this driver, please contact Bill Ryder. ZyXEL omni.net lcd plus ISDN TA |