diff options
Diffstat (limited to 'Documentation')
234 files changed, 12558 insertions, 3932 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 43827780010..2a39aeba146 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -21,6 +21,9 @@ Changes - list of changes that break older software packages. CodingStyle - how the boss likes the C code in the kernel to look. +development-process/ + - An extended tutorial on how to work with the kernel development + process. DMA-API.txt - DMA API, pci_ API & extensions for non-consistent memory machines. DMA-ISA-LPC.txt @@ -39,14 +42,8 @@ IRQ.txt - description of what an IRQ is. ManagementStyle - how to (attempt to) manage kernel hackers. -MSI-HOWTO.txt - - the Message Signaled Interrupts (MSI) Driver Guide HOWTO and FAQ. RCU/ - directory with info on RCU (read-copy update). -README.DAC960 - - info on Mylex DAC960/DAC1100 PCI RAID Controller Driver for Linux. -README.cycladesZ - - info on Cyclades-Z firmware loading. SAK.txt - info on Secure Attention Keys. SM501.txt @@ -83,20 +80,16 @@ blackfin/ - directory with documentation for the Blackfin arch. block/ - info on the Block I/O (BIO) layer. +blockdev/ + - info on block devices & drivers cachetlb.txt - describes the cache/TLB flushing interfaces Linux uses. -cciss.txt - - info, major/minor #'s for Compaq's SMART Array Controllers. cdrom/ - directory with information on the CD-ROM drivers that Linux has. -computone.txt - - info on Computone Intelliport II/Plus Multiport Serial Driver. connector/ - docs on the netlink based userspace<->kernel space communication mod. console/ - documentation on Linux console drivers. -cpqarray.txt - - info on using Compaq's SMART2 Intelligent Disk Array Controllers. cpu-freq/ - info on CPU frequency and voltage scaling. cpu-hotplug.txt @@ -123,8 +116,6 @@ device-mapper/ - directory with info on Device Mapper. devices.txt - plain ASCII listing of all the nodes in /dev/ with major minor #'s. -digiepca.txt - - info on Digi Intl. {PC,PCI,EISA}Xx and Xem series cards. dontdiff - file containing a list of files that should never be diff'ed. driver-model/ @@ -149,14 +140,10 @@ filesystems/ - info on the vfs and the various filesystems that Linux supports. firmware_class/ - request_firmware() hotplug interface info. -floppy.txt - - notes and driver options for the floppy disk driver. frv/ - Fujitsu FR-V Linux documentation. gpio.txt - overview of GPIO (General Purpose Input/Output) access conventions. -hayes-esp.txt - - info on using the Hayes ESP serial driver. highuid.txt - notes on the change from 16 bit to 32 bit user/group IDs. timers/ @@ -169,7 +156,7 @@ i2c/ - directory with info about the I2C bus/protocol (2 wire, kHz speed). i2o/ - directory with info about the Linux I2O subsystem. -i386/ +x86/i386/ - directory with info about Linux on Intel 32 bit architecture. ia64/ - directory with info about Linux on Intel 64 bit architecture. @@ -183,8 +170,6 @@ io_ordering.txt - info on ordering I/O writes to memory-mapped addresses. ioctl/ - directory with documents describing various IOCTL calls. -ioctl-number.txt - - how to implement and register device/driver ioctl calls. iostats.txt - info on I/O statistics Linux kernel provides. irqflags-tracing.txt @@ -247,14 +232,10 @@ mips/ - directory with info about Linux on MIPS architecture. mono.txt - how to execute Mono-based .NET binaries with the help of BINFMT_MISC. -moxa-smartio - - file with info on installing/using Moxa multiport serial driver. mutex-design.txt - info on the generic mutex subsystem. namespaces/ - directory with various information about namespaces -nbd.txt - - info on a TCP implementation of a network block device. netlabel/ - directory with information on the NetLabel subsystem. networking/ @@ -267,8 +248,6 @@ numastat.txt - info on how to read Numa policy hit/miss statistics in sysfs. oops-tracing.txt - how to decode those nasty internal kernel error dump messages. -paride.txt - - information about the parallel port IDE subsystem. parisc/ - directory with info on using Linux on PA-RISC architecture. parport.txt @@ -287,20 +266,16 @@ powerpc/ - directory with info on using Linux with the PowerPC. preempt-locking.txt - info on locking under a preemptive kernel. +printk-formats.txt + - how to get printk format specifiers right prio_tree.txt - info on radix-priority-search-tree use for indexing vmas. -ramdisk.txt - - short guide on how to set up and use the RAM disk. rbtree.txt - info on what red-black trees are and what they are for. -riscom8.txt - - notes on using the RISCom/8 multi-port serial driver. robust-futex-ABI.txt - documentation of the robust futex ABI. robust-futexes.txt - a description of what robust futexes are. -rocket.txt - - info on the Comtrol RocketPort multiport serial driver. rt-mutex-design.txt - description of the RealTime mutex implementation design. rt-mutex.txt @@ -329,8 +304,6 @@ sparc/ - directory with info on using Linux on Sparc architecture. sparse.txt - info on how to obtain and use the sparse tool for typechecking. -specialix.txt - - info on hardware/driver for specialix IO8+ multiport serial card. spi/ - overview of Linux kernel Serial Peripheral Interface (SPI) support. spinlocks.txt @@ -339,14 +312,10 @@ stable_api_nonsense.txt - info on why the kernel does not have a stable in-kernel api or abi. stable_kernel_rules.txt - rules and procedures for the -stable kernel releases. -stallion.txt - - info on using the Stallion multiport serial driver. svga.txt - short guide on selecting video modes at boot via VGA BIOS. sysfs-rules.txt - How not to use sysfs. -sx.txt - - info on the Specialix SX/SI multiport serial driver. sysctl/ - directory with info on the /proc/sys/* files. sysrq.txt @@ -355,8 +324,6 @@ telephony/ - directory with info on telephony (e.g. voice over IP) support. time_interpolators.txt - info on time interpolators. -tty.txt - - guide to the locking policies of the tty layer. uml/ - directory with information about User Mode Linux. unicode.txt @@ -379,7 +346,7 @@ w1/ - directory with documents regarding the 1-wire (w1) subsystem. watchdog/ - how to auto-reboot Linux if it has "fallen and can't get up". ;-) -x86_64/ +x86/x86_64/ - directory with info on Linux support for AMD x86-64 (Hammer) machines. zorro.txt - info on writing drivers for Zorro bus devices found on Amigas. diff --git a/Documentation/ABI/stable/sysfs-driver-usb-usbtmc b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc new file mode 100644 index 00000000000..9a75fb22187 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc @@ -0,0 +1,62 @@ +What: /sys/bus/usb/drivers/usbtmc/devices/*/interface_capabilities +What: /sys/bus/usb/drivers/usbtmc/devices/*/device_capabilities +Date: August 2008 +Contact: Greg Kroah-Hartman <gregkh@suse.de> +Description: + These files show the various USB TMC capabilities as described + by the device itself. The full description of the bitfields + can be found in the USB TMC documents from the USB-IF entitled + "Universal Serial Bus Test and Measurement Class Specification + (USBTMC) Revision 1.0" section 4.2.1.8. + + The files are read only. + + +What: /sys/bus/usb/drivers/usbtmc/devices/*/usb488_interface_capabilities +What: /sys/bus/usb/drivers/usbtmc/devices/*/usb488_device_capabilities +Date: August 2008 +Contact: Greg Kroah-Hartman <gregkh@suse.de> +Description: + These files show the various USB TMC capabilities as described + by the device itself. The full description of the bitfields + can be found in the USB TMC documents from the USB-IF entitled + "Universal Serial Bus Test and Measurement Class, Subclass + USB488 Specification (USBTMC-USB488) Revision 1.0" section + 4.2.2. + + The files are read only. + + +What: /sys/bus/usb/drivers/usbtmc/devices/*/TermChar +Date: August 2008 +Contact: Greg Kroah-Hartman <gregkh@suse.de> +Description: + This file is the TermChar value to be sent to the USB TMC + device as described by the document, "Universal Serial Bus Test + and Measurement Class Specification + (USBTMC) Revision 1.0" as published by the USB-IF. + + Note that the TermCharEnabled file determines if this value is + sent to the device or not. + + +What: /sys/bus/usb/drivers/usbtmc/devices/*/TermCharEnabled +Date: August 2008 +Contact: Greg Kroah-Hartman <gregkh@suse.de> +Description: + This file determines if the TermChar is to be sent to the + device on every transaction or not. For more details about + this, please see the document, "Universal Serial Bus Test and + Measurement Class Specification (USBTMC) Revision 1.0" as + published by the USB-IF. + + +What: /sys/bus/usb/drivers/usbtmc/devices/*/auto_abort +Date: August 2008 +Contact: Greg Kroah-Hartman <gregkh@suse.de> +Description: + This file determines if the the transaction of the USB TMC + device is to be automatically aborted if there is any error. + For more details about this, please see the document, + "Universal Serial Bus Test and Measurement Class Specification + (USBTMC) Revision 1.0" as published by the USB-IF. diff --git a/Documentation/ABI/testing/sysfs-bus-umc b/Documentation/ABI/testing/sysfs-bus-umc new file mode 100644 index 00000000000..948fec41244 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-umc @@ -0,0 +1,28 @@ +What: /sys/bus/umc/ +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + The Wireless Host Controller Interface (WHCI) + specification describes a PCI-based device with + multiple capabilities; the UWB Multi-interface + Controller (UMC). + + The umc bus presents each of the individual + capabilties as a device. + +What: /sys/bus/umc/devices/.../capability_id +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + The ID of this capability, with 0 being the radio + controller capability. + +What: /sys/bus/umc/devices/.../version +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + The specification version this capability's hardware + interface complies with. diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 11a3c1682ce..7772928ee48 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -85,3 +85,62 @@ Description: Users: PowerTOP <power@bughost.org> http://www.lesswatts.org/projects/powertop/ + +What: /sys/bus/usb/device/<busnum>-<devnum>...:<config num>-<interface num>/supports_autosuspend +Date: January 2008 +KernelVersion: 2.6.27 +Contact: Sarah Sharp <sarah.a.sharp@intel.com> +Description: + When read, this file returns 1 if the interface driver + for this interface supports autosuspend. It also + returns 1 if no driver has claimed this interface, as an + unclaimed interface will not stop the device from being + autosuspended if all other interface drivers are idle. + The file returns 0 if autosuspend support has not been + added to the driver. +Users: + USB PM tool + git://git.moblin.org/users/sarah/usb-pm-tool/ + +What: /sys/bus/usb/device/.../authorized +Date: July 2008 +KernelVersion: 2.6.26 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + Authorized devices are available for use by device + drivers, non-authorized one are not. By default, wired + USB devices are authorized. + + Certified Wireless USB devices are not authorized + initially and should be (by writing 1) after the + device has been authenticated. + +What: /sys/bus/usb/device/.../wusb_cdid +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + For Certified Wireless USB devices only. + + A devices's CDID, as 16 space-separated hex octets. + +What: /sys/bus/usb/device/.../wusb_ck +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + For Certified Wireless USB devices only. + + Write the device's connection key (CK) to start the + authentication of the device. The CK is 16 + space-separated hex octets. + +What: /sys/bus/usb/device/.../wusb_disconnect +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + For Certified Wireless USB devices only. + + Write a 1 to force the device to disconnect + (equivalent to unplugging a wired USB device). diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg new file mode 100644 index 00000000000..cb830df8777 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg @@ -0,0 +1,43 @@ +Where: /sys/bus/usb/.../powered +Date: August 2008 +Kernel Version: 2.6.26 +Contact: Harrison Metzger <harrisonmetz@gmail.com> +Description: Controls whether the device's display will powered. + A value of 0 is off and a non-zero value is on. + +Where: /sys/bus/usb/.../mode_msb +Where: /sys/bus/usb/.../mode_lsb +Date: August 2008 +Kernel Version: 2.6.26 +Contact: Harrison Metzger <harrisonmetz@gmail.com> +Description: Controls the devices display mode. + For a 6 character display the values are + MSB 0x06; LSB 0x3F, and + for an 8 character display the values are + MSB 0x08; LSB 0xFF. + +Where: /sys/bus/usb/.../textmode +Date: August 2008 +Kernel Version: 2.6.26 +Contact: Harrison Metzger <harrisonmetz@gmail.com> +Description: Controls the way the device interprets its text buffer. + raw: each character controls its segment manually + hex: each character is between 0-15 + ascii: each character is between '0'-'9' and 'A'-'F'. + +Where: /sys/bus/usb/.../text +Date: August 2008 +Kernel Version: 2.6.26 +Contact: Harrison Metzger <harrisonmetz@gmail.com> +Description: The text (or data) for the device to display + +Where: /sys/bus/usb/.../decimals +Date: August 2008 +Kernel Version: 2.6.26 +Contact: Harrison Metzger <harrisonmetz@gmail.com> +Description: Controls the decimal places on the device. + To set the nth decimal place, give this field + the value of 10 ** n. Assume this field has + the value k and has 1 or more decimal places set, + to set the mth place (where m is not already set), + change this fields value to k + 10 ** m.
\ No newline at end of file diff --git a/Documentation/ABI/testing/sysfs-c2port b/Documentation/ABI/testing/sysfs-c2port new file mode 100644 index 00000000000..716cffc457e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-c2port @@ -0,0 +1,88 @@ +What: /sys/class/c2port/ +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/ directory will contain files and + directories that will provide a unified interface to + the C2 port interface. + +What: /sys/class/c2port/c2portX +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/ directory is related to X-th + C2 port into the system. Each directory will contain files to + manage and control its C2 port. + +What: /sys/class/c2port/c2portX/access +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/access file enable the access + to the C2 port from the system. No commands can be sent + till this entry is set to 0. + +What: /sys/class/c2port/c2portX/dev_id +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/dev_id file show the device ID + of the connected micro. + +What: /sys/class/c2port/c2portX/flash_access +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/flash_access file enable the + access to the on-board flash of the connected micro. + No commands can be sent till this entry is set to 0. + +What: /sys/class/c2port/c2portX/flash_block_size +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/flash_block_size file show + the on-board flash block size of the connected micro. + +What: /sys/class/c2port/c2portX/flash_blocks_num +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/flash_blocks_num file show + the on-board flash blocks number of the connected micro. + +What: /sys/class/c2port/c2portX/flash_data +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/flash_data file export + the content of the on-board flash of the connected micro. + +What: /sys/class/c2port/c2portX/flash_erase +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/flash_erase file execute + the "erase" command on the on-board flash of the connected + micro. + +What: /sys/class/c2port/c2portX/flash_erase +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/flash_erase file show the + on-board flash size of the connected micro. + +What: /sys/class/c2port/c2portX/reset +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/reset file execute a "reset" + command on the connected micro. + +What: /sys/class/c2port/c2portX/rev_id +Date: October 2008 +Contact: Rodolfo Giometti <giometti@linux.it> +Description: + The /sys/class/c2port/c2portX/rev_id file show the revision ID + of the connected micro. diff --git a/Documentation/ABI/testing/sysfs-class-usb_host b/Documentation/ABI/testing/sysfs-class-usb_host new file mode 100644 index 00000000000..46b66ad1f1b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-usb_host @@ -0,0 +1,25 @@ +What: /sys/class/usb_host/usb_hostN/wusb_chid +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + Write the CHID (16 space-separated hex octets) for this host controller. + This starts the host controller, allowing it to accept connection from + WUSB devices. + + Set an all zero CHID to stop the host controller. + +What: /sys/class/usb_host/usb_hostN/wusb_trust_timeout +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + Devices that haven't sent a WUSB packet to the host + within 'wusb_trust_timeout' ms are considered to have + disconnected and are removed. The default value of + 4000 ms is the value required by the WUSB + specification. + + Since this relates to security (specifically, the + lifetime of PTKs and GTKs) it should not be changed + from the default. diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc b/Documentation/ABI/testing/sysfs-class-uwb_rc new file mode 100644 index 00000000000..a0d18dbeb7a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-uwb_rc @@ -0,0 +1,144 @@ +What: /sys/class/uwb_rc +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + Interfaces for WiMedia Ultra Wideband Common Radio + Platform (UWB) radio controllers. + + Familiarity with the ECMA-368 'High Rate Ultra + Wideband MAC and PHY Specification' is assumed. + +What: /sys/class/uwb_rc/beacon_timeout_ms +Date: July 2008 +KernelVersion: 2.6.27 +Description: + If no beacons are received from a device for at least + this time, the device will be considered to have gone + and it will be removed. The default is 3 superframes + (~197 ms) as required by the specification. + +What: /sys/class/uwb_rc/uwbN/ +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + An individual UWB radio controller. + +What: /sys/class/uwb_rc/uwbN/beacon +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + Write: + + <channel> [<bpst offset>] + + to start beaconing on a specific channel, or stop + beaconing if <channel> is -1. Valid channels depends + on the radio controller's supported band groups. + + <bpst offset> may be used to try and join a specific + beacon group if more than one was found during a scan. + +What: /sys/class/uwb_rc/uwbN/scan +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + Write: + + <channel> <type> [<bpst offset>] + + to start (or stop) scanning on a channel. <type> is one of: + 0 - scan + 1 - scan outside BP + 2 - scan while inactive + 3 - scanning disabled + 4 - scan (with start time of <bpst offset>) + +What: /sys/class/uwb_rc/uwbN/mac_address +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + The EUI-48, in colon-separated hex octets, for this + radio controller. A write will change the radio + controller's EUI-48 but only do so while the device is + not beaconing or scanning. + +What: /sys/class/uwb_rc/uwbN/wusbhc +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + A symlink to the device (if any) of the WUSB Host + Controller PAL using this radio controller. + +What: /sys/class/uwb_rc/uwbN/<EUI-48>/ +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + A neighbour UWB device that has either been detected + as part of a scan or is a member of the radio + controllers beacon group. + +What: /sys/class/uwb_rc/uwbN/<EUI-48>/BPST +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + The time (using the radio controllers internal 1 ms + interval superframe timer) of the last beacon from + this device was received. + +What: /sys/class/uwb_rc/uwbN/<EUI-48>/DevAddr +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + The current DevAddr of this device in colon separated + hex octets. + +What: /sys/class/uwb_rc/uwbN/<EUI-48>/EUI_48 +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + + The EUI-48 of this device in colon separated hex + octets. + +What: /sys/class/uwb_rc/uwbN/<EUI-48>/BPST +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + +What: /sys/class/uwb_rc/uwbN/<EUI-48>/IEs +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + The latest IEs included in this device's beacon, in + space separated hex octets with one IE per line. + +What: /sys/class/uwb_rc/uwbN/<EUI-48>/LQE +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + Link Quality Estimate - the Signal to Noise Ratio + (SNR) of all packets received from this device in dB. + This gives an estimate on a suitable PHY rate. Refer + to [ECMA-368] section 13.3 for more details. + +What: /sys/class/uwb_rc/uwbN/<EUI-48>/RSSI +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + Received Signal Strength Indication - the strength of + the received signal in dB. LQE is a more useful + measure of the radio link quality. diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi index f27be7d1a49..e8ffc70ffe1 100644 --- a/Documentation/ABI/testing/sysfs-firmware-acpi +++ b/Documentation/ABI/testing/sysfs-firmware-acpi @@ -89,7 +89,7 @@ Description: error - an interrupt that can't be accounted for above. - invalid: it's either a wakeup GPE or a GPE/Fixed Event that + invalid: it's either a GPE or a Fixed Event that doesn't have an event handler. disable: the GPE/Fixed Event is valid but disabled. @@ -117,30 +117,30 @@ Description: and other user space applications so that the machine won't shutdown when pressing the power button. # cat ff_pwr_btn - 0 + 0 enabled # press the power button for 3 times; # cat ff_pwr_btn - 3 + 3 enabled # echo disable > ff_pwr_btn # cat ff_pwr_btn - disable + 3 disabled # press the power button for 3 times; # cat ff_pwr_btn - disable + 3 disabled # echo enable > ff_pwr_btn # cat ff_pwr_btn - 4 + 4 enabled /* * this is because the status bit is set even if the enable bit is cleared, * and it triggers an ACPI fixed event when the enable bit is set again */ # press the power button for 3 times; # cat ff_pwr_btn - 7 + 7 enabled # echo disable > ff_pwr_btn # press the power button for 3 times; # echo clear > ff_pwr_btn /* clear the status bit */ # echo disable > ff_pwr_btn # cat ff_pwr_btn - 7 + 7 enabled diff --git a/Documentation/ABI/testing/sysfs-profiling b/Documentation/ABI/testing/sysfs-profiling new file mode 100644 index 00000000000..b02d8b8c173 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-profiling @@ -0,0 +1,13 @@ +What: /sys/kernel/profile +Date: September 2008 +Contact: Dave Hansen <dave@linux.vnet.ibm.com> +Description: + /sys/kernel/profile is the runtime equivalent + of the boot-time profile= option. + + You can get the same effect running: + + echo 2 > /sys/kernel/profile + + as you would by issuing profile=2 on the boot + command line. diff --git a/Documentation/ABI/testing/sysfs-wusb_cbaf b/Documentation/ABI/testing/sysfs-wusb_cbaf new file mode 100644 index 00000000000..a99c5f86a37 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-wusb_cbaf @@ -0,0 +1,100 @@ +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_* +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + Various files for managing Cable Based Association of + (wireless) USB devices. + + The sequence of operations should be: + + 1. Device is plugged in. + + 2. The connection manager (CM) sees a device with CBA capability. + (the wusb_chid etc. files in /sys/devices/blah/OURDEVICE). + + 3. The CM writes the host name, supported band groups, + and the CHID (host ID) into the wusb_host_name, + wusb_host_band_groups and wusb_chid files. These + get sent to the device and the CDID (if any) for + this host is requested. + + 4. The CM can verify that the device's supported band + groups (wusb_device_band_groups) are compatible + with the host. + + 5. The CM reads the wusb_cdid file. + + 6. The CM looks it up its database. + + - If it has a matching CHID,CDID entry, the device + has been authorized before and nothing further + needs to be done. + + - If the CDID is zero (or the CM doesn't find a + matching CDID in its database), the device is + assumed to be not known. The CM may associate + the host with device by: writing a randomly + generated CDID to wusb_cdid and then a random CK + to wusb_ck (this uploads the new CC to the + device). + + CMD may choose to prompt the user before + associating with a new device. + + 7. Device is unplugged. + + References: + [WUSB-AM] Association Models Supplement to the + Certified Wireless Universal Serial Bus + Specification, version 1.0. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_chid +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + The CHID of the host formatted as 16 space-separated + hex octets. + + Writes fetches device's supported band groups and the + the CDID for any existing association with this host. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_name +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + A friendly name for the host as a UTF-8 encoded string. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_band_groups +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + The band groups supported by the host, in the format + defined in [WUSB-AM]. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_device_band_groups +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + The band groups supported by the device, in the format + defined in [WUSB-AM]. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_cdid +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + The device's CDID formatted as 16 space-separated hex + octets. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_ck +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + Write 16 space-separated random, hex octets to + associate with the device. diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt index b8e86460046..b462bb14954 100644 --- a/Documentation/DMA-API.txt +++ b/Documentation/DMA-API.txt @@ -316,12 +316,10 @@ reduce current DMA mapping usage or delay and try again later). pci_map_sg(struct pci_dev *hwdev, struct scatterlist *sg, int nents, int direction) -Maps a scatter gather list from the block layer. - Returns: the number of physical segments mapped (this may be shorter -than <nents> passed in if the block layer determines that some -elements of the scatter/gather list are physically adjacent and thus -may be mapped with a single entry). +than <nents> passed in if some elements of the scatter/gather list are +physically or virtually adjacent and an IOMMU maps them with a single +entry). Please note that the sg cannot be mapped again if it has been mapped once. The mapping process is allowed to destroy information in the sg. diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 1615350b7b5..0a08126d309 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -6,7 +6,7 @@ # To add a new book the only step required is to add the book to the # list of DOCBOOKS. -DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ +DOCBOOKS := z8530book.xml mcabook.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ procfs-guide.xml writing_usb_driver.xml networking.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ @@ -136,7 +136,7 @@ quiet_cmd_db2ps = PS $@ %.ps : %.xml $(call cmd,db2ps) -quiet_cmd_db2pdf = PDF $@ +quiet_cmd_db2pdf = PDF $@ cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template)) %.pdf : %.xml $(call cmd,db2pdf) @@ -148,7 +148,7 @@ build_main_index = rm -rf $(main_idx) && \ echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \ cat $(HTML) >> $(main_idx) -quiet_cmd_db2html = HTML $@ +quiet_cmd_db2html = HTML $@ cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ diff --git a/Documentation/DocBook/deviceiobook.tmpl b/Documentation/DocBook/deviceiobook.tmpl index 9ee6f3cbb41..3ed88126ab8 100644 --- a/Documentation/DocBook/deviceiobook.tmpl +++ b/Documentation/DocBook/deviceiobook.tmpl @@ -24,7 +24,7 @@ <surname>Cox</surname> <affiliation> <address> - <email>alan@redhat.com</email> + <email>alan@lxorguk.ukuu.org.uk</email> </address> </affiliation> </author> @@ -316,7 +316,7 @@ CPU B: spin_unlock_irqrestore(&dev_lock, flags) <chapter id="pubfunctions"> <title>Public Functions Provided</title> -!Iinclude/asm-x86/io_32.h +!Iarch/x86/include/asm/io_32.h !Elib/iomap.c </chapter> diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl index ea3bc9565e6..6ef2f0073e5 100644 --- a/Documentation/DocBook/gadget.tmpl +++ b/Documentation/DocBook/gadget.tmpl @@ -557,6 +557,9 @@ Near-term plans include converting all of them, except for "gadgetfs". </para> !Edrivers/usb/gadget/f_acm.c +!Edrivers/usb/gadget/f_ecm.c +!Edrivers/usb/gadget/f_subset.c +!Edrivers/usb/gadget/f_obex.c !Edrivers/usb/gadget/f_serial.c </sect1> diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 9d0058e788e..5818ff75786 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -45,8 +45,8 @@ </sect1> <sect1><title>Atomic and pointer manipulation</title> -!Iinclude/asm-x86/atomic_32.h -!Iinclude/asm-x86/unaligned.h +!Iarch/x86/include/asm/atomic_32.h +!Iarch/x86/include/asm/unaligned.h </sect1> <sect1><title>Delaying, scheduling, and timer routines</title> @@ -119,7 +119,7 @@ X!Ilib/string.c !Elib/string.c </sect1> <sect1><title>Bit Operations</title> -!Iinclude/asm-x86/bitops.h +!Iarch/x86/include/asm/bitops.h </sect1> </chapter> @@ -155,7 +155,7 @@ X!Ilib/string.c !Emm/slab.c </sect1> <sect1><title>User Space Memory Access</title> -!Iinclude/asm-x86/uaccess_32.h +!Iarch/x86/include/asm/uaccess_32.h !Earch/x86/lib/usercopy_32.c </sect1> <sect1><title>More Memory Management Functions</title> @@ -265,7 +265,7 @@ X!Earch/x86/kernel/mca_32.c --> </sect2> <sect2><title>MCA Bus DMA</title> -!Iinclude/asm-x86/mca_dma.h +!Iarch/x86/include/asm/mca_dma.h </sect2> </sect1> </chapter> diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl index 4c63e586416..a50d6cd5857 100644 --- a/Documentation/DocBook/kernel-hacking.tmpl +++ b/Documentation/DocBook/kernel-hacking.tmpl @@ -1105,7 +1105,7 @@ static struct block_device_operations opt_fops = { </listitem> <listitem> <para> - Function names as strings (__FUNCTION__). + Function names as strings (__func__). </para> </listitem> <listitem> @@ -1239,7 +1239,7 @@ static struct block_device_operations opt_fops = { </para> <para> - <filename>include/asm-x86/delay_32.h:</filename> + <filename>arch/x86/include/asm/delay.h:</filename> </para> <programlisting> #define ndelay(n) (__builtin_constant_p(n) ? \ @@ -1265,7 +1265,7 @@ static struct block_device_operations opt_fops = { </programlisting> <para> - <filename>include/asm-x86/uaccess_32.h:</filename> + <filename>arch/x86/include/asm/uaccess_32.h:</filename> </para> <programlisting> diff --git a/Documentation/DocBook/mcabook.tmpl b/Documentation/DocBook/mcabook.tmpl index 529a53dc138..467ccac6ec5 100644 --- a/Documentation/DocBook/mcabook.tmpl +++ b/Documentation/DocBook/mcabook.tmpl @@ -12,7 +12,7 @@ <surname>Cox</surname> <affiliation> <address> - <email>alan@redhat.com</email> + <email>alan@lxorguk.ukuu.org.uk</email> </address> </affiliation> </author> @@ -101,7 +101,7 @@ <chapter id="dmafunctions"> <title>DMA Functions Provided</title> -!Iinclude/asm-x86/mca_dma.h +!Iarch/x86/include/asm/mca_dma.h </chapter> </book> diff --git a/Documentation/DocBook/networking.tmpl b/Documentation/DocBook/networking.tmpl index f24f9e85e4a..627707a3cb9 100644 --- a/Documentation/DocBook/networking.tmpl +++ b/Documentation/DocBook/networking.tmpl @@ -98,9 +98,6 @@ X!Enet/core/wireless.c </sect1> --> - <sect1><title>Synchronous PPP</title> -!Edrivers/net/wan/syncppp.c - </sect1> </chapter> </book> diff --git a/Documentation/DocBook/procfs-guide.tmpl b/Documentation/DocBook/procfs-guide.tmpl index 8a5dc6e021f..9eba4b7af73 100644 --- a/Documentation/DocBook/procfs-guide.tmpl +++ b/Documentation/DocBook/procfs-guide.tmpl @@ -14,17 +14,20 @@ <othername>(J.A.K.)</othername> <surname>Mouw</surname> <affiliation> - <orgname>Delft University of Technology</orgname> - <orgdiv>Faculty of Information Technology and Systems</orgdiv> <address> - <email>J.A.K.Mouw@its.tudelft.nl</email> - <pob>PO BOX 5031</pob> - <postcode>2600 GA</postcode> - <city>Delft</city> - <country>The Netherlands</country> + <email>mouw@nl.linux.org</email> </address> </affiliation> </author> + <othercredit> + <contrib> + This software and documentation were written while working on the + LART computing board + (<ulink url="http://www.lartmaker.nl/">http://www.lartmaker.nl/</ulink>), + which was sponsored by the Delt University of Technology projects + Mobile Multi-media Communications and Ubiquitous Communications. + </contrib> + </othercredit> </authorgroup> <revhistory> @@ -109,18 +112,6 @@ </para> <para> - This documentation was written while working on the LART - computing board (<ulink - url="http://www.lart.tudelft.nl/">http://www.lart.tudelft.nl/</ulink>), - which is sponsored by the Mobile Multi-media Communications - (<ulink - url="http://www.mmc.tudelft.nl/">http://www.mmc.tudelft.nl/</ulink>) - and Ubiquitous Communications (<ulink - url="http://www.ubicom.tudelft.nl/">http://www.ubicom.tudelft.nl/</ulink>) - projects. - </para> - - <para> Erik </para> </preface> diff --git a/Documentation/DocBook/procfs_example.c b/Documentation/DocBook/procfs_example.c index 2f3de0fb836..8c6396e4bf3 100644 --- a/Documentation/DocBook/procfs_example.c +++ b/Documentation/DocBook/procfs_example.c @@ -1,28 +1,16 @@ /* * procfs_example.c: an example proc interface * - * Copyright (C) 2001, Erik Mouw (J.A.K.Mouw@its.tudelft.nl) + * Copyright (C) 2001, Erik Mouw (mouw@nl.linux.org) * * This file accompanies the procfs-guide in the Linux kernel * source. Its main use is to demonstrate the concepts and * functions described in the guide. * * This software has been developed while working on the LART - * computing board (http://www.lart.tudelft.nl/), which is - * sponsored by the Mobile Multi-media Communications - * (http://www.mmc.tudelft.nl/) and Ubiquitous Communications - * (http://www.ubicom.tudelft.nl/) projects. - * - * The author can be reached at: - * - * Erik Mouw - * Information and Communication Theory Group - * Faculty of Information Technology and Systems - * Delft University of Technology - * P.O. Box 5031 - * 2600 GA Delft - * The Netherlands - * + * computing board (http://www.lartmaker.nl), which was sponsored + * by the Delt University of Technology projects Mobile Multi-media + * Communications and Ubiquitous Communications. * * This program is free software; you can redistribute * it and/or modify it under the terms of the GNU General diff --git a/Documentation/DocBook/videobook.tmpl b/Documentation/DocBook/videobook.tmpl deleted file mode 100644 index 0bc25949b66..00000000000 --- a/Documentation/DocBook/videobook.tmpl +++ /dev/null @@ -1,1654 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="V4LGuide"> - <bookinfo> - <title>Video4Linux Programming</title> - - <authorgroup> - <author> - <firstname>Alan</firstname> - <surname>Cox</surname> - <affiliation> - <address> - <email>alan@redhat.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2000</year> - <holder>Alan Cox</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - Parts of this document first appeared in Linux Magazine under a - ninety day exclusivity. - </para> - <para> - Video4Linux is intended to provide a common programming interface - for the many TV and capture cards now on the market, as well as - parallel port and USB video cameras. Radio, teletext decoders and - vertical blanking data interfaces are also provided. - </para> - </chapter> - <chapter id="radio"> - <title>Radio Devices</title> - <para> - There are a wide variety of radio interfaces available for PC's, and these - are generally very simple to program. The biggest problem with supporting - such devices is normally extracting documentation from the vendor. - </para> - <para> - The radio interface supports a simple set of control ioctls standardised - across all radio and tv interfaces. It does not support read or write, which - are used for video streams. The reason radio cards do not allow you to read - the audio stream into an application is that without exception they provide - a connection on to a soundcard. Soundcards can be used to read the radio - data just fine. - </para> - <sect1 id="registerradio"> - <title>Registering Radio Devices</title> - <para> - The Video4linux core provides an interface for registering devices. The - first step in writing our radio card driver is to register it. - </para> - <programlisting> - - -static struct video_device my_radio -{ - "My radio", - VID_TYPE_TUNER, - radio_open. - radio_close, - NULL, /* no read */ - NULL, /* no write */ - NULL, /* no poll */ - radio_ioctl, - NULL, /* no special init function */ - NULL /* no private data */ -}; - - - </programlisting> - <para> - This declares our video4linux device driver interface. The VID_TYPE_ value - defines what kind of an interface we are, and defines basic capabilities. - </para> - <para> - The only defined value relevant for a radio card is VID_TYPE_TUNER which - indicates that the device can be tuned. Clearly our radio is going to have some - way to change channel so it is tuneable. - </para> - <para> - We declare an open and close routine, but we do not need read or write, - which are used to read and write video data to or from the card itself. As - we have no read or write there is no poll function. - </para> - <para> - The private initialise function is run when the device is registered. In - this driver we've already done all the work needed. The final pointer is a - private data pointer that can be used by the device driver to attach and - retrieve private data structures. We set this field "priv" to NULL for - the moment. - </para> - <para> - Having the structure defined is all very well but we now need to register it - with the kernel. - </para> - <programlisting> - - -static int io = 0x320; - -int __init myradio_init(struct video_init *v) -{ - if(!request_region(io, MY_IO_SIZE, "myradio")) - { - printk(KERN_ERR - "myradio: port 0x%03X is in use.\n", io); - return -EBUSY; - } - - if(video_device_register(&my_radio, VFL_TYPE_RADIO)==-1) { - release_region(io, MY_IO_SIZE); - return -EINVAL; - } - return 0; -} - - </programlisting> - <para> - The first stage of the initialisation, as is normally the case, is to check - that the I/O space we are about to fiddle with doesn't belong to some other - driver. If it is we leave well alone. If the user gives the address of the - wrong device then we will spot this. These policies will generally avoid - crashing the machine. - </para> - <para> - Now we ask the Video4Linux layer to register the device for us. We hand it - our carefully designed video_device structure and also tell it which group - of devices we want it registered with. In this case VFL_TYPE_RADIO. - </para> - <para> - The types available are - </para> - <table frame="all" id="Device_Types"><title>Device Types</title> - <tgroup cols="3" align="left"> - <tbody> - <row> - <entry>VFL_TYPE_RADIO</entry><entry>/dev/radio{n}</entry><entry> - - Radio devices are assigned in this block. As with all of these - selections the actual number assignment is done by the video layer - accordijng to what is free.</entry> - </row><row> - <entry>VFL_TYPE_GRABBER</entry><entry>/dev/video{n}</entry><entry> - Video capture devices and also -- counter-intuitively for the name -- - hardware video playback devices such as MPEG2 cards.</entry> - </row><row> - <entry>VFL_TYPE_VBI</entry><entry>/dev/vbi{n}</entry><entry> - The VBI devices capture the hidden lines on a television picture - that carry further information like closed caption data, teletext - (primarily in Europe) and now Intercast and the ATVEC internet - television encodings.</entry> - </row><row> - <entry>VFL_TYPE_VTX</entry><entry>/dev/vtx[n}</entry><entry> - VTX is 'Videotext' also known as 'Teletext'. This is a system for - sending numbered, 40x25, mostly textual page images over the hidden - lines. Unlike the /dev/vbi interfaces, this is for 'smart' decoder - chips. (The use of the word smart here has to be taken in context, - the smartest teletext chips are fairly dumb pieces of technology). - </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - We are most definitely a radio. - </para> - <para> - Finally we allocate our I/O space so that nobody treads on us and return 0 - to signify general happiness with the state of the universe. - </para> - </sect1> - <sect1 id="openradio"> - <title>Opening And Closing The Radio</title> - - <para> - The functions we declared in our video_device are mostly very simple. - Firstly we can drop in what is basically standard code for open and close. - </para> - <programlisting> - - -static int users = 0; - -static int radio_open(struct video_device *dev, int flags) -{ - if(users) - return -EBUSY; - users++; - return 0; -} - - </programlisting> - <para> - At open time we need to do nothing but check if someone else is also using - the radio card. If nobody is using it we make a note that we are using it, - then we ensure that nobody unloads our driver on us. - </para> - <programlisting> - - -static int radio_close(struct video_device *dev) -{ - users--; -} - - </programlisting> - <para> - At close time we simply need to reduce the user count and allow the module - to become unloadable. - </para> - <para> - If you are sharp you will have noticed neither the open nor the close - routines attempt to reset or change the radio settings. This is intentional. - It allows an application to set up the radio and exit. It avoids a user - having to leave an application running all the time just to listen to the - radio. - </para> - </sect1> - <sect1 id="ioctlradio"> - <title>The Ioctl Interface</title> - <para> - This leaves the ioctl routine, without which the driver will not be - terribly useful to anyone. - </para> - <programlisting> - - -static int radio_ioctl(struct video_device *dev, unsigned int cmd, void *arg) -{ - switch(cmd) - { - case VIDIOCGCAP: - { - struct video_capability v; - v.type = VID_TYPE_TUNER; - v.channels = 1; - v.audios = 1; - v.maxwidth = 0; - v.minwidth = 0; - v.maxheight = 0; - v.minheight = 0; - strcpy(v.name, "My Radio"); - if(copy_to_user(arg, &v, sizeof(v))) - return -EFAULT; - return 0; - } - - </programlisting> - <para> - VIDIOCGCAP is the first ioctl all video4linux devices must support. It - allows the applications to find out what sort of a card they have found and - to figure out what they want to do about it. The fields in the structure are - </para> - <table frame="all" id="video_capability_fields"><title>struct video_capability fields</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>name</entry><entry>The device text name. This is intended for the user.</entry> - </row><row> - <entry>channels</entry><entry>The number of different channels you can tune on - this card. It could even by zero for a card that has - no tuning capability. For our simple FM radio it is 1. - An AM/FM radio would report 2.</entry> - </row><row> - <entry>audios</entry><entry>The number of audio inputs on this device. For our - radio there is only one audio input.</entry> - </row><row> - <entry>minwidth,minheight</entry><entry>The smallest size the card is capable of capturing - images in. We set these to zero. Radios do not - capture pictures</entry> - </row><row> - <entry>maxwidth,maxheight</entry><entry>The largest image size the card is capable of - capturing. For our radio we report 0. - </entry> - </row><row> - <entry>type</entry><entry>This reports the capabilities of the device, and - matches the field we filled in in the struct - video_device when registering.</entry> - </row> - </tbody> - </tgroup> - </table> - <para> - Having filled in the fields, we use copy_to_user to copy the structure into - the users buffer. If the copy fails we return an EFAULT to the application - so that it knows it tried to feed us garbage. - </para> - <para> - The next pair of ioctl operations select which tuner is to be used and let - the application find the tuner properties. We have only a single FM band - tuner in our example device. - </para> - <programlisting> - - - case VIDIOCGTUNER: - { - struct video_tuner v; - if(copy_from_user(&v, arg, sizeof(v))!=0) - return -EFAULT; - if(v.tuner) - return -EINVAL; - v.rangelow=(87*16000); - v.rangehigh=(108*16000); - v.flags = VIDEO_TUNER_LOW; - v.mode = VIDEO_MODE_AUTO; - v.signal = 0xFFFF; - strcpy(v.name, "FM"); - if(copy_to_user(&v, arg, sizeof(v))!=0) - return -EFAULT; - return 0; - } - - </programlisting> - <para> - The VIDIOCGTUNER ioctl allows applications to query a tuner. The application - sets the tuner field to the tuner number it wishes to query. The query does - not change the tuner that is being used, it merely enquires about the tuner - in question. - </para> - <para> - We have exactly one tuner so after copying the user buffer to our temporary - structure we complain if they asked for a tuner other than tuner 0. - </para> - <para> - The video_tuner structure has the following fields - </para> - <table frame="all" id="video_tuner_fields"><title>struct video_tuner fields</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>int tuner</entry><entry>The number of the tuner in question</entry> - </row><row> - <entry>char name[32]</entry><entry>A text description of this tuner. "FM" will do fine. - This is intended for the application.</entry> - </row><row> - <entry>u32 flags</entry> - <entry>Tuner capability flags</entry> - </row> - <row> - <entry>u16 mode</entry><entry>The current reception mode</entry> - - </row><row> - <entry>u16 signal</entry><entry>The signal strength scaled between 0 and 65535. If - a device cannot tell the signal strength it should - report 65535. Many simple cards contain only a - signal/no signal bit. Such cards will report either - 0 or 65535.</entry> - - </row><row> - <entry>u32 rangelow, rangehigh</entry><entry> - The range of frequencies supported by the radio - or TV. It is scaled according to the VIDEO_TUNER_LOW - flag.</entry> - - </row> - </tbody> - </tgroup> - </table> - - <table frame="all" id="video_tuner_flags"><title>struct video_tuner flags</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>VIDEO_TUNER_PAL</entry><entry>A PAL TV tuner</entry> - </row><row> - <entry>VIDEO_TUNER_NTSC</entry><entry>An NTSC (US) TV tuner</entry> - </row><row> - <entry>VIDEO_TUNER_SECAM</entry><entry>A SECAM (French) TV tuner</entry> - </row><row> - <entry>VIDEO_TUNER_LOW</entry><entry> - The tuner frequency is scaled in 1/16th of a KHz - steps. If not it is in 1/16th of a MHz steps - </entry> - </row><row> - <entry>VIDEO_TUNER_NORM</entry><entry>The tuner can set its format</entry> - </row><row> - <entry>VIDEO_TUNER_STEREO_ON</entry><entry>The tuner is currently receiving a stereo signal</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="all" id="video_tuner_modes"><title>struct video_tuner modes</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>VIDEO_MODE_PAL</entry><entry>PAL Format</entry> - </row><row> - <entry>VIDEO_MODE_NTSC</entry><entry>NTSC Format (USA)</entry> - </row><row> - <entry>VIDEO_MODE_SECAM</entry><entry>French Format</entry> - </row><row> - <entry>VIDEO_MODE_AUTO</entry><entry>A device that does not need to do - TV format switching</entry> - </row> - </tbody> - </tgroup> - </table> - <para> - The settings for the radio card are thus fairly simple. We report that we - are a tuner called "FM" for FM radio. In order to get the best tuning - resolution we report VIDEO_TUNER_LOW and select tuning to 1/16th of KHz. Its - unlikely our card can do that resolution but it is a fair bet the card can - do better than 1/16th of a MHz. VIDEO_TUNER_LOW is appropriate to almost all - radio usage. - </para> - <para> - We report that the tuner automatically handles deciding what format it is - receiving - true enough as it only handles FM radio. Our example card is - also incapable of detecting stereo or signal strengths so it reports a - strength of 0xFFFF (maximum) and no stereo detected. - </para> - <para> - To finish off we set the range that can be tuned to be 87-108Mhz, the normal - FM broadcast radio range. It is important to find out what the card is - actually capable of tuning. It is easy enough to simply use the FM broadcast - range. Unfortunately if you do this you will discover the FM broadcast - ranges in the USA, Europe and Japan are all subtly different and some users - cannot receive all the stations they wish. - </para> - <para> - The application also needs to be able to set the tuner it wishes to use. In - our case, with a single tuner this is rather simple to arrange. - </para> - <programlisting> - - case VIDIOCSTUNER: - { - struct video_tuner v; - if(copy_from_user(&v, arg, sizeof(v))) - return -EFAULT; - if(v.tuner != 0) - return -EINVAL; - return 0; - } - - </programlisting> - <para> - We copy the user supplied structure into kernel memory so we can examine it. - If the user has selected a tuner other than zero we reject the request. If - they wanted tuner 0 then, surprisingly enough, that is the current tuner already. - </para> - <para> - The next two ioctls we need to provide are to get and set the frequency of - the radio. These both use an unsigned long argument which is the frequency. - The scale of the frequency depends on the VIDEO_TUNER_LOW flag as I - mentioned earlier on. Since we have VIDEO_TUNER_LOW set this will be in - 1/16ths of a KHz. - </para> - <programlisting> - -static unsigned long current_freq; - - - - case VIDIOCGFREQ: - if(copy_to_user(arg, &current_freq, - sizeof(unsigned long)) - return -EFAULT; - return 0; - - </programlisting> - <para> - Querying the frequency in our case is relatively simple. Our radio card is - too dumb to let us query the signal strength so we remember our setting if - we know it. All we have to do is copy it to the user. - </para> - <programlisting> - - - case VIDIOCSFREQ: - { - u32 freq; - if(copy_from_user(arg, &freq, - sizeof(unsigned long))!=0) - return -EFAULT; - if(hardware_set_freq(freq)<0) - return -EINVAL; - current_freq = freq; - return 0; - } - - </programlisting> - <para> - Setting the frequency is a little more complex. We begin by copying the - desired frequency into kernel space. Next we call a hardware specific routine - to set the radio up. This might be as simple as some scaling and a few - writes to an I/O port. For most radio cards it turns out a good deal more - complicated and may involve programming things like a phase locked loop on - the card. This is what documentation is for. - </para> - <para> - The final set of operations we need to provide for our radio are the - volume controls. Not all radio cards can even do volume control. After all - there is a perfectly good volume control on the sound card. We will assume - our radio card has a simple 4 step volume control. - </para> - <para> - There are two ioctls with audio we need to support - </para> - <programlisting> - -static int current_volume=0; - - case VIDIOCGAUDIO: - { - struct video_audio v; - if(copy_from_user(&v, arg, sizeof(v))) - return -EFAULT; - if(v.audio != 0) - return -EINVAL; - v.volume = 16384*current_volume; - v.step = 16384; - strcpy(v.name, "Radio"); - v.mode = VIDEO_SOUND_MONO; - v.balance = 0; - v.base = 0; - v.treble = 0; - - if(copy_to_user(arg. &v, sizeof(v))) - return -EFAULT; - return 0; - } - - </programlisting> - <para> - Much like the tuner we start by copying the user structure into kernel - space. Again we check if the user has asked for a valid audio input. We have - only input 0 and we punt if they ask for another input. - </para> - <para> - Then we fill in the video_audio structure. This has the following format - </para> - <table frame="all" id="video_audio_fields"><title>struct video_audio fields</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>audio</entry><entry>The input the user wishes to query</entry> - </row><row> - <entry>volume</entry><entry>The volume setting on a scale of 0-65535</entry> - </row><row> - <entry>base</entry><entry>The base level on a scale of 0-65535</entry> - </row><row> - <entry>treble</entry><entry>The treble level on a scale of 0-65535</entry> - </row><row> - <entry>flags</entry><entry>The features this audio device supports - </entry> - </row><row> - <entry>name</entry><entry>A text name to display to the user. We picked - "Radio" as it explains things quite nicely.</entry> - </row><row> - <entry>mode</entry><entry>The current reception mode for the audio - - We report MONO because our card is too stupid to know if it is in - mono or stereo. - </entry> - </row><row> - <entry>balance</entry><entry>The stereo balance on a scale of 0-65535, 32768 is - middle.</entry> - </row><row> - <entry>step</entry><entry>The step by which the volume control jumps. This is - used to help make it easy for applications to set - slider behaviour.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="all" id="video_audio_flags"><title>struct video_audio flags</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>VIDEO_AUDIO_MUTE</entry><entry>The audio is currently muted. We - could fake this in our driver but we - choose not to bother.</entry> - </row><row> - <entry>VIDEO_AUDIO_MUTABLE</entry><entry>The input has a mute option</entry> - </row><row> - <entry>VIDEO_AUDIO_TREBLE</entry><entry>The input has a treble control</entry> - </row><row> - <entry>VIDEO_AUDIO_BASS</entry><entry>The input has a base control</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="all" id="video_audio_modes"><title>struct video_audio modes</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>VIDEO_SOUND_MONO</entry><entry>Mono sound</entry> - </row><row> - <entry>VIDEO_SOUND_STEREO</entry><entry>Stereo sound</entry> - </row><row> - <entry>VIDEO_SOUND_LANG1</entry><entry>Alternative language 1 (TV specific)</entry> - </row><row> - <entry>VIDEO_SOUND_LANG2</entry><entry>Alternative language 2 (TV specific)</entry> - </row> - </tbody> - </tgroup> - </table> - <para> - Having filled in the structure we copy it back to user space. - </para> - <para> - The VIDIOCSAUDIO ioctl allows the user to set the audio parameters in the - video_audio structure. The driver does its best to honour the request. - </para> - <programlisting> - - case VIDIOCSAUDIO: - { - struct video_audio v; - if(copy_from_user(&v, arg, sizeof(v))) - return -EFAULT; - if(v.audio) - return -EINVAL; - current_volume = v/16384; - hardware_set_volume(current_volume); - return 0; - } - - </programlisting> - <para> - In our case there is very little that the user can set. The volume is - basically the limit. Note that we could pretend to have a mute feature - by rewriting this to - </para> - <programlisting> - - case VIDIOCSAUDIO: - { - struct video_audio v; - if(copy_from_user(&v, arg, sizeof(v))) - return -EFAULT; - if(v.audio) - return -EINVAL; - current_volume = v/16384; - if(v.flags&VIDEO_AUDIO_MUTE) - hardware_set_volume(0); - else - hardware_set_volume(current_volume); - current_muted = v.flags & - VIDEO_AUDIO_MUTE; - return 0; - } - - </programlisting> - <para> - This with the corresponding changes to the VIDIOCGAUDIO code to report the - state of the mute flag we save and to report the card has a mute function, - will allow applications to use a mute facility with this card. It is - questionable whether this is a good idea however. User applications can already - fake this themselves and kernel space is precious. - </para> - <para> - We now have a working radio ioctl handler. So we just wrap up the function - </para> - <programlisting> - - - } - return -ENOIOCTLCMD; -} - - </programlisting> - <para> - and pass the Video4Linux layer back an error so that it knows we did not - understand the request we got passed. - </para> - </sect1> - <sect1 id="modradio"> - <title>Module Wrapper</title> - <para> - Finally we add in the usual module wrapping and the driver is done. - </para> - <programlisting> - -#ifndef MODULE - -static int io = 0x300; - -#else - -static int io = -1; - -#endif - -MODULE_AUTHOR("Alan Cox"); -MODULE_DESCRIPTION("A driver for an imaginary radio card."); -module_param(io, int, 0444); -MODULE_PARM_DESC(io, "I/O address of the card."); - -static int __init init(void) -{ - if(io==-1) - { - printk(KERN_ERR - "You must set an I/O address with io=0x???\n"); - return -EINVAL; - } - return myradio_init(NULL); -} - -static void __exit cleanup(void) -{ - video_unregister_device(&my_radio); - release_region(io, MY_IO_SIZE); -} - -module_init(init); -module_exit(cleanup); - - </programlisting> - <para> - In this example we set the IO base by default if the driver is compiled into - the kernel: you can still set it using "my_radio.irq" if this file is called <filename>my_radio.c</filename>. For the module we require the - user sets the parameter. We set io to a nonsense port (-1) so that we can - tell if the user supplied an io parameter or not. - </para> - <para> - We use MODULE_ defines to give an author for the card driver and a - description. We also use them to declare that io is an integer and it is the - address of the card, and can be read by anyone from sysfs. - </para> - <para> - The clean-up routine unregisters the video_device we registered, and frees - up the I/O space. Note that the unregister takes the actual video_device - structure as its argument. Unlike the file operations structure which can be - shared by all instances of a device a video_device structure as an actual - instance of the device. If you are registering multiple radio devices you - need to fill in one structure per device (most likely by setting up a - template and copying it to each of the actual device structures). - </para> - </sect1> - </chapter> - <chapter id="Video_Capture_Devices"> - <title>Video Capture Devices</title> - <sect1 id="introvid"> - <title>Video Capture Device Types</title> - <para> - The video capture devices share the same interfaces as radio devices. In - order to explain the video capture interface I will use the example of a - camera that has no tuners or audio input. This keeps the example relatively - clean. To get both combine the two driver examples. - </para> - <para> - Video capture devices divide into four categories. A little technology - backgrounder. Full motion video even at television resolution (which is - actually fairly low) is pretty resource-intensive. You are continually - passing megabytes of data every second from the capture card to the display. - several alternative approaches have emerged because copying this through the - processor and the user program is a particularly bad idea . - </para> - <para> - The first is to add the television image onto the video output directly. - This is also how some 3D cards work. These basic cards can generally drop the - video into any chosen rectangle of the display. Cards like this, which - include most mpeg1 cards that used the feature connector, aren't very - friendly in a windowing environment. They don't understand windows or - clipping. The video window is always on the top of the display. - </para> - <para> - Chroma keying is a technique used by cards to get around this. It is an old - television mixing trick where you mark all the areas you wish to replace - with a single clear colour that isn't used in the image - TV people use an - incredibly bright blue while computing people often use a particularly - virulent purple. Bright blue occurs on the desktop. Anyone with virulent - purple windows has another problem besides their TV overlay. - </para> - <para> - The third approach is to copy the data from the capture card to the video - card, but to do it directly across the PCI bus. This relieves the processor - from doing the work but does require some smartness on the part of the video - capture chip, as well as a suitable video card. Programming this kind of - card and more so debugging it can be extremely tricky. There are some quite - complicated interactions with the display and you may also have to cope with - various chipset bugs that show up when PCI cards start talking to each - other. - </para> - <para> - To keep our example fairly simple we will assume a card that supports - overlaying a flat rectangular image onto the frame buffer output, and which - can also capture stuff into processor memory. - </para> - </sect1> - <sect1 id="regvid"> - <title>Registering Video Capture Devices</title> - <para> - This time we need to add more functions for our camera device. - </para> - <programlisting> -static struct video_device my_camera -{ - "My Camera", - VID_TYPE_OVERLAY|VID_TYPE_SCALES|\ - VID_TYPE_CAPTURE|VID_TYPE_CHROMAKEY, - camera_open. - camera_close, - camera_read, /* no read */ - NULL, /* no write */ - camera_poll, /* no poll */ - camera_ioctl, - NULL, /* no special init function */ - NULL /* no private data */ -}; - </programlisting> - <para> - We need a read() function which is used for capturing data from - the card, and we need a poll function so that a driver can wait for the next - frame to be captured. - </para> - <para> - We use the extra video capability flags that did not apply to the - radio interface. The video related flags are - </para> - <table frame="all" id="Capture_Capabilities"><title>Capture Capabilities</title> - <tgroup cols="2" align="left"> - <tbody> - <row> -<entry>VID_TYPE_CAPTURE</entry><entry>We support image capture</entry> -</row><row> -<entry>VID_TYPE_TELETEXT</entry><entry>A teletext capture device (vbi{n])</entry> -</row><row> -<entry>VID_TYPE_OVERLAY</entry><entry>The image can be directly overlaid onto the - frame buffer</entry> -</row><row> -<entry>VID_TYPE_CHROMAKEY</entry><entry>Chromakey can be used to select which parts - of the image to display</entry> -</row><row> -<entry>VID_TYPE_CLIPPING</entry><entry>It is possible to give the board a list of - rectangles to draw around. </entry> -</row><row> -<entry>VID_TYPE_FRAMERAM</entry><entry>The video capture goes into the video memory - and actually changes it. Applications need - to know this so they can clean up after the - card</entry> -</row><row> -<entry>VID_TYPE_SCALES</entry><entry>The image can be scaled to various sizes, - rather than being a single fixed size.</entry> -</row><row> -<entry>VID_TYPE_MONOCHROME</entry><entry>The capture will be monochrome. This isn't a - complete answer to the question since a mono - camera on a colour capture card will still - produce mono output.</entry> -</row><row> -<entry>VID_TYPE_SUBCAPTURE</entry><entry>The card allows only part of its field of - view to be captured. This enables - applications to avoid copying all of a large - image into memory when only some section is - relevant.</entry> - </row> - </tbody> - </tgroup> - </table> - <para> - We set VID_TYPE_CAPTURE so that we are seen as a capture card, - VID_TYPE_CHROMAKEY so the application knows it is time to draw in virulent - purple, and VID_TYPE_SCALES because we can be resized. - </para> - <para> - Our setup is fairly similar. This time we also want an interrupt line - for the 'frame captured' signal. Not all cards have this so some of them - cannot handle poll(). - </para> - <programlisting> - - -static int io = 0x320; -static int irq = 11; - -int __init mycamera_init(struct video_init *v) -{ - if(!request_region(io, MY_IO_SIZE, "mycamera")) - { - printk(KERN_ERR - "mycamera: port 0x%03X is in use.\n", io); - return -EBUSY; - } - - if(video_device_register(&my_camera, - VFL_TYPE_GRABBER)==-1) { - release_region(io, MY_IO_SIZE); - return -EINVAL; - } - return 0; -} - - </programlisting> - <para> - This is little changed from the needs of the radio card. We specify - VFL_TYPE_GRABBER this time as we want to be allocated a /dev/video name. - </para> - </sect1> - <sect1 id="opvid"> - <title>Opening And Closing The Capture Device</title> - <programlisting> - - -static int users = 0; - -static int camera_open(struct video_device *dev, int flags) -{ - if(users) - return -EBUSY; - if(request_irq(irq, camera_irq, 0, "camera", dev)<0) - return -EBUSY; - users++; - return 0; -} - - -static int camera_close(struct video_device *dev) -{ - users--; - free_irq(irq, dev); -} - </programlisting> - <para> - The open and close routines are also quite similar. The only real change is - that we now request an interrupt for the camera device interrupt line. If we - cannot get the interrupt we report EBUSY to the application and give up. - </para> - </sect1> - <sect1 id="irqvid"> - <title>Interrupt Handling</title> - <para> - Our example handler is for an ISA bus device. If it was PCI you would be - able to share the interrupt and would have set IRQF_SHARED to indicate a - shared IRQ. We pass the device pointer as the interrupt routine argument. We - don't need to since we only support one card but doing this will make it - easier to upgrade the driver for multiple devices in the future. - </para> - <para> - Our interrupt routine needs to do little if we assume the card can simply - queue one frame to be read after it captures it. - </para> - <programlisting> - - -static struct wait_queue *capture_wait; -static int capture_ready = 0; - -static void camera_irq(int irq, void *dev_id, - struct pt_regs *regs) -{ - capture_ready=1; - wake_up_interruptible(&capture_wait); -} - </programlisting> - <para> - The interrupt handler is nice and simple for this card as we are assuming - the card is buffering the frame for us. This means we have little to do but - wake up anybody interested. We also set a capture_ready flag, as we may - capture a frame before an application needs it. In this case we need to know - that a frame is ready. If we had to collect the frame on the interrupt life - would be more complex. - </para> - <para> - The two new routines we need to supply are camera_read which returns a - frame, and camera_poll which waits for a frame to become ready. - </para> - <programlisting> - - -static int camera_poll(struct video_device *dev, - struct file *file, struct poll_table *wait) -{ - poll_wait(file, &capture_wait, wait); - if(capture_read) - return POLLIN|POLLRDNORM; - return 0; -} - - </programlisting> - <para> - Our wait queue for polling is the capture_wait queue. This will cause the - task to be woken up by our camera_irq routine. We check capture_read to see - if there is an image present and if so report that it is readable. - </para> - </sect1> - <sect1 id="rdvid"> - <title>Reading The Video Image</title> - <programlisting> - - -static long camera_read(struct video_device *dev, char *buf, - unsigned long count) -{ - struct wait_queue wait = { current, NULL }; - u8 *ptr; - int len; - int i; - - add_wait_queue(&capture_wait, &wait); - - while(!capture_ready) - { - if(file->flags&O_NDELAY) - { - remove_wait_queue(&capture_wait, &wait); - current->state = TASK_RUNNING; - return -EWOULDBLOCK; - } - if(signal_pending(current)) - { - remove_wait_queue(&capture_wait, &wait); - current->state = TASK_RUNNING; - return -ERESTARTSYS; - } - schedule(); - current->state = TASK_INTERRUPTIBLE; - } - remove_wait_queue(&capture_wait, &wait); - current->state = TASK_RUNNING; - - </programlisting> - <para> - The first thing we have to do is to ensure that the application waits until - the next frame is ready. The code here is almost identical to the mouse code - we used earlier in this chapter. It is one of the common building blocks of - Linux device driver code and probably one which you will find occurs in any - drivers you write. - </para> - <para> - We wait for a frame to be ready, or for a signal to interrupt our waiting. If a - signal occurs we need to return from the system call so that the signal can - be sent to the application itself. We also check to see if the user actually - wanted to avoid waiting - ie if they are using non-blocking I/O and have other things - to get on with. - </para> - <para> - Next we copy the data from the card to the user application. This is rarely - as easy as our example makes out. We will add capture_w, and capture_h here - to hold the width and height of the captured image. We assume the card only - supports 24bit RGB for now. - </para> - <programlisting> - - - - capture_ready = 0; - - ptr=(u8 *)buf; - len = capture_w * 3 * capture_h; /* 24bit RGB */ - - if(len>count) - len=count; /* Doesn't all fit */ - - for(i=0; i<len; i++) - { - put_user(inb(io+IMAGE_DATA), ptr); - ptr++; - } - - hardware_restart_capture(); - - return i; -} - - </programlisting> - <para> - For a real hardware device you would try to avoid the loop with put_user(). - Each call to put_user() has a time overhead checking whether the accesses to user - space are allowed. It would be better to read a line into a temporary buffer - then copy this to user space in one go. - </para> - <para> - Having captured the image and put it into user space we can kick the card to - get the next frame acquired. - </para> - </sect1> - <sect1 id="iocvid"> - <title>Video Ioctl Handling</title> - <para> - As with the radio driver the major control interface is via the ioctl() - function. Video capture devices support the same tuner calls as a radio - device and also support additional calls to control how the video functions - are handled. In this simple example the card has no tuners to avoid making - the code complex. - </para> - <programlisting> - - - -static int camera_ioctl(struct video_device *dev, unsigned int cmd, void *arg) -{ - switch(cmd) - { - case VIDIOCGCAP: - { - struct video_capability v; - v.type = VID_TYPE_CAPTURE|\ - VID_TYPE_CHROMAKEY|\ - VID_TYPE_SCALES|\ - VID_TYPE_OVERLAY; - v.channels = 1; - v.audios = 0; - v.maxwidth = 640; - v.minwidth = 16; - v.maxheight = 480; - v.minheight = 16; - strcpy(v.name, "My Camera"); - if(copy_to_user(arg, &v, sizeof(v))) - return -EFAULT; - return 0; - } - - - </programlisting> - <para> - The first ioctl we must support and which all video capture and radio - devices are required to support is VIDIOCGCAP. This behaves exactly the same - as with a radio device. This time, however, we report the extra capabilities - we outlined earlier on when defining our video_dev structure. - </para> - <para> - We now set the video flags saying that we support overlay, capture, - scaling and chromakey. We also report size limits - our smallest image is - 16x16 pixels, our largest is 640x480. - </para> - <para> - To keep things simple we report no audio and no tuning capabilities at all. - </para> - <programlisting> - - case VIDIOCGCHAN: - { - struct video_channel v; - if(copy_from_user(&v, arg, sizeof(v))) - return -EFAULT; - if(v.channel != 0) - return -EINVAL; - v.flags = 0; - v.tuners = 0; - v.type = VIDEO_TYPE_CAMERA; - v.norm = VIDEO_MODE_AUTO; - strcpy(v.name, "Camera Input");break; - if(copy_to_user(&v, arg, sizeof(v))) - return -EFAULT; - return 0; - } - - - </programlisting> - <para> - This follows what is very much the standard way an ioctl handler looks - in Linux. We copy the data into a kernel space variable and we check that the - request is valid (in this case that the input is 0). Finally we copy the - camera info back to the user. - </para> - <para> - The VIDIOCGCHAN ioctl allows a user to ask about video channels (that is - inputs to the video card). Our example card has a single camera input. The - fields in the structure are - </para> - <table frame="all" id="video_channel_fields"><title>struct video_channel fields</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - - <entry>channel</entry><entry>The channel number we are selecting</entry> - </row><row> - <entry>name</entry><entry>The name for this channel. This is intended - to describe the port to the user. - Appropriate names are therefore things like - "Camera" "SCART input"</entry> - </row><row> - <entry>flags</entry><entry>Channel properties</entry> - </row><row> - <entry>type</entry><entry>Input type</entry> - </row><row> - <entry>norm</entry><entry>The current television encoding being used - if relevant for this channel. - </entry> - </row> - </tbody> - </tgroup> - </table> - <table frame="all" id="video_channel_flags"><title>struct video_channel flags</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>VIDEO_VC_TUNER</entry><entry>Channel has a tuner.</entry> - </row><row> - <entry>VIDEO_VC_AUDIO</entry><entry>Channel has audio.</entry> - </row> - </tbody> - </tgroup> - </table> - <table frame="all" id="video_channel_types"><title>struct video_channel types</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>VIDEO_TYPE_TV</entry><entry>Television input.</entry> - </row><row> - <entry>VIDEO_TYPE_CAMERA</entry><entry>Fixed camera input.</entry> - </row><row> - <entry>0</entry><entry>Type is unknown.</entry> - </row> - </tbody> - </tgroup> - </table> - <table frame="all" id="video_channel_norms"><title>struct video_channel norms</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>VIDEO_MODE_PAL</entry><entry>PAL encoded Television</entry> - </row><row> - <entry>VIDEO_MODE_NTSC</entry><entry>NTSC (US) encoded Television</entry> - </row><row> - <entry>VIDEO_MODE_SECAM</entry><entry>SECAM (French) Television </entry> - </row><row> - <entry>VIDEO_MODE_AUTO</entry><entry>Automatic switching, or format does not - matter</entry> - </row> - </tbody> - </tgroup> - </table> - <para> - The corresponding VIDIOCSCHAN ioctl allows a user to change channel and to - request the norm is changed - for example to switch between a PAL or an NTSC - format camera. - </para> - <programlisting> - - - case VIDIOCSCHAN: - { - struct video_channel v; - if(copy_from_user(&v, arg, sizeof(v))) - return -EFAULT; - if(v.channel != 0) - return -EINVAL; - if(v.norm != VIDEO_MODE_AUTO) - return -EINVAL; - return 0; - } - - - </programlisting> - <para> - The implementation of this call in our driver is remarkably easy. Because we - are assuming fixed format hardware we need only check that the user has not - tried to change anything. - </para> - <para> - The user also needs to be able to configure and adjust the picture they are - seeing. This is much like adjusting a television set. A user application - also needs to know the palette being used so that it knows how to display - the image that has been captured. The VIDIOCGPICT and VIDIOCSPICT ioctl - calls provide this information. - </para> - <programlisting> - - - case VIDIOCGPICT - { - struct video_picture v; - v.brightness = hardware_brightness(); - v.hue = hardware_hue(); - v.colour = hardware_saturation(); - v.contrast = hardware_brightness(); - /* Not settable */ - v.whiteness = 32768; - v.depth = 24; /* 24bit */ - v.palette = VIDEO_PALETTE_RGB24; - if(copy_to_user(&v, arg, - sizeof(v))) - return -EFAULT; - return 0; - } - - - </programlisting> - <para> - The brightness, hue, color, and contrast provide the picture controls that - are akin to a conventional television. Whiteness provides additional - control for greyscale images. All of these values are scaled between 0-65535 - and have 32768 as the mid point setting. The scaling means that applications - do not have to worry about the capability range of the hardware but can let - it make a best effort attempt. - </para> - <para> - Our depth is 24, as this is in bits. We will be returning RGB24 format. This - has one byte of red, then one of green, then one of blue. This then repeats - for every other pixel in the image. The other common formats the interface - defines are - </para> - <table frame="all" id="Framebuffer_Encodings"><title>Framebuffer Encodings</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>GREY</entry><entry>Linear greyscale. This is for simple cameras and the - like</entry> - </row><row> - <entry>RGB565</entry><entry>The top 5 bits hold 32 red levels, the next six bits - hold green and the low 5 bits hold blue. </entry> - </row><row> - <entry>RGB555</entry><entry>The top bit is clear. The red green and blue levels - each occupy five bits.</entry> - </row> - </tbody> - </tgroup> - </table> - <para> - Additional modes are support for YUV capture formats. These are common for - TV and video conferencing applications. - </para> - <para> - The VIDIOCSPICT ioctl allows a user to set some of the picture parameters. - Exactly which ones are supported depends heavily on the card itself. It is - possible to support many modes and effects in software. In general doing - this in the kernel is a bad idea. Video capture is a performance-sensitive - application and the programs can often do better if they aren't being - 'helped' by an overkeen driver writer. Thus for our device we will report - RGB24 only and refuse to allow a change. - </para> - <programlisting> - - - case VIDIOCSPICT: - { - struct video_picture v; - if(copy_from_user(&v, arg, sizeof(v))) - return -EFAULT; - if(v.depth!=24 || - v.palette != VIDEO_PALETTE_RGB24) - return -EINVAL; - set_hardware_brightness(v.brightness); - set_hardware_hue(v.hue); - set_hardware_saturation(v.colour); - set_hardware_brightness(v.contrast); - return 0; - } - - - </programlisting> - <para> - We check the user has not tried to change the palette or the depth. We do - not want to carry out some of the changes and then return an error. This may - confuse the application which will be assuming no change occurred. - </para> - <para> - In much the same way as you need to be able to set the picture controls to - get the right capture images, many cards need to know what they are - displaying onto when generating overlay output. In some cases getting this - wrong even makes a nasty mess or may crash the computer. For that reason - the VIDIOCSBUF ioctl used to set up the frame buffer information may well - only be usable by root. - </para> - <para> - We will assume our card is one of the old ISA devices with feature connector - and only supports a couple of standard video modes. Very common for older - cards although the PCI devices are way smarter than this. - </para> - <programlisting> - - -static struct video_buffer capture_fb; - - case VIDIOCGFBUF: - { - if(copy_to_user(arg, &capture_fb, - sizeof(capture_fb))) - return -EFAULT; - return 0; - - } - - - </programlisting> - <para> - We keep the frame buffer information in the format the ioctl uses. This - makes it nice and easy to work with in the ioctl calls. - </para> - <programlisting> - - case VIDIOCSFBUF: - { - struct video_buffer v; - - if(!capable(CAP_SYS_ADMIN)) - return -EPERM; - - if(copy_from_user(&v, arg, sizeof(v))) - return -EFAULT; - if(v.width!=320 && v.width!=640) - return -EINVAL; - if(v.height!=200 && v.height!=240 - && v.height!=400 - && v.height !=480) - return -EINVAL; - memcpy(&capture_fb, &v, sizeof(v)); - hardware_set_fb(&v); - return 0; - } - - - - </programlisting> - <para> - The capable() function checks a user has the required capability. The Linux - operating system has a set of about 30 capabilities indicating privileged - access to services. The default set up gives the superuser (uid 0) all of - them and nobody else has any. - </para> - <para> - We check that the user has the SYS_ADMIN capability, that is they are - allowed to operate as the machine administrator. We don't want anyone but - the administrator making a mess of the display. - </para> - <para> - Next we check for standard PC video modes (320 or 640 wide with either - EGA or VGA depths). If the mode is not a standard video mode we reject it as - not supported by our card. If the mode is acceptable we save it so that - VIDIOCFBUF will give the right answer next time it is called. The - hardware_set_fb() function is some undescribed card specific function to - program the card for the desired mode. - </para> - <para> - Before the driver can display an overlay window it needs to know where the - window should be placed, and also how large it should be. If the card - supports clipping it needs to know which rectangles to omit from the - display. The video_window structure is used to describe the way the image - should be displayed. - </para> - <table frame="all" id="video_window_fields"><title>struct video_window fields</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>width</entry><entry>The width in pixels of the desired image. The card - may use a smaller size if this size is not available</entry> - </row><row> - <entry>height</entry><entry>The height of the image. The card may use a smaller - size if this size is not available.</entry> - </row><row> - <entry>x</entry><entry> The X position of the top left of the window. This - is in pixels relative to the left hand edge of the - picture. Not all cards can display images aligned on - any pixel boundary. If the position is unsuitable - the card adjusts the image right and reduces the - width.</entry> - </row><row> - <entry>y</entry><entry> The Y position of the top left of the window. This - is counted in pixels relative to the top edge of the - picture. As with the width if the card cannot - display starting on this line it will adjust the - values.</entry> - </row><row> - <entry>chromakey</entry><entry>The colour (expressed in RGB32 format) for the - chromakey colour if chroma keying is being used. </entry> - </row><row> - <entry>clips</entry><entry>An array of rectangles that must not be drawn - over.</entry> - </row><row> - <entry>clipcount</entry><entry>The number of clips in this array.</entry> - </row> - </tbody> - </tgroup> - </table> - <para> - Each clip is a struct video_clip which has the following fields - </para> - <table frame="all" id="video_clip_fields"><title>video_clip fields</title> - <tgroup cols="2" align="left"> - <tbody> - <row> - <entry>x, y</entry><entry>Co-ordinates relative to the display</entry> - </row><row> - <entry>width, height</entry><entry>Width and height in pixels</entry> - </row><row> - <entry>next</entry><entry>A spare field for the application to use</entry> - </row> - </tbody> - </tgroup> - </table> - <para> - The driver is required to ensure it always draws in the area requested or a smaller area, and that it never draws in any of the areas that are clipped. - This may well mean it has to leave alone. small areas the application wished to be - drawn. - </para> - <para> - Our example card uses chromakey so does not have to address most of the - clipping. We will add a video_window structure to our global variables to - remember our parameters, as we did with the frame buffer. - </para> - <programlisting> - - - case VIDIOCGWIN: - { - if(copy_to_user(arg, &capture_win, - sizeof(capture_win))) - return -EFAULT; - return 0; - } - - - case VIDIOCSWIN: - { - struct video_window v; - if(copy_from_user(&v, arg, sizeof(v))) - return -EFAULT; - if(v.width > 640 || v.height > 480) - return -EINVAL; - if(v.width < 16 || v.height < 16) - return -EINVAL; - hardware_set_key(v.chromakey); - hardware_set_window(v); - memcpy(&capture_win, &v, sizeof(v)); - capture_w = v.width; - capture_h = v.height; - return 0; - } - - - </programlisting> - <para> - Because we are using Chromakey our setup is fairly simple. Mostly we have to - check the values are sane and load them into the capture card. - </para> - <para> - With all the setup done we can now turn on the actual capture/overlay. This - is done with the VIDIOCCAPTURE ioctl. This takes a single integer argument - where 0 is on and 1 is off. - </para> - <programlisting> - - - case VIDIOCCAPTURE: - { - int v; - if(get_user(v, (int *)arg)) - return -EFAULT; - if(v==0) - hardware_capture_off(); - else - { - if(capture_fb.width == 0 - || capture_w == 0) - return -EINVAL; - hardware_capture_on(); - } - return 0; - } - - - </programlisting> - <para> - We grab the flag from user space and either enable or disable according to - its value. There is one small corner case we have to consider here. Suppose - that the capture was requested before the video window or the frame buffer - had been set up. In those cases there will be unconfigured fields in our - card data, as well as unconfigured hardware settings. We check for this case and - return an error if the frame buffer or the capture window width is zero. - </para> - <programlisting> - - - default: - return -ENOIOCTLCMD; - } -} - </programlisting> - <para> - - We don't need to support any other ioctls, so if we get this far, it is time - to tell the video layer that we don't now what the user is talking about. - </para> - </sect1> - <sect1 id="endvid"> - <title>Other Functionality</title> - <para> - The Video4Linux layer supports additional features, including a high - performance mmap() based capture mode and capturing part of the image. - These features are out of the scope of the book. You should however have enough - example code to implement most simple video4linux devices for radio and TV - cards. - </para> - </sect1> - </chapter> - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - <variablelist> - <varlistentry><term>Multiple Opens</term> - <listitem> - <para> - The driver assumes multiple opens should not be allowed. A driver - can work around this but not cleanly. - </para> - </listitem></varlistentry> - - <varlistentry><term>API Deficiencies</term> - <listitem> - <para> - The existing API poorly reflects compression capable devices. There - are plans afoot to merge V4L, V4L2 and some other ideas into a - better interface. - </para> - </listitem></varlistentry> - </variablelist> - - </para> - </chapter> - - <chapter id="pubfunctions"> - <title>Public Functions Provided</title> -!Edrivers/media/video/v4l2-dev.c - </chapter> - -</book> diff --git a/Documentation/DocBook/wanbook.tmpl b/Documentation/DocBook/wanbook.tmpl deleted file mode 100644 index 9eebcc304de..00000000000 --- a/Documentation/DocBook/wanbook.tmpl +++ /dev/null @@ -1,99 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="WANGuide"> - <bookinfo> - <title>Synchronous PPP and Cisco HDLC Programming Guide</title> - - <authorgroup> - <author> - <firstname>Alan</firstname> - <surname>Cox</surname> - <affiliation> - <address> - <email>alan@redhat.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2000</year> - <holder>Alan Cox</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The syncppp drivers in Linux provide a fairly complete - implementation of Cisco HDLC and a minimal implementation of - PPP. The longer term goal is to switch the PPP layer to the - generic PPP interface that is new in Linux 2.3.x. The API should - remain unchanged when this is done, but support will then be - available for IPX, compression and other PPP features - </para> - </chapter> - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - <variablelist> - <varlistentry><term>PPP is minimal</term> - <listitem> - <para> - The current PPP implementation is very basic, although sufficient - for most wan usages. - </para> - </listitem></varlistentry> - - <varlistentry><term>Cisco HDLC Quirks</term> - <listitem> - <para> - Currently we do not end all packets with the correct Cisco multicast - or unicast flags. Nothing appears to mind too much but this should - be corrected. - </para> - </listitem></varlistentry> - </variablelist> - - </para> - </chapter> - - <chapter id="pubfunctions"> - <title>Public Functions Provided</title> -!Edrivers/net/wan/syncppp.c - </chapter> - -</book> diff --git a/Documentation/DocBook/z8530book.tmpl b/Documentation/DocBook/z8530book.tmpl index a42a8a4c768..6f3883be877 100644 --- a/Documentation/DocBook/z8530book.tmpl +++ b/Documentation/DocBook/z8530book.tmpl @@ -12,7 +12,7 @@ <surname>Cox</surname> <affiliation> <address> - <email>alan@redhat.com</email> + <email>alan@lxorguk.ukuu.org.uk</email> </address> </affiliation> </author> diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 48a3955f05f..8495fc97039 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -112,7 +112,7 @@ required reading: Other excellent descriptions of how to create patches properly are: "The Perfect Patch" - http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt + http://userweb.kernel.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html @@ -620,7 +620,7 @@ all time. It should describe the patch completely, containing: For more details on what this should all look like, please see the ChangeLog section of the document: "The Perfect Patch" - http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt + http://userweb.kernel.org/~akpm/stuff/tpp.txt diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle index 49a8efa5afe..a5f0ea58c78 100644 --- a/Documentation/ManagementStyle +++ b/Documentation/ManagementStyle @@ -17,7 +17,7 @@ companies. If you sign purchase orders or you have any clue about the budget of your group, you're almost certainly not a kernel manager. These suggestions may or may not apply to you. -First off, I'd suggest buying "Seven Habits of Highly Successful +First off, I'd suggest buying "Seven Habits of Highly Effective People", and NOT read it. Burn it, it's a great symbolic gesture. (*) This document does so not so much by answering the question, but by diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX index 49f43946c6b..812b17fe3ed 100644 --- a/Documentation/PCI/00-INDEX +++ b/Documentation/PCI/00-INDEX @@ -1,5 +1,7 @@ 00-INDEX - this file +MSI-HOWTO.txt + - the Message Signaled Interrupts (MSI) Driver Guide HOWTO and FAQ. PCI-DMA-mapping.txt - info for PCI drivers using DMA portably across all platforms PCIEBUS-HOWTO.txt diff --git a/Documentation/MSI-HOWTO.txt b/Documentation/PCI/MSI-HOWTO.txt index a51f693c154..256defd7e17 100644 --- a/Documentation/MSI-HOWTO.txt +++ b/Documentation/PCI/MSI-HOWTO.txt @@ -236,10 +236,8 @@ software system can set different pages for controlling accesses to the MSI-X structure. The implementation of MSI support requires the PCI subsystem, not a device driver, to maintain full control of the MSI-X table/MSI-X PBA (Pending Bit Array) and MMIO address space of the MSI-X -table/MSI-X PBA. A device driver is prohibited from requesting the MMIO -address space of the MSI-X table/MSI-X PBA. Otherwise, the PCI subsystem -will fail enabling MSI-X on its hardware device when it calls the function -pci_enable_msix(). +table/MSI-X PBA. A device driver should not access the MMIO address +space of the MSI-X table/MSI-X PBA. 5.3.2 API pci_enable_msix diff --git a/Documentation/PCI/pci.txt b/Documentation/PCI/pci.txt index 8d4dc6250c5..fd4907a2968 100644 --- a/Documentation/PCI/pci.txt +++ b/Documentation/PCI/pci.txt @@ -163,6 +163,10 @@ need pass only as many optional fields as necessary: o class and classmask fields default to 0 o driver_data defaults to 0UL. +Note that driver_data must match the value used by any of the pci_device_id +entries defined in the driver. This makes the driver_data field mandatory +if all the pci_device_id entries have a non-zero driver_data value. + Once added, the driver probe routine will be invoked for any unclaimed PCI devices listed in its (newly updated) pci_ids list. diff --git a/Documentation/PCI/pcieaer-howto.txt b/Documentation/PCI/pcieaer-howto.txt index 16c251230c8..ddeb14beacc 100644 --- a/Documentation/PCI/pcieaer-howto.txt +++ b/Documentation/PCI/pcieaer-howto.txt @@ -203,22 +203,17 @@ to mmio_enabled. 3.3 helper functions -3.3.1 int pci_find_aer_capability(struct pci_dev *dev); -pci_find_aer_capability locates the PCI Express AER capability -in the device configuration space. If the device doesn't support -PCI-Express AER, the function returns 0. - -3.3.2 int pci_enable_pcie_error_reporting(struct pci_dev *dev); +3.3.1 int pci_enable_pcie_error_reporting(struct pci_dev *dev); pci_enable_pcie_error_reporting enables the device to send error messages to root port when an error is detected. Note that devices don't enable the error reporting by default, so device drivers need call this function to enable it. -3.3.3 int pci_disable_pcie_error_reporting(struct pci_dev *dev); +3.3.2 int pci_disable_pcie_error_reporting(struct pci_dev *dev); pci_disable_pcie_error_reporting disables the device to send error messages to root port when an error is detected. -3.3.4 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev); +3.3.3 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev); pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable error status register. diff --git a/Documentation/RCU/00-INDEX b/Documentation/RCU/00-INDEX index 461481dfb7c..7dc0695a8f9 100644 --- a/Documentation/RCU/00-INDEX +++ b/Documentation/RCU/00-INDEX @@ -16,6 +16,8 @@ RTFP.txt - List of RCU papers (bibliography) going back to 1980. torture.txt - RCU Torture Test Operation (CONFIG_RCU_TORTURE_TEST) +trace.txt + - CONFIG_RCU_TRACE debugfs files and formats UP.txt - RCU on Uniprocessor Systems whatisRCU.txt diff --git a/Documentation/RCU/rculist_nulls.txt b/Documentation/RCU/rculist_nulls.txt new file mode 100644 index 00000000000..239f542d48b --- /dev/null +++ b/Documentation/RCU/rculist_nulls.txt @@ -0,0 +1,167 @@ +Using hlist_nulls to protect read-mostly linked lists and +objects using SLAB_DESTROY_BY_RCU allocations. + +Please read the basics in Documentation/RCU/listRCU.txt + +Using special makers (called 'nulls') is a convenient way +to solve following problem : + +A typical RCU linked list managing objects which are +allocated with SLAB_DESTROY_BY_RCU kmem_cache can +use following algos : + +1) Lookup algo +-------------- +rcu_read_lock() +begin: +obj = lockless_lookup(key); +if (obj) { + if (!try_get_ref(obj)) // might fail for free objects + goto begin; + /* + * Because a writer could delete object, and a writer could + * reuse these object before the RCU grace period, we + * must check key after geting the reference on object + */ + if (obj->key != key) { // not the object we expected + put_ref(obj); + goto begin; + } +} +rcu_read_unlock(); + +Beware that lockless_lookup(key) cannot use traditional hlist_for_each_entry_rcu() +but a version with an additional memory barrier (smp_rmb()) + +lockless_lookup(key) +{ + struct hlist_node *node, *next; + for (pos = rcu_dereference((head)->first); + pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) && + ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; }); + pos = rcu_dereference(next)) + if (obj->key == key) + return obj; + return NULL; + +And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb() : + + struct hlist_node *node; + for (pos = rcu_dereference((head)->first); + pos && ({ prefetch(pos->next); 1; }) && + ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; }); + pos = rcu_dereference(pos->next)) + if (obj->key == key) + return obj; + return NULL; +} + +Quoting Corey Minyard : + +"If the object is moved from one list to another list in-between the + time the hash is calculated and the next field is accessed, and the + object has moved to the end of a new list, the traversal will not + complete properly on the list it should have, since the object will + be on the end of the new list and there's not a way to tell it's on a + new list and restart the list traversal. I think that this can be + solved by pre-fetching the "next" field (with proper barriers) before + checking the key." + +2) Insert algo : +---------------- + +We need to make sure a reader cannot read the new 'obj->obj_next' value +and previous value of 'obj->key'. Or else, an item could be deleted +from a chain, and inserted into another chain. If new chain was empty +before the move, 'next' pointer is NULL, and lockless reader can +not detect it missed following items in original chain. + +/* + * Please note that new inserts are done at the head of list, + * not in the middle or end. + */ +obj = kmem_cache_alloc(...); +lock_chain(); // typically a spin_lock() +obj->key = key; +atomic_inc(&obj->refcnt); +/* + * we need to make sure obj->key is updated before obj->next + */ +smp_wmb(); +hlist_add_head_rcu(&obj->obj_node, list); +unlock_chain(); // typically a spin_unlock() + + +3) Remove algo +-------------- +Nothing special here, we can use a standard RCU hlist deletion. +But thanks to SLAB_DESTROY_BY_RCU, beware a deleted object can be reused +very very fast (before the end of RCU grace period) + +if (put_last_reference_on(obj) { + lock_chain(); // typically a spin_lock() + hlist_del_init_rcu(&obj->obj_node); + unlock_chain(); // typically a spin_unlock() + kmem_cache_free(cachep, obj); +} + + + +-------------------------------------------------------------------------- +With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup() +and extra smp_wmb() in insert function. + +For example, if we choose to store the slot number as the 'nulls' +end-of-list marker for each slot of the hash table, we can detect +a race (some writer did a delete and/or a move of an object +to another chain) checking the final 'nulls' value if +the lookup met the end of chain. If final 'nulls' value +is not the slot number, then we must restart the lookup at +the begining. If the object was moved to same chain, +then the reader doesnt care : It might eventually +scan the list again without harm. + + +1) lookup algo + + head = &table[slot]; + rcu_read_lock(); +begin: + hlist_nulls_for_each_entry_rcu(obj, node, head, member) { + if (obj->key == key) { + if (!try_get_ref(obj)) // might fail for free objects + goto begin; + if (obj->key != key) { // not the object we expected + put_ref(obj); + goto begin; + } + goto out; + } +/* + * if the nulls value we got at the end of this lookup is + * not the expected one, we must restart lookup. + * We probably met an item that was moved to another chain. + */ + if (get_nulls_value(node) != slot) + goto begin; + obj = NULL; + +out: + rcu_read_unlock(); + +2) Insert function : +-------------------- + +/* + * Please note that new inserts are done at the head of list, + * not in the middle or end. + */ +obj = kmem_cache_alloc(cachep); +lock_chain(); // typically a spin_lock() +obj->key = key; +atomic_set(&obj->refcnt, 1); +/* + * insert obj in RCU way (readers might be traversing chain) + */ +hlist_nulls_add_head_rcu(&obj->obj_node, list); +unlock_chain(); // typically a spin_unlock() diff --git a/Documentation/RCU/trace.txt b/Documentation/RCU/trace.txt new file mode 100644 index 00000000000..068848240a8 --- /dev/null +++ b/Documentation/RCU/trace.txt @@ -0,0 +1,413 @@ +CONFIG_RCU_TRACE debugfs Files and Formats + + +The rcupreempt and rcutree implementations of RCU provide debugfs trace +output that summarizes counters and state. This information is useful for +debugging RCU itself, and can sometimes also help to debug abuses of RCU. +Note that the rcuclassic implementation of RCU does not provide debugfs +trace output. + +The following sections describe the debugfs files and formats for +preemptable RCU (rcupreempt) and hierarchical RCU (rcutree). + + +Preemptable RCU debugfs Files and Formats + +This implementation of RCU provides three debugfs files under the +top-level directory RCU: rcu/rcuctrs (which displays the per-CPU +counters used by preemptable RCU) rcu/rcugp (which displays grace-period +counters), and rcu/rcustats (which internal counters for debugging RCU). + +The output of "cat rcu/rcuctrs" looks as follows: + +CPU last cur F M + 0 5 -5 0 0 + 1 -1 0 0 0 + 2 0 1 0 0 + 3 0 1 0 0 + 4 0 1 0 0 + 5 0 1 0 0 + 6 0 2 0 0 + 7 0 -1 0 0 + 8 0 1 0 0 +ggp = 26226, state = waitzero + +The per-CPU fields are as follows: + +o "CPU" gives the CPU number. Offline CPUs are not displayed. + +o "last" gives the value of the counter that is being decremented + for the current grace period phase. In the example above, + the counters sum to 4, indicating that there are still four + RCU read-side critical sections still running that started + before the last counter flip. + +o "cur" gives the value of the counter that is currently being + both incremented (by rcu_read_lock()) and decremented (by + rcu_read_unlock()). In the example above, the counters sum to + 1, indicating that there is only one RCU read-side critical section + still running that started after the last counter flip. + +o "F" indicates whether RCU is waiting for this CPU to acknowledge + a counter flip. In the above example, RCU is not waiting on any, + which is consistent with the state being "waitzero" rather than + "waitack". + +o "M" indicates whether RCU is waiting for this CPU to execute a + memory barrier. In the above example, RCU is not waiting on any, + which is consistent with the state being "waitzero" rather than + "waitmb". + +o "ggp" is the global grace-period counter. + +o "state" is the RCU state, which can be one of the following: + + o "idle": there is no grace period in progress. + + o "waitack": RCU just incremented the global grace-period + counter, which has the effect of reversing the roles of + the "last" and "cur" counters above, and is waiting for + all the CPUs to acknowledge the flip. Once the flip has + been acknowledged, CPUs will no longer be incrementing + what are now the "last" counters, so that their sum will + decrease monotonically down to zero. + + o "waitzero": RCU is waiting for the sum of the "last" counters + to decrease to zero. + + o "waitmb": RCU is waiting for each CPU to execute a memory + barrier, which ensures that instructions from a given CPU's + last RCU read-side critical section cannot be reordered + with instructions following the memory-barrier instruction. + +The output of "cat rcu/rcugp" looks as follows: + +oldggp=48870 newggp=48873 + +Note that reading from this file provokes a synchronize_rcu(). The +"oldggp" value is that of "ggp" from rcu/rcuctrs above, taken before +executing the synchronize_rcu(), and the "newggp" value is also the +"ggp" value, but taken after the synchronize_rcu() command returns. + + +The output of "cat rcu/rcugp" looks as follows: + +na=1337955 nl=40 wa=1337915 wl=44 da=1337871 dl=0 dr=1337871 di=1337871 +1=50989 e1=6138 i1=49722 ie1=82 g1=49640 a1=315203 ae1=265563 a2=49640 +z1=1401244 ze1=1351605 z2=49639 m1=5661253 me1=5611614 m2=49639 + +These are counters tracking internal preemptable-RCU events, however, +some of them may be useful for debugging algorithms using RCU. In +particular, the "nl", "wl", and "dl" values track the number of RCU +callbacks in various states. The fields are as follows: + +o "na" is the total number of RCU callbacks that have been enqueued + since boot. + +o "nl" is the number of RCU callbacks waiting for the previous + grace period to end so that they can start waiting on the next + grace period. + +o "wa" is the total number of RCU callbacks that have started waiting + for a grace period since boot. "na" should be roughly equal to + "nl" plus "wa". + +o "wl" is the number of RCU callbacks currently waiting for their + grace period to end. + +o "da" is the total number of RCU callbacks whose grace periods + have completed since boot. "wa" should be roughly equal to + "wl" plus "da". + +o "dr" is the total number of RCU callbacks that have been removed + from the list of callbacks ready to invoke. "dr" should be roughly + equal to "da". + +o "di" is the total number of RCU callbacks that have been invoked + since boot. "di" should be roughly equal to "da", though some + early versions of preemptable RCU had a bug so that only the + last CPU's count of invocations was displayed, rather than the + sum of all CPU's counts. + +o "1" is the number of calls to rcu_try_flip(). This should be + roughly equal to the sum of "e1", "i1", "a1", "z1", and "m1" + described below. In other words, the number of times that + the state machine is visited should be equal to the sum of the + number of times that each state is visited plus the number of + times that the state-machine lock acquisition failed. + +o "e1" is the number of times that rcu_try_flip() was unable to + acquire the fliplock. + +o "i1" is the number of calls to rcu_try_flip_idle(). + +o "ie1" is the number of times rcu_try_flip_idle() exited early + due to the calling CPU having no work for RCU. + +o "g1" is the number of times that rcu_try_flip_idle() decided + to start a new grace period. "i1" should be roughly equal to + "ie1" plus "g1". + +o "a1" is the number of calls to rcu_try_flip_waitack(). + +o "ae1" is the number of times that rcu_try_flip_waitack() found + that at least one CPU had not yet acknowledge the new grace period + (AKA "counter flip"). + +o "a2" is the number of time rcu_try_flip_waitack() found that + all CPUs had acknowledged. "a1" should be roughly equal to + "ae1" plus "a2". (This particular output was collected on + a 128-CPU machine, hence the smaller-than-usual fraction of + calls to rcu_try_flip_waitack() finding all CPUs having already + acknowledged.) + +o "z1" is the number of calls to rcu_try_flip_waitzero(). + +o "ze1" is the number of times that rcu_try_flip_waitzero() found + that not all of the old RCU read-side critical sections had + completed. + +o "z2" is the number of times that rcu_try_flip_waitzero() finds + the sum of the counters equal to zero, in other words, that + all of the old RCU read-side critical sections had completed. + The value of "z1" should be roughly equal to "ze1" plus + "z2". + +o "m1" is the number of calls to rcu_try_flip_waitmb(). + +o "me1" is the number of times that rcu_try_flip_waitmb() finds + that at least one CPU has not yet executed a memory barrier. + +o "m2" is the number of times that rcu_try_flip_waitmb() finds that + all CPUs have executed a memory barrier. + + +Hierarchical RCU debugfs Files and Formats + +This implementation of RCU provides three debugfs files under the +top-level directory RCU: rcu/rcudata (which displays fields in struct +rcu_data), rcu/rcugp (which displays grace-period counters), and +rcu/rcuhier (which displays the struct rcu_node hierarchy). + +The output of "cat rcu/rcudata" looks as follows: + +rcu: + 0 c=4011 g=4012 pq=1 pqc=4011 qp=0 rpfq=1 rp=3c2a dt=23301/73 dn=2 df=1882 of=0 ri=2126 ql=2 b=10 + 1 c=4011 g=4012 pq=1 pqc=4011 qp=0 rpfq=3 rp=39a6 dt=78073/1 dn=2 df=1402 of=0 ri=1875 ql=46 b=10 + 2 c=4010 g=4010 pq=1 pqc=4010 qp=0 rpfq=-5 rp=1d12 dt=16646/0 dn=2 df=3140 of=0 ri=2080 ql=0 b=10 + 3 c=4012 g=4013 pq=1 pqc=4012 qp=1 rpfq=3 rp=2b50 dt=21159/1 dn=2 df=2230 of=0 ri=1923 ql=72 b=10 + 4 c=4012 g=4013 pq=1 pqc=4012 qp=1 rpfq=3 rp=1644 dt=5783/1 dn=2 df=3348 of=0 ri=2805 ql=7 b=10 + 5 c=4012 g=4013 pq=0 pqc=4011 qp=1 rpfq=3 rp=1aac dt=5879/1 dn=2 df=3140 of=0 ri=2066 ql=10 b=10 + 6 c=4012 g=4013 pq=1 pqc=4012 qp=1 rpfq=3 rp=ed8 dt=5847/1 dn=2 df=3797 of=0 ri=1266 ql=10 b=10 + 7 c=4012 g=4013 pq=1 pqc=4012 qp=1 rpfq=3 rp=1fa2 dt=6199/1 dn=2 df=2795 of=0 ri=2162 ql=28 b=10 +rcu_bh: + 0 c=-268 g=-268 pq=1 pqc=-268 qp=0 rpfq=-145 rp=21d6 dt=23301/73 dn=2 df=0 of=0 ri=0 ql=0 b=10 + 1 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-170 rp=20ce dt=78073/1 dn=2 df=26 of=0 ri=5 ql=0 b=10 + 2 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-83 rp=fbd dt=16646/0 dn=2 df=28 of=0 ri=4 ql=0 b=10 + 3 c=-268 g=-268 pq=1 pqc=-268 qp=0 rpfq=-105 rp=178c dt=21159/1 dn=2 df=28 of=0 ri=2 ql=0 b=10 + 4 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-30 rp=b54 dt=5783/1 dn=2 df=32 of=0 ri=0 ql=0 b=10 + 5 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-29 rp=df5 dt=5879/1 dn=2 df=30 of=0 ri=3 ql=0 b=10 + 6 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-28 rp=788 dt=5847/1 dn=2 df=32 of=0 ri=0 ql=0 b=10 + 7 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-53 rp=1098 dt=6199/1 dn=2 df=30 of=0 ri=3 ql=0 b=10 + +The first section lists the rcu_data structures for rcu, the second for +rcu_bh. Each section has one line per CPU, or eight for this 8-CPU system. +The fields are as follows: + +o The number at the beginning of each line is the CPU number. + CPUs numbers followed by an exclamation mark are offline, + but have been online at least once since boot. There will be + no output for CPUs that have never been online, which can be + a good thing in the surprisingly common case where NR_CPUS is + substantially larger than the number of actual CPUs. + +o "c" is the count of grace periods that this CPU believes have + completed. CPUs in dynticks idle mode may lag quite a ways + behind, for example, CPU 4 under "rcu" above, which has slept + through the past 25 RCU grace periods. It is not unusual to + see CPUs lagging by thousands of grace periods. + +o "g" is the count of grace periods that this CPU believes have + started. Again, CPUs in dynticks idle mode may lag behind. + If the "c" and "g" values are equal, this CPU has already + reported a quiescent state for the last RCU grace period that + it is aware of, otherwise, the CPU believes that it owes RCU a + quiescent state. + +o "pq" indicates that this CPU has passed through a quiescent state + for the current grace period. It is possible for "pq" to be + "1" and "c" different than "g", which indicates that although + the CPU has passed through a quiescent state, either (1) this + CPU has not yet reported that fact, (2) some other CPU has not + yet reported for this grace period, or (3) both. + +o "pqc" indicates which grace period the last-observed quiescent + state for this CPU corresponds to. This is important for handling + the race between CPU 0 reporting an extended dynticks-idle + quiescent state for CPU 1 and CPU 1 suddenly waking up and + reporting its own quiescent state. If CPU 1 was the last CPU + for the current grace period, then the CPU that loses this race + will attempt to incorrectly mark CPU 1 as having checked in for + the next grace period! + +o "qp" indicates that RCU still expects a quiescent state from + this CPU. + +o "rpfq" is the number of rcu_pending() calls on this CPU required + to induce this CPU to invoke force_quiescent_state(). + +o "rp" is low-order four hex digits of the count of how many times + rcu_pending() has been invoked on this CPU. + +o "dt" is the current value of the dyntick counter that is incremented + when entering or leaving dynticks idle state, either by the + scheduler or by irq. The number after the "/" is the interrupt + nesting depth when in dyntick-idle state, or one greater than + the interrupt-nesting depth otherwise. + + This field is displayed only for CONFIG_NO_HZ kernels. + +o "dn" is the current value of the dyntick counter that is incremented + when entering or leaving dynticks idle state via NMI. If both + the "dt" and "dn" values are even, then this CPU is in dynticks + idle mode and may be ignored by RCU. If either of these two + counters is odd, then RCU must be alert to the possibility of + an RCU read-side critical section running on this CPU. + + This field is displayed only for CONFIG_NO_HZ kernels. + +o "df" is the number of times that some other CPU has forced a + quiescent state on behalf of this CPU due to this CPU being in + dynticks-idle state. + + This field is displayed only for CONFIG_NO_HZ kernels. + +o "of" is the number of times that some other CPU has forced a + quiescent state on behalf of this CPU due to this CPU being + offline. In a perfect world, this might neve happen, but it + turns out that offlining and onlining a CPU can take several grace + periods, and so there is likely to be an extended period of time + when RCU believes that the CPU is online when it really is not. + Please note that erring in the other direction (RCU believing a + CPU is offline when it is really alive and kicking) is a fatal + error, so it makes sense to err conservatively. + +o "ri" is the number of times that RCU has seen fit to send a + reschedule IPI to this CPU in order to get it to report a + quiescent state. + +o "ql" is the number of RCU callbacks currently residing on + this CPU. This is the total number of callbacks, regardless + of what state they are in (new, waiting for grace period to + start, waiting for grace period to end, ready to invoke). + +o "b" is the batch limit for this CPU. If more than this number + of RCU callbacks is ready to invoke, then the remainder will + be deferred. + + +The output of "cat rcu/rcugp" looks as follows: + +rcu: completed=33062 gpnum=33063 +rcu_bh: completed=464 gpnum=464 + +Again, this output is for both "rcu" and "rcu_bh". The fields are +taken from the rcu_state structure, and are as follows: + +o "completed" is the number of grace periods that have completed. + It is comparable to the "c" field from rcu/rcudata in that a + CPU whose "c" field matches the value of "completed" is aware + that the corresponding RCU grace period has completed. + +o "gpnum" is the number of grace periods that have started. It is + comparable to the "g" field from rcu/rcudata in that a CPU + whose "g" field matches the value of "gpnum" is aware that the + corresponding RCU grace period has started. + + If these two fields are equal (as they are for "rcu_bh" above), + then there is no grace period in progress, in other words, RCU + is idle. On the other hand, if the two fields differ (as they + do for "rcu" above), then an RCU grace period is in progress. + + +The output of "cat rcu/rcuhier" looks as follows, with very long lines: + +c=6902 g=6903 s=2 jfq=3 j=72c7 nfqs=13142/nfqsng=0(13142) fqlh=6 +1/1 0:127 ^0 +3/3 0:35 ^0 0/0 36:71 ^1 0/0 72:107 ^2 0/0 108:127 ^3 +3/3f 0:5 ^0 2/3 6:11 ^1 0/0 12:17 ^2 0/0 18:23 ^3 0/0 24:29 ^4 0/0 30:35 ^5 0/0 36:41 ^0 0/0 42:47 ^1 0/0 48:53 ^2 0/0 54:59 ^3 0/0 60:65 ^4 0/0 66:71 ^5 0/0 72:77 ^0 0/0 78:83 ^1 0/0 84:89 ^2 0/0 90:95 ^3 0/0 96:101 ^4 0/0 102:107 ^5 0/0 108:113 ^0 0/0 114:119 ^1 0/0 120:125 ^2 0/0 126:127 ^3 +rcu_bh: +c=-226 g=-226 s=1 jfq=-5701 j=72c7 nfqs=88/nfqsng=0(88) fqlh=0 +0/1 0:127 ^0 +0/3 0:35 ^0 0/0 36:71 ^1 0/0 72:107 ^2 0/0 108:127 ^3 +0/3f 0:5 ^0 0/3 6:11 ^1 0/0 12:17 ^2 0/0 18:23 ^3 0/0 24:29 ^4 0/0 30:35 ^5 0/0 36:41 ^0 0/0 42:47 ^1 0/0 48:53 ^2 0/0 54:59 ^3 0/0 60:65 ^4 0/0 66:71 ^5 0/0 72:77 ^0 0/0 78:83 ^1 0/0 84:89 ^2 0/0 90:95 ^3 0/0 96:101 ^4 0/0 102:107 ^5 0/0 108:113 ^0 0/0 114:119 ^1 0/0 120:125 ^2 0/0 126:127 ^3 + +This is once again split into "rcu" and "rcu_bh" portions. The fields are +as follows: + +o "c" is exactly the same as "completed" under rcu/rcugp. + +o "g" is exactly the same as "gpnum" under rcu/rcugp. + +o "s" is the "signaled" state that drives force_quiescent_state()'s + state machine. + +o "jfq" is the number of jiffies remaining for this grace period + before force_quiescent_state() is invoked to help push things + along. Note that CPUs in dyntick-idle mode thoughout the grace + period will not report on their own, but rather must be check by + some other CPU via force_quiescent_state(). + +o "j" is the low-order four hex digits of the jiffies counter. + Yes, Paul did run into a number of problems that turned out to + be due to the jiffies counter no longer counting. Why do you ask? + +o "nfqs" is the number of calls to force_quiescent_state() since + boot. + +o "nfqsng" is the number of useless calls to force_quiescent_state(), + where there wasn't actually a grace period active. This can + happen due to races. The number in parentheses is the difference + between "nfqs" and "nfqsng", or the number of times that + force_quiescent_state() actually did some real work. + +o "fqlh" is the number of calls to force_quiescent_state() that + exited immediately (without even being counted in nfqs above) + due to contention on ->fqslock. + +o Each element of the form "1/1 0:127 ^0" represents one struct + rcu_node. Each line represents one level of the hierarchy, from + root to leaves. It is best to think of the rcu_data structures + as forming yet another level after the leaves. Note that there + might be either one, two, or three levels of rcu_node structures, + depending on the relationship between CONFIG_RCU_FANOUT and + CONFIG_NR_CPUS. + + o The numbers separated by the "/" are the qsmask followed + by the qsmaskinit. The qsmask will have one bit + set for each entity in the next lower level that + has not yet checked in for the current grace period. + The qsmaskinit will have one bit for each entity that is + currently expected to check in during each grace period. + The value of qsmaskinit is assigned to that of qsmask + at the beginning of each grace period. + + For example, for "rcu", the qsmask of the first entry + of the lowest level is 0x14, meaning that we are still + waiting for CPUs 2 and 4 to check in for the current + grace period. + + o The numbers separated by the ":" are the range of CPUs + served by this struct rcu_node. This can be helpful + in working out how the hierarchy is wired together. + + For example, the first entry at the lowest level shows + "0:5", indicating that it covers CPUs 0 through 5. + + o The number after the "^" indicates the bit in the + next higher level rcu_node structure that this + rcu_node structure corresponds to. + + For example, the first entry at the lowest level shows + "^0", indicating that it corresponds to bit zero in + the first entry at the middle level. diff --git a/Documentation/SAK.txt b/Documentation/SAK.txt index b9019ca872e..74be14679ed 100644 --- a/Documentation/SAK.txt +++ b/Documentation/SAK.txt @@ -1,5 +1,5 @@ Linux 2.4.2 Secure Attention Key (SAK) handling -18 March 2001, Andrew Morton <akpm@osdl.org> +18 March 2001, Andrew Morton An operating system's Secure Attention Key is a security tool which is provided as protection against trojan password capturing programs. It diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist index 21f0795af20..ac5e0b2f109 100644 --- a/Documentation/SubmitChecklist +++ b/Documentation/SubmitChecklist @@ -85,3 +85,6 @@ kernel patches. 23: Tested after it has been merged into the -mm patchset to make sure that it still works with all of the other queued patches and various changes in the VM, VFS, and other subsystems. + +24: All memory barriers {e.g., barrier(), rmb(), wmb()} need a comment in the + source code that explains the logic of what they are doing and why. diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index 24f2eb40cae..99e72a81fa2 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -41,7 +41,7 @@ Linux 2.4: Linux 2.6: The same rules apply as 2.4 except that you should follow linux-kernel to track changes in API's. The final contact point for Linux 2.6 - submissions is Andrew Morton <akpm@osdl.org>. + submissions is Andrew Morton. What Criteria Determine Acceptance ---------------------------------- diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index f79ad9ff603..f309d3c6221 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -77,7 +77,7 @@ Quilt: http://savannah.nongnu.org/projects/quilt Andrew Morton's patch scripts: -http://www.zip.com.au/~akpm/linux/patches/ +http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz Instead of these scripts, quilt is the recommended patch management tool (see above). @@ -405,7 +405,7 @@ person it names. This tag documents that potentially interested parties have been included in the discussion -14) Using Test-by: and Reviewed-by: +14) Using Tested-by: and Reviewed-by: A Tested-by: tag indicates that the patch has been successfully tested (in some environment) by the person named. This tag informs maintainers that @@ -653,7 +653,7 @@ SECTION 3 - REFERENCES ---------------------- Andrew Morton, "The perfect patch" (tpp). - <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt> + <http://userweb.kernel.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Linux kernel patch submission format". <http://linux.yyz.us/patch-format.html> @@ -672,4 +672,9 @@ Kernel Documentation/CodingStyle: Linus Torvalds's mail on the canonical patch format: <http://lkml.org/lkml/2005/4/7/183> + +Andi Kleen, "On submitting kernel patches" + Some strategies to get difficult or controversal changes in. + http://halobates.de/on-submitting-patches.pdf + -- diff --git a/Documentation/accounting/.gitignore b/Documentation/accounting/.gitignore new file mode 100644 index 00000000000..86485203c4a --- /dev/null +++ b/Documentation/accounting/.gitignore @@ -0,0 +1 @@ +getdelays diff --git a/Documentation/acpi/debug.txt b/Documentation/acpi/debug.txt new file mode 100644 index 00000000000..65bf47c46b6 --- /dev/null +++ b/Documentation/acpi/debug.txt @@ -0,0 +1,148 @@ + ACPI Debug Output + + +The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug +output. This document describes how to use this facility. + +Compile-time configuration +-------------------------- + +ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG. If this config +option is turned off, the debug messages are not even built into the +kernel. + +Boot- and run-time configuration +-------------------------------- + +When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages +you're interested in. At boot-time, use the acpi.debug_layer and +acpi.debug_level kernel command line options. After boot, you can use the +debug_layer and debug_level files in /sys/module/acpi/parameters/ to control +the debug messages. + +debug_layer (component) +----------------------- + +The "debug_layer" is a mask that selects components of interest, e.g., a +specific driver or part of the ACPI interpreter. To build the debug_layer +bitmask, look for the "#define _COMPONENT" in an ACPI source file. + +You can set the debug_layer mask at boot-time using the acpi.debug_layer +command line argument, and you can change it after boot by writing values +to /sys/module/acpi/parameters/debug_layer. + +The possible components are defined in include/acpi/acoutput.h and +include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer +shows the supported mask values, currently these: + + ACPI_UTILITIES 0x00000001 + ACPI_HARDWARE 0x00000002 + ACPI_EVENTS 0x00000004 + ACPI_TABLES 0x00000008 + ACPI_NAMESPACE 0x00000010 + ACPI_PARSER 0x00000020 + ACPI_DISPATCHER 0x00000040 + ACPI_EXECUTER 0x00000080 + ACPI_RESOURCES 0x00000100 + ACPI_CA_DEBUGGER 0x00000200 + ACPI_OS_SERVICES 0x00000400 + ACPI_CA_DISASSEMBLER 0x00000800 + ACPI_COMPILER 0x00001000 + ACPI_TOOLS 0x00002000 + ACPI_BUS_COMPONENT 0x00010000 + ACPI_AC_COMPONENT 0x00020000 + ACPI_BATTERY_COMPONENT 0x00040000 + ACPI_BUTTON_COMPONENT 0x00080000 + ACPI_SBS_COMPONENT 0x00100000 + ACPI_FAN_COMPONENT 0x00200000 + ACPI_PCI_COMPONENT 0x00400000 + ACPI_POWER_COMPONENT 0x00800000 + ACPI_CONTAINER_COMPONENT 0x01000000 + ACPI_SYSTEM_COMPONENT 0x02000000 + ACPI_THERMAL_COMPONENT 0x04000000 + ACPI_MEMORY_DEVICE_COMPONENT 0x08000000 + ACPI_VIDEO_COMPONENT 0x10000000 + ACPI_PROCESSOR_COMPONENT 0x20000000 + +debug_level +----------- + +The "debug_level" is a mask that selects different types of messages, e.g., +those related to initialization, method execution, informational messages, etc. +To build debug_level, look at the level specified in an ACPI_DEBUG_PRINT() +statement. + +The ACPI interpreter uses several different levels, but the Linux +ACPI core and ACPI drivers generally only use ACPI_LV_INFO. + +You can set the debug_level mask at boot-time using the acpi.debug_level +command line argument, and you can change it after boot by writing values +to /sys/module/acpi/parameters/debug_level. + +The possible levels are defined in include/acpi/acoutput.h. Reading +/sys/module/acpi/parameters/debug_level shows the supported mask values, +currently these: + + ACPI_LV_INIT 0x00000001 + ACPI_LV_DEBUG_OBJECT 0x00000002 + ACPI_LV_INFO 0x00000004 + ACPI_LV_INIT_NAMES 0x00000020 + ACPI_LV_PARSE 0x00000040 + ACPI_LV_LOAD 0x00000080 + ACPI_LV_DISPATCH 0x00000100 + ACPI_LV_EXEC 0x00000200 + ACPI_LV_NAMES 0x00000400 + ACPI_LV_OPREGION 0x00000800 + ACPI_LV_BFIELD 0x00001000 + ACPI_LV_TABLES 0x00002000 + ACPI_LV_VALUES 0x00004000 + ACPI_LV_OBJECTS 0x00008000 + ACPI_LV_RESOURCES 0x00010000 + ACPI_LV_USER_REQUESTS 0x00020000 + ACPI_LV_PACKAGE 0x00040000 + ACPI_LV_ALLOCATIONS 0x00100000 + ACPI_LV_FUNCTIONS 0x00200000 + ACPI_LV_OPTIMIZATIONS 0x00400000 + ACPI_LV_MUTEX 0x01000000 + ACPI_LV_THREADS 0x02000000 + ACPI_LV_IO 0x04000000 + ACPI_LV_INTERRUPTS 0x08000000 + ACPI_LV_AML_DISASSEMBLE 0x10000000 + ACPI_LV_VERBOSE_INFO 0x20000000 + ACPI_LV_FULL_TABLES 0x40000000 + ACPI_LV_EVENTS 0x80000000 + +Examples +-------- + +For example, drivers/acpi/bus.c contains this: + + #define _COMPONENT ACPI_BUS_COMPONENT + ... + ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Device insertion detected\n")); + +To turn on this message, set the ACPI_BUS_COMPONENT bit in acpi.debug_layer +and the ACPI_LV_INFO bit in acpi.debug_level. (The ACPI_DEBUG_PRINT +statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO +definition.) + +Enable all AML "Debug" output (stores to the Debug object while interpreting +AML) during boot: + + acpi.debug_layer=0xffffffff acpi.debug_level=0x2 + +Enable PCI and PCI interrupt routing debug messages: + + acpi.debug_layer=0x400000 acpi.debug_level=0x4 + +Enable all ACPI hardware-related messages: + + acpi.debug_layer=0x2 acpi.debug_level=0xffffffff + +Enable all ACPI_DB_INFO messages after boot: + + # echo 0x4 > /sys/module/acpi/parameters/debug_level + +Show all valid component values: + + # cat /sys/module/acpi/parameters/debug_layer diff --git a/Documentation/arm/empeg/README b/Documentation/arm/empeg/README deleted file mode 100644 index 09cc8d03ae5..00000000000 --- a/Documentation/arm/empeg/README +++ /dev/null @@ -1,13 +0,0 @@ -Empeg, Ltd's Empeg MP3 Car Audio Player - -The initial design is to go in your car, but you can use it at home, on a -boat... almost anywhere. The principle is to store CD-quality music using -MPEG technology onto a hard disk in the unit, and use the power of the -embedded computer to serve up the music you want. - -For more details, see: - - http://www.empeg.com - - - diff --git a/Documentation/arm/empeg/ir.txt b/Documentation/arm/empeg/ir.txt deleted file mode 100644 index 10a29745016..00000000000 --- a/Documentation/arm/empeg/ir.txt +++ /dev/null @@ -1,49 +0,0 @@ -Infra-red driver documentation. - -Mike Crowe <mac@empeg.com> -(C) Empeg Ltd 1999 - -Not a lot here yet :-) - -The Kenwood KCA-R6A remote control generates a sequence like the following: - -Go low for approx 16T (Around 9000us) -Go high for approx 8T (Around 4000us) -Go low for less than 2T (Around 750us) - -For each of the 32 bits - Go high for more than 2T (Around 1500us) == 1 - Go high for less than T (Around 400us) == 0 - Go low for less than 2T (Around 750us) - -Rather than repeat a signal when the button is held down certain buttons -generate the following code to indicate repetition. - -Go low for approx 16T -Go high for approx 4T -Go low for less than 2T - -(By removing the <2T from the start of the sequence and placing at the end - it can be considered a stop bit but I found it easier to deal with it at - the start). - -The 32 bits are encoded as XxYy where x and y are the actual data values -while X and Y are the logical inverses of the associated data values. Using -LSB first yields sensible codes for the numbers. - -All codes are of the form b9xx - -The numeric keys generate the code 0x where x is the number pressed. - -Tuner 1c -Tape 1d -CD 1e -CD-MD-CH 1f -Track- 0a -Track+ 0b -Rewind 0c -FF 0d -DNPP 5e -Play/Pause 0e -Vol+ 14 -Vol- 15 diff --git a/Documentation/arm/empeg/mkdevs b/Documentation/arm/empeg/mkdevs deleted file mode 100644 index 7a85e28d14f..00000000000 --- a/Documentation/arm/empeg/mkdevs +++ /dev/null @@ -1,11 +0,0 @@ -#!/bin/sh -mknod /dev/display c 244 0 -mknod /dev/ir c 242 0 -mknod /dev/usb0 c 243 0 -mknod /dev/audio c 245 4 -mknod /dev/dsp c 245 3 -mknod /dev/mixer c 245 0 -mknod /dev/empeg_state c 246 0 -mknod /dev/radio0 c 81 64 -ln -sf radio0 radio -ln -sf usb0 usb diff --git a/Documentation/arm/mem_alignment b/Documentation/arm/mem_alignment index d145ccca169..c7c7a114c78 100644 --- a/Documentation/arm/mem_alignment +++ b/Documentation/arm/mem_alignment @@ -24,7 +24,7 @@ real bad - it changes the behaviour of all unaligned instructions in user space, and might cause programs to fail unexpectedly. To change the alignment trap behavior, simply echo a number into -/proc/sys/debug/alignment. The number is made up from various bits: +/proc/cpu/alignment. The number is made up from various bits: bit behavior when set --- ----------------- diff --git a/Documentation/arm/pxa/mfp.txt b/Documentation/arm/pxa/mfp.txt new file mode 100644 index 00000000000..a179e5bc02c --- /dev/null +++ b/Documentation/arm/pxa/mfp.txt @@ -0,0 +1,286 @@ + MFP Configuration for PXA2xx/PXA3xx Processors + + Eric Miao <eric.miao@marvell.com> + +MFP stands for Multi-Function Pin, which is the pin-mux logic on PXA3xx and +later PXA series processors. This document describes the existing MFP API, +and how board/platform driver authors could make use of it. + + Basic Concept +=============== + +Unlike the GPIO alternate function settings on PXA25x and PXA27x, a new MFP +mechanism is introduced from PXA3xx to completely move the pin-mux functions +out of the GPIO controller. In addition to pin-mux configurations, the MFP +also controls the low power state, driving strength, pull-up/down and event +detection of each pin. Below is a diagram of internal connections between +the MFP logic and the remaining SoC peripherals: + + +--------+ + | |--(GPIO19)--+ + | GPIO | | + | |--(GPIO...) | + +--------+ | + | +---------+ + +--------+ +------>| | + | PWM2 |--(PWM_OUT)-------->| MFP | + +--------+ +------>| |-------> to external PAD + | +---->| | + +--------+ | | +-->| | + | SSP2 |---(TXD)----+ | | +---------+ + +--------+ | | + | | + +--------+ | | + | Keypad |--(MKOUT4)----+ | + +--------+ | + | + +--------+ | + | UART2 |---(TXD)--------+ + +--------+ + +NOTE: the external pad is named as MFP_PIN_GPIO19, it doesn't necessarily +mean it's dedicated for GPIO19, only as a hint that internally this pin +can be routed from GPIO19 of the GPIO controller. + +To better understand the change from PXA25x/PXA27x GPIO alternate function +to this new MFP mechanism, here are several key points: + + 1. GPIO controller on PXA3xx is now a dedicated controller, same as other + internal controllers like PWM, SSP and UART, with 128 internal signals + which can be routed to external through one or more MFPs (e.g. GPIO<0> + can be routed through either MFP_PIN_GPIO0 as well as MFP_PIN_GPIO0_2, + see arch/arm/mach-pxa/mach/include/mfp-pxa300.h) + + 2. Alternate function configuration is removed from this GPIO controller, + the remaining functions are pure GPIO-specific, i.e. + + - GPIO signal level control + - GPIO direction control + - GPIO level change detection + + 3. Low power state for each pin is now controlled by MFP, this means the + PGSRx registers on PXA2xx are now useless on PXA3xx + + 4. Wakeup detection is now controlled by MFP, PWER does not control the + wakeup from GPIO(s) any more, depending on the sleeping state, ADxER + (as defined in pxa3xx-regs.h) controls the wakeup from MFP + +NOTE: with such a clear separation of MFP and GPIO, by GPIO<xx> we normally +mean it is a GPIO signal, and by MFP<xxx> or pin xxx, we mean a physical +pad (or ball). + + MFP API Usage +=============== + +For board code writers, here are some guidelines: + +1. include ONE of the following header files in your <board>.c: + + - #include <mach/mfp-pxa25x.h> + - #include <mach/mfp-pxa27x.h> + - #include <mach/mfp-pxa300.h> + - #include <mach/mfp-pxa320.h> + - #include <mach/mfp-pxa930.h> + + NOTE: only one file in your <board>.c, depending on the processors used, + because pin configuration definitions may conflict in these file (i.e. + same name, different meaning and settings on different processors). E.g. + for zylonite platform, which support both PXA300/PXA310 and PXA320, two + separate files are introduced: zylonite_pxa300.c and zylonite_pxa320.c + (in addition to handle MFP configuration differences, they also handle + the other differences between the two combinations). + + NOTE: PXA300 and PXA310 are almost identical in pin configurations (with + PXA310 supporting some additional ones), thus the difference is actually + covered in a single mfp-pxa300.h. + +2. prepare an array for the initial pin configurations, e.g.: + + static unsigned long mainstone_pin_config[] __initdata = { + /* Chip Select */ + GPIO15_nCS_1, + + /* LCD - 16bpp Active TFT */ + GPIOxx_TFT_LCD_16BPP, + GPIO16_PWM0_OUT, /* Backlight */ + + /* MMC */ + GPIO32_MMC_CLK, + GPIO112_MMC_CMD, + GPIO92_MMC_DAT_0, + GPIO109_MMC_DAT_1, + GPIO110_MMC_DAT_2, + GPIO111_MMC_DAT_3, + + ... + + /* GPIO */ + GPIO1_GPIO | WAKEUP_ON_EDGE_BOTH, + }; + + a) once the pin configurations are passed to pxa{2xx,3xx}_mfp_config(), + and written to the actual registers, they are useless and may discard, + adding '__initdata' will help save some additional bytes here. + + b) when there is only one possible pin configurations for a component, + some simplified definitions can be used, e.g. GPIOxx_TFT_LCD_16BPP on + PXA25x and PXA27x processors + + c) if by board design, a pin can be configured to wake up the system + from low power state, it can be 'OR'ed with any of: + + WAKEUP_ON_EDGE_BOTH + WAKEUP_ON_EDGE_RISE + WAKEUP_ON_EDGE_FALL + WAKEUP_ON_LEVEL_HIGH - specifically for enabling of keypad GPIOs, + + to indicate that this pin has the capability of wake-up the system, + and on which edge(s). This, however, doesn't necessarily mean the + pin _will_ wakeup the system, it will only when set_irq_wake() is + invoked with the corresponding GPIO IRQ (GPIO_IRQ(xx) or gpio_to_irq()) + and eventually calls gpio_set_wake() for the actual register setting. + + d) although PXA3xx MFP supports edge detection on each pin, the + internal logic will only wakeup the system when those specific bits + in ADxER registers are set, which can be well mapped to the + corresponding peripheral, thus set_irq_wake() can be called with + the peripheral IRQ to enable the wakeup. + + + MFP on PXA3xx +=============== + +Every external I/O pad on PXA3xx (excluding those for special purpose) has +one MFP logic associated, and is controlled by one MFP register (MFPR). + +The MFPR has the following bit definitions (for PXA300/PXA310/PXA320): + + 31 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + | RESERVED |PS|PU|PD| DRIVE |SS|SD|SO|EC|EF|ER|--| AF_SEL | + +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + + Bit 3: RESERVED + Bit 4: EDGE_RISE_EN - enable detection of rising edge on this pin + Bit 5: EDGE_FALL_EN - enable detection of falling edge on this pin + Bit 6: EDGE_CLEAR - disable edge detection on this pin + Bit 7: SLEEP_OE_N - enable outputs during low power modes + Bit 8: SLEEP_DATA - output data on the pin during low power modes + Bit 9: SLEEP_SEL - selection control for low power modes signals + Bit 13: PULLDOWN_EN - enable the internal pull-down resistor on this pin + Bit 14: PULLUP_EN - enable the internal pull-up resistor on this pin + Bit 15: PULL_SEL - pull state controlled by selected alternate function + (0) or by PULL{UP,DOWN}_EN bits (1) + + Bit 0 - 2: AF_SEL - alternate function selection, 8 possibilities, from 0-7 + Bit 10-12: DRIVE - drive strength and slew rate + 0b000 - fast 1mA + 0b001 - fast 2mA + 0b002 - fast 3mA + 0b003 - fast 4mA + 0b004 - slow 6mA + 0b005 - fast 6mA + 0b006 - slow 10mA + 0b007 - fast 10mA + + MFP Design for PXA2xx/PXA3xx +============================== + +Due to the difference of pin-mux handling between PXA2xx and PXA3xx, a unified +MFP API is introduced to cover both series of processors. + +The basic idea of this design is to introduce definitions for all possible pin +configurations, these definitions are processor and platform independent, and +the actual API invoked to convert these definitions into register settings and +make them effective there-after. + + Files Involved + -------------- + + - arch/arm/mach-pxa/include/mach/mfp.h + + for + 1. Unified pin definitions - enum constants for all configurable pins + 2. processor-neutral bit definitions for a possible MFP configuration + + - arch/arm/mach-pxa/include/mach/mfp-pxa3xx.h + + for PXA3xx specific MFPR register bit definitions and PXA3xx common pin + configurations + + - arch/arm/mach-pxa/include/mach/mfp-pxa2xx.h + + for PXA2xx specific definitions and PXA25x/PXA27x common pin configurations + + - arch/arm/mach-pxa/include/mach/mfp-pxa25x.h + arch/arm/mach-pxa/include/mach/mfp-pxa27x.h + arch/arm/mach-pxa/include/mach/mfp-pxa300.h + arch/arm/mach-pxa/include/mach/mfp-pxa320.h + arch/arm/mach-pxa/include/mach/mfp-pxa930.h + + for processor specific definitions + + - arch/arm/mach-pxa/mfp-pxa3xx.c + - arch/arm/mach-pxa/mfp-pxa2xx.c + + for implementation of the pin configuration to take effect for the actual + processor. + + Pin Configuration + ----------------- + + The following comments are copied from mfp.h (see the actual source code + for most updated info) + + /* + * a possible MFP configuration is represented by a 32-bit integer + * + * bit 0.. 9 - MFP Pin Number (1024 Pins Maximum) + * bit 10..12 - Alternate Function Selection + * bit 13..15 - Drive Strength + * bit 16..18 - Low Power Mode State + * bit 19..20 - Low Power Mode Edge Detection + * bit 21..22 - Run Mode Pull State + * + * to facilitate the definition, the following macros are provided + * + * MFP_CFG_DEFAULT - default MFP configuration value, with + * alternate function = 0, + * drive strength = fast 3mA (MFP_DS03X) + * low power mode = default + * edge detection = none + * + * MFP_CFG - default MFPR value with alternate function + * MFP_CFG_DRV - default MFPR value with alternate function and + * pin drive strength + * MFP_CFG_LPM - default MFPR value with alternate function and + * low power mode + * MFP_CFG_X - default MFPR value with alternate function, + * pin drive strength and low power mode + */ + + Examples of pin configurations are: + + #define GPIO94_SSP3_RXD MFP_CFG_X(GPIO94, AF1, DS08X, FLOAT) + + which reads GPIO94 can be configured as SSP3_RXD, with alternate function + selection of 1, driving strength of 0b101, and a float state in low power + modes. + + NOTE: this is the default setting of this pin being configured as SSP3_RXD + which can be modified a bit in board code, though it is not recommended to + do so, simply because this default setting is usually carefully encoded, + and is supposed to work in most cases. + + Register Settings + ----------------- + + Register settings on PXA3xx for a pin configuration is actually very + straight-forward, most bits can be converted directly into MFPR value + in a easier way. Two sets of MFPR values are calculated: the run-time + ones and the low power mode ones, to allow different settings. + + The conversion from a generic pin configuration to the actual register + settings on PXA2xx is a bit complicated: many registers are involved, + including GAFRx, GPDRx, PGSRx, PWER, PKWR, PFER and PRER. Please see + mfp-pxa2xx.c for how the conversion is made. diff --git a/Documentation/auxdisplay/.gitignore b/Documentation/auxdisplay/.gitignore new file mode 100644 index 00000000000..7af222860a9 --- /dev/null +++ b/Documentation/auxdisplay/.gitignore @@ -0,0 +1 @@ +cfag12864b-example diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index 4dbb8be1c99..3c5434c83da 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -914,7 +914,7 @@ I/O scheduler, a.k.a. elevator, is implemented in two layers. Generic dispatch queue and specific I/O schedulers. Unless stated otherwise, elevator is used to refer to both parts and I/O scheduler to specific I/O schedulers. -Block layer implements generic dispatch queue in ll_rw_blk.c and elevator.c. +Block layer implements generic dispatch queue in block/*.c. The generic dispatch queue is responsible for properly ordering barrier requests, requeueing, handling non-fs requests and all other subtleties. @@ -926,8 +926,8 @@ be built inside the kernel. Each queue can choose different one and can also change to another one dynamically. A block layer call to the i/o scheduler follows the convention elv_xxx(). This -calls elevator_xxx_fn in the elevator switch (drivers/block/elevator.c). Oh, -xxx and xxx might not match exactly, but use your imagination. If an elevator +calls elevator_xxx_fn in the elevator switch (block/elevator.c). Oh, xxx +and xxx might not match exactly, but use your imagination. If an elevator doesn't implement a function, the switch does nothing or some minimal house keeping work. diff --git a/Documentation/block/data-integrity.txt b/Documentation/block/data-integrity.txt index e9dc8d86adc..e8ca040ba2c 100644 --- a/Documentation/block/data-integrity.txt +++ b/Documentation/block/data-integrity.txt @@ -246,7 +246,7 @@ will require extra work due to the application tag. retrieve the tag buffer using bio_integrity_get_tag(). -6.3 PASSING EXISTING INTEGRITY METADATA +5.3 PASSING EXISTING INTEGRITY METADATA Filesystems that either generate their own integrity metadata or are capable of transferring IMD from user space can use the @@ -283,7 +283,7 @@ will require extra work due to the application tag. integrity upon completion. -6.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY +5.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY METADATA To enable integrity exchange on a block device the gendisk must be diff --git a/Documentation/blockdev/00-INDEX b/Documentation/blockdev/00-INDEX new file mode 100644 index 00000000000..86f054c4701 --- /dev/null +++ b/Documentation/blockdev/00-INDEX @@ -0,0 +1,16 @@ +00-INDEX + - this file +README.DAC960 + - info on Mylex DAC960/DAC1100 PCI RAID Controller Driver for Linux. +cciss.txt + - info, major/minor #'s for Compaq's SMART Array Controllers. +cpqarray.txt + - info on using Compaq's SMART2 Intelligent Disk Array Controllers. +floppy.txt + - notes and driver options for the floppy disk driver. +nbd.txt + - info on a TCP implementation of a network block device. +paride.txt + - information about the parallel port IDE subsystem. +ramdisk.txt + - short guide on how to set up and use the RAM disk. diff --git a/Documentation/README.DAC960 b/Documentation/blockdev/README.DAC960 index 0e8f618ab53..0e8f618ab53 100644 --- a/Documentation/README.DAC960 +++ b/Documentation/blockdev/README.DAC960 diff --git a/Documentation/cciss.txt b/Documentation/blockdev/cciss.txt index 8244c6442fa..89698e8df7d 100644 --- a/Documentation/cciss.txt +++ b/Documentation/blockdev/cciss.txt @@ -21,11 +21,14 @@ This driver is known to work with the following cards: * SA E200 * SA E200i * SA E500 + * SA P700m * SA P212 * SA P410 * SA P410i * SA P411 * SA P812 + * SA P712m + * SA P711m Detecting drive failures: ------------------------- diff --git a/Documentation/cpqarray.txt b/Documentation/blockdev/cpqarray.txt index c7154e20ef5..c7154e20ef5 100644 --- a/Documentation/cpqarray.txt +++ b/Documentation/blockdev/cpqarray.txt diff --git a/Documentation/floppy.txt b/Documentation/blockdev/floppy.txt index 6ccab88705c..6ccab88705c 100644 --- a/Documentation/floppy.txt +++ b/Documentation/blockdev/floppy.txt diff --git a/Documentation/nbd.txt b/Documentation/blockdev/nbd.txt index aeb93ffe641..aeb93ffe641 100644 --- a/Documentation/nbd.txt +++ b/Documentation/blockdev/nbd.txt diff --git a/Documentation/paride.txt b/Documentation/blockdev/paride.txt index e4312676bdd..e4312676bdd 100644 --- a/Documentation/paride.txt +++ b/Documentation/blockdev/paride.txt diff --git a/Documentation/ramdisk.txt b/Documentation/blockdev/ramdisk.txt index 6c820baa19a..6c820baa19a 100644 --- a/Documentation/ramdisk.txt +++ b/Documentation/blockdev/ramdisk.txt diff --git a/Documentation/c2port.txt b/Documentation/c2port.txt new file mode 100644 index 00000000000..d9bf93ea439 --- /dev/null +++ b/Documentation/c2port.txt @@ -0,0 +1,90 @@ + C2 port support + --------------- + +(C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com> + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + + + +Overview +-------- + +This driver implements the support for Linux of Silicon Labs (Silabs) +C2 Interface used for in-system programming of micro controllers. + +By using this driver you can reprogram the in-system flash without EC2 +or EC3 debug adapter. This solution is also useful in those systems +where the micro controller is connected via special GPIOs pins. + +References +---------- + +The C2 Interface main references are at (http://www.silabs.com) +Silicon Laboratories site], see: + +- AN127: FLASH Programming via the C2 Interface at +http://www.silabs.com/public/documents/tpub_doc/anote/Microcontrollers/Small_Form_Factor/en/an127.pdf, and + +- C2 Specification at +http://www.silabs.com/public/documents/tpub_doc/spec/Microcontrollers/en/C2spec.pdf, + +however it implements a two wire serial communication protocol (bit +banging) designed to enable in-system programming, debugging, and +boundary-scan testing on low pin-count Silicon Labs devices. Currently +this code supports only flash programming but extensions are easy to +add. + +Using the driver +---------------- + +Once the driver is loaded you can use sysfs support to get C2port's +info or read/write in-system flash. + +# ls /sys/class/c2port/c2port0/ +access flash_block_size flash_erase rev_id +dev_id flash_blocks_num flash_size subsystem/ +flash_access flash_data reset uevent + +Initially the C2port access is disabled since you hardware may have +such lines multiplexed with other devices so, to get access to the +C2port, you need the command: + +# echo 1 > /sys/class/c2port/c2port0/access + +after that you should read the device ID and revision ID of the +connected micro controller: + +# cat /sys/class/c2port/c2port0/dev_id +8 +# cat /sys/class/c2port/c2port0/rev_id +1 + +However, for security reasons, the in-system flash access in not +enabled yet, to do so you need the command: + +# echo 1 > /sys/class/c2port/c2port0/flash_access + +After that you can read the whole flash: + +# cat /sys/class/c2port/c2port0/flash_data > image + +erase it: + +# echo 1 > /sys/class/c2port/c2port0/flash_erase + +and write it: + +# cat image > /sys/class/c2port/c2port0/flash_data + +after writing you have to reset the device to execute the new code: + +# echo 1 > /sys/class/c2port/c2port0/reset diff --git a/Documentation/cgroups.txt b/Documentation/cgroups/cgroups.txt index d9014aa0eb6..d9014aa0eb6 100644 --- a/Documentation/cgroups.txt +++ b/Documentation/cgroups/cgroups.txt diff --git a/Documentation/cgroups/freezer-subsystem.txt b/Documentation/cgroups/freezer-subsystem.txt new file mode 100644 index 00000000000..41f37fea127 --- /dev/null +++ b/Documentation/cgroups/freezer-subsystem.txt @@ -0,0 +1,102 @@ +The cgroup freezer is useful to batch job management system which start +and stop sets of tasks in order to schedule the resources of a machine +according to the desires of a system administrator. This sort of program +is often used on HPC clusters to schedule access to the cluster as a +whole. The cgroup freezer uses cgroups to describe the set of tasks to +be started/stopped by the batch job management system. It also provides +a means to start and stop the tasks composing the job. + +The cgroup freezer will also be useful for checkpointing running groups +of tasks. The freezer allows the checkpoint code to obtain a consistent +image of the tasks by attempting to force the tasks in a cgroup into a +quiescent state. Once the tasks are quiescent another task can +walk /proc or invoke a kernel interface to gather information about the +quiesced tasks. Checkpointed tasks can be restarted later should a +recoverable error occur. This also allows the checkpointed tasks to be +migrated between nodes in a cluster by copying the gathered information +to another node and restarting the tasks there. + +Sequences of SIGSTOP and SIGCONT are not always sufficient for stopping +and resuming tasks in userspace. Both of these signals are observable +from within the tasks we wish to freeze. While SIGSTOP cannot be caught, +blocked, or ignored it can be seen by waiting or ptracing parent tasks. +SIGCONT is especially unsuitable since it can be caught by the task. Any +programs designed to watch for SIGSTOP and SIGCONT could be broken by +attempting to use SIGSTOP and SIGCONT to stop and resume tasks. We can +demonstrate this problem using nested bash shells: + + $ echo $$ + 16644 + $ bash + $ echo $$ + 16690 + + From a second, unrelated bash shell: + $ kill -SIGSTOP 16690 + $ kill -SIGCONT 16990 + + <at this point 16990 exits and causes 16644 to exit too> + +This happens because bash can observe both signals and choose how it +responds to them. + +Another example of a program which catches and responds to these +signals is gdb. In fact any program designed to use ptrace is likely to +have a problem with this method of stopping and resuming tasks. + +In contrast, the cgroup freezer uses the kernel freezer code to +prevent the freeze/unfreeze cycle from becoming visible to the tasks +being frozen. This allows the bash example above and gdb to run as +expected. + +The freezer subsystem in the container filesystem defines a file named +freezer.state. Writing "FROZEN" to the state file will freeze all tasks in the +cgroup. Subsequently writing "THAWED" will unfreeze the tasks in the cgroup. +Reading will return the current state. + +Note freezer.state doesn't exist in root cgroup, which means root cgroup +is non-freezable. + +* Examples of usage : + + # mkdir /containers + # mount -t cgroup -ofreezer freezer /containers + # mkdir /containers/0 + # echo $some_pid > /containers/0/tasks + +to get status of the freezer subsystem : + + # cat /containers/0/freezer.state + THAWED + +to freeze all tasks in the container : + + # echo FROZEN > /containers/0/freezer.state + # cat /containers/0/freezer.state + FREEZING + # cat /containers/0/freezer.state + FROZEN + +to unfreeze all tasks in the container : + + # echo THAWED > /containers/0/freezer.state + # cat /containers/0/freezer.state + THAWED + +This is the basic mechanism which should do the right thing for user space task +in a simple scenario. + +It's important to note that freezing can be incomplete. In that case we return +EBUSY. This means that some tasks in the cgroup are busy doing something that +prevents us from completely freezing the cgroup at this time. After EBUSY, +the cgroup will remain partially frozen -- reflected by freezer.state reporting +"FREEZING" when read. The state will remain "FREEZING" until one of these +things happens: + + 1) Userspace cancels the freezing operation by writing "THAWED" to + the freezer.state file + 2) Userspace retries the freezing operation by writing "FROZEN" to + the freezer.state file (writing "FREEZING" is not legal + and returns EINVAL) + 3) The tasks that blocked the cgroup from entering the "FROZEN" + state disappear from the cgroup's set of tasks. diff --git a/Documentation/connector/.gitignore b/Documentation/connector/.gitignore new file mode 100644 index 00000000000..d2b9c32accd --- /dev/null +++ b/Documentation/connector/.gitignore @@ -0,0 +1 @@ +ucon diff --git a/Documentation/controllers/cpuacct.txt b/Documentation/controllers/cpuacct.txt new file mode 100644 index 00000000000..bb775fbe43d --- /dev/null +++ b/Documentation/controllers/cpuacct.txt @@ -0,0 +1,32 @@ +CPU Accounting Controller +------------------------- + +The CPU accounting controller is used to group tasks using cgroups and +account the CPU usage of these groups of tasks. + +The CPU accounting controller supports multi-hierarchy groups. An accounting +group accumulates the CPU usage of all of its child groups and the tasks +directly present in its group. + +Accounting groups can be created by first mounting the cgroup filesystem. + +# mkdir /cgroups +# mount -t cgroup -ocpuacct none /cgroups + +With the above step, the initial or the parent accounting group +becomes visible at /cgroups. At bootup, this group includes all the +tasks in the system. /cgroups/tasks lists the tasks in this cgroup. +/cgroups/cpuacct.usage gives the CPU time (in nanoseconds) obtained by +this group which is essentially the CPU time obtained by all the tasks +in the system. + +New accounting groups can be created under the parent group /cgroups. + +# cd /cgroups +# mkdir g1 +# echo $$ > g1 + +The above steps create a new group g1 and move the current shell +process (bash) into it. CPU time consumed by this bash and its children +can be obtained from g1/cpuacct.usage and the same is accumulated in +/cgroups/cpuacct.usage also. diff --git a/Documentation/controllers/memory.txt b/Documentation/controllers/memory.txt index 9b53d582736..1c07547d3f8 100644 --- a/Documentation/controllers/memory.txt +++ b/Documentation/controllers/memory.txt @@ -112,14 +112,22 @@ the per cgroup LRU. 2.2.1 Accounting details -All mapped pages (RSS) and unmapped user pages (Page Cache) are accounted. -RSS pages are accounted at the time of page_add_*_rmap() unless they've already -been accounted for earlier. A file page will be accounted for as Page Cache; -it's mapped into the page tables of a process, duplicate accounting is carefully -avoided. Page Cache pages are accounted at the time of add_to_page_cache(). -The corresponding routines that remove a page from the page tables or removes -a page from Page Cache is used to decrement the accounting counters of the -cgroup. +All mapped anon pages (RSS) and cache pages (Page Cache) are accounted. +(some pages which never be reclaimable and will not be on global LRU + are not accounted. we just accounts pages under usual vm management.) + +RSS pages are accounted at page_fault unless they've already been accounted +for earlier. A file page will be accounted for as Page Cache when it's +inserted into inode (radix-tree). While it's mapped into the page tables of +processes, duplicate accounting is carefully avoided. + +A RSS page is unaccounted when it's fully unmapped. A PageCache page is +unaccounted when it's removed from radix-tree. + +At page migration, accounting information is kept. + +Note: we just account pages-on-lru because our purpose is to control amount +of used pages. not-on-lru pages are tend to be out-of-control from vm view. 2.3 Shared Page Accounting diff --git a/Documentation/cpu-freq/user-guide.txt b/Documentation/cpu-freq/user-guide.txt index 6c442d8426b..e3443ddcfb8 100644 --- a/Documentation/cpu-freq/user-guide.txt +++ b/Documentation/cpu-freq/user-guide.txt @@ -23,6 +23,7 @@ Contents: 1.3 sparc64 1.4 ppc 1.5 SuperH +1.6 Blackfin 2. "Policy" / "Governor"? 2.1 Policy @@ -92,10 +93,19 @@ Several "PowerBook" and "iBook2" notebooks are supported. 1.5 SuperH ---------- -The following SuperH processors are supported by cpufreq: +All SuperH processors supporting rate rounding through the clock +framework are supported by cpufreq. -SH-3 -SH-4 +1.6 Blackfin +------------ + +The following Blackfin processors are supported by cpufreq: + +BF522, BF523, BF524, BF525, BF526, BF527, Rev 0.1 or higher +BF531, BF532, BF533, Rev 0.3 or higher +BF534, BF536, BF537, Rev 0.2 or higher +BF561, Rev 0.3 or higher +BF542, BF544, BF547, BF548, BF549, Rev 0.1 or higher 2. "Policy" / "Governor" ? diff --git a/Documentation/cpusets.txt b/Documentation/cpusets.txt index 47e568a9370..5c86c258c79 100644 --- a/Documentation/cpusets.txt +++ b/Documentation/cpusets.txt @@ -48,7 +48,7 @@ hooks, beyond what is already present, required to manage dynamic job placement on large systems. Cpusets use the generic cgroup subsystem described in -Documentation/cgroup.txt. +Documentation/cgroups/cgroups.txt. Requests by a task, using the sched_setaffinity(2) system call to include CPUs in its CPU affinity mask, and using the mbind(2) and diff --git a/Documentation/credentials.txt b/Documentation/credentials.txt new file mode 100644 index 00000000000..df03169782e --- /dev/null +++ b/Documentation/credentials.txt @@ -0,0 +1,582 @@ + ==================== + CREDENTIALS IN LINUX + ==================== + +By: David Howells <dhowells@redhat.com> + +Contents: + + (*) Overview. + + (*) Types of credentials. + + (*) File markings. + + (*) Task credentials. + + - Immutable credentials. + - Accessing task credentials. + - Accessing another task's credentials. + - Altering credentials. + - Managing credentials. + + (*) Open file credentials. + + (*) Overriding the VFS's use of credentials. + + +======== +OVERVIEW +======== + +There are several parts to the security check performed by Linux when one +object acts upon another: + + (1) Objects. + + Objects are things in the system that may be acted upon directly by + userspace programs. Linux has a variety of actionable objects, including: + + - Tasks + - Files/inodes + - Sockets + - Message queues + - Shared memory segments + - Semaphores + - Keys + + As a part of the description of all these objects there is a set of + credentials. What's in the set depends on the type of object. + + (2) Object ownership. + + Amongst the credentials of most objects, there will be a subset that + indicates the ownership of that object. This is used for resource + accounting and limitation (disk quotas and task rlimits for example). + + In a standard UNIX filesystem, for instance, this will be defined by the + UID marked on the inode. + + (3) The objective context. + + Also amongst the credentials of those objects, there will be a subset that + indicates the 'objective context' of that object. This may or may not be + the same set as in (2) - in standard UNIX files, for instance, this is the + defined by the UID and the GID marked on the inode. + + The objective context is used as part of the security calculation that is + carried out when an object is acted upon. + + (4) Subjects. + + A subject is an object that is acting upon another object. + + Most of the objects in the system are inactive: they don't act on other + objects within the system. Processes/tasks are the obvious exception: + they do stuff; they access and manipulate things. + + Objects other than tasks may under some circumstances also be subjects. + For instance an open file may send SIGIO to a task using the UID and EUID + given to it by a task that called fcntl(F_SETOWN) upon it. In this case, + the file struct will have a subjective context too. + + (5) The subjective context. + + A subject has an additional interpretation of its credentials. A subset + of its credentials forms the 'subjective context'. The subjective context + is used as part of the security calculation that is carried out when a + subject acts. + + A Linux task, for example, has the FSUID, FSGID and the supplementary + group list for when it is acting upon a file - which are quite separate + from the real UID and GID that normally form the objective context of the + task. + + (6) Actions. + + Linux has a number of actions available that a subject may perform upon an + object. The set of actions available depends on the nature of the subject + and the object. + + Actions include reading, writing, creating and deleting files; forking or + signalling and tracing tasks. + + (7) Rules, access control lists and security calculations. + + When a subject acts upon an object, a security calculation is made. This + involves taking the subjective context, the objective context and the + action, and searching one or more sets of rules to see whether the subject + is granted or denied permission to act in the desired manner on the + object, given those contexts. + + There are two main sources of rules: + + (a) Discretionary access control (DAC): + + Sometimes the object will include sets of rules as part of its + description. This is an 'Access Control List' or 'ACL'. A Linux + file may supply more than one ACL. + + A traditional UNIX file, for example, includes a permissions mask that + is an abbreviated ACL with three fixed classes of subject ('user', + 'group' and 'other'), each of which may be granted certain privileges + ('read', 'write' and 'execute' - whatever those map to for the object + in question). UNIX file permissions do not allow the arbitrary + specification of subjects, however, and so are of limited use. + + A Linux file might also sport a POSIX ACL. This is a list of rules + that grants various permissions to arbitrary subjects. + + (b) Mandatory access control (MAC): + + The system as a whole may have one or more sets of rules that get + applied to all subjects and objects, regardless of their source. + SELinux and Smack are examples of this. + + In the case of SELinux and Smack, each object is given a label as part + of its credentials. When an action is requested, they take the + subject label, the object label and the action and look for a rule + that says that this action is either granted or denied. + + +==================== +TYPES OF CREDENTIALS +==================== + +The Linux kernel supports the following types of credentials: + + (1) Traditional UNIX credentials. + + Real User ID + Real Group ID + + The UID and GID are carried by most, if not all, Linux objects, even if in + some cases it has to be invented (FAT or CIFS files for example, which are + derived from Windows). These (mostly) define the objective context of + that object, with tasks being slightly different in some cases. + + Effective, Saved and FS User ID + Effective, Saved and FS Group ID + Supplementary groups + + These are additional credentials used by tasks only. Usually, an + EUID/EGID/GROUPS will be used as the subjective context, and real UID/GID + will be used as the objective. For tasks, it should be noted that this is + not always true. + + (2) Capabilities. + + Set of permitted capabilities + Set of inheritable capabilities + Set of effective capabilities + Capability bounding set + + These are only carried by tasks. They indicate superior capabilities + granted piecemeal to a task that an ordinary task wouldn't otherwise have. + These are manipulated implicitly by changes to the traditional UNIX + credentials, but can also be manipulated directly by the capset() system + call. + + The permitted capabilities are those caps that the process might grant + itself to its effective or permitted sets through capset(). This + inheritable set might also be so constrained. + + The effective capabilities are the ones that a task is actually allowed to + make use of itself. + + The inheritable capabilities are the ones that may get passed across + execve(). + + The bounding set limits the capabilities that may be inherited across + execve(), especially when a binary is executed that will execute as UID 0. + + (3) Secure management flags (securebits). + + These are only carried by tasks. These govern the way the above + credentials are manipulated and inherited over certain operations such as + execve(). They aren't used directly as objective or subjective + credentials. + + (4) Keys and keyrings. + + These are only carried by tasks. They carry and cache security tokens + that don't fit into the other standard UNIX credentials. They are for + making such things as network filesystem keys available to the file + accesses performed by processes, without the necessity of ordinary + programs having to know about security details involved. + + Keyrings are a special type of key. They carry sets of other keys and can + be searched for the desired key. Each process may subscribe to a number + of keyrings: + + Per-thread keying + Per-process keyring + Per-session keyring + + When a process accesses a key, if not already present, it will normally be + cached on one of these keyrings for future accesses to find. + + For more information on using keys, see Documentation/keys.txt. + + (5) LSM + + The Linux Security Module allows extra controls to be placed over the + operations that a task may do. Currently Linux supports two main + alternate LSM options: SELinux and Smack. + + Both work by labelling the objects in a system and then applying sets of + rules (policies) that say what operations a task with one label may do to + an object with another label. + + (6) AF_KEY + + This is a socket-based approach to credential management for networking + stacks [RFC 2367]. It isn't discussed by this document as it doesn't + interact directly with task and file credentials; rather it keeps system + level credentials. + + +When a file is opened, part of the opening task's subjective context is +recorded in the file struct created. This allows operations using that file +struct to use those credentials instead of the subjective context of the task +that issued the operation. An example of this would be a file opened on a +network filesystem where the credentials of the opened file should be presented +to the server, regardless of who is actually doing a read or a write upon it. + + +============= +FILE MARKINGS +============= + +Files on disk or obtained over the network may have annotations that form the +objective security context of that file. Depending on the type of filesystem, +this may include one or more of the following: + + (*) UNIX UID, GID, mode; + + (*) Windows user ID; + + (*) Access control list; + + (*) LSM security label; + + (*) UNIX exec privilege escalation bits (SUID/SGID); + + (*) File capabilities exec privilege escalation bits. + +These are compared to the task's subjective security context, and certain +operations allowed or disallowed as a result. In the case of execve(), the +privilege escalation bits come into play, and may allow the resulting process +extra privileges, based on the annotations on the executable file. + + +================ +TASK CREDENTIALS +================ + +In Linux, all of a task's credentials are held in (uid, gid) or through +(groups, keys, LSM security) a refcounted structure of type 'struct cred'. +Each task points to its credentials by a pointer called 'cred' in its +task_struct. + +Once a set of credentials has been prepared and committed, it may not be +changed, barring the following exceptions: + + (1) its reference count may be changed; + + (2) the reference count on the group_info struct it points to may be changed; + + (3) the reference count on the security data it points to may be changed; + + (4) the reference count on any keyrings it points to may be changed; + + (5) any keyrings it points to may be revoked, expired or have their security + attributes changed; and + + (6) the contents of any keyrings to which it points may be changed (the whole + point of keyrings being a shared set of credentials, modifiable by anyone + with appropriate access). + +To alter anything in the cred struct, the copy-and-replace principle must be +adhered to. First take a copy, then alter the copy and then use RCU to change +the task pointer to make it point to the new copy. There are wrappers to aid +with this (see below). + +A task may only alter its _own_ credentials; it is no longer permitted for a +task to alter another's credentials. This means the capset() system call is no +longer permitted to take any PID other than the one of the current process. +Also keyctl_instantiate() and keyctl_negate() functions no longer permit +attachment to process-specific keyrings in the requesting process as the +instantiating process may need to create them. + + +IMMUTABLE CREDENTIALS +--------------------- + +Once a set of credentials has been made public (by calling commit_creds() for +example), it must be considered immutable, barring two exceptions: + + (1) The reference count may be altered. + + (2) Whilst the keyring subscriptions of a set of credentials may not be + changed, the keyrings subscribed to may have their contents altered. + +To catch accidental credential alteration at compile time, struct task_struct +has _const_ pointers to its credential sets, as does struct file. Furthermore, +certain functions such as get_cred() and put_cred() operate on const pointers, +thus rendering casts unnecessary, but require to temporarily ditch the const +qualification to be able to alter the reference count. + + +ACCESSING TASK CREDENTIALS +-------------------------- + +A task being able to alter only its own credentials permits the current process +to read or replace its own credentials without the need for any form of locking +- which simplifies things greatly. It can just call: + + const struct cred *current_cred() + +to get a pointer to its credentials structure, and it doesn't have to release +it afterwards. + +There are convenience wrappers for retrieving specific aspects of a task's +credentials (the value is simply returned in each case): + + uid_t current_uid(void) Current's real UID + gid_t current_gid(void) Current's real GID + uid_t current_euid(void) Current's effective UID + gid_t current_egid(void) Current's effective GID + uid_t current_fsuid(void) Current's file access UID + gid_t current_fsgid(void) Current's file access GID + kernel_cap_t current_cap(void) Current's effective capabilities + void *current_security(void) Current's LSM security pointer + struct user_struct *current_user(void) Current's user account + +There are also convenience wrappers for retrieving specific associated pairs of +a task's credentials: + + void current_uid_gid(uid_t *, gid_t *); + void current_euid_egid(uid_t *, gid_t *); + void current_fsuid_fsgid(uid_t *, gid_t *); + +which return these pairs of values through their arguments after retrieving +them from the current task's credentials. + + +In addition, there is a function for obtaining a reference on the current +process's current set of credentials: + + const struct cred *get_current_cred(void); + +and functions for getting references to one of the credentials that don't +actually live in struct cred: + + struct user_struct *get_current_user(void); + struct group_info *get_current_groups(void); + +which get references to the current process's user accounting structure and +supplementary groups list respectively. + +Once a reference has been obtained, it must be released with put_cred(), +free_uid() or put_group_info() as appropriate. + + +ACCESSING ANOTHER TASK'S CREDENTIALS +------------------------------------ + +Whilst a task may access its own credentials without the need for locking, the +same is not true of a task wanting to access another task's credentials. It +must use the RCU read lock and rcu_dereference(). + +The rcu_dereference() is wrapped by: + + const struct cred *__task_cred(struct task_struct *task); + +This should be used inside the RCU read lock, as in the following example: + + void foo(struct task_struct *t, struct foo_data *f) + { + const struct cred *tcred; + ... + rcu_read_lock(); + tcred = __task_cred(t); + f->uid = tcred->uid; + f->gid = tcred->gid; + f->groups = get_group_info(tcred->groups); + rcu_read_unlock(); + ... + } + +A function need not get RCU read lock to use __task_cred() if it is holding a +spinlock at the time as this implicitly holds the RCU read lock. + +Should it be necessary to hold another task's credentials for a long period of +time, and possibly to sleep whilst doing so, then the caller should get a +reference on them using: + + const struct cred *get_task_cred(struct task_struct *task); + +This does all the RCU magic inside of it. The caller must call put_cred() on +the credentials so obtained when they're finished with. + +There are a couple of convenience functions to access bits of another task's +credentials, hiding the RCU magic from the caller: + + uid_t task_uid(task) Task's real UID + uid_t task_euid(task) Task's effective UID + +If the caller is holding a spinlock or the RCU read lock at the time anyway, +then: + + __task_cred(task)->uid + __task_cred(task)->euid + +should be used instead. Similarly, if multiple aspects of a task's credentials +need to be accessed, RCU read lock or a spinlock should be used, __task_cred() +called, the result stored in a temporary pointer and then the credential +aspects called from that before dropping the lock. This prevents the +potentially expensive RCU magic from being invoked multiple times. + +Should some other single aspect of another task's credentials need to be +accessed, then this can be used: + + task_cred_xxx(task, member) + +where 'member' is a non-pointer member of the cred struct. For instance: + + uid_t task_cred_xxx(task, suid); + +will retrieve 'struct cred::suid' from the task, doing the appropriate RCU +magic. This may not be used for pointer members as what they point to may +disappear the moment the RCU read lock is dropped. + + +ALTERING CREDENTIALS +-------------------- + +As previously mentioned, a task may only alter its own credentials, and may not +alter those of another task. This means that it doesn't need to use any +locking to alter its own credentials. + +To alter the current process's credentials, a function should first prepare a +new set of credentials by calling: + + struct cred *prepare_creds(void); + +this locks current->cred_replace_mutex and then allocates and constructs a +duplicate of the current process's credentials, returning with the mutex still +held if successful. It returns NULL if not successful (out of memory). + +The mutex prevents ptrace() from altering the ptrace state of a process whilst +security checks on credentials construction and changing is taking place as +the ptrace state may alter the outcome, particularly in the case of execve(). + +The new credentials set should be altered appropriately, and any security +checks and hooks done. Both the current and the proposed sets of credentials +are available for this purpose as current_cred() will return the current set +still at this point. + + +When the credential set is ready, it should be committed to the current process +by calling: + + int commit_creds(struct cred *new); + +This will alter various aspects of the credentials and the process, giving the +LSM a chance to do likewise, then it will use rcu_assign_pointer() to actually +commit the new credentials to current->cred, it will release +current->cred_replace_mutex to allow ptrace() to take place, and it will notify +the scheduler and others of the changes. + +This function is guaranteed to return 0, so that it can be tail-called at the +end of such functions as sys_setresuid(). + +Note that this function consumes the caller's reference to the new credentials. +The caller should _not_ call put_cred() on the new credentials afterwards. + +Furthermore, once this function has been called on a new set of credentials, +those credentials may _not_ be changed further. + + +Should the security checks fail or some other error occur after prepare_creds() +has been called, then the following function should be invoked: + + void abort_creds(struct cred *new); + +This releases the lock on current->cred_replace_mutex that prepare_creds() got +and then releases the new credentials. + + +A typical credentials alteration function would look something like this: + + int alter_suid(uid_t suid) + { + struct cred *new; + int ret; + + new = prepare_creds(); + if (!new) + return -ENOMEM; + + new->suid = suid; + ret = security_alter_suid(new); + if (ret < 0) { + abort_creds(new); + return ret; + } + + return commit_creds(new); + } + + +MANAGING CREDENTIALS +-------------------- + +There are some functions to help manage credentials: + + (*) void put_cred(const struct cred *cred); + + This releases a reference to the given set of credentials. If the + reference count reaches zero, the credentials will be scheduled for + destruction by the RCU system. + + (*) const struct cred *get_cred(const struct cred *cred); + + This gets a reference on a live set of credentials, returning a pointer to + that set of credentials. + + (*) struct cred *get_new_cred(struct cred *cred); + + This gets a reference on a set of credentials that is under construction + and is thus still mutable, returning a pointer to that set of credentials. + + +===================== +OPEN FILE CREDENTIALS +===================== + +When a new file is opened, a reference is obtained on the opening task's +credentials and this is attached to the file struct as 'f_cred' in place of +'f_uid' and 'f_gid'. Code that used to access file->f_uid and file->f_gid +should now access file->f_cred->fsuid and file->f_cred->fsgid. + +It is safe to access f_cred without the use of RCU or locking because the +pointer will not change over the lifetime of the file struct, and nor will the +contents of the cred struct pointed to, barring the exceptions listed above +(see the Task Credentials section). + + +======================================= +OVERRIDING THE VFS'S USE OF CREDENTIALS +======================================= + +Under some circumstances it is desirable to override the credentials used by +the VFS, and that can be done by calling into such as vfs_mkdir() with a +different set of credentials. This is done in the following places: + + (*) sys_faccessat(). + + (*) do_coredump(). + + (*) nfs4recover.c. diff --git a/Documentation/cris/README b/Documentation/cris/README index 795a1dabe6c..d9b086869a6 100644 --- a/Documentation/cris/README +++ b/Documentation/cris/README @@ -27,7 +27,7 @@ operating system. The ETRAX 100LX chip -------------------- -For reference, plase see the press-release: +For reference, please see the press-release: http://www.axis.com/news/us/001101_etrax.htm diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro new file mode 100644 index 00000000000..8cc2cba2b10 --- /dev/null +++ b/Documentation/development-process/1.Intro @@ -0,0 +1,274 @@ +1: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS + +The purpose of this document is to help developers (and their managers) +work with the development community with a minimum of frustration. It is +an attempt to document how this community works in a way which is +accessible to those who are not intimately familiar with Linux kernel +development (or, indeed, free software development in general). While +there is some technical material here, this is very much a process-oriented +discussion which does not require a deep knowledge of kernel programming to +understand. + + +1.1: EXECUTIVE SUMMARY + +The rest of this section covers the scope of the kernel development process +and the kinds of frustrations that developers and their employers can +encounter there. There are a great many reasons why kernel code should be +merged into the official ("mainline") kernel, including automatic +availability to users, community support in many forms, and the ability to +influence the direction of kernel development. Code contributed to the +Linux kernel must be made available under a GPL-compatible license. + +Section 2 introduces the development process, the kernel release cycle, and +the mechanics of the merge window. The various phases in the patch +development, review, and merging cycle are covered. There is some +discussion of tools and mailing lists. Developers wanting to get started +with kernel development are encouraged to track down and fix bugs as an +initial exercise. + +Section 3 covers early-stage project planning, with an emphasis on +involving the development community as soon as possible. + +Section 4 is about the coding process; several pitfalls which have been +encountered by other developers are discussed. Some requirements for +patches are covered, and there is an introduction to some of the tools +which can help to ensure that kernel patches are correct. + +Section 5 talks about the process of posting patches for review. To be +taken seriously by the development community, patches must be properly +formatted and described, and they must be sent to the right place. +Following the advice in this section should help to ensure the best +possible reception for your work. + +Section 6 covers what happens after posting patches; the job is far from +done at that point. Working with reviewers is a crucial part of the +development process; this section offers a number of tips on how to avoid +problems at this important stage. Developers are cautioned against +assuming that the job is done when a patch is merged into the mainline. + +Section 7 introduces a couple of "advanced" topics: managing patches with +git and reviewing patches posted by others. + +Section 8 concludes the document with pointers to sources for more +information on kernel development. + + +1.2: WHAT THIS DOCUMENT IS ABOUT + +The Linux kernel, at over 6 million lines of code and well over 1000 active +contributors, is one of the largest and most active free software projects +in existence. Since its humble beginning in 1991, this kernel has evolved +into a best-of-breed operating system component which runs on pocket-sized +digital music players, desktop PCs, the largest supercomputers in +existence, and all types of systems in between. It is a robust, efficient, +and scalable solution for almost any situation. + +With the growth of Linux has come an increase in the number of developers +(and companies) wishing to participate in its development. Hardware +vendors want to ensure that Linux supports their products well, making +those products attractive to Linux users. Embedded systems vendors, who +use Linux as a component in an integrated product, want Linux to be as +capable and well-suited to the task at hand as possible. Distributors and +other software vendors who base their products on Linux have a clear +interest in the capabilities, performance, and reliability of the Linux +kernel. And end users, too, will often wish to change Linux to make it +better suit their needs. + +One of the most compelling features of Linux is that it is accessible to +these developers; anybody with the requisite skills can improve Linux and +influence the direction of its development. Proprietary products cannot +offer this kind of openness, which is a characteristic of the free software +process. But, if anything, the kernel is even more open than most other +free software projects. A typical three-month kernel development cycle can +involve over 1000 developers working for more than 100 different companies +(or for no company at all). + +Working with the kernel development community is not especially hard. But, +that notwithstanding, many potential contributors have experienced +difficulties when trying to do kernel work. The kernel community has +evolved its own distinct ways of operating which allow it to function +smoothly (and produce a high-quality product) in an environment where +thousands of lines of code are being changed every day. So it is not +surprising that Linux kernel development process differs greatly from +proprietary development methods. + +The kernel's development process may come across as strange and +intimidating to new developers, but there are good reasons and solid +experience behind it. A developer who does not understand the kernel +community's ways (or, worse, who tries to flout or circumvent them) will +have a frustrating experience in store. The development community, while +being helpful to those who are trying to learn, has little time for those +who will not listen or who do not care about the development process. + +It is hoped that those who read this document will be able to avoid that +frustrating experience. There is a lot of material here, but the effort +involved in reading it will be repaid in short order. The development +community is always in need of developers who will help to make the kernel +better; the following text should help you - or those who work for you - +join our community. + + +1.3: CREDITS + +This document was written by Jonathan Corbet, corbet@lwn.net. It has been +improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland +Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, +Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and +Jochen Voß. + +This work was supported by the Linux Foundation; thanks especially to +Amanda McPherson, who saw the value of this effort and made it all happen. + + +1.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE + +Some companies and developers occasionally wonder why they should bother +learning how to work with the kernel community and get their code into the +mainline kernel (the "mainline" being the kernel maintained by Linus +Torvalds and used as a base by Linux distributors). In the short term, +contributing code can look like an avoidable expense; it seems easier to +just keep the code separate and support users directly. The truth of the +matter is that keeping code separate ("out of tree") is a false economy. + +As a way of illustrating the costs of out-of-tree code, here are a few +relevant aspects of the kernel development process; most of these will be +discussed in greater detail later in this document. Consider: + +- Code which has been merged into the mainline kernel is available to all + Linux users. It will automatically be present on all distributions which + enable it. There is no need for driver disks, downloads, or the hassles + of supporting multiple versions of multiple distributions; it all just + works, for the developer and for the user. Incorporation into the + mainline solves a large number of distribution and support problems. + +- While kernel developers strive to maintain a stable interface to user + space, the internal kernel API is in constant flux. The lack of a stable + internal interface is a deliberate design decision; it allows fundamental + improvements to be made at any time and results in higher-quality code. + But one result of that policy is that any out-of-tree code requires + constant upkeep if it is to work with new kernels. Maintaining + out-of-tree code requires significant amounts of work just to keep that + code working. + + Code which is in the mainline, instead, does not require this work as the + result of a simple rule requiring any developer who makes an API change + to also fix any code that breaks as the result of that change. So code + which has been merged into the mainline has significantly lower + maintenance costs. + +- Beyond that, code which is in the kernel will often be improved by other + developers. Surprising results can come from empowering your user + community and customers to improve your product. + +- Kernel code is subjected to review, both before and after merging into + the mainline. No matter how strong the original developer's skills are, + this review process invariably finds ways in which the code can be + improved. Often review finds severe bugs and security problems. This is + especially true for code which has been developed in a closed + environment; such code benefits strongly from review by outside + developers. Out-of-tree code is lower-quality code. + +- Participation in the development process is your way to influence the + direction of kernel development. Users who complain from the sidelines + are heard, but active developers have a stronger voice - and the ability + to implement changes which make the kernel work better for their needs. + +- When code is maintained separately, the possibility that a third party + will contribute a different implementation of a similar feature always + exists. Should that happen, getting your code merged will become much + harder - to the point of impossibility. Then you will be faced with the + unpleasant alternatives of either (1) maintaining a nonstandard feature + out of tree indefinitely, or (2) abandoning your code and migrating your + users over to the in-tree version. + +- Contribution of code is the fundamental action which makes the whole + process work. By contributing your code you can add new functionality to + the kernel and provide capabilities and examples which are of use to + other kernel developers. If you have developed code for Linux (or are + thinking about doing so), you clearly have an interest in the continued + success of this platform; contributing code is one of the best ways to + help ensure that success. + +All of the reasoning above applies to any out-of-tree kernel code, +including code which is distributed in proprietary, binary-only form. +There are, however, additional factors which should be taken into account +before considering any sort of binary-only kernel code distribution. These +include: + +- The legal issues around the distribution of proprietary kernel modules + are cloudy at best; quite a few kernel copyright holders believe that + most binary-only modules are derived products of the kernel and that, as + a result, their distribution is a violation of the GNU General Public + license (about which more will be said below). Your author is not a + lawyer, and nothing in this document can possibly be considered to be + legal advice. The true legal status of closed-source modules can only be + determined by the courts. But the uncertainty which haunts those modules + is there regardless. + +- Binary modules greatly increase the difficulty of debugging kernel + problems, to the point that most kernel developers will not even try. So + the distribution of binary-only modules will make it harder for your + users to get support from the community. + +- Support is also harder for distributors of binary-only modules, who must + provide a version of the module for every distribution and every kernel + version they wish to support. Dozens of builds of a single module can + be required to provide reasonably comprehensive coverage, and your users + will have to upgrade your module separately every time they upgrade their + kernel. + +- Everything that was said above about code review applies doubly to + closed-source code. Since this code is not available at all, it cannot + have been reviewed by the community and will, beyond doubt, have serious + problems. + +Makers of embedded systems, in particular, may be tempted to disregard much +of what has been said in this section in the belief that they are shipping +a self-contained product which uses a frozen kernel version and requires no +more development after its release. This argument misses the value of +widespread code review and the value of allowing your users to add +capabilities to your product. But these products, too, have a limited +commercial life, after which a new version must be released. At that +point, vendors whose code is in the mainline and well maintained will be +much better positioned to get the new product ready for market quickly. + + +1.5: LICENSING + +Code is contributed to the Linux kernel under a number of licenses, but all +code must be compatible with version 2 of the GNU General Public License +(GPLv2), which is the license covering the kernel distribution as a whole. +In practice, that means that all code contributions are covered either by +GPLv2 (with, optionally, language allowing distribution under later +versions of the GPL) or the three-clause BSD license. Any contributions +which are not covered by a compatible license will not be accepted into the +kernel. + +Copyright assignments are not required (or requested) for code contributed +to the kernel. All code merged into the mainline kernel retains its +original ownership; as a result, the kernel now has thousands of owners. + +One implication of this ownership structure is that any attempt to change +the licensing of the kernel is doomed to almost certain failure. There are +few practical scenarios where the agreement of all copyright holders could +be obtained (or their code removed from the kernel). So, in particular, +there is no prospect of a migration to version 3 of the GPL in the +foreseeable future. + +It is imperative that all code contributed to the kernel be legitimately +free software. For that reason, code from anonymous (or pseudonymous) +contributors will not be accepted. All contributors are required to "sign +off" on their code, stating that the code can be distributed with the +kernel under the GPL. Code which has not been licensed as free software by +its owner, or which risks creating copyright-related problems for the +kernel (such as code which derives from reverse-engineering efforts lacking +proper safeguards) cannot be contributed. + +Questions about copyright-related issues are common on Linux development +mailing lists. Such questions will normally receive no shortage of +answers, but one should bear in mind that the people answering those +questions are not lawyers and cannot provide legal advice. If you have +legal questions relating to Linux source code, there is no substitute for +talking with a lawyer who understands this field. Relying on answers +obtained on technical mailing lists is a risky affair. diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process new file mode 100644 index 00000000000..d750321acd5 --- /dev/null +++ b/Documentation/development-process/2.Process @@ -0,0 +1,459 @@ +2: HOW THE DEVELOPMENT PROCESS WORKS + +Linux kernel development in the early 1990's was a pretty loose affair, +with relatively small numbers of users and developers involved. With a +user base in the millions and with some 2,000 developers involved over the +course of one year, the kernel has since had to evolve a number of +processes to keep development happening smoothly. A solid understanding of +how the process works is required in order to be an effective part of it. + + +2.1: THE BIG PICTURE + +The kernel developers use a loosely time-based release process, with a new +major kernel release happening every two or three months. The recent +release history looks like this: + + 2.6.26 July 13, 2008 + 2.6.25 April 16, 2008 + 2.6.24 January 24, 2008 + 2.6.23 October 9, 2007 + 2.6.22 July 8, 2007 + 2.6.21 April 25, 2007 + 2.6.20 February 4, 2007 + +Every 2.6.x release is a major kernel release with new features, internal +API changes, and more. A typical 2.6 release can contain over 10,000 +changesets with changes to several hundred thousand lines of code. 2.6 is +thus the leading edge of Linux kernel development; the kernel uses a +rolling development model which is continually integrating major changes. + +A relatively straightforward discipline is followed with regard to the +merging of patches for each release. At the beginning of each development +cycle, the "merge window" is said to be open. At that time, code which is +deemed to be sufficiently stable (and which is accepted by the development +community) is merged into the mainline kernel. The bulk of changes for a +new development cycle (and all of the major changes) will be merged during +this time, at a rate approaching 1,000 changes ("patches," or "changesets") +per day. + +(As an aside, it is worth noting that the changes integrated during the +merge window do not come out of thin air; they have been collected, tested, +and staged ahead of time. How that process works will be described in +detail later on). + +The merge window lasts for two weeks. At the end of this time, Linus +Torvalds will declare that the window is closed and release the first of +the "rc" kernels. For the kernel which is destined to be 2.6.26, for +example, the release which happens at the end of the merge window will be +called 2.6.26-rc1. The -rc1 release is the signal that the time to merge +new features has passed, and that the time to stabilize the next kernel has +begun. + +Over the next six to ten weeks, only patches which fix problems should be +submitted to the mainline. On occasion a more significant change will be +allowed, but such occasions are rare; developers who try to merge new +features outside of the merge window tend to get an unfriendly reception. +As a general rule, if you miss the merge window for a given feature, the +best thing to do is to wait for the next development cycle. (An occasional +exception is made for drivers for previously-unsupported hardware; if they +touch no in-tree code, they cannot cause regressions and should be safe to +add at any time). + +As fixes make their way into the mainline, the patch rate will slow over +time. Linus releases new -rc kernels about once a week; a normal series +will get up to somewhere between -rc6 and -rc9 before the kernel is +considered to be sufficiently stable and the final 2.6.x release is made. +At that point the whole process starts over again. + +As an example, here is how the 2.6.25 development cycle went (all dates in +2008): + + January 24 2.6.24 stable release + February 10 2.6.25-rc1, merge window closes + February 15 2.6.25-rc2 + February 24 2.6.25-rc3 + March 4 2.6.25-rc4 + March 9 2.6.25-rc5 + March 16 2.6.25-rc6 + March 25 2.6.25-rc7 + April 1 2.6.25-rc8 + April 11 2.6.25-rc9 + April 16 2.6.25 stable release + +How do the developers decide when to close the development cycle and create +the stable release? The most significant metric used is the list of +regressions from previous releases. No bugs are welcome, but those which +break systems which worked in the past are considered to be especially +serious. For this reason, patches which cause regressions are looked upon +unfavorably and are quite likely to be reverted during the stabilization +period. + +The developers' goal is to fix all known regressions before the stable +release is made. In the real world, this kind of perfection is hard to +achieve; there are just too many variables in a project of this size. +There comes a point where delaying the final release just makes the problem +worse; the pile of changes waiting for the next merge window will grow +larger, creating even more regressions the next time around. So most 2.6.x +kernels go out with a handful of known regressions though, hopefully, none +of them are serious. + +Once a stable release is made, its ongoing maintenance is passed off to the +"stable team," currently comprised of Greg Kroah-Hartman and Chris Wright. +The stable team will release occasional updates to the stable release using +the 2.6.x.y numbering scheme. To be considered for an update release, a +patch must (1) fix a significant bug, and (2) already be merged into the +mainline for the next development kernel. Continuing our 2.6.25 example, +the history (as of this writing) is: + + May 1 2.6.25.1 + May 6 2.6.25.2 + May 9 2.6.25.3 + May 15 2.6.25.4 + June 7 2.6.25.5 + June 9 2.6.25.6 + June 16 2.6.25.7 + June 21 2.6.25.8 + June 24 2.6.25.9 + +Stable updates for a given kernel are made for approximately six months; +after that, the maintenance of stable releases is solely the responsibility +of the distributors which have shipped that particular kernel. + + +2.2: THE LIFECYCLE OF A PATCH + +Patches do not go directly from the developer's keyboard into the mainline +kernel. There is, instead, a somewhat involved (if somewhat informal) +process designed to ensure that each patch is reviewed for quality and that +each patch implements a change which is desirable to have in the mainline. +This process can happen quickly for minor fixes, or, in the case of large +and controversial changes, go on for years. Much developer frustration +comes from a lack of understanding of this process or from attempts to +circumvent it. + +In the hopes of reducing that frustration, this document will describe how +a patch gets into the kernel. What follows below is an introduction which +describes the process in a somewhat idealized way. A much more detailed +treatment will come in later sections. + +The stages that a patch goes through are, generally: + + - Design. This is where the real requirements for the patch - and the way + those requirements will be met - are laid out. Design work is often + done without involving the community, but it is better to do this work + in the open if at all possible; it can save a lot of time redesigning + things later. + + - Early review. Patches are posted to the relevant mailing list, and + developers on that list reply with any comments they may have. This + process should turn up any major problems with a patch if all goes + well. + + - Wider review. When the patch is getting close to ready for mainline + inclusion, it will be accepted by a relevant subsystem maintainer - + though this acceptance is not a guarantee that the patch will make it + all the way to the mainline. The patch will show up in the maintainer's + subsystem tree and into the staging trees (described below). When the + process works, this step leads to more extensive review of the patch and + the discovery of any problems resulting from the integration of this + patch with work being done by others. + + - Merging into the mainline. Eventually, a successful patch will be + merged into the mainline repository managed by Linus Torvalds. More + comments and/or problems may surface at this time; it is important that + the developer be responsive to these and fix any issues which arise. + + - Stable release. The number of users potentially affected by the patch + is now large, so, once again, new problems may arise. + + - Long-term maintenance. While it is certainly possible for a developer + to forget about code after merging it, that sort of behavior tends to + leave a poor impression in the development community. Merging code + eliminates some of the maintenance burden, in that others will fix + problems caused by API changes. But the original developer should + continue to take responsibility for the code if it is to remain useful + in the longer term. + +One of the largest mistakes made by kernel developers (or their employers) +is to try to cut the process down to a single "merging into the mainline" +step. This approach invariably leads to frustration for everybody +involved. + + +2.3: HOW PATCHES GET INTO THE KERNEL + +There is exactly one person who can merge patches into the mainline kernel +repository: Linus Torvalds. But, of the over 12,000 patches which went +into the 2.6.25 kernel, only 250 (around 2%) were directly chosen by Linus +himself. The kernel project has long since grown to a size where no single +developer could possibly inspect and select every patch unassisted. The +way the kernel developers have addressed this growth is through the use of +a lieutenant system built around a chain of trust. + +The kernel code base is logically broken down into a set of subsystems: +networking, specific architecture support, memory management, video +devices, etc. Most subsystems have a designated maintainer, a developer +who has overall responsibility for the code within that subsystem. These +subsystem maintainers are the gatekeepers (in a loose way) for the portion +of the kernel they manage; they are the ones who will (usually) accept a +patch for inclusion into the mainline kernel. + +Subsystem maintainers each manage their own version of the kernel source +tree, usually (but certainly not always) using the git source management +tool. Tools like git (and related tools like quilt or mercurial) allow +maintainers to track a list of patches, including authorship information +and other metadata. At any given time, the maintainer can identify which +patches in his or her repository are not found in the mainline. + +When the merge window opens, top-level maintainers will ask Linus to "pull" +the patches they have selected for merging from their repositories. If +Linus agrees, the stream of patches will flow up into his repository, +becoming part of the mainline kernel. The amount of attention that Linus +pays to specific patches received in a pull operation varies. It is clear +that, sometimes, he looks quite closely. But, as a general rule, Linus +trusts the subsystem maintainers to not send bad patches upstream. + +Subsystem maintainers, in turn, can pull patches from other maintainers. +For example, the networking tree is built from patches which accumulated +first in trees dedicated to network device drivers, wireless networking, +etc. This chain of repositories can be arbitrarily long, though it rarely +exceeds two or three links. Since each maintainer in the chain trusts +those managing lower-level trees, this process is known as the "chain of +trust." + +Clearly, in a system like this, getting patches into the kernel depends on +finding the right maintainer. Sending patches directly to Linus is not +normally the right way to go. + + +2.4: STAGING TREES + +The chain of subsystem trees guides the flow of patches into the kernel, +but it also raises an interesting question: what if somebody wants to look +at all of the patches which are being prepared for the next merge window? +Developers will be interested in what other changes are pending to see +whether there are any conflicts to worry about; a patch which changes a +core kernel function prototype, for example, will conflict with any other +patches which use the older form of that function. Reviewers and testers +want access to the changes in their integrated form before all of those +changes land in the mainline kernel. One could pull changes from all of +the interesting subsystem trees, but that would be a big and error-prone +job. + +The answer comes in the form of staging trees, where subsystem trees are +collected for testing and review. The older of these trees, maintained by +Andrew Morton, is called "-mm" (for memory management, which is how it got +started). The -mm tree integrates patches from a long list of subsystem +trees; it also has some patches aimed at helping with debugging. + +Beyond that, -mm contains a significant collection of patches which have +been selected by Andrew directly. These patches may have been posted on a +mailing list, or they may apply to a part of the kernel for which there is +no designated subsystem tree. As a result, -mm operates as a sort of +subsystem tree of last resort; if there is no other obvious path for a +patch into the mainline, it is likely to end up in -mm. Miscellaneous +patches which accumulate in -mm will eventually either be forwarded on to +an appropriate subsystem tree or be sent directly to Linus. In a typical +development cycle, approximately 10% of the patches going into the mainline +get there via -mm. + +The current -mm patch can always be found from the front page of + + http://kernel.org/ + +Those who want to see the current state of -mm can get the "-mm of the +moment" tree, found at: + + http://userweb.kernel.org/~akpm/mmotm/ + +Use of the MMOTM tree is likely to be a frustrating experience, though; +there is a definite chance that it will not even compile. + +The other staging tree, started more recently, is linux-next, maintained by +Stephen Rothwell. The linux-next tree is, by design, a snapshot of what +the mainline is expected to look like after the next merge window closes. +Linux-next trees are announced on the linux-kernel and linux-next mailing +lists when they are assembled; they can be downloaded from: + + http://www.kernel.org/pub/linux/kernel/people/sfr/linux-next/ + +Some information about linux-next has been gathered at: + + http://linux.f-seidel.de/linux-next/pmwiki/ + +How the linux-next tree will fit into the development process is still +changing. As of this writing, the first full development cycle involving +linux-next (2.6.26) is coming to an end; thus far, it has proved to be a +valuable resource for finding and fixing integration problems before the +beginning of the merge window. See http://lwn.net/Articles/287155/ for +more information on how linux-next has worked to set up the 2.6.27 merge +window. + +Some developers have begun to suggest that linux-next should be used as the +target for future development as well. The linux-next tree does tend to be +far ahead of the mainline and is more representative of the tree into which +any new work will be merged. The downside to this idea is that the +volatility of linux-next tends to make it a difficult development target. +See http://lwn.net/Articles/289013/ for more information on this topic, and +stay tuned; much is still in flux where linux-next is involved. + + +2.5: TOOLS + +As can be seen from the above text, the kernel development process depends +heavily on the ability to herd collections of patches in various +directions. The whole thing would not work anywhere near as well as it +does without suitably powerful tools. Tutorials on how to use these tools +are well beyond the scope of this document, but there is space for a few +pointers. + +By far the dominant source code management system used by the kernel +community is git. Git is one of a number of distributed version control +systems being developed in the free software community. It is well tuned +for kernel development, in that it performs quite well when dealing with +large repositories and large numbers of patches. It also has a reputation +for being difficult to learn and use, though it has gotten better over +time. Some sort of familiarity with git is almost a requirement for kernel +developers; even if they do not use it for their own work, they'll need git +to keep up with what other developers (and the mainline) are doing. + +Git is now packaged by almost all Linux distributions. There is a home +page at + + http://git.or.cz/ + +That page has pointers to documentation and tutorials. One should be +aware, in particular, of the Kernel Hacker's Guide to git, which has +information specific to kernel development: + + http://linux.yyz.us/git-howto.html + +Among the kernel developers who do not use git, the most popular choice is +almost certainly Mercurial: + + http://www.selenic.com/mercurial/ + +Mercurial shares many features with git, but it provides an interface which +many find easier to use. + +The other tool worth knowing about is Quilt: + + http://savannah.nongnu.org/projects/quilt/ + +Quilt is a patch management system, rather than a source code management +system. It does not track history over time; it is, instead, oriented +toward tracking a specific set of changes against an evolving code base. +Some major subsystem maintainers use quilt to manage patches intended to go +upstream. For the management of certain kinds of trees (-mm, for example), +quilt is the best tool for the job. + + +2.6: MAILING LISTS + +A great deal of Linux kernel development work is done by way of mailing +lists. It is hard to be a fully-functioning member of the community +without joining at least one list somewhere. But Linux mailing lists also +represent a potential hazard to developers, who risk getting buried under a +load of electronic mail, running afoul of the conventions used on the Linux +lists, or both. + +Most kernel mailing lists are run on vger.kernel.org; the master list can +be found at: + + http://vger.kernel.org/vger-lists.html + +There are lists hosted elsewhere, though; a number of them are at +lists.redhat.com. + +The core mailing list for kernel development is, of course, linux-kernel. +This list is an intimidating place to be; volume can reach 500 messages per +day, the amount of noise is high, the conversation can be severely +technical, and participants are not always concerned with showing a high +degree of politeness. But there is no other place where the kernel +development community comes together as a whole; developers who avoid this +list will miss important information. + +There are a few hints which can help with linux-kernel survival: + +- Have the list delivered to a separate folder, rather than your main + mailbox. One must be able to ignore the stream for sustained periods of + time. + +- Do not try to follow every conversation - nobody else does. It is + important to filter on both the topic of interest (though note that + long-running conversations can drift away from the original subject + without changing the email subject line) and the people who are + participating. + +- Do not feed the trolls. If somebody is trying to stir up an angry + response, ignore them. + +- When responding to linux-kernel email (or that on other lists) preserve + the Cc: header for all involved. In the absence of a strong reason (such + as an explicit request), you should never remove recipients. Always make + sure that the person you are responding to is in the Cc: list. This + convention also makes it unnecessary to explicitly ask to be copied on + replies to your postings. + +- Search the list archives (and the net as a whole) before asking + questions. Some developers can get impatient with people who clearly + have not done their homework. + +- Avoid top-posting (the practice of putting your answer above the quoted + text you are responding to). It makes your response harder to read and + makes a poor impression. + +- Ask on the correct mailing list. Linux-kernel may be the general meeting + point, but it is not the best place to find developers from all + subsystems. + +The last point - finding the correct mailing list - is a common place for +beginning developers to go wrong. Somebody who asks a networking-related +question on linux-kernel will almost certainly receive a polite suggestion +to ask on the netdev list instead, as that is the list frequented by most +networking developers. Other lists exist for the SCSI, video4linux, IDE, +filesystem, etc. subsystems. The best place to look for mailing lists is +in the MAINTAINERS file packaged with the kernel source. + + +2.7: GETTING STARTED WITH KERNEL DEVELOPMENT + +Questions about how to get started with the kernel development process are +common - from both individuals and companies. Equally common are missteps +which make the beginning of the relationship harder than it has to be. + +Companies often look to hire well-known developers to get a development +group started. This can, in fact, be an effective technique. But it also +tends to be expensive and does not do much to grow the pool of experienced +kernel developers. It is possible to bring in-house developers up to speed +on Linux kernel development, given the investment of a bit of time. Taking +this time can endow an employer with a group of developers who understand +the kernel and the company both, and who can help to train others as well. +Over the medium term, this is often the more profitable approach. + +Individual developers are often, understandably, at a loss for a place to +start. Beginning with a large project can be intimidating; one often wants +to test the waters with something smaller first. This is the point where +some developers jump into the creation of patches fixing spelling errors or +minor coding style issues. Unfortunately, such patches create a level of +noise which is distracting for the development community as a whole, so, +increasingly, they are looked down upon. New developers wishing to +introduce themselves to the community will not get the sort of reception +they wish for by these means. + +Andrew Morton gives this advice for aspiring kernel developers + + The #1 project for all kernel beginners should surely be "make sure + that the kernel runs perfectly at all times on all machines which + you can lay your hands on". Usually the way to do this is to work + with others on getting things fixed up (this can require + persistence!) but that's fine - it's a part of kernel development. + +(http://lwn.net/Articles/283982/). + +In the absence of obvious problems to fix, developers are advised to look +at the current lists of regressions and open bugs in general. There is +never any shortage of issues in need of fixing; by addressing these issues, +developers will gain experience with the process while, at the same time, +building respect with the rest of the development community. diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage new file mode 100644 index 00000000000..307a159a70c --- /dev/null +++ b/Documentation/development-process/3.Early-stage @@ -0,0 +1,195 @@ +3: EARLY-STAGE PLANNING + +When contemplating a Linux kernel development project, it can be tempting +to jump right in and start coding. As with any significant project, +though, much of the groundwork for success is best laid before the first +line of code is written. Some time spent in early planning and +communication can save far more time later on. + + +3.1: SPECIFYING THE PROBLEM + +Like any engineering project, a successful kernel enhancement starts with a +clear description of the problem to be solved. In some cases, this step is +easy: when a driver is needed for a specific piece of hardware, for +example. In others, though, it is tempting to confuse the real problem +with the proposed solution, and that can lead to difficulties. + +Consider an example: some years ago, developers working with Linux audio +sought a way to run applications without dropouts or other artifacts caused +by excessive latency in the system. The solution they arrived at was a +kernel module intended to hook into the Linux Security Module (LSM) +framework; this module could be configured to give specific applications +access to the realtime scheduler. This module was implemented and sent to +the linux-kernel mailing list, where it immediately ran into problems. + +To the audio developers, this security module was sufficient to solve their +immediate problem. To the wider kernel community, though, it was seen as a +misuse of the LSM framework (which is not intended to confer privileges +onto processes which they would not otherwise have) and a risk to system +stability. Their preferred solutions involved realtime scheduling access +via the rlimit mechanism for the short term, and ongoing latency reduction +work in the long term. + +The audio community, however, could not see past the particular solution +they had implemented; they were unwilling to accept alternatives. The +resulting disagreement left those developers feeling disillusioned with the +entire kernel development process; one of them went back to an audio list +and posted this: + + There are a number of very good Linux kernel developers, but they + tend to get outshouted by a large crowd of arrogant fools. Trying + to communicate user requirements to these people is a waste of + time. They are much too "intelligent" to listen to lesser mortals. + +(http://lwn.net/Articles/131776/). + +The reality of the situation was different; the kernel developers were far +more concerned about system stability, long-term maintenance, and finding +the right solution to the problem than they were with a specific module. +The moral of the story is to focus on the problem - not a specific solution +- and to discuss it with the development community before investing in the +creation of a body of code. + +So, when contemplating a kernel development project, one should obtain +answers to a short set of questions: + + - What, exactly, is the problem which needs to be solved? + + - Who are the users affected by this problem? Which use cases should the + solution address? + + - How does the kernel fall short in addressing that problem now? + +Only then does it make sense to start considering possible solutions. + + +3.2: EARLY DISCUSSION + +When planning a kernel development project, it makes great sense to hold +discussions with the community before launching into implementation. Early +communication can save time and trouble in a number of ways: + + - It may well be that the problem is addressed by the kernel in ways which + you have not understood. The Linux kernel is large and has a number of + features and capabilities which are not immediately obvious. Not all + kernel capabilities are documented as well as one might like, and it is + easy to miss things. Your author has seen the posting of a complete + driver which duplicated an existing driver that the new author had been + unaware of. Code which reinvents existing wheels is not only wasteful; + it will also not be accepted into the mainline kernel. + + - There may be elements of the proposed solution which will not be + acceptable for mainline merging. It is better to find out about + problems like this before writing the code. + + - It's entirely possible that other developers have thought about the + problem; they may have ideas for a better solution, and may be willing + to help in the creation of that solution. + +Years of experience with the kernel development community have taught a +clear lesson: kernel code which is designed and developed behind closed +doors invariably has problems which are only revealed when the code is +released into the community. Sometimes these problems are severe, +requiring months or years of effort before the code can be brought up to +the kernel community's standards. Some examples include: + + - The Devicescape network stack was designed and implemented for + single-processor systems. It could not be merged into the mainline + until it was made suitable for multiprocessor systems. Retrofitting + locking and such into code is a difficult task; as a result, the merging + of this code (now called mac80211) was delayed for over a year. + + - The Reiser4 filesystem included a number of capabilities which, in the + core kernel developers' opinion, should have been implemented in the + virtual filesystem layer instead. It also included features which could + not easily be implemented without exposing the system to user-caused + deadlocks. The late revelation of these problems - and refusal to + address some of them - has caused Reiser4 to stay out of the mainline + kernel. + + - The AppArmor security module made use of internal virtual filesystem + data structures in ways which were considered to be unsafe and + unreliable. This code has since been significantly reworked, but + remains outside of the mainline. + +In each of these cases, a great deal of pain and extra work could have been +avoided with some early discussion with the kernel developers. + + +3.3: WHO DO YOU TALK TO? + +When developers decide to take their plans public, the next question will +be: where do we start? The answer is to find the right mailing list(s) and +the right maintainer. For mailing lists, the best approach is to look in +the MAINTAINERS file for a relevant place to post. If there is a suitable +subsystem list, posting there is often preferable to posting on +linux-kernel; you are more likely to reach developers with expertise in the +relevant subsystem and the environment may be more supportive. + +Finding maintainers can be a bit harder. Again, the MAINTAINERS file is +the place to start. That file tends to not always be up to date, though, +and not all subsystems are represented there. The person listed in the +MAINTAINERS file may, in fact, not be the person who is actually acting in +that role currently. So, when there is doubt about who to contact, a +useful trick is to use git (and "git log" in particular) to see who is +currently active within the subsystem of interest. Look at who is writing +patches, and who, if anybody, is attaching Signed-off-by lines to those +patches. Those are the people who will be best placed to help with a new +development project. + +If all else fails, talking to Andrew Morton can be an effective way to +track down a maintainer for a specific piece of code. + + +3.4: WHEN TO POST? + +If possible, posting your plans during the early stages can only be +helpful. Describe the problem being solved and any plans that have been +made on how the implementation will be done. Any information you can +provide can help the development community provide useful input on the +project. + +One discouraging thing which can happen at this stage is not a hostile +reaction, but, instead, little or no reaction at all. The sad truth of the +matter is (1) kernel developers tend to be busy, (2) there is no shortage +of people with grand plans and little code (or even prospect of code) to +back them up, and (3) nobody is obligated to review or comment on ideas +posted by others. If a request-for-comments posting yields little in the +way of comments, do not assume that it means there is no interest in the +project. Unfortunately, you also cannot assume that there are no problems +with your idea. The best thing to do in this situation is to proceed, +keeping the community informed as you go. + + +3.5: GETTING OFFICIAL BUY-IN + +If your work is being done in a corporate environment - as most Linux +kernel work is - you must, obviously, have permission from suitably +empowered managers before you can post your company's plans or code to a +public mailing list. The posting of code which has not been cleared for +release under a GPL-compatible license can be especially problematic; the +sooner that a company's management and legal staff can agree on the posting +of a kernel development project, the better off everybody involved will be. + +Some readers may be thinking at this point that their kernel work is +intended to support a product which does not yet have an officially +acknowledged existence. Revealing their employer's plans on a public +mailing list may not be a viable option. In cases like this, it is worth +considering whether the secrecy is really necessary; there is often no real +need to keep development plans behind closed doors. + +That said, there are also cases where a company legitimately cannot +disclose its plans early in the development process. Companies with +experienced kernel developers may choose to proceed in an open-loop manner +on the assumption that they will be able to avoid serious integration +problems later. For companies without that sort of in-house expertise, the +best option is often to hire an outside developer to review the plans under +a non-disclosure agreement. The Linux Foundation operates an NDA program +designed to help with this sort of situation; more information can be found +at: + + http://www.linuxfoundation.org/en/NDA_program + +This kind of review is often enough to avoid serious problems later on +without requiring public disclosure of the project. diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding new file mode 100644 index 00000000000..014aca8f14e --- /dev/null +++ b/Documentation/development-process/4.Coding @@ -0,0 +1,384 @@ +4: GETTING THE CODE RIGHT + +While there is much to be said for a solid and community-oriented design +process, the proof of any kernel development project is in the resulting +code. It is the code which will be examined by other developers and merged +(or not) into the mainline tree. So it is the quality of this code which +will determine the ultimate success of the project. + +This section will examine the coding process. We'll start with a look at a +number of ways in which kernel developers can go wrong. Then the focus +will shift toward doing things right and the tools which can help in that +quest. + + +4.1: PITFALLS + +* Coding style + +The kernel has long had a standard coding style, described in +Documentation/CodingStyle. For much of that time, the policies described +in that file were taken as being, at most, advisory. As a result, there is +a substantial amount of code in the kernel which does not meet the coding +style guidelines. The presence of that code leads to two independent +hazards for kernel developers. + +The first of these is to believe that the kernel coding standards do not +matter and are not enforced. The truth of the matter is that adding new +code to the kernel is very difficult if that code is not coded according to +the standard; many developers will request that the code be reformatted +before they will even review it. A code base as large as the kernel +requires some uniformity of code to make it possible for developers to +quickly understand any part of it. So there is no longer room for +strangely-formatted code. + +Occasionally, the kernel's coding style will run into conflict with an +employer's mandated style. In such cases, the kernel's style will have to +win before the code can be merged. Putting code into the kernel means +giving up a degree of control in a number of ways - including control over +how the code is formatted. + +The other trap is to assume that code which is already in the kernel is +urgently in need of coding style fixes. Developers may start to generate +reformatting patches as a way of gaining familiarity with the process, or +as a way of getting their name into the kernel changelogs - or both. But +pure coding style fixes are seen as noise by the development community; +they tend to get a chilly reception. So this type of patch is best +avoided. It is natural to fix the style of a piece of code while working +on it for other reasons, but coding style changes should not be made for +their own sake. + +The coding style document also should not be read as an absolute law which +can never be transgressed. If there is a good reason to go against the +style (a line which becomes far less readable if split to fit within the +80-column limit, for example), just do it. + + +* Abstraction layers + +Computer Science professors teach students to make extensive use of +abstraction layers in the name of flexibility and information hiding. +Certainly the kernel makes extensive use of abstraction; no project +involving several million lines of code could do otherwise and survive. +But experience has shown that excessive or premature abstraction can be +just as harmful as premature optimization. Abstraction should be used to +the level required and no further. + +At a simple level, consider a function which has an argument which is +always passed as zero by all callers. One could retain that argument just +in case somebody eventually needs to use the extra flexibility that it +provides. By that time, though, chances are good that the code which +implements this extra argument has been broken in some subtle way which was +never noticed - because it has never been used. Or, when the need for +extra flexibility arises, it does not do so in a way which matches the +programmer's early expectation. Kernel developers will routinely submit +patches to remove unused arguments; they should, in general, not be added +in the first place. + +Abstraction layers which hide access to hardware - often to allow the bulk +of a driver to be used with multiple operating systems - are especially +frowned upon. Such layers obscure the code and may impose a performance +penalty; they do not belong in the Linux kernel. + +On the other hand, if you find yourself copying significant amounts of code +from another kernel subsystem, it is time to ask whether it would, in fact, +make sense to pull out some of that code into a separate library or to +implement that functionality at a higher level. There is no value in +replicating the same code throughout the kernel. + + +* #ifdef and preprocessor use in general + +The C preprocessor seems to present a powerful temptation to some C +programmers, who see it as a way to efficiently encode a great deal of +flexibility into a source file. But the preprocessor is not C, and heavy +use of it results in code which is much harder for others to read and +harder for the compiler to check for correctness. Heavy preprocessor use +is almost always a sign of code which needs some cleanup work. + +Conditional compilation with #ifdef is, indeed, a powerful feature, and it +is used within the kernel. But there is little desire to see code which is +sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use +should be confined to header files whenever possible. +Conditionally-compiled code can be confined to functions which, if the code +is not to be present, simply become empty. The compiler will then quietly +optimize out the call to the empty function. The result is far cleaner +code which is easier to follow. + +C preprocessor macros present a number of hazards, including possible +multiple evaluation of expressions with side effects and no type safety. +If you are tempted to define a macro, consider creating an inline function +instead. The code which results will be the same, but inline functions are +easier to read, do not evaluate their arguments multiple times, and allow +the compiler to perform type checking on the arguments and return value. + + +* Inline functions + +Inline functions present a hazard of their own, though. Programmers can +become enamored of the perceived efficiency inherent in avoiding a function +call and fill a source file with inline functions. Those functions, +however, can actually reduce performance. Since their code is replicated +at each call site, they end up bloating the size of the compiled kernel. +That, in turn, creates pressure on the processor's memory caches, which can +slow execution dramatically. Inline functions, as a rule, should be quite +small and relatively rare. The cost of a function call, after all, is not +that high; the creation of large numbers of inline functions is a classic +example of premature optimization. + +In general, kernel programmers ignore cache effects at their peril. The +classic time/space tradeoff taught in beginning data structures classes +often does not apply to contemporary hardware. Space *is* time, in that a +larger program will run slower than one which is more compact. + + +* Locking + +In May, 2006, the "Devicescape" networking stack was, with great +fanfare, released under the GPL and made available for inclusion in the +mainline kernel. This donation was welcome news; support for wireless +networking in Linux was considered substandard at best, and the Devicescape +stack offered the promise of fixing that situation. Yet, this code did not +actually make it into the mainline until June, 2007 (2.6.22). What +happened? + +This code showed a number of signs of having been developed behind +corporate doors. But one large problem in particular was that it was not +designed to work on multiprocessor systems. Before this networking stack +(now called mac80211) could be merged, a locking scheme needed to be +retrofitted onto it. + +Once upon a time, Linux kernel code could be developed without thinking +about the concurrency issues presented by multiprocessor systems. Now, +however, this document is being written on a dual-core laptop. Even on +single-processor systems, work being done to improve responsiveness will +raise the level of concurrency within the kernel. The days when kernel +code could be written without thinking about locking are long past. + +Any resource (data structures, hardware registers, etc.) which could be +accessed concurrently by more than one thread must be protected by a lock. +New code should be written with this requirement in mind; retrofitting +locking after the fact is a rather more difficult task. Kernel developers +should take the time to understand the available locking primitives well +enough to pick the right tool for the job. Code which shows a lack of +attention to concurrency will have a difficult path into the mainline. + + +* Regressions + +One final hazard worth mentioning is this: it can be tempting to make a +change (which may bring big improvements) which causes something to break +for existing users. This kind of change is called a "regression," and +regressions have become most unwelcome in the mainline kernel. With few +exceptions, changes which cause regressions will be backed out if the +regression cannot be fixed in a timely manner. Far better to avoid the +regression in the first place. + +It is often argued that a regression can be justified if it causes things +to work for more people than it creates problems for. Why not make a +change if it brings new functionality to ten systems for each one it +breaks? The best answer to this question was expressed by Linus in July, +2007: + + So we don't fix bugs by introducing new problems. That way lies + madness, and nobody ever knows if you actually make any real + progress at all. Is it two steps forwards, one step back, or one + step forward and two steps back? + +(http://lwn.net/Articles/243460/). + +An especially unwelcome type of regression is any sort of change to the +user-space ABI. Once an interface has been exported to user space, it must +be supported indefinitely. This fact makes the creation of user-space +interfaces particularly challenging: since they cannot be changed in +incompatible ways, they must be done right the first time. For this +reason, a great deal of thought, clear documentation, and wide review for +user-space interfaces is always required. + + + +4.2: CODE CHECKING TOOLS + +For now, at least, the writing of error-free code remains an ideal that few +of us can reach. What we can hope to do, though, is to catch and fix as +many of those errors as possible before our code goes into the mainline +kernel. To that end, the kernel developers have put together an impressive +array of tools which can catch a wide variety of obscure problems in an +automated way. Any problem caught by the computer is a problem which will +not afflict a user later on, so it stands to reason that the automated +tools should be used whenever possible. + +The first step is simply to heed the warnings produced by the compiler. +Contemporary versions of gcc can detect (and warn about) a large number of +potential errors. Quite often, these warnings point to real problems. +Code submitted for review should, as a rule, not produce any compiler +warnings. When silencing warnings, take care to understand the real cause +and try to avoid "fixes" which make the warning go away without addressing +its cause. + +Note that not all compiler warnings are enabled by default. Build the +kernel with "make EXTRA_CFLAGS=-W" to get the full set. + +The kernel provides several configuration options which turn on debugging +features; most of these are found in the "kernel hacking" submenu. Several +of these options should be turned on for any kernel used for development or +testing purposes. In particular, you should turn on: + + - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, and FRAME_WARN to get an + extra set of warnings for problems like the use of deprecated interfaces + or ignoring an important return value from a function. The output + generated by these warnings can be verbose, but one need not worry about + warnings from other parts of the kernel. + + - DEBUG_OBJECTS will add code to track the lifetime of various objects + created by the kernel and warn when things are done out of order. If + you are adding a subsystem which creates (and exports) complex objects + of its own, consider adding support for the object debugging + infrastructure. + + - DEBUG_SLAB can find a variety of memory allocation and use errors; it + should be used on most development kernels. + + - DEBUG_SPINLOCK, DEBUG_SPINLOCK_SLEEP, and DEBUG_MUTEXES will find a + number of common locking errors. + +There are quite a few other debugging options, some of which will be +discussed below. Some of them have a significant performance impact and +should not be used all of the time. But some time spent learning the +available options will likely be paid back many times over in short order. + +One of the heavier debugging tools is the locking checker, or "lockdep." +This tool will track the acquisition and release of every lock (spinlock or +mutex) in the system, the order in which locks are acquired relative to +each other, the current interrupt environment, and more. It can then +ensure that locks are always acquired in the same order, that the same +interrupt assumptions apply in all situations, and so on. In other words, +lockdep can find a number of scenarios in which the system could, on rare +occasion, deadlock. This kind of problem can be painful (for both +developers and users) in a deployed system; lockdep allows them to be found +in an automated manner ahead of time. Code with any sort of non-trivial +locking should be run with lockdep enabled before being submitted for +inclusion. + +As a diligent kernel programmer, you will, beyond doubt, check the return +status of any operation (such as a memory allocation) which can fail. The +fact of the matter, though, is that the resulting failure recovery paths +are, probably, completely untested. Untested code tends to be broken code; +you could be much more confident of your code if all those error-handling +paths had been exercised a few times. + +The kernel provides a fault injection framework which can do exactly that, +especially where memory allocations are involved. With fault injection +enabled, a configurable percentage of memory allocations will be made to +fail; these failures can be restricted to a specific range of code. +Running with fault injection enabled allows the programmer to see how the +code responds when things go badly. See +Documentation/fault-injection/fault-injection.text for more information on +how to use this facility. + +Other kinds of errors can be found with the "sparse" static analysis tool. +With sparse, the programmer can be warned about confusion between +user-space and kernel-space addresses, mixture of big-endian and +small-endian quantities, the passing of integer values where a set of bit +flags is expected, and so on. Sparse must be installed separately (it can +be found at http://www.kernel.org/pub/software/devel/sparse/ if your +distributor does not package it); it can then be run on the code by adding +"C=1" to your make command. + +Other kinds of portability errors are best found by compiling your code for +other architectures. If you do not happen to have an S/390 system or a +Blackfin development board handy, you can still perform the compilation +step. A large set of cross compilers for x86 systems can be found at + + http://www.kernel.org/pub/tools/crosstool/ + +Some time spent installing and using these compilers will help avoid +embarrassment later. + + +4.3: DOCUMENTATION + +Documentation has often been more the exception than the rule with kernel +development. Even so, adequate documentation will help to ease the merging +of new code into the kernel, make life easier for other developers, and +will be helpful for your users. In many cases, the addition of +documentation has become essentially mandatory. + +The first piece of documentation for any patch is its associated +changelog. Log entries should describe the problem being solved, the form +of the solution, the people who worked on the patch, any relevant +effects on performance, and anything else that might be needed to +understand the patch. + +Any code which adds a new user-space interface - including new sysfs or +/proc files - should include documentation of that interface which enables +user-space developers to know what they are working with. See +Documentation/ABI/README for a description of how this documentation should +be formatted and what information needs to be provided. + +The file Documentation/kernel-parameters.txt describes all of the kernel's +boot-time parameters. Any patch which adds new parameters should add the +appropriate entries to this file. + +Any new configuration options must be accompanied by help text which +clearly explains the options and when the user might want to select them. + +Internal API information for many subsystems is documented by way of +specially-formatted comments; these comments can be extracted and formatted +in a number of ways by the "kernel-doc" script. If you are working within +a subsystem which has kerneldoc comments, you should maintain them and add +them, as appropriate, for externally-available functions. Even in areas +which have not been so documented, there is no harm in adding kerneldoc +comments for the future; indeed, this can be a useful activity for +beginning kernel developers. The format of these comments, along with some +information on how to create kerneldoc templates can be found in the file +Documentation/kernel-doc-nano-HOWTO.txt. + +Anybody who reads through a significant amount of existing kernel code will +note that, often, comments are most notable by their absence. Once again, +the expectations for new code are higher than they were in the past; +merging uncommented code will be harder. That said, there is little desire +for verbosely-commented code. The code should, itself, be readable, with +comments explaining the more subtle aspects. + +Certain things should always be commented. Uses of memory barriers should +be accompanied by a line explaining why the barrier is necessary. The +locking rules for data structures generally need to be explained somewhere. +Major data structures need comprehensive documentation in general. +Non-obvious dependencies between separate bits of code should be pointed +out. Anything which might tempt a code janitor to make an incorrect +"cleanup" needs a comment saying why it is done the way it is. And so on. + + +4.4: INTERNAL API CHANGES + +The binary interface provided by the kernel to user space cannot be broken +except under the most severe circumstances. The kernel's internal +programming interfaces, instead, are highly fluid and can be changed when +the need arises. If you find yourself having to work around a kernel API, +or simply not using a specific functionality because it does not meet your +needs, that may be a sign that the API needs to change. As a kernel +developer, you are empowered to make such changes. + +There are, of course, some catches. API changes can be made, but they need +to be well justified. So any patch making an internal API change should be +accompanied by a description of what the change is and why it is +necessary. This kind of change should also be broken out into a separate +patch, rather than buried within a larger patch. + +The other catch is that a developer who changes an internal API is +generally charged with the task of fixing any code within the kernel tree +which is broken by the change. For a widely-used function, this duty can +lead to literally hundreds or thousands of changes - many of which are +likely to conflict with work being done by other developers. Needless to +say, this can be a large job, so it is best to be sure that the +justification is solid. + +When making an incompatible API change, one should, whenever possible, +ensure that code which has not been updated is caught by the compiler. +This will help you to be sure that you have found all in-tree uses of that +interface. It will also alert developers of out-of-tree code that there is +a change that they need to respond to. Supporting out-of-tree code is not +something that kernel developers need to be worried about, but we also do +not have to make life harder for out-of-tree developers than it it needs to +be. diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting new file mode 100644 index 00000000000..dd48132a74d --- /dev/null +++ b/Documentation/development-process/5.Posting @@ -0,0 +1,278 @@ +5: POSTING PATCHES + +Sooner or later, the time comes when your work is ready to be presented to +the community for review and, eventually, inclusion into the mainline +kernel. Unsurprisingly, the kernel development community has evolved a set +of conventions and procedures which are used in the posting of patches; +following them will make life much easier for everybody involved. This +document will attempt to cover these expectations in reasonable detail; +more information can also be found in the files SubmittingPatches, +SubmittingDrivers, and SubmitChecklist in the kernel documentation +directory. + + +5.1: WHEN TO POST + +There is a constant temptation to avoid posting patches before they are +completely "ready." For simple patches, that is not a problem. If the +work being done is complex, though, there is a lot to be gained by getting +feedback from the community before the work is complete. So you should +consider posting in-progress work, or even making a git tree available so +that interested developers can catch up with your work at any time. + +When posting code which is not yet considered ready for inclusion, it is a +good idea to say so in the posting itself. Also mention any major work +which remains to be done and any known problems. Fewer people will look at +patches which are known to be half-baked, but those who do will come in +with the idea that they can help you drive the work in the right direction. + + +5.2: BEFORE CREATING PATCHES + +There are a number of things which should be done before you consider +sending patches to the development community. These include: + + - Test the code to the extent that you can. Make use of the kernel's + debugging tools, ensure that the kernel will build with all reasonable + combinations of configuration options, use cross-compilers to build for + different architectures, etc. + + - Make sure your code is compliant with the kernel coding style + guidelines. + + - Does your change have performance implications? If so, you should run + benchmarks showing what the impact (or benefit) of your change is; a + summary of the results should be included with the patch. + + - Be sure that you have the right to post the code. If this work was done + for an employer, the employer likely has a right to the work and must be + agreeable with its release under the GPL. + +As a general rule, putting in some extra thought before posting code almost +always pays back the effort in short order. + + +5.3: PATCH PREPARATION + +The preparation of patches for posting can be a surprising amount of work, +but, once again, attempting to save time here is not generally advisable +even in the short term. + +Patches must be prepared against a specific version of the kernel. As a +general rule, a patch should be based on the current mainline as found in +Linus's git tree. It may become necessary to make versions against -mm, +linux-next, or a subsystem tree, though, to facilitate wider testing and +review. Depending on the area of your patch and what is going on +elsewhere, basing a patch against these other trees can require a +significant amount of work resolving conflicts and dealing with API +changes. + +Only the most simple changes should be formatted as a single patch; +everything else should be made as a logical series of changes. Splitting +up patches is a bit of an art; some developers spend a long time figuring +out how to do it in the way that the community expects. There are a few +rules of thumb, however, which can help considerably: + + - The patch series you post will almost certainly not be the series of + changes found in your working revision control system. Instead, the + changes you have made need to be considered in their final form, then + split apart in ways which make sense. The developers are interested in + discrete, self-contained changes, not the path you took to get to those + changes. + + - Each logically independent change should be formatted as a separate + patch. These changes can be small ("add a field to this structure") or + large (adding a significant new driver, for example), but they should be + conceptually small and amenable to a one-line description. Each patch + should make a specific change which can be reviewed on its own and + verified to do what it says it does. + + - As a way of restating the guideline above: do not mix different types of + changes in the same patch. If a single patch fixes a critical security + bug, rearranges a few structures, and reformats the code, there is a + good chance that it will be passed over and the important fix will be + lost. + + - Each patch should yield a kernel which builds and runs properly; if your + patch series is interrupted in the middle, the result should still be a + working kernel. Partial application of a patch series is a common + scenario when the "git bisect" tool is used to find regressions; if the + result is a broken kernel, you will make life harder for developers and + users who are engaging in the noble work of tracking down problems. + + - Do not overdo it, though. One developer recently posted a set of edits + to a single file as 500 separate patches - an act which did not make him + the most popular person on the kernel mailing list. A single patch can + be reasonably large as long as it still contains a single *logical* + change. + + - It can be tempting to add a whole new infrastructure with a series of + patches, but to leave that infrastructure unused until the final patch + in the series enables the whole thing. This temptation should be + avoided if possible; if that series adds regressions, bisection will + finger the last patch as the one which caused the problem, even though + the real bug is elsewhere. Whenever possible, a patch which adds new + code should make that code active immediately. + +Working to create the perfect patch series can be a frustrating process +which takes quite a bit of time and thought after the "real work" has been +done. When done properly, though, it is time well spent. + + +5.4: PATCH FORMATTING + +So now you have a perfect series of patches for posting, but the work is +not done quite yet. Each patch needs to be formatted into a message which +quickly and clearly communicates its purpose to the rest of the world. To +that end, each patch will be composed of the following: + + - An optional "From" line naming the author of the patch. This line is + only necessary if you are passing on somebody else's patch via email, + but it never hurts to add it when in doubt. + + - A one-line description of what the patch does. This message should be + enough for a reader who sees it with no other context to figure out the + scope of the patch; it is the line that will show up in the "short form" + changelogs. This message is usually formatted with the relevant + subsystem name first, followed by the purpose of the patch. For + example: + + gpio: fix build on CONFIG_GPIO_SYSFS=n + + - A blank line followed by a detailed description of the contents of the + patch. This description can be as long as is required; it should say + what the patch does and why it should be applied to the kernel. + + - One or more tag lines, with, at a minimum, one Signed-off-by: line from + the author of the patch. Tags will be described in more detail below. + +The above three items should, normally, be the text used when committing +the change to a revision control system. They are followed by: + + - The patch itself, in the unified ("-u") patch format. Using the "-p" + option to diff will associate function names with changes, making the + resulting patch easier for others to read. + +You should avoid including changes to irrelevant files (those generated by +the build process, for example, or editor backup files) in the patch. The +file "dontdiff" in the Documentation directory can help in this regard; +pass it to diff with the "-X" option. + +The tags mentioned above are used to describe how various developers have +been associated with the development of this patch. They are described in +detail in the SubmittingPatches document; what follows here is a brief +summary. Each of these lines has the format: + + tag: Full Name <email address> optional-other-stuff + +The tags in common use are: + + - Signed-off-by: this is a developer's certification that he or she has + the right to submit the patch for inclusion into the kernel. It is an + agreement to the Developer's Certificate of Origin, the full text of + which can be found in Documentation/SubmittingPatches. Code without a + proper signoff cannot be merged into the mainline. + + - Acked-by: indicates an agreement by another developer (often a + maintainer of the relevant code) that the patch is appropriate for + inclusion into the kernel. + + - Tested-by: states that the named person has tested the patch and found + it to work. + + - Reviewed-by: the named developer has reviewed the patch for correctness; + see the reviewer's statement in Documentation/SubmittingPatches for more + detail. + + - Reported-by: names a user who reported a problem which is fixed by this + patch; this tag is used to give credit to the (often underappreciated) + people who test our code and let us know when things do not work + correctly. + + - Cc: the named person received a copy of the patch and had the + opportunity to comment on it. + +Be careful in the addition of tags to your patches: only Cc: is appropriate +for addition without the explicit permission of the person named. + + +5.5: SENDING THE PATCH + +Before you mail your patches, there are a couple of other things you should +take care of: + + - Are you sure that your mailer will not corrupt the patches? Patches + which have had gratuitous white-space changes or line wrapping performed + by the mail client will not apply at the other end, and often will not + be examined in any detail. If there is any doubt at all, mail the patch + to yourself and convince yourself that it shows up intact. + + Documentation/email-clients.txt has some helpful hints on making + specific mail clients work for sending patches. + + - Are you sure your patch is free of silly mistakes? You should always + run patches through scripts/checkpatch.pl and address the complaints it + comes up with. Please bear in mind that checkpatch.pl, while being the + embodiment of a fair amount of thought about what kernel patches should + look like, is not smarter than you. If fixing a checkpatch.pl complaint + would make the code worse, don't do it. + +Patches should always be sent as plain text. Please do not send them as +attachments; that makes it much harder for reviewers to quote sections of +the patch in their replies. Instead, just put the patch directly into your +message. + +When mailing patches, it is important to send copies to anybody who might +be interested in it. Unlike some other projects, the kernel encourages +people to err on the side of sending too many copies; don't assume that the +relevant people will see your posting on the mailing lists. In particular, +copies should go to: + + - The maintainer(s) of the affected subsystem(s). As described earlier, + the MAINTAINERS file is the first place to look for these people. + + - Other developers who have been working in the same area - especially + those who might be working there now. Using git to see who else has + modified the files you are working on can be helpful. + + - If you are responding to a bug report or a feature request, copy the + original poster as well. + + - Send a copy to the relevant mailing list, or, if nothing else applies, + the linux-kernel list. + + - If you are fixing a bug, think about whether the fix should go into the + next stable update. If so, stable@kernel.org should get a copy of the + patch. Also add a "Cc: stable@kernel.org" to the tags within the patch + itself; that will cause the stable team to get a notification when your + fix goes into the mainline. + +When selecting recipients for a patch, it is good to have an idea of who +you think will eventually accept the patch and get it merged. While it +is possible to send patches directly to Linus Torvalds and have him merge +them, things are not normally done that way. Linus is busy, and there are +subsystem maintainers who watch over specific parts of the kernel. Usually +you will be wanting that maintainer to merge your patches. If there is no +obvious maintainer, Andrew Morton is often the patch target of last resort. + +Patches need good subject lines. The canonical format for a patch line is +something like: + + [PATCH nn/mm] subsys: one-line description of the patch + +where "nn" is the ordinal number of the patch, "mm" is the total number of +patches in the series, and "subsys" is the name of the affected subsystem. +Clearly, nn/mm can be omitted for a single, standalone patch. + +If you have a significant series of patches, it is customary to send an +introductory description as part zero. This convention is not universally +followed though; if you use it, remember that information in the +introduction does not make it into the kernel changelogs. So please ensure +that the patches, themselves, have complete changelog information. + +In general, the second and following parts of a multi-part patch should be +sent as a reply to the first part so that they all thread together at the +receiving end. Tools like git and quilt have commands to mail out a set of +patches with the proper threading. If you have a long series, though, and +are using git, please provide the --no-chain-reply-to option to avoid +creating exceptionally deep nesting. diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough new file mode 100644 index 00000000000..a8fba3d83a8 --- /dev/null +++ b/Documentation/development-process/6.Followthrough @@ -0,0 +1,202 @@ +6: FOLLOWTHROUGH + +At this point, you have followed the guidelines given so far and, with the +addition of your own engineering skills, have posted a perfect series of +patches. One of the biggest mistakes that even experienced kernel +developers can make is to conclude that their work is now done. In truth, +posting patches indicates a transition into the next stage of the process, +with, possibly, quite a bit of work yet to be done. + +It is a rare patch which is so good at its first posting that there is no +room for improvement. The kernel development process recognizes this fact, +and, as a result, is heavily oriented toward the improvement of posted +code. You, as the author of that code, will be expected to work with the +kernel community to ensure that your code is up to the kernel's quality +standards. A failure to participate in this process is quite likely to +prevent the inclusion of your patches into the mainline. + + +6.1: WORKING WITH REVIEWERS + +A patch of any significance will result in a number of comments from other +developers as they review the code. Working with reviewers can be, for +many developers, the most intimidating part of the kernel development +process. Life can be made much easier, though, if you keep a few things in +mind: + + - If you have explained your patch well, reviewers will understand its + value and why you went to the trouble of writing it. But that value + will not keep them from asking a fundamental question: what will it be + like to maintain a kernel with this code in it five or ten years later? + Many of the changes you may be asked to make - from coding style tweaks + to substantial rewrites - come from the understanding that Linux will + still be around and under development a decade from now. + + - Code review is hard work, and it is a relatively thankless occupation; + people remember who wrote kernel code, but there is little lasting fame + for those who reviewed it. So reviewers can get grumpy, especially when + they see the same mistakes being made over and over again. If you get a + review which seems angry, insulting, or outright offensive, resist the + impulse to respond in kind. Code review is about the code, not about + the people, and code reviewers are not attacking you personally. + + - Similarly, code reviewers are not trying to promote their employers' + agendas at the expense of your own. Kernel developers often expect to + be working on the kernel years from now, but they understand that their + employer could change. They truly are, almost without exception, + working toward the creation of the best kernel they can; they are not + trying to create discomfort for their employers' competitors. + +What all of this comes down to is that, when reviewers send you comments, +you need to pay attention to the technical observations that they are +making. Do not let their form of expression or your own pride keep that +from happening. When you get review comments on a patch, take the time to +understand what the reviewer is trying to say. If possible, fix the things +that the reviewer is asking you to fix. And respond back to the reviewer: +thank them, and describe how you will answer their questions. + +Note that you do not have to agree with every change suggested by +reviewers. If you believe that the reviewer has misunderstood your code, +explain what is really going on. If you have a technical objection to a +suggested change, describe it and justify your solution to the problem. If +your explanations make sense, the reviewer will accept them. Should your +explanation not prove persuasive, though, especially if others start to +agree with the reviewer, take some time to think things over again. It can +be easy to become blinded by your own solution to a problem to the point +that you don't realize that something is fundamentally wrong or, perhaps, +you're not even solving the right problem. + +One fatal mistake is to ignore review comments in the hope that they will +go away. They will not go away. If you repost code without having +responded to the comments you got the time before, you're likely to find +that your patches go nowhere. + +Speaking of reposting code: please bear in mind that reviewers are not +going to remember all the details of the code you posted the last time +around. So it is always a good idea to remind reviewers of previously +raised issues and how you dealt with them; the patch changelog is a good +place for this kind of information. Reviewers should not have to search +through list archives to familiarize themselves with what was said last +time; if you help them get a running start, they will be in a better mood +when they revisit your code. + +What if you've tried to do everything right and things still aren't going +anywhere? Most technical disagreements can be resolved through discussion, +but there are times when somebody simply has to make a decision. If you +honestly believe that this decision is going against you wrongly, you can +always try appealing to a higher power. As of this writing, that higher +power tends to be Andrew Morton. Andrew has a great deal of respect in the +kernel development community; he can often unjam a situation which seems to +be hopelessly blocked. Appealing to Andrew should not be done lightly, +though, and not before all other alternatives have been explored. And bear +in mind, of course, that he may not agree with you either. + + +6.2: WHAT HAPPENS NEXT + +If a patch is considered to be a good thing to add to the kernel, and once +most of the review issues have been resolved, the next step is usually +entry into a subsystem maintainer's tree. How that works varies from one +subsystem to the next; each maintainer has his or her own way of doing +things. In particular, there may be more than one tree - one, perhaps, +dedicated to patches planned for the next merge window, and another for +longer-term work. + +For patches applying to areas for which there is no obvious subsystem tree +(memory management patches, for example), the default tree often ends up +being -mm. Patches which affect multiple subsystems can also end up going +through the -mm tree. + +Inclusion into a subsystem tree can bring a higher level of visibility to a +patch. Now other developers working with that tree will get the patch by +default. Subsystem trees typically feed into -mm and linux-next as well, +making their contents visible to the development community as a whole. At +this point, there's a good chance that you will get more comments from a +new set of reviewers; these comments need to be answered as in the previous +round. + +What may also happen at this point, depending on the nature of your patch, +is that conflicts with work being done by others turn up. In the worst +case, heavy patch conflicts can result in some work being put on the back +burner so that the remaining patches can be worked into shape and merged. +Other times, conflict resolution will involve working with the other +developers and, possibly, moving some patches between trees to ensure that +everything applies cleanly. This work can be a pain, but count your +blessings: before the advent of the linux-next tree, these conflicts often +only turned up during the merge window and had to be addressed in a hurry. +Now they can be resolved at leisure, before the merge window opens. + +Some day, if all goes well, you'll log on and see that your patch has been +merged into the mainline kernel. Congratulations! Once the celebration is +complete (and you have added yourself to the MAINTAINERS file), though, it +is worth remembering an important little fact: the job still is not done. +Merging into the mainline brings its own challenges. + +To begin with, the visibility of your patch has increased yet again. There +may be a new round of comments from developers who had not been aware of +the patch before. It may be tempting to ignore them, since there is no +longer any question of your code being merged. Resist that temptation, +though; you still need to be responsive to developers who have questions or +suggestions. + +More importantly, though: inclusion into the mainline puts your code into +the hands of a much larger group of testers. Even if you have contributed +a driver for hardware which is not yet available, you will be surprised by +how many people will build your code into their kernels. And, of course, +where there are testers, there will be bug reports. + +The worst sort of bug reports are regressions. If your patch causes a +regression, you'll find an uncomfortable number of eyes upon you; +regressions need to be fixed as soon as possible. If you are unwilling or +unable to fix the regression (and nobody else does it for you), your patch +will almost certainly be removed during the stabilization period. Beyond +negating all of the work you have done to get your patch into the mainline, +having a patch pulled as the result of a failure to fix a regression could +well make it harder for you to get work merged in the future. + +After any regressions have been dealt with, there may be other, ordinary +bugs to deal with. The stabilization period is your best opportunity to +fix these bugs and ensure that your code's debut in a mainline kernel +release is as solid as possible. So, please, answer bug reports, and fix +the problems if at all possible. That's what the stabilization period is +for; you can start creating cool new patches once any problems with the old +ones have been taken care of. + +And don't forget that there are other milestones which may also create bug +reports: the next mainline stable release, when prominent distributors pick +up a version of the kernel containing your patch, etc. Continuing to +respond to these reports is a matter of basic pride in your work. If that +is insufficient motivation, though, it's also worth considering that the +development community remembers developers who lose interest in their code +after it's merged. The next time you post a patch, they will be evaluating +it with the assumption that you will not be around to maintain it +afterward. + + +6.3: OTHER THINGS THAT CAN HAPPEN + +One day, you may open your mail client and see that somebody has mailed you +a patch to your code. That is one of the advantages of having your code +out there in the open, after all. If you agree with the patch, you can +either forward it on to the subsystem maintainer (be sure to include a +proper From: line so that the attribution is correct, and add a signoff of +your own), or send an Acked-by: response back and let the original poster +send it upward. + +If you disagree with the patch, send a polite response explaining why. If +possible, tell the author what changes need to be made to make the patch +acceptable to you. There is a certain resistance to merging patches which +are opposed by the author and maintainer of the code, but it only goes so +far. If you are seen as needlessly blocking good work, those patches will +eventually flow around you and get into the mainline anyway. In the Linux +kernel, nobody has absolute veto power over any code. Except maybe Linus. + +On very rare occasion, you may see something completely different: another +developer posts a different solution to your problem. At that point, +chances are that one of the two patches will not be merged, and "mine was +here first" is not considered to be a compelling technical argument. If +somebody else's patch displaces yours and gets into the mainline, there is +really only one way to respond: be pleased that your problem got solved and +get on with your work. Having one's work shoved aside in this manner can +be hurtful and discouraging, but the community will remember your reaction +long after they have forgotten whose patch actually got merged. diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics new file mode 100644 index 00000000000..a2cf74093aa --- /dev/null +++ b/Documentation/development-process/7.AdvancedTopics @@ -0,0 +1,173 @@ +7: ADVANCED TOPICS + +At this point, hopefully, you have a handle on how the development process +works. There is still more to learn, however! This section will cover a +number of topics which can be helpful for developers wanting to become a +regular part of the Linux kernel development process. + +7.1: MANAGING PATCHES WITH GIT + +The use of distributed version control for the kernel began in early 2002, +when Linus first started playing with the proprietary BitKeeper +application. While BitKeeper was controversial, the approach to software +version management it embodied most certainly was not. Distributed version +control enabled an immediate acceleration of the kernel development +project. In current times, there are several free alternatives to +BitKeeper. For better or for worse, the kernel project has settled on git +as its tool of choice. + +Managing patches with git can make life much easier for the developer, +especially as the volume of those patches grows. Git also has its rough +edges and poses certain hazards; it is a young and powerful tool which is +still being civilized by its developers. This document will not attempt to +teach the reader how to use git; that would be sufficient material for a +long document in its own right. Instead, the focus here will be on how git +fits into the kernel development process in particular. Developers who +wish to come up to speed with git will find more information at: + + http://git.or.cz/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + +and on various tutorials found on the web. + +The first order of business is to read the above sites and get a solid +understanding of how git works before trying to use it to make patches +available to others. A git-using developer should be able to obtain a copy +of the mainline repository, explore the revision history, commit changes to +the tree, use branches, etc. An understanding of git's tools for the +rewriting of history (such as rebase) is also useful. Git comes with its +own terminology and concepts; a new user of git should know about refs, +remote branches, the index, fast-forward merges, pushes and pulls, detached +heads, etc. It can all be a little intimidating at the outset, but the +concepts are not that hard to grasp with a bit of study. + +Using git to generate patches for submission by email can be a good +exercise while coming up to speed. + +When you are ready to start putting up git trees for others to look at, you +will, of course, need a server that can be pulled from. Setting up such a +server with git-daemon is relatively straightforward if you have a system +which is accessible to the Internet. Otherwise, free, public hosting sites +(Github, for example) are starting to appear on the net. Established +developers can get an account on kernel.org, but those are not easy to come +by; see http://kernel.org/faq/ for more information. + +The normal git workflow involves the use of a lot of branches. Each line +of development can be separated into a separate "topic branch" and +maintained independently. Branches in git are cheap, there is no reason to +not make free use of them. And, in any case, you should not do your +development in any branch which you intend to ask others to pull from. +Publicly-available branches should be created with care; merge in patches +from development branches when they are in complete form and ready to go - +not before. + +Git provides some powerful tools which can allow you to rewrite your +development history. An inconvenient patch (one which breaks bisection, +say, or which has some other sort of obvious bug) can be fixed in place or +made to disappear from the history entirely. A patch series can be +rewritten as if it had been written on top of today's mainline, even though +you have been working on it for months. Changes can be transparently +shifted from one branch to another. And so on. Judicious use of git's +ability to revise history can help in the creation of clean patch sets with +fewer problems. + +Excessive use of this capability can lead to other problems, though, beyond +a simple obsession for the creation of the perfect project history. +Rewriting history will rewrite the changes contained in that history, +turning a tested (hopefully) kernel tree into an untested one. But, beyond +that, developers cannot easily collaborate if they do not have a shared +view of the project history; if you rewrite history which other developers +have pulled into their repositories, you will make life much more difficult +for those developers. So a simple rule of thumb applies here: history +which has been exported to others should generally be seen as immutable +thereafter. + +So, once you push a set of changes to your publicly-available server, those +changes should not be rewritten. Git will attempt to enforce this rule if +you try to push changes which do not result in a fast-forward merge +(i.e. changes which do not share the same history). It is possible to +override this check, and there may be times when it is necessary to rewrite +an exported tree. Moving changesets between trees to avoid conflicts in +linux-next is one example. But such actions should be rare. This is one +of the reasons why development should be done in private branches (which +can be rewritten if necessary) and only moved into public branches when +it's in a reasonably advanced state. + +As the mainline (or other tree upon which a set of changes is based) +advances, it is tempting to merge with that tree to stay on the leading +edge. For a private branch, rebasing can be an easy way to keep up with +another tree, but rebasing is not an option once a tree is exported to the +world. Once that happens, a full merge must be done. Merging occasionally +makes good sense, but overly frequent merges can clutter the history +needlessly. Suggested technique in this case is to merge infrequently, and +generally only at specific release points (such as a mainline -rc +release). If you are nervous about specific changes, you can always +perform test merges in a private branch. The git "rerere" tool can be +useful in such situations; it remembers how merge conflicts were resolved +so that you don't have to do the same work twice. + +One of the biggest recurring complaints about tools like git is this: the +mass movement of patches from one repository to another makes it easy to +slip in ill-advised changes which go into the mainline below the review +radar. Kernel developers tend to get unhappy when they see that kind of +thing happening; putting up a git tree with unreviewed or off-topic patches +can affect your ability to get trees pulled in the future. Quoting Linus: + + You can send me patches, but for me to pull a git patch from you, I + need to know that you know what you're doing, and I need to be able + to trust things *without* then having to go and check every + individual change by hand. + +(http://lwn.net/Articles/224135/). + +To avoid this kind of situation, ensure that all patches within a given +branch stick closely to the associated topic; a "driver fixes" branch +should not be making changes to the core memory management code. And, most +importantly, do not use a git tree to bypass the review process. Post an +occasional summary of the tree to the relevant list, and, when the time is +right, request that the tree be included in linux-next. + +If and when others start to send patches for inclusion into your tree, +don't forget to review them. Also ensure that you maintain the correct +authorship information; the git "am" tool does its best in this regard, but +you may have to add a "From:" line to the patch if it has been relayed to +you via a third party. + +When requesting a pull, be sure to give all the relevant information: where +your tree is, what branch to pull, and what changes will result from the +pull. The git request-pull command can be helpful in this regard; it will +format the request as other developers expect, and will also check to be +sure that you have remembered to push those changes to the public server. + + +7.2: REVIEWING PATCHES + +Some readers will certainly object to putting this section with "advanced +topics" on the grounds that even beginning kernel developers should be +reviewing patches. It is certainly true that there is no better way to +learn how to program in the kernel environment than by looking at code +posted by others. In addition, reviewers are forever in short supply; by +looking at code you can make a significant contribution to the process as a +whole. + +Reviewing code can be an intimidating prospect, especially for a new kernel +developer who may well feel nervous about questioning code - in public - +which has been posted by those with more experience. Even code written by +the most experienced developers can be improved, though. Perhaps the best +piece of advice for reviewers (all reviewers) is this: phrase review +comments as questions rather than criticisms. Asking "how does the lock +get released in this path?" will always work better than stating "the +locking here is wrong." + +Different developers will review code from different points of view. Some +are mostly concerned with coding style and whether code lines have trailing +white space. Others will focus primarily on whether the change implemented +by the patch as a whole is a good thing for the kernel or not. Yet others +will check for problematic locking, excessive stack usage, possible +security issues, duplication of code found elsewhere, adequate +documentation, adverse effects on performance, user-space ABI changes, etc. +All types of review, if they lead to better code going into the kernel, are +welcome and worthwhile. + + diff --git a/Documentation/development-process/8.Conclusion b/Documentation/development-process/8.Conclusion new file mode 100644 index 00000000000..1990ab4b494 --- /dev/null +++ b/Documentation/development-process/8.Conclusion @@ -0,0 +1,74 @@ +8: FOR MORE INFORMATION + +There are numerous sources of information on Linux kernel development and +related topics. First among those will always be the Documentation +directory found in the kernel source distribution. The top-level HOWTO +file is an important starting point; SubmittingPatches and +SubmittingDrivers are also something which all kernel developers should +read. Many internal kernel APIs are documented using the kerneldoc +mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those +documents in HTML or PDF format (though the version of TeX shipped by some +distributions runs into internal limits and fails to process the documents +properly). + +Various web sites discuss kernel development at all levels of detail. Your +author would like to humbly suggest http://lwn.net/ as a source; +information on many specific kernel topics can be found via the LWN kernel +index at: + + http://lwn.net/Kernel/Index/ + +Beyond that, a valuable resource for kernel developers is: + + http://kernelnewbies.org/ + +Information about the linux-next tree gathers at: + + http://linux.f-seidel.de/linux-next/pmwiki/ + +And, of course, one should not forget http://kernel.org/, the definitive +location for kernel release information. + +There are a number of books on kernel development: + + Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro + Rubini, and Greg Kroah-Hartman). Online at + http://lwn.net/Kernel/LDD3/. + + Linux Kernel Development (Robert Love). + + Understanding the Linux Kernel (Daniel Bovet and Marco Cesati). + +All of these books suffer from a common fault, though: they tend to be +somewhat obsolete by the time they hit the shelves, and they have been on +the shelves for a while now. Still, there is quite a bit of good +information to be found there. + +Documentation for git can be found at: + + http://www.kernel.org/pub/software/scm/git/docs/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + + +9: CONCLUSION + +Congratulations to anybody who has made it through this long-winded +document. Hopefully it has provided a helpful understanding of how the +Linux kernel is developed and how you can participate in that process. + +In the end, it's the participation that matters. Any open source software +project is no more than the sum of what its contributors put into it. The +Linux kernel has progressed as quickly and as well as it has because it has +been helped by an impressively large group of developers, all of whom are +working to make it better. The kernel is a premier example of what can be +done when thousands of people work together toward a common goal. + +The kernel can always benefit from a larger developer base, though. There +is always more work to do. But, just as importantly, most other +participants in the Linux ecosystem can benefit through contributing to the +kernel. Getting code into the mainline is the key to higher code quality, +lower maintenance and distribution costs, a higher level of influence over +the direction of kernel development, and more. It is a situation where +everybody involved wins. Fire up your editor and come join us; you will be +more than welcome. diff --git a/Documentation/devices.txt b/Documentation/devices.txt index 05c80645e4e..2be08240ee8 100644 --- a/Documentation/devices.txt +++ b/Documentation/devices.txt @@ -2571,6 +2571,9 @@ Your cooperation is appreciated. 160 = /dev/usb/legousbtower0 1st USB Legotower device ... 175 = /dev/usb/legousbtower15 16th USB Legotower device + 176 = /dev/usb/usbtmc1 First USB TMC device + ... + 192 = /dev/usb/usbtmc16 16th USB TMC device 240 = /dev/usb/dabusb0 First daubusb device ... 243 = /dev/usb/dabusb3 Fourth dabusb device diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 27809357da5..1e89a51ea49 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -2,11 +2,13 @@ *.aux *.bin *.cpio -*.css +*.csp +*.dsp *.dvi +*.elf *.eps -*.fw.gen.S *.fw +*.gen.S *.gif *.grep *.grp @@ -30,6 +32,7 @@ *.s *.sgml *.so +*.so.dbg *.symtypes *.tab.c *.tab.h @@ -38,24 +41,17 @@ *.xml *_MODULES *_vga16.c -*cscope* *~ *.9 *.9.gz .* -.cscope -.gitignore -.mailmap .mm 53c700_d.h -53c8xx_d.h* -COPYING -CREDITS CVS ChangeSet Image Kerntypes -MODS.txt +Module.markers Module.symvers PENDING SCCS @@ -73,7 +69,9 @@ autoconf.h* bbootsect bin2c binkernel.spec +binoffset bootsect +bounds.h bsetup btfixupprep build @@ -89,39 +87,36 @@ config_data.h* config_data.gz* conmakehash consolemap_deftbl.c* +cpustr.h crc32table.h* cscope.* -defkeymap.c* +defkeymap.c devlist.h* docproc -dummy_sym.c* elf2ecoff elfconfig.h* -filelist fixdep fore200e_mkfirm fore200e_pca_fw.c* gconf gen-devlist -gen-kdb_cmds.c* gen_crc32table gen_init_cpio genksyms -gentbl *_gray256.c +ihex2fw ikconfig.h* initramfs_data.cpio initramfs_data.cpio.gz initramfs_list kallsyms kconfig -kconfig.tk -keywords.c* +keywords.c ksym.c* ksym.h* kxgettext lkc_defs.h -lex.c* +lex.c lex.*.c logo_*.c logo_*_clut224.c @@ -130,7 +125,6 @@ lxdialog mach-types mach-types.h machtypes.h -make_times_h map maui_boot.h mconf @@ -138,6 +132,7 @@ miboot* mk_elfconfig mkboot mkbugboot +mkcpustr mkdep mkprep mktables @@ -145,11 +140,12 @@ mktree modpost modules.order modversions.h* +ncscope.* offset.h offsets.h oui.c* -parse.c* -parse.h* +parse.c +parse.h patches* pca200e.bin pca200e_ecd.bin2 @@ -157,7 +153,7 @@ piggy.gz piggyback pnmtologo ppc_defs.h* -promcon_tbl.c* +promcon_tbl.c pss_boot.h qconf raid6altivec*.c @@ -168,27 +164,38 @@ series setup setup.bin setup.elf -sim710_d.h* sImage sm_tbl* split-include +syscalltab.h tags tftpboot.img timeconst.h times.h* -tkparse trix_boot.h utsrelease.h* +vdso-syms.lds vdso.lds +vdso32-int80-syms.lds +vdso32-syms.lds +vdso32-syscall-syms.lds +vdso32-sysenter-syms.lds +vdso32.lds +vdso32.so.dbg +vdso64.lds +vdso64.so.dbg version.h* vmlinux vmlinux-* vmlinux.aout -vmlinux*.lds* -vmlinux*.scr +vmlinux.lds vsyscall.lds +vsyscall_32.lds wanxlfw.inc uImage unifdef +wakeup.bin +wakeup.elf +wakeup.lds zImage* zconf.hash.c diff --git a/Documentation/dvb/technisat.txt b/Documentation/dvb/technisat.txt new file mode 100644 index 00000000000..cdf6ee4b2da --- /dev/null +++ b/Documentation/dvb/technisat.txt @@ -0,0 +1,69 @@ +How to set up the Technisat devices +=================================== + +1) Find out what device you have +================================ + +First start your linux box with a shipped kernel: +lspci -vvv for a PCI device (lsusb -vvv for an USB device) will show you for example: +02:0b.0 Network controller: Techsan Electronics Co Ltd B2C2 FlexCopII DVB chip / Technisat SkyStar2 DVB card (rev 02) + +dmesg | grep frontend may show you for example: +DVB: registering frontend 0 (Conexant CX24123/CX24109)... + +2) Kernel compilation: +====================== + +If the Technisat is the only TV device in your box get rid of unnecessary modules and check this one: +"Multimedia devices" => "Customise analog and hybrid tuner modules to build" +In this directory uncheck every driver which is activated there. + +Then please activate: +2a) Main module part: + +a.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" +b.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Technisat/B2C2 Air/Sky/Cable2PC PCI" in case of a PCI card OR +c.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Technisat/B2C2 Air/Sky/Cable2PC USB" in case of an USB 1.1 adapter +d.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Enable debug for the B2C2 FlexCop drivers" +Notice: d.) is helpful for troubleshooting + +2b) Frontend module part: + +1.) Revision 2.3: +a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" +b.)"Multimedia devices" => "Customise DVB frontends" => "Zarlink VP310/MT312/ZL10313 based" + +2.) Revision 2.6: +a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" +b.)"Multimedia devices" => "Customise DVB frontends" => "ST STV0299 based" + +3.) Revision 2.7: +a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" +b.)"Multimedia devices" => "Customise DVB frontends" => "Samsung S5H1420 based" +c.)"Multimedia devices" => "Customise DVB frontends" => "Integrant ITD1000 Zero IF tuner for DVB-S/DSS" +d.)"Multimedia devices" => "Customise DVB frontends" => "ISL6421 SEC controller" + +4.) Revision 2.8: +a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" +b.)"Multimedia devices" => "Customise DVB frontends" => "Conexant CX24113/CX24128 tuner for DVB-S/DSS" +c.)"Multimedia devices" => "Customise DVB frontends" => "Conexant CX24123 based" +d.)"Multimedia devices" => "Customise DVB frontends" => "ISL6421 SEC controller" + +5.) DVB-T card: +a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" +b.)"Multimedia devices" => "Customise DVB frontends" => "Zarlink MT352 based" + +6.) DVB-C card: +a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" +b.)"Multimedia devices" => "Customise DVB frontends" => "ST STV0297 based" + +7.) ATSC card 1st generation: +a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" +b.)"Multimedia devices" => "Customise DVB frontends" => "Broadcom BCM3510" + +8.) ATSC card 2nd generation: +a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build" +b.)"Multimedia devices" => "Customise DVB frontends" => "NxtWave Communications NXT2002/NXT2004 based" +c.)"Multimedia devices" => "Customise DVB frontends" => "LG Electronics LGDT3302/LGDT3303 based" + +Author: Uwe Bugla <uwe.bugla@gmx.de> December 2008 diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt index 2ebb94d6ed8..a618efab7b1 100644 --- a/Documentation/email-clients.txt +++ b/Documentation/email-clients.txt @@ -213,4 +213,29 @@ TkRat (GUI) Works. Use "Insert file..." or external editor. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Gmail (Web GUI) + +If you just have to use Gmail to send patches, it CAN be made to work. It +requires a bit of external help, though. + +The first problem is that Gmail converts tabs to spaces. This will +totally break your patches. To prevent this, you have to use a different +editor. There is a firefox extension called "ViewSourceWith" +(https://addons.mozilla.org/en-US/firefox/addon/394) which allows you to +edit any text box in the editor of your choice. Configure it to launch +your favorite editor. When you want to send a patch, use this technique. +Once you have crafted your messsage + patch, save and exit the editor, +which should reload the Gmail edit box. GMAIL WILL PRESERVE THE TABS. +Hoorah. Apparently you can cut-n-paste literal tabs, but Gmail will +convert those to spaces upon sending! + +The second problem is that Gmail converts tabs to spaces on replies. If +you reply to a patch, don't expect to be able to apply it as a patch. + +The last problem is that Gmail will base64-encode any message that has a +non-ASCII character. That includes things like European names. Be aware. + +Gmail is not convenient for lkml patches, but CAN be made to work. + ### diff --git a/Documentation/fb/intelfb.txt b/Documentation/fb/intelfb.txt index 27a3160650a..dd9e944ea62 100644 --- a/Documentation/fb/intelfb.txt +++ b/Documentation/fb/intelfb.txt @@ -14,6 +14,7 @@ graphics devices. These would include: Intel 915GM Intel 945G Intel 945GM + Intel 945GME Intel 965G Intel 965GM diff --git a/Documentation/fb/pxafb.txt b/Documentation/fb/pxafb.txt index db9b8500b43..d143a0a749f 100644 --- a/Documentation/fb/pxafb.txt +++ b/Documentation/fb/pxafb.txt @@ -5,9 +5,13 @@ The driver supports the following options, either via options=<OPTIONS> when modular or video=pxafb:<OPTIONS> when built in. For example: - modprobe pxafb options=mode:640x480-8,passive + modprobe pxafb options=vmem:2M,mode:640x480-8,passive or on the kernel command line - video=pxafb:mode:640x480-8,passive + video=pxafb:vmem:2M,mode:640x480-8,passive + +vmem: VIDEO_MEM_SIZE + Amount of video memory to allocate (can be suffixed with K or M + for kilobytes or megabytes) mode:XRESxYRES[-BPP] XRES == LCCR1_PPL + 1 @@ -52,3 +56,87 @@ outputen:POLARITY pixclockpol:POLARITY pixel clock polarity 0 => falling edge, 1 => rising edge + + +Overlay Support for PXA27x and later LCD controllers +==================================================== + + PXA27x and later processors support overlay1 and overlay2 on-top of the + base framebuffer (although under-neath the base is also possible). They + support palette and no-palette RGB formats, as well as YUV formats (only + available on overlay2). These overlays have dedicated DMA channels and + behave in a similar way as a framebuffer. + + However, there are some differences between these overlay framebuffers + and normal framebuffers, as listed below: + + 1. overlay can start at a 32-bit word aligned position within the base + framebuffer, which means they have a start (x, y). This information + is encoded into var->nonstd (no, var->xoffset and var->yoffset are + not for such purpose). + + 2. overlay framebuffer is allocated dynamically according to specified + 'struct fb_var_screeninfo', the amount is decided by: + + var->xres_virtual * var->yres_virtual * bpp + + bpp = 16 -- for RGB565 or RGBT555 + = 24 -- for YUV444 packed + = 24 -- for YUV444 planar + = 16 -- for YUV422 planar (1 pixel = 1 Y + 1/2 Cb + 1/2 Cr) + = 12 -- for YUV420 planar (1 pixel = 1 Y + 1/4 Cb + 1/4 Cr) + + NOTE: + + a. overlay does not support panning in x-direction, thus + var->xres_virtual will always be equal to var->xres + + b. line length of overlay(s) must be on a 32-bit word boundary, + for YUV planar modes, it is a requirement for the component + with minimum bits per pixel, e.g. for YUV420, Cr component + for one pixel is actually 2-bits, it means the line length + should be a multiple of 16-pixels + + c. starting horizontal position (XPOS) should start on a 32-bit + word boundary, otherwise the fb_check_var() will just fail. + + d. the rectangle of the overlay should be within the base plane, + otherwise fail + + Applications should follow the sequence below to operate an overlay + framebuffer: + + a. open("/dev/fb[1-2]", ...) + b. ioctl(fd, FBIOGET_VSCREENINFO, ...) + c. modify 'var' with desired parameters: + 1) var->xres and var->yres + 2) larger var->yres_virtual if more memory is required, + usually for double-buffering + 3) var->nonstd for starting (x, y) and color format + 4) var->{red, green, blue, transp} if RGB mode is to be used + d. ioctl(fd, FBIOPUT_VSCREENINFO, ...) + e. ioctl(fd, FBIOGET_FSCREENINFO, ...) + f. mmap + g. ... + + 3. for YUV planar formats, these are actually not supported within the + framebuffer framework, application has to take care of the offsets + and lengths of each component within the framebuffer. + + 4. var->nonstd is used to pass starting (x, y) position and color format, + the detailed bit fields are shown below: + + 31 23 20 10 0 + +-----------------+---+----------+----------+ + | ... unused ... |FOR| XPOS | YPOS | + +-----------------+---+----------+----------+ + + FOR - color format, as defined by OVERLAY_FORMAT_* in pxafb.h + 0 - RGB + 1 - YUV444 PACKED + 2 - YUV444 PLANAR + 3 - YUV422 PLANAR + 4 - YUR420 PLANAR + + XPOS - starting horizontal position + YPOS - starting vertical position diff --git a/Documentation/fb/uvesafb.txt b/Documentation/fb/uvesafb.txt index bcfc233a008..7ac3c4078ff 100644 --- a/Documentation/fb/uvesafb.txt +++ b/Documentation/fb/uvesafb.txt @@ -52,7 +52,7 @@ are either given on the kernel command line or as module parameters, e.g.: video=uvesafb:1024x768-32,mtrr:3,ywrap (compiled into the kernel) - # modprobe uvesafb mode=1024x768-32 mtrr=3 scroll=ywrap (module) + # modprobe uvesafb mode_option=1024x768-32 mtrr=3 scroll=ywrap (module) Accepted options: @@ -105,7 +105,7 @@ vtotal:n <mode> The mode you want to set, in the standard modedb format. Refer to modedb.txt for a detailed description. When uvesafb is compiled as a module, the mode string should be provided as a value of the - 'mode' option. + 'mode_option' option. vbemode:x Force the use of VBE mode x. The mode will only be set if it's diff --git a/Documentation/fb/viafb.modes b/Documentation/fb/viafb.modes new file mode 100644 index 00000000000..02e5b487f00 --- /dev/null +++ b/Documentation/fb/viafb.modes @@ -0,0 +1,870 @@ +# +# +# These data are based on the CRTC parameters in +# +# VIA Integration Graphics Chip +# (C) 2004 VIA Technologies Inc. +# + +# +# 640x480, 60 Hz, Non-Interlaced (25.175 MHz dotclock) +# +# Horizontal Vertical +# Resolution 640 480 +# Scan Frequency 31.469 kHz 59.94 Hz +# Sync Width 3.813 us 0.064 ms +# 12 chars 2 lines +# Front Porch 0.636 us 0.318 ms +# 2 chars 10 lines +# Back Porch 1.907 us 1.048 ms +# 6 chars 33 lines +# Active Time 25.422 us 15.253 ms +# 80 chars 480 lines +# Blank Time 6.356 us 1.430 ms +# 20 chars 45 lines +# Polarity negative negative +# + +mode "640x480-60" +# D: 25.175 MHz, H: 31.469 kHz, V: 59.94 Hz + geometry 640 480 640 480 32 + timings 39722 48 16 33 10 96 2 endmode mode "480x640-60" +# D: 24.823 MHz, H: 39.780 kHz, V: 60.00 Hz + geometry 480 640 480 640 32 timings 39722 72 24 19 1 48 3 endmode +# +# 640x480, 75 Hz, Non-Interlaced (31.50 MHz dotclock) +# +# Horizontal Vertical +# Resolution 640 480 +# Scan Frequency 37.500 kHz 75.00 Hz +# Sync Width 2.032 us 0.080 ms +# 8 chars 3 lines +# Front Porch 0.508 us 0.027 ms +# 2 chars 1 lines +# Back Porch 3.810 us 0.427 ms +# 15 chars 16 lines +# Active Time 20.317 us 12.800 ms +# 80 chars 480 lines +# Blank Time 6.349 us 0.533 ms +# 25 chars 20 lines +# Polarity negative negative +# + mode "640x480-75" +# D: 31.50 MHz, H: 37.500 kHz, V: 75.00 Hz + geometry 640 480 640 480 32 timings 31747 120 16 16 1 64 3 endmode +# +# 640x480, 85 Hz, Non-Interlaced (36.000 MHz dotclock) +# +# Horizontal Vertical +# Resolution 640 480 +# Scan Frequency 43.269 kHz 85.00 Hz +# Sync Width 1.556 us 0.069 ms +# 7 chars 3 lines +# Front Porch 1.556 us 0.023 ms +# 7 chars 1 lines +# Back Porch 2.222 us 0.578 ms +# 10 chars 25 lines +# Active Time 17.778 us 11.093 ms +# 80 chars 480 lines +# Blank Time 5.333 us 0.670 ms +# 24 chars 29 lines +# Polarity negative negative +# + mode "640x480-85" +# D: 36.000 MHz, H: 43.269 kHz, V: 85.00 Hz + geometry 640 480 640 480 32 timings 27777 80 56 25 1 56 3 endmode +# +# 640x480, 100 Hz, Non-Interlaced (43.163 MHz dotclock) +# +# Horizontal Vertical +# Resolution 640 480 +# Scan Frequency 50.900 kHz 100.00 Hz +# Sync Width 1.483 us 0.058 ms +# 8 chars 3 lines +# Front Porch 0.927 us 0.019 ms +# 5 chars 1 lines +# Back Porch 2.409 us 0.475 ms +# 13 chars 25 lines +# Active Time 14.827 us 9.430 ms +# 80 chars 480 lines +# Blank Time 4.819 us 0.570 ms +# 26 chars 29 lines +# Polarity positive positive +# + mode "640x480-100" +# D: 43.163 MHz, H: 50.900 kHz, V: 100.00 Hz + geometry 640 480 640 480 32 timings 23168 104 40 25 1 64 3 endmode +# +# 640x480, 120 Hz, Non-Interlaced (52.406 MHz dotclock) +# +# Horizontal Vertical +# Resolution 640 480 +# Scan Frequency 61.800 kHz 120.00 Hz +# Sync Width 1.221 us 0.048 ms +# 8 chars 3 lines +# Front Porch 0.763 us 0.016 ms +# 5 chars 1 lines +# Back Porch 1.984 us 0.496 ms +# 13 chars 31 lines +# Active Time 12.212 us 7.767 ms +# 80 chars 480 lines +# Blank Time 3.969 us 0.566 ms +# 26 chars 35 lines +# Polarity positive positive +# + mode "640x480-120" +# D: 52.406 MHz, H: 61.800 kHz, V: 120.00 Hz + geometry 640 480 640 480 32 timings 19081 104 40 31 1 64 3 endmode +# +# 720x480, 60 Hz, Non-Interlaced (26.880 MHz dotclock) +# +# Horizontal Vertical +# Resolution 720 480 +# Scan Frequency 30.000 kHz 60.241 Hz +# Sync Width 2.679 us 0.099 ms +# 9 chars 3 lines +# Front Porch 0.595 us 0.033 ms +# 2 chars 1 lines +# Back Porch 3.274 us 0.462 ms +# 11 chars 14 lines +# Active Time 26.786 us 16.000 ms +# 90 chars 480 lines +# Blank Time 6.548 us 0.600 ms +# 22 chars 18 lines +# Polarity positive positive +# + mode "720x480-60" +# D: 26.880 MHz, H: 30.000 kHz, V: 60.24 Hz + geometry 720 480 720 480 32 timings 37202 88 16 14 1 72 3 endmode +# +# 800x480, 60 Hz, Non-Interlaced (29.581 MHz dotclock) +# +# Horizontal Vertical +# Resolution 800 480 +# Scan Frequency 29.892 kHz 60.00 Hz +# Sync Width 2.704 us 100.604 us +# 10 chars 3 lines +# Front Porch 0.541 us 33.535 us +# 2 chars 1 lines +# Back Porch 3.245 us 435.949 us +# 12 chars 13 lines +# Active Time 27.044 us 16.097 ms +# 100 chars 480 lines +# Blank Time 6.491 us 0.570 ms +# 24 chars 17 lines +# Polarity positive positive +# + mode "800x480-60" +# D: 29.500 MHz, H: 29.738 kHz, V: 60.00 Hz + geometry 800 480 800 480 32 timings 33805 96 24 10 3 72 7 endmode +# +# 720x576, 60 Hz, Non-Interlaced (32.668 MHz dotclock) +# +# Horizontal Vertical +# Resolution 720 576 +# Scan Frequency 35.820 kHz 60.00 Hz +# Sync Width 2.204 us 0.083 ms +# 9 chars 3 lines +# Front Porch 0.735 us 0.027 ms +# 3 chars 1 lines +# Back Porch 2.939 us 0.459 ms +# 12 chars 17 lines +# Active Time 22.040 us 16.080 ms +# 90 chars 476 lines +# Blank Time 5.877 us 0.586 ms +# 24 chars 21 lines +# Polarity positive positive +# + mode "720x576-60" +# D: 32.668 MHz, H: 35.820 kHz, V: 60.00 Hz + geometry 720 576 720 576 32 timings 30611 96 24 17 1 72 3 endmode +# +# 800x600, 60 Hz, Non-Interlaced (40.00 MHz dotclock) +# +# Horizontal Vertical +# Resolution 800 600 +# Scan Frequency 37.879 kHz 60.32 Hz +# Sync Width 3.200 us 0.106 ms +# 16 chars 4 lines +# Front Porch 1.000 us 0.026 ms +# 5 chars 1 lines +# Back Porch 2.200 us 0.607 ms +# 11 chars 23 lines +# Active Time 20.000 us 15.840 ms +# 100 chars 600 lines +# Blank Time 6.400 us 0.739 ms +# 32 chars 28 lines +# Polarity positive positive +# + mode "800x600-60" +# D: 40.00 MHz, H: 37.879 kHz, V: 60.32 Hz + geometry 800 600 800 600 32 + timings 25000 88 40 23 1 128 4 hsync high vsync high endmode +# +# 800x600, 75 Hz, Non-Interlaced (49.50 MHz dotclock) +# +# Horizontal Vertical +# Resolution 800 600 +# Scan Frequency 46.875 kHz 75.00 Hz +# Sync Width 1.616 us 0.064 ms +# 10 chars 3 lines +# Front Porch 0.323 us 0.021 ms +# 2 chars 1 lines +# Back Porch 3.232 us 0.448 ms +# 20 chars 21 lines +# Active Time 16.162 us 12.800 ms +# 100 chars 600 lines +# Blank Time 5.172 us 0.533 ms +# 32 chars 25 lines +# Polarity positive positive +# + mode "800x600-75" +# D: 49.50 MHz, H: 46.875 kHz, V: 75.00 Hz + geometry 800 600 800 600 32 + timings 20203 160 16 21 1 80 3 hsync high vsync high endmode +# +# 800x600, 85 Hz, Non-Interlaced (56.25 MHz dotclock) +# +# Horizontal Vertical +# Resolution 800 600 +# Scan Frequency 53.674 kHz 85.061 Hz +# Sync Width 1.138 us 0.056 ms +# 8 chars 3 lines +# Front Porch 0.569 us 0.019 ms +# 4 chars 1 lines +# Back Porch 2.702 us 0.503 ms +# 19 chars 27 lines +# Active Time 14.222 us 11.179 ms +# 100 chars 600 lines +# Blank Time 4.409 us 0.578 ms +# 31 chars 31 lines +# Polarity positive positive +# + mode "800x600-85" +# D: 56.25 MHz, H: 53.674 kHz, V: 85.061 Hz + geometry 800 600 800 600 32 + timings 17777 152 32 27 1 64 3 hsync high vsync high endmode +# +# 800x600, 100 Hz, Non-Interlaced (67.50 MHz dotclock) +# +# Horizontal Vertical +# Resolution 800 600 +# Scan Frequency 62.500 kHz 100.00 Hz +# Sync Width 0.948 us 0.064 ms +# 8 chars 4 lines +# Front Porch 0.000 us 0.112 ms +# 0 chars 7 lines +# Back Porch 3.200 us 0.224 ms +# 27 chars 14 lines +# Active Time 11.852 us 9.600 ms +# 100 chars 600 lines +# Blank Time 4.148 us 0.400 ms +# 35 chars 25 lines +# Polarity positive positive +# + mode "800x600-100" +# D: 67.50 MHz, H: 62.500 kHz, V: 100.00 Hz + geometry 800 600 800 600 32 + timings 14667 216 0 14 7 64 4 hsync high vsync high endmode +# +# 800x600, 120 Hz, Non-Interlaced (83.950 MHz dotclock) +# +# Horizontal Vertical +# Resolution 800 600 +# Scan Frequency 77.160 kHz 120.00 Hz +# Sync Width 1.048 us 0.039 ms +# 11 chars 3 lines +# Front Porch 0.667 us 0.013 ms +# 7 chars 1 lines +# Back Porch 1.715 us 0.507 ms +# 18 chars 39 lines +# Active Time 9.529 us 7.776 ms +# 100 chars 600 lines +# Blank Time 3.431 us 0.557 ms +# 36 chars 43 lines +# Polarity positive positive +# + mode "800x600-120" +# D: 83.950 MHz, H: 77.160 kHz, V: 120.00 Hz + geometry 800 600 800 600 32 + timings 11912 144 56 39 1 88 3 hsync high vsync high endmode +# +# 848x480, 60 Hz, Non-Interlaced (31.490 MHz dotclock) +# +# Horizontal Vertical +# Resolution 848 480 +# Scan Frequency 29.820 kHz 60.00 Hz +# Sync Width 2.795 us 0.099 ms +# 11 chars 3 lines +# Front Porch 0.508 us 0.033 ms +# 2 chars 1 lines +# Back Porch 3.303 us 0.429 ms +# 13 chars 13 lines +# Active Time 26.929 us 16.097 ms +# 106 chars 480 lines +# Blank Time 6.605 us 0.570 ms +# 26 chars 17 lines +# Polarity positive positive +# + mode "848x480-60" +# D: 31.500 MHz, H: 29.830 kHz, V: 60.00 Hz + geometry 848 480 848 480 32 + timings 31746 104 24 12 3 80 5 hsync high vsync high endmode +# +# 856x480, 60 Hz, Non-Interlaced (31.728 MHz dotclock) +# +# Horizontal Vertical +# Resolution 856 480 +# Scan Frequency 29.820 kHz 60.00 Hz +# Sync Width 2.774 us 0.099 ms +# 11 chars 3 lines +# Front Porch 0.504 us 0.033 ms +# 2 chars 1 lines +# Back Porch 3.728 us 0.429 ms +# 13 chars 13 lines +# Active Time 26.979 us 16.097 ms +# 107 chars 480 lines +# Blank Time 6.556 us 0.570 ms +# 26 chars 17 lines +# Polarity positive positive +# + mode "856x480-60" +# D: 31.728 MHz, H: 29.820 kHz, V: 60.00 Hz + geometry 856 480 856 480 32 + timings 31518 104 16 13 1 88 3 + hsync high vsync high endmode mode "960x600-60" +# D: 45.250 MHz, H: 37.212 kHz, V: 60.00 Hz + geometry 960 600 960 600 32 timings 22099 128 32 15 3 96 6 endmode +# +# 1000x600, 60 Hz, Non-Interlaced (48.068 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1000 600 +# Scan Frequency 37.320 kHz 60.00 Hz +# Sync Width 2.164 us 0.080 ms +# 13 chars 3 lines +# Front Porch 0.832 us 0.027 ms +# 5 chars 1 lines +# Back Porch 2.996 us 0.483 ms +# 18 chars 18 lines +# Active Time 20.804 us 16.077 ms +# 125 chars 600 lines +# Blank Time 5.991 us 0.589 ms +# 36 chars 22 lines +# Polarity negative positive +# + mode "1000x600-60" +# D: 48.068 MHz, H: 37.320 kHz, V: 60.00 Hz + geometry 1000 600 1000 600 32 + timings 20834 144 40 18 1 104 3 endmode mode "1024x576-60" +# D: 46.996 MHz, H: 35.820 kHz, V: 60.00 Hz + geometry 1024 576 1024 576 32 + timings 21278 144 40 17 1 104 3 endmode mode "1024x600-60" +# D: 48.964 MHz, H: 37.320 kHz, V: 60.00 Hz + geometry 1024 600 1024 600 32 + timings 20461 144 40 18 1 104 3 endmode mode "1088x612-60" +# D: 52.952 MHz, H: 38.040 kHz, V: 60.00 Hz + geometry 1088 612 1088 612 32 timings 18877 152 48 16 3 104 5 endmode +# +# 1024x512, 60 Hz, Non-Interlaced (41.291 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1024 512 +# Scan Frequency 31.860 kHz 60.00 Hz +# Sync Width 2.519 us 0.094 ms +# 13 chars 3 lines +# Front Porch 0.775 us 0.031 ms +# 4 chars 1 lines +# Back Porch 3.294 us 0.465 ms +# 17 chars 15 lines +# Active Time 24.800 us 16.070 ms +# 128 chars 512 lines +# Blank Time 6.587 us 0.596 ms +# 34 chars 19 lines +# Polarity positive positive +# + mode "1024x512-60" +# D: 41.291 MHz, H: 31.860 kHz, V: 60.00 Hz + geometry 1024 512 1024 512 32 + timings 24218 126 32 15 1 104 3 hsync high vsync high endmode +# +# 1024x600, 60 Hz, Non-Interlaced (48.875 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1024 768 +# Scan Frequency 37.252 kHz 60.00 Hz +# Sync Width 2.128 us 80.532us +# 13 chars 3 lines +# Front Porch 0.818 us 26.844 us +# 5 chars 1 lines +# Back Porch 2.946 us 483.192 us +# 18 chars 18 lines +# Active Time 20.951 us 16.697 ms +# 128 chars 622 lines +# Blank Time 5.893 us 0.591 ms +# 36 chars 22 lines +# Polarity negative positive +# +#mode "1024x600-60" +# # D: 48.875 MHz, H: 37.252 kHz, V: 60.00 Hz +# geometry 1024 600 1024 600 32 +# timings 20460 144 40 18 1 104 3 +# endmode +# +# 1024x768, 60 Hz, Non-Interlaced (65.00 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1024 768 +# Scan Frequency 48.363 kHz 60.00 Hz +# Sync Width 2.092 us 0.124 ms +# 17 chars 6 lines +# Front Porch 0.369 us 0.062 ms +# 3 chars 3 lines +# Back Porch 2.462 us 0.601 ms +# 20 chars 29 lines +# Active Time 15.754 us 15.880 ms +# 128 chars 768 lines +# Blank Time 4.923 us 0.786 ms +# 40 chars 38 lines +# Polarity negative negative +# + mode "1024x768-60" +# D: 65.00 MHz, H: 48.363 kHz, V: 60.00 Hz + geometry 1024 768 1024 768 32 timings 15385 160 24 29 3 136 6 endmode +# +# 1024x768, 75 Hz, Non-Interlaced (78.75 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1024 768 +# Scan Frequency 60.023 kHz 75.03 Hz +# Sync Width 1.219 us 0.050 ms +# 12 chars 3 lines +# Front Porch 0.203 us 0.017 ms +# 2 chars 1 lines +# Back Porch 2.235 us 0.466 ms +# 22 chars 28 lines +# Active Time 13.003 us 12.795 ms +# 128 chars 768 lines +# Blank Time 3.657 us 0.533 ms +# 36 chars 32 lines +# Polarity positive positive +# + mode "1024x768-75" +# D: 78.75 MHz, H: 60.023 kHz, V: 75.03 Hz + geometry 1024 768 1024 768 32 + timings 12699 176 16 28 1 96 3 hsync high vsync high endmode +# +# 1024x768, 85 Hz, Non-Interlaced (94.50 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1024 768 +# Scan Frequency 68.677 kHz 85.00 Hz +# Sync Width 1.016 us 0.044 ms +# 12 chars 3 lines +# Front Porch 0.508 us 0.015 ms +# 6 chars 1 lines +# Back Porch 2.201 us 0.524 ms +# 26 chars 36 lines +# Active Time 10.836 us 11.183 ms +# 128 chars 768 lines +# Blank Time 3.725 us 0.582 ms +# 44 chars 40 lines +# Polarity positive positive +# + mode "1024x768-85" +# D: 94.50 MHz, H: 68.677 kHz, V: 85.00 Hz + geometry 1024 768 1024 768 32 + timings 10582 208 48 36 1 96 3 hsync high vsync high endmode +# +# 1024x768, 100 Hz, Non-Interlaced (110.0 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1024 768 +# Scan Frequency 79.023 kHz 99.78 Hz +# Sync Width 0.800 us 0.101 ms +# 11 chars 8 lines +# Front Porch 0.000 us 0.000 ms +# 0 chars 0 lines +# Back Porch 2.545 us 0.202 ms +# 35 chars 16 lines +# Active Time 9.309 us 9.719 ms +# 128 chars 768 lines +# Blank Time 3.345 us 0.304 ms +# 46 chars 24 lines +# Polarity negative negative +# + mode "1024x768-100" +# D: 113.3 MHz, H: 79.023 kHz, V: 99.78 Hz + geometry 1024 768 1024 768 32 + timings 8825 280 0 16 0 88 8 endmode mode "1152x720-60" +# D: 66.750 MHz, H: 44.859 kHz, V: 60.00 Hz + geometry 1152 720 1152 720 32 timings 14981 168 56 19 3 112 6 endmode +# +# 1152x864, 75 Hz, Non-Interlaced (110.0 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1152 864 +# Scan Frequency 75.137 kHz 74.99 Hz +# Sync Width 1.309 us 0.106 ms +# 18 chars 8 lines +# Front Porch 0.245 us 0.599 ms +# 3 chars 45 lines +# Back Porch 1.282 us 1.132 ms +# 18 chars 85 lines +# Active Time 10.473 us 11.499 ms +# 144 chars 864 lines +# Blank Time 2.836 us 1.837 ms +# 39 chars 138 lines +# Polarity positive positive +# + mode "1152x864-75" +# D: 110.0 MHz, H: 75.137 kHz, V: 74.99 Hz + geometry 1152 864 1152 864 32 + timings 9259 144 24 85 45 144 8 + hsync high vsync high endmode mode "1200x720-60" +# D: 70.184 MHz, H: 44.760 kHz, V: 60.00 Hz + geometry 1200 720 1200 720 32 + timings 14253 184 28 22 1 128 3 endmode mode "1280x600-60" +# D: 61.503 MHz, H: 37.320 kHz, V: 60.00 Hz + geometry 1280 600 1280 600 32 + timings 16260 184 28 18 1 128 3 endmode mode "1280x720-50" +# D: 60.466 MHz, H: 37.050 kHz, V: 50.00 Hz + geometry 1280 720 1280 720 32 + timings 16538 176 48 17 1 128 3 endmode mode "1280x768-50" +# D: 65.178 MHz, H: 39.550 kHz, V: 50.00 Hz + geometry 1280 768 1280 768 32 timings 15342 184 28 19 1 128 3 endmode +# +# 1280x768, 60 Hz, Non-Interlaced (80.136 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1280 768 +# Scan Frequency 47.700 kHz 60.00 Hz +# Sync Width 1.697 us 0.063 ms +# 17 chars 3 lines +# Front Porch 0.799 us 0.021 ms +# 8 chars 1 lines +# Back Porch 2.496 us 0.483 ms +# 25 chars 23 lines +# Active Time 15.973 us 16.101 ms +# 160 chars 768 lines +# Blank Time 4.992 us 0.566 ms +# 50 chars 27 lines +# Polarity positive positive +# + mode "1280x768-60" +# D: 80.13 MHz, H: 47.700 kHz, V: 60.00 Hz + geometry 1280 768 1280 768 32 + timings 12480 200 48 23 1 126 3 hsync high vsync high endmode +# +# 1280x800, 60 Hz, Non-Interlaced (83.375 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1280 800 +# Scan Frequency 49.628 kHz 60.00 Hz +# Sync Width 1.631 us 60.450 us +# 17 chars 3 lines +# Front Porch 0.768 us 20.15 us +# 8 chars 1 lines +# Back Porch 2.399 us 0.483 ms +# 25 chars 24 lines +# Active Time 15.352 us 16.120 ms +# 160 chars 800 lines +# Blank Time 4.798 us 0.564 ms +# 50 chars 28 lines +# Polarity negtive positive +# + mode "1280x800-60" +# D: 83.500 MHz, H: 49.702 kHz, V: 60.00 Hz + geometry 1280 800 1280 800 32 timings 11994 200 72 22 3 128 6 endmode +# +# 1280x960, 60 Hz, Non-Interlaced (108.00 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1280 960 +# Scan Frequency 60.000 kHz 60.00 Hz +# Sync Width 1.037 us 0.050 ms +# 14 chars 3 lines +# Front Porch 0.889 us 0.017 ms +# 12 chars 1 lines +# Back Porch 2.889 us 0.600 ms +# 39 chars 36 lines +# Active Time 11.852 us 16.000 ms +# 160 chars 960 lines +# Blank Time 4.815 us 0.667 ms +# 65 chars 40 lines +# Polarity positive positive +# + mode "1280x960-60" +# D: 108.00 MHz, H: 60.000 kHz, V: 60.00 Hz + geometry 1280 960 1280 960 32 + timings 9259 312 96 36 1 112 3 hsync high vsync high endmode +# +# 1280x1024, 60 Hz, Non-Interlaced (108.00 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1280 1024 +# Scan Frequency 63.981 kHz 60.02 Hz +# Sync Width 1.037 us 0.047 ms +# 14 chars 3 lines +# Front Porch 0.444 us 0.015 ms +# 6 chars 1 lines +# Back Porch 2.297 us 0.594 ms +# 31 chars 38 lines +# Active Time 11.852 us 16.005 ms +# 160 chars 1024 lines +# Blank Time 3.778 us 0.656 ms +# 51 chars 42 lines +# Polarity positive positive +# + mode "1280x1024-60" +# D: 108.00 MHz, H: 63.981 kHz, V: 60.02 Hz + geometry 1280 1024 1280 1024 32 + timings 9260 248 48 38 1 112 3 hsync high vsync high endmode +# +# 1280x1024, 75 Hz, Non-Interlaced (135.00 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1280 1024 +# Scan Frequency 79.976 kHz 75.02 Hz +# Sync Width 1.067 us 0.038 ms +# 18 chars 3 lines +# Front Porch 0.119 us 0.012 ms +# 2 chars 1 lines +# Back Porch 1.837 us 0.475 ms +# 31 chars 38 lines +# Active Time 9.481 us 12.804 ms +# 160 chars 1024 lines +# Blank Time 3.022 us 0.525 ms +# 51 chars 42 lines +# Polarity positive positive +# + mode "1280x1024-75" +# D: 135.00 MHz, H: 79.976 kHz, V: 75.02 Hz + geometry 1280 1024 1280 1024 32 + timings 7408 248 16 38 1 144 3 hsync high vsync high endmode +# +# 1280x1024, 85 Hz, Non-Interlaced (157.50 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1280 1024 +# Scan Frequency 91.146 kHz 85.02 Hz +# Sync Width 1.016 us 0.033 ms +# 20 chars 3 lines +# Front Porch 0.406 us 0.011 ms +# 8 chars 1 lines +# Back Porch 1.422 us 0.483 ms +# 28 chars 44 lines +# Active Time 8.127 us 11.235 ms +# 160 chars 1024 lines +# Blank Time 2.844 us 0.527 ms +# 56 chars 48 lines +# Polarity positive positive +# + mode "1280x1024-85" +# D: 157.50 MHz, H: 91.146 kHz, V: 85.02 Hz + geometry 1280 1024 1280 1024 32 + timings 6349 224 64 44 1 160 3 + hsync high vsync high endmode mode "1440x900-60" +# D: 106.500 MHz, H: 55.935 kHz, V: 60.00 Hz + geometry 1440 900 1440 900 32 + timings 9390 232 80 25 3 152 6 + hsync high vsync high endmode mode "1440x900-75" +# D: 136.750 MHz, H: 70.635 kHz, V: 75.00 Hz + geometry 1440 900 1440 900 32 + timings 7315 248 96 33 3 152 6 hsync high vsync high endmode +# +# 1440x1050, 60 Hz, Non-Interlaced (125.10 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1440 1050 +# Scan Frequency 65.220 kHz 60.00 Hz +# Sync Width 1.204 us 0.046 ms +# 19 chars 3 lines +# Front Porch 0.760 us 0.015 ms +# 12 chars 1 lines +# Back Porch 1.964 us 0.495 ms +# 31 chars 33 lines +# Active Time 11.405 us 16.099 ms +# 180 chars 1050 lines +# Blank Time 3.928 us 0.567 ms +# 62 chars 37 lines +# Polarity positive positive +# + mode "1440x1050-60" +# D: 125.10 MHz, H: 65.220 kHz, V: 60.00 Hz + geometry 1440 1050 1440 1050 32 + timings 7993 248 96 33 1 152 3 + hsync high vsync high endmode mode "1600x900-60" +# D: 118.250 MHz, H: 55.990 kHz, V: 60.00 Hz + geometry 1600 900 1600 900 32 + timings 8415 256 88 26 3 168 5 endmode mode "1600x1024-60" +# D: 136.358 MHz, H: 63.600 kHz, V: 60.00 Hz + geometry 1600 1024 1600 1024 32 timings 7315 272 104 32 1 168 3 endmode +# +# 1600x1200, 60 Hz, Non-Interlaced (156.00 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1600 1200 +# Scan Frequency 76.200 kHz 60.00 Hz +# Sync Width 1.026 us 0.105 ms +# 20 chars 8 lines +# Front Porch 0.205 us 0.131 ms +# 4 chars 10 lines +# Back Porch 1.636 us 0.682 ms +# 32 chars 52 lines +# Active Time 10.256 us 15.748 ms +# 200 chars 1200 lines +# Blank Time 2.872 us 0.866 ms +# 56 chars 66 lines +# Polarity negative negative +# + mode "1600x1200-60" +# D: 156.00 MHz, H: 76.200 kHz, V: 60.00 Hz + geometry 1600 1200 1600 1200 32 timings 6172 256 32 52 10 160 8 endmode +# +# 1600x1200, 75 Hz, Non-Interlaced (202.50 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1600 1200 +# Scan Frequency 93.750 kHz 75.00 Hz +# Sync Width 0.948 us 0.032 ms +# 24 chars 3 lines +# Front Porch 0.316 us 0.011 ms +# 8 chars 1 lines +# Back Porch 1.501 us 0.491 ms +# 38 chars 46 lines +# Active Time 7.901 us 12.800 ms +# 200 chars 1200 lines +# Blank Time 2.765 us 0.533 ms +# 70 chars 50 lines +# Polarity positive positive +# + mode "1600x1200-75" +# D: 202.50 MHz, H: 93.750 kHz, V: 75.00 Hz + geometry 1600 1200 1600 1200 32 + timings 4938 304 64 46 1 192 3 + hsync high vsync high endmode mode "1680x1050-60" +# D: 146.250 MHz, H: 65.290 kHz, V: 59.954 Hz + geometry 1680 1050 1680 1050 32 + timings 6814 280 104 30 3 176 6 + hsync high vsync high endmode mode "1680x1050-75" +# D: 187.000 MHz, H: 82.306 kHz, V: 74.892 Hz + geometry 1680 1050 1680 1050 32 + timings 5348 296 120 40 3 176 6 + hsync high vsync high endmode mode "1792x1344-60" +# D: 202.975 MHz, H: 83.460 kHz, V: 60.00 Hz + geometry 1792 1344 1792 1344 32 + timings 4902 320 128 43 1 192 3 + hsync high vsync high endmode mode "1856x1392-60" +# D: 218.571 MHz, H: 86.460 kHz, V: 60.00 Hz + geometry 1856 1392 1856 1392 32 + timings 4577 336 136 45 1 200 3 + hsync high vsync high endmode mode "1920x1200-60" +# D: 193.250 MHz, H: 74.556 kHz, V: 60.00 Hz + geometry 1920 1200 1920 1200 32 + timings 5173 336 136 36 3 200 6 + hsync high vsync high endmode mode "1920x1440-60" +# D: 234.000 MHz, H:90.000 kHz, V: 60.00 Hz + geometry 1920 1440 1920 1440 32 + timings 4274 344 128 56 1 208 3 + hsync high vsync high endmode mode "1920x1440-75" +# D: 297.000 MHz, H:112.500 kHz, V: 75.00 Hz + geometry 1920 1440 1920 1440 32 + timings 3367 352 144 56 1 224 3 + hsync high vsync high endmode mode "2048x1536-60" +# D: 267.250 MHz, H: 95.446 kHz, V: 60.00 Hz + geometry 2048 1536 2048 1536 32 + timings 3742 376 152 49 3 224 4 hsync high vsync high endmode +# +# 1280x720, 60 Hz, Non-Interlaced (74.481 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1280 720 +# Scan Frequency 44.760 kHz 60.00 Hz +# Sync Width 1.826 us 67.024 ms +# 17 chars 3 lines +# Front Porch 0.752 us 22.341 ms +# 7 chars 1 lines +# Back Porch 2.578 us 491.510 ms +# 24 chars 22 lines +# Active Time 17.186 us 16.086 ms +# 160 chars 720 lines +# Blank Time 5.156 us 0.581 ms +# 48 chars 26 lines +# Polarity negative negative +# + mode "1280x720-60" +# D: 74.481 MHz, H: 44.760 kHz, V: 60.00 Hz + geometry 1280 720 1280 720 32 timings 13426 192 64 22 1 136 3 endmode +# +# 1920x1080, 60 Hz, Non-Interlaced (172.798 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1920 1080 +# Scan Frequency 67.080 kHz 60.00 Hz +# Sync Width 1.204 us 44.723 ms +# 26 chars 3 lines +# Front Porch 0.694 us 14.908 ms +# 15 chars 1 lines +# Back Porch 1.898 us 506.857 ms +# 41 chars 34 lines +# Active Time 11.111 us 16.100 ms +# 240 chars 1080 lines +# Blank Time 3.796 us 0.566 ms +# 82 chars 38 lines +# Polarity negative negative +# + mode "1920x1080-60" +# D: 74.481 MHz, H: 67.080 kHz, V: 60.00 Hz + geometry 1920 1080 1920 1080 32 timings 5787 328 120 34 1 208 3 endmode +# +# 1400x1050, 60 Hz, Non-Interlaced (122.61 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1400 1050 +# Scan Frequency 65.218 kHz 59.99 Hz +# Sync Width 1.037 us 0.047 ms +# 19 chars 3 lines +# Front Porch 0.444 us 0.015 ms +# 11 chars 1 lines +# Back Porch 1.185 us 0.188 ms +# 30 chars 33 lines +# Active Time 12.963 us 16.411 ms +# 175 chars 1050 lines +# Blank Time 2.667 us 0.250 ms +# 60 chars 37 lines +# Polarity negative positive +# + mode "1400x1050-60" +# D: 122.750 MHz, H: 65.317 kHz, V: 59.99 Hz + geometry 1400 1050 1408 1050 32 + timings 8214 232 88 32 3 144 4 endmode mode "1400x1050-75" +# D: 156.000 MHz, H: 82.278 kHz, V: 74.867 Hz + geometry 1400 1050 1408 1050 32 timings 6410 248 104 42 3 144 4 endmode +# +# 1366x768, 60 Hz, Non-Interlaced (85.86 MHz dotclock) +# +# Horizontal Vertical +# Resolution 1366 768 +# Scan Frequency 47.700 kHz 60.00 Hz +# Sync Width 1.677 us 0.063 ms +# 18 chars 3 lines +# Front Porch 0.839 us 0.021 ms +# 9 chars 1 lines +# Back Porch 2.516 us 0.482 ms +# 27 chars 23 lines +# Active Time 15.933 us 16.101 ms +# 171 chars 768 lines +# Blank Time 5.031 us 0.566 ms +# 54 chars 27 lines +# Polarity negative positive +# + mode "1360x768-60" +# D: 84.750 MHz, H: 47.720 kHz, V: 60.00 Hz + geometry 1360 768 1360 768 32 + timings 11799 208 72 22 3 136 5 endmode mode "1366x768-60" +# D: 85.86 MHz, H: 47.700 kHz, V: 60.00 Hz + geometry 1366 768 1366 768 32 + timings 11647 216 72 23 1 144 3 endmode mode "1366x768-50" +# D: 69,924 MHz, H: 39.550 kHz, V: 50.00 Hz + geometry 1366 768 1366 768 32 timings 14301 200 56 19 1 144 3 endmode diff --git a/Documentation/fb/viafb.txt b/Documentation/fb/viafb.txt new file mode 100644 index 00000000000..67dbf442b0b --- /dev/null +++ b/Documentation/fb/viafb.txt @@ -0,0 +1,214 @@ + + VIA Integration Graphic Chip Console Framebuffer Driver + +[Platform] +----------------------- + The console framebuffer driver is for graphics chips of + VIA UniChrome Family(CLE266, PM800 / CN400 / CN300, + P4M800CE / P4M800Pro / CN700 / VN800, + CX700 / VX700, K8M890, P4M890, + CN896 / P4M900, VX800) + +[Driver features] +------------------------ + Device: CRT, LCD, DVI + + Support viafb_mode: + CRT: + 640x480(60, 75, 85, 100, 120 Hz), 720x480(60 Hz), + 720x576(60 Hz), 800x600(60, 75, 85, 100, 120 Hz), + 848x480(60 Hz), 856x480(60 Hz), 1024x512(60 Hz), + 1024x768(60, 75, 85, 100 Hz), 1152x864(75 Hz), + 1280x768(60 Hz), 1280x960(60 Hz), 1280x1024(60, 75, 85 Hz), + 1440x1050(60 Hz), 1600x1200(60, 75 Hz), 1280x720(60 Hz), + 1920x1080(60 Hz), 1400x1050(60 Hz), 800x480(60 Hz) + + color depth: 8 bpp, 16 bpp, 32 bpp supports. + + Support 2D hardware accelerator. + +[Using the viafb module] +-- -- -------------------- + Start viafb with default settings: + #modprobe viafb + + Start viafb with with user options: + #modprobe viafb viafb_mode=800x600 viafb_bpp=16 viafb_refresh=60 + viafb_active_dev=CRT+DVI viafb_dvi_port=DVP1 + viafb_mode1=1024x768 viafb_bpp=16 viafb_refresh1=60 + viafb_SAMM_ON=1 + + viafb_mode: + 640x480 (default) + 720x480 + 800x600 + 1024x768 + ...... + + viafb_bpp: + 8, 16, 32 (default:32) + + viafb_refresh: + 60, 75, 85, 100, 120 (default:60) + + viafb_lcd_dsp_method: + 0 : expansion (default) + 1 : centering + + viafb_lcd_mode: + 0 : LCD panel with LSB data format input (default) + 1 : LCD panel with MSB data format input + + viafb_lcd_panel_id: + 0 : Resolution: 640x480, Channel: single, Dithering: Enable + 1 : Resolution: 800x600, Channel: single, Dithering: Enable + 2 : Resolution: 1024x768, Channel: single, Dithering: Enable (default) + 3 : Resolution: 1280x768, Channel: single, Dithering: Enable + 4 : Resolution: 1280x1024, Channel: dual, Dithering: Enable + 5 : Resolution: 1400x1050, Channel: dual, Dithering: Enable + 6 : Resolution: 1600x1200, Channel: dual, Dithering: Enable + + 8 : Resolution: 800x480, Channel: single, Dithering: Enable + 9 : Resolution: 1024x768, Channel: dual, Dithering: Enable + 10: Resolution: 1024x768, Channel: single, Dithering: Disable + 11: Resolution: 1024x768, Channel: dual, Dithering: Disable + 12: Resolution: 1280x768, Channel: single, Dithering: Disable + 13: Resolution: 1280x1024, Channel: dual, Dithering: Disable + 14: Resolution: 1400x1050, Channel: dual, Dithering: Disable + 15: Resolution: 1600x1200, Channel: dual, Dithering: Disable + 16: Resolution: 1366x768, Channel: single, Dithering: Disable + 17: Resolution: 1024x600, Channel: single, Dithering: Enable + 18: Resolution: 1280x768, Channel: dual, Dithering: Enable + 19: Resolution: 1280x800, Channel: single, Dithering: Enable + + viafb_accel: + 0 : No 2D Hardware Acceleration + 1 : 2D Hardware Acceleration (default) + + viafb_SAMM_ON: + 0 : viafb_SAMM_ON disable (default) + 1 : viafb_SAMM_ON enable + + viafb_mode1: (secondary display device) + 640x480 (default) + 720x480 + 800x600 + 1024x768 + ... ... + + viafb_bpp1: (secondary display device) + 8, 16, 32 (default:32) + + viafb_refresh1: (secondary display device) + 60, 75, 85, 100, 120 (default:60) + + viafb_active_dev: + This option is used to specify active devices.(CRT, DVI, CRT+LCD...) + DVI stands for DVI or HDMI, E.g., If you want to enable HDMI, + set viafb_active_dev=DVI. In SAMM case, the previous of + viafb_active_dev is primary device, and the following is + secondary device. + + For example: + To enable one device, such as DVI only, we can use: + modprobe viafb viafb_active_dev=DVI + To enable two devices, such as CRT+DVI: + modprobe viafb viafb_active_dev=CRT+DVI; + + For DuoView case, we can use: + modprobe viafb viafb_active_dev=CRT+DVI + OR + modprobe viafb viafb_active_dev=DVI+CRT... + + For SAMM case: + If CRT is primary and DVI is secondary, we should use: + modprobe viafb viafb_active_dev=CRT+DVI viafb_SAMM_ON=1... + If DVI is primary and CRT is secondary, we should use: + modprobe viafb viafb_active_dev=DVI+CRT viafb_SAMM_ON=1... + + viafb_display_hardware_layout: + This option is used to specify display hardware layout for CX700 chip. + 1 : LCD only + 2 : DVI only + 3 : LCD+DVI (default) + 4 : LCD1+LCD2 (internal + internal) + 16: LCD1+ExternalLCD2 (internal + external) + + viafb_second_size: + This option is used to set second device memory size(MB) in SAMM case. + The minimal size is 16. + + viafb_platform_epia_dvi: + This option is used to enable DVI on EPIA - M + 0 : No DVI on EPIA - M (default) + 1 : DVI on EPIA - M + + viafb_bus_width: + When using 24 - Bit Bus Width Digital Interface, + this option should be set. + 12: 12-Bit LVDS or 12-Bit TMDS (default) + 24: 24-Bit LVDS or 24-Bit TMDS + + viafb_device_lcd_dualedge: + When using Dual Edge Panel, this option should be set. + 0 : No Dual Edge Panel (default) + 1 : Dual Edge Panel + + viafb_video_dev: + This option is used to specify video output devices(CRT, DVI, LCD) for + duoview case. + For example: + To output video on DVI, we should use: + modprobe viafb viafb_video_dev=DVI... + + viafb_lcd_port: + This option is used to specify LCD output port, + available values are "DVP0" "DVP1" "DFP_HIGHLOW" "DFP_HIGH" "DFP_LOW". + for external LCD + external DVI on CX700(External LCD is on DVP0), + we should use: + modprobe viafb viafb_lcd_port=DVP0... + +Notes: + 1. CRT may not display properly for DuoView CRT & DVI display at + the "640x480" PAL mode with DVI overscan enabled. + 2. SAMM stands for single adapter multi monitors. It is different from + multi-head since SAMM support multi monitor at driver layers, thus fbcon + layer doesn't even know about it; SAMM's second screen doesn't have a + device node file, thus a user mode application can't access it directly. + When SAMM is enabled, viafb_mode and viafb_mode1, viafb_bpp and + viafb_bpp1, viafb_refresh and viafb_refresh1 can be different. + 3. When console is depending on viafbinfo1, dynamically change resolution + and bpp, need to call VIAFB specified ioctl interface VIAFB_SET_DEVICE + instead of calling common ioctl function FBIOPUT_VSCREENINFO since + viafb doesn't support multi-head well, or it will cause screen crush. + 4. VX800 2D accelerator hasn't been supported in this driver yet. When + using driver on VX800, the driver will disable the acceleration + function as default. + + +[Configure viafb with "fbset" tool] +----------------------------------- + "fbset" is an inbox utility of Linux. + 1. Inquire current viafb information, type, + # fbset -i + + 2. Set various resolutions and viafb_refresh rates, + # fbset <resolution-vertical_sync> + + example, + # fbset "1024x768-75" + or + # fbset -g 1024 768 1024 768 32 + Check the file "/etc/fb.modes" to find display modes available. + + 3. Set the color depth, + # fbset -depth <value> + + example, + # fbset -depth 16 + +[Bootup with viafb]: +-------------------- + Add the following line to your grub.conf: + append = "video=viafb:viafb_mode=1024x768,viafb_bpp=32,viafb_refresh=85" + diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 4d2566a7d16..dc7c681e532 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -56,30 +56,6 @@ Who: Mauro Carvalho Chehab <mchehab@infradead.org> --------------------------- -What: old tuner-3036 i2c driver -When: 2.6.28 -Why: This driver is for VERY old i2c-over-parallel port teletext receiver - boxes. Rather then spending effort on converting this driver to V4L2, - and since it is extremely unlikely that anyone still uses one of these - devices, it was decided to drop it. -Who: Hans Verkuil <hverkuil@xs4all.nl> - Mauro Carvalho Chehab <mchehab@infradead.org> - - --------------------------- - -What: V4L2 dpc7146 driver -When: 2.6.28 -Why: Old driver for the dpc7146 demonstration board that is no longer - relevant. The last time this was tested on actual hardware was - probably around 2002. Since this is a driver for a demonstration - board the decision was made to remove it rather than spending a - lot of effort continually updating this driver to stay in sync - with the latest internal V4L2 or I2C API. -Who: Hans Verkuil <hverkuil@xs4all.nl> - Mauro Carvalho Chehab <mchehab@infradead.org> - ---------------------------- - What: PCMCIA control ioctl (needed for pcmcia-cs [cardmgr, cardctl]) When: November 2005 Files: drivers/pcmcia/: pcmcia_ioctl.c @@ -144,13 +120,6 @@ Who: Christoph Hellwig <hch@lst.de> --------------------------- -What: eepro100 network driver -When: January 2007 -Why: replaced by the e100 driver -Who: Adrian Bunk <bunk@stusta.de> - ---------------------------- - What: Unused EXPORT_SYMBOL/EXPORT_SYMBOL_GPL exports (temporary transition config option provided until then) The transition config option will also be removed at the same time. @@ -268,18 +237,6 @@ Who: Michael Buesch <mb@bu3sch.de> --------------------------- -What: init_mm export -When: 2.6.26 -Why: Not used in-tree. The current out-of-tree users used it to - work around problems in the CPA code which should be resolved - by now. One usecase was described to provide verification code - of the CPA operation. That's a good idea in general, but such - code / infrastructure should be in the kernel and not in some - out-of-tree driver. -Who: Thomas Gleixner <tglx@linutronix.de> - ----------------------------- - What: usedac i386 kernel parameter When: 2.6.27 Why: replaced by allowdac and no dac combination @@ -294,6 +251,15 @@ Who: Jiri Slaby <jirislaby@gmail.com> --------------------------- +What: print_fn_descriptor_symbol() +When: October 2009 +Why: The %pF vsprintf format provides the same functionality in a + simpler way. print_fn_descriptor_symbol() is deprecated but + still present to give out-of-tree modules time to change. +Who: Bjorn Helgaas <bjorn.helgaas@hp.com> + +--------------------------- + What: /sys/o2cb symlink When: January 2010 Why: /sys/fs/o2cb is the proper location for this information - /sys/o2cb @@ -350,3 +316,11 @@ Why: The 2.6 kernel supports direct writing to ide CD drives, which eliminates the need for ide-scsi. The new method is more efficient in every way. Who: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp> + +--------------------------- + +What: i2c_attach_client(), i2c_detach_client(), i2c_driver->detach_client() +When: 2.6.29 (ideally) or 2.6.30 (more likely) +Why: Deprecated by the new (standard) device driver binding model. Use + i2c_driver->probe() and ->remove() instead. +Who: Jean Delvare <khali@linux-fr.org> diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index 8362860e21a..23d2f4460de 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -161,8 +161,12 @@ prototypes: int (*set_page_dirty)(struct page *page); int (*readpages)(struct file *filp, struct address_space *mapping, struct list_head *pages, unsigned nr_pages); - int (*prepare_write)(struct file *, struct page *, unsigned, unsigned); - int (*commit_write)(struct file *, struct page *, unsigned, unsigned); + int (*write_begin)(struct file *, struct address_space *mapping, + loff_t pos, unsigned len, unsigned flags, + struct page **pagep, void **fsdata); + int (*write_end)(struct file *, struct address_space *mapping, + loff_t pos, unsigned len, unsigned copied, + struct page *page, void *fsdata); sector_t (*bmap)(struct address_space *, sector_t); int (*invalidatepage) (struct page *, unsigned long); int (*releasepage) (struct page *, int); @@ -180,8 +184,6 @@ sync_page: no maybe writepages: no set_page_dirty no no readpages: no -prepare_write: no yes yes -commit_write: no yes yes write_begin: no locks the page yes write_end: no yes, unlocks yes perform_write: no n/a yes @@ -191,7 +193,7 @@ releasepage: no yes direct_IO: no launder_page: no yes - ->prepare_write(), ->commit_write(), ->sync_page() and ->readpage() + ->write_begin(), ->write_end(), ->sync_page() and ->readpage() may be called from the request handler (/dev/loop). ->readpage() unlocks the page, either synchronously or via I/O diff --git a/Documentation/filesystems/autofs4-mount-control.txt b/Documentation/filesystems/autofs4-mount-control.txt new file mode 100644 index 00000000000..c6341745df3 --- /dev/null +++ b/Documentation/filesystems/autofs4-mount-control.txt @@ -0,0 +1,393 @@ + +Miscellaneous Device control operations for the autofs4 kernel module +==================================================================== + +The problem +=========== + +There is a problem with active restarts in autofs (that is to say +restarting autofs when there are busy mounts). + +During normal operation autofs uses a file descriptor opened on the +directory that is being managed in order to be able to issue control +operations. Using a file descriptor gives ioctl operations access to +autofs specific information stored in the super block. The operations +are things such as setting an autofs mount catatonic, setting the +expire timeout and requesting expire checks. As is explained below, +certain types of autofs triggered mounts can end up covering an autofs +mount itself which prevents us being able to use open(2) to obtain a +file descriptor for these operations if we don't already have one open. + +Currently autofs uses "umount -l" (lazy umount) to clear active mounts +at restart. While using lazy umount works for most cases, anything that +needs to walk back up the mount tree to construct a path, such as +getcwd(2) and the proc file system /proc/<pid>/cwd, no longer works +because the point from which the path is constructed has been detached +from the mount tree. + +The actual problem with autofs is that it can't reconnect to existing +mounts. Immediately one thinks of just adding the ability to remount +autofs file systems would solve it, but alas, that can't work. This is +because autofs direct mounts and the implementation of "on demand mount +and expire" of nested mount trees have the file system mounted directly +on top of the mount trigger directory dentry. + +For example, there are two types of automount maps, direct (in the kernel +module source you will see a third type called an offset, which is just +a direct mount in disguise) and indirect. + +Here is a master map with direct and indirect map entries: + +/- /etc/auto.direct +/test /etc/auto.indirect + +and the corresponding map files: + +/etc/auto.direct: + +/automount/dparse/g6 budgie:/autofs/export1 +/automount/dparse/g1 shark:/autofs/export1 +and so on. + +/etc/auto.indirect: + +g1 shark:/autofs/export1 +g6 budgie:/autofs/export1 +and so on. + +For the above indirect map an autofs file system is mounted on /test and +mounts are triggered for each sub-directory key by the inode lookup +operation. So we see a mount of shark:/autofs/export1 on /test/g1, for +example. + +The way that direct mounts are handled is by making an autofs mount on +each full path, such as /automount/dparse/g1, and using it as a mount +trigger. So when we walk on the path we mount shark:/autofs/export1 "on +top of this mount point". Since these are always directories we can +use the follow_link inode operation to trigger the mount. + +But, each entry in direct and indirect maps can have offsets (making +them multi-mount map entries). + +For example, an indirect mount map entry could also be: + +g1 \ + / shark:/autofs/export5/testing/test \ + /s1 shark:/autofs/export/testing/test/s1 \ + /s2 shark:/autofs/export5/testing/test/s2 \ + /s1/ss1 shark:/autofs/export1 \ + /s2/ss2 shark:/autofs/export2 + +and a similarly a direct mount map entry could also be: + +/automount/dparse/g1 \ + / shark:/autofs/export5/testing/test \ + /s1 shark:/autofs/export/testing/test/s1 \ + /s2 shark:/autofs/export5/testing/test/s2 \ + /s1/ss1 shark:/autofs/export2 \ + /s2/ss2 shark:/autofs/export2 + +One of the issues with version 4 of autofs was that, when mounting an +entry with a large number of offsets, possibly with nesting, we needed +to mount and umount all of the offsets as a single unit. Not really a +problem, except for people with a large number of offsets in map entries. +This mechanism is used for the well known "hosts" map and we have seen +cases (in 2.4) where the available number of mounts are exhausted or +where the number of privileged ports available is exhausted. + +In version 5 we mount only as we go down the tree of offsets and +similarly for expiring them which resolves the above problem. There is +somewhat more detail to the implementation but it isn't needed for the +sake of the problem explanation. The one important detail is that these +offsets are implemented using the same mechanism as the direct mounts +above and so the mount points can be covered by a mount. + +The current autofs implementation uses an ioctl file descriptor opened +on the mount point for control operations. The references held by the +descriptor are accounted for in checks made to determine if a mount is +in use and is also used to access autofs file system information held +in the mount super block. So the use of a file handle needs to be +retained. + + +The Solution +============ + +To be able to restart autofs leaving existing direct, indirect and +offset mounts in place we need to be able to obtain a file handle +for these potentially covered autofs mount points. Rather than just +implement an isolated operation it was decided to re-implement the +existing ioctl interface and add new operations to provide this +functionality. + +In addition, to be able to reconstruct a mount tree that has busy mounts, +the uid and gid of the last user that triggered the mount needs to be +available because these can be used as macro substitution variables in +autofs maps. They are recorded at mount request time and an operation +has been added to retrieve them. + +Since we're re-implementing the control interface, a couple of other +problems with the existing interface have been addressed. First, when +a mount or expire operation completes a status is returned to the +kernel by either a "send ready" or a "send fail" operation. The +"send fail" operation of the ioctl interface could only ever send +ENOENT so the re-implementation allows user space to send an actual +status. Another expensive operation in user space, for those using +very large maps, is discovering if a mount is present. Usually this +involves scanning /proc/mounts and since it needs to be done quite +often it can introduce significant overhead when there are many entries +in the mount table. An operation to lookup the mount status of a mount +point dentry (covered or not) has also been added. + +Current kernel development policy recommends avoiding the use of the +ioctl mechanism in favor of systems such as Netlink. An implementation +using this system was attempted to evaluate its suitability and it was +found to be inadequate, in this case. The Generic Netlink system was +used for this as raw Netlink would lead to a significant increase in +complexity. There's no question that the Generic Netlink system is an +elegant solution for common case ioctl functions but it's not a complete +replacement probably because it's primary purpose in life is to be a +message bus implementation rather than specifically an ioctl replacement. +While it would be possible to work around this there is one concern +that lead to the decision to not use it. This is that the autofs +expire in the daemon has become far to complex because umount +candidates are enumerated, almost for no other reason than to "count" +the number of times to call the expire ioctl. This involves scanning +the mount table which has proved to be a big overhead for users with +large maps. The best way to improve this is try and get back to the +way the expire was done long ago. That is, when an expire request is +issued for a mount (file handle) we should continually call back to +the daemon until we can't umount any more mounts, then return the +appropriate status to the daemon. At the moment we just expire one +mount at a time. A Generic Netlink implementation would exclude this +possibility for future development due to the requirements of the +message bus architecture. + + +autofs4 Miscellaneous Device mount control interface +==================================================== + +The control interface is opening a device node, typically /dev/autofs. + +All the ioctls use a common structure to pass the needed parameter +information and return operation results: + +struct autofs_dev_ioctl { + __u32 ver_major; + __u32 ver_minor; + __u32 size; /* total size of data passed in + * including this struct */ + __s32 ioctlfd; /* automount command fd */ + + __u32 arg1; /* Command parameters */ + __u32 arg2; + + char path[0]; +}; + +The ioctlfd field is a mount point file descriptor of an autofs mount +point. It is returned by the open call and is used by all calls except +the check for whether a given path is a mount point, where it may +optionally be used to check a specific mount corresponding to a given +mount point file descriptor, and when requesting the uid and gid of the +last successful mount on a directory within the autofs file system. + +The fields arg1 and arg2 are used to communicate parameters and results of +calls made as described below. + +The path field is used to pass a path where it is needed and the size field +is used account for the increased structure length when translating the +structure sent from user space. + +This structure can be initialized before setting specific fields by using +the void function call init_autofs_dev_ioctl(struct autofs_dev_ioctl *). + +All of the ioctls perform a copy of this structure from user space to +kernel space and return -EINVAL if the size parameter is smaller than +the structure size itself, -ENOMEM if the kernel memory allocation fails +or -EFAULT if the copy itself fails. Other checks include a version check +of the compiled in user space version against the module version and a +mismatch results in a -EINVAL return. If the size field is greater than +the structure size then a path is assumed to be present and is checked to +ensure it begins with a "/" and is NULL terminated, otherwise -EINVAL is +returned. Following these checks, for all ioctl commands except +AUTOFS_DEV_IOCTL_VERSION_CMD, AUTOFS_DEV_IOCTL_OPENMOUNT_CMD and +AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD the ioctlfd is validated and if it is +not a valid descriptor or doesn't correspond to an autofs mount point +an error of -EBADF, -ENOTTY or -EINVAL (not an autofs descriptor) is +returned. + + +The ioctls +========== + +An example of an implementation which uses this interface can be seen +in autofs version 5.0.4 and later in file lib/dev-ioctl-lib.c of the +distribution tar available for download from kernel.org in directory +/pub/linux/daemons/autofs/v5. + +The device node ioctl operations implemented by this interface are: + + +AUTOFS_DEV_IOCTL_VERSION +------------------------ + +Get the major and minor version of the autofs4 device ioctl kernel module +implementation. It requires an initialized struct autofs_dev_ioctl as an +input parameter and sets the version information in the passed in structure. +It returns 0 on success or the error -EINVAL if a version mismatch is +detected. + + +AUTOFS_DEV_IOCTL_PROTOVER_CMD and AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD +------------------------------------------------------------------ + +Get the major and minor version of the autofs4 protocol version understood +by loaded module. This call requires an initialized struct autofs_dev_ioctl +with the ioctlfd field set to a valid autofs mount point descriptor +and sets the requested version number in structure field arg1. These +commands return 0 on success or one of the negative error codes if +validation fails. + + +AUTOFS_DEV_IOCTL_OPENMOUNT and AUTOFS_DEV_IOCTL_CLOSEMOUNT +---------------------------------------------------------- + +Obtain and release a file descriptor for an autofs managed mount point +path. The open call requires an initialized struct autofs_dev_ioctl with +the the path field set and the size field adjusted appropriately as well +as the arg1 field set to the device number of the autofs mount. The +device number can be obtained from the mount options shown in +/proc/mounts. The close call requires an initialized struct +autofs_dev_ioct with the ioctlfd field set to the descriptor obtained +from the open call. The release of the file descriptor can also be done +with close(2) so any open descriptors will also be closed at process exit. +The close call is included in the implemented operations largely for +completeness and to provide for a consistent user space implementation. + + +AUTOFS_DEV_IOCTL_READY_CMD and AUTOFS_DEV_IOCTL_FAIL_CMD +-------------------------------------------------------- + +Return mount and expire result status from user space to the kernel. +Both of these calls require an initialized struct autofs_dev_ioctl +with the ioctlfd field set to the descriptor obtained from the open +call and the arg1 field set to the wait queue token number, received +by user space in the foregoing mount or expire request. The arg2 field +is set to the status to be returned. For the ready call this is always +0 and for the fail call it is set to the errno of the operation. + + +AUTOFS_DEV_IOCTL_SETPIPEFD_CMD +------------------------------ + +Set the pipe file descriptor used for kernel communication to the daemon. +Normally this is set at mount time using an option but when reconnecting +to a existing mount we need to use this to tell the autofs mount about +the new kernel pipe descriptor. In order to protect mounts against +incorrectly setting the pipe descriptor we also require that the autofs +mount be catatonic (see next call). + +The call requires an initialized struct autofs_dev_ioctl with the +ioctlfd field set to the descriptor obtained from the open call and +the arg1 field set to descriptor of the pipe. On success the call +also sets the process group id used to identify the controlling process +(eg. the owning automount(8) daemon) to the process group of the caller. + + +AUTOFS_DEV_IOCTL_CATATONIC_CMD +------------------------------ + +Make the autofs mount point catatonic. The autofs mount will no longer +issue mount requests, the kernel communication pipe descriptor is released +and any remaining waits in the queue released. + +The call requires an initialized struct autofs_dev_ioctl with the +ioctlfd field set to the descriptor obtained from the open call. + + +AUTOFS_DEV_IOCTL_TIMEOUT_CMD +---------------------------- + +Set the expire timeout for mounts withing an autofs mount point. + +The call requires an initialized struct autofs_dev_ioctl with the +ioctlfd field set to the descriptor obtained from the open call. + + +AUTOFS_DEV_IOCTL_REQUESTER_CMD +------------------------------ + +Return the uid and gid of the last process to successfully trigger a the +mount on the given path dentry. + +The call requires an initialized struct autofs_dev_ioctl with the path +field set to the mount point in question and the size field adjusted +appropriately as well as the arg1 field set to the device number of the +containing autofs mount. Upon return the struct field arg1 contains the +uid and arg2 the gid. + +When reconstructing an autofs mount tree with active mounts we need to +re-connect to mounts that may have used the original process uid and +gid (or string variations of them) for mount lookups within the map entry. +This call provides the ability to obtain this uid and gid so they may be +used by user space for the mount map lookups. + + +AUTOFS_DEV_IOCTL_EXPIRE_CMD +--------------------------- + +Issue an expire request to the kernel for an autofs mount. Typically +this ioctl is called until no further expire candidates are found. + +The call requires an initialized struct autofs_dev_ioctl with the +ioctlfd field set to the descriptor obtained from the open call. In +addition an immediate expire, independent of the mount timeout, can be +requested by setting the arg1 field to 1. If no expire candidates can +be found the ioctl returns -1 with errno set to EAGAIN. + +This call causes the kernel module to check the mount corresponding +to the given ioctlfd for mounts that can be expired, issues an expire +request back to the daemon and waits for completion. + +AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD +------------------------------ + +Checks if an autofs mount point is in use. + +The call requires an initialized struct autofs_dev_ioctl with the +ioctlfd field set to the descriptor obtained from the open call and +it returns the result in the arg1 field, 1 for busy and 0 otherwise. + + +AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD +--------------------------------- + +Check if the given path is a mountpoint. + +The call requires an initialized struct autofs_dev_ioctl. There are two +possible variations. Both use the path field set to the path of the mount +point to check and the size field adjusted appropriately. One uses the +ioctlfd field to identify a specific mount point to check while the other +variation uses the path and optionaly arg1 set to an autofs mount type. +The call returns 1 if this is a mount point and sets arg1 to the device +number of the mount and field arg2 to the relevant super block magic +number (described below) or 0 if it isn't a mountpoint. In both cases +the the device number (as returned by new_encode_dev()) is returned +in field arg1. + +If supplied with a file descriptor we're looking for a specific mount, +not necessarily at the top of the mounted stack. In this case the path +the descriptor corresponds to is considered a mountpoint if it is itself +a mountpoint or contains a mount, such as a multi-mount without a root +mount. In this case we return 1 if the descriptor corresponds to a mount +point and and also returns the super magic of the covering mount if there +is one or 0 if it isn't a mountpoint. + +If a path is supplied (and the ioctlfd field is set to -1) then the path +is looked up and is checked to see if it is the root of a mount. If a +type is also given we are looking for a particular autofs mount and if +a match isn't found a fail is returned. If the the located path is the +root of a mount 1 is returned along with the super magic of the mount +or 0 otherwise. + diff --git a/Documentation/filesystems/ext3.txt b/Documentation/filesystems/ext3.txt index b45f3c1b8b4..9dd2a3bb2ac 100644 --- a/Documentation/filesystems/ext3.txt +++ b/Documentation/filesystems/ext3.txt @@ -96,6 +96,11 @@ errors=remount-ro(*) Remount the filesystem read-only on an error. errors=continue Keep going on a filesystem error. errors=panic Panic and halt the machine if an error occurs. +data_err=ignore(*) Just print an error message if an error occurs + in a file data buffer in ordered mode. +data_err=abort Abort the journal if an error occurs in a file + data buffer in ordered mode. + grpid Give objects the same group ID as their creator. bsdgroups @@ -193,6 +198,5 @@ kernel source: <file:fs/ext3/> programs: http://e2fsprogs.sourceforge.net/ http://ext2resize.sourceforge.net -useful links: http://www.zip.com.au/~akpm/linux/ext3/ext3-usage.html - http://www-106.ibm.com/developerworks/linux/library/l-fs7/ +useful links: http://www-106.ibm.com/developerworks/linux/library/l-fs7/ http://www-106.ibm.com/developerworks/linux/library/l-fs8/ diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt index eb154ef36c2..174eaff7ded 100644 --- a/Documentation/filesystems/ext4.txt +++ b/Documentation/filesystems/ext4.txt @@ -2,19 +2,24 @@ Ext4 Filesystem =============== -This is a development version of the ext4 filesystem, an advanced level -of the ext3 filesystem which incorporates scalability and reliability -enhancements for supporting large filesystems (64 bit) in keeping with -increasing disk capacities and state-of-the-art feature requirements. +Ext4 is an an advanced level of the ext3 filesystem which incorporates +scalability and reliability enhancements for supporting large filesystems +(64 bit) in keeping with increasing disk capacities and state-of-the-art +feature requirements. -Mailing list: linux-ext4@vger.kernel.org +Mailing list: linux-ext4@vger.kernel.org +Web site: http://ext4.wiki.kernel.org 1. Quick usage instructions: =========================== +Note: More extensive information for getting started with ext4 can be + found at the ext4 wiki site at the URL: + http://ext4.wiki.kernel.org/index.php/Ext4_Howto + - Compile and install the latest version of e2fsprogs (as of this - writing version 1.41) from: + writing version 1.41.3) from: http://sourceforge.net/project/showfiles.php?group_id=2406 @@ -36,11 +41,9 @@ Mailing list: linux-ext4@vger.kernel.org # mke2fs -t ext4 /dev/hda1 - Or configure an existing ext3 filesystem to support extents and set - the test_fs flag to indicate that it's ok for an in-development - filesystem to touch this filesystem: + Or to configure an existing ext3 filesystem to support extents: - # tune2fs -O extents -E test_fs /dev/hda1 + # tune2fs -O extents /dev/hda1 If the filesystem was created with 128 byte inodes, it can be converted to use 256 byte for greater efficiency via: @@ -104,8 +107,8 @@ exist yet so I'm not sure they're in the near-term roadmap. The big performance win will come with mballoc, delalloc and flex_bg grouping of bitmaps and inode tables. Some test results available here: - - http://www.bullopensource.org/ext4/20080530/ffsb-write-2.6.26-rc2.html - - http://www.bullopensource.org/ext4/20080530/ffsb-readwrite-2.6.26-rc2.html + - http://www.bullopensource.org/ext4/20080818-ffsb/ffsb-write-2.6.27-rc1.html + - http://www.bullopensource.org/ext4/20080818-ffsb/ffsb-readwrite-2.6.27-rc1.html 3. Options ========== @@ -214,9 +217,6 @@ noreservation bsddf (*) Make 'df' act like BSD. minixdf Make 'df' act like Minix. -check=none Don't do extra checking of bitmaps on mount. -nocheck - debug Extra debugging information is sent to syslog. errors=remount-ro(*) Remount the filesystem read-only on an error. @@ -253,8 +253,6 @@ nobh (a) cache disk block mapping information "nobh" option tries to avoid associating buffer heads (supported only for "writeback" mode). -mballoc (*) Use the multiple block allocator for block allocation -nomballoc disabled multiple block allocator for block allocation. stripe=n Number of filesystem blocks that mballoc will try to use for allocation size and alignment. For RAID5/6 systems this should be the number of data diff --git a/Documentation/filesystems/nfsroot.txt b/Documentation/filesystems/nfsroot.txt index 31b32917234..68baddf3c3e 100644 --- a/Documentation/filesystems/nfsroot.txt +++ b/Documentation/filesystems/nfsroot.txt @@ -169,7 +169,7 @@ They depend on various facilities being available: 3.1) Booting from a floppy using syslinux When building kernels, an easy way to create a boot floppy that uses - syslinux is to use the zdisk or bzdisk make targets which use + syslinux is to use the zdisk or bzdisk make targets which use zimage and bzimage images respectively. Both targets accept the FDARGS parameter which can be used to set the kernel command line. diff --git a/Documentation/filesystems/ocfs2.txt b/Documentation/filesystems/ocfs2.txt index 4340cc82579..67310fbbb7d 100644 --- a/Documentation/filesystems/ocfs2.txt +++ b/Documentation/filesystems/ocfs2.txt @@ -28,10 +28,7 @@ Manish Singh <manish.singh@oracle.com> Caveats ======= Features which OCFS2 does not support yet: - - extended attributes - quotas - - cluster aware flock - - cluster aware lockf - Directory change notification (F_NOTIFY) - Distributed Caching (F_SETLEASE/F_GETLEASE/break_lease) - POSIX ACLs diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index b488edad743..71df353e367 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -44,6 +44,7 @@ Table of Contents 2.14 /proc/<pid>/io - Display the IO accounting fields 2.15 /proc/<pid>/coredump_filter - Core dump filtering settings 2.16 /proc/<pid>/mountinfo - Information about mounts + 2.17 /proc/sys/fs/epoll - Configuration options for the epoll interface ------------------------------------------------------------------------------ Preface @@ -1321,15 +1322,30 @@ debugging information is displayed on console. NMI switch that most IA32 servers have fires unknown NMI up, for example. If a system hangs up, try pressing the NMI switch. +panic_on_unrecovered_nmi +------------------------ + +The default Linux behaviour on an NMI of either memory or unknown is to continue +operation. For many environments such as scientific computing it is preferable +that the box is taken out and the error dealt with than an uncorrected +parity/ECC error get propogated. + +A small number of systems do generate NMI's for bizarre random reasons such as +power management so the default is off. That sysctl works like the existing +panic controls already in that directory. + nmi_watchdog ------------ Enables/Disables the NMI watchdog on x86 systems. When the value is non-zero the NMI watchdog is enabled and will continuously test all online cpus to -determine whether or not they are still functioning properly. +determine whether or not they are still functioning properly. Currently, +passing "nmi_watchdog=" parameter at boot time is required for this function +to work. -Because the NMI watchdog shares registers with oprofile, by disabling the NMI -watchdog, oprofile may have more registers to utilize. +If LAPIC NMI watchdog method is in use (nmi_watchdog=2 kernel parameter), the +NMI watchdog shares registers with oprofile. By disabling the NMI watchdog, +oprofile may have more registers to utilize. msgmni ------ @@ -1372,15 +1388,18 @@ causes the kernel to prefer to reclaim dentries and inodes. dirty_background_ratio ---------------------- -Contains, as a percentage of total system memory, the number of pages at which -the pdflush background writeback daemon will start writing out dirty data. +Contains, as a percentage of the dirtyable system memory (free pages + mapped +pages + file cache, not including locked pages and HugePages), the number of +pages at which the pdflush background writeback daemon will start writing out +dirty data. dirty_ratio ----------------- -Contains, as a percentage of total system memory, the number of pages at which -a process which is generating disk writes will itself start writing out dirty -data. +Contains, as a percentage of the dirtyable system memory (free pages + mapped +pages + file cache, not including locked pages and HugePages), the number of +pages at which a process which is generating disk writes will itself start +writing out dirty data. dirty_writeback_centisecs ------------------------- @@ -2400,24 +2419,29 @@ will be dumped when the <pid> process is dumped. coredump_filter is a bitmask of memory types. If a bit of the bitmask is set, memory segments of the corresponding memory type are dumped, otherwise they are not dumped. -The following 4 memory types are supported: +The following 7 memory types are supported: - (bit 0) anonymous private memory - (bit 1) anonymous shared memory - (bit 2) file-backed private memory - (bit 3) file-backed shared memory - (bit 4) ELF header pages in file-backed private memory areas (it is effective only if the bit 2 is cleared) + - (bit 5) hugetlb private memory + - (bit 6) hugetlb shared memory Note that MMIO pages such as frame buffer are never dumped and vDSO pages are always dumped regardless of the bitmask status. -Default value of coredump_filter is 0x3; this means all anonymous memory -segments are dumped. + Note bit 0-4 doesn't effect any hugetlb memory. hugetlb memory are only + effected by bit 5-6. + +Default value of coredump_filter is 0x23; this means all anonymous memory +segments and hugetlb private memory are dumped. If you don't want to dump all shared memory segments attached to pid 1234, -write 1 to the process's proc file. +write 0x21 to the process's proc file. - $ echo 0x1 > /proc/1234/coredump_filter + $ echo 0x21 > /proc/1234/coredump_filter When a new process is created, the process inherits the bitmask status from its parent. It is useful to set up coredump_filter before the program runs. @@ -2463,4 +2487,30 @@ For more information on mount propagation see: Documentation/filesystems/sharedsubtree.txt +2.17 /proc/sys/fs/epoll - Configuration options for the epoll interface +-------------------------------------------------------- + +This directory contains configuration options for the epoll(7) interface. + +max_user_instances +------------------ + +This is the maximum number of epoll file descriptors that a single user can +have open at a given time. The default value is 128, and should be enough +for normal users. + +max_user_watches +---------------- + +Every epoll file descriptor can store a number of files to be monitored +for event readiness. Each one of these monitored files constitutes a "watch". +This configuration option sets the maximum number of "watches" that are +allowed for each user. +Each "watch" costs roughly 90 bytes on a 32bit kernel, and roughly 160 bytes +on a 64bit one. +The current default value for max_user_watches is the 1/32 of the available +low memory, divided for the "watch" cost in bytes. + + ------------------------------------------------------------------------------ + diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.txt b/Documentation/filesystems/ramfs-rootfs-initramfs.txt index 7be232b44ee..a8273d5fad2 100644 --- a/Documentation/filesystems/ramfs-rootfs-initramfs.txt +++ b/Documentation/filesystems/ramfs-rootfs-initramfs.txt @@ -130,12 +130,12 @@ The 2.6 kernel build process always creates a gzipped cpio format initramfs archive and links it into the resulting kernel binary. By default, this archive is empty (consuming 134 bytes on x86). -The config option CONFIG_INITRAMFS_SOURCE (for some reason buried under -devices->block devices in menuconfig, and living in usr/Kconfig) can be used -to specify a source for the initramfs archive, which will automatically be -incorporated into the resulting binary. This option can point to an existing -gzipped cpio archive, a directory containing files to be archived, or a text -file specification such as the following example: +The config option CONFIG_INITRAMFS_SOURCE (in General Setup in menuconfig, +and living in usr/Kconfig) can be used to specify a source for the +initramfs archive, which will automatically be incorporated into the +resulting binary. This option can point to an existing gzipped cpio +archive, a directory containing files to be archived, or a text file +specification such as the following example: dir /dev 755 0 0 nod /dev/console 644 0 0 c 5 1 @@ -263,7 +263,7 @@ User Mode Linux, like so: sleep(999999999); } EOF - gcc -static hello2.c -o init + gcc -static hello.c -o init echo init | cpio -o -H newc | gzip > test.cpio.gz # Testing external initramfs using the initrd loading mechanism. qemu -kernel /boot/vmlinuz -initrd test.cpio.gz /dev/zero diff --git a/Documentation/filesystems/ubifs.txt b/Documentation/filesystems/ubifs.txt index 6a0d70a22f0..dd84ea3c10d 100644 --- a/Documentation/filesystems/ubifs.txt +++ b/Documentation/filesystems/ubifs.txt @@ -86,6 +86,15 @@ norm_unmount (*) commit on unmount; the journal is committed fast_unmount do not commit on unmount; this option makes unmount faster, but the next mount slower because of the need to replay the journal. +bulk_read read more in one go to take advantage of flash + media that read faster sequentially +no_bulk_read (*) do not bulk-read +no_chk_data_crc skip checking of CRCs on data nodes in order to + improve read performance. Use this option only + if the flash media is highly reliable. The effect + of this option is that corruption of the contents + of a file can go unnoticed. +chk_data_crc (*) do not skip checking CRCs on data nodes Quick usage instructions diff --git a/Documentation/filesystems/vfat.txt b/Documentation/filesystems/vfat.txt index bbac4f1d905..3a5ddc96901 100644 --- a/Documentation/filesystems/vfat.txt +++ b/Documentation/filesystems/vfat.txt @@ -8,6 +8,12 @@ if you want to format from within Linux. VFAT MOUNT OPTIONS ---------------------------------------------------------------------- +uid=### -- Set the owner of all files on this filesystem. + The default is the uid of current process. + +gid=### -- Set the group of all files on this filesystem. + The default is the gid of current process. + umask=### -- The permission mask (for files and directories, see umask(1)). The default is the umask of current process. @@ -36,7 +42,7 @@ codepage=### -- Sets the codepage number for converting to shortname characters on FAT filesystem. By default, FAT_DEFAULT_CODEPAGE setting is used. -iocharset=name -- Character set to use for converting between the +iocharset=<name> -- Character set to use for converting between the encoding is used for user visible filename and 16 bit Unicode characters. Long filenames are stored on disk in Unicode format, but Unix for the most part doesn't @@ -86,6 +92,8 @@ check=s|r|n -- Case sensitivity checking setting. r: relaxed, case insensitive n: normal, default setting, currently case insensitive +nocase -- This was deprecated for vfat. Use shortname=win95 instead. + shortname=lower|win95|winnt|mixed -- Shortname display/create setting. lower: convert to lowercase for display, @@ -99,11 +107,31 @@ shortname=lower|win95|winnt|mixed tz=UTC -- Interpret timestamps as UTC rather than local time. This option disables the conversion of timestamps between local time (as used by Windows on FAT) and UTC - (which Linux uses internally). This is particuluarly + (which Linux uses internally). This is particularly useful when mounting devices (like digital cameras) that are set to UTC in order to avoid the pitfalls of local time. +showexec -- If set, the execute permission bits of the file will be + allowed only if the extension part of the name is .EXE, + .COM, or .BAT. Not set by default. + +debug -- Can be set, but unused by the current implementation. + +sys_immutable -- If set, ATTR_SYS attribute on FAT is handled as + IMMUTABLE flag on Linux. Not set by default. + +flush -- If set, the filesystem will try to flush to disk more + early than normal. Not set by default. + +rodir -- FAT has the ATTR_RO (read-only) attribute. But on Windows, + the ATTR_RO of the directory will be just ignored actually, + and is used by only applications as flag. E.g. it's setted + for the customized folder. + + If you want to use ATTR_RO as read-only flag even for + the directory, set this option. + <bool>: 0,1,yes,no,true,false TODO diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index c4d348dabe9..5579bda58a6 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -492,7 +492,7 @@ written-back to storage typically in whole pages, however the address_space has finer control of write sizes. The read process essentially only requires 'readpage'. The write -process is more complicated and uses prepare_write/commit_write or +process is more complicated and uses write_begin/write_end or set_page_dirty to write data into the address_space, and writepage, sync_page, and writepages to writeback data to storage. @@ -521,8 +521,6 @@ struct address_space_operations { int (*set_page_dirty)(struct page *page); int (*readpages)(struct file *filp, struct address_space *mapping, struct list_head *pages, unsigned nr_pages); - int (*prepare_write)(struct file *, struct page *, unsigned, unsigned); - int (*commit_write)(struct file *, struct page *, unsigned, unsigned); int (*write_begin)(struct file *, struct address_space *mapping, loff_t pos, unsigned len, unsigned flags, struct page **pagep, void **fsdata); @@ -598,37 +596,7 @@ struct address_space_operations { readpages is only used for read-ahead, so read errors are ignored. If anything goes wrong, feel free to give up. - prepare_write: called by the generic write path in VM to set up a write - request for a page. This indicates to the address space that - the given range of bytes is about to be written. The - address_space should check that the write will be able to - complete, by allocating space if necessary and doing any other - internal housekeeping. If the write will update parts of - any basic-blocks on storage, then those blocks should be - pre-read (if they haven't been read already) so that the - updated blocks can be written out properly. - The page will be locked. - - Note: the page _must not_ be marked uptodate in this function - (or anywhere else) unless it actually is uptodate right now. As - soon as a page is marked uptodate, it is possible for a concurrent - read(2) to copy it to userspace. - - commit_write: If prepare_write succeeds, new data will be copied - into the page and then commit_write will be called. It will - typically update the size of the file (if appropriate) and - mark the inode as dirty, and do any other related housekeeping - operations. It should avoid returning an error if possible - - errors should have been handled by prepare_write. - - write_begin: This is intended as a replacement for prepare_write. The - key differences being that: - - it returns a locked page (in *pagep) rather than being - given a pre locked page; - - it must be able to cope with short writes (where the - length passed to write_begin is greater than the number - of bytes copied into the page). - + write_begin: Called by the generic buffered write code to ask the filesystem to prepare to write len bytes at the given offset in the file. The address_space should check that the write will be able to complete, @@ -640,6 +608,9 @@ struct address_space_operations { The filesystem must return the locked pagecache page for the specified offset, in *pagep, for the caller to write into. + It must be able to cope with short writes (where the length passed to + write_begin is greater than the number of bytes copied into the page). + flags is a field for AOP_FLAG_xxx flags, described in include/linux/fs.h. diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt index 0a1668ba260..9878f50d6ed 100644 --- a/Documentation/filesystems/xfs.txt +++ b/Documentation/filesystems/xfs.txt @@ -229,10 +229,6 @@ The following sysctls are available for the XFS filesystem: ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl is set. - fs.xfs.restrict_chown (Min: 0 Default: 1 Max: 1) - Controls whether unprivileged users can use chown to "give away" - a file to another user. - fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1) Setting this to "1" will cause the "sync" flag set by the xfs_io(8) chattr command on a directory to be diff --git a/Documentation/filesystems/xip.txt b/Documentation/filesystems/xip.txt index 3cc4010521a..0466ee56927 100644 --- a/Documentation/filesystems/xip.txt +++ b/Documentation/filesystems/xip.txt @@ -39,10 +39,11 @@ The block device operation is optional, these block devices support it as of today: - dcssblk: s390 dcss block device driver -An address space operation named get_xip_page is used to retrieve reference -to a struct page. To address the target page, a reference to an address_space, -and a sector number is provided. A 3rd argument indicates whether the -function should allocate blocks if needed. +An address space operation named get_xip_mem is used to retrieve references +to a page frame number and a kernel address. To obtain these values a reference +to an address_space is provided. This function assigns values to the kmem and +pfn parameters. The third argument indicates whether the function should allocate +blocks if needed. This address space operation is mutually exclusive with readpage&writepage that do page cache read/write operations. diff --git a/Documentation/ftrace.txt b/Documentation/ftrace.txt index d330fe3103d..803b1318b13 100644 --- a/Documentation/ftrace.txt +++ b/Documentation/ftrace.txt @@ -8,7 +8,7 @@ Copyright 2008 Red Hat Inc. Reviewers: Elias Oltmanns, Randy Dunlap, Andrew Morton, John Kacur, and David Teigland. -Written for: 2.6.27-rc1 +Written for: 2.6.28-rc2 Introduction ------------ @@ -50,26 +50,26 @@ of ftrace. Here is a list of some of the key files: Note: all time values are in microseconds. - current_tracer : This is used to set or display the current tracer + current_tracer: This is used to set or display the current tracer that is configured. - available_tracers : This holds the different types of tracers that + available_tracers: This holds the different types of tracers that have been compiled into the kernel. The tracers listed here can be configured by echoing their name into current_tracer. - tracing_enabled : This sets or displays whether the current_tracer + tracing_enabled: This sets or displays whether the current_tracer is activated and tracing or not. Echo 0 into this file to disable the tracer or 1 to enable it. - trace : This file holds the output of the trace in a human readable + trace: This file holds the output of the trace in a human readable format (described below). - latency_trace : This file shows the same trace but the information + latency_trace: This file shows the same trace but the information is organized more to display possible latencies in the system (described below). - trace_pipe : The output is the same as the "trace" file but this + trace_pipe: The output is the same as the "trace" file but this file is meant to be streamed with live tracing. Reads from this file will block until new data is retrieved. Unlike the "trace" and "latency_trace" @@ -82,11 +82,11 @@ of ftrace. Here is a list of some of the key files: tracer is not adding more data, they will display the same information every time they are read. - iter_ctrl : This file lets the user control the amount of data + trace_options: This file lets the user control the amount of data that is displayed in one of the above output files. - trace_max_latency : Some of the tracers record the max latency. + trace_max_latency: Some of the tracers record the max latency. For example, the time interrupts are disabled. This time is saved in this file. The max trace will also be stored, and displayed by either @@ -94,29 +94,26 @@ of ftrace. Here is a list of some of the key files: only be recorded if the latency is greater than the value in this file. (in microseconds) - trace_entries : This sets or displays the number of trace - entries each CPU buffer can hold. The tracer buffers - are the same size for each CPU. The displayed number - is the size of the CPU buffer and not total size. The + buffer_size_kb: This sets or displays the number of kilobytes each CPU + buffer can hold. The tracer buffers are the same size + for each CPU. The displayed number is the size of the + CPU buffer and not total size of all buffers. The trace buffers are allocated in pages (blocks of memory that the kernel uses for allocation, usually 4 KB in size). - Since each entry is smaller than a page, if the last - allocated page has room for more entries than were - requested, the rest of the page is used to allocate - entries. + If the last page allocated has room for more bytes + than requested, the rest of the page will be used, + making the actual allocation bigger than requested. + (Note, the size may not be a multiple of the page size due + to buffer managment overhead.) This can only be updated when the current_tracer - is set to "none". + is set to "nop". - NOTE: It is planned on changing the allocated buffers - from being the number of possible CPUS to - the number of online CPUS. - - tracing_cpumask : This is a mask that lets the user only trace + tracing_cpumask: This is a mask that lets the user only trace on specified CPUS. The format is a hex string representing the CPUS. - set_ftrace_filter : When dynamic ftrace is configured in (see the + set_ftrace_filter: When dynamic ftrace is configured in (see the section below "dynamic ftrace"), the code is dynamically modified (code text rewrite) to disable calling of the function profiler (mcount). This lets tracing be configured @@ -130,14 +127,13 @@ of ftrace. Here is a list of some of the key files: be traced. If a function exists in both set_ftrace_filter and set_ftrace_notrace, the function will _not_ be traced. - available_filter_functions : When a function is encountered the first - time by the dynamic tracer, it is recorded and - later the call is converted into a nop. This file - lists the functions that have been recorded - by the dynamic tracer and these functions can - be used to set the ftrace filter by the above - "set_ftrace_filter" file. (See the section "dynamic ftrace" - below for more details). + set_ftrace_pid: Have the function tracer only trace a single thread. + + available_filter_functions: This lists the functions that ftrace + has processed and can trace. These are the function + names that you can pass to "set_ftrace_filter" or + "set_ftrace_notrace". (See the section "dynamic ftrace" + below for more details.) The Tracers @@ -145,7 +141,7 @@ The Tracers Here is the list of current tracers that may be configured. - ftrace - function tracer that uses mcount to trace all functions. + function - function tracer that uses mcount to trace all functions. sched_switch - traces the context switches between tasks. @@ -166,8 +162,8 @@ Here is the list of current tracers that may be configured. the highest priority task to get scheduled after it has been woken up. - none - This is not a tracer. To remove all tracers from tracing - simply echo "none" into current_tracer. + nop - This is not a tracer. To remove all tracers from tracing + simply echo "nop" into current_tracer. Examples of using the tracer @@ -182,7 +178,7 @@ Output format: Here is an example of the output format of the file "trace" -------- -# tracer: ftrace +# tracer: function # # TASK-PID CPU# TIMESTAMP FUNCTION # | | | | | @@ -192,7 +188,7 @@ Here is an example of the output format of the file "trace" -------- A header is printed with the tracer name that is represented by the trace. -In this case the tracer is "ftrace". Then a header showing the format. Task +In this case the tracer is "function". Then a header showing the format. Task name "bash", the task PID "4251", the CPU that it was running on "01", the timestamp in <secs>.<usecs> format, the function name that was traced "path_put" and the parent function that called this function @@ -291,6 +287,9 @@ explains which is which. CPU#: The CPU which the process was running on. irqs-off: 'd' interrupts are disabled. '.' otherwise. + Note: If the architecture does not support a way to + read the irq flags variable, an 'X' will always + be printed here. need-resched: 'N' task need_resched is set, '.' otherwise. @@ -319,23 +318,23 @@ The above is mostly meaningful for kernel developers. The rest is the same as the 'trace' file. -iter_ctrl ---------- +trace_options +------------- -The iter_ctrl file is used to control what gets printed in the trace +The trace_options file is used to control what gets printed in the trace output. To see what is available, simply cat the file: - cat /debug/tracing/iter_ctrl + cat /debug/tracing/trace_options print-parent nosym-offset nosym-addr noverbose noraw nohex nobin \ - noblock nostacktrace nosched-tree + noblock nostacktrace nosched-tree nouserstacktrace nosym-userobj To disable one of the options, echo in the option prepended with "no". - echo noprint-parent > /debug/tracing/iter_ctrl + echo noprint-parent > /debug/tracing/trace_options To enable an option, leave off the "no". - echo sym-offset > /debug/tracing/iter_ctrl + echo sym-offset > /debug/tracing/trace_options Here are the available options: @@ -381,6 +380,20 @@ Here are the available options: When a trace is recorded, so is the stack of functions. This allows for back traces of trace sites. + userstacktrace - This option changes the trace. + It records a stacktrace of the current userspace thread. + + sym-userobj - when user stacktrace are enabled, look up which object the + address belongs to, and print a relative address + This is especially useful when ASLR is on, otherwise you don't + get a chance to resolve the address to object/file/line after the app is no + longer running + + The lookup is performed when you read trace,trace_pipe,latency_trace. Example: + + a.out-1623 [000] 40874.465068: /root/a.out[+0x480] <-/root/a.out[+0 +x494] <- /root/a.out[+0x4a8] <- /lib/libc-2.7.so[+0x1e1a6] + sched-tree - TBD (any users??) @@ -1000,22 +1013,20 @@ is the stack for the hard interrupt. This hides the fact that NEED_RESCHED has been set. We do not see the 'N' until we switch back to the task's assigned stack. -ftrace ------- +function +-------- -ftrace is not only the name of the tracing infrastructure, but it -is also a name of one of the tracers. The tracer is the function -tracer. Enabling the function tracer can be done from the -debug file system. Make sure the ftrace_enabled is set otherwise -this tracer is a nop. +This tracer is the function tracer. Enabling the function tracer +can be done from the debug file system. Make sure the ftrace_enabled is +set; otherwise this tracer is a nop. # sysctl kernel.ftrace_enabled=1 - # echo ftrace > /debug/tracing/current_tracer + # echo function > /debug/tracing/current_tracer # echo 1 > /debug/tracing/tracing_enabled # usleep 1 # echo 0 > /debug/tracing/tracing_enabled # cat /debug/tracing/trace -# tracer: ftrace +# tracer: function # # TASK-PID CPU# TIMESTAMP FUNCTION # | | | | | @@ -1037,10 +1048,10 @@ this tracer is a nop. [...] -Note: ftrace uses ring buffers to store the above entries. The newest data -may overwrite the oldest data. Sometimes using echo to stop the trace -is not sufficient because the tracing could have overwritten the data -that you wanted to record. For this reason, it is sometimes better to +Note: function tracer uses ring buffers to store the above entries. +The newest data may overwrite the oldest data. Sometimes using echo to +stop the trace is not sufficient because the tracing could have overwritten +the data that you wanted to record. For this reason, it is sometimes better to disable tracing directly from a program. This allows you to stop the tracing at the point that you hit the part that you are interested in. To disable the tracing directly from a C program, something like following @@ -1064,6 +1075,83 @@ For simple one time traces, the above is sufficent. For anything else, a search through /proc/mounts may be needed to find where the debugfs file-system is mounted. + +Single thread tracing +--------------------- + +By writing into /debug/tracing/set_ftrace_pid you can trace a +single thread. For example: + +# cat /debug/tracing/set_ftrace_pid +no pid +# echo 3111 > /debug/tracing/set_ftrace_pid +# cat /debug/tracing/set_ftrace_pid +3111 +# echo function > /debug/tracing/current_tracer +# cat /debug/tracing/trace | head + # tracer: function + # + # TASK-PID CPU# TIMESTAMP FUNCTION + # | | | | | + yum-updatesd-3111 [003] 1637.254676: finish_task_switch <-thread_return + yum-updatesd-3111 [003] 1637.254681: hrtimer_cancel <-schedule_hrtimeout_range + yum-updatesd-3111 [003] 1637.254682: hrtimer_try_to_cancel <-hrtimer_cancel + yum-updatesd-3111 [003] 1637.254683: lock_hrtimer_base <-hrtimer_try_to_cancel + yum-updatesd-3111 [003] 1637.254685: fget_light <-do_sys_poll + yum-updatesd-3111 [003] 1637.254686: pipe_poll <-do_sys_poll +# echo -1 > /debug/tracing/set_ftrace_pid +# cat /debug/tracing/trace |head + # tracer: function + # + # TASK-PID CPU# TIMESTAMP FUNCTION + # | | | | | + ##### CPU 3 buffer started #### + yum-updatesd-3111 [003] 1701.957688: free_poll_entry <-poll_freewait + yum-updatesd-3111 [003] 1701.957689: remove_wait_queue <-free_poll_entry + yum-updatesd-3111 [003] 1701.957691: fput <-free_poll_entry + yum-updatesd-3111 [003] 1701.957692: audit_syscall_exit <-sysret_audit + yum-updatesd-3111 [003] 1701.957693: path_put <-audit_syscall_exit + +If you want to trace a function when executing, you could use +something like this simple program: + +#include <stdio.h> +#include <stdlib.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <fcntl.h> +#include <unistd.h> + +int main (int argc, char **argv) +{ + if (argc < 1) + exit(-1); + + if (fork() > 0) { + int fd, ffd; + char line[64]; + int s; + + ffd = open("/debug/tracing/current_tracer", O_WRONLY); + if (ffd < 0) + exit(-1); + write(ffd, "nop", 3); + + fd = open("/debug/tracing/set_ftrace_pid", O_WRONLY); + s = sprintf(line, "%d\n", getpid()); + write(fd, line, s); + + write(ffd, "function", 8); + + close(fd); + close(ffd); + + execvp(argv[1], argv+1); + } + + return 0; +} + dynamic ftrace -------------- @@ -1074,18 +1162,31 @@ every kernel function, produced by the -pg switch in gcc), starts of pointing to a simple return. (Enabling FTRACE will include the -pg switch in the compiling of the kernel.) -When dynamic ftrace is initialized, it calls kstop_machine to make -the machine act like a uniprocessor so that it can freely modify code -without worrying about other processors executing that same code. At -initialization, the mcount calls are changed to call a "record_ip" -function. After this, the first time a kernel function is called, -it has the calling address saved in a hash table. - -Later on the ftraced kernel thread is awoken and will again call -kstop_machine if new functions have been recorded. The ftraced thread -will change all calls to mcount to "nop". Just calling mcount -and having mcount return has shown a 10% overhead. By converting -it to a nop, there is no measurable overhead to the system. +At compile time every C file object is run through the +recordmcount.pl script (located in the scripts directory). This +script will process the C object using objdump to find all the +locations in the .text section that call mcount. (Note, only +the .text section is processed, since processing other sections +like .init.text may cause races due to those sections being freed). + +A new section called "__mcount_loc" is created that holds references +to all the mcount call sites in the .text section. This section is +compiled back into the original object. The final linker will add +all these references into a single table. + +On boot up, before SMP is initialized, the dynamic ftrace code +scans this table and updates all the locations into nops. It also +records the locations, which are added to the available_filter_functions +list. Modules are processed as they are loaded and before they are +executed. When a module is unloaded, it also removes its functions from +the ftrace function list. This is automatic in the module unload +code, and the module author does not need to worry about it. + +When tracing is enabled, kstop_machine is called to prevent races +with the CPUS executing code being modified (which can cause the +CPU to do undesireable things), and the nops are patched back +to calls. But this time, they do not call mcount (which is just +a function stub). They now call into the ftrace infrastructure. One special side-effect to the recording of the functions being traced is that we can now selectively choose which functions we @@ -1150,7 +1251,11 @@ These are the only wild cards which are supported. <match>*<match> will not work. - # echo hrtimer_* > /debug/tracing/set_ftrace_filter +Note: It is better to use quotes to enclose the wild cards, otherwise + the shell may expand the parameters into names of files in the local + directory. + + # echo 'hrtimer_*' > /debug/tracing/set_ftrace_filter Produces: @@ -1205,7 +1310,7 @@ Again, now we want to append. # echo sys_nanosleep > /debug/tracing/set_ftrace_filter # cat /debug/tracing/set_ftrace_filter sys_nanosleep - # echo hrtimer_* >> /debug/tracing/set_ftrace_filter + # echo 'hrtimer_*' >> /debug/tracing/set_ftrace_filter # cat /debug/tracing/set_ftrace_filter hrtimer_run_queues hrtimer_run_pending @@ -1248,36 +1353,6 @@ Produces: We can see that there's no more lock or preempt tracing. -ftraced -------- - -As mentioned above, when dynamic ftrace is configured in, a kernel -thread wakes up once a second and checks to see if there are mcount -calls that need to be converted into nops. If there are not any, then -it simply goes back to sleep. But if there are some, it will call -kstop_machine to convert the calls to nops. - -There may be a case in which you do not want this added latency. -Perhaps you are doing some audio recording and this activity might -cause skips in the playback. There is an interface to disable -and enable the "ftraced" kernel thread. - - # echo 0 > /debug/tracing/ftraced_enabled - -This will disable the calling of kstop_machine to update the -mcount calls to nops. Remember that there is a large overhead -to calling mcount. Without this kernel thread, that overhead will -exist. - -If there are recorded calls to mcount, any write to the ftraced_enabled -file will cause the kstop_machine to run. This means that a -user can manually perform the updates when they want to by simply -echoing a '0' into the ftraced_enabled file. - -The updates are also done at the beginning of enabling a tracer -that uses ftrace function recording. - - trace_pipe ---------- @@ -1286,14 +1361,14 @@ on the tracing is different. Every read from trace_pipe is consumed. This means that subsequent reads will be different. The trace is live. - # echo ftrace > /debug/tracing/current_tracer + # echo function > /debug/tracing/current_tracer # cat /debug/tracing/trace_pipe > /tmp/trace.out & [1] 4153 # echo 1 > /debug/tracing/tracing_enabled # usleep 1 # echo 0 > /debug/tracing/tracing_enabled # cat /debug/tracing/trace -# tracer: ftrace +# tracer: function # # TASK-PID CPU# TIMESTAMP FUNCTION # | | | | | @@ -1314,48 +1389,36 @@ is live. Note, reading the trace_pipe file will block until more input is added. By changing the tracer, trace_pipe will issue an EOF. We needed -to set the ftrace tracer _before_ cating the trace_pipe file. +to set the function tracer _before_ we "cat" the trace_pipe file. trace entries ------------- Having too much or not enough data can be troublesome in diagnosing -an issue in the kernel. The file trace_entries is used to modify +an issue in the kernel. The file buffer_size_kb is used to modify the size of the internal trace buffers. The number listed is the number of entries that can be recorded per CPU. To know the full size, multiply the number of possible CPUS with the number of entries. - # cat /debug/tracing/trace_entries -65620 + # cat /debug/tracing/buffer_size_kb +1408 (units kilobytes) Note, to modify this, you must have tracing completely disabled. To do that, -echo "none" into the current_tracer. If the current_tracer is not set -to "none", an EINVAL error will be returned. - - # echo none > /debug/tracing/current_tracer - # echo 100000 > /debug/tracing/trace_entries - # cat /debug/tracing/trace_entries -100045 - - -Notice that we echoed in 100,000 but the size is 100,045. The entries -are held in individual pages. It allocates the number of pages it takes -to fulfill the request. If more entries may fit on the last page -then they will be added. - - # echo 1 > /debug/tracing/trace_entries - # cat /debug/tracing/trace_entries -85 +echo "nop" into the current_tracer. If the current_tracer is not set +to "nop", an EINVAL error will be returned. -This shows us that 85 entries can fit in a single page. + # echo nop > /debug/tracing/current_tracer + # echo 10000 > /debug/tracing/buffer_size_kb + # cat /debug/tracing/buffer_size_kb +10000 (units kilobytes) The number of pages which will be allocated is limited to a percentage of available memory. Allocating too much will produce an error. - # echo 1000000000000 > /debug/tracing/trace_entries + # echo 1000000000000 > /debug/tracing/buffer_size_kb -bash: echo: write error: Cannot allocate memory - # cat /debug/tracing/trace_entries + # cat /debug/tracing/buffer_size_kb 85 diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt index 18022e249c5..b1b98870124 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio.txt @@ -240,6 +240,10 @@ signal, or (b) something wrongly believes it's safe to remove drivers needed to manage a signal that's in active use. That is, requesting a GPIO can serve as a kind of lock. +Some platforms may also use knowledge about what GPIOs are active for +power management, such as by powering down unused chip sectors and, more +easily, gating off unused clocks. + These two calls are optional because not not all current Linux platforms offer such functionality in their GPIO support; a valid implementation could return success for all gpio_request() calls. Unlike the other calls, @@ -264,7 +268,7 @@ map between them using calls like: /* map GPIO numbers to IRQ numbers */ int gpio_to_irq(unsigned gpio); - /* map IRQ numbers to GPIO numbers */ + /* map IRQ numbers to GPIO numbers (avoid using this) */ int irq_to_gpio(unsigned irq); Those return either the corresponding number in the other namespace, or @@ -284,7 +288,8 @@ system wakeup capabilities. Non-error values returned from irq_to_gpio() would most commonly be used with gpio_get_value(), for example to initialize or update driver state -when the IRQ is edge-triggered. +when the IRQ is edge-triggered. Note that some platforms don't support +this reverse mapping, so you should avoid using it. Emulating Open Drain Signals diff --git a/Documentation/hwmon/adt7462 b/Documentation/hwmon/adt7462 new file mode 100644 index 00000000000..ec660b32827 --- /dev/null +++ b/Documentation/hwmon/adt7462 @@ -0,0 +1,67 @@ +Kernel driver adt7462 +====================== + +Supported chips: + * Analog Devices ADT7462 + Prefix: 'adt7462' + Addresses scanned: I2C 0x58, 0x5C + Datasheet: Publicly available at the Analog Devices website + +Author: Darrick J. Wong + +Description +----------- + +This driver implements support for the Analog Devices ADT7462 chip family. + +This chip is a bit of a beast. It has 8 counters for measuring fan speed. It +can also measure 13 voltages or 4 temperatures, or various combinations of the +two. See the chip documentation for more details about the exact set of +configurations. This driver does not allow one to configure the chip; that is +left to the system designer. + +A sophisticated control system for the PWM outputs is designed into the ADT7462 +that allows fan speed to be adjusted automatically based on any of the three +temperature sensors. Each PWM output is individually adjustable and +programmable. Once configured, the ADT7462 will adjust the PWM outputs in +response to the measured temperatures without further host intervention. This +feature can also be disabled for manual control of the PWM's. + +Each of the measured inputs (voltage, temperature, fan speed) has +corresponding high/low limit values. The ADT7462 will signal an ALARM if +any measured value exceeds either limit. + +The ADT7462 samples all inputs continuously. The driver will not read +the registers more often than once every other second. Further, +configuration data is only read once per minute. + +Special Features +---------------- + +The ADT7462 have a 10-bit ADC and can therefore measure temperatures +with 0.25 degC resolution. + +The Analog Devices datasheet is very detailed and describes a procedure for +determining an optimal configuration for the automatic PWM control. + +The driver will report sensor labels when it is able to determine that +information from the configuration registers. + +Configuration Notes +------------------- + +Besides standard interfaces driver adds the following: + +* PWM Control + +* pwm#_auto_point1_pwm and temp#_auto_point1_temp and +* pwm#_auto_point2_pwm and temp#_auto_point2_temp - + +point1: Set the pwm speed at a lower temperature bound. +point2: Set the pwm speed at a higher temperature bound. + +The ADT7462 will scale the pwm between the lower and higher pwm speed when +the temperature is between the two temperature boundaries. PWM values range +from 0 (off) to 255 (full speed). Fan speed will be set to maximum when the +temperature sensor associated with the PWM control exceeds temp#_max. + diff --git a/Documentation/hwmon/adt7470 b/Documentation/hwmon/adt7470 new file mode 100644 index 00000000000..75d13ca147c --- /dev/null +++ b/Documentation/hwmon/adt7470 @@ -0,0 +1,76 @@ +Kernel driver adt7470 +===================== + +Supported chips: + * Analog Devices ADT7470 + Prefix: 'adt7470' + Addresses scanned: I2C 0x2C, 0x2E, 0x2F + Datasheet: Publicly available at the Analog Devices website + +Author: Darrick J. Wong + +Description +----------- + +This driver implements support for the Analog Devices ADT7470 chip. There may +be other chips that implement this interface. + +The ADT7470 uses the 2-wire interface compatible with the SMBus 2.0 +specification. Using an analog to digital converter it measures up to ten (10) +external temperatures. It has four (4) 16-bit counters for measuring fan speed. +There are four (4) PWM outputs that can be used to control fan speed. + +A sophisticated control system for the PWM outputs is designed into the ADT7470 +that allows fan speed to be adjusted automatically based on any of the ten +temperature sensors. Each PWM output is individually adjustable and +programmable. Once configured, the ADT7470 will adjust the PWM outputs in +response to the measured temperatures with further host intervention. This +feature can also be disabled for manual control of the PWM's. + +Each of the measured inputs (temperature, fan speed) has corresponding high/low +limit values. The ADT7470 will signal an ALARM if any measured value exceeds +either limit. + +The ADT7470 DOES NOT sample all inputs continuously. A single pin on the +ADT7470 is connected to a multitude of thermal diodes, but the chip must be +instructed explicitly to read the multitude of diodes. If you want to use +automatic fan control mode, you must manually read any of the temperature +sensors or the fan control algorithm will not run. The chip WILL NOT DO THIS +AUTOMATICALLY; this must be done from userspace. This may be a bug in the chip +design, given that many other AD chips take care of this. The driver will not +read the registers more often than once every 5 seconds. Further, +configuration data is only read once per minute. + +Special Features +---------------- + +The ADT7470 has a 8-bit ADC and is capable of measuring temperatures with 1 +degC resolution. + +The Analog Devices datasheet is very detailed and describes a procedure for +determining an optimal configuration for the automatic PWM control. + +Configuration Notes +------------------- + +Besides standard interfaces driver adds the following: + +* PWM Control + +* pwm#_auto_point1_pwm and pwm#_auto_point1_temp and +* pwm#_auto_point2_pwm and pwm#_auto_point2_temp - + +point1: Set the pwm speed at a lower temperature bound. +point2: Set the pwm speed at a higher temperature bound. + +The ADT7470 will scale the pwm between the lower and higher pwm speed when +the temperature is between the two temperature boundaries. PWM values range +from 0 (off) to 255 (full speed). Fan speed will be set to maximum when the +temperature sensor associated with the PWM control exceeds +pwm#_auto_point2_temp. + +Notes +----- + +As stated above, the temperature inputs must be read periodically from +userspace in order for the automatic pwm algorithm to run. diff --git a/Documentation/hwmon/it87 b/Documentation/hwmon/it87 index 3496b7020e7..042c0415140 100644 --- a/Documentation/hwmon/it87 +++ b/Documentation/hwmon/it87 @@ -136,10 +136,10 @@ once-only alarms. The IT87xx only updates its values each 1.5 seconds; reading it more often will do no harm, but will return 'old' values. -To change sensor N to a thermistor, 'echo 2 > tempN_type' where N is 1, 2, +To change sensor N to a thermistor, 'echo 4 > tempN_type' where N is 1, 2, or 3. To change sensor N to a thermal diode, 'echo 3 > tempN_type'. Give 0 for unused sensor. Any other value is invalid. To configure this at -startup, consult lm_sensors's /etc/sensors.conf. (2 = thermistor; +startup, consult lm_sensors's /etc/sensors.conf. (4 = thermistor; 3 = thermal diode) diff --git a/Documentation/hwmon/lis3lv02d b/Documentation/hwmon/lis3lv02d new file mode 100644 index 00000000000..65dfb0c0fd6 --- /dev/null +++ b/Documentation/hwmon/lis3lv02d @@ -0,0 +1,49 @@ +Kernel driver lis3lv02d +================== + +Supported chips: + + * STMicroelectronics LIS3LV02DL and LIS3LV02DQ + +Author: + Yan Burman <burman.yan@gmail.com> + Eric Piel <eric.piel@tremplin-utc.net> + + +Description +----------- + +This driver provides support for the accelerometer found in various HP laptops +sporting the feature officially called "HP Mobile Data Protection System 3D" or +"HP 3D DriveGuard". It detect automatically laptops with this sensor. Known models +(for now the HP 2133, nc6420, nc2510, nc8510, nc84x0, nw9440 and nx9420) will +have their axis automatically oriented on standard way (eg: you can directly +play neverball). The accelerometer data is readable via +/sys/devices/platform/lis3lv02d. + +Sysfs attributes under /sys/devices/platform/lis3lv02d/: +position - 3D position that the accelerometer reports. Format: "(x,y,z)" +calibrate - read: values (x, y, z) that are used as the base for input class device operation. + write: forces the base to be recalibrated with the current position. +rate - reports the sampling rate of the accelerometer device in HZ + +This driver also provides an absolute input class device, allowing +the laptop to act as a pinball machine-esque joystick. + +Axes orientation +---------------- + +For better compatibility between the various laptops. The values reported by +the accelerometer are converted into a "standard" organisation of the axes +(aka "can play neverball out of the box"): + * When the laptop is horizontal the position reported is about 0 for X and Y +and a positive value for Z + * If the left side is elevated, X increases (becomes positive) + * If the front side (where the touchpad is) is elevated, Y decreases (becomes negative) + * If the laptop is put upside-down, Z becomes negative + +If your laptop model is not recognized (cf "dmesg"), you can send an email to the +authors to add it to the database. When reporting a new laptop, please include +the output of "dmidecode" plus the value of /sys/devices/platform/lis3lv02d/position +in these four cases. + diff --git a/Documentation/hwmon/lm85 b/Documentation/hwmon/lm85 index 6d41db7f17f..40062074129 100644 --- a/Documentation/hwmon/lm85 +++ b/Documentation/hwmon/lm85 @@ -163,16 +163,6 @@ configured individually according to the following options. * pwm#_auto_pwm_min - this specifies the PWM value for temp#_auto_temp_off temperature. (PWM value from 0 to 255) -* pwm#_auto_pwm_freq - select base frequency of PWM output. You can select - in range of 10.0 to 94.0 Hz in .1 Hz units. - (Values 100 to 940). - -The pwm#_auto_pwm_freq can be set to one of the following 8 values. Setting the -frequency to a value not on this list, will result in the next higher frequency -being selected. The actual device frequency may vary slightly from this -specification as designed by the manufacturer. Consult the datasheet for more -details. (PWM Frequency values: 100, 150, 230, 300, 380, 470, 620, 940) - * pwm#_auto_pwm_minctl - this flags selects for temp#_auto_temp_off temperature the bahaviour of fans. Write 1 to let fans spinning at pwm#_auto_pwm_min or write 0 to let them off. diff --git a/Documentation/hwmon/lm87 b/Documentation/hwmon/lm87 index ec27aa1b94c..6b47b67fd96 100644 --- a/Documentation/hwmon/lm87 +++ b/Documentation/hwmon/lm87 @@ -65,11 +65,10 @@ The LM87 has four pins which can serve one of two possible functions, depending on the hardware configuration. Some functions share pins, so not all functions are available at the same -time. Which are depends on the hardware setup. This driver assumes that -the BIOS configured the chip correctly. In that respect, it differs from -the original driver (from lm_sensors for Linux 2.4), which would force the -LM87 to an arbitrary, compile-time chosen mode, regardless of the actual -chipset wiring. +time. Which are depends on the hardware setup. This driver normally +assumes that firmware configured the chip correctly. Where this is not +the case, platform code must set the I2C client's platform_data to point +to a u8 value to be written to the channel register. For reference, here is the list of exclusive functions: - in0+in5 (default) or temp3 diff --git a/Documentation/hwmon/lm90 b/Documentation/hwmon/lm90 index aa4a0ec2008..0e841171023 100644 --- a/Documentation/hwmon/lm90 +++ b/Documentation/hwmon/lm90 @@ -8,10 +8,10 @@ Supported chips: Datasheet: Publicly available at the National Semiconductor website http://www.national.com/pf/LM/LM90.html * National Semiconductor LM89 - Prefix: 'lm99' + Prefix: 'lm89' (no auto-detection) Addresses scanned: I2C 0x4c and 0x4d Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/pf/LM/LM89.html + http://www.national.com/mpf/LM/LM89.html * National Semiconductor LM99 Prefix: 'lm99' Addresses scanned: I2C 0x4c and 0x4d @@ -21,18 +21,32 @@ Supported chips: Prefix: 'lm86' Addresses scanned: I2C 0x4c Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/pf/LM/LM86.html + http://www.national.com/mpf/LM/LM86.html * Analog Devices ADM1032 Prefix: 'adm1032' Addresses scanned: I2C 0x4c and 0x4d - Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/en/prod/0,2877,ADM1032,00.html + Datasheet: Publicly available at the ON Semiconductor website + http://www.onsemi.com/PowerSolutions/product.do?id=ADM1032 * Analog Devices ADT7461 Prefix: 'adt7461' Addresses scanned: I2C 0x4c and 0x4d - Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/en/prod/0,2877,ADT7461,00.html - Note: Only if in ADM1032 compatibility mode + Datasheet: Publicly available at the ON Semiconductor website + http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461 + * Maxim MAX6646 + Prefix: 'max6646' + Addresses scanned: I2C 0x4d + Datasheet: Publicly available at the Maxim website + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497 + * Maxim MAX6647 + Prefix: 'max6646' + Addresses scanned: I2C 0x4e + Datasheet: Publicly available at the Maxim website + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497 + * Maxim MAX6649 + Prefix: 'max6646' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at the Maxim website + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497 * Maxim MAX6657 Prefix: 'max6657' Addresses scanned: I2C 0x4c @@ -70,25 +84,21 @@ Description The LM90 is a digital temperature sensor. It senses its own temperature as well as the temperature of up to one external diode. It is compatible -with many other devices such as the LM86, the LM89, the LM99, the ADM1032, -the MAX6657, MAX6658, MAX6659, MAX6680 and the MAX6681 all of which are -supported by this driver. +with many other devices, many of which are supported by this driver. Note that there is no easy way to differentiate between the MAX6657, MAX6658 and MAX6659 variants. The extra address and features of the MAX6659 are not supported by this driver. The MAX6680 and MAX6681 only differ in their pinout, therefore they obviously can't (and don't need to) -be distinguished. Additionally, the ADT7461 is supported if found in -ADM1032 compatibility mode. +be distinguished. The specificity of this family of chipsets over the ADM1021/LM84 family is that it features critical limits with hysteresis, and an increased resolution of the remote temperature measurement. The different chipsets of the family are not strictly identical, although -very similar. This driver doesn't handle any specific feature for now, -with the exception of SMBus PEC. For reference, here comes a non-exhaustive -list of specific features: +very similar. For reference, here comes a non-exhaustive list of specific +features: LM90: * Filter and alert configuration register at 0xBF. @@ -114,9 +124,11 @@ ADT7461: * Lower resolution for remote temperature MAX6657 and MAX6658: + * Better local resolution * Remote sensor type selection MAX6659: + * Better local resolution * Selectable address * Second critical temperature limit * Remote sensor type selection @@ -127,7 +139,8 @@ MAX6680 and MAX6681: All temperature values are given in degrees Celsius. Resolution is 1.0 degree for the local temperature, 0.125 degree for the remote -temperature. +temperature, except for the MAX6657, MAX6658 and MAX6659 which have a +resolution of 0.125 degree for both temperatures. Each sensor has its own high and low limits, plus a critical limit. Additionally, there is a relative hysteresis value common to both critical diff --git a/Documentation/hwmon/pc87360 b/Documentation/hwmon/pc87360 index 89a8fcfa78d..cbac32b59c8 100644 --- a/Documentation/hwmon/pc87360 +++ b/Documentation/hwmon/pc87360 @@ -5,12 +5,7 @@ Supported chips: * National Semiconductor PC87360, PC87363, PC87364, PC87365 and PC87366 Prefixes: 'pc87360', 'pc87363', 'pc87364', 'pc87365', 'pc87366' Addresses scanned: none, address read from Super I/O config space - Datasheets: - http://www.national.com/pf/PC/PC87360.html - http://www.national.com/pf/PC/PC87363.html - http://www.national.com/pf/PC/PC87364.html - http://www.national.com/pf/PC/PC87365.html - http://www.national.com/pf/PC/PC87366.html + Datasheets: No longer available Authors: Jean Delvare <khali@linux-fr.org> diff --git a/Documentation/hwmon/pc87427 b/Documentation/hwmon/pc87427 index 9a0708f9f49..d1ebbe510f3 100644 --- a/Documentation/hwmon/pc87427 +++ b/Documentation/hwmon/pc87427 @@ -5,7 +5,7 @@ Supported chips: * National Semiconductor PC87427 Prefix: 'pc87427' Addresses scanned: none, address read from Super I/O config space - Datasheet: http://www.winbond.com.tw/E-WINBONDHTM/partner/apc_007.html + Datasheet: No longer available Author: Jean Delvare <khali@linux-fr.org> diff --git a/Documentation/hwmon/w83781d b/Documentation/hwmon/w83781d index 6f800a0283e..c91e0b63ea1 100644 --- a/Documentation/hwmon/w83781d +++ b/Documentation/hwmon/w83781d @@ -353,7 +353,7 @@ in6=255 # PWM -Additional info about PWM on the AS99127F (may apply to other Asus +* Additional info about PWM on the AS99127F (may apply to other Asus chips as well) by Jean Delvare as of 2004-04-09: AS99127F revision 2 seems to have two PWM registers at 0x59 and 0x5A, @@ -396,7 +396,7 @@ Please contact us if you can figure out how it is supposed to work. As long as we don't know more, the w83781d driver doesn't handle PWM on AS99127F chips at all. -Additional info about PWM on the AS99127F rev.1 by Hector Martin: +* Additional info about PWM on the AS99127F rev.1 by Hector Martin: I've been fiddling around with the (in)famous 0x59 register and found out the following values do work as a form of coarse pwm: @@ -418,3 +418,36 @@ change. My mobo is an ASUS A7V266-E. This behavior is similar to what I got with speedfan under Windows, where 0-15% would be off, 15-2x% (can't remember the exact value) would be 70% and higher would be full on. + +* Additional info about PWM on the AS99127F rev.1 from lm-sensors + ticket #2350: + +I conducted some experiment on Asus P3B-F motherboard with AS99127F +(Ver. 1). + +I confirm that 0x59 register control the CPU_Fan Header on this +motherboard, and 0x5a register control PWR_Fan. + +In order to reduce the dependency of specific fan, the measurement is +conducted with a digital scope without fan connected. I found out that +P3B-F actually output variable DC voltage on fan header center pin, +looks like PWM is filtered on this motherboard. + +Here are some of measurements: + +0x80 20 mV +0x81 20 mV +0x82 232 mV +0x83 1.2 V +0x84 2.31 V +0x85 3.44 V +0x86 4.62 V +0x87 5.81 V +0x88 7.01 V +9x89 8.22 V +0x8a 9.42 V +0x8b 10.6 V +0x8c 11.9 V +0x8d 12.4 V +0x8e 12.4 V +0x8f 12.4 V diff --git a/Documentation/hwmon/w83791d b/Documentation/hwmon/w83791d index a67d3b7a709..5663e491655 100644 --- a/Documentation/hwmon/w83791d +++ b/Documentation/hwmon/w83791d @@ -58,29 +58,35 @@ 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, five fan rotation speed -sensors, and ten voltage sensors. +The driver implements three temperature sensors, ten voltage sensors, +five fan rotation speed sensors and manual PWM control of each fan. 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. +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. + 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 for all fans) 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. +Each fan controlled is controlled by PWM. The PWM duty cycle can be read and +set for each fan separately. Valid values range from 0 (stop) to 255 (full). +PWM 1-3 support Thermal Cruise mode, in which the PWMs are automatically +regulated to keep respectively temp 1-3 at a certain target temperature. +See below for the description of the sysfs-interface. The w83791d has a global bit used to enable beeping from the speaker when an alarm is triggered as well as a bitmask to enable or disable the beep for specific alarms. You need both the global beep enable bit and the corresponding beep bit to be on for a triggered alarm to sound a beep. -The sysfs interface to the gloabal enable is via the sysfs beep_enable file. +The sysfs interface to the global enable is via the sysfs beep_enable file. This file is used for both legacy and new code. The sysfs interface to the beep bitmask has migrated from the original legacy @@ -105,6 +111,27 @@ going forward. The driver reads the hardware chip values at most once every three seconds. User mode code requesting values more often will receive cached values. +/sys files +---------- +The sysfs-interface is documented in the 'sysfs-interface' file. Only +chip-specific options are documented here. + +pwm[1-3]_enable - this file controls mode of fan/temperature control for + fan 1-3. Fan/PWM 4-5 only support manual mode. + * 1 Manual mode + * 2 Thermal Cruise mode + * 3 Fan Speed Cruise mode (no further support) + +temp[1-3]_target - defines the target temperature for Thermal Cruise mode. + Unit: millidegree Celsius + RW + +temp[1-3]_tolerance - temperature tolerance for Thermal Cruise mode. + Specifies an interval around the target temperature + in which the fan speed is not changed. + Unit: millidegree Celsius + RW + Alarms bitmap vs. beep_mask bitmask ------------------------------------ For legacy code using the alarms and beep_mask files: @@ -132,7 +159,3 @@ tart2 : alarms: 0x020000 beep_mask: 0x080000 <== mismatch tart3 : alarms: 0x040000 beep_mask: 0x100000 <== mismatch case_open : alarms: 0x001000 beep_mask: 0x001000 global_enable: alarms: -------- beep_mask: 0x800000 (modified via beep_enable) - -W83791D TODO: ---------------- -Provide a patch for smart-fan control (still need appropriate motherboard/fans) diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index c31e0291e16..81c0c59a60e 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -13,8 +13,9 @@ Supported adapters: * Intel 631xESB/632xESB (ESB2) * Intel 82801H (ICH8) * Intel 82801I (ICH9) - * Intel Tolapai - * Intel ICH10 + * Intel EP80579 (Tolapai) + * Intel 82801JI (ICH10) + * Intel PCH Datasheets: Publicly available at the Intel website Authors: @@ -32,7 +33,7 @@ Description ----------- The ICH (properly known as the 82801AA), ICH0 (82801AB), ICH2 (82801BA), -ICH3 (82801CA/CAM) and later devices are Intel chips that are a part of +ICH3 (82801CA/CAM) and later devices (PCH) are Intel chips that are a part of Intel's '810' chipset for Celeron-based PCs, '810E' chipset for Pentium-based PCs, '815E' chipset, and others. diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x index 266481fd26e..70e6a0cc1e1 100644 --- a/Documentation/i2c/busses/i2c-sis96x +++ b/Documentation/i2c/busses/i2c-sis96x @@ -42,7 +42,7 @@ I suspect that this driver could be made to work for the following SiS chipsets as well: 635, and 635T. If anyone owns a board with those chips AND is willing to risk crashing & burning an otherwise well-behaved kernel in the name of progress... please contact me at <mhoffman@lightlink.com> or -via the project's mailing list: <i2c@lm-sensors.org>. Please send bug +via the linux-i2c mailing list: <linux-i2c@vger.kernel.org>. Please send bug reports and/or success stories as well. diff --git a/Documentation/i2c/porting-clients b/Documentation/i2c/porting-clients deleted file mode 100644 index 7bf82c08f6c..00000000000 --- a/Documentation/i2c/porting-clients +++ /dev/null @@ -1,160 +0,0 @@ -Revision 7, 2007-04-19 -Jean Delvare <khali@linux-fr.org> -Greg KH <greg@kroah.com> - -This is a guide on how to convert I2C chip drivers from Linux 2.4 to -Linux 2.6. I have been using existing drivers (lm75, lm78) as examples. -Then I converted a driver myself (lm83) and updated this document. -Note that this guide is strongly oriented towards hardware monitoring -drivers. Many points are still valid for other type of drivers, but -others may be irrelevant. - -There are two sets of points below. The first set concerns technical -changes. The second set concerns coding policy. Both are mandatory. - -Although reading this guide will help you porting drivers, I suggest -you keep an eye on an already ported driver while porting your own -driver. This will help you a lot understanding what this guide -exactly means. Choose the chip driver that is the more similar to -yours for best results. - -Technical changes: - -* [Driver type] Any driver that was relying on i2c-isa has to be - converted to a proper isa, platform or pci driver. This is not - covered by this guide. - -* [Includes] Get rid of "version.h" and <linux/i2c-proc.h>. - Includes typically look like that: - #include <linux/module.h> - #include <linux/init.h> - #include <linux/slab.h> - #include <linux/jiffies.h> - #include <linux/i2c.h> - #include <linux/hwmon.h> /* for hardware monitoring drivers */ - #include <linux/hwmon-sysfs.h> - #include <linux/hwmon-vid.h> /* if you need VRM support */ - #include <linux/err.h> /* for class registration */ - 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, ISA addresses - are no more handled by the i2c core. Address ranges are no more - supported either, define each individual address separately. - SENSORS_INSMOD_<n> becomes I2C_CLIENT_INSMOD_<n>. - -* [Client data] Get rid of sysctl_id. Try using standard names for - register values (for example, temp_os becomes temp_max). You're - still relatively free here, but you *have* to follow the standard - names for sysfs files (see the Sysctl section below). - -* [Function prototypes] The detect functions loses its flags - parameter. Sysctl (e.g. lm75_temp) and miscellaneous functions - are off the list of prototypes. This usually leaves five - prototypes: - static int lm75_attach_adapter(struct i2c_adapter *adapter); - static int lm75_detect(struct i2c_adapter *adapter, int address, - int kind); - static void lm75_init_client(struct i2c_client *client); - static int lm75_detach_client(struct i2c_client *client); - static struct lm75_data lm75_update_device(struct device *dev); - -* [Sysctl] All sysctl stuff is of course gone (defines, ctl_table - and functions). Instead, you have to define show and set functions for - each sysfs file. Only define set for writable values. Take a look at an - existing 2.6 driver for details (it87 for example). Don't forget - to define the attributes for each file (this is that step that - links callback functions). Use the file names specified in - Documentation/hwmon/sysfs-interface for the individual files. Also - convert the units these files read and write to the specified ones. - If you need to add a new type of file, please discuss it on the - sensors mailing list <lm-sensors@lm-sensors.org> by providing a - patch to the Documentation/hwmon/sysfs-interface file. - -* [Attach] The attach function should make sure that the adapter's - class has I2C_CLASS_HWMON (or whatever class is suitable for your - driver), using the following construct: - if (!(adapter->class & I2C_CLASS_HWMON)) - return 0; - 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. - The labels used for error paths are reduced to the number needed. - It is advised that the labels are given descriptive names such as - exit and exit_free. Don't forget to properly set err before - jumping to error labels. By the way, labels should be left-aligned. - Use kzalloc instead of kmalloc. - Use i2c_set_clientdata to set the client data (as opposed to - a direct access to client->data). - Use strlcpy instead of strcpy or snprintf to copy the client name. - Replace the sysctl directory registration by calls to - device_create_file. Move the driver initialization before any - sysfs file creation. - Register the client with the hwmon class (using hwmon_device_register) - if applicable. - 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. - Don't add I2C_CLIENT_ALLOW_USE to client->flags, it's the default now. - -* [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 - parameter may be used to force it), and initialization should be - limited to the strictly necessary steps. - -* [Detach] Remove the call to i2c_deregister_entry. Do not log an - error message if i2c_detach_client fails, as i2c-core will now do - it for you. - Unregister from the hwmon class if applicable. - -* [Update] The function prototype changed, it is now - passed a device structure, which you have to convert to a client - using to_i2c_client(dev). The update function should return a - pointer to the client data. - Don't access client->data directly, use i2c_get_clientdata(client) - instead. - Use time_after() instead of direct jiffies comparison. - -* [Interface] Make sure there is a MODULE_LICENSE() line, at the bottom - of the file (after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this - order). - -* [Driver] The flags field of the i2c_driver structure is gone. - I2C_DF_NOTIFY is now the default behavior. - The i2c_driver structure has a driver member, which is itself a - structure, those name member should be initialized to a driver name - string. i2c_driver itself has no name member anymore. - -* [Driver model] Instead of shutdown or reboot notifiers, provide a - shutdown() method in your driver. - -* [Power management] Use the driver model suspend() and resume() - callbacks instead of the obsolete pm_register() calls. - -Coding policy: - -* [Copyright] Use (C), not (c), for copyright. - -* [Debug/log] Get rid of #ifdef DEBUG/#endif constructs whenever you - can. Calls to printk for debugging purposes are replaced by calls to - dev_dbg where possible, else to pr_debug. Here is an example of how - to call it (taken from lm75_detect): - dev_dbg(&client->dev, "Starting lm75 update\n"); - Replace other printk calls with the dev_info, dev_err or dev_warn - function, as appropriate. - -* [Constants] Constants defines (registers, conversions) should be - aligned. This greatly improves readability. - Alignments are achieved by the means of tabs, not spaces. Remember - that tabs are set to 8 in the Linux kernel code. - -* [Layout] Avoid extra empty lines between comments and what they - comment. Respect the coding style (see Documentation/CodingStyle), - in particular when it comes to placing curly braces. - -* [Comments] Make sure that no comment refers to a file that isn't - part of the Linux source tree (typically doc/chips/<chip name>), - and that remaining comments still match the code. Merging comment - lines when possible is encouraged. diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients index d73ee117a8c..6b9af7d479c 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients @@ -10,23 +10,21 @@ General remarks =============== Try to keep the kernel namespace as clean as possible. The best way to -do this is to use a unique prefix for all global symbols. This is +do this is to use a unique prefix for all global symbols. This is especially important for exported symbols, but it is a good idea to do it for non-exported symbols too. We will use the prefix `foo_' in this -tutorial, and `FOO_' for preprocessor variables. +tutorial. The driver structure ==================== Usually, you will implement a single driver structure, and instantiate -all clients from it. Remember, a driver structure contains general access +all clients from it. Remember, a driver structure contains general access routines, and should be zero-initialized except for fields with data you provide. A client structure holds device-specific information like the driver model device node, and its I2C address. -/* iff driver uses driver model ("new style") binding model: */ - static struct i2c_device_id foo_idtable[] = { { "foo", my_id_for_foo }, { "bar", my_id_for_bar }, @@ -40,7 +38,6 @@ static struct i2c_driver foo_driver = { .name = "foo", }, - /* iff driver uses driver model ("new style") binding model: */ .id_table = foo_ids, .probe = foo_probe, .remove = foo_remove, @@ -49,24 +46,19 @@ static struct i2c_driver foo_driver = { .detect = foo_detect, .address_data = &addr_data, - /* else, driver uses "legacy" binding model: */ - .attach_adapter = foo_attach_adapter, - .detach_client = foo_detach_client, - - /* these may be used regardless of the driver binding model */ .shutdown = foo_shutdown, /* optional */ .suspend = foo_suspend, /* optional */ .resume = foo_resume, /* optional */ - .command = foo_command, /* optional */ + .command = foo_command, /* optional, deprecated */ } - + The name field is the driver name, and must not contain spaces. It should match the module name (if the driver can be compiled as a module), although you can use MODULE_ALIAS (passing "foo" in this example) to add another name for the module. If the driver name doesn't match the module name, the module won't be automatically loaded (hotplug/coldplug). -All other fields are for call-back functions which will be explained +All other fields are for call-back functions which will be explained below. @@ -74,34 +66,13 @@ Extra client data ================= Each client structure has a special `data' field that can point to any -structure at all. You should use this to keep device-specific data, -especially in drivers that handle multiple I2C or SMBUS devices. You -do not always need this, but especially for `sensors' drivers, it can -be very useful. +structure at all. You should use this to keep device-specific data. /* store the value */ void i2c_set_clientdata(struct i2c_client *client, void *data); /* retrieve the value */ - void *i2c_get_clientdata(struct i2c_client *client); - -An example structure is below. - - struct foo_data { - struct i2c_client client; - enum chips type; /* To keep the chips type for `sensors' drivers. */ - - /* Because the i2c bus is slow, it is often useful to cache the read - information of a chip for some time (for example, 1 or 2 seconds). - It depends of course on the device whether this is really worthwhile - or even sensible. */ - struct mutex update_lock; /* When we are reading lots of information, - another process should not update the - below information */ - char valid; /* != 0 if the following fields are valid. */ - unsigned long last_updated; /* In jiffies */ - /* Add the read information here too */ - }; + void *i2c_get_clientdata(const struct i2c_client *client); Accessing the client @@ -109,11 +80,9 @@ Accessing the client Let's say we have a valid client structure. At some time, we will need to gather information from the client, or write new information to the -client. How we will export this information to user-space is less -important at this moment (perhaps we do not need to do this at all for -some obscure clients). But we need generic reading and writing routines. +client. -I have found it useful to define foo_read and foo_write function for this. +I have found it useful to define foo_read and foo_write functions for this. For some cases, it will be easier to call the i2c functions directly, but many chips have some kind of register-value idea that can easily be encapsulated. @@ -121,33 +90,33 @@ be encapsulated. The below functions are simple examples, and should not be copied literally. - int foo_read_value(struct i2c_client *client, u8 reg) - { - if (reg < 0x10) /* byte-sized register */ - return i2c_smbus_read_byte_data(client,reg); - else /* word-sized register */ - return i2c_smbus_read_word_data(client,reg); - } - - int foo_write_value(struct i2c_client *client, u8 reg, u16 value) - { - if (reg == 0x10) /* Impossible to write - driver error! */ { - return -1; - else if (reg < 0x10) /* byte-sized register */ - return i2c_smbus_write_byte_data(client,reg,value); - else /* word-sized register */ - return i2c_smbus_write_word_data(client,reg,value); - } +int foo_read_value(struct i2c_client *client, u8 reg) +{ + if (reg < 0x10) /* byte-sized register */ + return i2c_smbus_read_byte_data(client, reg); + else /* word-sized register */ + return i2c_smbus_read_word_data(client, reg); +} + +int foo_write_value(struct i2c_client *client, u8 reg, u16 value) +{ + if (reg == 0x10) /* Impossible to write - driver error! */ + return -EINVAL; + else if (reg < 0x10) /* byte-sized register */ + return i2c_smbus_write_byte_data(client, reg, value); + else /* word-sized register */ + return i2c_smbus_write_word_data(client, reg, value); +} Probing and attaching ===================== The Linux I2C stack was originally written to support access to hardware -monitoring chips on PC motherboards, and thus it embeds some assumptions -that are more appropriate to SMBus (and PCs) than to I2C. One of these -assumptions is that most adapters and devices drivers support the SMBUS_QUICK -protocol to probe device presence. Another is that devices and their drivers +monitoring chips on PC motherboards, and thus used to embed some assumptions +that were more appropriate to SMBus (and PCs) than to I2C. One of these +assumptions was that most adapters and devices drivers support the SMBUS_QUICK +protocol to probe device presence. Another was that devices and their drivers can be sufficiently configured using only such probe primitives. As Linux and its I2C stack became more widely used in embedded systems @@ -164,6 +133,9 @@ since the "legacy" model requires drivers to create "i2c_client" device objects after SMBus style probing, while the Linux driver model expects drivers to be given such device objects in their probe() routines. +The legacy model is deprecated now and will soon be removed, so we no +longer document it here. + Standard Driver Model Binding ("New Style") ------------------------------------------- @@ -193,8 +165,8 @@ matches the device's name. It is passed the entry that was matched so the driver knows which one in the table matched. -Device Creation (Standard driver model) ---------------------------------------- +Device Creation +--------------- If you know for a fact that an I2C device is connected to a given I2C bus, you can instantiate that device by simply filling an i2c_board_info @@ -221,8 +193,8 @@ in the I2C bus driver. You may want to save the returned i2c_client reference for later use. -Device Detection (Standard driver model) ----------------------------------------- +Device Detection +---------------- Sometimes you do not know in advance which I2C devices are connected to a given I2C bus. This is for example the case of hardware monitoring @@ -246,8 +218,8 @@ otherwise misdetections are likely to occur and things can get wrong quickly. -Device Deletion (Standard driver model) ---------------------------------------- +Device Deletion +--------------- Each I2C device which has been created using i2c_new_device() or i2c_new_probed_device() can be unregistered by calling @@ -256,264 +228,37 @@ called automatically before the underlying I2C bus itself is removed, as a device can't survive its parent in the device driver model. -Legacy Driver Binding Model ---------------------------- +Initializing the driver +======================= + +When the kernel is booted, or when your foo driver module is inserted, +you have to do some initializing. Fortunately, just registering the +driver module is usually enough. -Most i2c devices can be present on several i2c addresses; for some this -is determined in hardware (by soldering some chip pins to Vcc or Ground), -for others this can be changed in software (by writing to specific client -registers). Some devices are usually on a specific address, but not always; -and some are even more tricky. So you will probably need to scan several -i2c addresses for your clients, and do some sort of detection to see -whether it is actually a device supported by your driver. +static int __init foo_init(void) +{ + return i2c_add_driver(&foo_driver); +} + +static void __exit foo_cleanup(void) +{ + i2c_del_driver(&foo_driver); +} + +/* Substitute your own name and email address */ +MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" +MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); -To give the user a maximum of possibilities, some default module parameters -are defined to help determine what addresses are scanned. Several macros -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() if you don't. - - -Probing classes (Legacy model) ------------------------------- - -All parameters are given as lists of unsigned 16-bit integers. Lists are -terminated by I2C_CLIENT_END. -The following lists are used internally: - - normal_i2c: filled in by the module writer. - A list of I2C addresses which should normally be examined. - probe: insmod parameter. - A list of pairs. The first value is a bus number (-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. - 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 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_<kind>. - -Fortunately, as a module writer, you just have to define the `normal_i2c' -parameter. The complete declaration could look like this: - - /* Scan 0x4c to 0x4f */ - static const unsigned short normal_i2c[] = { 0x4c, 0x4d, 0x4e, 0x4f, - I2C_CLIENT_END }; - - /* 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! - - -Attaching to an adapter (Legacy model) --------------------------------------- - -Whenever a new adapter is inserted, or for all adapters if the driver is -being registered, the callback attach_adapter() is called. Now is the -time to determine what devices are present on the adapter, and to register -a client for each of them. - -The attach_adapter callback is really easy: we just call the generic -detection function. This function will scan the bus for us, using the -information as defined in the lists explained above. If a device is -detected at a specific address, another callback is called. - - int foo_attach_adapter(struct i2c_adapter *adapter) - { - return i2c_probe(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 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. - - -The detect client function (Legacy model) ------------------------------------------ - -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. - -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. - - int foo_detect_client(struct i2c_adapter *adapter, int address, - int kind) - { - int err = 0; - int i; - struct i2c_client *client; - struct foo_data *data; - const char *name = ""; - - /* Let's see whether this adapter can support what we need. - Please substitute the things you need here! */ - if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA | - I2C_FUNC_SMBUS_WRITE_BYTE)) - goto ERROR0; - - /* OK. For now, we presume we have a valid client. We now create the - client structure, even though we cannot fill it completely yet. - But it allows us to access several i2c functions safely */ - - if (!(data = kzalloc(sizeof(struct foo_data), GFP_KERNEL))) { - err = -ENOMEM; - goto ERROR0; - } - - client = &data->client; - i2c_set_clientdata(client, data); - - client->addr = address; - client->adapter = adapter; - client->driver = &foo_driver; - - /* Now, we do the remaining detection. If no `force' parameter is used. */ - - /* First, the generic detection (if any), that is skipped if any force - parameter was used. */ - if (kind < 0) { - /* The below is of course bogus */ - if (foo_read(client, FOO_REG_GENERIC) != FOO_GENERIC_VALUE) - goto ERROR1; - } - - /* Next, specific detection. This is especially important for `sensors' - devices. */ - - /* Determine the chip type. Not needed if a `force_CHIPTYPE' parameter - was used. */ - if (kind <= 0) { - i = foo_read(client, FOO_REG_CHIPTYPE); - if (i == FOO_TYPE_1) - kind = chip1; /* As defined in the enum */ - else if (i == FOO_TYPE_2) - kind = chip2; - else { - printk("foo: Ignoring 'force' parameter for unknown chip at " - "adapter %d, address 0x%02x\n",i2c_adapter_id(adapter),address); - goto ERROR1; - } - } - - /* Now set the type and chip names */ - if (kind == chip1) { - name = "chip1"; - } else if (kind == chip2) { - name = "chip2"; - } - - /* Fill in the remaining client fields. */ - strlcpy(client->name, name, I2C_NAME_SIZE); - data->type = kind; - mutex_init(&data->update_lock); /* Only if you use this field */ - - /* Any other initializations in data must be done here too. */ - - /* This function can write default values to the client registers, if - needed. */ - foo_init_client(client); - - /* Tell the i2c layer a new client has arrived */ - if ((err = i2c_attach_client(client))) - goto ERROR1; - - return 0; - - /* OK, this is not exactly good programming practice, usually. But it is - very code-efficient in this case. */ - - ERROR1: - kfree(data); - ERROR0: - return err; - } - - -Removing the client (Legacy model) -================================== - -The detach_client call back function is called when a client should be -removed. It may actually fail, but only when panicking. This code is -much simpler than the attachment code, fortunately! - - int foo_detach_client(struct i2c_client *client) - { - int err; - - /* Try to detach the client from i2c space */ - if ((err = i2c_detach_client(client))) - return err; - - kfree(i2c_get_clientdata(client)); - return 0; - } - - -Initializing the module or kernel -================================= - -When the kernel is booted, or when your foo driver module is inserted, -you have to do some initializing. Fortunately, just attaching (registering) -the driver module is usually enough. - - static int __init foo_init(void) - { - int res; - - if ((res = i2c_add_driver(&foo_driver))) { - printk("foo: Driver registration failed, module not inserted.\n"); - return res; - } - return 0; - } - - static void __exit foo_cleanup(void) - { - i2c_del_driver(&foo_driver); - } - - /* Substitute your own name and email address */ - MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" - MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); - - /* a few non-GPL license types are also allowed */ - MODULE_LICENSE("GPL"); - - module_init(foo_init); - module_exit(foo_cleanup); - -Note that some functions are marked by `__init', and some data structures -by `__initdata'. These functions and structures can be removed after -kernel booting (or module loading) is completed. +/* a few non-GPL license types are also allowed */ +MODULE_LICENSE("GPL"); + +module_init(foo_init); +module_exit(foo_cleanup); + +Note that some functions are marked by `__init'. These functions can +be removed after kernel booting (or module loading) is completed. +Likewise, functions marked by `__exit' are dropped by the compiler when +the code is built into the kernel, as they would never be called. Power Management @@ -548,33 +293,35 @@ Command function A generic ioctl-like function call back is supported. You will seldom need this, and its use is deprecated anyway, so newer design should not -use it. Set it to NULL. +use it. Sending and receiving ===================== If you want to communicate with your device, there are several functions -to do this. You can find all of them in i2c.h. +to do this. You can find all of them in <linux/i2c.h>. -If you can choose between plain i2c communication and SMBus level -communication, please use the last. All adapters understand SMBus level -commands, but only some of them understand plain i2c! +If you can choose between plain I2C communication and SMBus level +communication, please use the latter. All adapters understand SMBus level +commands, but only some of them understand plain I2C! -Plain i2c communication +Plain I2C communication ----------------------- - extern int i2c_master_send(struct i2c_client *,const char* ,int); - extern int i2c_master_recv(struct i2c_client *,char* ,int); + int i2c_master_send(struct i2c_client *client, const char *buf, + int count); + int i2c_master_recv(struct i2c_client *client, char *buf, int count); These routines read and write some bytes from/to a client. The client contains the i2c address, so you do not have to include it. The second -parameter contains the bytes the read/write, the third the length of the -buffer. Returned is the actual number of bytes read/written. - - extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, - int num); +parameter contains the bytes to read/write, the third the number of bytes +to read/write (must be less than the length of the buffer.) Returned is +the actual number of bytes read/written. + + int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, + int num); This sends a series of messages. Each message can be a read or write, and they can be mixed in any way. The transactions are combined: no @@ -583,49 +330,45 @@ for each message the client address, the number of bytes of the message and the message data itself. You can read the file `i2c-protocol' for more information about the -actual i2c protocol. +actual I2C protocol. SMBus communication ------------------- - extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr, - unsigned short flags, - char read_write, u8 command, int size, - union i2c_smbus_data * data); - - This is the generic SMBus function. All functions below are implemented - in terms of it. Never use this function directly! - - - extern s32 i2c_smbus_read_byte(struct i2c_client * client); - extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value); - extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command); - extern s32 i2c_smbus_write_byte_data(struct i2c_client * client, - u8 command, u8 value); - extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command); - extern s32 i2c_smbus_write_word_data(struct i2c_client * client, - u8 command, u16 value); - extern s32 i2c_smbus_process_call(struct i2c_client *client, - u8 command, u16 value); - extern s32 i2c_smbus_read_block_data(struct i2c_client * client, - u8 command, u8 *values); - extern s32 i2c_smbus_write_block_data(struct i2c_client * client, - u8 command, u8 length, - u8 *values); - extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client, - u8 command, u8 length, u8 *values); - extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client, - u8 command, u8 length, - u8 *values); + s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, + unsigned short flags, char read_write, u8 command, + int size, union i2c_smbus_data *data); + +This is the generic SMBus function. All functions below are implemented +in terms of it. Never use this function directly! + + s32 i2c_smbus_read_byte(struct i2c_client *client); + s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value); + s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command); + s32 i2c_smbus_write_byte_data(struct i2c_client *client, + u8 command, u8 value); + s32 i2c_smbus_read_word_data(struct i2c_client *client, u8 command); + s32 i2c_smbus_write_word_data(struct i2c_client *client, + u8 command, u16 value); + s32 i2c_smbus_process_call(struct i2c_client *client, + u8 command, u16 value); + s32 i2c_smbus_read_block_data(struct i2c_client *client, + u8 command, u8 *values); + s32 i2c_smbus_write_block_data(struct i2c_client *client, + u8 command, u8 length, const u8 *values); + s32 i2c_smbus_read_i2c_block_data(struct i2c_client *client, + u8 command, u8 length, u8 *values); + s32 i2c_smbus_write_i2c_block_data(struct i2c_client *client, + u8 command, u8 length, + const u8 *values); These ones were removed from i2c-core because they had no users, but could be added back later if needed: - extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value); - extern s32 i2c_smbus_block_process_call(struct i2c_client *client, - u8 command, u8 length, - u8 *values) + s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value); + s32 i2c_smbus_block_process_call(struct i2c_client *client, + u8 command, u8 length, u8 *values); All these transactions return a negative errno value on failure. The 'write' transactions return 0 on success; the 'read' transactions return the read @@ -642,7 +385,5 @@ General purpose routines Below all general purpose routines are listed, that were not mentioned before. - /* This call returns a unique low identifier for each registered adapter. - */ - extern int i2c_adapter_id(struct i2c_adapter *adap); - + /* Return the adapter number for a specific adapter */ + int i2c_adapter_id(struct i2c_adapter *adap); diff --git a/Documentation/ia64/.gitignore b/Documentation/ia64/.gitignore new file mode 100644 index 00000000000..ab806edc873 --- /dev/null +++ b/Documentation/ia64/.gitignore @@ -0,0 +1 @@ +aliasing-test diff --git a/Documentation/ia64/kvm.txt b/Documentation/ia64/kvm.txt index 914d07f4926..84f7cb3d5be 100644 --- a/Documentation/ia64/kvm.txt +++ b/Documentation/ia64/kvm.txt @@ -1,7 +1,8 @@ -Currently, kvm module in EXPERIMENTAL stage on IA64. This means that -interfaces are not stable enough to use. So, plase had better don't run -critical applications in virtual machine. We will try our best to make it -strong in future versions! +Currently, kvm module is in EXPERIMENTAL stage on IA64. This means that +interfaces are not stable enough to use. So, please don't run critical +applications in virtual machine. +We will try our best to improve it in future versions! + Guide: How to boot up guests on kvm/ia64 This guide is to describe how to enable kvm support for IA-64 systems. diff --git a/Documentation/ia64/xen.txt b/Documentation/ia64/xen.txt new file mode 100644 index 00000000000..c61a99f7c8b --- /dev/null +++ b/Documentation/ia64/xen.txt @@ -0,0 +1,183 @@ + Recipe for getting/building/running Xen/ia64 with pv_ops + -------------------------------------------------------- + +This recipe describes how to get xen-ia64 source and build it, +and run domU with pv_ops. + +============ +Requirements +============ + + - python + - mercurial + it (aka "hg") is an open-source source code + management software. See the below. + http://www.selenic.com/mercurial/wiki/ + - git + - bridge-utils + +================================= +Getting and Building Xen and Dom0 +================================= + + My environment is; + Machine : Tiger4 + Domain0 OS : RHEL5 + DomainU OS : RHEL5 + + 1. Download source + # hg clone http://xenbits.xensource.com/ext/ia64/xen-unstable.hg + # cd xen-unstable.hg + # hg clone http://xenbits.xensource.com/ext/ia64/linux-2.6.18-xen.hg + + 2. # make world + + 3. # make install-tools + + 4. copy kernels and xen + # cp xen/xen.gz /boot/efi/efi/redhat/ + # cp build-linux-2.6.18-xen_ia64/vmlinux.gz \ + /boot/efi/efi/redhat/vmlinuz-2.6.18.8-xen + + 5. make initrd for Dom0/DomU + # make -C linux-2.6.18-xen.hg ARCH=ia64 modules_install \ + O=$(/bin/pwd)/build-linux-2.6.18-xen_ia64 + # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6.18.8-xen.img \ + 2.6.18.8-xen --builtin mptspi --builtin mptbase \ + --builtin mptscsih --builtin uhci-hcd --builtin ohci-hcd \ + --builtin ehci-hcd + +================================ +Making a disk image for guest OS +================================ + + 1. make file + # dd if=/dev/zero of=/root/rhel5.img bs=1M seek=4096 count=0 + # mke2fs -F -j /root/rhel5.img + # mount -o loop /root/rhel5.img /mnt + # cp -ax /{dev,var,etc,usr,bin,sbin,lib} /mnt + # mkdir /mnt/{root,proc,sys,home,tmp} + + Note: You may miss some device files. If so, please create them + with mknod. Or you can use tar instead of cp. + + 2. modify DomU's fstab + # vi /mnt/etc/fstab + /dev/xvda1 / ext3 defaults 1 1 + none /dev/pts devpts gid=5,mode=620 0 0 + none /dev/shm tmpfs defaults 0 0 + none /proc proc defaults 0 0 + none /sys sysfs defaults 0 0 + + 3. modify inittab + set runlevel to 3 to avoid X trying to start + # vi /mnt/etc/inittab + id:3:initdefault: + Start a getty on the hvc0 console + X0:2345:respawn:/sbin/mingetty hvc0 + tty1-6 mingetty can be commented out + + 4. add hvc0 into /etc/securetty + # vi /mnt/etc/securetty (add hvc0) + + 5. umount + # umount /mnt + +FYI, virt-manager can also make a disk image for guest OS. +It's GUI tools and easy to make it. + +================== +Boot Xen & Domain0 +================== + + 1. replace elilo + elilo of RHEL5 can boot Xen and Dom0. + If you use old elilo (e.g RHEL4), please download from the below + http://elilo.sourceforge.net/cgi-bin/blosxom + and copy into /boot/efi/efi/redhat/ + # cp elilo-3.6-ia64.efi /boot/efi/efi/redhat/elilo.efi + + 2. modify elilo.conf (like the below) + # vi /boot/efi/efi/redhat/elilo.conf + prompt + timeout=20 + default=xen + relocatable + + image=vmlinuz-2.6.18.8-xen + label=xen + vmm=xen.gz + initrd=initrd-2.6.18.8-xen.img + read-only + append=" -- rhgb root=/dev/sda2" + +The append options before "--" are for xen hypervisor, +the options after "--" are for dom0. + +FYI, your machine may need console options like +"com1=19200,8n1 console=vga,com1". For example, +append="com1=19200,8n1 console=vga,com1 -- rhgb console=tty0 \ +console=ttyS0 root=/dev/sda2" + +===================================== +Getting and Building domU with pv_ops +===================================== + + 1. get pv_ops tree + # git clone http://people.valinux.co.jp/~yamahata/xen-ia64/linux-2.6-xen-ia64.git/ + + 2. git branch (if necessary) + # cd linux-2.6-xen-ia64/ + # git checkout -b your_branch origin/xen-ia64-domu-minimal-2008may19 + (Note: The current branch is xen-ia64-domu-minimal-2008may19. + But you would find the new branch. You can see with + "git branch -r" to get the branch lists. + http://people.valinux.co.jp/~yamahata/xen-ia64/for_eagl/linux-2.6-ia64-pv-ops.git/ + is also available. The tree is based on + git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6 test) + + + 3. copy .config for pv_ops of domU + # cp arch/ia64/configs/xen_domu_wip_defconfig .config + + 4. make kernel with pv_ops + # make oldconfig + # make + + 5. install the kernel and initrd + # cp vmlinux.gz /boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU + # make modules_install + # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img \ + 2.6.26-rc3xen-ia64-08941-g1b12161 --builtin mptspi \ + --builtin mptbase --builtin mptscsih --builtin uhci-hcd \ + --builtin ohci-hcd --builtin ehci-hcd + +======================== +Boot DomainU with pv_ops +======================== + + 1. make config of DomU + # vi /etc/xen/rhel5 + kernel = "/boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU" + ramdisk = "/boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img" + vcpus = 1 + memory = 512 + name = "rhel5" + disk = [ 'file:/root/rhel5.img,xvda1,w' ] + root = "/dev/xvda1 ro" + extra= "rhgb console=hvc0" + + 2. After boot xen and dom0, start xend + # /etc/init.d/xend start + ( In the debugging case, # XEND_DEBUG=1 xend trace_start ) + + 3. start domU + # xm create -c rhel5 + +========= +Reference +========= +- Wiki of Xen/IA64 upstream merge + http://wiki.xensource.com/xenwiki/XenIA64/UpstreamMerge + +Written by Akio Takebe <takebe_akio@jp.fujitsu.com> on 28 May 2008 diff --git a/Documentation/ics932s401 b/Documentation/ics932s401 new file mode 100644 index 00000000000..07a739f406d --- /dev/null +++ b/Documentation/ics932s401 @@ -0,0 +1,31 @@ +Kernel driver ics932s401 +====================== + +Supported chips: + * IDT ICS932S401 + Prefix: 'ics932s401' + Addresses scanned: I2C 0x69 + Datasheet: Publically available at the IDT website + +Author: Darrick J. Wong + +Description +----------- + +This driver implements support for the IDT ICS932S401 chip family. + +This chip has 4 clock outputs--a base clock for the CPU (which is likely +multiplied to get the real CPU clock), a system clock, a PCI clock, a USB +clock, and a reference clock. The driver reports selected and actual +frequency. If spread spectrum mode is enabled, the driver also reports by what +percent the clock signal is being spread, which should be between 0 and -0.5%. +All frequencies are reported in KHz. + +The ICS932S401 monitors all inputs continuously. The driver will not read +the registers more often than once every other second. + +Special Features +---------------- + +The clocks could be reprogrammed to increase system speed. I will not help you +do this, as you risk damaging your system! diff --git a/Documentation/input/elantech.txt b/Documentation/input/elantech.txt new file mode 100644 index 00000000000..a10c3b6ba7c --- /dev/null +++ b/Documentation/input/elantech.txt @@ -0,0 +1,405 @@ +Elantech Touchpad Driver +======================== + + Copyright (C) 2007-2008 Arjan Opmeer <arjan@opmeer.net> + + Extra information for hardware version 1 found and + provided by Steve Havelka + + Version 2 (EeePC) hardware support based on patches + received from Woody at Xandros and forwarded to me + by user StewieGriffin at the eeeuser.com forum + + +Contents +~~~~~~~~ + + 1. Introduction + 2. Extra knobs + 3. Hardware version 1 + 3.1 Registers + 3.2 Native relative mode 4 byte packet format + 3.3 Native absolute mode 4 byte packet format + 4. Hardware version 2 + 4.1 Registers + 4.2 Native absolute mode 6 byte packet format + 4.2.1 One finger touch + 4.2.2 Two finger touch + + + +1. Introduction + ~~~~~~~~~~~~ + +Currently the Linux Elantech touchpad driver is aware of two different +hardware versions unimaginatively called version 1 and version 2. Version 1 +is found in "older" laptops and uses 4 bytes per packet. Version 2 seems to +be introduced with the EeePC and uses 6 bytes per packet. + +The driver tries to support both hardware versions and should be compatible +with the Xorg Synaptics touchpad driver and its graphical configuration +utilities. + +Additionally the operation of the touchpad can be altered by adjusting the +contents of some of its internal registers. These registers are represented +by the driver as sysfs entries under /sys/bus/serio/drivers/psmouse/serio? +that can be read from and written to. + +Currently only the registers for hardware version 1 are somewhat understood. +Hardware version 2 seems to use some of the same registers but it is not +known whether the bits in the registers represent the same thing or might +have changed their meaning. + +On top of that, some register settings have effect only when the touchpad is +in relative mode and not in absolute mode. As the Linux Elantech touchpad +driver always puts the hardware into absolute mode not all information +mentioned below can be used immediately. But because there is no freely +available Elantech documentation the information is provided here anyway for +completeness sake. + + +///////////////////////////////////////////////////////////////////////////// + + +2. Extra knobs + ~~~~~~~~~~~ + +Currently the Linux Elantech touchpad driver provides two extra knobs under +/sys/bus/serio/drivers/psmouse/serio? for the user. + +* debug + + Turn different levels of debugging ON or OFF. + + By echoing "0" to this file all debugging will be turned OFF. + + Currently a value of "1" will turn on some basic debugging and a value of + "2" will turn on packet debugging. For hardware version 1 the default is + OFF. For version 2 the default is "1". + + Turning packet debugging on will make the driver dump every packet + received to the syslog before processing it. Be warned that this can + generate quite a lot of data! + +* paritycheck + + Turns parity checking ON or OFF. + + By echoing "0" to this file parity checking will be turned OFF. Any + non-zero value will turn it ON. For hardware version 1 the default is ON. + For version 2 the default it is OFF. + + Hardware version 1 provides basic data integrity verification by + calculating a parity bit for the last 3 bytes of each packet. The driver + can check these bits and reject any packet that appears corrupted. Using + this knob you can bypass that check. + + It is not known yet whether hardware version 2 provides the same parity + bits. Hence checking is disabled by default. Currently even turning it on + will do nothing. + + +///////////////////////////////////////////////////////////////////////////// + + +3. Hardware version 1 + ================== + +3.1 Registers + ~~~~~~~~~ + +By echoing a hexadecimal value to a register it contents can be altered. + +For example: + + echo -n 0x16 > reg_10 + +* reg_10 + + bit 7 6 5 4 3 2 1 0 + B C T D L A S E + + E: 1 = enable smart edges unconditionally + S: 1 = enable smart edges only when dragging + A: 1 = absolute mode (needs 4 byte packets, see reg_11) + L: 1 = enable drag lock (see reg_22) + D: 1 = disable dynamic resolution + T: 1 = disable tapping + C: 1 = enable corner tap + B: 1 = swap left and right button + +* reg_11 + + bit 7 6 5 4 3 2 1 0 + 1 0 0 H V 1 F P + + P: 1 = enable parity checking for relative mode + F: 1 = enable native 4 byte packet mode + V: 1 = enable vertical scroll area + H: 1 = enable horizontal scroll area + +* reg_20 + + single finger width? + +* reg_21 + + scroll area width (small: 0x40 ... wide: 0xff) + +* reg_22 + + drag lock time out (short: 0x14 ... long: 0xfe; + 0xff = tap again to release) + +* reg_23 + + tap make timeout? + +* reg_24 + + tap release timeout? + +* reg_25 + + smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast) + +* reg_26 + + smart edge activation area width? + + +3.2 Native relative mode 4 byte packet format + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +byte 0: + bit 7 6 5 4 3 2 1 0 + c c p2 p1 1 M R L + + L, R, M = 1 when Left, Right, Middle mouse button pressed + some models have M as byte 3 odd parity bit + when parity checking is enabled (reg_11, P = 1): + p1..p2 = byte 1 and 2 odd parity bit + c = 1 when corner tap detected + +byte 1: + bit 7 6 5 4 3 2 1 0 + dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0 + + dx7..dx0 = x movement; positive = right, negative = left + byte 1 = 0xf0 when corner tap detected + +byte 2: + bit 7 6 5 4 3 2 1 0 + dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0 + + dy7..dy0 = y movement; positive = up, negative = down + +byte 3: + parity checking enabled (reg_11, P = 1): + + bit 7 6 5 4 3 2 1 0 + w h n1 n0 ds3 ds2 ds1 ds0 + + normally: + ds3..ds0 = scroll wheel amount and direction + positive = down or left + negative = up or right + when corner tap detected: + ds0 = 1 when top right corner tapped + ds1 = 1 when bottom right corner tapped + ds2 = 1 when bottom left corner tapped + ds3 = 1 when top left corner tapped + n1..n0 = number of fingers on touchpad + only models with firmware 2.x report this, models with + firmware 1.x seem to map one, two and three finger taps + directly to L, M and R mouse buttons + h = 1 when horizontal scroll action + w = 1 when wide finger touch? + + otherwise (reg_11, P = 0): + + bit 7 6 5 4 3 2 1 0 + ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0 + + ds7..ds0 = vertical scroll amount and direction + negative = up + positive = down + + +3.3 Native absolute mode 4 byte packet format + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +byte 0: + firmware version 1.x: + + bit 7 6 5 4 3 2 1 0 + D U p1 p2 1 p3 R L + + L, R = 1 when Left, Right mouse button pressed + p1..p3 = byte 1..3 odd parity bit + D, U = 1 when rocker switch pressed Up, Down + + firmware version 2.x: + + bit 7 6 5 4 3 2 1 0 + n1 n0 p2 p1 1 p3 R L + + L, R = 1 when Left, Right mouse button pressed + p1..p3 = byte 1..3 odd parity bit + n1..n0 = number of fingers on touchpad + +byte 1: + firmware version 1.x: + + bit 7 6 5 4 3 2 1 0 + f 0 th tw x9 x8 y9 y8 + + tw = 1 when two finger touch + th = 1 when three finger touch + f = 1 when finger touch + + firmware version 2.x: + + bit 7 6 5 4 3 2 1 0 + . . . . x9 x8 y9 y8 + +byte 2: + bit 7 6 5 4 3 2 1 0 + x7 x6 x5 x4 x3 x2 x1 x0 + + x9..x0 = absolute x value (horizontal) + +byte 3: + bit 7 6 5 4 3 2 1 0 + y7 y6 y5 y4 y3 y2 y1 y0 + + y9..y0 = absolute y value (vertical) + + +///////////////////////////////////////////////////////////////////////////// + + +4. Hardware version 2 + ================== + + +4.1 Registers + ~~~~~~~~~ + +By echoing a hexadecimal value to a register it contents can be altered. + +For example: + + echo -n 0x56 > reg_10 + +* reg_10 + + bit 7 6 5 4 3 2 1 0 + 0 1 0 1 0 1 D 0 + + D: 1 = enable drag and drop + +* reg_11 + + bit 7 6 5 4 3 2 1 0 + 1 0 0 0 S 0 1 0 + + S: 1 = enable vertical scroll + +* reg_21 + + unknown (0x00) + +* reg_22 + + drag and drop release time out (short: 0x70 ... long 0x7e; + 0x7f = never i.e. tap again to release) + + +4.2 Native absolute mode 6 byte packet format + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +4.2.1 One finger touch + ~~~~~~~~~~~~~~~~ + +byte 0: + + bit 7 6 5 4 3 2 1 0 + n1 n0 . . . . R L + + L, R = 1 when Left, Right mouse button pressed + n1..n0 = numbers of fingers on touchpad + +byte 1: + + bit 7 6 5 4 3 2 1 0 + x15 x14 x13 x12 x11 x10 x9 x8 + +byte 2: + + bit 7 6 5 4 3 2 1 0 + x7 x6 x5 x4 x4 x2 x1 x0 + + x15..x0 = absolute x value (horizontal) + +byte 3: + + bit 7 6 5 4 3 2 1 0 + . . . . . . . . + +byte 4: + + bit 7 6 5 4 3 2 1 0 + y15 y14 y13 y12 y11 y10 y8 y8 + +byte 5: + + bit 7 6 5 4 3 2 1 0 + y7 y6 y5 y4 y3 y2 y1 y0 + + y15..y0 = absolute y value (vertical) + + +4.2.2 Two finger touch + ~~~~~~~~~~~~~~~~ + +byte 0: + + bit 7 6 5 4 3 2 1 0 + n1 n0 ay8 ax8 . . R L + + L, R = 1 when Left, Right mouse button pressed + n1..n0 = numbers of fingers on touchpad + +byte 1: + + bit 7 6 5 4 3 2 1 0 + ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0 + + ax8..ax0 = first finger absolute x value + +byte 2: + + bit 7 6 5 4 3 2 1 0 + ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0 + + ay8..ay0 = first finger absolute y value + +byte 3: + + bit 7 6 5 4 3 2 1 0 + . . by8 bx8 . . . . + +byte 4: + + bit 7 6 5 4 3 2 1 0 + bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0 + + bx8..bx0 = second finger absolute x value + +byte 5: + + bit 7 6 5 4 3 2 1 0 + by7 by8 by5 by4 by3 by2 by1 by0 + + by8..by0 = second finger absolute y value diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.txt index 81905e81585..7f8b9d97bc4 100644 --- a/Documentation/input/input-programming.txt +++ b/Documentation/input/input-programming.txt @@ -20,10 +20,11 @@ pressed or released a BUTTON_IRQ happens. The driver could look like: static struct input_dev *button_dev; -static void button_interrupt(int irq, void *dummy, struct pt_regs *fp) +static irqreturn_t button_interrupt(int irq, void *dummy) { input_report_key(button_dev, BTN_0, inb(BUTTON_PORT) & 1); input_sync(button_dev); + return IRQ_HANDLED; } static int __init button_init(void) diff --git a/Documentation/io-mapping.txt b/Documentation/io-mapping.txt new file mode 100644 index 00000000000..473e43b2d58 --- /dev/null +++ b/Documentation/io-mapping.txt @@ -0,0 +1,82 @@ +The io_mapping functions in linux/io-mapping.h provide an abstraction for +efficiently mapping small regions of an I/O device to the CPU. The initial +usage is to support the large graphics aperture on 32-bit processors where +ioremap_wc cannot be used to statically map the entire aperture to the CPU +as it would consume too much of the kernel address space. + +A mapping object is created during driver initialization using + + struct io_mapping *io_mapping_create_wc(unsigned long base, + unsigned long size) + + 'base' is the bus address of the region to be made + mappable, while 'size' indicates how large a mapping region to + enable. Both are in bytes. + + This _wc variant provides a mapping which may only be used + with the io_mapping_map_atomic_wc or io_mapping_map_wc. + +With this mapping object, individual pages can be mapped either atomically +or not, depending on the necessary scheduling environment. Of course, atomic +maps are more efficient: + + void *io_mapping_map_atomic_wc(struct io_mapping *mapping, + unsigned long offset) + + 'offset' is the offset within the defined mapping region. + Accessing addresses beyond the region specified in the + creation function yields undefined results. Using an offset + which is not page aligned yields an undefined result. The + return value points to a single page in CPU address space. + + This _wc variant returns a write-combining map to the + page and may only be used with mappings created by + io_mapping_create_wc + + Note that the task may not sleep while holding this page + mapped. + + void io_mapping_unmap_atomic(void *vaddr) + + 'vaddr' must be the the value returned by the last + io_mapping_map_atomic_wc call. This unmaps the specified + page and allows the task to sleep once again. + +If you need to sleep while holding the lock, you can use the non-atomic +variant, although they may be significantly slower. + + void *io_mapping_map_wc(struct io_mapping *mapping, + unsigned long offset) + + This works like io_mapping_map_atomic_wc except it allows + the task to sleep while holding the page mapped. + + void io_mapping_unmap(void *vaddr) + + This works like io_mapping_unmap_atomic, except it is used + for pages mapped with io_mapping_map_wc. + +At driver close time, the io_mapping object must be freed: + + void io_mapping_free(struct io_mapping *mapping) + +Current Implementation: + +The initial implementation of these functions uses existing mapping +mechanisms and so provides only an abstraction layer and no new +functionality. + +On 64-bit processors, io_mapping_create_wc calls ioremap_wc for the whole +range, creating a permanent kernel-visible mapping to the resource. The +map_atomic and map functions add the requested offset to the base of the +virtual address returned by ioremap_wc. + +On 32-bit processors with HIGHMEM defined, io_mapping_map_atomic_wc uses +kmap_atomic_pfn to map the specified page in an atomic fashion; +kmap_atomic_pfn isn't really supposed to be used with device pages, but it +provides an efficient mapping for this usage. + +On 32-bit processors without HIGHMEM defined, io_mapping_map_atomic_wc and +io_mapping_map_wc both use ioremap_wc, a terribly inefficient function which +performs an IPI to inform all processors about the new mapping. This results +in a significant performance penalty. diff --git a/Documentation/ioctl/00-INDEX b/Documentation/ioctl/00-INDEX new file mode 100644 index 00000000000..d2fe4d4729e --- /dev/null +++ b/Documentation/ioctl/00-INDEX @@ -0,0 +1,10 @@ +00-INDEX + - this file +cdrom.txt + - summary of CDROM ioctl calls +hdio.txt + - summary of HDIO_ ioctl calls +ioctl-decoding.txt + - how to decode the bits of an IOCTL code +ioctl-number.txt + - how to implement and register device/driver ioctl calls diff --git a/Documentation/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 1c6b545635a..b880ce5dbd3 100644 --- a/Documentation/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -92,6 +92,7 @@ Code Seq# Include File Comments 'J' 00-1F drivers/scsi/gdth_ioctl.h 'K' all linux/kd.h 'L' 00-1F linux/loop.h +'L' 20-2F driver/usb/misc/vstusb.h 'L' E0-FF linux/ppdd.h encrypted disk device driver <http://linux01.gwdg.de/~alatham/ppdd.html> 'M' all linux/soundcard.h @@ -110,6 +111,8 @@ Code Seq# Include File Comments 'W' 00-1F linux/wanrouter.h conflict! 'X' all linux/xfs_fs.h 'Y' all linux/cyclades.h +'[' 00-07 linux/usb/usbtmc.h USB Test and Measurement Devices + <mailto:gregkh@suse.de> 'a' all ATM on linux <http://lrcwww.epfl.ch/linux-atm/magic.html> 'b' 00-FF bit3 vme host bridge diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/CREDITS index 8cac6c2f23e..c1679e913fc 100644 --- a/Documentation/isdn/CREDITS +++ b/Documentation/isdn/CREDITS @@ -5,7 +5,7 @@ I want to thank all who contributed to this project and especially to: Thomas Bogendörfer (tsbogend@bigbug.franken.de) Tester, lots of bugfixes and hints. -Alan Cox (alan@redhat.com) +Alan Cox (alan@lxorguk.ukuu.org.uk) For help getting into standard-kernel. Henner Eisen (eis@baty.hanse.de) diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO index 0775cf4798b..55476982b5c 100644 --- a/Documentation/ja_JP/HOWTO +++ b/Documentation/ja_JP/HOWTO @@ -11,14 +11,14 @@ for non English (read: Japanese) speakers and is not intended as a fork. So if you have any comments or updates for this file, please try to update the original English file first. -Last Updated: 2008/08/21 +Last Updated: 2008/10/24 ================================== ã“ã‚Œã¯ã€ -linux-2.6.27/Documentation/HOWTO +linux-2.6.28/Documentation/HOWTO ã®å’Œè¨³ã§ã™ã€‚ 翻訳団体： JF プãƒã‚¸ã‚§ã‚¯ãƒˆ < http://www.linux.or.jp/JF/ > -翻訳日： 2008/8/5 +翻訳日： 2008/10/24 翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com> æ ¡æ£è€…： æ¾å€‰ã•ã‚“ <nbh--mats at nifty dot com> å°æž— é›…å…¸ã•ã‚“ (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp> @@ -110,8 +110,8 @@ Linux カーãƒãƒ«ã‚½ãƒ¼ã‚¹ãƒ„リーã¯å¹…広ã„範囲ã®ãƒ‰ã‚ュメントをå æ–°ã—ã„ドã‚ãƒ¥ãƒ¡ãƒ³ãƒˆãƒ•ã‚¡ã‚¤ãƒ«ã‚‚è¿½åŠ ã™ã‚‹ã“ã¨ã‚’勧ã‚ã¾ã™ã€‚ カーãƒãƒ«ã®å¤‰æ›´ãŒã€ã‚«ãƒ¼ãƒãƒ«ãŒãƒ¦ãƒ¼ã‚¶ç©ºé–“ã«å…¬é–‹ã—ã¦ã„るインターフェイス㮠変更を引ãèµ·ã“ã™å ´åˆã€ãã®å¤‰æ›´ã‚’説明ã™ã‚‹ãƒžãƒ‹ãƒ¥ã‚¢ãƒ«ãƒšãƒ¼ã‚¸ã®ãƒ‘ッãƒã‚„æƒ…å ± -をマニュアルページã®ãƒ¡ãƒ³ãƒ†ãƒŠ mtk.manpages@gmail.com ã«é€ã‚‹ã“ã¨ã‚’勧ã‚ã¾ -ã™ã€‚ +をマニュアルページã®ãƒ¡ãƒ³ãƒ†ãƒŠ mtk.manpages@gmail.com ã«é€ã‚Šã€CC ã‚’ +linux-api@ver.kernel.org ã«é€ã‚‹ã“ã¨ã‚’勧ã‚ã¾ã™ã€‚ 以下ã¯ã‚«ãƒ¼ãƒãƒ«ã‚½ãƒ¼ã‚¹ãƒ„リーã«å«ã¾ã‚Œã¦ã„ã‚‹èªã‚“ã§ãŠãã¹ãファイルã®ä¸€è¦§ã§ ã™- @@ -149,7 +149,7 @@ Linux カーãƒãƒ«ã‚½ãƒ¼ã‚¹ãƒ„リーã¯å¹…広ã„範囲ã®ãƒ‰ã‚ュメントをå ã“ã®ä»–ã«ãƒ‘ッãƒã‚’作る方法ã«ã¤ã„ã¦ã®ã‚ˆãã§ããŸè¨˜è¿°ã¯- "The Perfect Patch" - http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt + http://userweb.kernel.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html @@ -664,7 +664,7 @@ Linux カーãƒãƒ«ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¯ã€ä¸€åº¦ã«å¤§é‡ã®ã‚³ãƒ¼ãƒ‰ã®å¡Šã‚’å– ã“ã‚Œã«ã¤ã„ã¦å…¨ã¦ãŒã©ã®ã‚ˆã†ã«ã‚ã‚‹ã¹ãã‹ã«ã¤ã„ã¦ã®è©³ç´°ã¯ã€ä»¥ä¸‹ã®ãƒ‰ã‚ュメ ント㮠ChangeLog セクションを見ã¦ãã ã•ã„- "The Perfect Patch" - http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt + http://userweb.kernel.org/~akpm/stuff/tpp.txt ã“れらã®ã©ã‚Œã‚‚ãŒã€æ™‚ã«ã¯ã¨ã¦ã‚‚困難ã§ã™ã€‚ã“れらã®æ…£ä¾‹ã‚’完璧ã«å®Ÿæ–½ã™ã‚‹ã« ã¯æ•°å¹´ã‹ã‹ã‚‹ã‹ã‚‚ã—ã‚Œã¾ã›ã‚“。ã“ã‚Œã¯ç¶™ç¶šçš„ãªæ”¹å–„ã®ãƒ—ãƒã‚»ã‚¹ã§ã‚ã‚Šã€ãã®ãŸ diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index 7a7753321a2..51104f9194a 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -383,6 +383,20 @@ more details, with real examples. to prerequisites are referenced with $(src) (because they are not generated files). + $(kecho) + echoing information to user in a rule is often a good practice + but when execution "make -s" one does not expect to see any output + except for warnings/errors. + To support this kbuild define $(kecho) which will echo out the + text following $(kecho) to stdout except if "make -s" is used. + + Example: + #arch/blackfin/boot/Makefile + $(obj)/vmImage: $(obj)/vmlinux.gz + $(call if_changed,uimage) + @$(kecho) 'Kernel: $@ is ready' + + --- 3.11 $(CC) support functions The kernel may be built with several different versions of diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt index 0705040531a..3f4bc840da8 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -109,7 +109,8 @@ There are two possible methods of using Kdump. 2) Or use the system kernel binary itself as dump-capture kernel and there is no need to build a separate dump-capture kernel. This is possible only with the architecutres which support a relocatable kernel. As - of today, i386, x86_64 and ia64 architectures support relocatable kernel. + of today, i386, x86_64, ppc64 and ia64 architectures support relocatable + kernel. Building a relocatable kernel is advantageous from the point of view that one does not have to build a second kernel for capturing the dump. But @@ -207,8 +208,15 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64) Dump-capture kernel config options (Arch Dependent, ppc64) ---------------------------------------------------------- -* Make and install the kernel and its modules. DO NOT add this kernel - to the boot loader configuration files. +1) Enable "Build a kdump crash kernel" support under "Kernel" options: + + CONFIG_CRASH_DUMP=y + +2) Enable "Build a relocatable kernel" support + + CONFIG_RELOCATABLE=y + + Make and install the kernel and its modules. Dump-capture kernel config options (Arch Dependent, ia64) ---------------------------------------------------------- diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 2443f5bb436..a2d8805c03d 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -89,6 +89,7 @@ parameter is applicable: SPARC Sparc architecture is enabled. SWSUSP Software suspend (hibernation) is enabled. SUSPEND System suspend states are enabled. + FTRACE Function tracing enabled. TS Appropriate touchscreen support is enabled. USB USB support is enabled. USBHID USB Human Interface Device support is enabled. @@ -100,7 +101,8 @@ parameter is applicable: X86-32 X86-32, aka i386 architecture is enabled. X86-64 X86-64 architecture is enabled. More X86-64 boot options can be found in - Documentation/x86_64/boot-options.txt . + Documentation/x86/x86_64/boot-options.txt . + X86 Either 32bit or 64bit x86 (same as X86-32+X86-64) In addition, the following text indicates that the option: @@ -111,10 +113,10 @@ In addition, the following text indicates that the option: Parameters denoted with BOOT are actually interpreted by the boot loader, and have no meaning to the kernel directly. Do not modify the syntax of boot loader parameters without extreme -need or coordination with <Documentation/i386/boot.txt>. +need or coordination with <Documentation/x86/i386/boot.txt>. There are also arch-specific kernel-parameters not documented here. -See for example <Documentation/x86_64/boot-options.txt>. +See for example <Documentation/x86/x86_64/boot-options.txt>. Note that ALL kernel parameters listed below are CASE SENSITIVE, and that a trailing = on the name of any parameter states that that parameter will @@ -197,40 +199,53 @@ and is between 256 and 4096 characters. It is defined in the file that require a timer override, but don't have HPET - acpi.debug_layer= [HW,ACPI] - Format: <int> - Each bit of the <int> indicates an ACPI debug layer, - 1: enable, 0: disable. It is useful for boot time - debugging. After system has booted up, it can be set - via /sys/module/acpi/parameters/debug_layer. - CONFIG_ACPI_DEBUG must be enabled for this to produce any output. - Available bits (add the numbers together) to enable debug output - for specific parts of the ACPI subsystem: - 0x01 utilities 0x02 hardware 0x04 events 0x08 tables - 0x10 namespace 0x20 parser 0x40 dispatcher - 0x80 executer 0x100 resources 0x200 acpica debugger - 0x400 os services 0x800 acpica disassembler. - The number can be in decimal or prefixed with 0x in hex. - Warning: Many of these options can produce a lot of - output and make your system unusable. Be very careful. - - acpi.debug_level= [HW,ACPI] + acpi_backlight= [HW,ACPI] + acpi_backlight=vendor + acpi_backlight=video + If set to vendor, prefer vendor specific driver + (e.g. thinkpad_acpi, sony_acpi, etc.) instead + of the ACPI video.ko driver. + + acpi_display_output= [HW,ACPI] + acpi_display_output=vendor + acpi_display_output=video + See above. + + acpi.debug_layer= [HW,ACPI,ACPI_DEBUG] + acpi.debug_level= [HW,ACPI,ACPI_DEBUG] Format: <int> - Each bit of the <int> indicates an ACPI debug level, - 1: enable, 0: disable. It is useful for boot time - debugging. After system has booted up, it can be set - via /sys/module/acpi/parameters/debug_level. - CONFIG_ACPI_DEBUG must be enabled for this to produce any output. - Available bits (add the numbers together) to enable different - debug output levels of the ACPI subsystem: - 0x01 error 0x02 warn 0x04 init 0x08 debug object - 0x10 info 0x20 init names 0x40 parse 0x80 load - 0x100 dispatch 0x200 execute 0x400 names 0x800 operation region - 0x1000 bfield 0x2000 tables 0x4000 values 0x8000 objects - 0x10000 resources 0x20000 user requests 0x40000 package. - The number can be in decimal or prefixed with 0x in hex. - Warning: Many of these options can produce a lot of - output and make your system unusable. Be very careful. + CONFIG_ACPI_DEBUG must be enabled to produce any ACPI + debug output. Bits in debug_layer correspond to a + _COMPONENT in an ACPI source file, e.g., + #define _COMPONENT ACPI_PCI_COMPONENT + Bits in debug_level correspond to a level in + ACPI_DEBUG_PRINT statements, e.g., + ACPI_DEBUG_PRINT((ACPI_DB_INFO, ... + The debug_level mask defaults to "info". See + Documentation/acpi/debug.txt for more information about + debug layers and levels. + + Enable processor driver info messages: + acpi.debug_layer=0x20000000 + Enable PCI/PCI interrupt routing info messages: + acpi.debug_layer=0x400000 + Enable AML "Debug" output, i.e., stores to the Debug + object while interpreting AML: + acpi.debug_layer=0xffffffff acpi.debug_level=0x2 + Enable all messages related to ACPI hardware: + acpi.debug_layer=0x2 acpi.debug_level=0xffffffff + + Some values produce so much output that the system is + unusable. The "log_buf_len" parameter may be useful + if you need to capture more output. + + acpi.power_nocheck= [HW,ACPI] + Format: 1/0 enable/disable the check of power state. + On some bogus BIOS the _PSC object/_STA object of + power resource can't return the correct device power + state. In such case it is unneccessary to check its + power state again in power transition. + 1 : disable the power state check acpi_pm_good [X86-32,X86-64] Override the pmtimer bug detection: force the kernel @@ -283,7 +298,9 @@ and is between 256 and 4096 characters. It is defined in the file Possible values are: isolate - enable device isolation (each device, as far as possible, will get its own protection - domain) + domain) [default] + share - put every device behind one IOMMU into the + same protection domain fullflush - enable flushing of IO/TLB entries when they are unmapped. Otherwise they are flushed before they will be reused, which @@ -618,7 +635,7 @@ and is between 256 and 4096 characters. It is defined in the file digiepca= [HW,SERIAL] See drivers/char/README.epca and - Documentation/digiepca.txt. + Documentation/serial/digiepca.txt. disable_mtrr_cleanup [X86] enable_mtrr_cleanup [X86] @@ -690,7 +707,7 @@ and is between 256 and 4096 characters. It is defined in the file See Documentation/block/as-iosched.txt and Documentation/block/deadline-iosched.txt for details. - elfcorehdr= [X86-32, X86_64] + elfcorehdr= [IA64,PPC,SH,X86-32,X86_64] Specifies physical address of start of kernel core image elf header. Generally kexec loader will pass this option to capture kernel. @@ -729,7 +746,7 @@ and is between 256 and 4096 characters. It is defined in the file See header of drivers/scsi/fdomain.c. floppy= [HW] - See Documentation/floppy.txt. + See Documentation/blockdev/floppy.txt. force_pal_cache_flush [IA-64] Avoid check_sal_cache_flush which may hang on @@ -737,6 +754,14 @@ and is between 256 and 4096 characters. It is defined in the file parameter will force ia64_sal_cache_flush to call ia64_pal_cache_flush instead of SAL_CACHE_FLUSH. + ftrace=[tracer] + [ftrace] will set and start the specified tracer + as early as possible in order to facilitate early + boot debugging. + + ftrace_dump_on_oops + [ftrace] will dump the trace buffers on oops. + gamecon.map[2|3]= [HW,JOY] Multisystem joystick and NES/SNES/PSX pad support via parallel port (up to 5 devices per port) @@ -796,6 +821,12 @@ and is between 256 and 4096 characters. It is defined in the file Defaults to the default architecture's huge page size if not specified. + hlt [BUGS=ARM,SH] + + hvc_iucv= [S390] Number of z/VM IUCV Hypervisor console (HVC) + back-ends. Valid parameters: 0..8 + + i8042.debug [HW] Toggle i8042 debug mode i8042.direct [HW] Put keyboard port into non-translated mode i8042.dumbkbd [HW] Pretend that controller can only read data from keyboard and cannot control its state @@ -964,13 +995,15 @@ and is between 256 and 4096 characters. It is defined in the file Format: <cpu number>,...,<cpu number> or - <cpu number>-<cpu number> (must be a positive range in ascending order) + <cpu number>-<cpu number> + (must be a positive range in ascending order) or a mixture <cpu number>,...,<cpu number>-<cpu number> + This option can be used to specify one or more CPUs to isolate from the general SMP balancing and scheduling - algorithms. The only way to move a process onto or off - an "isolated" CPU is via the CPU affinity syscalls. + algorithms. You can move a process onto or off an + "isolated" CPU via the CPU affinity syscalls or cpuset. <cpu number> begins at 0 and the maximum value is "number of CPUs in system - 1". @@ -1085,7 +1118,7 @@ and is between 256 and 4096 characters. It is defined in the file the same attribute, the last one is used. load_ramdisk= [RAM] List of ramdisks to load from floppy - See Documentation/ramdisk.txt. + See Documentation/blockdev/ramdisk.txt. lockd.nlm_grace_period=P [NFS] Assign grace period. Format: <integer> @@ -1177,8 +1210,8 @@ and is between 256 and 4096 characters. It is defined in the file it is equivalent to "nosmp", which also disables the IO APIC. - max_addr=[KMG] [KNL,BOOT,ia64] All physical memory greater than or - equal to this physical address is ignored. + max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater than + or equal to this physical address is ignored. max_luns= [SCSI] Maximum number of LUNs to probe. Should be between 1 and 2^32-1. @@ -1191,7 +1224,7 @@ and is between 256 and 4096 characters. It is defined in the file mce [X86-32] Machine Check Exception - mce=option [X86-64] See Documentation/x86_64/boot-options.txt + mce=option [X86-64] See Documentation/x86/x86_64/boot-options.txt md= [HW] RAID subsystems devices and level See Documentation/md.txt. @@ -1210,6 +1243,10 @@ and is between 256 and 4096 characters. It is defined in the file mem=nopentium [BUGS=X86-32] Disable usage of 4MB pages for kernel memory. + memchunk=nn[KMG] + [KNL,SH] Allow user to override the default size for + per-device physically contiguous DMA buffers. + memmap=exactmap [KNL,X86-32,X86_64] Enable setting of an exact E820 memory map, as specified by the user. Such memmap=exactmap lines can be constructed based on @@ -1274,6 +1311,9 @@ and is between 256 and 4096 characters. It is defined in the file mga= [HW,DRM] + min_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory below this + physical address is ignored. + mminit_loglevel= [KNL] When CONFIG_DEBUG_MEMORY_INIT is set, this parameter allows control of the logging verbosity for @@ -1368,7 +1408,20 @@ and is between 256 and 4096 characters. It is defined in the file when a NMI is triggered. Format: [state][,regs][,debounce][,die] - nmi_watchdog= [KNL,BUGS=X86-32] Debugging features for SMP kernels + nmi_watchdog= [KNL,BUGS=X86-32,X86-64] Debugging features for SMP kernels + Format: [panic,][num] + Valid num: 0,1,2 + 0 - turn nmi_watchdog off + 1 - use the IO-APIC timer for the NMI watchdog + 2 - use the local APIC for the NMI watchdog using + a performance counter. Note: This will use one performance + counter and the local APIC's performance vector. + When panic is specified panic when an NMI watchdog timeout occurs. + This is useful when you use a panic=... timeout and need the box + quickly up again. + Instead of 1 and 2 it is possible to use the following + symbolic names: lapic and ioapic + Example: nmi_watchdog=2 or nmi_watchdog=panic,lapic no387 [BUGS=X86-32] Tells the kernel to use the 387 maths emulation library even if a 387 maths coprocessor @@ -1392,6 +1445,8 @@ and is between 256 and 4096 characters. It is defined in the file nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects. + nodsp [SH] Disable hardware DSP at boot time. + noefi [X86-32,X86-64] Disable EFI runtime services support. noexec [IA-64] @@ -1408,18 +1463,24 @@ and is between 256 and 4096 characters. It is defined in the file noexec32=off: disable non-executable mappings read implies executable mappings + nofpu [SH] Disable hardware FPU at boot time. + nofxsr [BUGS=X86-32] Disables x86 floating point extended register save and restore. The kernel will only save legacy floating-point registers on task switch. noclflush [BUGS=X86] Don't use the CLFLUSH instruction - nohlt [BUGS=ARM] + nohlt [BUGS=ARM,SH] no-hlt [BUGS=X86-32] Tells the kernel that the hlt instruction doesn't work correctly and not to use it. + no_file_caps Tells the kernel not to honor file capabilities. The + only way then for a file to be executed with privilege + is to be setuid root or executed by root. + nohalt [IA-64] Tells the kernel not to use the power saving function PAL_HALT_LIGHT when idle. This increases power-consumption. On the positive side, it reduces @@ -1431,8 +1492,6 @@ and is between 256 and 4096 characters. It is defined in the file Valid arguments: on, off Default: on - noirqbalance [X86-32,SMP,KNL] Disable kernel irq balancing - noirqdebug [X86-32] Disables the code which attempts to detect and disable unhandled interrupt sources. @@ -1574,10 +1633,10 @@ and is between 256 and 4096 characters. It is defined in the file pcd. [PARIDE] See header of drivers/block/paride/pcd.c. - See also Documentation/paride.txt. + See also Documentation/blockdev/paride.txt. pci=option[,option...] [PCI] various PCI subsystem options: - off [X86-32] don't probe for the PCI bus + off [X86] don't probe for the PCI bus bios [X86-32] force use of PCI BIOS, don't access the hardware directly. Use this if your machine has a non-standard PCI host bridge. @@ -1585,9 +1644,9 @@ and is between 256 and 4096 characters. It is defined in the file hardware access methods are allowed. Use this if you experience crashes upon bootup and you suspect they are caused by the BIOS. - conf1 [X86-32] Force use of PCI Configuration + conf1 [X86] Force use of PCI Configuration Mechanism 1. - conf2 [X86-32] Force use of PCI Configuration + conf2 [X86] Force use of PCI Configuration Mechanism 2. noaer [PCIE] If the PCIEAER kernel config parameter is enabled, this kernel boot option can be used to @@ -1599,6 +1658,17 @@ and is between 256 and 4096 characters. It is defined in the file nomsi [MSI] If the PCI_MSI kernel config parameter is enabled, this kernel boot option can be used to disable the use of MSI interrupts system-wide. + noioapicquirk [APIC] Disable all boot interrupt quirks. + Safety option to keep boot IRQs enabled. This + should never be necessary. + ioapicreroute [APIC] Enable rerouting of boot IRQs to the + primary IO-APIC for bridges that cannot disable + boot IRQs. This fixes a source of spurious IRQs + when the system masks IRQs. + noioapicreroute [APIC] Disable workaround that uses the + boot IRQ equivalent of an IRQ that connects to + a chipset where boot IRQs cannot be disabled. + The opposite of ioapicreroute. biosirq [X86-32] Use PCI BIOS calls to get the interrupt routing table. These calls are known to be buggy on several machines and they hang the machine @@ -1607,37 +1677,37 @@ and is between 256 and 4096 characters. It is defined in the file this option if the kernel is unable to allocate IRQs or discover secondary PCI buses on your motherboard. - rom [X86-32] Assign address space to expansion ROMs. + rom [X86] Assign address space to expansion ROMs. Use with caution as certain devices share address decoders between ROMs and other resources. - norom [X86-32,X86_64] Do not assign address space to + norom [X86] Do not assign address space to expansion ROMs that do not already have BIOS assigned address ranges. - irqmask=0xMMMM [X86-32] Set a bit mask of IRQs allowed to be + irqmask=0xMMMM [X86] Set a bit mask of IRQs allowed to be assigned automatically to PCI devices. You can make the kernel exclude IRQs of your ISA cards this way. - pirqaddr=0xAAAAA [X86-32] Specify the physical address + pirqaddr=0xAAAAA [X86] Specify the physical address of the PIRQ table (normally generated by the BIOS) if it is outside the F0000h-100000h range. - lastbus=N [X86-32] Scan all buses thru bus #N. Can be + lastbus=N [X86] Scan all buses thru bus #N. Can be useful if the kernel is unable to find your secondary buses and you want to tell it explicitly which ones they are. - assign-busses [X86-32] Always assign all PCI bus + assign-busses [X86] Always assign all PCI bus numbers ourselves, overriding whatever the firmware may have done. - usepirqmask [X86-32] Honor the possible IRQ mask stored + usepirqmask [X86] Honor the possible IRQ mask stored in the BIOS $PIR table. This is needed on some systems with broken BIOSes, notably some HP Pavilion N5400 and Omnibook XE3 notebooks. This will have no effect if ACPI IRQ routing is enabled. - noacpi [X86-32] Do not use ACPI for IRQ routing + noacpi [X86] Do not use ACPI for IRQ routing or for PCI scanning. - use_crs [X86-32] Use _CRS for PCI resource + use_crs [X86] Use _CRS for PCI resource allocation. routeirq Do IRQ routing for all PCI devices. This is normally done in pci_enable_device(), @@ -1666,10 +1736,16 @@ and is between 256 and 4096 characters. It is defined in the file reserved for the CardBus bridge's memory window. The default value is 64 megabytes. + pcie_aspm= [PCIE] Forcibly enable or disable PCIe Active State Power + Management. + off Disable ASPM. + force Enable ASPM even on devices that claim not to support it. + WARNING: Forcing ASPM on may cause system lockups. + pcmv= [HW,PCMCIA] BadgePAD 4 pd. [PARIDE] - See Documentation/paride.txt. + See Documentation/blockdev/paride.txt. pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at boot time. @@ -1677,13 +1753,13 @@ and is between 256 and 4096 characters. It is defined in the file See arch/parisc/kernel/pdc_chassis.c pf. [PARIDE] - See Documentation/paride.txt. + See Documentation/blockdev/paride.txt. pg. [PARIDE] - See Documentation/paride.txt. + See Documentation/blockdev/paride.txt. pirq= [SMP,APIC] Manual mp-table setup - See Documentation/i386/IO-APIC.txt. + See Documentation/x86/i386/IO-APIC.txt. plip= [PPT,NET] Parallel port network link Format: { parport<nr> | timid | 0 } @@ -1693,6 +1769,10 @@ and is between 256 and 4096 characters. It is defined in the file Override pmtimer IOPort with a hex value. e.g. pmtmr=0x508 + pnp.debug [PNP] + Enable PNP debug messages. This depends on the + CONFIG_PNP_DEBUG_MESSAGES option. + pnpacpi= [ACPI] { off } @@ -1713,6 +1793,11 @@ and is between 256 and 4096 characters. It is defined in the file autoconfiguration. Ranges are in pairs (memory base and size). + dynamic_printk + Enables pr_debug()/dev_dbg() calls if + CONFIG_DYNAMIC_PRINTK_DEBUG has been enabled. These can also + be switched on/off via <debugfs>/dynamic_printk/modules + print-fatal-signals= [KNL] debug: print fatal signals print-fatal-signals=1: print segfault info to @@ -1741,7 +1826,7 @@ and is between 256 and 4096 characters. It is defined in the file prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk before loading. - See Documentation/ramdisk.txt. + See Documentation/blockdev/ramdisk.txt. psmouse.proto= [HW,MOUSE] Highest PS2 mouse protocol extension to probe for; one of (bare|imps|exps|lifebook|any). @@ -1761,7 +1846,7 @@ and is between 256 and 4096 characters. It is defined in the file <io>,<mss_io>,<mss_irq>,<mss_dma>,<mpu_io>,<mpu_irq> pt. [PARIDE] - See Documentation/paride.txt. + See Documentation/blockdev/paride.txt. pty.legacy_count= [KNL] Number of legacy pty's. Overwrites compiled-in @@ -1775,10 +1860,10 @@ and is between 256 and 4096 characters. It is defined in the file See Documentation/md.txt. ramdisk_blocksize= [RAM] - See Documentation/ramdisk.txt. + See Documentation/blockdev/ramdisk.txt. ramdisk_size= [RAM] Sizes of RAM disks in kilobytes - See Documentation/ramdisk.txt. + See Documentation/blockdev/ramdisk.txt. rcupdate.blimit= [KNL,BOOT] Set maximum number of finished RCU callbacks to process @@ -2110,7 +2195,7 @@ and is between 256 and 4096 characters. It is defined in the file See Documentation/sonypi.txt specialix= [HW,SERIAL] Specialix multi-serial port adapter - See Documentation/specialix.txt. + See Documentation/serial/specialix.txt. spia_io_base= [HW,MTD] spia_fio_base= @@ -2123,6 +2208,9 @@ and is between 256 and 4096 characters. It is defined in the file st= [HW,SCSI] SCSI tape parameters (buffers, etc.) See Documentation/scsi/st.txt. + stacktrace [FTRACE] + Enabled the stack tracer on boot up. + sti= [PARISC,HW] Format: <num> Set the STI (builtin display/keyboard on the HP-PARISC @@ -2185,7 +2273,7 @@ and is between 256 and 4096 characters. It is defined in the file thermal.crt= [HW,ACPI] -1: disable all critical trip points in all thermal zones - <degrees C>: lower all critical trip points + <degrees C>: override all critical trip points thermal.nocrt= [HW,ACPI] Set to disable actions on ACPI thermal zone @@ -2207,12 +2295,27 @@ and is between 256 and 4096 characters. It is defined in the file See comment before function dc390_setup() in drivers/scsi/tmscsim.c. + topology= [S390] + Format: {off | on} + Specify if the kernel should make use of the cpu + topology informations if the hardware supports these. + The scheduler will make use of these informations and + e.g. base its process migration decisions on it. + Default is off. + tp720= [HW,PS2] trix= [HW,OSS] MediaTrix AudioTrix Pro Format: <io>,<irq>,<dma>,<dma2>,<sb_io>,<sb_irq>,<sb_dma>,<mpu_io>,<mpu_irq> + tsc= Disable clocksource-must-verify flag for TSC. + Format: <string> + [x86] reliable: mark tsc clocksource as reliable, this + disables clocksource verification at runtime. + Used to enable high-resolution timer mode on older + hardware, and in virtualized environment. + turbografx.map[2|3]= [HW,JOY] TurboGraFX parallel port interface Format: @@ -2247,6 +2350,25 @@ and is between 256 and 4096 characters. It is defined in the file autosuspended. Devices for which the delay is set to a negative value won't be autosuspended at all. + usbcore.usbfs_snoop= + [USB] Set to log all usbfs traffic (default 0 = off). + + usbcore.blinkenlights= + [USB] Set to cycle leds on hubs (default 0 = off). + + usbcore.old_scheme_first= + [USB] Start with the old device initialization + scheme (default 0 = off). + + usbcore.use_both_schemes= + [USB] Try the other device initialization scheme + if the first one fails (default 1 = enabled). + + usbcore.initial_descriptor_timeout= + [USB] Specifies timeout for the initial 64-byte + USB_REQ_GET_DESCRIPTOR request in milliseconds + (default 5000 = 5.0 seconds). + usbhid.mousepoll= [USBHID] The interval which mice are to be polled at. @@ -2270,7 +2392,7 @@ and is between 256 and 4096 characters. It is defined in the file See Documentation/fb/modedb.txt. vga= [BOOT,X86-32] Select a particular video mode - See Documentation/i386/boot.txt and + See Documentation/x86/i386/boot.txt and Documentation/svga.txt. Use vga=ask for menu. This is actually a boot loader parameter; the value is diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt index 51a8021ee53..f5d2aad65a6 100644 --- a/Documentation/kobject.txt +++ b/Documentation/kobject.txt @@ -118,6 +118,10 @@ the name of the kobject, call kobject_rename(): int kobject_rename(struct kobject *kobj, const char *new_name); +Note kobject_rename does perform any locking or have a solid notion of +what names are valid so the provide must provide their own sanity checking +and serialization. + There is a function called kobject_set_name() but that is legacy cruft and is being removed. If your code needs to call this function, it is incorrect and needs to be fixed. diff --git a/Documentation/laptops/acer-wmi.txt b/Documentation/laptops/acer-wmi.txt index 69b5dd4e5a5..2b3a6b5260b 100644 --- a/Documentation/laptops/acer-wmi.txt +++ b/Documentation/laptops/acer-wmi.txt @@ -1,7 +1,7 @@ Acer Laptop WMI Extras Driver http://code.google.com/p/aceracpi -Version 0.1 -9th February 2008 +Version 0.2 +18th August 2008 Copyright 2007-2008 Carlos Corbacho <carlos@strangeworlds.co.uk> @@ -87,17 +87,7 @@ acer-wmi come with built-in wireless. However, should you feel so inclined to ever wish to remove the card, or swap it out at some point, please get in touch with me, as we may well be able to gain some data on wireless card detection. -To read the status of the wireless radio (0=off, 1=on): -cat /sys/devices/platform/acer-wmi/wireless - -To enable the wireless radio: -echo 1 > /sys/devices/platform/acer-wmi/wireless - -To disable the wireless radio: -echo 0 > /sys/devices/platform/acer-wmi/wireless - -To set the state of the wireless radio when loading acer-wmi, pass: -wireless=X (where X is 0 or 1) +The wireless radio is exposed through rfkill. Bluetooth ********* @@ -117,17 +107,7 @@ For the adventurously minded - if you want to buy an internal bluetooth module off the internet that is compatible with your laptop and fit it, then it will work just fine with acer-wmi. -To read the status of the bluetooth module (0=off, 1=on): -cat /sys/devices/platform/acer-wmi/wireless - -To enable the bluetooth module: -echo 1 > /sys/devices/platform/acer-wmi/bluetooth - -To disable the bluetooth module: -echo 0 > /sys/devices/platform/acer-wmi/bluetooth - -To set the state of the bluetooth module when loading acer-wmi, pass: -bluetooth=X (where X is 0 or 1) +Bluetooth is exposed through rfkill. 3G ** diff --git a/Documentation/lguest/Makefile b/Documentation/lguest/Makefile index bac037eb1cd..725eef81cd4 100644 --- a/Documentation/lguest/Makefile +++ b/Documentation/lguest/Makefile @@ -1,5 +1,5 @@ # This creates the demonstration utility "lguest" which runs a Linux guest. -CFLAGS:=-Wall -Wmissing-declarations -Wmissing-prototypes -O3 -I../../include +CFLAGS:=-Wall -Wmissing-declarations -Wmissing-prototypes -O3 -I../../include -I../../arch/x86/include LDLIBS:=-lz all: lguest diff --git a/Documentation/lguest/lguest.c b/Documentation/lguest/lguest.c index 7228369d101..f2dbbf3bdea 100644 --- a/Documentation/lguest/lguest.c +++ b/Documentation/lguest/lguest.c @@ -44,7 +44,7 @@ #include "linux/virtio_console.h" #include "linux/virtio_rng.h" #include "linux/virtio_ring.h" -#include "asm-x86/bootparam.h" +#include "asm/bootparam.h" /*L:110 We can ignore the 39 include files we need for this program, but I do * want to draw attention to the use of kernel-style types. * @@ -402,7 +402,7 @@ static unsigned long load_bzimage(int fd) void *p = from_guest_phys(0x100000); /* Go back to the start of the file and read the header. It should be - * a Linux boot header (see Documentation/i386/boot.txt) */ + * a Linux boot header (see Documentation/x86/i386/boot.txt) */ lseek(fd, 0, SEEK_SET); read(fd, &boot, sizeof(boot)); @@ -481,51 +481,6 @@ static unsigned long load_initrd(const char *name, unsigned long mem) /* We return the initrd size. */ return len; } - -/* Once we know how much memory we have we can construct simple linear page - * tables which set virtual == physical which will get the Guest far enough - * into the boot to create its own. - * - * We lay them out of the way, just below the initrd (which is why we need to - * know its size here). */ -static unsigned long setup_pagetables(unsigned long mem, - unsigned long initrd_size) -{ - unsigned long *pgdir, *linear; - unsigned int mapped_pages, i, linear_pages; - unsigned int ptes_per_page = getpagesize()/sizeof(void *); - - mapped_pages = mem/getpagesize(); - - /* Each PTE page can map ptes_per_page pages: how many do we need? */ - linear_pages = (mapped_pages + ptes_per_page-1)/ptes_per_page; - - /* We put the toplevel page directory page at the top of memory. */ - pgdir = from_guest_phys(mem) - initrd_size - getpagesize(); - - /* Now we use the next linear_pages pages as pte pages */ - linear = (void *)pgdir - linear_pages*getpagesize(); - - /* Linear mapping is easy: put every page's address into the mapping in - * order. PAGE_PRESENT contains the flags Present, Writable and - * Executable. */ - for (i = 0; i < mapped_pages; i++) - linear[i] = ((i * getpagesize()) | PAGE_PRESENT); - - /* The top level points to the linear page table pages above. */ - for (i = 0; i < mapped_pages; i += ptes_per_page) { - pgdir[i/ptes_per_page] - = ((to_guest_phys(linear) + i*sizeof(void *)) - | PAGE_PRESENT); - } - - verbose("Linear mapping of %u pages in %u pte pages at %#lx\n", - mapped_pages, linear_pages, to_guest_phys(linear)); - - /* We return the top level (guest-physical) address: the kernel needs - * to know where it is. */ - return to_guest_phys(pgdir); -} /*:*/ /* Simple routine to roll all the commandline arguments together with spaces @@ -548,13 +503,13 @@ static void concat(char *dst, char *args[]) /*L:185 This is where we actually tell the kernel to initialize the Guest. We * saw the arguments it expects when we looked at initialize() in lguest_user.c: - * the base of Guest "physical" memory, the top physical page to allow, the - * top level pagetable and the entry point for the Guest. */ -static int tell_kernel(unsigned long pgdir, unsigned long start) + * the base of Guest "physical" memory, the top physical page to allow and the + * entry point for the Guest. */ +static int tell_kernel(unsigned long start) { unsigned long args[] = { LHREQ_INITIALIZE, (unsigned long)guest_base, - guest_limit / getpagesize(), pgdir, start }; + guest_limit / getpagesize(), start }; int fd; verbose("Guest: %p - %p (%#lx)\n", @@ -1030,7 +985,7 @@ static void update_device_status(struct device *dev) /* Zero out the virtqueues. */ for (vq = dev->vq; vq; vq = vq->next) { memset(vq->vring.desc, 0, - vring_size(vq->config.num, getpagesize())); + vring_size(vq->config.num, LGUEST_VRING_ALIGN)); lg_last_avail(vq) = 0; } } else if (dev->desc->status & VIRTIO_CONFIG_S_FAILED) { @@ -1211,7 +1166,7 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs, void *p; /* First we need some memory for this virtqueue. */ - pages = (vring_size(num_descs, getpagesize()) + getpagesize() - 1) + pages = (vring_size(num_descs, LGUEST_VRING_ALIGN) + getpagesize() - 1) / getpagesize(); p = get_pages(pages); @@ -1228,7 +1183,7 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs, vq->config.pfn = to_guest_phys(p) / getpagesize(); /* Initialize the vring. */ - vring_init(&vq->vring, num_descs, p, getpagesize()); + vring_init(&vq->vring, num_descs, p, LGUEST_VRING_ALIGN); /* Append virtqueue to this device's descriptor. We use * device_config() to get the end of the device's current virtqueues; @@ -1941,7 +1896,7 @@ int main(int argc, char *argv[]) { /* Memory, top-level pagetable, code startpoint and size of the * (optional) initrd. */ - unsigned long mem = 0, pgdir, start, initrd_size = 0; + unsigned long mem = 0, start, initrd_size = 0; /* Two temporaries and the /dev/lguest file descriptor. */ int i, c, lguest_fd; /* The boot information for the Guest. */ @@ -2040,9 +1995,6 @@ int main(int argc, char *argv[]) boot->hdr.type_of_loader = 0xFF; } - /* Set up the initial linear pagetables, starting below the initrd. */ - pgdir = setup_pagetables(mem, initrd_size); - /* The Linux boot header contains an "E820" memory map: ours is a * simple, single region. */ boot->e820_entries = 1; @@ -2064,7 +2016,7 @@ int main(int argc, char *argv[]) /* We tell the kernel to initialize the Guest: this returns the open * /dev/lguest file descriptor. */ - lguest_fd = tell_kernel(pgdir, start); + lguest_fd = tell_kernel(start); /* We clone off a thread, which wakes the Launcher whenever one of the * input file descriptors needs attention. We call this the Waker, and diff --git a/Documentation/local_ops.txt b/Documentation/local_ops.txt index f4f8b1c6c8b..23045b8b50f 100644 --- a/Documentation/local_ops.txt +++ b/Documentation/local_ops.txt @@ -149,7 +149,7 @@ static void do_test_timer(unsigned long data) int cpu; /* Increment the counters */ - on_each_cpu(test_each, NULL, 0, 1); + on_each_cpu(test_each, NULL, 1); /* Read all the counters */ printk("Counters read from CPU %d\n", smp_processor_id()); for_each_online_cpu(cpu) { diff --git a/Documentation/lockstat.txt b/Documentation/lockstat.txt index 4ba4664ce5c..9cb9138f7a7 100644 --- a/Documentation/lockstat.txt +++ b/Documentation/lockstat.txt @@ -71,35 +71,50 @@ Look at the current lock statistics: # less /proc/lock_stat -01 lock_stat version 0.2 +01 lock_stat version 0.3 02 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 03 class name con-bounces contentions waittime-min waittime-max waittime-total acq-bounces acquisitions holdtime-min holdtime-max holdtime-total 04 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 05 -06 &inode->i_data.tree_lock-W: 15 21657 0.18 1093295.30 11547131054.85 58 10415 0.16 87.51 6387.60 -07 &inode->i_data.tree_lock-R: 0 0 0.00 0.00 0.00 23302 231198 0.25 8.45 98023.38 -08 -------------------------- -09 &inode->i_data.tree_lock 0 [<ffffffff8027c08f>] add_to_page_cache+0x5f/0x190 -10 -11 ............................................................................................................................................................................................... -12 -13 dcache_lock: 1037 1161 0.38 45.32 774.51 6611 243371 0.15 306.48 77387.24 -14 ----------- -15 dcache_lock 180 [<ffffffff802c0d7e>] sys_getcwd+0x11e/0x230 -16 dcache_lock 165 [<ffffffff802c002a>] d_alloc+0x15a/0x210 -17 dcache_lock 33 [<ffffffff8035818d>] _atomic_dec_and_lock+0x4d/0x70 -18 dcache_lock 1 [<ffffffff802beef8>] shrink_dcache_parent+0x18/0x130 +06 &mm->mmap_sem-W: 233 538 18446744073708 22924.27 607243.51 1342 45806 1.71 8595.89 1180582.34 +07 &mm->mmap_sem-R: 205 587 18446744073708 28403.36 731975.00 1940 412426 0.58 187825.45 6307502.88 +08 --------------- +09 &mm->mmap_sem 487 [<ffffffff8053491f>] do_page_fault+0x466/0x928 +10 &mm->mmap_sem 179 [<ffffffff802a6200>] sys_mprotect+0xcd/0x21d +11 &mm->mmap_sem 279 [<ffffffff80210a57>] sys_mmap+0x75/0xce +12 &mm->mmap_sem 76 [<ffffffff802a490b>] sys_munmap+0x32/0x59 +13 --------------- +14 &mm->mmap_sem 270 [<ffffffff80210a57>] sys_mmap+0x75/0xce +15 &mm->mmap_sem 431 [<ffffffff8053491f>] do_page_fault+0x466/0x928 +16 &mm->mmap_sem 138 [<ffffffff802a490b>] sys_munmap+0x32/0x59 +17 &mm->mmap_sem 145 [<ffffffff802a6200>] sys_mprotect+0xcd/0x21d +18 +19 ............................................................................................................................................................................................... +20 +21 dcache_lock: 621 623 0.52 118.26 1053.02 6745 91930 0.29 316.29 118423.41 +22 ----------- +23 dcache_lock 179 [<ffffffff80378274>] _atomic_dec_and_lock+0x34/0x54 +24 dcache_lock 113 [<ffffffff802cc17b>] d_alloc+0x19a/0x1eb +25 dcache_lock 99 [<ffffffff802ca0dc>] d_rehash+0x1b/0x44 +26 dcache_lock 104 [<ffffffff802cbca0>] d_instantiate+0x36/0x8a +27 ----------- +28 dcache_lock 192 [<ffffffff80378274>] _atomic_dec_and_lock+0x34/0x54 +29 dcache_lock 98 [<ffffffff802ca0dc>] d_rehash+0x1b/0x44 +30 dcache_lock 72 [<ffffffff802cc17b>] d_alloc+0x19a/0x1eb +31 dcache_lock 112 [<ffffffff802cbca0>] d_instantiate+0x36/0x8a This excerpt shows the first two lock class statistics. Line 01 shows the output version - each time the format changes this will be updated. Line 02-04 -show the header with column descriptions. Lines 05-10 and 13-18 show the actual +show the header with column descriptions. Lines 05-18 and 20-31 show the actual statistics. These statistics come in two parts; the actual stats separated by a -short separator (line 08, 14) from the contention points. +short separator (line 08, 13) from the contention points. -The first lock (05-10) is a read/write lock, and shows two lines above the +The first lock (05-18) is a read/write lock, and shows two lines above the short separator. The contention points don't match the column descriptors, -they have two: contentions and [<IP>] symbol. +they have two: contentions and [<IP>] symbol. The second set of contention +points are the points we're contending with. +The integer part of the time values is in us. View the top contending locks: diff --git a/Documentation/markers.txt b/Documentation/markers.txt index d9f50a19fa0..d2b3d0e91b2 100644 --- a/Documentation/markers.txt +++ b/Documentation/markers.txt @@ -50,10 +50,17 @@ Connecting a function (probe) to a marker is done by providing a probe (function to call) for the specific marker through marker_probe_register() and can be activated by calling marker_arm(). Marker deactivation can be done by calling marker_disarm() as many times as marker_arm() has been called. Removing a probe -is done through marker_probe_unregister(); it will disarm the probe and make -sure there is no caller left using the probe when it returns. Probe removal is -preempt-safe because preemption is disabled around the probe call. See the -"Probe example" section below for a sample probe module. +is done through marker_probe_unregister(); it will disarm the probe. + +marker_synchronize_unregister() must be called between probe unregistration and +the first occurrence of +- the end of module exit function, + to make sure there is no caller left using the probe; +- the free of any resource used by the probes, + to make sure the probes wont be accessing invalid data. +This, and the fact that preemption is disabled around the probe call, make sure +that probe removal and module unload are safe. See the "Probe example" section +below for a sample probe module. The marker mechanism supports inserting multiple instances of the same marker. Markers can be put in inline functions, inlined static functions, and @@ -68,6 +75,20 @@ a printk warning which identifies the inconsistency: "Format mismatch for probe probe_name (format), marker (format)" +Another way to use markers is to simply define the marker without generating any +function call to actually call into the marker. This is useful in combination +with tracepoint probes in a scheme like this : + +void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk); + +DEFINE_MARKER_TP(marker_eventname, tracepoint_name, probe_tracepoint_name, + "arg1 %u pid %d"); + +notrace void probe_tracepoint_name(unsigned int arg1, struct task_struct *tsk) +{ + struct marker *marker = &GET_MARKER(kernel_irq_entry); + /* write data to trace buffers ... */ +} * Probe / marker example diff --git a/Documentation/mtd/nand_ecc.txt b/Documentation/mtd/nand_ecc.txt new file mode 100644 index 00000000000..bdf93b7f0f2 --- /dev/null +++ b/Documentation/mtd/nand_ecc.txt @@ -0,0 +1,714 @@ +Introduction +============ + +Having looked at the linux mtd/nand driver and more specific at nand_ecc.c +I felt there was room for optimisation. I bashed the code for a few hours +performing tricks like table lookup removing superfluous code etc. +After that the speed was increased by 35-40%. +Still I was not too happy as I felt there was additional room for improvement. + +Bad! I was hooked. +I decided to annotate my steps in this file. Perhaps it is useful to someone +or someone learns something from it. + + +The problem +=========== + +NAND flash (at least SLC one) typically has sectors of 256 bytes. +However NAND flash is not extremely reliable so some error detection +(and sometimes correction) is needed. + +This is done by means of a Hamming code. I'll try to explain it in +laymans terms (and apologies to all the pro's in the field in case I do +not use the right terminology, my coding theory class was almost 30 +years ago, and I must admit it was not one of my favourites). + +As I said before the ecc calculation is performed on sectors of 256 +bytes. This is done by calculating several parity bits over the rows and +columns. The parity used is even parity which means that the parity bit = 1 +if the data over which the parity is calculated is 1 and the parity bit = 0 +if the data over which the parity is calculated is 0. So the total +number of bits over the data over which the parity is calculated + the +parity bit is even. (see wikipedia if you can't follow this). +Parity is often calculated by means of an exclusive or operation, +sometimes also referred to as xor. In C the operator for xor is ^ + +Back to ecc. +Let's give a small figure: + +byte 0: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp2 rp4 ... rp14 +byte 1: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp1 rp2 rp4 ... rp14 +byte 2: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp3 rp4 ... rp14 +byte 3: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp1 rp3 rp4 ... rp14 +byte 4: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp2 rp5 ... rp14 +.... +byte 254: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp3 rp5 ... rp15 +byte 255: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp1 rp3 rp5 ... rp15 + cp1 cp0 cp1 cp0 cp1 cp0 cp1 cp0 + cp3 cp3 cp2 cp2 cp3 cp3 cp2 cp2 + cp5 cp5 cp5 cp5 cp4 cp4 cp4 cp4 + +This figure represents a sector of 256 bytes. +cp is my abbreviaton for column parity, rp for row parity. + +Let's start to explain column parity. +cp0 is the parity that belongs to all bit0, bit2, bit4, bit6. +so the sum of all bit0, bit2, bit4 and bit6 values + cp0 itself is even. +Similarly cp1 is the sum of all bit1, bit3, bit5 and bit7. +cp2 is the parity over bit0, bit1, bit4 and bit5 +cp3 is the parity over bit2, bit3, bit6 and bit7. +cp4 is the parity over bit0, bit1, bit2 and bit3. +cp5 is the parity over bit4, bit5, bit6 and bit7. +Note that each of cp0 .. cp5 is exactly one bit. + +Row parity actually works almost the same. +rp0 is the parity of all even bytes (0, 2, 4, 6, ... 252, 254) +rp1 is the parity of all odd bytes (1, 3, 5, 7, ..., 253, 255) +rp2 is the parity of all bytes 0, 1, 4, 5, 8, 9, ... +(so handle two bytes, then skip 2 bytes). +rp3 is covers the half rp2 does not cover (bytes 2, 3, 6, 7, 10, 11, ...) +for rp4 the rule is cover 4 bytes, skip 4 bytes, cover 4 bytes, skip 4 etc. +so rp4 calculates parity over bytes 0, 1, 2, 3, 8, 9, 10, 11, 16, ...) +and rp5 covers the other half, so bytes 4, 5, 6, 7, 12, 13, 14, 15, 20, .. +The story now becomes quite boring. I guess you get the idea. +rp6 covers 8 bytes then skips 8 etc +rp7 skips 8 bytes then covers 8 etc +rp8 covers 16 bytes then skips 16 etc +rp9 skips 16 bytes then covers 16 etc +rp10 covers 32 bytes then skips 32 etc +rp11 skips 32 bytes then covers 32 etc +rp12 covers 64 bytes then skips 64 etc +rp13 skips 64 bytes then covers 64 etc +rp14 covers 128 bytes then skips 128 +rp15 skips 128 bytes then covers 128 + +In the end the parity bits are grouped together in three bytes as +follows: +ECC Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 +ECC 0 rp07 rp06 rp05 rp04 rp03 rp02 rp01 rp00 +ECC 1 rp15 rp14 rp13 rp12 rp11 rp10 rp09 rp08 +ECC 2 cp5 cp4 cp3 cp2 cp1 cp0 1 1 + +I detected after writing this that ST application note AN1823 +(http://www.st.com/stonline/books/pdf/docs/10123.pdf) gives a much +nicer picture.(but they use line parity as term where I use row parity) +Oh well, I'm graphically challenged, so suffer with me for a moment :-) +And I could not reuse the ST picture anyway for copyright reasons. + + +Attempt 0 +========= + +Implementing the parity calculation is pretty simple. +In C pseudocode: +for (i = 0; i < 256; i++) +{ + if (i & 0x01) + rp1 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp1; + else + rp0 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp1; + if (i & 0x02) + rp3 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp3; + else + rp2 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp2; + if (i & 0x04) + rp5 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp5; + else + rp4 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp4; + if (i & 0x08) + rp7 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp7; + else + rp6 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp6; + if (i & 0x10) + rp9 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp9; + else + rp8 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp8; + if (i & 0x20) + rp11 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp11; + else + rp10 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp10; + if (i & 0x40) + rp13 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp13; + else + rp12 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp12; + if (i & 0x80) + rp15 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp15; + else + rp14 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp14; + cp0 = bit6 ^ bit4 ^ bit2 ^ bit0 ^ cp0; + cp1 = bit7 ^ bit5 ^ bit3 ^ bit1 ^ cp1; + cp2 = bit5 ^ bit4 ^ bit1 ^ bit0 ^ cp2; + cp3 = bit7 ^ bit6 ^ bit3 ^ bit2 ^ cp3 + cp4 = bit3 ^ bit2 ^ bit1 ^ bit0 ^ cp4 + cp5 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ cp5 +} + + +Analysis 0 +========== + +C does have bitwise operators but not really operators to do the above +efficiently (and most hardware has no such instructions either). +Therefore without implementing this it was clear that the code above was +not going to bring me a Nobel prize :-) + +Fortunately the exclusive or operation is commutative, so we can combine +the values in any order. So instead of calculating all the bits +individually, let us try to rearrange things. +For the column parity this is easy. We can just xor the bytes and in the +end filter out the relevant bits. This is pretty nice as it will bring +all cp calculation out of the if loop. + +Similarly we can first xor the bytes for the various rows. +This leads to: + + +Attempt 1 +========= + +const char parity[256] = { + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0 +}; + +void ecc1(const unsigned char *buf, unsigned char *code) +{ + int i; + const unsigned char *bp = buf; + unsigned char cur; + unsigned char rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7; + unsigned char rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15; + unsigned char par; + + par = 0; + rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0; + rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0; + rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0; + rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0; + + for (i = 0; i < 256; i++) + { + cur = *bp++; + par ^= cur; + if (i & 0x01) rp1 ^= cur; else rp0 ^= cur; + if (i & 0x02) rp3 ^= cur; else rp2 ^= cur; + if (i & 0x04) rp5 ^= cur; else rp4 ^= cur; + if (i & 0x08) rp7 ^= cur; else rp6 ^= cur; + if (i & 0x10) rp9 ^= cur; else rp8 ^= cur; + if (i & 0x20) rp11 ^= cur; else rp10 ^= cur; + if (i & 0x40) rp13 ^= cur; else rp12 ^= cur; + if (i & 0x80) rp15 ^= cur; else rp14 ^= cur; + } + code[0] = + (parity[rp7] << 7) | + (parity[rp6] << 6) | + (parity[rp5] << 5) | + (parity[rp4] << 4) | + (parity[rp3] << 3) | + (parity[rp2] << 2) | + (parity[rp1] << 1) | + (parity[rp0]); + code[1] = + (parity[rp15] << 7) | + (parity[rp14] << 6) | + (parity[rp13] << 5) | + (parity[rp12] << 4) | + (parity[rp11] << 3) | + (parity[rp10] << 2) | + (parity[rp9] << 1) | + (parity[rp8]); + code[2] = + (parity[par & 0xf0] << 7) | + (parity[par & 0x0f] << 6) | + (parity[par & 0xcc] << 5) | + (parity[par & 0x33] << 4) | + (parity[par & 0xaa] << 3) | + (parity[par & 0x55] << 2); + code[0] = ~code[0]; + code[1] = ~code[1]; + code[2] = ~code[2]; +} + +Still pretty straightforward. The last three invert statements are there to +give a checksum of 0xff 0xff 0xff for an empty flash. In an empty flash +all data is 0xff, so the checksum then matches. + +I also introduced the parity lookup. I expected this to be the fastest +way to calculate the parity, but I will investigate alternatives later +on. + + +Analysis 1 +========== + +The code works, but is not terribly efficient. On my system it took +almost 4 times as much time as the linux driver code. But hey, if it was +*that* easy this would have been done long before. +No pain. no gain. + +Fortunately there is plenty of room for improvement. + +In step 1 we moved from bit-wise calculation to byte-wise calculation. +However in C we can also use the unsigned long data type and virtually +every modern microprocessor supports 32 bit operations, so why not try +to write our code in such a way that we process data in 32 bit chunks. + +Of course this means some modification as the row parity is byte by +byte. A quick analysis: +for the column parity we use the par variable. When extending to 32 bits +we can in the end easily calculate p0 and p1 from it. +(because par now consists of 4 bytes, contributing to rp1, rp0, rp1, rp0 +respectively) +also rp2 and rp3 can be easily retrieved from par as rp3 covers the +first two bytes and rp2 the last two bytes. + +Note that of course now the loop is executed only 64 times (256/4). +And note that care must taken wrt byte ordering. The way bytes are +ordered in a long is machine dependent, and might affect us. +Anyway, if there is an issue: this code is developed on x86 (to be +precise: a DELL PC with a D920 Intel CPU) + +And of course the performance might depend on alignment, but I expect +that the I/O buffers in the nand driver are aligned properly (and +otherwise that should be fixed to get maximum performance). + +Let's give it a try... + + +Attempt 2 +========= + +extern const char parity[256]; + +void ecc2(const unsigned char *buf, unsigned char *code) +{ + int i; + const unsigned long *bp = (unsigned long *)buf; + unsigned long cur; + unsigned long rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7; + unsigned long rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15; + unsigned long par; + + par = 0; + rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0; + rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0; + rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0; + rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0; + + for (i = 0; i < 64; i++) + { + cur = *bp++; + par ^= cur; + if (i & 0x01) rp5 ^= cur; else rp4 ^= cur; + if (i & 0x02) rp7 ^= cur; else rp6 ^= cur; + if (i & 0x04) rp9 ^= cur; else rp8 ^= cur; + if (i & 0x08) rp11 ^= cur; else rp10 ^= cur; + if (i & 0x10) rp13 ^= cur; else rp12 ^= cur; + if (i & 0x20) rp15 ^= cur; else rp14 ^= cur; + } + /* + we need to adapt the code generation for the fact that rp vars are now + long; also the column parity calculation needs to be changed. + we'll bring rp4 to 15 back to single byte entities by shifting and + xoring + */ + rp4 ^= (rp4 >> 16); rp4 ^= (rp4 >> 8); rp4 &= 0xff; + rp5 ^= (rp5 >> 16); rp5 ^= (rp5 >> 8); rp5 &= 0xff; + rp6 ^= (rp6 >> 16); rp6 ^= (rp6 >> 8); rp6 &= 0xff; + rp7 ^= (rp7 >> 16); rp7 ^= (rp7 >> 8); rp7 &= 0xff; + rp8 ^= (rp8 >> 16); rp8 ^= (rp8 >> 8); rp8 &= 0xff; + rp9 ^= (rp9 >> 16); rp9 ^= (rp9 >> 8); rp9 &= 0xff; + rp10 ^= (rp10 >> 16); rp10 ^= (rp10 >> 8); rp10 &= 0xff; + rp11 ^= (rp11 >> 16); rp11 ^= (rp11 >> 8); rp11 &= 0xff; + rp12 ^= (rp12 >> 16); rp12 ^= (rp12 >> 8); rp12 &= 0xff; + rp13 ^= (rp13 >> 16); rp13 ^= (rp13 >> 8); rp13 &= 0xff; + rp14 ^= (rp14 >> 16); rp14 ^= (rp14 >> 8); rp14 &= 0xff; + rp15 ^= (rp15 >> 16); rp15 ^= (rp15 >> 8); rp15 &= 0xff; + rp3 = (par >> 16); rp3 ^= (rp3 >> 8); rp3 &= 0xff; + rp2 = par & 0xffff; rp2 ^= (rp2 >> 8); rp2 &= 0xff; + par ^= (par >> 16); + rp1 = (par >> 8); rp1 &= 0xff; + rp0 = (par & 0xff); + par ^= (par >> 8); par &= 0xff; + + code[0] = + (parity[rp7] << 7) | + (parity[rp6] << 6) | + (parity[rp5] << 5) | + (parity[rp4] << 4) | + (parity[rp3] << 3) | + (parity[rp2] << 2) | + (parity[rp1] << 1) | + (parity[rp0]); + code[1] = + (parity[rp15] << 7) | + (parity[rp14] << 6) | + (parity[rp13] << 5) | + (parity[rp12] << 4) | + (parity[rp11] << 3) | + (parity[rp10] << 2) | + (parity[rp9] << 1) | + (parity[rp8]); + code[2] = + (parity[par & 0xf0] << 7) | + (parity[par & 0x0f] << 6) | + (parity[par & 0xcc] << 5) | + (parity[par & 0x33] << 4) | + (parity[par & 0xaa] << 3) | + (parity[par & 0x55] << 2); + code[0] = ~code[0]; + code[1] = ~code[1]; + code[2] = ~code[2]; +} + +The parity array is not shown any more. Note also that for these +examples I kinda deviated from my regular programming style by allowing +multiple statements on a line, not using { } in then and else blocks +with only a single statement and by using operators like ^= + + +Analysis 2 +========== + +The code (of course) works, and hurray: we are a little bit faster than +the linux driver code (about 15%). But wait, don't cheer too quickly. +THere is more to be gained. +If we look at e.g. rp14 and rp15 we see that we either xor our data with +rp14 or with rp15. However we also have par which goes over all data. +This means there is no need to calculate rp14 as it can be calculated from +rp15 through rp14 = par ^ rp15; +(or if desired we can avoid calculating rp15 and calculate it from +rp14). That is why some places refer to inverse parity. +Of course the same thing holds for rp4/5, rp6/7, rp8/9, rp10/11 and rp12/13. +Effectively this means we can eliminate the else clause from the if +statements. Also we can optimise the calculation in the end a little bit +by going from long to byte first. Actually we can even avoid the table +lookups + +Attempt 3 +========= + +Odd replaced: + if (i & 0x01) rp5 ^= cur; else rp4 ^= cur; + if (i & 0x02) rp7 ^= cur; else rp6 ^= cur; + if (i & 0x04) rp9 ^= cur; else rp8 ^= cur; + if (i & 0x08) rp11 ^= cur; else rp10 ^= cur; + if (i & 0x10) rp13 ^= cur; else rp12 ^= cur; + if (i & 0x20) rp15 ^= cur; else rp14 ^= cur; +with + if (i & 0x01) rp5 ^= cur; + if (i & 0x02) rp7 ^= cur; + if (i & 0x04) rp9 ^= cur; + if (i & 0x08) rp11 ^= cur; + if (i & 0x10) rp13 ^= cur; + if (i & 0x20) rp15 ^= cur; + + and outside the loop added: + rp4 = par ^ rp5; + rp6 = par ^ rp7; + rp8 = par ^ rp9; + rp10 = par ^ rp11; + rp12 = par ^ rp13; + rp14 = par ^ rp15; + +And after that the code takes about 30% more time, although the number of +statements is reduced. This is also reflected in the assembly code. + + +Analysis 3 +========== + +Very weird. Guess it has to do with caching or instruction parallellism +or so. I also tried on an eeePC (Celeron, clocked at 900 Mhz). Interesting +observation was that this one is only 30% slower (according to time) +executing the code as my 3Ghz D920 processor. + +Well, it was expected not to be easy so maybe instead move to a +different track: let's move back to the code from attempt2 and do some +loop unrolling. This will eliminate a few if statements. I'll try +different amounts of unrolling to see what works best. + + +Attempt 4 +========= + +Unrolled the loop 1, 2, 3 and 4 times. +For 4 the code starts with: + + for (i = 0; i < 4; i++) + { + cur = *bp++; + par ^= cur; + rp4 ^= cur; + rp6 ^= cur; + rp8 ^= cur; + rp10 ^= cur; + if (i & 0x1) rp13 ^= cur; else rp12 ^= cur; + if (i & 0x2) rp15 ^= cur; else rp14 ^= cur; + cur = *bp++; + par ^= cur; + rp5 ^= cur; + rp6 ^= cur; + ... + + +Analysis 4 +========== + +Unrolling once gains about 15% +Unrolling twice keeps the gain at about 15% +Unrolling three times gives a gain of 30% compared to attempt 2. +Unrolling four times gives a marginal improvement compared to unrolling +three times. + +I decided to proceed with a four time unrolled loop anyway. It was my gut +feeling that in the next steps I would obtain additional gain from it. + +The next step was triggered by the fact that par contains the xor of all +bytes and rp4 and rp5 each contain the xor of half of the bytes. +So in effect par = rp4 ^ rp5. But as xor is commutative we can also say +that rp5 = par ^ rp4. So no need to keep both rp4 and rp5 around. We can +eliminate rp5 (or rp4, but I already foresaw another optimisation). +The same holds for rp6/7, rp8/9, rp10/11 rp12/13 and rp14/15. + + +Attempt 5 +========= + +Effectively so all odd digit rp assignments in the loop were removed. +This included the else clause of the if statements. +Of course after the loop we need to correct things by adding code like: + rp5 = par ^ rp4; +Also the initial assignments (rp5 = 0; etc) could be removed. +Along the line I also removed the initialisation of rp0/1/2/3. + + +Analysis 5 +========== + +Measurements showed this was a good move. The run-time roughly halved +compared with attempt 4 with 4 times unrolled, and we only require 1/3rd +of the processor time compared to the current code in the linux kernel. + +However, still I thought there was more. I didn't like all the if +statements. Why not keep a running parity and only keep the last if +statement. Time for yet another version! + + +Attempt 6 +========= + +THe code within the for loop was changed to: + + for (i = 0; i < 4; i++) + { + cur = *bp++; tmppar = cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; rp6 ^= tmppar; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; rp8 ^= tmppar; + + cur = *bp++; tmppar ^= cur; rp4 ^= cur; rp6 ^= cur; + cur = *bp++; tmppar ^= cur; rp6 ^= cur; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; rp10 ^= tmppar; + + cur = *bp++; tmppar ^= cur; rp4 ^= cur; rp6 ^= cur; rp8 ^= cur; + cur = *bp++; tmppar ^= cur; rp6 ^= cur; rp8 ^= cur; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; rp8 ^= cur; + cur = *bp++; tmppar ^= cur; rp8 ^= cur; + + cur = *bp++; tmppar ^= cur; rp4 ^= cur; rp6 ^= cur; + cur = *bp++; tmppar ^= cur; rp6 ^= cur; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; + + par ^= tmppar; + if ((i & 0x1) == 0) rp12 ^= tmppar; + if ((i & 0x2) == 0) rp14 ^= tmppar; + } + +As you can see tmppar is used to accumulate the parity within a for +iteration. In the last 3 statements is is added to par and, if needed, +to rp12 and rp14. + +While making the changes I also found that I could exploit that tmppar +contains the running parity for this iteration. So instead of having: +rp4 ^= cur; rp6 = cur; +I removed the rp6 = cur; statement and did rp6 ^= tmppar; on next +statement. A similar change was done for rp8 and rp10 + + +Analysis 6 +========== + +Measuring this code again showed big gain. When executing the original +linux code 1 million times, this took about 1 second on my system. +(using time to measure the performance). After this iteration I was back +to 0.075 sec. Actually I had to decide to start measuring over 10 +million interations in order not to loose too much accuracy. This one +definitely seemed to be the jackpot! + +There is a little bit more room for improvement though. There are three +places with statements: +rp4 ^= cur; rp6 ^= cur; +It seems more efficient to also maintain a variable rp4_6 in the while +loop; This eliminates 3 statements per loop. Of course after the loop we +need to correct by adding: + rp4 ^= rp4_6; + rp6 ^= rp4_6 +Furthermore there are 4 sequential assingments to rp8. This can be +encoded slightly more efficient by saving tmppar before those 4 lines +and later do rp8 = rp8 ^ tmppar ^ notrp8; +(where notrp8 is the value of rp8 before those 4 lines). +Again a use of the commutative property of xor. +Time for a new test! + + +Attempt 7 +========= + +The new code now looks like: + + for (i = 0; i < 4; i++) + { + cur = *bp++; tmppar = cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; rp6 ^= tmppar; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; rp8 ^= tmppar; + + cur = *bp++; tmppar ^= cur; rp4_6 ^= cur; + cur = *bp++; tmppar ^= cur; rp6 ^= cur; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; rp10 ^= tmppar; + + notrp8 = tmppar; + cur = *bp++; tmppar ^= cur; rp4_6 ^= cur; + cur = *bp++; tmppar ^= cur; rp6 ^= cur; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; + rp8 = rp8 ^ tmppar ^ notrp8; + + cur = *bp++; tmppar ^= cur; rp4_6 ^= cur; + cur = *bp++; tmppar ^= cur; rp6 ^= cur; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; + + par ^= tmppar; + if ((i & 0x1) == 0) rp12 ^= tmppar; + if ((i & 0x2) == 0) rp14 ^= tmppar; + } + rp4 ^= rp4_6; + rp6 ^= rp4_6; + + +Not a big change, but every penny counts :-) + + +Analysis 7 +========== + +Acutally this made things worse. Not very much, but I don't want to move +into the wrong direction. Maybe something to investigate later. Could +have to do with caching again. + +Guess that is what there is to win within the loop. Maybe unrolling one +more time will help. I'll keep the optimisations from 7 for now. + + +Attempt 8 +========= + +Unrolled the loop one more time. + + +Analysis 8 +========== + +This makes things worse. Let's stick with attempt 6 and continue from there. +Although it seems that the code within the loop cannot be optimised +further there is still room to optimize the generation of the ecc codes. +We can simply calcualate the total parity. If this is 0 then rp4 = rp5 +etc. If the parity is 1, then rp4 = !rp5; +But if rp4 = rp5 we do not need rp5 etc. We can just write the even bits +in the result byte and then do something like + code[0] |= (code[0] << 1); +Lets test this. + + +Attempt 9 +========= + +Changed the code but again this slightly degrades performance. Tried all +kind of other things, like having dedicated parity arrays to avoid the +shift after parity[rp7] << 7; No gain. +Change the lookup using the parity array by using shift operators (e.g. +replace parity[rp7] << 7 with: +rp7 ^= (rp7 << 4); +rp7 ^= (rp7 << 2); +rp7 ^= (rp7 << 1); +rp7 &= 0x80; +No gain. + +The only marginal change was inverting the parity bits, so we can remove +the last three invert statements. + +Ah well, pity this does not deliver more. Then again 10 million +iterations using the linux driver code takes between 13 and 13.5 +seconds, whereas my code now takes about 0.73 seconds for those 10 +million iterations. So basically I've improved the performance by a +factor 18 on my system. Not that bad. Of course on different hardware +you will get different results. No warranties! + +But of course there is no such thing as a free lunch. The codesize almost +tripled (from 562 bytes to 1434 bytes). Then again, it is not that much. + + +Correcting errors +================= + +For correcting errors I again used the ST application note as a starter, +but I also peeked at the existing code. +The algorithm itself is pretty straightforward. Just xor the given and +the calculated ecc. If all bytes are 0 there is no problem. If 11 bits +are 1 we have one correctable bit error. If there is 1 bit 1, we have an +error in the given ecc code. +It proved to be fastest to do some table lookups. Performance gain +introduced by this is about a factor 2 on my system when a repair had to +be done, and 1% or so if no repair had to be done. +Code size increased from 330 bytes to 686 bytes for this function. +(gcc 4.2, -O3) + + +Conclusion +========== + +The gain when calculating the ecc is tremendous. Om my development hardware +a speedup of a factor of 18 for ecc calculation was achieved. On a test on an +embedded system with a MIPS core a factor 7 was obtained. +On a test with a Linksys NSLU2 (ARMv5TE processor) the speedup was a factor +5 (big endian mode, gcc 4.1.2, -O3) +For correction not much gain could be obtained (as bitflips are rare). Then +again there are also much less cycles spent there. + +It seems there is not much more gain possible in this, at least when +programmed in C. Of course it might be possible to squeeze something more +out of it with an assembler program, but due to pipeline behaviour etc +this is very tricky (at least for intel hw). + +Author: Frans Meulenbroeks +Copyright (C) 2008 Koninklijke Philips Electronics NV. diff --git a/Documentation/networking/.gitignore b/Documentation/networking/.gitignore new file mode 100644 index 00000000000..286a5680f49 --- /dev/null +++ b/Documentation/networking/.gitignore @@ -0,0 +1 @@ +ifenslave diff --git a/Documentation/networking/README.ipw2200 b/Documentation/networking/README.ipw2200 index 4f2a40f1dbc..80c728522c4 100644 --- a/Documentation/networking/README.ipw2200 +++ b/Documentation/networking/README.ipw2200 @@ -147,7 +147,7 @@ Where the supported parameter are: driver. If disabled, the driver will not attempt to scan for and associate to a network until it has been configured with one or more properties for the target network, for example configuring - the network SSID. Default is 1 (auto-associate) + the network SSID. Default is 0 (do not auto-associate) Example: % modprobe ipw2200 associate=0 diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt index 688dfe1e6b7..5ede7473b42 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.txt @@ -194,6 +194,48 @@ or, for backwards compatibility, the option value. E.g., The parameters are as follows: +ad_select + + Specifies the 802.3ad aggregation selection logic to use. The + possible values and their effects are: + + stable or 0 + + The active aggregator is chosen by largest aggregate + bandwidth. + + Reselection of the active aggregator occurs only when all + slaves of the active aggregator are down or the active + aggregator has no slaves. + + This is the default value. + + bandwidth or 1 + + The active aggregator is chosen by largest aggregate + bandwidth. Reselection occurs if: + + - A slave is added to or removed from the bond + + - Any slave's link state changes + + - Any slave's 802.3ad association state changes + + - The bond's adminstrative state changes to up + + count or 2 + + The active aggregator is chosen by the largest number of + ports (slaves). Reselection occurs as described under the + "bandwidth" setting, above. + + The bandwidth and count selection policies permit failover of + 802.3ad aggregations when partial failure of the active aggregator + occurs. This keeps the aggregator with the highest availability + (either in bandwidth or in number of ports) active at all times. + + This option was added in bonding version 3.4.0. + arp_interval Specifies the ARP link monitoring frequency in milliseconds. @@ -551,6 +593,16 @@ num_grat_arp affects only the active-backup mode. This option was added for bonding version 3.3.0. +num_unsol_na + + Specifies the number of unsolicited IPv6 Neighbor Advertisements + to be issued after a failover event. One unsolicited NA is issued + immediately after the failover. + + The valid range is 0 - 255; the default value is 1. This option + affects only the active-backup mode. This option was added for + bonding version 3.4.0. + primary A string (eth0, eth2, etc) specifying which slave is the @@ -922,17 +974,19 @@ USERCTL=no NETMASK, NETWORK and BROADCAST) to match your network configuration. For later versions of initscripts, such as that found with Fedora -7 and Red Hat Enterprise Linux version 5 (or later), it is possible, and, -indeed, preferable, to specify the bonding options in the ifcfg-bond0 +7 (or later) and Red Hat Enterprise Linux version 5 (or later), it is possible, +and, indeed, preferable, to specify the bonding options in the ifcfg-bond0 file, e.g. a line of the format: -BONDING_OPTS="mode=active-backup arp_interval=60 arp_ip_target=+192.168.1.254" +BONDING_OPTS="mode=active-backup arp_interval=60 arp_ip_target=192.168.1.254" will configure the bond with the specified options. The options specified in BONDING_OPTS are identical to the bonding module parameters -except for the arp_ip_target field. Each target should be included as a -separate option and should be preceded by a '+' to indicate it should be -added to the list of queried targets, e.g., +except for the arp_ip_target field when using versions of initscripts older +than and 8.57 (Fedora 8) and 8.45.19 (Red Hat Enterprise Linux 5.2). When +using older versions each target should be included as a separate option and +should be preceded by a '+' to indicate it should be added to the list of +queried targets, e.g., arp_ip_target=+192.168.1.1 arp_ip_target=+192.168.1.2 @@ -940,7 +994,7 @@ added to the list of queried targets, e.g., options via BONDING_OPTS, it is not necessary to edit /etc/modules.conf or /etc/modprobe.conf. - For older versions of initscripts that do not support + For even older versions of initscripts that do not support BONDING_OPTS, it is necessary to edit /etc/modules.conf (or /etc/modprobe.conf, depending upon your distro) to load the bonding module with your desired options when the bond0 interface is brought up. The diff --git a/Documentation/networking/cs89x0.txt b/Documentation/networking/cs89x0.txt index 6387d3decf8..c725d33b316 100644 --- a/Documentation/networking/cs89x0.txt +++ b/Documentation/networking/cs89x0.txt @@ -3,7 +3,7 @@ NOTE ---- This document was contributed by Cirrus Logic for kernel 2.2.5. This version -has been updated for 2.3.48 by Andrew Morton <andrewm@uow.edu.au> +has been updated for 2.3.48 by Andrew Morton. Cirrus make a copy of this driver available at their website, as described below. In general, you should use the driver version which @@ -690,7 +690,7 @@ latest drivers and technical publications. 6.4 Current maintainer In February 2000 the maintenance of this driver was assumed by Andrew -Morton <akpm@zip.com.au> +Morton. 6.5 Kernel module parameters diff --git a/Documentation/networking/dccp.txt b/Documentation/networking/dccp.txt index 39131a3c78f..7a3bb1abb83 100644 --- a/Documentation/networking/dccp.txt +++ b/Documentation/networking/dccp.txt @@ -57,6 +57,24 @@ can be set before calling bind(). DCCP_SOCKOPT_GET_CUR_MPS is read-only and retrieves the current maximum packet size (application payload size) in bytes, see RFC 4340, section 14. +DCCP_SOCKOPT_AVAILABLE_CCIDS is also read-only and returns the list of CCIDs +supported by the endpoint (see include/linux/dccp.h for symbolic constants). +The caller needs to provide a sufficiently large (> 2) array of type uint8_t. + +DCCP_SOCKOPT_CCID is write-only and sets both the TX and RX CCIDs at the same +time, combining the operation of the next two socket options. This option is +preferrable over the latter two, since often applications will use the same +type of CCID for both directions; and mixed use of CCIDs is not currently well +understood. This socket option takes as argument at least one uint8_t value, or +an array of uint8_t values, which must match available CCIDS (see above). CCIDs +must be registered on the socket before calling connect() or listen(). + +DCCP_SOCKOPT_TX_CCID is read/write. It returns the current CCID (if set) or sets +the preference list for the TX CCID, using the same format as DCCP_SOCKOPT_CCID. +Please note that the getsockopt argument type here is `int', not uint8_t. + +DCCP_SOCKOPT_RX_CCID is analogous to DCCP_SOCKOPT_TX_CCID, but for the RX CCID. + DCCP_SOCKOPT_SERVER_TIMEWAIT enables the server (listening socket) to hold timewait state when closing the connection (RFC 4340, 8.3). The usual case is that the closing server sends a CloseReq, whereupon the client holds timewait @@ -115,20 +133,12 @@ retries2 importance for retransmitted acknowledgments and feature negotiation, data packets are never retransmitted. Analogue of tcp_retries2. -send_ndp = 1 - Whether or not to send NDP count options (sec. 7.7.2). - -send_ackvec = 1 - Whether or not to send Ack Vector options (sec. 11.5). - -ack_ratio = 2 - The default Ack Ratio (sec. 11.3) to use. - tx_ccid = 2 - Default CCID for the sender-receiver half-connection. + Default CCID for the sender-receiver half-connection. Depending on the + choice of CCID, the Send Ack Vector feature is enabled automatically. rx_ccid = 2 - Default CCID for the receiver-sender half-connection. + Default CCID for the receiver-sender half-connection; see tx_ccid. seq_window = 100 The initial sequence window (sec. 7.5.2). diff --git a/Documentation/networking/dmfe.txt b/Documentation/networking/dmfe.txt index b1b7499dd9d..8006c227fda 100644 --- a/Documentation/networking/dmfe.txt +++ b/Documentation/networking/dmfe.txt @@ -60,6 +60,6 @@ Tobias Ringstrom <tori@unhappy.mine.nu> : Current Maintainer Contributors: Marcelo Tosatti <marcelo@conectiva.com.br> -Alan Cox <alan@redhat.com> +Alan Cox <alan@lxorguk.ukuu.org.uk> Jeff Garzik <jgarzik@pobox.com> Vojtech Pavlik <vojtech@suse.cz> diff --git a/Documentation/networking/driver.txt b/Documentation/networking/driver.txt index ea72d2e66ca..03283daa64f 100644 --- a/Documentation/networking/driver.txt +++ b/Documentation/networking/driver.txt @@ -13,7 +13,7 @@ Transmit path guidelines: static int drv_hard_start_xmit(struct sk_buff *skb, struct net_device *dev) { - struct drv *dp = dev->priv; + struct drv *dp = netdev_priv(dev); lock_tx(dp); ... diff --git a/Documentation/networking/generic-hdlc.txt b/Documentation/networking/generic-hdlc.txt index 31bc8b759b7..4eb3cc40b70 100644 --- a/Documentation/networking/generic-hdlc.txt +++ b/Documentation/networking/generic-hdlc.txt @@ -3,15 +3,15 @@ Krzysztof Halasa <khc@pm.waw.pl> Generic HDLC layer currently supports: -1. Frame Relay (ANSI, CCITT, Cisco and no LMI). +1. Frame Relay (ANSI, CCITT, Cisco and no LMI) - Normal (routed) and Ethernet-bridged (Ethernet device emulation) interfaces can share a single PVC. - ARP support (no InARP support in the kernel - there is an experimental InARP user-space daemon available on: http://www.kernel.org/pub/linux/utils/net/hdlc/). -2. raw HDLC - either IP (IPv4) interface or Ethernet device emulation. -3. Cisco HDLC. -4. PPP (uses syncppp.c). +2. raw HDLC - either IP (IPv4) interface or Ethernet device emulation +3. Cisco HDLC +4. PPP 5. X.25 (uses X.25 routines). Generic HDLC is a protocol driver only - it needs a low-level driver diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index d84932650fd..c7712787933 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -27,6 +27,12 @@ min_adv_mss - INTEGER The advertised MSS depends on the first hop route MTU, but will never be lower than this setting. +rt_cache_rebuild_count - INTEGER + The per net-namespace route cache emergency rebuild threshold. + Any net-namespace having its route cache rebuilt due to + a hash bucket chain being too long more than this many times + will have its route caching disabled + IP Fragmentation: ipfrag_high_thresh - INTEGER diff --git a/Documentation/networking/mac80211_hwsim/README b/Documentation/networking/mac80211_hwsim/README index 2ff8ccb8dc3..24ac91d5669 100644 --- a/Documentation/networking/mac80211_hwsim/README +++ b/Documentation/networking/mac80211_hwsim/README @@ -50,10 +50,6 @@ associates with the AP. hostapd and wpa_supplicant are used to take care of WPA2-PSK authentication. In addition, hostapd is also processing access point side of association. -Please note that the current Linux kernel does not enable AP mode, so a -simple patch is needed to enable AP mode selection: -http://johannes.sipsolutions.net/patches/kernel/all/LATEST/006-allow-ap-vlan-modes.patch - # Build mac80211_hwsim as part of kernel configuration @@ -65,3 +61,8 @@ hostapd hostapd.conf # Run wpa_supplicant (station) for wlan1 wpa_supplicant -Dwext -iwlan1 -c wpa_supplicant.conf + + +More test cases are available in hostap.git: +git://w1.fi/srv/git/hostap.git and mac80211_hwsim/tests subdirectory +(http://w1.fi/gitweb/gitweb.cgi?p=hostap.git;a=tree;f=mac80211_hwsim/tests) diff --git a/Documentation/networking/netdevices.txt b/Documentation/networking/netdevices.txt index d0f71fc7f78..a2ab6a0b116 100644 --- a/Documentation/networking/netdevices.txt +++ b/Documentation/networking/netdevices.txt @@ -18,7 +18,7 @@ There are routines in net_init.c to handle the common cases of alloc_etherdev, alloc_netdev. These reserve extra space for driver private data which gets freed when the network device is freed. If separately allocated data is attached to the network device -(dev->priv) then it is up to the module exit handler to free that. +(netdev_priv(dev)) then it is up to the module exit handler to free that. MTU === diff --git a/Documentation/networking/phonet.txt b/Documentation/networking/phonet.txt index 0e6e592f4f5..6a07e45d4a9 100644 --- a/Documentation/networking/phonet.txt +++ b/Documentation/networking/phonet.txt @@ -146,8 +146,8 @@ WARNING: When polling a connected pipe socket for writability, there is an intrinsic race condition whereby writability might be lost between the polling and the writing system calls. In this case, the socket will -block until write because possible again, unless non-blocking mode -becomes enabled. +block until write becomes possible again, unless non-blocking mode +is enabled. The pipe protocol provides two socket options at the SOL_PNPIPE level: diff --git a/Documentation/networking/phy.txt b/Documentation/networking/phy.txt index 8df6a7b0e66..88bb71b46da 100644 --- a/Documentation/networking/phy.txt +++ b/Documentation/networking/phy.txt @@ -96,7 +96,7 @@ Letting the PHY Abstraction Layer do Everything static void adjust_link(struct net_device *dev); Next, you need to know the device name of the PHY connected to this device. - The name will look something like, "phy0:0", where the first number is the + The name will look something like, "0:00", where the first number is the bus id, and the second is the PHY's address on that bus. Typically, the bus is responsible for making its ID unique. diff --git a/Documentation/networking/regulatory.txt b/Documentation/networking/regulatory.txt index a96989a8ff3..dcf31648414 100644 --- a/Documentation/networking/regulatory.txt +++ b/Documentation/networking/regulatory.txt @@ -131,11 +131,13 @@ are expected to do this during initialization. r = zd_reg2alpha2(mac->regdomain, alpha2); if (!r) - regulatory_hint(hw->wiphy, alpha2, NULL); + regulatory_hint(hw->wiphy, alpha2); Example code - drivers providing a built in regulatory domain: -------------------------------------------------------------- +[NOTE: This API is not currently available, it can be added when required] + If you have regulatory information you can obtain from your driver and you *need* to use this we let you build a regulatory domain structure and pass it to the wireless core. To do this you should @@ -167,7 +169,6 @@ struct ieee80211_regdomain mydriver_jp_regdom = { Then in some part of your code after your wiphy has been registered: - int r; struct ieee80211_regdomain *rd; int size_of_regd; int num_rules = mydriver_jp_regdom.n_reg_rules; @@ -178,17 +179,12 @@ Then in some part of your code after your wiphy has been registered: rd = kzalloc(size_of_regd, GFP_KERNEL); if (!rd) - return -ENOMEM; + return -ENOMEM; memcpy(rd, &mydriver_jp_regdom, sizeof(struct ieee80211_regdomain)); - for (i=0; i < num_rules; i++) { - memcpy(&rd->reg_rules[i], &mydriver_jp_regdom.reg_rules[i], - sizeof(struct ieee80211_reg_rule)); - } - r = regulatory_hint(hw->wiphy, NULL, rd); - if (r) { - kfree(rd); - return r; - } - + for (i=0; i < num_rules; i++) + memcpy(&rd->reg_rules[i], + &mydriver_jp_regdom.reg_rules[i], + sizeof(struct ieee80211_reg_rule)); + regulatory_struct_hint(rd); diff --git a/Documentation/networking/vortex.txt b/Documentation/networking/vortex.txt index 6356d3faed3..bd70976b816 100644 --- a/Documentation/networking/vortex.txt +++ b/Documentation/networking/vortex.txt @@ -1,5 +1,5 @@ Documentation/networking/vortex.txt -Andrew Morton <andrewm@uow.edu.au> +Andrew Morton 30 April 2000 @@ -11,7 +11,7 @@ The driver was written by Donald Becker <becker@scyld.com> Don is no longer the prime maintainer of this version of the driver. Please report problems to one or more of: - Andrew Morton <akpm@osdl.org> + Andrew Morton Netdev mailing list <netdev@vger.kernel.org> Linux kernel mailing list <linux-kernel@vger.kernel.org> @@ -305,11 +305,6 @@ Donald's wake-on-LAN page: ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe -Driver updates and a detailed changelog for the modifications which -were made for the 2.3/2,4 series kernel is available at - - http://www.zip.com.au/~akpm/linux/#3c59x-bc - Autonegotiation notes --------------------- diff --git a/Documentation/nmi_watchdog.txt b/Documentation/nmi_watchdog.txt index 90aa4531cb6..bf9f80a9828 100644 --- a/Documentation/nmi_watchdog.txt +++ b/Documentation/nmi_watchdog.txt @@ -69,6 +69,11 @@ to the overall system performance. On x86 nmi_watchdog is disabled by default so you have to enable it with a boot time parameter. +It's possible to disable the NMI watchdog in run-time by writing "0" to +/proc/sys/kernel/nmi_watchdog. Writing "1" to the same file will re-enable +the NMI watchdog. Notice that you still need to use "nmi_watchdog=" parameter +at boot time. + NOTE: In kernels prior to 2.4.2-ac18 the NMI-oopser is enabled unconditionally on x86 SMP boxes. diff --git a/Documentation/pcmcia/.gitignore b/Documentation/pcmcia/.gitignore new file mode 100644 index 00000000000..53d08133675 --- /dev/null +++ b/Documentation/pcmcia/.gitignore @@ -0,0 +1 @@ +crc32hash diff --git a/Documentation/power/s2ram.txt b/Documentation/power/s2ram.txt index b05f512130e..2ebdc6091ce 100644 --- a/Documentation/power/s2ram.txt +++ b/Documentation/power/s2ram.txt @@ -54,3 +54,21 @@ used to run with "radeonfb" (it's an ATI Radeon mobility). It turns out that "radeonfb" simply cannot resume that device - it tries to set the PLL's, and it just _hangs_. Using the regular VGA console and letting X resume it instead works fine. + +NOTE +==== +pm_trace uses the system's Real Time Clock (RTC) to save the magic number. +Reason for this is that the RTC is the only reliably available piece of +hardware during resume operations where a value can be set that will +survive a reboot. + +Consequence is that after a resume (even if it is successful) your system +clock will have a value corresponding to the magic mumber instead of the +correct date/time! It is therefore advisable to use a program like ntp-date +or rdate to reset the correct date/time from an external time source when +using this trace option. + +As the clock keeps ticking it is also essential that the reboot is done +quickly after the resume failure. The trace option does not use the seconds +or the low order bits of the minutes of the RTC, but a too long delay will +corrupt the magic value. diff --git a/Documentation/powerpc/00-INDEX b/Documentation/powerpc/00-INDEX index 29d839ce732..e3960b8c868 100644 --- a/Documentation/powerpc/00-INDEX +++ b/Documentation/powerpc/00-INDEX @@ -18,10 +18,6 @@ mpc52xx.txt - Linux 2.6.x on MPC52xx family mpc52xx-device-tree-bindings.txt - MPC5200 Device Tree Bindings -ppc_htab.txt - - info about the Linux/PPC /proc/ppc_htab entry -smp.txt - - use and state info about Linux/PPC on MP machines sound.txt - info on sound support under Linux/PPC zImage_layout.txt diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt index de4063cb4fd..0ab0230cbcb 100644 --- a/Documentation/powerpc/booting-without-of.txt +++ b/Documentation/powerpc/booting-without-of.txt @@ -41,25 +41,14 @@ Table of Contents VI - System-on-a-chip devices and nodes 1) Defining child nodes of an SOC 2) Representing devices without a current OF specification - a) MDIO IO device - b) Gianfar-compatible ethernet nodes - c) PHY nodes - d) Interrupt controllers - e) I2C - f) Freescale SOC USB controllers - g) Freescale SOC SEC Security Engines - h) Board Control and Status (BCSR) - i) Freescale QUICC Engine module (QE) - j) CFI or JEDEC memory-mapped NOR flash - k) Global Utilities Block - l) Freescale Communications Processor Module - m) Chipselect/Local Bus - n) 4xx/Axon EMAC ethernet nodes - o) Xilinx IP cores - p) Freescale Synchronous Serial Interface - q) USB EHCI controllers - r) MDIO on GPIOs - s) SPI busses + a) PHY nodes + b) Interrupt controllers + c) CFI or JEDEC memory-mapped NOR flash + d) 4xx/Axon EMAC ethernet nodes + e) Xilinx IP cores + f) USB EHCI controllers + g) MDIO on GPIOs + h) SPI busses VII - Marvell Discovery mv64[345]6x System Controller chips 1) The /system-controller node @@ -1830,41 +1819,7 @@ platforms are moved over to use the flattened-device-tree model. big-endian; }; - r) Freescale Display Interface Unit - - The Freescale DIU is a LCD controller, with proper hardware, it can also - drive DVI monitors. - - Required properties: - - compatible : should be "fsl-diu". - - reg : should contain at least address and length of the DIU register - set. - - Interrupts : one DIU interrupt should be describe here. - - Example (MPC8610HPCD) - display@2c000 { - compatible = "fsl,diu"; - reg = <0x2c000 100>; - interrupts = <72 2>; - interrupt-parent = <&mpic>; - }; - - s) Freescale on board FPGA - - This is the memory-mapped registers for on board FPGA. - - Required properities: - - compatible : should be "fsl,fpga-pixis". - - reg : should contain the address and the lenght of the FPPGA register - set. - - Example (MPC8610HPCD) - board-control@e8000000 { - compatible = "fsl,fpga-pixis"; - reg = <0xe8000000 32>; - }; - - r) MDIO on GPIOs + g) MDIO on GPIOs Currently defined compatibles: - virtual,gpio-mdio @@ -1884,7 +1839,7 @@ platforms are moved over to use the flattened-device-tree model. &qe_pio_c 6>; }; - s) SPI (Serial Peripheral Interface) busses + h) SPI (Serial Peripheral Interface) busses SPI busses can be described with a node for the SPI master device and a set of child nodes for each SPI slave on the bus. For this @@ -1917,6 +1872,8 @@ platforms are moved over to use the flattened-device-tree model. inverse clock polarity (CPOL) mode - spi-cpha - (optional) Empty property indicating device requires shifted clock phase (CPHA) mode + - spi-cs-high - (optional) Empty property indicating device requires + chip select active high SPI example for an MPC5200 SPI bus: spi@f00 { diff --git a/Documentation/powerpc/dts-bindings/fsl/83xx-512x-pci.txt b/Documentation/powerpc/dts-bindings/fsl/83xx-512x-pci.txt new file mode 100644 index 00000000000..35a46536240 --- /dev/null +++ b/Documentation/powerpc/dts-bindings/fsl/83xx-512x-pci.txt @@ -0,0 +1,40 @@ +* Freescale 83xx and 512x PCI bridges + +Freescale 83xx and 512x SOCs include the same pci bridge core. + +83xx/512x specific notes: +- reg: should contain two address length tuples + The first is for the internal pci bridge registers + The second is for the pci config space access registers + +Example (MPC8313ERDB) + pci0: pci@e0008500 { + cell-index = <1>; + interrupt-map-mask = <0xf800 0x0 0x0 0x7>; + interrupt-map = < + /* IDSEL 0x0E -mini PCI */ + 0x7000 0x0 0x0 0x1 &ipic 18 0x8 + 0x7000 0x0 0x0 0x2 &ipic 18 0x8 + 0x7000 0x0 0x0 0x3 &ipic 18 0x8 + 0x7000 0x0 0x0 0x4 &ipic 18 0x8 + + /* IDSEL 0x0F - PCI slot */ + 0x7800 0x0 0x0 0x1 &ipic 17 0x8 + 0x7800 0x0 0x0 0x2 &ipic 18 0x8 + 0x7800 0x0 0x0 0x3 &ipic 17 0x8 + 0x7800 0x0 0x0 0x4 &ipic 18 0x8>; + interrupt-parent = <&ipic>; + interrupts = <66 0x8>; + bus-range = <0x0 0x0>; + ranges = <0x02000000 0x0 0x90000000 0x90000000 0x0 0x10000000 + 0x42000000 0x0 0x80000000 0x80000000 0x0 0x10000000 + 0x01000000 0x0 0x00000000 0xe2000000 0x0 0x00100000>; + clock-frequency = <66666666>; + #interrupt-cells = <1>; + #size-cells = <2>; + #address-cells = <3>; + reg = <0xe0008500 0x100 /* internal registers */ + 0xe0008300 0x8>; /* config space access registers */ + compatible = "fsl,mpc8349-pci"; + device_type = "pci"; + }; diff --git a/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt b/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt new file mode 100644 index 00000000000..d015dcec401 --- /dev/null +++ b/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt @@ -0,0 +1,40 @@ +GPIO controllers on MPC8xxx SoCs + +This is for the non-QE/CPM/GUTs GPIO controllers as found on +8349, 8572, 8610 and compatible. + +Every GPIO controller node must have #gpio-cells property defined, +this information will be used to translate gpio-specifiers. + +Required properties: +- compatible : "fsl,<CHIP>-gpio" followed by "fsl,mpc8349-gpio" for + 83xx, "fsl,mpc8572-gpio" for 85xx and "fsl,mpc8610-gpio" for 86xx. +- #gpio-cells : Should be two. The first cell is the pin number and the + second cell is used to specify optional parameters (currently unused). + - interrupts : Interrupt mapping for GPIO IRQ (currently unused). + - interrupt-parent : Phandle for the interrupt controller that + services interrupts for this device. +- gpio-controller : Marks the port as GPIO controller. + +Example of gpio-controller nodes for a MPC8347 SoC: + + gpio1: gpio-controller@c00 { + #gpio-cells = <2>; + compatible = "fsl,mpc8347-gpio", "fsl,mpc8349-gpio"; + reg = <0xc00 0x100>; + interrupts = <74 0x8>; + interrupt-parent = <&ipic>; + gpio-controller; + }; + + gpio2: gpio-controller@d00 { + #gpio-cells = <2>; + compatible = "fsl,mpc8347-gpio", "fsl,mpc8349-gpio"; + reg = <0xd00 0x100>; + interrupts = <75 0x8>; + interrupt-parent = <&ipic>; + gpio-controller; + }; + +See booting-without-of.txt for details of how to specify GPIO +information for devices. diff --git a/Documentation/powerpc/dts-bindings/fsl/board.txt b/Documentation/powerpc/dts-bindings/fsl/board.txt index 74ae6f1cd2d..81a917ef96e 100644 --- a/Documentation/powerpc/dts-bindings/fsl/board.txt +++ b/Documentation/powerpc/dts-bindings/fsl/board.txt @@ -2,13 +2,13 @@ Required properties: - - device_type : Should be "board-control" + - compatible : Should be "fsl,<board>-bcsr" - reg : Offset and length of the register set for the device Example: bcsr@f8000000 { - device_type = "board-control"; + compatible = "fsl,mpc8360mds-bcsr"; reg = <f8000000 8000>; }; diff --git a/Documentation/powerpc/dts-bindings/fsl/dma.txt b/Documentation/powerpc/dts-bindings/fsl/dma.txt index 86826df00e6..cc453110fc4 100644 --- a/Documentation/powerpc/dts-bindings/fsl/dma.txt +++ b/Documentation/powerpc/dts-bindings/fsl/dma.txt @@ -20,7 +20,7 @@ Required properties: - compatible : compatible list, contains 2 entries, first is "fsl,CHIP-dma-channel", where CHIP is the processor (mpc8349, mpc8350, etc.) and the second is - "fsl,elo-dma-channel" + "fsl,elo-dma-channel". However, see note below. - reg : <registers mapping for channel> - cell-index : dma channel index starts at 0. @@ -82,7 +82,7 @@ Required properties: - compatible : compatible list, contains 2 entries, first is "fsl,CHIP-dma-channel", where CHIP is the processor (mpc8540, mpc8560, etc.) and the second is - "fsl,eloplus-dma-channel" + "fsl,eloplus-dma-channel". However, see note below. - cell-index : dma channel index starts at 0. - reg : <registers mapping for channel> - interrupts : <interrupt mapping for DMA channel IRQ> @@ -125,3 +125,12 @@ Example: interrupts = <17 2>; }; }; + +Note on DMA channel compatible properties: The compatible property must say +"fsl,elo-dma-channel" or "fsl,eloplus-dma-channel" to be used by the Elo DMA +driver (fsldma). Any DMA channel used by fsldma cannot be used by another +DMA driver, such as the SSI sound drivers for the MPC8610. Therefore, any DMA +channel that should be used for another driver should not use +"fsl,elo-dma-channel" or "fsl,eloplus-dma-channel". For the SSI drivers, for +example, the compatible property should be "fsl,ssi-dma-channel". See ssi.txt +for more information. diff --git a/Documentation/powerpc/dts-bindings/fsl/ssi.txt b/Documentation/powerpc/dts-bindings/fsl/ssi.txt index d100555d488..a2d963998a6 100644 --- a/Documentation/powerpc/dts-bindings/fsl/ssi.txt +++ b/Documentation/powerpc/dts-bindings/fsl/ssi.txt @@ -24,6 +24,12 @@ Required properties: "rj-master" - r.j., SSI is clock master "ac97-slave" - AC97 mode, SSI is clock slave "ac97-master" - AC97 mode, SSI is clock master +- fsl,playback-dma: phandle to a node for the DMA channel to use for + playback of audio. This is typically dictated by SOC + design. See the notes below. +- fsl,capture-dma: phandle to a node for the DMA channel to use for + capture (recording) of audio. This is typically dictated + by SOC design. See the notes below. Optional properties: - codec-handle : phandle to a 'codec' node that defines an audio @@ -36,3 +42,20 @@ Child 'codec' node required properties: Child 'codec' node optional properties: - clock-frequency : The frequency of the input clock, which typically comes from an on-board dedicated oscillator. + +Notes on fsl,playback-dma and fsl,capture-dma: + +On SOCs that have an SSI, specific DMA channels are hard-wired for playback +and capture. On the MPC8610, for example, SSI1 must use DMA channel 0 for +playback and DMA channel 1 for capture. SSI2 must use DMA channel 2 for +playback and DMA channel 3 for capture. The developer can choose which +DMA controller to use, but the channels themselves are hard-wired. The +purpose of these two properties is to represent this hardware design. + +The device tree nodes for the DMA channels that are referenced by +"fsl,playback-dma" and "fsl,capture-dma" must be marked as compatible with +"fsl,ssi-dma-channel". The SOC-specific compatible string (e.g. +"fsl,mpc8610-dma-channel") can remain. If these nodes are left as +"fsl,elo-dma-channel" or "fsl,eloplus-dma-channel", then the generic Elo DMA +drivers (fsldma) will attempt to use them, and it will conflict with the +sound drivers. diff --git a/Documentation/powerpc/dts-bindings/fsl/tsec.txt b/Documentation/powerpc/dts-bindings/fsl/tsec.txt index cf55fa4112d..7fa4b27574b 100644 --- a/Documentation/powerpc/dts-bindings/fsl/tsec.txt +++ b/Documentation/powerpc/dts-bindings/fsl/tsec.txt @@ -2,8 +2,8 @@ The MDIO is a bus to which the PHY devices are connected. For each device that exists on this bus, a child node should be created. See -the definition of the PHY node below for an example of how to define -a PHY. +the definition of the PHY node in booting-without-of.txt for an example +of how to define a PHY. Required properties: - reg : Offset and length of the register set for the device @@ -21,6 +21,14 @@ Example: }; }; +* TBI Internal MDIO bus + +As of this writing, every tsec is associated with an internal TBI PHY. +This PHY is accessed through the local MDIO bus. These buses are defined +similarly to the mdio buses, except they are compatible with "fsl,gianfar-tbi". +The TBI PHYs underneath them are similar to normal PHYs, but the reg property +is considered instructive, rather than descriptive. The reg property should +be chosen so it doesn't interfere with other PHYs on the bus. * Gianfar-compatible ethernet nodes diff --git a/Documentation/powerpc/ppc_htab.txt b/Documentation/powerpc/ppc_htab.txt deleted file mode 100644 index 8b8c7df29fa..00000000000 --- a/Documentation/powerpc/ppc_htab.txt +++ /dev/null @@ -1,118 +0,0 @@ - Information about /proc/ppc_htab -===================================================================== - -This document and the related code was written by me (Cort Dougan), please -email me (cort@fsmlabs.com) if you have questions, comments or corrections. - -Last Change: 2.16.98 - -This entry in the proc directory is readable by all users but only -writable by root. - -The ppc_htab interface is a user level way of accessing the -performance monitoring registers as well as providing information -about the PTE hash table. - -1. Reading - - Reading this file will give you information about the memory management - hash table that serves as an extended tlb for page translation on the - powerpc. It will also give you information about performance measurement - specific to the cpu that you are using. - - Explanation of the 604 Performance Monitoring Fields: - MMCR0 - the current value of the MMCR0 register - PMC1 - PMC2 - the value of the performance counters and a - description of what events they are counting - which are based on MMCR0 bit settings. - Explanation of the PTE Hash Table fields: - - Size - hash table size in Kb. - Buckets - number of buckets in the table. - Address - the virtual kernel address of the hash table base. - Entries - the number of ptes that can be stored in the hash table. - User/Kernel - how many pte's are in use by the kernel or user at that time. - Overflows - How many of the entries are in their secondary hash location. - Percent full - ratio of free pte entries to in use entries. - Reloads - Count of how many hash table misses have occurred - that were fixed with a reload from the linux tables. - Should always be 0 on 603 based machines. - Non-error Misses - Count of how many hash table misses have occurred - that were completed with the creation of a pte in the linux - tables with a call to do_page_fault(). - Error Misses - Number of misses due to errors such as bad address - and permission violations. This includes kernel access of - bad user addresses that are fixed up by the trap handler. - - Note that calculation of the data displayed from /proc/ppc_htab takes - a long time and spends a great deal of time in the kernel. It would - be quite hard on performance to read this file constantly. In time - there may be a counter in the kernel that allows successive reads from - this file only after a given amount of time has passed to reduce the - possibility of a user slowing the system by reading this file. - -2. Writing - - Writing to the ppc_htab allows you to change the characteristics of - the powerpc PTE hash table and setup performance monitoring. - - Resizing the PTE hash table is not enabled right now due to many - complications with moving the hash table, rehashing the entries - and many many SMP issues that would have to be dealt with. - - Write options to ppc_htab: - - - To set the size of the hash table to 64Kb: - - echo 'size 64' > /proc/ppc_htab - - The size must be a multiple of 64 and must be greater than or equal to - 64. - - - To turn off performance monitoring: - - echo 'off' > /proc/ppc_htab - - - To reset the counters without changing what they're counting: - - echo 'reset' > /proc/ppc_htab - - Note that counting will continue after the reset if it is enabled. - - - To count only events in user mode or only in kernel mode: - - echo 'user' > /proc/ppc_htab - ...or... - echo 'kernel' > /proc/ppc_htab - - Note that these two options are exclusive of one another and the - lack of either of these options counts user and kernel. - Using 'reset' and 'off' reset these flags. - - - The 604 has 2 performance counters which can each count events from - a specific set of events. These sets are disjoint so it is not - possible to count _any_ combination of 2 events. One event can - be counted by PMC1 and one by PMC2. - - To start counting a particular event use: - - echo 'event' > /proc/ppc_htab - - and choose from these events: - - PMC1 - ---- - 'ic miss' - instruction cache misses - 'dtlb' - data tlb misses (not hash table misses) - - PMC2 - ---- - 'dc miss' - data cache misses - 'itlb' - instruction tlb misses (not hash table misses) - 'load miss time' - cycles to complete a load miss - -3. Bugs - - The PMC1 and PMC2 counters can overflow and give no indication of that - in /proc/ppc_htab. diff --git a/Documentation/powerpc/smp.txt b/Documentation/powerpc/smp.txt deleted file mode 100644 index 5b581b849ff..00000000000 --- a/Documentation/powerpc/smp.txt +++ /dev/null @@ -1,34 +0,0 @@ - Information about Linux/PPC SMP mode -===================================================================== - -This document and the related code was written by me -(Cort Dougan, cort@fsmlabs.com) please email me if you have questions, -comments or corrections. - -Last Change: 3.31.99 - -If you want to help by writing code or testing different hardware please -email me! - -1. State of Supported Hardware - - PowerSurge Architecture - tested on UMAX s900, Apple 9600 - The second processor on this machine boots up just fine and - enters its idle loop. Hopefully a completely working SMP kernel - on this machine will be done shortly. - - The code makes the assumption of only two processors. The changes - necessary to work with any number would not be overly difficult but - I don't have any machines with >2 processors so it's not high on my - list of priorities. If anyone else would like do to the work email - me and I can point out the places that need changed. If you have >2 - processors and don't want to add support yourself let me know and I - can take a look into it. - - BeBox - BeBox support hasn't been added to the 2.1.X kernels from 2.0.X - but work is being done and SMP support for BeBox is in the works. - - CHRP - CHRP SMP works and is fairly solid. It's been tested on the IBM F50 - with 4 processors for quite some time now. diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt new file mode 100644 index 00000000000..1b5a5ddbc3e --- /dev/null +++ b/Documentation/printk-formats.txt @@ -0,0 +1,35 @@ +If variable is of Type, use printk format specifier: +--------------------------------------------------------- + int %d or %x + unsigned int %u or %x + long %ld or %lx + unsigned long %lu or %lx + long long %lld or %llx + unsigned long long %llu or %llx + size_t %zu or %zx + ssize_t %zd or %zx + +Raw pointer value SHOULD be printed with %p. + +u64 SHOULD be printed with %llu/%llx, (unsigned long long): + + printk("%llu", (unsigned long long)u64_var); + +s64 SHOULD be printed with %lld/%llx, (long long): + + printk("%lld", (long long)s64_var); + +If <type> is dependent on a config option for its size (e.g., sector_t, +blkcnt_t, phys_addr_t, resource_size_t) or is architecture-dependent +for its size (e.g., tcflag_t), use a format specifier of its largest +possible type and explicitly cast to it. Example: + + printk("test: sector number/total blocks: %llu/%llu\n", + (unsigned long long)sector, (unsigned long long)blockcount); + +Reminder: sizeof() result is of type size_t. + +Thank you for your cooperation and attention. + + +By Randy Dunlap <rdunlap@xenotime.net> diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt index b65f0799df4..4d3ee317a4a 100644 --- a/Documentation/rfkill.txt +++ b/Documentation/rfkill.txt @@ -191,12 +191,20 @@ Userspace input handlers (uevents) or kernel input handlers (rfkill-input): to tell the devices registered with the rfkill class to change their state (i.e. translates the input layer event into real action). + * rfkill-input implements EPO by handling EV_SW SW_RFKILL_ALL 0 (power off all transmitters) in a special way: it ignores any overrides and local state cache and forces all transmitters to the RFKILL_STATE_SOFT_BLOCKED state (including those which are already - supposed to be BLOCKED). Note that the opposite event (power on all - transmitters) is handled normally. + supposed to be BLOCKED). + * rfkill EPO will remain active until rfkill-input receives an + EV_SW SW_RFKILL_ALL 1 event. While the EPO is active, transmitters + are locked in the blocked state (rfkill will refuse to unblock them). + * rfkill-input implements different policies that the user can + select for handling EV_SW SW_RFKILL_ALL 1. It will unlock rfkill, + and either do nothing (leave transmitters blocked, but now unlocked), + restore the transmitters to their state before the EPO, or unblock + them all. Userspace uevent handler or kernel platform-specific drivers hooked to the rfkill notifier chain: @@ -331,11 +339,9 @@ class to get a sysfs interface :-) correct event for your switch/button. These events are emergency power-off events when they are trying to turn the transmitters off. An example of an input device which SHOULD generate *_RFKILL_ALL events is the wireless-kill -switch in a laptop which is NOT a hotkey, but a real switch that kills radios -in hardware, even if the O.S. has gone to lunch. An example of an input device -which SHOULD NOT generate *_RFKILL_ALL events by default, is any sort of hot -key that does nothing by itself, as well as any hot key that is type-specific -(e.g. the one for WLAN). +switch in a laptop which is NOT a hotkey, but a real sliding/rocker switch. +An example of an input device which SHOULD NOT generate *_RFKILL_ALL events by +default, is any sort of hot key that is type-specific (e.g. the one for WLAN). 3.1 Guidelines for wireless device drivers diff --git a/Documentation/scheduler/00-INDEX b/Documentation/scheduler/00-INDEX index fc234d093fb..aabcc3a089b 100644 --- a/Documentation/scheduler/00-INDEX +++ b/Documentation/scheduler/00-INDEX @@ -4,8 +4,6 @@ sched-arch.txt - CPU Scheduler implementation hints for architecture specific code. sched-coding.txt - reference for various scheduler-related methods in the O(1) scheduler. -sched-design.txt - - goals, design and implementation of the Linux O(1) scheduler. sched-design-CFS.txt - goals, design and implementation of the Complete Fair Scheduler. sched-domains.txt diff --git a/Documentation/scheduler/sched-arch.txt b/Documentation/scheduler/sched-arch.txt index 941615a9769..d43dbcbd163 100644 --- a/Documentation/scheduler/sched-arch.txt +++ b/Documentation/scheduler/sched-arch.txt @@ -8,7 +8,7 @@ Context switch By default, the switch_to arch function is called with the runqueue locked. This is usually not a problem unless switch_to may need to take the runqueue lock. This is usually due to a wake up operation in -the context switch. See include/asm-ia64/system.h for an example. +the context switch. See arch/ia64/include/asm/system.h for an example. To request the scheduler call switch_to with the runqueue unlocked, you must `#define __ARCH_WANT_UNLOCKED_CTXSW` in a header file @@ -23,7 +23,7 @@ disabled. Interrupts may be enabled over the call if it is likely to introduce a significant interrupt latency by adding the line `#define __ARCH_WANT_INTERRUPTS_ON_CTXSW` in the same place as for unlocked context switches. This define also implies -`__ARCH_WANT_UNLOCKED_CTXSW`. See include/asm-arm/system.h for an +`__ARCH_WANT_UNLOCKED_CTXSW`. See arch/arm/include/asm/system.h for an example. diff --git a/Documentation/scheduler/sched-design-CFS.txt b/Documentation/scheduler/sched-design-CFS.txt index 9d8eb553884..8398ca4ff4e 100644 --- a/Documentation/scheduler/sched-design-CFS.txt +++ b/Documentation/scheduler/sched-design-CFS.txt @@ -92,7 +92,7 @@ other HZ detail. Thus the CFS scheduler has no notion of "timeslices" in the way the previous scheduler had, and has no heuristics whatsoever. There is only one central tunable (you have to switch on CONFIG_SCHED_DEBUG): - /proc/sys/kernel/sched_granularity_ns + /proc/sys/kernel/sched_min_granularity_ns which can be used to tune the scheduler from "desktop" (i.e., low latencies) to "server" (i.e., good batching) workloads. It defaults to a setting suitable @@ -273,3 +273,24 @@ task groups and modify their CPU share using the "cgroups" pseudo filesystem. # #Launch gmplayer (or your favourite movie player) # echo <movie_player_pid> > multimedia/tasks + +8. Implementation note: user namespaces + +User namespaces are intended to be hierarchical. But they are currently +only partially implemented. Each of those has ramifications for CFS. + +First, since user namespaces are hierarchical, the /sys/kernel/uids +presentation is inadequate. Eventually we will likely want to use sysfs +tagging to provide private views of /sys/kernel/uids within each user +namespace. + +Second, the hierarchical nature is intended to support completely +unprivileged use of user namespaces. So if using user groups, then +we want the users in a user namespace to be children of the user +who created it. + +That is currently unimplemented. So instead, every user in a new +user namespace will receive 1024 shares just like any user in the +initial user namespace. Note that at the moment creation of a new +user namespace requires each of CAP_SYS_ADMIN, CAP_SETUID, and +CAP_SETGID. diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid index 37796fe45bd..eaa4801f2ce 100644 --- a/Documentation/scsi/ChangeLog.megaraid +++ b/Documentation/scsi/ChangeLog.megaraid @@ -409,7 +409,7 @@ i. Function reordering so that inline functions are defined before they megaraid_mbox_prepare_pthru, megaraid_mbox_prepare_epthru, megaraid_busywait_mbox - - Andrew Morton <akpm@osdl.org>, 08.19.2004 + - Andrew Morton, 08.19.2004 linux-scsi mailing list "Something else to clean up after inclusion: every instance of an @@ -471,13 +471,13 @@ vi. Add support for 64-bit applications. Current drivers assume only vii. Move the function declarations for the management module from megaraid_mm.h to megaraid_mm.c - - Andrew Morton <akpm@osdl.org>, 08.19.2004 + - Andrew Morton, 08.19.2004 linux-scsi mailing list viii. Change default values for MEGARAID_NEWGEN, MEGARAID_MM, and MEGARAID_MAILBOX to 'n' in Kconfig.megaraid - - Andrew Morton <akpm@osdl.org>, 08.19.2004 + - Andrew Morton, 08.19.2004 linux-scsi mailing list ix. replace udelay with msleep diff --git a/Documentation/scsi/aacraid.txt b/Documentation/scsi/aacraid.txt index 709ca991a45..ddace3afc83 100644 --- a/Documentation/scsi/aacraid.txt +++ b/Documentation/scsi/aacraid.txt @@ -128,7 +128,7 @@ Supported Cards/Chipsets People ------------------------- -Alan Cox <alan@redhat.com> +Alan Cox <alan@lxorguk.ukuu.org.uk> Christoph Hellwig <hch@infradead.org> (updates for new-style PCI probing and SCSI host registration, small cleanups/fixes) Matt Domsch <matt_domsch@dell.com> (revision ioctl, adapter messages) diff --git a/Documentation/scsi/cxgb3i.txt b/Documentation/scsi/cxgb3i.txt new file mode 100644 index 00000000000..8141fa01978 --- /dev/null +++ b/Documentation/scsi/cxgb3i.txt @@ -0,0 +1,85 @@ +Chelsio S3 iSCSI Driver for Linux + +Introduction +============ + +The Chelsio T3 ASIC based Adapters (S310, S320, S302, S304, Mezz cards, etc. +series of products) supports iSCSI acceleration and iSCSI Direct Data Placement +(DDP) where the hardware handles the expensive byte touching operations, such +as CRC computation and verification, and direct DMA to the final host memory +destination: + + - iSCSI PDU digest generation and verification + + On transmitting, Chelsio S3 h/w computes and inserts the Header and + Data digest into the PDUs. + On receiving, Chelsio S3 h/w computes and verifies the Header and + Data digest of the PDUs. + + - Direct Data Placement (DDP) + + S3 h/w can directly place the iSCSI Data-In or Data-Out PDU's + payload into pre-posted final destination host-memory buffers based + on the Initiator Task Tag (ITT) in Data-In or Target Task Tag (TTT) + in Data-Out PDUs. + + - PDU Transmit and Recovery + + On transmitting, S3 h/w accepts the complete PDU (header + data) + from the host driver, computes and inserts the digests, decomposes + the PDU into multiple TCP segments if necessary, and transmit all + the TCP segments onto the wire. It handles TCP retransmission if + needed. + + On receving, S3 h/w recovers the iSCSI PDU by reassembling TCP + segments, separating the header and data, calculating and verifying + the digests, then forwards the header to the host. The payload data, + if possible, will be directly placed into the pre-posted host DDP + buffer. Otherwise, the payload data will be sent to the host too. + +The cxgb3i driver interfaces with open-iscsi initiator and provides the iSCSI +acceleration through Chelsio hardware wherever applicable. + +Using the cxgb3i Driver +======================= + +The following steps need to be taken to accelerates the open-iscsi initiator: + +1. Load the cxgb3i driver: "modprobe cxgb3i" + + The cxgb3i module registers a new transport class "cxgb3i" with open-iscsi. + + * in the case of recompiling the kernel, the cxgb3i selection is located at + Device Drivers + SCSI device support ---> + [*] SCSI low-level drivers ---> + <M> Chelsio S3xx iSCSI support + +2. Create an interface file located under /etc/iscsi/ifaces/ for the new + transport class "cxgb3i". + + The content of the file should be in the following format: + iface.transport_name = cxgb3i + iface.net_ifacename = <ethX> + iface.ipaddress = <iscsi ip address> + + * if iface.ipaddress is specified, <iscsi ip address> needs to be either the + same as the ethX's ip address or an address on the same subnet. Make + sure the ip address is unique in the network. + +3. edit /etc/iscsi/iscsid.conf + The default setting for MaxRecvDataSegmentLength (131072) is too big, + replace "node.conn[0].iscsi.MaxRecvDataSegmentLength" to be a value no + bigger than 15360 (for example 8192): + + node.conn[0].iscsi.MaxRecvDataSegmentLength = 8192 + + * The login would fail for a normal session if MaxRecvDataSegmentLength is + too big. A error message in the format of + "cxgb3i: ERR! MaxRecvSegmentLength <X> too big. Need to be <= <Y>." + would be logged to dmesg. + +4. To direct open-iscsi traffic to go through cxgb3i's accelerated path, + "-I <iface file name>" option needs to be specified with most of the + iscsiadm command. <iface file name> is the transport interface file created + in step 2. diff --git a/Documentation/serial/00-INDEX b/Documentation/serial/00-INDEX new file mode 100644 index 00000000000..07dcdb0d2a3 --- /dev/null +++ b/Documentation/serial/00-INDEX @@ -0,0 +1,24 @@ +00-INDEX + - this file. +README.cycladesZ + - info on Cyclades-Z firmware loading. +computone.txt + - info on Computone Intelliport II/Plus Multiport Serial Driver. +digiepca.txt + - info on Digi Intl. {PC,PCI,EISA}Xx and Xem series cards. +hayes-esp.txt + - info on using the Hayes ESP serial driver. +moxa-smartio + - file with info on installing/using Moxa multiport serial driver. +riscom8.txt + - notes on using the RISCom/8 multi-port serial driver. +rocket.txt + - info on the Comtrol RocketPort multiport serial driver. +specialix.txt + - info on hardware/driver for specialix IO8+ multiport serial card. +stallion.txt + - info on using the Stallion multiport serial driver. +sx.txt + - info on the Specialix SX/SI multiport serial driver. +tty.txt + - guide to the locking policies of the tty layer. diff --git a/Documentation/README.cycladesZ b/Documentation/serial/README.cycladesZ index 024a69443cc..024a69443cc 100644 --- a/Documentation/README.cycladesZ +++ b/Documentation/serial/README.cycladesZ diff --git a/Documentation/computone.txt b/Documentation/serial/computone.txt index 5e2a0c76bfa..c57ea4781e5 100644 --- a/Documentation/computone.txt +++ b/Documentation/serial/computone.txt @@ -247,7 +247,7 @@ shar archive to make it easier to extract the script from the documentation. To create the ip2mkdev shell script change to a convenient directory (/tmp works just fine) and run the following command: - unshar Documentation/computone.txt + unshar Documentation/serial/computone.txt (This file) You should now have a file ip2mkdev in your current working directory with diff --git a/Documentation/digiepca.txt b/Documentation/serial/digiepca.txt index f2560e22f2c..f2560e22f2c 100644 --- a/Documentation/digiepca.txt +++ b/Documentation/serial/digiepca.txt diff --git a/Documentation/hayes-esp.txt b/Documentation/serial/hayes-esp.txt index 09b5d585675..09b5d585675 100644 --- a/Documentation/hayes-esp.txt +++ b/Documentation/serial/hayes-esp.txt diff --git a/Documentation/moxa-smartio b/Documentation/serial/moxa-smartio index 5337e80a5b9..5337e80a5b9 100644 --- a/Documentation/moxa-smartio +++ b/Documentation/serial/moxa-smartio diff --git a/Documentation/riscom8.txt b/Documentation/serial/riscom8.txt index 14f61fdad7c..14f61fdad7c 100644 --- a/Documentation/riscom8.txt +++ b/Documentation/serial/riscom8.txt diff --git a/Documentation/rocket.txt b/Documentation/serial/rocket.txt index 1d858299043..1d858299043 100644 --- a/Documentation/rocket.txt +++ b/Documentation/serial/rocket.txt diff --git a/Documentation/specialix.txt b/Documentation/serial/specialix.txt index 6eb6f3a3331..6eb6f3a3331 100644 --- a/Documentation/specialix.txt +++ b/Documentation/serial/specialix.txt diff --git a/Documentation/stallion.txt b/Documentation/serial/stallion.txt index 5c4902d9a5b..5c4902d9a5b 100644 --- a/Documentation/stallion.txt +++ b/Documentation/serial/stallion.txt diff --git a/Documentation/sx.txt b/Documentation/serial/sx.txt index cb4efa0fb5c..cb4efa0fb5c 100644 --- a/Documentation/sx.txt +++ b/Documentation/serial/sx.txt diff --git a/Documentation/tty.txt b/Documentation/serial/tty.txt index 8e65c4498c5..8e65c4498c5 100644 --- a/Documentation/tty.txt +++ b/Documentation/serial/tty.txt diff --git a/Documentation/sh/kgdb.txt b/Documentation/sh/kgdb.txt deleted file mode 100644 index 05b4ba89d28..00000000000 --- a/Documentation/sh/kgdb.txt +++ /dev/null @@ -1,179 +0,0 @@ - -This file describes the configuration and behavior of KGDB for the SH -kernel. Based on a description from Henry Bell <henry.bell@st.com>, it -has been modified to account for quirks in the current implementation. - -Version -======= - -This version of KGDB was written for 2.4.xx kernels for the SH architecture. -Further documentation is available from the linux-sh project website. - - -Debugging Setup: Host -====================== - -The two machines will be connected together via a serial line - this -should be a null modem cable i.e. with a twist. - -On your DEVELOPMENT machine, go to your kernel source directory and -build the kernel, enabling KGDB support in the "kernel hacking" section. -This includes the KGDB code, and also makes the kernel be compiled with -the "-g" option set -- necessary for debugging. - -To install this new kernel, use the following installation procedure. - -Decide on which tty port you want the machines to communicate, then -cable them up back-to-back using the null modem. On the DEVELOPMENT -machine, you may wish to create an initialization file called .gdbinit -(in the kernel source directory or in your home directory) to execute -commonly-used commands at startup. - -A minimal .gdbinit might look like this: - - file vmlinux - set remotebaud 115200 - target remote /dev/ttyS0 - -Change the "target" definition so that it specifies the tty port that -you intend to use. Change the "remotebaud" definition to match the -data rate that you are going to use for the com line (115200 is the -default). - -Debugging Setup: Target -======================== - -By default, the KGDB stub will communicate with the host GDB using -ttySC1 at 115200 baud, 8 databits, no parity; these defaults can be -changed in the kernel configuration. As the kernel starts up, KGDB will -initialize so that breakpoints, kernel segfaults, and so forth will -generally enter the debugger. - -This behavior can be modified by including the "kgdb" option in the -kernel command line; this option has the general form: - - kgdb=<ttyspec>,<action> - -The <ttyspec> indicates the port to use, and can optionally specify -baud, parity and databits -- e.g. "ttySC0,9600N8" or "ttySC1,19200". - -The <action> can be "halt" or "disabled". The "halt" action enters the -debugger via a breakpoint as soon as kgdb is initialized; the "disabled" -action causes kgdb to ignore kernel segfaults and such until explicitly -entered by a breakpoint in the code or by external action (sysrq or NMI). - -(Both <ttyspec> and <action> can appear alone, w/o the separating comma.) - -For example, if you wish to debug early in kernel startup code, you -might specify the halt option: - - kgdb=halt - -Boot the TARGET machine, which will appear to hang. - -On your DEVELOPMENT machine, cd to the source directory and run the gdb -program. (This is likely to be a cross GDB which runs on your host but -is built for an SH target.) If everything is working correctly you -should see gdb print out a few lines indicating that a breakpoint has -been taken. It will actually show a line of code in the target kernel -inside the gdbstub activation code. - -NOTE: BE SURE TO TERMINATE OR SUSPEND any other host application which -may be using the same serial port (for example, a terminal emulator you -have been using to connect to the target boot code.) Otherwise, data -from the target may not all get to GDB! - -You can now use whatever gdb commands you like to set breakpoints. -Enter "continue" to start your target machine executing again. At this -point the target system will run at full speed until it encounters -your breakpoint or gets a segment violation in the kernel, or whatever. - -Serial Ports: KGDB, Console -============================ - -This version of KGDB may not gracefully handle conflict with other -drivers in the kernel using the same port. If KGDB is configured on the -same port (and with the same parameters) as the kernel console, or if -CONFIG_SH_KGDB_CONSOLE is configured, things should be fine (though in -some cases console messages may appear twice through GDB). But if the -KGDB port is not the kernel console and used by another serial driver -which assumes different serial parameters (e.g. baud rate) KGDB may not -recover. - -Also, when KGDB is entered via sysrq-g (requires CONFIG_KGDB_SYSRQ) and -the kgdb port uses the same port as the console, detaching GDB will not -restore the console to working order without the port being re-opened. - -Another serious consequence of this is that GDB currently CANNOT break -into KGDB externally (e.g. via ^C or <BREAK>); unless a breakpoint or -error is encountered, the only way to enter KGDB after the initial halt -(see above) is via NMI (CONFIG_KGDB_NMI) or sysrq-g (CONFIG_KGDB_SYSRQ). - -Code is included for the basic Hitachi Solution Engine boards to allow -the use of ttyS0 for KGDB if desired; this is less robust, but may be -useful in some cases. (This cannot be selected using the config file, -but only through the kernel command line, e.g. "kgdb=ttyS0", though the -configured defaults for baud rate etc. still apply if not overridden.) - -If gdbstub Does Not Work -======================== - -If it doesn't work, you will have to troubleshoot it. Do the easy -things first like double checking your cabling and data rates. You -might try some non-kernel based programs to see if the back-to-back -connection works properly. Just something simple like cat /etc/hosts -/dev/ttyS0 on one machine and cat /dev/ttyS0 on the other will tell you -if you can send data from one machine to the other. There is no point -in tearing out your hair in the kernel if the line doesn't work. - -If you need to debug the GDB/KGDB communication itself, the gdb commands -"set debug remote 1" and "set debug serial 1" may be useful, but be -warned: they produce a lot of output. - -Threads -======= - -Each process in a target machine is seen as a gdb thread. gdb thread related -commands (info threads, thread n) can be used. CONFIG_KGDB_THREAD must -be defined for this to work. - -In this version, kgdb reports PID_MAX (32768) as the process ID for the -idle process (pid 0), since GDB does not accept 0 as an ID. - -Detaching (exiting KGDB) -========================= - -There are two ways to resume full-speed target execution: "continue" and -"detach". With "continue", GDB inserts any specified breakpoints in the -target code and resumes execution; the target is still in "gdb mode". -If a breakpoint or other debug event (e.g. NMI) happens, the target -halts and communicates with GDB again, which is waiting for it. - -With "detach", GDB does *not* insert any breakpoints; target execution -is resumed and GDB stops communicating (does not wait for the target). -In this case, the target is no longer in "gdb mode" -- for example, -console messages no longer get sent separately to the KGDB port, or -encapsulated for GDB. If a debug event (e.g. NMI) occurs, the target -will re-enter "gdb mode" and will display this fact on the console; you -must give a new "target remote" command to gdb. - -NOTE: TO AVOID LOSSING CONSOLE MESSAGES IN CASE THE KERNEL CONSOLE AND -KGDB USING THE SAME PORT, THE TARGET WAITS FOR ANY INPUT CHARACTER ON -THE KGDB PORT AFTER A DETACH COMMAND. For example, after the detach you -could start a terminal emulator on the same host port and enter a <cr>; -however, this program must then be terminated or suspended in order to -use GBD again if KGDB is re-entered. - - -Acknowledgements -================ - -This code was mostly generated by Henry Bell <henry.bell@st.com>; -largely from KGDB by Amit S. Kale <akale@veritas.com> - extracts from -code by Glenn Engel, Jim Kingdon, David Grothe <dave@gcom.com>, Tigran -Aivazian <tigran@sco.com>, William Gatliff <bgat@open-widgets.com>, Ben -Lee, Steve Chamberlain and Benoit Miller <fulg@iname.com> are also -included. - -Jeremy Siegel -<jsiegel@mvista.com> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.txt index 5482bf5d005..f0354164cb0 100644 --- a/Documentation/sh/new-machine.txt +++ b/Documentation/sh/new-machine.txt @@ -47,9 +47,7 @@ Next, for companion chips: `-- sh `-- cchips `-- hd6446x - |-- hd64461 - | `-- cchip-specific files - `-- hd64465 + `-- hd64461 `-- cchip-specific files ... and so on. Headers for the companion chips are treated the same way as diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index e0e54a27fc1..841a9365d5f 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt @@ -757,6 +757,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. model - force the model name position_fix - Fix DMA pointer (0 = auto, 1 = use LPIB, 2 = POSBUF) probe_mask - Bitmask to probe codecs (default = -1, meaning all slots) + probe_only - Only probing and no codec initialization (default=off); + Useful to check the initial codec status for debugging bdl_pos_adj - Specifies the DMA IRQ timing delay in samples. Passing -1 will make the driver to choose the appropriate value based on the controller chip. @@ -772,322 +774,23 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. This module supports multiple cards and autoprobe. + See Documentation/sound/alsa/HD-Audio.txt for more details about + HD-audio driver. + Each codec may have a model table for different configurations. If your machine isn't listed there, the default (usually minimal) configuration is set up. You can pass "model=<name>" option to specify a certain model in such a case. There are different - models depending on the codec chip. - - Model name Description - ---------- ----------- - ALC880 - 3stack 3-jack in back and a headphone out - 3stack-digout 3-jack in back, a HP out and a SPDIF out - 5stack 5-jack in back, 2-jack in front - 5stack-digout 5-jack in back, 2-jack in front, a SPDIF out - 6stack 6-jack in back, 2-jack in front - 6stack-digout 6-jack with a SPDIF out - w810 3-jack - z71v 3-jack (HP shared SPDIF) - asus 3-jack (ASUS Mobo) - asus-w1v ASUS W1V - asus-dig ASUS with SPDIF out - asus-dig2 ASUS with SPDIF out (using GPIO2) - uniwill 3-jack - fujitsu Fujitsu Laptops (Pi1536) - F1734 2-jack - lg LG laptop (m1 express dual) - lg-lw LG LW20/LW25 laptop - tcl TCL S700 - clevo Clevo laptops (m520G, m665n) - medion Medion Rim 2150 - test for testing/debugging purpose, almost all controls can be - adjusted. Appearing only when compiled with - $CONFIG_SND_DEBUG=y - auto auto-config reading BIOS (default) - - ALC260 - hp HP machines - hp-3013 HP machines (3013-variant) - hp-dc7600 HP DC7600 - fujitsu Fujitsu S7020 - acer Acer TravelMate - will Will laptops (PB V7900) - replacer Replacer 672V - basic fixed pin assignment (old default model) - test for testing/debugging purpose, almost all controls can - adjusted. Appearing only when compiled with - $CONFIG_SND_DEBUG=y - auto auto-config reading BIOS (default) - - ALC262 - fujitsu Fujitsu Laptop - hp-bpc HP xw4400/6400/8400/9400 laptops - hp-bpc-d7000 HP BPC D7000 - hp-tc-t5735 HP Thin Client T5735 - hp-rp5700 HP RP5700 - benq Benq ED8 - benq-t31 Benq T31 - hippo Hippo (ATI) with jack detection, Sony UX-90s - hippo_1 Hippo (Benq) with jack detection - sony-assamd Sony ASSAMD - toshiba-s06 Toshiba S06 - toshiba-rx1 Toshiba RX1 - ultra Samsung Q1 Ultra Vista model - lenovo-3000 Lenovo 3000 y410 - nec NEC Versa S9100 - basic fixed pin assignment w/o SPDIF - auto auto-config reading BIOS (default) - - ALC267/268 - quanta-il1 Quanta IL1 mini-notebook - 3stack 3-stack model - toshiba Toshiba A205 - acer Acer laptops - acer-aspire Acer Aspire One - dell Dell OEM laptops (Vostro 1200) - zepto Zepto laptops - test for testing/debugging purpose, almost all controls can - adjusted. Appearing only when compiled with - $CONFIG_SND_DEBUG=y - auto auto-config reading BIOS (default) - - ALC269 - basic Basic preset - quanta Quanta FL1 - eeepc-p703 ASUS Eeepc P703 P900A - eeepc-p901 ASUS Eeepc P901 S101 - - ALC662/663 - 3stack-dig 3-stack (2-channel) with SPDIF - 3stack-6ch 3-stack (6-channel) - 3stack-6ch-dig 3-stack (6-channel) with SPDIF - 6stack-dig 6-stack with SPDIF - lenovo-101e Lenovo laptop - eeepc-p701 ASUS Eeepc P701 - eeepc-ep20 ASUS Eeepc EP20 - ecs ECS/Foxconn mobo - m51va ASUS M51VA - g71v ASUS G71V - h13 ASUS H13 - g50v ASUS G50V - asus-mode1 ASUS - asus-mode2 ASUS - asus-mode3 ASUS - asus-mode4 ASUS - asus-mode5 ASUS - asus-mode6 ASUS - auto auto-config reading BIOS (default) - - ALC882/885 - 3stack-dig 3-jack with SPDIF I/O - 6stack-dig 6-jack digital with SPDIF I/O - arima Arima W820Di1 - targa Targa T8, MSI-1049 T8 - asus-a7j ASUS A7J - asus-a7m ASUS A7M - macpro MacPro support - mbp3 Macbook Pro rev3 - imac24 iMac 24'' with jack detection - w2jc ASUS W2JC - auto auto-config reading BIOS (default) - - ALC883/888 - 3stack-dig 3-jack with SPDIF I/O - 6stack-dig 6-jack digital with SPDIF I/O - 3stack-6ch 3-jack 6-channel - 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O - 6stack-dig-demo 6-jack digital for Intel demo board - acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc) - acer-aspire Acer Aspire 9810 - medion Medion Laptops - medion-md2 Medion MD2 - targa-dig Targa/MSI - targa-2ch-dig Targs/MSI with 2-channel - laptop-eapd 3-jack with SPDIF I/O and EAPD (Clevo M540JE, M550JE) - lenovo-101e Lenovo 101E - lenovo-nb0763 Lenovo NB0763 - lenovo-ms7195-dig Lenovo MS7195 - lenovo-sky Lenovo Sky - haier-w66 Haier W66 - 3stack-hp HP machines with 3stack (Lucknow, Samba boards) - 6stack-dell Dell machines with 6stack (Inspiron 530) - mitac Mitac 8252D - clevo-m720 Clevo M720 laptop series - fujitsu-pi2515 Fujitsu AMILO Pi2515 - 3stack-6ch-intel Intel DG33* boards - auto auto-config reading BIOS (default) - - ALC861/660 - 3stack 3-jack - 3stack-dig 3-jack with SPDIF I/O - 6stack-dig 6-jack with SPDIF I/O - 3stack-660 3-jack (for ALC660) - uniwill-m31 Uniwill M31 laptop - toshiba Toshiba laptop support - asus Asus laptop support - asus-laptop ASUS F2/F3 laptops - auto auto-config reading BIOS (default) - - ALC861VD/660VD - 3stack 3-jack - 3stack-dig 3-jack with SPDIF OUT - 6stack-dig 6-jack with SPDIF OUT - 3stack-660 3-jack (for ALC660VD) - 3stack-660-digout 3-jack with SPDIF OUT (for ALC660VD) - lenovo Lenovo 3000 C200 - dallas Dallas laptops - hp HP TX1000 - auto auto-config reading BIOS (default) - - CMI9880 - minimal 3-jack in back - min_fp 3-jack in back, 2-jack in front - full 6-jack in back, 2-jack in front - full_dig 6-jack in back, 2-jack in front, SPDIF I/O - allout 5-jack in back, 2-jack in front, SPDIF out - auto auto-config reading BIOS (default) - - AD1882 / AD1882A - 3stack 3-stack mode (default) - 6stack 6-stack mode - - AD1884A / AD1883 / AD1984A / AD1984B - desktop 3-stack desktop (default) - laptop laptop with HP jack sensing - mobile mobile devices with HP jack sensing - thinkpad Lenovo Thinkpad X300 - - AD1884 - N/A - - AD1981 - basic 3-jack (default) - hp HP nx6320 - thinkpad Lenovo Thinkpad T60/X60/Z60 - toshiba Toshiba U205 - - AD1983 - N/A - - AD1984 - basic default configuration - thinkpad Lenovo Thinkpad T61/X61 - dell Dell T3400 - - AD1986A - 6stack 6-jack, separate surrounds (default) - 3stack 3-stack, shared surrounds - laptop 2-channel only (FSC V2060, Samsung M50) - laptop-eapd 2-channel with EAPD (Samsung R65, ASUS A6J) - laptop-automute 2-channel with EAPD and HP-automute (Lenovo N100) - ultra 2-channel with EAPD (Samsung Ultra tablet PC) - - AD1988/AD1988B/AD1989A/AD1989B - 6stack 6-jack - 6stack-dig ditto with SPDIF - 3stack 3-jack - 3stack-dig ditto with SPDIF - laptop 3-jack with hp-jack automute - laptop-dig ditto with SPDIF - auto auto-config reading BIOS (default) - - Conexant 5045 - laptop-hpsense Laptop with HP sense (old model laptop) - laptop-micsense Laptop with Mic sense (old model fujitsu) - laptop-hpmicsense Laptop with HP and Mic senses - benq Benq R55E - test for testing/debugging purpose, almost all controls - can be adjusted. Appearing only when compiled with - $CONFIG_SND_DEBUG=y - - Conexant 5047 - laptop Basic Laptop config - laptop-hp Laptop config for some HP models (subdevice 30A5) - laptop-eapd Laptop config with EAPD support - test for testing/debugging purpose, almost all controls - can be adjusted. Appearing only when compiled with - $CONFIG_SND_DEBUG=y - - Conexant 5051 - laptop Basic Laptop config (default) - hp HP Spartan laptop - - STAC9200 - ref Reference board - dell-d21 Dell (unknown) - dell-d22 Dell (unknown) - dell-d23 Dell (unknown) - dell-m21 Dell Inspiron 630m, Dell Inspiron 640m - dell-m22 Dell Latitude D620, Dell Latitude D820 - dell-m23 Dell XPS M1710, Dell Precision M90 - dell-m24 Dell Latitude 120L - dell-m25 Dell Inspiron E1505n - dell-m26 Dell Inspiron 1501 - dell-m27 Dell Inspiron E1705/9400 - gateway Gateway laptops with EAPD control - panasonic Panasonic CF-74 - - STAC9205/9254 - ref Reference board - dell-m42 Dell (unknown) - dell-m43 Dell Precision - dell-m44 Dell Inspiron - - STAC9220/9221 - ref Reference board - 3stack D945 3stack - 5stack D945 5stack + SPDIF - intel-mac-v1 Intel Mac Type 1 - intel-mac-v2 Intel Mac Type 2 - intel-mac-v3 Intel Mac Type 3 - intel-mac-v4 Intel Mac Type 4 - intel-mac-v5 Intel Mac Type 5 - intel-mac-auto Intel Mac (detect type according to subsystem id) - macmini Intel Mac Mini (equivalent with type 3) - macbook Intel Mac Book (eq. type 5) - macbook-pro-v1 Intel Mac Book Pro 1st generation (eq. type 3) - macbook-pro Intel Mac Book Pro 2nd generation (eq. type 3) - imac-intel Intel iMac (eq. type 2) - imac-intel-20 Intel iMac (newer version) (eq. type 3) - dell-d81 Dell (unknown) - dell-d82 Dell (unknown) - dell-m81 Dell (unknown) - dell-m82 Dell XPS M1210 - - STAC9202/9250/9251 - ref Reference board, base config - m2-2 Some Gateway MX series laptops - m6 Some Gateway NX series laptops - pa6 Gateway NX860 series - - STAC9227/9228/9229/927x - ref Reference board - 3stack D965 3stack - 5stack D965 5stack + SPDIF - dell-3stack Dell Dimension E520 - dell-bios Fixes with Dell BIOS setup - - STAC92HD71B* - ref Reference board - dell-m4-1 Dell desktops - dell-m4-2 Dell desktops - - STAC92HD73* - ref Reference board - dell-m6 Dell desktops - - STAC9872 - vaio Setup for VAIO FE550G/SZ110 - vaio-ar Setup for VAIO AR + models depending on the codec chip. The list of available models + is found in HD-Audio-Models.txt The model name "genric" is treated as a special case. When this model is given, the driver uses the generic codec parser without "codec-patch". It's sometimes good for testing and debugging. If the default configuration doesn't work and one of the above - matches with your device, report it together with the PCI - subsystem ID (output of "lspci -nv") to ALSA BTS or alsa-devel + matches with your device, report it together with alsa-info.sh + output (with --no-upload option) to kernel bugzilla or alsa-devel ML (see the section "Links and Addresses"). power_save and power_save_controller options are for power-saving @@ -1647,7 +1350,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. * AuzenTech X-Meridian * Bgears b-Enspirer * Club3D Theatron DTS - * HT-Omega Claro + * HT-Omega Claro (plus) + * HT-Omega Claro halo (XT) * Razer Barracuda AC-1 * Sondigo Inferno @@ -2404,8 +2108,11 @@ Links and Addresses ALSA project homepage http://www.alsa-project.org - ALSA Bug Tracking System - https://bugtrack.alsa-project.org/bugs/ + Kernel Bugzilla + http://bugzilla.kernel.org/ ALSA Developers ML mailto:alsa-devel@alsa-project.org + + alsa-info.sh script + http://www.alsa-project.org/alsa-info.sh diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt new file mode 100644 index 00000000000..4b7ac21ea9e --- /dev/null +++ b/Documentation/sound/alsa/HD-Audio-Models.txt @@ -0,0 +1,348 @@ + Model name Description + ---------- ----------- +ALC880 +====== + 3stack 3-jack in back and a headphone out + 3stack-digout 3-jack in back, a HP out and a SPDIF out + 5stack 5-jack in back, 2-jack in front + 5stack-digout 5-jack in back, 2-jack in front, a SPDIF out + 6stack 6-jack in back, 2-jack in front + 6stack-digout 6-jack with a SPDIF out + w810 3-jack + z71v 3-jack (HP shared SPDIF) + asus 3-jack (ASUS Mobo) + asus-w1v ASUS W1V + asus-dig ASUS with SPDIF out + asus-dig2 ASUS with SPDIF out (using GPIO2) + uniwill 3-jack + fujitsu Fujitsu Laptops (Pi1536) + F1734 2-jack + lg LG laptop (m1 express dual) + lg-lw LG LW20/LW25 laptop + tcl TCL S700 + clevo Clevo laptops (m520G, m665n) + medion Medion Rim 2150 + test for testing/debugging purpose, almost all controls can be + adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y + auto auto-config reading BIOS (default) + +ALC260 +====== + hp HP machines + hp-3013 HP machines (3013-variant) + hp-dc7600 HP DC7600 + fujitsu Fujitsu S7020 + acer Acer TravelMate + will Will laptops (PB V7900) + replacer Replacer 672V + basic fixed pin assignment (old default model) + test for testing/debugging purpose, almost all controls can + adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y + auto auto-config reading BIOS (default) + +ALC262 +====== + fujitsu Fujitsu Laptop + hp-bpc HP xw4400/6400/8400/9400 laptops + hp-bpc-d7000 HP BPC D7000 + hp-tc-t5735 HP Thin Client T5735 + hp-rp5700 HP RP5700 + benq Benq ED8 + benq-t31 Benq T31 + hippo Hippo (ATI) with jack detection, Sony UX-90s + hippo_1 Hippo (Benq) with jack detection + sony-assamd Sony ASSAMD + toshiba-s06 Toshiba S06 + toshiba-rx1 Toshiba RX1 + ultra Samsung Q1 Ultra Vista model + lenovo-3000 Lenovo 3000 y410 + nec NEC Versa S9100 + basic fixed pin assignment w/o SPDIF + auto auto-config reading BIOS (default) + +ALC267/268 +========== + quanta-il1 Quanta IL1 mini-notebook + 3stack 3-stack model + toshiba Toshiba A205 + acer Acer laptops + acer-dmic Acer laptops with digital-mic + acer-aspire Acer Aspire One + dell Dell OEM laptops (Vostro 1200) + zepto Zepto laptops + test for testing/debugging purpose, almost all controls can + adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y + auto auto-config reading BIOS (default) + +ALC269 +====== + basic Basic preset + quanta Quanta FL1 + eeepc-p703 ASUS Eeepc P703 P900A + eeepc-p901 ASUS Eeepc P901 S101 + fujitsu FSC Amilo + auto auto-config reading BIOS (default) + +ALC662/663 +========== + 3stack-dig 3-stack (2-channel) with SPDIF + 3stack-6ch 3-stack (6-channel) + 3stack-6ch-dig 3-stack (6-channel) with SPDIF + 6stack-dig 6-stack with SPDIF + lenovo-101e Lenovo laptop + eeepc-p701 ASUS Eeepc P701 + eeepc-ep20 ASUS Eeepc EP20 + ecs ECS/Foxconn mobo + m51va ASUS M51VA + g71v ASUS G71V + h13 ASUS H13 + g50v ASUS G50V + asus-mode1 ASUS + asus-mode2 ASUS + asus-mode3 ASUS + asus-mode4 ASUS + asus-mode5 ASUS + asus-mode6 ASUS + auto auto-config reading BIOS (default) + +ALC882/885 +========== + 3stack-dig 3-jack with SPDIF I/O + 6stack-dig 6-jack digital with SPDIF I/O + arima Arima W820Di1 + targa Targa T8, MSI-1049 T8 + asus-a7j ASUS A7J + asus-a7m ASUS A7M + macpro MacPro support + mbp3 Macbook Pro rev3 + imac24 iMac 24'' with jack detection + w2jc ASUS W2JC + auto auto-config reading BIOS (default) + +ALC883/888 +========== + 3stack-dig 3-jack with SPDIF I/O + 6stack-dig 6-jack digital with SPDIF I/O + 3stack-6ch 3-jack 6-channel + 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O + 6stack-dig-demo 6-jack digital for Intel demo board + acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc) + acer-aspire Acer Aspire 9810 + acer-aspire-4930g Acer Aspire 4930G + medion Medion Laptops + medion-md2 Medion MD2 + targa-dig Targa/MSI + targa-2ch-dig Targs/MSI with 2-channel + laptop-eapd 3-jack with SPDIF I/O and EAPD (Clevo M540JE, M550JE) + lenovo-101e Lenovo 101E + lenovo-nb0763 Lenovo NB0763 + lenovo-ms7195-dig Lenovo MS7195 + lenovo-sky Lenovo Sky + haier-w66 Haier W66 + 3stack-hp HP machines with 3stack (Lucknow, Samba boards) + 6stack-dell Dell machines with 6stack (Inspiron 530) + mitac Mitac 8252D + clevo-m720 Clevo M720 laptop series + fujitsu-pi2515 Fujitsu AMILO Pi2515 + fujitsu-xa3530 Fujitsu AMILO XA3530 + 3stack-6ch-intel Intel DG33* boards + auto auto-config reading BIOS (default) + +ALC861/660 +========== + 3stack 3-jack + 3stack-dig 3-jack with SPDIF I/O + 6stack-dig 6-jack with SPDIF I/O + 3stack-660 3-jack (for ALC660) + uniwill-m31 Uniwill M31 laptop + toshiba Toshiba laptop support + asus Asus laptop support + asus-laptop ASUS F2/F3 laptops + auto auto-config reading BIOS (default) + +ALC861VD/660VD +============== + 3stack 3-jack + 3stack-dig 3-jack with SPDIF OUT + 6stack-dig 6-jack with SPDIF OUT + 3stack-660 3-jack (for ALC660VD) + 3stack-660-digout 3-jack with SPDIF OUT (for ALC660VD) + lenovo Lenovo 3000 C200 + dallas Dallas laptops + hp HP TX1000 + asus-v1s ASUS V1Sn + auto auto-config reading BIOS (default) + +CMI9880 +======= + minimal 3-jack in back + min_fp 3-jack in back, 2-jack in front + full 6-jack in back, 2-jack in front + full_dig 6-jack in back, 2-jack in front, SPDIF I/O + allout 5-jack in back, 2-jack in front, SPDIF out + auto auto-config reading BIOS (default) + +AD1882 / AD1882A +================ + 3stack 3-stack mode (default) + 6stack 6-stack mode + +AD1884A / AD1883 / AD1984A / AD1984B +==================================== + desktop 3-stack desktop (default) + laptop laptop with HP jack sensing + mobile mobile devices with HP jack sensing + thinkpad Lenovo Thinkpad X300 + +AD1884 +====== + N/A + +AD1981 +====== + basic 3-jack (default) + hp HP nx6320 + thinkpad Lenovo Thinkpad T60/X60/Z60 + toshiba Toshiba U205 + +AD1983 +====== + N/A + +AD1984 +====== + basic default configuration + thinkpad Lenovo Thinkpad T61/X61 + dell Dell T3400 + +AD1986A +======= + 6stack 6-jack, separate surrounds (default) + 3stack 3-stack, shared surrounds + laptop 2-channel only (FSC V2060, Samsung M50) + laptop-eapd 2-channel with EAPD (ASUS A6J) + laptop-automute 2-channel with EAPD and HP-automute (Lenovo N100) + ultra 2-channel with EAPD (Samsung Ultra tablet PC) + samsung 2-channel with EAPD (Samsung R65) + +AD1988/AD1988B/AD1989A/AD1989B +============================== + 6stack 6-jack + 6stack-dig ditto with SPDIF + 3stack 3-jack + 3stack-dig ditto with SPDIF + laptop 3-jack with hp-jack automute + laptop-dig ditto with SPDIF + auto auto-config reading BIOS (default) + +Conexant 5045 +============= + laptop-hpsense Laptop with HP sense (old model laptop) + laptop-micsense Laptop with Mic sense (old model fujitsu) + laptop-hpmicsense Laptop with HP and Mic senses + benq Benq R55E + test for testing/debugging purpose, almost all controls + can be adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y + +Conexant 5047 +============= + laptop Basic Laptop config + laptop-hp Laptop config for some HP models (subdevice 30A5) + laptop-eapd Laptop config with EAPD support + test for testing/debugging purpose, almost all controls + can be adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y + +Conexant 5051 +============= + laptop Basic Laptop config (default) + hp HP Spartan laptop + +STAC9200 +======== + ref Reference board + dell-d21 Dell (unknown) + dell-d22 Dell (unknown) + dell-d23 Dell (unknown) + dell-m21 Dell Inspiron 630m, Dell Inspiron 640m + dell-m22 Dell Latitude D620, Dell Latitude D820 + dell-m23 Dell XPS M1710, Dell Precision M90 + dell-m24 Dell Latitude 120L + dell-m25 Dell Inspiron E1505n + dell-m26 Dell Inspiron 1501 + dell-m27 Dell Inspiron E1705/9400 + gateway Gateway laptops with EAPD control + panasonic Panasonic CF-74 + +STAC9205/9254 +============= + ref Reference board + dell-m42 Dell (unknown) + dell-m43 Dell Precision + dell-m44 Dell Inspiron + +STAC9220/9221 +============= + ref Reference board + 3stack D945 3stack + 5stack D945 5stack + SPDIF + intel-mac-v1 Intel Mac Type 1 + intel-mac-v2 Intel Mac Type 2 + intel-mac-v3 Intel Mac Type 3 + intel-mac-v4 Intel Mac Type 4 + intel-mac-v5 Intel Mac Type 5 + intel-mac-auto Intel Mac (detect type according to subsystem id) + macmini Intel Mac Mini (equivalent with type 3) + macbook Intel Mac Book (eq. type 5) + macbook-pro-v1 Intel Mac Book Pro 1st generation (eq. type 3) + macbook-pro Intel Mac Book Pro 2nd generation (eq. type 3) + imac-intel Intel iMac (eq. type 2) + imac-intel-20 Intel iMac (newer version) (eq. type 3) + dell-d81 Dell (unknown) + dell-d82 Dell (unknown) + dell-m81 Dell (unknown) + dell-m82 Dell XPS M1210 + +STAC9202/9250/9251 +================== + ref Reference board, base config + m2-2 Some Gateway MX series laptops + m6 Some Gateway NX series laptops + pa6 Gateway NX860 series + +STAC9227/9228/9229/927x +======================= + ref Reference board + ref-no-jd Reference board without HP/Mic jack detection + 3stack D965 3stack + 5stack D965 5stack + SPDIF + dell-3stack Dell Dimension E520 + dell-bios Fixes with Dell BIOS setup + +STAC92HD71B* +============ + ref Reference board + dell-m4-1 Dell desktops + dell-m4-2 Dell desktops + dell-m4-3 Dell desktops + +STAC92HD73* +=========== + ref Reference board + no-jd BIOS setup but without jack-detection + dell-m6-amic Dell desktops/laptops with analog mics + dell-m6-dmic Dell desktops/laptops with digital mics + dell-m6 Dell desktops/laptops with both type of mics + +STAC92HD83* +=========== + ref Reference board + +STAC9872 +======== + vaio Setup for VAIO FE550G/SZ110 + vaio-ar Setup for VAIO AR diff --git a/Documentation/sound/alsa/HD-Audio.txt b/Documentation/sound/alsa/HD-Audio.txt new file mode 100644 index 00000000000..8d68fff7183 --- /dev/null +++ b/Documentation/sound/alsa/HD-Audio.txt @@ -0,0 +1,577 @@ +MORE NOTES ON HD-AUDIO DRIVER +============================= + Takashi Iwai <tiwai@suse.de> + + +GENERAL +------- + +HD-audio is the new standard on-board audio component on modern PCs +after AC97. Although Linux has been supporting HD-audio since long +time ago, there are often problems with new machines. A part of the +problem is broken BIOS, and the rest is the driver implementation. +This document explains the brief trouble-shooting and debugging +methods for the HD-audio hardware. + +The HD-audio component consists of two parts: the controller chip and +the codec chips on the HD-audio bus. Linux provides a single driver +for all controllers, snd-hda-intel. Although the driver name contains +a word of a well-known harware vendor, it's not specific to it but for +all controller chips by other companies. Since the HD-audio +controllers are supposed to be compatible, the single snd-hda-driver +should work in most cases. But, not surprisingly, there are known +bugs and issues specific to each controller type. The snd-hda-intel +driver has a bunch of workarounds for these as described below. + +A controller may have multiple codecs. Usually you have one audio +codec and optionally one modem codec. In theory, there might be +multiple audio codecs, e.g. for analog and digital outputs, and the +driver might not work properly because of conflict of mixer elements. +This should be fixed in future if such hardware really exists. + +The snd-hda-intel driver has several different codec parsers depending +on the codec. It has a generic parser as a fallback, but this +functionality is fairly limited until now. Instead of the generic +parser, usually the codec-specific parser (coded in patch_*.c) is used +for the codec-specific implementations. The details about the +codec-specific problems are explained in the later sections. + +If you are interested in the deep debugging of HD-audio, read the +HD-audio specification at first. The specification is found on +Intel's web page, for example: + +- http://www.intel.com/standards/hdaudio/ + + +HD-AUDIO CONTROLLER +------------------- + +DMA-Position Problem +~~~~~~~~~~~~~~~~~~~~ +The most common problem of the controller is the inaccurate DMA +pointer reporting. The DMA pointer for playback and capture can be +read in two ways, either via a LPIB register or via a position-buffer +map. As default the driver tries to read from the io-mapped +position-buffer, and falls back to LPIB if the position-buffer appears +dead. However, this detection isn't perfect on some devices. In such +a case, you can change the default method via `position_fix` option. + +`position_fix=1` means to use LPIB method explicitly. +`position_fix=2` means to use the position-buffer. 0 is the default +value, the automatic check and fallback to LPIB as described in the +above. If you get a problem of repeated sounds, this option might +help. + +In addition to that, every controller is known to be broken regarding +the wake-up timing. It wakes up a few samples before actually +processing the data on the buffer. This caused a lot of problems, for +example, with ALSA dmix or JACK. Since 2.6.27 kernel, the driver puts +an artificial delay to the wake up timing. This delay is controlled +via `bdl_pos_adj` option. + +When `bdl_pos_adj` is a negative value (as default), it's assigned to +an appropriate value depending on the controller chip. For Intel +chips, it'd be 1 while it'd be 32 for others. Usually this works. +Only in case it doesn't work and you get warning messages, you should +change this parameter to other values. + + +Codec-Probing Problem +~~~~~~~~~~~~~~~~~~~~~ +A less often but a more severe problem is the codec probing. When +BIOS reports the available codec slots wrongly, the driver gets +confused and tries to access the non-existing codec slot. This often +results in the total screw-up, and destructs the further communication +with the codec chips. The symptom appears usually as error messages +like: +------------------------------------------------------------------------ + hda_intel: azx_get_response timeout, switching to polling mode: + last cmd=0x12345678 + hda_intel: azx_get_response timeout, switching to single_cmd mode: + last cmd=0x12345678 +------------------------------------------------------------------------ + +The first line is a warning, and this is usually relatively harmless. +It means that the codec response isn't notified via an IRQ. The +driver uses explicit polling method to read the response. It gives +very slight CPU overhead, but you'd unlikely notice it. + +The second line is, however, a fatal error. If this happens, usually +it means that something is really wrong. Most likely you are +accessing a non-existing codec slot. + +Thus, if the second error message appears, try to narrow the probed +codec slots via `probe_mask` option. It's a bitmask, and each bit +corresponds to the codec slot. For example, to probe only the first +slot, pass `probe_mask=1`. For the first and the third slots, pass +`probe_mask=5` (where 5 = 1 | 4), and so on. + +Since 2.6.29 kernel, the driver has a more robust probing method, so +this error might happen rarely, though. + + +Interrupt Handling +~~~~~~~~~~~~~~~~~~ +In rare but some cases, the interrupt isn't properly handled as +default. You would notice this by the DMA transfer error reported by +ALSA PCM core, for example. Using MSI might help in such a case. +Pass `enable_msi=1` option for enabling MSI. + + +HD-AUDIO CODEC +-------------- + +Model Option +~~~~~~~~~~~~ +The most common problem regarding the HD-audio driver is the +unsupported codec features or the mismatched device configuration. +Most of codec-specific code has several preset models, either to +override the BIOS setup or to provide more comprehensive features. + +The driver checks PCI SSID and looks through the static configuration +table until any matching entry is found. If you have a new machine, +you may see a message like below: +------------------------------------------------------------------------ + hda_codec: Unknown model for ALC880, trying auto-probe from BIOS... +------------------------------------------------------------------------ +Even if you see such a message, DON'T PANIC. Take a deep breath and +keep your towel. First of all, it's an informational message, no +warning, no error. This means that the PCI SSID of your device isn't +listed in the known preset model (white-)list. But, this doesn't mean +that the driver is broken. Many codec-drivers provide the automatic +configuration mechanism based on the BIOS setup. + +The HD-audio codec has usually "pin" widgets, and BIOS sets the default +configuration of each pin, which indicates the location, the +connection type, the jack color, etc. The HD-audio driver can guess +the right connection judging from these default configuration values. +However -- some codec-support codes, such as patch_analog.c, don't +support the automatic probing (yet as of 2.6.28). And, BIOS is often, +yes, pretty often broken. It sets up wrong values and screws up the +driver. + +The preset model is provided basically to overcome such a situation. +When the matching preset model is found in the white-list, the driver +assumes the static configuration of that preset and builds the mixer +elements and PCM streams based on the static information. Thus, if +you have a newer machine with a slightly different PCI SSID from the +existing one, you may have a good chance to re-use the same model. +You can pass the `model` option to specify the preset model instead of +PCI SSID look-up. + +What `model` option values are available depends on the codec chip. +Check your codec chip from the codec proc file (see "Codec Proc-File" +section below). It will show the vendor/product name of your codec +chip. Then, see Documentation/sound/alsa/HD-Audio-Modelstxt file, +the section of HD-audio driver. You can find a list of codecs +and `model` options belonging to each codec. For example, for Realtek +ALC262 codec chip, pass `model=ultra` for devices that are compatible +with Samsung Q1 Ultra. + +Thus, the first thing you can do for any brand-new, unsupported and +non-working HD-audio hardware is to check HD-audio codec and several +different `model` option values. If you have a luck, some of them +might suit with your device well. + +Some codecs such as ALC880 have a special model option `model=test`. +This configures the driver to provide as many mixer controls as +possible for every single pin feature except for the unsolicited +events (and maybe some other specials). Adjust each mixer element and +try the I/O in the way of trial-and-error until figuring out the whole +I/O pin mappings. + +Note that `model=generic` has a special meaning. It means to use the +generic parser regardless of the codec. Usually the codec-specific +parser is much better than the generic parser (as now). Thus this +option is more about the debugging purpose. + + +Speaker and Headphone Output +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +One of the most frequent (and obvious) bugs with HD-audio is the +silent output from either or both of a built-in speaker and a +headphone jack. In general, you should try a headphone output at +first. A speaker output often requires more additional controls like +the external amplifier bits. Thus a headphone output has a slightly +better chance. + +Before making a bug report, double-check whether the mixer is set up +correctly. The recent version of snd-hda-intel driver provides mostly +"Master" volume control as well as "Front" volume (where Front +indicates the front-channels). In addition, there can be individual +"Headphone" and "Speaker" controls. + +Ditto for the speaker output. There can be "External Amplifier" +switch on some codecs. Turn on this if present. + +Another related problem is the automatic mute of speaker output by +headphone plugging. This feature is implemented in most cases, but +not on every preset model or codec-support code. + +In anyway, try a different model option if you have such a problem. +Some other models may match better and give you more matching +functionality. If none of the available models works, send a bug +report. See the bug report section for details. + +If you are masochistic enough to debug the driver problem, note the +following: + +- The speaker (and the headphone, too) output often requires the + external amplifier. This can be set usually via EAPD verb or a + certain GPIO. If the codec pin supports EAPD, you have a better + chance via SET_EAPD_BTL verb (0x70c). On others, GPIO pin (mostly + it's either GPIO0 or GPIO1) may turn on/off EAPD. +- Some Realtek codecs require special vendor-specific coefficients to + turn on the amplifier. See patch_realtek.c. +- IDT codecs may have extra power-enable/disable controls on each + analog pin. See patch_sigmatel.c. +- Very rare but some devices don't accept the pin-detection verb until + triggered. Issuing GET_PIN_SENSE verb (0xf09) may result in the + codec-communication stall. Some examples are found in + patch_realtek.c. + + +Capture Problems +~~~~~~~~~~~~~~~~ +The capture problems are often because of missing setups of mixers. +Thus, before submitting a bug report, make sure that you set up the +mixer correctly. For example, both "Capture Volume" and "Capture +Switch" have to be set properly in addition to the right "Capture +Source" or "Input Source" selection. Some devices have "Mic Boost" +volume or switch. + +When the PCM device is opened via "default" PCM (without pulse-audio +plugin), you'll likely have "Digital Capture Volume" control as well. +This is provided for the extra gain/attenuation of the signal in +software, especially for the inputs without the hardware volume +control such as digital microphones. Unless really needed, this +should be set to exactly 50%, corresponding to 0dB -- neither extra +gain nor attenuation. When you use "hw" PCM, i.e., a raw access PCM, +this control will have no influence, though. + +It's known that some codecs / devices have fairly bad analog circuits, +and the recorded sound contains a certain DC-offset. This is no bug +of the driver. + +Most of modern laptops have no analog CD-input connection. Thus, the +recording from CD input won't work in many cases although the driver +provides it as the capture source. Use CDDA instead. + +The automatic switching of the built-in and external mic per plugging +is implemented on some codec models but not on every model. Partly +because of my laziness but mostly lack of testers. Feel free to +submit the improvement patch to the author. + + +Direct Debugging +~~~~~~~~~~~~~~~~ +If no model option gives you a better result, and you are a tough guy +to fight against evil, try debugging via hitting the raw HD-audio +codec verbs to the device. Some tools are available: hda-emu and +hda-analyzer. The detailed description is found in the sections +below. You'd need to enable hwdep for using these tools. See "Kernel +Configuration" section. + + +OTHER ISSUES +------------ + +Kernel Configuration +~~~~~~~~~~~~~~~~~~~~ +In general, I recommend you to enable the sound debug option, +`CONFIG_SND_DEBUG=y`, no matter whether you are debugging or not. +This enables snd_printd() macro and others, and you'll get additional +kernel messages at probing. + +In addition, you can enable `CONFIG_SND_DEBUG_VERBOSE=y`. But this +will give you far more messages. Thus turn this on only when you are +sure to want it. + +Don't forget to turn on the appropriate `CONFIG_SND_HDA_CODEC_*` +options. Note that each of them corresponds to the codec chip, not +the controller chip. Thus, even if lspci shows the Nvidia controller, +you may need to choose the option for other vendors. If you are +unsure, just select all yes. + +`CONFIG_SND_HDA_HWDEP` is a useful option for debugging the driver. +When this is enabled, the driver creates hardware-dependent devices +(one per each codec), and you have a raw access to the device via +these device files. For example, `hwC0D2` will be created for the +codec slot #2 of the first card (#0). For debug-tools such as +hda-verb and hda-analyzer, the hwdep device has to be enabled. +Thus, it'd be better to turn this on always. + +`CONFIG_SND_HDA_RECONFIG` is a new option, and this depends on the +hwdep option above. When enabled, you'll have some sysfs files under +the corresponding hwdep directory. See "HD-audio reconfiguration" +section below. + +`CONFIG_SND_HDA_POWER_SAVE` option enables the power-saving feature. +See "Power-saving" section below. + + +Codec Proc-File +~~~~~~~~~~~~~~~ +The codec proc-file is a treasure-chest for debugging HD-audio. +It shows most of useful information of each codec widget. + +The proc file is located in /proc/asound/card*/codec#*, one file per +each codec slot. You can know the codec vendor, product id and +names, the type of each widget, capabilities and so on. +This file, however, doesn't show the jack sensing state, so far. This +is because the jack-sensing might be depending on the trigger state. + +This file will be picked up by the debug tools, and also it can be fed +to the emulator as the primary codec information. See the debug tools +section below. + +This proc file can be also used to check whether the generic parser is +used. When the generic parser is used, the vendor/product ID name +will appear as "Realtek ID 0262", instead of "Realtek ALC262". + + +HD-Audio Reconfiguration +~~~~~~~~~~~~~~~~~~~~~~~~ +This is an experimental feature to allow you re-configure the HD-audio +codec dynamically without reloading the driver. The following sysfs +files are available under each codec-hwdep device directory (e.g. +/sys/class/sound/hwC0D0): + +vendor_id:: + Shows the 32bit codec vendor-id hex number. You can change the + vendor-id value by writing to this file. +subsystem_id:: + Shows the 32bit codec subsystem-id hex number. You can change the + subsystem-id value by writing to this file. +revision_id:: + Shows the 32bit codec revision-id hex number. You can change the + revision-id value by writing to this file. +afg:: + Shows the AFG ID. This is read-only. +mfg:: + Shows the MFG ID. This is read-only. +name:: + Shows the codec name string. Can be changed by writing to this + file. +modelname:: + Shows the currently set `model` option. Can be changed by writing + to this file. +init_verbs:: + The extra verbs to execute at initialization. You can add a verb by + writing to this file. Pass tree numbers, nid, verb and parameter. +hints:: + Shows hint strings for codec parsers for any use. Right now it's + not used. +reconfig:: + Triggers the codec re-configuration. When any value is written to + this file, the driver re-initialize and parses the codec tree + again. All the changes done by the sysfs entries above are taken + into account. +clear:: + Resets the codec, removes the mixer elements and PCM stuff of the + specified codec, and clear all init verbs and hints. + + +Power-Saving +~~~~~~~~~~~~ +The power-saving is a kind of auto-suspend of the device. When the +device is inactive for a certain time, the device is automatically +turned off to save the power. The time to go down is specified via +`power_save` module option, and this option can be changed dynamically +via sysfs. + +The power-saving won't work when the analog loopback is enabled on +some codecs. Make sure that you mute all unneeded signal routes when +you want the power-saving. + +The power-saving feature might cause audible click noises at each +power-down/up depending on the device. Some of them might be +solvable, but some are hard, I'm afraid. Some distros such as +openSUSE enables the power-saving feature automatically when the power +cable is unplugged. Thus, if you hear noises, suspect first the +power-saving. See /sys/module/snd_hda_intel/parameters/power_save to +check the current value. If it's non-zero, the feature is turned on. + + +Development Tree +~~~~~~~~~~~~~~~~ +The latest development codes for HD-audio are found on sound git tree: + +- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound-2.6.git + +The master branch or for-next branches can be used as the main +development branches in general while the HD-audio specific patches +are committed in topic/hda branch. + +If you are using the latest Linus tree, it'd be better to pull the +above GIT tree onto it. If you are using the older kernels, an easy +way to try the latest ALSA code is to build from the snapshot +tarball. There are daily tarballs and the latest snapshot tarball. +All can be built just like normal alsa-driver release packages, that +is, installed via the usual spells: configure, make and make +install(-modules). See INSTALL in the package. The snapshot tarballs +are found at: + +- ftp://ftp.kernel.org/pub/linux/kernel/people/tiwai/snapshot/ + + +Sending a Bug Report +~~~~~~~~~~~~~~~~~~~~ +If any model or module options don't work for your device, it's time +to send a bug report to the developers. Give the following in your +bug report: + +- Hardware vendor, product and model names +- Kernel version (and ALSA-driver version if you built externally) +- `alsa-info.sh` output; run with `--no-upload` option. See the + section below about alsa-info + +If it's a regression, at best, send alsa-info outputs of both working +and non-working kernels. This is really helpful because we can +compare the codec registers directly. + +Send a bug report either the followings: + +kernel-bugzilla:: + http://bugme.linux-foundation.org/ +alsa-devel ML:: + alsa-devel@alsa-project.org + + +DEBUG TOOLS +----------- + +This section describes some tools available for debugging HD-audio +problems. + +alsa-info +~~~~~~~~~ +The script `alsa-info.sh` is a very useful tool to gather the audio +device information. You can fetch the latest version from: + +- http://www.alsa-project.org/alsa-info.sh + +Run this script as root, and it will gather the important information +such as the module lists, module parameters, proc file contents +including the codec proc files, mixer outputs and the control +elements. As default, it will store the information onto a web server +on alsa-project.org. But, if you send a bug report, it'd be better to +run with `--no-upload` option, and attach the generated file. + +There are some other useful options. See `--help` option output for +details. + + +hda-verb +~~~~~~~~ +hda-verb is a tiny program that allows you to access the HD-audio +codec directly. You can execute a raw HD-audio codec verb with this. +This program accesses the hwdep device, thus you need to enable the +kernel config `CONFIG_SND_HDA_HWDEP=y` beforehand. + +The hda-verb program takes four arguments: the hwdep device file, the +widget NID, the verb and the parameter. When you access to the codec +on the slot 2 of the card 0, pass /dev/snd/hwC0D2 to the first +argument, typically. (However, the real path name depends on the +system.) + +The second parameter is the widget number-id to access. The third +parameter can be either a hex/digit number or a string corresponding +to a verb. Similarly, the last parameter is the value to write, or +can be a string for the parameter type. + +------------------------------------------------------------------------ + % hda-verb /dev/snd/hwC0D0 0x12 0x701 2 + nid = 0x12, verb = 0x701, param = 0x2 + value = 0x0 + + % hda-verb /dev/snd/hwC0D0 0x0 PARAMETERS VENDOR_ID + nid = 0x0, verb = 0xf00, param = 0x0 + value = 0x10ec0262 + + % hda-verb /dev/snd/hwC0D0 2 set_a 0xb080 + nid = 0x2, verb = 0x300, param = 0xb080 + value = 0x0 +------------------------------------------------------------------------ + +Although you can issue any verbs with this program, the driver state +won't be always updated. For example, the volume values are usually +cached in the driver, and thus changing the widget amp value directly +via hda-verb won't change the mixer value. + +The hda-verb program is found in the ftp directory: + +- ftp://ftp.kernel.org/pub/linux/kernel/people/tiwai/misc/ + +Also a git repository is available: + +- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/hda-verb.git + +See README file in the tarball for more details about hda-verb +program. + + +hda-analyzer +~~~~~~~~~~~~ +hda-analyzer provides a graphical interface to access the raw HD-audio +control, based on pyGTK2 binding. It's a more powerful version of +hda-verb. The program gives you an easy-to-use GUI stuff for showing +the widget information and adjusting the amp values, as well as the +proc-compatible output. + +The hda-analyzer is a part of alsa.git repository in +alsa-project.org: + +- http://git.alsa-project.org/?p=alsa.git;a=tree;f=hda-analyzer + + +Codecgraph +~~~~~~~~~~ +Codecgraph is a utility program to generate a graph and visualizes the +codec-node connection of a codec chip. It's especially useful when +you analyze or debug a codec without a proper datasheet. The program +parses the given codec proc file and converts to SVG via graphiz +program. + +The tarball and GIT trees are found in the web page at: + +- http://helllabs.org/codecgraph/ + + +hda-emu +~~~~~~~ +hda-emu is an HD-audio emulator. The main purpose of this program is +to debug an HD-audio codec without the real hardware. Thus, it +doesn't emulate the behavior with the real audio I/O, but it just +dumps the codec register changes and the ALSA-driver internal changes +at probing and operating the HD-audio driver. + +The program requires a codec proc-file to simulate. Get a proc file +for the target codec beforehand, or pick up an example codec from the +codec proc collections in the tarball. Then, run the program with the +proc file, and the hda-emu program will start parsing the codec file +and simulates the HD-audio driver: + +------------------------------------------------------------------------ + % hda-emu codecs/stac9200-dell-d820-laptop + # Parsing.. + hda_codec: Unknown model for STAC9200, using BIOS defaults + hda_codec: pin nid 08 bios pin config 40c003fa + .... +------------------------------------------------------------------------ + +The program gives you only a very dumb command-line interface. You +can get a proc-file dump at the current state, get a list of control +(mixer) elements, set/get the control element value, simulate the PCM +operation, the jack plugging simulation, etc. + +The package is found in: + +- ftp://ftp.kernel.org/pub/linux/kernel/people/tiwai/misc/ + +A git repository is available: + +- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/hda-emu.git + +See README file in the tarball for more details about hda-emu +program. diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt index f738b296440..bba2dbb79d8 100644 --- a/Documentation/sound/alsa/Procfile.txt +++ b/Documentation/sound/alsa/Procfile.txt @@ -153,6 +153,16 @@ card*/codec#* Shows the general codec information and the attribute of each widget node. +card*/eld#* + Available for HDMI or DisplayPort interfaces. + Shows ELD(EDID Like Data) info retrieved from the attached HDMI sink, + and describes its audio capabilities and configurations. + + Some ELD fields may be modified by doing `echo name hex_value > eld#*`. + Only do this if you are sure the HDMI sink provided value is wrong. + And if that makes your HDMI audio work, please report to us so that we + can fix it in future kernel releases. + Sequencer Information --------------------- diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt index f370e7db86a..bab7711ce96 100644 --- a/Documentation/sound/alsa/soc/machine.txt +++ b/Documentation/sound/alsa/soc/machine.txt @@ -9,7 +9,7 @@ the audio subsystem with the kernel as a platform device and is represented by the following struct:- /* SoC machine */ -struct snd_soc_machine { +struct snd_soc_card { char *name; int (*probe)(struct platform_device *pdev); @@ -67,10 +67,10 @@ static struct snd_soc_dai_link corgi_dai = { .ops = &corgi_ops, }; -struct snd_soc_machine then sets up the machine with it's DAIs. e.g. +struct snd_soc_card then sets up the machine with it's DAIs. e.g. /* corgi audio machine driver */ -static struct snd_soc_machine snd_soc_machine_corgi = { +static struct snd_soc_card snd_soc_corgi = { .name = "Corgi", .dai_link = &corgi_dai, .num_links = 1, @@ -90,7 +90,7 @@ static struct wm8731_setup_data corgi_wm8731_setup = { /* corgi audio subsystem */ static struct snd_soc_device corgi_snd_devdata = { - .machine = &snd_soc_machine_corgi, + .machine = &snd_soc_corgi, .platform = &pxa2xx_soc_platform, .codec_dev = &soc_codec_dev_wm8731, .codec_data = &corgi_wm8731_setup, diff --git a/Documentation/spi/.gitignore b/Documentation/spi/.gitignore new file mode 100644 index 00000000000..4280576397e --- /dev/null +++ b/Documentation/spi/.gitignore @@ -0,0 +1,2 @@ +spidev_fdx +spidev_test diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx index bbe8dee681a..6bb916d57c9 100644 --- a/Documentation/spi/pxa2xx +++ b/Documentation/spi/pxa2xx @@ -96,7 +96,7 @@ Each slave device attached to the PXA must provide slave specific configuration information via the structure "pxa2xx_spi_chip" found in "arch/arm/mach-pxa/include/mach/pxa2xx_spi.h". The pxa2xx_spi master controller driver will uses the configuration whenever the driver communicates with the slave -device. +device. All fields are optional. struct pxa2xx_spi_chip { u8 tx_threshold; @@ -112,14 +112,17 @@ used to configure the SSP hardware fifo. These fields are critical to the performance of pxa2xx_spi driver and misconfiguration will result in rx fifo overruns (especially in PIO mode transfers). Good default values are - .tx_threshold = 12, - .rx_threshold = 4, + .tx_threshold = 8, + .rx_threshold = 8, + +The range is 1 to 16 where zero indicates "use default". The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA engine and is related the "spi_device.bits_per_word" field. Read and understand the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers to determine the correct value. An SSP configured for byte-wide transfers would -use a value of 8. +use a value of 8. The driver will determine a reasonable default if +dma_burst_size == 0. The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle trailing bytes in the SSP receiver fifo. The correct value for this field is @@ -137,7 +140,13 @@ function for asserting/deasserting a slave device chip select. If the field is NULL, the pxa2xx_spi master controller driver assumes that the SSP port is configured to use SSPFRM instead. -NSSP SALVE SAMPLE +NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the +chipselect is dropped after each spi_transfer. Most devices need chip select +asserted around the complete message. Use SSPFRM as a GPIO (through cs_control) +to accomodate these chips. + + +NSSP SLAVE SAMPLE ----------------- The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the "spi_board_info.controller_data" field. Below is a sample configuration using @@ -206,18 +215,21 @@ static void __init streetracer_init(void) DMA and PIO I/O Support ----------------------- -The pxa2xx_spi driver support both DMA and interrupt driven PIO message -transfers. The driver defaults to PIO mode and DMA transfers must enabled by -setting the "enable_dma" flag in the "pxa2xx_spi_master" structure and -ensuring that the "pxa2xx_spi_chip.dma_burst_size" field is non-zero. The DMA -mode support both coherent and stream based DMA mappings. +The pxa2xx_spi driver supports both DMA and interrupt driven PIO message +transfers. The driver defaults to PIO mode and DMA transfers must be enabled +by setting the "enable_dma" flag in the "pxa2xx_spi_master" structure. The DMA +mode supports both coherent and stream based DMA mappings. The following logic is used to determine the type of I/O to be used on a per "spi_transfer" basis: -if !enable_dma or dma_burst_size == 0 then +if !enable_dma then always use PIO transfers +if spi_message.len > 8191 then + print "rate limited" warning + use PIO transfers + if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then use coherent DMA mode diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary index 8bae2f018d3..0f5122eb282 100644 --- a/Documentation/spi/spi-summary +++ b/Documentation/spi/spi-summary @@ -215,7 +215,7 @@ So for example arch/.../mach-*/board-*.c files might have code like: /* if your mach-* infrastructure doesn't support kernels that can * run on multiple boards, pdata wouldn't benefit from "__init". */ - static struct mysoc_spi_data __init pdata = { ... }; + static struct mysoc_spi_data __initdata pdata = { ... }; static __init board_init(void) { diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt index 4cfc78835bc..a452227361b 100644 --- a/Documentation/stable_kernel_rules.txt +++ b/Documentation/stable_kernel_rules.txt @@ -12,6 +12,7 @@ Rules on what kind of patches are accepted, and which ones are not, into the marked CONFIG_BROKEN), an oops, a hang, data corruption, a real security issue, or some "oh, that's not good" issue. In short, something critical. + - New device IDs and quirks are also accepted. - No "theoretical race condition" issues, unless an explanation of how the race can be exploited is also provided. - It cannot contain any "trivial" fixes in it (spelling changes, diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index e1ff0d920a5..a4ccdd1981c 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -363,10 +363,21 @@ tainted: Non-zero if the kernel has been tainted. Numeric values, which can be ORed together: - 1 - A module with a non-GPL license has been loaded, this - includes modules with no license. - Set by modutils >= 2.4.9 and module-init-tools. - 2 - A module was force loaded by insmod -f. - Set by modutils >= 2.4.9 and module-init-tools. - 4 - Unsafe SMP processors: SMP with CPUs not designed for SMP. + 1 - A module with a non-GPL license has been loaded, this + includes modules with no license. + Set by modutils >= 2.4.9 and module-init-tools. + 2 - A module was force loaded by insmod -f. + Set by modutils >= 2.4.9 and module-init-tools. + 4 - Unsafe SMP processors: SMP with CPUs not designed for SMP. + 8 - A module was forcibly unloaded from the system by rmmod -f. + 16 - A hardware machine check error occurred on the system. + 32 - A bad page was discovered on the system. + 64 - The user has asked that the system be marked "tainted". This + could be because they are running software that directly modifies + the hardware, or for other reasons. + 128 - The system has died. + 256 - The ACPI DSDT has been overridden with one supplied by the user + instead of using the one provided by the hardware. + 512 - A kernel warning has occurred. +1024 - A module from drivers/staging was loaded. diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt index 5ce0952aa06..10a0263ebb3 100644 --- a/Documentation/sysrq.txt +++ b/Documentation/sysrq.txt @@ -95,7 +95,9 @@ On all - write a character to /proc/sysrq-trigger. e.g.: 'p' - Will dump the current registers and flags to your console. -'q' - Will dump a list of all running timers. +'q' - Will dump per CPU lists of all armed hrtimers (but NOT regular + timer_list timers) and detailed information about all + clockevent devices. 'r' - Turns off keyboard raw mode and sets it to XLATE. diff --git a/Documentation/tracepoints.txt b/Documentation/tracepoints.txt new file mode 100644 index 00000000000..6f0a044f5b5 --- /dev/null +++ b/Documentation/tracepoints.txt @@ -0,0 +1,115 @@ + Using the Linux Kernel Tracepoints + + Mathieu Desnoyers + + +This document introduces Linux Kernel Tracepoints and their use. It +provides examples of how to insert tracepoints in the kernel and +connect probe functions to them and provides some examples of probe +functions. + + +* Purpose of tracepoints + +A tracepoint placed in code provides a hook to call a function (probe) +that you can provide at runtime. A tracepoint can be "on" (a probe is +connected to it) or "off" (no probe is attached). When a tracepoint is +"off" it has no effect, except for adding a tiny time penalty +(checking a condition for a branch) and space penalty (adding a few +bytes for the function call at the end of the instrumented function +and adds a data structure in a separate section). When a tracepoint +is "on", the function you provide is called each time the tracepoint +is executed, in the execution context of the caller. When the function +provided ends its execution, it returns to the caller (continuing from +the tracepoint site). + +You can put tracepoints at important locations in the code. They are +lightweight hooks that can pass an arbitrary number of parameters, +which prototypes are described in a tracepoint declaration placed in a +header file. + +They can be used for tracing and performance accounting. + + +* Usage + +Two elements are required for tracepoints : + +- A tracepoint definition, placed in a header file. +- The tracepoint statement, in C code. + +In order to use tracepoints, you should include linux/tracepoint.h. + +In include/trace/subsys.h : + +#include <linux/tracepoint.h> + +DECLARE_TRACE(subsys_eventname, + TPPROTO(int firstarg, struct task_struct *p), + TPARGS(firstarg, p)); + +In subsys/file.c (where the tracing statement must be added) : + +#include <trace/subsys.h> + +DEFINE_TRACE(subsys_eventname); + +void somefct(void) +{ + ... + trace_subsys_eventname(arg, task); + ... +} + +Where : +- subsys_eventname is an identifier unique to your event + - subsys is the name of your subsystem. + - eventname is the name of the event to trace. + +- TPPROTO(int firstarg, struct task_struct *p) is the prototype of the + function called by this tracepoint. + +- TPARGS(firstarg, p) are the parameters names, same as found in the + prototype. + +Connecting a function (probe) to a tracepoint is done by providing a +probe (function to call) for the specific tracepoint through +register_trace_subsys_eventname(). Removing a probe is done through +unregister_trace_subsys_eventname(); it will remove the probe. + +tracepoint_synchronize_unregister() must be called before the end of +the module exit function to make sure there is no caller left using +the probe. This, and the fact that preemption is disabled around the +probe call, make sure that probe removal and module unload are safe. +See the "Probe example" section below for a sample probe module. + +The tracepoint mechanism supports inserting multiple instances of the +same tracepoint, but a single definition must be made of a given +tracepoint name over all the kernel to make sure no type conflict will +occur. Name mangling of the tracepoints is done using the prototypes +to make sure typing is correct. Verification of probe type correctness +is done at the registration site by the compiler. Tracepoints can be +put in inline functions, inlined static functions, and unrolled loops +as well as regular functions. + +The naming scheme "subsys_event" is suggested here as a convention +intended to limit collisions. Tracepoint names are global to the +kernel: they are considered as being the same whether they are in the +core kernel image or in modules. + +If the tracepoint has to be used in kernel modules, an +EXPORT_TRACEPOINT_SYMBOL_GPL() or EXPORT_TRACEPOINT_SYMBOL() can be +used to export the defined tracepoints. + +* Probe / tracepoint example + +See the example provided in samples/tracepoints/src + +Compile them with your kernel. + +Run, as root : +modprobe tracepoint-example (insmod order is not important) +modprobe tracepoint-probe-example +cat /proc/tracepoint-example (returns an expected error) +rmmod tracepoint-example tracepoint-probe-example +dmesg diff --git a/Documentation/tracers/mmiotrace.txt b/Documentation/tracers/mmiotrace.txt index a4afb560a45..cde23b4a12a 100644 --- a/Documentation/tracers/mmiotrace.txt +++ b/Documentation/tracers/mmiotrace.txt @@ -36,8 +36,8 @@ $ mount -t debugfs debugfs /debug $ echo mmiotrace > /debug/tracing/current_tracer $ cat /debug/tracing/trace_pipe > mydump.txt & Start X or whatever. -$ echo "X is up" > /debug/tracing/marker -$ echo none > /debug/tracing/current_tracer +$ echo "X is up" > /debug/tracing/trace_marker +$ echo nop > /debug/tracing/current_tracer Check for lost events. @@ -59,15 +59,14 @@ The 'cat' process should stay running (sleeping) in the background. Load the driver you want to trace and use it. Mmiotrace will only catch MMIO accesses to areas that are ioremapped while mmiotrace is active. -[Unimplemented feature:] During tracing you can place comments (markers) into the trace by -$ echo "X is up" > /debug/tracing/marker +$ echo "X is up" > /debug/tracing/trace_marker This makes it easier to see which part of the (huge) trace corresponds to which action. It is recommended to place descriptive markers about what you do. Shut down mmiotrace (requires root privileges): -$ echo none > /debug/tracing/current_tracer +$ echo nop > /debug/tracing/current_tracer The 'cat' process exits. If it does not, kill it by issuing 'fg' command and pressing ctrl+c. @@ -82,7 +81,9 @@ are: $ cat /debug/tracing/trace_entries gives you a number. Approximately double this number and write it back, for instance: +$ echo 0 > /debug/tracing/tracing_enabled $ echo 128000 > /debug/tracing/trace_entries +$ echo 1 > /debug/tracing/tracing_enabled Then start again from the top. If you are doing a trace for a driver project, e.g. Nouveau, you should also diff --git a/Documentation/usb/WUSB-Design-overview.txt b/Documentation/usb/WUSB-Design-overview.txt new file mode 100644 index 00000000000..4c3d62c7843 --- /dev/null +++ b/Documentation/usb/WUSB-Design-overview.txt @@ -0,0 +1,448 @@ + +Linux UWB + Wireless USB + WiNET + + (C) 2005-2006 Intel Corporation + Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com> + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License version + 2 as published by the Free Software Foundation. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA. + + +Please visit http://bughost.org/thewiki/Design-overview.txt-1.8 for +updated content. + + * Design-overview.txt-1.8 + +This code implements a Ultra Wide Band stack for Linux, as well as +drivers for the the USB based UWB radio controllers defined in the +Wireless USB 1.0 specification (including Wireless USB host controller +and an Intel WiNET controller). + + 1. Introduction + 1. HWA: Host Wire adapters, your Wireless USB dongle + + 2. DWA: Device Wired Adaptor, a Wireless USB hub for wired + devices + 3. WHCI: Wireless Host Controller Interface, the PCI WUSB host + adapter + 2. The UWB stack + 1. Devices and hosts: the basic structure + + 2. Host Controller life cycle + + 3. On the air: beacons and enumerating the radio neighborhood + + 4. Device lists + 5. Bandwidth allocation + + 3. Wireless USB Host Controller drivers + + 4. Glossary + + + Introduction + +UWB is a wide-band communication protocol that is to serve also as the +low-level protocol for others (much like TCP sits on IP). Currently +these others are Wireless USB and TCP/IP, but seems Bluetooth and +Firewire/1394 are coming along. + +UWB uses a band from roughly 3 to 10 GHz, transmitting at a max of +~-41dB (or 0.074 uW/MHz--geography specific data is still being +negotiated w/ regulators, so watch for changes). That band is divided in +a bunch of ~1.5 GHz wide channels (or band groups) composed of three +subbands/subchannels (528 MHz each). Each channel is independent of each +other, so you could consider them different "busses". Initially this +driver considers them all a single one. + +Radio time is divided in 65536 us long /superframes/, each one divided +in 256 256us long /MASs/ (Media Allocation Slots), which are the basic +time/media allocation units for transferring data. At the beginning of +each superframe there is a Beacon Period (BP), where every device +transmit its beacon on a single MAS. The length of the BP depends on how +many devices are present and the length of their beacons. + +Devices have a MAC (fixed, 48 bit address) and a device (changeable, 16 +bit address) and send periodic beacons to advertise themselves and pass +info on what they are and do. They advertise their capabilities and a +bunch of other stuff. + +The different logical parts of this driver are: + + * + + *UWB*: the Ultra-Wide-Band stack -- manages the radio and + associated spectrum to allow for devices sharing it. Allows to + control bandwidth assingment, beaconing, scanning, etc + + * + + *WUSB*: the layer that sits on top of UWB to provide Wireless USB. + The Wireless USB spec defines means to control a UWB radio and to + do the actual WUSB. + + + HWA: Host Wire adapters, your Wireless USB dongle + +WUSB also defines a device called a Host Wire Adaptor (HWA), which in +mere terms is a USB dongle that enables your PC to have UWB and Wireless +USB. The Wireless USB Host Controller in a HWA looks to the host like a +[Wireless] USB controller connected via USB (!) + +The HWA itself is broken in two or three main interfaces: + + * + + *RC*: Radio control -- this implements an interface to the + Ultra-Wide-Band radio controller. The driver for this implements a + USB-based UWB Radio Controller to the UWB stack. + + * + + *HC*: the wireless USB host controller. It looks like a USB host + whose root port is the radio and the WUSB devices connect to it. + To the system it looks like a separate USB host. The driver (will) + implement a USB host controller (similar to UHCI, OHCI or EHCI) + for which the root hub is the radio...To reiterate: it is a USB + controller that is connected via USB instead of PCI. + + * + + *WINET*: some HW provide a WiNET interface (IP over UWB). This + package provides a driver for it (it looks like a network + interface, winetX). The driver detects when there is a link up for + their type and kick into gear. + + + DWA: Device Wired Adaptor, a Wireless USB hub for wired devices + +These are the complement to HWAs. They are a USB host for connecting +wired devices, but it is connected to your PC connected via Wireless +USB. To the system it looks like yet another USB host. To the untrained +eye, it looks like a hub that connects upstream wirelessly. + +We still offer no support for this; however, it should share a lot of +code with the HWA-RC driver; there is a bunch of factorization work that +has been done to support that in upcoming releases. + + + WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter + +This is your usual PCI device that implements WHCI. Similar in concept +to EHCI, it allows your wireless USB devices (including DWAs) to connect +to your host via a PCI interface. As in the case of the HWA, it has a +Radio Control interface and the WUSB Host Controller interface per se. + +There is still no driver support for this, but will be in upcoming +releases. + + + The UWB stack + +The main mission of the UWB stack is to keep a tally of which devices +are in radio proximity to allow drivers to connect to them. As well, it +provides an API for controlling the local radio controllers (RCs from +now on), such as to start/stop beaconing, scan, allocate bandwidth, etc. + + + Devices and hosts: the basic structure + +The main building block here is the UWB device (struct uwb_dev). For +each device that pops up in radio presence (ie: the UWB host receives a +beacon from it) you get a struct uwb_dev that will show up in +/sys/class/uwb and in /sys/bus/uwb/devices. + +For each RC that is detected, a new struct uwb_rc is created. In turn, a +RC is also a device, so they also show in /sys/class/uwb and +/sys/bus/uwb/devices, but at the same time, only radio controllers show +up in /sys/class/uwb_rc. + + * + + [*] The reason for RCs being also devices is that not only we can + see them while enumerating the system device tree, but also on the + radio (their beacons and stuff), so the handling has to be + likewise to that of a device. + +Each RC driver is implemented by a separate driver that plugs into the +interface that the UWB stack provides through a struct uwb_rc_ops. The +spec creators have been nice enough to make the message format the same +for HWA and WHCI RCs, so the driver is really a very thin transport that +moves the requests from the UWB API to the device [/uwb_rc_ops->cmd()/] +and sends the replies and notifications back to the API +[/uwb_rc_neh_grok()/]. Notifications are handled to the UWB daemon, that +is chartered, among other things, to keep the tab of how the UWB radio +neighborhood looks, creating and destroying devices as they show up or +dissapear. + +Command execution is very simple: a command block is sent and a event +block or reply is expected back. For sending/receiving command/events, a +handle called /neh/ (Notification/Event Handle) is opened with +/uwb_rc_neh_open()/. + +The HWA-RC (USB dongle) driver (drivers/uwb/hwa-rc.c) does this job for +the USB connected HWA. Eventually, drivers/whci-rc.c will do the same +for the PCI connected WHCI controller. + + + Host Controller life cycle + +So let's say we connect a dongle to the system: it is detected and +firmware uploaded if needed [for Intel's i1480 +/drivers/uwb/ptc/usb.c:ptc_usb_probe()/] and then it is reenumerated. +Now we have a real HWA device connected and +/drivers/uwb/hwa-rc.c:hwarc_probe()/ picks it up, that will set up the +Wire-Adaptor environment and then suck it into the UWB stack's vision of +the world [/drivers/uwb/lc-rc.c:uwb_rc_add()/]. + + * + + [*] The stack should put a new RC to scan for devices + [/uwb_rc_scan()/] so it finds what's available around and tries to + connect to them, but this is policy stuff and should be driven + from user space. As of now, the operator is expected to do it + manually; see the release notes for documentation on the procedure. + +When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/ +takes time of tearing everything down safely (or not...). + + + On the air: beacons and enumerating the radio neighborhood + +So assuming we have devices and we have agreed for a channel to connect +on (let's say 9), we put the new RC to beacon: + + * + + $ echo 9 0 > /sys/class/uwb_rc/uwb0/beacon + +Now it is visible. If there were other devices in the same radio channel +and beacon group (that's what the zero is for), the dongle's radio +control interface will send beacon notifications on its +notification/event endpoint (NEEP). The beacon notifications are part of +the event stream that is funneled into the API with +/drivers/uwb/neh.c:uwb_rc_neh_grok()/ and delivered to the UWBD, the UWB +daemon through a notification list. + +UWBD wakes up and scans the event list; finds a beacon and adds it to +the BEACON CACHE (/uwb_beca/). If he receives a number of beacons from +the same device, he considers it to be 'onair' and creates a new device +[/drivers/uwb/lc-dev.c:uwbd_dev_onair()/]. Similarly, when no beacons +are received in some time, the device is considered gone and wiped out +[uwbd calls periodically /uwb/beacon.c:uwb_beca_purge()/ that will purge +the beacon cache of dead devices]. + + + Device lists + +All UWB devices are kept in the list of the struct bus_type uwb_bus. + + + Bandwidth allocation + +The UWB stack maintains a local copy of DRP availability through +processing of incoming *DRP Availability Change* notifications. This +local copy is currently used to present the current bandwidth +availability to the user through the sysfs file +/sys/class/uwb_rc/uwbx/bw_avail. In the future the bandwidth +availability information will be used by the bandwidth reservation +routines. + +The bandwidth reservation routines are in progress and are thus not +present in the current release. When completed they will enable a user +to initiate DRP reservation requests through interaction with sysfs. DRP +reservation requests from remote UWB devices will also be handled. The +bandwidth management done by the UWB stack will include callbacks to the +higher layers will enable the higher layers to use the reservations upon +completion. [Note: The bandwidth reservation work is in progress and +subject to change.] + + + Wireless USB Host Controller drivers + +*WARNING* This section needs a lot of work! + +As explained above, there are three different types of HCs in the WUSB +world: HWA-HC, DWA-HC and WHCI-HC. + +HWA-HC and DWA-HC share that they are Wire-Adapters (USB or WUSB +connected controllers), and their transfer management system is almost +identical. So is their notification delivery system. + +HWA-HC and WHCI-HC share that they are both WUSB host controllers, so +they have to deal with WUSB device life cycle and maintenance, wireless +root-hub + +HWA exposes a Host Controller interface (HWA-HC 0xe0/02/02). This has +three endpoints (Notifications, Data Transfer In and Data Transfer +Out--known as NEP, DTI and DTO in the code). + +We reserve UWB bandwidth for our Wireless USB Cluster, create a Cluster +ID and tell the HC to use all that. Then we start it. This means the HC +starts sending MMCs. + + * + + The MMCs are blocks of data defined somewhere in the WUSB1.0 spec + that define a stream in the UWB channel time allocated for sending + WUSB IEs (host to device commands/notifications) and Device + Notifications (device initiated to host). Each host defines a + unique Wireless USB cluster through MMCs. Devices can connect to a + single cluster at the time. The IEs are Information Elements, and + among them are the bandwidth allocations that tell each device + when can they transmit or receive. + +Now it all depends on external stimuli. + +*New device connection* + +A new device pops up, it scans the radio looking for MMCs that give out +the existence of Wireless USB channels. Once one (or more) are found, +selects which one to connect to. Sends a /DN_Connect/ (device +notification connect) during the DNTS (Device Notification Time +Slot--announced in the MMCs + +HC picks the /DN_Connect/ out (nep module sends to notif.c for delivery +into /devconnect/). This process starts the authentication process for +the device. First we allocate a /fake port/ and assign an +unauthenticated address (128 to 255--what we really do is +0x80 | fake_port_idx). We fiddle with the fake port status and /khubd/ +sees a new connection, so he moves on to enable the fake port with a reset. + +So now we are in the reset path -- we know we have a non-yet enumerated +device with an unauthorized address; we ask user space to authenticate +(FIXME: not yet done, similar to bluetooth pairing), then we do the key +exchange (FIXME: not yet done) and issue a /set address 0/ to bring the +device to the default state. Device is authenticated. + +From here, the USB stack takes control through the usb_hcd ops. khubd +has seen the port status changes, as we have been toggling them. It will +start enumerating and doing transfers through usb_hcd->urb_enqueue() to +read descriptors and move our data. + +*Device life cycle and keep alives* + +Everytime there is a succesful transfer to/from a device, we update a +per-device activity timestamp. If not, every now and then we check and +if the activity timestamp gets old, we ping the device by sending it a +Keep Alive IE; it responds with a /DN_Alive/ pong during the DNTS (this +arrives to us as a notification through +devconnect.c:wusb_handle_dn_alive(). If a device times out, we +disconnect it from the system (cleaning up internal information and +toggling the bits in the fake hub port, which kicks khubd into removing +the rest of the stuff). + +This is done through devconnect:__wusb_check_devs(), which will scan the +device list looking for whom needs refreshing. + +If the device wants to disconnect, it will either die (ugly) or send a +/DN_Disconnect/ that will prompt a disconnection from the system. + +*Sending and receiving data* + +Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is +/aimed/ at an endpoint in a WUSB device. This is the same for HWAs and +DWAs. + +Each HC has a number of rpipes and buffers that can be assigned to them; +when doing a data transfer (xfer), first the rpipe has to be aimed and +prepared (buffers assigned), then we can start queueing requests for +data in or out. + +Data buffers have to be segmented out before sending--so we send first a +header (segment request) and then if there is any data, a data buffer +immediately after to the DTI interface (yep, even the request). If our +buffer is bigger than the max segment size, then we just do multiple +requests. + +[This sucks, because doing USB scatter gatter in Linux is resource +intensive, if any...not that the current approach is not. It just has to +be cleaned up a lot :)]. + +If reading, we don't send data buffers, just the segment headers saying +we want to read segments. + +When the xfer is executed, we receive a notification that says data is +ready in the DTI endpoint (handled through +xfer.c:wa_handle_notif_xfer()). In there we read from the DTI endpoint a +descriptor that gives us the status of the transfer, its identification +(given when we issued it) and the segment number. If it was a data read, +we issue another URB to read into the destination buffer the chunk of +data coming out of the remote endpoint. Done, wait for the next guy. The +callbacks for the URBs issued from here are the ones that will declare +the xfer complete at some point and call it's callback. + +Seems simple, but the implementation is not trivial. + + * + + *WARNING* Old!! + +The main xfer descriptor, wa_xfer (equivalent to a URB) contains an +array of segments, tallys on segments and buffers and callback +information. Buried in there is a lot of URBs for executing the segments +and buffer transfers. + +For OUT xfers, there is an array of segments, one URB for each, another +one of buffer URB. When submitting, we submit URBs for segment request +1, buffer 1, segment 2, buffer 2...etc. Then we wait on the DTI for xfer +result data; when all the segments are complete, we call the callback to +finalize the transfer. + +For IN xfers, we only issue URBs for the segments we want to read and +then wait for the xfer result data. + +*URB mapping into xfers* + +This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an +rpipe to the endpoint where we have to transmit, create a transfer +context (wa_xfer) and submit it. When the xfer is done, our callback is +called and we assign the status bits and release the xfer resources. + +In dequeue() we are basically cancelling/aborting the transfer. We issue +a xfer abort request to the HC, cancell all the URBs we had submitted +and not yet done and when all that is done, the xfer callback will be +called--this will call the URB callback. + + + Glossary + +*DWA* -- Device Wire Adapter + +USB host, wired for downstream devices, upstream connects wirelessly +with Wireless USB. + +*EVENT* -- Response to a command on the NEEP + +*HWA* -- Host Wire Adapter / USB dongle for UWB and Wireless USB + +*NEH* -- Notification/Event Handle + +Handle/file descriptor for receiving notifications or events. The WA +code requires you to get one of this to listen for notifications or +events on the NEEP. + +*NEEP* -- Notification/Event EndPoint + +Stuff related to the management of the first endpoint of a HWA USB +dongle that is used to deliver an stream of events and notifications to +the host. + +*NOTIFICATION* -- Message coming in the NEEP as response to something. + +*RC* -- Radio Control + +Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by +InakyPerezGonzalez) + diff --git a/Documentation/usb/anchors.txt b/Documentation/usb/anchors.txt index 5e6b64c20d2..6f24f566955 100644 --- a/Documentation/usb/anchors.txt +++ b/Documentation/usb/anchors.txt @@ -52,6 +52,11 @@ Therefore no guarantee is made that the URBs have been unlinked when the call returns. They may be unlinked later but will be unlinked in finite time. +usb_scuttle_anchored_urbs() +--------------------------- + +All URBs of an anchor are unanchored en masse. + usb_wait_anchor_empty_timeout() ------------------------------- @@ -59,4 +64,16 @@ 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. +usb_anchor_empty() +------------------ + +Returns true if no URBs are associated with an anchor. Locking +is the caller's responsibility. + +usb_get_from_anchor() +--------------------- +Returns the oldest anchored URB of an anchor. The URB is unanchored +and returned with a reference. As you may mix URBs to several +destinations in one anchor you have no guarantee the chronologically +first submitted URB is returned.
\ No newline at end of file diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt index 9b22bd14c34..eac7df94d8e 100644 --- a/Documentation/usb/gadget_serial.txt +++ b/Documentation/usb/gadget_serial.txt @@ -114,11 +114,11 @@ modules. Then you must load the gadget serial driver. To load it as an ACM device (recommended for interoperability), do this: - modprobe g_serial use_acm=1 + modprobe g_serial To load it as a vendor specific bulk in/out device, do this: - modprobe g_serial + modprobe g_serial use_acm=0 This will also automatically load the underlying gadget peripheral controller driver. This must be done each time you reboot the gadget diff --git a/Documentation/usb/misc_usbsevseg.txt b/Documentation/usb/misc_usbsevseg.txt new file mode 100644 index 00000000000..0f6be4f9930 --- /dev/null +++ b/Documentation/usb/misc_usbsevseg.txt @@ -0,0 +1,46 @@ +USB 7-Segment Numeric Display +Manufactured by Delcom Engineering + +Device Information +------------------ +USB VENDOR_ID 0x0fc5 +USB PRODUCT_ID 0x1227 +Both the 6 character and 8 character displays have PRODUCT_ID, +and according to Delcom Engineering no queryable information +can be obtained from the device to tell them apart. + +Device Modes +------------ +By default, the driver assumes the display is only 6 characters +The mode for 6 characters is: + MSB 0x06; LSB 0x3f +For the 8 character display: + MSB 0x08; LSB 0xff +The device can accept "text" either in raw, hex, or ascii textmode. +raw controls each segment manually, +hex expects a value between 0-15 per character, +ascii expects a value between '0'-'9' and 'A'-'F'. +The default is ascii. + +Device Operation +---------------- +1. Turn on the device: + echo 1 > /sys/bus/usb/.../powered +2. Set the device's mode: + echo $mode_msb > /sys/bus/usb/.../mode_msb + echo $mode_lsb > /sys/bus/usb/.../mode_lsb +3. Set the textmode: + echo $textmode > /sys/bus/usb/.../textmode +4. set the text (for example): + echo "123ABC" > /sys/bus/usb/.../text (ascii) + echo "A1B2" > /sys/bus/usb/.../text (ascii) + echo -ne "\x01\x02\x03" > /sys/bus/usb/.../text (hex) +5. Set the decimal places. + The device has either 6 or 8 decimal points. + to set the nth decimal place calculate 10 ** n + and echo it in to /sys/bus/usb/.../decimals + To set multiple decimals points sum up each power. + For example, to set the 0th and 3rd decimal place + echo 1001 > /sys/bus/usb/.../decimals + + diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt index 9d31140e3f5..e48ea1d5101 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -350,12 +350,12 @@ without holding the mutex. There also are a couple of utility routines drivers can use: - usb_autopm_enable() sets pm_usage_cnt to 1 and then calls - usb_autopm_set_interface(), which will attempt an autoresume. - - usb_autopm_disable() sets pm_usage_cnt to 0 and then calls + usb_autopm_enable() sets pm_usage_cnt to 0 and then calls usb_autopm_set_interface(), which will attempt an autosuspend. + usb_autopm_disable() sets pm_usage_cnt to 1 and then calls + usb_autopm_set_interface(), which will attempt an autoresume. + The conventional usage pattern is that a driver calls usb_autopm_get_interface() in its open routine and usb_autopm_put_interface() in its close or release routine. But diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt index 077e9032d0c..fafcd472326 100644 --- a/Documentation/usb/proc_usb_info.txt +++ b/Documentation/usb/proc_usb_info.txt @@ -49,8 +49,10 @@ it and 002/048 sometime later. These files can be read as binary data. The binary data consists of first the device descriptor, then the descriptors for each -configuration of the device. That information is also shown in -text form by the /proc/bus/usb/devices file, described later. +configuration of the device. Multi-byte fields in the device and +configuration descriptors, but not other descriptors, are converted +to host endianness by the kernel. This information is also shown +in text form by the /proc/bus/usb/devices file, described later. These files may also be used to write user-level drivers for the USB devices. You would open the /proc/bus/usb/BBB/DDD file read/write, diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index 2917ce4ffdc..270481906dc 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -34,11 +34,12 @@ if usbmon is built into the kernel. Verify that bus sockets are present. # ls /sys/kernel/debug/usbmon -0s 0t 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u +0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u # -Now you can choose to either use the sockets numbered '0' (to capture packets on -all buses), and skip to step #3, or find the bus used by your device with step #2. +Now you can choose to either use the socket '0u' (to capture packets on all +buses), and skip to step #3, or find the bus used by your device with step #2. +This allows to filter away annoying devices that talk continuously. 2. Find which bus connects to the desired device @@ -99,8 +100,9 @@ on the event type, but there is a set of words, common for all types. Here is the list of words, from left to right: -- URB Tag. This is used to identify URBs is normally a kernel mode address - of the URB structure in hexadecimal. +- URB Tag. This is used to identify URBs, and is normally an in-kernel address + of the URB structure in hexadecimal, but can be a sequence number or any + other unique string, within reason. - Timestamp in microseconds, a decimal number. The timestamp's resolution depends on available clock, and so it can be much worse than a microsecond diff --git a/Documentation/usb/wusb-cbaf b/Documentation/usb/wusb-cbaf new file mode 100644 index 00000000000..2e78b70f3ad --- /dev/null +++ b/Documentation/usb/wusb-cbaf @@ -0,0 +1,139 @@ +#! /bin/bash +# + +set -e + +progname=$(basename $0) +function help +{ + cat <<EOF +Usage: $progname COMMAND DEVICEs [ARGS] + +Command for manipulating the pairing/authentication credentials of a +Wireless USB device that supports wired-mode Cable-Based-Association. + +Works in conjunction with the wusb-cba.ko driver from http://linuxuwb.org. + + +DEVICE + + sysfs path to the device to authenticate; for example, both this + guys are the same: + + /sys/devices/pci0000:00/0000:00:1d.7/usb1/1-4/1-4.4/1-4.4:1.1 + /sys/bus/usb/drivers/wusb-cbaf/1-4.4:1.1 + +COMMAND/ARGS are + + start + + Start a WUSB host controller (by setting up a CHID) + + set-chid DEVICE HOST-CHID HOST-BANDGROUP HOST-NAME + + Sets host information in the device; after this you can call the + get-cdid to see how does this device report itself to us. + + get-cdid DEVICE + + Get the device ID associated to the HOST-CHDI we sent with + 'set-chid'. We might not know about it. + + set-cc DEVICE + + If we allow the device to connect, set a random new CDID and CK + (connection key). Device saves them for the next time it wants to + connect wireless. We save them for that next time also so we can + authenticate the device (when we see the CDID he uses to id + itself) and the CK to crypto talk to it. + +CHID is always 16 hex bytes in 'XX YY ZZ...' form +BANDGROUP is almost always 0001 + +Examples: + + You can default most arguments to '' to get a sane value: + + $ $progname set-chid '' '' '' "My host name" + + A full sequence: + + $ $progname set-chid '' '' '' "My host name" + $ $progname get-cdid '' + $ $progname set-cc '' + +EOF +} + + +# Defaults +# FIXME: CHID should come from a database :), band group from the host +host_CHID="00 11 22 33 44 55 66 77 88 99 aa bb cc dd ee ff" +host_band_group="0001" +host_name=$(hostname) + +devs="$(echo /sys/bus/usb/drivers/wusb-cbaf/[0-9]*)" +hdevs="$(for h in /sys/class/uwb_rc/*/wusbhc; do readlink -f $h; done)" + +result=0 +case $1 in + start) + for dev in ${2:-$hdevs} + do + uwb_rc=$(readlink -f $dev/uwb_rc) + if cat $uwb_rc/beacon | grep -q -- "-1" + then + echo 13 0 > $uwb_rc/beacon + echo I: started beaconing on ch 13 on $(basename $uwb_rc) >&2 + fi + echo $host_CHID > $dev/wusb_chid + echo I: started host $(basename $dev) >&2 + done + ;; + stop) + for dev in ${2:-$hdevs} + do + echo 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 > $dev/wusb_chid + echo I: stopped host $(basename $dev) >&2 + uwb_rc=$(readlink -f $dev/uwb_rc) + echo -1 | cat > $uwb_rc/beacon + echo I: stopped beaconing on $(basename $uwb_rc) >&2 + done + ;; + set-chid) + shift + for dev in ${2:-$devs}; do + echo "${4:-$host_name}" > $dev/wusb_host_name + echo "${3:-$host_band_group}" > $dev/wusb_host_band_groups + echo ${2:-$host_CHID} > $dev/wusb_chid + done + ;; + get-cdid) + for dev in ${2:-$devs} + do + cat $dev/wusb_cdid + done + ;; + set-cc) + for dev in ${2:-$devs}; do + shift + CDID="$(head --bytes=16 /dev/urandom | od -tx1 -An)" + CK="$(head --bytes=16 /dev/urandom | od -tx1 -An)" + echo "$CDID" > $dev/wusb_cdid + echo "$CK" > $dev/wusb_ck + + echo I: CC set >&2 + echo "CHID: $(cat $dev/wusb_chid)" + echo "CDID:$CDID" + echo "CK: $CK" + done + ;; + help|h|--help|-h) + help + ;; + *) + echo "E: Unknown usage" 1>&2 + help 1>&2 + result=1 +esac +exit $result diff --git a/Documentation/video4linux/.gitignore b/Documentation/video4linux/.gitignore new file mode 100644 index 00000000000..952703943e8 --- /dev/null +++ b/Documentation/video4linux/.gitignore @@ -0,0 +1 @@ +v4lgrab diff --git a/Documentation/video4linux/API.html b/Documentation/video4linux/API.html index afbe9ae7ee9..d749d41f647 100644 --- a/Documentation/video4linux/API.html +++ b/Documentation/video4linux/API.html @@ -1,16 +1,27 @@ -<TITLE>V4L API</TITLE> -<H1>Video For Linux APIs</H1> -<table border=0> -<tr> -<td> -<A HREF=http://www.linuxtv.org/downloads/video4linux/API/V4L1_API.html> -V4L original API</a> -</td><td> -Obsoleted by V4L2 API -</td></tr><tr><td> -<A HREF=http://www.linuxtv.org/downloads/video4linux/API/V4L2_API> -V4L2 API</a> -</td><td> -Should be used for new projects -</td></tr> -</table> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> + <head> + <meta content="text/html;charset=ISO-8859-2" http-equiv="Content-Type" /> + <title>V4L API</title> + </head> + <body> + <h1>Video For Linux APIs</h1> + <table border="0"> + <tr> + <td> + <a href="http://www.linuxtv.org/downloads/video4linux/API/V4L1_API.html">V4L original API</a> + </td> + <td> + Obsoleted by V4L2 API + </td> + </tr> + <tr> + <td> + <a href="http://www.linuxtv.org/downloads/video4linux/API/V4L2_API">V4L2 API</a> + </td> + <td>Should be used for new projects + </td> + </tr> + </table> + </body> +</html> diff --git a/Documentation/video4linux/CARDLIST.au0828 b/Documentation/video4linux/CARDLIST.au0828 index aa05e5bb22f..d5cb4ea287b 100644 --- a/Documentation/video4linux/CARDLIST.au0828 +++ b/Documentation/video4linux/CARDLIST.au0828 @@ -1,5 +1,5 @@ 0 -> Unknown board (au0828) - 1 -> Hauppauge HVR950Q (au0828) [2040:7200,2040:7210,2040:7217,2040:721b,2040:721f,2040:7280,0fd9:0008] + 1 -> Hauppauge HVR950Q (au0828) [2040:7200,2040:7210,2040:7217,2040:721b,2040:721e,2040:721f,2040:7280,0fd9:0008] 2 -> Hauppauge HVR850 (au0828) [2040:7240] 3 -> DViCO FusionHDTV USB (au0828) [0fe9:d620] 4 -> Hauppauge HVR950Q rev xxF8 (au0828) [2040:7201,2040:7211,2040:7281] diff --git a/Documentation/video4linux/CARDLIST.bttv b/Documentation/video4linux/CARDLIST.bttv index 60ba6683603..0d93fa1ac25 100644 --- a/Documentation/video4linux/CARDLIST.bttv +++ b/Documentation/video4linux/CARDLIST.bttv @@ -104,8 +104,8 @@ 103 -> Grand X-Guard / Trust 814PCI [0304:0102] 104 -> Nebula Electronics DigiTV [0071:0101] 105 -> ProVideo PV143 [aa00:1430,aa00:1431,aa00:1432,aa00:1433,aa03:1433] -106 -> PHYTEC VD-009-X1 MiniDIN (bt878) -107 -> PHYTEC VD-009-X1 Combi (bt878) +106 -> PHYTEC VD-009-X1 VD-011 MiniDIN (bt878) +107 -> PHYTEC VD-009-X1 VD-011 Combi (bt878) 108 -> PHYTEC VD-009 MiniDIN (bt878) 109 -> PHYTEC VD-009 Combi (bt878) 110 -> IVC-100 [ff00:a132] @@ -151,3 +151,6 @@ 150 -> Geovision GV-600 [008a:763c] 151 -> Kozumi KTV-01C 152 -> Encore ENL TV-FM-2 [1000:1801] +153 -> PHYTEC VD-012 (bt878) +154 -> PHYTEC VD-012-X1 (bt878) +155 -> PHYTEC VD-012-X2 (bt878) diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885 index 64823ccacd6..35ea130e989 100644 --- a/Documentation/video4linux/CARDLIST.cx23885 +++ b/Documentation/video4linux/CARDLIST.cx23885 @@ -11,3 +11,4 @@ 10 -> DViCO FusionHDTV7 Dual Express [18ac:d618] 11 -> DViCO FusionHDTV DVB-T Dual Express [18ac:db78] 12 -> Leadtek Winfast PxDVR3200 H [107d:6681] + 13 -> Compro VideoMate E650F [185b:e800] diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88 index a5227e308f4..0d08f1edcf6 100644 --- a/Documentation/video4linux/CARDLIST.cx88 +++ b/Documentation/video4linux/CARDLIST.cx88 @@ -2,7 +2,7 @@ 1 -> Hauppauge WinTV 34xxx models [0070:3400,0070:3401] 2 -> GDI Black Gold [14c7:0106,14c7:0107] 3 -> PixelView [1554:4811] - 4 -> ATI TV Wonder Pro [1002:00f8] + 4 -> ATI TV Wonder Pro [1002:00f8,1002:00f9] 5 -> Leadtek Winfast 2000XP Expert [107d:6611,107d:6613] 6 -> AverTV Studio 303 (M126) [1461:000b] 7 -> MSI TV-@nywhere Master [1462:8606] @@ -74,3 +74,6 @@ 73 -> TeVii S420 DVB-S [d420:9022] 74 -> Prolink Pixelview Global Extreme [1554:4976] 75 -> PROF 7300 DVB-S/S2 [B033:3033] + 76 -> SATTRADE ST4200 DVB-S/S2 [b200:4200] + 77 -> TBS 8910 DVB-S [8910:8888] + 78 -> Prof 6200 DVB-S [b022:3022] diff --git a/Documentation/video4linux/CARDLIST.em28xx b/Documentation/video4linux/CARDLIST.em28xx index 187cc48d092..75bded8a4aa 100644 --- a/Documentation/video4linux/CARDLIST.em28xx +++ b/Documentation/video4linux/CARDLIST.em28xx @@ -1,5 +1,5 @@ 0 -> Unknown EM2800 video grabber (em2800) [eb1a:2800] - 1 -> Unknown EM2750/28xx video grabber (em2820/em2840) [eb1a:2820,eb1a:2860,eb1a:2861,eb1a:2870,eb1a:2881,eb1a:2883] + 1 -> Unknown EM2750/28xx video grabber (em2820/em2840) [eb1a:2820,eb1a:2821,eb1a:2860,eb1a:2861,eb1a:2870,eb1a:2881,eb1a:2883] 2 -> Terratec Cinergy 250 USB (em2820/em2840) [0ccd:0036] 3 -> Pinnacle PCTV USB 2 (em2820/em2840) [2304:0208] 4 -> Hauppauge WinTV USB 2 (em2820/em2840) [2040:4200,2040:4201] @@ -12,9 +12,9 @@ 11 -> Terratec Hybrid XS (em2880) [0ccd:0042] 12 -> Kworld PVR TV 2800 RF (em2820/em2840) 13 -> Terratec Prodigy XS (em2880) [0ccd:0047] - 14 -> Pixelview Prolink PlayTV USB 2.0 (em2820/em2840) [eb1a:2821] + 14 -> Pixelview Prolink PlayTV USB 2.0 (em2820/em2840) 15 -> V-Gear PocketTV (em2800) - 16 -> Hauppauge WinTV HVR 950 (em2883) [2040:6513,2040:6517,2040:651b,2040:651f] + 16 -> Hauppauge WinTV HVR 950 (em2883) [2040:6513,2040:6517,2040:651b] 17 -> Pinnacle PCTV HD Pro Stick (em2880) [2304:0227] 18 -> Hauppauge WinTV HVR 900 (R2) (em2880) [2040:6502] 19 -> PointNix Intra-Oral Camera (em2860) @@ -27,7 +27,6 @@ 26 -> Hercules Smart TV USB 2.0 (em2820/em2840) 27 -> Pinnacle PCTV USB 2 (Philips FM1216ME) (em2820/em2840) 28 -> Leadtek Winfast USB II Deluxe (em2820/em2840) - 29 -> Pinnacle Dazzle DVC 100 (em2820/em2840) 30 -> Videology 20K14XUSB USB2.0 (em2820/em2840) 31 -> Usbgear VD204v9 (em2821) 32 -> Supercomp USB 2.0 TV (em2821) @@ -57,3 +56,5 @@ 56 -> Pinnacle Hybrid Pro (2) (em2882) [2304:0226] 57 -> Kworld PlusTV HD Hybrid 330 (em2883) [eb1a:a316] 58 -> Compro VideoMate ForYou/Stereo (em2820/em2840) [185b:2041] + 60 -> Hauppauge WinTV HVR 850 (em2883) [2040:651f] + 61 -> Pixelview PlayTV Box 4 USB 2.0 (em2820/em2840) diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index dc67eef38ff..335aef4dcae 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -10,7 +10,7 @@ 9 -> Medion 5044 10 -> Kworld/KuroutoShikou SAA7130-TVPCI 11 -> Terratec Cinergy 600 TV [153b:1143] - 12 -> Medion 7134 [16be:0003] + 12 -> Medion 7134 [16be:0003,16be:5000] 13 -> Typhoon TV+Radio 90031 14 -> ELSA EX-VISION 300TV [1048:226b] 15 -> ELSA EX-VISION 500TV [1048:226a] @@ -151,3 +151,4 @@ 150 -> Zogis Real Angel 220 151 -> ADS Tech Instant HDTV [1421:0380] 152 -> Asus Tiger Rev:1.00 [1043:4857] +153 -> Kworld Plus TV Analog Lite PCI [17de:7128] diff --git a/Documentation/video4linux/CARDLIST.tuner b/Documentation/video4linux/CARDLIST.tuner index 30bbdda68d0..691d2f37dc5 100644 --- a/Documentation/video4linux/CARDLIST.tuner +++ b/Documentation/video4linux/CARDLIST.tuner @@ -75,3 +75,4 @@ tuner=73 - Samsung TCPG 6121P30A tuner=75 - Philips TEA5761 FM Radio tuner=76 - Xceive 5000 tuner tuner=77 - TCL tuner MF02GIP-5N-E +tuner=78 - Philips FMD1216MEX MK3 Hybrid Tuner diff --git a/Documentation/video4linux/README.cx88 b/Documentation/video4linux/README.cx88 index 06a33a4f52f..35fae23f883 100644 --- a/Documentation/video4linux/README.cx88 +++ b/Documentation/video4linux/README.cx88 @@ -1,4 +1,3 @@ - cx8800 release notes ==================== @@ -10,25 +9,24 @@ current status video - Basically works. - - Some minor image quality glitches. - - For now only capture, overlay support isn't completed yet. + - For now, only capture and read(). Overlay isn't supported. audio - The chip specs for the on-chip TV sound decoder are next to useless :-/ - Neverless the builtin TV sound decoder starts working now, - at least for PAL-BG. Other TV norms need other code ... + at least for some standards. FOR ANY REPORTS ON THIS PLEASE MENTION THE TV NORM YOU ARE USING. - Most tuner chips do provide mono sound, which may or may not be useable depending on the board design. With the Hauppauge cards it works, so there is mono sound available as fallback. - audio data dma (i.e. recording without loopback cable to the - sound card) should be possible, but there is no code yet ... + sound card) is supported via cx88-alsa. vbi - - some code present. Doesn't crash any more, but also doesn't - work yet ... + - Code present. Works for NTSC closed caption. PAL and other + TV norms may or may not work. how to add support for new cards diff --git a/Documentation/video4linux/bttv/CONTRIBUTORS b/Documentation/video4linux/bttv/CONTRIBUTORS index 8aad6dd93d6..eb41b265086 100644 --- a/Documentation/video4linux/bttv/CONTRIBUTORS +++ b/Documentation/video4linux/bttv/CONTRIBUTORS @@ -3,7 +3,7 @@ Contributors to bttv: Michael Chu <mmchu@pobox.com> AverMedia fix and more flexible card recognition -Alan Cox <alan@redhat.com> +Alan Cox <alan@lxorguk.ukuu.org.uk> Video4Linux interface and 2.1.x kernel adaptation Chris Kleitsch diff --git a/Documentation/video4linux/gspca.txt b/Documentation/video4linux/gspca.txt index 004818fab04..1c58a763014 100644 --- a/Documentation/video4linux/gspca.txt +++ b/Documentation/video4linux/gspca.txt @@ -50,9 +50,14 @@ ov519 045e:028c Micro$oft xbox cam spca508 0461:0815 Micro Innovation IC200 sunplus 0461:0821 Fujifilm MV-1 zc3xx 0461:0a00 MicroInnovation WebCam320 +stv06xx 046d:0840 QuickCam Express +stv06xx 046d:0850 LEGO cam / QuickCam Web +stv06xx 046d:0870 Dexxa WebCam USB spca500 046d:0890 Logitech QuickCam traveler vc032x 046d:0892 Logitech Orbicam vc032x 046d:0896 Logitech Orbicam +vc032x 046d:0897 Logitech QuickCam for Dell notebooks +zc3xx 046d:089d Logitech QuickCam E2500 zc3xx 046d:08a0 Logitech QC IM zc3xx 046d:08a1 Logitech QC IM 0x08A1 +sound zc3xx 046d:08a2 Labtec Webcam Pro @@ -169,6 +174,9 @@ spca500 06bd:0404 Agfa CL20 spca500 06be:0800 Optimedia sunplus 06d6:0031 Trust 610 LCD PowerC@m Zoom spca506 06e1:a190 ADS Instant VCD +ov534 06f8:3002 Hercules Blog Webcam +ov534 06f8:3003 Hercules Dualpix HD Weblog +sonixj 06f8:3004 Hercules Classic Silver spca508 0733:0110 ViewQuest VQ110 spca508 0130:0130 Clone Digital Webcam 11043 spca501 0733:0401 Intel Create and Share @@ -199,7 +207,8 @@ sunplus 08ca:2050 Medion MD 41437 sunplus 08ca:2060 Aiptek PocketDV5300 tv8532 0923:010f ICM532 cams mars 093a:050f Mars-Semi Pc-Camera -pac207 093a:2460 PAC207 Qtec Webcam 100 +pac207 093a:2460 Qtec Webcam 100 +pac207 093a:2461 HP Webcam pac207 093a:2463 Philips SPC 220 NC pac207 093a:2464 Labtec Webcam 1200 pac207 093a:2468 PAC207 @@ -213,10 +222,13 @@ pac7311 093a:2603 PAC7312 pac7311 093a:2608 Trust WB-3300p pac7311 093a:260e Gigaware VGA PC Camera, Trust WB-3350p, SIGMA cam 2350 pac7311 093a:260f SnakeCam +pac7311 093a:2620 Apollo AC-905 pac7311 093a:2621 PAC731x +pac7311 093a:2622 Genius Eye 312 pac7311 093a:2624 PAC7302 pac7311 093a:2626 Labtec 2200 pac7311 093a:262a Webcam 300k +pac7311 093a:262c Philips SPC 230 NC zc3xx 0ac8:0302 Z-star Vimicro zc0302 vc032x 0ac8:0321 Vimicro generic vc0321 vc032x 0ac8:0323 Vimicro Vc0323 @@ -249,11 +261,13 @@ sonixj 0c45:60c0 Sangha Sn535 sonixj 0c45:60ec SN9C105+MO4000 sonixj 0c45:60fb Surfer NoName sonixj 0c45:60fc LG-LIC300 +sonixj 0c45:60fe Microdia Audio sonixj 0c45:6128 Microdia/Sonix SNP325 sonixj 0c45:612a Avant Camera sonixj 0c45:612c Typhoon Rasy Cam 1.3MPix sonixj 0c45:6130 Sonix Pccam sonixj 0c45:6138 Sn9c120 Mo4000 +sonixj 0c45:613a Microdia Sonix PC Camera sonixj 0c45:613b Surfer SN-206 sonixj 0c45:613c Sonix Pccam168 sonixj 0c45:6143 Sonix Pccam168 @@ -263,6 +277,9 @@ etoms 102c:6251 Qcam xxxxxx VGA zc3xx 10fd:0128 Typhoon Webshot II USB 300k 0x0128 spca561 10fd:7e50 FlyCam Usb 100 zc3xx 10fd:8050 Typhoon Webshot II USB 300k +ov534 1415:2000 Sony HD Eye for PS3 (SLEH 00201) +pac207 145f:013a Trust WB-1300N +vc032x 15b8:6002 HP 2.0 Megapixel rz406aa spca501 1776:501c Arowana 300K CMOS Camera t613 17a1:0128 TASCORP JPEG Webcam, NGS Cyclops vc032x 17ef:4802 Lenovo Vc0323+MI1310_SOC diff --git a/Documentation/video4linux/si470x.txt b/Documentation/video4linux/si470x.txt new file mode 100644 index 00000000000..11c5fd22a33 --- /dev/null +++ b/Documentation/video4linux/si470x.txt @@ -0,0 +1,118 @@ +Driver for USB radios for the Silicon Labs Si470x FM Radio Receivers + +Copyright (c) 2008 Tobias Lorenz <tobias.lorenz@gmx.net> + + +Information from Silicon Labs +============================= +Silicon Laboratories is the manufacturer of the radio ICs, that nowadays are the +most often used radio receivers in cell phones. Usually they are connected with +I2C. But SiLabs also provides a reference design, which integrates this IC, +together with a small microcontroller C8051F321, to form a USB radio. +Part of this reference design is also a radio application in binary and source +code. The software also contains an automatic firmware upgrade to the most +current version. Information on these can be downloaded here: +http://www.silabs.com/usbradio + + +Supported ICs +============= +The following ICs have a very similar register set, so that they are or will be +supported somewhen by the driver: +- Si4700: FM radio receiver +- Si4701: FM radio receiver, RDS Support +- Si4702: FM radio receiver +- Si4703: FM radio receiver, RDS Support +- Si4704: FM radio receiver, no external antenna required +- Si4705: FM radio receiver, no external antenna required, RDS support, Dig I/O +- Si4706: Enhanced FM RDS/TMC radio receiver, no external antenna required, RDS + Support +- Si4707: Dedicated weather band radio receiver with SAME decoder, RDS Support +- Si4708: Smallest FM receivers +- Si4709: Smallest FM receivers, RDS Support +More information on these can be downloaded here: +http://www.silabs.com/products/mcu/Pages/USBFMRadioRD.aspx + + +Supported USB devices +===================== +Currently the following USB radios (vendor:product) with the Silicon Labs si470x +chips are known to work: +- 10c4:818a: Silicon Labs USB FM Radio Reference Design +- 06e1:a155: ADS/Tech FM Radio Receiver (formerly Instant FM Music) (RDX-155-EF) +- 1b80:d700: KWorld USB FM Radio SnapMusic Mobile 700 (FM700) + + +Software +======== +Testing is usually done with most application under Debian/testing: +- fmtools - Utility for managing FM tuner cards +- gnomeradio - FM-radio tuner for the GNOME desktop +- gradio - GTK FM radio tuner +- kradio - Comfortable Radio Application for KDE +- radio - ncurses-based radio application + +There is also a library libv4l, which can be used. It's going to have a function +for frequency seeking, either by using hardware functionality as in radio-si470x +or by implementing a function as we currently have in every of the mentioned +programs. Somewhen the radio programs should make use of libv4l. + +For processing RDS information, there is a project ongoing at: +http://rdsd.berlios.de/ + +There is currently no project for making TMC sentences human readable. + + +Audio Listing +============= +USB Audio is provided by the ALSA snd_usb_audio module. It is recommended to +also select SND_USB_AUDIO, as this is required to get sound from the radio. For +listing you have to redirect the sound, for example using one of the following +commands. + +If you just want to test audio (very poor quality): +cat /dev/dsp1 > /dev/dsp + +If you use OSS try: +sox -2 --endian little -r 96000 -t oss /dev/dsp1 -t oss /dev/dsp + +If you use arts try: +arecord -D hw:1,0 -r96000 -c2 -f S16_LE | artsdsp aplay -B - + + +Module Parameters +================= +After loading the module, you still have access to some of them in the sysfs +mount under /sys/module/radio_si470x/parameters. The contents of read-only files +(0444) are not updated, even if space, band and de are changed using private +video controls. The others are runtime changeable. + + +Errors +====== +Increase tune_timeout, if you often get -EIO errors. + +When timed out or band limit is reached, hw_freq_seek returns -EAGAIN. + +If you get any errors from snd_usb_audio, please report them to the ALSA people. + + +Open Issues +=========== +V4L minor device allocation and parameter setting is not perfect. A solution is +currently under discussion. + +There is an USB interface for downloading/uploading new firmware images. Support +for it can be implemented using the request_firmware interface. + +There is a RDS interrupt mode. The driver is already using the same interface +for polling RDS information, but is currently not using the interrupt mode. + +There is a LED interface, which can be used to override the LED control +programmed in the firmware. This can be made available using the LED support +functions in the kernel. + + +Other useful information and links +================================== +http://www.silabs.com/usbradio diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt new file mode 100644 index 00000000000..eeae76c22a9 --- /dev/null +++ b/Documentation/video4linux/v4l2-framework.txt @@ -0,0 +1,520 @@ +Overview of the V4L2 driver framework +===================================== + +This text documents the various structures provided by the V4L2 framework and +their relationships. + + +Introduction +------------ + +The V4L2 drivers tend to be very complex due to the complexity of the +hardware: most devices have multiple ICs, export multiple device nodes in +/dev, and create also non-V4L2 devices such as DVB, ALSA, FB, I2C and input +(IR) devices. + +Especially the fact that V4L2 drivers have to setup supporting ICs to +do audio/video muxing/encoding/decoding makes it more complex than most. +Usually these ICs are connected to the main bridge driver through one or +more I2C busses, but other busses can also be used. Such devices are +called 'sub-devices'. + +For a long time the framework was limited to the video_device struct for +creating V4L device nodes and video_buf for handling the video buffers +(note that this document does not discuss the video_buf framework). + +This meant that all drivers had to do the setup of device instances and +connecting to sub-devices themselves. Some of this is quite complicated +to do right and many drivers never did do it correctly. + +There is also a lot of common code that could never be refactored due to +the lack of a framework. + +So this framework sets up the basic building blocks that all drivers +need and this same framework should make it much easier to refactor +common code into utility functions shared by all drivers. + + +Structure of a driver +--------------------- + +All drivers have the following structure: + +1) A struct for each device instance containing the device state. + +2) A way of initializing and commanding sub-devices (if any). + +3) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX, /dev/radioX and + /dev/vtxX) and keeping track of device-node specific data. + +4) Filehandle-specific structs containing per-filehandle data. + +This is a rough schematic of how it all relates: + + device instances + | + +-sub-device instances + | + \-V4L2 device nodes + | + \-filehandle instances + + +Structure of the framework +-------------------------- + +The framework closely resembles the driver structure: it has a v4l2_device +struct for the device instance data, a v4l2_subdev struct to refer to +sub-device instances, the video_device struct stores V4L2 device node data +and in the future a v4l2_fh struct will keep track of filehandle instances +(this is not yet implemented). + + +struct v4l2_device +------------------ + +Each device instance is represented by a struct v4l2_device (v4l2-device.h). +Very simple devices can just allocate this struct, but most of the time you +would embed this struct inside a larger struct. + +You must register the device instance: + + v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev); + +Registration will initialize the v4l2_device struct and link dev->driver_data +to v4l2_dev. Registration will also set v4l2_dev->name to a value derived from +dev (driver name followed by the bus_id, to be precise). You may change the +name after registration if you want. + +The first 'dev' argument is normally the struct device pointer of a pci_dev, +usb_device or platform_device. + +You unregister with: + + v4l2_device_unregister(struct v4l2_device *v4l2_dev); + +Unregistering will also automatically unregister all subdevs from the device. + +Sometimes you need to iterate over all devices registered by a specific +driver. This is usually the case if multiple device drivers use the same +hardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv +hardware. The same is true for alsa drivers for example. + +You can iterate over all registered devices as follows: + +static int callback(struct device *dev, void *p) +{ + struct v4l2_device *v4l2_dev = dev_get_drvdata(dev); + + /* test if this device was inited */ + if (v4l2_dev == NULL) + return 0; + ... + return 0; +} + +int iterate(void *p) +{ + struct device_driver *drv; + int err; + + /* Find driver 'ivtv' on the PCI bus. + pci_bus_type is a global. For USB busses use usb_bus_type. */ + drv = driver_find("ivtv", &pci_bus_type); + /* iterate over all ivtv device instances */ + err = driver_for_each_device(drv, NULL, p, callback); + put_driver(drv); + return err; +} + +Sometimes you need to keep a running counter of the device instance. This is +commonly used to map a device instance to an index of a module option array. + +The recommended approach is as follows: + +static atomic_t drv_instance = ATOMIC_INIT(0); + +static int __devinit drv_probe(struct pci_dev *dev, + const struct pci_device_id *pci_id) +{ + ... + state->instance = atomic_inc_return(&drv_instance) - 1; +} + + +struct v4l2_subdev +------------------ + +Many drivers need to communicate with sub-devices. These devices can do all +sort of tasks, but most commonly they handle audio and/or video muxing, +encoding or decoding. For webcams common sub-devices are sensors and camera +controllers. + +Usually these are I2C devices, but not necessarily. In order to provide the +driver with a consistent interface to these sub-devices the v4l2_subdev struct +(v4l2-subdev.h) was created. + +Each sub-device driver must have a v4l2_subdev struct. This struct can be +stand-alone for simple sub-devices or it might be embedded in a larger struct +if more state information needs to be stored. Usually there is a low-level +device struct (e.g. i2c_client) that contains the device data as setup +by the kernel. It is recommended to store that pointer in the private +data of v4l2_subdev using v4l2_set_subdevdata(). That makes it easy to go +from a v4l2_subdev to the actual low-level bus-specific device data. + +You also need a way to go from the low-level struct to v4l2_subdev. For the +common i2c_client struct the i2c_set_clientdata() call is used to store a +v4l2_subdev pointer, for other busses you may have to use other methods. + +From the bridge driver perspective you load the sub-device module and somehow +obtain the v4l2_subdev pointer. For i2c devices this is easy: you call +i2c_get_clientdata(). For other busses something similar needs to be done. +Helper functions exists for sub-devices on an I2C bus that do most of this +tricky work for you. + +Each v4l2_subdev contains function pointers that sub-device drivers can +implement (or leave NULL if it is not applicable). Since sub-devices can do +so many different things and you do not want to end up with a huge ops struct +of which only a handful of ops are commonly implemented, the function pointers +are sorted according to category and each category has its own ops struct. + +The top-level ops struct contains pointers to the category ops structs, which +may be NULL if the subdev driver does not support anything from that category. + +It looks like this: + +struct v4l2_subdev_core_ops { + int (*g_chip_ident)(struct v4l2_subdev *sd, struct v4l2_chip_ident *chip); + int (*log_status)(struct v4l2_subdev *sd); + int (*init)(struct v4l2_subdev *sd, u32 val); + ... +}; + +struct v4l2_subdev_tuner_ops { + ... +}; + +struct v4l2_subdev_audio_ops { + ... +}; + +struct v4l2_subdev_video_ops { + ... +}; + +struct v4l2_subdev_ops { + const struct v4l2_subdev_core_ops *core; + const struct v4l2_subdev_tuner_ops *tuner; + const struct v4l2_subdev_audio_ops *audio; + const struct v4l2_subdev_video_ops *video; +}; + +The core ops are common to all subdevs, the other categories are implemented +depending on the sub-device. E.g. a video device is unlikely to support the +audio ops and vice versa. + +This setup limits the number of function pointers while still making it easy +to add new ops and categories. + +A sub-device driver initializes the v4l2_subdev struct using: + + v4l2_subdev_init(subdev, &ops); + +Afterwards you need to initialize subdev->name with a unique name and set the +module owner. This is done for you if you use the i2c helper functions. + +A device (bridge) driver needs to register the v4l2_subdev with the +v4l2_device: + + int err = v4l2_device_register_subdev(device, subdev); + +This can fail if the subdev module disappeared before it could be registered. +After this function was called successfully the subdev->dev field points to +the v4l2_device. + +You can unregister a sub-device using: + + v4l2_device_unregister_subdev(subdev); + +Afterwards the subdev module can be unloaded and subdev->dev == NULL. + +You can call an ops function either directly: + + err = subdev->ops->core->g_chip_ident(subdev, &chip); + +but it is better and easier to use this macro: + + err = v4l2_subdev_call(subdev, core, g_chip_ident, &chip); + +The macro will to the right NULL pointer checks and returns -ENODEV if subdev +is NULL, -ENOIOCTLCMD if either subdev->core or subdev->core->g_chip_ident is +NULL, or the actual result of the subdev->ops->core->g_chip_ident ops. + +It is also possible to call all or a subset of the sub-devices: + + v4l2_device_call_all(dev, 0, core, g_chip_ident, &chip); + +Any subdev that does not support this ops is skipped and error results are +ignored. If you want to check for errors use this: + + err = v4l2_device_call_until_err(dev, 0, core, g_chip_ident, &chip); + +Any error except -ENOIOCTLCMD will exit the loop with that error. If no +errors (except -ENOIOCTLCMD) occured, then 0 is returned. + +The second argument to both calls is a group ID. If 0, then all subdevs are +called. If non-zero, then only those whose group ID match that value will +be called. Before a bridge driver registers a subdev it can set subdev->grp_id +to whatever value it wants (it's 0 by default). This value is owned by the +bridge driver and the sub-device driver will never modify or use it. + +The group ID gives the bridge driver more control how callbacks are called. +For example, there may be multiple audio chips on a board, each capable of +changing the volume. But usually only one will actually be used when the +user want to change the volume. You can set the group ID for that subdev to +e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling +v4l2_device_call_all(). That ensures that it will only go to the subdev +that needs it. + +The advantage of using v4l2_subdev is that it is a generic struct and does +not contain any knowledge about the underlying hardware. So a driver might +contain several subdevs that use an I2C bus, but also a subdev that is +controlled through GPIO pins. This distinction is only relevant when setting +up the device, but once the subdev is registered it is completely transparent. + + +I2C sub-device drivers +---------------------- + +Since these drivers are so common, special helper functions are available to +ease the use of these drivers (v4l2-common.h). + +The recommended method of adding v4l2_subdev support to an I2C driver is to +embed the v4l2_subdev struct into the state struct that is created for each +I2C device instance. Very simple devices have no state struct and in that case +you can just create a v4l2_subdev directly. + +A typical state struct would look like this (where 'chipname' is replaced by +the name of the chip): + +struct chipname_state { + struct v4l2_subdev sd; + ... /* additional state fields */ +}; + +Initialize the v4l2_subdev struct as follows: + + v4l2_i2c_subdev_init(&state->sd, client, subdev_ops); + +This function will fill in all the fields of v4l2_subdev and ensure that the +v4l2_subdev and i2c_client both point to one another. + +You should also add a helper inline function to go from a v4l2_subdev pointer +to a chipname_state struct: + +static inline struct chipname_state *to_state(struct v4l2_subdev *sd) +{ + return container_of(sd, struct chipname_state, sd); +} + +Use this to go from the v4l2_subdev struct to the i2c_client struct: + + struct i2c_client *client = v4l2_get_subdevdata(sd); + +And this to go from an i2c_client to a v4l2_subdev struct: + + struct v4l2_subdev *sd = i2c_get_clientdata(client); + +Finally you need to make a command function to make driver->command() +call the right subdev_ops functions: + +static int subdev_command(struct i2c_client *client, unsigned cmd, void *arg) +{ + return v4l2_subdev_command(i2c_get_clientdata(client), cmd, arg); +} + +If driver->command is never used then you can leave this out. Eventually the +driver->command usage should be removed from v4l. + +Make sure to call v4l2_device_unregister_subdev(sd) when the remove() callback +is called. This will unregister the sub-device from the bridge driver. It is +safe to call this even if the sub-device was never registered. + + +The bridge driver also has some helper functions it can use: + +struct v4l2_subdev *sd = v4l2_i2c_new_subdev(adapter, "module_foo", "chipid", 0x36); + +This loads the given module (can be NULL if no module needs to be loaded) and +calls i2c_new_device() with the given i2c_adapter and chip/address arguments. +If all goes well, then it registers the subdev with the v4l2_device. It gets +the v4l2_device by calling i2c_get_adapdata(adapter), so you should make sure +that adapdata is set to v4l2_device when you setup the i2c_adapter in your +driver. + +You can also use v4l2_i2c_new_probed_subdev() which is very similar to +v4l2_i2c_new_subdev(), except that it has an array of possible I2C addresses +that it should probe. Internally it calls i2c_new_probed_device(). + +Both functions return NULL if something went wrong. + + +struct video_device +------------------- + +The actual device nodes in the /dev directory are created using the +video_device struct (v4l2-dev.h). This struct can either be allocated +dynamically or embedded in a larger struct. + +To allocate it dynamically use: + + struct video_device *vdev = video_device_alloc(); + + if (vdev == NULL) + return -ENOMEM; + + vdev->release = video_device_release; + +If you embed it in a larger struct, then you must set the release() +callback to your own function: + + struct video_device *vdev = &my_vdev->vdev; + + vdev->release = my_vdev_release; + +The release callback must be set and it is called when the last user +of the video device exits. + +The default video_device_release() callback just calls kfree to free the +allocated memory. + +You should also set these fields: + +- parent: set to the parent device (same device as was used to register + v4l2_device). +- name: set to something descriptive and unique. +- fops: set to the file_operations struct. +- ioctl_ops: if you use the v4l2_ioctl_ops to simplify ioctl maintenance + (highly recommended to use this and it might become compulsory in the + future!), then set this to your v4l2_ioctl_ops struct. + +If you use v4l2_ioctl_ops, then you should set .unlocked_ioctl to +__video_ioctl2 or .ioctl to video_ioctl2 in your file_operations struct. + + +video_device registration +------------------------- + +Next you register the video device: this will create the character device +for you. + + err = video_register_device(vdev, VFL_TYPE_GRABBER, -1); + if (err) { + video_device_release(vdev); // or kfree(my_vdev); + return err; + } + +Which device is registered depends on the type argument. The following +types exist: + +VFL_TYPE_GRABBER: videoX for video input/output devices +VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext) +VFL_TYPE_RADIO: radioX for radio tuners +VFL_TYPE_VTX: vtxX for teletext devices (deprecated, don't use) + +The last argument gives you a certain amount of control over the device +kernel number used (i.e. the X in videoX). Normally you will pass -1 to +let the v4l2 framework pick the first free number. But if a driver creates +many devices, then it can be useful to have different video devices in +separate ranges. For example, video capture devices start at 0, video +output devices start at 16. + +So you can use the last argument to specify a minimum kernel number and +the v4l2 framework will try to pick the first free number that is equal +or higher to what you passed. If that fails, then it will just pick the +first free number. + +Whenever a device node is created some attributes are also created for you. +If you look in /sys/class/video4linux you see the devices. Go into e.g. +video0 and you will see 'name' and 'index' attributes. The 'name' attribute +is the 'name' field of the video_device struct. The 'index' attribute is +a device node index that can be assigned by the driver, or that is calculated +for you. + +If you call video_register_device(), then the index is just increased by +1 for each device node you register. The first video device node you register +always starts off with 0. + +Alternatively you can call video_register_device_index() which is identical +to video_register_device(), but with an extra index argument. Here you can +pass a specific index value (between 0 and 31) that should be used. + +Users can setup udev rules that utilize the index attribute to make fancy +device names (e.g. 'mpegX' for MPEG video capture device nodes). + +After the device was successfully registered, then you can use these fields: + +- vfl_type: the device type passed to video_register_device. +- minor: the assigned device minor number. +- num: the device kernel number (i.e. the X in videoX). +- index: the device index number (calculated or set explicitly using + video_register_device_index). + +If the registration failed, then you need to call video_device_release() +to free the allocated video_device struct, or free your own struct if the +video_device was embedded in it. The vdev->release() callback will never +be called if the registration failed, nor should you ever attempt to +unregister the device if the registration failed. + + +video_device cleanup +-------------------- + +When the video device nodes have to be removed, either during the unload +of the driver or because the USB device was disconnected, then you should +unregister them: + + video_unregister_device(vdev); + +This will remove the device nodes from sysfs (causing udev to remove them +from /dev). + +After video_unregister_device() returns no new opens can be done. + +However, in the case of USB devices some application might still have one +of these device nodes open. You should block all new accesses to read, +write, poll, etc. except possibly for certain ioctl operations like +queueing buffers. + +When the last user of the video device node exits, then the vdev->release() +callback is called and you can do the final cleanup there. + + +video_device helper functions +----------------------------- + +There are a few useful helper functions: + +You can set/get driver private data in the video_device struct using: + +void *video_get_drvdata(struct video_device *dev); +void video_set_drvdata(struct video_device *dev, void *data); + +Note that you can safely call video_set_drvdata() before calling +video_register_device(). + +And this function: + +struct video_device *video_devdata(struct file *file); + +returns the video_device belonging to the file struct. + +The final helper function combines video_get_drvdata with +video_devdata: + +void *video_drvdata(struct file *file); + +You can go from a video_device struct to the v4l2_device struct using: + +struct v4l2_device *v4l2_dev = dev_get_drvdata(vdev->parent); + diff --git a/Documentation/vm/.gitignore b/Documentation/vm/.gitignore new file mode 100644 index 00000000000..33e8a023df0 --- /dev/null +++ b/Documentation/vm/.gitignore @@ -0,0 +1 @@ +slabinfo diff --git a/Documentation/vm/unevictable-lru.txt b/Documentation/vm/unevictable-lru.txt new file mode 100644 index 00000000000..125eed560e5 --- /dev/null +++ b/Documentation/vm/unevictable-lru.txt @@ -0,0 +1,615 @@ + +This document describes the Linux memory management "Unevictable LRU" +infrastructure and the use of this infrastructure to manage several types +of "unevictable" pages. The document attempts to provide the overall +rationale behind this mechanism and the rationale for some of the design +decisions that drove the implementation. The latter design rationale is +discussed in the context of an implementation description. Admittedly, one +can obtain the implementation details--the "what does it do?"--by reading the +code. One hopes that the descriptions below add value by provide the answer +to "why does it do that?". + +Unevictable LRU Infrastructure: + +The Unevictable LRU adds an additional LRU list to track unevictable pages +and to hide these pages from vmscan. This mechanism is based on a patch by +Larry Woodman of Red Hat to address several scalability problems with page +reclaim in Linux. The problems have been observed at customer sites on large +memory x86_64 systems. For example, a non-numal x86_64 platform with 128GB +of main memory will have over 32 million 4k pages in a single zone. When a +large fraction of these pages are not evictable for any reason [see below], +vmscan will spend a lot of time scanning the LRU lists looking for the small +fraction of pages that are evictable. This can result in a situation where +all cpus are spending 100% of their time in vmscan for hours or days on end, +with the system completely unresponsive. + +The Unevictable LRU infrastructure addresses the following classes of +unevictable pages: + ++ page owned by ramfs ++ page mapped into SHM_LOCKed shared memory regions ++ page mapped into VM_LOCKED [mlock()ed] vmas + +The infrastructure might be able to handle other conditions that make pages +unevictable, either by definition or by circumstance, in the future. + + +The Unevictable LRU List + +The Unevictable LRU infrastructure consists of an additional, per-zone, LRU list +called the "unevictable" list and an associated page flag, PG_unevictable, to +indicate that the page is being managed on the unevictable list. The +PG_unevictable flag is analogous to, and mutually exclusive with, the PG_active +flag in that it indicates on which LRU list a page resides when PG_lru is set. +The unevictable LRU list is source configurable based on the UNEVICTABLE_LRU +Kconfig option. + +The Unevictable LRU infrastructure maintains unevictable pages on an additional +LRU list for a few reasons: + +1) We get to "treat unevictable pages just like we treat other pages in the + system, which means we get to use the same code to manipulate them, the + same code to isolate them (for migrate, etc.), the same code to keep track + of the statistics, etc..." [Rik van Riel] + +2) We want to be able to migrate unevictable pages between nodes--for memory + defragmentation, workload management and memory hotplug. The linux kernel + can only migrate pages that it can successfully isolate from the lru lists. + If we were to maintain pages elsewise than on an lru-like list, where they + can be found by isolate_lru_page(), we would prevent their migration, unless + we reworked migration code to find the unevictable pages. + + +The unevictable LRU list does not differentiate between file backed and swap +backed [anon] pages. This differentiation is only important while the pages +are, in fact, evictable. + +The unevictable LRU list benefits from the "arrayification" of the per-zone +LRU lists and statistics originally proposed and posted by Christoph Lameter. + +The unevictable list does not use the lru pagevec mechanism. Rather, +unevictable pages are placed directly on the page's zone's unevictable +list under the zone lru_lock. The reason for this is to prevent stranding +of pages on the unevictable list when one task has the page isolated from the +lru and other tasks are changing the "evictability" state of the page. + + +Unevictable LRU and Memory Controller Interaction + +The memory controller data structure automatically gets a per zone unevictable +lru list as a result of the "arrayification" of the per-zone LRU lists. The +memory controller tracks the movement of pages to and from the unevictable list. +When a memory control group comes under memory pressure, the controller will +not attempt to reclaim pages on the unevictable list. This has a couple of +effects. Because the pages are "hidden" from reclaim on the unevictable list, +the reclaim process can be more efficient, dealing only with pages that have +a chance of being reclaimed. On the other hand, if too many of the pages +charged to the control group are unevictable, the evictable portion of the +working set of the tasks in the control group may not fit into the available +memory. This can cause the control group to thrash or to oom-kill tasks. + + +Unevictable LRU: Detecting Unevictable Pages + +The function page_evictable(page, vma) in vmscan.c determines whether a +page is evictable or not. For ramfs pages and pages in SHM_LOCKed regions, +page_evictable() tests a new address space flag, AS_UNEVICTABLE, in the page's +address space using a wrapper function. Wrapper functions are used to set, +clear and test the flag to reduce the requirement for #ifdef's throughout the +source code. AS_UNEVICTABLE is set on ramfs inode/mapping when it is created. +This flag remains for the life of the inode. + +For shared memory regions, AS_UNEVICTABLE is set when an application +successfully SHM_LOCKs the region and is removed when the region is +SHM_UNLOCKed. Note that shmctl(SHM_LOCK, ...) does not populate the page +tables for the region as does, for example, mlock(). So, we make no special +effort to push any pages in the SHM_LOCKed region to the unevictable list. +Vmscan will do this when/if it encounters the pages during reclaim. On +SHM_UNLOCK, shmctl() scans the pages in the region and "rescues" them from the +unevictable list if no other condition keeps them unevictable. If a SHM_LOCKed +region is destroyed, the pages are also "rescued" from the unevictable list in +the process of freeing them. + +page_evictable() detects mlock()ed pages by testing an additional page flag, +PG_mlocked via the PageMlocked() wrapper. If the page is NOT mlocked, and a +non-NULL vma is supplied, page_evictable() will check whether the vma is +VM_LOCKED via is_mlocked_vma(). is_mlocked_vma() will SetPageMlocked() and +update the appropriate statistics if the vma is VM_LOCKED. This method allows +efficient "culling" of pages in the fault path that are being faulted in to +VM_LOCKED vmas. + + +Unevictable Pages and Vmscan [shrink_*_list()] + +If unevictable pages are culled in the fault path, or moved to the unevictable +list at mlock() or mmap() time, vmscan will never encounter the pages until +they have become evictable again, for example, via munlock() and have been +"rescued" from the unevictable list. However, there may be situations where we +decide, for the sake of expediency, to leave a unevictable page on one of the +regular active/inactive LRU lists for vmscan to deal with. Vmscan checks for +such pages in all of the shrink_{active|inactive|page}_list() functions and +will "cull" such pages that it encounters--that is, it diverts those pages to +the unevictable list for the zone being scanned. + +There may be situations where a page is mapped into a VM_LOCKED vma, but the +page is not marked as PageMlocked. Such pages will make it all the way to +shrink_page_list() where they will be detected when vmscan walks the reverse +map in try_to_unmap(). If try_to_unmap() returns SWAP_MLOCK, shrink_page_list() +will cull the page at that point. + +Note that for anonymous pages, shrink_page_list() attempts to add the page to +the swap cache before it tries to unmap the page. To avoid this unnecessary +consumption of swap space, shrink_page_list() calls try_to_munlock() to check +whether any VM_LOCKED vmas map the page without attempting to unmap the page. +If try_to_munlock() returns SWAP_MLOCK, shrink_page_list() will cull the page +without consuming swap space. try_to_munlock() will be described below. + +To "cull" an unevictable page, vmscan simply puts the page back on the lru +list using putback_lru_page()--the inverse operation to isolate_lru_page()-- +after dropping the page lock. Because the condition which makes the page +unevictable may change once the page is unlocked, putback_lru_page() will +recheck the unevictable state of a page that it places on the unevictable lru +list. If the page has become unevictable, putback_lru_page() removes it from +the list and retries, including the page_unevictable() test. Because such a +race is a rare event and movement of pages onto the unevictable list should be +rare, these extra evictabilty checks should not occur in the majority of calls +to putback_lru_page(). + + +Mlocked Page: Prior Work + +The "Unevictable Mlocked Pages" infrastructure is based on work originally +posted by Nick Piggin in an RFC patch entitled "mm: mlocked pages off LRU". +Nick posted his patch as an alternative to a patch posted by Christoph +Lameter to achieve the same objective--hiding mlocked pages from vmscan. +In Nick's patch, he used one of the struct page lru list link fields as a count +of VM_LOCKED vmas that map the page. This use of the link field for a count +prevented the management of the pages on an LRU list. Thus, mlocked pages were +not migratable as isolate_lru_page() could not find them and the lru list link +field was not available to the migration subsystem. Nick resolved this by +putting mlocked pages back on the lru list before attempting to isolate them, +thus abandoning the count of VM_LOCKED vmas. When Nick's patch was integrated +with the Unevictable LRU work, the count was replaced by walking the reverse +map to determine whether any VM_LOCKED vmas mapped the page. More on this +below. + + +Mlocked Pages: Basic Management + +Mlocked pages--pages mapped into a VM_LOCKED vma--represent one class of +unevictable pages. When such a page has been "noticed" by the memory +management subsystem, the page is marked with the PG_mlocked [PageMlocked()] +flag. A PageMlocked() page will be placed on the unevictable LRU list when +it is added to the LRU. Pages can be "noticed" by memory management in +several places: + +1) in the mlock()/mlockall() system call handlers. +2) in the mmap() system call handler when mmap()ing a region with the + MAP_LOCKED flag, or mmap()ing a region in a task that has called + mlockall() with the MCL_FUTURE flag. Both of these conditions result + in the VM_LOCKED flag being set for the vma. +3) in the fault path, if mlocked pages are "culled" in the fault path, + and when a VM_LOCKED stack segment is expanded. +4) as mentioned above, in vmscan:shrink_page_list() with attempting to + reclaim a page in a VM_LOCKED vma--via try_to_unmap() or try_to_munlock(). + +Mlocked pages become unlocked and rescued from the unevictable list when: + +1) mapped in a range unlocked via the munlock()/munlockall() system calls. +2) munmapped() out of the last VM_LOCKED vma that maps the page, including + unmapping at task exit. +3) when the page is truncated from the last VM_LOCKED vma of an mmap()ed file. +4) before a page is COWed in a VM_LOCKED vma. + + +Mlocked Pages: mlock()/mlockall() System Call Handling + +Both [do_]mlock() and [do_]mlockall() system call handlers call mlock_fixup() +for each vma in the range specified by the call. In the case of mlockall(), +this is the entire active address space of the task. Note that mlock_fixup() +is used for both mlock()ing and munlock()ing a range of memory. A call to +mlock() an already VM_LOCKED vma, or to munlock() a vma that is not VM_LOCKED +is treated as a no-op--mlock_fixup() simply returns. + +If the vma passes some filtering described in "Mlocked Pages: Filtering Vmas" +below, mlock_fixup() will attempt to merge the vma with its neighbors or split +off a subset of the vma if the range does not cover the entire vma. Once the +vma has been merged or split or neither, mlock_fixup() will call +__mlock_vma_pages_range() to fault in the pages via get_user_pages() and +to mark the pages as mlocked via mlock_vma_page(). + +Note that the vma being mlocked might be mapped with PROT_NONE. In this case, +get_user_pages() will be unable to fault in the pages. That's OK. If pages +do end up getting faulted into this VM_LOCKED vma, we'll handle them in the +fault path or in vmscan. + +Also note that a page returned by get_user_pages() could be truncated or +migrated out from under us, while we're trying to mlock it. To detect +this, __mlock_vma_pages_range() tests the page_mapping after acquiring +the page lock. If the page is still associated with its mapping, we'll +go ahead and call mlock_vma_page(). If the mapping is gone, we just +unlock the page and move on. Worse case, this results in page mapped +in a VM_LOCKED vma remaining on a normal LRU list without being +PageMlocked(). Again, vmscan will detect and cull such pages. + +mlock_vma_page(), called with the page locked [N.B., not "mlocked"], will +TestSetPageMlocked() for each page returned by get_user_pages(). We use +TestSetPageMlocked() because the page might already be mlocked by another +task/vma and we don't want to do extra work. We especially do not want to +count an mlocked page more than once in the statistics. If the page was +already mlocked, mlock_vma_page() is done. + +If the page was NOT already mlocked, mlock_vma_page() attempts to isolate the +page from the LRU, as it is likely on the appropriate active or inactive list +at that time. If the isolate_lru_page() succeeds, mlock_vma_page() will +putback the page--putback_lru_page()--which will notice that the page is now +mlocked and divert the page to the zone's unevictable LRU list. If +mlock_vma_page() is unable to isolate the page from the LRU, vmscan will handle +it later if/when it attempts to reclaim the page. + + +Mlocked Pages: Filtering Special Vmas + +mlock_fixup() filters several classes of "special" vmas: + +1) vmas with VM_IO|VM_PFNMAP set are skipped entirely. The pages behind + these mappings are inherently pinned, so we don't need to mark them as + mlocked. In any case, most of the pages have no struct page in which to + so mark the page. Because of this, get_user_pages() will fail for these + vmas, so there is no sense in attempting to visit them. + +2) vmas mapping hugetlbfs page are already effectively pinned into memory. + We don't need nor want to mlock() these pages. However, to preserve the + prior behavior of mlock()--before the unevictable/mlock changes--mlock_fixup() + will call make_pages_present() in the hugetlbfs vma range to allocate the + huge pages and populate the ptes. + +3) vmas with VM_DONTEXPAND|VM_RESERVED are generally user space mappings of + kernel pages, such as the vdso page, relay channel pages, etc. These pages + are inherently unevictable and are not managed on the LRU lists. + mlock_fixup() treats these vmas the same as hugetlbfs vmas. It calls + make_pages_present() to populate the ptes. + +Note that for all of these special vmas, mlock_fixup() does not set the +VM_LOCKED flag. Therefore, we won't have to deal with them later during +munlock() or munmap()--for example, at task exit. Neither does mlock_fixup() +account these vmas against the task's "locked_vm". + +Mlocked Pages: Downgrading the Mmap Semaphore. + +mlock_fixup() must be called with the mmap semaphore held for write, because +it may have to merge or split vmas. However, mlocking a large region of +memory can take a long time--especially if vmscan must reclaim pages to +satisfy the regions requirements. Faulting in a large region with the mmap +semaphore held for write can hold off other faults on the address space, in +the case of a multi-threaded task. It can also hold off scans of the task's +address space via /proc. While testing under heavy load, it was observed that +the ps(1) command could be held off for many minutes while a large segment was +mlock()ed down. + +To address this issue, and to make the system more responsive during mlock()ing +of large segments, mlock_fixup() downgrades the mmap semaphore to read mode +during the call to __mlock_vma_pages_range(). This works fine. However, the +callers of mlock_fixup() expect the semaphore to be returned in write mode. +So, mlock_fixup() "upgrades" the semphore to write mode. Linux does not +support an atomic upgrade_sem() call, so mlock_fixup() must drop the semaphore +and reacquire it in write mode. In a multi-threaded task, it is possible for +the task memory map to change while the semaphore is dropped. Therefore, +mlock_fixup() looks up the vma at the range start address after reacquiring +the semaphore in write mode and verifies that it still covers the original +range. If not, mlock_fixup() returns an error [-EAGAIN]. All callers of +mlock_fixup() have been changed to deal with this new error condition. + +Note: when munlocking a region, all of the pages should already be resident-- +unless we have racing threads mlocking() and munlocking() regions. So, +unlocking should not have to wait for page allocations nor faults of any kind. +Therefore mlock_fixup() does not downgrade the semaphore for munlock(). + + +Mlocked Pages: munlock()/munlockall() System Call Handling + +The munlock() and munlockall() system calls are handled by the same functions-- +do_mlock[all]()--as the mlock() and mlockall() system calls with the unlock +vs lock operation indicated by an argument. So, these system calls are also +handled by mlock_fixup(). Again, if called for an already munlock()ed vma, +mlock_fixup() simply returns. Because of the vma filtering discussed above, +VM_LOCKED will not be set in any "special" vmas. So, these vmas will be +ignored for munlock. + +If the vma is VM_LOCKED, mlock_fixup() again attempts to merge or split off +the specified range. The range is then munlocked via the function +__mlock_vma_pages_range()--the same function used to mlock a vma range-- +passing a flag to indicate that munlock() is being performed. + +Because the vma access protections could have been changed to PROT_NONE after +faulting in and mlocking some pages, get_user_pages() was unreliable for visiting +these pages for munlocking. Because we don't want to leave pages mlocked(), +get_user_pages() was enhanced to accept a flag to ignore the permissions when +fetching the pages--all of which should be resident as a result of previous +mlock()ing. + +For munlock(), __mlock_vma_pages_range() unlocks individual pages by calling +munlock_vma_page(). munlock_vma_page() unconditionally clears the PG_mlocked +flag using TestClearPageMlocked(). As with mlock_vma_page(), munlock_vma_page() +use the Test*PageMlocked() function to handle the case where the page might +have already been unlocked by another task. If the page was mlocked, +munlock_vma_page() updates that zone statistics for the number of mlocked +pages. Note, however, that at this point we haven't checked whether the page +is mapped by other VM_LOCKED vmas. + +We can't call try_to_munlock(), the function that walks the reverse map to check +for other VM_LOCKED vmas, without first isolating the page from the LRU. +try_to_munlock() is a variant of try_to_unmap() and thus requires that the page +not be on an lru list. [More on these below.] However, the call to +isolate_lru_page() could fail, in which case we couldn't try_to_munlock(). +So, we go ahead and clear PG_mlocked up front, as this might be the only chance +we have. If we can successfully isolate the page, we go ahead and +try_to_munlock(), which will restore the PG_mlocked flag and update the zone +page statistics if it finds another vma holding the page mlocked. If we fail +to isolate the page, we'll have left a potentially mlocked page on the LRU. +This is fine, because we'll catch it later when/if vmscan tries to reclaim the +page. This should be relatively rare. + +Mlocked Pages: Migrating Them... + +A page that is being migrated has been isolated from the lru lists and is +held locked across unmapping of the page, updating the page's mapping +[address_space] entry and copying the contents and state, until the +page table entry has been replaced with an entry that refers to the new +page. Linux supports migration of mlocked pages and other unevictable +pages. This involves simply moving the PageMlocked and PageUnevictable states +from the old page to the new page. + +Note that page migration can race with mlocking or munlocking of the same +page. This has been discussed from the mlock/munlock perspective in the +respective sections above. Both processes [migration, m[un]locking], hold +the page locked. This provides the first level of synchronization. Page +migration zeros out the page_mapping of the old page before unlocking it, +so m[un]lock can skip these pages by testing the page mapping under page +lock. + +When completing page migration, we place the new and old pages back onto the +lru after dropping the page lock. The "unneeded" page--old page on success, +new page on failure--will be freed when the reference count held by the +migration process is released. To ensure that we don't strand pages on the +unevictable list because of a race between munlock and migration, page +migration uses the putback_lru_page() function to add migrated pages back to +the lru. + + +Mlocked Pages: mmap(MAP_LOCKED) System Call Handling + +In addition the the mlock()/mlockall() system calls, an application can request +that a region of memory be mlocked using the MAP_LOCKED flag with the mmap() +call. Furthermore, any mmap() call or brk() call that expands the heap by a +task that has previously called mlockall() with the MCL_FUTURE flag will result +in the newly mapped memory being mlocked. Before the unevictable/mlock changes, +the kernel simply called make_pages_present() to allocate pages and populate +the page table. + +To mlock a range of memory under the unevictable/mlock infrastructure, the +mmap() handler and task address space expansion functions call +mlock_vma_pages_range() specifying the vma and the address range to mlock. +mlock_vma_pages_range() filters vmas like mlock_fixup(), as described above in +"Mlocked Pages: Filtering Vmas". It will clear the VM_LOCKED flag, which will +have already been set by the caller, in filtered vmas. Thus these vma's need +not be visited for munlock when the region is unmapped. + +For "normal" vmas, mlock_vma_pages_range() calls __mlock_vma_pages_range() to +fault/allocate the pages and mlock them. Again, like mlock_fixup(), +mlock_vma_pages_range() downgrades the mmap semaphore to read mode before +attempting to fault/allocate and mlock the pages; and "upgrades" the semaphore +back to write mode before returning. + +The callers of mlock_vma_pages_range() will have already added the memory +range to be mlocked to the task's "locked_vm". To account for filtered vmas, +mlock_vma_pages_range() returns the number of pages NOT mlocked. All of the +callers then subtract a non-negative return value from the task's locked_vm. +A negative return value represent an error--for example, from get_user_pages() +attempting to fault in a vma with PROT_NONE access. In this case, we leave +the memory range accounted as locked_vm, as the protections could be changed +later and pages allocated into that region. + + +Mlocked Pages: munmap()/exit()/exec() System Call Handling + +When unmapping an mlocked region of memory, whether by an explicit call to +munmap() or via an internal unmap from exit() or exec() processing, we must +munlock the pages if we're removing the last VM_LOCKED vma that maps the pages. +Before the unevictable/mlock changes, mlocking did not mark the pages in any way, +so unmapping them required no processing. + +To munlock a range of memory under the unevictable/mlock infrastructure, the +munmap() hander and task address space tear down function call +munlock_vma_pages_all(). The name reflects the observation that one always +specifies the entire vma range when munlock()ing during unmap of a region. +Because of the vma filtering when mlocking() regions, only "normal" vmas that +actually contain mlocked pages will be passed to munlock_vma_pages_all(). + +munlock_vma_pages_all() clears the VM_LOCKED vma flag and, like mlock_fixup() +for the munlock case, calls __munlock_vma_pages_range() to walk the page table +for the vma's memory range and munlock_vma_page() each resident page mapped by +the vma. This effectively munlocks the page, only if this is the last +VM_LOCKED vma that maps the page. + + +Mlocked Page: try_to_unmap() + +[Note: the code changes represented by this section are really quite small +compared to the text to describe what happening and why, and to discuss the +implications.] + +Pages can, of course, be mapped into multiple vmas. Some of these vmas may +have VM_LOCKED flag set. It is possible for a page mapped into one or more +VM_LOCKED vmas not to have the PG_mlocked flag set and therefore reside on one +of the active or inactive LRU lists. This could happen if, for example, a +task in the process of munlock()ing the page could not isolate the page from +the LRU. As a result, vmscan/shrink_page_list() might encounter such a page +as described in "Unevictable Pages and Vmscan [shrink_*_list()]". To +handle this situation, try_to_unmap() has been enhanced to check for VM_LOCKED +vmas while it is walking a page's reverse map. + +try_to_unmap() is always called, by either vmscan for reclaim or for page +migration, with the argument page locked and isolated from the LRU. BUG_ON() +assertions enforce this requirement. Separate functions handle anonymous and +mapped file pages, as these types of pages have different reverse map +mechanisms. + + try_to_unmap_anon() + +To unmap anonymous pages, each vma in the list anchored in the anon_vma must be +visited--at least until a VM_LOCKED vma is encountered. If the page is being +unmapped for migration, VM_LOCKED vmas do not stop the process because mlocked +pages are migratable. However, for reclaim, if the page is mapped into a +VM_LOCKED vma, the scan stops. try_to_unmap() attempts to acquire the mmap +semphore of the mm_struct to which the vma belongs in read mode. If this is +successful, try_to_unmap() will mlock the page via mlock_vma_page()--we +wouldn't have gotten to try_to_unmap() if the page were already mlocked--and +will return SWAP_MLOCK, indicating that the page is unevictable. If the +mmap semaphore cannot be acquired, we are not sure whether the page is really +unevictable or not. In this case, try_to_unmap() will return SWAP_AGAIN. + + try_to_unmap_file() -- linear mappings + +Unmapping of a mapped file page works the same, except that the scan visits +all vmas that maps the page's index/page offset in the page's mapping's +reverse map priority search tree. It must also visit each vma in the page's +mapping's non-linear list, if the list is non-empty. As for anonymous pages, +on encountering a VM_LOCKED vma for a mapped file page, try_to_unmap() will +attempt to acquire the associated mm_struct's mmap semaphore to mlock the page, +returning SWAP_MLOCK if this is successful, and SWAP_AGAIN, if not. + + try_to_unmap_file() -- non-linear mappings + +If a page's mapping contains a non-empty non-linear mapping vma list, then +try_to_un{map|lock}() must also visit each vma in that list to determine +whether the page is mapped in a VM_LOCKED vma. Again, the scan must visit +all vmas in the non-linear list to ensure that the pages is not/should not be +mlocked. If a VM_LOCKED vma is found in the list, the scan could terminate. +However, there is no easy way to determine whether the page is actually mapped +in a given vma--either for unmapping or testing whether the VM_LOCKED vma +actually pins the page. + +So, try_to_unmap_file() handles non-linear mappings by scanning a certain +number of pages--a "cluster"--in each non-linear vma associated with the page's +mapping, for each file mapped page that vmscan tries to unmap. If this happens +to unmap the page we're trying to unmap, try_to_unmap() will notice this on +return--(page_mapcount(page) == 0)--and return SWAP_SUCCESS. Otherwise, it +will return SWAP_AGAIN, causing vmscan to recirculate this page. We take +advantage of the cluster scan in try_to_unmap_cluster() as follows: + +For each non-linear vma, try_to_unmap_cluster() attempts to acquire the mmap +semaphore of the associated mm_struct for read without blocking. If this +attempt is successful and the vma is VM_LOCKED, try_to_unmap_cluster() will +retain the mmap semaphore for the scan; otherwise it drops it here. Then, +for each page in the cluster, if we're holding the mmap semaphore for a locked +vma, try_to_unmap_cluster() calls mlock_vma_page() to mlock the page. This +call is a no-op if the page is already locked, but will mlock any pages in +the non-linear mapping that happen to be unlocked. If one of the pages so +mlocked is the page passed in to try_to_unmap(), try_to_unmap_cluster() will +return SWAP_MLOCK, rather than the default SWAP_AGAIN. This will allow vmscan +to cull the page, rather than recirculating it on the inactive list. Again, +if try_to_unmap_cluster() cannot acquire the vma's mmap sem, it returns +SWAP_AGAIN, indicating that the page is mapped by a VM_LOCKED vma, but +couldn't be mlocked. + + +Mlocked pages: try_to_munlock() Reverse Map Scan + +TODO/FIXME: a better name might be page_mlocked()--analogous to the +page_referenced() reverse map walker--especially if we continue to call this +from shrink_page_list(). See related TODO/FIXME below. + +When munlock_vma_page()--see "Mlocked Pages: munlock()/munlockall() System +Call Handling" above--tries to munlock a page, or when shrink_page_list() +encounters an anonymous page that is not yet in the swap cache, they need to +determine whether or not the page is mapped by any VM_LOCKED vma, without +actually attempting to unmap all ptes from the page. For this purpose, the +unevictable/mlock infrastructure introduced a variant of try_to_unmap() called +try_to_munlock(). + +try_to_munlock() calls the same functions as try_to_unmap() for anonymous and +mapped file pages with an additional argument specifing unlock versus unmap +processing. Again, these functions walk the respective reverse maps looking +for VM_LOCKED vmas. When such a vma is found for anonymous pages and file +pages mapped in linear VMAs, as in the try_to_unmap() case, the functions +attempt to acquire the associated mmap semphore, mlock the page via +mlock_vma_page() and return SWAP_MLOCK. This effectively undoes the +pre-clearing of the page's PG_mlocked done by munlock_vma_page() and informs +shrink_page_list() that the anonymous page should be culled rather than added +to the swap cache in preparation for a try_to_unmap() that will almost +certainly fail. + +If try_to_unmap() is unable to acquire a VM_LOCKED vma's associated mmap +semaphore, it will return SWAP_AGAIN. This will allow shrink_page_list() +to recycle the page on the inactive list and hope that it has better luck +with the page next time. + +For file pages mapped into non-linear vmas, the try_to_munlock() logic works +slightly differently. On encountering a VM_LOCKED non-linear vma that might +map the page, try_to_munlock() returns SWAP_AGAIN without actually mlocking +the page. munlock_vma_page() will just leave the page unlocked and let +vmscan deal with it--the usual fallback position. + +Note that try_to_munlock()'s reverse map walk must visit every vma in a pages' +reverse map to determine that a page is NOT mapped into any VM_LOCKED vma. +However, the scan can terminate when it encounters a VM_LOCKED vma and can +successfully acquire the vma's mmap semphore for read and mlock the page. +Although try_to_munlock() can be called many [very many!] times when +munlock()ing a large region or tearing down a large address space that has been +mlocked via mlockall(), overall this is a fairly rare event. In addition, +although shrink_page_list() calls try_to_munlock() for every anonymous page that +it handles that is not yet in the swap cache, on average anonymous pages will +have very short reverse map lists. + +Mlocked Page: Page Reclaim in shrink_*_list() + +shrink_active_list() culls any obviously unevictable pages--i.e., +!page_evictable(page, NULL)--diverting these to the unevictable lru +list. However, shrink_active_list() only sees unevictable pages that +made it onto the active/inactive lru lists. Note that these pages do not +have PageUnevictable set--otherwise, they would be on the unevictable list and +shrink_active_list would never see them. + +Some examples of these unevictable pages on the LRU lists are: + +1) ramfs pages that have been placed on the lru lists when first allocated. + +2) SHM_LOCKed shared memory pages. shmctl(SHM_LOCK) does not attempt to + allocate or fault in the pages in the shared memory region. This happens + when an application accesses the page the first time after SHM_LOCKing + the segment. + +3) Mlocked pages that could not be isolated from the lru and moved to the + unevictable list in mlock_vma_page(). + +3) Pages mapped into multiple VM_LOCKED vmas, but try_to_munlock() couldn't + acquire the vma's mmap semaphore to test the flags and set PageMlocked. + munlock_vma_page() was forced to let the page back on to the normal + LRU list for vmscan to handle. + +shrink_inactive_list() also culls any unevictable pages that it finds +on the inactive lists, again diverting them to the appropriate zone's unevictable +lru list. shrink_inactive_list() should only see SHM_LOCKed pages that became +SHM_LOCKed after shrink_active_list() had moved them to the inactive list, or +pages mapped into VM_LOCKED vmas that munlock_vma_page() couldn't isolate from +the lru to recheck via try_to_munlock(). shrink_inactive_list() won't notice +the latter, but will pass on to shrink_page_list(). + +shrink_page_list() again culls obviously unevictable pages that it could +encounter for similar reason to shrink_inactive_list(). As already discussed, +shrink_page_list() proactively looks for anonymous pages that should have +PG_mlocked set but don't--these would not be detected by page_evictable()--to +avoid adding them to the swap cache unnecessarily. File pages mapped into +VM_LOCKED vmas but without PG_mlocked set will make it all the way to +try_to_unmap(). shrink_page_list() will divert them to the unevictable list when +try_to_unmap() returns SWAP_MLOCK, as discussed above. + +TODO/FIXME: If we can enhance the swap cache to reliably remove entries +with page_count(page) > 2, as long as all ptes are mapped to the page and +not the swap entry, we can probably remove the call to try_to_munlock() in +shrink_page_list() and just remove the page from the swap cache when +try_to_unmap() returns SWAP_MLOCK. Currently, remove_exclusive_swap_page() +doesn't seem to allow that. + + diff --git a/Documentation/w1/00-INDEX b/Documentation/w1/00-INDEX index 5270cf4cb10..cb49802745d 100644 --- a/Documentation/w1/00-INDEX +++ b/Documentation/w1/00-INDEX @@ -1,5 +1,7 @@ 00-INDEX - This file +slaves/ + - Drivers that provide support for specific family codes. masters/ - Individual chips providing 1-wire busses. w1.generic diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490 index 239f9ae0184..28176def3d6 100644 --- a/Documentation/w1/masters/ds2490 +++ b/Documentation/w1/masters/ds2490 @@ -16,3 +16,55 @@ which allows to build USB <-> W1 bridges. DS9490(R) is a USB <-> W1 bus master device which has 0x81 family ID integrated chip and DS2490 low-level operational chip. + +Notes and limitations. +- The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA. +- The 5V strong pullup is supported with a minimum of 5.9mA and a + maximum of 30.4 mA. (From DS2490.pdf) +- While the ds2490 supports a hardware search the code doesn't take + advantage of it (in tested case it only returned first device). +- The hardware will detect when devices are attached to the bus on the + next bus (reset?) operation, however only a message is printed as + the core w1 code doesn't make use of the information. Connecting + one device tends to give multiple new device notifications. +- The number of USB bus transactions could be reduced if w1_reset_send + was added to the API. The name is just a suggestion. It would take + a write buffer and a read buffer (along with sizes) as arguments. + The ds2490 block I/O command supports reset, write buffer, read + buffer, and strong pullup all in one command, instead of the current + 1 reset bus, 2 write the match rom command and slave rom id, 3 block + write and read data. The write buffer needs to have the match rom + command and slave rom id prepended to the front of the requested + write buffer, both of which are known to the driver. +- The hardware supports normal, flexible, and overdrive bus + communication speeds, but only the normal is supported. +- The registered w1_bus_master functions don't define error + conditions. If a bus search is in progress and the ds2490 is + removed it can produce a good amount of error output before the bus + search finishes. +- The hardware supports detecting some error conditions, such as + short, alarming presence on reset, and no presence on reset, but the + driver doesn't query those values. +- The ds2490 specification doesn't cover short bulk in reads in + detail, but my observation is if fewer bytes are requested than are + available, the bulk read will return an error and the hardware will + clear the entire bulk in buffer. It would be possible to read the + maximum buffer size to not run into this error condition, only extra + bytes in the buffer is a logic error in the driver. The code should + should match reads and writes as well as data sizes. Reads and + writes are serialized and the status verifies that the chip is idle + (and data is available) before the read is executed, so it should + not happen. +- Running x86_64 2.6.24 UHCI under qemu 0.9.0 under x86_64 2.6.22-rc6 + with a OHCI controller, ds2490 running in the guest would operate + normally the first time the module was loaded after qemu attached + the ds2490 hardware, but if the module was unloaded, then reloaded + most of the time one of the bulk out or in, and usually the bulk in + would fail. qemu sets a 50ms timeout and the bulk in would timeout + even when the status shows data available. A bulk out write would + show a successful completion, but the ds2490 status register would + show 0 bytes written. Detaching qemu from the ds2490 hardware and + reattaching would clear the problem. usbmon output in the guest and + host did not explain the problem. My guess is a bug in either qemu + or the host OS and more likely the host OS. +-- 03-06-2008 David Fries <David@Fries.net> diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq new file mode 100644 index 00000000000..ca722e09b6a --- /dev/null +++ b/Documentation/w1/masters/omap-hdq @@ -0,0 +1,46 @@ +Kernel driver for omap HDQ/1-wire module. +======================================== + +Supported chips: +================ + HDQ/1-wire controller on the TI OMAP 2430/3430 platforms. + +A useful link about HDQ basics: +=============================== +http://focus.ti.com/lit/an/slua408/slua408.pdf + +Description: +============ +The HDQ/1-Wire module of TI OMAP2430/3430 platforms implement the hardware +protocol of the master functions of the Benchmark HDQ and the Dallas +Semiconductor 1-Wire protocols. These protocols use a single wire for +communication between the master (HDQ/1-Wire controller) and the slave +(HDQ/1-Wire external compliant device). + +A typical application of the HDQ/1-Wire module is the communication with battery +monitor (gas gauge) integrated circuits. + +The controller supports operation in both HDQ and 1-wire mode. The essential +difference between the HDQ and 1-wire mode is how the slave device responds to +initialization pulse.In HDQ mode, the firmware does not require the host to +create an initialization pulse to the slave.However, the slave can be reset by +using an initialization pulse (also referred to as a break pulse).The slave +does not respond with a presence pulse as it does in the 1-Wire protocol. + +Remarks: +======== +The driver (drivers/w1/masters/omap_hdq.c) supports the HDQ mode of the +controller. In this mode, as we can not read the ID which obeys the W1 +spec(family:id:crc), a module parameter can be passed to the driver which will +be used to calculate the CRC and pass back an appropriate slave ID to the W1 +core. + +By default the master driver and the BQ slave i/f +driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1. +Please note to load both the modules with a different ID if required, but note +that the ID used should be same for both master and slave driver loading. + +e.g: +insmod omap_hdq.ko W1_ID=2 +inamod w1_bq27000.ko F_ID=2 + diff --git a/Documentation/w1/slaves/00-INDEX b/Documentation/w1/slaves/00-INDEX new file mode 100644 index 00000000000..f8101d6b07b --- /dev/null +++ b/Documentation/w1/slaves/00-INDEX @@ -0,0 +1,4 @@ +00-INDEX + - This file +w1_therm + - The Maxim/Dallas Semiconductor ds18*20 temperature sensor. diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm new file mode 100644 index 00000000000..0403aaaba87 --- /dev/null +++ b/Documentation/w1/slaves/w1_therm @@ -0,0 +1,41 @@ +Kernel driver w1_therm +==================== + +Supported chips: + * Maxim ds18*20 based temperature sensors. + +Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru> + + +Description +----------- + +w1_therm provides basic temperature conversion for ds18*20 devices. +supported family codes: +W1_THERM_DS18S20 0x10 +W1_THERM_DS1822 0x22 +W1_THERM_DS18B20 0x28 + +Support is provided through the sysfs w1_slave file. Each open and +read sequence will initiate a temperature conversion then provide two +lines of ASCII output. The first line contains the nine hex bytes +read along with a calculated crc value and YES or NO if it matched. +If the crc matched the returned values are retained. The second line +displays the retained values along with a temperature in millidegrees +Centigrade after t=. + +Parasite powered devices are limited to one slave performing a +temperature conversion at a time. If none of the devices are parasite +powered it would be possible to convert all the devices at the same +time and then go back to read individual sensors. That isn't +currently supported. The driver also doesn't support reduced +precision (which would also reduce the conversion time). + +The module parameter strong_pullup can be set to 0 to disable the +strong pullup or 1 to enable. If enabled the 5V strong pullup will be +enabled when the conversion is taking place provided the master driver +must support the strong pullup (or it falls back to a pullup +resistor). The DS18b20 temperature sensor specification lists a +maximum current draw of 1.5mA and that a 5k pullup resistor is not +sufficient. The strong pullup is designed to provide the additional +current required. diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1.generic index 4c6509dd478..e3333eec432 100644 --- a/Documentation/w1/w1.generic +++ b/Documentation/w1/w1.generic @@ -79,10 +79,13 @@ w1 master sysfs interface <xx-xxxxxxxxxxxxx> - a directory for a found device. The format is family-serial bus - (standard) symlink to the w1 bus driver - (standard) symlink to the w1 driver +w1_master_add - Manually register a slave device w1_master_attempts - the number of times a search was attempted w1_master_max_slave_count - the maximum slaves that may be attached to a master w1_master_name - the name of the device (w1_bus_masterX) +w1_master_pullup - 5V strong pullup 0 enabled, 1 disabled +w1_master_remove - Manually remove a slave device w1_master_search - the number of searches left to do, -1=continual (default) w1_master_slave_count - the number of slaves found @@ -90,7 +93,13 @@ w1_master_slaves - the names of the slaves, one per line w1_master_timeout - the delay in seconds between searches If you have a w1 bus that never changes (you don't add or remove devices), -you can set w1_master_search to a positive value to disable searches. +you can set the module parameter search_count to a small positive number +for an initially small number of bus searches. Alternatively it could be +set to zero, then manually add the slave device serial numbers by +w1_master_add device file. The w1_master_add and w1_master_remove files +generally only make sense when searching is disabled, as a search will +redetect manually removed devices that are present and timeout manually +added devices that aren't on the bus. w1 slave sysfs interface diff --git a/Documentation/watchdog/src/.gitignore b/Documentation/watchdog/src/.gitignore new file mode 100644 index 00000000000..ac90997dba9 --- /dev/null +++ b/Documentation/watchdog/src/.gitignore @@ -0,0 +1,2 @@ +watchdog-simple +watchdog-test diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 83c0033ee9e..fcdc62b3c3d 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -349,7 +349,7 @@ Protocol: 2.00+ 3 SYSLINUX 4 EtherBoot 5 ELILO - 7 GRuB + 7 GRUB 8 U-BOOT 9 Xen A Gujin @@ -537,8 +537,8 @@ Type: read Offset/size: 0x248/4 Protocol: 2.08+ - If non-zero then this field contains the offset from the end of the - real-mode code to the payload. + If non-zero then this field contains the offset from the beginning + of the protected-mode code to the payload. The payload may be compressed. The format of both the compressed and uncompressed data should be determined using the standard magic diff --git a/Documentation/x86/pat.txt b/Documentation/x86/pat.txt index c93ff5f4c0d..cf08c9fff3c 100644 --- a/Documentation/x86/pat.txt +++ b/Documentation/x86/pat.txt @@ -80,6 +80,30 @@ pci proc | -- | -- | WC | | | | | ------------------------------------------------------------------- +Advanced APIs for drivers +------------------------- +A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range, +vm_insert_pfn + +Drivers wanting to export some pages to userspace do it by using mmap +interface and a combination of +1) pgprot_noncached() +2) io_remap_pfn_range() or remap_pfn_range() or vm_insert_pfn() + +With PAT support, a new API pgprot_writecombine is being added. So, drivers can +continue to use the above sequence, with either pgprot_noncached() or +pgprot_writecombine() in step 1, followed by step 2. + +In addition, step 2 internally tracks the region as UC or WC in memtype +list in order to ensure no conflicting mapping. + +Note that this set of APIs only works with IO (non RAM) regions. If driver +wants to export a RAM region, it has to do set_memory_uc() or set_memory_wc() +as step 0 above and also track the usage of those pages and use set_memory_wb() +before the page is freed to free pool. + + + Notes: -- in the above table mean "Not suggested usage for the API". Some of the --'s diff --git a/Documentation/x86/x86_64/boot-options.txt b/Documentation/x86/x86_64/boot-options.txt index 72ffb5373ec..34c13040a71 100644 --- a/Documentation/x86/x86_64/boot-options.txt +++ b/Documentation/x86/x86_64/boot-options.txt @@ -35,7 +35,7 @@ APICs nolapic Don't use the local APIC (alias for i386 compatibility) - pirq=... See Documentation/i386/IO-APIC.txt + pirq=... See Documentation/x86/i386/IO-APIC.txt noapictimer Don't set up the APIC timer @@ -79,17 +79,6 @@ Timing Report when timer interrupts are lost because some code turned off interrupts for too long. - nmi_watchdog=NUMBER[,panic] - NUMBER can be: - 0 don't use an NMI watchdog - 1 use the IO-APIC timer for the NMI watchdog - 2 use the local APIC for the NMI watchdog using a performance counter. Note - This will use one performance counter and the local APIC's performance - vector. - When panic is specified panic when an NMI watchdog timeout occurs. - This is useful when you use a panic=... timeout and need the box - quickly up again. - nohpet Don't use the HPET timer. @@ -139,7 +128,7 @@ Non Executable Mappings SMP additional_cpus=NUM Allow NUM more CPUs for hotplug - (defaults are specified by the BIOS, see Documentation/x86_64/cpu-hotplug-spec) + (defaults are specified by the BIOS, see Documentation/x86/x86_64/cpu-hotplug-spec) NUMA diff --git a/Documentation/x86/x86_64/fake-numa-for-cpusets b/Documentation/x86/x86_64/fake-numa-for-cpusets index d1a985c5b00..33bb5665599 100644 --- a/Documentation/x86/x86_64/fake-numa-for-cpusets +++ b/Documentation/x86/x86_64/fake-numa-for-cpusets @@ -10,7 +10,7 @@ amount of system memory that are available to a certain class of tasks. For more information on the features of cpusets, see Documentation/cpusets.txt. There are a number of different configurations you can use for your needs. For more information on the numa=fake command line option and its various ways of -configuring fake nodes, see Documentation/x86_64/boot-options.txt. +configuring fake nodes, see Documentation/x86/x86_64/boot-options.txt. For the purposes of this introduction, we'll assume a very primitive NUMA emulation setup of "numa=fake=4*512,". This will split our system memory into diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt index efce7509736..29b52b14d0b 100644 --- a/Documentation/x86/x86_64/mm.txt +++ b/Documentation/x86/x86_64/mm.txt @@ -6,7 +6,7 @@ Virtual memory map with 4 level page tables: 0000000000000000 - 00007fffffffffff (=47 bits) user space, different per mm hole caused by [48:63] sign extension ffff800000000000 - ffff80ffffffffff (=40 bits) guard hole -ffff810000000000 - ffffc0ffffffffff (=46 bits) direct mapping of all phys. memory +ffff880000000000 - ffffc0ffffffffff (=57 TB) direct mapping of all phys. memory ffffc10000000000 - ffffc1ffffffffff (=40 bits) hole ffffc20000000000 - ffffe1ffffffffff (=45 bits) vmalloc/ioremap space ffffe20000000000 - ffffe2ffffffffff (=40 bits) virtual memory map (1TB) |