diff options
Diffstat (limited to 'Documentation')
359 files changed, 12474 insertions, 4186 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 5405f7aecef..8dfc6708a25 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -130,8 +130,6 @@ edac.txt - information on EDAC - Error Detection And Correction eisa.txt - info on EISA bus support. -exception.txt - - how Linux v2.2 handles exceptions without verify_area etc. fault-injection/ - dir with docs about the fault injection capabilities infrastructure. fb/ @@ -234,6 +232,8 @@ memory.txt - info on typical Linux memory problems. mips/ - directory with info about Linux on MIPS architecture. +mmc/ + - directory with info about the MMC subsystem mono.txt - how to execute Mono-based .NET binaries with the help of BINFMT_MISC. mutex-design.txt diff --git a/Documentation/ABI/obsolete/dv1394 b/Documentation/ABI/obsolete/dv1394 deleted file mode 100644 index 2ee36864ca1..00000000000 --- a/Documentation/ABI/obsolete/dv1394 +++ /dev/null @@ -1,9 +0,0 @@ -What: dv1394 (a.k.a. "OHCI-DV I/O support" for FireWire) -Contact: linux1394-devel@lists.sourceforge.net -Description: - New application development should use raw1394 + userspace libraries - instead, notably libiec61883 which is functionally equivalent. - -Users: - ffmpeg/libavformat (used by a variety of media players) - dvgrab v1.x (replaced by dvgrab2 on top of raw1394 and resp. libraries) diff --git a/Documentation/ABI/removed/dv1394 b/Documentation/ABI/removed/dv1394 new file mode 100644 index 00000000000..c2310b6676f --- /dev/null +++ b/Documentation/ABI/removed/dv1394 @@ -0,0 +1,14 @@ +What: dv1394 (a.k.a. "OHCI-DV I/O support" for FireWire) +Date: May 2010 (scheduled), finally removed in kernel v2.6.37 +Contact: linux1394-devel@lists.sourceforge.net +Description: + /dev/dv1394/* were character device files, one for each FireWire + controller and for NTSC and PAL respectively, from which DV data + could be received by read() or transmitted by write(). A few + ioctl()s allowed limited control. + This special-purpose interface has been superseded by libraw1394 + + libiec61883 which are functionally equivalent, support HDV, and + transparently work on top of the newer firewire kernel drivers. + +Users: + ffmpeg/libavformat (if configured for DV1394) diff --git a/Documentation/ABI/removed/raw1394 b/Documentation/ABI/removed/raw1394 new file mode 100644 index 00000000000..490aa1efc4a --- /dev/null +++ b/Documentation/ABI/removed/raw1394 @@ -0,0 +1,15 @@ +What: raw1394 (a.k.a. "Raw IEEE1394 I/O support" for FireWire) +Date: May 2010 (scheduled), finally removed in kernel v2.6.37 +Contact: linux1394-devel@lists.sourceforge.net +Description: + /dev/raw1394 was a character device file that allowed low-level + access to FireWire buses. Its major drawbacks were its inability + to implement sensible device security policies, and its low level + of abstraction that required userspace clients do duplicate much + of the kernel's ieee1394 core functionality. + Replaced by /dev/fw*, i.e. the <linux/firewire-cdev.h> ABI of + firewire-core. + +Users: + libraw1394 (works with firewire-cdev too, transparent to library ABI + users) diff --git a/Documentation/ABI/removed/raw1394_legacy_isochronous b/Documentation/ABI/removed/raw1394_legacy_isochronous deleted file mode 100644 index 1b629622d88..00000000000 --- a/Documentation/ABI/removed/raw1394_legacy_isochronous +++ /dev/null @@ -1,16 +0,0 @@ -What: legacy isochronous ABI of raw1394 (1st generation iso ABI) -Date: June 2007 (scheduled), removed in kernel v2.6.23 -Contact: linux1394-devel@lists.sourceforge.net -Description: - The two request types RAW1394_REQ_ISO_SEND, RAW1394_REQ_ISO_LISTEN have - been deprecated for quite some time. They are very inefficient as they - come with high interrupt load and several layers of callbacks for each - packet. Because of these deficiencies, the video1394 and dv1394 drivers - and the 3rd-generation isochronous ABI in raw1394 (rawiso) were created. - -Users: - libraw1394 users via the long deprecated API raw1394_iso_write, - raw1394_start_iso_write, raw1394_start_iso_rcv, raw1394_stop_iso_rcv - - libdc1394, which optionally uses these old libraw1394 calls - alternatively to the more efficient video1394 ABI diff --git a/Documentation/ABI/removed/video1394 b/Documentation/ABI/removed/video1394 new file mode 100644 index 00000000000..c39c25aee77 --- /dev/null +++ b/Documentation/ABI/removed/video1394 @@ -0,0 +1,16 @@ +What: video1394 (a.k.a. "OHCI-1394 Video support" for FireWire) +Date: May 2010 (scheduled), finally removed in kernel v2.6.37 +Contact: linux1394-devel@lists.sourceforge.net +Description: + /dev/video1394/* were character device files, one for each FireWire + controller, which were used for isochronous I/O. It was added as an + alternative to raw1394's isochronous I/O functionality which had + performance issues in its first generation. Any video1394 user had + to use raw1394 + libraw1394 too because video1394 did not provide + asynchronous I/O for device discovery and configuration. + Replaced by /dev/fw*, i.e. the <linux/firewire-cdev.h> ABI of + firewire-core. + +Users: + libdc1394 (works with firewire-cdev too, transparent to library ABI + users) diff --git a/Documentation/ABI/testing/debugfs-ec b/Documentation/ABI/testing/debugfs-ec new file mode 100644 index 00000000000..6546115a94d --- /dev/null +++ b/Documentation/ABI/testing/debugfs-ec @@ -0,0 +1,20 @@ +What: /sys/kernel/debug/ec/*/{gpe,use_global_lock,io} +Date: July 2010 +Contact: Thomas Renninger <trenn@suse.de> +Description: + +General information like which GPE is assigned to the EC and whether +the global lock should get used. +Knowing the EC GPE one can watch the amount of HW events related to +the EC here (XY -> GPE number from /sys/kernel/debug/ec/*/gpe): +/sys/firmware/acpi/interrupts/gpeXY + +The io file is binary and a userspace tool located here: +ftp://ftp.suse.com/pub/people/trenn/sources/ec/ +should get used to read out the 256 Embedded Controller registers +or writing to them. + +CAUTION: Do not write to the Embedded Controller if you don't know +what you are doing! Rebooting afterwards also is a good idea. +This can influence the way your machine is cooled and fans may +not get switched on again after you did a wrong write. diff --git a/Documentation/ABI/testing/debugfs-kmemtrace b/Documentation/ABI/testing/debugfs-kmemtrace deleted file mode 100644 index 5e6a92a02d8..00000000000 --- a/Documentation/ABI/testing/debugfs-kmemtrace +++ /dev/null @@ -1,71 +0,0 @@ -What: /sys/kernel/debug/kmemtrace/ -Date: July 2008 -Contact: Eduard - Gabriel Munteanu <eduard.munteanu@linux360.ro> -Description: - -In kmemtrace-enabled kernels, the following files are created: - -/sys/kernel/debug/kmemtrace/ - cpu<n> (0400) Per-CPU tracing data, see below. (binary) - total_overruns (0400) Total number of bytes which were dropped from - cpu<n> files because of full buffer condition, - non-binary. (text) - abi_version (0400) Kernel's kmemtrace ABI version. (text) - -Each per-CPU file should be read according to the relay interface. That is, -the reader should set affinity to that specific CPU and, as currently done by -the userspace application (though there are other methods), use poll() with -an infinite timeout before every read(). Otherwise, erroneous data may be -read. The binary data has the following _core_ format: - - Event ID (1 byte) Unsigned integer, one of: - 0 - represents an allocation (KMEMTRACE_EVENT_ALLOC) - 1 - represents a freeing of previously allocated memory - (KMEMTRACE_EVENT_FREE) - Type ID (1 byte) Unsigned integer, one of: - 0 - this is a kmalloc() / kfree() - 1 - this is a kmem_cache_alloc() / kmem_cache_free() - 2 - this is a __get_free_pages() et al. - Event size (2 bytes) Unsigned integer representing the - size of this event. Used to extend - kmemtrace. Discard the bytes you - don't know about. - Sequence number (4 bytes) Signed integer used to reorder data - logged on SMP machines. Wraparound - must be taken into account, although - it is unlikely. - Caller address (8 bytes) Return address to the caller. - Pointer to mem (8 bytes) Pointer to target memory area. Can be - NULL, but not all such calls might be - recorded. - -In case of KMEMTRACE_EVENT_ALLOC events, the next fields follow: - - Requested bytes (8 bytes) Total number of requested bytes, - unsigned, must not be zero. - Allocated bytes (8 bytes) Total number of actually allocated - bytes, unsigned, must not be lower - than requested bytes. - Requested flags (4 bytes) GFP flags supplied by the caller. - Target CPU (4 bytes) Signed integer, valid for event id 1. - If equal to -1, target CPU is the same - as origin CPU, but the reverse might - not be true. - -The data is made available in the same endianness the machine has. - -Other event ids and type ids may be defined and added. Other fields may be -added by increasing event size, but see below for details. -Every modification to the ABI, including new id definitions, are followed -by bumping the ABI version by one. - -Adding new data to the packet (features) is done at the end of the mandatory -data: - Feature size (2 byte) - Feature ID (1 byte) - Feature data (Feature size - 3 bytes) - - -Users: - kmemtrace-user - git://repo.or.cz/kmemtrace-user.git - diff --git a/Documentation/ABI/testing/sysfs-ata b/Documentation/ABI/testing/sysfs-ata new file mode 100644 index 00000000000..0a932155cbb --- /dev/null +++ b/Documentation/ABI/testing/sysfs-ata @@ -0,0 +1,99 @@ +What: /sys/class/ata_... +Date: August 2008 +Contact: Gwendal Grignou<gwendal@google.com> +Description: + +Provide a place in sysfs for storing the ATA topology of the system. This allows +retrieving various information about ATA objects. + +Files under /sys/class/ata_port +------------------------------- + + For each port, a directory ataX is created where X is the ata_port_id of + the port. The device parent is the ata host device. + +idle_irq (read) + + Number of IRQ received by the port while idle [some ata HBA only]. + +nr_pmp_links (read) + + If a SATA Port Multiplier (PM) is connected, number of link behind it. + +Files under /sys/class/ata_link +------------------------------- + + Behind each port, there is a ata_link. If there is a SATA PM in the + topology, 15 ata_link objects are created. + + If a link is behind a port, the directory name is linkX, where X is + ata_port_id of the port. + If a link is behind a PM, its name is linkX.Y where X is ata_port_id + of the parent port and Y the PM port. + +hw_sata_spd_limit + + Maximum speed supported by the connected SATA device. + +sata_spd_limit + + Maximum speed imposed by libata. + +sata_spd + + Current speed of the link [1.5, 3Gps,...]. + +Files under /sys/class/ata_device +--------------------------------- + + Behind each link, up to two ata device are created. + The name of the directory is devX[.Y].Z where: + - X is ata_port_id of the port where the device is connected, + - Y the port of the PM if any, and + - Z the device id: for PATA, there is usually 2 devices [0,1], + only 1 for SATA. + +class + Device class. Can be "ata" for disk, "atapi" for packet device, + "pmp" for PM, or "none" if no device was found behind the link. + +dma_mode + + Transfer modes supported by the device when in DMA mode. + Mostly used by PATA device. + +pio_mode + + Transfer modes supported by the device when in PIO mode. + Mostly used by PATA device. + +xfer_mode + + Current transfer mode. + +id + + Cached result of IDENTIFY command, as described in ATA8 7.16 and 7.17. + Only valid if the device is not a PM. + +gscr + + Cached result of the dump of PM GSCR register. + Valid registers are: + 0: SATA_PMP_GSCR_PROD_ID, + 1: SATA_PMP_GSCR_REV, + 2: SATA_PMP_GSCR_PORT_INFO, + 32: SATA_PMP_GSCR_ERROR, + 33: SATA_PMP_GSCR_ERROR_EN, + 64: SATA_PMP_GSCR_FEAT, + 96: SATA_PMP_GSCR_FEAT_EN, + 130: SATA_PMP_GSCR_SII_GPIO + Only valid if the device is a PM. + +spdn_cnt + + Number of time libata decided to lower the speed of link due to errors. + +ering + + Formatted output of the error ring of the device. diff --git a/Documentation/ABI/testing/sysfs-block-zram b/Documentation/ABI/testing/sysfs-block-zram new file mode 100644 index 00000000000..c8b3b48ec62 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-zram @@ -0,0 +1,99 @@ +What: /sys/block/zram<id>/disksize +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The disksize file is read-write and specifies the disk size + which represents the limit on the *uncompressed* worth of data + that can be stored in this disk. + +What: /sys/block/zram<id>/initstate +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The disksize file is read-only and shows the initialization + state of the device. + +What: /sys/block/zram<id>/reset +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The disksize file is write-only and allows resetting the + device. The reset operation frees all the memory assocaited + with this device. + +What: /sys/block/zram<id>/num_reads +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The num_reads file is read-only and specifies the number of + reads (failed or successful) done on this device. + +What: /sys/block/zram<id>/num_writes +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The num_writes file is read-only and specifies the number of + writes (failed or successful) done on this device. + +What: /sys/block/zram<id>/invalid_io +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The invalid_io file is read-only and specifies the number of + non-page-size-aligned I/O requests issued to this device. + +What: /sys/block/zram<id>/notify_free +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The notify_free file is read-only and specifies the number of + swap slot free notifications received by this device. These + notifications are send to a swap block device when a swap slot + is freed. This statistic is applicable only when this disk is + being used as a swap disk. + +What: /sys/block/zram<id>/discard +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The discard file is read-only and specifies the number of + discard requests received by this device. These requests + provide information to block device regarding blocks which are + no longer used by filesystem. + +What: /sys/block/zram<id>/zero_pages +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The zero_pages file is read-only and specifies number of zero + filled pages written to this disk. No memory is allocated for + such pages. + +What: /sys/block/zram<id>/orig_data_size +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The orig_data_size file is read-only and specifies uncompressed + size of data stored in this disk. This excludes zero-filled + pages (zero_pages) since no memory is allocated for them. + Unit: bytes + +What: /sys/block/zram<id>/compr_data_size +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The compr_data_size file is read-only and specifies compressed + size of data stored in this disk. So, compression ratio can be + calculated using orig_data_size and this statistic. + Unit: bytes + +What: /sys/block/zram<id>/mem_used_total +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The mem_used_total file is read-only and specifies the amount + of memory, including allocator fragmentation and metadata + overhead, allocated for this disk. So, allocator space + efficiency can be calculated using compr_data_size and this + statistic. + Unit: bytes
\ No newline at end of file diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 new file mode 100644 index 00000000000..feb2e4a8707 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 @@ -0,0 +1,21 @@ +Where: /sys/bus/i2c/devices/.../heading0_input +Date: April 2010 +Kernel Version: 2.6.36? +Contact: alan.cox@intel.com +Description: Reports the current heading from the compass as a floating + point value in degrees. + +Where: /sys/bus/i2c/devices/.../power_state +Date: April 2010 +Kernel Version: 2.6.36? +Contact: alan.cox@intel.com +Description: Sets the power state of the device. 0 sets the device into + sleep mode, 1 wakes it up. + +Where: /sys/bus/i2c/devices/.../calibration +Date: April 2010 +Kernel Version: 2.6.36? +Contact: alan.cox@intel.com +Description: Sets the calibration on or off (1 = on, 0 = off). See the + chip data sheet. + diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 25be3250f7d..f979d825d11 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -139,3 +139,30 @@ Contact: linux-pci@vger.kernel.org Description: This symbolic link points to the PCI hotplug controller driver module that manages the hotplug slot. + +What: /sys/bus/pci/devices/.../label +Date: July 2010 +Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com +Description: + Reading this attribute will provide the firmware + given name(SMBIOS type 41 string) of the PCI device. + The attribute will be created only if the firmware + has given a name to the PCI device. +Users: + Userspace applications interested in knowing the + firmware assigned name of the PCI device. + +What: /sys/bus/pci/devices/.../index +Date: July 2010 +Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com +Description: + Reading this attribute will provide the firmware + given instance(SMBIOS type 41 device type instance) + of the PCI device. The attribute will be created + only if the firmware has given a device type instance + to the PCI device. +Users: + Userspace applications interested in knowing the + firmware assigned device type instance of the PCI + device that can help in understanding the firmware + intended order of the PCI device. diff --git a/Documentation/ABI/testing/sysfs-devices-memory b/Documentation/ABI/testing/sysfs-devices-memory index aba7d989208..7405de26ee6 100644 --- a/Documentation/ABI/testing/sysfs-devices-memory +++ b/Documentation/ABI/testing/sysfs-devices-memory @@ -7,7 +7,7 @@ Description: added or removed dynamically to represent hot-add/remove operations. Users: hotplug memory add/remove tools - https://w3.opensource.ibm.com/projects/powerpc-utils/ + http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils What: /sys/devices/system/memory/memoryX/removable Date: June 2008 @@ -19,7 +19,7 @@ Description: identify removable sections of the memory before attempting potentially expensive hot-remove memory operation Users: hotplug memory remove tools - https://w3.opensource.ibm.com/projects/powerpc-utils/ + http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils What: /sys/devices/system/memory/memoryX/phys_device Date: September 2008 @@ -58,7 +58,7 @@ Description: by root to offline that section. # echo offline > /sys/devices/system/memory/memory22/state Users: hotplug memory remove tools - https://w3.opensource.ibm.com/projects/powerpc-utils/ + http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils What: /sys/devices/system/memoryX/nodeY diff --git a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget index 34034027b13..d548eaac230 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget +++ b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget @@ -7,3 +7,15 @@ Description: 0 -> resumed (_UDC_ is the name of the USB Device Controller driver) + +What: /sys/devices/platform/_UDC_/gadget/gadget-lunX/nofua +Date: July 2010 +Contact: Andy Shevchenko <andy.shevchenko@gmail.com> +Description: + Show or set the reaction on the FUA (Force Unit Access) bit in + the SCSI WRITE(10,12) commands when a gadget in USB Mass + Storage mode. + + Possible values are: + 1 -> ignore the FUA flag + 0 -> obey the FUA flag diff --git a/Documentation/ABI/testing/sysfs-devices-power b/Documentation/ABI/testing/sysfs-devices-power index 6123c523bfd..7628cd1bc36 100644 --- a/Documentation/ABI/testing/sysfs-devices-power +++ b/Documentation/ABI/testing/sysfs-devices-power @@ -77,3 +77,91 @@ Description: devices this attribute is set to "enabled" by bus type code or device drivers and in that cases it should be safe to leave the default value. + +What: /sys/devices/.../power/wakeup_count +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@sisk.pl> +Description: + The /sys/devices/.../wakeup_count attribute contains the number + of signaled wakeup events associated with the device. This + attribute is read-only. If the device is not enabled to wake up + the system from sleep states, this attribute is empty. + +What: /sys/devices/.../power/wakeup_active_count +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@sisk.pl> +Description: + The /sys/devices/.../wakeup_active_count attribute contains the + number of times the processing of wakeup events associated with + the device was completed (at the kernel level). This attribute + is read-only. If the device is not enabled to wake up the + system from sleep states, this attribute is empty. + +What: /sys/devices/.../power/wakeup_hit_count +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@sisk.pl> +Description: + The /sys/devices/.../wakeup_hit_count attribute contains the + number of times the processing of a wakeup event associated with + the device might prevent the system from entering a sleep state. + This attribute is read-only. If the device is not enabled to + wake up the system from sleep states, this attribute is empty. + +What: /sys/devices/.../power/wakeup_active +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@sisk.pl> +Description: + The /sys/devices/.../wakeup_active attribute contains either 1, + or 0, depending on whether or not a wakeup event associated with + the device is being processed (1). This attribute is read-only. + If the device is not enabled to wake up the system from sleep + states, this attribute is empty. + +What: /sys/devices/.../power/wakeup_total_time_ms +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@sisk.pl> +Description: + The /sys/devices/.../wakeup_total_time_ms attribute contains + the total time of processing wakeup events associated with the + device, in milliseconds. This attribute is read-only. If the + device is not enabled to wake up the system from sleep states, + this attribute is empty. + +What: /sys/devices/.../power/wakeup_max_time_ms +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@sisk.pl> +Description: + The /sys/devices/.../wakeup_max_time_ms attribute contains + the maximum time of processing a single wakeup event associated + with the device, in milliseconds. This attribute is read-only. + If the device is not enabled to wake up the system from sleep + states, this attribute is empty. + +What: /sys/devices/.../power/wakeup_last_time_ms +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@sisk.pl> +Description: + The /sys/devices/.../wakeup_last_time_ms attribute contains + the value of the monotonic clock corresponding to the time of + signaling the last wakeup event associated with the device, in + milliseconds. This attribute is read-only. If the device is + not enabled to wake up the system from sleep states, this + attribute is empty. + +What: /sys/devices/.../power/autosuspend_delay_ms +Date: September 2010 +Contact: Alan Stern <stern@rowland.harvard.edu> +Description: + The /sys/devices/.../power/autosuspend_delay_ms attribute + contains the autosuspend delay value (in milliseconds). Some + drivers do not want their device to suspend as soon as it + becomes idle at run time; they want the device to remain + inactive for a certain minimum period of time first. That + period is called the autosuspend delay. Negative values will + prevent the device from being suspended at run time (similar + to writing "on" to the power/control attribute). Values >= + 1000 will cause the autosuspend timer expiration to be rounded + up to the nearest second. + + Not all drivers support this attribute. If it isn't supported, + attempts to read or write it will yield I/O errors. diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 84a710f87c6..7564e88bfa4 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -197,7 +197,7 @@ Description: These files exist in every cpu's cache index directories. Currently, only AMD Family 10h Processors support cache index disable, and only for their L3 caches. See the BIOS and Kernel Developer's Guide at - http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/31116-Public-GH-BKDG_3.20_2-4-09.pdf + http://support.amd.com/us/Embedded_TechDocs/31116-Public-GH-BKDG_3-28_5-28-09.pdf for formatting information and other details on the cache index disable. Users: joachim.deguara@amd.com diff --git a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl new file mode 100644 index 00000000000..b82deeaec31 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl @@ -0,0 +1,22 @@ +What: state +Date: Sep 2010 +KernelVersion: 2.6.37 +Contact: Vernon Mauery <vernux@us.ibm.com> +Description: The state file allows a means by which to change in and + out of Premium Real-Time Mode (PRTM), as well as the + ability to query the current state. + 0 => PRTM off + 1 => PRTM enabled +Users: The ibm-prtm userspace daemon uses this interface. + + +What: version +Date: Sep 2010 +KernelVersion: 2.6.37 +Contact: Vernon Mauery <vernux@us.ibm.com> +Description: The version file provides a means by which to query + the RTL table version that lives in the Extended + BIOS Data Area (EBDA). +Users: The ibm-prtm userspace daemon uses this interface. + + diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone index 88340a23ce9..063bda7fe70 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone @@ -33,19 +33,6 @@ Description: When read, this file returns the raw integer version number of the left. E.g. a returned value of 138 means 1.38 This file is readonly. -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/kone_driver_version -Date: March 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When read, this file returns the driver version. - The format of the string is "v<major>.<minor>.<patchlevel>". - This attribute is used by the userland tools to find the sysfs- - paths of installed kone-mice and determine the capabilites of - the driver. Versions of this driver for old kernels replace - usbhid instead of generic-usb. The way to scan for this file - has been chosen to provide a consistent way for all supported - kernel versions. - This file is readonly. - What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/profile[1-5] Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra new file mode 100644 index 00000000000..ad1125b02ff --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra @@ -0,0 +1,98 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/actual_cpi +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: It is possible to switch the cpi setting of the mouse with the + press of a button. + When read, this file returns the raw number of the actual cpi + setting reported by the mouse. This number has to be further + processed to receive the real dpi value. + + VALUE DPI + 1 400 + 2 800 + 4 1600 + + This file is readonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/actual_profile +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the number of the actual profile in + range 0-4. + This file is readonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/firmware_version +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the raw integer version number of the + firmware reported by the mouse. Using the integer value eases + further usage in other programs. To receive the real version + number the decimal point has to be shifted 2 positions to the + left. E.g. a returned value of 138 means 1.38 + This file is readonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/profile_settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds informations like resolution, sensitivity + and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 13 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + This file is writeonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/profile[1-5]_settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds informations like resolution, sensitivity + and light effects. + When read, these files return the respective profile settings. + The returned data is 13 bytes in size. + This file is readonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/profile_buttons +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds informations about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 19 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + This file is writeonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/profile[1-5]_buttons +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds informations about button layout. + When read, these files return the respective profile buttons. + The returned data is 19 bytes in size. + This file is readonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/startup_profile +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 0-4. + When read, this attribute returns the number of the profile + that's active when the mouse is powered on. + This file is readonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the settings stored in the mouse. + The size of the data is 3 bytes and holds information on the + startup_profile. + When written, this file lets write settings back to the mouse. + The data has to be 3 bytes long. The mouse will reject invalid + data. diff --git a/Documentation/ABI/testing/sysfs-i2c-bmp085 b/Documentation/ABI/testing/sysfs-i2c-bmp085 new file mode 100644 index 00000000000..585962ad046 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-i2c-bmp085 @@ -0,0 +1,31 @@ +What: /sys/bus/i2c/devices/<busnum>-<devaddr>/pressure0_input +Date: June 2010 +Contact: Christoph Mair <christoph.mair@gmail.com> +Description: Start a pressure measurement and read the result. Values + represent the ambient air pressure in pascal (0.01 millibar). + + Reading: returns the current air pressure. + + +What: /sys/bus/i2c/devices/<busnum>-<devaddr>/temp0_input +Date: June 2010 +Contact: Christoph Mair <christoph.mair@gmail.com> +Description: Measure the ambient temperature. The returned value represents + the ambient temperature in units of 0.1 degree celsius. + + Reading: returns the current temperature. + + +What: /sys/bus/i2c/devices/<busnum>-<devaddr>/oversampling +Date: June 2010 +Contact: Christoph Mair <christoph.mair@gmail.com> +Description: Tell the bmp085 to use more samples to calculate a pressure + value. When writing to this file the chip will use 2^x samples + to calculate the next pressure value with x being the value + written. Using this feature will decrease RMS noise and + increase the measurement time. + + Reading: returns the current oversampling setting. + + Writing: sets a new oversampling setting. + Accepted values: 0..3. diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module new file mode 100644 index 00000000000..cfcec3bffc0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-module @@ -0,0 +1,12 @@ +What: /sys/module/pch_phub/drivers/.../pch_mac +Date: August 2010 +KernelVersion: 2.6.35 +Contact: masa-korg@dsn.okisemi.com +Description: Write/read GbE MAC address. + +What: /sys/module/pch_phub/drivers/.../pch_firmware +Date: August 2010 +KernelVersion: 2.6.35 +Contact: masa-korg@dsn.okisemi.com +Description: Write/read Option ROM data. + diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power index d6a801f45b4..194ca446ac2 100644 --- a/Documentation/ABI/testing/sysfs-power +++ b/Documentation/ABI/testing/sysfs-power @@ -99,9 +99,38 @@ Description: dmesg -s 1000000 | grep 'hash matches' + If you do not get any matches (or they appear to be false + positives), it is possible that the last PM event point + referred to a device created by a loadable kernel module. In + this case cat /sys/power/pm_trace_dev_match (see below) after + your system is started up and the kernel modules are loaded. + CAUTION: Using it will cause your machine's real-time (CMOS) clock to be set to a random invalid time after a resume. +What; /sys/power/pm_trace_dev_match +Date: October 2010 +Contact: James Hogan <james@albanarts.com> +Description: + The /sys/power/pm_trace_dev_match file contains the name of the + device associated with the last PM event point saved in the RTC + across reboots when pm_trace has been used. More precisely it + contains the list of current devices (including those + registered by loadable kernel modules since boot) which match + the device hash in the RTC at boot, with a newline after each + one. + + The advantage of this file over the hash matches printed to the + kernel log (see /sys/power/pm_trace), is that it includes + devices created after boot by loadable kernel modules. + + Due to the small hash size necessary to fit in the RTC, it is + possible that more than one device matches the hash, in which + case further investigation is required to determine which + device is causing the problem. Note that genuine RTC clock + values (such as when pm_trace has not been used), can still + match a device and output it's name here. + What: /sys/power/pm_async Date: January 2009 Contact: Rafael J. Wysocki <rjw@sisk.pl> @@ -114,3 +143,18 @@ Description: if this file contains "1", which is the default. It may be disabled by writing "0" to this file, in which case all devices will be suspended and resumed synchronously. + +What: /sys/power/wakeup_count +Date: July 2010 +Contact: Rafael J. Wysocki <rjw@sisk.pl> +Description: + The /sys/power/wakeup_count file allows user space to put the + system into a sleep state while taking into account the + concurrent arrival of wakeup events. Reading from it returns + the current number of registered wakeup events and it blocks if + some wakeup events are being processed at the time the file is + read from. Writing to it will only succeed if the current + number of wakeup events is equal to the written value and, if + successful, will make the kernel abort a subsequent transition + to a sleep state if any wakeup events are reported after the + write has returned. diff --git a/Documentation/Changes b/Documentation/Changes index eca9f6e6fbe..4fb88f15f2e 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -331,7 +331,7 @@ o <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/> Mkinitrd -------- -o <ftp://rawhide.redhat.com/pub/rawhide/SRPMS/SRPMS/> +o <https://code.launchpad.net/initrd-tools/main> E2fsprogs --------- @@ -343,11 +343,11 @@ o <http://jfs.sourceforge.net/> Reiserfsprogs ------------- -o <http://www.namesys.com/pub/reiserfsprogs/reiserfsprogs-3.6.3.tar.gz> +o <http://www.kernel.org/pub/linux/utils/fs/reiserfs/> Xfsprogs -------- -o <ftp://oss.sgi.com/projects/xfs/download/> +o <ftp://oss.sgi.com/projects/xfs/> Pcmciautils ----------- @@ -387,18 +387,18 @@ o <http://sourceforge.net/projects/fuse> mcelog ------ -o <ftp://ftp.kernel.org/pub/linux/utils/cpu/mce/mcelog/> +o <ftp://ftp.kernel.org/pub/linux/utils/cpu/mce/> Networking ********** PPP --- -o <ftp://ftp.samba.org/pub/ppp/ppp-2.4.0.tar.gz> +o <ftp://ftp.samba.org/pub/ppp/> Isdn4k-utils ------------ -o <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/isdn4k-utils.v3.1pre1.tar.gz> +o <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/> NFS-utils --------- diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index 98ce51796f7..d568bc235bc 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -738,21 +738,31 @@ to "Closing". CONFIG_NEED_SG_DMA_LENGTH if the architecture supports IOMMUs (including software IOMMU). -2) ARCH_KMALLOC_MINALIGN +2) ARCH_DMA_MINALIGN Architectures must ensure that kmalloc'ed buffer is DMA-safe. Drivers and subsystems depend on it. If an architecture isn't fully DMA-coherent (i.e. hardware doesn't ensure that data in the CPU cache is identical to data in main memory), - ARCH_KMALLOC_MINALIGN must be set so that the memory allocator + ARCH_DMA_MINALIGN must be set so that the memory allocator makes sure that kmalloc'ed buffer doesn't share a cache line with the others. See arch/arm/include/asm/cache.h as an example. - Note that ARCH_KMALLOC_MINALIGN is about DMA memory alignment + Note that ARCH_DMA_MINALIGN is about DMA memory alignment constraints. You don't need to worry about the architecture data alignment constraints (e.g. the alignment constraints about 64-bit objects). +3) Supporting multiple types of IOMMUs + + If your architecture needs to support multiple types of IOMMUs, you + can use include/linux/asm-generic/dma-mapping-common.h. It's a + library to support the DMA API with multiple types of IOMMUs. Lots + of architectures (x86, powerpc, sh, alpha, ia64, microblaze and + sparc) use it. Choose one to see how it can be used. If you need to + support multiple types of IOMMUs in a single system, the example of + x86 or powerpc helps. + Closing This document, and the API itself, would not be in its current diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt index 05e2ae23686..fe232690661 100644 --- a/Documentation/DMA-API.txt +++ b/Documentation/DMA-API.txt @@ -456,12 +456,6 @@ be identical to those passed in (and returned by dma_alloc_noncoherent()). int -dma_is_consistent(struct device *dev, dma_addr_t dma_handle) - -Returns true if the device dev is performing consistent DMA on the memory -area pointed to by the dma_handle. - -int dma_get_cache_alignment(void) Returns the processor cache alignment. This is the absolute minimum diff --git a/Documentation/DocBook/80211.tmpl b/Documentation/DocBook/80211.tmpl new file mode 100644 index 00000000000..19a1210c253 --- /dev/null +++ b/Documentation/DocBook/80211.tmpl @@ -0,0 +1,495 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> +<set> + <setinfo> + <title>The 802.11 subsystems – for kernel developers</title> + <subtitle> + Explaining wireless 802.11 networking in the Linux kernel + </subtitle> + + <copyright> + <year>2007-2009</year> + <holder>Johannes Berg</holder> + </copyright> + + <authorgroup> + <author> + <firstname>Johannes</firstname> + <surname>Berg</surname> + <affiliation> + <address><email>johannes@sipsolutions.net</email></address> + </affiliation> + </author> + </authorgroup> + + <legalnotice> + <para> + This documentation 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. + </para> + <para> + This documentation 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 documentation; 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> + + <abstract> + <para> + These books attempt to give a description of the + various subsystems that play a role in 802.11 wireless + networking in Linux. Since these books are for kernel + developers they attempts to document the structures + and functions used in the kernel as well as giving a + higher-level overview. + </para> + <para> + The reader is expected to be familiar with the 802.11 + standard as published by the IEEE in 802.11-2007 (or + possibly later versions). References to this standard + will be given as "802.11-2007 8.1.5". + </para> + </abstract> + </setinfo> + <book id="cfg80211-developers-guide"> + <bookinfo> + <title>The cfg80211 subsystem</title> + + <abstract> +!Pinclude/net/cfg80211.h Introduction + </abstract> + </bookinfo> + <chapter> + <title>Device registration</title> +!Pinclude/net/cfg80211.h Device registration +!Finclude/net/cfg80211.h ieee80211_band +!Finclude/net/cfg80211.h ieee80211_channel_flags +!Finclude/net/cfg80211.h ieee80211_channel +!Finclude/net/cfg80211.h ieee80211_rate_flags +!Finclude/net/cfg80211.h ieee80211_rate +!Finclude/net/cfg80211.h ieee80211_sta_ht_cap +!Finclude/net/cfg80211.h ieee80211_supported_band +!Finclude/net/cfg80211.h cfg80211_signal_type +!Finclude/net/cfg80211.h wiphy_params_flags +!Finclude/net/cfg80211.h wiphy_flags +!Finclude/net/cfg80211.h wiphy +!Finclude/net/cfg80211.h wireless_dev +!Finclude/net/cfg80211.h wiphy_new +!Finclude/net/cfg80211.h wiphy_register +!Finclude/net/cfg80211.h wiphy_unregister +!Finclude/net/cfg80211.h wiphy_free + +!Finclude/net/cfg80211.h wiphy_name +!Finclude/net/cfg80211.h wiphy_dev +!Finclude/net/cfg80211.h wiphy_priv +!Finclude/net/cfg80211.h priv_to_wiphy +!Finclude/net/cfg80211.h set_wiphy_dev +!Finclude/net/cfg80211.h wdev_priv + </chapter> + <chapter> + <title>Actions and configuration</title> +!Pinclude/net/cfg80211.h Actions and configuration +!Finclude/net/cfg80211.h cfg80211_ops +!Finclude/net/cfg80211.h vif_params +!Finclude/net/cfg80211.h key_params +!Finclude/net/cfg80211.h survey_info_flags +!Finclude/net/cfg80211.h survey_info +!Finclude/net/cfg80211.h beacon_parameters +!Finclude/net/cfg80211.h plink_actions +!Finclude/net/cfg80211.h station_parameters +!Finclude/net/cfg80211.h station_info_flags +!Finclude/net/cfg80211.h rate_info_flags +!Finclude/net/cfg80211.h rate_info +!Finclude/net/cfg80211.h station_info +!Finclude/net/cfg80211.h monitor_flags +!Finclude/net/cfg80211.h mpath_info_flags +!Finclude/net/cfg80211.h mpath_info +!Finclude/net/cfg80211.h bss_parameters +!Finclude/net/cfg80211.h ieee80211_txq_params +!Finclude/net/cfg80211.h cfg80211_crypto_settings +!Finclude/net/cfg80211.h cfg80211_auth_request +!Finclude/net/cfg80211.h cfg80211_assoc_request +!Finclude/net/cfg80211.h cfg80211_deauth_request +!Finclude/net/cfg80211.h cfg80211_disassoc_request +!Finclude/net/cfg80211.h cfg80211_ibss_params +!Finclude/net/cfg80211.h cfg80211_connect_params +!Finclude/net/cfg80211.h cfg80211_pmksa +!Finclude/net/cfg80211.h cfg80211_send_rx_auth +!Finclude/net/cfg80211.h cfg80211_send_auth_timeout +!Finclude/net/cfg80211.h __cfg80211_auth_canceled +!Finclude/net/cfg80211.h cfg80211_send_rx_assoc +!Finclude/net/cfg80211.h cfg80211_send_assoc_timeout +!Finclude/net/cfg80211.h cfg80211_send_deauth +!Finclude/net/cfg80211.h __cfg80211_send_deauth +!Finclude/net/cfg80211.h cfg80211_send_disassoc +!Finclude/net/cfg80211.h __cfg80211_send_disassoc +!Finclude/net/cfg80211.h cfg80211_ibss_joined +!Finclude/net/cfg80211.h cfg80211_connect_result +!Finclude/net/cfg80211.h cfg80211_roamed +!Finclude/net/cfg80211.h cfg80211_disconnected +!Finclude/net/cfg80211.h cfg80211_ready_on_channel +!Finclude/net/cfg80211.h cfg80211_remain_on_channel_expired +!Finclude/net/cfg80211.h cfg80211_new_sta +!Finclude/net/cfg80211.h cfg80211_rx_mgmt +!Finclude/net/cfg80211.h cfg80211_mgmt_tx_status +!Finclude/net/cfg80211.h cfg80211_cqm_rssi_notify +!Finclude/net/cfg80211.h cfg80211_michael_mic_failure + </chapter> + <chapter> + <title>Scanning and BSS list handling</title> +!Pinclude/net/cfg80211.h Scanning and BSS list handling +!Finclude/net/cfg80211.h cfg80211_ssid +!Finclude/net/cfg80211.h cfg80211_scan_request +!Finclude/net/cfg80211.h cfg80211_scan_done +!Finclude/net/cfg80211.h cfg80211_bss +!Finclude/net/cfg80211.h cfg80211_inform_bss_frame +!Finclude/net/cfg80211.h cfg80211_inform_bss +!Finclude/net/cfg80211.h cfg80211_unlink_bss +!Finclude/net/cfg80211.h cfg80211_find_ie +!Finclude/net/cfg80211.h ieee80211_bss_get_ie + </chapter> + <chapter> + <title>Utility functions</title> +!Pinclude/net/cfg80211.h Utility functions +!Finclude/net/cfg80211.h ieee80211_channel_to_frequency +!Finclude/net/cfg80211.h ieee80211_frequency_to_channel +!Finclude/net/cfg80211.h ieee80211_get_channel +!Finclude/net/cfg80211.h ieee80211_get_response_rate +!Finclude/net/cfg80211.h ieee80211_hdrlen +!Finclude/net/cfg80211.h ieee80211_get_hdrlen_from_skb +!Finclude/net/cfg80211.h ieee80211_radiotap_iterator + </chapter> + <chapter> + <title>Data path helpers</title> +!Pinclude/net/cfg80211.h Data path helpers +!Finclude/net/cfg80211.h ieee80211_data_to_8023 +!Finclude/net/cfg80211.h ieee80211_data_from_8023 +!Finclude/net/cfg80211.h ieee80211_amsdu_to_8023s +!Finclude/net/cfg80211.h cfg80211_classify8021d + </chapter> + <chapter> + <title>Regulatory enforcement infrastructure</title> +!Pinclude/net/cfg80211.h Regulatory enforcement infrastructure +!Finclude/net/cfg80211.h regulatory_hint +!Finclude/net/cfg80211.h wiphy_apply_custom_regulatory +!Finclude/net/cfg80211.h freq_reg_info + </chapter> + <chapter> + <title>RFkill integration</title> +!Pinclude/net/cfg80211.h RFkill integration +!Finclude/net/cfg80211.h wiphy_rfkill_set_hw_state +!Finclude/net/cfg80211.h wiphy_rfkill_start_polling +!Finclude/net/cfg80211.h wiphy_rfkill_stop_polling + </chapter> + <chapter> + <title>Test mode</title> +!Pinclude/net/cfg80211.h Test mode +!Finclude/net/cfg80211.h cfg80211_testmode_alloc_reply_skb +!Finclude/net/cfg80211.h cfg80211_testmode_reply +!Finclude/net/cfg80211.h cfg80211_testmode_alloc_event_skb +!Finclude/net/cfg80211.h cfg80211_testmode_event + </chapter> + </book> + <book id="mac80211-developers-guide"> + <bookinfo> + <title>The mac80211 subsystem</title> + <abstract> +!Pinclude/net/mac80211.h Introduction +!Pinclude/net/mac80211.h Warning + </abstract> + </bookinfo> + + <toc></toc> + + <!-- + Generally, this document shall be ordered by increasing complexity. + It is important to note that readers should be able to read only + the first few sections to get a working driver and only advanced + usage should require reading the full document. + --> + + <part> + <title>The basic mac80211 driver interface</title> + <partintro> + <para> + You should read and understand the information contained + within this part of the book while implementing a driver. + In some chapters, advanced usage is noted, that may be + skipped at first. + </para> + <para> + This part of the book only covers station and monitor mode + functionality, additional information required to implement + the other modes is covered in the second part of the book. + </para> + </partintro> + + <chapter id="basics"> + <title>Basic hardware handling</title> + <para>TBD</para> + <para> + This chapter shall contain information on getting a hw + struct allocated and registered with mac80211. + </para> + <para> + Since it is required to allocate rates/modes before registering + a hw struct, this chapter shall also contain information on setting + up the rate/mode structs. + </para> + <para> + Additionally, some discussion about the callbacks and + the general programming model should be in here, including + the definition of ieee80211_ops which will be referred to + a lot. + </para> + <para> + Finally, a discussion of hardware capabilities should be done + with references to other parts of the book. + </para> + <!-- intentionally multiple !F lines to get proper order --> +!Finclude/net/mac80211.h ieee80211_hw +!Finclude/net/mac80211.h ieee80211_hw_flags +!Finclude/net/mac80211.h SET_IEEE80211_DEV +!Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR +!Finclude/net/mac80211.h ieee80211_ops +!Finclude/net/mac80211.h ieee80211_alloc_hw +!Finclude/net/mac80211.h ieee80211_register_hw +!Finclude/net/mac80211.h ieee80211_get_tx_led_name +!Finclude/net/mac80211.h ieee80211_get_rx_led_name +!Finclude/net/mac80211.h ieee80211_get_assoc_led_name +!Finclude/net/mac80211.h ieee80211_get_radio_led_name +!Finclude/net/mac80211.h ieee80211_unregister_hw +!Finclude/net/mac80211.h ieee80211_free_hw + </chapter> + + <chapter id="phy-handling"> + <title>PHY configuration</title> + <para>TBD</para> + <para> + This chapter should describe PHY handling including + start/stop callbacks and the various structures used. + </para> +!Finclude/net/mac80211.h ieee80211_conf +!Finclude/net/mac80211.h ieee80211_conf_flags + </chapter> + + <chapter id="iface-handling"> + <title>Virtual interfaces</title> + <para>TBD</para> + <para> + This chapter should describe virtual interface basics + that are relevant to the driver (VLANs, MGMT etc are not.) + It should explain the use of the add_iface/remove_iface + callbacks as well as the interface configuration callbacks. + </para> + <para>Things related to AP mode should be discussed there.</para> + <para> + Things related to supporting multiple interfaces should be + in the appropriate chapter, a BIG FAT note should be here about + this though and the recommendation to allow only a single + interface in STA mode at first! + </para> +!Finclude/net/mac80211.h ieee80211_vif + </chapter> + + <chapter id="rx-tx"> + <title>Receive and transmit processing</title> + <sect1> + <title>what should be here</title> + <para>TBD</para> + <para> + This should describe the receive and transmit + paths in mac80211/the drivers as well as + transmit status handling. + </para> + </sect1> + <sect1> + <title>Frame format</title> +!Pinclude/net/mac80211.h Frame format + </sect1> + <sect1> + <title>Packet alignment</title> +!Pnet/mac80211/rx.c Packet alignment + </sect1> + <sect1> + <title>Calling into mac80211 from interrupts</title> +!Pinclude/net/mac80211.h Calling mac80211 from interrupts + </sect1> + <sect1> + <title>functions/definitions</title> +!Finclude/net/mac80211.h ieee80211_rx_status +!Finclude/net/mac80211.h mac80211_rx_flags +!Finclude/net/mac80211.h ieee80211_tx_info +!Finclude/net/mac80211.h ieee80211_rx +!Finclude/net/mac80211.h ieee80211_rx_irqsafe +!Finclude/net/mac80211.h ieee80211_tx_status +!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe +!Finclude/net/mac80211.h ieee80211_rts_get +!Finclude/net/mac80211.h ieee80211_rts_duration +!Finclude/net/mac80211.h ieee80211_ctstoself_get +!Finclude/net/mac80211.h ieee80211_ctstoself_duration +!Finclude/net/mac80211.h ieee80211_generic_frame_duration +!Finclude/net/mac80211.h ieee80211_wake_queue +!Finclude/net/mac80211.h ieee80211_stop_queue +!Finclude/net/mac80211.h ieee80211_wake_queues +!Finclude/net/mac80211.h ieee80211_stop_queues + </sect1> + </chapter> + + <chapter id="filters"> + <title>Frame filtering</title> +!Pinclude/net/mac80211.h Frame filtering +!Finclude/net/mac80211.h ieee80211_filter_flags + </chapter> + </part> + + <part id="advanced"> + <title>Advanced driver interface</title> + <partintro> + <para> + Information contained within this part of the book is + of interest only for advanced interaction of mac80211 + with drivers to exploit more hardware capabilities and + improve performance. + </para> + </partintro> + + <chapter id="hardware-crypto-offload"> + <title>Hardware crypto acceleration</title> +!Pinclude/net/mac80211.h Hardware crypto acceleration + <!-- intentionally multiple !F lines to get proper order --> +!Finclude/net/mac80211.h set_key_cmd +!Finclude/net/mac80211.h ieee80211_key_conf +!Finclude/net/mac80211.h ieee80211_key_flags + </chapter> + + <chapter id="powersave"> + <title>Powersave support</title> +!Pinclude/net/mac80211.h Powersave support + </chapter> + + <chapter id="beacon-filter"> + <title>Beacon filter support</title> +!Pinclude/net/mac80211.h Beacon filter support +!Finclude/net/mac80211.h ieee80211_beacon_loss + </chapter> + + <chapter id="qos"> + <title>Multiple queues and QoS support</title> + <para>TBD</para> +!Finclude/net/mac80211.h ieee80211_tx_queue_params + </chapter> + + <chapter id="AP"> + <title>Access point mode support</title> + <para>TBD</para> + <para>Some parts of the if_conf should be discussed here instead</para> + <para> + Insert notes about VLAN interfaces with hw crypto here or + in the hw crypto chapter. + </para> +!Finclude/net/mac80211.h ieee80211_get_buffered_bc +!Finclude/net/mac80211.h ieee80211_beacon_get + </chapter> + + <chapter id="multi-iface"> + <title>Supporting multiple virtual interfaces</title> + <para>TBD</para> + <para> + Note: WDS with identical MAC address should almost always be OK + </para> + <para> + Insert notes about having multiple virtual interfaces with + different MAC addresses here, note which configurations are + supported by mac80211, add notes about supporting hw crypto + with it. + </para> + </chapter> + + <chapter id="hardware-scan-offload"> + <title>Hardware scan offload</title> + <para>TBD</para> +!Finclude/net/mac80211.h ieee80211_scan_completed + </chapter> + </part> + + <part id="rate-control"> + <title>Rate control interface</title> + <partintro> + <para>TBD</para> + <para> + This part of the book describes the rate control algorithm + interface and how it relates to mac80211 and drivers. + </para> + </partintro> + <chapter id="dummy"> + <title>dummy chapter</title> + <para>TBD</para> + </chapter> + </part> + + <part id="internal"> + <title>Internals</title> + <partintro> + <para>TBD</para> + <para> + This part of the book describes mac80211 internals. + </para> + </partintro> + + <chapter id="key-handling"> + <title>Key handling</title> + <sect1> + <title>Key handling basics</title> +!Pnet/mac80211/key.c Key handling basics + </sect1> + <sect1> + <title>MORE TBD</title> + <para>TBD</para> + </sect1> + </chapter> + + <chapter id="rx-processing"> + <title>Receive processing</title> + <para>TBD</para> + </chapter> + + <chapter id="tx-processing"> + <title>Transmit processing</title> + <para>TBD</para> + </chapter> + + <chapter id="sta-info"> + <title>Station info handling</title> + <sect1> + <title>Programming information</title> +!Fnet/mac80211/sta_info.h sta_info +!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags + </sect1> + <sect1> + <title>STA information lifetime rules</title> +!Pnet/mac80211/sta_info.c STA information lifetime rules + </sect1> + </chapter> + + <chapter id="synchronisation"> + <title>Synchronisation</title> + <para>TBD</para> + <para>Locking, lots of RCU</para> + </chapter> + </part> + </book> +</set> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index c7e5dc7e8cb..8b6e00a7103 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -12,7 +12,7 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ - mac80211.xml debugobjects.xml sh.xml regulator.xml \ + 80211.xml debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ tracepoint.xml media.xml drm.xml @@ -35,7 +35,7 @@ PS_METHOD = $(prefer-db2x) PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs xmldoclinks BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) -xmldocs: $(BOOKS) xmldoclinks +xmldocs: $(BOOKS) sgmldocs: xmldocs PS := $(patsubst %.xml, %.ps, $(BOOKS)) @@ -45,7 +45,7 @@ PDF := $(patsubst %.xml, %.pdf, $(BOOKS)) pdfdocs: $(PDF) HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) -htmldocs: $(HTML) +htmldocs: $(HTML) xmldoclinks $(call build_main_index) $(call build_images) @@ -95,7 +95,7 @@ define rule_docproc ) > $(dir $@).$(notdir $@).cmd endef -%.xml: %.tmpl FORCE +%.xml: %.tmpl xmldoclinks FORCE $(call if_changed_rule,docproc) ### diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 1b2dd4fc3db..22edcbb9dda 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -46,14 +46,18 @@ <sect1><title>Atomic and pointer manipulation</title> !Iarch/x86/include/asm/atomic.h -!Iarch/x86/include/asm/unaligned.h </sect1> <sect1><title>Delaying, scheduling, and timer routines</title> !Iinclude/linux/sched.h !Ekernel/sched.c +!Iinclude/linux/completion.h !Ekernel/timer.c </sect1> + <sect1><title>Wait queues and Wake events</title> +!Iinclude/linux/wait.h +!Ekernel/wait.c + </sect1> <sect1><title>High-resolution timers</title> !Iinclude/linux/ktime.h !Iinclude/linux/hrtimer.h @@ -111,6 +115,7 @@ X!Edrivers/base/attribute_container.c <!-- X!Edrivers/base/interface.c --> +!Iinclude/linux/platform_device.h !Edrivers/base/platform.c !Edrivers/base/bus.c </sect1> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 910c923a9b8..2861055afd7 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -136,6 +136,7 @@ #ifdef CONFIG_COMPAT .compat_ioctl = i915_compat_ioctl, #endif + .llseek = noop_llseek, }, .pci_driver = { .name = DRIVER_NAME, diff --git a/Documentation/DocBook/dvb/dvbapi.xml b/Documentation/DocBook/dvb/dvbapi.xml index 63c528fee62..e3a97fdd62a 100644 --- a/Documentation/DocBook/dvb/dvbapi.xml +++ b/Documentation/DocBook/dvb/dvbapi.xml @@ -12,10 +12,12 @@ <othername role="mi">O. C.</othername> <affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> </author> +</authorgroup> +<authorgroup> <author> <firstname>Mauro</firstname> -<surname>Chehab</surname> <othername role="mi">Carvalho</othername> +<surname>Chehab</surname> <affiliation><address><email>mchehab@redhat.com</email></address></affiliation> <contrib>Ported document to Docbook XML.</contrib> </author> @@ -23,13 +25,24 @@ <copyright> <year>2002</year> <year>2003</year> - <year>2009</year> <holder>Convergence GmbH</holder> </copyright> +<copyright> + <year>2009-2010</year> + <holder>Mauro Carvalho Chehab</holder> +</copyright> <revhistory> <!-- Put document revisions here, newest first. --> <revision> + <revnumber>2.0.3</revnumber> + <date>2010-07-03</date> + <authorinitials>mcc</authorinitials> + <revremark> + Add some frontend capabilities flags, present on kernel, but missing at the specs. + </revremark> +</revision> +<revision> <revnumber>2.0.2</revnumber> <date>2009-10-25</date> <authorinitials>mcc</authorinitials> @@ -63,7 +76,7 @@ Added ISDB-T test originally written by Patrick Boettcher <title>LINUX DVB API</title> -<subtitle>Version 3</subtitle> +<subtitle>Version 5.2</subtitle> <!-- ADD THE CHAPTERS HERE --> <chapter id="dvb_introdution"> &sub-intro; diff --git a/Documentation/DocBook/dvb/frontend.h.xml b/Documentation/DocBook/dvb/frontend.h.xml index b99644f5340..d08e0d40141 100644 --- a/Documentation/DocBook/dvb/frontend.h.xml +++ b/Documentation/DocBook/dvb/frontend.h.xml @@ -63,6 +63,7 @@ typedef enum fe_caps { FE_CAN_8VSB = 0x200000, FE_CAN_16VSB = 0x400000, FE_HAS_EXTENDED_CAPS = 0x800000, /* We need more bitspace for newer APIs, indicate this. */ + FE_CAN_TURBO_FEC = 0x8000000, /* frontend supports "turbo fec modulation" */ FE_CAN_2G_MODULATION = 0x10000000, /* frontend supports "2nd generation modulation" (DVB-S2) */ FE_NEEDS_BENDING = 0x20000000, /* not supported anymore, don't use (frontend requires frequency bending) */ FE_CAN_RECOVER = 0x40000000, /* frontend can recover from a cable unplug automatically */ diff --git a/Documentation/DocBook/dvb/frontend.xml b/Documentation/DocBook/dvb/frontend.xml index 300ba1f0417..78d756de590 100644 --- a/Documentation/DocBook/dvb/frontend.xml +++ b/Documentation/DocBook/dvb/frontend.xml @@ -64,8 +64,14 @@ a specific frontend type.</para> FE_CAN_BANDWIDTH_AUTO = 0x40000, FE_CAN_GUARD_INTERVAL_AUTO = 0x80000, FE_CAN_HIERARCHY_AUTO = 0x100000, - FE_CAN_MUTE_TS = 0x80000000, - FE_CAN_CLEAN_SETUP = 0x40000000 + FE_CAN_8VSB = 0x200000, + FE_CAN_16VSB = 0x400000, + FE_HAS_EXTENDED_CAPS = 0x800000, + FE_CAN_TURBO_FEC = 0x8000000, + FE_CAN_2G_MODULATION = 0x10000000, + FE_NEEDS_BENDING = 0x20000000, + FE_CAN_RECOVER = 0x40000000, + FE_CAN_MUTE_TS = 0x80000000 } fe_caps_t; </programlisting> </section> diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl index 1448b33fd22..fb10fd08c05 100644 --- a/Documentation/DocBook/genericirq.tmpl +++ b/Documentation/DocBook/genericirq.tmpl @@ -28,7 +28,7 @@ </authorgroup> <copyright> - <year>2005-2006</year> + <year>2005-2010</year> <holder>Thomas Gleixner</holder> </copyright> <copyright> @@ -100,6 +100,10 @@ <listitem><para>Edge type</para></listitem> <listitem><para>Simple type</para></listitem> </itemizedlist> + During the implementation we identified another type: + <itemizedlist> + <listitem><para>Fast EOI type</para></listitem> + </itemizedlist> In the SMP world of the __do_IRQ() super-handler another type was identified: <itemizedlist> @@ -153,6 +157,7 @@ is still available. This leads to a kind of duality for the time being. Over time the new model should be used in more and more architectures, as it enables smaller and cleaner IRQ subsystems. + It's deprecated for three years now and about to be removed. </para> </chapter> <chapter id="bugs"> @@ -217,6 +222,7 @@ <itemizedlist> <listitem><para>handle_level_irq</para></listitem> <listitem><para>handle_edge_irq</para></listitem> + <listitem><para>handle_fasteoi_irq</para></listitem> <listitem><para>handle_simple_irq</para></listitem> <listitem><para>handle_percpu_irq</para></listitem> </itemizedlist> @@ -233,33 +239,33 @@ are used by the default flow implementations. The following helper functions are implemented (simplified excerpt): <programlisting> -default_enable(irq) +default_enable(struct irq_data *data) { - desc->chip->unmask(irq); + desc->chip->irq_unmask(data); } -default_disable(irq) +default_disable(struct irq_data *data) { - if (!delay_disable(irq)) - desc->chip->mask(irq); + if (!delay_disable(data)) + desc->chip->irq_mask(data); } -default_ack(irq) +default_ack(struct irq_data *data) { - chip->ack(irq); + chip->irq_ack(data); } -default_mask_ack(irq) +default_mask_ack(struct irq_data *data) { - if (chip->mask_ack) { - chip->mask_ack(irq); + if (chip->irq_mask_ack) { + chip->irq_mask_ack(data); } else { - chip->mask(irq); - chip->ack(irq); + chip->irq_mask(data); + chip->irq_ack(data); } } -noop(irq) +noop(struct irq_data *data)) { } @@ -278,12 +284,27 @@ noop(irq) <para> The following control flow is implemented (simplified excerpt): <programlisting> -desc->chip->start(); +desc->chip->irq_mask(); handle_IRQ_event(desc->action); -desc->chip->end(); +desc->chip->irq_unmask(); </programlisting> </para> - </sect3> + </sect3> + <sect3 id="Default_FASTEOI_IRQ_flow_handler"> + <title>Default Fast EOI IRQ flow handler</title> + <para> + handle_fasteoi_irq provides a generic implementation + for interrupts, which only need an EOI at the end of + the handler + </para> + <para> + The following control flow is implemented (simplified excerpt): + <programlisting> +handle_IRQ_event(desc->action); +desc->chip->irq_eoi(); + </programlisting> + </para> + </sect3> <sect3 id="Default_Edge_IRQ_flow_handler"> <title>Default Edge IRQ flow handler</title> <para> @@ -294,20 +315,19 @@ desc->chip->end(); The following control flow is implemented (simplified excerpt): <programlisting> if (desc->status & running) { - desc->chip->hold(); + desc->chip->irq_mask(); desc->status |= pending | masked; return; } -desc->chip->start(); +desc->chip->irq_ack(); desc->status |= running; do { if (desc->status & masked) - desc->chip->enable(); + desc->chip->irq_unmask(); desc->status &= ~pending; handle_IRQ_event(desc->action); } while (status & pending); desc->status &= ~running; -desc->chip->end(); </programlisting> </para> </sect3> @@ -342,9 +362,9 @@ handle_IRQ_event(desc->action); <para> The following control flow is implemented (simplified excerpt): <programlisting> -desc->chip->start(); handle_IRQ_event(desc->action); -desc->chip->end(); +if (desc->chip->irq_eoi) + desc->chip->irq_eoi(); </programlisting> </para> </sect3> @@ -375,8 +395,7 @@ desc->chip->end(); mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use the delayed interrupt disable feature and your hardware is not capable of retriggering an interrupt.) - The delayed interrupt disable can be runtime enabled, per interrupt, - by setting the IRQ_DELAYED_DISABLE flag in the irq_desc status field. + The delayed interrupt disable is not configurable. </para> </sect2> </sect1> @@ -387,13 +406,13 @@ desc->chip->end(); contains all the direct chip relevant functions, which can be utilized by the irq flow implementations. <itemizedlist> - <listitem><para>ack()</para></listitem> - <listitem><para>mask_ack() - Optional, recommended for performance</para></listitem> - <listitem><para>mask()</para></listitem> - <listitem><para>unmask()</para></listitem> - <listitem><para>retrigger() - Optional</para></listitem> - <listitem><para>set_type() - Optional</para></listitem> - <listitem><para>set_wake() - Optional</para></listitem> + <listitem><para>irq_ack()</para></listitem> + <listitem><para>irq_mask_ack() - Optional, recommended for performance</para></listitem> + <listitem><para>irq_mask()</para></listitem> + <listitem><para>irq_unmask()</para></listitem> + <listitem><para>irq_retrigger() - Optional</para></listitem> + <listitem><para>irq_set_type() - Optional</para></listitem> + <listitem><para>irq_set_wake() - Optional</para></listitem> </itemizedlist> These primitives are strictly intended to mean what they say: ack means ACK, masking means masking of an IRQ line, etc. It is up to the flow @@ -458,6 +477,7 @@ desc->chip->end(); <para> This chapter contains the autogenerated documentation of the internal functions. </para> +!Ikernel/irq/irqdesc.c !Ikernel/irq/handle.c !Ikernel/irq/chip.c </chapter> diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 44b3def961a..7160652a873 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -57,7 +57,6 @@ </para> <sect1><title>String Conversions</title> -!Ilib/vsprintf.c !Elib/vsprintf.c </sect1> <sect1><title>String Manipulation</title> @@ -94,6 +93,12 @@ X!Ilib/string.c !Elib/crc32.c !Elib/crc-ccitt.c </sect1> + + <sect1 id="idr"><title>idr/ida Functions</title> +!Pinclude/linux/idr.h idr sync +!Plib/idr.c IDA description +!Elib/idr.c + </sect1> </chapter> <chapter id="mm"> @@ -132,7 +137,6 @@ X!Ilib/string.c <title>FIFO Buffer</title> <sect1><title>kfifo interface</title> !Iinclude/linux/kfifo.h -!Ekernel/kfifo.c </sect1> </chapter> @@ -259,7 +263,8 @@ X!Earch/x86/kernel/mca_32.c !Iblock/blk-sysfs.c !Eblock/blk-settings.c !Eblock/blk-exec.c -!Eblock/blk-barrier.c +!Eblock/blk-flush.c +!Eblock/blk-lib.c !Eblock/blk-tag.c !Iblock/blk-tag.c !Eblock/blk-integrity.c diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl index 084f6ad7b7a..f66f4df1869 100644 --- a/Documentation/DocBook/kernel-locking.tmpl +++ b/Documentation/DocBook/kernel-locking.tmpl @@ -1645,7 +1645,9 @@ the amount of locking which needs to be done. all the readers who were traversing the list when we deleted the element are finished. We use <function>call_rcu()</function> to register a callback which will actually destroy the object once - the readers are finished. + all pre-existing readers are finished. Alternatively, + <function>synchronize_rcu()</function> may be used to block until + all pre-existing are finished. </para> <para> But how does Read Copy Update know when the readers are @@ -1714,7 +1716,7 @@ the amount of locking which needs to be done. - object_put(obj); + list_del_rcu(&obj->list); cache_num--; -+ call_rcu(&obj->rcu, cache_delete_rcu, obj); ++ call_rcu(&obj->rcu, cache_delete_rcu); } /* Must be holding cache_lock */ @@ -1725,14 +1727,6 @@ the amount of locking which needs to be done. if (++cache_num > MAX_CACHE_SIZE) { struct object *i, *outcast = NULL; list_for_each_entry(i, &cache, list) { -@@ -85,6 +94,7 @@ - obj->popularity = 0; - atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ - spin_lock_init(&obj->lock); -+ INIT_RCU_HEAD(&obj->rcu); - - spin_lock_irqsave(&cache_lock, flags); - __cache_add(obj); @@ -104,12 +114,11 @@ struct object *cache_find(int id) { @@ -1922,9 +1916,12 @@ machines due to caching. <function>mutex_lock()</function> </para> <para> - There is a <function>mutex_trylock()</function> which can be - used inside interrupt context, as it will not sleep. + There is a <function>mutex_trylock()</function> which does not + sleep. Still, it must not be used inside interrupt context since + its implementation is not safe for that. <function>mutex_unlock()</function> will also never sleep. + It cannot be used in interrupt context either since a mutex + must be released by the same task that acquired it. </para> </listitem> </itemizedlist> @@ -1958,6 +1955,12 @@ machines due to caching. </sect1> </chapter> + <chapter id="apiref"> + <title>Mutex API reference</title> +!Iinclude/linux/mutex.h +!Ekernel/mutex.c + </chapter> + <chapter id="references"> <title>Further reading</title> diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl index 55f12ac37ac..d71b57fcf11 100644 --- a/Documentation/DocBook/kgdb.tmpl +++ b/Documentation/DocBook/kgdb.tmpl @@ -199,10 +199,33 @@ may be configured as a kernel built-in or a kernel loadable module. You can only make use of <constant>kgdbwait</constant> and early debugging if you build kgdboc into the kernel as a built-in. + <para>Optionally you can elect to activate kms (Kernel Mode + Setting) integration. When you use kms with kgdboc and you have a + video driver that has atomic mode setting hooks, it is possible to + enter the debugger on the graphics console. When the kernel + execution is resumed, the previous graphics mode will be restored. + This integration can serve as a useful tool to aid in diagnosing + crashes or doing analysis of memory with kdb while allowing the + full graphics console applications to run. + </para> </para> <sect2 id="kgdbocArgs"> <title>kgdboc arguments</title> - <para>Usage: <constant>kgdboc=[kbd][[,]serial_device][,baud]</constant></para> + <para>Usage: <constant>kgdboc=[kms][[,]kbd][[,]serial_device][,baud]</constant></para> + <para>The order listed above must be observed if you use any of the + optional configurations together. + </para> + <para>Abbreviations: + <itemizedlist> + <listitem><para>kms = Kernel Mode Setting</para></listitem> + <listitem><para>kbd = Keyboard</para></listitem> + </itemizedlist> + </para> + <para>You can configure kgdboc to use the keyboard, and or a serial + device depending on if you are using kdb and or kgdb, in one of the + following scenarios. The order listed above must be observed if + you use any of the optional configurations together. Using kms + + only gdb is generally not a useful combination.</para> <sect3 id="kgdbocArgs1"> <title>Using loadable module or built-in</title> <para> @@ -212,7 +235,7 @@ <listitem> <para>As a kernel loadable module:</para> <para>Use the command: <constant>modprobe kgdboc kgdboc=<tty-device>,[baud]</constant></para> - <para>Here are two examples of how you might formate the kgdboc + <para>Here are two examples of how you might format the kgdboc string. The first is for an x86 target using the first serial port. The second example is for the ARM Versatile AB using the second serial port. @@ -240,6 +263,9 @@ </sect3> <sect3 id="kgdbocArgs3"> <title>More examples</title> + <para>You can configure kgdboc to use the keyboard, and or a serial + device depending on if you are using kdb and or kgdb, in one of the + following scenarios.</para> <para>You can configure kgdboc to use the keyboard, and or a serial device depending on if you are using kdb and or kgdb, in one of the following scenarios. @@ -255,6 +281,12 @@ <listitem><para>kdb with a keyboard</para> <para><constant>kgdboc=kbd</constant></para> </listitem> + <listitem><para>kdb with kernel mode setting</para> + <para><constant>kgdboc=kms,kbd</constant></para> + </listitem> + <listitem><para>kdb with kernel mode setting and kgdb over a serial port</para> + <para><constant>kgdboc=kms,kbd,ttyS0,115200</constant></para> + </listitem> </orderedlist> </para> </sect3> @@ -637,6 +669,8 @@ Task Addr Pid Parent [*] cpu State Thread Command <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem> <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem> <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem> + <listitem><para>The structures and callback API for atomic kernel mode setting.</para> + <para>NOTE: kgdboc is where the kms callbacks are invoked.</para></listitem> </itemizedlist> </para> </listitem> @@ -676,7 +710,18 @@ Task Addr Pid Parent [*] cpu State Thread Command <listitem><para>A simple shell</para></listitem> <listitem><para>The kdb core command set</para></listitem> <listitem><para>A registration API to register additional kdb shell commands.</para> - <para>A good example of a self-contained kdb module is the "ftdump" command for dumping the ftrace buffer. See: kernel/trace/trace_kdb.c</para></listitem> + <itemizedlist> + <listitem><para>A good example of a self-contained kdb module + is the "ftdump" command for dumping the ftrace buffer. See: + kernel/trace/trace_kdb.c</para></listitem> + <listitem><para>For an example of how to dynamically register + a new kdb command you can build the kdb_hello.ko kernel module + from samples/kdb/kdb_hello.c. To build this example you can + set CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel + config. Later run "modprobe kdb_hello" and the next time you + enter the kdb shell, you can run the "hello" + command.</para></listitem> + </itemizedlist></listitem> <listitem><para>The implementation for kdb_printf() which emits messages directly to I/O drivers, bypassing the kernel log.</para></listitem> @@ -747,6 +792,8 @@ Task Addr Pid Parent [*] cpu State Thread Command </sect1> <sect1 id="kgdbocDesign"> <title>kgdboc internals</title> + <sect2> + <title>kgdboc and uarts</title> <para> The kgdboc driver is actually a very thin driver that relies on the underlying low level to the hardware driver having "polling hooks" @@ -754,11 +801,8 @@ Task Addr Pid Parent [*] cpu State Thread Command implementation of kgdboc it the serial_core was changed to expose a low level UART hook for doing polled mode reading and writing of a single character while in an atomic context. When kgdb makes an I/O - request to the debugger, kgdboc invokes a call back in the serial - core which in turn uses the call back in the UART driver. It is - certainly possible to extend kgdboc to work with non-UART based - consoles in the future. - </para> + request to the debugger, kgdboc invokes a callback in the serial + core which in turn uses the callback in the UART driver.</para> <para> When using kgdboc with a UART, the UART driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting> #ifdef CONFIG_CONSOLE_POLL @@ -772,9 +816,68 @@ Task Addr Pid Parent [*] cpu State Thread Command that they can be called from an atomic context and have to restore the state of the UART chip on return such that the system can return to normal when the debugger detaches. You need to be very careful - with any kind of lock you consider, because failing here is most + with any kind of lock you consider, because failing here is most likely going to mean pressing the reset button. </para> + </sect2> + <sect2 id="kgdbocKbd"> + <title>kgdboc and keyboards</title> + <para>The kgdboc driver contains logic to configure communications + with an attached keyboard. The keyboard infrastructure is only + compiled into the kernel when CONFIG_KDB_KEYBOARD=y is set in the + kernel configuration.</para> + <para>The core polled keyboard driver driver for PS/2 type keyboards + is in drivers/char/kdb_keyboard.c. This driver is hooked into the + debug core when kgdboc populates the callback in the array + called <constant>kdb_poll_funcs[]</constant>. The + kdb_get_kbd_char() is the top-level function which polls hardware + for single character input. + </para> + </sect2> + <sect2 id="kgdbocKms"> + <title>kgdboc and kms</title> + <para>The kgdboc driver contains logic to request the graphics + display to switch to a text context when you are using + "kgdboc=kms,kbd", provided that you have a video driver which has a + frame buffer console and atomic kernel mode setting support.</para> + <para> + Every time the kernel + debugger is entered it calls kgdboc_pre_exp_handler() which in turn + calls con_debug_enter() in the virtual console layer. On resuming kernel + execution, the kernel debugger calls kgdboc_post_exp_handler() which + in turn calls con_debug_leave().</para> + <para>Any video driver that wants to be compatible with the kernel + debugger and the atomic kms callbacks must implement the + mode_set_base_atomic, fb_debug_enter and fb_debug_leave operations. + For the fb_debug_enter and fb_debug_leave the option exists to use + the generic drm fb helper functions or implement something custom for + the hardware. The following example shows the initialization of the + .mode_set_base_atomic operation in + drivers/gpu/drm/i915/intel_display.c: + <informalexample> + <programlisting> +static const struct drm_crtc_helper_funcs intel_helper_funcs = { +[...] + .mode_set_base_atomic = intel_pipe_set_base_atomic, +[...] +}; + </programlisting> + </informalexample> + </para> + <para>Here is an example of how the i915 driver initializes the fb_debug_enter and fb_debug_leave functions to use the generic drm helpers in + drivers/gpu/drm/i915/intel_fb.c: + <informalexample> + <programlisting> +static struct fb_ops intelfb_ops = { +[...] + .fb_debug_enter = drm_fb_helper_debug_enter, + .fb_debug_leave = drm_fb_helper_debug_leave, +[...] +}; + </programlisting> + </informalexample> + </para> + </sect2> </sect1> </chapter> <chapter id="credits"> diff --git a/Documentation/DocBook/mac80211.tmpl b/Documentation/DocBook/mac80211.tmpl deleted file mode 100644 index affb15a344a..00000000000 --- a/Documentation/DocBook/mac80211.tmpl +++ /dev/null @@ -1,337 +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="mac80211-developers-guide"> - <bookinfo> - <title>The mac80211 subsystem for kernel developers</title> - - <authorgroup> - <author> - <firstname>Johannes</firstname> - <surname>Berg</surname> - <affiliation> - <address><email>johannes@sipsolutions.net</email></address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2007-2009</year> - <holder>Johannes Berg</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 version 2 as published by the Free Software Foundation. - </para> - - <para> - This documentation 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 documentation; 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> - - <abstract> -!Pinclude/net/mac80211.h Introduction -!Pinclude/net/mac80211.h Warning - </abstract> - </bookinfo> - - <toc></toc> - -<!-- -Generally, this document shall be ordered by increasing complexity. -It is important to note that readers should be able to read only -the first few sections to get a working driver and only advanced -usage should require reading the full document. ---> - - <part> - <title>The basic mac80211 driver interface</title> - <partintro> - <para> - You should read and understand the information contained - within this part of the book while implementing a driver. - In some chapters, advanced usage is noted, that may be - skipped at first. - </para> - <para> - This part of the book only covers station and monitor mode - functionality, additional information required to implement - the other modes is covered in the second part of the book. - </para> - </partintro> - - <chapter id="basics"> - <title>Basic hardware handling</title> - <para>TBD</para> - <para> - This chapter shall contain information on getting a hw - struct allocated and registered with mac80211. - </para> - <para> - Since it is required to allocate rates/modes before registering - a hw struct, this chapter shall also contain information on setting - up the rate/mode structs. - </para> - <para> - Additionally, some discussion about the callbacks and - the general programming model should be in here, including - the definition of ieee80211_ops which will be referred to - a lot. - </para> - <para> - Finally, a discussion of hardware capabilities should be done - with references to other parts of the book. - </para> -<!-- intentionally multiple !F lines to get proper order --> -!Finclude/net/mac80211.h ieee80211_hw -!Finclude/net/mac80211.h ieee80211_hw_flags -!Finclude/net/mac80211.h SET_IEEE80211_DEV -!Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR -!Finclude/net/mac80211.h ieee80211_ops -!Finclude/net/mac80211.h ieee80211_alloc_hw -!Finclude/net/mac80211.h ieee80211_register_hw -!Finclude/net/mac80211.h ieee80211_get_tx_led_name -!Finclude/net/mac80211.h ieee80211_get_rx_led_name -!Finclude/net/mac80211.h ieee80211_get_assoc_led_name -!Finclude/net/mac80211.h ieee80211_get_radio_led_name -!Finclude/net/mac80211.h ieee80211_unregister_hw -!Finclude/net/mac80211.h ieee80211_free_hw - </chapter> - - <chapter id="phy-handling"> - <title>PHY configuration</title> - <para>TBD</para> - <para> - This chapter should describe PHY handling including - start/stop callbacks and the various structures used. - </para> -!Finclude/net/mac80211.h ieee80211_conf -!Finclude/net/mac80211.h ieee80211_conf_flags - </chapter> - - <chapter id="iface-handling"> - <title>Virtual interfaces</title> - <para>TBD</para> - <para> - This chapter should describe virtual interface basics - that are relevant to the driver (VLANs, MGMT etc are not.) - It should explain the use of the add_iface/remove_iface - callbacks as well as the interface configuration callbacks. - </para> - <para>Things related to AP mode should be discussed there.</para> - <para> - Things related to supporting multiple interfaces should be - in the appropriate chapter, a BIG FAT note should be here about - this though and the recommendation to allow only a single - interface in STA mode at first! - </para> -!Finclude/net/mac80211.h ieee80211_vif - </chapter> - - <chapter id="rx-tx"> - <title>Receive and transmit processing</title> - <sect1> - <title>what should be here</title> - <para>TBD</para> - <para> - This should describe the receive and transmit - paths in mac80211/the drivers as well as - transmit status handling. - </para> - </sect1> - <sect1> - <title>Frame format</title> -!Pinclude/net/mac80211.h Frame format - </sect1> - <sect1> - <title>Packet alignment</title> -!Pnet/mac80211/rx.c Packet alignment - </sect1> - <sect1> - <title>Calling into mac80211 from interrupts</title> -!Pinclude/net/mac80211.h Calling mac80211 from interrupts - </sect1> - <sect1> - <title>functions/definitions</title> -!Finclude/net/mac80211.h ieee80211_rx_status -!Finclude/net/mac80211.h mac80211_rx_flags -!Finclude/net/mac80211.h ieee80211_tx_info -!Finclude/net/mac80211.h ieee80211_rx -!Finclude/net/mac80211.h ieee80211_rx_irqsafe -!Finclude/net/mac80211.h ieee80211_tx_status -!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe -!Finclude/net/mac80211.h ieee80211_rts_get -!Finclude/net/mac80211.h ieee80211_rts_duration -!Finclude/net/mac80211.h ieee80211_ctstoself_get -!Finclude/net/mac80211.h ieee80211_ctstoself_duration -!Finclude/net/mac80211.h ieee80211_generic_frame_duration -!Finclude/net/mac80211.h ieee80211_wake_queue -!Finclude/net/mac80211.h ieee80211_stop_queue -!Finclude/net/mac80211.h ieee80211_wake_queues -!Finclude/net/mac80211.h ieee80211_stop_queues - </sect1> - </chapter> - - <chapter id="filters"> - <title>Frame filtering</title> -!Pinclude/net/mac80211.h Frame filtering -!Finclude/net/mac80211.h ieee80211_filter_flags - </chapter> - </part> - - <part id="advanced"> - <title>Advanced driver interface</title> - <partintro> - <para> - Information contained within this part of the book is - of interest only for advanced interaction of mac80211 - with drivers to exploit more hardware capabilities and - improve performance. - </para> - </partintro> - - <chapter id="hardware-crypto-offload"> - <title>Hardware crypto acceleration</title> -!Pinclude/net/mac80211.h Hardware crypto acceleration -<!-- intentionally multiple !F lines to get proper order --> -!Finclude/net/mac80211.h set_key_cmd -!Finclude/net/mac80211.h ieee80211_key_conf -!Finclude/net/mac80211.h ieee80211_key_alg -!Finclude/net/mac80211.h ieee80211_key_flags - </chapter> - - <chapter id="powersave"> - <title>Powersave support</title> -!Pinclude/net/mac80211.h Powersave support - </chapter> - - <chapter id="beacon-filter"> - <title>Beacon filter support</title> -!Pinclude/net/mac80211.h Beacon filter support -!Finclude/net/mac80211.h ieee80211_beacon_loss - </chapter> - - <chapter id="qos"> - <title>Multiple queues and QoS support</title> - <para>TBD</para> -!Finclude/net/mac80211.h ieee80211_tx_queue_params - </chapter> - - <chapter id="AP"> - <title>Access point mode support</title> - <para>TBD</para> - <para>Some parts of the if_conf should be discussed here instead</para> - <para> - Insert notes about VLAN interfaces with hw crypto here or - in the hw crypto chapter. - </para> -!Finclude/net/mac80211.h ieee80211_get_buffered_bc -!Finclude/net/mac80211.h ieee80211_beacon_get - </chapter> - - <chapter id="multi-iface"> - <title>Supporting multiple virtual interfaces</title> - <para>TBD</para> - <para> - Note: WDS with identical MAC address should almost always be OK - </para> - <para> - Insert notes about having multiple virtual interfaces with - different MAC addresses here, note which configurations are - supported by mac80211, add notes about supporting hw crypto - with it. - </para> - </chapter> - - <chapter id="hardware-scan-offload"> - <title>Hardware scan offload</title> - <para>TBD</para> -!Finclude/net/mac80211.h ieee80211_scan_completed - </chapter> - </part> - - <part id="rate-control"> - <title>Rate control interface</title> - <partintro> - <para>TBD</para> - <para> - This part of the book describes the rate control algorithm - interface and how it relates to mac80211 and drivers. - </para> - </partintro> - <chapter id="dummy"> - <title>dummy chapter</title> - <para>TBD</para> - </chapter> - </part> - - <part id="internal"> - <title>Internals</title> - <partintro> - <para>TBD</para> - <para> - This part of the book describes mac80211 internals. - </para> - </partintro> - - <chapter id="key-handling"> - <title>Key handling</title> - <sect1> - <title>Key handling basics</title> -!Pnet/mac80211/key.c Key handling basics - </sect1> - <sect1> - <title>MORE TBD</title> - <para>TBD</para> - </sect1> - </chapter> - - <chapter id="rx-processing"> - <title>Receive processing</title> - <para>TBD</para> - </chapter> - - <chapter id="tx-processing"> - <title>Transmit processing</title> - <para>TBD</para> - </chapter> - - <chapter id="sta-info"> - <title>Station info handling</title> - <sect1> - <title>Programming information</title> -!Fnet/mac80211/sta_info.h sta_info -!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags - </sect1> - <sect1> - <title>STA information lifetime rules</title> -!Pnet/mac80211/sta_info.c STA information lifetime rules - </sect1> - </chapter> - - <chapter id="synchronisation"> - <title>Synchronisation</title> - <para>TBD</para> - <para>Locking, lots of RCU</para> - </chapter> - </part> -</book> diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl index 5d4d40f429a..be34dcbe0d9 100644 --- a/Documentation/DocBook/media-entities.tmpl +++ b/Documentation/DocBook/media-entities.tmpl @@ -218,6 +218,7 @@ <!ENTITY sub-dev-teletext SYSTEM "v4l/dev-teletext.xml"> <!ENTITY sub-driver SYSTEM "v4l/driver.xml"> <!ENTITY sub-libv4l SYSTEM "v4l/libv4l.xml"> +<!ENTITY sub-lirc_device_interface SYSTEM "v4l/lirc_device_interface.xml"> <!ENTITY sub-remote_controllers SYSTEM "v4l/remote_controllers.xml"> <!ENTITY sub-fdl-appendix SYSTEM "v4l/fdl-appendix.xml"> <!ENTITY sub-close SYSTEM "v4l/func-close.xml"> @@ -249,6 +250,9 @@ <!ENTITY sub-yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml"> <!ENTITY sub-yuyv SYSTEM "v4l/pixfmt-yuyv.xml"> <!ENTITY sub-yvyu SYSTEM "v4l/pixfmt-yvyu.xml"> +<!ENTITY sub-srggb10 SYSTEM "v4l/pixfmt-srggb10.xml"> +<!ENTITY sub-srggb8 SYSTEM "v4l/pixfmt-srggb8.xml"> +<!ENTITY sub-y10 SYSTEM "v4l/pixfmt-y10.xml"> <!ENTITY sub-pixfmt SYSTEM "v4l/pixfmt.xml"> <!ENTITY sub-cropcap SYSTEM "v4l/vidioc-cropcap.xml"> <!ENTITY sub-dbg-g-register SYSTEM "v4l/vidioc-dbg-g-register.xml"> @@ -346,6 +350,9 @@ <!ENTITY yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml"> <!ENTITY yuyv SYSTEM "v4l/pixfmt-yuyv.xml"> <!ENTITY yvyu SYSTEM "v4l/pixfmt-yvyu.xml"> +<!ENTITY srggb10 SYSTEM "v4l/pixfmt-srggb10.xml"> +<!ENTITY srggb8 SYSTEM "v4l/pixfmt-srggb8.xml"> +<!ENTITY y10 SYSTEM "v4l/pixfmt-y10.xml"> <!ENTITY cropcap SYSTEM "v4l/vidioc-cropcap.xml"> <!ENTITY dbg-g-register SYSTEM "v4l/vidioc-dbg-g-register.xml"> <!ENTITY encoder-cmd SYSTEM "v4l/vidioc-encoder-cmd.xml"> diff --git a/Documentation/DocBook/media.tmpl b/Documentation/DocBook/media.tmpl index eea564bb12c..f11048d4053 100644 --- a/Documentation/DocBook/media.tmpl +++ b/Documentation/DocBook/media.tmpl @@ -28,7 +28,7 @@ <title>LINUX MEDIA INFRASTRUCTURE API</title> <copyright> - <year>2009</year> + <year>2009-2010</year> <holder>LinuxTV Developers</holder> </copyright> @@ -61,7 +61,7 @@ Foundation. A copy of the license is included in the chapter entitled in fact it covers several different video standards including DVB-T, DVB-S, DVB-C and ATSC. The API is currently being updated to documment support also for DVB-S2, ISDB-T and ISDB-S.</para> - <para>The third part covers other API's used by all media infrastructure devices</para> + <para>The third part covers Remote Controller API</para> <para>For additional information and for the latest development code, see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> <para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para> @@ -86,7 +86,7 @@ Foundation. A copy of the license is included in the chapter entitled </author> </authorgroup> <copyright> - <year>2009</year> + <year>2009-2010</year> <holder>Mauro Carvalho Chehab</holder> </copyright> @@ -101,7 +101,7 @@ Foundation. A copy of the license is included in the chapter entitled </revhistory> </partinfo> -<title>Other API's used by media infrastructure drivers</title> +<title>Remote Controller API</title> <chapter id="remote_controllers"> &sub-remote_controllers; </chapter> diff --git a/Documentation/DocBook/scsi.tmpl b/Documentation/DocBook/scsi.tmpl index d87f4569e76..324b53494f0 100644 --- a/Documentation/DocBook/scsi.tmpl +++ b/Documentation/DocBook/scsi.tmpl @@ -393,7 +393,7 @@ </para> <para> For documentation see - <ulink url='http://www.torque.net/sg/sdebug26.html'>http://www.torque.net/sg/sdebug26.html</ulink> + <ulink url='http://sg.danny.cz/sg/sdebug26.html'>http://sg.danny.cz/sg/sdebug26.html</ulink> </para> <!-- !Edrivers/scsi/scsi_debug.c --> </sect2> diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl index 254c1d5d2e5..85b25275196 100644 --- a/Documentation/DocBook/stylesheet.xsl +++ b/Documentation/DocBook/stylesheet.xsl @@ -6,4 +6,5 @@ <param name="callout.graphics">0</param> <!-- <param name="paper.type">A4</param> --> <param name="generate.section.toc.level">2</param> +<param name="use.id.as.filename">1</param> </stylesheet> diff --git a/Documentation/DocBook/tracepoint.tmpl b/Documentation/DocBook/tracepoint.tmpl index e8473eae2a2..b57a9ede322 100644 --- a/Documentation/DocBook/tracepoint.tmpl +++ b/Documentation/DocBook/tracepoint.tmpl @@ -104,4 +104,9 @@ <title>Block IO</title> !Iinclude/trace/events/block.h </chapter> + + <chapter id="workqueue"> + <title>Workqueue</title> +!Iinclude/trace/events/workqueue.h + </chapter> </book> diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml index b42b935913c..c9ce61d981f 100644 --- a/Documentation/DocBook/v4l/compat.xml +++ b/Documentation/DocBook/v4l/compat.xml @@ -21,11 +21,15 @@ API.</para> <title>Opening and Closing Devices</title> <para>For compatibility reasons the character device file names -recommended for V4L2 video capture, overlay, radio, teletext and raw +recommended for V4L2 video capture, overlay, radio and raw vbi capture devices did not change from those used by V4L. They are listed in <xref linkend="devices" /> and below in <xref linkend="v4l-dev" />.</para> + <para>The teletext devices (minor range 192-223) have been removed in +V4L2 and no longer exist. There is no hardware available anymore for handling +pure teletext. Instead raw or sliced VBI is used.</para> + <para>The V4L <filename>videodev</filename> module automatically assigns minor numbers to drivers in load order, depending on the registered device type. We recommend that V4L2 drivers by default @@ -66,13 +70,6 @@ not compatible with V4L or V4L2.</para> </footnote>, <entry>64-127</entry> </row> <row> - <entry>Teletext decoder</entry> - <entry><para><filename>/dev/vtx</filename>, -<filename>/dev/vtx0</filename> to -<filename>/dev/vtx31</filename></para></entry> - <entry>192-223</entry> - </row> - <row> <entry>Raw VBI capture</entry> <entry><para><filename>/dev/vbi</filename>, <filename>/dev/vbi0</filename> to @@ -1091,8 +1088,9 @@ signed 64-bit integer. Output devices should not send a buffer out until the time in the timestamp field has arrived. I would like to follow SGI's lead, and adopt a multimedia timestamping system like their UST (Unadjusted System Time). See -http://reality.sgi.com/cpirazzi_engr/lg/time/intro.html. [This link is -no longer valid.] UST uses timestamps that are 64-bit signed integers +http://web.archive.org/web/*/http://reality.sgi.com +/cpirazzi_engr/lg/time/intro.html. +UST uses timestamps that are 64-bit signed integers (not struct timeval's) and given in nanosecond units. The UST clock starts at zero when the system is booted and runs continuously and uniformly. It takes a little over 292 years for UST to overflow. There @@ -2344,6 +2342,17 @@ more information.</para> </listitem> </orderedlist> </section> + <section> + <title>V4L2 in Linux 2.6.37</title> + <orderedlist> + <listitem> + <para>Remove the vtx (videotext/teletext) API. This API was no longer +used and no hardware exists to verify the API. Nor were any userspace applications found +that used it. It was originally scheduled for removal in 2.6.35. + </para> + </listitem> + </orderedlist> + </section> <section id="other"> <title>Relation of V4L2 to other Linux multimedia APIs</title> diff --git a/Documentation/DocBook/v4l/controls.xml b/Documentation/DocBook/v4l/controls.xml index 8408caaee27..2fae3e87ce7 100644 --- a/Documentation/DocBook/v4l/controls.xml +++ b/Documentation/DocBook/v4l/controls.xml @@ -312,10 +312,17 @@ minimum value disables backlight compensation.</entry> information and bits 24-31 must be zero.</entry> </row> <row> + <entry><constant>V4L2_CID_ILLUMINATORS_1</constant> + <constant>V4L2_CID_ILLUMINATORS_2</constant></entry> + <entry>boolean</entry> + <entry>Switch on or off the illuminator 1 or 2 of the device + (usually a microscope).</entry> + </row> + <row> <entry><constant>V4L2_CID_LASTP1</constant></entry> <entry></entry> <entry>End of the predefined control IDs (currently -<constant>V4L2_CID_BG_COLOR</constant> + 1).</entry> +<constant>V4L2_CID_ILLUMINATORS_2</constant> + 1).</entry> </row> <row> <entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry> @@ -357,9 +364,6 @@ enumerate_menu (void) querymenu.index++) { if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &querymenu)) { printf (" %s\n", querymenu.name); - } else { - perror ("VIDIOC_QUERYMENU"); - exit (EXIT_FAILURE); } } } diff --git a/Documentation/DocBook/v4l/dev-rds.xml b/Documentation/DocBook/v4l/dev-rds.xml index 0869d701b1e..360d2737e64 100644 --- a/Documentation/DocBook/v4l/dev-rds.xml +++ b/Documentation/DocBook/v4l/dev-rds.xml @@ -3,15 +3,16 @@ <para>The Radio Data System transmits supplementary information in binary format, for example the station name or travel information, on an inaudible audio subcarrier of a radio program. This -interface is aimed at devices capable of receiving and decoding RDS +interface is aimed at devices capable of receiving and/or transmitting RDS information.</para> <para>For more information see the core RDS standard <xref linkend="en50067" /> and the RBDS standard <xref linkend="nrsc4" />.</para> <para>Note that the RBDS standard as is used in the USA is almost identical -to the RDS standard. Any RDS decoder can also handle RBDS. Only some of the fields -have slightly different meanings. See the RBDS standard for more information.</para> +to the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only some of the +fields have slightly different meanings. See the RBDS standard for more +information.</para> <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search). This is a proprietary format which seems to be discontinued. The RDS interface does not @@ -21,16 +22,25 @@ be needed, then please contact the linux-media mailing list: &v4l-ml;.</para> <section> <title>Querying Capabilities</title> - <para>Devices supporting the RDS capturing API -set the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in + <para>Devices supporting the RDS capturing API set +the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in the <structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. -Any tuner that supports RDS will set the -<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> -field of &v4l2-tuner;. -Whether an RDS signal is present can be detected by looking at -the <structfield>rxsubchans</structfield> field of &v4l2-tuner;: the -<constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data was detected.</para> +returned by the &VIDIOC-QUERYCAP; ioctl. Any tuner that supports RDS +will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in +the <structfield>capability</structfield> field of &v4l2-tuner;. If +the driver only passes RDS blocks without interpreting the data +the <constant>V4L2_TUNER_SUB_RDS_BLOCK_IO</constant> flag has to be +set, see <link linkend="reading-rds-data">Reading RDS data</link>. +For future use the +flag <constant>V4L2_TUNER_SUB_RDS_CONTROLS</constant> has also been +defined. However, a driver for a radio tuner with this capability does +not yet exist, so if you are planning to write such a driver you +should discuss this on the linux-media mailing list: &v4l-ml;.</para> + + <para> Whether an RDS signal is present can be detected by looking +at the <structfield>rxsubchans</structfield> field of &v4l2-tuner;: +the <constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data +was detected.</para> <para>Devices supporting the RDS output API set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in @@ -40,16 +50,31 @@ Any modulator that supports RDS will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> field of &v4l2-modulator;. In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant> -bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.</para> - +bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;. +If the driver only passes RDS blocks without interpreting the data +the <constant>V4L2_TUNER_SUB_RDS_BLOCK_IO</constant> flag has to be set. If the +tuner is capable of handling RDS entities like program identification codes and radio +text, the flag <constant>V4L2_TUNER_SUB_RDS_CONTROLS</constant> should be set, +see <link linkend="writing-rds-data">Writing RDS data</link> and +<link linkend="fm-tx-controls">FM Transmitter Control Reference</link>.</para> </section> - <section> + <section id="reading-rds-data"> <title>Reading RDS data</title> <para>RDS data can be read from the radio device -with the &func-read; function. The data is packed in groups of three bytes, +with the &func-read; function. The data is packed in groups of three bytes.</para> + </section> + + <section id="writing-rds-data"> + <title>Writing RDS data</title> + + <para>RDS data can be written to the radio device +with the &func-write; function. The data is packed in groups of three bytes, as follows:</para> + </section> + + <section> <table frame="none" pgwide="1" id="v4l2-rds-data"> <title>struct <structname>v4l2_rds_data</structname></title> @@ -111,48 +136,57 @@ as follows:</para> <tbody valign="top"> <row> <entry>V4L2_RDS_BLOCK_MSK</entry> + <entry> </entry> <entry>7</entry> <entry>Mask for bits 0-2 to get the block ID.</entry> </row> <row> <entry>V4L2_RDS_BLOCK_A</entry> + <entry> </entry> <entry>0</entry> <entry>Block A.</entry> </row> <row> <entry>V4L2_RDS_BLOCK_B</entry> + <entry> </entry> <entry>1</entry> <entry>Block B.</entry> </row> <row> <entry>V4L2_RDS_BLOCK_C</entry> + <entry> </entry> <entry>2</entry> <entry>Block C.</entry> </row> <row> <entry>V4L2_RDS_BLOCK_D</entry> + <entry> </entry> <entry>3</entry> <entry>Block D.</entry> </row> <row> <entry>V4L2_RDS_BLOCK_C_ALT</entry> + <entry> </entry> <entry>4</entry> <entry>Block C'.</entry> </row> <row> <entry>V4L2_RDS_BLOCK_INVALID</entry> + <entry>read-only</entry> <entry>7</entry> <entry>An invalid block.</entry> </row> <row> <entry>V4L2_RDS_BLOCK_CORRECTED</entry> + <entry>read-only</entry> <entry>0x40</entry> <entry>A bit error was detected but corrected.</entry> </row> <row> <entry>V4L2_RDS_BLOCK_ERROR</entry> + <entry>read-only</entry> <entry>0x80</entry> - <entry>An incorrectable error occurred.</entry> + <entry>An uncorrectable error occurred.</entry> </row> </tbody> </tgroup> diff --git a/Documentation/DocBook/v4l/dev-teletext.xml b/Documentation/DocBook/v4l/dev-teletext.xml index 76184e8ed61..414b1cfff9f 100644 --- a/Documentation/DocBook/v4l/dev-teletext.xml +++ b/Documentation/DocBook/v4l/dev-teletext.xml @@ -1,35 +1,32 @@ <title>Teletext Interface</title> - <para>This interface aims at devices receiving and demodulating + <para>This interface was aimed at devices receiving and demodulating Teletext data [<xref linkend="ets300706" />, <xref linkend="itu653" />], evaluating the Teletext packages and storing formatted pages in cache memory. Such devices are usually implemented as microcontrollers with serial -interface (I<superscript>2</superscript>C) and can be found on older +interface (I<superscript>2</superscript>C) and could be found on old TV cards, dedicated Teletext decoding cards and home-brew devices connected to the PC parallel port.</para> - <para>The Teletext API was designed by Martin Buck. It is defined in + <para>The Teletext API was designed by Martin Buck. It was defined in the kernel header file <filename>linux/videotext.h</filename>, the specification is available from <ulink url="ftp://ftp.gwdg.de/pub/linux/misc/videotext/"> ftp://ftp.gwdg.de/pub/linux/misc/videotext/</ulink>. (Videotext is the name of -the German public television Teletext service.) Conventional character -device file names are <filename>/dev/vtx</filename> and -<filename>/dev/vttuner</filename>, with device number 83, 0 and 83, 16 -respectively. A similar interface exists for the Philips SAA5249 -Teletext decoder [specification?] with character device file names -<filename>/dev/tlkN</filename>, device number 102, N.</para> +the German public television Teletext service.)</para> <para>Eventually the Teletext API was integrated into the V4L API with character device file names <filename>/dev/vtx0</filename> to <filename>/dev/vtx31</filename>, device major number 81, minor numbers -192 to 223. For reference the V4L Teletext API specification is -reproduced here in full: "Teletext interfaces talk the existing VTX -API." Teletext devices with major number 83 and 102 will be removed in -Linux 2.6.</para> +192 to 223.</para> - <para>There are no plans to replace the Teletext API or to integrate -it into V4L2. Please write to the linux-media mailing list: &v4l-ml; -when the need arises.</para> + <para>However, teletext decoders were quickly replaced by more +generic VBI demodulators and those dedicated teletext decoders no longer exist. +For many years the vtx devices were still around, even though nobody used +them. So the decision was made to finally remove support for the Teletext API in +kernel 2.6.37.</para> + + <para>Modern devices all use the <link linkend="raw-vbi">raw</link> or +<link linkend="sliced">sliced</link> VBI API.</para> <!-- Local Variables: diff --git a/Documentation/DocBook/v4l/fdl-appendix.xml b/Documentation/DocBook/v4l/fdl-appendix.xml index b6ce50dbe49..ae22394ba99 100644 --- a/Documentation/DocBook/v4l/fdl-appendix.xml +++ b/Documentation/DocBook/v4l/fdl-appendix.xml @@ -2,7 +2,7 @@ The GNU Free Documentation License 1.1 in DocBook Markup by Eric Baudais <baudais@okstate.edu> Maintained by the GNOME Documentation Project - http://developer.gnome.org/projects/gdp + http://live.gnome.org/DocumentationProject Version: 1.0.1 Last Modified: Nov 16, 2000 --> diff --git a/Documentation/DocBook/v4l/lirc_device_interface.xml b/Documentation/DocBook/v4l/lirc_device_interface.xml new file mode 100644 index 00000000000..68134c0ab4d --- /dev/null +++ b/Documentation/DocBook/v4l/lirc_device_interface.xml @@ -0,0 +1,251 @@ +<section id="lirc_dev"> +<title>LIRC Device Interface</title> + + +<section id="lirc_dev_intro"> +<title>Introduction</title> + +<para>The LIRC device interface is a bi-directional interface for +transporting raw IR data between userspace and kernelspace. Fundamentally, +it is just a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number +of standard struct file_operations defined on it. With respect to +transporting raw IR data to and fro, the essential fops are read, write +and ioctl.</para> + +<para>Example dmesg output upon a driver registering w/LIRC:</para> + <blockquote> + <para>$ dmesg |grep lirc_dev</para> + <para>lirc_dev: IR Remote Control driver registered, major 248</para> + <para>rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0</para> + </blockquote> + +<para>What you should see for a chardev:</para> + <blockquote> + <para>$ ls -l /dev/lirc*</para> + <para>crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0</para> + </blockquote> +</section> + +<section id="lirc_read"> +<title>LIRC read fop</title> + +<para>The lircd userspace daemon reads raw IR data from the LIRC chardev. The +exact format of the data depends on what modes a driver supports, and what +mode has been selected. lircd obtains supported modes and sets the active mode +via the ioctl interface, detailed at <xref linkend="lirc_ioctl"/>. The generally +preferred mode is LIRC_MODE_MODE2, in which packets containing an int value +describing an IR signal are read from the chardev.</para> + +<para>See also <ulink url="http://www.lirc.org/html/technical.html">http://www.lirc.org/html/technical.html</ulink> for more info.</para> +</section> + +<section id="lirc_write"> +<title>LIRC write fop</title> + +<para>The data written to the chardev is a pulse/space sequence of integer +values. Pulses and spaces are only marked implicitly by their position. The +data must start and end with a pulse, therefore, the data must always include +an unevent number of samples. The write function must block until the data has +been transmitted by the hardware.</para> +</section> + +<section id="lirc_ioctl"> +<title>LIRC ioctl fop</title> + +<para>The LIRC device's ioctl definition is bound by the ioctl function +definition of struct file_operations, leaving us with an unsigned int +for the ioctl command and an unsigned long for the arg. For the purposes +of ioctl portability across 32-bit and 64-bit, these values are capped +to their 32-bit sizes.</para> + +<para>The following ioctls can be used to change specific hardware settings. +In general each driver should have a default set of settings. The driver +implementation is expected to re-apply the default settings when the device +is closed by user-space, so that every application opening the device can rely +on working with the default settings initially.</para> + +<variablelist> + <varlistentry> + <term>LIRC_GET_FEATURES</term> + <listitem> + <para>Obviously, get the underlying hardware device's features. If a driver + does not announce support of certain features, calling of the corresponding + ioctls is undefined.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_GET_SEND_MODE</term> + <listitem> + <para>Get supported transmit mode. Only LIRC_MODE_PULSE is supported by lircd.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_GET_REC_MODE</term> + <listitem> + <para>Get supported receive modes. Only LIRC_MODE_MODE2 and LIRC_MODE_LIRCCODE + are supported by lircd.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_GET_SEND_CARRIER</term> + <listitem> + <para>Get carrier frequency (in Hz) currently used for transmit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_GET_REC_CARRIER</term> + <listitem> + <para>Get carrier frequency (in Hz) currently used for IR reception.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE</term> + <listitem> + <para>Get/set the duty cycle (from 0 to 100) of the carrier signal. Currently, + no special meaning is defined for 0 or 100, but this could be used to switch + off carrier generation in the future, so these values should be reserved.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_GET_REC_RESOLUTION</term> + <listitem> + <para>Some receiver have maximum resolution which is defined by internal + sample rate or data format limitations. E.g. it's common that signals can + only be reported in 50 microsecond steps. This integer value is used by + lircd to automatically adjust the aeps tolerance value in the lircd + config file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_GET_M{IN,AX}_TIMEOUT</term> + <listitem> + <para>Some devices have internal timers that can be used to detect when + there's no IR activity for a long time. This can help lircd in detecting + that a IR signal is finished and can speed up the decoding process. + Returns an integer value with the minimum/maximum timeout that can be + set. Some devices have a fixed timeout, in that case both ioctls will + return the same value even though the timeout cannot be changed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}</term> + <listitem> + <para>Some devices are able to filter out spikes in the incoming signal + using given filter rules. These ioctls return the hardware capabilities + that describe the bounds of the possible filters. Filter settings depend + on the IR protocols that are expected. lircd derives the settings from + all protocols definitions found in its config file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_GET_LENGTH</term> + <listitem> + <para>Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE). + Reads on the device must be done in blocks matching the bit count. + The bit could should be rounded up so that it matches full bytes.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_SET_{SEND,REC}_MODE</term> + <listitem> + <para>Set send/receive mode. Largely obsolete for send, as only + LIRC_MODE_PULSE is supported.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_SET_{SEND,REC}_CARRIER</term> + <listitem> + <para>Set send/receive carrier (in Hz).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_SET_TRANSMITTER_MASK</term> + <listitem> + <para>This enables the given set of transmitters. The first transmitter + is encoded by the least significant bit, etc. When an invalid bit mask + is given, i.e. a bit is set, even though the device does not have so many + transitters, then this ioctl returns the number of available transitters + and does nothing otherwise.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_SET_REC_TIMEOUT</term> + <listitem> + <para>Sets the integer value for IR inactivity timeout (cf. + LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0 (if + supported by the hardware) disables all hardware timeouts and data should + be reported as soon as possible. If the exact value cannot be set, then + the next possible value _greater_ than the given value should be set.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_SET_REC_TIMEOUT_REPORTS</term> + <listitem> + <para>Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By + default, timeout reports should be turned off.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_SET_REC_FILTER_{,PULSE,SPACE}</term> + <listitem> + <para>Pulses/spaces shorter than this are filtered out by hardware. If + filters cannot be set independently for pulse/space, the corresponding + ioctls must return an error and LIRC_SET_REC_FILTER shall be used instead.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_SET_MEASURE_CARRIER_MODE</term> + <listitem> + <para>Enable (1)/disable (0) measure mode. If enabled, from the next key + press on, the driver will send LIRC_MODE2_FREQUENCY packets. By default + this should be turned off.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE</term> + <listitem> + <para>To set a range use LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE + with the lower bound first and later LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER + with the upper bound.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_NOTIFY_DECODE</term> + <listitem> + <para>This ioctl is called by lircd whenever a successful decoding of an + incoming IR signal could be done. This can be used by supporting hardware + to give visual feedback to the user e.g. by flashing a LED.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_SETUP_{START,END}</term> + <listitem> + <para>Setting of several driver parameters can be optimized by encapsulating + the according ioctl calls with LIRC_SETUP_START/LIRC_SETUP_END. When a + driver receives a LIRC_SETUP_START ioctl it can choose to not commit + further setting changes to the hardware until a LIRC_SETUP_END is received. + But this is open to the driver implementation and every driver must also + handle parameter changes which are not encapsulated by LIRC_SETUP_START + and LIRC_SETUP_END. Drivers can also choose to ignore these ioctls.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>LIRC_SET_WIDEBAND_RECEIVER</term> + <listitem> + <para>Some receivers are equipped with special wide band receiver which is intended + to be used to learn output of existing remote. + Calling that ioctl with (1) will enable it, and with (0) disable it. + This might be useful of receivers that have otherwise narrow band receiver + that prevents them to be used with some remotes. + Wide band receiver might also be more precise + On the other hand its disadvantage it usually reduced range of reception. + Note: wide band receiver might be implictly enabled if you enable + carrier reports. In that case it will be disabled as soon as you disable + carrier reports. Trying to disable wide band receiver while carrier + reports are active will do nothing.</para> + </listitem> + </varlistentry> +</variablelist> + +</section> +</section> diff --git a/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml index d2dd697a81d..4db272b8a0d 100644 --- a/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml +++ b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml @@ -240,6 +240,45 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> + <row id="V4L2-PIX-FMT-BGR666"> + <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry> + <entry>'BGRH'</entry> + <entry></entry> + <entry>b<subscript>5</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>r<subscript>5</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> <row id="V4L2-PIX-FMT-BGR24"> <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> <entry>'BGR3'</entry> @@ -700,6 +739,45 @@ defined in error. Drivers may interpret them as in <xref <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> + <row><!-- id="V4L2-PIX-FMT-BGR666" --> + <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry> + <entry>'BGRH'</entry> + <entry></entry> + <entry>b<subscript>5</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>r<subscript>5</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> <row><!-- id="V4L2-PIX-FMT-BGR24" --> <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> <entry>'BGR3'</entry> diff --git a/Documentation/DocBook/v4l/pixfmt-srggb10.xml b/Documentation/DocBook/v4l/pixfmt-srggb10.xml new file mode 100644 index 00000000000..7b274092e60 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-srggb10.xml @@ -0,0 +1,90 @@ + <refentry> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_SRGGB10 ('RG10'), + V4L2_PIX_FMT_SGRBG10 ('BA10'), + V4L2_PIX_FMT_SGBRG10 ('GB10'), + V4L2_PIX_FMT_SBGGR10 ('BG10'), + </refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname id="V4L2-PIX-FMT-SRGGB10"><constant>V4L2_PIX_FMT_SRGGB10</constant></refname> + <refname id="V4L2-PIX-FMT-SGRBG10"><constant>V4L2_PIX_FMT_SGRBG10</constant></refname> + <refname id="V4L2-PIX-FMT-SGBRG10"><constant>V4L2_PIX_FMT_SGBRG10</constant></refname> + <refname id="V4L2-PIX-FMT-SBGGR10"><constant>V4L2_PIX_FMT_SBGGR10</constant></refname> + <refpurpose>10-bit Bayer formats expanded to 16 bits</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>The following four pixel formats are raw sRGB / Bayer formats with +10 bits per colour. Each colour component is stored in a 16-bit word, with 6 +unused high bits filled with zeros. Each n-pixel row contains n/2 green samples +and n/2 blue or red samples, with alternating red and blue rows. Bytes are +stored in memory in little endian order. They are conventionally described +as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example of one of these +formats</para> + + <example> + <title><constant>V4L2_PIX_FMT_SBGGR10</constant> 4 × 4 +pixel image</title> + + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte, high 6 bits in high bytes are 0. + <informaltable frame="none"> + <tgroup cols="5" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>B<subscript>00low</subscript></entry> + <entry>B<subscript>00high</subscript></entry> + <entry>G<subscript>01low</subscript></entry> + <entry>G<subscript>01high</subscript></entry> + <entry>B<subscript>02low</subscript></entry> + <entry>B<subscript>02high</subscript></entry> + <entry>G<subscript>03low</subscript></entry> + <entry>G<subscript>03high</subscript></entry> + </row> + <row> + <entry>start + 8:</entry> + <entry>G<subscript>10low</subscript></entry> + <entry>G<subscript>10high</subscript></entry> + <entry>R<subscript>11low</subscript></entry> + <entry>R<subscript>11high</subscript></entry> + <entry>G<subscript>12low</subscript></entry> + <entry>G<subscript>12high</subscript></entry> + <entry>R<subscript>13low</subscript></entry> + <entry>R<subscript>13high</subscript></entry> + </row> + <row> + <entry>start + 16:</entry> + <entry>B<subscript>20low</subscript></entry> + <entry>B<subscript>20high</subscript></entry> + <entry>G<subscript>21low</subscript></entry> + <entry>G<subscript>21high</subscript></entry> + <entry>B<subscript>22low</subscript></entry> + <entry>B<subscript>22high</subscript></entry> + <entry>G<subscript>23low</subscript></entry> + <entry>G<subscript>23high</subscript></entry> + </row> + <row> + <entry>start + 24:</entry> + <entry>G<subscript>30low</subscript></entry> + <entry>G<subscript>30high</subscript></entry> + <entry>R<subscript>31low</subscript></entry> + <entry>R<subscript>31high</subscript></entry> + <entry>G<subscript>32low</subscript></entry> + <entry>G<subscript>32high</subscript></entry> + <entry>R<subscript>33low</subscript></entry> + <entry>R<subscript>33high</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/pixfmt-srggb8.xml b/Documentation/DocBook/v4l/pixfmt-srggb8.xml new file mode 100644 index 00000000000..2570e3be3cf --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-srggb8.xml @@ -0,0 +1,67 @@ + <refentry id="V4L2-PIX-FMT-SRGGB8"> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_SRGGB8 ('RGGB')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname><constant>V4L2_PIX_FMT_SRGGB8</constant></refname> + <refpurpose>Bayer RGB format</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>This is commonly the native format of digital cameras, +reflecting the arrangement of sensors on the CCD device. Only one red, +green or blue value is given for each pixel. Missing components must +be interpolated from neighbouring pixels. From left to right the first +row consists of a red and green value, the second row of a green and +blue value. This scheme repeats to the right and down for every two +columns and rows.</para> + + <example> + <title><constant>V4L2_PIX_FMT_SRGGB8</constant> 4 × 4 +pixel image</title> + + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="5" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>R<subscript>00</subscript></entry> + <entry>G<subscript>01</subscript></entry> + <entry>R<subscript>02</subscript></entry> + <entry>G<subscript>03</subscript></entry> + </row> + <row> + <entry>start + 4:</entry> + <entry>G<subscript>10</subscript></entry> + <entry>B<subscript>11</subscript></entry> + <entry>G<subscript>12</subscript></entry> + <entry>B<subscript>13</subscript></entry> + </row> + <row> + <entry>start + 8:</entry> + <entry>R<subscript>20</subscript></entry> + <entry>G<subscript>21</subscript></entry> + <entry>R<subscript>22</subscript></entry> + <entry>G<subscript>23</subscript></entry> + </row> + <row> + <entry>start + 12:</entry> + <entry>G<subscript>30</subscript></entry> + <entry>B<subscript>31</subscript></entry> + <entry>G<subscript>32</subscript></entry> + <entry>B<subscript>33</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> + </refentry> diff --git a/Documentation/DocBook/v4l/pixfmt-y10.xml b/Documentation/DocBook/v4l/pixfmt-y10.xml new file mode 100644 index 00000000000..d065043db8d --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-y10.xml @@ -0,0 +1,79 @@ +<refentry id="V4L2-PIX-FMT-Y10"> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_Y10 ('Y10 ')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname><constant>V4L2_PIX_FMT_Y10</constant></refname> + <refpurpose>Grey-scale image</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>This is a grey-scale image with a depth of 10 bits per pixel. Pixels +are stored in 16-bit words with unused high bits padded with 0. The least +significant byte is stored at lower memory addresses (little-endian).</para> + + <example> + <title><constant>V4L2_PIX_FMT_Y10</constant> 4 × 4 +pixel image</title> + + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="9" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>Y'<subscript>00low</subscript></entry> + <entry>Y'<subscript>00high</subscript></entry> + <entry>Y'<subscript>01low</subscript></entry> + <entry>Y'<subscript>01high</subscript></entry> + <entry>Y'<subscript>02low</subscript></entry> + <entry>Y'<subscript>02high</subscript></entry> + <entry>Y'<subscript>03low</subscript></entry> + <entry>Y'<subscript>03high</subscript></entry> + </row> + <row> + <entry>start + 8:</entry> + <entry>Y'<subscript>10low</subscript></entry> + <entry>Y'<subscript>10high</subscript></entry> + <entry>Y'<subscript>11low</subscript></entry> + <entry>Y'<subscript>11high</subscript></entry> + <entry>Y'<subscript>12low</subscript></entry> + <entry>Y'<subscript>12high</subscript></entry> + <entry>Y'<subscript>13low</subscript></entry> + <entry>Y'<subscript>13high</subscript></entry> + </row> + <row> + <entry>start + 16:</entry> + <entry>Y'<subscript>20low</subscript></entry> + <entry>Y'<subscript>20high</subscript></entry> + <entry>Y'<subscript>21low</subscript></entry> + <entry>Y'<subscript>21high</subscript></entry> + <entry>Y'<subscript>22low</subscript></entry> + <entry>Y'<subscript>22high</subscript></entry> + <entry>Y'<subscript>23low</subscript></entry> + <entry>Y'<subscript>23high</subscript></entry> + </row> + <row> + <entry>start + 24:</entry> + <entry>Y'<subscript>30low</subscript></entry> + <entry>Y'<subscript>30high</subscript></entry> + <entry>Y'<subscript>31low</subscript></entry> + <entry>Y'<subscript>31high</subscript></entry> + <entry>Y'<subscript>32low</subscript></entry> + <entry>Y'<subscript>32high</subscript></entry> + <entry>Y'<subscript>33low</subscript></entry> + <entry>Y'<subscript>33high</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/pixfmt.xml b/Documentation/DocBook/v4l/pixfmt.xml index c4ad0a8e42d..d7c46718709 100644 --- a/Documentation/DocBook/v4l/pixfmt.xml +++ b/Documentation/DocBook/v4l/pixfmt.xml @@ -566,7 +566,9 @@ access the palette, this must be done with ioctls of the Linux framebuffer API.< &sub-sbggr8; &sub-sgbrg8; &sub-sgrbg8; + &sub-srggb8; &sub-sbggr16; + &sub-srggb10; </section> <section id="yuv-formats"> @@ -589,6 +591,7 @@ information.</para> &sub-packed-yuv; &sub-grey; + &sub-y10; &sub-y16; &sub-yuyv; &sub-uyvy; @@ -685,6 +688,11 @@ http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename> </para></entry> </row> + <row id="V4L2-PIX-FMT-CPIA1"> + <entry><constant>V4L2_PIX_FMT_CPIA1</constant></entry> + <entry>'CPIA'</entry> + <entry>YUV format used by the gspca cpia1 driver.</entry> + </row> <row id="V4L2-PIX-FMT-SPCA501"> <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry> <entry>'S501'</entry> @@ -705,11 +713,6 @@ kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm <entry>'S561'</entry> <entry>Compressed GBRG Bayer format used by the gspca driver.</entry> </row> - <row id="V4L2-PIX-FMT-SGRBG10"> - <entry><constant>V4L2_PIX_FMT_SGRBG10</constant></entry> - <entry>'DA10'</entry> - <entry>10 bit raw Bayer, expanded to 16 bits.</entry> - </row> <row id="V4L2-PIX-FMT-SGRBG10DPCM8"> <entry><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></entry> <entry>'DB10'</entry> @@ -770,6 +773,11 @@ kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm <entry>'S920'</entry> <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry> </row> + <row id="V4L2-PIX-FMT-SN9C2028"> + <entry><constant>V4L2_PIX_FMT_SN9C2028</constant></entry> + <entry>'SONX'</entry> + <entry>Compressed GBRG bayer format of the gspca sn9c2028 driver.</entry> + </row> <row id="V4L2-PIX-FMT-STV0680"> <entry><constant>V4L2_PIX_FMT_STV0680</constant></entry> <entry>'S680'</entry> @@ -787,6 +795,20 @@ http://www.thedirks.org/winnov/</ulink></para></entry> <entry>'TM60'</entry> <entry><para>Used by Trident tm6000</para></entry> </row> + <row id="V4L2-PIX-FMT-CIT-YYVYUY"> + <entry><constant>V4L2_PIX_FMT_CIT_YYVYUY</constant></entry> + <entry>'CITV'</entry> + <entry><para>Used by xirlink CIT, found at IBM webcams.</para> + <para>Uses one line of Y then 1 line of VYUY</para> + </entry> + </row> + <row id="V4L2-PIX-FMT-KONICA420"> + <entry><constant>V4L2_PIX_FMT_KONICA420</constant></entry> + <entry>'KONI'</entry> + <entry><para>Used by Konica webcams.</para> + <para>YUV420 planar in blocks of 256 pixels.</para> + </entry> + </row> <row id="V4L2-PIX-FMT-YYUV"> <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry> <entry>'YYUV'</entry> diff --git a/Documentation/DocBook/v4l/remote_controllers.xml b/Documentation/DocBook/v4l/remote_controllers.xml index 73f5eab091f..3c3b667b28e 100644 --- a/Documentation/DocBook/v4l/remote_controllers.xml +++ b/Documentation/DocBook/v4l/remote_controllers.xml @@ -173,3 +173,5 @@ keymapping.</para> <para>This program demonstrates how to replace the keymap tables.</para> &sub-keytable-c; </section> + +&sub-lirc_device_interface; diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml index 7c3c098d5d0..839e93e875a 100644 --- a/Documentation/DocBook/v4l/v4l2.xml +++ b/Documentation/DocBook/v4l/v4l2.xml @@ -99,6 +99,7 @@ Remote Controller chapter.</contrib> <year>2007</year> <year>2008</year> <year>2009</year> + <year>2010</year> <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab</holder> </copyright> @@ -110,10 +111,17 @@ Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab</holder> <!-- Put document revisions here, newest first. --> <!-- API revisions (changes and additions of defines, enums, structs, ioctls) must be noted in more detail in the history chapter -(compat.sgml), along with the possible impact on existing drivers and +(compat.xml), along with the possible impact on existing drivers and applications. --> <revision> + <revnumber>2.6.37</revnumber> + <date>2010-08-06</date> + <authorinitials>hv</authorinitials> + <revremark>Removed obsolete vtx (videotext) API.</revremark> + </revision> + + <revision> <revnumber>2.6.33</revnumber> <date>2009-12-03</date> <authorinitials>mk</authorinitials> diff --git a/Documentation/DocBook/v4l/videodev2.h.xml b/Documentation/DocBook/v4l/videodev2.h.xml index 865b06d9e67..325b23b6964 100644 --- a/Documentation/DocBook/v4l/videodev2.h.xml +++ b/Documentation/DocBook/v4l/videodev2.h.xml @@ -154,23 +154,13 @@ enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> { V4L2_BUF_TYPE_VBI_OUTPUT = 5, V4L2_BUF_TYPE_SLICED_VBI_CAPTURE = 6, V4L2_BUF_TYPE_SLICED_VBI_OUTPUT = 7, -#if 1 /*KEEP*/ +#if 1 /* Experimental */ V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8, #endif V4L2_BUF_TYPE_PRIVATE = 0x80, }; -enum <link linkend="v4l2-ctrl-type">v4l2_ctrl_type</link> { - V4L2_CTRL_TYPE_INTEGER = 1, - V4L2_CTRL_TYPE_BOOLEAN = 2, - V4L2_CTRL_TYPE_MENU = 3, - V4L2_CTRL_TYPE_BUTTON = 4, - V4L2_CTRL_TYPE_INTEGER64 = 5, - V4L2_CTRL_TYPE_CTRL_CLASS = 6, - V4L2_CTRL_TYPE_STRING = 7, -}; - enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> { V4L2_TUNER_RADIO = 1, V4L2_TUNER_ANALOG_TV = 2, @@ -288,6 +278,7 @@ struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> { #define <link linkend="V4L2-PIX-FMT-RGB565">V4L2_PIX_FMT_RGB565</link> v4l2_fourcc('R', 'G', 'B', 'P') /* 16 RGB-5-6-5 */ #define <link linkend="V4L2-PIX-FMT-RGB555X">V4L2_PIX_FMT_RGB555X</link> v4l2_fourcc('R', 'G', 'B', 'Q') /* 16 RGB-5-5-5 BE */ #define <link linkend="V4L2-PIX-FMT-RGB565X">V4L2_PIX_FMT_RGB565X</link> v4l2_fourcc('R', 'G', 'B', 'R') /* 16 RGB-5-6-5 BE */ +#define <link linkend="V4L2-PIX-FMT-BGR666">V4L2_PIX_FMT_BGR666</link> v4l2_fourcc('B', 'G', 'R', 'H') /* 18 BGR-6-6-6 */ #define <link linkend="V4L2-PIX-FMT-BGR24">V4L2_PIX_FMT_BGR24</link> v4l2_fourcc('B', 'G', 'R', '3') /* 24 BGR-8-8-8 */ #define <link linkend="V4L2-PIX-FMT-RGB24">V4L2_PIX_FMT_RGB24</link> v4l2_fourcc('R', 'G', 'B', '3') /* 24 RGB-8-8-8 */ #define <link linkend="V4L2-PIX-FMT-BGR32">V4L2_PIX_FMT_BGR32</link> v4l2_fourcc('B', 'G', 'R', '4') /* 32 BGR-8-8-8-8 */ @@ -295,6 +286,9 @@ struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> { /* Grey formats */ #define <link linkend="V4L2-PIX-FMT-GREY">V4L2_PIX_FMT_GREY</link> v4l2_fourcc('G', 'R', 'E', 'Y') /* 8 Greyscale */ +#define <link linkend="V4L2-PIX-FMT-Y4">V4L2_PIX_FMT_Y4</link> v4l2_fourcc('Y', '0', '4', ' ') /* 4 Greyscale */ +#define <link linkend="V4L2-PIX-FMT-Y6">V4L2_PIX_FMT_Y6</link> v4l2_fourcc('Y', '0', '6', ' ') /* 6 Greyscale */ +#define <link linkend="V4L2-PIX-FMT-Y10">V4L2_PIX_FMT_Y10</link> v4l2_fourcc('Y', '1', '0', ' ') /* 10 Greyscale */ #define <link linkend="V4L2-PIX-FMT-Y16">V4L2_PIX_FMT_Y16</link> v4l2_fourcc('Y', '1', '6', ' ') /* 16 Greyscale */ /* Palette formats */ @@ -330,7 +324,11 @@ struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> { #define <link linkend="V4L2-PIX-FMT-SBGGR8">V4L2_PIX_FMT_SBGGR8</link> v4l2_fourcc('B', 'A', '8', '1') /* 8 BGBG.. GRGR.. */ #define <link linkend="V4L2-PIX-FMT-SGBRG8">V4L2_PIX_FMT_SGBRG8</link> v4l2_fourcc('G', 'B', 'R', 'G') /* 8 GBGB.. RGRG.. */ #define <link linkend="V4L2-PIX-FMT-SGRBG8">V4L2_PIX_FMT_SGRBG8</link> v4l2_fourcc('G', 'R', 'B', 'G') /* 8 GRGR.. BGBG.. */ -#define <link linkend="V4L2-PIX-FMT-SGRBG10">V4L2_PIX_FMT_SGRBG10</link> v4l2_fourcc('B', 'A', '1', '0') /* 10bit raw bayer */ +#define <link linkend="V4L2-PIX-FMT-SRGGB8">V4L2_PIX_FMT_SRGGB8</link> v4l2_fourcc('R', 'G', 'G', 'B') /* 8 RGRG.. GBGB.. */ +#define <link linkend="V4L2-PIX-FMT-SBGGR10">V4L2_PIX_FMT_SBGGR10</link> v4l2_fourcc('B', 'G', '1', '0') /* 10 BGBG.. GRGR.. */ +#define <link linkend="V4L2-PIX-FMT-SGBRG10">V4L2_PIX_FMT_SGBRG10</link> v4l2_fourcc('G', 'B', '1', '0') /* 10 GBGB.. RGRG.. */ +#define <link linkend="V4L2-PIX-FMT-SGRBG10">V4L2_PIX_FMT_SGRBG10</link> v4l2_fourcc('B', 'A', '1', '0') /* 10 GRGR.. BGBG.. */ +#define <link linkend="V4L2-PIX-FMT-SRGGB10">V4L2_PIX_FMT_SRGGB10</link> v4l2_fourcc('R', 'G', '1', '0') /* 10 RGRG.. GBGB.. */ /* 10bit raw bayer DPCM compressed to 8 bits */ #define <link linkend="V4L2-PIX-FMT-SGRBG10DPCM8">V4L2_PIX_FMT_SGRBG10DPCM8</link> v4l2_fourcc('B', 'D', '1', '0') /* @@ -346,6 +344,7 @@ struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> { #define <link linkend="V4L2-PIX-FMT-MPEG">V4L2_PIX_FMT_MPEG</link> v4l2_fourcc('M', 'P', 'E', 'G') /* MPEG-1/2/4 */ /* Vendor-specific formats */ +#define <link linkend="V4L2-PIX-FMT-CPIA1">V4L2_PIX_FMT_CPIA1</link> v4l2_fourcc('C', 'P', 'I', 'A') /* cpia1 YUV */ #define <link linkend="V4L2-PIX-FMT-WNVA">V4L2_PIX_FMT_WNVA</link> v4l2_fourcc('W', 'N', 'V', 'A') /* Winnov hw compress */ #define <link linkend="V4L2-PIX-FMT-SN9C10X">V4L2_PIX_FMT_SN9C10X</link> v4l2_fourcc('S', '9', '1', '0') /* SN9C10x compression */ #define <link linkend="V4L2-PIX-FMT-SN9C20X-I420">V4L2_PIX_FMT_SN9C20X_I420</link> v4l2_fourcc('S', '9', '2', '0') /* SN9C20x YUV 4:2:0 */ @@ -358,12 +357,15 @@ struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> { #define <link linkend="V4L2-PIX-FMT-SPCA561">V4L2_PIX_FMT_SPCA561</link> v4l2_fourcc('S', '5', '6', '1') /* compressed GBRG bayer */ #define <link linkend="V4L2-PIX-FMT-PAC207">V4L2_PIX_FMT_PAC207</link> v4l2_fourcc('P', '2', '0', '7') /* compressed BGGR bayer */ #define <link linkend="V4L2-PIX-FMT-MR97310A">V4L2_PIX_FMT_MR97310A</link> v4l2_fourcc('M', '3', '1', '0') /* compressed BGGR bayer */ +#define <link linkend="V4L2-PIX-FMT-SN9C2028">V4L2_PIX_FMT_SN9C2028</link> v4l2_fourcc('S', 'O', 'N', 'X') /* compressed GBRG bayer */ #define <link linkend="V4L2-PIX-FMT-SQ905C">V4L2_PIX_FMT_SQ905C</link> v4l2_fourcc('9', '0', '5', 'C') /* compressed RGGB bayer */ #define <link linkend="V4L2-PIX-FMT-PJPG">V4L2_PIX_FMT_PJPG</link> v4l2_fourcc('P', 'J', 'P', 'G') /* Pixart 73xx JPEG */ #define <link linkend="V4L2-PIX-FMT-OV511">V4L2_PIX_FMT_OV511</link> v4l2_fourcc('O', '5', '1', '1') /* ov511 JPEG */ #define <link linkend="V4L2-PIX-FMT-OV518">V4L2_PIX_FMT_OV518</link> v4l2_fourcc('O', '5', '1', '8') /* ov518 JPEG */ -#define <link linkend="V4L2-PIX-FMT-TM6000">V4L2_PIX_FMT_TM6000</link> v4l2_fourcc('T', 'M', '6', '0') /* tm5600/tm60x0 */ #define <link linkend="V4L2-PIX-FMT-STV0680">V4L2_PIX_FMT_STV0680</link> v4l2_fourcc('S', '6', '8', '0') /* stv0680 bayer */ +#define <link linkend="V4L2-PIX-FMT-TM6000">V4L2_PIX_FMT_TM6000</link> v4l2_fourcc('T', 'M', '6', '0') /* tm5600/tm60x0 */ +#define <link linkend="V4L2-PIX-FMT-CIT-YYVYUY">V4L2_PIX_FMT_CIT_YYVYUY</link> v4l2_fourcc('C', 'I', 'T', 'V') /* one line of Y then 1 line of VYUY */ +#define <link linkend="V4L2-PIX-FMT-KONICA420">V4L2_PIX_FMT_KONICA420</link> v4l2_fourcc('K', 'O', 'N', 'I') /* YUV420 planar in blocks of 256 pixels */ /* * F O R M A T E N U M E R A T I O N @@ -380,7 +382,7 @@ struct <link linkend="v4l2-fmtdesc">v4l2_fmtdesc</link> { #define V4L2_FMT_FLAG_COMPRESSED 0x0001 #define V4L2_FMT_FLAG_EMULATED 0x0002 -#if 1 /*KEEP*/ +#if 1 /* Experimental Frame Size and frame rate enumeration */ /* * F R A M E S I Z E E N U M E R A T I O N @@ -544,6 +546,8 @@ struct <link linkend="v4l2-buffer">v4l2_buffer</link> { #define V4L2_BUF_FLAG_KEYFRAME 0x0008 /* Image is a keyframe (I-frame) */ #define V4L2_BUF_FLAG_PFRAME 0x0010 /* Image is a P-frame */ #define V4L2_BUF_FLAG_BFRAME 0x0020 /* Image is a B-frame */ +/* Buffer is ready, but the data contained within is corrupted. */ +#define V4L2_BUF_FLAG_ERROR 0x0040 #define V4L2_BUF_FLAG_TIMECODE 0x0100 /* timecode field is valid */ #define V4L2_BUF_FLAG_INPUT 0x0200 /* input field is valid */ @@ -934,6 +938,16 @@ struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link> { #define V4L2_CTRL_ID2CLASS(id) ((id) & 0x0fff0000UL) #define V4L2_CTRL_DRIVER_PRIV(id) (((id) & 0xffff) >= 0x1000) +enum <link linkend="v4l2-ctrl-type">v4l2_ctrl_type</link> { + V4L2_CTRL_TYPE_INTEGER = 1, + V4L2_CTRL_TYPE_BOOLEAN = 2, + V4L2_CTRL_TYPE_MENU = 3, + V4L2_CTRL_TYPE_BUTTON = 4, + V4L2_CTRL_TYPE_INTEGER64 = 5, + V4L2_CTRL_TYPE_CTRL_CLASS = 6, + V4L2_CTRL_TYPE_STRING = 7, +}; + /* Used in the VIDIOC_QUERYCTRL ioctl for querying controls */ struct <link linkend="v4l2-queryctrl">v4l2_queryctrl</link> { __u32 id; @@ -1018,21 +1032,27 @@ enum <link linkend="v4l2-colorfx">v4l2_colorfx</link> { V4L2_COLORFX_NONE = 0, V4L2_COLORFX_BW = 1, V4L2_COLORFX_SEPIA = 2, - V4L2_COLORFX_NEGATIVE = 3, - V4L2_COLORFX_EMBOSS = 4, - V4L2_COLORFX_SKETCH = 5, - V4L2_COLORFX_SKY_BLUE = 6, + V4L2_COLORFX_NEGATIVE = 3, + V4L2_COLORFX_EMBOSS = 4, + V4L2_COLORFX_SKETCH = 5, + V4L2_COLORFX_SKY_BLUE = 6, V4L2_COLORFX_GRASS_GREEN = 7, V4L2_COLORFX_SKIN_WHITEN = 8, - V4L2_COLORFX_VIVID = 9. + V4L2_COLORFX_VIVID = 9, }; #define V4L2_CID_AUTOBRIGHTNESS (V4L2_CID_BASE+32) #define V4L2_CID_BAND_STOP_FILTER (V4L2_CID_BASE+33) #define V4L2_CID_ROTATE (V4L2_CID_BASE+34) #define V4L2_CID_BG_COLOR (V4L2_CID_BASE+35) + +#define V4L2_CID_CHROMA_GAIN (V4L2_CID_BASE+36) + +#define V4L2_CID_ILLUMINATORS_1 (V4L2_CID_BASE+37) +#define V4L2_CID_ILLUMINATORS_2 (V4L2_CID_BASE+38) + /* last CID + 1 */ -#define V4L2_CID_LASTP1 (V4L2_CID_BASE+36) +#define V4L2_CID_LASTP1 (V4L2_CID_BASE+39) /* MPEG-class control IDs defined by V4L2 */ #define V4L2_CID_MPEG_BASE (V4L2_CTRL_CLASS_MPEG | 0x900) @@ -1349,6 +1369,8 @@ struct <link linkend="v4l2-modulator">v4l2_modulator</link> { #define V4L2_TUNER_CAP_SAP 0x0020 #define V4L2_TUNER_CAP_LANG1 0x0040 #define V4L2_TUNER_CAP_RDS 0x0080 +#define V4L2_TUNER_CAP_RDS_BLOCK_IO 0x0100 +#define V4L2_TUNER_CAP_RDS_CONTROLS 0x0200 /* Flags for the 'rxsubchans' field */ #define V4L2_TUNER_SUB_MONO 0x0001 @@ -1378,7 +1400,8 @@ struct <link linkend="v4l2-hw-freq-seek">v4l2_hw_freq_seek</link> { enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> type; __u32 seek_upward; __u32 wrap_around; - __u32 reserved[8]; + __u32 spacing; + __u32 reserved[7]; }; /* @@ -1433,7 +1456,7 @@ struct <link linkend="v4l2-audioout">v4l2_audioout</link> { * * NOTE: EXPERIMENTAL API */ -#if 1 /*KEEP*/ +#if 1 #define V4L2_ENC_IDX_FRAME_I (0) #define V4L2_ENC_IDX_FRAME_P (1) #define V4L2_ENC_IDX_FRAME_B (2) @@ -1626,6 +1649,38 @@ struct <link linkend="v4l2-streamparm">v4l2_streamparm</link> { }; /* + * E V E N T S + */ + +#define V4L2_EVENT_ALL 0 +#define V4L2_EVENT_VSYNC 1 +#define V4L2_EVENT_EOS 2 +#define V4L2_EVENT_PRIVATE_START 0x08000000 + +/* Payload for V4L2_EVENT_VSYNC */ +struct <link linkend="v4l2-event-vsync">v4l2_event_vsync</link> { + /* Can be V4L2_FIELD_ANY, _NONE, _TOP or _BOTTOM */ + __u8 field; +} __attribute__ ((packed)); + +struct <link linkend="v4l2-event">v4l2_event</link> { + __u32 type; + union { + struct <link linkend="v4l2-event-vsync">v4l2_event_vsync</link> vsync; + __u8 data[64]; + } u; + __u32 pending; + __u32 sequence; + struct timespec timestamp; + __u32 reserved[9]; +}; + +struct <link linkend="v4l2-event-subscription">v4l2_event_subscription</link> { + __u32 type; + __u32 reserved[7]; +}; + +/* * A D V A N C E D D E B U G G I N G * * NOTE: EXPERIMENTAL API, NEVER RELY ON THIS IN APPLICATIONS! @@ -1720,7 +1775,7 @@ struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link> { #define VIDIOC_G_EXT_CTRLS _IOWR('V', 71, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>) #define VIDIOC_S_EXT_CTRLS _IOWR('V', 72, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>) #define VIDIOC_TRY_EXT_CTRLS _IOWR('V', 73, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>) -#if 1 /*KEEP*/ +#if 1 #define VIDIOC_ENUM_FRAMESIZES _IOWR('V', 74, struct <link linkend="v4l2-frmsizeenum">v4l2_frmsizeenum</link>) #define VIDIOC_ENUM_FRAMEINTERVALS _IOWR('V', 75, struct <link linkend="v4l2-frmivalenum">v4l2_frmivalenum</link>) #define VIDIOC_G_ENC_INDEX _IOR('V', 76, struct <link linkend="v4l2-enc-idx">v4l2_enc_idx</link>) @@ -1728,7 +1783,7 @@ struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link> { #define VIDIOC_TRY_ENCODER_CMD _IOWR('V', 78, struct <link linkend="v4l2-encoder-cmd">v4l2_encoder_cmd</link>) #endif -#if 1 /*KEEP*/ +#if 1 /* Experimental, meant for debugging, testing and internal use. Only implemented if CONFIG_VIDEO_ADV_DEBUG is defined. You must be root to use these ioctls. Never use these in applications! */ @@ -1747,6 +1802,9 @@ struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link> { #define VIDIOC_QUERY_DV_PRESET _IOR('V', 86, struct <link linkend="v4l2-dv-preset">v4l2_dv_preset</link>) #define VIDIOC_S_DV_TIMINGS _IOWR('V', 87, struct <link linkend="v4l2-dv-timings">v4l2_dv_timings</link>) #define VIDIOC_G_DV_TIMINGS _IOWR('V', 88, struct <link linkend="v4l2-dv-timings">v4l2_dv_timings</link>) +#define VIDIOC_DQEVENT _IOR('V', 89, struct <link linkend="v4l2-event">v4l2_event</link>) +#define VIDIOC_SUBSCRIBE_EVENT _IOW('V', 90, struct <link linkend="v4l2-event-subscription">v4l2_event_subscription</link>) +#define VIDIOC_UNSUBSCRIBE_EVENT _IOW('V', 91, struct <link linkend="v4l2-event-subscription">v4l2_event_subscription</link>) /* Reminder: when adding new ioctls please add support for them to drivers/media/video/v4l2-compat-ioctl32.c as well! */ diff --git a/Documentation/DocBook/v4l/vidioc-g-dv-preset.xml b/Documentation/DocBook/v4l/vidioc-g-dv-preset.xml index 3c6784e132f..d733721a751 100644 --- a/Documentation/DocBook/v4l/vidioc-g-dv-preset.xml +++ b/Documentation/DocBook/v4l/vidioc-g-dv-preset.xml @@ -16,8 +16,7 @@ <funcdef>int <function>ioctl</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>&v4l2-dv-preset; -*<parameter>argp</parameter></paramdef> + <paramdef>struct v4l2_dv_preset *<parameter>argp</parameter></paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> diff --git a/Documentation/DocBook/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/v4l/vidioc-g-dv-timings.xml index ecc19576bb8..d5ec6abf0ce 100644 --- a/Documentation/DocBook/v4l/vidioc-g-dv-timings.xml +++ b/Documentation/DocBook/v4l/vidioc-g-dv-timings.xml @@ -16,8 +16,7 @@ <funcdef>int <function>ioctl</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>&v4l2-dv-timings; -*<parameter>argp</parameter></paramdef> + <paramdef>struct v4l2_dv_timings *<parameter>argp</parameter></paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> diff --git a/Documentation/DocBook/v4l/vidioc-query-dv-preset.xml b/Documentation/DocBook/v4l/vidioc-query-dv-preset.xml index 402229ee06f..d272f7ab91b 100644 --- a/Documentation/DocBook/v4l/vidioc-query-dv-preset.xml +++ b/Documentation/DocBook/v4l/vidioc-query-dv-preset.xml @@ -16,7 +16,7 @@ input</refpurpose> <funcdef>int <function>ioctl</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>&v4l2-dv-preset; *<parameter>argp</parameter></paramdef> + <paramdef>struct v4l2_dv_preset *<parameter>argp</parameter></paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> diff --git a/Documentation/DocBook/v4l/vidioc-querycap.xml b/Documentation/DocBook/v4l/vidioc-querycap.xml index 6ab7e25b31b..d499da93a45 100644 --- a/Documentation/DocBook/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/v4l/vidioc-querycap.xml @@ -184,7 +184,7 @@ data.</entry> <row> <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry> <entry>0x00000100</entry> - <entry>The device supports the <link linkend="rds">RDS</link> interface.</entry> + <entry>The device supports the <link linkend="rds">RDS</link> capture interface.</entry> </row> <row> <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry> @@ -206,6 +206,11 @@ driver capabilities.</para></footnote></entry> hardware frequency seeking.</entry> </row> <row> + <entry><constant>V4L2_CAP_RDS_OUTPUT</constant></entry> + <entry>0x00000800</entry> + <entry>The device supports the <link linkend="rds">RDS</link> output interface.</entry> + </row> + <row> <entry><constant>V4L2_CAP_TUNER</constant></entry> <entry>0x00010000</entry> <entry>The device has some sort of tuner to diff --git a/Documentation/DocBook/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/v4l/vidioc-queryctrl.xml index 8e0e055ac93..0d5e8283cf3 100644 --- a/Documentation/DocBook/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/v4l/vidioc-queryctrl.xml @@ -103,8 +103,12 @@ structure. The driver fills the rest of the structure or returns an <structfield>index</structfield> is invalid. Menu items are enumerated by calling <constant>VIDIOC_QUERYMENU</constant> with successive <structfield>index</structfield> values from &v4l2-queryctrl; -<structfield>minimum</structfield> (0) to -<structfield>maximum</structfield>, inclusive.</para> +<structfield>minimum</structfield> to +<structfield>maximum</structfield>, inclusive. Note that it is possible +for <constant>VIDIOC_QUERYMENU</constant> to return an &EINVAL; for some +indices between <structfield>minimum</structfield> and <structfield>maximum</structfield>. +In that case that particular menu item is not supported by this driver. Also note that +the <structfield>minimum</structfield> value is not necessarily 0.</para> <para>See also the examples in <xref linkend="control" />.</para> @@ -139,7 +143,7 @@ string. This information is intended for the user.</entry> <entry><structfield>minimum</structfield></entry> <entry>Minimum value, inclusive. This field gives a lower bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the -lowest valid index (always 0) for <constant>V4L2_CTRL_TYPE_MENU</constant> controls. +lowest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> controls. For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value gives the minimum length of the string. This length <emphasis>does not include the terminating zero</emphasis>. It may not be valid for any other type of control, including @@ -279,7 +283,7 @@ values which are actually different on the hardware.</entry> </row> <row> <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry> - <entry>0</entry> + <entry>≥ 0</entry> <entry>1</entry> <entry>N-1</entry> <entry>The control has a menu of N choices. The names of @@ -405,8 +409,10 @@ writing a value will cause the device to carry out a given action <term><errorcode>EINVAL</errorcode></term> <listitem> <para>The &v4l2-queryctrl; <structfield>id</structfield> -is invalid. The &v4l2-querymenu; <structfield>id</structfield> or -<structfield>index</structfield> is invalid.</para> +is invalid. The &v4l2-querymenu; <structfield>id</structfield> is +invalid or <structfield>index</structfield> is out of range (less than +<structfield>minimum</structfield> or greater than <structfield>maximum</structfield>) +or this particular menu item is not supported by the driver.</para> </listitem> </varlistentry> <varlistentry> diff --git a/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml index 14b3ec7ed75..c30dcc4232c 100644 --- a/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml +++ b/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml @@ -51,7 +51,8 @@ <para>Start a hardware frequency seek from the current frequency. To do this applications initialize the <structfield>tuner</structfield>, -<structfield>type</structfield>, <structfield>seek_upward</structfield> and +<structfield>type</structfield>, <structfield>seek_upward</structfield>, +<structfield>spacing</structfield> and <structfield>wrap_around</structfield> fields, and zero out the <structfield>reserved</structfield> array of a &v4l2-hw-freq-seek; and call the <constant>VIDIOC_S_HW_FREQ_SEEK</constant> ioctl with a pointer @@ -89,7 +90,12 @@ field and the &v4l2-tuner; <structfield>index</structfield> field.</entry> </row> <row> <entry>__u32</entry> - <entry><structfield>reserved</structfield>[8]</entry> + <entry><structfield>spacing</structfield></entry> + <entry>If non-zero, defines the hardware seek resolution in Hz. The driver selects the nearest value that is supported by the device. If spacing is zero a reasonable default value is used.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[7]</entry> <entry>Reserved for future extensions. Drivers and applications must set the array to zero.</entry> </row> diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 40ada93b820..365bda9a0d9 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -187,7 +187,7 @@ apply a patch. If you do not know where you want to start, but you want to look for some task to start doing to join into the kernel development community, go to the Linux Kernel Janitor's project: - http://janitor.kernelnewbies.org/ + http://kernelnewbies.org/KernelJanitors It is a great place to start. It describes a list of relatively simple problems that need to be cleaned up and fixed within the Linux kernel source tree. Working with the developers in charge of this project, you @@ -315,7 +315,7 @@ process is tracked with the tool patchwork. Patchwork offers a web interface which shows patch postings, any comments on a patch or revisions to it, and maintainers can mark patches as under review, accepted, or rejected. Most of these patchwork sites are listed at -http://patchwork.kernel.org/ or http://patchwork.ozlabs.org/. +http://patchwork.kernel.org/. 2.6.x -next kernel tree for integration tests --------------------------------------------- @@ -595,7 +595,7 @@ start exactly where you are now. ---------- Thanks to Paolo Ciarrocchi who allowed the "Development Process" -(http://linux.tar.bz/articles/2.6-development_process) section +(http://lwn.net/Articles/94386/) section to be based on text he had written, and to Randy Dunlap and Gerrit Huizenga for some of the list of things you should and should not say. Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, diff --git a/Documentation/PCI/pci.txt b/Documentation/PCI/pci.txt index 7f6de6ea5b4..6148d4080f8 100644 --- a/Documentation/PCI/pci.txt +++ b/Documentation/PCI/pci.txt @@ -581,7 +581,7 @@ to be handled by platform and generic code, not individual drivers. 8. Vendor and device identifications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -One is not not required to add new device ids to include/linux/pci_ids.h. +One is not required to add new device ids to include/linux/pci_ids.h. Please add PCI_VENDOR_ID_xxx for vendors and a hex constant for device ids. PCI_VENDOR_ID_xxx constants are re-used. The device ids are arbitrary diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.txt index 5aea459e3dd..c43460dade0 100644 --- a/Documentation/RCU/RTFP.txt +++ b/Documentation/RCU/RTFP.txt @@ -606,7 +606,7 @@ Suparna Bhattacharya" ,Year="2006" ,pages="v2 123-138" ,note="Available: -\url{http://www.linuxsymposium.org/2006/view_abstract.php?content_key=184} +\url{http://www.linuxsymposium.org/2006/index_2006.php} \url{http://www.rdrop.com/users/paulmck/RCU/OLSrtRCU.2006.08.11a.pdf} [Viewed January 1, 2007]" ,annotation=" diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt index 790d1a81237..0c134f8afc6 100644 --- a/Documentation/RCU/checklist.txt +++ b/Documentation/RCU/checklist.txt @@ -218,13 +218,22 @@ over a rather long period of time, but improvements are always welcome! include: a. Keeping a count of the number of data-structure elements - used by the RCU-protected data structure, including those - waiting for a grace period to elapse. Enforce a limit - on this number, stalling updates as needed to allow - previously deferred frees to complete. - - Alternatively, limit only the number awaiting deferred - free rather than the total number of elements. + used by the RCU-protected data structure, including + those waiting for a grace period to elapse. Enforce a + limit on this number, stalling updates as needed to allow + previously deferred frees to complete. Alternatively, + limit only the number awaiting deferred free rather than + the total number of elements. + + One way to stall the updates is to acquire the update-side + mutex. (Don't try this with a spinlock -- other CPUs + spinning on the lock could prevent the grace period + from ever ending.) Another way to stall the updates + is for the updates to use a wrapper function around + the memory allocator, so that this wrapper function + simulates OOM when there is too much memory awaiting an + RCU grace period. There are of course many other + variations on this theme. b. Limiting update rate. For example, if updates occur only once per hour, then no explicit rate limiting is required, @@ -365,3 +374,26 @@ over a rather long period of time, but improvements are always welcome! and the compiler to freely reorder code into and out of RCU read-side critical sections. It is the responsibility of the RCU update-side primitives to deal with this. + +17. Use CONFIG_PROVE_RCU, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and + the __rcu sparse checks to validate your RCU code. These + can help find problems as follows: + + CONFIG_PROVE_RCU: check that accesses to RCU-protected data + structures are carried out under the proper RCU + read-side critical section, while holding the right + combination of locks, or whatever other conditions + are appropriate. + + CONFIG_DEBUG_OBJECTS_RCU_HEAD: check that you don't pass the + same object to call_rcu() (or friends) before an RCU + grace period has elapsed since the last time that you + passed that same object to call_rcu() (or friends). + + __rcu sparse checks: tag the pointer to the RCU-protected data + structure with __rcu, and sparse will warn you if you + access that pointer without the services of one of the + variants of rcu_dereference(). + + These debugging aids can help you find problems that are + otherwise extremely difficult to spot. diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index 44c6dcc93d6..862c08ef1fd 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -80,6 +80,24 @@ o A CPU looping with bottom halves disabled. This condition can o For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel without invoking schedule(). +o A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might + happen to preempt a low-priority task in the middle of an RCU + read-side critical section. This is especially damaging if + that low-priority task is not permitted to run on any other CPU, + in which case the next RCU grace period can never complete, which + will eventually cause the system to run out of memory and hang. + While the system is in the process of running itself out of + memory, you might see stall-warning messages. + +o A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that + is running at a higher priority than the RCU softirq threads. + This will prevent RCU callbacks from ever being invoked, + and in a CONFIG_TREE_PREEMPT_RCU kernel will further prevent + RCU grace periods from ever completing. Either way, the + system will eventually run out of memory and hang. In the + CONFIG_TREE_PREEMPT_RCU case, you might see stall-warning + messages. + o A bug in the RCU implementation. o A hardware failure. This is quite unlikely, but has occurred diff --git a/Documentation/RCU/trace.txt b/Documentation/RCU/trace.txt index efd8cc95c06..a851118775d 100644 --- a/Documentation/RCU/trace.txt +++ b/Documentation/RCU/trace.txt @@ -125,6 +125,17 @@ 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. +o "ci" is the number of RCU callbacks that have been invoked for + this CPU. Note that ci+ql is the number of callbacks that have + been registered in absence of CPU-hotplug activity. + +o "co" is the number of RCU callbacks that have been orphaned due to + this CPU going offline. + +o "ca" is the number of RCU callbacks that have been adopted due to + other CPUs going offline. Note that ci+co-ca+ql is the number of + RCU callbacks registered on this CPU. + There is also an rcu/rcudata.csv file with the same information in comma-separated-variable spreadsheet format. @@ -180,7 +191,7 @@ o "s" is the "signaled" state that drives force_quiescent_state()'s 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 + along. Note that CPUs in dyntick-idle mode throughout the grace period will not report on their own, but rather must be check by some other CPU via force_quiescent_state(). diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index 4947fd8fb18..38d2aab59ca 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -161,7 +161,7 @@ How to NOT write kernel driver by Arjan van de Ven: http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf Kernel Janitor: - http://janitor.kernelnewbies.org/ + http://kernelnewbies.org/KernelJanitors GIT, Fast Version Control System: http://git-scm.com/ diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 72651f788f4..689e2371095 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -98,6 +98,17 @@ system, git, as a "commit log". See #15, below. If your description starts to get long, that's a sign that you probably need to split up your patch. See #3, next. +When you submit or resubmit a patch or patch series, include the +complete patch description and justification for it. Don't just +say that this is version N of the patch (series). Don't expect the +patch merger to refer back to earlier patch versions or referenced +URLs to find the patch description and put that into the patch. +I.e., the patch (series) and its description should be self-contained. +This benefits both the patch merger(s) and reviewers. Some reviewers +probably didn't even receive earlier versions of the patch. + +If the patch fixes a logged bug entry, refer to that bug entry by +number and URL. 3) Separate your changes. diff --git a/Documentation/accounting/getdelays.c b/Documentation/accounting/getdelays.c index 6e25c2659e0..a2976a6de03 100644 --- a/Documentation/accounting/getdelays.c +++ b/Documentation/accounting/getdelays.c @@ -21,6 +21,7 @@ #include <sys/types.h> #include <sys/stat.h> #include <sys/socket.h> +#include <sys/wait.h> #include <signal.h> #include <linux/genetlink.h> @@ -266,11 +267,13 @@ int main(int argc, char *argv[]) int containerset = 0; char containerpath[1024]; int cfd = 0; + int forking = 0; + sigset_t sigset; struct msgtemplate msg; - while (1) { - c = getopt(argc, argv, "qdiw:r:m:t:p:vlC:"); + while (!forking) { + c = getopt(argc, argv, "qdiw:r:m:t:p:vlC:c:"); if (c < 0) break; @@ -319,6 +322,28 @@ int main(int argc, char *argv[]) err(1, "Invalid pid\n"); cmd_type = TASKSTATS_CMD_ATTR_PID; break; + case 'c': + + /* Block SIGCHLD for sigwait() later */ + if (sigemptyset(&sigset) == -1) + err(1, "Failed to empty sigset"); + if (sigaddset(&sigset, SIGCHLD)) + err(1, "Failed to set sigchld in sigset"); + sigprocmask(SIG_BLOCK, &sigset, NULL); + + /* fork/exec a child */ + tid = fork(); + if (tid < 0) + err(1, "Fork failed\n"); + if (tid == 0) + if (execvp(argv[optind - 1], + &argv[optind - 1]) < 0) + exit(-1); + + /* Set the command type and avoid further processing */ + cmd_type = TASKSTATS_CMD_ATTR_PID; + forking = 1; + break; case 'v': printf("debug on\n"); dbg = 1; @@ -370,6 +395,15 @@ int main(int argc, char *argv[]) goto err; } + /* + * If we forked a child, wait for it to exit. Cannot use waitpid() + * as all the delicious data would be reaped as part of the wait + */ + if (tid && forking) { + int sig_received; + sigwait(&sigset, &sig_received); + } + if (tid) { rc = send_cmd(nl_sd, id, mypid, TASKSTATS_CMD_GET, cmd_type, &tid, sizeof(__u32)); diff --git a/Documentation/acpi/method-customizing.txt b/Documentation/acpi/method-customizing.txt index e628cd23ca8..3e1d25aee3f 100644 --- a/Documentation/acpi/method-customizing.txt +++ b/Documentation/acpi/method-customizing.txt @@ -19,6 +19,8 @@ Note: Only ACPI METHOD can be overridden, any other object types like "Device", "OperationRegion", are not recognized. Note: The same ACPI control method can be overridden for many times, and it's always the latest one that used by Linux/kernel. +Note: To get the ACPI debug object output (Store (AAAA, Debug)), + please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output". 1. override an existing method a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT, diff --git a/Documentation/aoe/aoe.txt b/Documentation/aoe/aoe.txt index 3a4dbe4663c..b5aada9f20c 100644 --- a/Documentation/aoe/aoe.txt +++ b/Documentation/aoe/aoe.txt @@ -1,6 +1,6 @@ The EtherDrive (R) HOWTO for users of 2.6 kernels is found at ... - http://www.coraid.com/support/linux/EtherDrive-2.6-HOWTO.html + http://www.coraid.com/SUPPORT/EtherDrive-HBA It has many tips and hints! diff --git a/Documentation/apparmor.txt b/Documentation/apparmor.txt new file mode 100644 index 00000000000..93c1fd7d063 --- /dev/null +++ b/Documentation/apparmor.txt @@ -0,0 +1,39 @@ +--- What is AppArmor? --- + +AppArmor is MAC style security extension for the Linux kernel. It implements +a task centered policy, with task "profiles" being created and loaded +from user space. Tasks on the system that do not have a profile defined for +them run in an unconfined state which is equivalent to standard Linux DAC +permissions. + +--- How to enable/disable --- + +set CONFIG_SECURITY_APPARMOR=y + +If AppArmor should be selected as the default security module then + set CONFIG_DEFAULT_SECURITY="apparmor" + and CONFIG_SECURITY_APPARMOR_BOOTPARAM_VALUE=1 + +Build the kernel + +If AppArmor is not the default security module it can be enabled by passing +security=apparmor on the kernel's command line. + +If AppArmor is the default security module it can be disabled by passing +apparmor=0, security=XXXX (where XXX is valid security module), on the +kernel's command line + +For AppArmor to enforce any restrictions beyond standard Linux DAC permissions +policy must be loaded into the kernel from user space (see the Documentation +and tools links). + +--- Documentation --- + +Documentation can be found on the wiki. + +--- Links --- + +Mailing List - apparmor@lists.ubuntu.com +Wiki - http://apparmor.wiki.kernel.org/ +User space tools - https://launchpad.net/apparmor +Kernel module - git://git.kernel.org/pub/scm/linux/kernel/git/jj/apparmor-dev.git diff --git a/Documentation/arm/00-INDEX b/Documentation/arm/00-INDEX index 7f5fc3ba9c9..ecf7d04bca2 100644 --- a/Documentation/arm/00-INDEX +++ b/Documentation/arm/00-INDEX @@ -6,6 +6,8 @@ Interrupts - ARM Interrupt subsystem documentation IXP2000 - Release Notes for Linux on Intel's IXP2000 Network Processor +msm + - MSM specific documentation Netwinder - Netwinder specific documentation Porting diff --git a/Documentation/arm/IXP2000 b/Documentation/arm/IXP2000 index e0148b6b2c4..68d21d92a30 100644 --- a/Documentation/arm/IXP2000 +++ b/Documentation/arm/IXP2000 @@ -14,7 +14,7 @@ telecom systems. In addition to an XScale core, it contains up to 8 interfaces (UTOPIA, SPI, etc), a PCI host bridge, one serial port, flash interface, and some other odds and ends. For more information, see: -http://developer.intel.com/design/network/products/npfamily/ixp2xxx.htm +http://developer.intel.com 2. Linux Support diff --git a/Documentation/arm/IXP4xx b/Documentation/arm/IXP4xx index 72fbcc4fcab..133c5fa6c7a 100644 --- a/Documentation/arm/IXP4xx +++ b/Documentation/arm/IXP4xx @@ -45,7 +45,7 @@ require the use of Intel's propietary CSR softare: If you need to use any of the above, you need to download Intel's software from: - http://developer.intel.com/design/network/products/npfamily/ixp425swr1.htm + http://developer.intel.com/design/network/products/npfamily/ixp425.htm DO NOT POST QUESTIONS TO THE LINUX MAILING LISTS REGARDING THE PROPIETARY SOFTWARE. @@ -53,7 +53,7 @@ SOFTWARE. There are several websites that provide directions/pointers on using Intel's software: -http://ixp4xx-osdg.sourceforge.net/ + http://sourceforge.net/projects/ixp4xx-osdg/ Open Source Developer's Guide for using uClinux and the Intel libraries http://gatewaymaker.sourceforge.net/ @@ -112,21 +112,21 @@ http://www.adiengineering.com/productsCoyote.html Finally, there is an IDE port hanging off the expansion bus. Gateworks Avila Network Platform -http://www.gateworks.com/avila_sbc.htm +http://www.gateworks.com/support/overview.php The Avila platform is basically and IXDP425 with the 4 PCI slots replaced with mini-PCI slots and a CF IDE interface hanging off the expansion bus. Intel IXDP425 Development Platform -http://developer.intel.com/design/network/products/npfamily/ixdp425.htm +http://www.intel.com/design/network/products/npfamily/ixdpg425.htm This is Intel's standard reference platform for the IXDP425 and is also known as the Richfield board. It contains 4 PCI slots, 16MB of flash, two 10/100 ports and one ADSL port. Intel IXDP465 Development Platform -http://developer.intel.com/design/network/products/npfamily/ixdp465.htm +http://www.intel.com/design/network/products/npfamily/ixdp465.htm This is basically an IXDP425 with an IXP465 and 32M of flash instead of just 16. @@ -141,15 +141,13 @@ Intel IXDPG425 Development Platform a pivot_root to NFS. Motorola PrPMC1100 Processor Mezanine Card -http://www.fountainsys.com/datasheet/PrPMC1100.pdf +http://www.fountainsys.com The PrPMC1100 is based on the IXCP1100 and is meant to plug into and IXP2400/2800 system to act as the system controller. It simply contains a CPU and 16MB of flash on the board and needs to be plugged into a carrier board to function. Currently Linux only supports the Motorola PrPMC carrier board for this platform. - See https://mcg.motorola.com/us/ds/pdf/ds0144.pdf for info - on the carrier board. 5. TODO LIST diff --git a/Documentation/arm/README b/Documentation/arm/README index d98783fbe0c..aea34095cdc 100644 --- a/Documentation/arm/README +++ b/Documentation/arm/README @@ -41,12 +41,12 @@ Bug reports etc --------------- Please send patches to the patch system. For more information, see - http://www.arm.linux.org.uk/patches/info.html Always include some + http://www.arm.linux.org.uk/developer/patches/info.php Always include some explanation as to what the patch does and why it is needed. Bug reports should be sent to linux-arm-kernel@lists.arm.linux.org.uk, or submitted through the web form at - http://www.arm.linux.org.uk/forms/solution.shtml + http://www.arm.linux.org.uk/developer/ When sending bug reports, please ensure that they contain all relevant information, eg. the kernel messages that were printed before/during diff --git a/Documentation/arm/SA1100/Assabet b/Documentation/arm/SA1100/Assabet index 91f7ce7ba42..08b885d3567 100644 --- a/Documentation/arm/SA1100/Assabet +++ b/Documentation/arm/SA1100/Assabet @@ -2,8 +2,7 @@ The Intel Assabet (SA-1110 evaluation) board ============================================ Please see: -http://developer.intel.com/design/strong/quicklist/eval-plat/sa-1110.htm -http://developer.intel.com/design/strong/guides/278278.htm +http://developer.intel.com Also some notes from John G Dorsey <jd5q@andrew.cmu.edu>: http://www.cs.cmu.edu/~wearable/software/assabet.html @@ -64,7 +63,7 @@ Initial RedBoot configuration ----------------------------- The commands used here are explained in The RedBoot User's Guide available -on-line at http://sources.redhat.com/ecos/docs-latest/redboot/redboot.html. +on-line at http://sources.redhat.com/ecos/docs.html. Please refer to it for explanations. If you have a CF network card (my Assabet kit contained a CF+ LP-E from diff --git a/Documentation/arm/SA1100/Brutus b/Documentation/arm/SA1100/Brutus index b1cfd405dcc..6a3aa95e9bf 100644 --- a/Documentation/arm/SA1100/Brutus +++ b/Documentation/arm/SA1100/Brutus @@ -1,7 +1,7 @@ Brutus is an evaluation platform for the SA1100 manufactured by Intel. For more details, see: -http://developer.intel.com/design/strong/applnots/sa1100lx/getstart.htm +http://developer.intel.com To compile for Brutus, you must issue the following commands: diff --git a/Documentation/arm/SA1100/FreeBird b/Documentation/arm/SA1100/FreeBird index eda28b3232e..ab9193663b2 100644 --- a/Documentation/arm/SA1100/FreeBird +++ b/Documentation/arm/SA1100/FreeBird @@ -1,6 +1,6 @@ -Freebird-1.1 is produced by Legned(C) ,Inc. -(http://www.legend.com.cn) -and software/linux mainatined by Coventive(C),Inc. +Freebird-1.1 is produced by Legend(C), Inc. +http://web.archive.org/web/*/http://www.legend.com.cn +and software/linux maintained by Coventive(C), Inc. (http://www.coventive.com) Based on the Nicolas's strongarm kernel tree. diff --git a/Documentation/arm/SA1100/GraphicsClient b/Documentation/arm/SA1100/GraphicsClient index 6c9c4f5a36e..867bb35943a 100644 --- a/Documentation/arm/SA1100/GraphicsClient +++ b/Documentation/arm/SA1100/GraphicsClient @@ -71,7 +71,7 @@ Supported peripherals: - serial ports (ttyS[0-2]) - ttyS0 is default for serial console - Smart I/O (ADC, keypad, digital inputs, etc) - See http://www.applieddata.com/developers/linux for IOCTL documentation + See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation and example user space code. ps/2 keybd is multiplexed through this driver To do: diff --git a/Documentation/arm/SA1100/GraphicsMaster b/Documentation/arm/SA1100/GraphicsMaster index ee7c6595f23..9145088a0ba 100644 --- a/Documentation/arm/SA1100/GraphicsMaster +++ b/Documentation/arm/SA1100/GraphicsMaster @@ -28,7 +28,7 @@ Supported peripherals: - serial ports (ttyS[0-2]) - ttyS0 is default for serial console - Smart I/O (ADC, keypad, digital inputs, etc) - See http://www.applieddata.com/developers/linux for IOCTL documentation + See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation and example user space code. ps/2 keybd is multiplexed through this driver To do: diff --git a/Documentation/arm/SA1100/Itsy b/Documentation/arm/SA1100/Itsy index 3b594534323..44b94997fa0 100644 --- a/Documentation/arm/SA1100/Itsy +++ b/Documentation/arm/SA1100/Itsy @@ -4,7 +4,7 @@ research projects at Compaq that are related to pocket computing. For more information, see: - http://www.research.digital.com/wrl/itsy/index.html + http://www.hpl.hp.com/downloads/crl/itsy/ Notes on initial 2.4 Itsy support (8/27/2000) : The port was done on an Itsy version 1.5 machine with a daughtercard with diff --git a/Documentation/arm/SA1100/PLEB b/Documentation/arm/SA1100/PLEB index 92cae066908..b9c8a631a35 100644 --- a/Documentation/arm/SA1100/PLEB +++ b/Documentation/arm/SA1100/PLEB @@ -6,6 +6,6 @@ PLEB support has yet to be fully integrated. For more information, see: - http://www.cse.unsw.edu.au/~pleb/ + http://www.cse.unsw.edu.au diff --git a/Documentation/arm/SA1100/Victor b/Documentation/arm/SA1100/Victor index f938a29fdc2..9cff415da5a 100644 --- a/Documentation/arm/SA1100/Victor +++ b/Documentation/arm/SA1100/Victor @@ -3,7 +3,7 @@ VisuAide, Inc. to be used by blind people. For more information related to Victor, see: - http://www.visuaide.com/victor + http://www.humanware.com/en-usa/products Of course Victor is using Linux as its main operating system. The Victor implementation for Linux is maintained by Nicolas Pitre: diff --git a/Documentation/arm/SA1100/nanoEngine b/Documentation/arm/SA1100/nanoEngine index fc431cbfefc..48a7934f95f 100644 --- a/Documentation/arm/SA1100/nanoEngine +++ b/Documentation/arm/SA1100/nanoEngine @@ -7,5 +7,5 @@ for more info. (Ref: Stuart Adams <sja@brightstareng.com>) Also visit Larry Doolittle's "Linux for the nanoEngine" site: -http://recycle.lbl.gov/~ldoolitt/bse/ +http://www.brightstareng.com/arm/nanoeng.htm diff --git a/Documentation/arm/memory.txt b/Documentation/arm/memory.txt index eb0fae18ffb..771d48d3b33 100644 --- a/Documentation/arm/memory.txt +++ b/Documentation/arm/memory.txt @@ -33,7 +33,13 @@ ffff0000 ffff0fff CPU vector page. fffe0000 fffeffff XScale cache flush area. This is used in proc-xscale.S to flush the whole data - cache. Free for other usage on non-XScale. + cache. (XScale does not have TCM.) + +fffe8000 fffeffff DTCM mapping area for platforms with + DTCM mounted inside the CPU. + +fffe0000 fffe7fff ITCM mapping area for platforms with + ITCM mounted inside the CPU. fff00000 fffdffff Fixmap mapping region. Addresses provided by fix_to_virt() will be located here. diff --git a/Documentation/arm/msm/gpiomux.txt b/Documentation/arm/msm/gpiomux.txt new file mode 100644 index 00000000000..67a81620adf --- /dev/null +++ b/Documentation/arm/msm/gpiomux.txt @@ -0,0 +1,176 @@ +This document provides an overview of the msm_gpiomux interface, which +is used to provide gpio pin multiplexing and configuration on mach-msm +targets. + +History +======= + +The first-generation API for gpio configuration & multiplexing on msm +is the function gpio_tlmm_config(). This function has a few notable +shortcomings, which led to its deprecation and replacement by gpiomux: + +The 'disable' parameter: Setting the second parameter to +gpio_tlmm_config to GPIO_CFG_DISABLE tells the peripheral +processor in charge of the subsystem to perform a look-up into a +low-power table and apply the low-power/sleep setting for the pin. +As the msm family evolved this became problematic. Not all pins +have sleep settings, not all peripheral processors will accept requests +to apply said sleep settings, and not all msm targets have their gpio +subsystems managed by a peripheral processor. In order to get consistent +behavior on all targets, drivers are forced to ignore this parameter, +rendering it useless. + +The 'direction' flag: for all mux-settings other than raw-gpio (0), +the output-enable bit of a gpio is hard-wired to a known +input (usually VDD or ground). For those settings, the direction flag +is meaningless at best, and deceptive at worst. In addition, using the +direction flag to change output-enable (OE) directly can cause trouble in +gpiolib, which has no visibility into gpio direction changes made +in this way. Direction control in gpio mode should be made through gpiolib. + +Key Features of gpiomux +======================= + +- A consistent interface across all generations of msm. Drivers can expect +the same results on every target. +- gpiomux plays nicely with gpiolib. Functions that should belong to gpiolib +are left to gpiolib and not duplicated here. gpiomux is written with the +intent that gpio_chips will call gpiomux reference-counting methods +from their request() and free() hooks, providing full integration. +- Tabular configuration. Instead of having to call gpio_tlmm_config +hundreds of times, gpio configuration is placed in a single table. +- Per-gpio sleep. Each gpio is individually reference counted, allowing only +those lines which are in use to be put in high-power states. +- 0 means 'do nothing': all flags are designed so that the default memset-zero +equates to a sensible default of 'no configuration', preventing users +from having to provide hundreds of 'no-op' configs for unused or +unwanted lines. + +Usage +===== + +To use gpiomux, provide configuration information for relevant gpio lines +in the msm_gpiomux_configs table. Since a 0 equates to "unconfigured", +only those lines to be managed by gpiomux need to be specified. Here +is a completely fictional example: + +struct msm_gpiomux_config msm_gpiomux_configs[GPIOMUX_NGPIOS] = { + [12] = { + .active = GPIOMUX_VALID | GPIOMUX_DRV_8MA | GPIOMUX_FUNC_1, + .suspended = GPIOMUX_VALID | GPIOMUX_PULL_DOWN, + }, + [34] = { + .suspended = GPIOMUX_VALID | GPIOMUX_PULL_DOWN, + }, +}; + +To indicate that a gpio is in use, call msm_gpiomux_get() to increase +its reference count. To decrease the reference count, call msm_gpiomux_put(). + +The effect of this configuration is as follows: + +When the system boots, gpios 12 and 34 will be initialized with their +'suspended' configurations. All other gpios, which were left unconfigured, +will not be touched. + +When msm_gpiomux_get() is called on gpio 12 to raise its reference count +above 0, its active configuration will be applied. Since no other gpio +line has a valid active configuration, msm_gpiomux_get() will have no +effect on any other line. + +When msm_gpiomux_put() is called on gpio 12 or 34 to drop their reference +count to 0, their suspended configurations will be applied. +Since no other gpio line has a valid suspended configuration, no other +gpio line will be effected by msm_gpiomux_put(). Since gpio 34 has no valid +active configuration, this is effectively a no-op for gpio 34 as well, +with one small caveat, see the section "About Output-Enable Settings". + +All of the GPIOMUX_VALID flags may seem like unnecessary overhead, but +they address some important issues. As unused entries (all those +except 12 and 34) are zero-filled, gpiomux needs a way to distinguish +the used fields from the unused. In addition, the all-zero pattern +is a valid configuration! Therefore, gpiomux defines an additional bit +which is used to indicate when a field is used. This has the pleasant +side-effect of allowing calls to msm_gpiomux_write to use '0' to indicate +that a value should not be changed: + + msm_gpiomux_write(0, GPIOMUX_VALID, 0); + +replaces the active configuration of gpio 0 with an all-zero configuration, +but leaves the suspended configuration as it was. + +Static Configurations +===================== + +To install a static configuration, which is applied at boot and does +not change after that, install a configuration with a suspended component +but no active component, as in the previous example: + + [34] = { + .suspended = GPIOMUX_VALID | GPIOMUX_PULL_DOWN, + }, + +The suspended setting is applied during boot, and the lack of any valid +active setting prevents any other setting from being applied at runtime. +If other subsystems attempting to access the line is a concern, one could +*really* anchor the configuration down by calling msm_gpiomux_get on the +line at initialization to move the line into active mode. With the line +held, it will never be re-suspended, and with no valid active configuration, +no new configurations will be applied. + +But then, if having other subsystems grabbing for the line is truly a concern, +it should be reserved with gpio_request instead, which carries an implicit +msm_gpiomux_get. + +gpiomux and gpiolib +=================== + +It is expected that msm gpio_chips will call msm_gpiomux_get() and +msm_gpiomux_put() from their request and free hooks, like this fictional +example: + +static int request(struct gpio_chip *chip, unsigned offset) +{ + return msm_gpiomux_get(chip->base + offset); +} + +static void free(struct gpio_chip *chip, unsigned offset) +{ + msm_gpiomux_put(chip->base + offset); +} + + ...somewhere in a gpio_chip declaration... + .request = request, + .free = free, + +This provides important functionality: +- It guarantees that a gpio line will have its 'active' config applied + when the line is requested, and will not be suspended while the line + remains requested; and +- It guarantees that gpio-direction settings from gpiolib behave sensibly. + See "About Output-Enable Settings." + +This mechanism allows for "auto-request" of gpiomux lines via gpiolib +when it is suitable. Drivers wishing more exact control are, of course, +free to also use msm_gpiomux_set and msm_gpiomux_get. + +About Output-Enable Settings +============================ + +Some msm targets do not have the ability to query the current gpio +configuration setting. This means that changes made to the output-enable +(OE) bit by gpiolib cannot be consistently detected and preserved by gpiomux. +Therefore, when gpiomux applies a configuration setting, any direction +settings which may have been applied by gpiolib are lost and the default +input settings are re-applied. + +For this reason, drivers should not assume that gpio direction settings +continue to hold if they free and then re-request a gpio. This seems like +common sense - after all, anybody could have obtained the line in the +meantime - but it needs saying. + +This also means that calls to msm_gpiomux_write will reset the OE bit, +which means that if the gpio line is held by a client of gpiolib and +msm_gpiomux_write is called, the direction setting has been lost and +gpiolib's internal state has been broken. +Release gpio lines before reconfiguring them. diff --git a/Documentation/arm/tcm.txt b/Documentation/arm/tcm.txt index 77fd9376e6d..7c15871c188 100644 --- a/Documentation/arm/tcm.txt +++ b/Documentation/arm/tcm.txt @@ -19,8 +19,8 @@ defines a CPUID_TCM register that you can read out from the system control coprocessor. Documentation from ARM can be found at http://infocenter.arm.com, search for "TCM Status Register" to see documents for all CPUs. Reading this register you can -determine if ITCM (bit 0) and/or DTCM (bit 16) is present in the -machine. +determine if ITCM (bits 1-0) and/or DTCM (bit 17-16) is present +in the machine. There is further a TCM region register (search for "TCM Region Registers" at the ARM site) that can report and modify the location @@ -35,7 +35,15 @@ The TCM memory can then be remapped to another address again using the MMU, but notice that the TCM if often used in situations where the MMU is turned off. To avoid confusion the current Linux implementation will map the TCM 1 to 1 from physical to virtual -memory in the location specified by the machine. +memory in the location specified by the kernel. Currently Linux +will map ITCM to 0xfffe0000 and on, and DTCM to 0xfffe8000 and +on, supporting a maximum of 32KiB of ITCM and 32KiB of DTCM. + +Newer versions of the region registers also support dividing these +TCMs in two separate banks, so for example an 8KiB ITCM is divided +into two 4KiB banks with its own control registers. The idea is to +be able to lock and hide one of the banks for use by the secure +world (TrustZone). TCM is used for a few things: @@ -65,18 +73,18 @@ in <asm/tcm.h>. Using this interface it is possible to: memory. Such a heap is great for things like saving device state when shutting off device power domains. -A machine that has TCM memory shall select HAVE_TCM in -arch/arm/Kconfig for itself, and then the -rest of the functionality will depend on the physical -location and size of ITCM and DTCM to be defined in -mach/memory.h for the machine. Code that needs to use -TCM shall #include <asm/tcm.h> If the TCM is not located -at the place given in memory.h it will be moved using -the TCM Region registers. +A machine that has TCM memory shall select HAVE_TCM from +arch/arm/Kconfig for itself. Code that needs to use TCM shall +#include <asm/tcm.h> Functions to go into itcm can be tagged like this: int __tcmfunc foo(int bar); +Since these are marked to become long_calls and you may want +to have functions called locally inside the TCM without +wasting space, there is also the __tcmlocalfunc prefix that +will make the call relative. + Variables to go into dtcm can be tagged like this: int __tcmdata foo; diff --git a/Documentation/binfmt_misc.txt b/Documentation/binfmt_misc.txt index f609ebf9c78..c1ed6948ba8 100644 --- a/Documentation/binfmt_misc.txt +++ b/Documentation/binfmt_misc.txt @@ -111,6 +111,6 @@ cause unexpected behaviour and can be a security hazard. There is a web page about binfmt_misc at -http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html +http://www.tat.physik.uni-tuebingen.de Richard Günther <rguenth@tat.physik.uni-tuebingen.de> diff --git a/Documentation/blackfin/00-INDEX b/Documentation/blackfin/00-INDEX index c34e12440fe..2df0365f2df 100644 --- a/Documentation/blackfin/00-INDEX +++ b/Documentation/blackfin/00-INDEX @@ -1,11 +1,8 @@ 00-INDEX - This file -cachefeatures.txt - - Supported cache features. - -Filesystems - - Requirements for mounting the root file system. - -bfin-gpio-note.txt +bfin-gpio-notes.txt - Notes in developing/using bfin-gpio driver. + +bfin-spi-notes.txt + - Notes for using bfin spi bus driver. diff --git a/Documentation/blackfin/Filesystems b/Documentation/blackfin/Filesystems deleted file mode 100644 index 51260a1b803..00000000000 --- a/Documentation/blackfin/Filesystems +++ /dev/null @@ -1,169 +0,0 @@ -/* - * File: Documentation/blackfin/Filesystems - * Based on: - * Author: - * - * Created: - * Description: This file contains the simple DMA Implementation for Blackfin - * - * Rev: $Id: Filesystems 2384 2006-11-01 04:12:43Z magicyang $ - * - * Modified: - * Copyright 2004-2006 Analog Devices Inc. - * - * Bugs: Enter bugs at http://blackfin.uclinux.org/ - * - */ - - How to mount the root file system in uClinux/Blackfin - ----------------------------------------------------- - -1 Mounting EXT3 File system. - ------------------------ - - Creating an EXT3 File system for uClinux/Blackfin: - - -Please follow the steps to form the EXT3 File system and mount the same as root -file system. - -a Make an ext3 file system as large as you want the final root file - system. - - mkfs.ext3 /dev/ram0 <your-rootfs-size-in-1k-blocks> - -b Mount this Empty file system on a free directory as: - - mount -t ext3 /dev/ram0 ./test - where ./test is the empty directory. - -c Copy your root fs directory that you have so carefully made over. - - cp -af /tmp/my_final_rootfs_files/* ./test - - (For ex: cp -af uClinux-dist/romfs/* ./test) - -d If you have done everything right till now you should be able to see - the required "root" dir's (that's etc, root, bin, lib, sbin...) - -e Now unmount the file system - - umount ./test - -f Create the root file system image. - - dd if=/dev/ram0 bs=1k count=<your-rootfs-size-in-1k-blocks> \ - > ext3fs.img - - -Now you have to tell the kernel that will be mounting this file system as -rootfs. -So do a make menuconfig under kernel and select the Ext3 journaling file system -support under File system --> submenu. - - -2. Mounting EXT2 File system. - ------------------------- - -By default the ext2 file system image will be created if you invoke make from -the top uClinux-dist directory. - - -3. Mounting CRAMFS File System - ---------------------------- - -To create a CRAMFS file system image execute the command - - mkfs.cramfs ./test cramfs.img - - where ./test is the target directory. - - -4. Mounting ROMFS File System - -------------------------- - -To create a ROMFS file system image execute the command - - genromfs -v -V "ROMdisk" -f romfs.img -d ./test - - where ./test is the target directory - - -5. Mounting the JFFS2 Filesystem - ----------------------------- - -To create a compressed JFFS filesystem (JFFS2), please execute the command - - mkfs.jffs2 -d ./test -o jffs2.img - - where ./test is the target directory. - -However, please make sure the following is in your kernel config. - -/* - * RAM/ROM/Flash chip drivers - */ -#define CONFIG_MTD_CFI 1 -#define CONFIG_MTD_ROM 1 -/* - * Mapping drivers for chip access - */ -#define CONFIG_MTD_COMPLEX_MAPPINGS 1 -#define CONFIG_MTD_BF533 1 -#undef CONFIG_MTD_UCLINUX - -Through the u-boot boot loader, use the jffs2.img in the corresponding -partition made in linux-2.6.x/drivers/mtd/maps/bf533_flash.c. - -NOTE - Currently the Flash driver is available only for EZKIT. Watch out for a - STAMP driver soon. - - -6. Mounting the NFS File system - ----------------------------- - - For mounting the NFS please do the following in the kernel config. - - In Networking Support --> Networking options --> TCP/IP networking --> - IP: kernel level autoconfiguration - - Enable BOOTP Support. - - In Kernel hacking --> Compiled-in kernel boot parameter add the following - - root=/dev/nfs rw ip=bootp - - In File system --> Network File system, Enable - - NFS file system support --> NFSv3 client support - Root File system on NFS - - in uClibc menuconfig, do the following - In Networking Support - enable Remote Procedure Call (RPC) support - Full RPC Support - - On the Host side, ensure that /etc/dhcpd.conf looks something like this - - ddns-update-style ad-hoc; - allow bootp; - subnet 10.100.4.0 netmask 255.255.255.0 { - default-lease-time 122209600; - max-lease-time 31557600; - group { - host bf533 { - hardware ethernet 00:CF:52:49:C3:01; - fixed-address 10.100.4.50; - option root-path "/home/nfsmount"; - } - } - - ensure that /etc/exports looks something like this - /home/nfsmount *(rw,no_root_squash,no_all_squash) - - run the following commands as root (may differ depending on your - distribution) : - - service nfs start - - service portmap start - - service dhcpd start - - /usr/sbin/exportfs diff --git a/Documentation/blackfin/bfin-spi-notes.txt b/Documentation/blackfin/bfin-spi-notes.txt new file mode 100644 index 00000000000..556fa877f2e --- /dev/null +++ b/Documentation/blackfin/bfin-spi-notes.txt @@ -0,0 +1,14 @@ +SPI Chip Select behavior: + +With the Blackfin on-chip SPI peripheral, there is some logic tied to the CPHA +bit whether the Slave Select Line is controlled by hardware (CPHA=0) or +controlled by software (CPHA=1). However, the Linux SPI bus driver assumes that +the Slave Select is always under software control and being asserted during +the entire SPI transfer. - And not just bits_per_word duration. + +In most cases you can utilize SPI MODE_3 instead of MODE_0 to work-around this +behavior. If your SPI slave device in question requires SPI MODE_0 or MODE_2 +timing, you can utilize the GPIO controlled SPI Slave Select option instead. + +You can even use the same pin whose peripheral role is a SSEL, +but use it as a GPIO instead. diff --git a/Documentation/blackfin/cachefeatures.txt b/Documentation/blackfin/cachefeatures.txt deleted file mode 100644 index 75de51f9451..00000000000 --- a/Documentation/blackfin/cachefeatures.txt +++ /dev/null @@ -1,55 +0,0 @@ -/* - * File: Documentation/blackfin/cachefeatures.txt - * Based on: - * Author: - * - * Created: - * Description: This file contains the simple DMA Implementation for Blackfin - * - * Rev: $Id: cachefeatures.txt 2384 2006-11-01 04:12:43Z magicyang $ - * - * Modified: - * Copyright 2004-2006 Analog Devices Inc. - * - * Bugs: Enter bugs at http://blackfin.uclinux.org/ - * - */ - - - Instruction and Data cache initialization. - icache_init(); - dcache_init(); - - - Instruction and Data cache Invalidation Routines, when flushing the - same is not required. - _icache_invalidate(); - _dcache_invalidate(); - - Also, for invalidating the entire instruction and data cache, the below - routines are provided (another method for invalidation, refer page no 267 and 287 of - ADSP-BF533 Hardware Reference manual) - - invalidate_entire_dcache(); - invalidate_entire_icache(); - - -External Flushing of Instruction and data cache routines. - - flush_instruction_cache(); - flush_data_cache(); - - - Internal Flushing of Instruction and Data Cache. - - icplb_flush(); - dcplb_flush(); - - - Miscellaneous cache functions. - - flush_cache_all(); - flush_cache_mm(); - invalidate_dcache_range(); - flush_dcache_range(); - flush_dcache_page(); - flush_cache_range(); - flush_cache_page(); - invalidate_dcache_range(); - flush_page_to_ram(); - diff --git a/Documentation/block/00-INDEX b/Documentation/block/00-INDEX index a406286f6f3..d111e3b23db 100644 --- a/Documentation/block/00-INDEX +++ b/Documentation/block/00-INDEX @@ -1,7 +1,5 @@ 00-INDEX - This file -barrier.txt - - I/O Barriers biodoc.txt - Notes on the Generic Block Layer Rewrite in Linux 2.5 capability.txt @@ -16,3 +14,5 @@ stat.txt - Block layer statistics in /sys/block/<dev>/stat switching-sched.txt - Switching I/O schedulers at runtime +writeback_cache_control.txt + - Control of volatile write back caches diff --git a/Documentation/block/barrier.txt b/Documentation/block/barrier.txt deleted file mode 100644 index 2c2f24f634e..00000000000 --- a/Documentation/block/barrier.txt +++ /dev/null @@ -1,261 +0,0 @@ -I/O Barriers -============ -Tejun Heo <htejun@gmail.com>, July 22 2005 - -I/O barrier requests are used to guarantee ordering around the barrier -requests. Unless you're crazy enough to use disk drives for -implementing synchronization constructs (wow, sounds interesting...), -the ordering is meaningful only for write requests for things like -journal checkpoints. All requests queued before a barrier request -must be finished (made it to the physical medium) before the barrier -request is started, and all requests queued after the barrier request -must be started only after the barrier request is finished (again, -made it to the physical medium). - -In other words, I/O barrier requests have the following two properties. - -1. Request ordering - -Requests cannot pass the barrier request. Preceding requests are -processed before the barrier and following requests after. - -Depending on what features a drive supports, this can be done in one -of the following three ways. - -i. For devices which have queue depth greater than 1 (TCQ devices) and -support ordered tags, block layer can just issue the barrier as an -ordered request and the lower level driver, controller and drive -itself are responsible for making sure that the ordering constraint is -met. Most modern SCSI controllers/drives should support this. - -NOTE: SCSI ordered tag isn't currently used due to limitation in the - SCSI midlayer, see the following random notes section. - -ii. For devices which have queue depth greater than 1 but don't -support ordered tags, block layer ensures that the requests preceding -a barrier request finishes before issuing the barrier request. Also, -it defers requests following the barrier until the barrier request is -finished. Older SCSI controllers/drives and SATA drives fall in this -category. - -iii. Devices which have queue depth of 1. This is a degenerate case -of ii. Just keeping issue order suffices. Ancient SCSI -controllers/drives and IDE drives are in this category. - -2. Forced flushing to physical medium - -Again, if you're not gonna do synchronization with disk drives (dang, -it sounds even more appealing now!), the reason you use I/O barriers -is mainly to protect filesystem integrity when power failure or some -other events abruptly stop the drive from operating and possibly make -the drive lose data in its cache. So, I/O barriers need to guarantee -that requests actually get written to non-volatile medium in order. - -There are four cases, - -i. No write-back cache. Keeping requests ordered is enough. - -ii. Write-back cache but no flush operation. There's no way to -guarantee physical-medium commit order. This kind of devices can't to -I/O barriers. - -iii. Write-back cache and flush operation but no FUA (forced unit -access). We need two cache flushes - before and after the barrier -request. - -iv. Write-back cache, flush operation and FUA. We still need one -flush to make sure requests preceding a barrier are written to medium, -but post-barrier flush can be avoided by using FUA write on the -barrier itself. - - -How to support barrier requests in drivers ------------------------------------------- - -All barrier handling is done inside block layer proper. All low level -drivers have to are implementing its prepare_flush_fn and using one -the following two functions to indicate what barrier type it supports -and how to prepare flush requests. Note that the term 'ordered' is -used to indicate the whole sequence of performing barrier requests -including draining and flushing. - -typedef void (prepare_flush_fn)(struct request_queue *q, struct request *rq); - -int blk_queue_ordered(struct request_queue *q, unsigned ordered, - prepare_flush_fn *prepare_flush_fn); - -@q : the queue in question -@ordered : the ordered mode the driver/device supports -@prepare_flush_fn : this function should prepare @rq such that it - flushes cache to physical medium when executed - -For example, SCSI disk driver's prepare_flush_fn looks like the -following. - -static void sd_prepare_flush(struct request_queue *q, struct request *rq) -{ - memset(rq->cmd, 0, sizeof(rq->cmd)); - rq->cmd_type = REQ_TYPE_BLOCK_PC; - rq->timeout = SD_TIMEOUT; - rq->cmd[0] = SYNCHRONIZE_CACHE; - rq->cmd_len = 10; -} - -The following seven ordered modes are supported. The following table -shows which mode should be used depending on what features a -device/driver supports. In the leftmost column of table, -QUEUE_ORDERED_ prefix is omitted from the mode names to save space. - -The table is followed by description of each mode. Note that in the -descriptions of QUEUE_ORDERED_DRAIN*, '=>' is used whereas '->' is -used for QUEUE_ORDERED_TAG* descriptions. '=>' indicates that the -preceding step must be complete before proceeding to the next step. -'->' indicates that the next step can start as soon as the previous -step is issued. - - write-back cache ordered tag flush FUA ------------------------------------------------------------------------ -NONE yes/no N/A no N/A -DRAIN no no N/A N/A -DRAIN_FLUSH yes no yes no -DRAIN_FUA yes no yes yes -TAG no yes N/A N/A -TAG_FLUSH yes yes yes no -TAG_FUA yes yes yes yes - - -QUEUE_ORDERED_NONE - I/O barriers are not needed and/or supported. - - Sequence: N/A - -QUEUE_ORDERED_DRAIN - Requests are ordered by draining the request queue and cache - flushing isn't needed. - - Sequence: drain => barrier - -QUEUE_ORDERED_DRAIN_FLUSH - Requests are ordered by draining the request queue and both - pre-barrier and post-barrier cache flushings are needed. - - Sequence: drain => preflush => barrier => postflush - -QUEUE_ORDERED_DRAIN_FUA - Requests are ordered by draining the request queue and - pre-barrier cache flushing is needed. By using FUA on barrier - request, post-barrier flushing can be skipped. - - Sequence: drain => preflush => barrier - -QUEUE_ORDERED_TAG - Requests are ordered by ordered tag and cache flushing isn't - needed. - - Sequence: barrier - -QUEUE_ORDERED_TAG_FLUSH - Requests are ordered by ordered tag and both pre-barrier and - post-barrier cache flushings are needed. - - Sequence: preflush -> barrier -> postflush - -QUEUE_ORDERED_TAG_FUA - Requests are ordered by ordered tag and pre-barrier cache - flushing is needed. By using FUA on barrier request, - post-barrier flushing can be skipped. - - Sequence: preflush -> barrier - - -Random notes/caveats --------------------- - -* SCSI layer currently can't use TAG ordering even if the drive, -controller and driver support it. The problem is that SCSI midlayer -request dispatch function is not atomic. It releases queue lock and -switch to SCSI host lock during issue and it's possible and likely to -happen in time that requests change their relative positions. Once -this problem is solved, TAG ordering can be enabled. - -* Currently, no matter which ordered mode is used, there can be only -one barrier request in progress. All I/O barriers are held off by -block layer until the previous I/O barrier is complete. This doesn't -make any difference for DRAIN ordered devices, but, for TAG ordered -devices with very high command latency, passing multiple I/O barriers -to low level *might* be helpful if they are very frequent. Well, this -certainly is a non-issue. I'm writing this just to make clear that no -two I/O barrier is ever passed to low-level driver. - -* Completion order. Requests in ordered sequence are issued in order -but not required to finish in order. Barrier implementation can -handle out-of-order completion of ordered sequence. IOW, the requests -MUST be processed in order but the hardware/software completion paths -are allowed to reorder completion notifications - eg. current SCSI -midlayer doesn't preserve completion order during error handling. - -* Requeueing order. Low-level drivers are free to requeue any request -after they removed it from the request queue with -blkdev_dequeue_request(). As barrier sequence should be kept in order -when requeued, generic elevator code takes care of putting requests in -order around barrier. See blk_ordered_req_seq() and -ELEVATOR_INSERT_REQUEUE handling in __elv_add_request() for details. - -Note that block drivers must not requeue preceding requests while -completing latter requests in an ordered sequence. Currently, no -error checking is done against this. - -* Error handling. Currently, block layer will report error to upper -layer if any of requests in an ordered sequence fails. Unfortunately, -this doesn't seem to be enough. Look at the following request flow. -QUEUE_ORDERED_TAG_FLUSH is in use. - - [0] [1] [2] [3] [pre] [barrier] [post] < [4] [5] [6] ... > - still in elevator - -Let's say request [2], [3] are write requests to update file system -metadata (journal or whatever) and [barrier] is used to mark that -those updates are valid. Consider the following sequence. - - i. Requests [0] ~ [post] leaves the request queue and enters - low-level driver. - ii. After a while, unfortunately, something goes wrong and the - drive fails [2]. Note that any of [0], [1] and [3] could have - completed by this time, but [pre] couldn't have been finished - as the drive must process it in order and it failed before - processing that command. - iii. Error handling kicks in and determines that the error is - unrecoverable and fails [2], and resumes operation. - iv. [pre] [barrier] [post] gets processed. - v. *BOOM* power fails - -The problem here is that the barrier request is *supposed* to indicate -that filesystem update requests [2] and [3] made it safely to the -physical medium and, if the machine crashes after the barrier is -written, filesystem recovery code can depend on that. Sadly, that -isn't true in this case anymore. IOW, the success of a I/O barrier -should also be dependent on success of some of the preceding requests, -where only upper layer (filesystem) knows what 'some' is. - -This can be solved by implementing a way to tell the block layer which -requests affect the success of the following barrier request and -making lower lever drivers to resume operation on error only after -block layer tells it to do so. - -As the probability of this happening is very low and the drive should -be faulty, implementing the fix is probably an overkill. But, still, -it's there. - -* In previous drafts of barrier implementation, there was fallback -mechanism such that, if FUA or ordered TAG fails, less fancy ordered -mode can be selected and the failed barrier request is retried -automatically. The rationale for this feature was that as FUA is -pretty new in ATA world and ordered tag was never used widely, there -could be devices which report to support those features but choke when -actually given such requests. - - This was removed for two reasons 1. it's an overkill 2. it's -impossible to implement properly when TAG ordering is used as low -level drivers resume after an error automatically. If it's ever -needed adding it back and modifying low level drivers accordingly -shouldn't be difficult. diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index 508b5b2b028..b9a83dd2473 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -7,7 +7,7 @@ Notes Written on Jan 15, 2002: Last Updated May 2, 2002 September 2003: Updated I/O Scheduler portions - Nick Piggin <piggin@cyberone.com.au> + Nick Piggin <npiggin@kernel.dk> Introduction: diff --git a/Documentation/block/cfq-iosched.txt b/Documentation/block/cfq-iosched.txt new file mode 100644 index 00000000000..e578feed6d8 --- /dev/null +++ b/Documentation/block/cfq-iosched.txt @@ -0,0 +1,45 @@ +CFQ ioscheduler tunables +======================== + +slice_idle +---------- +This specifies how long CFQ should idle for next request on certain cfq queues +(for sequential workloads) and service trees (for random workloads) before +queue is expired and CFQ selects next queue to dispatch from. + +By default slice_idle is a non-zero value. That means by default we idle on +queues/service trees. This can be very helpful on highly seeky media like +single spindle SATA/SAS disks where we can cut down on overall number of +seeks and see improved throughput. + +Setting slice_idle to 0 will remove all the idling on queues/service tree +level and one should see an overall improved throughput on faster storage +devices like multiple SATA/SAS disks in hardware RAID configuration. The down +side is that isolation provided from WRITES also goes down and notion of +IO priority becomes weaker. + +So depending on storage and workload, it might be useful to set slice_idle=0. +In general I think for SATA/SAS disks and software RAID of SATA/SAS disks +keeping slice_idle enabled should be useful. For any configurations where +there are multiple spindles behind single LUN (Host based hardware RAID +controller or for storage arrays), setting slice_idle=0 might end up in better +throughput and acceptable latencies. + +CFQ IOPS Mode for group scheduling +=================================== +Basic CFQ design is to provide priority based time slices. Higher priority +process gets bigger time slice and lower priority process gets smaller time +slice. Measuring time becomes harder if storage is fast and supports NCQ and +it would be better to dispatch multiple requests from multiple cfq queues in +request queue at a time. In such scenario, it is not possible to measure time +consumed by single queue accurately. + +What is possible though is to measure number of requests dispatched from a +single queue and also allow dispatch from multiple cfq queue at the same time. +This effectively becomes the fairness in terms of IOPS (IO operations per +second). + +If one sets slice_idle=0 and if storage supports NCQ, CFQ internally switches +to IOPS mode and starts providing fairness in terms of number of requests +dispatched. Note that this mode switching takes effect only for group +scheduling. For non-cgroup users nothing should change. diff --git a/Documentation/block/writeback_cache_control.txt b/Documentation/block/writeback_cache_control.txt new file mode 100644 index 00000000000..83407d36630 --- /dev/null +++ b/Documentation/block/writeback_cache_control.txt @@ -0,0 +1,86 @@ + +Explicit volatile write back cache control +===================================== + +Introduction +------------ + +Many storage devices, especially in the consumer market, come with volatile +write back caches. That means the devices signal I/O completion to the +operating system before data actually has hit the non-volatile storage. This +behavior obviously speeds up various workloads, but it means the operating +system needs to force data out to the non-volatile storage when it performs +a data integrity operation like fsync, sync or an unmount. + +The Linux block layer provides two simple mechanisms that let filesystems +control the caching behavior of the storage device. These mechanisms are +a forced cache flush, and the Force Unit Access (FUA) flag for requests. + + +Explicit cache flushes +---------------------- + +The REQ_FLUSH flag can be OR ed into the r/w flags of a bio submitted from +the filesystem and will make sure the volatile cache of the storage device +has been flushed before the actual I/O operation is started. This explicitly +guarantees that previously completed write requests are on non-volatile +storage before the flagged bio starts. In addition the REQ_FLUSH flag can be +set on an otherwise empty bio structure, which causes only an explicit cache +flush without any dependent I/O. It is recommend to use +the blkdev_issue_flush() helper for a pure cache flush. + + +Forced Unit Access +----------------- + +The REQ_FUA flag can be OR ed into the r/w flags of a bio submitted from the +filesystem and will make sure that I/O completion for this request is only +signaled after the data has been committed to non-volatile storage. + + +Implementation details for filesystems +-------------------------------------- + +Filesystems can simply set the REQ_FLUSH and REQ_FUA bits and do not have to +worry if the underlying devices need any explicit cache flushing and how +the Forced Unit Access is implemented. The REQ_FLUSH and REQ_FUA flags +may both be set on a single bio. + + +Implementation details for make_request_fn based block drivers +-------------------------------------------------------------- + +These drivers will always see the REQ_FLUSH and REQ_FUA bits as they sit +directly below the submit_bio interface. For remapping drivers the REQ_FUA +bits need to be propagated to underlying devices, and a global flush needs +to be implemented for bios with the REQ_FLUSH bit set. For real device +drivers that do not have a volatile cache the REQ_FLUSH and REQ_FUA bits +on non-empty bios can simply be ignored, and REQ_FLUSH requests without +data can be completed successfully without doing any work. Drivers for +devices with volatile caches need to implement the support for these +flags themselves without any help from the block layer. + + +Implementation details for request_fn based block drivers +-------------------------------------------------------------- + +For devices that do not support volatile write caches there is no driver +support required, the block layer completes empty REQ_FLUSH requests before +entering the driver and strips off the REQ_FLUSH and REQ_FUA bits from +requests that have a payload. For devices with volatile write caches the +driver needs to tell the block layer that it supports flushing caches by +doing: + + blk_queue_flush(sdkp->disk->queue, REQ_FLUSH); + +and handle empty REQ_FLUSH requests in its prep_fn/request_fn. Note that +REQ_FLUSH requests with a payload are automatically turned into a sequence +of an empty REQ_FLUSH request followed by the actual write by the block +layer. For devices that also support the FUA bit the block layer needs +to be told to pass through the REQ_FUA bit using: + + blk_queue_flush(sdkp->disk->queue, REQ_FLUSH | REQ_FUA); + +and the driver must handle write requests that have the REQ_FUA bit set +in prep_fn/request_fn. If the FUA bit is not natively supported the block +layer turns it into an empty REQ_FLUSH request after the actual write. diff --git a/Documentation/blockdev/paride.txt b/Documentation/blockdev/paride.txt index e4312676bdd..ee6717e3771 100644 --- a/Documentation/blockdev/paride.txt +++ b/Documentation/blockdev/paride.txt @@ -412,6 +412,6 @@ have in your mail headers, when sending mail to the list server. You might also find some useful information on the linux-parport web pages (although they are not always up to date) at - http://www.torque.net/parport/ + http://web.archive.org/web/*/http://www.torque.net/parport/ diff --git a/Documentation/cdrom/packet-writing.txt b/Documentation/cdrom/packet-writing.txt index 1c407778c8b..13c251d5add 100644 --- a/Documentation/cdrom/packet-writing.txt +++ b/Documentation/cdrom/packet-writing.txt @@ -95,7 +95,7 @@ Using the pktcdvd sysfs interface Since Linux 2.6.20, the pktcdvd module has a sysfs interface and can be controlled by it. For example the "pktcdvd" tool uses -this interface. (see http://people.freenet.de/BalaGi#pktcdvd ) +this interface. (see http://tom.ist-im-web.de/download/pktcdvd ) "pktcdvd" works similar to "pktsetup", e.g.: diff --git a/Documentation/cgroups/blkio-controller.txt b/Documentation/cgroups/blkio-controller.txt index 48e0b21b005..d6da611f8f6 100644 --- a/Documentation/cgroups/blkio-controller.txt +++ b/Documentation/cgroups/blkio-controller.txt @@ -8,12 +8,17 @@ both at leaf nodes as well as at intermediate nodes in a storage hierarchy. Plan is to use the same cgroup based management interface for blkio controller and based on user options switch IO policies in the background. -In the first phase, this patchset implements proportional weight time based -division of disk policy. It is implemented in CFQ. Hence this policy takes -effect only on leaf nodes when CFQ is being used. +Currently two IO control policies are implemented. First one is proportional +weight time based division of disk policy. It is implemented in CFQ. Hence +this policy takes effect only on leaf nodes when CFQ is being used. The second +one is throttling policy which can be used to specify upper IO rate limits +on devices. This policy is implemented in generic block layer and can be +used on leaf nodes as well as higher level logical devices like device mapper. HOWTO ===== +Proportional Weight division of bandwidth +----------------------------------------- You can do a very simple testing of running two dd threads in two different cgroups. Here is what you can do. @@ -55,6 +60,35 @@ cgroups. Here is what you can do. group dispatched to the disk. We provide fairness in terms of disk time, so ideally io.disk_time of cgroups should be in proportion to the weight. +Throttling/Upper Limit policy +----------------------------- +- Enable Block IO controller + CONFIG_BLK_CGROUP=y + +- Enable throttling in block layer + CONFIG_BLK_DEV_THROTTLING=y + +- Mount blkio controller + mount -t cgroup -o blkio none /cgroup/blkio + +- Specify a bandwidth rate on particular device for root group. The format + for policy is "<major>:<minor> <byes_per_second>". + + echo "8:16 1048576" > /cgroup/blkio/blkio.read_bps_device + + Above will put a limit of 1MB/second on reads happening for root group + on device having major/minor number 8:16. + +- Run dd to read a file and see if rate is throttled to 1MB/s or not. + + # dd if=/mnt/common/zerofile of=/dev/null bs=4K count=1024 + # iflag=direct + 1024+0 records in + 1024+0 records out + 4194304 bytes (4.2 MB) copied, 4.0001 s, 1.0 MB/s + + Limits for writes can be put using blkio.write_bps_device file. + Various user visible config options =================================== CONFIG_BLK_CGROUP @@ -68,8 +102,13 @@ CONFIG_CFQ_GROUP_IOSCHED - Enables group scheduling in CFQ. Currently only 1 level of group creation is allowed. +CONFIG_BLK_DEV_THROTTLING + - Enable block device throttling support in block layer. + Details of cgroup files ======================= +Proportional weight policy files +-------------------------------- - blkio.weight - Specifies per cgroup weight. This is default weight of the group on all the devices until and unless overridden by per device rule. @@ -210,6 +249,67 @@ Details of cgroup files and minor number of the device and third field specifies the number of times a group was dequeued from a particular device. +Throttling/Upper limit policy files +----------------------------------- +- blkio.throttle.read_bps_device + - Specifies upper limit on READ rate from the device. IO rate is + specified in bytes per second. Rules are per deivce. Following is + the format. + + echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.read_bps_device + +- blkio.throttle.write_bps_device + - Specifies upper limit on WRITE rate to the device. IO rate is + specified in bytes per second. Rules are per deivce. Following is + the format. + + echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.write_bps_device + +- blkio.throttle.read_iops_device + - Specifies upper limit on READ rate from the device. IO rate is + specified in IO per second. Rules are per deivce. Following is + the format. + + echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.read_iops_device + +- blkio.throttle.write_iops_device + - Specifies upper limit on WRITE rate to the device. IO rate is + specified in io per second. Rules are per deivce. Following is + the format. + + echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.write_iops_device + +Note: If both BW and IOPS rules are specified for a device, then IO is + subjectd to both the constraints. + +- blkio.throttle.io_serviced + - Number of IOs (bio) completed to/from the disk by the group (as + seen by throttling policy). These are further divided by the type + of operation - read or write, sync or async. First two fields specify + the major and minor number of the device, third field specifies the + operation type and the fourth field specifies the number of IOs. + + blkio.io_serviced does accounting as seen by CFQ and counts are in + number of requests (struct request). On the other hand, + blkio.throttle.io_serviced counts number of IO in terms of number + of bios as seen by throttling policy. These bios can later be + merged by elevator and total number of requests completed can be + lesser. + +- blkio.throttle.io_service_bytes + - Number of bytes transferred to/from the disk by the group. These + are further divided by the type of operation - read or write, sync + or async. First two fields specify the major and minor number of the + device, third field specifies the operation type and the fourth field + specifies the number of bytes. + + These numbers should roughly be same as blkio.io_service_bytes as + updated by CFQ. The difference between two is that + blkio.io_service_bytes will not be updated if CFQ is not operating + on request queue. + +Common files among various policies +----------------------------------- - blkio.reset_stats - Writing an int to this file will result in resetting all the stats for that cgroup. @@ -217,6 +317,7 @@ Details of cgroup files CFQ sysfs tunable ================= /sys/block/<disk>/queue/iosched/group_isolation +----------------------------------------------- If group_isolation=1, it provides stronger isolation between groups at the expense of throughput. By default group_isolation is 0. In general that @@ -243,6 +344,33 @@ By default one should run with group_isolation=0. If that is not sufficient and one wants stronger isolation between groups, then set group_isolation=1 but this will come at cost of reduced throughput. +/sys/block/<disk>/queue/iosched/slice_idle +------------------------------------------ +On a faster hardware CFQ can be slow, especially with sequential workload. +This happens because CFQ idles on a single queue and single queue might not +drive deeper request queue depths to keep the storage busy. In such scenarios +one can try setting slice_idle=0 and that would switch CFQ to IOPS +(IO operations per second) mode on NCQ supporting hardware. + +That means CFQ will not idle between cfq queues of a cfq group and hence be +able to driver higher queue depth and achieve better throughput. That also +means that cfq provides fairness among groups in terms of IOPS and not in +terms of disk time. + +/sys/block/<disk>/queue/iosched/group_idle +------------------------------------------ +If one disables idling on individual cfq queues and cfq service trees by +setting slice_idle=0, group_idle kicks in. That means CFQ will still idle +on the group in an attempt to provide fairness among groups. + +By default group_idle is same as slice_idle and does not do anything if +slice_idle is enabled. + +One can experience an overall throughput drop if you have created multiple +groups and put applications in that group which are not driving enough +IO to keep disk busy. In that case set group_idle=0, and CFQ will not idle +on individual groups and throughput should improve. + What works ========== - Currently only sync IO queues are support. All the buffered writes are diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroups/cgroups.txt index b34823ff164..190018b0c64 100644 --- a/Documentation/cgroups/cgroups.txt +++ b/Documentation/cgroups/cgroups.txt @@ -18,7 +18,8 @@ CONTENTS: 1.2 Why are cgroups needed ? 1.3 How are cgroups implemented ? 1.4 What does notify_on_release do ? - 1.5 How do I use cgroups ? + 1.5 What does clone_children do ? + 1.6 How do I use cgroups ? 2. Usage Examples and Syntax 2.1 Basic Usage 2.2 Attaching processes @@ -293,7 +294,16 @@ notify_on_release in the root cgroup at system boot is disabled value of their parents notify_on_release setting. The default value of a cgroup hierarchy's release_agent path is empty. -1.5 How do I use cgroups ? +1.5 What does clone_children do ? +--------------------------------- + +If the clone_children flag is enabled (1) in a cgroup, then all +cgroups created beneath will call the post_clone callbacks for each +subsystem of the newly created cgroup. Usually when this callback is +implemented for a subsystem, it copies the values of the parent +subsystem, this is the case for the cpuset. + +1.6 How do I use cgroups ? -------------------------- To start a new job that is to be contained within a cgroup, using diff --git a/Documentation/cgroups/cpusets.txt b/Documentation/cgroups/cpusets.txt index 51682ab2dd1..5d0d5692a36 100644 --- a/Documentation/cgroups/cpusets.txt +++ b/Documentation/cgroups/cpusets.txt @@ -691,7 +691,7 @@ There are ways to query or modify cpusets: cat, rmdir commands from the shell, or their equivalent from C. - via the C library libcpuset. - via the C library libcgroup. - (http://sourceforge.net/proects/libcg/) + (http://sourceforge.net/projects/libcg/) - via the python application cset. (http://developer.novell.com/wiki/index.php/Cpuset) diff --git a/Documentation/coccinelle.txt b/Documentation/coccinelle.txt new file mode 100644 index 00000000000..4a276ea7001 --- /dev/null +++ b/Documentation/coccinelle.txt @@ -0,0 +1,286 @@ +Copyright 2010 Nicolas Palix <npalix@diku.dk> +Copyright 2010 Julia Lawall <julia@diku.dk> +Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr> + + + Getting Coccinelle +~~~~~~~~~~~~~~~~~~~~ + +The semantic patches included in the kernel use the 'virtual rule' +feature which was introduced in Coccinelle version 0.1.11. + +Coccinelle (>=0.2.0) is available through the package manager +of many distributions, e.g. : + + - Debian (>=squeeze) + - Fedora (>=13) + - Ubuntu (>=10.04 Lucid Lynx) + - OpenSUSE + - Arch Linux + - NetBSD + - FreeBSD + + +You can get the latest version released from the Coccinelle homepage at +http://coccinelle.lip6.fr/ + +Information and tips about Coccinelle are also provided on the wiki +pages at http://cocci.ekstranet.diku.dk/wiki/doku.php + +Once you have it, run the following command: + + ./configure + make + +as a regular user, and install it with + + sudo make install + + + Using Coccinelle on the Linux kernel +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A Coccinelle-specific target is defined in the top level +Makefile. This target is named 'coccicheck' and calls the 'coccicheck' +front-end in the 'scripts' directory. + +Four modes are defined: patch, report, context, and org. The mode to +use is specified by setting the MODE variable with 'MODE=<mode>'. + +'patch' proposes a fix, when possible. + +'report' generates a list in the following format: + file:line:column-column: message + +'context' highlights lines of interest and their context in a +diff-like style.Lines of interest are indicated with '-'. + +'org' generates a report in the Org mode format of Emacs. + +Note that not all semantic patches implement all modes. For easy use +of Coccinelle, the default mode is "chain" which tries the previous +modes in the order above until one succeeds. + +To make a report for every semantic patch, run the following command: + + make coccicheck MODE=report + +NB: The 'report' mode is the default one. + +To produce patches, run: + + make coccicheck MODE=patch + + +The coccicheck target applies every semantic patch available in the +sub-directories of 'scripts/coccinelle' to the entire Linux kernel. + +For each semantic patch, a commit message is proposed. It gives a +description of the problem being checked by the semantic patch, and +includes a reference to Coccinelle. + +As any static code analyzer, Coccinelle produces false +positives. Thus, reports must be carefully checked, and patches +reviewed. + + + Using Coccinelle with a single semantic patch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The optional make variable COCCI can be used to check a single +semantic patch. In that case, the variable must be initialized with +the name of the semantic patch to apply. + +For instance: + + make coccicheck COCCI=<my_SP.cocci> MODE=patch +or + make coccicheck COCCI=<my_SP.cocci> MODE=report + + + Using Coccinelle on (modified) files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To apply Coccinelle on a file basis, instead of a directory basis, the +following command may be used: + + make C=1 CHECK="scripts/coccicheck" + +To check only newly edited code, use the value 2 for the C flag, i.e. + + make C=2 CHECK="scripts/coccicheck" + +This runs every semantic patch in scripts/coccinelle by default. The +COCCI variable may additionally be used to only apply a single +semantic patch as shown in the previous section. + +The "chain" mode is the default. You can select another one with the +MODE variable explained above. + +In this mode, there is no information about semantic patches +displayed, and no commit message proposed. + + + Proposing new semantic patches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +New semantic patches can be proposed and submitted by kernel +developers. For sake of clarity, they should be organized in the +sub-directories of 'scripts/coccinelle/'. + + + Detailed description of the 'report' mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +'report' generates a list in the following format: + file:line:column-column: message + +Example: + +Running + + make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script. + +<smpl> +@r depends on !context && !patch && (org || report)@ +expression x; +position p; +@@ + + ERR_PTR@p(PTR_ERR(x)) + +@script:python depends on report@ +p << r.p; +x << r.x; +@@ + +msg="ERR_CAST can be used with %s" % (x) +coccilib.report.print_report(p[0], msg) +</smpl> + +This SmPL excerpt generates entries on the standard output, as +illustrated below: + +/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg +/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth +/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg + + + Detailed description of the 'patch' mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the 'patch' mode is available, it proposes a fix for each problem +identified. + +Example: + +Running + make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script. + +<smpl> +@ depends on !context && patch && !org && !report @ +expression x; +@@ + +- ERR_PTR(PTR_ERR(x)) ++ ERR_CAST(x) +</smpl> + +This SmPL excerpt generates patch hunks on the standard output, as +illustrated below: + +diff -u -p a/crypto/ctr.c b/crypto/ctr.c +--- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 ++++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 +@@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct + alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, + CRYPTO_ALG_TYPE_MASK); + if (IS_ERR(alg)) +- return ERR_PTR(PTR_ERR(alg)); ++ return ERR_CAST(alg); + + /* Block size must be >= 4 bytes. */ + err = -EINVAL; + + Detailed description of the 'context' mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +'context' highlights lines of interest and their context +in a diff-like style. + +NOTE: The diff-like output generated is NOT an applicable patch. The + intent of the 'context' mode is to highlight the important lines + (annotated with minus, '-') and gives some surrounding context + lines around. This output can be used with the diff mode of + Emacs to review the code. + +Example: + +Running + make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script. + +<smpl> +@ depends on context && !patch && !org && !report@ +expression x; +@@ + +* ERR_PTR(PTR_ERR(x)) +</smpl> + +This SmPL excerpt generates diff hunks on the standard output, as +illustrated below: + +diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing +--- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 ++++ /tmp/nothing +@@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct + alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, + CRYPTO_ALG_TYPE_MASK); + if (IS_ERR(alg)) +- return ERR_PTR(PTR_ERR(alg)); + + /* Block size must be >= 4 bytes. */ + err = -EINVAL; + + Detailed description of the 'org' mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +'org' generates a report in the Org mode format of Emacs. + +Example: + +Running + make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script. + +<smpl> +@r depends on !context && !patch && (org || report)@ +expression x; +position p; +@@ + + ERR_PTR@p(PTR_ERR(x)) + +@script:python depends on org@ +p << r.p; +x << r.x; +@@ + +msg="ERR_CAST can be used with %s" % (x) +msg_safe=msg.replace("[","@(").replace("]",")") +coccilib.org.print_todo(p[0], msg_safe) +</smpl> + +This SmPL excerpt generates Org entries on the standard output, as +illustrated below: + +* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] +* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] +* TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] diff --git a/Documentation/cpu-hotplug.txt b/Documentation/cpu-hotplug.txt index a99d7031cdf..45d5a217484 100644 --- a/Documentation/cpu-hotplug.txt +++ b/Documentation/cpu-hotplug.txt @@ -2,7 +2,7 @@ Maintainers: CPU Hotplug Core: - Rusty Russell <rusty@rustycorp.com.au> + Rusty Russell <rusty@rustcorp.com.au> Srivatsa Vaddagiri <vatsa@in.ibm.com> i386: Zwane Mwaikambo <zwane@arm.linux.org.uk> diff --git a/Documentation/cputopology.txt b/Documentation/cputopology.txt index f1c5c4bccd3..902d3151f52 100644 --- a/Documentation/cputopology.txt +++ b/Documentation/cputopology.txt @@ -14,25 +14,39 @@ to /proc/cpuinfo. identifier (rather than the kernel's). The actual value is architecture and platform dependent. -3) /sys/devices/system/cpu/cpuX/topology/thread_siblings: +3) /sys/devices/system/cpu/cpuX/topology/book_id: + + the book ID of cpuX. Typically it is the hardware platform's + identifier (rather than the kernel's). The actual value is + architecture and platform dependent. + +4) /sys/devices/system/cpu/cpuX/topology/thread_siblings: internel kernel map of cpuX's hardware threads within the same core as cpuX -4) /sys/devices/system/cpu/cpuX/topology/core_siblings: +5) /sys/devices/system/cpu/cpuX/topology/core_siblings: internal kernel map of cpuX's hardware threads within the same physical_package_id. +6) /sys/devices/system/cpu/cpuX/topology/book_siblings: + + internal kernel map of cpuX's hardware threads within the same + book_id. + To implement it in an architecture-neutral way, a new source file, -drivers/base/topology.c, is to export the 4 attributes. +drivers/base/topology.c, is to export the 4 or 6 attributes. The two book +related sysfs files will only be created if CONFIG_SCHED_BOOK is selected. For an architecture to support this feature, it must define some of these macros in include/asm-XXX/topology.h: #define topology_physical_package_id(cpu) #define topology_core_id(cpu) +#define topology_book_id(cpu) #define topology_thread_cpumask(cpu) #define topology_core_cpumask(cpu) +#define topology_book_cpumask(cpu) The type of **_id is int. The type of siblings is (const) struct cpumask *. @@ -45,6 +59,9 @@ not defined by include/asm-XXX/topology.h: 3) thread_siblings: just the given CPU 4) core_siblings: just the given CPU +For architectures that don't support books (CONFIG_SCHED_BOOK) there are no +default definitions for topology_book_id() and topology_book_cpumask(). + Additionally, CPU topology information is provided under /sys/devices/system/cpu and includes these files. The internal source for the output is in brackets ("[]"). diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding index a5a3450faaa..2278693c8ff 100644 --- a/Documentation/development-process/4.Coding +++ b/Documentation/development-process/4.Coding @@ -281,7 +281,7 @@ 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 +be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your distributor does not package it); it can then be run on the code by adding "C=1" to your make command. diff --git a/Documentation/device-mapper/dm-crypt.txt b/Documentation/device-mapper/dm-crypt.txt index 6680cab2c70..524de926290 100644 --- a/Documentation/device-mapper/dm-crypt.txt +++ b/Documentation/device-mapper/dm-crypt.txt @@ -36,7 +36,7 @@ Example scripts =============== LUKS (Linux Unified Key Setup) is now the preferred way to set up disk encryption with dm-crypt using the 'cryptsetup' utility, see -http://luks.endorphin.org/ +http://clemens.endorphin.org/cryptography [[ #!/bin/sh diff --git a/Documentation/devices.txt b/Documentation/devices.txt index 1d83d124056..eccffe71522 100644 --- a/Documentation/devices.txt +++ b/Documentation/devices.txt @@ -239,6 +239,7 @@ Your cooperation is appreciated. 0 = /dev/tty Current TTY device 1 = /dev/console System console 2 = /dev/ptmx PTY master multiplex + 3 = /dev/ttyprintk User messages via printk TTY device 64 = /dev/cua0 Callout device for ttyS0 ... 255 = /dev/cua191 Callout device for ttyS191 @@ -445,6 +446,7 @@ Your cooperation is appreciated. 233 = /dev/kmview View-OS A process with a view 234 = /dev/btrfs-control Btrfs control device 235 = /dev/autofs Autofs control device + 236 = /dev/mapper/control Device-Mapper control device 240-254 Reserved for local use 255 Reserved for MISC_DYNAMIC_MINOR @@ -1494,9 +1496,6 @@ Your cooperation is appreciated. 64 = /dev/radio0 Radio device ... 127 = /dev/radio63 Radio device - 192 = /dev/vtx0 Teletext device - ... - 223 = /dev/vtx31 Teletext device 224 = /dev/vbi0 Vertical blank interrupt ... 255 = /dev/vbi31 Vertical blank interrupt @@ -1517,7 +1516,7 @@ Your cooperation is appreciated. ... The driver and documentation may be obtained from - http://www.proximity.com.au/~brian/winradio/ + http://www.winradio.com/ 82 block I2O hard disk 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk @@ -1723,7 +1722,7 @@ Your cooperation is appreciated. 1 = /dev/comedi1 Second comedi device ... - See http://stm.lbl.gov/comedi or http://www.llp.fu-berlin.de/. + See http://stm.lbl.gov/comedi. 98 block User-mode virtual block device 0 = /dev/ubda First user-mode block device @@ -1984,7 +1983,7 @@ Your cooperation is appreciated. 256 NetWare volumes can be supported in a single machine. - http://www.kernel.org/pub/linux/kernel/people/jmerkey/nwfs + http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume @@ -2518,6 +2517,12 @@ Your cooperation is appreciated. 8 = /dev/mmcblk1 Second SD/MMC card ... + The start of next SD/MMC card can be configured with + CONFIG_MMC_BLOCK_MINORS, or overridden at boot/modprobe + time using the mmcblk.perdev_minors option. That would + bump the offset between each card to be the configured + value instead of the default 8. + 179 char CCube DVXChip-based PCI products 0 = /dev/dvxirq0 First DVX device 1 = /dev/dvxirq1 Second DVX device @@ -2552,7 +2557,10 @@ Your cooperation is appreciated. 175 = /dev/usb/legousbtower15 16th USB Legotower device 176 = /dev/usb/usbtmc1 First USB TMC device ... - 192 = /dev/usb/usbtmc16 16th USB TMC device + 191 = /dev/usb/usbtmc16 16th USB TMC device + 192 = /dev/usb/yurex1 First USB Yurex device + ... + 209 = /dev/usb/yurex16 16th USB Yurex device 240 = /dev/usb/dabusb0 First daubusb device ... 243 = /dev/usb/dabusb3 Fourth dabusb device @@ -2591,7 +2599,8 @@ Your cooperation is appreciated. 1 = /dev/intermezzo1 Second cache manager ... - See http://www.inter-mezzo.org/ for more information. + See http://web.archive.org/web/20080115195241/ + http://inter-mezzo.org/index.html 186 char Object-based storage control device 0 = /dev/obd0 First obd control device diff --git a/Documentation/dvb/faq.txt b/Documentation/dvb/faq.txt index 2511a335abd..121832e5d89 100644 --- a/Documentation/dvb/faq.txt +++ b/Documentation/dvb/faq.txt @@ -76,7 +76,7 @@ Some very frequently asked questions about linuxtv-dvb the TuxBox CVS many interesting DVB applications and the dBox2 DVB source - http://sourceforge.net/projects/dvbsak/ + http://www.linuxtv.org/downloads/ DVB Swiss Army Knife library and utilities http://www.nenie.org/misc/mpsys/ diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware index 239cbdbf4d1..59690de8ebf 100644 --- a/Documentation/dvb/get_dvb_firmware +++ b/Documentation/dvb/get_dvb_firmware @@ -26,7 +26,8 @@ use IO::Handle; "dec3000s", "vp7041", "dibusb", "nxt2002", "nxt2004", "or51211", "or51132_qam", "or51132_vsb", "bluebird", "opera1", "cx231xx", "cx18", "cx23885", "pvrusb2", "mpc718", - "af9015", "ngene"); + "af9015", "ngene", "az6027", "lme2510_lg", "lme2510c_s7395", + "lme2510c_s7395_old"); # Check args syntax() if (scalar(@ARGV) != 1); @@ -518,11 +519,11 @@ sub bluebird { sub af9015 { my $sourcefile = "download.ashx?file=57"; my $url = "http://www.ite.com.tw/EN/Services/$sourcefile"; - my $hash = "ff5b096ed47c080870eacdab2de33ad6"; + my $hash = "e3f08935158038d385ad382442f4bb2d"; my $outfile = "dvb-usb-af9015.fw"; my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); - my $fwoffset = 0x22708; - my $fwlength = 18225; + my $fwoffset = 0x25690; + my $fwlength = 18725; my ($chunklength, $buf, $rcount); checkstandard(); @@ -567,6 +568,66 @@ sub ngene { "$file1, $file2"; } +sub az6027{ + my $file = "AZ6027_Linux_Driver.tar.gz"; + my $url = "http://linux.terratec.de/files/$file"; + my $firmware = "dvb-usb-az6027-03.fw"; + + wgetfile($file, $url); + + #untar + if( system("tar xzvf $file $firmware")){ + die "failed to untar firmware"; + } + if( system("rm $file")){ + die ("unable to remove unnecessary files"); + } + + $firmware; +} + +sub lme2510_lg { + my $sourcefile = "LMEBDA_DVBS.sys"; + my $hash = "fc6017ad01e79890a97ec53bea157ed2"; + my $outfile = "dvb-usb-lme2510-lg.fw"; + my $hasho = "caa065d5fdbd2c09ad57b399bbf55cad"; + + checkstandard(); + + verify($sourcefile, $hash); + extract($sourcefile, 4168, 3841, $outfile); + verify($outfile, $hasho); + $outfile; +} + +sub lme2510c_s7395 { + my $sourcefile = "US2A0D.sys"; + my $hash = "b0155a8083fb822a3bd47bc360e74601"; + my $outfile = "dvb-usb-lme2510c-s7395.fw"; + my $hasho = "3a3cf1aeebd17b6ddc04cebe131e94cf"; + + checkstandard(); + + verify($sourcefile, $hash); + extract($sourcefile, 37248, 3720, $outfile); + verify($outfile, $hasho); + $outfile; +} + +sub lme2510c_s7395_old { + my $sourcefile = "LMEBDA_DVBS7395C.sys"; + my $hash = "7572ae0eb9cdf91baabd7c0ba9e09b31"; + my $outfile = "dvb-usb-lme2510c-s7395.fw"; + my $hasho = "90430c5b435eb5c6f88fd44a9d950674"; + + checkstandard(); + + verify($sourcefile, $hash); + extract($sourcefile, 4208, 3881, $outfile); + verify($outfile, $hasho); + $outfile; +} + # --------------------------------------------------------------- # Utilities diff --git a/Documentation/dvb/lmedm04.txt b/Documentation/dvb/lmedm04.txt new file mode 100644 index 00000000000..e175784b89b --- /dev/null +++ b/Documentation/dvb/lmedm04.txt @@ -0,0 +1,58 @@ +To extract firmware for the DM04/QQBOX you need to copy the +following file(s) to this directory. + +for DM04+/QQBOX LME2510C (Sharp 7395 Tuner) +------------------------------------------- + +The Sharp 7395 driver can be found in windows/system32/driver + +US2A0D.sys (dated 17 Mar 2009) + + +and run +./get_dvb_firmware lme2510c_s7395 + + will produce + dvb-usb-lme2510c-s7395.fw + +An alternative but older firmware can be found on the driver +disk DVB-S_EN_3.5A in BDADriver/driver + +LMEBDA_DVBS7395C.sys (dated 18 Jan 2008) + +and run +./get_dvb_firmware lme2510c_s7395_old + + will produce + dvb-usb-lme2510c-s7395.fw + +-------------------------------------------------------------------- + +The LG firmware can be found on the driver +disk DM04+_5.1A[LG] in BDADriver/driver + +for DM04 LME2510 (LG Tuner) +--------------------------- + +LMEBDA_DVBS.sys (dated 13 Nov 2007) + +and run +./get_dvb_firmware lme2510_lg + + will produce + dvb-usb-lme2510-lg.fw + + +Other LG firmware can be extracted manually from US280D.sys +only found in windows/system32/driver. + +dd if=US280D.sys ibs=1 skip=42616 count=3668 of=dvb-usb-lme2510-lg.fw + +for DM04 LME2510C (LG Tuner) +--------------------------- + +dd if=US280D.sys ibs=1 skip=35200 count=3850 of=dvb-usb-lme2510c-lg.fw + +--------------------------------------------------------------------- + +Copy the firmware file(s) to /lib/firmware diff --git a/Documentation/dynamic-debug-howto.txt b/Documentation/dynamic-debug-howto.txt index 674c5663d34..58ea64a9616 100644 --- a/Documentation/dynamic-debug-howto.txt +++ b/Documentation/dynamic-debug-howto.txt @@ -24,7 +24,7 @@ Dynamic debug has even more useful features: read to display the complete list of known debug statements, to help guide you Controlling dynamic debug Behaviour -=============================== +=================================== The behaviour of pr_debug()/dev_debug()s are controlled via writing to a control file in the 'debugfs' filesystem. Thus, you must first mount the debugfs @@ -212,6 +212,26 @@ Note the regexp ^[-+=][scp]+$ matches a flags specification. Note also that there is no convenient syntax to remove all the flags at once, you need to use "-psc". + +Debug messages during boot process +================================== + +To be able to activate debug messages during the boot process, +even before userspace and debugfs exists, use the boot parameter: +ddebug_query="QUERY" + +QUERY follows the syntax described above, but must not exceed 1023 +characters. The enablement of debug messages is done as an arch_initcall. +Thus you can enable debug messages in all code processed after this +arch_initcall via this boot parameter. +On an x86 system for example ACPI enablement is a subsys_initcall and +ddebug_query="file ec.c +p" +will show early Embedded Controller transactions during ACPI setup if +your machine (typically a laptop) has an Embedded Controller. +PCI (or other devices) initialization also is a hot candidate for using +this boot parameter for debugging purposes. + + Examples ======== diff --git a/Documentation/fb/framebuffer.txt b/Documentation/fb/framebuffer.txt index fe79e3c8847..58c5ae2e9f5 100644 --- a/Documentation/fb/framebuffer.txt +++ b/Documentation/fb/framebuffer.txt @@ -330,7 +330,7 @@ and on its mirrors. The latest version of fbset can be found at - http://home.tvd.be/cr26864/Linux/fbdev/ + http://www.linux-fbdev.org/ 10. Credits diff --git a/Documentation/fb/viafb.txt b/Documentation/fb/viafb.txt index f3e046a6a98..1a2e8aa3fbb 100644 --- a/Documentation/fb/viafb.txt +++ b/Documentation/fb/viafb.txt @@ -197,6 +197,54 @@ Notes: example, # fbset -depth 16 + +[Configure viafb via /proc] +--------------------------- + The following files exist in /proc/viafb + + supported_output_devices + + This read-only file contains a full ',' seperated list containing all + output devices that could be available on your platform. It is likely + that not all of those have a connector on your hardware but it should + provide a good starting point to figure out which of those names match + a real connector. + Example: + # cat /proc/viafb/supported_output_devices + + iga1/output_devices + iga2/output_devices + + These two files are readable and writable. iga1 and iga2 are the two + independent units that produce the screen image. Those images can be + forwarded to one or more output devices. Reading those files is a way + to query which output devices are currently used by an iga. + Example: + # cat /proc/viafb/iga1/output_devices + If there are no output devices printed the output of this iga is lost. + This can happen for example if only one (the other) iga is used. + Writing to these files allows adjusting the output devices during + runtime. One can add new devices, remove existing ones or switch + between igas. Essentially you can write a ',' seperated list of device + names (or a single one) in the same format as the output to those + files. You can add a '+' or '-' as a prefix allowing simple addition + and removal of devices. So a prefix '+' adds the devices from your list + to the already existing ones, '-' removes the listed devices from the + existing ones and if no prefix is given it replaces all existing ones + with the listed ones. If you remove devices they are expected to turn + off. If you add devices that are already part of the other iga they are + removed there and added to the new one. + Examples: + Add CRT as output device to iga1 + # echo +CRT > /proc/viafb/iga1/output_devices + + Remove (turn off) DVP1 and LVDS1 as output devices of iga2 + # echo -DVP1,LVDS1 > /proc/viafb/iga2/output_devices + + Replace all iga1 output devices by CRT + # echo CRT > /proc/viafb/iga1/output_devices + + [Bootup with viafb]: -------------------- Add the following line to your grub.conf: diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 1571c0c83db..d8f36f984fa 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -93,12 +93,12 @@ Why: Broken design for runtime control over driver power states, confusing inputs. This framework was never widely used, and most attempts to use it were broken. Drivers should instead be exposing domain-specific interfaces either to kernel or to userspace. -Who: Pavel Machek <pavel@suse.cz> +Who: Pavel Machek <pavel@ucw.cz> --------------------------- What: Video4Linux API 1 ioctls and from Video devices. -When: July 2009 +When: kernel 2.6.38 Files: include/linux/videodev.h Check: include/linux/videodev.h Why: V4L1 AP1 was replaced by V4L2 API during migration from 2.4 to 2.6 @@ -116,26 +116,18 @@ Who: Mauro Carvalho Chehab <mchehab@infradead.org> --------------------------- -What: PCMCIA control ioctl (needed for pcmcia-cs [cardmgr, cardctl]) -When: 2.6.35/2.6.36 -Files: drivers/pcmcia/: pcmcia_ioctl.c -Why: With the 16-bit PCMCIA subsystem now behaving (almost) like a - normal hotpluggable bus, and with it using the default kernel - infrastructure (hotplug, driver core, sysfs) keeping the PCMCIA - control ioctl needed by cardmgr and cardctl from pcmcia-cs is - unnecessary and potentially harmful (it does not provide for - proper locking), and makes further cleanups and integration of the - PCMCIA subsystem into the Linux kernel device driver model more - difficult. The features provided by cardmgr and cardctl are either - handled by the kernel itself now or are available in the new - pcmciautils package available at - http://kernel.org/pub/linux/utils/kernel/pcmcia/ - - For all architectures except ARM, the associated config symbol - has been removed from kernel 2.6.34; for ARM, it will be likely - be removed from kernel 2.6.35. The actual code will then likely - be removed from kernel 2.6.36. -Who: Dominik Brodowski <linux@dominikbrodowski.net> +What: Video4Linux obsolete drivers using V4L1 API +When: kernel 2.6.38 +Files: drivers/staging/cpia/* drivers/staging/stradis/* +Check: drivers/staging/cpia/cpia.c drivers/staging/stradis/stradis.c +Why: There are some drivers still using V4L1 API, despite all efforts we've done + to migrate. Those drivers are for obsolete hardware that the old maintainer + didn't care (or not have the hardware anymore), and that no other developer + could find any hardware to buy. They probably have no practical usage today, + and people with such old hardware could probably keep using an older version + of the kernel. Those drivers will be moved to staging on 2.6.37 and, if nobody + care enough to port and test them with V4L2 API, they'll be removed on 2.6.38. +Who: Mauro Carvalho Chehab <mchehab@infradead.org> --------------------------- @@ -174,6 +166,31 @@ Who: Eric Biederman <ebiederm@xmission.com> --------------------------- +What: /proc/<pid>/oom_adj +When: August 2012 +Why: /proc/<pid>/oom_adj allows userspace to influence the oom killer's + badness heuristic used to determine which task to kill when the kernel + is out of memory. + + The badness heuristic has since been rewritten since the introduction of + this tunable such that its meaning is deprecated. The value was + implemented as a bitshift on a score generated by the badness() + function that did not have any precise units of measure. With the + rewrite, the score is given as a proportion of available memory to the + task allocating pages, so using a bitshift which grows the score + exponentially is, thus, impossible to tune with fine granularity. + + A much more powerful interface, /proc/<pid>/oom_score_adj, was + introduced with the oom killer rewrite that allows users to increase or + decrease the badness() score linearly. This interface will replace + /proc/<pid>/oom_adj. + + A warning will be emitted to the kernel log if an application uses this + deprecated interface. After it is printed once, future warnings will be + suppressed until the kernel is rebooted. + +--------------------------- + What: remove EXPORT_SYMBOL(kernel_thread) When: August 2006 Files: arch/*/kernel/*_ksyms.c @@ -303,15 +320,6 @@ Who: Johannes Berg <johannes@sipsolutions.net> --------------------------- -What: CONFIG_NF_CT_ACCT -When: 2.6.29 -Why: Accounting can now be enabled/disabled without kernel recompilation. - Currently used only to set a default value for a feature that is also - controlled by a kernel/module/sysfs/sysctl parameter. -Who: Krzysztof Piotr Oledzki <ole@ans.pl> - ---------------------------- - What: sysfs ui for changing p4-clockmod parameters When: September 2009 Why: See commits 129f8ae9b1b5be94517da76009ea956e89104ce8 and @@ -367,24 +375,6 @@ When: 2.6.33 Why: Should be implemented in userspace, policy daemon. Who: Johannes Berg <johannes@sipsolutions.net> ---------------------------- - -What: CONFIG_INOTIFY -When: 2.6.33 -Why: last user (audit) will be converted to the newer more generic - and more easily maintained fsnotify subsystem -Who: Eric Paris <eparis@redhat.com> - ----------------------------- - -What: lock_policy_rwsem_* and unlock_policy_rwsem_* will not be - exported interface anymore. -When: 2.6.33 -Why: cpu_policy_rwsem has a new cleaner definition making it local to - cpufreq core and contained inside cpufreq.c. Other dependent - drivers should not use it in order to safely avoid lockdep issues. -Who: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> - ---------------------------- What: sound-slot/service-* module aliases and related clutters in @@ -411,34 +401,6 @@ Who: Tejun Heo <tj@kernel.org> ---------------------------- -What: Support for VMware's guest paravirtuliazation technique [VMI] will be - dropped. -When: 2.6.37 or earlier. -Why: With the recent innovations in CPU hardware acceleration technologies - from Intel and AMD, VMware ran a few experiments to compare these - techniques to guest paravirtualization technique on VMware's platform. - These hardware assisted virtualization techniques have outperformed the - performance benefits provided by VMI in most of the workloads. VMware - expects that these hardware features will be ubiquitous in a couple of - years, as a result, VMware has started a phased retirement of this - feature from the hypervisor. We will be removing this feature from the - Kernel too. Right now we are targeting 2.6.37 but can retire earlier if - technical reasons (read opportunity to remove major chunk of pvops) - arise. - - Please note that VMI has always been an optimization and non-VMI kernels - still work fine on VMware's platform. - Latest versions of VMware's product which support VMI are, - Workstation 7.0 and VSphere 4.0 on ESX side, future maintainence - releases for these products will continue supporting VMI. - - For more details about VMI retirement take a look at this, - http://blogs.vmware.com/guestosguide/2009/09/vmi-retirement.html - -Who: Alok N Kataria <akataria@vmware.com> - ----------------------------- - What: Support for lcd_switch and display_get in asus-laptop driver When: March 2010 Why: These two features use non-standard interfaces. There are the @@ -459,57 +421,6 @@ Who: Corentin Chary <corentin.chary@gmail.com> ---------------------------- -What: usbvideo quickcam_messenger driver -When: 2.6.35 -Files: drivers/media/video/usbvideo/quickcam_messenger.[ch] -Why: obsolete v4l1 driver replaced by gspca_stv06xx -Who: Hans de Goede <hdegoede@redhat.com> - ----------------------------- - -What: ov511 v4l1 driver -When: 2.6.35 -Files: drivers/media/video/ov511.[ch] -Why: obsolete v4l1 driver replaced by gspca_ov519 -Who: Hans de Goede <hdegoede@redhat.com> - ----------------------------- - -What: w9968cf v4l1 driver -When: 2.6.35 -Files: drivers/media/video/w9968cf*.[ch] -Why: obsolete v4l1 driver replaced by gspca_ov519 -Who: Hans de Goede <hdegoede@redhat.com> - ----------------------------- - -What: ovcamchip sensor framework -When: 2.6.35 -Files: drivers/media/video/ovcamchip/* -Why: Only used by obsoleted v4l1 drivers -Who: Hans de Goede <hdegoede@redhat.com> - ----------------------------- - -What: stv680 v4l1 driver -When: 2.6.35 -Files: drivers/media/video/stv680.[ch] -Why: obsolete v4l1 driver replaced by gspca_stv0680 -Who: Hans de Goede <hdegoede@redhat.com> - ----------------------------- - -What: zc0301 v4l driver -When: 2.6.35 -Files: drivers/media/video/zc0301/* -Why: Duplicate functionality with the gspca_zc3xx driver, zc0301 only - supports 2 USB-ID's (because it only supports a limited set of - sensors) wich are also supported by the gspca_zc3xx driver - (which supports 53 USB-ID's in total) -Who: Hans de Goede <hdegoede@redhat.com> - ----------------------------- - What: sysfs-class-rfkill state file When: Feb 2014 Files: net/rfkill/core.c @@ -538,37 +449,6 @@ Who: Jan Kiszka <jan.kiszka@web.de> ---------------------------- -What: KVM memory aliases support -When: July 2010 -Why: Memory aliasing support is used for speeding up guest vga access - through the vga windows. - - Modern userspace no longer uses this feature, so it's just bitrotted - code and can be removed with no impact. -Who: Avi Kivity <avi@redhat.com> - ----------------------------- - -What: xtime, wall_to_monotonic -When: 2.6.36+ -Files: kernel/time/timekeeping.c include/linux/time.h -Why: Cleaning up timekeeping internal values. Please use - existing timekeeping accessor functions to access - the equivalent functionality. -Who: John Stultz <johnstul@us.ibm.com> - ----------------------------- - -What: KVM kernel-allocated memory slots -When: July 2010 -Why: Since 2.6.25, kvm supports user-allocated memory slots, which are - much more flexible than kernel-allocated slots. All current userspace - supports the newer interface and this code can be removed with no - impact. -Who: Avi Kivity <avi@redhat.com> - ----------------------------- - What: KVM paravirt mmu host support When: January 2011 Why: The paravirt mmu host support is slower than non-paravirt mmu, both @@ -605,29 +485,6 @@ When: April 2011 Why: Superseded by xt_CT Who: Netfilter developer team <netfilter-devel@vger.kernel.org> ---------------------------- - -What: video4linux /dev/vtx teletext API support -When: 2.6.35 -Files: drivers/media/video/saa5246a.c drivers/media/video/saa5249.c - include/linux/videotext.h -Why: The vtx device nodes have been superseded by vbi device nodes - for many years. No applications exist that use the vtx support. - Of the two i2c drivers that actually support this API the saa5249 - has been impossible to use for a year now and no known hardware - that supports this device exists. The saa5246a is theoretically - supported by the old mxb boards, but it never actually worked. - - In summary: there is no hardware that can use this API and there - are no applications actually implementing this API. - - The vtx support still reserves minors 192-223 and we would really - like to reuse those for upcoming new functionality. In the unlikely - event that new hardware appears that wants to use the functionality - provided by the vtx API, then that functionality should be build - around the sliced VBI API instead. -Who: Hans Verkuil <hverkuil@xs4all.nl> - ---------------------------- What: IRQF_DISABLED @@ -637,16 +494,6 @@ Who: Thomas Gleixner <tglx@linutronix.de> ---------------------------- -What: old ieee1394 subsystem (CONFIG_IEEE1394) -When: 2.6.37 -Files: drivers/ieee1394/ except init_ohci1394_dma.c -Why: superseded by drivers/firewire/ (CONFIG_FIREWIRE) which offers more - features, better performance, and better security, all with smaller - and more modern code base -Who: Stefan Richter <stefanr@s5r6.in-berlin.de> - ----------------------------- - What: The acpi_sleep=s4_nonvs command line option When: 2.6.37 Files: arch/x86/kernel/acpi/sleep.c @@ -654,3 +501,56 @@ Why: superseded by acpi_sleep=nonvs Who: Rafael J. Wysocki <rjw@sisk.pl> ---------------------------- + +What: PCI DMA unmap state API +When: August 2012 +Why: PCI DMA unmap state API (include/linux/pci-dma.h) was replaced + with DMA unmap state API (DMA unmap state API can be used for + any bus). +Who: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp> + +---------------------------- + +What: DMA_xxBIT_MASK macros +When: Jun 2011 +Why: DMA_xxBIT_MASK macros were replaced with DMA_BIT_MASK() macros. +Who: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp> + +---------------------------- + +What: namespace cgroup (ns_cgroup) +When: 2.6.38 +Why: The ns_cgroup leads to some problems: + * cgroup creation is out-of-control + * cgroup name can conflict when pids are looping + * it is not possible to have a single process handling + a lot of namespaces without falling in a exponential creation time + * we may want to create a namespace without creating a cgroup + + The ns_cgroup is replaced by a compatibility flag 'clone_children', + where a newly created cgroup will copy the parent cgroup values. + The userspace has to manually create a cgroup and add a task to + the 'tasks' file. +Who: Daniel Lezcano <daniel.lezcano@free.fr> + +---------------------------- + +What: iwlwifi disable_hw_scan module parameters +When: 2.6.40 +Why: Hareware scan is the prefer method for iwlwifi devices for + scanning operation. Remove software scan support for all the + iwlwifi devices. + +Who: Wey-Yi Guy <wey-yi.w.guy@intel.com> + +---------------------------- + +What: access to nfsd auth cache through sys_nfsservctl or '.' files + in the 'nfsd' filesystem. +When: 2.6.40 +Why: This is a legacy interface which have been replaced by a more + dynamic cache. Continuing to maintain this interface is an + unnecessary burden. +Who: NeilBrown <neilb@suse.de> + +---------------------------- diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX index 4303614b5ad..8c624a18f67 100644 --- a/Documentation/filesystems/00-INDEX +++ b/Documentation/filesystems/00-INDEX @@ -96,8 +96,6 @@ seq_file.txt - how to use the seq_file API sharedsubtree.txt - a description of shared subtrees for namespaces. -smbfs.txt - - info on using filesystems with the SMB protocol (Win 3.11 and NT). spufs.txt - info and mount options for the SPU filesystem used on Cell. sysfs-pci.txt diff --git a/Documentation/filesystems/9p.txt b/Documentation/filesystems/9p.txt index c0236e753bc..b22abba78fe 100644 --- a/Documentation/filesystems/9p.txt +++ b/Documentation/filesystems/9p.txt @@ -111,7 +111,7 @@ OPTIONS This can be used to share devices/named pipes/sockets between hosts. This functionality will be expanded in later versions. - access there are three access modes. + access there are four access modes. user = if a user tries to access a file on v9fs filesystem for the first time, v9fs sends an attach command (Tattach) for that user. @@ -120,6 +120,8 @@ OPTIONS the files on the mounted filesystem any = v9fs does single attach and performs all operations as one user + client = ACL based access check on the 9p client + side for access validation cachetag cache tag to use the specified persistent cache. cache tags for existing cache sessions can be listed at @@ -128,7 +130,7 @@ OPTIONS RESOURCES ========= -Our current recommendation is to use Inferno (http://www.vitanuova.com/inferno) +Our current recommendation is to use Inferno (http://www.vitanuova.com/nferno/index.html) as the 9p server. You can start a 9p server under Inferno by issuing the following command: ; styxlisten -A tcp!*!564 export '#U*' diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index 96d4293607e..a91f3089001 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -92,8 +92,8 @@ prototypes: void (*destroy_inode)(struct inode *); void (*dirty_inode) (struct inode *); int (*write_inode) (struct inode *, int); - void (*drop_inode) (struct inode *); - void (*delete_inode) (struct inode *); + int (*drop_inode) (struct inode *); + void (*evict_inode) (struct inode *); void (*put_super) (struct super_block *); void (*write_super) (struct super_block *); int (*sync_fs)(struct super_block *sb, int wait); @@ -101,14 +101,13 @@ prototypes: int (*unfreeze_fs) (struct super_block *); int (*statfs) (struct dentry *, struct kstatfs *); int (*remount_fs) (struct super_block *, int *, char *); - void (*clear_inode) (struct inode *); void (*umount_begin) (struct super_block *); int (*show_options)(struct seq_file *, struct vfsmount *); ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); locking rules: - All may block. + All may block [not true, see below] None have BKL s_umount alloc_inode: @@ -116,22 +115,25 @@ destroy_inode: dirty_inode: (must not sleep) write_inode: drop_inode: !!!inode_lock!!! -delete_inode: +evict_inode: put_super: write write_super: read sync_fs: read freeze_fs: read unfreeze_fs: read -statfs: no -remount_fs: maybe (see below) -clear_inode: +statfs: maybe(read) (see below) +remount_fs: write umount_begin: no show_options: no (namespace_sem) quota_read: no (see below) quota_write: no (see below) -->remount_fs() will have the s_umount exclusive lock if it's already mounted. -When called from get_sb_single, it does NOT have the s_umount lock. +->statfs() has s_umount (shared) when called by ustat(2) (native or +compat), but that's an accident of bad API; s_umount is used to pin +the superblock down when we only have dev_t given us by userland to +identify the superblock. Everything else (statfs(), fstatfs(), etc.) +doesn't hold it when calling ->statfs() - superblock is pinned down +by resolving the pathname passed to syscall. ->quota_read() and ->quota_write() functions are both guaranteed to be the only ones operating on the quota file by the quota code (via dqio_sem) (unless an admin really wants to screw up something and @@ -320,7 +322,6 @@ fl_release_private: yes yes prototypes: int (*fl_compare_owner)(struct file_lock *, struct file_lock *); void (*fl_notify)(struct file_lock *); /* unblock callback */ - void (*fl_copy_lock)(struct file_lock *, struct file_lock *); void (*fl_release_private)(struct file_lock *); void (*fl_break)(struct file_lock *); /* break_lease callback */ @@ -328,7 +329,6 @@ locking rules: BKL may block fl_compare_owner: yes no fl_notify: yes no -fl_copy_lock: yes no fl_release_private: yes yes fl_break: yes no @@ -347,21 +347,36 @@ call this method upon the IO completion. --------------------------- block_device_operations ----------------------- prototypes: - int (*open) (struct inode *, struct file *); - int (*release) (struct inode *, struct file *); - int (*ioctl) (struct inode *, struct file *, unsigned, unsigned long); + int (*open) (struct block_device *, fmode_t); + int (*release) (struct gendisk *, fmode_t); + int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); + int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); + int (*direct_access) (struct block_device *, sector_t, void **, unsigned long *); int (*media_changed) (struct gendisk *); + void (*unlock_native_capacity) (struct gendisk *); int (*revalidate_disk) (struct gendisk *); + int (*getgeo)(struct block_device *, struct hd_geometry *); + void (*swap_slot_free_notify) (struct block_device *, unsigned long); locking rules: - BKL bd_sem -open: yes yes -release: yes yes -ioctl: yes no + BKL bd_mutex +open: no yes +release: no yes +ioctl: no no +compat_ioctl: no no +direct_access: no no media_changed: no no +unlock_native_capacity: no no revalidate_disk: no no +getgeo: no no +swap_slot_free_notify: no no (see below) + +media_changed, unlock_native_capacity and revalidate_disk are called only from +check_disk_change(). + +swap_slot_free_notify is called with swap_lock and sometimes the page lock +held. -The last two are called only from check_disk_change(). --------------------------- file_operations ------------------------------- prototypes: @@ -372,8 +387,6 @@ prototypes: ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t); int (*readdir) (struct file *, void *, filldir_t); unsigned int (*poll) (struct file *, struct poll_table_struct *); - int (*ioctl) (struct inode *, struct file *, unsigned int, - unsigned long); long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); long (*compat_ioctl) (struct file *, unsigned int, unsigned long); int (*mmap) (struct file *, struct vm_area_struct *); @@ -407,8 +420,7 @@ write: no aio_write: no readdir: no poll: no -ioctl: yes (see below) -unlocked_ioctl: no (see below) +unlocked_ioctl: no compat_ioctl: no mmap: no open: no @@ -451,9 +463,6 @@ move ->readdir() to inode_operations and use a separate method for directory anything that resembles union-mount we won't have a struct file for all components. And there are other reasons why the current interface is a mess... -->ioctl() on regular files is superceded by the ->unlocked_ioctl() that -doesn't take the BKL. - ->read on directories probably must go away - we should just enforce -EISDIR in sys_read() and friends. diff --git a/Documentation/filesystems/affs.txt b/Documentation/filesystems/affs.txt index 2d1524469c2..81ac488e375 100644 --- a/Documentation/filesystems/affs.txt +++ b/Documentation/filesystems/affs.txt @@ -216,4 +216,4 @@ due to an incompatibility with the Amiga floppy controller. If you are interested in an Amiga Emulator for Linux, look at -http://www.freiburg.linux.de/~uae/ +http://web.archive.org/web/*/http://www.freiburg.linux.de/~uae/ diff --git a/Documentation/filesystems/befs.txt b/Documentation/filesystems/befs.txt index 67391a15949..6e49c363938 100644 --- a/Documentation/filesystems/befs.txt +++ b/Documentation/filesystems/befs.txt @@ -31,7 +31,7 @@ Current maintainer: Sergey S. Kostyliov <rathamahata@php4.ru> WHAT IS THIS DRIVER? ================== -This module implements the native filesystem of BeOS <http://www.be.com/> +This module implements the native filesystem of BeOS http://www.beincorporated.com/ for the linux 2.4.1 and later kernels. Currently it is a read-only implementation. @@ -61,7 +61,7 @@ step 2. Configuration & make kernel The linux kernel has many compile-time options. Most of them are beyond the scope of this document. I suggest the Kernel-HOWTO document as a good general -reference on this topic. <http://www.linux.com/howto/Kernel-HOWTO.html> +reference on this topic. http://www.linuxdocs.org/HOWTOs/Kernel-HOWTO-4.html However, to use the BeFS module, you must enable it at configure time. diff --git a/Documentation/filesystems/caching/fscache.txt b/Documentation/filesystems/caching/fscache.txt index a91e2e2095b..770267af5b3 100644 --- a/Documentation/filesystems/caching/fscache.txt +++ b/Documentation/filesystems/caching/fscache.txt @@ -343,8 +343,8 @@ This will look something like: [root@andromeda ~]# head /proc/fs/fscache/objects OBJECT PARENT STAT CHLDN OPS OOP IPR EX READS EM EV F S | NETFS_COOKIE_DEF TY FL NETFS_DATA OBJECT_KEY, AUX_DATA ======== ======== ==== ===== === === === == ===== == == = = | ================ == == ================ ================ - 17e4b 2 ACTV 0 0 0 0 0 0 7b 4 0 8 | NFS.fh DT 0 ffff88001dd82820 010006017edcf8bbc93b43298fdfbe71e50b57b13a172c0117f38472, e567634700000000000000000000000063f2404a000000000000000000000000c9030000000000000000000063f2404a - 1693a 2 ACTV 0 0 0 0 0 0 7b 4 0 8 | NFS.fh DT 0 ffff88002db23380 010006017edcf8bbc93b43298fdfbe71e50b57b1e0162c01a2df0ea6, 420ebc4a000000000000000000000000420ebc4a0000000000000000000000000e1801000000000000000000420ebc4a + 17e4b 2 ACTV 0 0 0 0 0 0 7b 4 0 0 | NFS.fh DT 0 ffff88001dd82820 010006017edcf8bbc93b43298fdfbe71e50b57b13a172c0117f38472, e567634700000000000000000000000063f2404a000000000000000000000000c9030000000000000000000063f2404a + 1693a 2 ACTV 0 0 0 0 0 0 7b 4 0 0 | NFS.fh DT 0 ffff88002db23380 010006017edcf8bbc93b43298fdfbe71e50b57b1e0162c01a2df0ea6, 420ebc4a000000000000000000000000420ebc4a0000000000000000000000000e1801000000000000000000420ebc4a where the first set of columns before the '|' describe the object: @@ -362,7 +362,7 @@ where the first set of columns before the '|' describe the object: EM Object's event mask EV Events raised on this object F Object flags - S Object slow-work work item flags + S Object work item busy state mask (1:pending 2:running) and the second set of columns describe the object's cookie, if present: @@ -395,8 +395,8 @@ and the following paired letters: w Show objects that don't have pending writes R Show objects that have outstanding reads r Show objects that don't have outstanding reads - S Show objects that have slow work queued - s Show objects that don't have slow work queued + S Show objects that have work queued + s Show objects that don't have work queued If neither side of a letter pair is given, then both are implied. For example: diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt index e1def1786e5..6ab9442d7ee 100644 --- a/Documentation/filesystems/ext4.txt +++ b/Documentation/filesystems/ext4.txt @@ -353,6 +353,20 @@ noauto_da_alloc replacing existing files via patterns such as system crashes before the delayed allocation blocks are forced to disk. +noinit_itable Do not initialize any uninitialized inode table + blocks in the background. This feature may be + used by installation CD's so that the install + process can complete as quickly as possible; the + inode table initialization process would then be + deferred until the next time the file system + is unmounted. + +init_itable=n The lazy itable init code will wait n times the + number of milliseconds it took to zero out the + previous block group's inode table. This + minimizes the impact on the systme performance + while file system's inode table is being initialized. + discard Controls whether ext4 should issue discard/TRIM nodiscard(*) commands to the underlying block device when blocks are freed. This is useful for SSD devices diff --git a/Documentation/filesystems/isofs.txt b/Documentation/filesystems/isofs.txt index 3c367c3b360..ba0a93384de 100644 --- a/Documentation/filesystems/isofs.txt +++ b/Documentation/filesystems/isofs.txt @@ -41,7 +41,7 @@ Mount options unique to the isofs filesystem. sbsector=xxx Session begins from sector xxx Recommended documents about ISO 9660 standard are located at: -http://www.y-adagio.com/public/standards/iso_cdromr/tocont.htm +http://www.y-adagio.com/ ftp://ftp.ecma.ch/ecma-st/Ecma-119.pdf Quoting from the PDF "This 2nd Edition of Standard ECMA-119 is technically identical with ISO 9660.", so it is a valid and gratis substitute of the diff --git a/Documentation/filesystems/nfs/00-INDEX b/Documentation/filesystems/nfs/00-INDEX index 2f68cd68876..a57e12411d2 100644 --- a/Documentation/filesystems/nfs/00-INDEX +++ b/Documentation/filesystems/nfs/00-INDEX @@ -12,5 +12,9 @@ nfs-rdma.txt - how to install and setup the Linux NFS/RDMA client and server software nfsroot.txt - short guide on setting up a diskless box with NFS root filesystem. +pnfs.txt + - short explanation of some of the internals of the pnfs client code rpc-cache.txt - introduction to the caching mechanisms in the sunrpc layer. +idmapper.txt + - information for configuring request-keys to be used by idmapper diff --git a/Documentation/filesystems/nfs/idmapper.txt b/Documentation/filesystems/nfs/idmapper.txt new file mode 100644 index 00000000000..b9b4192ea8b --- /dev/null +++ b/Documentation/filesystems/nfs/idmapper.txt @@ -0,0 +1,67 @@ + +========= +ID Mapper +========= +Id mapper is used by NFS to translate user and group ids into names, and to +translate user and group names into ids. Part of this translation involves +performing an upcall to userspace to request the information. Id mapper will +user request-key to perform this upcall and cache the result. The program +/usr/sbin/nfs.idmap should be called by request-key, and will perform the +translation and initialize a key with the resulting information. + + NFS_USE_NEW_IDMAPPER must be selected when configuring the kernel to use this + feature. + +=========== +Configuring +=========== +The file /etc/request-key.conf will need to be modified so /sbin/request-key can +direct the upcall. The following line should be added: + +#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ... +#====== ======= =============== =============== =============================== +create id_resolver * * /usr/sbin/nfs.idmap %k %d 600 + +This will direct all id_resolver requests to the program /usr/sbin/nfs.idmap. +The last parameter, 600, defines how many seconds into the future the key will +expire. This parameter is optional for /usr/sbin/nfs.idmap. When the timeout +is not specified, nfs.idmap will default to 600 seconds. + +id mapper uses for key descriptions: + uid: Find the UID for the given user + gid: Find the GID for the given group + user: Find the user name for the given UID + group: Find the group name for the given GID + +You can handle any of these individually, rather than using the generic upcall +program. If you would like to use your own program for a uid lookup then you +would edit your request-key.conf so it look similar to this: + +#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ... +#====== ======= =============== =============== =============================== +create id_resolver uid:* * /some/other/program %k %d 600 +create id_resolver * * /usr/sbin/nfs.idmap %k %d 600 + +Notice that the new line was added above the line for the generic program. +request-key will find the first matching line and corresponding program. In +this case, /some/other/program will handle all uid lookups and +/usr/sbin/nfs.idmap will handle gid, user, and group lookups. + +See <file:Documentation/keys-request-keys.txt> for more information about the +request-key function. + + +========= +nfs.idmap +========= +nfs.idmap is designed to be called by request-key, and should not be run "by +hand". This program takes two arguments, a serialized key and a key +description. The serialized key is first converted into a key_serial_t, and +then passed as an argument to keyctl_instantiate (both are part of keyutils.h). + +The actual lookups are performed by functions found in nfsidmap.h. nfs.idmap +determines the correct function to call by looking at the first part of the +description string. For example, a uid lookup description will appear as +"uid:user@domain". + +nfs.idmap will return 0 if the key was instantiated, and non-zero otherwise. diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/filesystems/nfs/nfsroot.txt index 3ba0b945aaf..90c71c6f0d0 100644 --- a/Documentation/filesystems/nfs/nfsroot.txt +++ b/Documentation/filesystems/nfs/nfsroot.txt @@ -124,6 +124,8 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> <hostname> Name of the client. May be supplied by autoconfiguration, but its absence will not trigger autoconfiguration. + If specified and DHCP is used, the user provided hostname will + be carried in the DHCP request to hopefully update DNS record. Default: Client IP address is used in ASCII notation. @@ -157,6 +159,28 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> Default: any +nfsrootdebug + + This parameter enables debugging messages to appear in the kernel + log at boot time so that administrators can verify that the correct + NFS mount options, server address, and root path are passed to the + NFS client. + + +rdinit=<executable file> + + To specify which file contains the program that starts system + initialization, administrators can use this command line parameter. + The default value of this parameter is "/init". If the specified + file exists and the kernel can execute it, root filesystem related + kernel command line parameters, including `nfsroot=', are ignored. + + A description of the process of mounting the root file system can be + found in: + + Documentation/early-userspace/README + + 3.) Boot Loader diff --git a/Documentation/filesystems/nfs/pnfs.txt b/Documentation/filesystems/nfs/pnfs.txt new file mode 100644 index 00000000000..bc0b9cfe095 --- /dev/null +++ b/Documentation/filesystems/nfs/pnfs.txt @@ -0,0 +1,48 @@ +Reference counting in pnfs: +========================== + +The are several inter-related caches. We have layouts which can +reference multiple devices, each of which can reference multiple data servers. +Each data server can be referenced by multiple devices. Each device +can be referenced by multiple layouts. To keep all of this straight, +we need to reference count. + + +struct pnfs_layout_hdr +---------------------- +The on-the-wire command LAYOUTGET corresponds to struct +pnfs_layout_segment, usually referred to by the variable name lseg. +Each nfs_inode may hold a pointer to a cache of of these layout +segments in nfsi->layout, of type struct pnfs_layout_hdr. + +We reference the header for the inode pointing to it, across each +outstanding RPC call that references it (LAYOUTGET, LAYOUTRETURN, +LAYOUTCOMMIT), and for each lseg held within. + +Each header is also (when non-empty) put on a list associated with +struct nfs_client (cl_layouts). Being put on this list does not bump +the reference count, as the layout is kept around by the lseg that +keeps it in the list. + +deviceid_cache +-------------- +lsegs reference device ids, which are resolved per nfs_client and +layout driver type. The device ids are held in a RCU cache (struct +nfs4_deviceid_cache). The cache itself is referenced across each +mount. The entries (struct nfs4_deviceid) themselves are held across +the lifetime of each lseg referencing them. + +RCU is used because the deviceid is basically a write once, read many +data structure. The hlist size of 32 buckets needs better +justification, but seems reasonable given that we can have multiple +deviceid's per filesystem, and multiple filesystems per nfs_client. + +The hash code is copied from the nfsd code base. A discussion of +hashing and variations of this algorithm can be found at: +http://groups.google.com/group/comp.lang.c/browse_thread/thread/9522965e2b8d3809 + +data server cache +----------------- +file driver devices refer to data servers, which are kept in a module +level cache. Its reference is held over the lifetime of the deviceid +pointing to it. diff --git a/Documentation/filesystems/nilfs2.txt b/Documentation/filesystems/nilfs2.txt index d3e7673995e..d5c0cef38a7 100644 --- a/Documentation/filesystems/nilfs2.txt +++ b/Documentation/filesystems/nilfs2.txt @@ -49,7 +49,10 @@ Mount options NILFS2 supports the following mount options: (*) == default -nobarrier Disables barriers. +barrier(*) This enables/disables the use of write barriers. This +nobarrier requires an IO stack which can support barriers, and + if nilfs gets an error on a barrier write, it will + disable again with a warning. errors=continue Keep going on a filesystem error. errors=remount-ro(*) Remount the filesystem read-only on an error. errors=panic Panic and halt the machine if an error occurs. @@ -74,9 +77,10 @@ norecovery Disable recovery of the filesystem on mount. This disables every write access on the device for read-only mounts or snapshots. This option will fail for r/w mounts on an unclean volume. -discard Issue discard/TRIM commands to the underlying block - device when blocks are freed. This is useful for SSD - devices and sparse/thinly-provisioned LUNs. +discard This enables/disables the use of discard/TRIM commands. +nodiscard(*) The discard/TRIM commands are sent to the underlying + block device when blocks are freed. This is useful + for SSD devices and sparse/thinly-provisioned LUNs. NILFS2 usage ============ diff --git a/Documentation/filesystems/ocfs2.txt b/Documentation/filesystems/ocfs2.txt index 1f7ae144f6d..5393e661169 100644 --- a/Documentation/filesystems/ocfs2.txt +++ b/Documentation/filesystems/ocfs2.txt @@ -87,3 +87,10 @@ dir_resv_level= (*) By default, directory reservations will scale with file reservations - users should rarely need to change this value. If allocation reservations are turned off, this option will have no effect. +coherency=full (*) Disallow concurrent O_DIRECT writes, cluster inode + lock will be taken to force other nodes drop cache, + therefore full cluster coherency is guaranteed even + for O_DIRECT writes. +coherency=buffered Allow concurrent O_DIRECT writes without EX lock among + nodes, which gains high performance at risk of getting + stale data on other nodes. diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index a7e9746ee7e..b12c8953868 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -273,3 +273,48 @@ it's safe to remove it. If you don't need it, remove it. deliberate; as soon as struct block_device * is propagated in a reasonable way by that code fixing will become trivial; until then nothing can be done. + +[mandatory] + + block truncatation on error exit from ->write_begin, and ->direct_IO +moved from generic methods (block_write_begin, cont_write_begin, +nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at +ext2_write_failed and callers for an example. + +[mandatory] + + ->truncate is going away. The whole truncate sequence needs to be +implemented in ->setattr, which is now mandatory for filesystems +implementing on-disk size changes. Start with a copy of the old inode_setattr +and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to +be in order of zeroing blocks using block_truncate_page or similar helpers, +size update and on finally on-disk truncation which should not fail. +inode_change_ok now includes the size checks for ATTR_SIZE and must be called +in the beginning of ->setattr unconditionally. + +[mandatory] + + ->clear_inode() and ->delete_inode() are gone; ->evict_inode() should +be used instead. It gets called whenever the inode is evicted, whether it has +remaining links or not. Caller does *not* evict the pagecache or inode-associated +metadata buffers; getting rid of those is responsibility of method, as it had +been for ->delete_inode(). + ->drop_inode() returns int now; it's called on final iput() with inode_lock +held and it returns true if filesystems wants the inode to be dropped. As before, +generic_drop_inode() is still the default and it's been updated appropriately. +generic_delete_inode() is also alive and it consists simply of return 1. Note that +all actual eviction work is done by caller after ->drop_inode() returns. + clear_inode() is gone; use end_writeback() instead. As before, it must +be called exactly once on each call of ->evict_inode() (as it used to be for +each call of ->delete_inode()). Unlike before, if you are using inode-associated +metadata buffers (i.e. mark_buffer_dirty_inode()), it's your responsibility to +call invalidate_inode_buffers() before end_writeback(). + No async writeback (and thus no calls of ->write_inode()) will happen +after end_writeback() returns, so actions that should not overlap with ->write_inode() +(e.g. freeing on-disk inode if i_nlink is 0) ought to be done after that call. + + NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out +if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput() +may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly +free the on-disk inode, you may end up doing that while ->write_inode() is writing +to it. diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 9fb6cbe70bd..e73df2722ff 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -33,7 +33,8 @@ Table of Contents 2 Modifying System Parameters 3 Per-Process Parameters - 3.1 /proc/<pid>/oom_adj - Adjust the oom-killer score + 3.1 /proc/<pid>/oom_adj & /proc/<pid>/oom_score_adj - Adjust the oom-killer + score 3.2 /proc/<pid>/oom_score - Display current oom-killer score 3.3 /proc/<pid>/io - Display the IO accounting fields 3.4 /proc/<pid>/coredump_filter - Core dump filtering settings @@ -73,9 +74,9 @@ contact Bodo Bauer at bb@ricochet.net. We'll be happy to add them to this document. The latest version of this document is available online at -http://skaro.nightcrawler.com/~bb/Docs/Proc as HTML version. +http://tldp.org/LDP/Linux-Filesystem-Hierarchy/html/proc.html -If the above direction does not works for you, ypu could try the kernel +If the above direction does not works for you, you could try the kernel mailing list at linux-kernel@vger.kernel.org and/or try to reach me at comandante@zaralinux.com. @@ -135,6 +136,7 @@ Table 1-1: Process specific entries in /proc statm Process memory status information status Process status in human readable form wchan If CONFIG_KALLSYMS is set, a pre-decoded wchan + pagemap Page table stack Report full stack trace, enable via CONFIG_STACKTRACE smaps a extension based on maps, showing the memory consumption of each mapping @@ -369,17 +371,24 @@ Shared_Dirty: 0 kB Private_Clean: 0 kB Private_Dirty: 0 kB Referenced: 892 kB +Anonymous: 0 kB Swap: 0 kB KernelPageSize: 4 kB MMUPageSize: 4 kB -The first of these lines shows the same information as is displayed for the -mapping in /proc/PID/maps. The remaining lines show the size of the mapping, -the amount of the mapping that is currently resident in RAM, the "proportional -set size” (divide each shared page by the number of processes sharing it), the -number of clean and dirty shared pages in the mapping, and the number of clean -and dirty private pages in the mapping. The "Referenced" indicates the amount -of memory currently marked as referenced or accessed. +The first of these lines shows the same information as is displayed for the +mapping in /proc/PID/maps. The remaining lines show the size of the mapping +(size), the amount of the mapping that is currently resident in RAM (RSS), the +process' proportional share of this mapping (PSS), the number of clean and +dirty private pages in the mapping. Note that even a page which is part of a +MAP_SHARED mapping, but has only a single pte mapped, i.e. is currently used +by only one process, is accounted as private and not as shared. "Referenced" +indicates the amount of memory currently marked as referenced or accessed. +"Anonymous" shows the amount of memory that does not belong to any file. Even +a mapping associated with a file may contain anonymous pages: when MAP_PRIVATE +and a page is modified, the file page is replaced by a private anonymous copy. +"Swap" shows how much would-be-anonymous memory is also used, but out on +swap. This file is only present if the CONFIG_MMU kernel configuration option is enabled. @@ -396,6 +405,9 @@ To clear the bits for the file mapped pages associated with the process > echo 3 > /proc/PID/clear_refs Any other value written to /proc/PID/clear_refs will have no effect. +The /proc/pid/pagemap gives the PFN, which can be used to find the pageflags +using /proc/kpageflags and number of times a page is mapped using +/proc/kpagecount. For detailed explanation, see Documentation/vm/pagemap.txt. 1.2 Kernel data --------------- @@ -1234,42 +1246,64 @@ of the kernel. CHAPTER 3: PER-PROCESS PARAMETERS ------------------------------------------------------------------------------ -3.1 /proc/<pid>/oom_adj - Adjust the oom-killer score ------------------------------------------------------- - -This file can be used to adjust the score used to select which processes -should be killed in an out-of-memory situation. Giving it a high score will -increase the likelihood of this process being killed by the oom-killer. Valid -values are in the range -16 to +15, plus the special value -17, which disables -oom-killing altogether for this process. - -The process to be killed in an out-of-memory situation is selected among all others -based on its badness score. This value equals the original memory size of the process -and is then updated according to its CPU time (utime + stime) and the -run time (uptime - start time). The longer it runs the smaller is the score. -Badness score is divided by the square root of the CPU time and then by -the double square root of the run time. - -Swapped out tasks are killed first. Half of each child's memory size is added to -the parent's score if they do not share the same memory. Thus forking servers -are the prime candidates to be killed. Having only one 'hungry' child will make -parent less preferable than the child. - -/proc/<pid>/oom_score shows process' current badness score. - -The following heuristics are then applied: - * if the task was reniced, its score doubles - * superuser or direct hardware access tasks (CAP_SYS_ADMIN, CAP_SYS_RESOURCE - or CAP_SYS_RAWIO) have their score divided by 4 - * if oom condition happened in one cpuset and checked process does not belong - to it, its score is divided by 8 - * the resulting score is multiplied by two to the power of oom_adj, i.e. - points <<= oom_adj when it is positive and - points >>= -(oom_adj) otherwise - -The task with the highest badness score is then selected and its children -are killed, process itself will be killed in an OOM situation when it does -not have children or some of them disabled oom like described above. +3.1 /proc/<pid>/oom_adj & /proc/<pid>/oom_score_adj- Adjust the oom-killer score +-------------------------------------------------------------------------------- + +These file can be used to adjust the badness heuristic used to select which +process gets killed in out of memory conditions. + +The badness heuristic assigns a value to each candidate task ranging from 0 +(never kill) to 1000 (always kill) to determine which process is targeted. The +units are roughly a proportion along that range of allowed memory the process +may allocate from based on an estimation of its current memory and swap use. +For example, if a task is using all allowed memory, its badness score will be +1000. If it is using half of its allowed memory, its score will be 500. + +There is an additional factor included in the badness score: root +processes are given 3% extra memory over other tasks. + +The amount of "allowed" memory depends on the context in which the oom killer +was called. If it is due to the memory assigned to the allocating task's cpuset +being exhausted, the allowed memory represents the set of mems assigned to that +cpuset. If it is due to a mempolicy's node(s) being exhausted, the allowed +memory represents the set of mempolicy nodes. If it is due to a memory +limit (or swap limit) being reached, the allowed memory is that configured +limit. Finally, if it is due to the entire system being out of memory, the +allowed memory represents all allocatable resources. + +The value of /proc/<pid>/oom_score_adj is added to the badness score before it +is used to determine which task to kill. Acceptable values range from -1000 +(OOM_SCORE_ADJ_MIN) to +1000 (OOM_SCORE_ADJ_MAX). This allows userspace to +polarize the preference for oom killing either by always preferring a certain +task or completely disabling it. The lowest possible value, -1000, is +equivalent to disabling oom killing entirely for that task since it will always +report a badness score of 0. + +Consequently, it is very simple for userspace to define the amount of memory to +consider for each task. Setting a /proc/<pid>/oom_score_adj value of +500, for +example, is roughly equivalent to allowing the remainder of tasks sharing the +same system, cpuset, mempolicy, or memory controller resources to use at least +50% more memory. A value of -500, on the other hand, would be roughly +equivalent to discounting 50% of the task's allowed memory from being considered +as scoring against the task. + +For backwards compatibility with previous kernels, /proc/<pid>/oom_adj may also +be used to tune the badness score. Its acceptable values range from -16 +(OOM_ADJUST_MIN) to +15 (OOM_ADJUST_MAX) and a special value of -17 +(OOM_DISABLE) to disable oom killing entirely for that task. Its value is +scaled linearly with /proc/<pid>/oom_score_adj. + +Writing to /proc/<pid>/oom_score_adj or /proc/<pid>/oom_adj will change the +other with its scaled value. + +NOTICE: /proc/<pid>/oom_adj is deprecated and will be removed, please see +Documentation/feature-removal-schedule.txt. + +Caveat: when a parent task is selected, the oom killer will sacrifice any first +generation children with seperate address spaces instead, if possible. This +avoids servers and important system daemons from being killed and loses the +minimal amount of work. + 3.2 /proc/<pid>/oom_score - Display current oom-killer score ------------------------------------------------------------- diff --git a/Documentation/filesystems/sharedsubtree.txt b/Documentation/filesystems/sharedsubtree.txt index fc0e39af43c..4ede421c968 100644 --- a/Documentation/filesystems/sharedsubtree.txt +++ b/Documentation/filesystems/sharedsubtree.txt @@ -62,10 +62,10 @@ replicas continue to be exactly same. # mount /dev/sd0 /tmp/a #ls /tmp/a - t1 t2 t2 + t1 t2 t3 #ls /mnt/a - t1 t2 t2 + t1 t2 t3 Note that the mount has propagated to the mount at /mnt as well. diff --git a/Documentation/filesystems/smbfs.txt b/Documentation/filesystems/smbfs.txt deleted file mode 100644 index 194fb0decd2..00000000000 --- a/Documentation/filesystems/smbfs.txt +++ /dev/null @@ -1,8 +0,0 @@ -Smbfs is a filesystem that implements the SMB protocol, which is the -protocol used by Windows for Workgroups, Windows 95 and Windows NT. -Smbfs was inspired by Samba, the program written by Andrew Tridgell -that turns any Unix host into a file server for DOS or Windows clients. - -Smbfs is a SMB client, but uses parts of samba for its operation. For -more info on samba, including documentation, please go to -http://www.samba.org/ and then on to your nearest mirror. diff --git a/Documentation/filesystems/squashfs.txt b/Documentation/filesystems/squashfs.txt index 203f7202cc9..66699afd66c 100644 --- a/Documentation/filesystems/squashfs.txt +++ b/Documentation/filesystems/squashfs.txt @@ -2,7 +2,7 @@ SQUASHFS 4.0 FILESYSTEM ======================= Squashfs is a compressed read-only filesystem for Linux. -It uses zlib compression to compress files, inodes and directories. +It uses zlib/lzo compression to compress files, inodes and directories. Inodes in the system are very small and all blocks are packed to minimise data overhead. Block sizes greater than 4K are supported up to a maximum of 1Mbytes (default block size 128K). diff --git a/Documentation/filesystems/sysfs-pci.txt b/Documentation/filesystems/sysfs-pci.txt index 85354b32d73..74eaac26f8b 100644 --- a/Documentation/filesystems/sysfs-pci.txt +++ b/Documentation/filesystems/sysfs-pci.txt @@ -39,7 +39,7 @@ files, each with their own function. local_cpus nearby CPU mask (cpumask, ro) remove remove device from kernel's list (ascii, wo) resource PCI resource host addresses (ascii, ro) - resource0..N PCI resource N, if present (binary, mmap) + resource0..N PCI resource N, if present (binary, mmap, rw[1]) resource0_wc..N_wc PCI WC map resource N, if prefetchable (binary, mmap) rom PCI ROM resource, if present (binary, ro) subsystem_device PCI subsystem device (ascii, ro) @@ -54,13 +54,16 @@ files, each with their own function. binary - file contains binary data cpumask - file contains a cpumask type +[1] rw for RESOURCE_IO (I/O port) regions only + The read only files are informational, writes to them will be ignored, with the exception of the 'rom' file. Writable files can be used to perform actions on the device (e.g. changing config space, detaching a device). mmapable files are available via an mmap of the file at offset 0 and can be used to do actual device programming from userspace. Note that some platforms don't support mmapping of certain resources, so be sure to check the return -value from any attempted mmap. +value from any attempted mmap. The most notable of these are I/O port +resources, which also provide read/write access. The 'enable' file provides a counter that indicates how many times the device has been enabled. If the 'enable' file currently returns '4', and a '1' is diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 931c806642c..5d1335faec2 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -4,7 +4,7 @@ sysfs - _The_ filesystem for exporting kernel objects. Patrick Mochel <mochel@osdl.org> Mike Murphy <mamurph@cs.clemson.edu> -Revised: 22 February 2009 +Revised: 15 July 2010 Original: 10 January 2003 @@ -124,7 +124,7 @@ show and store methods of the attribute owners. struct sysfs_ops { ssize_t (*show)(struct kobject *, struct attribute *, char *); - ssize_t (*store)(struct kobject *, struct attribute *, const char *); + ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); }; [ Subsystems should have already defined a struct kobj_type as a @@ -139,18 +139,22 @@ calls the associated methods. To illustrate: +#define to_dev(obj) container_of(obj, struct device, kobj) #define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) -#define to_dev(d) container_of(d, struct device, kobj) -static ssize_t -dev_attr_show(struct kobject * kobj, struct attribute * attr, char * buf) +static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, + char *buf) { - struct device_attribute * dev_attr = to_dev_attr(attr); - struct device * dev = to_dev(kobj); - ssize_t ret = 0; + struct device_attribute *dev_attr = to_dev_attr(attr); + struct device *dev = to_dev(kobj); + ssize_t ret = -EIO; if (dev_attr->show) - ret = dev_attr->show(dev, buf); + ret = dev_attr->show(dev, dev_attr, buf); + if (ret >= (ssize_t)PAGE_SIZE) { + print_symbol("dev_attr_show: %s returned bad count\n", + (unsigned long)dev_attr->show); + } return ret; } @@ -163,10 +167,9 @@ To read or write attributes, show() or store() methods must be specified when declaring the attribute. The method types should be as simple as those defined for device attributes: -ssize_t (*show)(struct device * dev, struct device_attribute * attr, - char * buf); -ssize_t (*store)(struct device * dev, struct device_attribute * attr, - const char * buf); +ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf); +ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); IOW, they should take only an object, an attribute, and a buffer as parameters. @@ -209,8 +212,8 @@ Other notes: - show() should always use snprintf(). -- store() should return the number of bytes used from the buffer. This - can be done using strlen(). +- store() should return the number of bytes used from the buffer. If the + entire buffer has been used, just return the count argument. - show() or store() can always return errors. If a bad value comes through, be sure to return an error. @@ -223,15 +226,18 @@ Other notes: A very simple (and naive) implementation of a device attribute is: -static ssize_t show_name(struct device *dev, struct device_attribute *attr, char *buf) +static ssize_t show_name(struct device *dev, struct device_attribute *attr, + char *buf) { return snprintf(buf, PAGE_SIZE, "%s\n", dev->name); } -static ssize_t store_name(struct device * dev, const char * buf) +static ssize_t store_name(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count) { - sscanf(buf, "%20s", dev->name); - return strnlen(buf, PAGE_SIZE); + snprintf(dev->name, sizeof(dev->name), "%.*s", + (int)min(count, sizeof(dev->name) - 1), buf); + return count; } static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); @@ -327,7 +333,7 @@ Structure: struct bus_attribute { struct attribute attr; ssize_t (*show)(struct bus_type *, char * buf); - ssize_t (*store)(struct bus_type *, const char * buf); + ssize_t (*store)(struct bus_type *, const char * buf, size_t count); }; Declaring: diff --git a/Documentation/filesystems/vfat.txt b/Documentation/filesystems/vfat.txt index eed520fd0c8..ead764b2728 100644 --- a/Documentation/filesystems/vfat.txt +++ b/Documentation/filesystems/vfat.txt @@ -165,7 +165,8 @@ TEST SUITE If you plan to make any modifications to the vfat filesystem, please get the test suite that comes with the vfat distribution at - http://bmrc.berkeley.edu/people/chaffee/vfat.html + http://web.archive.org/web/*/http://bmrc.berkeley.edu/ + people/chaffee/vfat.html This tests quite a few parts of the vfat filesystem and additional tests for new features or untested features would be appreciated. diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 94677e7dcb1..ed7e5efc06d 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -727,7 +727,6 @@ struct file_operations { ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t); int (*readdir) (struct file *, void *, filldir_t); unsigned int (*poll) (struct file *, struct poll_table_struct *); - int (*ioctl) (struct inode *, struct file *, unsigned int, unsigned long); long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); long (*compat_ioctl) (struct file *, unsigned int, unsigned long); int (*mmap) (struct file *, struct vm_area_struct *); @@ -768,10 +767,7 @@ otherwise noted. activity on this file and (optionally) go to sleep until there is activity. Called by the select(2) and poll(2) system calls - ioctl: called by the ioctl(2) system call - - unlocked_ioctl: called by the ioctl(2) system call. Filesystems that do not - require the BKL should use this method instead of the ioctl() above. + unlocked_ioctl: called by the ioctl(2) system call. compat_ioctl: called by the ioctl(2) system call when 32 bit system calls are used on 64 bit kernels. diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt index 9878f50d6ed..7bff3e4f35d 100644 --- a/Documentation/filesystems/xfs.txt +++ b/Documentation/filesystems/xfs.txt @@ -131,17 +131,6 @@ When mounting an XFS filesystem, the following options are accepted. Don't check for double mounted file systems using the file system uuid. This is useful to mount LVM snapshot volumes. - osyncisosync - Make O_SYNC writes implement true O_SYNC. WITHOUT this option, - Linux XFS behaves as if an "osyncisdsync" option is used, - which will make writes to files opened with the O_SYNC flag set - behave as if the O_DSYNC flag had been used instead. - This can result in better performance without compromising - data safety. - However if this option is not in effect, timestamp updates from - O_SYNC writes can be lost if the system crashes. - If timestamp updates are critical, use the osyncisosync option. - uquota/usrquota/uqnoenforce/quota User disk quota accounting enabled, and limits (optionally) enforced. Refer to xfs_quota(8) for further details. diff --git a/Documentation/firmware_class/hotplug-script b/Documentation/firmware_class/hotplug-script index 1990130f2ab..8143a950b60 100644 --- a/Documentation/firmware_class/hotplug-script +++ b/Documentation/firmware_class/hotplug-script @@ -6,11 +6,12 @@ HOTPLUG_FW_DIR=/usr/lib/hotplug/firmware/ -echo 1 > /sys/$DEVPATH/loading -cat $HOTPLUG_FW_DIR/$FIRMWARE > /sys/$DEVPATH/data -echo 0 > /sys/$DEVPATH/loading - -# To cancel the load in case of error: -# -# echo -1 > /sys/$DEVPATH/loading -# +if [ "$SUBSYSTEM" == "firmware" -a "$ACTION" == "add" ]; then + if [ -f $HOTPLUG_FW_DIR/$FIRMWARE ]; then + echo 1 > /sys/$DEVPATH/loading + cat $HOTPLUG_FW_DIR/$FIRMWARE > /sys/$DEVPATH/data + echo 0 > /sys/$DEVPATH/loading + else + echo -1 > /sys/$DEVPATH/loading + fi +fi diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt index c2c6e9b39bb..9633da01ff4 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio.txt @@ -109,17 +109,19 @@ use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders. If you want to initialize a structure with an invalid GPIO number, use some negative number (perhaps "-EINVAL"); that will never be valid. To -test if a number could reference a GPIO, you may use this predicate: +test if such number from such a structure could reference a GPIO, you +may use this predicate: int gpio_is_valid(int number); A number that's not valid will be rejected by calls which may request or free GPIOs (see below). Other numbers may also be rejected; for -example, a number might be valid but unused on a given board. - -Whether a platform supports multiple GPIO controllers is currently a -platform-specific implementation issue. +example, a number might be valid but temporarily unused on a given board. +Whether a platform supports multiple GPIO controllers is a platform-specific +implementation issue, as are whether that support can leave "holes" in the space +of GPIO numbers, and whether new controllers can be added at runtime. Such issues +can affect things including whether adjacent GPIO numbers are both valid. Using GPIOs ----------- @@ -158,10 +160,11 @@ and configure pullups/pulldowns appropriately.) Spinlock-Safe GPIO access ------------------------- Most GPIO controllers can be accessed with memory read/write instructions. -That doesn't need to sleep, and can safely be done from inside IRQ handlers. -(That includes hardirq contexts on RT kernels.) +Those don't need to sleep, and can safely be done from inside hard +(nonthreaded) IRQ handlers and similar contexts. -Use these calls to access such GPIOs: +Use the following calls to access such GPIOs, +for which gpio_cansleep() will always return false (see below): /* GPIO INPUT: return zero or nonzero */ int gpio_get_value(unsigned gpio); @@ -210,9 +213,31 @@ To access such GPIOs, a different set of accessors is defined: /* GPIO OUTPUT, might sleep */ void gpio_set_value_cansleep(unsigned gpio, int value); -Other than the fact that these calls might sleep, and will not be ignored -for GPIOs that can't be accessed from IRQ handlers, these calls act the -same as the spinlock-safe calls. + +Accessing such GPIOs requires a context which may sleep, for example +a threaded IRQ handler, and those accessors must be used instead of +spinlock-safe accessors without the cansleep() name suffix. + +Other than the fact that these accessors might sleep, and will work +on GPIOs that can't be accessed from hardIRQ handlers, these calls act +the same as the spinlock-safe calls. + + ** IN ADDITION ** calls to setup and configure such GPIOs must be made +from contexts which may sleep, since they may need to access the GPIO +controller chip too: (These setup calls are usually made from board +setup or driver probe/teardown code, so this is an easy constraint.) + + gpio_direction_input() + gpio_direction_output() + gpio_request() + +## gpio_request_one() +## gpio_request_array() +## gpio_free_array() + + gpio_free() + gpio_set_debounce() + Claiming and Releasing GPIOs @@ -457,12 +482,16 @@ To support this framework, a platform's Kconfig will "select" either ARCH_REQUIRE_GPIOLIB or ARCH_WANT_OPTIONAL_GPIOLIB and arrange that its <asm/gpio.h> includes <asm-generic/gpio.h> and defines three functions: gpio_get_value(), gpio_set_value(), and gpio_cansleep(). -They may also want to provide a custom value for ARCH_NR_GPIOS. -ARCH_REQUIRE_GPIOLIB means that the gpio-lib code will always get compiled +It may also provide a custom value for ARCH_NR_GPIOS, so that it better +reflects the number of GPIOs in actual use on that platform, without +wasting static table space. (It should count both built-in/SoC GPIOs and +also ones on GPIO expanders. + +ARCH_REQUIRE_GPIOLIB means that the gpiolib code will always get compiled into the kernel on that architecture. -ARCH_WANT_OPTIONAL_GPIOLIB means the gpio-lib code defaults to off and the user +ARCH_WANT_OPTIONAL_GPIOLIB means the gpiolib code defaults to off and the user can enable it and build it into the kernel optionally. If neither of these options are selected, the platform does not support diff --git a/Documentation/hwmon/adm1026 b/Documentation/hwmon/adm1026 index f4327db2307..d8fabe0c23a 100644 --- a/Documentation/hwmon/adm1026 +++ b/Documentation/hwmon/adm1026 @@ -6,7 +6,7 @@ Supported chips: Prefix: 'adm1026' Addresses scanned: I2C 0x2c, 0x2d, 0x2e Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/en/prod/0,,766_825_ADM1026,00.html + http://www.onsemi.com/PowerSolutions/product.do?id=ADM1026 Authors: Philip Pokorny <ppokorny@penguincomputing.com> for Penguin Computing diff --git a/Documentation/hwmon/coretemp b/Documentation/hwmon/coretemp index 92267b62db5..25568f84480 100644 --- a/Documentation/hwmon/coretemp +++ b/Documentation/hwmon/coretemp @@ -21,8 +21,8 @@ Temperature is measured in degrees Celsius and measurement resolution is 1 degree C. Valid temperatures are from 0 to TjMax degrees C, because the actual value of temperature register is in fact a delta from TjMax. -Temperature known as TjMax is the maximum junction temperature of processor. -Intel defines this temperature as 85C or 100C. At this temperature, protection +Temperature known as TjMax is the maximum junction temperature of processor, +which depends on the CPU model. See table below. At this temperature, protection mechanism will perform actions to forcibly cool down the processor. Alarm may be raised, if the temperature grows enough (more than TjMax) to trigger the Out-Of-Spec bit. Following table summarizes the exported sysfs files: @@ -38,3 +38,104 @@ temp1_label - Contains string "Core X", where X is processor The TjMax temperature is set to 85 degrees C if undocumented model specific register (UMSR) 0xee has bit 30 set. If not the TjMax is 100 degrees C as (sometimes) documented in processor datasheet. + +Appendix A. Known TjMax lists (TBD): +Some information comes from ark.intel.com + +Process Processor TjMax(C) + +32nm Core i3/i5/i7 Processors + i7 660UM/640/620, 640LM/620, 620M, 610E 105 + i5 540UM/520/430, 540M/520/450/430 105 + i3 330E, 370M/350/330 90 rPGA, 105 BGA + i3 330UM 105 + +32nm Core i7 Extreme Processors + 980X 100 + +32nm Celeron Processors + U3400 105 + P4505/P4500 90 + +45nm Xeon Processors 5400 Quad-Core + X5492, X5482, X5472, X5470, X5460, X5450 85 + E5472, E5462, E5450/40/30/20/10/05 85 + L5408 95 + L5430, L5420, L5410 70 + +45nm Xeon Processors 5200 Dual-Core + X5282, X5272, X5270, X5260 90 + E5240 90 + E5205, E5220 70, 90 + L5240 70 + L5238, L5215 95 + +45nm Atom Processors + D525/510/425/410 100 + Z560/550/540/530P/530/520PT/520/515/510PT/510P 90 + Z510/500 90 + N475/470/455/450 100 + N280/270 90 + 330/230 125 + +45nm Core2 Processors + Solo ULV SU3500/3300 100 + T9900/9800/9600/9550/9500/9400/9300/8300/8100 105 + T6670/6500/6400 105 + T6600 90 + SU9600/9400/9300 105 + SP9600/9400 105 + SL9600/9400/9380/9300 105 + P9700/9600/9500/8800/8700/8600/8400/7570 105 + P7550/7450 90 + +45nm Core2 Quad Processors + Q9100/9000 100 + +45nm Core2 Extreme Processors + X9100/9000 105 + QX9300 100 + +45nm Core i3/i5/i7 Processors + i7 940XM/920 100 + i7 840QM/820/740/720 100 + +45nm Celeron Processors + SU2300 100 + 900 105 + +65nm Core2 Duo Processors + Solo U2200, U2100 100 + U7700/7600/7500 100 + T7800/7700/7600/7500/7400/7300/7250/7200/7100 100 + T5870/5670/5600/5550/5500/5470/5450/5300/5270 100 + T5250 100 + T5800/5750/5200 85 + L7700/7500/7400/7300/7200 100 + +65nm Core2 Extreme Processors + X7900/7800 100 + +65nm Core Duo Processors + U2500/2400 100 + T2700/2600/2450/2400/2350/2300E/2300/2250/2050 100 + L2500/2400/2300 100 + +65nm Core Solo Processors + U1500/1400/1300 100 + T1400/1350/1300/1250 100 + +65nm Xeon Processors 5000 Quad-Core + X5000 90-95 + E5000 80 + L5000 70 + L5318 95 + +65nm Xeon Processors 5000 Dual-Core + 5080, 5063, 5060, 5050, 5030 80-90 + 5160, 5150, 5148, 5140, 5130, 5120, 5110 80 + L5138 100 + +65nm Celeron Processors + T1700/1600 100 + 560/550/540/530 100 diff --git a/Documentation/hwmon/emc2103 b/Documentation/hwmon/emc2103 new file mode 100644 index 00000000000..a12b2c12714 --- /dev/null +++ b/Documentation/hwmon/emc2103 @@ -0,0 +1,33 @@ +Kernel driver emc2103 +====================== + +Supported chips: + * SMSC EMC2103 + Addresses scanned: I2C 0x2e + Prefix: 'emc2103' + Datasheet: Not public + +Authors: + Steve Glendinning <steve.glendinning@smsc.com> + +Description +----------- + +The Standard Microsystems Corporation (SMSC) EMC2103 chips +contain up to 4 temperature sensors and a single fan controller. + +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 or 8) to give +the readings more range or accuracy. Not all RPM values can accurately be +represented, so some rounding is done. With a divider of 1, the lowest +representable value is 480 RPM. + +This driver supports RPM based control, to use this a fan target +should be written to fan1_target and pwm1_enable should be set to 3. + +The 2103-2 and 2103-4 variants have a third temperature sensor, which can +be connected to two anti-parallel diodes. These values can be read +as temp3 and temp4. If only one diode is attached to this channel, temp4 +will show as "fault". The module parameter "apd=0" can be used to suppress +this 4th channel when anti-parallel diodes are not fitted. diff --git a/Documentation/hwmon/g760a b/Documentation/hwmon/g760a index e032eeb7562..cfc89453706 100644 --- a/Documentation/hwmon/g760a +++ b/Documentation/hwmon/g760a @@ -5,7 +5,7 @@ Supported chips: * Global Mixed-mode Technology Inc. G760A Prefix: 'g760a' Datasheet: Publicly available at the GMT website - http://www.gmt.com.tw/datasheet/g760a.pdf + http://www.gmt.com.tw/product/datasheet/EDS-760A.pdf Author: Herbert Valerio Riedel <hvr@gnu.org> diff --git a/Documentation/hwmon/gl518sm b/Documentation/hwmon/gl518sm index 229f8b78918..26f9f3c02dc 100644 --- a/Documentation/hwmon/gl518sm +++ b/Documentation/hwmon/gl518sm @@ -5,11 +5,10 @@ Supported chips: * Genesys Logic GL518SM release 0x00 Prefix: 'gl518sm' Addresses scanned: I2C 0x2c and 0x2d - Datasheet: http://www.genesyslogic.com/pdf * Genesys Logic GL518SM release 0x80 Prefix: 'gl518sm' Addresses scanned: I2C 0x2c and 0x2d - Datasheet: http://www.genesyslogic.com/pdf + Datasheet: http://www.genesyslogic.com/ Authors: Frodo Looijaard <frodol@dds.nl>, diff --git a/Documentation/hwmon/hpfall.c b/Documentation/hwmon/hpfall.c index 681ec22b9d0..a4a8fc5d05d 100644 --- a/Documentation/hwmon/hpfall.c +++ b/Documentation/hwmon/hpfall.c @@ -1,7 +1,7 @@ /* Disk protection for HP machines. * * Copyright 2008 Eric Piel - * Copyright 2009 Pavel Machek <pavel@suse.cz> + * Copyright 2009 Pavel Machek <pavel@ucw.cz> * * GPLv2. */ diff --git a/Documentation/hwmon/it87 b/Documentation/hwmon/it87 index 8d08bf0d38e..38425f0f264 100644 --- a/Documentation/hwmon/it87 +++ b/Documentation/hwmon/it87 @@ -22,6 +22,10 @@ Supported chips: Prefix: 'it8720' Addresses scanned: from Super I/O config space (8 I/O ports) Datasheet: Not publicly available + * IT8721F/IT8758E + Prefix: 'it8721' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available * SiS950 [clone of IT8705F] Prefix: 'it87' Addresses scanned: from Super I/O config space (8 I/O ports) @@ -67,7 +71,7 @@ Description ----------- This driver implements support for the IT8705F, IT8712F, IT8716F, -IT8718F, IT8720F, IT8726F and SiS950 chips. +IT8718F, IT8720F, IT8721F, IT8726F, IT8758E and SiS950 chips. These chips are 'Super I/O chips', supporting floppy disks, infrared ports, joysticks and other miscellaneous stuff. For hardware monitoring, they @@ -86,14 +90,15 @@ the driver won't notice and report changes in the VID value. The two upper VID bits share their pins with voltage inputs (in5 and in6) so you can't have both on a given board. -The IT8716F, IT8718F, IT8720F and later IT8712F revisions have support for -2 additional fans. The additional fans are supported by the driver. +The IT8716F, IT8718F, IT8720F, IT8721F/IT8758E and later IT8712F revisions +have support for 2 additional fans. The additional fans are supported by the +driver. -The IT8716F, IT8718F and IT8720F, and late IT8712F and IT8705F also have -optional 16-bit tachometer counters for fans 1 to 3. This is better (no more -fan clock divider mess) but not compatible with the older chips and -revisions. The 16-bit tachometer mode is enabled by the driver when one -of the above chips is detected. +The IT8716F, IT8718F, IT8720F and IT8721F/IT8758E, and late IT8712F and +IT8705F also have optional 16-bit tachometer counters for fans 1 to 3. This +is better (no more fan clock divider mess) but not compatible with the older +chips and revisions. The 16-bit tachometer mode is enabled by the driver when +one of the above chips is detected. The IT8726F is just bit enhanced IT8716F with additional hardware for AMD power sequencing. Therefore the chip will appear as IT8716F @@ -115,7 +120,12 @@ alarm is triggered if the voltage has crossed a programmable minimum or maximum limit. Note that minimum in this case always means 'closest to zero'; this is important for negative voltage measurements. All voltage inputs can measure voltages between 0 and 4.08 volts, with a resolution of -0.016 volt. The battery voltage in8 does not have limit registers. +0.016 volt (except IT8721F/IT8758E: 0.012 volt.) The battery voltage in8 does +not have limit registers. + +On the IT8721F/IT8758E, some voltage inputs are internal and scaled inside +the chip (in7, in8 and optionally in3). The driver handles this transparently +so user-space doesn't have to care. The VID lines (IT8712F/IT8716F/IT8718F/IT8720F) encode the core voltage value: the voltage level your processor should work with. This is hardcoded by diff --git a/Documentation/hwmon/jc42 b/Documentation/hwmon/jc42 new file mode 100644 index 00000000000..0e76ef12e4c --- /dev/null +++ b/Documentation/hwmon/jc42 @@ -0,0 +1,97 @@ +Kernel driver jc42 +================== + +Supported chips: + * Analog Devices ADT7408 + Prefix: 'adt7408' + Addresses scanned: I2C 0x18 - 0x1f + Datasheets: + http://www.analog.com/static/imported-files/data_sheets/ADT7408.pdf + * IDT TSE2002B3, TS3000B3 + Prefix: 'tse2002b3', 'ts3000b3' + Addresses scanned: I2C 0x18 - 0x1f + Datasheets: + http://www.idt.com/products/getdoc.cfm?docid=18715691 + http://www.idt.com/products/getdoc.cfm?docid=18715692 + * Maxim MAX6604 + Prefix: 'max6604' + Addresses scanned: I2C 0x18 - 0x1f + Datasheets: + http://datasheets.maxim-ic.com/en/ds/MAX6604.pdf + * Microchip MCP9805, MCP98242, MCP98243, MCP9843 + Prefixes: 'mcp9805', 'mcp98242', 'mcp98243', 'mcp9843' + Addresses scanned: I2C 0x18 - 0x1f + Datasheets: + http://ww1.microchip.com/downloads/en/DeviceDoc/21977b.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/21996a.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/22153c.pdf + * NXP Semiconductors SE97, SE97B + Prefix: 'se97' + Addresses scanned: I2C 0x18 - 0x1f + Datasheets: + http://www.nxp.com/documents/data_sheet/SE97.pdf + http://www.nxp.com/documents/data_sheet/SE97B.pdf + * NXP Semiconductors SE98 + Prefix: 'se98' + Addresses scanned: I2C 0x18 - 0x1f + Datasheets: + http://www.nxp.com/documents/data_sheet/SE98.pdf + * ON Semiconductor CAT34TS02, CAT6095 + Prefix: 'cat34ts02', 'cat6095' + Addresses scanned: I2C 0x18 - 0x1f + Datasheet: + http://www.onsemi.com/pub_link/Collateral/CAT34TS02-D.PDF + http://www.onsemi.com/pub/Collateral/CAT6095-D.PDF + * ST Microelectronics STTS424, STTS424E02 + Prefix: 'stts424' + Addresses scanned: I2C 0x18 - 0x1f + Datasheets: + http://www.st.com/stonline/products/literature/ds/13447/stts424.pdf + http://www.st.com/stonline/products/literature/ds/13448/stts424e02.pdf + * JEDEC JC 42.4 compliant temperature sensor chips + Prefix: 'jc42' + Addresses scanned: I2C 0x18 - 0x1f + Datasheet: - + +Author: + Guenter Roeck <guenter.roeck@ericsson.com> + + +Description +----------- + +This driver implements support for JEDEC JC 42.4 compliant temperature sensors. +The driver auto-detects the chips listed above, but can be manually instantiated +to support other JC 42.4 compliant chips. + +Example: the following will load the driver for a generic JC 42.4 compliant +temperature sensor at address 0x18 on I2C bus #1: + +# modprobe jc42 +# echo jc42 0x18 > /sys/bus/i2c/devices/i2c-1/new_device + +A JC 42.4 compliant chip supports a single temperature sensor. Minimum, maximum, +and critical temperature can be configured. There are alarms for high, low, +and critical thresholds. + +There is also an hysteresis to control the thresholds for resetting alarms. +Per JC 42.4 specification, the hysteresis threshold can be configured to 0, 1.5, +3.0, and 6.0 degrees C. Configured hysteresis values will be rounded to those +limits. The chip supports only a single register to configure the hysteresis, +which applies to all limits. This register can be written by writing into +temp1_crit_hyst. Other hysteresis attributes are read-only. + +Sysfs entries +------------- + +temp1_input Temperature (RO) +temp1_min Minimum temperature (RW) +temp1_max Maximum temperature (RW) +temp1_crit Critical high temperature (RW) + +temp1_crit_hyst Critical hysteresis temperature (RW) +temp1_max_hyst Maximum hysteresis temperature (RO) + +temp1_min_alarm Temperature low alarm +temp1_max_alarm Temperature high alarm +temp1_crit_alarm Temperature critical alarm diff --git a/Documentation/hwmon/k8temp b/Documentation/hwmon/k8temp index 0005c716614..716dc24c723 100644 --- a/Documentation/hwmon/k8temp +++ b/Documentation/hwmon/k8temp @@ -5,7 +5,7 @@ Supported chips: * AMD Athlon64/FX or Opteron CPUs Prefix: 'k8temp' Addresses scanned: PCI space - Datasheet: http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/32559.pdf + Datasheet: http://support.amd.com/us/Processor_TechDocs/32559.pdf Author: Rudolf Marek Contact: Rudolf Marek <r.marek@assembler.cz> diff --git a/Documentation/hwmon/lm85 b/Documentation/hwmon/lm85 index a76aefeeb68..239258a63c8 100644 --- a/Documentation/hwmon/lm85 +++ b/Documentation/hwmon/lm85 @@ -9,15 +9,19 @@ Supported chips: * Analog Devices ADM1027 Prefix: 'adm1027' Addresses scanned: I2C 0x2c, 0x2d, 0x2e - Datasheet: http://www.analog.com/en/prod/0,,766_825_ADM1027,00.html + Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADM1027 * Analog Devices ADT7463 Prefix: 'adt7463' Addresses scanned: I2C 0x2c, 0x2d, 0x2e - Datasheet: http://www.analog.com/en/prod/0,,766_825_ADT7463,00.html + Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7463 + * Analog Devices ADT7468 + Prefix: 'adt7468' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7468 * SMSC EMC6D100, SMSC EMC6D101 Prefix: 'emc6d100' Addresses scanned: I2C 0x2c, 0x2d, 0x2e - Datasheet: http://www.smsc.com/main/tools/discontinued/6d100.pdf + Datasheet: http://www.smsc.com/media/Downloads_Public/discontinued/6d100.pdf * SMSC EMC6D102 Prefix: 'emc6d102' Addresses scanned: I2C 0x2c, 0x2d, 0x2e @@ -34,7 +38,7 @@ Description ----------- This driver implements support for the National Semiconductor LM85 and -compatible chips including the Analog Devices ADM1027, ADT7463 and +compatible chips including the Analog Devices ADM1027, ADT7463, ADT7468 and SMSC EMC6D10x chips family. The LM85 uses the 2-wire interface compatible with the SMBUS 2.0 @@ -87,14 +91,22 @@ To smooth the response of fans to changes in temperature, the LM85 has an optional filter for smoothing temperatures. The ADM1027 has the same config option but uses it to rate limit the changes to fan speed instead. -The ADM1027 and ADT7463 have a 10-bit ADC and can therefore measure -temperatures with 0.25 degC resolution. They also provide an offset to the -temperature readings that is automatically applied during measurement. -This offset can be used to zero out any errors due to traces and placement. -The documentation says that the offset is in 0.25 degC steps, but in -initial testing of the ADM1027 it was 1.00 degC steps. Analog Devices has -confirmed this "bug". The ADT7463 is reported to work as described in the -documentation. The current lm85 driver does not show the offset register. +The ADM1027, ADT7463 and ADT7468 have a 10-bit ADC and can therefore +measure temperatures with 0.25 degC resolution. They also provide an offset +to the temperature readings that is automatically applied during +measurement. This offset can be used to zero out any errors due to traces +and placement. The documentation says that the offset is in 0.25 degC +steps, but in initial testing of the ADM1027 it was 1.00 degC steps. Analog +Devices has confirmed this "bug". The ADT7463 is reported to work as +described in the documentation. The current lm85 driver does not show the +offset register. + +The ADT7468 has a high-frequency PWM mode, where all PWM outputs are +driven by a 22.5 kHz clock. This is a global mode, not per-PWM output, +which means that setting any PWM frequency above 11.3 kHz will switch +all 3 PWM outputs to a 22.5 kHz frequency. Conversely, setting any PWM +frequency below 11.3 kHz will switch all 3 PWM outputs to a frequency +between 10 and 100 Hz, which can then be tuned separately. See the vendor datasheets for more information. There is application note from National (AN-1260) with some additional information about the LM85. @@ -125,17 +137,17 @@ datasheet for a complete description of the differences. Other than identifying the chip, the driver behaves no differently with regard to these two chips. The LM85B is recommended for new designs. -The ADM1027 and ADT7463 chips have an optional SMBALERT output that can be -used to signal the chipset in case a limit is exceeded or the temperature -sensors fail. Individual sensor interrupts can be masked so they won't -trigger SMBALERT. The SMBALERT output if configured replaces one of the other -functions (PWM2 or IN0). This functionality is not implemented in current -driver. +The ADM1027, ADT7463 and ADT7468 chips have an optional SMBALERT output +that can be used to signal the chipset in case a limit is exceeded or the +temperature sensors fail. Individual sensor interrupts can be masked so +they won't trigger SMBALERT. The SMBALERT output if configured replaces one +of the other functions (PWM2 or IN0). This functionality is not implemented +in current driver. -The ADT7463 also has an optional THERM output/input which can be connected -to the processor PROC_HOT output. If available, the autofan control -dynamic Tmin feature can be enabled to keep the system temperature within -spec (just?!) with the least possible fan noise. +The ADT7463 and ADT7468 also have an optional THERM output/input which can +be connected to the processor PROC_HOT output. If available, the autofan +control dynamic Tmin feature can be enabled to keep the system temperature +within spec (just?!) with the least possible fan noise. Configuration Notes ------------------- @@ -201,8 +213,8 @@ the temperatures to compensate for systemic errors in the measurements. These features are not currently supported by the lm85 driver. -In addition to the ADM1027 features, the ADT7463 also has Tmin control -and THERM asserted counts. Automatic Tmin control acts to adjust the -Tmin value to maintain the measured temperature sensor at a specified -temperature. There isn't much documentation on this feature in the -ADT7463 data sheet. This is not supported by current driver. +In addition to the ADM1027 features, the ADT7463 and ADT7468 also have +Tmin control and THERM asserted counts. Automatic Tmin control acts to +adjust the Tmin value to maintain the measured temperature sensor at a +specified temperature. There isn't much documentation on this feature in +the ADT7463 data sheet. This is not supported by current driver. diff --git a/Documentation/hwmon/lm90 b/Documentation/hwmon/lm90 index 6a03dd4bcc9..fa475c0a48a 100644 --- a/Documentation/hwmon/lm90 +++ b/Documentation/hwmon/lm90 @@ -63,8 +63,8 @@ Supported chips: Datasheet: Publicly available at the Maxim website http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578 * Maxim MAX6659 - Prefix: 'max6657' - Addresses scanned: I2C 0x4c, 0x4d (unsupported 0x4e) + Prefix: 'max6659' + Addresses scanned: I2C 0x4c, 0x4d, 0x4e Datasheet: Publicly available at the Maxim website http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578 * Maxim MAX6680 @@ -84,6 +84,21 @@ Supported chips: Addresses scanned: I2C 0x4c Datasheet: Publicly available at the Maxim website http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3500 + * Maxim MAX6695 + Prefix: 'max6695' + Addresses scanned: I2C 0x18 + Datasheet: Publicly available at the Maxim website + http://www.maxim-ic.com/datasheet/index.mvp/id/4199 + * Maxim MAX6696 + Prefix: 'max6695' + Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b, + 0x4c, 0x4d and 0x4e + Datasheet: Publicly available at the Maxim website + http://www.maxim-ic.com/datasheet/index.mvp/id/4199 + * Winbond/Nuvoton W83L771W/G + Prefix: 'w83l771' + Addresses scanned: I2C 0x4c + Datasheet: No longer available * Winbond/Nuvoton W83L771AWG/ASG Prefix: 'w83l771' Addresses scanned: I2C 0x4c @@ -101,10 +116,11 @@ well as the temperature of up to one external diode. It is compatible 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. +MAX6658 and MAX6659 variants. The extra features of the MAX6659 are only +supported by this driver if the chip is located at address 0x4d or 0x4e, +or if the chip type is explicitly selected as max6659. +The MAX6680 and MAX6681 only differ in their pinout, therefore they obviously +can't (and don't need to) be distinguished. The specificity of this family of chipsets over the ADM1021/LM84 family is that it features critical limits with hysteresis, and an @@ -151,11 +167,21 @@ MAX6680 and MAX6681: * Selectable address * Remote sensor type selection +MAX6695 and MAX6696: + * Better local resolution + * Selectable address (max6696) + * Second critical temperature limit + * Two remote sensors + +W83L771W/G + * The G variant is lead-free, otherwise similar to the W. + * Filter and alert configuration register at 0xBF + * Moving average (depending on conversion rate) + W83L771AWG/ASG + * Successor of the W83L771W/G, same features. * The AWG and ASG variants only differ in package format. - * Filter and alert configuration register at 0xBF * Diode ideality factor configuration (remote sensor) at 0xE3 - * Moving average (depending on conversion rate) All temperature values are given in degrees Celsius. Resolution is 1.0 degree for the local temperature, 0.125 degree for the remote diff --git a/Documentation/hwmon/ltc4245 b/Documentation/hwmon/ltc4245 index 86b5880d850..b478b086496 100644 --- a/Documentation/hwmon/ltc4245 +++ b/Documentation/hwmon/ltc4245 @@ -72,9 +72,31 @@ in6_min_alarm 5v output undervoltage alarm in7_min_alarm 3v output undervoltage alarm in8_min_alarm Vee (-12v) output undervoltage alarm -in9_input GPIO voltage data +in9_input GPIO voltage data (see note 1) +in10_input GPIO voltage data (see note 1) +in11_input GPIO voltage data (see note 1) power1_input 12v power usage (mW) power2_input 5v power usage (mW) power3_input 3v power usage (mW) power4_input Vee (-12v) power usage (mW) + + +Note 1 +------ + +If you have NOT configured the driver to sample all GPIO pins as analog +voltages, then the in10_input and in11_input sysfs attributes will not be +created. The driver will sample the GPIO pin that is currently connected to the +ADC as an analog voltage, and report the value in in9_input. + +If you have configured the driver to sample all GPIO pins as analog voltages, +then they will be sampled in round-robin fashion. If userspace reads too +slowly, -EAGAIN will be returned when you read the sysfs attribute containing +the sensor reading. + +The LTC4245 chip can be configured to sample all GPIO pins with two methods: +1) platform data -- see include/linux/i2c/ltc4245.h +2) OF device tree -- add the "ltc4245,use-extra-gpios" property to each chip + +The default mode of operation is to sample a single GPIO pin. diff --git a/Documentation/hwmon/ltc4261 b/Documentation/hwmon/ltc4261 new file mode 100644 index 00000000000..eba2e2c4b94 --- /dev/null +++ b/Documentation/hwmon/ltc4261 @@ -0,0 +1,63 @@ +Kernel driver ltc4261 +===================== + +Supported chips: + * Linear Technology LTC4261 + Prefix: 'ltc4261' + Addresses scanned: - + Datasheet: + http://cds.linear.com/docs/Datasheet/42612fb.pdf + +Author: Guenter Roeck <guenter.roeck@ericsson.com> + + +Description +----------- + +The LTC4261/LTC4261-2 negative voltage Hot Swap controllers allow a board +to be safely inserted and removed from a live backplane. + + +Usage Notes +----------- + +This driver does not probe for LTC4261 devices, since there is no register +which can be safely used to identify the chip. You will have to instantiate +the devices explicitly. + +Example: the following will load the driver for an LTC4261 at address 0x10 +on I2C bus #1: +$ modprobe ltc4261 +$ echo ltc4261 0x10 > /sys/bus/i2c/devices/i2c-1/new_device + + +Sysfs entries +------------- + +Voltage readings provided by this driver are reported as obtained from the ADC +registers. If a set of voltage divider resistors is installed, calculate the +real voltage by multiplying the reported value with (R1+R2)/R2, where R1 is the +value of the divider resistor against the measured voltage and R2 is the value +of the divider resistor against Ground. + +Current reading provided by this driver is reported as obtained from the ADC +Current Sense register. The reported value assumes that a 1 mOhm sense resistor +is installed. If a different sense resistor is installed, calculate the real +current by dividing the reported value by the sense resistor value in mOhm. + +The chip has two voltage sensors, but only one set of voltage alarm status bits. +In many many designs, those alarms are associated with the ADIN2 sensor, due to +the proximity of the ADIN2 pin to the OV pin. ADIN2 is, however, not available +on all chip variants. To ensure that the alarm condition is reported to the user, +report it with both voltage sensors. + +in1_input ADIN2 voltage (mV) +in1_min_alarm ADIN/ADIN2 Undervoltage alarm +in1_max_alarm ADIN/ADIN2 Overvoltage alarm + +in2_input ADIN voltage (mV) +in2_min_alarm ADIN/ADIN2 Undervoltage alarm +in2_max_alarm ADIN/ADIN2 Overvoltage alarm + +curr1_input SENSE current (mA) +curr1_alarm SENSE overcurrent alarm diff --git a/Documentation/hwmon/pc87427 b/Documentation/hwmon/pc87427 index db5cc1227a8..8fdd08c9e48 100644 --- a/Documentation/hwmon/pc87427 +++ b/Documentation/hwmon/pc87427 @@ -18,10 +18,11 @@ Description The National Semiconductor Super I/O chip includes complete hardware monitoring capabilities. It can monitor up to 18 voltages, 8 fans and -6 temperature sensors. Only the fans are supported at the moment. +6 temperature sensors. Only the fans and temperatures are supported at +the moment, voltages aren't. -This chip also has fan controlling features, which are not yet supported -by this driver either. +This chip also has fan controlling features (up to 4 PWM outputs), +which are partly supported by this driver. The driver assumes that no more than one chip is present, which seems reasonable. @@ -36,3 +37,23 @@ signal. Speeds down to 83 RPM can be measured. An alarm is triggered if the rotation speed drops below a programmable limit. Another alarm is triggered if the speed is too low to be measured (including stalled or missing fan). + + +Fan Speed Control +----------------- + +Fan speed can be controlled by PWM outputs. There are 4 possible modes: +always off, always on, manual and automatic. The latter isn't supported +by the driver: you can only return to that mode if it was the original +setting, and the configuration interface is missing. + + +Temperature Monitoring +---------------------- + +The PC87427 relies on external sensors (following the SensorPath +standard), so the resolution and range depend on the type of sensor +connected. The integer part can be 8-bit or 9-bit, and can be signed or +not. I couldn't find a way to figure out the external sensor data +temperature format, so user-space adjustment (typically by a factor 2) +may be required. diff --git a/Documentation/hwmon/pcf8591 b/Documentation/hwmon/pcf8591 index e76a7892f68..ac020b3bb7b 100644 --- a/Documentation/hwmon/pcf8591 +++ b/Documentation/hwmon/pcf8591 @@ -4,7 +4,7 @@ Kernel driver pcf8591 Supported chips: * Philips/NXP PCF8591 Prefix: 'pcf8591' - Addresses scanned: I2C 0x48 - 0x4f + Addresses scanned: none Datasheet: Publicly available at the NXP website http://www.nxp.com/pip/PCF8591_6.html @@ -58,18 +58,16 @@ Module parameters Accessing PCF8591 via /sys interface ------------------------------------- -! Be careful ! -The PCF8591 is plainly impossible to detect! Stupid chip. -So every chip with address in the interval [0x48..0x4f] is -detected as PCF8591. If you have other chips in this address -range, the workaround is to load this module after the one -for your others chips. +The PCF8591 is plainly impossible to detect! Thus the driver won't even +try. You have to explicitly instantiate the device at the relevant +address (in the interval [0x48..0x4f]) either through platform data, or +using the sysfs interface. See Documentation/i2c/instantiating-devices +for details. -On detection (i.e. insmod, modprobe et al.), directories are being -created for each detected PCF8591: +Directories are being created for each instantiated PCF8591: /sys/bus/i2c/devices/<0>-<1>/ -where <0> is the bus the chip was detected on (e. g. i2c-0) +where <0> is the bus the chip is connected to (e. g. i2c-0) and <1> the chip address ([48..4f]) Inside these directories, there are such files: diff --git a/Documentation/hwmon/pkgtemp b/Documentation/hwmon/pkgtemp new file mode 100644 index 00000000000..c8e1fb0fadd --- /dev/null +++ b/Documentation/hwmon/pkgtemp @@ -0,0 +1,36 @@ +Kernel driver pkgtemp +====================== + +Supported chips: + * Intel family + Prefix: 'pkgtemp' + CPUID: + Datasheet: Intel 64 and IA-32 Architectures Software Developer's Manual + Volume 3A: System Programming Guide + +Author: Fenghua Yu + +Description +----------- + +This driver permits reading package level temperature sensor embedded inside +Intel CPU package. The sensors can be in core, uncore, memory controller, or +other components in a package. The feature is first implemented in Intel Sandy +Bridge platform. + +Temperature is measured in degrees Celsius and measurement resolution is +1 degree C. Valid temperatures are from 0 to TjMax degrees C, because the actual +value of temperature register is in fact a delta from TjMax. + +Temperature known as TjMax is the maximum junction temperature of package. +We get this from MSR_IA32_TEMPERATURE_TARGET. If the MSR is not accessible, +we define TjMax as 100 degrees Celsius. At this temperature, protection +mechanism will perform actions to forcibly cool down the package. Alarm +may be raised, if the temperature grows enough (more than TjMax) to trigger +the Out-Of-Spec bit. Following table summarizes the exported sysfs files: + +temp1_input - Package temperature (in millidegrees Celsius). +temp1_max - All cooling devices should be turned on. +temp1_crit - Maximum junction temperature (in millidegrees Celsius). +temp1_crit_alarm - Set when Out-of-spec bit is set, never clears. + Correct CPU operation is no longer guaranteed. diff --git a/Documentation/hwmon/smm665 b/Documentation/hwmon/smm665 new file mode 100644 index 00000000000..3820fc9ca52 --- /dev/null +++ b/Documentation/hwmon/smm665 @@ -0,0 +1,157 @@ +Kernel driver smm665 +==================== + +Supported chips: + * Summit Microelectronics SMM465 + Prefix: 'smm465' + Addresses scanned: - + Datasheet: + http://www.summitmicro.com/prod_select/summary/SMM465/SMM465DS.pdf + * Summit Microelectronics SMM665, SMM665B + Prefix: 'smm665' + Addresses scanned: - + Datasheet: + http://www.summitmicro.com/prod_select/summary/SMM665/SMM665B_2089_20.pdf + * Summit Microelectronics SMM665C + Prefix: 'smm665c' + Addresses scanned: - + Datasheet: + http://www.summitmicro.com/prod_select/summary/SMM665C/SMM665C_2125.pdf + * Summit Microelectronics SMM764 + Prefix: 'smm764' + Addresses scanned: - + Datasheet: + http://www.summitmicro.com/prod_select/summary/SMM764/SMM764_2098.pdf + * Summit Microelectronics SMM766, SMM766B + Prefix: 'smm766' + Addresses scanned: - + Datasheets: + http://www.summitmicro.com/prod_select/summary/SMM766/SMM766_2086.pdf + http://www.summitmicro.com/prod_select/summary/SMM766B/SMM766B_2122.pdf + +Author: Guenter Roeck <guenter.roeck@ericsson.com> + + +Module Parameters +----------------- + +* vref: int + Default: 1250 (mV) + Reference voltage on VREF_ADC pin in mV. It should not be necessary to set + this parameter unless a non-default reference voltage is used. + + +Description +----------- + +[From datasheet] The SMM665 is an Active DC Output power supply Controller +that monitors, margins and cascade sequences power. The part monitors six +power supply channels as well as VDD, 12V input, two general-purpose analog +inputs and an internal temperature sensor using a 10-bit ADC. + +Each monitored channel has its own high and low limits, plus a critical +limit. + +Support for SMM465, SMM764, and SMM766 has been implemented but is untested. + + +Usage Notes +----------- + +This driver does not probe for devices, since there is no register which +can be safely used to identify the chip. You will have to instantiate +the devices explicitly. When instantiating the device, you have to specify +its configuration register address. + +Example: the following will load the driver for an SMM665 at address 0x57 +on I2C bus #1: +$ modprobe smm665 +$ echo smm665 0x57 > /sys/bus/i2c/devices/i2c-1/new_device + + +Sysfs entries +------------- + +This driver uses the values in the datasheet to convert ADC register values +into the values specified in the sysfs-interface document. All attributes are +read only. + +Min, max, lcrit, and crit values are used by the chip to trigger external signals +and/or other activity. Triggered signals can include HEALTHY, RST, Power Off, +or Fault depending on the chip configuration. The driver reports values as lcrit +or crit if exceeding the limits triggers RST, Power Off, or Fault, and as min or +max otherwise. For details please see the SMM665 datasheet. + +For SMM465 and SMM764, values for Channel E and F are reported but undefined. + +in1_input 12V input voltage (mV) +in2_input 3.3V (VDD) input voltage (mV) +in3_input Channel A voltage (mV) +in4_input Channel B voltage (mV) +in5_input Channel C voltage (mV) +in6_input Channel D voltage (mV) +in7_input Channel E voltage (mV) +in8_input Channel F voltage (mV) +in9_input AIN1 voltage (mV) +in10_input AIN2 voltage (mV) + +in1_min 12v input minimum voltage (mV) +in2_min 3.3V (VDD) input minimum voltage (mV) +in3_min Channel A minimum voltage (mV) +in4_min Channel B minimum voltage (mV) +in5_min Channel C minimum voltage (mV) +in6_min Channel D minimum voltage (mV) +in7_min Channel E minimum voltage (mV) +in8_min Channel F minimum voltage (mV) +in9_min AIN1 minimum voltage (mV) +in10_min AIN2 minimum voltage (mV) + +in1_max 12v input maximum voltage (mV) +in2_max 3.3V (VDD) input maximum voltage (mV) +in3_max Channel A maximum voltage (mV) +in4_max Channel B maximum voltage (mV) +in5_max Channel C maximum voltage (mV) +in6_max Channel D maximum voltage (mV) +in7_max Channel E maximum voltage (mV) +in8_max Channel F maximum voltage (mV) +in9_max AIN1 maximum voltage (mV) +in10_max AIN2 maximum voltage (mV) + +in1_lcrit 12v input critical minimum voltage (mV) +in2_lcrit 3.3V (VDD) input critical minimum voltage (mV) +in3_lcrit Channel A critical minimum voltage (mV) +in4_lcrit Channel B critical minimum voltage (mV) +in5_lcrit Channel C critical minimum voltage (mV) +in6_lcrit Channel D critical minimum voltage (mV) +in7_lcrit Channel E critical minimum voltage (mV) +in8_lcrit Channel F critical minimum voltage (mV) +in9_lcrit AIN1 critical minimum voltage (mV) +in10_lcrit AIN2 critical minimum voltage (mV) + +in1_crit 12v input critical maximum voltage (mV) +in2_crit 3.3V (VDD) input critical maximum voltage (mV) +in3_crit Channel A critical maximum voltage (mV) +in4_crit Channel B critical maximum voltage (mV) +in5_crit Channel C critical maximum voltage (mV) +in6_crit Channel D critical maximum voltage (mV) +in7_crit Channel E critical maximum voltage (mV) +in8_crit Channel F critical maximum voltage (mV) +in9_crit AIN1 critical maximum voltage (mV) +in10_crit AIN2 critical maximum voltage (mV) + +in1_crit_alarm 12v input critical alarm +in2_crit_alarm 3.3V (VDD) input critical alarm +in3_crit_alarm Channel A critical alarm +in4_crit_alarm Channel B critical alarm +in5_crit_alarm Channel C critical alarm +in6_crit_alarm Channel D critical alarm +in7_crit_alarm Channel E critical alarm +in8_crit_alarm Channel F critical alarm +in9_crit_alarm AIN1 critical alarm +in10_crit_alarm AIN2 critical alarm + +temp1_input Chip tempererature +temp1_min Mimimum chip tempererature +temp1_max Maximum chip tempererature +temp1_crit Critical chip tempererature +temp1_crit_alarm Temperature critical alarm diff --git a/Documentation/hwmon/smsc47m1 b/Documentation/hwmon/smsc47m1 index 42c8431b3c9..2a13378dcf2 100644 --- a/Documentation/hwmon/smsc47m1 +++ b/Documentation/hwmon/smsc47m1 @@ -7,13 +7,10 @@ Supported chips: Addresses scanned: none, address read from Super I/O config space Prefix: 'smsc47m1' Datasheets: - http://www.smsc.com/main/datasheets/47b27x.pdf - http://www.smsc.com/main/datasheets/47m10x.pdf - http://www.smsc.com/main/datasheets/47m112.pdf - http://www.smsc.com/main/tools/discontinued/47m13x.pdf - http://www.smsc.com/main/datasheets/47m14x.pdf - http://www.smsc.com/main/tools/discontinued/47m15x.pdf - http://www.smsc.com/main/datasheets/47m192.pdf + http://www.smsc.com/media/Downloads_Public/Data_Sheets/47b272.pdf + http://www.smsc.com/media/Downloads_Public/Data_Sheets/47m10x.pdf + http://www.smsc.com/media/Downloads_Public/Data_Sheets/47m112.pdf + http://www.smsc.com/ * SMSC LPC47M292 Addresses scanned: none, address read from Super I/O config space Prefix: 'smsc47m2' diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface index d4e2917c6f1..64569901055 100644 --- a/Documentation/hwmon/sysfs-interface +++ b/Documentation/hwmon/sysfs-interface @@ -91,12 +91,11 @@ name The chip name. I2C devices get this attribute created automatically. RO -update_rate The rate at which the chip will update readings. +update_interval The interval at which the chip will update readings. Unit: millisecond RW - Some devices have a variable update rate. This attribute - can be used to change the update rate to the desired - frequency. + Some devices have a variable update rate or interval. + This attribute can be used to change it to the desired value. ************ @@ -107,10 +106,24 @@ in[0-*]_min Voltage min value. Unit: millivolt RW +in[0-*]_lcrit Voltage critical min value. + Unit: millivolt + RW + If voltage drops to or below this limit, the system may + take drastic action such as power down or reset. At the very + least, it should report a fault. + in[0-*]_max Voltage max value. Unit: millivolt RW +in[0-*]_crit Voltage critical max value. + Unit: millivolt + RW + If voltage reaches or exceeds this limit, the system may + take drastic action such as power down or reset. At the very + least, it should report a fault. + in[0-*]_input Voltage input value. Unit: millivolt RO @@ -284,7 +297,7 @@ temp[1-*]_input Temperature input value. Unit: millidegree Celsius RO -temp[1-*]_crit Temperature critical value, typically greater than +temp[1-*]_crit Temperature critical max value, typically greater than corresponding temp_max values. Unit: millidegree Celsius RW @@ -296,6 +309,25 @@ temp[1-*]_crit_hyst from the critical value. RW +temp[1-*]_emergency + Temperature emergency max value, for chips supporting more than + two upper temperature limits. Must be equal or greater than + corresponding temp_crit values. + Unit: millidegree Celsius + RW + +temp[1-*]_emergency_hyst + Temperature hysteresis value for emergency limit. + Unit: millidegree Celsius + Must be reported as an absolute temperature, NOT a delta + from the emergency value. + RW + +temp[1-*]_lcrit Temperature critical min value, typically lower than + corresponding temp_min values. + Unit: millidegree Celsius + RW + temp[1-*]_offset Temperature offset which is added to the temperature reading by the chip. @@ -344,9 +376,6 @@ Also see the Alarms section for status flags associated with temperatures. * Currents * ************ -Note that no known chip provides current measurements as of writing, -so this part is theoretical, so to say. - curr[1-*]_max Current max value Unit: milliampere RW @@ -471,6 +500,7 @@ limit-related alarms, not both. The driver should just reflect the hardware implementation. in[0-*]_alarm +curr[1-*]_alarm fan[1-*]_alarm temp[1-*]_alarm Channel alarm @@ -482,11 +512,14 @@ OR in[0-*]_min_alarm in[0-*]_max_alarm +curr[1-*]_min_alarm +curr[1-*]_max_alarm fan[1-*]_min_alarm fan[1-*]_max_alarm temp[1-*]_min_alarm temp[1-*]_max_alarm temp[1-*]_crit_alarm +temp[1-*]_emergency_alarm Limit alarm 0: no alarm 1: alarm @@ -497,7 +530,6 @@ to notify open diodes, unconnected fans etc. where the hardware supports it. When this boolean has value 1, the measurement for that channel should not be trusted. -in[0-*]_fault fan[1-*]_fault temp[1-*]_fault Input fault condition @@ -513,6 +545,7 @@ beep_enable Master beep enable RW in[0-*]_beep +curr[1-*]_beep fan[1-*]_beep temp[1-*]_beep Channel beep diff --git a/Documentation/hwmon/thmc50 b/Documentation/hwmon/thmc50 index 9639ca93d55..8a7772ade8d 100644 --- a/Documentation/hwmon/thmc50 +++ b/Documentation/hwmon/thmc50 @@ -9,7 +9,7 @@ Supported chips: * Texas Instruments THMC50 Prefix: 'thmc50' Addresses scanned: I2C 0x2c - 0x2e - Datasheet: http://focus.ti.com/docs/prod/folders/print/thmc50.html + Datasheet: http://www.ti.com/ Author: Krzysztof Helt <krzysztof.h1@wp.pl> diff --git a/Documentation/hwmon/via686a b/Documentation/hwmon/via686a index d651b25f751..e5f90ab5c48 100644 --- a/Documentation/hwmon/via686a +++ b/Documentation/hwmon/via686a @@ -5,7 +5,7 @@ Supported chips: * Via VT82C686A, VT82C686B Southbridge Integrated Hardware Monitor Prefix: 'via686a' Addresses scanned: ISA in PCI-space encoded address - Datasheet: On request through web form (http://www.via.com.tw/en/support/datasheets/) + Datasheet: On request through web form (http://www.via.com.tw/en/resources/download-center/) Authors: Kyösti Mälkki <kmalkki@cc.hut.fi>, diff --git a/Documentation/hwmon/w83627ehf b/Documentation/hwmon/w83627ehf index b7e42ec4b26..13d556112fc 100644 --- a/Documentation/hwmon/w83627ehf +++ b/Documentation/hwmon/w83627ehf @@ -20,6 +20,10 @@ Supported chips: Prefix: 'w83667hg' Addresses scanned: ISA address retrieved from Super I/O registers Datasheet: not available + * Winbond W83667HG-B + Prefix: 'w83667hg' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request Authors: Jean Delvare <khali@linux-fr.org> @@ -32,8 +36,8 @@ Description ----------- This driver implements support for the Winbond W83627EHF, W83627EHG, -W83627DHG, W83627DHG-P and W83667HG super I/O chips. We will refer to them -collectively as Winbond chips. +W83627DHG, W83627DHG-P, W83667HG and W83667HG-B super I/O chips. +We will refer to them collectively as Winbond chips. The chips implement three temperature sensors, five fan rotation speed sensors, ten analog voltage sensors (only nine for the 627DHG), one @@ -68,14 +72,15 @@ follows: temp1 -> pwm1 temp2 -> pwm2 temp3 -> pwm3 -prog -> pwm4 (not on 667HG; the programmable setting is not supported by - the driver) +prog -> pwm4 (not on 667HG and 667HG-B; the programmable setting is not + supported by the driver) /sys files ---------- name - this is a standard hwmon device entry. For the W83627EHF and W83627EHG, - it is set to "w83627ehf" and for the W83627DHG it is set to "w83627dhg" + it is set to "w83627ehf", for the W83627DHG it is set to "w83627dhg", + and for the W83667HG it is set to "w83667hg". pwm[1-4] - this file stores PWM duty cycle or DC value (fan speed) in range: 0 (stop) to 255 (full) diff --git a/Documentation/hwmon/w83627hf b/Documentation/hwmon/w83627hf index 44dd2bcc72b..fb145e5e722 100644 --- a/Documentation/hwmon/w83627hf +++ b/Documentation/hwmon/w83627hf @@ -5,23 +5,19 @@ Supported chips: * Winbond W83627HF (ISA accesses ONLY) Prefix: 'w83627hf' Addresses scanned: ISA address retrieved from Super I/O registers - Datasheet: http://www.winbond.com/PDF/sheet/w83627hf.pdf * Winbond W83627THF Prefix: 'w83627thf' Addresses scanned: ISA address retrieved from Super I/O registers - Datasheet: http://www.winbond.com/PDF/sheet/w83627thf.pdf * Winbond W83697HF Prefix: 'w83697hf' Addresses scanned: ISA address retrieved from Super I/O registers - Datasheet: http://www.winbond.com/PDF/sheet/697hf.pdf * Winbond W83637HF Prefix: 'w83637hf' Addresses scanned: ISA address retrieved from Super I/O registers - Datasheet: http://www.winbond.com/PDF/sheet/w83637hf.pdf * Winbond W83687THF Prefix: 'w83687thf' Addresses scanned: ISA address retrieved from Super I/O registers - Datasheet: Provided by Winbond on request + Datasheet: Provided by Winbond on request(http://www.winbond.com/hq/enu) Authors: Frodo Looijaard <frodol@dds.nl>, diff --git a/Documentation/hwmon/w83781d b/Documentation/hwmon/w83781d index c91e0b63ea1..ecbc1e4574b 100644 --- a/Documentation/hwmon/w83781d +++ b/Documentation/hwmon/w83781d @@ -9,7 +9,7 @@ Supported chips: * Winbond W83782D Prefix: 'w83782d' Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports) - Datasheet: http://www.winbond.com/PDF/sheet/w83782d.pdf + Datasheet: http://www.winbond.com * Winbond W83783S Prefix: 'w83783s' Addresses scanned: I2C 0x2d diff --git a/Documentation/hwmon/w83792d b/Documentation/hwmon/w83792d index 14a668ed8aa..8a023ce0b72 100644 --- a/Documentation/hwmon/w83792d +++ b/Documentation/hwmon/w83792d @@ -5,7 +5,7 @@ Supported chips: * Winbond W83792D Prefix: 'w83792d' Addresses scanned: I2C 0x2c - 0x2f - Datasheet: http://www.winbond.com.tw/E-WINBONDHTM/partner/PDFresult.asp?Pname=1035 + Datasheet: http://www.winbond.com.tw Author: Chunhao Huang Contact: DZShen <DZShen@Winbond.com.tw> diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535 index acbc65a0809..5d46342e486 100644 --- a/Documentation/i2c/busses/i2c-ali1535 +++ b/Documentation/i2c/busses/i2c-ali1535 @@ -3,7 +3,7 @@ Kernel driver i2c-ali1535 Supported adapters: * Acer Labs, Inc. ALI 1535 (south bridge) Datasheet: Now under NDA - http://www.ali.com.tw/eng/support/datasheet_request.php + http://www.ali.com.tw/ Authors: Frodo Looijaard <frodol@dds.nl>, diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563 index 54691698d2d..41b1a077e4c 100644 --- a/Documentation/i2c/busses/i2c-ali1563 +++ b/Documentation/i2c/busses/i2c-ali1563 @@ -3,7 +3,7 @@ Kernel driver i2c-ali1563 Supported adapters: * Acer Labs, Inc. ALI 1563 (south bridge) Datasheet: Now under NDA - http://www.ali.com.tw/eng/support/datasheet_request.php + http://www.ali.com.tw/ Author: Patrick Mochel <mochel@digitalimplant.org> diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3 index 600da90b8f1..42888d8ac12 100644 --- a/Documentation/i2c/busses/i2c-ali15x3 +++ b/Documentation/i2c/busses/i2c-ali15x3 @@ -3,7 +3,7 @@ Kernel driver i2c-ali15x3 Supported adapters: * Acer Labs, Inc. ALI 1533 and 1543C (south bridge) Datasheet: Now under NDA - http://www.ali.com.tw/eng/support/datasheet_request.php + http://www.ali.com.tw/ Authors: Frodo Looijaard <frodol@dds.nl>, diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index e307914a3ed..93fe76e5652 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -15,10 +15,14 @@ Supported adapters: * Intel 82801I (ICH9) * Intel EP80579 (Tolapai) * Intel 82801JI (ICH10) - * Intel 3400/5 Series (PCH) + * Intel 5/3400 Series (PCH) * Intel Cougar Point (PCH) + * Intel Patsburg (PCH) Datasheets: Publicly available at the Intel website +On Intel Patsburg and later chipsets, both the normal host SMBus controller +and the additional 'Integrated Device Function' controllers are supported. + Authors: Mark Studebaker <mdsxyz123@yahoo.com> Jean Delvare <khali@linux-fr.org> diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4 index ac540c71c7e..475bb4ae072 100644 --- a/Documentation/i2c/busses/i2c-piix4 +++ b/Documentation/i2c/busses/i2c-piix4 @@ -97,4 +97,4 @@ of all affected systems, so the only safe solution was to prevent access to the SMBus on all IBM systems (detected using DMI data.) For additional information, read: -http://www.lm-sensors.org/browser/lm-sensors/trunk/README.thinkpad +http://www.lm-sensors.org/browser/lm-sensors/trunk/README diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630 index 629ea2c356f..0b969736693 100644 --- a/Documentation/i2c/busses/i2c-sis630 +++ b/Documentation/i2c/busses/i2c-sis630 @@ -2,7 +2,7 @@ Kernel driver i2c-sis630 Supported adapters: * Silicon Integrated Systems Corp (SiS) - 630 chipset (Datasheet: available at http://amalysh.bei.t-online.de/docs/SIS/) + 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) 730 chipset * Possible other SiS chipsets ? diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices index e89490270ab..87da405a859 100644 --- a/Documentation/i2c/instantiating-devices +++ b/Documentation/i2c/instantiating-devices @@ -102,7 +102,7 @@ static int __devinit usb_hcd_pnx4008_probe(struct platform_device *pdev) memset(&i2c_info, 0, sizeof(struct i2c_board_info)); strlcpy(i2c_info.name, "isp1301_pnx", I2C_NAME_SIZE); isp1301_i2c_client = i2c_new_probed_device(i2c_adap, &i2c_info, - normal_i2c); + normal_i2c, NULL); i2c_put_adapter(i2c_adap); (...) } diff --git a/Documentation/ia64/aliasing.txt b/Documentation/ia64/aliasing.txt index aa3e953f0f7..5a4dea6abeb 100644 --- a/Documentation/ia64/aliasing.txt +++ b/Documentation/ia64/aliasing.txt @@ -168,8 +168,6 @@ PAST PROBLEM CASES mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled - See https://bugzilla.novell.com/show_bug.cgi?id=140858. - The EFI memory map reports the following attributes: 0x00000-0x9FFFF WB only 0xA0000-0xBFFFF UC only (VGA frame buffer) diff --git a/Documentation/ia64/serial.txt b/Documentation/ia64/serial.txt index 040b9773209..6869c73de4e 100644 --- a/Documentation/ia64/serial.txt +++ b/Documentation/ia64/serial.txt @@ -133,7 +133,7 @@ TROUBLESHOOTING SERIAL CONSOLE PROBLEMS -[1] http://www.dig64.org/specifications/DIG64_PCDPv20.pdf +[1] http://www.dig64.org/specifications/agreement The table was originally defined as the "HCDP" for "Headless Console/Debug Port." The current version is the "PCDP" for "Primary Console and Debug Port Devices." diff --git a/Documentation/infiniband/user_verbs.txt b/Documentation/infiniband/user_verbs.txt index afe3f8da901..e5092d696da 100644 --- a/Documentation/infiniband/user_verbs.txt +++ b/Documentation/infiniband/user_verbs.txt @@ -5,7 +5,7 @@ USERSPACE VERBS ACCESS described in chapter 11 of the InfiniBand Architecture Specification. To use the verbs, the libibverbs library, available from - <http://openib.org/>, is required. libibverbs contains a + http://www.openfabrics.org/, is required. libibverbs contains a device-independent API for using the ib_uverbs interface. libibverbs also requires appropriate device-dependent kernel and userspace driver for your InfiniBand hardware. For example, to use diff --git a/Documentation/input/appletouch.txt b/Documentation/input/appletouch.txt index 4f7c633a76d..b13de3f8910 100644 --- a/Documentation/input/appletouch.txt +++ b/Documentation/input/appletouch.txt @@ -82,4 +82,4 @@ Links: ------ [1]: http://johannes.sipsolutions.net/PowerBook/touchpad/ -[2]: http://web.telia.com/~u89404340/touchpad/index.html +[2]: http://web.archive.org/web/*/http://web.telia.com/~u89404340/touchpad/index.html diff --git a/Documentation/input/bcm5974.txt b/Documentation/input/bcm5974.txt index 5e22dcf6d48..74d3876d6f3 100644 --- a/Documentation/input/bcm5974.txt +++ b/Documentation/input/bcm5974.txt @@ -62,4 +62,4 @@ Links ----- [1] http://ubuntuforums.org/showthread.php?t=840040 -[2] http://http://bitmath.org/code/ +[2] http://bitmath.org/code/ diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.txt index 3ac92413c87..2d5fbfd6023 100644 --- a/Documentation/input/iforce-protocol.txt +++ b/Documentation/input/iforce-protocol.txt @@ -251,7 +251,7 @@ Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy. ** Author of this document ** Johann Deneux <johann.deneux@gmail.com> -Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/ +Home page at http://web.archive.org/web/*/http://www.esil.univ-mrs.fr Additions by Vojtech Pavlik. diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index c0fc1c75fd8..bdcba154b83 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -6,31 +6,149 @@ Multi-touch (MT) Protocol Introduction ------------ -In order to utilize the full power of the new multi-touch devices, a way to -report detailed finger data to user space is needed. This document -describes the multi-touch (MT) protocol which allows kernel drivers to -report details for an arbitrary number of fingers. +In order to utilize the full power of the new multi-touch and multi-user +devices, a way to report detailed data from multiple contacts, i.e., +objects in direct contact with the device surface, is needed. This +document describes the multi-touch (MT) protocol which allows kernel +drivers to report details for an arbitrary number of contacts. + +The protocol is divided into two types, depending on the capabilities of the +hardware. For devices handling anonymous contacts (type A), the protocol +describes how to send the raw data for all contacts to the receiver. For +devices capable of tracking identifiable contacts (type B), the protocol +describes how to send updates for individual contacts via event slots. + + +Protocol Usage +-------------- + +Contact details are sent sequentially as separate packets of ABS_MT +events. Only the ABS_MT events are recognized as part of a contact +packet. Since these events are ignored by current single-touch (ST) +applications, the MT protocol can be implemented on top of the ST protocol +in an existing driver. + +Drivers for type A devices separate contact packets by calling +input_mt_sync() at the end of each packet. This generates a SYN_MT_REPORT +event, which instructs the receiver to accept the data for the current +contact and prepare to receive another. + +Drivers for type B devices separate contact packets by calling +input_mt_slot(), with a slot as argument, at the beginning of each packet. +This generates an ABS_MT_SLOT event, which instructs the receiver to +prepare for updates of the given slot. + +All drivers mark the end of a multi-touch transfer by calling the usual +input_sync() function. This instructs the receiver to act upon events +accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new set +of events/packets. + +The main difference between the stateless type A protocol and the stateful +type B slot protocol lies in the usage of identifiable contacts to reduce +the amount of data sent to userspace. The slot protocol requires the use of +the ABS_MT_TRACKING_ID, either provided by the hardware or computed from +the raw data [5]. + +For type A devices, the kernel driver should generate an arbitrary +enumeration of the full set of anonymous contacts currently on the +surface. The order in which the packets appear in the event stream is not +important. Event filtering and finger tracking is left to user space [3]. + +For type B devices, the kernel driver should associate a slot with each +identified contact, and use that slot to propagate changes for the contact. +Creation, replacement and destruction of contacts is achieved by modifying +the ABS_MT_TRACKING_ID of the associated slot. A non-negative tracking id +is interpreted as a contact, and the value -1 denotes an unused slot. A +tracking id not previously present is considered new, and a tracking id no +longer present is considered removed. Since only changes are propagated, +the full state of each initiated contact has to reside in the receiving +end. Upon receiving an MT event, one simply updates the appropriate +attribute of the current slot. + + +Protocol Example A +------------------ + +Here is what a minimal event sequence for a two-contact touch would look +like for a type A device: + + ABS_MT_POSITION_X x[0] + ABS_MT_POSITION_Y y[0] + SYN_MT_REPORT + ABS_MT_POSITION_X x[1] + ABS_MT_POSITION_Y y[1] + SYN_MT_REPORT + SYN_REPORT +The sequence after moving one of the contacts looks exactly the same; the +raw data for all present contacts are sent between every synchronization +with SYN_REPORT. -Usage ------ +Here is the sequence after lifting the first contact: + + ABS_MT_POSITION_X x[1] + ABS_MT_POSITION_Y y[1] + SYN_MT_REPORT + SYN_REPORT + +And here is the sequence after lifting the second contact: + + SYN_MT_REPORT + SYN_REPORT + +If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the +ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the +last SYN_REPORT will be dropped by the input core, resulting in no +zero-contact event reaching userland. -Anonymous finger details are sent sequentially as separate packets of ABS -events. Only the ABS_MT events are recognized as part of a finger -packet. The end of a packet is marked by calling the input_mt_sync() -function, which generates a SYN_MT_REPORT event. This instructs the -receiver to accept the data for the current finger and prepare to receive -another. The end of a multi-touch transfer is marked by calling the usual -input_sync() function. This instructs the receiver to act upon events -accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new -set of events/packets. + +Protocol Example B +------------------ + +Here is what a minimal event sequence for a two-contact touch would look +like for a type B device: + + ABS_MT_SLOT 0 + ABS_MT_TRACKING_ID 45 + ABS_MT_POSITION_X x[0] + ABS_MT_POSITION_Y y[0] + ABS_MT_SLOT 1 + ABS_MT_TRACKING_ID 46 + ABS_MT_POSITION_X x[1] + ABS_MT_POSITION_Y y[1] + SYN_REPORT + +Here is the sequence after moving contact 45 in the x direction: + + ABS_MT_SLOT 0 + ABS_MT_POSITION_X x[0] + SYN_REPORT + +Here is the sequence after lifting the contact in slot 0: + + ABS_MT_TRACKING_ID -1 + SYN_REPORT + +The slot being modified is already 0, so the ABS_MT_SLOT is omitted. The +message removes the association of slot 0 with contact 45, thereby +destroying contact 45 and freeing slot 0 to be reused for another contact. + +Finally, here is the sequence after lifting the second contact: + + ABS_MT_SLOT 1 + ABS_MT_TRACKING_ID -1 + SYN_REPORT + + +Event Usage +----------- A set of ABS_MT events with the desired properties is defined. The events are divided into categories, to allow for partial implementation. The minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which -allows for multiple fingers to be tracked. If the device supports it, the +allows for multiple contacts to be tracked. If the device supports it, the ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size -of the contact area and approaching finger, respectively. +of the contact area and approaching contact, respectively. The TOUCH and WIDTH parameters have a geometrical interpretation; imagine looking through a window at someone gently holding a finger against the @@ -41,56 +159,26 @@ ABS_MT_TOUCH_MAJOR, the diameter of the outer region is ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder against the glass. The inner region will increase, and in general, the ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than -unity, is related to the finger pressure. For pressure-based devices, +unity, is related to the contact pressure. For pressure-based devices, ABS_MT_PRESSURE may be used to provide the pressure on the contact area instead. -In addition to the MAJOR parameters, the oval shape of the finger can be +In addition to the MAJOR parameters, the oval shape of the contact can be described by adding the MINOR parameters, such that MAJOR and MINOR are the major and minor axis of an ellipse. Finally, the orientation of the oval shape can be describe with the ORIENTATION parameter. The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a -finger or a pen or something else. Devices with more granular information +contact or a pen or something else. Devices with more granular information may specify general shapes as blobs, i.e., as a sequence of rectangular shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices that currently support it, the ABS_MT_TRACKING_ID event may be used to -report finger tracking from hardware [5]. +report contact tracking from hardware [5]. -Here is what a minimal event sequence for a two-finger touch would look -like: - - ABS_MT_POSITION_X - ABS_MT_POSITION_Y - SYN_MT_REPORT - ABS_MT_POSITION_X - ABS_MT_POSITION_Y - SYN_MT_REPORT - SYN_REPORT - -Here is the sequence after lifting one of the fingers: - - ABS_MT_POSITION_X - ABS_MT_POSITION_Y - SYN_MT_REPORT - SYN_REPORT - -And here is the sequence after lifting the remaining finger: - - SYN_MT_REPORT - SYN_REPORT - -If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the -ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the -last SYN_REPORT will be dropped by the input core, resulting in no -zero-finger event reaching userland. Event Semantics --------------- -The word "contact" is used to describe a tool which is in direct contact -with the surface. A finger, a pen or a rubber all classify as contacts. - ABS_MT_TOUCH_MAJOR The length of the major axis of the contact. The length should be given in @@ -157,15 +245,16 @@ MT_TOOL_PEN [2]. ABS_MT_BLOB_ID The BLOB_ID groups several packets together into one arbitrarily shaped -contact. This is a low-level anonymous grouping, and should not be confused -with the high-level trackingID [5]. Most kernel drivers will not have blob -capability, and can safely omit the event. +contact. This is a low-level anonymous grouping for type A devices, and +should not be confused with the high-level trackingID [5]. Most type A +devices do not have blob capability, so drivers can safely omit this event. ABS_MT_TRACKING_ID The TRACKING_ID identifies an initiated contact throughout its life cycle -[5]. There are currently only a few devices that support it, so this event -should normally be omitted. +[5]. This event is mandatory for type B devices. The value range of the +TRACKING_ID should be large enough to ensure unique identification of a +contact maintained over an extended period of time. Event Computation @@ -192,20 +281,11 @@ finger along the X axis (1). Finger Tracking --------------- -The kernel driver should generate an arbitrary enumeration of the set of -anonymous contacts currently on the surface. The order in which the packets -appear in the event stream is not important. - The process of finger tracking, i.e., to assign a unique trackingID to each -initiated contact on the surface, is left to user space; preferably the -multi-touch X driver [3]. In that driver, the trackingID stays the same and -unique until the contact vanishes (when the finger leaves the surface). The -problem of assigning a set of anonymous fingers to a set of identified -fingers is a euclidian bipartite matching problem at each event update, and -relies on a sufficiently rapid update rate. - -There are a few devices that support trackingID in hardware. User space can -make use of these native identifiers to reduce bandwidth and cpu usage. +initiated contact on the surface, is a Euclidian Bipartite Matching +problem. At each event synchronization, the set of actual contacts is +matched to the set of contacts from the previous synchronization. A full +implementation can be found in [3]. Gestures diff --git a/Documentation/input/ntrig.txt b/Documentation/input/ntrig.txt new file mode 100644 index 00000000000..be1fd981f73 --- /dev/null +++ b/Documentation/input/ntrig.txt @@ -0,0 +1,126 @@ +N-Trig touchscreen Driver +------------------------- + Copyright (c) 2008-2010 Rafi Rubin <rafi@seas.upenn.edu> + Copyright (c) 2009-2010 Stephane Chatty + +This driver provides support for N-Trig pen and multi-touch sensors. Single +and multi-touch events are translated to the appropriate protocols for +the hid and input systems. Pen events are sufficiently hid compliant and +are left to the hid core. The driver also provides additional filtering +and utility functions accessible with sysfs and module parameters. + +This driver has been reported to work properly with multiple N-Trig devices +attached. + + +Parameters +---------- + +Note: values set at load time are global and will apply to all applicable +devices. Adjusting parameters with sysfs will override the load time values, +but only for that one device. + +The following parameters are used to configure filters to reduce noise: + +activate_slack number of fingers to ignore before processing events + +activation_height size threshold to activate immediately +activation_width + +min_height size threshold bellow which fingers are ignored +min_width both to decide activation and during activity + +deactivate_slack the number of "no contact" frames to ignore before + propagating the end of activity events + +When the last finger is removed from the device, it sends a number of empty +frames. By holding off on deactivation for a few frames we can tolerate false +erroneous disconnects, where the sensor may mistakenly not detect a finger that +is still present. Thus deactivate_slack addresses problems where a users might +see breaks in lines during drawing, or drop an object during a long drag. + + +Additional sysfs items +---------------------- + +These nodes just provide easy access to the ranges reported by the device. +sensor_logical_height the range for positions reported during activity +sensor_logical_width + +sensor_physical_height internal ranges not used for normal events but +sensor_physical_width useful for tuning + +All N-Trig devices with product id of 1 report events in the ranges of +X: 0-9600 +Y: 0-7200 +However not all of these devices have the same physical dimensions. Most +seem to be 12" sensors (Dell Latitude XT and XT2 and the HP TX2), and +at least one model (Dell Studio 17) has a 17" sensor. The ratio of physical +to logical sizes is used to adjust the size based filter parameters. + + +Filtering +--------- + +With the release of the early multi-touch firmwares it became increasingly +obvious that these sensors were prone to erroneous events. Users reported +seeing both inappropriately dropped contact and ghosts, contacts reported +where no finger was actually touching the screen. + +Deactivation slack helps prevent dropped contact for single touch use, but does +not address the problem of dropping one of more contacts while other contacts +are still active. Drops in the multi-touch context require additional +processing and should be handled in tandem with tacking. + +As observed ghost contacts are similar to actual use of the sensor, but they +seem to have different profiles. Ghost activity typically shows up as small +short lived touches. As such, I assume that the longer the continuous stream +of events the more likely those events are from a real contact, and that the +larger the size of each contact the more likely it is real. Balancing the +goals of preventing ghosts and accepting real events quickly (to minimize +user observable latency), the filter accumulates confidence for incoming +events until it hits thresholds and begins propagating. In the interest in +minimizing stored state as well as the cost of operations to make a decision, +I've kept that decision simple. + +Time is measured in terms of the number of fingers reported, not frames since +the probability of multiple simultaneous ghosts is expected to drop off +dramatically with increasing numbers. Rather than accumulate weight as a +function of size, I just use it as a binary threshold. A sufficiently large +contact immediately overrides the waiting period and leads to activation. + +Setting the activation size thresholds to large values will result in deciding +primarily on activation slack. If you see longer lived ghosts, turning up the +activation slack while reducing the size thresholds may suffice to eliminate +the ghosts while keeping the screen quite responsive to firm taps. + +Contacts continue to be filtered with min_height and min_width even after +the initial activation filter is satisfied. The intent is to provide +a mechanism for filtering out ghosts in the form of an extra finger while +you actually are using the screen. In practice this sort of ghost has +been far less problematic or relatively rare and I've left the defaults +set to 0 for both parameters, effectively turning off that filter. + +I don't know what the optimal values are for these filters. If the defaults +don't work for you, please play with the parameters. If you do find other +values more comfortable, I would appreciate feedback. + +The calibration of these devices does drift over time. If ghosts or contact +dropping worsen and interfere with the normal usage of your device, try +recalibrating it. + + +Calibration +----------- + +The N-Trig windows tools provide calibration and testing routines. Also an +unofficial unsupported set of user space tools including a calibrator is +available at: +http://code.launchpad.net/~rafi-seas/+junk/ntrig_calib + + +Tracking +-------- + +As of yet, all tested N-Trig firmwares do not track fingers. When multiple +contacts are active they seem to be sorted primarily by Y position. diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.txt index b35affd5c64..b2ef125b71f 100644 --- a/Documentation/input/sentelic.txt +++ b/Documentation/input/sentelic.txt @@ -341,7 +341,7 @@ Byte 5~8: Don't care (Absolute packet) FSP supports basic PS/2 commanding set and modes, refer to following URL for details about PS/2 commands: -http://www.computer-engineering.org/index.php?title=PS/2_Mouse_Interface +http://www.computer-engineering.org/ps2mouse/ ============================================================================== * Programming Sequence for Determining Packet Parsing Flow diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt index aae0d404c56..7cc9a436e6a 100644 --- a/Documentation/input/xpad.txt +++ b/Documentation/input/xpad.txt @@ -150,7 +150,7 @@ the basic functionality. 1. http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki) 2. http://xpad.xbox-scene.com/ -3. http://www.xboxhackz.com/Hackz-Reference.htm +3. http://www.markosweb.com/www/xboxhackz.com/ 4. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany): diff --git a/Documentation/intel_txt.txt b/Documentation/intel_txt.txt index 5dc59b04a71..849de1a78e7 100644 --- a/Documentation/intel_txt.txt +++ b/Documentation/intel_txt.txt @@ -25,20 +25,18 @@ which has been updated for the new released platforms. Intel TXT has been presented at various events over the past few years, some of which are: LinuxTAG 2008: - http://www.linuxtag.org/2008/en/conf/events/vp-donnerstag/ - details.html?talkid=110 + http://www.linuxtag.org/2008/en/conf/events/vp-donnerstag.html TRUST2008: - http://www.trust2008.eu/downloads/Keynote-Speakers/ + http://www.trust-conference.eu/downloads/Keynote-Speakers/ 3_David-Grawrock_The-Front-Door-of-Trusted-Computing.pdf - IDF 2008, Shanghai: - http://inteldeveloperforum.com.edgesuite.net/shanghai_2008/ - aep/PROS003/index.html + IDF, Shanghai: + http://www.prcidf.com.cn/index_en.html IDFs 2006, 2007 (I'm not sure if/where they are online) Trusted Boot Project Overview: ============================= -Trusted Boot (tboot) is an open source, pre- kernel/VMM module that +Trusted Boot (tboot) is an open source, pre-kernel/VMM module that uses Intel TXT to perform a measured and verified launch of an OS kernel/VMM. diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index dd5806f4fcc..63ffd78824d 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -74,11 +74,12 @@ Code Seq#(hex) Include File Comments 0x10 00-0F drivers/char/s390/vmcp.h 0x12 all linux/fs.h linux/blkpg.h -0x1b all InfiniBand Subsystem <http://www.openib.org/> +0x1b all InfiniBand Subsystem <http://infiniband.sourceforge.net/> 0x20 all drivers/cdrom/cm206.h 0x22 all scsi/sg.h '#' 00-3F IEEE 1394 Subsystem Block for the entire subsystem '$' 00-0F linux/perf_counter.h, linux/perf_event.h +'&' 00-07 drivers/firewire/nosy-user.h '1' 00-1F <linux/timepps.h> PPS kit from Ulrich Windl <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/> '2' 01-04 linux/i2o.h @@ -190,7 +191,7 @@ Code Seq#(hex) Include File Comments '[' 00-07 linux/usb/tmc.h USB Test and Measurement Devices <mailto:gregkh@suse.de> 'a' all linux/atm*.h, linux/sonet.h ATM on linux - <http://lrcwww.epfl.ch/linux-atm/magic.html> + <http://lrcwww.epfl.ch/> 'b' 00-FF conflict! bit3 vme host bridge <mailto:natalia@nikhefk.nikhef.nl> 'b' 00-0F media/bt819.h conflict! @@ -225,7 +226,7 @@ Code Seq#(hex) Include File Comments 'k' 00-0F linux/spi/spidev.h conflict! 'k' 00-05 video/kyro.h conflict! 'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system - <http://mikonos.dia.unisa.it/tcfs> + <http://web.archive.org/web/*/http://mikonos.dia.unisa.it/tcfs> 'l' 40-7F linux/udf_fs_i.h in development: <http://sourceforge.net/projects/linux-udf/> 'm' 00-09 linux/mmtimer.h conflict! @@ -252,13 +253,13 @@ Code Seq#(hex) Include File Comments <mailto:giometti@linux.it> 'q' 00-1F linux/serio.h 'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK - linux/ixjuser.h <http://www.quicknet.net> + linux/ixjuser.h <http://web.archive.org/web/*/http://www.quicknet.net> 'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c 's' all linux/cdk.h 't' 00-7F linux/if_ppp.h 't' 80-8F linux/isdn_ppp.h 't' 90 linux/toshiba.h -'u' 00-1F linux/smb_fs.h +'u' 00-1F linux/smb_fs.h gone 'v' all linux/videodev.h conflict! 'v' 00-1F linux/ext2_fs.h conflict! 'v' 00-1F linux/fs.h conflict! @@ -277,7 +278,6 @@ Code Seq#(hex) Include File Comments <mailto:oe@port.de> 'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict! 0x80 00-1F linux/fb.h -0x81 00-1F linux/videotext.h 0x88 00-3F media/ovcamchip.h 0x89 00-06 arch/x86/include/asm/sockios.h 0x89 0B-DF linux/sockios.h @@ -286,7 +286,7 @@ Code Seq#(hex) Include File Comments 0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range 0x8B all linux/wireless.h 0x8C 00-3F WiNRADiO driver - <http://www.proximity.com.au/~brian/winradio/> + <http://www.winradio.com.au/> 0x90 00 drivers/cdrom/sbpcd.h 0x92 00-0F drivers/usb/mon/mon_bin.c 0x93 60-7F linux/auto_fs.h diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI index f172091fb7c..309eb5ed942 100644 --- a/Documentation/isdn/INTERFACE.CAPI +++ b/Documentation/isdn/INTERFACE.CAPI @@ -113,12 +113,16 @@ char *driver_name int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata) (optional) pointer to a callback function for sending firmware and configuration data to the device + The function may return before the operation has completed. + Completion must be signalled by a call to capi_ctr_ready(). Return value: 0 on success, error code on error Called in process context. void (*reset_ctr)(struct capi_ctr *ctrlr) - (optional) pointer to a callback function for performing a reset on - the device, releasing all registered applications + (optional) pointer to a callback function for stopping the device, + releasing all registered applications + The function may return before the operation has completed. + Completion must be signalled by a call to capi_ctr_down(). Called in process context. void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, diff --git a/Documentation/isdn/README b/Documentation/isdn/README index 6783437f21c..cfb1884342e 100644 --- a/Documentation/isdn/README +++ b/Documentation/isdn/README @@ -36,7 +36,7 @@ README for the ISDN-subsystem http://www.mhessler.de/i4lfaq/ It can be viewed online, or downloaded in sgml/text/html format. The FAQ can also be viewed online at - http://www.isdn4inux.de/faq/ + http://www.isdn4linux.de/faq/ or downloaded from ftp://ftp.isdn4linux.de/pub/isdn4linux/FAQ/ diff --git a/Documentation/isdn/README.HiSax b/Documentation/isdn/README.HiSax index 031c8d81433..99e87a61897 100644 --- a/Documentation/isdn/README.HiSax +++ b/Documentation/isdn/README.HiSax @@ -486,7 +486,7 @@ Appendix: Teles PCMCIA driver ----------------------------- See - http://www.stud.uni-wuppertal.de/~ea0141/pcmcia.html + http://www.linux.no/teles_cs.txt for instructions. Appendix: Linux and ISDN-leased lines diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/README.gigaset index e472df84232..ef3343eaa00 100644 --- a/Documentation/isdn/README.gigaset +++ b/Documentation/isdn/README.gigaset @@ -47,9 +47,9 @@ GigaSet 307x Device Driver 1.2. Software -------- - The driver works with ISDN4linux and so can be used with any software - which is able to use ISDN4linux for ISDN connections (voice or data). - Experimental Kernel CAPI support is available as a compilation option. + The driver works with the Kernel CAPI subsystem as well as the old + ISDN4Linux subsystem, so it can be used with any software which is able + to use CAPI 2.0 or ISDN4Linux for ISDN connections (voice or data). There are some user space tools available at http://sourceforge.net/projects/gigaset307x/ @@ -152,61 +152,42 @@ GigaSet 307x Device Driver - GIGVER_FWBASE: retrieve the firmware version of the base Upon return, version[] is filled with the requested version information. -2.3. ISDN4linux - ---------- - This is the "normal" mode of operation. After loading the module you can - set up the ISDN system just as you'd do with any ISDN card supported by - the ISDN4Linux subsystem. Most distributions provide some configuration - utility. If not, you can use some HOWTOs like - http://www.linuxhaven.de/dlhp/HOWTO/DE-ISDN-HOWTO-5.html - If this doesn't work, because you have some device like SX100 where - debug output (see section 3.2.) shows something like this when dialing - CMD Received: ERROR - Available Params: 0 - Connection State: 0, Response: -1 - gigaset_process_response: resp_code -1 in ConState 0 ! - Timeout occurred - you probably need to use unimodem mode. (see section 2.5.) - -2.4. CAPI +2.3. CAPI ---- If the driver is compiled with CAPI support (kernel configuration option - GIGASET_CAPI, experimental) it can also be used with CAPI 2.0 kernel and - user space applications. For user space access, the module capi.ko must - be loaded. The capiinit command (included in the capi4k-utils package) - does this for you. - - The CAPI variant of the driver supports legacy ISDN4Linux applications - via the capidrv compatibility driver. The kernel module capidrv.ko must - be loaded explicitly with the command + GIGASET_CAPI) the devices will show up as CAPI controllers as soon as the + corresponding driver module is loaded, and can then be used with CAPI 2.0 + kernel and user space applications. For user space access, the module + capi.ko must be loaded. + + Legacy ISDN4Linux applications are supported via the capidrv + compatibility driver. The kernel module capidrv.ko must be loaded + explicitly with the command modprobe capidrv if needed, and cannot be unloaded again without unloading the driver first. (These are limitations of capidrv.) - The note about unimodem mode in the preceding section applies here, too. - -2.5. Unimodem mode - ------------- - This is needed for some devices [e.g. SX100] as they have problems with - the "normal" commands. + Most distributions handle loading and unloading of the various CAPI + modules automatically via the command capiinit(1) from the capi4k-utils + package or a similar mechanism. Note that capiinit(1) cannot unload the + Gigaset drivers because it doesn't support more than one module per + driver. - If you have installed the command line tool gigacontr, you can enter - unimodem mode using - gigacontr --mode unimodem - You can switch back using - gigacontr --mode isdn +2.4. ISDN4Linux + ---------- + If the driver is compiled without CAPI support (native ISDN4Linux + variant), it registers the device with the legacy ISDN4Linux subsystem + after loading the module. It can then be used with ISDN4Linux + applications only. Most distributions provide some configuration utility + for setting up that subsystem. Otherwise you can use some HOWTOs like + http://www.linuxhaven.de/dlhp/HOWTO/DE-ISDN-HOWTO-5.html - You can also put the driver directly into Unimodem mode when it's loaded, - by passing the module parameter startmode=0 to the hardware specific - module, e.g. - modprobe usb_gigaset startmode=0 - or by adding a line like - options usb_gigaset startmode=0 - to an appropriate module configuration file, like /etc/modprobe.d/gigaset - or /etc/modprobe.conf.local. +2.5. Unimodem mode + ------------- In this mode the device works like a modem connected to a serial port (the /dev/ttyGU0, ... mentioned above) which understands the commands + ATZ init, reset => OK or ERROR ATD @@ -234,6 +215,31 @@ GigaSet 307x Device Driver to an appropriate module configuration file, like /etc/modprobe.d/gigaset or /etc/modprobe.conf.local. + Unimodem mode is needed for making some devices [e.g. SX100] work which + do not support the regular Gigaset command set. If debug output (see + section 3.2.) shows something like this when dialing: + CMD Received: ERROR + Available Params: 0 + Connection State: 0, Response: -1 + gigaset_process_response: resp_code -1 in ConState 0 ! + Timeout occurred + then switching to unimodem mode may help. + + If you have installed the command line tool gigacontr, you can enter + unimodem mode using + gigacontr --mode unimodem + You can switch back using + gigacontr --mode isdn + + You can also put the driver directly into Unimodem mode when it's loaded, + by passing the module parameter startmode=0 to the hardware specific + module, e.g. + modprobe usb_gigaset startmode=0 + or by adding a line like + options usb_gigaset startmode=0 + to an appropriate module configuration file, like /etc/modprobe.d/gigaset + or /etc/modprobe.conf.local. + 2.6. Call-ID (CID) mode ------------------ Call-IDs are numbers used to tag commands to, and responses from, the @@ -263,7 +269,22 @@ GigaSet 307x Device Driver change its CID mode while the driver is loaded, eg. echo 0 > /sys/class/tty/ttyGU0/cidmode -2.7. Unregistered Wireless Devices (M101/M105) +2.7. Dialing Numbers + --------------- + The called party number provided by an application for dialing out must + be a public network number according to the local dialing plan, without + any dial prefix for getting an outside line. + + Internal calls can be made by providing an internal extension number + prefixed with "**" (two asterisks) as the called party number. So to dial + eg. the first registered DECT handset, give "**11" as the called party + number. Dialing "***" (three asterisks) calls all extensions + simultaneously (global call). + + This holds for both CAPI 2.0 and ISDN4Linux applications. Unimodem mode + does not support internal calls. + +2.8. Unregistered Wireless Devices (M101/M105) ----------------------------------------- The main purpose of the ser_gigaset and usb_gigaset drivers is to allow the M101 and M105 wireless devices to be used as ISDN devices for ISDN diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO index 55476982b5c..b63301a0381 100644 --- a/Documentation/ja_JP/HOWTO +++ b/Documentation/ja_JP/HOWTO @@ -223,7 +223,7 @@ web サイトには、コードの構成、サブシステム、現在存在す あなたがどこからスタートして良いかわからないが、Linux カーネル開発コミュ ニティに参加して何かすることをさがしている場合には、Linux kernel Janitor's プロジェクトにいけば良いでしょう - - http://janitor.kernelnewbies.org/ + http://kernelnewbies.org/KernelJanitors ここはそのようなスタートをするのにうってつけの場所です。ここには、 Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな らない、単純な問題のリストが記述されています。このプロジェクトに関わる diff --git a/Documentation/ja_JP/SubmittingPatches b/Documentation/ja_JP/SubmittingPatches index a9dc1243e85..f107c834d24 100644 --- a/Documentation/ja_JP/SubmittingPatches +++ b/Documentation/ja_JP/SubmittingPatches @@ -97,7 +97,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/tpp.txt このリンクの先のスクリプトの代わりとして、quilt がパッチマネジメント ツールとして推奨されています(上のリンクを見てください)。 @@ -210,7 +210,7 @@ VGER.KERNEL.ORG でホスティングされているメーリングリストの ・移植性のないコードから移植性のあるコードへの置き換え(小さい範囲で あればアーキテクチャ特有のことでも他の人がコピーできます) ・作者やメンテナによる修正(すなわち patch monkey の再転送モード) -URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/> +EMAIL: <trivial@kernel.org> 7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ @@ -534,7 +534,7 @@ gcc においては、マクロと同じくらい軽いです。 ---------------------- 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> diff --git a/Documentation/kbuild/kbuild.txt b/Documentation/kbuild/kbuild.txt index e903f20077c..1e5165aa9e4 100644 --- a/Documentation/kbuild/kbuild.txt +++ b/Documentation/kbuild/kbuild.txt @@ -62,15 +62,15 @@ Set the directory to look for the kernel source when building external modules. The directory can be specified in several ways: 1) Use "M=..." on the command line -2) Environmnet variable KBUILD_EXTMOD -3) Environmnet variable SUBDIRS +2) Environment variable KBUILD_EXTMOD +3) Environment variable SUBDIRS The possibilities are listed in the order they take precedence. Using "M=..." will always override the others. KBUILD_OUTPUT -------------------------------------------------- Specify the output directory when building the kernel. -The output directory can also be specificed using "O=...". +The output directory can also be specified using "O=...". Setting "O=..." takes precedence over KBUILD_OUTPUT. ARCH @@ -112,7 +112,7 @@ The script will be called with the following arguments: $3 - kernel map file $4 - default install path (use root directory if blank) -The implmentation of "make install" is architecture specific +The implementation of "make install" is architecture specific and it may differ from the above. INSTALLKERNEL is provided to enable the possibility to diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt index b472e4e0ba6..2fe93ca7c77 100644 --- a/Documentation/kbuild/kconfig-language.txt +++ b/Documentation/kbuild/kconfig-language.txt @@ -322,7 +322,8 @@ mainmenu: "mainmenu" <prompt> This sets the config program's title bar if the config program chooses -to use it. +to use it. It should be placed at the top of the configuration, before any +other statement. Kconfig hints diff --git a/Documentation/kbuild/kconfig.txt b/Documentation/kbuild/kconfig.txt index b2cb16ebcb1..cca46b1a0f6 100644 --- a/Documentation/kbuild/kconfig.txt +++ b/Documentation/kbuild/kconfig.txt @@ -65,7 +65,7 @@ also use the environment variable KCONFIG_ALLCONFIG as a flag or a filename that contains config symbols that the user requires to be set to a specific value. If KCONFIG_ALLCONFIG is used without a filename, "make *config" checks for a file named -"all{yes/mod/no/random}.config" (corresponding to the *config command +"all{yes/mod/no/def/random}.config" (corresponding to the *config command that was used) for symbol values that are to be forced. If this file is not found, it checks for a file named "all.config" to contain forced values. diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index c899192b37b..0ef00bd6e54 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -45,7 +45,6 @@ This document describes the Linux kernel Makefiles. --- 7.1 header-y --- 7.2 objhdr-y --- 7.3 destination-y - --- 7.4 unifdef-y (deprecated) === 8 Kbuild Variables === 9 Makefile language @@ -168,7 +167,7 @@ more details, with real examples. #drivers/isdn/i4l/Makefile # Makefile for the kernel ISDN subsystem and device drivers. # Each configuration option enables a list of files. - obj-$(CONFIG_ISDN) += isdn.o + obj-$(CONFIG_ISDN_I4L) += isdn.o obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o --- 3.3 Loadable module goals - obj-m @@ -187,34 +186,35 @@ more details, with real examples. Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm' If a kernel module is built from several source files, you specify - that you want to build a module in the same way as above. - - Kbuild needs to know which the parts that you want to build your - module from, so you have to tell it by setting an - $(<module_name>-objs) variable. + that you want to build a module in the same way as above; however, + kbuild needs to know which object files you want to build your + module from, so you have to tell it by setting a $(<module_name>-y) + variable. Example: #drivers/isdn/i4l/Makefile - obj-$(CONFIG_ISDN) += isdn.o - isdn-objs := isdn_net_lib.o isdn_v110.o isdn_common.o + obj-$(CONFIG_ISDN_I4L) += isdn.o + isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o In this example, the module name will be isdn.o. Kbuild will - compile the objects listed in $(isdn-objs) and then run + compile the objects listed in $(isdn-y) and then run "$(LD) -r" on the list of these files to generate isdn.o. - Kbuild recognises objects used for composite objects by the suffix - -objs, and the suffix -y. This allows the Makefiles to use - the value of a CONFIG_ symbol to determine if an object is part - of a composite object. + Due to kbuild recognizing $(<module_name>-y) for composite objects, + you can use the value of a CONFIG_ symbol to optionally include an + object file as part of a composite object. Example: #fs/ext2/Makefile - obj-$(CONFIG_EXT2_FS) += ext2.o - ext2-y := balloc.o bitmap.o - ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o + obj-$(CONFIG_EXT2_FS) += ext2.o + ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \ + namei.o super.o symlink.o + ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \ + xattr_trusted.o - In this example, xattr.o is only part of the composite object - ext2.o if $(CONFIG_EXT2_FS_XATTR) evaluates to 'y'. + In this example, xattr.o, xattr_user.o and xattr_trusted.o are only + part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR) + evaluates to 'y'. Note: Of course, when you are building objects into the kernel, the syntax above will also work. So, if you have CONFIG_EXT2_FS=y, @@ -244,12 +244,12 @@ more details, with real examples. may contain both a built-in.o and a lib.a file. Example: - #arch/i386/lib/Makefile - lib-y := checksum.o delay.o + #arch/x86/lib/Makefile + lib-y := delay.o - This will create a library lib.a based on checksum.o and delay.o. - For kbuild to actually recognize that there is a lib.a being built, - the directory shall be listed in libs-y. + This will create a library lib.a based on delay.o. For kbuild to + actually recognize that there is a lib.a being built, the directory + shall be listed in libs-y. See also "6.3 List directories to visit when descending". Use of lib-y is normally restricted to lib/ and arch/*/lib. @@ -284,43 +284,40 @@ more details, with real examples. --- 3.7 Compilation flags ccflags-y, asflags-y and ldflags-y - The three flags listed above applies only to the kbuild makefile - where they are assigned. They are used for all the normal - cc, as and ld invocation happenign during a recursive build. + These three flags apply only to the kbuild makefile in which they + are assigned. They are used for all the normal cc, as and ld + invocations happening during a recursive build. Note: Flags with the same behaviour were previously named: EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS. - They are yet supported but their use are deprecated. + They are still supported but their usage is deprecated. - ccflags-y specifies options for compiling C files with $(CC). + ccflags-y specifies options for compiling with $(CC). Example: - # drivers/sound/emu10k1/Makefile - ccflags-y += -I$(obj) - ccflags-$(DEBUG) += -DEMU10K1_DEBUG - + # drivers/acpi/Makefile + ccflags-y := -Os + ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT This variable is necessary because the top Makefile owns the variable $(KBUILD_CFLAGS) and uses it for compilation flags for the entire tree. - asflags-y is a similar string for per-directory options - when compiling assembly language source. + asflags-y specifies options for assembling with $(AS). Example: - #arch/x86_64/kernel/Makefile - asflags-y := -traditional + #arch/sparc/kernel/Makefile + asflags-y := -ansi - - ldflags-y is a string for per-directory options to $(LD). + ldflags-y specifies options for linking with $(LD). Example: - #arch/m68k/fpsp040/Makefile - ldflags-y := -x + #arch/cris/boot/compressed/Makefile + ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds subdir-ccflags-y, subdir-asflags-y - The two flags listed above are similar to ccflags-y and as-falgs-y. - The difference is that the subdir- variants has effect for the kbuild - file where tey are present and all subdirectories. + The two flags listed above are similar to ccflags-y and asflags-y. + The difference is that the subdir- variants have effect for the kbuild + file where they are present and all subdirectories. Options specified using subdir-* are added to the commandline before the options specified using the non-subdir variants. @@ -340,18 +337,18 @@ more details, with real examples. CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \ -DGDTH_STATISTICS - CFLAGS_seagate.o = -DARBITRATE -DPARITY -DSEAGATE_USE_ASM - These three lines specify compilation flags for aha152x.o, - gdth.o, and seagate.o + These two lines specify compilation flags for aha152x.o and gdth.o. $(AFLAGS_$@) is a similar feature for source files in assembly languages. Example: # arch/arm/kernel/Makefile - AFLAGS_head-armv.o := -DTEXTADDR=$(TEXTADDR) -traditional - AFLAGS_head-armo.o := -DTEXTADDR=$(TEXTADDR) -traditional + AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET) + AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312 + AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt + --- 3.9 Dependency tracking @@ -1200,14 +1197,14 @@ When kbuild executes, the following steps are followed (roughly): === 7 Kbuild syntax for exported headers The kernel include a set of headers that is exported to userspace. -Many headers can be exported as-is but other headers requires a +Many headers can be exported as-is but other headers require a minimal pre-processing before they are ready for user-space. The pre-processing does: - drop kernel specific annotations - drop include of compiler.h -- drop all sections that is kernel internat (guarded by ifdef __KERNEL__) +- drop all sections that are kernel internal (guarded by ifdef __KERNEL__) -Each relevant directory contain a file name "Kbuild" which specify the +Each relevant directory contains a file name "Kbuild" which specifies the headers to be exported. See subsequent chapter for the syntax of the Kbuild file. @@ -1254,11 +1251,6 @@ See subsequent chapter for the syntax of the Kbuild file. will be located in the directory "include/linux" when exported. - --- 7.4 unifdef-y (deprecated) - - unifdef-y is deprecated. A direct replacement is header-y. - - === 8 Kbuild Variables The top Makefile exports the following variables: diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.txt index 0767cf69c69..3fb39e0116b 100644 --- a/Documentation/kbuild/modules.txt +++ b/Documentation/kbuild/modules.txt @@ -1,215 +1,185 @@ +Building External Modules -In this document you will find information about: -- how to build external modules -- how to make your module use the kbuild infrastructure -- how kbuild will install a kernel -- how to install modules in a non-standard location +This document describes how to build an out-of-tree kernel module. === Table of Contents === 1 Introduction - === 2 How to build external modules - --- 2.1 Building external modules - --- 2.2 Available targets - --- 2.3 Available options - --- 2.4 Preparing the kernel tree for module build - --- 2.5 Building separate files for a module - === 3. Example commands - === 4. Creating a kbuild file for an external module - === 5. Include files - --- 5.1 How to include files from the kernel include dir - --- 5.2 External modules using an include/ dir - --- 5.3 External modules using several directories - === 6. Module installation - --- 6.1 INSTALL_MOD_PATH - --- 6.2 INSTALL_MOD_DIR - === 7. Module versioning & Module.symvers - --- 7.1 Symbols from the kernel (vmlinux + modules) - --- 7.2 Symbols and external modules - --- 7.3 Symbols from another external module - === 8. Tips & Tricks - --- 8.1 Testing for CONFIG_FOO_BAR + === 2 How to Build External Modules + --- 2.1 Command Syntax + --- 2.2 Options + --- 2.3 Targets + --- 2.4 Building Separate Files + === 3. Creating a Kbuild File for an External Module + --- 3.1 Shared Makefile + --- 3.2 Separate Kbuild file and Makefile + --- 3.3 Binary Blobs + --- 3.4 Building Multiple Modules + === 4. Include Files + --- 4.1 Kernel Includes + --- 4.2 Single Subdirectory + --- 4.3 Several Subdirectories + === 5. Module Installation + --- 5.1 INSTALL_MOD_PATH + --- 5.2 INSTALL_MOD_DIR + === 6. Module Versioning + --- 6.1 Symbols From the Kernel (vmlinux + modules) + --- 6.2 Symbols and External Modules + --- 6.3 Symbols From Another External Module + === 7. Tips & Tricks + --- 7.1 Testing for CONFIG_FOO_BAR === 1. Introduction -kbuild includes functionality for building modules both -within the kernel source tree and outside the kernel source tree. -The latter is usually referred to as external or "out-of-tree" -modules and is used both during development and for modules that -are not planned to be included in the kernel tree. +"kbuild" is the build system used by the Linux kernel. Modules must use +kbuild to stay compatible with changes in the build infrastructure and +to pick up the right flags to "gcc." Functionality for building modules +both in-tree and out-of-tree is provided. The method for building +either is similar, and all modules are initially developed and built +out-of-tree. -What is covered within this file is mainly information to authors -of modules. The author of an external module should supply -a makefile that hides most of the complexity, so one only has to type -'make' to build the module. A complete example will be presented in -chapter 4, "Creating a kbuild file for an external module". +Covered in this document is information aimed at developers interested +in building out-of-tree (or "external") modules. The author of an +external module should supply a makefile that hides most of the +complexity, so one only has to type "make" to build the module. This is +easily accomplished, and a complete example will be presented in +section 3. -=== 2. How to build external modules +=== 2. How to Build External Modules -kbuild offers functionality to build external modules, with the -prerequisite that there is a pre-built kernel available with full source. -A subset of the targets available when building the kernel is available -when building an external module. +To build external modules, you must have a prebuilt kernel available +that contains the configuration and header files used in the build. +Also, the kernel must have been built with modules enabled. If you are +using a distribution kernel, there will be a package for the kernel you +are running provided by your distribution. ---- 2.1 Building external modules +An alternative is to use the "make" target "modules_prepare." This will +make sure the kernel contains the information required. The target +exists solely as a simple way to prepare a kernel source tree for +building external modules. - Use the following command to build an external module: +NOTE: "modules_prepare" will not build Module.symvers even if +CONFIG_MODVERSIONS is set; therefore, a full kernel build needs to be +executed to make module versioning work. - make -C <path-to-kernel> M=`pwd` +--- 2.1 Command Syntax - For the running kernel use: + The command to build an external module is: - make -C /lib/modules/`uname -r`/build M=`pwd` + $ make -C <path_to_kernel_src> M=$PWD - For the above command to succeed, the kernel must have been - built with modules enabled. + The kbuild system knows that an external module is being built + due to the "M=<dir>" option given in the command. - To install the modules that were just built: + To build against the running kernel use: - make -C <path-to-kernel> M=`pwd` modules_install + $ make -C /lib/modules/`uname -r`/build M=$PWD - More complex examples will be shown later, the above should - be enough to get you started. + Then to install the module(s) just built, add the target + "modules_install" to the command: ---- 2.2 Available targets + $ make -C /lib/modules/`uname -r`/build M=$PWD modules_install - $KDIR refers to the path to the kernel source top-level directory +--- 2.2 Options - make -C $KDIR M=`pwd` - Will build the module(s) located in current directory. - All output files will be located in the same directory - as the module source. - No attempts are made to update the kernel source, and it is - a precondition that a successful make has been executed - for the kernel. + ($KDIR refers to the path of the kernel source directory.) - make -C $KDIR M=`pwd` modules - The modules target is implied when no target is given. - Same functionality as if no target was specified. - See description above. + make -C $KDIR M=$PWD - make -C $KDIR M=`pwd` modules_install - Install the external module(s). - Installation default is in /lib/modules/<kernel-version>/extra, - but may be prefixed with INSTALL_MOD_PATH - see separate - chapter. + -C $KDIR + The directory where the kernel source is located. + "make" will actually change to the specified directory + when executing and will change back when finished. - make -C $KDIR M=`pwd` clean - Remove all generated files for the module - the kernel - source directory is not modified. + M=$PWD + Informs kbuild that an external module is being built. + The value given to "M" is the absolute path of the + directory where the external module (kbuild file) is + located. - make -C $KDIR M=`pwd` help - help will list the available target when building external - modules. +--- 2.3 Targets ---- 2.3 Available options: + When building an external module, only a subset of the "make" + targets are available. - $KDIR refers to the path to the kernel source top-level directory + make -C $KDIR M=$PWD [target] - make -C $KDIR - Used to specify where to find the kernel source. - '$KDIR' represent the directory where the kernel source is. - Make will actually change directory to the specified directory - when executed but change back when finished. + The default will build the module(s) located in the current + directory, so a target does not need to be specified. All + output files will also be generated in this directory. No + attempts are made to update the kernel source, and it is a + precondition that a successful "make" has been executed for the + kernel. - make -C $KDIR M=`pwd` - M= is used to tell kbuild that an external module is - being built. - The option given to M= is the directory where the external - module (kbuild file) is located. - When an external module is being built only a subset of the - usual targets are available. + modules + The default target for external modules. It has the + same functionality as if no target was specified. See + description above. - make -C $KDIR SUBDIRS=`pwd` - Same as M=. The SUBDIRS= syntax is kept for backwards - compatibility. + modules_install + Install the external module(s). The default location is + /lib/modules/<kernel_release>/extra/, but a prefix may + be added with INSTALL_MOD_PATH (discussed in section 5). ---- 2.4 Preparing the kernel tree for module build + clean + Remove all generated files in the module directory only. - To make sure the kernel contains the information required to - build external modules the target 'modules_prepare' must be used. - 'modules_prepare' exists solely as a simple way to prepare - a kernel source tree for building external modules. - Note: modules_prepare will not build Module.symvers even if - CONFIG_MODVERSIONS is set. Therefore a full kernel build - needs to be executed to make module versioning work. + help + List the available targets for external modules. ---- 2.5 Building separate files for a module - It is possible to build single files which are part of a module. - This works equally well for the kernel, a module and even for - external modules. - Examples (module foo.ko, consist of bar.o, baz.o): - make -C $KDIR M=`pwd` bar.lst - make -C $KDIR M=`pwd` bar.o - make -C $KDIR M=`pwd` foo.ko - make -C $KDIR M=`pwd` / - - -=== 3. Example commands - -This example shows the actual commands to be executed when building -an external module for the currently running kernel. -In the example below, the distribution is supposed to use the -facility to locate output files for a kernel compile in a different -directory than the kernel source - but the examples will also work -when the source and the output files are mixed in the same directory. +--- 2.4 Building Separate Files -# Kernel source -/lib/modules/<kernel-version>/source -> /usr/src/linux-<version> - -# Output from kernel compile -/lib/modules/<kernel-version>/build -> /usr/src/linux-<version>-up - -Change to the directory where the kbuild file is located and execute -the following commands to build the module: + It is possible to build single files that are part of a module. + This works equally well for the kernel, a module, and even for + external modules. - cd /home/user/src/module - make -C /usr/src/`uname -r`/source \ - O=/lib/modules/`uname-r`/build \ - M=`pwd` + Example (The module foo.ko, consist of bar.o and baz.o): + make -C $KDIR M=$PWD bar.lst + make -C $KDIR M=$PWD baz.o + make -C $KDIR M=$PWD foo.ko + make -C $KDIR M=$PWD / -Then, to install the module use the following command: - make -C /usr/src/`uname -r`/source \ - O=/lib/modules/`uname-r`/build \ - M=`pwd` \ - modules_install +=== 3. Creating a Kbuild File for an External Module -If you look closely you will see that this is the same command as -listed before - with the directories spelled out. +In the last section we saw the command to build a module for the +running kernel. The module is not actually built, however, because a +build file is required. Contained in this file will be the name of +the module(s) being built, along with the list of requisite source +files. The file may be as simple as a single line: -The above are rather long commands, and the following chapter -lists a few tricks to make it all easier. + obj-m := <module_name>.o +The kbuild system will build <module_name>.o from <module_name>.c, +and, after linking, will result in the kernel module <module_name>.ko. +The above line can be put in either a "Kbuild" file or a "Makefile." +When the module is built from multiple sources, an additional line is +needed listing the files: -=== 4. Creating a kbuild file for an external module + <module_name>-y := <src1>.o <src2>.o ... -kbuild is the build system for the kernel, and external modules -must use kbuild to stay compatible with changes in the build system -and to pick up the right flags to gcc etc. +NOTE: Further documentation describing the syntax used by kbuild is +located in Documentation/kbuild/makefiles.txt. -The kbuild file used as input shall follow the syntax described -in Documentation/kbuild/makefiles.txt. This chapter will introduce a few -more tricks to be used when dealing with external modules. +The examples below demonstrate how to create a build file for the +module 8123.ko, which is built from the following files: -In the following a Makefile will be created for a module with the -following files: 8123_if.c 8123_if.h 8123_pci.c 8123_bin.o_shipped <= Binary blob ---- 4.1 Shared Makefile for module and kernel +--- 3.1 Shared Makefile - An external module always includes a wrapper Makefile supporting - building the module using 'make' with no arguments. - The Makefile provided will most likely include additional - functionality such as test targets etc. and this part shall - be filtered away from kbuild since it may impact kbuild if - name clashes occurs. + An external module always includes a wrapper makefile that + supports building the module using "make" with no arguments. + This target is not used by kbuild; it is only for convenience. + Additional functionality, such as test targets, can be included + but should be filtered out from kbuild due to possible name + clashes. Example 1: --> filename: Makefile @@ -219,11 +189,11 @@ following files: 8123-y := 8123_if.o 8123_pci.o 8123_bin.o else - # Normal Makefile + # normal makefile + KDIR ?= /lib/modules/`uname -r`/build - KERNELDIR := /lib/modules/`uname -r`/build - all:: - $(MAKE) -C $(KERNELDIR) M=`pwd` $@ + default: + $(MAKE) -C $(KDIR) M=$$PWD # Module specific targets genbin: @@ -231,15 +201,20 @@ following files: endif - In example 1, the check for KERNELRELEASE is used to separate - the two parts of the Makefile. kbuild will only see the two - assignments whereas make will see everything except the two - kbuild assignments. + The check for KERNELRELEASE is used to separate the two parts + of the makefile. In the example, kbuild will only see the two + assignments, whereas "make" will see everything except these + two assignments. This is due to two passes made on the file: + the first pass is by the "make" instance run on the command + line; the second pass is by the kbuild system, which is + initiated by the parameterized "make" in the default target. + +--- 3.2 Separate Kbuild File and Makefile - In recent versions of the kernel, kbuild will look for a file named - Kbuild and as second option look for a file named Makefile. - Utilising the Kbuild file makes us split up the Makefile in example 1 - into two files as shown in example 2: + In newer versions of the kernel, kbuild will first look for a + file named "Kbuild," and only if that is not found, will it + then look for a makefile. Utilizing a "Kbuild" file allows us + to split up the makefile from example 1 into two files: Example 2: --> filename: Kbuild @@ -247,20 +222,21 @@ following files: 8123-y := 8123_if.o 8123_pci.o 8123_bin.o --> filename: Makefile - KERNELDIR := /lib/modules/`uname -r`/build - all:: - $(MAKE) -C $(KERNELDIR) M=`pwd` $@ + KDIR ?= /lib/modules/`uname -r`/build + + default: + $(MAKE) -C $(KDIR) M=$$PWD # Module specific targets genbin: echo "X" > 8123_bin.o_shipped + The split in example 2 is questionable due to the simplicity of + each file; however, some external modules use makefiles + consisting of several hundred lines, and here it really pays + off to separate the kbuild part from the rest. - In example 2, we are down to two fairly simple files and for simple - files as used in this example the split is questionable. But some - external modules use Makefiles of several hundred lines and here it - really pays off to separate the kbuild part from the rest. - Example 3 shows a backward compatible version. + The next example shows a backward compatible version. Example 3: --> filename: Kbuild @@ -269,13 +245,15 @@ following files: --> filename: Makefile ifneq ($(KERNELRELEASE),) + # kbuild part of makefile include Kbuild + else - # Normal Makefile + # normal makefile + KDIR ?= /lib/modules/`uname -r`/build - KERNELDIR := /lib/modules/`uname -r`/build - all:: - $(MAKE) -C $(KERNELDIR) M=`pwd` $@ + default: + $(MAKE) -C $(KDIR) M=$$PWD # Module specific targets genbin: @@ -283,260 +261,271 @@ following files: endif - The trick here is to include the Kbuild file from Makefile, so - if an older version of kbuild picks up the Makefile, the Kbuild - file will be included. + Here the "Kbuild" file is included from the makefile. This + allows an older version of kbuild, which only knows of + makefiles, to be used when the "make" and kbuild parts are + split into separate files. ---- 4.2 Binary blobs included in a module +--- 3.3 Binary Blobs - Some external modules needs to include a .o as a blob. kbuild - has support for this, but requires the blob file to be named - <filename>_shipped. In our example the blob is named - 8123_bin.o_shipped and when the kbuild rules kick in the file - 8123_bin.o is created as a simple copy off the 8213_bin.o_shipped file - with the _shipped part stripped of the filename. - This allows the 8123_bin.o filename to be used in the assignment to - the module. + Some external modules need to include an object file as a blob. + kbuild has support for this, but requires the blob file to be + named <filename>_shipped. When the kbuild rules kick in, a copy + of <filename>_shipped is created with _shipped stripped off, + giving us <filename>. This shortened filename can be used in + the assignment to the module. + + Throughout this section, 8123_bin.o_shipped has been used to + build the kernel module 8123.ko; it has been included as + 8123_bin.o. - Example 4: - obj-m := 8123.o 8123-y := 8123_if.o 8123_pci.o 8123_bin.o - In example 4, there is no distinction between the ordinary .c/.h files - and the binary file. But kbuild will pick up different rules to create - the .o file. + Although there is no distinction between the ordinary source + files and the binary file, kbuild will pick up different rules + when creating the object file for the module. + +--- 3.4 Building Multiple Modules + kbuild supports building multiple modules with a single build + file. For example, if you wanted to build two modules, foo.ko + and bar.ko, the kbuild lines would be: -=== 5. Include files + obj-m := foo.o bar.o + foo-y := <foo_srcs> + bar-y := <bar_srcs> -Include files are a necessity when a .c file uses something from other .c -files (not strictly in the sense of C, but if good programming practice is -used). Any module that consists of more than one .c file will have a .h file -for one of the .c files. + It is that simple! -- If the .h file only describes a module internal interface, then the .h file - shall be placed in the same directory as the .c files. -- If the .h files describe an interface used by other parts of the kernel - located in different directories, the .h files shall be located in - include/linux/ or other include/ directories as appropriate. -One exception for this rule is larger subsystems that have their own directory -under include/ such as include/scsi. Another exception is arch-specific -.h files which are located under include/asm-$(ARCH)/*. +=== 4. Include Files -External modules have a tendency to locate include files in a separate include/ -directory and therefore need to deal with this in their kbuild file. +Within the kernel, header files are kept in standard locations +according to the following rule: ---- 5.1 How to include files from the kernel include dir + * If the header file only describes the internal interface of a + module, then the file is placed in the same directory as the + source files. + * If the header file describes an interface used by other parts + of the kernel that are located in different directories, then + the file is placed in include/linux/. - When a module needs to include a file from include/linux/, then one - just uses: + NOTE: There are two notable exceptions to this rule: larger + subsystems have their own directory under include/, such as + include/scsi; and architecture specific headers are located + under arch/$(ARCH)/include/. - #include <linux/modules.h> +--- 4.1 Kernel Includes - kbuild will make sure to add options to gcc so the relevant - directories are searched. - Likewise for .h files placed in the same directory as the .c file. + To include a header file located under include/linux/, simply + use: - #include "8123_if.h" + #include <linux/module.h> - will do the job. + kbuild will add options to "gcc" so the relevant directories + are searched. ---- 5.2 External modules using an include/ dir +--- 4.2 Single Subdirectory - External modules often locate their .h files in a separate include/ - directory although this is not usual kernel style. When an external - module uses an include/ dir then kbuild needs to be told so. - The trick here is to use either EXTRA_CFLAGS (take effect for all .c - files) or CFLAGS_$F.o (take effect only for a single file). + External modules tend to place header files in a separate + include/ directory where their source is located, although this + is not the usual kernel style. To inform kbuild of the + directory, use either ccflags-y or CFLAGS_<filename>.o. - In our example, if we move 8123_if.h to a subdirectory named include/ - the resulting Kbuild file would look like: + Using the example from section 3, if we moved 8123_if.h to a + subdirectory named include, the resulting kbuild file would + look like: --> filename: Kbuild - obj-m := 8123.o + obj-m := 8123.o - EXTRA_CFLAGS := -Iinclude + ccflags-y := -Iinclude 8123-y := 8123_if.o 8123_pci.o 8123_bin.o - Note that in the assignment there is no space between -I and the path. - This is a kbuild limitation: there must be no space present. + Note that in the assignment there is no space between -I and + the path. This is a limitation of kbuild: there must be no + space present. ---- 5.3 External modules using several directories - - If an external module does not follow the usual kernel style, but - decides to spread files over several directories, then kbuild can - handle this too. +--- 4.3 Several Subdirectories + kbuild can handle files that are spread over several directories. Consider the following example: - | - +- src/complex_main.c - | +- hal/hardwareif.c - | +- hal/include/hardwareif.h - +- include/complex.h - - To build a single module named complex.ko, we then need the following + . + |__ src + | |__ complex_main.c + | |__ hal + | |__ hardwareif.c + | |__ include + | |__ hardwareif.h + |__ include + |__ complex.h + + To build the module complex.ko, we then need the following kbuild file: - Kbuild: + --> filename: Kbuild obj-m := complex.o complex-y := src/complex_main.o complex-y += src/hal/hardwareif.o - EXTRA_CFLAGS := -I$(src)/include - EXTRA_CFLAGS += -I$(src)src/hal/include + ccflags-y := -I$(src)/include + ccflags-y += -I$(src)/src/hal/include + As you can see, kbuild knows how to handle object files located + in other directories. The trick is to specify the directory + relative to the kbuild file's location. That being said, this + is NOT recommended practice. - kbuild knows how to handle .o files located in another directory - - although this is NOT recommended practice. The syntax is to specify - the directory relative to the directory where the Kbuild file is - located. + For the header files, kbuild must be explicitly told where to + look. When kbuild executes, the current directory is always the + root of the kernel tree (the argument to "-C") and therefore an + absolute path is needed. $(src) provides the absolute path by + pointing to the directory where the currently executing kbuild + file is located. - To find the .h files, we have to explicitly tell kbuild where to look - for the .h files. When kbuild executes, the current directory is always - the root of the kernel tree (argument to -C) and therefore we have to - tell kbuild how to find the .h files using absolute paths. - $(src) will specify the absolute path to the directory where the - Kbuild file are located when being build as an external module. - Therefore -I$(src)/ is used to point out the directory of the Kbuild - file and any additional path are just appended. -=== 6. Module installation +=== 5. Module Installation -Modules which are included in the kernel are installed in the directory: +Modules which are included in the kernel are installed in the +directory: - /lib/modules/$(KERNELRELEASE)/kernel + /lib/modules/$(KERNELRELEASE)/kernel/ -External modules are installed in the directory: +And external modules are installed in: - /lib/modules/$(KERNELRELEASE)/extra + /lib/modules/$(KERNELRELEASE)/extra/ ---- 6.1 INSTALL_MOD_PATH +--- 5.1 INSTALL_MOD_PATH - Above are the default directories, but as always, some level of - customization is possible. One can prefix the path using the variable - INSTALL_MOD_PATH: + Above are the default directories but as always some level of + customization is possible. A prefix can be added to the + installation path using the variable INSTALL_MOD_PATH: $ make INSTALL_MOD_PATH=/frodo modules_install - => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel - - INSTALL_MOD_PATH may be set as an ordinary shell variable or as in the - example above, can be specified on the command line when calling make. - INSTALL_MOD_PATH has effect both when installing modules included in - the kernel as well as when installing external modules. + => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/ ---- 6.2 INSTALL_MOD_DIR + INSTALL_MOD_PATH may be set as an ordinary shell variable or, + as shown above, can be specified on the command line when + calling "make." This has effect when installing both in-tree + and out-of-tree modules. - When installing external modules they are by default installed to a - directory under /lib/modules/$(KERNELRELEASE)/extra, but one may wish - to locate modules for a specific functionality in a separate - directory. For this purpose, one can use INSTALL_MOD_DIR to specify an - alternative name to 'extra'. +--- 5.2 INSTALL_MOD_DIR - $ make INSTALL_MOD_DIR=gandalf -C KERNELDIR \ - M=`pwd` modules_install - => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf + External modules are by default installed to a directory under + /lib/modules/$(KERNELRELEASE)/extra/, but you may wish to + locate modules for a specific functionality in a separate + directory. For this purpose, use INSTALL_MOD_DIR to specify an + alternative name to "extra." + $ make INSTALL_MOD_DIR=gandalf -C $KDIR \ + M=$PWD modules_install + => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/ -=== 7. Module versioning & Module.symvers -Module versioning is enabled by the CONFIG_MODVERSIONS tag. +=== 6. Module Versioning -Module versioning is used as a simple ABI consistency check. The Module -versioning creates a CRC value of the full prototype for an exported symbol and -when a module is loaded/used then the CRC values contained in the kernel are -compared with similar values in the module. If they are not equal, then the -kernel refuses to load the module. +Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used +as a simple ABI consistency check. A CRC value of the full prototype +for an exported symbol is created. When a module is loaded/used, the +CRC values contained in the kernel are compared with similar values in +the module; if they are not equal, the kernel refuses to load the +module. -Module.symvers contains a list of all exported symbols from a kernel build. +Module.symvers contains a list of all exported symbols from a kernel +build. ---- 7.1 Symbols from the kernel (vmlinux + modules) +--- 6.1 Symbols From the Kernel (vmlinux + modules) - During a kernel build, a file named Module.symvers will be generated. - Module.symvers contains all exported symbols from the kernel and - compiled modules. For each symbols, the corresponding CRC value - is stored too. + During a kernel build, a file named Module.symvers will be + generated. Module.symvers contains all exported symbols from + the kernel and compiled modules. For each symbol, the + corresponding CRC value is also stored. The syntax of the Module.symvers file is: - <CRC> <Symbol> <module> - Sample: + <CRC> <Symbol> <module> + 0x2d036834 scsi_remove_host drivers/scsi/scsi_mod - For a kernel build without CONFIG_MODVERSIONS enabled, the crc - would read: 0x00000000 + For a kernel build without CONFIG_MODVERSIONS enabled, the CRC + would read 0x00000000. Module.symvers serves two purposes: - 1) It lists all exported symbols both from vmlinux and all modules - 2) It lists the CRC if CONFIG_MODVERSIONS is enabled - ---- 7.2 Symbols and external modules - - When building an external module, the build system needs access to - the symbols from the kernel to check if all external symbols are - defined. This is done in the MODPOST step and to obtain all - symbols, modpost reads Module.symvers from the kernel. - If a Module.symvers file is present in the directory where - the external module is being built, this file will be read too. - During the MODPOST step, a new Module.symvers file will be written - containing all exported symbols that were not defined in the kernel. - ---- 7.3 Symbols from another external module - - Sometimes, an external module uses exported symbols from another - external module. Kbuild needs to have full knowledge on all symbols - to avoid spitting out warnings about undefined symbols. - Three solutions exist to let kbuild know all symbols of more than - one external module. - The method with a top-level kbuild file is recommended but may be - impractical in certain situations. - - Use a top-level Kbuild file - If you have two modules: 'foo' and 'bar', and 'foo' needs - symbols from 'bar', then one can use a common top-level kbuild - file so both modules are compiled in same build. - - Consider following directory layout: - ./foo/ <= contains the foo module - ./bar/ <= contains the bar module - The top-level Kbuild file would then look like: - - #./Kbuild: (this file may also be named Makefile) + 1) It lists all exported symbols from vmlinux and all modules. + 2) It lists the CRC if CONFIG_MODVERSIONS is enabled. + +--- 6.2 Symbols and External Modules + + When building an external module, the build system needs access + to the symbols from the kernel to check if all external symbols + are defined. This is done in the MODPOST step. modpost obtains + the symbols by reading Module.symvers from the kernel source + tree. If a Module.symvers file is present in the directory + where the external module is being built, this file will be + read too. During the MODPOST step, a new Module.symvers file + will be written containing all exported symbols that were not + defined in the kernel. + +--- 6.3 Symbols From Another External Module + + Sometimes, an external module uses exported symbols from + another external module. kbuild needs to have full knowledge of + all symbols to avoid spitting out warnings about undefined + symbols. Three solutions exist for this situation. + + NOTE: The method with a top-level kbuild file is recommended + but may be impractical in certain situations. + + Use a top-level kbuild file + If you have two modules, foo.ko and bar.ko, where + foo.ko needs symbols from bar.ko, you can use a + common top-level kbuild file so both modules are + compiled in the same build. Consider the following + directory layout: + + ./foo/ <= contains foo.ko + ./bar/ <= contains bar.ko + + The top-level kbuild file would then look like: + + #./Kbuild (or ./Makefile): obj-y := foo/ bar/ - Executing: - make -C $KDIR M=`pwd` + And executing + + $ make -C $KDIR M=$PWD - will then do the expected and compile both modules with full - knowledge on symbols from both modules. + will then do the expected and compile both modules with + full knowledge of symbols from either module. Use an extra Module.symvers file - When an external module is built, a Module.symvers file is - generated containing all exported symbols which are not - defined in the kernel. - To get access to symbols from module 'bar', one can copy the - Module.symvers file from the compilation of the 'bar' module - to the directory where the 'foo' module is built. - During the module build, kbuild will read the Module.symvers - file in the directory of the external module and when the - build is finished, a new Module.symvers file is created - containing the sum of all symbols defined and not part of the - kernel. - - Use make variable KBUILD_EXTRA_SYMBOLS in the Makefile - If it is impractical to copy Module.symvers from another - module, you can assign a space separated list of files to - KBUILD_EXTRA_SYMBOLS in your Makfile. These files will be - loaded by modpost during the initialisation of its symbol - tables. - -=== 8. Tips & Tricks - ---- 8.1 Testing for CONFIG_FOO_BAR - - Modules often need to check for certain CONFIG_ options to decide if - a specific feature shall be included in the module. When kbuild is used - this is done by referencing the CONFIG_ variable directly. + When an external module is built, a Module.symvers file + is generated containing all exported symbols which are + not defined in the kernel. To get access to symbols + from bar.ko, copy the Module.symvers file from the + compilation of bar.ko to the directory where foo.ko is + built. During the module build, kbuild will read the + Module.symvers file in the directory of the external + module, and when the build is finished, a new + Module.symvers file is created containing the sum of + all symbols defined and not part of the kernel. + + Use "make" variable KBUILD_EXTRA_SYMBOLS + If it is impractical to copy Module.symvers from + another module, you can assign a space separated list + of files to KBUILD_EXTRA_SYMBOLS in your build file. + These files will be loaded by modpost during the + initialization of its symbol tables. + + +=== 7. Tips & Tricks + +--- 7.1 Testing for CONFIG_FOO_BAR + + Modules often need to check for certain CONFIG_ options to + decide if a specific feature is included in the module. In + kbuild this is done by referencing the CONFIG_ variable + directly. #fs/ext2/Makefile obj-$(CONFIG_EXT2_FS) += ext2.o @@ -544,9 +533,9 @@ Module.symvers contains a list of all exported symbols from a kernel build. ext2-y := balloc.o bitmap.o dir.o ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o - External modules have traditionally used grep to check for specific - CONFIG_ settings directly in .config. This usage is broken. - As introduced before, external modules shall use kbuild when building - and therefore can use the same methods as in-kernel modules when - testing for CONFIG_ definitions. + External modules have traditionally used "grep" to check for + specific CONFIG_ settings directly in .config. This usage is + broken. As introduced before, external modules should use + kbuild for building and can therefore use the same methods as + in-tree modules when testing for CONFIG_ definitions. diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 27a52b35d55..3d8a97747f7 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -345,5 +345,10 @@ documentation, in <filename>, for the functions listed. section titled <section title> from <filename>. Spaces are allowed in <section title>; do not quote the <section title>. +!C<filename> is replaced by nothing, but makes the tools check that +all DOC: sections and documented functions, symbols, etc. are used. +This makes sense to use when you use !F/!P only and want to verify +that all documentation is included. + Tim. */ <twaugh@redhat.com> diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index ec8d31ee12e..715eaaf1519 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -75,7 +75,7 @@ * Title: "Conceptual Architecture of the Linux Kernel" Author: Ivan T. Bowman. - URL: http://plg.uwaterloo.ca/~itbowman/papers/CS746G-a1.html + URL: http://plg.uwaterloo.ca/ Keywords: conceptual software architecture, extracted design, reverse engineering, system structure. Description: Conceptual software architecture of the Linux kernel, @@ -84,7 +84,7 @@ * Title: "Concrete Architecture of the Linux Kernel" Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan. - URL: http://plg.uwaterloo.ca/~itbowman/papers/CS746G-a2.html + URL: http://plg.uwaterloo.ca/ Keywords: concrete architecture, extracted design, reverse engineering, system structure, dependencies. Description: Concrete architecture of the Linux kernel, @@ -95,7 +95,7 @@ * Title: "Linux as a Case Study: Its Extracted Software Architecture" Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster. - URL: http://plg.uwaterloo.ca/~itbowman/papers/linuxcase.html + URL: http://plg.uwaterloo.ca/ Keywords: software architecture, architecture recovery, redocumentation. Description: Paper appeared at ICSE'99, Los Angeles, May 16-22, @@ -104,7 +104,7 @@ * Title: "Overview of the Virtual File System" Author: Richard Gooch. - URL: http://www.atnf.csiro.au/~rgooch/linux/vfs.txt + URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt Keywords: VFS, File System, mounting filesystems, opening files, dentries, dcache. Description: Brief introduction to the Linux Virtual File System. @@ -267,15 +267,13 @@ * Title: "Kernel API changes from 2.0 to 2.2" Author: Richard Gooch. URL: - http://www.atnf.csiro.au/~rgooch/linux/docs/porting-to-2.2.html + http://www.linuxhq.com/guides/LKMPG/node28.html Keywords: 2.2, changes. Description: Kernel functions/structures/variables which changed from 2.0.x to 2.2.x. * Title: "Kernel API changes from 2.2 to 2.4" Author: Richard Gooch. - URL: - http://www.atnf.csiro.au/~rgooch/linux/docs/porting-to-2.4.html Keywords: 2.4, changes. Description: Kernel functions/structures/variables which changed from 2.2.x to 2.4.x. @@ -290,7 +288,6 @@ * Title: "I/O Event Handling Under Linux" Author: Richard Gooch. - URL: http://www.atnf.csiro.au/~rgooch/linux/docs/io-events.html Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness event queues. Description: From the Introduction: "I/O Event handling is about @@ -386,64 +383,64 @@ * Title: "Porting Device Drivers To Linux 2.2: part II" Author: Alan Cox. - URL: http://www.linux-mag.com/1999-06/gear_01.html + URL: http://www.linux-mag.com/id/238 Keywords: ports, porting. Description: Second part on porting from 2.0 to 2.2 kernels. * Title: "How To Make Sure Your Driver Will Work On The Power Macintosh" Author: Paul Mackerras. - URL: http://www.linux-mag.com/1999-07/gear_01.html + URL: http://www.linux-mag.com/id/261 Keywords: Mac, Power Macintosh, porting, drivers, compatibility. Description: The title says it all. * Title: "An Introduction to SCSI Drivers" Author: Alan Cox. - URL: http://www.linux-mag.com/1999-08/gear_01.html + URL: http://www.linux-mag.com/id/284 Keywords: SCSI, device, driver. Description: The title says it all. * Title: "Advanced SCSI Drivers And Other Tales" Author: Alan Cox. - URL: http://www.linux-mag.com/1999-09/gear_01.html + URL: http://www.linux-mag.com/id/307 Keywords: SCSI, device, driver, advanced. Description: The title says it all. * Title: "Writing Linux Mouse Drivers" Author: Alan Cox. - URL: http://www.linux-mag.com/1999-10/gear_01.html + URL: http://www.linux-mag.com/id/330 Keywords: mouse, driver, gpm. Description: The title says it all. * Title: "More on Mouse Drivers" Author: Alan Cox. - URL: http://www.linux-mag.com/1999-11/gear_01.html + URL: http://www.linux-mag.com/id/356 Keywords: mouse, driver, gpm, races, asynchronous I/O. Description: The title still says it all. * Title: "Writing Video4linux Radio Driver" Author: Alan Cox. - URL: http://www.linux-mag.com/1999-12/gear_01.html + URL: http://www.linux-mag.com/id/381 Keywords: video4linux, driver, radio, radio devices. Description: The title says it all. * Title: "Video4linux Drivers, Part 1: Video-Capture Device" Author: Alan Cox. - URL: http://www.linux-mag.com/2000-01/gear_01.html + URL: http://www.linux-mag.com/id/406 Keywords: video4linux, driver, video capture, capture devices, camera driver. Description: The title says it all. * Title: "Video4linux Drivers, Part 2: Video-capture Devices" Author: Alan Cox. - URL: http://www.linux-mag.com/2000-02/gear_01.html + URL: http://www.linux-mag.com/id/429 Keywords: video4linux, driver, video capture, capture devices, camera driver, control, query capabilities, capability, facility. Description: The title says it all. * Title: "PCI Management in Linux 2.2" Author: Alan Cox. - URL: http://www.linux-mag.com/2000-03/gear_01.html + URL: http://www.linux-mag.com/id/452 Keywords: PCI, bus, bus-mastering. Description: The title says it all. @@ -502,7 +499,7 @@ * Title: "A Linux vm README" Author: Kanoj Sarcar. - URL: http://reality.sgi.com/kanoj_engr/vm229.html + URL: http://kos.enix.org/pub/linux-vmm.html Keywords: virtual memory, mm, pgd, vma, page, page flags, page cache, swap cache, kswapd. Description: Telegraphic, short descriptions and definitions @@ -659,7 +656,7 @@ * Name: "Linux Kernel Source Reference" Author: Thomas Graichen. - URL: http://innominate.org/~graichen/projects/lksr/ + URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4 Keywords: CVS, web, cvsweb, browsing source code. Description: Web interface to a CVS server with the kernel sources. "Here you can have a look at any file of the Linux kernel @@ -682,7 +679,7 @@ produced during the week. Published every Thursday. * Name: "Kernel Traffic" - URL: http://kt.zork.net/kernel-traffic/ + URL: http://kt.earth.li/kernel-traffic/index.html Keywords: linux-kernel mailing list, weekly kernel news. Description: Weekly newsletter covering the most relevant discussions of the linux-kernel mailing list. diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 2b2407d9a6d..ed45e9802aa 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -43,10 +43,11 @@ parameter is applicable: AVR32 AVR32 architecture is enabled. AX25 Appropriate AX.25 support is enabled. BLACKFIN Blackfin architecture is enabled. - DRM Direct Rendering Management support is enabled. EDD BIOS Enhanced Disk Drive Services (EDD) is enabled EFI EFI Partitioning (GPT) is enabled EIDE EIDE/ATAPI support is enabled. + DRM Direct Rendering Management support is enabled. + DYNAMIC_DEBUG Build in debug messages and enable them at runtime FB The frame buffer device is enabled. GCOV GCOV profiling is enabled. HW Appropriate hardware is enabled. @@ -73,7 +74,6 @@ parameter is applicable: MTD MTD (Memory Technology Device) support is enabled. NET Appropriate network support is enabled. NUMA NUMA support is enabled. - GENERIC_TIME The generic timeofday code is enabled. NFS Appropriate NFS support is enabled. OSS OSS sound support is enabled. PV_OPS A paravirtualized kernel is enabled. @@ -89,10 +89,11 @@ parameter is applicable: RAM RAM disk support is enabled. S390 S390 architecture is enabled. SCSI Appropriate SCSI support is enabled. - A lot of drivers has their options described inside of - Documentation/scsi/. + A lot of drivers have their options described inside + the Documentation/scsi/ sub-directory. SECURITY Different security models are enabled. SELINUX SELinux support is enabled. + APPARMOR AppArmor support is enabled. SERIAL Serial support is enabled. SH SuperH architecture is enabled. SMP The kernel is an SMP kernel. @@ -115,6 +116,7 @@ parameter is applicable: More X86-64 boot options can be found in Documentation/x86/x86_64/boot-options.txt . X86 Either 32bit or 64bit x86 (same as X86-32+X86-64) + XEN Xen support is enabled In addition, the following text indicates that the option: @@ -280,36 +282,17 @@ and is between 256 and 4096 characters. It is defined in the file no: ACPI OperationRegions are not marked as reserved, no further checks are performed. - ad1848= [HW,OSS] - Format: <io>,<irq>,<dma>,<dma2>,<type> - add_efi_memmap [EFI; X86] Include EFI memory map in kernel's map of available physical RAM. - advansys= [HW,SCSI] - See header of drivers/scsi/advansys.c. - - aedsp16= [HW,OSS] Audio Excel DSP 16 - Format: <io>,<irq>,<dma>,<mss_io>,<mpu_io>,<mpu_irq> - See also header of sound/oss/aedsp16.c. - agp= [AGP] { off | try_unsupported } off: disable AGP support try_unsupported: try to drive unsupported chipsets (may crash computer or cause data corruption) - aha152x= [HW,SCSI] - See Documentation/scsi/aha152x.txt. - - aha1542= [HW,SCSI] - Format: <portbase>[,<buson>,<busoff>[,<dmaspeed>]] - - aic7xxx= [HW,SCSI] - See Documentation/scsi/aic7xxx.txt. - - aic79xx= [HW,SCSI] - See Documentation/scsi/aic79xx.txt. + ALSA [HW,ALSA] + See Documentation/sound/alsa/alsa-parameters.txt alignment= [KNL,ARM] Allow the default userspace alignment fault handler @@ -371,8 +354,6 @@ and is between 256 and 4096 characters. It is defined in the file atarimouse= [HW,MOUSE] Atari Mouse - atascsi= [HW,SCSI] Atari SCSI - atkbd.extra= [HW] Enable extra LEDs and keys on IBM RapidAccess, EzKey and similar keyboards @@ -422,10 +403,6 @@ and is between 256 and 4096 characters. It is defined in the file bttv.pll= See Documentation/video4linux/bttv/Insmod-options bttv.tuner= and Documentation/video4linux/bttv/CARDLIST - BusLogic= [HW,SCSI] - See drivers/scsi/BusLogic.c, comment before function - BusLogic_ParseDriverOptions(). - c101= [NET] Moxa C101 synchronous serial card cachesize= [BUGS=X86-32] Override level 2 CPU cache size detection. @@ -468,7 +445,7 @@ and is between 256 and 4096 characters. It is defined in the file clocksource is not available, it defaults to PIT. Format: { pit | tsc | cyclone | pmtmr } - clocksource= [GENERIC_TIME] Override the default clocksource + clocksource= Override the default clocksource Format: <string> Override the default clocksource and use the clocksource with the name specified. @@ -479,7 +456,7 @@ and is between 256 and 4096 characters. It is defined in the file [ARM] imx_timer1,OSTS,netx_timer,mpu_timer2, pxa_timer,timer3,32k_counter,timer0_1 [AVR32] avr32 - [X86-32] pit,hpet,tsc,vmi-timer; + [X86-32] pit,hpet,tsc; scx200_hrt on Geode; cyclone on IBM x440 [MIPS] MIPS [PARISC] cr16 @@ -594,6 +571,10 @@ and is between 256 and 4096 characters. It is defined in the file Format: <port#>,<type> See also Documentation/input/joystick-parport.txt + ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot + time. See Documentation/dynamic-debug-howto.txt for + details. + debug [KNL] Enable kernel debugging (events log level). debug_locks_verbose= @@ -655,8 +636,6 @@ and is between 256 and 4096 characters. It is defined in the file Disable PIN 1 of APIC timer Can be useful to work around chipset bugs. - dmasound= [HW,OSS] Sound subsystem buffers - dma_debug=off If the kernel is compiled with DMA_API_DEBUG support, this option disables the debugging code at boot. @@ -676,8 +655,6 @@ and is between 256 and 4096 characters. It is defined in the file dscc4.setup= [NET] - dtc3181e= [HW,SCSI] - dynamic_printk Enables pr_debug()/dev_dbg() calls if CONFIG_DYNAMIC_PRINTK_DEBUG has been enabled. These can also be switched on/off via @@ -686,8 +663,11 @@ and is between 256 and 4096 characters. It is defined in the file earlycon= [KNL] Output early console device and options. uart[8250],io,<addr>[,options] uart[8250],mmio,<addr>[,options] + uart[8250],mmio32,<addr>[,options] Start an early, polled-mode console on the 8250/16550 UART at the specified I/O port or MMIO address. + MMIO inter-register address stride is either 8bit (mmio) + or 32bit (mmio32). The options are the same as for ttyS, above. earlyprintk= [X86,SH,BLACKFIN] @@ -715,8 +695,6 @@ and is between 256 and 4096 characters. It is defined in the file This is desgined to be used in conjunction with the boot argument: earlyprintk=vga - eata= [HW,SCSI] - edd= [EDD] Format: {"off" | "on" | "skip[mbr]"} @@ -772,12 +750,6 @@ and is between 256 and 4096 characters. It is defined in the file Format: <interval>,<probability>,<space>,<times> See also /Documentation/fault-injection/. - fd_mcs= [HW,SCSI] - See header of drivers/scsi/fd_mcs.c. - - fdomain= [HW,SCSI] - See header of drivers/scsi/fdomain.c. - floppy= [HW] See Documentation/blockdev/floppy.txt. @@ -837,14 +809,9 @@ and is between 256 and 4096 characters. It is defined in the file When zero, profiling data is discarded and associated debugfs files are removed at module unload time. - gdth= [HW,SCSI] - See header of drivers/scsi/gdth.c. - gpt [EFI] Forces disk with valid GPT signature but invalid Protective MBR to be treated as GPT. - gvp11= [HW,SCSI] - hashdist= [KNL,NUMA] Large hashes allocated during boot are distributed across NUMA nodes. Defaults on for 64bit NUMA, off otherwise. @@ -917,9 +884,6 @@ and is between 256 and 4096 characters. It is defined in the file controller i8042.nopnp [HW] Don't use ACPIPnP / PnPBIOS to discover KBD/AUX controllers - i8042.panicblink= - [HW] Frequency with which keyboard LEDs should blink - when kernel panics (default is 0.5 sec) i8042.reset [HW] Reset the controller during init and cleanup i8042.unlock [HW] Unlock (ignore) the keylock @@ -936,9 +900,6 @@ and is between 256 and 4096 characters. It is defined in the file i8k.restricted [HW] Allow controlling fans only if SYS_ADMIN capability is set. - ibmmcascsi= [HW,MCA,SCSI] IBM MicroChannel SCSI adapter - See Documentation/mca.txt. - icn= [HW,ISDN] Format: <io>[,<membase>[,<icn_id>[,<icn_id2>]]] @@ -988,9 +949,6 @@ and is between 256 and 4096 characters. It is defined in the file programs exec'd, files mmap'd for exec, and all files opened for read by uid=0. - in2000= [HW,SCSI] - See header of drivers/scsi/in2000.c. - init= [KNL] Format: <full_path> Run specified binary instead of /sbin/init as init @@ -1028,6 +986,12 @@ and is between 256 and 4096 characters. It is defined in the file result in a hardware IOTLB flush operation as opposed to batching them for performance. + intremap= [X86-64, Intel-IOMMU] + Format: { on (default) | off | nosid } + on enable Interrupt Remapping (default) + off disable Interrupt Remapping + nosid disable Source ID checking + inttest= [IA64] iomem= Disable strict checking of access to MMIO memory @@ -1068,9 +1032,6 @@ and is between 256 and 4096 characters. It is defined in the file See comment before ip2_setup() in drivers/char/ip2/ip2base.c. - ips= [HW,SCSI] Adaptec / IBM ServeRAID controller - See header of drivers/scsi/ips.c. - irqfixup [HW] When an interrupt is not handled search all handlers for it. Intended to get systems with badly broken @@ -1143,9 +1104,12 @@ and is between 256 and 4096 characters. It is defined in the file kgdboc= [KGDB,HW] kgdb over consoles. Requires a tty driver that supports console polling, or a supported polling keyboard driver (non-usb). - Serial only format: <serial_device>[,baud] - keyboard only format: kbd - keyboard and serial format: kbd,<serial_device>[,baud] + Serial only format: <serial_device>[,baud] + keyboard only format: kbd + keyboard and serial format: kbd,<serial_device>[,baud] + Optional Kernel mode setting: + kms, kbd format: kms,kbd + kms, kbd and serial format: kms,kbd,<ser_dev>[,baud] kgdbwait [KGDB] Stop kernel execution and enter the kernel debugger at the earliest opportunity. @@ -1167,9 +1131,13 @@ and is between 256 and 4096 characters. It is defined in the file kvm.oos_shadow= [KVM] Disable out-of-sync shadow paging. Default is 1 (enabled) - kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM. + kvm.mmu_audit= [KVM] This is a R/W parameter which allows audit + KVM MMU at runtime. Default is 0 (off) + kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM. + Default is 1 (enabled) + kvm-amd.npt= [KVM,AMD] Disable nested paging (virtualized MMU) for all guests. Default is 1 (enabled) if in 64bit or 32bit-PAE mode @@ -1343,9 +1311,6 @@ and is between 256 and 4096 characters. It is defined in the file ltpc= [NET] Format: <io>,<irq>,<dma> - mac5380= [HW,SCSI] Format: - <can_queue>,<cmd_per_lun>,<sg_tablesize>,<hostid>,<use_tags> - machvec= [IA64] Force the use of a particular machine-vector (machvec) in a generic kernel. Example: machvec=hpzx1_swiotlb @@ -1367,13 +1332,6 @@ and is between 256 and 4096 characters. It is defined in the file be mounted Format: <1-256> - max_luns= [SCSI] Maximum number of LUNs to probe. - Should be between 1 and 2^32-1. - - max_report_luns= - [SCSI] Maximum number of LUNs received. - Should be between 1 and 16384. - mcatest= [IA-64] mce [X86-32] Machine Check Exception @@ -1523,9 +1481,6 @@ and is between 256 and 4096 characters. It is defined in the file that the amount of memory usable for all allocations is not too small. - mpu401= [HW,OSS] - Format: <io>,<irq> - MTD_Partition= [MTD] Format: <name>,<region-number>,<size>,<offset> @@ -1573,19 +1528,6 @@ and is between 256 and 4096 characters. It is defined in the file n2= [NET] SDL Inc. RISCom/N2 synchronous serial card - NCR_D700= [HW,SCSI] - See header of drivers/scsi/NCR_D700.c. - - ncr5380= [HW,SCSI] - - ncr53c400= [HW,SCSI] - - ncr53c400a= [HW,SCSI] - - ncr53c406a= [HW,SCSI] - - ncr53c8xx= [HW,SCSI] - netdev= [NET] Network devices parameters Format: <irq>,<io>,<mem_start>,<mem_end>,<name> Note that mem_start is often overloaded to mean @@ -1597,15 +1539,17 @@ and is between 256 and 4096 characters. It is defined in the file [NETFILTER] Enable connection tracking flow accounting 0 to disable accounting 1 to enable accounting - Default value depends on CONFIG_NF_CT_ACCT that is - going to be removed in 2.6.29. + Default value is 0. - nfsaddrs= [NFS] + nfsaddrs= [NFS] Deprecated. Use ip= instead. See Documentation/filesystems/nfs/nfsroot.txt. nfsroot= [NFS] nfs root filesystem for disk-less boxes. See Documentation/filesystems/nfs/nfsroot.txt. + nfsrootdebug [NFS] enable nfsroot debugging messages. + See Documentation/filesystems/nfs/nfsroot.txt. + nfs.callback_tcpport= [NFS] set the TCP port on which the NFSv4 callback channel should listen. @@ -1755,11 +1699,14 @@ and is between 256 and 4096 characters. It is defined in the file nointremap [X86-64, Intel-IOMMU] Do not enable interrupt remapping. + [Deprecated - use intremap=off] nointroute [IA-64] nojitter [IA64] Disables jitter checking for ITC timers. + no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver + nolapic [X86-32,APIC] Do not enable or use the local APIC. nolapic_timer [X86-32,APIC] Do not use the local APIC timer. @@ -1780,7 +1727,7 @@ and is between 256 and 4096 characters. It is defined in the file norandmaps Don't use address space randomization. Equivalent to echo 0 > /proc/sys/kernel/randomize_va_space - noreplace-paravirt [X86-32,PV_OPS] Don't patch paravirt_ops + noreplace-paravirt [X86,IA-64,PV_OPS] Don't patch paravirt_ops noreplace-smp [X86-32,SMP] Don't replace SMP instructions with UP alternatives @@ -1812,6 +1759,8 @@ and is between 256 and 4096 characters. It is defined in the file nousb [USB] Disable the USB subsystem + nowatchdog [KNL] Disable the lockup detector. + nowb [ARM] nox2apic [X86-64,APIC] Do not enable x2APIC mode. @@ -1849,9 +1798,6 @@ and is between 256 and 4096 characters. It is defined in the file For example, to override I2C bus2: omap_mux=i2c2_scl.i2c2_scl=0x100,i2c2_sda.i2c2_sda=0x100 - opl3= [HW,OSS] - Format: <io> - oprofile.timer= [HW] Use timer interrupt instead of performance counters @@ -1863,9 +1809,8 @@ and is between 256 and 4096 characters. It is defined in the file perfmon on Intel CPUs instead of the CPU specific event set. - osst= [HW,SCSI] SCSI Tape Driver - Format: <buffer_size>,<write_threshold> - See also Documentation/scsi/st.txt. + OSS [HW,OSS] + See Documentation/sound/oss/oss-parameters.txt panic= [KNL] Kernel behaviour on panic Format: <timeout> @@ -1899,12 +1844,6 @@ and is between 256 and 4096 characters. It is defined in the file Currently this function knows 686a and 8231 chips. Format: [spp|ps2|epp|ecp|ecpepp] - pas2= [HW,OSS] Format: - <io>,<irq>,<dma>,<dma16>,<sb_io>,<sb_irq>,<sb_dma>,<sb_dma16> - - pas16= [HW,SCSI] - See header of drivers/scsi/pas16.c. - pause_on_oops= Halt all CPUs after the first oops has been printed for the specified number of seconds. This is to be used if @@ -1970,6 +1909,8 @@ and is between 256 and 4096 characters. It is defined in the file norom [X86] Do not assign address space to expansion ROMs that do not already have BIOS assigned address ranges. + nobar [X86] Do not assign address space to the + BARs that weren't assigned by the BIOS. 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 @@ -2047,15 +1988,18 @@ and is between 256 and 4096 characters. It is defined in the file force Enable ASPM even on devices that claim not to support it. WARNING: Forcing ASPM on may cause system lockups. + pcie_ports= [PCIE] PCIe ports handling: + auto Ask the BIOS whether or not to use native PCIe services + associated with PCIe ports (PME, hot-plug, AER). Use + them only if that is allowed by the BIOS. + native Use native PCIe services associated with PCIe ports + unconditionally. + compat Treat PCIe ports as PCI-to-PCI bridges, disable the PCIe + ports driver. + pcie_pme= [PCIE,PM] Native PCIe PME signaling options: - Format: {auto|force}[,nomsi] - auto Use native PCIe PME signaling if the BIOS allows the - kernel to control PCIe config registers of root ports. - force Use native PCIe PME signaling even if the BIOS refuses - to allow the kernel to control the relevant PCIe config - registers. nomsi Do not use MSI for native PCIe PME signaling (this makes - all PCIe root ports use INTx for everything). + all PCIe root ports use INTx for all services). pcmv= [HW,PCMCIA] BadgePAD 4 @@ -2171,10 +2115,6 @@ and is between 256 and 4096 characters. It is defined in the file [HW,MOUSE] Controls Logitech smartscroll autorepeat. 0 = disabled, 1 = enabled (default). - pss= [HW,OSS] Personal Sound System (ECHO ESC614) - Format: - <io>,<mss_io>,<mss_irq>,<mss_dma>,<mpu_io>,<mpu_irq> - pt. [PARIDE] See Documentation/blockdev/paride.txt. @@ -2227,9 +2167,19 @@ and is between 256 and 4096 characters. It is defined in the file Reserves a hole at the top of the kernel virtual address space. + reservelow= [X86] + Format: nn[K] + Set the amount of memory to reserve for BIOS at + the bottom of the address space. + reset_devices [KNL] Force drivers to reset the underlying device during initialization. + resource_alloc_from_bottom + Allocate new resources from the beginning of available + space, not the end. If you need to use this, please + report a bug. + resume= [SWSUSP] Specify the partition device for software suspend @@ -2239,6 +2189,11 @@ and is between 256 and 4096 characters. It is defined in the file in <PAGE_SIZE> units (needed only for swap files). See Documentation/power/swsusp-and-swap-files.txt + hibernate= [HIBERNATION] + noresume Don't check if there's a hibernation image + present during boot. + nocompress Don't compress/decompress hibernation images. + retain_initrd [RAM] Keep initrd memory after extraction rhash_entries= [KNL,NET] @@ -2273,30 +2228,6 @@ and is between 256 and 4096 characters. It is defined in the file sched_debug [KNL] Enables verbose scheduler debug messages. - scsi_debug_*= [SCSI] - See drivers/scsi/scsi_debug.c. - - scsi_default_dev_flags= - [SCSI] SCSI default device flags - Format: <integer> - - scsi_dev_flags= [SCSI] Black/white list entry for vendor and model - Format: <vendor>:<model>:<flags> - (flags are integer value) - - scsi_logging_level= [SCSI] a bit mask of logging levels - See drivers/scsi/scsi_logging.h for bits. Also - settable via sysctl at dev.scsi.logging_level - (/proc/sys/dev/scsi/logging_level). - There is also a nice 'scsi_logging_level' script in the - S390-tools package, available for download at - http://www-128.ibm.com/developerworks/linux/linux390/s390-tools-1.5.4.html - - scsi_mod.scan= [SCSI] sync (default) scans SCSI busses as they are - discovered. async scans them in kernel threads, - allowing boot to proceed. none ignores them, expecting - user space to do the scan. - security= [SECURITY] Choose a security module to enable at boot. If this boot parameter is not specified, only the first security module asking for security registration will be @@ -2312,6 +2243,13 @@ and is between 256 and 4096 characters. It is defined in the file If enabled at boot time, /selinux/disable can be used later to disable prior to initial policy load. + apparmor= [APPARMOR] Disable or enable AppArmor at boot time + Format: { "0" | "1" } + See security/apparmor/Kconfig help text + 0 -- disable. + 1 -- enable. + Default value is set via kernel config option. + serialnumber [BUGS=X86-32] shapers= [NET] @@ -2323,9 +2261,6 @@ and is between 256 and 4096 characters. It is defined in the file The parameter means the number of CPUs to show, for example 1 means boot CPU only. - sim710= [SCSI,HW] - See header of drivers/scsi/sim710.c. - simeth= [IA-64] simscsi= @@ -2383,128 +2318,6 @@ and is between 256 and 4096 characters. It is defined in the file 1: Fast pin select (default) 2: ATC IRMode - snd-ad1816a= [HW,ALSA] - - snd-ad1848= [HW,ALSA] - - snd-ali5451= [HW,ALSA] - - snd-als100= [HW,ALSA] - - snd-als4000= [HW,ALSA] - - snd-azt2320= [HW,ALSA] - - snd-cmi8330= [HW,ALSA] - - snd-cmipci= [HW,ALSA] - - snd-cs4231= [HW,ALSA] - - snd-cs4232= [HW,ALSA] - - snd-cs4236= [HW,ALSA] - - snd-cs4281= [HW,ALSA] - - snd-cs46xx= [HW,ALSA] - - snd-dt019x= [HW,ALSA] - - snd-dummy= [HW,ALSA] - - snd-emu10k1= [HW,ALSA] - - snd-ens1370= [HW,ALSA] - - snd-ens1371= [HW,ALSA] - - snd-es968= [HW,ALSA] - - snd-es1688= [HW,ALSA] - - snd-es18xx= [HW,ALSA] - - snd-es1938= [HW,ALSA] - - snd-es1968= [HW,ALSA] - - snd-fm801= [HW,ALSA] - - snd-gusclassic= [HW,ALSA] - - snd-gusextreme= [HW,ALSA] - - snd-gusmax= [HW,ALSA] - - snd-hdsp= [HW,ALSA] - - snd-ice1712= [HW,ALSA] - - snd-intel8x0= [HW,ALSA] - - snd-interwave= [HW,ALSA] - - snd-interwave-stb= - [HW,ALSA] - - snd-korg1212= [HW,ALSA] - - snd-maestro3= [HW,ALSA] - - snd-mpu401= [HW,ALSA] - - snd-mtpav= [HW,ALSA] - - snd-nm256= [HW,ALSA] - - snd-opl3sa2= [HW,ALSA] - - snd-opti92x-ad1848= - [HW,ALSA] - - snd-opti92x-cs4231= - [HW,ALSA] - - snd-opti93x= [HW,ALSA] - - snd-pmac= [HW,ALSA] - - snd-rme32= [HW,ALSA] - - snd-rme96= [HW,ALSA] - - snd-rme9652= [HW,ALSA] - - snd-sb8= [HW,ALSA] - - snd-sb16= [HW,ALSA] - - snd-sbawe= [HW,ALSA] - - snd-serial= [HW,ALSA] - - snd-sgalaxy= [HW,ALSA] - - snd-sonicvibes= [HW,ALSA] - - snd-sun-amd7930= - [HW,ALSA] - - snd-sun-cs4231= [HW,ALSA] - - snd-trident= [HW,ALSA] - - snd-usb-audio= [HW,ALSA,USB] - - snd-via82xx= [HW,ALSA] - - snd-virmidi= [HW,ALSA] - - snd-wavefront= [HW,ALSA] - - snd-ymfpci= [HW,ALSA] - softlockup_panic= [KNL] Should the soft-lockup detector generate panics. @@ -2519,12 +2332,6 @@ and is between 256 and 4096 characters. It is defined in the file spia_pedr= spia_peddr= - sscape= [HW,OSS] - Format: <io>,<irq>,<dma>,<mpu_io>,<mpu_irq> - - st= [HW,SCSI] SCSI tape parameters (buffers, etc.) - See Documentation/scsi/st.txt. - stacktrace [FTRACE] Enabled the stack tracer on boot up. @@ -2582,8 +2389,14 @@ and is between 256 and 4096 characters. It is defined in the file switches= [HW,M68k] - sym53c416= [HW,SCSI] - See header of drivers/scsi/sym53c416.c. + sysfs.deprecated=0|1 [KNL] + Enable/disable old style sysfs layout for old udev + on older distributions. When this option is enabled + very new udev will not work anymore. When this option + is disabled (or CONFIG_SYSFS_DEPRECATED not compiled) + in older udev will not work anymore. + Default depends on CONFIG_SYSFS_DEPRECATED_V2 set in + the kernel configuration. sysrq_always_enabled [KNL] @@ -2591,9 +2404,6 @@ and is between 256 and 4096 characters. It is defined in the file neutralize any effect of /proc/sys/kernel/sysrq. Useful for debugging. - t128= [HW,SCSI] - See header of drivers/scsi/t128.c. - tdfx= [HW,DRM] test_suspend= [SUSPEND] @@ -2630,17 +2440,13 @@ and is between 256 and 4096 characters. It is defined in the file <deci-seconds>: poll all this frequency 0: no polling (default) - tmscsim= [HW,SCSI] - 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. + Default is on. tp720= [HW,PS2] @@ -2661,16 +2467,16 @@ and is between 256 and 4096 characters. It is defined in the file to facilitate early boot debugging. See also Documentation/trace/events.txt - 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. + [x86] noirqtime: Do not use TSC to do irq accounting. + Used to run time disable IRQ_TIME_ACCOUNTING on any + platforms where RDTSC is slow and this accounting + can add overhead. turbografx.map[2|3]= [HW,JOY] TurboGraFX parallel port interface @@ -2678,15 +2484,6 @@ and is between 256 and 4096 characters. It is defined in the file <port#>,<js1>,<js2>,<js3>,<js4>,<js5>,<js6>,<js7> See also Documentation/input/joystick-parport.txt - u14-34f= [HW,SCSI] UltraStor 14F/34F SCSI host adapter - See header of drivers/scsi/u14-34f.c. - - uart401= [HW,OSS] - Format: <io>,<irq> - - uart6850= [HW,OSS] - Format: <io>,<irq> - uhash_entries= [KNL,NET] Set number of hash buckets for UDP/UDP-Lite connections @@ -2852,15 +2649,6 @@ and is between 256 and 4096 characters. It is defined in the file overridden by individual drivers. 0 will hide cursors, 1 will display them. - waveartist= [HW,OSS] - Format: <io>,<irq>,<dma>,<dma2> - - wd33c93= [HW,SCSI] - See header of drivers/scsi/wd33c93.c. - - wd7000= [HW,SCSI] - See header of drivers/scsi/wd7000.c. - watchdog timers [HW,WDT] For information on watchdog timers, see Documentation/watchdog/watchdog-parameters.txt or other driver-specific files in the @@ -2879,6 +2667,18 @@ and is between 256 and 4096 characters. It is defined in the file xd= [HW,XT] Original XT pre-IDE (RLL encoded) disks. xd_geo= See header of drivers/block/xd.c. + xen_emul_unplug= [HW,X86,XEN] + Unplug Xen emulated devices + Format: [unplug0,][unplug1] + ide-disks -- unplug primary master IDE devices + aux-ide-disks -- unplug non-primary-master IDE devices + nics -- unplug network devices + all -- unplug all emulated devices (NICs and IDE disks) + unnecessary -- unplugging emulated devices is + unnecessary even if the host did not respond to + the unplug protocol + never -- do not unplug even if version check succeeds + xirc2ps_cs= [NET,PCMCIA] Format: <irq>,<irq_mask>,<io>,<full_duplex>,<do_sound>,<lockup_hack>[,<irq2>[,<irq3>[,<irq4>]]] @@ -2887,5 +2687,4 @@ ______________________________________________________________________ TODO: - Add documentation for ALSA options. Add more DRM drivers. diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 029fca914c0..e3a55b6091e 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -122,7 +122,7 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 올바른 패치들을 만드는 법에 관한 훌륭한 다른 문서들이 있다. "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 @@ -192,7 +192,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 여러분이 어디서 시작해야 할진 모르지만 커널 개발 커뮤니티에 참여할 수 있는 일들을 찾길 원한다면 리눅스 커널 Janitor 프로젝트를 살펴봐라. - http://janitor.kernelnewbies.org/ + http://kernelnewbies.org/KernelJanitors 그곳은 시작하기에 훌륭한 장소이다. 그곳은 리눅스 커널 소스 트리내에 간단히 정리되고 수정될 수 있는 문제들에 관하여 설명한다. 여러분은 이 프로젝트를 대표하는 개발자들과 일하면서 자신의 패치를 리눅스 커널 트리에 @@ -596,7 +596,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 이것이 무엇인지 더 자세한 것을 알고 싶다면 다음 문서의 ChageLog 항을 봐라. "The Perfect Patch" - http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt + http://userweb.kernel.org/~akpm/stuff/tpp.txt @@ -610,7 +610,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 ---------- -"개발 프로세스"(http://linux.tar.gz/articles/2.6-development_process) 섹션을 +"개발 프로세스"(http://lwn.net/Articles/94386/) 섹션을 작성하는데 있어 참고할 문서를 사용하도록 허락해준 Paolo Ciarrocchi에게 감사한다. 여러분들이 말해야 할 것과 말해서는 안되는 것의 목록 중 일부를 제공해준 Randy Dunlap과 Gerrit Huizenga에게 감사한다. 또한 검토와 의견 그리고 diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt index 6653017680d..741fe66d6ec 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/kprobes.txt @@ -285,6 +285,7 @@ architectures: - sparc64 (Return probes not yet implemented.) - arm - ppc +- mips 3. Configuring Kprobes @@ -541,9 +542,11 @@ Kprobes does not use mutexes or allocate memory except during registration and unregistration. Probe handlers are run with preemption disabled. Depending on the -architecture, handlers may also run with interrupts disabled. In any -case, your handler should not yield the CPU (e.g., by attempting to -acquire a semaphore). +architecture and optimization state, handlers may also run with +interrupts disabled (e.g., kretprobe handlers and optimized kprobe +handlers run without interrupt disabled on x86/x86-64). In any case, +your handler should not yield the CPU (e.g., by attempting to acquire +a semaphore). Since a return probe is implemented by replacing the return address with the trampoline's address, stack backtraces and calls diff --git a/Documentation/kvm/api.txt b/Documentation/kvm/api.txt index a237518e51b..b336266bea5 100644 --- a/Documentation/kvm/api.txt +++ b/Documentation/kvm/api.txt @@ -126,6 +126,10 @@ user fills in the size of the indices array in nmsrs, and in return kvm adjusts nmsrs to reflect the actual number of msrs and fills in the indices array with their numbers. +Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are +not returned in the MSR list, as different vcpus can have a different number +of banks, as set via the KVM_X86_SETUP_MCE ioctl. + 4.4 KVM_CHECK_EXTENSION Capability: basic @@ -160,29 +164,7 @@ Type: vm ioctl Parameters: struct kvm_memory_region (in) Returns: 0 on success, -1 on error -struct kvm_memory_region { - __u32 slot; - __u32 flags; - __u64 guest_phys_addr; - __u64 memory_size; /* bytes */ -}; - -/* for kvm_memory_region::flags */ -#define KVM_MEM_LOG_DIRTY_PAGES 1UL - -This ioctl allows the user to create or modify a guest physical memory -slot. When changing an existing slot, it may be moved in the guest -physical memory space, or its flags may be modified. It may not be -resized. Slots may not overlap. - -The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which -instructs kvm to keep track of writes to memory within the slot. See -the KVM_GET_DIRTY_LOG ioctl. - -It is recommended to use the KVM_SET_USER_MEMORY_REGION ioctl instead -of this API, if available. This newer API allows placing guest memory -at specified locations in the host address space, yielding better -control and easy access. +This ioctl is obsolete and has been removed. 4.6 KVM_CREATE_VCPU @@ -226,17 +208,7 @@ Type: vm ioctl Parameters: struct kvm_memory_alias (in) Returns: 0 (success), -1 (error) -struct kvm_memory_alias { - __u32 slot; /* this has a different namespace than memory slots */ - __u32 flags; - __u64 guest_phys_addr; - __u64 memory_size; - __u64 target_phys_addr; -}; - -Defines a guest physical address space region as an alias to another -region. Useful for aliased address, for example the VGA low memory -window. Should not be used with userspace memory. +This ioctl is obsolete and has been removed. 4.9 KVM_RUN @@ -348,13 +320,13 @@ struct kvm_translation { 4.15 KVM_INTERRUPT Capability: basic -Architectures: x86 +Architectures: x86, ppc Type: vcpu ioctl Parameters: struct kvm_interrupt (in) Returns: 0 on success, -1 on error Queues a hardware interrupt vector to be injected. This is only -useful if in-kernel local APIC is not used. +useful if in-kernel local APIC or equivalent is not used. /* for KVM_INTERRUPT */ struct kvm_interrupt { @@ -362,8 +334,37 @@ struct kvm_interrupt { __u32 irq; }; +X86: + Note 'irq' is an interrupt vector, not an interrupt pin or line. +PPC: + +Queues an external interrupt to be injected. This ioctl is overleaded +with 3 different irq values: + +a) KVM_INTERRUPT_SET + + This injects an edge type external interrupt into the guest once it's ready + to receive interrupts. When injected, the interrupt is done. + +b) KVM_INTERRUPT_UNSET + + This unsets any pending interrupt. + + Only available with KVM_CAP_PPC_UNSET_IRQ. + +c) KVM_INTERRUPT_SET_LEVEL + + This injects a level type external interrupt into the guest context. The + interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET + is triggered. + + Only available with KVM_CAP_PPC_IRQ_LEVEL. + +Note that any value for 'irq' other than the ones stated above is invalid +and incurs unexpected behavior. + 4.16 KVM_DEBUG_GUEST Capability: basic @@ -892,6 +893,198 @@ arguments. This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel irqchip, the multiprocessing state must be maintained by userspace. +4.39 KVM_SET_IDENTITY_MAP_ADDR + +Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR +Architectures: x86 +Type: vm ioctl +Parameters: unsigned long identity (in) +Returns: 0 on success, -1 on error + +This ioctl defines the physical address of a one-page region in the guest +physical address space. The region must be within the first 4GB of the +guest physical address space and must not conflict with any memory slot +or any mmio address. The guest may malfunction if it accesses this memory +region. + +This ioctl is required on Intel-based hosts. This is needed on Intel hardware +because of a quirk in the virtualization implementation (see the internals +documentation when it pops into existence). + +4.40 KVM_SET_BOOT_CPU_ID + +Capability: KVM_CAP_SET_BOOT_CPU_ID +Architectures: x86, ia64 +Type: vm ioctl +Parameters: unsigned long vcpu_id +Returns: 0 on success, -1 on error + +Define which vcpu is the Bootstrap Processor (BSP). Values are the same +as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default +is vcpu 0. + +4.41 KVM_GET_XSAVE + +Capability: KVM_CAP_XSAVE +Architectures: x86 +Type: vcpu ioctl +Parameters: struct kvm_xsave (out) +Returns: 0 on success, -1 on error + +struct kvm_xsave { + __u32 region[1024]; +}; + +This ioctl would copy current vcpu's xsave struct to the userspace. + +4.42 KVM_SET_XSAVE + +Capability: KVM_CAP_XSAVE +Architectures: x86 +Type: vcpu ioctl +Parameters: struct kvm_xsave (in) +Returns: 0 on success, -1 on error + +struct kvm_xsave { + __u32 region[1024]; +}; + +This ioctl would copy userspace's xsave struct to the kernel. + +4.43 KVM_GET_XCRS + +Capability: KVM_CAP_XCRS +Architectures: x86 +Type: vcpu ioctl +Parameters: struct kvm_xcrs (out) +Returns: 0 on success, -1 on error + +struct kvm_xcr { + __u32 xcr; + __u32 reserved; + __u64 value; +}; + +struct kvm_xcrs { + __u32 nr_xcrs; + __u32 flags; + struct kvm_xcr xcrs[KVM_MAX_XCRS]; + __u64 padding[16]; +}; + +This ioctl would copy current vcpu's xcrs to the userspace. + +4.44 KVM_SET_XCRS + +Capability: KVM_CAP_XCRS +Architectures: x86 +Type: vcpu ioctl +Parameters: struct kvm_xcrs (in) +Returns: 0 on success, -1 on error + +struct kvm_xcr { + __u32 xcr; + __u32 reserved; + __u64 value; +}; + +struct kvm_xcrs { + __u32 nr_xcrs; + __u32 flags; + struct kvm_xcr xcrs[KVM_MAX_XCRS]; + __u64 padding[16]; +}; + +This ioctl would set vcpu's xcr to the value userspace specified. + +4.45 KVM_GET_SUPPORTED_CPUID + +Capability: KVM_CAP_EXT_CPUID +Architectures: x86 +Type: system ioctl +Parameters: struct kvm_cpuid2 (in/out) +Returns: 0 on success, -1 on error + +struct kvm_cpuid2 { + __u32 nent; + __u32 padding; + struct kvm_cpuid_entry2 entries[0]; +}; + +#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX 1 +#define KVM_CPUID_FLAG_STATEFUL_FUNC 2 +#define KVM_CPUID_FLAG_STATE_READ_NEXT 4 + +struct kvm_cpuid_entry2 { + __u32 function; + __u32 index; + __u32 flags; + __u32 eax; + __u32 ebx; + __u32 ecx; + __u32 edx; + __u32 padding[3]; +}; + +This ioctl returns x86 cpuid features which are supported by both the hardware +and kvm. Userspace can use the information returned by this ioctl to +construct cpuid information (for KVM_SET_CPUID2) that is consistent with +hardware, kernel, and userspace capabilities, and with user requirements (for +example, the user may wish to constrain cpuid to emulate older hardware, +or for feature consistency across a cluster). + +Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure +with the 'nent' field indicating the number of entries in the variable-size +array 'entries'. If the number of entries is too low to describe the cpu +capabilities, an error (E2BIG) is returned. If the number is too high, +the 'nent' field is adjusted and an error (ENOMEM) is returned. If the +number is just right, the 'nent' field is adjusted to the number of valid +entries in the 'entries' array, which is then filled. + +The entries returned are the host cpuid as returned by the cpuid instruction, +with unknown or unsupported features masked out. Some features (for example, +x2apic), may not be present in the host cpu, but are exposed by kvm if it can +emulate them efficiently. The fields in each entry are defined as follows: + + function: the eax value used to obtain the entry + index: the ecx value used to obtain the entry (for entries that are + affected by ecx) + flags: an OR of zero or more of the following: + KVM_CPUID_FLAG_SIGNIFCANT_INDEX: + if the index field is valid + KVM_CPUID_FLAG_STATEFUL_FUNC: + if cpuid for this function returns different values for successive + invocations; there will be several entries with the same function, + all with this flag set + KVM_CPUID_FLAG_STATE_READ_NEXT: + for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is + the first entry to be read by a cpu + eax, ebx, ecx, edx: the values returned by the cpuid instruction for + this function/index combination + +4.46 KVM_PPC_GET_PVINFO + +Capability: KVM_CAP_PPC_GET_PVINFO +Architectures: ppc +Type: vm ioctl +Parameters: struct kvm_ppc_pvinfo (out) +Returns: 0 on success, !0 on error + +struct kvm_ppc_pvinfo { + __u32 flags; + __u32 hcall[4]; + __u8 pad[108]; +}; + +This ioctl fetches PV specific information that need to be passed to the guest +using the device tree or other means from vm context. + +For now the only implemented piece of information distributed here is an array +of 4 instructions that make up a hypercall. + +If any additional field gets added to this structure later on, a bit for that +additional piece of information will be set in the flags bitmap. + 5. The kvm_run structure Application code obtains a pointer to the kvm_run structure by diff --git a/Documentation/kvm/mmu.txt b/Documentation/kvm/mmu.txt index aaed6ab9d7a..142cc513665 100644 --- a/Documentation/kvm/mmu.txt +++ b/Documentation/kvm/mmu.txt @@ -77,10 +77,10 @@ Memory Guest memory (gpa) is part of the user address space of the process that is using kvm. Userspace defines the translation between guest addresses and user -addresses (gpa->hva); note that two gpas may alias to the same gva, but not +addresses (gpa->hva); note that two gpas may alias to the same hva, but not vice versa. -These gvas may be backed using any method available to the host: anonymous +These hvas may be backed using any method available to the host: anonymous memory, file backed memory, and device memory. Memory might be paged by the host at any time. @@ -161,7 +161,7 @@ Shadow pages contain the following information: role.cr4_pae: Contains the value of cr4.pae for which the page is valid (e.g. whether 32-bit or 64-bit gptes are in use). - role.cr4_nxe: + role.nxe: Contains the value of efer.nxe for which the page is valid. role.cr0_wp: Contains the value of cr0.wp for which the page is valid. @@ -180,7 +180,9 @@ Shadow pages contain the following information: guest pages as leaves. gfns: An array of 512 guest frame numbers, one for each present pte. Used to - perform a reverse map from a pte to a gfn. + perform a reverse map from a pte to a gfn. When role.direct is set, any + element of this array can be calculated from the gfn field when used, in + this case, the array of gfns is not allocated. See role.direct and gfn. slot_bitmap: A bitmap containing one bit per memory slot. If the page contains a pte mapping a page from memory slot n, then bit n of slot_bitmap will be set @@ -296,6 +298,48 @@ Host translation updates: - look up affected sptes through reverse map - drop (or update) translations +Emulating cr0.wp +================ + +If tdp is not enabled, the host must keep cr0.wp=1 so page write protection +works for the guest kernel, not guest guest userspace. When the guest +cr0.wp=1, this does not present a problem. However when the guest cr0.wp=0, +we cannot map the permissions for gpte.u=1, gpte.w=0 to any spte (the +semantics require allowing any guest kernel access plus user read access). + +We handle this by mapping the permissions to two possible sptes, depending +on fault type: + +- kernel write fault: spte.u=0, spte.w=1 (allows full kernel access, + disallows user access) +- read fault: spte.u=1, spte.w=0 (allows full read access, disallows kernel + write access) + +(user write faults generate a #PF) + +Large pages +=========== + +The mmu supports all combinations of large and small guest and host pages. +Supported page sizes include 4k, 2M, 4M, and 1G. 4M pages are treated as +two separate 2M pages, on both guest and host, since the mmu always uses PAE +paging. + +To instantiate a large spte, four constraints must be satisfied: + +- the spte must point to a large host page +- the guest pte must be a large pte of at least equivalent size (if tdp is + enabled, there is no guest pte and this condition is satisified) +- if the spte will be writeable, the large page frame may not overlap any + write-protected pages +- the guest page must be wholly contained by a single memory slot + +To check the last two conditions, the mmu maintains a ->write_count set of +arrays for each memory slot and large page size. Every write protected page +causes its write_count to be incremented, thus preventing instantiation of +a large spte. The frames at the end of an unaligned memory slot have +artificically inflated ->write_counts so they can never be instantiated. + Further reading =============== diff --git a/Documentation/kvm/msr.txt b/Documentation/kvm/msr.txt new file mode 100644 index 00000000000..8ddcfe84c09 --- /dev/null +++ b/Documentation/kvm/msr.txt @@ -0,0 +1,153 @@ +KVM-specific MSRs. +Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010 +===================================================== + +KVM makes use of some custom MSRs to service some requests. +At present, this facility is only used by kvmclock. + +Custom MSRs have a range reserved for them, that goes from +0x4b564d00 to 0x4b564dff. There are MSRs outside this area, +but they are deprecated and their use is discouraged. + +Custom MSR list +-------- + +The current supported Custom MSR list is: + +MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00 + + data: 4-byte alignment physical address of a memory area which must be + in guest RAM. This memory is expected to hold a copy of the following + structure: + + struct pvclock_wall_clock { + u32 version; + u32 sec; + u32 nsec; + } __attribute__((__packed__)); + + whose data will be filled in by the hypervisor. The hypervisor is only + guaranteed to update this data at the moment of MSR write. + Users that want to reliably query this information more than once have + to write more than once to this MSR. Fields have the following meanings: + + version: guest has to check version before and after grabbing + time information and check that they are both equal and even. + An odd version indicates an in-progress update. + + sec: number of seconds for wallclock. + + nsec: number of nanoseconds for wallclock. + + Note that although MSRs are per-CPU entities, the effect of this + particular MSR is global. + + Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid + leaf prior to usage. + +MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 + + data: 4-byte aligned physical address of a memory area which must be in + guest RAM, plus an enable bit in bit 0. This memory is expected to hold + a copy of the following structure: + + struct pvclock_vcpu_time_info { + u32 version; + u32 pad0; + u64 tsc_timestamp; + u64 system_time; + u32 tsc_to_system_mul; + s8 tsc_shift; + u8 flags; + u8 pad[2]; + } __attribute__((__packed__)); /* 32 bytes */ + + whose data will be filled in by the hypervisor periodically. Only one + write, or registration, is needed for each VCPU. The interval between + updates of this structure is arbitrary and implementation-dependent. + The hypervisor may update this structure at any time it sees fit until + anything with bit0 == 0 is written to it. + + Fields have the following meanings: + + version: guest has to check version before and after grabbing + time information and check that they are both equal and even. + An odd version indicates an in-progress update. + + tsc_timestamp: the tsc value at the current VCPU at the time + of the update of this structure. Guests can subtract this value + from current tsc to derive a notion of elapsed time since the + structure update. + + system_time: a host notion of monotonic time, including sleep + time at the time this structure was last updated. Unit is + nanoseconds. + + tsc_to_system_mul: a function of the tsc frequency. One has + to multiply any tsc-related quantity by this value to get + a value in nanoseconds, besides dividing by 2^tsc_shift + + tsc_shift: cycle to nanosecond divider, as a power of two, to + allow for shift rights. One has to shift right any tsc-related + quantity by this value to get a value in nanoseconds, besides + multiplying by tsc_to_system_mul. + + With this information, guests can derive per-CPU time by + doing: + + time = (current_tsc - tsc_timestamp) + time = (time * tsc_to_system_mul) >> tsc_shift + time = time + system_time + + flags: bits in this field indicate extended capabilities + coordinated between the guest and the hypervisor. Availability + of specific flags has to be checked in 0x40000001 cpuid leaf. + Current flags are: + + flag bit | cpuid bit | meaning + ------------------------------------------------------------- + | | time measures taken across + 0 | 24 | multiple cpus are guaranteed to + | | be monotonic + ------------------------------------------------------------- + + Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid + leaf prior to usage. + + +MSR_KVM_WALL_CLOCK: 0x11 + + data and functioning: same as MSR_KVM_WALL_CLOCK_NEW. Use that instead. + + This MSR falls outside the reserved KVM range and may be removed in the + future. Its usage is deprecated. + + Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid + leaf prior to usage. + +MSR_KVM_SYSTEM_TIME: 0x12 + + data and functioning: same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead. + + This MSR falls outside the reserved KVM range and may be removed in the + future. Its usage is deprecated. + + Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid + leaf prior to usage. + + The suggested algorithm for detecting kvmclock presence is then: + + if (!kvm_para_available()) /* refer to cpuid.txt */ + return NON_PRESENT; + + flags = cpuid_eax(0x40000001); + if (flags & 3) { + msr_kvm_system_time = MSR_KVM_SYSTEM_TIME_NEW; + msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK_NEW; + return PRESENT; + } else if (flags & 0) { + msr_kvm_system_time = MSR_KVM_SYSTEM_TIME; + msr_kvm_wall_clock = MSR_KVM_WALL_CLOCK; + return PRESENT; + } else + return NON_PRESENT; diff --git a/Documentation/kvm/ppc-pv.txt b/Documentation/kvm/ppc-pv.txt new file mode 100644 index 00000000000..a7f2244b3be --- /dev/null +++ b/Documentation/kvm/ppc-pv.txt @@ -0,0 +1,196 @@ +The PPC KVM paravirtual interface +================================= + +The basic execution principle by which KVM on PowerPC works is to run all kernel +space code in PR=1 which is user space. This way we trap all privileged +instructions and can emulate them accordingly. + +Unfortunately that is also the downfall. There are quite some privileged +instructions that needlessly return us to the hypervisor even though they +could be handled differently. + +This is what the PPC PV interface helps with. It takes privileged instructions +and transforms them into unprivileged ones with some help from the hypervisor. +This cuts down virtualization costs by about 50% on some of my benchmarks. + +The code for that interface can be found in arch/powerpc/kernel/kvm* + +Querying for existence +====================== + +To find out if we're running on KVM or not, we leverage the device tree. When +Linux is running on KVM, a node /hypervisor exists. That node contains a +compatible property with the value "linux,kvm". + +Once you determined you're running under a PV capable KVM, you can now use +hypercalls as described below. + +KVM hypercalls +============== + +Inside the device tree's /hypervisor node there's a property called +'hypercall-instructions'. This property contains at most 4 opcodes that make +up the hypercall. To call a hypercall, just call these instructions. + +The parameters are as follows: + + Register IN OUT + + r0 - volatile + r3 1st parameter Return code + r4 2nd parameter 1st output value + r5 3rd parameter 2nd output value + r6 4th parameter 3rd output value + r7 5th parameter 4th output value + r8 6th parameter 5th output value + r9 7th parameter 6th output value + r10 8th parameter 7th output value + r11 hypercall number 8th output value + r12 - volatile + +Hypercall definitions are shared in generic code, so the same hypercall numbers +apply for x86 and powerpc alike with the exception that each KVM hypercall +also needs to be ORed with the KVM vendor code which is (42 << 16). + +Return codes can be as follows: + + Code Meaning + + 0 Success + 12 Hypercall not implemented + <0 Error + +The magic page +============== + +To enable communication between the hypervisor and guest there is a new shared +page that contains parts of supervisor visible register state. The guest can +map this shared page using the KVM hypercall KVM_HC_PPC_MAP_MAGIC_PAGE. + +With this hypercall issued the guest always gets the magic page mapped at the +desired location in effective and physical address space. For now, we always +map the page to -4096. This way we can access it using absolute load and store +functions. The following instruction reads the first field of the magic page: + + ld rX, -4096(0) + +The interface is designed to be extensible should there be need later to add +additional registers to the magic page. If you add fields to the magic page, +also define a new hypercall feature to indicate that the host can give you more +registers. Only if the host supports the additional features, make use of them. + +The magic page has the following layout as described in +arch/powerpc/include/asm/kvm_para.h: + +struct kvm_vcpu_arch_shared { + __u64 scratch1; + __u64 scratch2; + __u64 scratch3; + __u64 critical; /* Guest may not get interrupts if == r1 */ + __u64 sprg0; + __u64 sprg1; + __u64 sprg2; + __u64 sprg3; + __u64 srr0; + __u64 srr1; + __u64 dar; + __u64 msr; + __u32 dsisr; + __u32 int_pending; /* Tells the guest if we have an interrupt */ +}; + +Additions to the page must only occur at the end. Struct fields are always 32 +or 64 bit aligned, depending on them being 32 or 64 bit wide respectively. + +Magic page features +=================== + +When mapping the magic page using the KVM hypercall KVM_HC_PPC_MAP_MAGIC_PAGE, +a second return value is passed to the guest. This second return value contains +a bitmap of available features inside the magic page. + +The following enhancements to the magic page are currently available: + + KVM_MAGIC_FEAT_SR Maps SR registers r/w in the magic page + +For enhanced features in the magic page, please check for the existence of the +feature before using them! + +MSR bits +======== + +The MSR contains bits that require hypervisor intervention and bits that do +not require direct hypervisor intervention because they only get interpreted +when entering the guest or don't have any impact on the hypervisor's behavior. + +The following bits are safe to be set inside the guest: + + MSR_EE + MSR_RI + MSR_CR + MSR_ME + +If any other bit changes in the MSR, please still use mtmsr(d). + +Patched instructions +==================== + +The "ld" and "std" instructions are transormed to "lwz" and "stw" instructions +respectively on 32 bit systems with an added offset of 4 to accomodate for big +endianness. + +The following is a list of mapping the Linux kernel performs when running as +guest. Implementing any of those mappings is optional, as the instruction traps +also act on the shared page. So calling privileged instructions still works as +before. + +From To +==== == + +mfmsr rX ld rX, magic_page->msr +mfsprg rX, 0 ld rX, magic_page->sprg0 +mfsprg rX, 1 ld rX, magic_page->sprg1 +mfsprg rX, 2 ld rX, magic_page->sprg2 +mfsprg rX, 3 ld rX, magic_page->sprg3 +mfsrr0 rX ld rX, magic_page->srr0 +mfsrr1 rX ld rX, magic_page->srr1 +mfdar rX ld rX, magic_page->dar +mfdsisr rX lwz rX, magic_page->dsisr + +mtmsr rX std rX, magic_page->msr +mtsprg 0, rX std rX, magic_page->sprg0 +mtsprg 1, rX std rX, magic_page->sprg1 +mtsprg 2, rX std rX, magic_page->sprg2 +mtsprg 3, rX std rX, magic_page->sprg3 +mtsrr0 rX std rX, magic_page->srr0 +mtsrr1 rX std rX, magic_page->srr1 +mtdar rX std rX, magic_page->dar +mtdsisr rX stw rX, magic_page->dsisr + +tlbsync nop + +mtmsrd rX, 0 b <special mtmsr section> +mtmsr rX b <special mtmsr section> + +mtmsrd rX, 1 b <special mtmsrd section> + +[Book3S only] +mtsrin rX, rY b <special mtsrin section> + +[BookE only] +wrteei [0|1] b <special wrteei section> + + +Some instructions require more logic to determine what's going on than a load +or store instruction can deliver. To enable patching of those, we keep some +RAM around where we can live translate instructions to. What happens is the +following: + + 1) copy emulation code to memory + 2) patch that code to fit the emulated instruction + 3) patch that code to return to the original pc + 4 + 4) patch the original instruction to branch to the new code + +That way we can inject an arbitrary amount of code as replacement for a single +instruction. This allows us to check for pending interrupts when setting EE=1 +for example. diff --git a/Documentation/kvm/review-checklist.txt b/Documentation/kvm/review-checklist.txt new file mode 100644 index 00000000000..730475ae1b8 --- /dev/null +++ b/Documentation/kvm/review-checklist.txt @@ -0,0 +1,38 @@ +Review checklist for kvm patches +================================ + +1. The patch must follow Documentation/CodingStyle and + Documentation/SubmittingPatches. + +2. Patches should be against kvm.git master branch. + +3. If the patch introduces or modifies a new userspace API: + - the API must be documented in Documentation/kvm/api.txt + - the API must be discoverable using KVM_CHECK_EXTENSION + +4. New state must include support for save/restore. + +5. New features must default to off (userspace should explicitly request them). + Performance improvements can and should default to on. + +6. New cpu features should be exposed via KVM_GET_SUPPORTED_CPUID2 + +7. Emulator changes should be accompanied by unit tests for qemu-kvm.git + kvm/test directory. + +8. Changes should be vendor neutral when possible. Changes to common code + are better than duplicating changes to vendor code. + +9. Similarly, prefer changes to arch independent code than to arch dependent + code. + +10. User/kernel interfaces and guest/host interfaces must be 64-bit clean + (all variables and sizes naturally aligned on 64-bit; use specific types + only - u64 rather than ulong). + +11. New guest visible features must either be documented in a hardware manual + or be accompanied by documentation. + +12. Features must be robust against reset and kexec - for example, shared + host/guest memory must be unshared to prevent the host from writing to + guest memory that the guest has not reserved for this purpose. diff --git a/Documentation/kvm/timekeeping.txt b/Documentation/kvm/timekeeping.txt new file mode 100644 index 00000000000..0c5033a58c9 --- /dev/null +++ b/Documentation/kvm/timekeeping.txt @@ -0,0 +1,612 @@ + + Timekeeping Virtualization for X86-Based Architectures + + Zachary Amsden <zamsden@redhat.com> + Copyright (c) 2010, Red Hat. All rights reserved. + +1) Overview +2) Timing Devices +3) TSC Hardware +4) Virtualization Problems + +========================================================================= + +1) Overview + +One of the most complicated parts of the X86 platform, and specifically, +the virtualization of this platform is the plethora of timing devices available +and the complexity of emulating those devices. In addition, virtualization of +time introduces a new set of challenges because it introduces a multiplexed +division of time beyond the control of the guest CPU. + +First, we will describe the various timekeeping hardware available, then +present some of the problems which arise and solutions available, giving +specific recommendations for certain classes of KVM guests. + +The purpose of this document is to collect data and information relevant to +timekeeping which may be difficult to find elsewhere, specifically, +information relevant to KVM and hardware-based virtualization. + +========================================================================= + +2) Timing Devices + +First we discuss the basic hardware devices available. TSC and the related +KVM clock are special enough to warrant a full exposition and are described in +the following section. + +2.1) i8254 - PIT + +One of the first timer devices available is the programmable interrupt timer, +or PIT. The PIT has a fixed frequency 1.193182 MHz base clock and three +channels which can be programmed to deliver periodic or one-shot interrupts. +These three channels can be configured in different modes and have individual +counters. Channel 1 and 2 were not available for general use in the original +IBM PC, and historically were connected to control RAM refresh and the PC +speaker. Now the PIT is typically integrated as part of an emulated chipset +and a separate physical PIT is not used. + +The PIT uses I/O ports 0x40 - 0x43. Access to the 16-bit counters is done +using single or multiple byte access to the I/O ports. There are 6 modes +available, but not all modes are available to all timers, as only timer 2 +has a connected gate input, required for modes 1 and 5. The gate line is +controlled by port 61h, bit 0, as illustrated in the following diagram. + + -------------- ---------------- +| | | | +| 1.1932 MHz |---------->| CLOCK OUT | ---------> IRQ 0 +| Clock | | | | + -------------- | +->| GATE TIMER 0 | + | ---------------- + | + | ---------------- + | | | + |------>| CLOCK OUT | ---------> 66.3 KHZ DRAM + | | | (aka /dev/null) + | +->| GATE TIMER 1 | + | ---------------- + | + | ---------------- + | | | + |------>| CLOCK OUT | ---------> Port 61h, bit 5 + | | | +Port 61h, bit 0 ---------->| GATE TIMER 2 | \_.---- ____ + ---------------- _| )--|LPF|---Speaker + / *---- \___/ +Port 61h, bit 1 -----------------------------------/ + +The timer modes are now described. + +Mode 0: Single Timeout. This is a one-shot software timeout that counts down + when the gate is high (always true for timers 0 and 1). When the count + reaches zero, the output goes high. + +Mode 1: Triggered One-shot. The output is intially set high. When the gate + line is set high, a countdown is initiated (which does not stop if the gate is + lowered), during which the output is set low. When the count reaches zero, + the output goes high. + +Mode 2: Rate Generator. The output is initially set high. When the countdown + reaches 1, the output goes low for one count and then returns high. The value + is reloaded and the countdown automatically resumes. If the gate line goes + low, the count is halted. If the output is low when the gate is lowered, the + output automatically goes high (this only affects timer 2). + +Mode 3: Square Wave. This generates a high / low square wave. The count + determines the length of the pulse, which alternates between high and low + when zero is reached. The count only proceeds when gate is high and is + automatically reloaded on reaching zero. The count is decremented twice at + each clock to generate a full high / low cycle at the full periodic rate. + If the count is even, the clock remains high for N/2 counts and low for N/2 + counts; if the clock is odd, the clock is high for (N+1)/2 counts and low + for (N-1)/2 counts. Only even values are latched by the counter, so odd + values are not observed when reading. This is the intended mode for timer 2, + which generates sine-like tones by low-pass filtering the square wave output. + +Mode 4: Software Strobe. After programming this mode and loading the counter, + the output remains high until the counter reaches zero. Then the output + goes low for 1 clock cycle and returns high. The counter is not reloaded. + Counting only occurs when gate is high. + +Mode 5: Hardware Strobe. After programming and loading the counter, the + output remains high. When the gate is raised, a countdown is initiated + (which does not stop if the gate is lowered). When the counter reaches zero, + the output goes low for 1 clock cycle and then returns high. The counter is + not reloaded. + +In addition to normal binary counting, the PIT supports BCD counting. The +command port, 0x43 is used to set the counter and mode for each of the three +timers. + +PIT commands, issued to port 0x43, using the following bit encoding: + +Bit 7-4: Command (See table below) +Bit 3-1: Mode (000 = Mode 0, 101 = Mode 5, 11X = undefined) +Bit 0 : Binary (0) / BCD (1) + +Command table: + +0000 - Latch Timer 0 count for port 0x40 + sample and hold the count to be read in port 0x40; + additional commands ignored until counter is read; + mode bits ignored. + +0001 - Set Timer 0 LSB mode for port 0x40 + set timer to read LSB only and force MSB to zero; + mode bits set timer mode + +0010 - Set Timer 0 MSB mode for port 0x40 + set timer to read MSB only and force LSB to zero; + mode bits set timer mode + +0011 - Set Timer 0 16-bit mode for port 0x40 + set timer to read / write LSB first, then MSB; + mode bits set timer mode + +0100 - Latch Timer 1 count for port 0x41 - as described above +0101 - Set Timer 1 LSB mode for port 0x41 - as described above +0110 - Set Timer 1 MSB mode for port 0x41 - as described above +0111 - Set Timer 1 16-bit mode for port 0x41 - as described above + +1000 - Latch Timer 2 count for port 0x42 - as described above +1001 - Set Timer 2 LSB mode for port 0x42 - as described above +1010 - Set Timer 2 MSB mode for port 0x42 - as described above +1011 - Set Timer 2 16-bit mode for port 0x42 as described above + +1101 - General counter latch + Latch combination of counters into corresponding ports + Bit 3 = Counter 2 + Bit 2 = Counter 1 + Bit 1 = Counter 0 + Bit 0 = Unused + +1110 - Latch timer status + Latch combination of counter mode into corresponding ports + Bit 3 = Counter 2 + Bit 2 = Counter 1 + Bit 1 = Counter 0 + + The output of ports 0x40-0x42 following this command will be: + + Bit 7 = Output pin + Bit 6 = Count loaded (0 if timer has expired) + Bit 5-4 = Read / Write mode + 01 = MSB only + 10 = LSB only + 11 = LSB / MSB (16-bit) + Bit 3-1 = Mode + Bit 0 = Binary (0) / BCD mode (1) + +2.2) RTC + +The second device which was available in the original PC was the MC146818 real +time clock. The original device is now obsolete, and usually emulated by the +system chipset, sometimes by an HPET and some frankenstein IRQ routing. + +The RTC is accessed through CMOS variables, which uses an index register to +control which bytes are read. Since there is only one index register, read +of the CMOS and read of the RTC require lock protection (in addition, it is +dangerous to allow userspace utilities such as hwclock to have direct RTC +access, as they could corrupt kernel reads and writes of CMOS memory). + +The RTC generates an interrupt which is usually routed to IRQ 8. The interrupt +can function as a periodic timer, an additional once a day alarm, and can issue +interrupts after an update of the CMOS registers by the MC146818 is complete. +The type of interrupt is signalled in the RTC status registers. + +The RTC will update the current time fields by battery power even while the +system is off. The current time fields should not be read while an update is +in progress, as indicated in the status register. + +The clock uses a 32.768kHz crystal, so bits 6-4 of register A should be +programmed to a 32kHz divider if the RTC is to count seconds. + +This is the RAM map originally used for the RTC/CMOS: + +Location Size Description +------------------------------------------ +00h byte Current second (BCD) +01h byte Seconds alarm (BCD) +02h byte Current minute (BCD) +03h byte Minutes alarm (BCD) +04h byte Current hour (BCD) +05h byte Hours alarm (BCD) +06h byte Current day of week (BCD) +07h byte Current day of month (BCD) +08h byte Current month (BCD) +09h byte Current year (BCD) +0Ah byte Register A + bit 7 = Update in progress + bit 6-4 = Divider for clock + 000 = 4.194 MHz + 001 = 1.049 MHz + 010 = 32 kHz + 10X = test modes + 110 = reset / disable + 111 = reset / disable + bit 3-0 = Rate selection for periodic interrupt + 000 = periodic timer disabled + 001 = 3.90625 uS + 010 = 7.8125 uS + 011 = .122070 mS + 100 = .244141 mS + ... + 1101 = 125 mS + 1110 = 250 mS + 1111 = 500 mS +0Bh byte Register B + bit 7 = Run (0) / Halt (1) + bit 6 = Periodic interrupt enable + bit 5 = Alarm interrupt enable + bit 4 = Update-ended interrupt enable + bit 3 = Square wave interrupt enable + bit 2 = BCD calendar (0) / Binary (1) + bit 1 = 12-hour mode (0) / 24-hour mode (1) + bit 0 = 0 (DST off) / 1 (DST enabled) +OCh byte Register C (read only) + bit 7 = interrupt request flag (IRQF) + bit 6 = periodic interrupt flag (PF) + bit 5 = alarm interrupt flag (AF) + bit 4 = update interrupt flag (UF) + bit 3-0 = reserved +ODh byte Register D (read only) + bit 7 = RTC has power + bit 6-0 = reserved +32h byte Current century BCD (*) + (*) location vendor specific and now determined from ACPI global tables + +2.3) APIC + +On Pentium and later processors, an on-board timer is available to each CPU +as part of the Advanced Programmable Interrupt Controller. The APIC is +accessed through memory-mapped registers and provides interrupt service to each +CPU, used for IPIs and local timer interrupts. + +Although in theory the APIC is a safe and stable source for local interrupts, +in practice, many bugs and glitches have occurred due to the special nature of +the APIC CPU-local memory-mapped hardware. Beware that CPU errata may affect +the use of the APIC and that workarounds may be required. In addition, some of +these workarounds pose unique constraints for virtualization - requiring either +extra overhead incurred from extra reads of memory-mapped I/O or additional +functionality that may be more computationally expensive to implement. + +Since the APIC is documented quite well in the Intel and AMD manuals, we will +avoid repetition of the detail here. It should be pointed out that the APIC +timer is programmed through the LVT (local vector timer) register, is capable +of one-shot or periodic operation, and is based on the bus clock divided down +by the programmable divider register. + +2.4) HPET + +HPET is quite complex, and was originally intended to replace the PIT / RTC +support of the X86 PC. It remains to be seen whether that will be the case, as +the de facto standard of PC hardware is to emulate these older devices. Some +systems designated as legacy free may support only the HPET as a hardware timer +device. + +The HPET spec is rather loose and vague, requiring at least 3 hardware timers, +but allowing implementation freedom to support many more. It also imposes no +fixed rate on the timer frequency, but does impose some extremal values on +frequency, error and slew. + +In general, the HPET is recommended as a high precision (compared to PIT /RTC) +time source which is independent of local variation (as there is only one HPET +in any given system). The HPET is also memory-mapped, and its presence is +indicated through ACPI tables by the BIOS. + +Detailed specification of the HPET is beyond the current scope of this +document, as it is also very well documented elsewhere. + +2.5) Offboard Timers + +Several cards, both proprietary (watchdog boards) and commonplace (e1000) have +timing chips built into the cards which may have registers which are accessible +to kernel or user drivers. To the author's knowledge, using these to generate +a clocksource for a Linux or other kernel has not yet been attempted and is in +general frowned upon as not playing by the agreed rules of the game. Such a +timer device would require additional support to be virtualized properly and is +not considered important at this time as no known operating system does this. + +========================================================================= + +3) TSC Hardware + +The TSC or time stamp counter is relatively simple in theory; it counts +instruction cycles issued by the processor, which can be used as a measure of +time. In practice, due to a number of problems, it is the most complicated +timekeeping device to use. + +The TSC is represented internally as a 64-bit MSR which can be read with the +RDMSR, RDTSC, or RDTSCP (when available) instructions. In the past, hardware +limitations made it possible to write the TSC, but generally on old hardware it +was only possible to write the low 32-bits of the 64-bit counter, and the upper +32-bits of the counter were cleared. Now, however, on Intel processors family +0Fh, for models 3, 4 and 6, and family 06h, models e and f, this restriction +has been lifted and all 64-bits are writable. On AMD systems, the ability to +write the TSC MSR is not an architectural guarantee. + +The TSC is accessible from CPL-0 and conditionally, for CPL > 0 software by +means of the CR4.TSD bit, which when enabled, disables CPL > 0 TSC access. + +Some vendors have implemented an additional instruction, RDTSCP, which returns +atomically not just the TSC, but an indicator which corresponds to the +processor number. This can be used to index into an array of TSC variables to +determine offset information in SMP systems where TSCs are not synchronized. +The presence of this instruction must be determined by consulting CPUID feature +bits. + +Both VMX and SVM provide extension fields in the virtualization hardware which +allows the guest visible TSC to be offset by a constant. Newer implementations +promise to allow the TSC to additionally be scaled, but this hardware is not +yet widely available. + +3.1) TSC synchronization + +The TSC is a CPU-local clock in most implementations. This means, on SMP +platforms, the TSCs of different CPUs may start at different times depending +on when the CPUs are powered on. Generally, CPUs on the same die will share +the same clock, however, this is not always the case. + +The BIOS may attempt to resynchronize the TSCs during the poweron process and +the operating system or other system software may attempt to do this as well. +Several hardware limitations make the problem worse - if it is not possible to +write the full 64-bits of the TSC, it may be impossible to match the TSC in +newly arriving CPUs to that of the rest of the system, resulting in +unsynchronized TSCs. This may be done by BIOS or system software, but in +practice, getting a perfectly synchronized TSC will not be possible unless all +values are read from the same clock, which generally only is possible on single +socket systems or those with special hardware support. + +3.2) TSC and CPU hotplug + +As touched on already, CPUs which arrive later than the boot time of the system +may not have a TSC value that is synchronized with the rest of the system. +Either system software, BIOS, or SMM code may actually try to establish the TSC +to a value matching the rest of the system, but a perfect match is usually not +a guarantee. This can have the effect of bringing a system from a state where +TSC is synchronized back to a state where TSC synchronization flaws, however +small, may be exposed to the OS and any virtualization environment. + +3.3) TSC and multi-socket / NUMA + +Multi-socket systems, especially large multi-socket systems are likely to have +individual clocksources rather than a single, universally distributed clock. +Since these clocks are driven by different crystals, they will not have +perfectly matched frequency, and temperature and electrical variations will +cause the CPU clocks, and thus the TSCs to drift over time. Depending on the +exact clock and bus design, the drift may or may not be fixed in absolute +error, and may accumulate over time. + +In addition, very large systems may deliberately slew the clocks of individual +cores. This technique, known as spread-spectrum clocking, reduces EMI at the +clock frequency and harmonics of it, which may be required to pass FCC +standards for telecommunications and computer equipment. + +It is recommended not to trust the TSCs to remain synchronized on NUMA or +multiple socket systems for these reasons. + +3.4) TSC and C-states + +C-states, or idling states of the processor, especially C1E and deeper sleep +states may be problematic for TSC as well. The TSC may stop advancing in such +a state, resulting in a TSC which is behind that of other CPUs when execution +is resumed. Such CPUs must be detected and flagged by the operating system +based on CPU and chipset identifications. + +The TSC in such a case may be corrected by catching it up to a known external +clocksource. + +3.5) TSC frequency change / P-states + +To make things slightly more interesting, some CPUs may change frequency. They +may or may not run the TSC at the same rate, and because the frequency change +may be staggered or slewed, at some points in time, the TSC rate may not be +known other than falling within a range of values. In this case, the TSC will +not be a stable time source, and must be calibrated against a known, stable, +external clock to be a usable source of time. + +Whether the TSC runs at a constant rate or scales with the P-state is model +dependent and must be determined by inspecting CPUID, chipset or vendor +specific MSR fields. + +In addition, some vendors have known bugs where the P-state is actually +compensated for properly during normal operation, but when the processor is +inactive, the P-state may be raised temporarily to service cache misses from +other processors. In such cases, the TSC on halted CPUs could advance faster +than that of non-halted processors. AMD Turion processors are known to have +this problem. + +3.6) TSC and STPCLK / T-states + +External signals given to the processor may also have the effect of stopping +the TSC. This is typically done for thermal emergency power control to prevent +an overheating condition, and typically, there is no way to detect that this +condition has happened. + +3.7) TSC virtualization - VMX + +VMX provides conditional trapping of RDTSC, RDMSR, WRMSR and RDTSCP +instructions, which is enough for full virtualization of TSC in any manner. In +addition, VMX allows passing through the host TSC plus an additional TSC_OFFSET +field specified in the VMCS. Special instructions must be used to read and +write the VMCS field. + +3.8) TSC virtualization - SVM + +SVM provides conditional trapping of RDTSC, RDMSR, WRMSR and RDTSCP +instructions, which is enough for full virtualization of TSC in any manner. In +addition, SVM allows passing through the host TSC plus an additional offset +field specified in the SVM control block. + +3.9) TSC feature bits in Linux + +In summary, there is no way to guarantee the TSC remains in perfect +synchronization unless it is explicitly guaranteed by the architecture. Even +if so, the TSCs in multi-sockets or NUMA systems may still run independently +despite being locally consistent. + +The following feature bits are used by Linux to signal various TSC attributes, +but they can only be taken to be meaningful for UP or single node systems. + +X86_FEATURE_TSC : The TSC is available in hardware +X86_FEATURE_RDTSCP : The RDTSCP instruction is available +X86_FEATURE_CONSTANT_TSC : The TSC rate is unchanged with P-states +X86_FEATURE_NONSTOP_TSC : The TSC does not stop in C-states +X86_FEATURE_TSC_RELIABLE : TSC sync checks are skipped (VMware) + +4) Virtualization Problems + +Timekeeping is especially problematic for virtualization because a number of +challenges arise. The most obvious problem is that time is now shared between +the host and, potentially, a number of virtual machines. Thus the virtual +operating system does not run with 100% usage of the CPU, despite the fact that +it may very well make that assumption. It may expect it to remain true to very +exacting bounds when interrupt sources are disabled, but in reality only its +virtual interrupt sources are disabled, and the machine may still be preempted +at any time. This causes problems as the passage of real time, the injection +of machine interrupts and the associated clock sources are no longer completely +synchronized with real time. + +This same problem can occur on native harware to a degree, as SMM mode may +steal cycles from the naturally on X86 systems when SMM mode is used by the +BIOS, but not in such an extreme fashion. However, the fact that SMM mode may +cause similar problems to virtualization makes it a good justification for +solving many of these problems on bare metal. + +4.1) Interrupt clocking + +One of the most immediate problems that occurs with legacy operating systems +is that the system timekeeping routines are often designed to keep track of +time by counting periodic interrupts. These interrupts may come from the PIT +or the RTC, but the problem is the same: the host virtualization engine may not +be able to deliver the proper number of interrupts per second, and so guest +time may fall behind. This is especially problematic if a high interrupt rate +is selected, such as 1000 HZ, which is unfortunately the default for many Linux +guests. + +There are three approaches to solving this problem; first, it may be possible +to simply ignore it. Guests which have a separate time source for tracking +'wall clock' or 'real time' may not need any adjustment of their interrupts to +maintain proper time. If this is not sufficient, it may be necessary to inject +additional interrupts into the guest in order to increase the effective +interrupt rate. This approach leads to complications in extreme conditions, +where host load or guest lag is too much to compensate for, and thus another +solution to the problem has risen: the guest may need to become aware of lost +ticks and compensate for them internally. Although promising in theory, the +implementation of this policy in Linux has been extremely error prone, and a +number of buggy variants of lost tick compensation are distributed across +commonly used Linux systems. + +Windows uses periodic RTC clocking as a means of keeping time internally, and +thus requires interrupt slewing to keep proper time. It does use a low enough +rate (ed: is it 18.2 Hz?) however that it has not yet been a problem in +practice. + +4.2) TSC sampling and serialization + +As the highest precision time source available, the cycle counter of the CPU +has aroused much interest from developers. As explained above, this timer has +many problems unique to its nature as a local, potentially unstable and +potentially unsynchronized source. One issue which is not unique to the TSC, +but is highlighted because of its very precise nature is sampling delay. By +definition, the counter, once read is already old. However, it is also +possible for the counter to be read ahead of the actual use of the result. +This is a consequence of the superscalar execution of the instruction stream, +which may execute instructions out of order. Such execution is called +non-serialized. Forcing serialized execution is necessary for precise +measurement with the TSC, and requires a serializing instruction, such as CPUID +or an MSR read. + +Since CPUID may actually be virtualized by a trap and emulate mechanism, this +serialization can pose a performance issue for hardware virtualization. An +accurate time stamp counter reading may therefore not always be available, and +it may be necessary for an implementation to guard against "backwards" reads of +the TSC as seen from other CPUs, even in an otherwise perfectly synchronized +system. + +4.3) Timespec aliasing + +Additionally, this lack of serialization from the TSC poses another challenge +when using results of the TSC when measured against another time source. As +the TSC is much higher precision, many possible values of the TSC may be read +while another clock is still expressing the same value. + +That is, you may read (T,T+10) while external clock C maintains the same value. +Due to non-serialized reads, you may actually end up with a range which +fluctuates - from (T-1.. T+10). Thus, any time calculated from a TSC, but +calibrated against an external value may have a range of valid values. +Re-calibrating this computation may actually cause time, as computed after the +calibration, to go backwards, compared with time computed before the +calibration. + +This problem is particularly pronounced with an internal time source in Linux, +the kernel time, which is expressed in the theoretically high resolution +timespec - but which advances in much larger granularity intervals, sometimes +at the rate of jiffies, and possibly in catchup modes, at a much larger step. + +This aliasing requires care in the computation and recalibration of kvmclock +and any other values derived from TSC computation (such as TSC virtualization +itself). + +4.4) Migration + +Migration of a virtual machine raises problems for timekeeping in two ways. +First, the migration itself may take time, during which interrupts cannot be +delivered, and after which, the guest time may need to be caught up. NTP may +be able to help to some degree here, as the clock correction required is +typically small enough to fall in the NTP-correctable window. + +An additional concern is that timers based off the TSC (or HPET, if the raw bus +clock is exposed) may now be running at different rates, requiring compensation +in some way in the hypervisor by virtualizing these timers. In addition, +migrating to a faster machine may preclude the use of a passthrough TSC, as a +faster clock cannot be made visible to a guest without the potential of time +advancing faster than usual. A slower clock is less of a problem, as it can +always be caught up to the original rate. KVM clock avoids these problems by +simply storing multipliers and offsets against the TSC for the guest to convert +back into nanosecond resolution values. + +4.5) Scheduling + +Since scheduling may be based on precise timing and firing of interrupts, the +scheduling algorithms of an operating system may be adversely affected by +virtualization. In theory, the effect is random and should be universally +distributed, but in contrived as well as real scenarios (guest device access, +causes of virtualization exits, possible context switch), this may not always +be the case. The effect of this has not been well studied. + +In an attempt to work around this, several implementations have provided a +paravirtualized scheduler clock, which reveals the true amount of CPU time for +which a virtual machine has been running. + +4.6) Watchdogs + +Watchdog timers, such as the lock detector in Linux may fire accidentally when +running under hardware virtualization due to timer interrupts being delayed or +misinterpretation of the passage of real time. Usually, these warnings are +spurious and can be ignored, but in some circumstances it may be necessary to +disable such detection. + +4.7) Delays and precision timing + +Precise timing and delays may not be possible in a virtualized system. This +can happen if the system is controlling physical hardware, or issues delays to +compensate for slower I/O to and from devices. The first issue is not solvable +in general for a virtualized system; hardware control software can't be +adequately virtualized without a full real-time operating system, which would +require an RT aware virtualization platform. + +The second issue may cause performance problems, but this is unlikely to be a +significant issue. In many cases these delays may be eliminated through +configuration or paravirtualization. + +4.8) Covert channels and leaks + +In addition to the above problems, time information will inevitably leak to the +guest about the host in anything but a perfect implementation of virtualized +time. This may allow the guest to infer the presence of a hypervisor (as in a +red-pill type detection), and it may allow information to leak between guests +by using CPU utilization itself as a signalling channel. Preventing such +problems would require completely isolated virtual time which may not track +real time any longer. This may be useful in certain security or QA contexts, +but in general isn't recommended for real-world deployment scenarios. diff --git a/Documentation/laptops/acer-wmi.txt b/Documentation/laptops/acer-wmi.txt index 0768fcc3ba3..4beafa663dd 100644 --- a/Documentation/laptops/acer-wmi.txt +++ b/Documentation/laptops/acer-wmi.txt @@ -173,7 +173,7 @@ Credits ******* Olaf Tauber, who did the real hard work when he developed acerhk -http://www.informatik.hu-berlin.de/~tauber/acerhk +http://www.cakey.de/acerhk/ All the authors of laptop ACPI modules in the kernel, whose work was an inspiration in the early days of acer_acpi Mathieu Segaud, who solved the problem with having to modprobe the driver diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt index fc15538d8b4..1565eefd6fd 100644 --- a/Documentation/laptops/thinkpad-acpi.txt +++ b/Documentation/laptops/thinkpad-acpi.txt @@ -960,70 +960,21 @@ Sysfs notes: subsystem, and follow all of the hwmon guidelines at Documentation/hwmon. +EXPERIMENTAL: Embedded controller register dump +----------------------------------------------- -EXPERIMENTAL: Embedded controller register dump -- /proc/acpi/ibm/ecdump ------------------------------------------------------------------------- - -This feature is marked EXPERIMENTAL because the implementation -directly accesses hardware registers and may not work as expected. USE -WITH CAUTION! To use this feature, you need to supply the -experimental=1 parameter when loading the module. - -This feature dumps the values of 256 embedded controller -registers. Values which have changed since the last time the registers -were dumped are marked with a star: - -[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump -EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f -EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00 -EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00 -EC 0x20: 00 00 00 00 00 00 00 00 00 00 00 03 43 00 00 80 -EC 0x30: 01 07 1a 00 30 04 00 00 *85 00 00 10 00 50 00 00 -EC 0x40: 00 00 00 00 00 00 14 01 00 04 00 00 00 00 00 00 -EC 0x50: 00 c0 02 0d 00 01 01 02 02 03 03 03 03 *bc *02 *bc -EC 0x60: *02 *bc *02 00 00 00 00 00 00 00 00 00 00 00 00 00 -EC 0x70: 00 00 00 00 00 12 30 40 *24 *26 *2c *27 *20 80 *1f 80 -EC 0x80: 00 00 00 06 *37 *0e 03 00 00 00 0e 07 00 00 00 00 -EC 0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 -EC 0xa0: *ff 09 ff 09 ff ff *64 00 *00 *00 *a2 41 *ff *ff *e0 00 -EC 0xb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 -EC 0xc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 -EC 0xd0: 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 -EC 0xe0: 00 00 00 00 00 00 00 00 11 20 49 04 24 06 55 03 -EC 0xf0: 31 55 48 54 35 38 57 57 08 2f 45 73 07 65 6c 1a - -This feature can be used to determine the register holding the fan -speed on some models. To do that, do the following: +This feature is not included in the thinkpad driver anymore. +Instead the EC can be accessed through /sys/kernel/debug/ec with +a userspace tool which can be found here: +ftp://ftp.suse.com/pub/people/trenn/sources/ec +Use it to determine the register holding the fan +speed on some models. To do that, do the following: - make sure the battery is fully charged - make sure the fan is running - - run 'cat /proc/acpi/ibm/ecdump' several times, once per second or so - -The first step makes sure various charging-related values don't -vary. The second ensures that the fan-related values do vary, since -the fan speed fluctuates a bit. The third will (hopefully) mark the -fan register with a star: - -[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump -EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f -EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00 -EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00 -EC 0x20: 00 00 00 00 00 00 00 00 00 00 00 03 43 00 00 80 -EC 0x30: 01 07 1a 00 30 04 00 00 85 00 00 10 00 50 00 00 -EC 0x40: 00 00 00 00 00 00 14 01 00 04 00 00 00 00 00 00 -EC 0x50: 00 c0 02 0d 00 01 01 02 02 03 03 03 03 bc 02 bc -EC 0x60: 02 bc 02 00 00 00 00 00 00 00 00 00 00 00 00 00 -EC 0x70: 00 00 00 00 00 12 30 40 24 27 2c 27 21 80 1f 80 -EC 0x80: 00 00 00 06 *be 0d 03 00 00 00 0e 07 00 00 00 00 -EC 0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 -EC 0xa0: ff 09 ff 09 ff ff 64 00 00 00 a2 41 ff ff e0 00 -EC 0xb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 -EC 0xc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 -EC 0xd0: 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 -EC 0xe0: 00 00 00 00 00 00 00 00 11 20 49 04 24 06 55 03 -EC 0xf0: 31 55 48 54 35 38 57 57 08 2f 45 73 07 65 6c 1a - -Another set of values that varies often is the temperature + - use above mentioned tool to read out the EC + +Often fan and temperature values vary between readings. Since temperatures don't change vary fast, you can take several quick dumps to eliminate them. @@ -1073,6 +1024,10 @@ ThinkPad-specific interface. The driver will disable its native backlight brightness control interface if it detects that the standard ACPI interface is available in the ThinkPad. +If you want to use the thinkpad-acpi backlight brightness control +instead of the generic ACPI video backlight brightness control for some +reason, you should use the acpi_backlight=vendor kernel parameter. + The brightness_enable module parameter can be used to control whether the LCD brightness control feature will be enabled when available. brightness_enable=0 forces it to be disabled. brightness_enable=1 diff --git a/Documentation/ldm.txt b/Documentation/ldm.txt index 718085bc9f1..4f80edd14d0 100644 --- a/Documentation/ldm.txt +++ b/Documentation/ldm.txt @@ -98,7 +98,7 @@ More Documentation There is an Overview of the LDM together with complete Technical Documentation. It is available for download. - http://www.linux-ntfs.org/content/view/19/37/ + http://www.linux-ntfs.org/ If you have any LDM questions that aren't answered in the documentation, email me. diff --git a/Documentation/lguest/Makefile b/Documentation/lguest/Makefile index 28c8cdfcafd..bebac6b4f33 100644 --- a/Documentation/lguest/Makefile +++ b/Documentation/lguest/Makefile @@ -1,5 +1,6 @@ # This creates the demonstration utility "lguest" which runs a Linux guest. -CFLAGS:=-m32 -Wall -Wmissing-declarations -Wmissing-prototypes -O3 -I../../include -I../../arch/x86/include -U_FORTIFY_SOURCE +# Missing headers? Add "-I../../include -I../../arch/x86/include" +CFLAGS:=-m32 -Wall -Wmissing-declarations -Wmissing-prototypes -O3 -U_FORTIFY_SOURCE all: lguest diff --git a/Documentation/lguest/lguest.c b/Documentation/lguest/lguest.c index e9ce3c55451..dc73bc54cc4 100644 --- a/Documentation/lguest/lguest.c +++ b/Documentation/lguest/lguest.c @@ -39,14 +39,14 @@ #include <limits.h> #include <stddef.h> #include <signal.h> -#include "linux/lguest_launcher.h" -#include "linux/virtio_config.h" -#include "linux/virtio_net.h" -#include "linux/virtio_blk.h" -#include "linux/virtio_console.h" -#include "linux/virtio_rng.h" -#include "linux/virtio_ring.h" -#include "asm/bootparam.h" +#include <linux/virtio_config.h> +#include <linux/virtio_net.h> +#include <linux/virtio_blk.h> +#include <linux/virtio_console.h> +#include <linux/virtio_rng.h> +#include <linux/virtio_ring.h> +#include <asm/bootparam.h> +#include "../../include/linux/lguest_launcher.h" /*L:110 * We can ignore the 42 include files we need for this program, but I do want * to draw attention to the use of kernel-style types. @@ -1447,14 +1447,15 @@ static void add_to_bridge(int fd, const char *if_name, const char *br_name) static void configure_device(int fd, const char *tapif, u32 ipaddr) { struct ifreq ifr; - struct sockaddr_in *sin = (struct sockaddr_in *)&ifr.ifr_addr; + struct sockaddr_in sin; memset(&ifr, 0, sizeof(ifr)); strcpy(ifr.ifr_name, tapif); /* Don't read these incantations. Just cut & paste them like I did! */ - sin->sin_family = AF_INET; - sin->sin_addr.s_addr = htonl(ipaddr); + sin.sin_family = AF_INET; + sin.sin_addr.s_addr = htonl(ipaddr); + memcpy(&ifr.ifr_addr, &sin, sizeof(sin)); if (ioctl(fd, SIOCSIFADDR, &ifr) != 0) err(1, "Setting %s interface address", tapif); ifr.ifr_flags = IFF_UP; @@ -1639,15 +1640,6 @@ static void blk_request(struct virtqueue *vq) off = out->sector * 512; /* - * The block device implements "barriers", where the Guest indicates - * that it wants all previous writes to occur before this write. We - * don't have a way of asking our kernel to do a barrier, so we just - * synchronize all the data in the file. Pretty poor, no? - */ - if (out->type & VIRTIO_BLK_T_BARRIER) - fdatasync(vblk->fd); - - /* * In general the virtio block driver is allowed to try SCSI commands. * It'd be nice if we supported eject, for example, but we don't. */ @@ -1679,6 +1671,13 @@ static void blk_request(struct virtqueue *vq) /* Die, bad Guest, die. */ errx(1, "Write past end %llu+%u", off, ret); } + + wlen = sizeof(*in); + *in = (ret >= 0 ? VIRTIO_BLK_S_OK : VIRTIO_BLK_S_IOERR); + } else if (out->type & VIRTIO_BLK_T_FLUSH) { + /* Flush */ + ret = fdatasync(vblk->fd); + verbose("FLUSH fdatasync: %i\n", ret); wlen = sizeof(*in); *in = (ret >= 0 ? VIRTIO_BLK_S_OK : VIRTIO_BLK_S_IOERR); } else { @@ -1702,15 +1701,6 @@ static void blk_request(struct virtqueue *vq) } } - /* - * OK, so we noted that it was pretty poor to use an fdatasync as a - * barrier. But Christoph Hellwig points out that we need a sync - * *afterwards* as well: "Barriers specify no reordering to the front - * or the back." And Jens Axboe confirmed it, so here we are: - */ - if (out->type & VIRTIO_BLK_T_BARRIER) - fdatasync(vblk->fd); - /* Finished that request. */ add_used(vq, head, wlen); } @@ -1735,8 +1725,8 @@ static void setup_block_file(const char *filename) vblk->fd = open_or_die(filename, O_RDWR|O_LARGEFILE); vblk->len = lseek64(vblk->fd, 0, SEEK_END); - /* We support barriers. */ - add_feature(dev, VIRTIO_BLK_F_BARRIER); + /* We support FLUSH. */ + add_feature(dev, VIRTIO_BLK_F_FLUSH); /* Tell Guest how many sectors this device has. */ conf.capacity = cpu_to_le64(vblk->len / 512); diff --git a/Documentation/md.txt b/Documentation/md.txt index e4e893ef3e0..a81c7b4790f 100644 --- a/Documentation/md.txt +++ b/Documentation/md.txt @@ -1,5 +1,5 @@ Tools that manage md devices can be found at - http://www.<country>.kernel.org/pub/linux/utils/raid/.... + http://www.kernel.org/pub/linux/utils/raid/ Boot time assembly of RAID arrays diff --git a/Documentation/misc-devices/apds990x.txt b/Documentation/misc-devices/apds990x.txt new file mode 100644 index 00000000000..d5408cade32 --- /dev/null +++ b/Documentation/misc-devices/apds990x.txt @@ -0,0 +1,111 @@ +Kernel driver apds990x +====================== + +Supported chips: +Avago APDS990X + +Data sheet: +Not freely available + +Author: +Samu Onkalo <samu.p.onkalo@nokia.com> + +Description +----------- + +APDS990x is a combined ambient light and proximity sensor. ALS and proximity +functionality are highly connected. ALS measurement path must be running +while the proximity functionality is enabled. + +ALS produces raw measurement values for two channels: Clear channel +(infrared + visible light) and IR only. However, threshold comparisons happen +using clear channel only. Lux value and the threshold level on the HW +might vary quite much depending the spectrum of the light source. + +Driver makes necessary conversions to both directions so that user handles +only lux values. Lux value is calculated using information from the both +channels. HW threshold level is calculated from the given lux value to match +with current type of the lightning. Sometimes inaccuracy of the estimations +lead to false interrupt, but that doesn't harm. + +ALS contains 4 different gain steps. Driver automatically +selects suitable gain step. After each measurement, reliability of the results +is estimated and new measurement is trigged if necessary. + +Platform data can provide tuned values to the conversion formulas if +values are known. Otherwise plain sensor default values are used. + +Proximity side is little bit simpler. There is no need for complex conversions. +It produces directly usable values. + +Driver controls chip operational state using pm_runtime framework. +Voltage regulators are controlled based on chip operational state. + +SYSFS +----- + + +chip_id + RO - shows detected chip type and version + +power_state + RW - enable / disable chip. Uses counting logic + 1 enables the chip + 0 disables the chip +lux0_input + RO - measured lux value + sysfs_notify called when threshold interrupt occurs + +lux0_sensor_range + RO - lux0_input max value. Actually never reaches since sensor tends + to saturate much before that. Real max value varies depending + on the light spectrum etc. + +lux0_rate + RW - measurement rate in Hz + +lux0_rate_avail + RO - supported measurement rates + +lux0_calibscale + RW - calibration value. Set to neutral value by default. + Output results are multiplied with calibscale / calibscale_default + value. + +lux0_calibscale_default + RO - neutral calibration value + +lux0_thresh_above_value + RW - HI level threshold value. All results above the value + trigs an interrupt. 65535 (i.e. sensor_range) disables the above + interrupt. + +lux0_thresh_below_value + RW - LO level threshold value. All results below the value + trigs an interrupt. 0 disables the below interrupt. + +prox0_raw + RO - measured proximity value + sysfs_notify called when threshold interrupt occurs + +prox0_sensor_range + RO - prox0_raw max value (1023) + +prox0_raw_en + RW - enable / disable proximity - uses counting logic + 1 enables the proximity + 0 disables the proximity + +prox0_reporting_mode + RW - trigger / periodic. In "trigger" mode the driver tells two possible + values: 0 or prox0_sensor_range value. 0 means no proximity, + 1023 means proximity. This causes minimal number of interrupts. + In "periodic" mode the driver reports all values above + prox0_thresh_above. This causes more interrupts, but it can give + _rough_ estimate about the distance. + +prox0_reporting_mode_avail + RO - accepted values to prox0_reporting_mode (trigger, periodic) + +prox0_thresh_above_value + RW - threshold level which trigs proximity events. diff --git a/Documentation/misc-devices/bh1770glc.txt b/Documentation/misc-devices/bh1770glc.txt new file mode 100644 index 00000000000..7d64c014dc7 --- /dev/null +++ b/Documentation/misc-devices/bh1770glc.txt @@ -0,0 +1,116 @@ +Kernel driver bh1770glc +======================= + +Supported chips: +ROHM BH1770GLC +OSRAM SFH7770 + +Data sheet: +Not freely available + +Author: +Samu Onkalo <samu.p.onkalo@nokia.com> + +Description +----------- +BH1770GLC and SFH7770 are combined ambient light and proximity sensors. +ALS and proximity parts operates on their own, but they shares common I2C +interface and interrupt logic. In principle they can run on their own, +but ALS side results are used to estimate reliability of the proximity sensor. + +ALS produces 16 bit lux values. The chip contains interrupt logic to produce +low and high threshold interrupts. + +Proximity part contains IR-led driver up to 3 IR leds. The chip measures +amount of reflected IR light and produces proximity result. Resolution is +8 bit. Driver supports only one channel. Driver uses ALS results to estimate +reliability of the proximity results. Thus ALS is always running while +proximity detection is needed. + +Driver uses threshold interrupts to avoid need for polling the values. +Proximity low interrupt doesn't exists in the chip. This is simulated +by using a delayed work. As long as there is proximity threshold above +interrupts the delayed work is pushed forward. So, when proximity level goes +below the threshold value, there is no interrupt and the delayed work will +finally run. This is handled as no proximity indication. + +Chip state is controlled via runtime pm framework when enabled in config. + +Calibscale factor is used to hide differences between the chips. By default +value set to neutral state meaning factor of 1.00. To get proper values, +calibrated source of light is needed as a reference. Calibscale factor is set +so that measurement produces about the expected lux value. + +SYSFS +----- + +chip_id + RO - shows detected chip type and version + +power_state + RW - enable / disable chip. Uses counting logic + 1 enables the chip + 0 disables the chip + +lux0_input + RO - measured lux value + sysfs_notify called when threshold interrupt occurs + +lux0_sensor_range + RO - lux0_input max value + +lux0_rate + RW - measurement rate in Hz + +lux0_rate_avail + RO - supported measurement rates + +lux0_thresh_above_value + RW - HI level threshold value. All results above the value + trigs an interrupt. 65535 (i.e. sensor_range) disables the above + interrupt. + +lux0_thresh_below_value + RW - LO level threshold value. All results below the value + trigs an interrupt. 0 disables the below interrupt. + +lux0_calibscale + RW - calibration value. Set to neutral value by default. + Output results are multiplied with calibscale / calibscale_default + value. + +lux0_calibscale_default + RO - neutral calibration value + +prox0_raw + RO - measured proximity value + sysfs_notify called when threshold interrupt occurs + +prox0_sensor_range + RO - prox0_raw max value + +prox0_raw_en + RW - enable / disable proximity - uses counting logic + 1 enables the proximity + 0 disables the proximity + +prox0_thresh_above_count + RW - number of proximity interrupts needed before triggering the event + +prox0_rate_above + RW - Measurement rate (in Hz) when the level is above threshold + i.e. when proximity on has been reported. + +prox0_rate_below + RW - Measurement rate (in Hz) when the level is below threshold + i.e. when proximity off has been reported. + +prox0_rate_avail + RO - Supported proximity measurement rates in Hz + +prox0_thresh_above0_value + RW - threshold level which trigs proximity events. + Filtered by persistence filter (prox0_thresh_above_count) + +prox0_thresh_above1_value + RW - threshold level which trigs event immediately diff --git a/Documentation/misc-devices/c2port.txt b/Documentation/misc-devices/c2port.txt index d9bf93ea439..ea734446561 100644 --- a/Documentation/misc-devices/c2port.txt +++ b/Documentation/misc-devices/c2port.txt @@ -32,10 +32,10 @@ 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 +http://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf - C2 Specification at -http://www.silabs.com/public/documents/tpub_doc/spec/Microcontrollers/en/C2spec.pdf, +http://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults however it implements a two wire serial communication protocol (bit banging) designed to enable in-system programming, debugging, and diff --git a/Documentation/mmc/00-INDEX b/Documentation/mmc/00-INDEX new file mode 100644 index 00000000000..fca586f5b85 --- /dev/null +++ b/Documentation/mmc/00-INDEX @@ -0,0 +1,4 @@ +00-INDEX + - this file +mmc-dev-attrs.txt + - info on SD and MMC device attributes diff --git a/Documentation/mmc/mmc-dev-attrs.txt b/Documentation/mmc/mmc-dev-attrs.txt new file mode 100644 index 00000000000..ff2bd685bce --- /dev/null +++ b/Documentation/mmc/mmc-dev-attrs.txt @@ -0,0 +1,56 @@ +SD and MMC Device Attributes +============================ + +All attributes are read-only. + + cid Card Identifaction Register + csd Card Specific Data Register + scr SD Card Configuration Register (SD only) + date Manufacturing Date (from CID Register) + fwrev Firmware/Product Revision (from CID Register) (SD and MMCv1 only) + hwrev Hardware/Product Revision (from CID Register) (SD and MMCv1 only) + manfid Manufacturer ID (from CID Register) + name Product Name (from CID Register) + oemid OEM/Application ID (from CID Register) + serial Product Serial Number (from CID Register) + erase_size Erase group size + preferred_erase_size Preferred erase size + +Note on Erase Size and Preferred Erase Size: + + "erase_size" is the minimum size, in bytes, of an erase + operation. For MMC, "erase_size" is the erase group size + reported by the card. Note that "erase_size" does not apply + to trim or secure trim operations where the minimum size is + always one 512 byte sector. For SD, "erase_size" is 512 + if the card is block-addressed, 0 otherwise. + + SD/MMC cards can erase an arbitrarily large area up to and + including the whole card. When erasing a large area it may + be desirable to do it in smaller chunks for three reasons: + 1. A single erase command will make all other I/O on + the card wait. This is not a problem if the whole card + is being erased, but erasing one partition will make + I/O for another partition on the same card wait for the + duration of the erase - which could be a several + minutes. + 2. To be able to inform the user of erase progress. + 3. The erase timeout becomes too large to be very + useful. Because the erase timeout contains a margin + which is multiplied by the size of the erase area, + the value can end up being several minutes for large + areas. + + "erase_size" is not the most efficient unit to erase + (especially for SD where it is just one sector), + hence "preferred_erase_size" provides a good chunk + size for erasing large areas. + + For MMC, "preferred_erase_size" is the high-capacity + erase size if a card specifies one, otherwise it is + based on the capacity of the card. + + For SD, "preferred_erase_size" is the allocation unit + size specified by the card. + + "preferred_erase_size" is in bytes. diff --git a/Documentation/mtd/nand_ecc.txt b/Documentation/mtd/nand_ecc.txt index 274821b35a7..990efd7a981 100644 --- a/Documentation/mtd/nand_ecc.txt +++ b/Documentation/mtd/nand_ecc.txt @@ -91,7 +91,7 @@ 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 +(http://www.st.com/stonline/) 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. diff --git a/Documentation/mutex-design.txt b/Documentation/mutex-design.txt index c91ccc0720f..38c10fd7f41 100644 --- a/Documentation/mutex-design.txt +++ b/Documentation/mutex-design.txt @@ -9,7 +9,7 @@ firstly, there's nothing wrong with semaphores. But if the simpler mutex semantics are sufficient for your code, then there are a couple of advantages of mutexes: - - 'struct mutex' is smaller on most architectures: .e.g on x86, + - 'struct mutex' is smaller on most architectures: E.g. on x86, 'struct semaphore' is 20 bytes, 'struct mutex' is 16 bytes. A smaller structure size means less RAM footprint, and better CPU-cache utilization. @@ -136,3 +136,4 @@ the APIs of 'struct mutex' have been streamlined: void mutex_lock_nested(struct mutex *lock, unsigned int subclass); int mutex_lock_interruptible_nested(struct mutex *lock, unsigned int subclass); + int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock); diff --git a/Documentation/networking/3c509.txt b/Documentation/networking/3c509.txt index 3c45d5dcd63..dcc9eaf5939 100644 --- a/Documentation/networking/3c509.txt +++ b/Documentation/networking/3c509.txt @@ -31,7 +31,7 @@ models: Large portions of this documentation were heavily borrowed from the guide written the original author of the 3c509 driver, Donald Becker. The master copy of that document, which contains notes on older versions of the driver, -currently resides on Scyld web server: http://www.scyld.com/network/3c509.html. +currently resides on Scyld web server: http://www.scyld.com/. (1) Special Driver Features diff --git a/Documentation/networking/README.ipw2100 b/Documentation/networking/README.ipw2100 index f3fcaa41f77..6f85e1d0603 100644 --- a/Documentation/networking/README.ipw2100 +++ b/Documentation/networking/README.ipw2100 @@ -72,8 +72,7 @@ such, if you are interested in deploying or shipping a driver as part of solution intended to be used for purposes other than development, please obtain a tested driver from Intel Customer Support at: -http://support.intel.com/support/notebook/sb/CS-006408.htm - +http://www.intel.com/support/wireless/sb/CS-006408.htm 1. Introduction ----------------------------------------------- diff --git a/Documentation/networking/README.ipw2200 b/Documentation/networking/README.ipw2200 index 80c728522c4..616a8e540b0 100644 --- a/Documentation/networking/README.ipw2200 +++ b/Documentation/networking/README.ipw2200 @@ -85,7 +85,7 @@ such, if you are interested in deploying or shipping a driver as part of solution intended to be used for purposes other than development, please obtain a tested driver from Intel Customer Support at: -http://support.intel.com/support/notebook/sb/CS-006408.htm +http://support.intel.com 1. Introduction @@ -171,7 +171,7 @@ Where the supported parameter are: led Can be used to turn on experimental LED code. - 0 = Off, 1 = On. Default is 0. + 0 = Off, 1 = On. Default is 1. mode Can be used to set the default mode of the adapter. diff --git a/Documentation/networking/README.sb1000 b/Documentation/networking/README.sb1000 index f82d42584e9..f92c2aac56a 100644 --- a/Documentation/networking/README.sb1000 +++ b/Documentation/networking/README.sb1000 @@ -27,8 +27,8 @@ cable modem easy. in Franco's original source code distribution .tar.gz file. Support for the sb1000 driver can be found at: - http://home.adelphia.net/~siglercm/sb1000.html - http://linuxpower.cx/~cable/ + http://web.archive.org/web/*/http://home.adelphia.net/~siglercm/sb1000.html + http://web.archive.org/web/*/http://linuxpower.cx/~cable/ along with these utilities. diff --git a/Documentation/networking/arcnet.txt b/Documentation/networking/arcnet.txt index 79601254038..9ff57950215 100644 --- a/Documentation/networking/arcnet.txt +++ b/Documentation/networking/arcnet.txt @@ -68,7 +68,7 @@ REAL NAME" to listserv@tichy.ch.uj.edu.pl. Then, to submit messages to the list, mail to linux-arcnet@tichy.ch.uj.edu.pl. There are archives of the mailing list at: - http://tichy.ch.uj.edu.pl/lists/linux-arcnet + http://epistolary.org/mailman/listinfo.cgi/arcnet The people on linux-net@vger.kernel.org have also been known to be very helpful, especially when we're talking about ALPHA Linux kernels that may or @@ -79,7 +79,7 @@ Other Drivers and Info ---------------------- You can try my ARCNET page on the World Wide Web at: - http://www.worldvisions.ca/~apenwarr/arcnet/ + http://www.qis.net/~jschmitz/arcnet/ Also, SMC (one of the companies that makes ARCnet cards) has a WWW site you might be interested in, which includes several drivers for various cards diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt index 61f516b135b..5dc638791d9 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.txt @@ -49,6 +49,7 @@ Table of Contents 3.3 Configuring Bonding Manually with Ifenslave 3.3.1 Configuring Multiple Bonds Manually 3.4 Configuring Bonding Manually via Sysfs +3.5 Overriding Configuration for Special Cases 4. Querying Bonding Configuration 4.1 Bonding Configuration @@ -764,6 +765,14 @@ xmit_hash_policy does not exist, and the layer2 policy is the only policy. The layer2+3 value was added for bonding version 3.2.2. +resend_igmp + + Specifies the number of IGMP membership reports to be issued after + a failover event. One membership report is issued immediately after + the failover, subsequent packets are sent in each 200ms interval. + + The valid range is 0 - 255; the default value is 1. This option + was added for bonding version 3.7.0. 3. Configuring Bonding Devices ============================== @@ -1318,8 +1327,87 @@ echo 2000 > /sys/class/net/bond1/bonding/arp_interval echo +eth2 > /sys/class/net/bond1/bonding/slaves echo +eth3 > /sys/class/net/bond1/bonding/slaves - -4. Querying Bonding Configuration +3.5 Overriding Configuration for Special Cases +---------------------------------------------- +When using the bonding driver, the physical port which transmits a frame is +typically selected by the bonding driver, and is not relevant to the user or +system administrator. The output port is simply selected using the policies of +the selected bonding mode. On occasion however, it is helpful to direct certain +classes of traffic to certain physical interfaces on output to implement +slightly more complex policies. For example, to reach a web server over a +bonded interface in which eth0 connects to a private network, while eth1 +connects via a public network, it may be desirous to bias the bond to send said +traffic over eth0 first, using eth1 only as a fall back, while all other traffic +can safely be sent over either interface. Such configurations may be achieved +using the traffic control utilities inherent in linux. + +By default the bonding driver is multiqueue aware and 16 queues are created +when the driver initializes (see Documentation/networking/multiqueue.txt +for details). If more or less queues are desired the module parameter +tx_queues can be used to change this value. There is no sysfs parameter +available as the allocation is done at module init time. + +The output of the file /proc/net/bonding/bondX has changed so the output Queue +ID is now printed for each slave: + +Bonding Mode: fault-tolerance (active-backup) +Primary Slave: None +Currently Active Slave: eth0 +MII Status: up +MII Polling Interval (ms): 0 +Up Delay (ms): 0 +Down Delay (ms): 0 + +Slave Interface: eth0 +MII Status: up +Link Failure Count: 0 +Permanent HW addr: 00:1a:a0:12:8f:cb +Slave queue ID: 0 + +Slave Interface: eth1 +MII Status: up +Link Failure Count: 0 +Permanent HW addr: 00:1a:a0:12:8f:cc +Slave queue ID: 2 + +The queue_id for a slave can be set using the command: + +# echo "eth1:2" > /sys/class/net/bond0/bonding/queue_id + +Any interface that needs a queue_id set should set it with multiple calls +like the one above until proper priorities are set for all interfaces. On +distributions that allow configuration via initscripts, multiple 'queue_id' +arguments can be added to BONDING_OPTS to set all needed slave queues. + +These queue id's can be used in conjunction with the tc utility to configure +a multiqueue qdisc and filters to bias certain traffic to transmit on certain +slave devices. For instance, say we wanted, in the above configuration to +force all traffic bound to 192.168.1.100 to use eth1 in the bond as its output +device. The following commands would accomplish this: + +# tc qdisc add dev bond0 handle 1 root multiq + +# tc filter add dev bond0 protocol ip parent 1: prio 1 u32 match ip dst \ + 192.168.1.100 action skbedit queue_mapping 2 + +These commands tell the kernel to attach a multiqueue queue discipline to the +bond0 interface and filter traffic enqueued to it, such that packets with a dst +ip of 192.168.1.100 have their output queue mapping value overwritten to 2. +This value is then passed into the driver, causing the normal output path +selection policy to be overridden, selecting instead qid 2, which maps to eth1. + +Note that qid values begin at 1. Qid 0 is reserved to initiate to the driver +that normal output policy selection should take place. One benefit to simply +leaving the qid for a slave to 0 is the multiqueue awareness in the bonding +driver that is now present. This awareness allows tc filters to be placed on +slave devices as well as bond devices and the bonding driver will simply act as +a pass-through for selecting output queues on the slave device rather than +output port selection. + +This feature first appeared in bonding driver version 3.7.0 and support for +output slave selection was limited to round-robin and active-backup modes. + +4 Querying Bonding Configuration ================================= 4.1 Bonding Configuration @@ -2432,7 +2520,7 @@ be found at: https://lists.sourceforge.net/lists/listinfo/bonding-devel Donald Becker's Ethernet Drivers and diag programs may be found at : - - http://www.scyld.com/network/ + - http://web.archive.org/web/*/http://www.scyld.com/network/ You will also find a lot of information regarding Ethernet, NWay, MII, etc. at www.scyld.com. diff --git a/Documentation/networking/caif/spi_porting.txt b/Documentation/networking/caif/spi_porting.txt new file mode 100644 index 00000000000..61d7c924745 --- /dev/null +++ b/Documentation/networking/caif/spi_porting.txt @@ -0,0 +1,208 @@ +- CAIF SPI porting - + +- CAIF SPI basics: + +Running CAIF over SPI needs some extra setup, owing to the nature of SPI. +Two extra GPIOs have been added in order to negotiate the transfers + between the master and the slave. The minimum requirement for running +CAIF over SPI is a SPI slave chip and two GPIOs (more details below). +Please note that running as a slave implies that you need to keep up +with the master clock. An overrun or underrun event is fatal. + +- CAIF SPI framework: + +To make porting as easy as possible, the CAIF SPI has been divided in +two parts. The first part (called the interface part) deals with all +generic functionality such as length framing, SPI frame negotiation +and SPI frame delivery and transmission. The other part is the CAIF +SPI slave device part, which is the module that you have to write if +you want to run SPI CAIF on a new hardware. This part takes care of +the physical hardware, both with regard to SPI and to GPIOs. + +- Implementing a CAIF SPI device: + + - Functionality provided by the CAIF SPI slave device: + + In order to implement a SPI device you will, as a minimum, + need to implement the following + functions: + + int (*init_xfer) (struct cfspi_xfer * xfer, struct cfspi_dev *dev): + + This function is called by the CAIF SPI interface to give + you a chance to set up your hardware to be ready to receive + a stream of data from the master. The xfer structure contains + both physical and logical adresses, as well as the total length + of the transfer in both directions.The dev parameter can be used + to map to different CAIF SPI slave devices. + + void (*sig_xfer) (bool xfer, struct cfspi_dev *dev): + + This function is called by the CAIF SPI interface when the output + (SPI_INT) GPIO needs to change state. The boolean value of the xfer + variable indicates whether the GPIO should be asserted (HIGH) or + deasserted (LOW). The dev parameter can be used to map to different CAIF + SPI slave devices. + + - Functionality provided by the CAIF SPI interface: + + void (*ss_cb) (bool assert, struct cfspi_ifc *ifc); + + This function is called by the CAIF SPI slave device in order to + signal a change of state of the input GPIO (SS) to the interface. + Only active edges are mandatory to be reported. + This function can be called from IRQ context (recommended in order + not to introduce latency). The ifc parameter should be the pointer + returned from the platform probe function in the SPI device structure. + + void (*xfer_done_cb) (struct cfspi_ifc *ifc); + + This function is called by the CAIF SPI slave device in order to + report that a transfer is completed. This function should only be + called once both the transmission and the reception are completed. + This function can be called from IRQ context (recommended in order + not to introduce latency). The ifc parameter should be the pointer + returned from the platform probe function in the SPI device structure. + + - Connecting the bits and pieces: + + - Filling in the SPI slave device structure: + + Connect the necessary callback functions. + Indicate clock speed (used to calculate toggle delays). + Chose a suitable name (helps debugging if you use several CAIF + SPI slave devices). + Assign your private data (can be used to map to your structure). + + - Filling in the SPI slave platform device structure: + Add name of driver to connect to ("cfspi_sspi"). + Assign the SPI slave device structure as platform data. + +- Padding: + +In order to optimize throughput, a number of SPI padding options are provided. +Padding can be enabled independently for uplink and downlink transfers. +Padding can be enabled for the head, the tail and for the total frame size. +The padding needs to be correctly configured on both sides of the link. +The padding can be changed via module parameters in cfspi_sspi.c or via +the sysfs directory of the cfspi_sspi driver (before device registration). + +- CAIF SPI device template: + +/* + * Copyright (C) ST-Ericsson AB 2010 + * Author: Daniel Martensson / Daniel.Martensson@stericsson.com + * License terms: GNU General Public License (GPL), version 2. + * + */ + +#include <linux/init.h> +#include <linux/module.h> +#include <linux/device.h> +#include <linux/wait.h> +#include <linux/interrupt.h> +#include <linux/dma-mapping.h> +#include <net/caif/caif_spi.h> + +MODULE_LICENSE("GPL"); + +struct sspi_struct { + struct cfspi_dev sdev; + struct cfspi_xfer *xfer; +}; + +static struct sspi_struct slave; +static struct platform_device slave_device; + +static irqreturn_t sspi_irq(int irq, void *arg) +{ + /* You only need to trigger on an edge to the active state of the + * SS signal. Once a edge is detected, the ss_cb() function should be + * called with the parameter assert set to true. It is OK + * (and even advised) to call the ss_cb() function in IRQ context in + * order not to add any delay. */ + + return IRQ_HANDLED; +} + +static void sspi_complete(void *context) +{ + /* Normally the DMA or the SPI framework will call you back + * in something similar to this. The only thing you need to + * do is to call the xfer_done_cb() function, providing the pointer + * to the CAIF SPI interface. It is OK to call this function + * from IRQ context. */ +} + +static int sspi_init_xfer(struct cfspi_xfer *xfer, struct cfspi_dev *dev) +{ + /* Store transfer info. For a normal implementation you should + * set up your DMA here and make sure that you are ready to + * receive the data from the master SPI. */ + + struct sspi_struct *sspi = (struct sspi_struct *)dev->priv; + + sspi->xfer = xfer; + + return 0; +} + +void sspi_sig_xfer(bool xfer, struct cfspi_dev *dev) +{ + /* If xfer is true then you should assert the SPI_INT to indicate to + * the master that you are ready to recieve the data from the master + * SPI. If xfer is false then you should de-assert SPI_INT to indicate + * that the transfer is done. + */ + + struct sspi_struct *sspi = (struct sspi_struct *)dev->priv; +} + +static void sspi_release(struct device *dev) +{ + /* + * Here you should release your SPI device resources. + */ +} + +static int __init sspi_init(void) +{ + /* Here you should initialize your SPI device by providing the + * necessary functions, clock speed, name and private data. Once + * done, you can register your device with the + * platform_device_register() function. This function will return + * with the CAIF SPI interface initialized. This is probably also + * the place where you should set up your GPIOs, interrupts and SPI + * resources. */ + + int res = 0; + + /* Initialize slave device. */ + slave.sdev.init_xfer = sspi_init_xfer; + slave.sdev.sig_xfer = sspi_sig_xfer; + slave.sdev.clk_mhz = 13; + slave.sdev.priv = &slave; + slave.sdev.name = "spi_sspi"; + slave_device.dev.release = sspi_release; + + /* Initialize platform device. */ + slave_device.name = "cfspi_sspi"; + slave_device.dev.platform_data = &slave.sdev; + + /* Register platform device. */ + res = platform_device_register(&slave_device); + if (res) { + printk(KERN_WARNING "sspi_init: failed to register dev.\n"); + return -ENODEV; + } + + return res; +} + +static void __exit sspi_exit(void) +{ + platform_device_del(&slave_device); +} + +module_init(sspi_init); +module_exit(sspi_exit); diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt index cd79735013f..5b04b67ddca 100644 --- a/Documentation/networking/can.txt +++ b/Documentation/networking/can.txt @@ -22,6 +22,7 @@ This file contains 4.1.2 RAW socket option CAN_RAW_ERR_FILTER 4.1.3 RAW socket option CAN_RAW_LOOPBACK 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS + 4.1.5 RAW socket returned message flags 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) 4.3 connected transport protocols (SOCK_SEQPACKET) 4.4 unconnected transport protocols (SOCK_DGRAM) @@ -471,6 +472,17 @@ solution for a couple of reasons: setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, &recv_own_msgs, sizeof(recv_own_msgs)); + 4.1.5 RAW socket returned message flags + + When using recvmsg() call, the msg->msg_flags may contain following flags: + + MSG_DONTROUTE: set when the received frame was created on the local host. + + MSG_CONFIRM: set when the frame was sent via the socket it is received on. + This flag can be interpreted as a 'transmission confirmation' when the + CAN driver supports the echo of frames on driver level, see 3.2 and 6.2. + In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set. + 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) 4.3 connected transport protocols (SOCK_SEQPACKET) 4.4 unconnected transport protocols (SOCK_DGRAM) diff --git a/Documentation/networking/dccp.txt b/Documentation/networking/dccp.txt index a62fdf7a6bf..271d524a4c8 100644 --- a/Documentation/networking/dccp.txt +++ b/Documentation/networking/dccp.txt @@ -1,18 +1,20 @@ DCCP protocol -============ +============= Contents ======== - - Introduction - Missing features - Socket options +- Sysctl variables +- IOCTLs +- Other tunables - Notes + Introduction ============ - Datagram Congestion Control Protocol (DCCP) is an unreliable, connection oriented protocol designed to solve issues present in UDP and TCP, particularly for real-time and multimedia (streaming) traffic. @@ -29,9 +31,9 @@ It has a base protocol and pluggable congestion control IDs (CCIDs). DCCP is a Proposed Standard (RFC 2026), and the homepage for DCCP as a protocol is at http://www.ietf.org/html.charters/dccp-charter.html + Missing features ================ - The Linux DCCP implementation does not currently support all the features that are specified in RFCs 4340...42. @@ -45,7 +47,6 @@ http://linux-net.osdl.org/index.php/DCCP_Testing#Experimental_DCCP_source_tree Socket options ============== - DCCP_SOCKOPT_SERVICE sets the service. The specification mandates use of service codes (RFC 4340, sec. 8.1.2); if this socket option is not set, the socket will fall back to 0 (which means that no meaningful service code @@ -112,6 +113,7 @@ DCCP_SOCKOPT_CCID_TX_INFO On unidirectional connections it is useful to close the unused half-connection via shutdown (SHUT_WR or SHUT_RD): this will reduce per-packet processing costs. + Sysctl variables ================ Several DCCP default parameters can be managed by the following sysctls @@ -155,15 +157,30 @@ sync_ratelimit = 125 ms sequence-invalid packets on the same socket (RFC 4340, 7.5.4). The unit of this parameter is milliseconds; a value of 0 disables rate-limiting. + IOCTLS ====== FIONREAD Works as in udp(7): returns in the `int' argument pointer the size of the next pending datagram in bytes, or 0 when no datagram is pending. + +Other tunables +============== +Per-route rto_min support + CCID-2 supports the RTAX_RTO_MIN per-route setting for the minimum value + of the RTO timer. This setting can be modified via the 'rto_min' option + of iproute2; for example: + > ip route change 10.0.0.0/24 rto_min 250j dev wlan0 + > ip route add 10.0.0.254/32 rto_min 800j dev wlan0 + > ip route show dev wlan0 + CCID-3 also supports the rto_min setting: it is used to define the lower + bound for the expiry of the nofeedback timer. This can be useful on LANs + with very low RTTs (e.g., loopback, Gbit ethernet). + + Notes ===== - DCCP does not travel through NAT successfully at present on many boxes. This is because the checksum covers the pseudo-header as per TCP and UDP. Linux NAT support for DCCP has been added. diff --git a/Documentation/networking/decnet.txt b/Documentation/networking/decnet.txt index d8968958d83..e12a4900cf7 100644 --- a/Documentation/networking/decnet.txt +++ b/Documentation/networking/decnet.txt @@ -4,7 +4,7 @@ 1) Other documentation.... o Project Home Pages - http://www.chygwyn.com/DECnet/ - Kernel info + http://www.chygwyn.com/ - Kernel info http://linux-decnet.sourceforge.net/ - Userland tools http://www.sourceforge.net/projects/linux-decnet/ - Status page diff --git a/Documentation/networking/dns_resolver.txt b/Documentation/networking/dns_resolver.txt new file mode 100644 index 00000000000..aefd1e68180 --- /dev/null +++ b/Documentation/networking/dns_resolver.txt @@ -0,0 +1,146 @@ + =================== + DNS Resolver Module + =================== + +Contents: + + - Overview. + - Compilation. + - Setting up. + - Usage. + - Mechanism. + - Debugging. + + +======== +OVERVIEW +======== + +The DNS resolver module provides a way for kernel services to make DNS queries +by way of requesting a key of key type dns_resolver. These queries are +upcalled to userspace through /sbin/request-key. + +These routines must be supported by userspace tools dns.upcall, cifs.upcall and +request-key. It is under development and does not yet provide the full feature +set. The features it does support include: + + (*) Implements the dns_resolver key_type to contact userspace. + +It does not yet support the following AFS features: + + (*) Dns query support for AFSDB resource record. + +This code is extracted from the CIFS filesystem. + + +=========== +COMPILATION +=========== + +The module should be enabled by turning on the kernel configuration options: + + CONFIG_DNS_RESOLVER - tristate "DNS Resolver support" + + +========== +SETTING UP +========== + +To set up this facility, the /etc/request-key.conf file must be altered so that +/sbin/request-key can appropriately direct the upcalls. For example, to handle +basic dname to IPv4/IPv6 address resolution, the following line should be +added: + + #OP TYPE DESC CO-INFO PROGRAM ARG1 ARG2 ARG3 ... + #====== ============ ======= ======= ========================== + create dns_resolver * * /usr/sbin/cifs.upcall %k + +To direct a query for query type 'foo', a line of the following should be added +before the more general line given above as the first match is the one taken. + + create dns_resolver foo:* * /usr/sbin/dns.foo %k + + + +===== +USAGE +===== + +To make use of this facility, one of the following functions that are +implemented in the module can be called after doing: + + #include <linux/dns_resolver.h> + + (1) int dns_query(const char *type, const char *name, size_t namelen, + const char *options, char **_result, time_t *_expiry); + + This is the basic access function. It looks for a cached DNS query and if + it doesn't find it, it upcalls to userspace to make a new DNS query, which + may then be cached. The key description is constructed as a string of the + form: + + [<type>:]<name> + + where <type> optionally specifies the particular upcall program to invoke, + and thus the type of query to do, and <name> specifies the string to be + looked up. The default query type is a straight hostname to IP address + set lookup. + + The name parameter is not required to be a NUL-terminated string, and its + length should be given by the namelen argument. + + The options parameter may be NULL or it may be a set of options + appropriate to the query type. + + The return value is a string appropriate to the query type. For instance, + for the default query type it is just a list of comma-separated IPv4 and + IPv6 addresses. The caller must free the result. + + The length of the result string is returned on success, and a negative + error code is returned otherwise. -EKEYREJECTED will be returned if the + DNS lookup failed. + + If _expiry is non-NULL, the expiry time (TTL) of the result will be + returned also. + + +========= +MECHANISM +========= + +The dnsresolver module registers a key type called "dns_resolver". Keys of +this type are used to transport and cache DNS lookup results from userspace. + +When dns_query() is invoked, it calls request_key() to search the local +keyrings for a cached DNS result. If that fails to find one, it upcalls to +userspace to get a new result. + +Upcalls to userspace are made through the request_key() upcall vector, and are +directed by means of configuration lines in /etc/request-key.conf that tell +/sbin/request-key what program to run to instantiate the key. + +The upcall handler program is responsible for querying the DNS, processing the +result into a form suitable for passing to the keyctl_instantiate_key() +routine. This then passes the data to dns_resolver_instantiate() which strips +off and processes any options included in the data, and then attaches the +remainder of the string to the key as its payload. + +The upcall handler program should set the expiry time on the key to that of the +lowest TTL of all the records it has extracted a result from. This means that +the key will be discarded and recreated when the data it holds has expired. + +dns_query() returns a copy of the value attached to the key, or an error if +that is indicated instead. + +See <file:Documentation/keys-request-key.txt> for further information about +request-key function. + + +========= +DEBUGGING +========= + +Debugging messages can be turned on dynamically by writing a 1 into the +following file: + + /sys/module/dnsresolver/parameters/debug diff --git a/Documentation/networking/e1000.txt b/Documentation/networking/e1000.txt index 2df71861e57..d9271e74e48 100644 --- a/Documentation/networking/e1000.txt +++ b/Documentation/networking/e1000.txt @@ -1,82 +1,35 @@ Linux* Base Driver for the Intel(R) PRO/1000 Family of Adapters =============================================================== -September 26, 2006 - +Intel Gigabit Linux driver. +Copyright(c) 1999 - 2010 Intel Corporation. Contents ======== -- In This Release - Identifying Your Adapter -- Building and Installation - Command Line Parameters - Speed and Duplex Configuration - Additional Configurations -- Known Issues - Support - -In This Release -=============== - -This file describes the Linux* Base Driver for the Intel(R) PRO/1000 Family -of Adapters. This driver includes support for Itanium(R)2-based systems. - -For questions related to hardware requirements, refer to the documentation -supplied with your Intel PRO/1000 adapter. All hardware requirements listed -apply to use with Linux. - -The following features are now available in supported kernels: - - Native VLANs - - Channel Bonding (teaming) - - SNMP - -Channel Bonding documentation can be found in the Linux kernel source: -/Documentation/networking/bonding.txt - -The driver information previously displayed in the /proc filesystem is not -supported in this release. Alternatively, you can use ethtool (version 1.6 -or later), lspci, and ifconfig to obtain the same information. - -Instructions on updating ethtool can be found in the section "Additional -Configurations" later in this document. - -NOTE: The Intel(R) 82562v 10/100 Network Connection only provides 10/100 -support. - - Identifying Your Adapter ======================== For more information on how to identify your adapter, go to the Adapter & Driver ID Guide at: - http://support.intel.com/support/network/adapter/pro100/21397.htm + http://support.intel.com/support/go/network/adapter/idguide.htm For the latest Intel network drivers for Linux, refer to the following website. In the search field, enter your adapter name or type, or use the networking link on the left to search for your adapter: - http://downloadfinder.intel.com/scripts-df/support_intel.asp - + http://support.intel.com/support/go/network/adapter/home.htm Command Line Parameters ======================= -If the driver is built as a module, the following optional parameters -are used by entering them on the command line with the modprobe command -using this syntax: - - modprobe e1000 [<option>=<VAL1>,<VAL2>,...] - -For example, with two PRO/1000 PCI adapters, entering: - - modprobe e1000 TxDescriptors=80,128 - -loads the e1000 driver with 80 TX descriptors for the first adapter and -128 TX descriptors for the second adapter. - The default value for each parameter is generally the recommended setting, unless otherwise noted. @@ -89,10 +42,6 @@ NOTES: For more information about the AutoNeg, Duplex, and Speed parameters, see the application note at: http://www.intel.com/design/network/applnots/ap450.htm - A descriptor describes a data buffer and attributes related to - the data buffer. This information is accessed by the hardware. - - AutoNeg ------- (Supported only on adapters with copper connections) @@ -106,7 +55,6 @@ Duplex parameters must not be specified. NOTE: Refer to the Speed and Duplex section of this readme for more information on the AutoNeg parameter. - Duplex ------ (Supported only on adapters with copper connections) @@ -119,7 +67,6 @@ set to auto-negotiate, the board auto-detects the correct duplex. If the link partner is forced (either full or half), Duplex defaults to half- duplex. - FlowControl ----------- Valid Range: 0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx) @@ -128,16 +75,16 @@ Default Value: Reads flow control settings from the EEPROM This parameter controls the automatic generation(Tx) and response(Rx) to Ethernet PAUSE frames. - InterruptThrottleRate --------------------- (not supported on Intel(R) 82542, 82543 or 82544-based adapters) -Valid Range: 0,1,3,100-100000 (0=off, 1=dynamic, 3=dynamic conservative) +Valid Range: 0,1,3,4,100-100000 (0=off, 1=dynamic, 3=dynamic conservative, + 4=simplified balancing) Default Value: 3 The driver can limit the amount of interrupts per second that the adapter -will generate for incoming packets. It does this by writing a value to the -adapter that is based on the maximum amount of interrupts that the adapter +will generate for incoming packets. It does this by writing a value to the +adapter that is based on the maximum amount of interrupts that the adapter will generate per second. Setting InterruptThrottleRate to a value greater or equal to 100 @@ -146,37 +93,43 @@ per second, even if more packets have come in. This reduces interrupt load on the system and can lower CPU utilization under heavy load, but will increase latency as packets are not processed as quickly. -The default behaviour of the driver previously assumed a static -InterruptThrottleRate value of 8000, providing a good fallback value for -all traffic types,but lacking in small packet performance and latency. -The hardware can handle many more small packets per second however, and +The default behaviour of the driver previously assumed a static +InterruptThrottleRate value of 8000, providing a good fallback value for +all traffic types,but lacking in small packet performance and latency. +The hardware can handle many more small packets per second however, and for this reason an adaptive interrupt moderation algorithm was implemented. Since 7.3.x, the driver has two adaptive modes (setting 1 or 3) in which -it dynamically adjusts the InterruptThrottleRate value based on the traffic +it dynamically adjusts the InterruptThrottleRate value based on the traffic that it receives. After determining the type of incoming traffic in the last -timeframe, it will adjust the InterruptThrottleRate to an appropriate value +timeframe, it will adjust the InterruptThrottleRate to an appropriate value for that traffic. The algorithm classifies the incoming traffic every interval into -classes. Once the class is determined, the InterruptThrottleRate value is -adjusted to suit that traffic type the best. There are three classes defined: +classes. Once the class is determined, the InterruptThrottleRate value is +adjusted to suit that traffic type the best. There are three classes defined: "Bulk traffic", for large amounts of packets of normal size; "Low latency", for small amounts of traffic and/or a significant percentage of small -packets; and "Lowest latency", for almost completely small packets or +packets; and "Lowest latency", for almost completely small packets or minimal traffic. -In dynamic conservative mode, the InterruptThrottleRate value is set to 4000 -for traffic that falls in class "Bulk traffic". If traffic falls in the "Low -latency" or "Lowest latency" class, the InterruptThrottleRate is increased +In dynamic conservative mode, the InterruptThrottleRate value is set to 4000 +for traffic that falls in class "Bulk traffic". If traffic falls in the "Low +latency" or "Lowest latency" class, the InterruptThrottleRate is increased stepwise to 20000. This default mode is suitable for most applications. For situations where low latency is vital such as cluster or grid computing, the algorithm can reduce latency even more when InterruptThrottleRate is set to mode 1. In this mode, which operates -the same as mode 3, the InterruptThrottleRate will be increased stepwise to +the same as mode 3, the InterruptThrottleRate will be increased stepwise to 70000 for traffic in class "Lowest latency". +In simplified mode the interrupt rate is based on the ratio of Tx and +Rx traffic. If the bytes per second rate is approximately equal, the +interrupt rate will drop as low as 2000 interrupts per second. If the +traffic is mostly transmit or mostly receive, the interrupt rate could +be as high as 8000. + Setting InterruptThrottleRate to 0 turns off any interrupt moderation and may improve small packet latency, but is generally not suitable for bulk throughput traffic. @@ -212,8 +165,6 @@ NOTE: When e1000 is loaded with default settings and multiple adapters be platform-specific. If CPU utilization is not a concern, use RX_POLLING (NAPI) and default driver settings. - - RxDescriptors ------------- Valid Range: 80-256 for 82542 and 82543-based adapters @@ -225,15 +176,14 @@ by the driver. Increasing this value allows the driver to buffer more incoming packets, at the expense of increased system memory utilization. Each descriptor is 16 bytes. A receive buffer is also allocated for each -descriptor and can be either 2048, 4096, 8192, or 16384 bytes, depending +descriptor and can be either 2048, 4096, 8192, or 16384 bytes, depending on the MTU setting. The maximum MTU size is 16110. -NOTE: MTU designates the frame size. It only needs to be set for Jumbo - Frames. Depending on the available system resources, the request - for a higher number of receive descriptors may be denied. In this +NOTE: MTU designates the frame size. It only needs to be set for Jumbo + Frames. Depending on the available system resources, the request + for a higher number of receive descriptors may be denied. In this case, use a lower number. - RxIntDelay ---------- Valid Range: 0-65535 (0=off) @@ -254,7 +204,6 @@ CAUTION: When setting RxIntDelay to a value other than 0, adapters may restoring the network connection. To eliminate the potential for the hang ensure that RxIntDelay is set to 0. - RxAbsIntDelay ------------- (This parameter is supported only on 82540, 82545 and later adapters.) @@ -268,7 +217,6 @@ packet is received within the set amount of time. Proper tuning, along with RxIntDelay, may improve traffic throughput in specific network conditions. - Speed ----- (This parameter is supported only on adapters with copper connections.) @@ -280,7 +228,6 @@ Speed forces the line speed to the specified value in megabits per second partner is set to auto-negotiate, the board will auto-detect the correct speed. Duplex should also be set when Speed is set to either 10 or 100. - TxDescriptors ------------- Valid Range: 80-256 for 82542 and 82543-based adapters @@ -295,6 +242,36 @@ NOTE: Depending on the available system resources, the request for a higher number of transmit descriptors may be denied. In this case, use a lower number. +TxDescriptorStep +---------------- +Valid Range: 1 (use every Tx Descriptor) + 4 (use every 4th Tx Descriptor) + +Default Value: 1 (use every Tx Descriptor) + +On certain non-Intel architectures, it has been observed that intense TX +traffic bursts of short packets may result in an improper descriptor +writeback. If this occurs, the driver will report a "TX Timeout" and reset +the adapter, after which the transmit flow will restart, though data may +have stalled for as much as 10 seconds before it resumes. + +The improper writeback does not occur on the first descriptor in a system +memory cache-line, which is typically 32 bytes, or 4 descriptors long. + +Setting TxDescriptorStep to a value of 4 will ensure that all TX descriptors +are aligned to the start of a system memory cache line, and so this problem +will not occur. + +NOTES: Setting TxDescriptorStep to 4 effectively reduces the number of + TxDescriptors available for transmits to 1/4 of the normal allocation. + This has a possible negative performance impact, which may be + compensated for by allocating more descriptors using the TxDescriptors + module parameter. + + There are other conditions which may result in "TX Timeout", which will + not be resolved by the use of the TxDescriptorStep parameter. As the + issue addressed by this parameter has never been observed on Intel + Architecture platforms, it should not be used on Intel platforms. TxIntDelay ---------- @@ -307,7 +284,6 @@ efficiency if properly tuned for specific network traffic. If the system is reporting dropped transmits, this value may be set too high causing the driver to run out of available transmit descriptors. - TxAbsIntDelay ------------- (This parameter is supported only on 82540, 82545 and later adapters.) @@ -330,6 +306,35 @@ Default Value: 1 A value of '1' indicates that the driver should enable IP checksum offload for received packets (both UDP and TCP) to the adapter hardware. +Copybreak +--------- +Valid Range: 0-xxxxxxx (0=off) +Default Value: 256 +Usage: insmod e1000.ko copybreak=128 + +Driver copies all packets below or equaling this size to a fresh Rx +buffer before handing it up the stack. + +This parameter is different than other parameters, in that it is a +single (not 1,1,1 etc.) parameter applied to all driver instances and +it is also available during runtime at +/sys/module/e1000/parameters/copybreak + +SmartPowerDownEnable +-------------------- +Valid Range: 0-1 +Default Value: 0 (disabled) + +Allows PHY to turn off in lower power states. The user can turn off +this parameter in supported chipsets. + +KumeranLockLoss +--------------- +Valid Range: 0-1 +Default Value: 1 (enabled) + +This workaround skips resetting the PHY at shutdown for the initial +silicon releases of ICH8 systems. Speed and Duplex Configuration ============================== @@ -385,40 +390,9 @@ If the link partner is forced to a specific speed and duplex, then this parameter should not be used. Instead, use the Speed and Duplex parameters previously mentioned to force the adapter to the same speed and duplex. - Additional Configurations ========================= - Configuring the Driver on Different Distributions - ------------------------------------------------- - Configuring a network driver to load properly when the system is started - is distribution dependent. Typically, the configuration process involves - adding an alias line to /etc/modules.conf or /etc/modprobe.conf as well - as editing other system startup scripts and/or configuration files. Many - popular Linux distributions ship with tools to make these changes for you. - To learn the proper way to configure a network device for your system, - refer to your distribution documentation. If during this process you are - asked for the driver or module name, the name for the Linux Base Driver - for the Intel(R) PRO/1000 Family of Adapters is e1000. - - As an example, if you install the e1000 driver for two PRO/1000 adapters - (eth0 and eth1) and set the speed and duplex to 10full and 100half, add - the following to modules.conf or or modprobe.conf: - - alias eth0 e1000 - alias eth1 e1000 - options e1000 Speed=10,100 Duplex=2,1 - - Viewing Link Messages - --------------------- - Link messages will not be displayed to the console if the distribution is - restricting system messages. In order to see network driver link messages - on your console, set dmesg to eight by entering the following: - - dmesg -n 8 - - NOTE: This setting is not saved across reboots. - Jumbo Frames ------------ Jumbo Frames support is enabled by changing the MTU to a value larger than @@ -437,9 +411,11 @@ Additional Configurations setting in a different location. Notes: - - - To enable Jumbo Frames, increase the MTU size on the interface beyond - 1500. + Degradation in throughput performance may be observed in some Jumbo frames + environments. If this is observed, increasing the application's socket buffer + size and/or increasing the /proc/sys/net/ipv4/tcp_*mem entry values may help. + See the specific application manual and /usr/src/linux*/Documentation/ + networking/ip-sysctl.txt for more details. - The maximum MTU setting for Jumbo Frames is 16110. This value coincides with the maximum Jumbo Frames size of 16128. @@ -447,40 +423,11 @@ Additional Configurations - Using Jumbo Frames at 10 or 100 Mbps may result in poor performance or loss of link. - - Some Intel gigabit adapters that support Jumbo Frames have a frame size - limit of 9238 bytes, with a corresponding MTU size limit of 9216 bytes. - The adapters with this limitation are based on the Intel(R) 82571EB, - 82572EI, 82573L and 80003ES2LAN controller. These correspond to the - following product names: - Intel(R) PRO/1000 PT Server Adapter - Intel(R) PRO/1000 PT Desktop Adapter - Intel(R) PRO/1000 PT Network Connection - Intel(R) PRO/1000 PT Dual Port Server Adapter - Intel(R) PRO/1000 PT Dual Port Network Connection - Intel(R) PRO/1000 PF Server Adapter - Intel(R) PRO/1000 PF Network Connection - Intel(R) PRO/1000 PF Dual Port Server Adapter - Intel(R) PRO/1000 PB Server Connection - Intel(R) PRO/1000 PL Network Connection - Intel(R) PRO/1000 EB Network Connection with I/O Acceleration - Intel(R) PRO/1000 EB Backplane Connection with I/O Acceleration - Intel(R) PRO/1000 PT Quad Port Server Adapter - - Adapters based on the Intel(R) 82542 and 82573V/E controller do not support Jumbo Frames. These correspond to the following product names: Intel(R) PRO/1000 Gigabit Server Adapter Intel(R) PRO/1000 PM Network Connection - - The following adapters do not support Jumbo Frames: - Intel(R) 82562V 10/100 Network Connection - Intel(R) 82566DM Gigabit Network Connection - Intel(R) 82566DC Gigabit Network Connection - Intel(R) 82566MM Gigabit Network Connection - Intel(R) 82566MC Gigabit Network Connection - Intel(R) 82562GT 10/100 Network Connection - Intel(R) 82562G 10/100 Network Connection - - Ethtool ------- The driver utilizes the ethtool interface for driver configuration and @@ -490,142 +437,14 @@ Additional Configurations The latest release of ethtool can be found from http://sourceforge.net/projects/gkernel. - NOTE: Ethtool 1.6 only supports a limited set of ethtool options. Support - for a more complete ethtool feature set can be enabled by upgrading - ethtool to ethtool-1.8.1. - Enabling Wake on LAN* (WoL) --------------------------- - WoL is configured through the Ethtool* utility. Ethtool is included with - all versions of Red Hat after Red Hat 7.2. For other Linux distributions, - download and install Ethtool from the following website: - http://sourceforge.net/projects/gkernel. - - For instructions on enabling WoL with Ethtool, refer to the website listed - above. + WoL is configured through the Ethtool* utility. WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the e1000 driver must be loaded when shutting down or rebooting the system. - Wake On LAN is only supported on port A for the following devices: - Intel(R) PRO/1000 PT Dual Port Network Connection - Intel(R) PRO/1000 PT Dual Port Server Connection - Intel(R) PRO/1000 PT Dual Port Server Adapter - Intel(R) PRO/1000 PF Dual Port Server Adapter - Intel(R) PRO/1000 PT Quad Port Server Adapter - - NAPI - ---- - NAPI (Rx polling mode) is enabled in the e1000 driver. - - See www.cyberus.ca/~hadi/usenix-paper.tgz for more information on NAPI. - - -Known Issues -============ - -Dropped Receive Packets on Half-duplex 10/100 Networks ------------------------------------------------------- -If you have an Intel PCI Express adapter running at 10mbps or 100mbps, half- -duplex, you may observe occasional dropped receive packets. There are no -workarounds for this problem in this network configuration. The network must -be updated to operate in full-duplex, and/or 1000mbps only. - -Jumbo Frames System Requirement -------------------------------- -Memory allocation failures have been observed on Linux systems with 64 MB -of RAM or less that are running Jumbo Frames. If you are using Jumbo -Frames, your system may require more than the advertised minimum -requirement of 64 MB of system memory. - -Performance Degradation with Jumbo Frames ------------------------------------------ -Degradation in throughput performance may be observed in some Jumbo frames -environments. If this is observed, increasing the application's socket -buffer size and/or increasing the /proc/sys/net/ipv4/tcp_*mem entry values -may help. See the specific application manual and -/usr/src/linux*/Documentation/ -networking/ip-sysctl.txt for more details. - -Jumbo Frames on Foundry BigIron 8000 switch -------------------------------------------- -There is a known issue using Jumbo frames when connected to a Foundry -BigIron 8000 switch. This is a 3rd party limitation. If you experience -loss of packets, lower the MTU size. - -Allocating Rx Buffers when Using Jumbo Frames ---------------------------------------------- -Allocating Rx buffers when using Jumbo Frames on 2.6.x kernels may fail if -the available memory is heavily fragmented. This issue may be seen with PCI-X -adapters or with packet split disabled. This can be reduced or eliminated -by changing the amount of available memory for receive buffer allocation, by -increasing /proc/sys/vm/min_free_kbytes. - -Multiple Interfaces on Same Ethernet Broadcast Network ------------------------------------------------------- -Due to the default ARP behavior on Linux, it is not possible to have -one system on two IP networks in the same Ethernet broadcast domain -(non-partitioned switch) behave as expected. All Ethernet interfaces -will respond to IP traffic for any IP address assigned to the system. -This results in unbalanced receive traffic. - -If you have multiple interfaces in a server, either turn on ARP -filtering by entering: - - echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter -(this only works if your kernel's version is higher than 2.4.5), - -NOTE: This setting is not saved across reboots. The configuration -change can be made permanent by adding the line: - net.ipv4.conf.all.arp_filter = 1 -to the file /etc/sysctl.conf - - or, - -install the interfaces in separate broadcast domains (either in -different switches or in a switch partitioned to VLANs). - -82541/82547 can't link or are slow to link with some link partners ------------------------------------------------------------------ -There is a known compatibility issue with 82541/82547 and some -low-end switches where the link will not be established, or will -be slow to establish. In particular, these switches are known to -be incompatible with 82541/82547: - - Planex FXG-08TE - I-O Data ETG-SH8 - -To workaround this issue, the driver can be compiled with an override -of the PHY's master/slave setting. Forcing master or forcing slave -mode will improve time-to-link. - - # make CFLAGS_EXTRA=-DE1000_MASTER_SLAVE=<n> - -Where <n> is: - - 0 = Hardware default - 1 = Master mode - 2 = Slave mode - 3 = Auto master/slave - -Disable rx flow control with ethtool ------------------------------------- -In order to disable receive flow control using ethtool, you must turn -off auto-negotiation on the same command line. - -For example: - - ethtool -A eth? autoneg off rx off - -Unplugging network cable while ethtool -p is running ----------------------------------------------------- -In kernel versions 2.5.50 and later (including 2.6 kernel), unplugging -the network cable while ethtool -p is running will cause the system to -become unresponsive to keyboard commands, except for control-alt-delete. -Restarting the system appears to be the only remedy. - - Support ======= diff --git a/Documentation/networking/e1000e.txt b/Documentation/networking/e1000e.txt new file mode 100644 index 00000000000..6aa048badf3 --- /dev/null +++ b/Documentation/networking/e1000e.txt @@ -0,0 +1,302 @@ +Linux* Driver for Intel(R) Network Connection +=============================================================== + +Intel Gigabit Linux driver. +Copyright(c) 1999 - 2010 Intel Corporation. + +Contents +======== + +- Identifying Your Adapter +- Command Line Parameters +- Additional Configurations +- Support + +Identifying Your Adapter +======================== + +The e1000e driver supports all PCI Express Intel(R) Gigabit Network +Connections, except those that are 82575, 82576 and 82580-based*. + +* NOTE: The Intel(R) PRO/1000 P Dual Port Server Adapter is supported by + the e1000 driver, not the e1000e driver due to the 82546 part being used + behind a PCI Express bridge. + +For more information on how to identify your adapter, go to the Adapter & +Driver ID Guide at: + + http://support.intel.com/support/go/network/adapter/idguide.htm + +For the latest Intel network drivers for Linux, refer to the following +website. In the search field, enter your adapter name or type, or use the +networking link on the left to search for your adapter: + + http://support.intel.com/support/go/network/adapter/home.htm + +Command Line Parameters +======================= + +The default value for each parameter is generally the recommended setting, +unless otherwise noted. + +NOTES: For more information about the InterruptThrottleRate, + RxIntDelay, TxIntDelay, RxAbsIntDelay, and TxAbsIntDelay + parameters, see the application note at: + http://www.intel.com/design/network/applnots/ap450.htm + +InterruptThrottleRate +--------------------- +Valid Range: 0,1,3,4,100-100000 (0=off, 1=dynamic, 3=dynamic conservative, + 4=simplified balancing) +Default Value: 3 + +The driver can limit the amount of interrupts per second that the adapter +will generate for incoming packets. It does this by writing a value to the +adapter that is based on the maximum amount of interrupts that the adapter +will generate per second. + +Setting InterruptThrottleRate to a value greater or equal to 100 +will program the adapter to send out a maximum of that many interrupts +per second, even if more packets have come in. This reduces interrupt +load on the system and can lower CPU utilization under heavy load, +but will increase latency as packets are not processed as quickly. + +The driver has two adaptive modes (setting 1 or 3) in which +it dynamically adjusts the InterruptThrottleRate value based on the traffic +that it receives. After determining the type of incoming traffic in the last +timeframe, it will adjust the InterruptThrottleRate to an appropriate value +for that traffic. + +The algorithm classifies the incoming traffic every interval into +classes. Once the class is determined, the InterruptThrottleRate value is +adjusted to suit that traffic type the best. There are three classes defined: +"Bulk traffic", for large amounts of packets of normal size; "Low latency", +for small amounts of traffic and/or a significant percentage of small +packets; and "Lowest latency", for almost completely small packets or +minimal traffic. + +In dynamic conservative mode, the InterruptThrottleRate value is set to 4000 +for traffic that falls in class "Bulk traffic". If traffic falls in the "Low +latency" or "Lowest latency" class, the InterruptThrottleRate is increased +stepwise to 20000. This default mode is suitable for most applications. + +For situations where low latency is vital such as cluster or +grid computing, the algorithm can reduce latency even more when +InterruptThrottleRate is set to mode 1. In this mode, which operates +the same as mode 3, the InterruptThrottleRate will be increased stepwise to +70000 for traffic in class "Lowest latency". + +In simplified mode the interrupt rate is based on the ratio of Tx and +Rx traffic. If the bytes per second rate is approximately equal the +interrupt rate will drop as low as 2000 interrupts per second. If the +traffic is mostly transmit or mostly receive, the interrupt rate could +be as high as 8000. + +Setting InterruptThrottleRate to 0 turns off any interrupt moderation +and may improve small packet latency, but is generally not suitable +for bulk throughput traffic. + +NOTE: InterruptThrottleRate takes precedence over the TxAbsIntDelay and + RxAbsIntDelay parameters. In other words, minimizing the receive + and/or transmit absolute delays does not force the controller to + generate more interrupts than what the Interrupt Throttle Rate + allows. + +NOTE: When e1000e is loaded with default settings and multiple adapters + are in use simultaneously, the CPU utilization may increase non- + linearly. In order to limit the CPU utilization without impacting + the overall throughput, we recommend that you load the driver as + follows: + + modprobe e1000e InterruptThrottleRate=3000,3000,3000 + + This sets the InterruptThrottleRate to 3000 interrupts/sec for + the first, second, and third instances of the driver. The range + of 2000 to 3000 interrupts per second works on a majority of + systems and is a good starting point, but the optimal value will + be platform-specific. If CPU utilization is not a concern, use + RX_POLLING (NAPI) and default driver settings. + +RxIntDelay +---------- +Valid Range: 0-65535 (0=off) +Default Value: 0 + +This value delays the generation of receive interrupts in units of 1.024 +microseconds. Receive interrupt reduction can improve CPU efficiency if +properly tuned for specific network traffic. Increasing this value adds +extra latency to frame reception and can end up decreasing the throughput +of TCP traffic. If the system is reporting dropped receives, this value +may be set too high, causing the driver to run out of available receive +descriptors. + +CAUTION: When setting RxIntDelay to a value other than 0, adapters may + hang (stop transmitting) under certain network conditions. If + this occurs a NETDEV WATCHDOG message is logged in the system + event log. In addition, the controller is automatically reset, + restoring the network connection. To eliminate the potential + for the hang ensure that RxIntDelay is set to 0. + +RxAbsIntDelay +------------- +Valid Range: 0-65535 (0=off) +Default Value: 8 + +This value, in units of 1.024 microseconds, limits the delay in which a +receive interrupt is generated. Useful only if RxIntDelay is non-zero, +this value ensures that an interrupt is generated after the initial +packet is received within the set amount of time. Proper tuning, +along with RxIntDelay, may improve traffic throughput in specific network +conditions. + +TxIntDelay +---------- +Valid Range: 0-65535 (0=off) +Default Value: 8 + +This value delays the generation of transmit interrupts in units of +1.024 microseconds. Transmit interrupt reduction can improve CPU +efficiency if properly tuned for specific network traffic. If the +system is reporting dropped transmits, this value may be set too high +causing the driver to run out of available transmit descriptors. + +TxAbsIntDelay +------------- +Valid Range: 0-65535 (0=off) +Default Value: 32 + +This value, in units of 1.024 microseconds, limits the delay in which a +transmit interrupt is generated. Useful only if TxIntDelay is non-zero, +this value ensures that an interrupt is generated after the initial +packet is sent on the wire within the set amount of time. Proper tuning, +along with TxIntDelay, may improve traffic throughput in specific +network conditions. + +Copybreak +--------- +Valid Range: 0-xxxxxxx (0=off) +Default Value: 256 + +Driver copies all packets below or equaling this size to a fresh Rx +buffer before handing it up the stack. + +This parameter is different than other parameters, in that it is a +single (not 1,1,1 etc.) parameter applied to all driver instances and +it is also available during runtime at +/sys/module/e1000e/parameters/copybreak + +SmartPowerDownEnable +-------------------- +Valid Range: 0-1 +Default Value: 0 (disabled) + +Allows PHY to turn off in lower power states. The user can set this parameter +in supported chipsets. + +KumeranLockLoss +--------------- +Valid Range: 0-1 +Default Value: 1 (enabled) + +This workaround skips resetting the PHY at shutdown for the initial +silicon releases of ICH8 systems. + +IntMode +------- +Valid Range: 0-2 (0=legacy, 1=MSI, 2=MSI-X) +Default Value: 2 + +Allows changing the interrupt mode at module load time, without requiring a +recompile. If the driver load fails to enable a specific interrupt mode, the +driver will try other interrupt modes, from least to most compatible. The +interrupt order is MSI-X, MSI, Legacy. If specifying MSI (IntMode=1) +interrupts, only MSI and Legacy will be attempted. + +CrcStripping +------------ +Valid Range: 0-1 +Default Value: 1 (enabled) + +Strip the CRC from received packets before sending up the network stack. If +you have a machine with a BMC enabled but cannot receive IPMI traffic after +loading or enabling the driver, try disabling this feature. + +WriteProtectNVM +--------------- +Valid Range: 0-1 +Default Value: 1 (enabled) + +Set the hardware to ignore all write/erase cycles to the GbE region in the +ICHx NVM (non-volatile memory). This feature can be disabled by the +WriteProtectNVM module parameter (enabled by default) only after a hardware +reset, but the machine must be power cycled before trying to enable writes. + +Note: the kernel boot option iomem=relaxed may need to be set if the kernel +config option CONFIG_STRICT_DEVMEM=y, if the root user wants to write the +NVM from user space via ethtool. + +Additional Configurations +========================= + + Jumbo Frames + ------------ + Jumbo Frames support is enabled by changing the MTU to a value larger than + the default of 1500. Use the ifconfig command to increase the MTU size. + For example: + + ifconfig eth<x> mtu 9000 up + + This setting is not saved across reboots. + + Notes: + + - The maximum MTU setting for Jumbo Frames is 9216. This value coincides + with the maximum Jumbo Frames size of 9234 bytes. + + - Using Jumbo Frames at 10 or 100 Mbps is not supported and may result in + poor performance or loss of link. + + - Some adapters limit Jumbo Frames sized packets to a maximum of + 4096 bytes and some adapters do not support Jumbo Frames. + + + Ethtool + ------- + The driver utilizes the ethtool interface for driver configuration and + diagnostics, as well as displaying statistical information. We + strongly recommend downloading the latest version of Ethtool at: + + http://sourceforge.net/projects/gkernel. + + Speed and Duplex + ---------------- + Speed and Duplex are configured through the Ethtool* utility. For + instructions, refer to the Ethtool man page. + + Enabling Wake on LAN* (WoL) + --------------------------- + WoL is configured through the Ethtool* utility. For instructions on + enabling WoL with Ethtool, refer to the Ethtool man page. + + WoL will be enabled on the system during the next shut down or reboot. + For this driver version, in order to enable WoL, the e1000e driver must be + loaded when shutting down or rebooting the system. + + In most cases Wake On LAN is only supported on port A for multiple port + adapters. To verify if a port supports Wake on LAN run ethtool eth<X>. + + +Support +======= + +For general information, go to the Intel support website at: + + www.intel.com/support/ + +or the Intel Wired Networking project hosted by Sourceforge at: + + http://sourceforge.net/projects/e1000 + +If an issue is identified with the released source code on the supported +kernel with a supported adapter, email the specific information related +to the issue to e1000-devel@lists.sf.net diff --git a/Documentation/networking/fore200e.txt b/Documentation/networking/fore200e.txt index b1f337f0f4c..6e0d2a9613e 100644 --- a/Documentation/networking/fore200e.txt +++ b/Documentation/networking/fore200e.txt @@ -39,7 +39,7 @@ version. Alternative binary firmware images can be found somewhere on the ForeThought CD-ROM supplied with your adapter by FORE Systems. You can also get the latest firmware images from FORE Systems at -http://www.fore.com. Register TACTics Online and go to +http://en.wikipedia.org/wiki/FORE_Systems. Register TACTics Online and go to the 'software updates' pages. The firmware binaries are part of the various ForeThought software distributions. diff --git a/Documentation/networking/igb.txt b/Documentation/networking/igb.txt new file mode 100644 index 00000000000..ab2d7183189 --- /dev/null +++ b/Documentation/networking/igb.txt @@ -0,0 +1,132 @@ +Linux* Base Driver for Intel(R) Network Connection +================================================== + +Intel Gigabit Linux driver. +Copyright(c) 1999 - 2010 Intel Corporation. + +Contents +======== + +- Identifying Your Adapter +- Additional Configurations +- Support + +Identifying Your Adapter +======================== + +This driver supports all 82575, 82576 and 82580-based Intel (R) gigabit network +connections. + +For specific information on how to identify your adapter, go to the Adapter & +Driver ID Guide at: + + http://support.intel.com/support/go/network/adapter/idguide.htm + +Command Line Parameters +======================= + +The default value for each parameter is generally the recommended setting, +unless otherwise noted. + +max_vfs +------- +Valid Range: 0-7 +Default Value: 0 + +This parameter adds support for SR-IOV. It causes the driver to spawn up to +max_vfs worth of virtual function. + +Additional Configurations +========================= + + Jumbo Frames + ------------ + Jumbo Frames support is enabled by changing the MTU to a value larger than + the default of 1500. Use the ifconfig command to increase the MTU size. + For example: + + ifconfig eth<x> mtu 9000 up + + This setting is not saved across reboots. + + Notes: + + - The maximum MTU setting for Jumbo Frames is 9216. This value coincides + with the maximum Jumbo Frames size of 9234 bytes. + + - Using Jumbo Frames at 10 or 100 Mbps may result in poor performance or + loss of link. + + Ethtool + ------- + The driver utilizes the ethtool interface for driver configuration and + diagnostics, as well as displaying statistical information. + + http://sourceforge.net/projects/gkernel. + + Enabling Wake on LAN* (WoL) + --------------------------- + WoL is configured through the Ethtool* utility. + + For instructions on enabling WoL with Ethtool, refer to the Ethtool man page. + + WoL will be enabled on the system during the next shut down or reboot. + For this driver version, in order to enable WoL, the igb driver must be + loaded when shutting down or rebooting the system. + + Wake On LAN is only supported on port A of multi-port adapters. + + Wake On LAN is not supported for the Intel(R) Gigabit VT Quad Port Server + Adapter. + + Multiqueue + ---------- + In this mode, a separate MSI-X vector is allocated for each queue and one + for "other" interrupts such as link status change and errors. All + interrupts are throttled via interrupt moderation. Interrupt moderation + must be used to avoid interrupt storms while the driver is processing one + interrupt. The moderation value should be at least as large as the expected + time for the driver to process an interrupt. Multiqueue is off by default. + + REQUIREMENTS: MSI-X support is required for Multiqueue. If MSI-X is not + found, the system will fallback to MSI or to Legacy interrupts. + + LRO + --- + Large Receive Offload (LRO) is a technique for increasing inbound throughput + of high-bandwidth network connections by reducing CPU overhead. It works by + aggregating multiple incoming packets from a single stream into a larger + buffer before they are passed higher up the networking stack, thus reducing + the number of packets that have to be processed. LRO combines multiple + Ethernet frames into a single receive in the stack, thereby potentially + decreasing CPU utilization for receives. + + NOTE: You need to have inet_lro enabled via either the CONFIG_INET_LRO or + CONFIG_INET_LRO_MODULE kernel config option. Additionally, if + CONFIG_INET_LRO_MODULE is used, the inet_lro module needs to be loaded + before the igb driver. + + You can verify that the driver is using LRO by looking at these counters in + Ethtool: + + lro_aggregated - count of total packets that were combined + lro_flushed - counts the number of packets flushed out of LRO + lro_no_desc - counts the number of times an LRO descriptor was not available + for the LRO packet + + NOTE: IPv6 and UDP are not supported by LRO. + +Support +======= + +For general information, go to the Intel support website at: + + www.intel.com/support/ + +or the Intel Wired Networking project hosted by Sourceforge at: + + http://sourceforge.net/projects/e1000 + +If an issue is identified with the released source code on the supported +kernel with a supported adapter, email the specific information related +to the issue to e1000-devel@lists.sf.net diff --git a/Documentation/networking/igbvf.txt b/Documentation/networking/igbvf.txt new file mode 100644 index 00000000000..056028138d9 --- /dev/null +++ b/Documentation/networking/igbvf.txt @@ -0,0 +1,78 @@ +Linux* Base Driver for Intel(R) Network Connection +================================================== + +Intel Gigabit Linux driver. +Copyright(c) 1999 - 2010 Intel Corporation. + +Contents +======== + +- Identifying Your Adapter +- Additional Configurations +- Support + +This file describes the igbvf Linux* Base Driver for Intel Network Connection. + +The igbvf driver supports 82576-based virtual function devices that can only +be activated on kernels that support SR-IOV. SR-IOV requires the correct +platform and OS support. + +The igbvf driver requires the igb driver, version 2.0 or later. The igbvf +driver supports virtual functions generated by the igb driver with a max_vfs +value of 1 or greater. For more information on the max_vfs parameter refer +to the README included with the igb driver. + +The guest OS loading the igbvf driver must support MSI-X interrupts. + +This driver is only supported as a loadable module at this time. Intel is +not supplying patches against the kernel source to allow for static linking +of the driver. For questions related to hardware requirements, refer to the +documentation supplied with your Intel Gigabit adapter. All hardware +requirements listed apply to use with Linux. + +Instructions on updating ethtool can be found in the section "Additional +Configurations" later in this document. + +VLANs: There is a limit of a total of 32 shared VLANs to 1 or more VFs. + +Identifying Your Adapter +======================== + +The igbvf driver supports 82576-based virtual function devices that can only +be activated on kernels that support SR-IOV. + +For more information on how to identify your adapter, go to the Adapter & +Driver ID Guide at: + + http://support.intel.com/support/go/network/adapter/idguide.htm + +For the latest Intel network drivers for Linux, refer to the following +website. In the search field, enter your adapter name or type, or use the +networking link on the left to search for your adapter: + + http://downloadcenter.intel.com/scripts-df-external/Support_Intel.aspx + +Additional Configurations +========================= + + Ethtool + ------- + The driver utilizes the ethtool interface for driver configuration and + diagnostics, as well as displaying statistical information. + + http://sourceforge.net/projects/gkernel. + +Support +======= + +For general information, go to the Intel support website at: + + http://support.intel.com + +or the Intel Wired Networking project hosted by Sourceforge at: + + http://sourceforge.net/projects/e1000 + +If an issue is identified with the released source code on the supported +kernel with a supported adapter, email the specific information related +to the issue to e1000-devel@lists.sf.net diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index d0536b5a4e0..c7165f4cb79 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -903,7 +903,7 @@ arp_ignore - INTEGER arp_notify - BOOLEAN Define mode for notification of address and device changes. 0 - (default): do nothing - 1 - Generate gratuitous arp replies when device is brought up + 1 - Generate gratuitous arp requests when device is brought up or hardware address changes. arp_accept - BOOLEAN @@ -1014,6 +1014,12 @@ conf/interface/*: accept_ra - BOOLEAN Accept Router Advertisements; autoconfigure using them. + Possible values are: + 0 Do not accept Router Advertisements. + 1 Accept Router Advertisements if forwarding is disabled. + 2 Overrule forwarding behaviour. Accept Router Advertisements + even if forwarding is enabled. + Functional default: enabled if local forwarding is disabled. disabled if local forwarding is enabled. @@ -1075,7 +1081,12 @@ forwarding - BOOLEAN Note: It is recommended to have the same setting on all interfaces; mixed router/host scenarios are rather uncommon. - FALSE: + Possible values are: + 0 Forwarding disabled + 1 Forwarding enabled + 2 Forwarding enabled (Hybrid Mode) + + FALSE (0): By default, Host behaviour is assumed. This means: @@ -1085,18 +1096,24 @@ forwarding - BOOLEAN Advertisements (and do autoconfiguration). 4. If accept_redirects is TRUE (default), accept Redirects. - TRUE: + TRUE (1): If local forwarding is enabled, Router behaviour is assumed. This means exactly the reverse from the above: 1. IsRouter flag is set in Neighbour Advertisements. 2. Router Solicitations are not sent. - 3. Router Advertisements are ignored. + 3. Router Advertisements are ignored unless accept_ra is 2. 4. Redirects are ignored. - Default: FALSE if global forwarding is disabled (default), - otherwise TRUE. + TRUE (2): + + Hybrid mode. Same behaviour as TRUE, except for: + + 2. Router Solicitations are being sent when necessary. + + Default: 0 (disabled) if global forwarding is disabled (default), + otherwise 1 (enabled). hop_limit - INTEGER Default Hop Limit to set. diff --git a/Documentation/networking/ipddp.txt b/Documentation/networking/ipddp.txt index 661a5558dd8..ba5c217fffe 100644 --- a/Documentation/networking/ipddp.txt +++ b/Documentation/networking/ipddp.txt @@ -36,11 +36,6 @@ AppleTalk-IP to IP decapsulation. Basic instructions for user space tools ======================================= -To enable AppleTalk-IP decapsulation/encapsulation you will need the -proper tools. You can get the tools for decapsulation from -http://spacs1.spacs.k12.wi.us/~jschlst/index.html and for encapsulation -from http://www.maths.unm.edu/~bradford/ltpc.html - I will briefly describe the operation of the tools, but you will need to consult the supporting documentation for each set of tools. diff --git a/Documentation/networking/iphase.txt b/Documentation/networking/iphase.txt index 55eac4a784e..670b72f1658 100644 --- a/Documentation/networking/iphase.txt +++ b/Documentation/networking/iphase.txt @@ -22,7 +22,7 @@ The features and limitations of this driver are as follows: - All variants of Interphase ATM PCI (i)Chip adapter cards are supported, including x575 (OC3, control memory 128K , 512K and packet memory 128K, 512K and 1M), x525 (UTP25) and x531 (DS3 and E3). See - http://www.iphase.com/site/iphase-web/?epi_menuItemID=e196f04b4b3b40502f150882e21046a0 + http://www.iphase.com/ for details. - Only x86 platforms are supported. - SMP is supported. diff --git a/Documentation/networking/ixgbevf.txt b/Documentation/networking/ixgbevf.txt index 19015de6725..21dd5d15b6b 100755..100644 --- a/Documentation/networking/ixgbevf.txt +++ b/Documentation/networking/ixgbevf.txt @@ -1,19 +1,16 @@ Linux* Base Driver for Intel(R) Network Connection ================================================== -November 24, 2009 +Intel Gigabit Linux driver. +Copyright(c) 1999 - 2010 Intel Corporation. Contents ======== -- In This Release - Identifying Your Adapter - Known Issues/Troubleshooting - Support -In This Release -=============== - This file describes the ixgbevf Linux* Base Driver for Intel Network Connection. @@ -33,7 +30,7 @@ Identifying Your Adapter For more information on how to identify your adapter, go to the Adapter & Driver ID Guide at: - http://support.intel.com/support/network/sb/CS-008441.htm + http://support.intel.com/support/go/network/adapter/idguide.htm Known Issues/Troubleshooting ============================ @@ -57,34 +54,3 @@ or the Intel Wired Networking project hosted by Sourceforge at: If an issue is identified with the released source code on the supported kernel with a supported adapter, email the specific information related to the issue to e1000-devel@lists.sf.net - -License -======= - -Intel 10 Gigabit Linux driver. -Copyright(c) 1999 - 2009 Intel Corporation. - -This program is free software; you can redistribute it and/or modify it -under the terms and conditions of the GNU General Public License, -version 2, as published by the Free Software Foundation. - -This program is distributed in the hope 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 St - Fifth Floor, Boston, MA 02110-1301 USA. - -The full GNU General Public License is included in this distribution in -the file called "COPYING". - -Trademarks -========== - -Intel, Itanium, and Pentium are trademarks or registered trademarks of -Intel Corporation or its subsidiaries in the United States and other -countries. - -* Other names and brands may be claimed as the property of others. diff --git a/Documentation/networking/packet_mmap.txt b/Documentation/networking/packet_mmap.txt index 98f71a5cef0..073894d1c09 100644 --- a/Documentation/networking/packet_mmap.txt +++ b/Documentation/networking/packet_mmap.txt @@ -8,7 +8,7 @@ capture network traffic with utilities like tcpdump or any other that needs raw access to network interface. You can find the latest version of this document at: - http://pusa.uv.es/~ulisses/packet_mmap/ + http://wiki.ipxwarzone.com/index.php5?title=Linux_packet_mmap Howto can be found at: http://wiki.gnu-log.net (packet_mmap) @@ -56,7 +56,7 @@ support for PACKET_MMAP, and also probably the libpcap included in your distribu I'm aware of two implementations of PACKET_MMAP in libpcap: - http://pusa.uv.es/~ulisses/packet_mmap/ (by Simon Patarin, based on libpcap 0.6.2) + http://wiki.ipxwarzone.com/ (by Simon Patarin, based on libpcap 0.6.2) http://public.lanl.gov/cpw/ (by Phil Wood, based on lastest libpcap) The rest of this document is intended for people who want to understand @@ -493,6 +493,32 @@ The user can also use poll() to check if a buffer is available: pfd.events = POLLOUT; retval = poll(&pfd, 1, timeout); +------------------------------------------------------------------------------- ++ PACKET_TIMESTAMP +------------------------------------------------------------------------------- + +The PACKET_TIMESTAMP setting determines the source of the timestamp in +the packet meta information. If your NIC is capable of timestamping +packets in hardware, you can request those hardware timestamps to used. +Note: you may need to enable the generation of hardware timestamps with +SIOCSHWTSTAMP. + +PACKET_TIMESTAMP accepts the same integer bit field as +SO_TIMESTAMPING. However, only the SOF_TIMESTAMPING_SYS_HARDWARE +and SOF_TIMESTAMPING_RAW_HARDWARE values are recognized by +PACKET_TIMESTAMP. SOF_TIMESTAMPING_SYS_HARDWARE takes precedence over +SOF_TIMESTAMPING_RAW_HARDWARE if both bits are set. + + int req = 0; + req |= SOF_TIMESTAMPING_SYS_HARDWARE; + setsockopt(fd, SOL_PACKET, PACKET_TIMESTAMP, (void *) &req, sizeof(req)) + +If PACKET_TIMESTAMP is not set, a software timestamp generated inside +the networking stack is used (the behavior before this setting was added). + +See include/linux/net_tstamp.h and Documentation/networking/timestamping +for more information on hardware timestamps. + -------------------------------------------------------------------------------- + THANKS -------------------------------------------------------------------------------- diff --git a/Documentation/networking/phonet.txt b/Documentation/networking/phonet.txt index 6e8ce09f9c7..24ad2adba6e 100644 --- a/Documentation/networking/phonet.txt +++ b/Documentation/networking/phonet.txt @@ -112,6 +112,22 @@ However, connect() and getpeername() are not supported, as they did not seem useful with Phonet usages (could be added easily). +Resource subscription +--------------------- + +A Phonet datagram socket can be subscribed to any number of 8-bits +Phonet resources, as follow: + + uint32_t res = 0xXX; + ioctl(fd, SIOCPNADDRESOURCE, &res); + +Subscription is similarly cancelled using the SIOCPNDELRESOURCE I/O +control request, or when the socket is closed. + +Note that no more than one socket can be subcribed to any given +resource at a time. If not, ioctl() will return EBUSY. + + Phonet Pipe protocol -------------------- @@ -166,6 +182,46 @@ The pipe protocol provides two socket options at the SOL_PNPIPE level: or zero if encapsulation is off. +Phonet Pipe-controller Implementation +------------------------------------- + +Phonet Pipe-controller is enabled by selecting the CONFIG_PHONET_PIPECTRLR Kconfig +option. It is useful when communicating with those Nokia Modems which do not +implement Pipe controller in them e.g. Nokia Slim Modem used in ST-Ericsson +U8500 platform. + +The implementation is based on the Data Connection Establishment Sequence +depicted in 'Nokia Wireless Modem API - Wireless_modem_user_guide.pdf' +document. + +It allows a phonet sequenced socket (host-pep) to initiate a Pipe connection +between itself and a remote pipe-end point (e.g. modem). + +The implementation adds socket options at SOL_PNPIPE level: + + PNPIPE_PIPE_HANDLE + It accepts an integer argument for setting value of pipe handle. + + PNPIPE_ENABLE accepts one integer value (int). If set to zero, the pipe + is disabled. If the value is non-zero, the pipe is enabled. If the pipe + is not (yet) connected, ENOTCONN is error is returned. + +The implementation also adds socket 'connect'. On calling the 'connect', pipe +will be created between the source socket and the destination, and the pipe +state will be set to PIPE_DISABLED. + +After a pipe has been created and enabled successfully, the Pipe data can be +exchanged between the host-pep and remote-pep (modem). + +User-space would typically follow below sequence with Pipe controller:- +-socket +-bind +-setsockopt for PNPIPE_PIPE_HANDLE +-connect +-setsockopt for PNPIPE_ENCAP_IP +-setsockopt for PNPIPE_ENABLE + + Authors ------- diff --git a/Documentation/networking/phy.txt b/Documentation/networking/phy.txt index 88bb71b46da..9eb1ba52013 100644 --- a/Documentation/networking/phy.txt +++ b/Documentation/networking/phy.txt @@ -177,18 +177,6 @@ Doing it all yourself A convenience function to print out the PHY status neatly. - int phy_clear_interrupt(struct phy_device *phydev); - int phy_config_interrupt(struct phy_device *phydev, u32 interrupts); - - Clear the PHY's interrupt, and configure which ones are allowed, - respectively. Currently only supports all on, or all off. - - int phy_enable_interrupts(struct phy_device *phydev); - int phy_disable_interrupts(struct phy_device *phydev); - - Functions which enable/disable PHY interrupts, clearing them - before and after, respectively. - int phy_start_interrupts(struct phy_device *phydev); int phy_stop_interrupts(struct phy_device *phydev); @@ -213,12 +201,6 @@ Doing it all yourself Fills the phydev structure with up-to-date information about the current settings in the PHY. - void phy_sanitize_settings(struct phy_device *phydev) - - Resolves differences between currently desired settings, and - supported settings for the given PHY device. Does not make - the changes in the hardware, though. - int phy_ethtool_sset(struct phy_device *phydev, struct ethtool_cmd *cmd); int phy_ethtool_gset(struct phy_device *phydev, struct ethtool_cmd *cmd); diff --git a/Documentation/networking/pktgen.txt b/Documentation/networking/pktgen.txt index 61bb645d50e..75e4fd708cc 100644 --- a/Documentation/networking/pktgen.txt +++ b/Documentation/networking/pktgen.txt @@ -151,6 +151,8 @@ Examples: pgset stop aborts injection. Also, ^C aborts generator. + pgset "rate 300M" set rate to 300 Mb/s + pgset "ratep 1000000" set rate to 1Mpps Example scripts =============== @@ -241,6 +243,9 @@ src6 flows flowlen +rate +ratep + References: ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/ ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/examples/ diff --git a/Documentation/networking/ray_cs.txt b/Documentation/networking/ray_cs.txt index 145d27a5239..c0c12307ed9 100644 --- a/Documentation/networking/ray_cs.txt +++ b/Documentation/networking/ray_cs.txt @@ -13,8 +13,8 @@ wireless LAN cards. As of kernel 2.3.18, the ray_cs driver is part of the Linux kernel source. My web page for the development of ray_cs is at -http://world.std.com/~corey/raylink.html and I can be emailed at -corey@world.std.com +http://web.ralinktech.com/ralink/Home/Support/Linux.html +and I can be emailed at corey@world.std.com The kernel driver is based on ray_cs-1.62.tgz diff --git a/Documentation/networking/s2io.txt b/Documentation/networking/s2io.txt index c3d6b4d5d01..9d4e0f4df5a 100644 --- a/Documentation/networking/s2io.txt +++ b/Documentation/networking/s2io.txt @@ -133,7 +133,8 @@ bring down CPU utilization. ** For AMD opteron platforms with 8131 chipset, MMRBC=1 and MOST=1 are recommended as safe parameters. For more information, please review the AMD8131 errata at -http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/26310.pdf +http://vip.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/ +26310_AMD-8131_HyperTransport_PCI-X_Tunnel_Revision_Guide_rev_3_18.pdf 6. Available Downloads Neterion "s2io" driver in Red Hat and Suse 2.6-based distributions is kept up diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt index e8c8f4f06c6..98097d8cb91 100644 --- a/Documentation/networking/timestamping.txt +++ b/Documentation/networking/timestamping.txt @@ -172,15 +172,19 @@ struct skb_shared_hwtstamps { }; Time stamps for outgoing packets are to be generated as follows: -- In hard_start_xmit(), check if skb_tx(skb)->hardware is set no-zero. - If yes, then the driver is expected to do hardware time stamping. +- In hard_start_xmit(), check if (skb_shinfo(skb)->tx_flags & SKBTX_HW_TSTAMP) + is set no-zero. If yes, then the driver is expected to do hardware time + stamping. - If this is possible for the skb and requested, then declare - that the driver is doing the time stamping by setting the field - skb_tx(skb)->in_progress non-zero. You might want to keep a pointer - to the associated skb for the next step and not free the skb. A driver - not supporting hardware time stamping doesn't do that. A driver must - never touch sk_buff::tstamp! It is used to store software generated - time stamps by the network subsystem. + that the driver is doing the time stamping by setting the flag + SKBTX_IN_PROGRESS in skb_shinfo(skb)->tx_flags , e.g. with + + skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS; + + You might want to keep a pointer to the associated skb for the next step + and not free the skb. A driver not supporting hardware time stamping doesn't + do that. A driver must never touch sk_buff::tstamp! It is used to store + software generated time stamps by the network subsystem. - As soon as the driver has sent the packet and/or obtained a hardware time stamp for it, it passes the time stamp back by calling skb_hwtstamp_tx() with the original skb, the raw @@ -191,6 +195,6 @@ Time stamps for outgoing packets are to be generated as follows: this would occur at a later time in the processing pipeline than other software time stamping and therefore could lead to unexpected deltas between time stamps. -- If the driver did not call set skb_tx(skb)->in_progress, then +- If the driver did not set the SKBTX_IN_PROGRESS flag (see above), then dev_hard_start_xmit() checks whether software time stamping is wanted as fallback and potentially generates the time stamp. diff --git a/Documentation/networking/tlan.txt b/Documentation/networking/tlan.txt index 7e6aa5b20c3..34550dfcef7 100644 --- a/Documentation/networking/tlan.txt +++ b/Documentation/networking/tlan.txt @@ -2,7 +2,7 @@ (C) 1998 James Banks (C) 1999-2001 Torben Mathiasen <tmm@image.dk, torben.mathiasen@compaq.com> -For driver information/updates visit http://opensource.compaq.com +For driver information/updates visit http://www.compaq.com TLAN driver for Linux, version 1.14a @@ -113,5 +113,5 @@ III. Things to try if you have problems. There is also a tlan mailing list which you can join by sending "subscribe tlan" in the body of an email to majordomo@vuser.vu.union.edu. -There is also a tlan website at http://opensource.compaq.com +There is also a tlan website at http://www.compaq.com diff --git a/Documentation/networking/udplite.txt b/Documentation/networking/udplite.txt index 855d8da57a2..d727a382910 100644 --- a/Documentation/networking/udplite.txt +++ b/Documentation/networking/udplite.txt @@ -11,11 +11,13 @@ This file briefly describes the existing kernel support and the socket API. For in-depth information, you can consult: - o The UDP-Lite Homepage: http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/ + o The UDP-Lite Homepage: + http://web.archive.org/web/*/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/ From here you can also download some example application source code. o The UDP-Lite HOWTO on - http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/files/UDP-Lite-HOWTO.txt + http://web.archive.org/web/*/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/ + files/UDP-Lite-HOWTO.txt o The Wireshark UDP-Lite WiKi (with capture files): http://wiki.wireshark.org/Lightweight_User_Datagram_Protocol @@ -26,12 +28,7 @@ I) APPLICATIONS Several applications have been ported successfully to UDP-Lite. Ethereal - (now called wireshark) has UDP-Litev4/v6 support by default. The tarball on - - http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/files/udplite_linux.tar.gz - - has source code for several v4/v6 client-server and network testing examples. - + (now called wireshark) has UDP-Litev4/v6 support by default. Porting applications to UDP-Lite is straightforward: only socket level and IPPROTO need to be changed; senders additionally set the checksum coverage length (default = header length = 8). Details are in the next section. diff --git a/Documentation/networking/wavelan.txt b/Documentation/networking/wavelan.txt deleted file mode 100644 index afa6e521c68..00000000000 --- a/Documentation/networking/wavelan.txt +++ /dev/null @@ -1,73 +0,0 @@ - The Wavelan drivers saga - ------------------------ - - By Jean Tourrilhes <jt@hpl.hp.com> - - The Wavelan is a Radio network adapter designed by -Lucent. Under this generic name is hidden quite a variety of hardware, -and many Linux driver to support it. - The get the full story on Wireless LANs, please consult : - http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/ - -"wavelan" driver (old ISA Wavelan) ----------------- - o Config : Network device -> Wireless LAN -> AT&T WaveLAN - o Location : .../drivers/net/wireless/wavelan* - o in-line doc : .../drivers/net/wireless/wavelan.p.h - o on-line doc : - http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Wavelan.html - - This is the driver for the ISA version of the first generation -of the Wavelan, now discontinued. The device is 2 Mb/s, composed of a -Intel 82586 controller and a Lucent Modem, and is NOT 802.11 compliant. - The driver has been tested with the following hardware : - o Wavelan ISA 915 MHz (full length ISA card) - o Wavelan ISA 915 MHz 2.0 (half length ISA card) - o Wavelan ISA 2.4 GHz (full length ISA card, fixed frequency) - o Wavelan ISA 2.4 GHz 2.0 (half length ISA card, frequency selectable) - o Above cards with the optional DES encryption feature - -"wavelan_cs" driver (old Pcmcia Wavelan) -------------------- - o Config : Network device -> PCMCIA network -> - Pcmcia Wireless LAN -> AT&T/Lucent WaveLAN - o Location : .../drivers/net/pcmcia/wavelan* - o in-line doc : .../drivers/net/pcmcia/wavelan_cs.h - o on-line doc : - http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Wavelan.html - - This is the driver for the PCMCIA version of the first -generation of the Wavelan, now discontinued. The device is 2 Mb/s, -composed of a Intel 82593 controller (totally different from the 82586) -and a Lucent Modem, and NOT 802.11 compatible. - The driver has been tested with the following hardware : - o Wavelan Pcmcia 915 MHz 2.0 (Pcmcia card + separate - modem/antenna block) - o Wavelan Pcmcia 2.4 GHz 2.0 (Pcmcia card + separate - modem/antenna block) - -"wvlan_cs" driver (Wavelan IEEE, GPL) ------------------ - o Config : Not yet in kernel - o Location : Pcmcia package 3.1.10+ - o on-line doc : http://www.fasta.fh-dortmund.de/users/andy/wvlan/ - - This is the driver for the current generation of Wavelan IEEE, -which is 802.11 compatible. Depending on version, it is 2 Mb/s or 11 -Mb/s, with or without encryption, all implemented in Lucent specific -DSP (the Hermes). - This is a GPL full source PCMCIA driver (ISA is just a Pcmcia -card with ISA-Pcmcia bridge). - -"wavelan2_cs" driver (Wavelan IEEE, binary) --------------------- - o Config : Not yet in kernel - o Location : ftp://sourceforge.org/pcmcia/contrib/ - - This driver support exactly the same hardware as the previous -driver, the main difference is that it is based on a binary library -and supported by Lucent. - - I hope it clears the confusion ;-) - - Jean diff --git a/Documentation/padata.txt b/Documentation/padata.txt index 269d7d0d833..7ddfe216a0a 100644 --- a/Documentation/padata.txt +++ b/Documentation/padata.txt @@ -1,5 +1,5 @@ The padata parallel execution mechanism -Last updated for 2.6.34 +Last updated for 2.6.36 Padata is a mechanism by which the kernel can farm work out to be done in parallel on multiple CPUs while retaining the ordering of tasks. It was @@ -13,31 +13,86 @@ overall control of how tasks are to be run: #include <linux/padata.h> - struct padata_instance *padata_alloc(const struct cpumask *cpumask, - struct workqueue_struct *wq); + struct padata_instance *padata_alloc(struct workqueue_struct *wq, + const struct cpumask *pcpumask, + const struct cpumask *cbcpumask); -The cpumask describes which processors will be used to execute work -submitted to this instance. The workqueue wq is where the work will -actually be done; it should be a multithreaded queue, naturally. +The pcpumask describes which processors will be used to execute work +submitted to this instance in parallel. The cbcpumask defines which +processors are allowed to be used as the serialization callback processor. +The workqueue wq is where the work will actually be done; it should be +a multithreaded queue, naturally. + +To allocate a padata instance with the cpu_possible_mask for both +cpumasks this helper function can be used: + + struct padata_instance *padata_alloc_possible(struct workqueue_struct *wq); + +Note: Padata maintains two kinds of cpumasks internally. The user supplied +cpumasks, submitted by padata_alloc/padata_alloc_possible and the 'usable' +cpumasks. The usable cpumasks are always a subset of active CPUs in the +user supplied cpumasks; these are the cpumasks padata actually uses. So +it is legal to supply a cpumask to padata that contains offline CPUs. +Once an offline CPU in the user supplied cpumask comes online, padata +is going to use it. There are functions for enabling and disabling the instance: - void padata_start(struct padata_instance *pinst); + int padata_start(struct padata_instance *pinst); void padata_stop(struct padata_instance *pinst); -These functions literally do nothing beyond setting or clearing the -"padata_start() was called" flag; if that flag is not set, other functions -will refuse to work. +These functions are setting or clearing the "PADATA_INIT" flag; +if that flag is not set, other functions will refuse to work. +padata_start returns zero on success (flag set) or -EINVAL if the +padata cpumask contains no active CPU (flag not set). +padata_stop clears the flag and blocks until the padata instance +is unused. The list of CPUs to be used can be adjusted with these functions: - int padata_set_cpumask(struct padata_instance *pinst, + int padata_set_cpumasks(struct padata_instance *pinst, + cpumask_var_t pcpumask, + cpumask_var_t cbcpumask); + int padata_set_cpumask(struct padata_instance *pinst, int cpumask_type, cpumask_var_t cpumask); - int padata_add_cpu(struct padata_instance *pinst, int cpu); - int padata_remove_cpu(struct padata_instance *pinst, int cpu); + int padata_add_cpu(struct padata_instance *pinst, int cpu, int mask); + int padata_remove_cpu(struct padata_instance *pinst, int cpu, int mask); + +Changing the CPU masks are expensive operations, though, so it should not be +done with great frequency. + +It's possible to change both cpumasks of a padata instance with +padata_set_cpumasks by specifying the cpumasks for parallel execution (pcpumask) +and for the serial callback function (cbcpumask). padata_set_cpumask is used to +change just one of the cpumasks. Here cpumask_type is one of PADATA_CPU_SERIAL, +PADATA_CPU_PARALLEL and cpumask specifies the new cpumask to use. +To simply add or remove one CPU from a certain cpumask the functions +padata_add_cpu/padata_remove_cpu are used. cpu specifies the CPU to add or +remove and mask is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL. + +If a user is interested in padata cpumask changes, he can register to +the padata cpumask change notifier: + + int padata_register_cpumask_notifier(struct padata_instance *pinst, + struct notifier_block *nblock); + +To unregister from that notifier: + + int padata_unregister_cpumask_notifier(struct padata_instance *pinst, + struct notifier_block *nblock); + +The padata cpumask change notifier notifies about changes of the usable +cpumasks, i.e. the subset of active CPUs in the user supplied cpumask. + +Padata calls the notifier chain with: + + blocking_notifier_call_chain(&pinst->cpumask_change_notifier, + notification_mask, + &pd_new->cpumask); -Changing the CPU mask has the look of an expensive operation, though, so it -probably should not be done with great frequency. +Here cpumask_change_notifier is registered notifier, notification_mask +is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL and cpumask is a pointer +to a struct padata_cpumask that contains the new cpumask information. Actually submitting work to the padata instance requires the creation of a padata_priv structure: @@ -49,8 +104,8 @@ padata_priv structure: }; This structure will almost certainly be embedded within some larger -structure specific to the work to be done. Most its fields are private to -padata, but the structure should be zeroed at initialization time, and the +structure specific to the work to be done. Most of its fields are private to +padata, but the structure should be zeroed at initialisation time, and the parallel() and serial() functions should be provided. Those functions will be called in the process of getting the work done as we will see momentarily. @@ -63,12 +118,10 @@ The submission of work is done with: The pinst and padata structures must be set up as described above; cb_cpu specifies which CPU will be used for the final callback when the work is done; it must be in the current instance's CPU mask. The return value from -padata_do_parallel() is a little strange; zero is an error return -indicating that the caller forgot the padata_start() formalities. -EBUSY -means that somebody, somewhere else is messing with the instance's CPU -mask, while -EINVAL is a complaint about cb_cpu not being in that CPU mask. -If all goes well, this function will return -EINPROGRESS, indicating that -the work is in progress. +padata_do_parallel() is zero on success, indicating that the work is in +progress. -EBUSY means that somebody, somewhere else is messing with the +instance's CPU mask, while -EINVAL is a complaint about cb_cpu not being +in that CPU mask or about a not running instance. Each task submitted to padata_do_parallel() will, in turn, be passed to exactly one call to the above-mentioned parallel() function, on one CPU, so diff --git a/Documentation/pcmcia/driver-changes.txt b/Documentation/pcmcia/driver-changes.txt index 61bc4e94311..dd04361dd36 100644 --- a/Documentation/pcmcia/driver-changes.txt +++ b/Documentation/pcmcia/driver-changes.txt @@ -1,4 +1,41 @@ This file details changes in 2.6 which affect PCMCIA card driver authors: +* pcmcia_loop_config() and autoconfiguration (as of 2.6.36) + If struct pcmcia_device *p_dev->config_flags is set accordingly, + pcmcia_loop_config() now sets up certain configuration values + automatically, though the driver may still override the settings + in the callback function. The following autoconfiguration options + are provided at the moment: + CONF_AUTO_CHECK_VCC : check for matching Vcc + CONF_AUTO_SET_VPP : set Vpp + CONF_AUTO_AUDIO : auto-enable audio line, if required + CONF_AUTO_SET_IO : set ioport resources (->resource[0,1]) + CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2]) + +* pcmcia_request_configuration -> pcmcia_enable_device (as of 2.6.36) + pcmcia_request_configuration() got renamed to pcmcia_enable_device(), + as it mirrors pcmcia_disable_device(). Configuration settings are now + stored in struct pcmcia_device, e.g. in the fields config_flags, + config_index, config_base, vpp. + +* pcmcia_request_window changes (as of 2.6.36) + Instead of win_req_t, drivers are now requested to fill out + struct pcmcia_device *p_dev->resource[2,3,4,5] for up to four ioport + ranges. After a call to pcmcia_request_window(), the regions found there + are reserved and may be used immediately -- until pcmcia_release_window() + is called. + +* pcmcia_request_io changes (as of 2.6.36) + Instead of io_req_t, drivers are now requested to fill out + struct pcmcia_device *p_dev->resource[0,1] for up to two ioport + ranges. After a call to pcmcia_request_io(), the ports found there + are reserved, after calling pcmcia_request_configuration(), they may + be used. + +* No dev_info_t, no cs_types.h (as of 2.6.36) + dev_info_t and a few other typedefs are removed. No longer use them + in PCMCIA device drivers. Also, do not include pcmcia/cs_types.h, as + this file is gone. + * No dev_node_t (as of 2.6.35) There is no more need to fill out a "dev_node_t" structure. diff --git a/Documentation/power/00-INDEX b/Documentation/power/00-INDEX index fb742c213c9..45e9d4a9128 100644 --- a/Documentation/power/00-INDEX +++ b/Documentation/power/00-INDEX @@ -14,6 +14,8 @@ interface.txt - Power management user interface in /sys/power notifiers.txt - Registering suspend notifiers in device drivers +opp.txt + - Operating Performance Point library pci.txt - How the PCI Subsystem Does Power Management pm_qos_interface.txt diff --git a/Documentation/power/apm-acpi.txt b/Documentation/power/apm-acpi.txt index 1bd799dc17e..6cc423d3662 100644 --- a/Documentation/power/apm-acpi.txt +++ b/Documentation/power/apm-acpi.txt @@ -28,5 +28,5 @@ and be sure that they are started sometime in the system boot process. Go ahead and start both. If ACPI or APM is not available on your system the associated daemon will exit gracefully. - apmd: http://worldvisions.ca/~apenwarr/apmd/ + apmd: http://ftp.debian.org/pool/main/a/apmd/ acpid: http://acpid.sf.net/ diff --git a/Documentation/power/basic-pm-debugging.txt b/Documentation/power/basic-pm-debugging.txt index 1555001bc73..ddd78172ef7 100644 --- a/Documentation/power/basic-pm-debugging.txt +++ b/Documentation/power/basic-pm-debugging.txt @@ -179,8 +179,7 @@ use the PM_TRACE mechanism documented in Documentation/s2ram.txt . To verify that the STR works, it is generally more convenient to use the s2ram tool available from http://suspend.sf.net and documented at -http://en.opensuse.org/s2ram . However, before doing that it is recommended to -carry out STR testing using the facility described in section 1. +http://en.opensuse.org/SDB:Suspend_to_RAM. Namely, after writing "freezer", "devices", "platform", "processors", or "core" into /sys/power/pm_test (available if the kernel is compiled with diff --git a/Documentation/power/interface.txt b/Documentation/power/interface.txt index e67211fe0ee..c537834af00 100644 --- a/Documentation/power/interface.txt +++ b/Documentation/power/interface.txt @@ -57,7 +57,7 @@ smallest image possible. In particular, if "0" is written to this file, the suspend image will be as small as possible. Reading from this file will display the current image size limit, which -is set to 500 MB by default. +is set to 2/5 of available RAM by default. /sys/power/pm_trace controls the code which saves the last PM event point in the RTC across reboots, so that you can debug a machine that just hangs diff --git a/Documentation/power/opp.txt b/Documentation/power/opp.txt new file mode 100644 index 00000000000..44d87ad3cea --- /dev/null +++ b/Documentation/power/opp.txt @@ -0,0 +1,375 @@ +*=============* +* OPP Library * +*=============* + +(C) 2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated + +Contents +-------- +1. Introduction +2. Initial OPP List Registration +3. OPP Search Functions +4. OPP Availability Control Functions +5. OPP Data Retrieval Functions +6. Cpufreq Table Generation +7. Data Structures + +1. Introduction +=============== +Complex SoCs of today consists of a multiple sub-modules working in conjunction. +In an operational system executing varied use cases, not all modules in the SoC +need to function at their highest performing frequency all the time. To +facilitate this, sub-modules in a SoC are grouped into domains, allowing some +domains to run at lower voltage and frequency while other domains are loaded +more. The set of discrete tuples consisting of frequency and voltage pairs that +the device will support per domain are called Operating Performance Points or +OPPs. + +OPP library provides a set of helper functions to organize and query the OPP +information. The library is located in drivers/base/power/opp.c and the header +is located in include/linux/opp.h. OPP library can be enabled by enabling +CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on +CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to +optionally boot at a certain OPP without needing cpufreq. + +Typical usage of the OPP library is as follows: +(users) -> registers a set of default OPPs -> (library) +SoC framework -> modifies on required cases certain OPPs -> OPP layer + -> queries to search/retrieve information -> + +OPP layer expects each domain to be represented by a unique device pointer. SoC +framework registers a set of initial OPPs per device with the OPP layer. This +list is expected to be an optimally small number typically around 5 per device. +This initial list contains a set of OPPs that the framework expects to be safely +enabled by default in the system. + +Note on OPP Availability: +------------------------ +As the system proceeds to operate, SoC framework may choose to make certain +OPPs available or not available on each device based on various external +factors. Example usage: Thermal management or other exceptional situations where +SoC framework might choose to disable a higher frequency OPP to safely continue +operations until that OPP could be re-enabled if possible. + +OPP library facilitates this concept in it's implementation. The following +operational functions operate only on available opps: +opp_find_freq_{ceil, floor}, opp_get_voltage, opp_get_freq, opp_get_opp_count +and opp_init_cpufreq_table + +opp_find_freq_exact is meant to be used to find the opp pointer which can then +be used for opp_enable/disable functions to make an opp available as required. + +WARNING: Users of OPP library should refresh their availability count using +get_opp_count if opp_enable/disable functions are invoked for a device, the +exact mechanism to trigger these or the notification mechanism to other +dependent subsystems such as cpufreq are left to the discretion of the SoC +specific framework which uses the OPP library. Similar care needs to be taken +care to refresh the cpufreq table in cases of these operations. + +WARNING on OPP List locking mechanism: +------------------------------------------------- +OPP library uses RCU for exclusivity. RCU allows the query functions to operate +in multiple contexts and this synchronization mechanism is optimal for a read +intensive operations on data structure as the OPP library caters to. + +To ensure that the data retrieved are sane, the users such as SoC framework +should ensure that the section of code operating on OPP queries are locked +using RCU read locks. The opp_find_freq_{exact,ceil,floor}, +opp_get_{voltage, freq, opp_count} fall into this category. + +opp_{add,enable,disable} are updaters which use mutex and implement it's own +RCU locking mechanisms. opp_init_cpufreq_table acts as an updater and uses +mutex to implment RCU updater strategy. These functions should *NOT* be called +under RCU locks and other contexts that prevent blocking functions in RCU or +mutex operations from working. + +2. Initial OPP List Registration +================================ +The SoC implementation calls opp_add function iteratively to add OPPs per +device. It is expected that the SoC framework will register the OPP entries +optimally- typical numbers range to be less than 5. The list generated by +registering the OPPs is maintained by OPP library throughout the device +operation. The SoC framework can subsequently control the availability of the +OPPs dynamically using the opp_enable / disable functions. + +opp_add - Add a new OPP for a specific domain represented by the device pointer. + The OPP is defined using the frequency and voltage. Once added, the OPP + is assumed to be available and control of it's availability can be done + with the opp_enable/disable functions. OPP library internally stores + and manages this information in the opp struct. This function may be + used by SoC framework to define a optimal list as per the demands of + SoC usage environment. + + WARNING: Do not use this function in interrupt context. + + Example: + soc_pm_init() + { + /* Do things */ + r = opp_add(mpu_dev, 1000000, 900000); + if (!r) { + pr_err("%s: unable to register mpu opp(%d)\n", r); + goto no_cpufreq; + } + /* Do cpufreq things */ + no_cpufreq: + /* Do remaining things */ + } + +3. OPP Search Functions +======================= +High level framework such as cpufreq operates on frequencies. To map the +frequency back to the corresponding OPP, OPP library provides handy functions +to search the OPP list that OPP library internally manages. These search +functions return the matching pointer representing the opp if a match is +found, else returns error. These errors are expected to be handled by standard +error checks such as IS_ERR() and appropriate actions taken by the caller. + +opp_find_freq_exact - Search for an OPP based on an *exact* frequency and + availability. This function is especially useful to enable an OPP which + is not available by default. + Example: In a case when SoC framework detects a situation where a + higher frequency could be made available, it can use this function to + find the OPP prior to call the opp_enable to actually make it available. + rcu_read_lock(); + opp = opp_find_freq_exact(dev, 1000000000, false); + rcu_read_unlock(); + /* dont operate on the pointer.. just do a sanity check.. */ + if (IS_ERR(opp)) { + pr_err("frequency not disabled!\n"); + /* trigger appropriate actions.. */ + } else { + opp_enable(dev,1000000000); + } + + NOTE: This is the only search function that operates on OPPs which are + not available. + +opp_find_freq_floor - Search for an available OPP which is *at most* the + provided frequency. This function is useful while searching for a lesser + match OR operating on OPP information in the order of decreasing + frequency. + Example: To find the highest opp for a device: + freq = ULONG_MAX; + rcu_read_lock(); + opp_find_freq_floor(dev, &freq); + rcu_read_unlock(); + +opp_find_freq_ceil - Search for an available OPP which is *at least* the + provided frequency. This function is useful while searching for a + higher match OR operating on OPP information in the order of increasing + frequency. + Example 1: To find the lowest opp for a device: + freq = 0; + rcu_read_lock(); + opp_find_freq_ceil(dev, &freq); + rcu_read_unlock(); + Example 2: A simplified implementation of a SoC cpufreq_driver->target: + soc_cpufreq_target(..) + { + /* Do stuff like policy checks etc. */ + /* Find the best frequency match for the req */ + rcu_read_lock(); + opp = opp_find_freq_ceil(dev, &freq); + rcu_read_unlock(); + if (!IS_ERR(opp)) + soc_switch_to_freq_voltage(freq); + else + /* do something when we cant satisfy the req */ + /* do other stuff */ + } + +4. OPP Availability Control Functions +===================================== +A default OPP list registered with the OPP library may not cater to all possible +situation. The OPP library provides a set of functions to modify the +availability of a OPP within the OPP list. This allows SoC frameworks to have +fine grained dynamic control of which sets of OPPs are operationally available. +These functions are intended to *temporarily* remove an OPP in conditions such +as thermal considerations (e.g. don't use OPPx until the temperature drops). + +WARNING: Do not use these functions in interrupt context. + +opp_enable - Make a OPP available for operation. + Example: Lets say that 1GHz OPP is to be made available only if the + SoC temperature is lower than a certain threshold. The SoC framework + implementation might choose to do something as follows: + if (cur_temp < temp_low_thresh) { + /* Enable 1GHz if it was disabled */ + rcu_read_lock(); + opp = opp_find_freq_exact(dev, 1000000000, false); + rcu_read_unlock(); + /* just error check */ + if (!IS_ERR(opp)) + ret = opp_enable(dev, 1000000000); + else + goto try_something_else; + } + +opp_disable - Make an OPP to be not available for operation + Example: Lets say that 1GHz OPP is to be disabled if the temperature + exceeds a threshold value. The SoC framework implementation might + choose to do something as follows: + if (cur_temp > temp_high_thresh) { + /* Disable 1GHz if it was enabled */ + rcu_read_lock(); + opp = opp_find_freq_exact(dev, 1000000000, true); + rcu_read_unlock(); + /* just error check */ + if (!IS_ERR(opp)) + ret = opp_disable(dev, 1000000000); + else + goto try_something_else; + } + +5. OPP Data Retrieval Functions +=============================== +Since OPP library abstracts away the OPP information, a set of functions to pull +information from the OPP structure is necessary. Once an OPP pointer is +retrieved using the search functions, the following functions can be used by SoC +framework to retrieve the information represented inside the OPP layer. + +opp_get_voltage - Retrieve the voltage represented by the opp pointer. + Example: At a cpufreq transition to a different frequency, SoC + framework requires to set the voltage represented by the OPP using + the regulator framework to the Power Management chip providing the + voltage. + soc_switch_to_freq_voltage(freq) + { + /* do things */ + rcu_read_lock(); + opp = opp_find_freq_ceil(dev, &freq); + v = opp_get_voltage(opp); + rcu_read_unlock(); + if (v) + regulator_set_voltage(.., v); + /* do other things */ + } + +opp_get_freq - Retrieve the freq represented by the opp pointer. + Example: Lets say the SoC framework uses a couple of helper functions + we could pass opp pointers instead of doing additional parameters to + handle quiet a bit of data parameters. + soc_cpufreq_target(..) + { + /* do things.. */ + max_freq = ULONG_MAX; + rcu_read_lock(); + max_opp = opp_find_freq_floor(dev,&max_freq); + requested_opp = opp_find_freq_ceil(dev,&freq); + if (!IS_ERR(max_opp) && !IS_ERR(requested_opp)) + r = soc_test_validity(max_opp, requested_opp); + rcu_read_unlock(); + /* do other things */ + } + soc_test_validity(..) + { + if(opp_get_voltage(max_opp) < opp_get_voltage(requested_opp)) + return -EINVAL; + if(opp_get_freq(max_opp) < opp_get_freq(requested_opp)) + return -EINVAL; + /* do things.. */ + } + +opp_get_opp_count - Retrieve the number of available opps for a device + Example: Lets say a co-processor in the SoC needs to know the available + frequencies in a table, the main processor can notify as following: + soc_notify_coproc_available_frequencies() + { + /* Do things */ + rcu_read_lock(); + num_available = opp_get_opp_count(dev); + speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL); + /* populate the table in increasing order */ + freq = 0; + while (!IS_ERR(opp = opp_find_freq_ceil(dev, &freq))) { + speeds[i] = freq; + freq++; + i++; + } + rcu_read_unlock(); + + soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available); + /* Do other things */ + } + +6. Cpufreq Table Generation +=========================== +opp_init_cpufreq_table - cpufreq framework typically is initialized with + cpufreq_frequency_table_cpuinfo which is provided with the list of + frequencies that are available for operation. This function provides + a ready to use conversion routine to translate the OPP layer's internal + information about the available frequencies into a format readily + providable to cpufreq. + + WARNING: Do not use this function in interrupt context. + + Example: + soc_pm_init() + { + /* Do things */ + r = opp_init_cpufreq_table(dev, &freq_table); + if (!r) + cpufreq_frequency_table_cpuinfo(policy, freq_table); + /* Do other things */ + } + + NOTE: This function is available only if CONFIG_CPU_FREQ is enabled in + addition to CONFIG_PM as power management feature is required to + dynamically scale voltage and frequency in a system. + +7. Data Structures +================== +Typically an SoC contains multiple voltage domains which are variable. Each +domain is represented by a device pointer. The relationship to OPP can be +represented as follows: +SoC + |- device 1 + | |- opp 1 (availability, freq, voltage) + | |- opp 2 .. + ... ... + | `- opp n .. + |- device 2 + ... + `- device m + +OPP library maintains a internal list that the SoC framework populates and +accessed by various functions as described above. However, the structures +representing the actual OPPs and domains are internal to the OPP library itself +to allow for suitable abstraction reusable across systems. + +struct opp - The internal data structure of OPP library which is used to + represent an OPP. In addition to the freq, voltage, availability + information, it also contains internal book keeping information required + for the OPP library to operate on. Pointer to this structure is + provided back to the users such as SoC framework to be used as a + identifier for OPP in the interactions with OPP layer. + + WARNING: The struct opp pointer should not be parsed or modified by the + users. The defaults of for an instance is populated by opp_add, but the + availability of the OPP can be modified by opp_enable/disable functions. + +struct device - This is used to identify a domain to the OPP layer. The + nature of the device and it's implementation is left to the user of + OPP library such as the SoC framework. + +Overall, in a simplistic view, the data structure operations is represented as +following: + +Initialization / modification: + +-----+ /- opp_enable +opp_add --> | opp | <------- + | +-----+ \- opp_disable + \-------> domain_info(device) + +Search functions: + /-- opp_find_freq_ceil ---\ +-----+ +domain_info<---- opp_find_freq_exact -----> | opp | + \-- opp_find_freq_floor ---/ +-----+ + +Retrieval functions: ++-----+ /- opp_get_voltage +| opp | <--- ++-----+ \- opp_get_freq + +domain_info <- opp_get_opp_count diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.txt index 9363e056188..8ed17587a74 100644 --- a/Documentation/power/regulator/overview.txt +++ b/Documentation/power/regulator/overview.txt @@ -13,7 +13,7 @@ regulators (where voltage output is controllable) and current sinks (where current limit is controllable). (C) 2008 Wolfson Microelectronics PLC. -Author: Liam Girdwood <lg@opensource.wolfsonmicro.com> +Author: Liam Girdwood <lrg@slimlogic.co.uk> Nomenclature diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index 55b859b3bc7..489e9bacd16 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -1,6 +1,7 @@ Run-time Power Management Framework for I/O Devices (C) 2009 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. +(C) 2010 Alan Stern <stern@rowland.harvard.edu> 1. Introduction @@ -157,7 +158,8 @@ rules: to execute it, the other callbacks will not be executed for the same device. * A request to execute ->runtime_resume() will cancel any pending or - scheduled requests to execute the other callbacks for the same device. + scheduled requests to execute the other callbacks for the same device, + except for scheduled autosuspends. 3. Run-time PM Device Fields @@ -165,7 +167,7 @@ The following device run-time PM fields are present in 'struct dev_pm_info', as defined in include/linux/pm.h: struct timer_list suspend_timer; - - timer used for scheduling (delayed) suspend request + - timer used for scheduling (delayed) suspend and autosuspend requests unsigned long timer_expires; - timer expiration time, in jiffies (if this is different from zero, the @@ -230,6 +232,28 @@ defined in include/linux/pm.h: interface; it may only be modified with the help of the pm_runtime_allow() and pm_runtime_forbid() helper functions + unsigned int no_callbacks; + - indicates that the device does not use the run-time PM callbacks (see + Section 8); it may be modified only by the pm_runtime_no_callbacks() + helper function + + unsigned int use_autosuspend; + - indicates that the device's driver supports delayed autosuspend (see + Section 9); it may be modified only by the + pm_runtime{_dont}_use_autosuspend() helper functions + + unsigned int timer_autosuspends; + - indicates that the PM core should attempt to carry out an autosuspend + when the timer expires rather than a normal suspend + + int autosuspend_delay; + - the delay time (in milliseconds) to be used for autosuspend + + unsigned long last_busy; + - the time (in jiffies) when the pm_runtime_mark_last_busy() helper + function was last called for this device; used in calculating inactivity + periods for autosuspend + All of the above fields are members of the 'power' member of 'struct device'. 4. Run-time PM Device Helper Functions @@ -255,6 +279,12 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt to suspend the device again in future + int pm_runtime_autosuspend(struct device *dev); + - same as pm_runtime_suspend() except that the autosuspend delay is taken + into account; if pm_runtime_autosuspend_expiration() says the delay has + not yet expired then an autosuspend is scheduled for the appropriate time + and 0 is returned + int pm_runtime_resume(struct device *dev); - execute the subsystem-level resume callback for the device; returns 0 on success, 1 if the device's run-time PM status was already 'active' or @@ -267,6 +297,11 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: device (the request is represented by a work item in pm_wq); returns 0 on success or error code if the request has not been queued up + int pm_request_autosuspend(struct device *dev); + - schedule the execution of the subsystem-level suspend callback for the + device when the autosuspend delay has expired; if the delay has already + expired then the work item is queued up immediately + int pm_schedule_suspend(struct device *dev, unsigned int delay); - schedule the execution of the subsystem-level suspend callback for the device in future, where 'delay' is the time to wait before queuing up a @@ -298,12 +333,20 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: - decrement the device's usage counter int pm_runtime_put(struct device *dev); - - decrement the device's usage counter, run pm_request_idle(dev) and return - its result + - decrement the device's usage counter; if the result is 0 then run + pm_request_idle(dev) and return its result + + int pm_runtime_put_autosuspend(struct device *dev); + - decrement the device's usage counter; if the result is 0 then run + pm_request_autosuspend(dev) and return its result int pm_runtime_put_sync(struct device *dev); - - decrement the device's usage counter, run pm_runtime_idle(dev) and return - its result + - decrement the device's usage counter; if the result is 0 then run + pm_runtime_idle(dev) and return its result + + int pm_runtime_put_sync_autosuspend(struct device *dev); + - decrement the device's usage counter; if the result is 0 then run + pm_runtime_autosuspend(dev) and return its result void pm_runtime_enable(struct device *dev); - enable the run-time PM helper functions to run the device bus type's @@ -349,19 +392,51 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: counter (used by the /sys/devices/.../power/control interface to effectively prevent the device from being power managed at run time) + void pm_runtime_no_callbacks(struct device *dev); + - set the power.no_callbacks flag for the device and remove the run-time + PM attributes from /sys/devices/.../power (or prevent them from being + added when the device is registered) + + void pm_runtime_mark_last_busy(struct device *dev); + - set the power.last_busy field to the current time + + void pm_runtime_use_autosuspend(struct device *dev); + - set the power.use_autosuspend flag, enabling autosuspend delays + + void pm_runtime_dont_use_autosuspend(struct device *dev); + - clear the power.use_autosuspend flag, disabling autosuspend delays + + void pm_runtime_set_autosuspend_delay(struct device *dev, int delay); + - set the power.autosuspend_delay value to 'delay' (expressed in + milliseconds); if 'delay' is negative then run-time suspends are + prevented + + unsigned long pm_runtime_autosuspend_expiration(struct device *dev); + - calculate the time when the current autosuspend delay period will expire, + based on power.last_busy and power.autosuspend_delay; if the delay time + is 1000 ms or larger then the expiration time is rounded up to the + nearest second; returns 0 if the delay period has already expired or + power.use_autosuspend isn't set, otherwise returns the expiration time + in jiffies + It is safe to execute the following helper functions from interrupt context: pm_request_idle() +pm_request_autosuspend() pm_schedule_suspend() pm_request_resume() pm_runtime_get_noresume() pm_runtime_get() pm_runtime_put_noidle() pm_runtime_put() +pm_runtime_put_autosuspend() +pm_runtime_enable() pm_suspend_ignore_children() pm_runtime_set_active() pm_runtime_set_suspended() -pm_runtime_enable() +pm_runtime_suspended() +pm_runtime_mark_last_busy() +pm_runtime_autosuspend_expiration() 5. Run-time PM Initialization, Device Probing and Removal @@ -524,3 +599,141 @@ poweroff and run-time suspend callback, and similarly for system resume, thaw, restore, and run-time resume, can achieve this with the help of the UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its last argument to NULL). + +8. "No-Callback" Devices + +Some "devices" are only logical sub-devices of their parent and cannot be +power-managed on their own. (The prototype example is a USB interface. Entire +USB devices can go into low-power mode or send wake-up requests, but neither is +possible for individual interfaces.) The drivers for these devices have no +need of run-time PM callbacks; if the callbacks did exist, ->runtime_suspend() +and ->runtime_resume() would always return 0 without doing anything else and +->runtime_idle() would always call pm_runtime_suspend(). + +Subsystems can tell the PM core about these devices by calling +pm_runtime_no_callbacks(). This should be done after the device structure is +initialized and before it is registered (although after device registration is +also okay). The routine will set the device's power.no_callbacks flag and +prevent the non-debugging run-time PM sysfs attributes from being created. + +When power.no_callbacks is set, the PM core will not invoke the +->runtime_idle(), ->runtime_suspend(), or ->runtime_resume() callbacks. +Instead it will assume that suspends and resumes always succeed and that idle +devices should be suspended. + +As a consequence, the PM core will never directly inform the device's subsystem +or driver about run-time power changes. Instead, the driver for the device's +parent must take responsibility for telling the device's driver when the +parent's power state changes. + +9. Autosuspend, or automatically-delayed suspends + +Changing a device's power state isn't free; it requires both time and energy. +A device should be put in a low-power state only when there's some reason to +think it will remain in that state for a substantial time. A common heuristic +says that a device which hasn't been used for a while is liable to remain +unused; following this advice, drivers should not allow devices to be suspended +at run-time until they have been inactive for some minimum period. Even when +the heuristic ends up being non-optimal, it will still prevent devices from +"bouncing" too rapidly between low-power and full-power states. + +The term "autosuspend" is an historical remnant. It doesn't mean that the +device is automatically suspended (the subsystem or driver still has to call +the appropriate PM routines); rather it means that run-time suspends will +automatically be delayed until the desired period of inactivity has elapsed. + +Inactivity is determined based on the power.last_busy field. Drivers should +call pm_runtime_mark_last_busy() to update this field after carrying out I/O, +typically just before calling pm_runtime_put_autosuspend(). The desired length +of the inactivity period is a matter of policy. Subsystems can set this length +initially by calling pm_runtime_set_autosuspend_delay(), but after device +registration the length should be controlled by user space, using the +/sys/devices/.../power/autosuspend_delay_ms attribute. + +In order to use autosuspend, subsystems or drivers must call +pm_runtime_use_autosuspend() (preferably before registering the device), and +thereafter they should use the various *_autosuspend() helper functions instead +of the non-autosuspend counterparts: + + Instead of: pm_runtime_suspend use: pm_runtime_autosuspend; + Instead of: pm_schedule_suspend use: pm_request_autosuspend; + Instead of: pm_runtime_put use: pm_runtime_put_autosuspend; + Instead of: pm_runtime_put_sync use: pm_runtime_put_sync_autosuspend. + +Drivers may also continue to use the non-autosuspend helper functions; they +will behave normally, not taking the autosuspend delay into account. +Similarly, if the power.use_autosuspend field isn't set then the autosuspend +helper functions will behave just like the non-autosuspend counterparts. + +The implementation is well suited for asynchronous use in interrupt contexts. +However such use inevitably involves races, because the PM core can't +synchronize ->runtime_suspend() callbacks with the arrival of I/O requests. +This synchronization must be handled by the driver, using its private lock. +Here is a schematic pseudo-code example: + + foo_read_or_write(struct foo_priv *foo, void *data) + { + lock(&foo->private_lock); + add_request_to_io_queue(foo, data); + if (foo->num_pending_requests++ == 0) + pm_runtime_get(&foo->dev); + if (!foo->is_suspended) + foo_process_next_request(foo); + unlock(&foo->private_lock); + } + + foo_io_completion(struct foo_priv *foo, void *req) + { + lock(&foo->private_lock); + if (--foo->num_pending_requests == 0) { + pm_runtime_mark_last_busy(&foo->dev); + pm_runtime_put_autosuspend(&foo->dev); + } else { + foo_process_next_request(foo); + } + unlock(&foo->private_lock); + /* Send req result back to the user ... */ + } + + int foo_runtime_suspend(struct device *dev) + { + struct foo_priv foo = container_of(dev, ...); + int ret = 0; + + lock(&foo->private_lock); + if (foo->num_pending_requests > 0) { + ret = -EBUSY; + } else { + /* ... suspend the device ... */ + foo->is_suspended = 1; + } + unlock(&foo->private_lock); + return ret; + } + + int foo_runtime_resume(struct device *dev) + { + struct foo_priv foo = container_of(dev, ...); + + lock(&foo->private_lock); + /* ... resume the device ... */ + foo->is_suspended = 0; + pm_runtime_mark_last_busy(&foo->dev); + if (foo->num_pending_requests > 0) + foo_process_requests(foo); + unlock(&foo->private_lock); + return 0; + } + +The important point is that after foo_io_completion() asks for an autosuspend, +the foo_runtime_suspend() callback may race with foo_read_or_write(). +Therefore foo_runtime_suspend() has to check whether there are any pending I/O +requests (while holding the private lock) before allowing the suspend to +proceed. + +In addition, the power.autosuspend_delay field can be changed by user space at +any time. If a driver cares about this, it can call +pm_runtime_autosuspend_expiration() from within the ->runtime_suspend() +callback while holding its private lock. If the function returns a nonzero +value then the delay has not yet expired and the callback should return +-EAGAIN. diff --git a/Documentation/power/s2ram.txt b/Documentation/power/s2ram.txt index 514b94fc931..1bdfa044377 100644 --- a/Documentation/power/s2ram.txt +++ b/Documentation/power/s2ram.txt @@ -49,6 +49,13 @@ machine that doesn't boot) is: device (lspci and /sys/devices/pci* is your friend), and see if you can fix it, disable it, or trace into its resume function. + If no device matches the hash (or any matches appear to be false positives), + the culprit may be a device from a loadable kernel module that is not loaded + until after the hash is checked. You can check the hash against the current + devices again after more modules are loaded using sysfs: + + cat /sys/power/pm_trace_dev_match + For example, the above happens to be the VGA device on my EVO, which I 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 diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt index 9d60ab717a7..ea718891a66 100644 --- a/Documentation/power/swsusp.txt +++ b/Documentation/power/swsusp.txt @@ -66,7 +66,8 @@ swsusp saves the state of the machine into active swaps and then reboots or powerdowns. You must explicitly specify the swap partition to resume from with ``resume='' kernel option. If signature is found it loads and restores saved state. If the option ``noresume'' is specified as a boot parameter, it skips -the resuming. +the resuming. If the option ``hibernate=nocompress'' is specified as a boot +parameter, it saves hibernation image without compression. In the meantime while the system is suspended you should not add/remove any of the hardware, write to the filesystems, etc. diff --git a/Documentation/power/tricks.txt b/Documentation/power/tricks.txt index 3b26bb502a4..a1b8f7249f4 100644 --- a/Documentation/power/tricks.txt +++ b/Documentation/power/tricks.txt @@ -1,6 +1,6 @@ swsusp/S3 tricks ~~~~~~~~~~~~~~~~ -Pavel Machek <pavel@suse.cz> +Pavel Machek <pavel@ucw.cz> If you want to trick swsusp/S3 into working, you might want to try: diff --git a/Documentation/power/video.txt b/Documentation/power/video.txt index 2b358498d09..3e6272bc447 100644 --- a/Documentation/power/video.txt +++ b/Documentation/power/video.txt @@ -67,11 +67,11 @@ There are a few types of systems where video works after S3 resume: POSTing bios works. Ole Rohne has patch to do just that at http://dev.gentoo.org/~marineam/patch-radeonfb-2.6.11-rc2-mm2. -(8) on some systems, you can use the video_post utility mentioned here: - http://bugzilla.kernel.org/show_bug.cgi?id=3670. Do echo 3 > /sys/power/state - && /usr/sbin/video_post - which will initialize the display in console mode. - If you are in X, you can switch to a virtual terminal and back to X using - CTRL+ALT+F1 - CTRL+ALT+F7 to get the display working in graphical mode again. +(8) on some systems, you can use the video_post utility and or + do echo 3 > /sys/power/state && /usr/sbin/video_post - which will + initialize the display in console mode. If you are in X, you can switch + to a virtual terminal and back to X using CTRL+ALT+F1 - CTRL+ALT+F7 to get + the display working in graphical mode again. Now, if you pass acpi_sleep=something, and it does not work with your bios, you'll get a hard crash during resume. Be careful. Also it is @@ -177,7 +177,7 @@ Mainboard Graphics card hack (or "how to do it") Asus A7V8X nVidia RIVA TNT2 model 64 s3_bios,s3_mode (4) -(*) from http://www.ubuntulinux.org/wiki/HoaryPMResults, not sure +(*) from https://wiki.ubuntu.com/HoaryPMResults, not sure which options to use. If you know, please tell me. (***) To be tested with a newer kernel. diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt index 46d22105aa0..302db5da49b 100644 --- a/Documentation/powerpc/booting-without-of.txt +++ b/Documentation/powerpc/booting-without-of.txt @@ -49,40 +49,13 @@ Table of Contents f) MDIO on GPIOs g) SPI busses - VII - Marvell Discovery mv64[345]6x System Controller chips - 1) The /system-controller node - 2) Child nodes of /system-controller - a) Marvell Discovery MDIO bus - b) Marvell Discovery ethernet controller - c) Marvell Discovery PHY nodes - d) Marvell Discovery SDMA nodes - e) Marvell Discovery BRG nodes - f) Marvell Discovery CUNIT nodes - g) Marvell Discovery MPSCROUTING nodes - h) Marvell Discovery MPSCINTR nodes - i) Marvell Discovery MPSC nodes - j) Marvell Discovery Watch Dog Timer nodes - k) Marvell Discovery I2C nodes - l) Marvell Discovery PIC (Programmable Interrupt Controller) nodes - m) Marvell Discovery MPP (Multipurpose Pins) multiplexing nodes - n) Marvell Discovery GPP (General Purpose Pins) nodes - o) Marvell Discovery PCI host bridge node - p) Marvell Discovery CPU Error nodes - q) Marvell Discovery SRAM Controller nodes - r) Marvell Discovery PCI Error Handler nodes - s) Marvell Discovery Memory Controller nodes - - VIII - Specifying interrupt information for devices + VII - Specifying interrupt information for devices 1) interrupts property 2) interrupt-parent property 3) OpenPIC Interrupt Controllers 4) ISA Interrupt Controllers - IX - Specifying GPIO information for devices - 1) gpios property - 2) gpio-controller nodes - - X - Specifying device power management information (sleep property) + VIII - Specifying device power management information (sleep property) Appendix A - Sample SOC node for MPC8540 @@ -1048,7 +1021,7 @@ IV - "dtc", the device tree compiler dtc source code can be found at -<http://ozlabs.org/~dgibson/dtc/dtc.tar.gz> +<http://git.jdl.com/gitweb/?p=dtc.git> WARNING: This version is still in early development stage; the resulting device-tree "blobs" have not yet been validated with the diff --git a/Documentation/powerpc/dts-bindings/fsl/diu.txt b/Documentation/powerpc/dts-bindings/fsl/diu.txt index deb35de7098..b66cb6d31d6 100644 --- a/Documentation/powerpc/dts-bindings/fsl/diu.txt +++ b/Documentation/powerpc/dts-bindings/fsl/diu.txt @@ -4,10 +4,17 @@ The Freescale DIU is a LCD controller, with proper hardware, it can also drive DVI monitors. Required properties: -- compatible : should be "fsl-diu". +- compatible : should be "fsl,diu" or "fsl,mpc5121-diu". - reg : should contain at least address and length of the DIU register set. -- Interrupts : one DIU interrupt should be describe here. +- interrupts : one DIU interrupt should be described here. +- interrupt-parent : the phandle for the interrupt controller that + services interrupts for this device. + +Optional properties: +- edid : verbatim EDID data block describing attached display. + Data from the detailed timing descriptor will be used to + program the display controller. Example (MPC8610HPCD): display@2c000 { @@ -16,3 +23,12 @@ Example (MPC8610HPCD): interrupts = <72 2>; interrupt-parent = <&mpic>; }; + +Example for MPC5121: + display@2100 { + compatible = "fsl,mpc5121-diu"; + reg = <0x2100 0x100>; + interrupts = <64 0x8>; + interrupt-parent = <&ipic>; + edid = [edid-data]; + }; diff --git a/Documentation/powerpc/dts-bindings/fsl/esdhc.txt b/Documentation/powerpc/dts-bindings/fsl/esdhc.txt index 8a004073896..64bcb8be973 100644 --- a/Documentation/powerpc/dts-bindings/fsl/esdhc.txt +++ b/Documentation/powerpc/dts-bindings/fsl/esdhc.txt @@ -14,6 +14,8 @@ Required properties: reports inverted write-protect state; - sdhci,1-bit-only : (optional) specifies that a controller can only handle 1-bit data transfers. + - sdhci,auto-cmd12: (optional) specifies that a controller can + only handle auto CMD12. Example: diff --git a/Documentation/powerpc/dts-bindings/fsl/i2c.txt b/Documentation/powerpc/dts-bindings/fsl/i2c.txt index 50da2031058..1eacd6b20ed 100644 --- a/Documentation/powerpc/dts-bindings/fsl/i2c.txt +++ b/Documentation/powerpc/dts-bindings/fsl/i2c.txt @@ -20,6 +20,7 @@ Recommended properties : - fsl,preserve-clocking : boolean; if defined, the clock settings from the bootloader are preserved (not touched). - clock-frequency : desired I2C bus clock frequency in Hz. + - fsl,timeout : I2C bus timeout in microseconds. Examples : @@ -59,4 +60,5 @@ Examples : interrupts = <43 2>; interrupt-parent = <&mpic>; clock-frequency = <400000>; + fsl,timeout = <10000>; }; diff --git a/Documentation/powerpc/dts-bindings/fsl/spi.txt b/Documentation/powerpc/dts-bindings/fsl/spi.txt index 80510c018ee..777abd7399d 100644 --- a/Documentation/powerpc/dts-bindings/fsl/spi.txt +++ b/Documentation/powerpc/dts-bindings/fsl/spi.txt @@ -1,7 +1,9 @@ * SPI (Serial Peripheral Interface) Required properties: -- cell-index : SPI controller index. +- cell-index : QE SPI subblock index. + 0: QE subblock SPI1 + 1: QE subblock SPI2 - compatible : should be "fsl,spi". - mode : the SPI operation mode, it can be "cpu" or "cpu-qe". - reg : Offset and length of the register set for the device @@ -29,3 +31,23 @@ Example: gpios = <&gpio 18 1 // device reg=<0> &gpio 19 1>; // device reg=<1> }; + + +* eSPI (Enhanced Serial Peripheral Interface) + +Required properties: +- compatible : should be "fsl,mpc8536-espi". +- reg : Offset and length of the register set for the device. +- interrupts : should contain eSPI interrupt, the device has one interrupt. +- fsl,espi-num-chipselects : the number of the chipselect signals. + +Example: + spi@110000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,mpc8536-espi"; + reg = <0x110000 0x1000>; + interrupts = <53 0x2>; + interrupt-parent = <&mpic>; + fsl,espi-num-chipselects = <4>; + }; diff --git a/Documentation/powerpc/dts-bindings/fsl/usb.txt b/Documentation/powerpc/dts-bindings/fsl/usb.txt index b0015240269..bd5723f0b67 100644 --- a/Documentation/powerpc/dts-bindings/fsl/usb.txt +++ b/Documentation/powerpc/dts-bindings/fsl/usb.txt @@ -8,6 +8,7 @@ and additions : Required properties : - compatible : Should be "fsl-usb2-mph" for multi port host USB controllers, or "fsl-usb2-dr" for dual role USB controllers + or "fsl,mpc5121-usb2-dr" for dual role USB controllers of MPC5121 - phy_type : For multi port host USB controllers, should be one of "ulpi", or "serial". For dual role USB controllers, should be one of "ulpi", "utmi", "utmi_wide", or "serial". @@ -33,6 +34,12 @@ Recommended properties : - interrupt-parent : the phandle for the interrupt controller that services interrupts for this device. +Optional properties : + - fsl,invert-drvvbus : boolean; for MPC5121 USB0 only. Indicates the + port power polarity of internal PHY signal DRVVBUS is inverted. + - fsl,invert-pwr-fault : boolean; for MPC5121 USB0 only. Indicates + the PWR_FAULT signal polarity is inverted. + Example multi port host USB controller device node : usb@22000 { compatible = "fsl-usb2-mph"; @@ -57,3 +64,18 @@ Example dual role USB controller device node : dr_mode = "otg"; phy = "ulpi"; }; + +Example dual role USB controller device node for MPC5121ADS: + + usb@4000 { + compatible = "fsl,mpc5121-usb2-dr"; + reg = <0x4000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + interrupt-parent = < &ipic >; + interrupts = <44 0x8>; + dr_mode = "otg"; + phy_type = "utmi_wide"; + fsl,invert-drvvbus; + fsl,invert-pwr-fault; + }; diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.txt index f93462c5db2..6d8be3468d7 100644 --- a/Documentation/powerpc/hvcs.txt +++ b/Documentation/powerpc/hvcs.txt @@ -560,7 +560,7 @@ The proper channel for reporting bugs is either through the Linux OS distribution company that provided your OS or by posting issues to the PowerPC development mailing list at: -linuxppc-dev@ozlabs.org +linuxppc-dev@lists.ozlabs.org This request is to provide a documented and searchable public exchange of the problems and solutions surrounding this driver for the benefit of diff --git a/Documentation/rt-mutex-design.txt b/Documentation/rt-mutex-design.txt index 8df0b782c4d..33ed8007a84 100644 --- a/Documentation/rt-mutex-design.txt +++ b/Documentation/rt-mutex-design.txt @@ -364,7 +364,7 @@ process this is rather easy to know what needs to be adjusted. The functions implementing the task adjustments are rt_mutex_adjust_prio, __rt_mutex_adjust_prio (same as the former, but expects the task pi_lock -to already be taken), rt_mutex_get_prio, and rt_mutex_setprio. +to already be taken), rt_mutex_getprio, and rt_mutex_setprio. rt_mutex_getprio and rt_mutex_setprio are only used in __rt_mutex_adjust_prio. diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt index 1eb576a023b..86f9f74b2b3 100644 --- a/Documentation/s390/Debugging390.txt +++ b/Documentation/s390/Debugging390.txt @@ -2531,5 +2531,5 @@ Special Thanks ============== Special thanks to Neale Ferguson who maintains a much prettier HTML version of this page at -http://penguinvm.princeton.edu/notes.html#Debug390 +http://linuxvm.org/penguinvm/ Bob Grainger Stefan Bader & others for reporting bugs diff --git a/Documentation/scsi/BusLogic.txt b/Documentation/scsi/BusLogic.txt index 98023baa0f0..d7fbc9488b9 100644 --- a/Documentation/scsi/BusLogic.txt +++ b/Documentation/scsi/BusLogic.txt @@ -47,7 +47,7 @@ tune driver performance and error recovery to their particular needs. The latest information on Linux support for BusLogic SCSI Host Adapters, as well as the most recent release of this driver and the latest firmware for the BT-948/958/958D, will always be available from my Linux Home Page at URL -"http://www.dandelion.com/Linux/". +"http://sourceforge.net/projects/dandelion/". Bug reports should be sent via electronic mail to "lnz@dandelion.com". Please include with the bug report the complete configuration messages reported by the diff --git a/Documentation/scsi/ChangeLog.lpfc b/Documentation/scsi/ChangeLog.lpfc index e759e92e286..337c924cc81 100644 --- a/Documentation/scsi/ChangeLog.lpfc +++ b/Documentation/scsi/ChangeLog.lpfc @@ -807,7 +807,7 @@ Changes from 20040908 to 20040920 lpfc_disc_done/lpfc_do_dpc cleanup - lpfc_disc_done can return void - move lpfc_do_dpc and lpfc_disc_done to lpfc_hbadisc.c - remove checking of list emptiness before calling lpfc_disc_done, - it handles the emtpy list case just fine and the additional + it handles the empty list case just fine and the additional instructions cost less then the bustlocked spinlock operations. * Integrated patch from Christoph Hellwig: This adds a new 64bit counter instead, brd_no isn't reused anymore. Also some tiny diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid index 38e9e7cadc9..5e07d320817 100644 --- a/Documentation/scsi/ChangeLog.megaraid +++ b/Documentation/scsi/ChangeLog.megaraid @@ -215,7 +215,7 @@ Older Version : 2.20.4.5 (scsi module), 2.20.2.5 (cmm module) 3. Convert pci_module_init to pci_register_driver Convert from pci_module_init to pci_register_driver - (from:http://kerneljanitors.org/TODO) + (from:http://kernelnewbies.org/KernelJanitors/TODO) - Signed-off-by: Domen Puncer <domen@coderock.org> 4. Use the pre defined DMA mask constants from dma-mapping.h diff --git a/Documentation/scsi/ChangeLog.megaraid_sas b/Documentation/scsi/ChangeLog.megaraid_sas index 30023568805..00301ed9c37 100644 --- a/Documentation/scsi/ChangeLog.megaraid_sas +++ b/Documentation/scsi/ChangeLog.megaraid_sas @@ -1,3 +1,50 @@ +1 Release Date : Thur. May 03, 2010 09:12:45 PST 2009 - + (emaild-id:megaraidlinux@lsi.com) + Bo Yang + +2 Current Version : 00.00.04.31-rc1 +3 Older Version : 00.00.04.17.1-rc1 + +1. Add the Online Controller Reset (OCR) to the Driver. + OCR is the new feature for megaraid_sas driver which + will allow the fw to do the chip reset which will not + affact the OS behavious. + + To add the OCR support, driver need to do: + a). reset the controller chips -- Xscale and Gen2 which + will change the function calls and add the reset function + related to this two chips. + + b). during the reset, driver will store the pending cmds + which not returned by FW to driver's pending queue. Driver + will re-issue those pending cmds again to FW after the OCR + finished. + + c). In driver's timeout routine, driver will report to + OS as reset. Also driver's queue routine will block the + cmds until the OCR finished. + + d). in Driver's ISR routine, if driver get the FW state as + state change, FW in Failure status and FW support online controller + reset (OCR), driver will start to do the controller reset. + + e). In driver's IOCTL routine, the application cmds will wait for the + OCR to finish, then issue the cmds to FW. + + f). Before driver kill adapter, driver will do last chance of + OCR to see if driver can bring back the FW. + +2. Add the support update flag to the driver to tell LSI megaraid_sas + application which driver will support the device update. So application + will not need to do the device update after application add/del the device + from the system. +3. In driver's timeout routine, driver will do three time reset if fw is in + failed state. Driver will kill adapter if can't bring back FW after the + this three times reset. +4. Add the input parameter max_sectors to 1MB support to our GEN2 controller. + customer can use the input paramenter max_sectors to add 1MB support to GEN2 + controller. + 1 Release Date : Thur. Oct 29, 2009 09:12:45 PST 2009 - (emaild-id:megaraidlinux@lsi.com) Bo Yang diff --git a/Documentation/scsi/FlashPoint.txt b/Documentation/scsi/FlashPoint.txt index 1540a92f6d2..5b5f29cb9f8 100644 --- a/Documentation/scsi/FlashPoint.txt +++ b/Documentation/scsi/FlashPoint.txt @@ -13,7 +13,7 @@ operating system support to its BusLogic brand of FlashPoint Ultra SCSI host adapters. All of BusLogic's other SCSI host adapters, including the MultiMaster line, currently support the Linux operating system. Linux drivers and information will be available on October 15th at -http://www.dandelion.com/Linux/. +http://sourceforge.net/projects/dandelion/. "Mylex is committed to supporting the Linux community," says Peter Shambora, vice president of marketing for Mylex. "We have supported Linux driver @@ -27,7 +27,7 @@ Linux is a freely-distributed implementation of UNIX for Intel x86, Sun SPARC, SGI MIPS, Motorola 68k, Digital Alpha AXP and Motorola PowerPC machines. It supports a wide range of software, including the X Window System, Emacs, and TCP/IP networking. Further information is available at -http://www.linux.org and http://www.ssc.com/linux. +http://www.linux.org and http://www.ssc.com/. FlashPoint Host Adapters diff --git a/Documentation/scsi/Mylex.txt b/Documentation/scsi/Mylex.txt index cdf69293f7d..3797f3e6c2b 100644 --- a/Documentation/scsi/Mylex.txt +++ b/Documentation/scsi/Mylex.txt @@ -2,4 +2,4 @@ Please see the file README.BusLogic for information about Linux support for Mylex (formerly BusLogic) MultiMaster and FlashPoint SCSI Host Adapters. The Mylex DAC960 PCI RAID Controllers are now supported. Please consult -http://www.dandelion.com/Linux/ for further information on the DAC960 driver. +http://sourceforge.net/projects/dandelion for further information on the DAC960 driver. diff --git a/Documentation/scsi/NinjaSCSI.txt b/Documentation/scsi/NinjaSCSI.txt index 3229b64cf24..ac8db8ceec7 100644 --- a/Documentation/scsi/NinjaSCSI.txt +++ b/Documentation/scsi/NinjaSCSI.txt @@ -3,8 +3,6 @@ 1. Comment This is Workbit corp.'s(http://www.workbit.co.jp/) NinjaSCSI-3 -(http://www.workbit.co.jp/ts/z_nj3r.html) and NinjaSCSI-32Bi -(http://www.workbit.co.jp/ts/z_njsc32bi.html) PCMCIA card driver module for Linux. 2. My Linux environment diff --git a/Documentation/scsi/aic79xx.txt b/Documentation/scsi/aic79xx.txt index c014eccaf19..16e054c9c70 100644 --- a/Documentation/scsi/aic79xx.txt +++ b/Documentation/scsi/aic79xx.txt @@ -447,7 +447,7 @@ The following information is available in this file: http://www.adaptec.com/buy-cables/. Europe - - Visit our Web site at http://www.adaptec-europe.com/. + - Visit our Web site at http://www.adaptec.com/en-US/_common/world_index. - To speak with a Technical Support Specialist, call, or email, * German: +49 89 4366 5522, Monday-Friday, 9:00-17:00 CET, http://ask-de.adaptec.com/. diff --git a/Documentation/scsi/aic7xxx.txt b/Documentation/scsi/aic7xxx.txt index b7e238cbb5a..18f8d1905e6 100644 --- a/Documentation/scsi/aic7xxx.txt +++ b/Documentation/scsi/aic7xxx.txt @@ -344,7 +344,7 @@ The following information is available in this file: http://www.adaptec.com/buy-cables/. Europe - - Visit our Web site at http://www.adaptec-europe.com/. + - Visit our Web site at http://www.adaptec.com/en-US/_common/world_index. - To speak with a Technical Support Specialist, call, or email, * German: +49 89 4366 5522, Monday-Friday, 9:00-17:00 CET, http://ask-de.adaptec.com/. diff --git a/Documentation/scsi/hpsa.txt b/Documentation/scsi/hpsa.txt new file mode 100644 index 00000000000..dca658362cb --- /dev/null +++ b/Documentation/scsi/hpsa.txt @@ -0,0 +1,107 @@ + +HPSA - Hewlett Packard Smart Array driver +----------------------------------------- + +This file describes the hpsa SCSI driver for HP Smart Array controllers. +The hpsa driver is intended to supplant the cciss driver for newer +Smart Array controllers. The hpsa driver is a SCSI driver, while the +cciss driver is a "block" driver. Actually cciss is both a block +driver (for logical drives) AND a SCSI driver (for tape drives). This +"split-brained" design of the cciss driver is a source of excess +complexity and eliminating that complexity is one of the reasons +for hpsa to exist. + +Supported devices: +------------------ + +Smart Array P212 +Smart Array P410 +Smart Array P410i +Smart Array P411 +Smart Array P812 +Smart Array P712m +Smart Array P711m +StorageWorks P1210m + +Additionally, older Smart Arrays may work with the hpsa driver if the kernel +boot parameter "hpsa_allow_any=1" is specified, however these are not tested +nor supported by HP with this driver. For older Smart Arrays, the cciss +driver should still be used. + +HPSA specific entries in /sys +----------------------------- + + In addition to the generic SCSI attributes available in /sys, hpsa supports + the following attributes: + + HPSA specific host attributes: + ------------------------------ + + /sys/class/scsi_host/host*/rescan + /sys/class/scsi_host/host*/firmware_revision + + the host "rescan" attribute is a write only attribute. Writing to this + attribute will cause the driver to scan for new, changed, or removed devices + (e.g. hot-plugged tape drives, or newly configured or deleted logical drives, + etc.) and notify the SCSI midlayer of any changes detected. Normally this is + triggered automatically by HP's Array Configuration Utility (either the GUI or + command line variety) so for logical drive changes, the user should not + normally have to use this. It may be useful when hot plugging devices like + tape drives, or entire storage boxes containing pre-configured logical drives. + + The "firmware_revision" attribute contains the firmware version of the Smart Array. + For example: + + root@host:/sys/class/scsi_host/host4# cat firmware_revision + 7.14 + + HPSA specific disk attributes: + ------------------------------ + + /sys/class/scsi_disk/c:b:t:l/device/unique_id + /sys/class/scsi_disk/c:b:t:l/device/raid_level + /sys/class/scsi_disk/c:b:t:l/device/lunid + + (where c:b:t:l are the controller, bus, target and lun of the device) + + For example: + + root@host:/sys/class/scsi_disk/4:0:0:0/device# cat unique_id + 600508B1001044395355323037570F77 + root@host:/sys/class/scsi_disk/4:0:0:0/device# cat lunid + 0x0000004000000000 + root@host:/sys/class/scsi_disk/4:0:0:0/device# cat raid_level + RAID 0 + +HPSA specific ioctls: +--------------------- + + For compatibility with applications written for the cciss driver, many, but + not all of the ioctls supported by the cciss driver are also supported by the + hpsa driver. The data structures used by these are described in + include/linux/cciss_ioctl.h + + CCISS_DEREGDISK + CCISS_REGNEWDISK + CCISS_REGNEWD + + The above three ioctls all do exactly the same thing, which is to cause the driver + to rescan for new devices. This does exactly the same thing as writing to the + hpsa specific host "rescan" attribute. + + CCISS_GETPCIINFO + + Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID). + + CCISS_GETDRIVVER + + Returns driver version in three bytes encoded as: + (major_version << 16) | (minor_version << 8) | (subminor_version) + + CCISS_PASSTHRU + CCISS_BIG_PASSTHRU + + Allows "BMIC" and "CISS" commands to be passed through to the Smart Array. + These are used extensively by the HP Array Configuration Utility, SNMP storage + agents, etc. See cciss_vol_status at http://cciss.sf.net for some examples. + diff --git a/Documentation/scsi/ibmmca.txt b/Documentation/scsi/ibmmca.txt index 3920f28710c..45d61ad8c6f 100644 --- a/Documentation/scsi/ibmmca.txt +++ b/Documentation/scsi/ibmmca.txt @@ -1109,7 +1109,7 @@ Q: Where can I find the latest info about this driver? A: See the file MAINTAINERS for the current WWW-address, which offers updates, info and Q/A lists. At this file's origin, the webaddress - was: http://www.uni-mainz.de/~langm000/linux.html + was: http://www.staff.uni-mainz.de/mlang/linux.html Q: My SCSI-adapter is not recognized by the driver, what can I do? A: Just force it to be recognized by kernel parameters. See section 5.1. If this really happens, do also send e-mail to the maintainer, as diff --git a/Documentation/scsi/osst.txt b/Documentation/scsi/osst.txt index 2b21890bc98..ad86c6d1e89 100644 --- a/Documentation/scsi/osst.txt +++ b/Documentation/scsi/osst.txt @@ -135,7 +135,7 @@ The driver development is coordinated through a mailing list a CVS repository and some web pages. The tester's pages which contain recent news and updated drivers to download can be found on -http://linux1.onstream.nl/test/ +http://sourceforge.net/projects/osst/ If you find any problems, please have a look at the tester's page in order to see whether the problem is already known and solved. Otherwise, please diff --git a/Documentation/scsi/ppa.txt b/Documentation/scsi/ppa.txt index 067ac394e0b..05ff47dbe8d 100644 --- a/Documentation/scsi/ppa.txt +++ b/Documentation/scsi/ppa.txt @@ -1,13 +1,13 @@ -------- Terse where to get ZIP Drive help info -------- General Iomega ZIP drive page for Linux: -http://www.torque.net/~campbell/ +http://web.archive.org/web/*/http://www.torque.net/~campbell/ Driver archive for old drivers: -http://www.torque.net/~campbell/ppa/ +http://web.archive.org/web/*/http://www.torque.net/~campbell/ppa Linux Parport page (parallel port) -http://www.torque.net/parport/ +http://web.archive.org/web/*/http://www.torque.net/parport/ Email list for Linux Parport linux-parport@torque.net diff --git a/Documentation/scsi/scsi-generic.txt b/Documentation/scsi/scsi-generic.txt index c38e2b3648e..0a22ab8ea0c 100644 --- a/Documentation/scsi/scsi-generic.txt +++ b/Documentation/scsi/scsi-generic.txt @@ -34,11 +34,11 @@ http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO This describes the sg version 3 driver found in the lk 2.4 series. The LDP renders documents in single and multiple page HTML, postscript and pdf. This document can also be found at: -http://www.torque.net/sg/p/sg_v3_ho.html +http://sg.danny.cz/sg/p/sg_v3_ho.html Documentation for the version 2 sg driver found in the lk 2.2 series can -be found at http://www.torque.net/sg/p/scsi-generic.txt . A larger version -is at: http://www.torque.net/sg/p/scsi-generic_long.txt . +be found at http://sg.danny.cz/sg/. A larger version +is at: http://sg.danny.cz/sg/p/scsi-generic_long.txt. The original documentation for the sg driver (prior to lk 2.2.6) can be found at http://www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt @@ -61,7 +61,7 @@ There are two packages of sg utilities: - sg_utils for the sg version 2 (and original) driver found in lk 2.2 and earlier Both packages will work in the lk 2.4 series however sg3_utils offers more -capabilities. They can be found at: http://www.torque.net/sg and +capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and freshmeat.net Another approach is to look at the applications that use the sg driver. diff --git a/Documentation/scsi/scsi-parameters.txt b/Documentation/scsi/scsi-parameters.txt new file mode 100644 index 00000000000..21e5798526e --- /dev/null +++ b/Documentation/scsi/scsi-parameters.txt @@ -0,0 +1,139 @@ + SCSI Kernel Parameters + ~~~~~~~~~~~~~~~~~~~~~~ + +See Documentation/kernel-parameters.txt for general information on +specifying module parameters. + +This document may not be entirely up to date and comprehensive. The command +"modinfo -p ${modulename}" shows a current list of all parameters of a loadable +module. Loadable modules, after being loaded into the running kernel, also +reveal their parameters in /sys/module/${modulename}/parameters/. Some of these +parameters may be changed at runtime by the command +"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}". + + + advansys= [HW,SCSI] + See header of drivers/scsi/advansys.c. + + aha152x= [HW,SCSI] + See Documentation/scsi/aha152x.txt. + + aha1542= [HW,SCSI] + Format: <portbase>[,<buson>,<busoff>[,<dmaspeed>]] + + aic7xxx= [HW,SCSI] + See Documentation/scsi/aic7xxx.txt. + + aic79xx= [HW,SCSI] + See Documentation/scsi/aic79xx.txt. + + atascsi= [HW,SCSI] Atari SCSI + + BusLogic= [HW,SCSI] + See drivers/scsi/BusLogic.c, comment before function + BusLogic_ParseDriverOptions(). + + dtc3181e= [HW,SCSI] + + eata= [HW,SCSI] + + fd_mcs= [HW,SCSI] + See header of drivers/scsi/fd_mcs.c. + + fdomain= [HW,SCSI] + See header of drivers/scsi/fdomain.c. + + gdth= [HW,SCSI] + See header of drivers/scsi/gdth.c. + + gvp11= [HW,SCSI] + + ibmmcascsi= [HW,MCA,SCSI] IBM MicroChannel SCSI adapter + See Documentation/mca.txt. + + in2000= [HW,SCSI] + See header of drivers/scsi/in2000.c. + + ips= [HW,SCSI] Adaptec / IBM ServeRAID controller + See header of drivers/scsi/ips.c. + + mac5380= [HW,SCSI] Format: + <can_queue>,<cmd_per_lun>,<sg_tablesize>,<hostid>,<use_tags> + + max_luns= [SCSI] Maximum number of LUNs to probe. + Should be between 1 and 2^32-1. + + max_report_luns= + [SCSI] Maximum number of LUNs received. + Should be between 1 and 16384. + + NCR_D700= [HW,SCSI] + See header of drivers/scsi/NCR_D700.c. + + ncr5380= [HW,SCSI] + + ncr53c400= [HW,SCSI] + + ncr53c400a= [HW,SCSI] + + ncr53c406a= [HW,SCSI] + + ncr53c8xx= [HW,SCSI] + + nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects. + + osst= [HW,SCSI] SCSI Tape Driver + Format: <buffer_size>,<write_threshold> + See also Documentation/scsi/st.txt. + + pas16= [HW,SCSI] + See header of drivers/scsi/pas16.c. + + scsi_debug_*= [SCSI] + See drivers/scsi/scsi_debug.c. + + scsi_default_dev_flags= + [SCSI] SCSI default device flags + Format: <integer> + + scsi_dev_flags= [SCSI] Black/white list entry for vendor and model + Format: <vendor>:<model>:<flags> + (flags are integer value) + + scsi_logging_level= [SCSI] a bit mask of logging levels + See drivers/scsi/scsi_logging.h for bits. Also + settable via sysctl at dev.scsi.logging_level + (/proc/sys/dev/scsi/logging_level). + There is also a nice 'scsi_logging_level' script in the + S390-tools package, available for download at + http://www-128.ibm.com/developerworks/linux/linux390/s390-tools-1.5.4.html + + scsi_mod.scan= [SCSI] sync (default) scans SCSI busses as they are + discovered. async scans them in kernel threads, + allowing boot to proceed. none ignores them, expecting + user space to do the scan. + + sim710= [SCSI,HW] + See header of drivers/scsi/sim710.c. + + st= [HW,SCSI] SCSI tape parameters (buffers, etc.) + See Documentation/scsi/st.txt. + + sym53c416= [HW,SCSI] + See header of drivers/scsi/sym53c416.c. + + t128= [HW,SCSI] + See header of drivers/scsi/t128.c. + + tmscsim= [HW,SCSI] + See comment before function dc390_setup() in + drivers/scsi/tmscsim.c. + + u14-34f= [HW,SCSI] UltraStor 14F/34F SCSI host adapter + See header of drivers/scsi/u14-34f.c. + + wd33c93= [HW,SCSI] + See header of drivers/scsi/wd33c93.c. + + wd7000= [HW,SCSI] + See header of drivers/scsi/wd7000.c. diff --git a/Documentation/scsi/scsi.txt b/Documentation/scsi/scsi.txt index dd1bbf4e98e..3d99d38cb62 100644 --- a/Documentation/scsi/scsi.txt +++ b/Documentation/scsi/scsi.txt @@ -4,8 +4,8 @@ The Linux Documentation Project (LDP) maintains a document describing the SCSI subsystem in the Linux kernel (lk) 2.4 series. See: http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . The LDP has single and multiple page HTML renderings as well as postscript and pdf. -It can also be found at http://www.torque.net/scsi/SCSI-2.4-HOWTO . - +It can also be found at: +http://web.archive.org/web/*/http://www.torque.net/scsi/SCSI-2.4-HOWTO Notes on using modules in the SCSI subsystem ============================================ diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index de67229251d..570ef2b3d79 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -43,7 +43,7 @@ There is a SCSI documentation directory within the kernel source tree, typically Documentation/scsi . Most documents are in plain (i.e. ASCII) text. This file is named scsi_mid_low_api.txt and can be found in that directory. A more recent copy of this document may be found -at http://www.torque.net/scsi/scsi_mid_low_api.txt.gz . +at http://web.archive.org/web/20070107183357rn_1/sg.torque.net/scsi/. Many LLDs are documented there (e.g. aic7xxx.txt). The SCSI mid-level is briefly described in scsi.txt which contains a url to a document describing the SCSI subsystem in the lk 2.4 series. Two upper level diff --git a/Documentation/scsi/st.txt b/Documentation/scsi/st.txt index 40752602c05..691ca292c24 100644 --- a/Documentation/scsi/st.txt +++ b/Documentation/scsi/st.txt @@ -2,7 +2,7 @@ This file contains brief information about the SCSI tape driver. The driver is currently maintained by Kai Mäkisara (email Kai.Makisara@kolumbus.fi) -Last modified: Sun Feb 24 21:59:07 2008 by kai.makisara +Last modified: Sun Aug 29 18:25:47 2010 by kai.makisara BASICS @@ -85,6 +85,17 @@ writing and the last operation has been a write. Two filemarks can be optionally written. In both cases end of data is signified by returning zero bytes for two consecutive reads. +Writing filemarks without the immediate bit set in the SCSI command block acts +as a synchronization point, i.e., all remaining data form the drive buffers is +written to tape before the command returns. This makes sure that write errors +are caught at that point, but this takes time. In some applications, several +consecutive files must be written fast. The MTWEOFI operation can be used to +write the filemarks without flushing the drive buffer. Writing filemark at +close() is always flushing the drive buffers. However, if the previous +operation is MTWEOFI, close() does not write a filemark. This can be used if +the program wants to close/open the tape device between files and wants to +skip waiting. + If rewind, offline, bsf, or seek is done and previous tape operation was write, a filemark is written before moving tape. @@ -301,6 +312,8 @@ MTBSR Space backward over count records. MTFSS Space forward over count setmarks. MTBSS Space backward over count setmarks. MTWEOF Write count filemarks. +MTWEOFI Write count filemarks with immediate bit set (i.e., does not + wait until data is on tape) MTWSM Write count setmarks. MTREW Rewind tape. MTOFFL Set device off line (often rewind plus eject). diff --git a/Documentation/serial/moxa-smartio b/Documentation/serial/moxa-smartio index 5337e80a5b9..d1044391868 100644 --- a/Documentation/serial/moxa-smartio +++ b/Documentation/serial/moxa-smartio @@ -76,7 +76,7 @@ Content GNU General Public License in this version. Please refer to GNU General Public License announcement in each source code file for more detail. - In Moxa's Web sites, you may always find latest driver at http://web.moxa.com. + In Moxa's Web sites, you may always find latest driver at http://www.moxa.com/. This version of driver can be installed as Loadable Module (Module driver) or built-in into kernel (Static driver). You may refer to following diff --git a/Documentation/slow-work.txt b/Documentation/slow-work.txt deleted file mode 100644 index 9dbf4470c7e..00000000000 --- a/Documentation/slow-work.txt +++ /dev/null @@ -1,322 +0,0 @@ - ==================================== - SLOW WORK ITEM EXECUTION THREAD POOL - ==================================== - -By: David Howells <dhowells@redhat.com> - -The slow work item execution thread pool is a pool of threads for performing -things that take a relatively long time, such as making mkdir calls. -Typically, when processing something, these items will spend a lot of time -blocking a thread on I/O, thus making that thread unavailable for doing other -work. - -The standard workqueue model is unsuitable for this class of work item as that -limits the owner to a single thread or a single thread per CPU. For some -tasks, however, more threads - or fewer - are required. - -There is just one pool per system. It contains no threads unless something -wants to use it - and that something must register its interest first. When -the pool is active, the number of threads it contains is dynamic, varying -between a maximum and minimum setting, depending on the load. - - -==================== -CLASSES OF WORK ITEM -==================== - -This pool support two classes of work items: - - (*) Slow work items. - - (*) Very slow work items. - -The former are expected to finish much quicker than the latter. - -An operation of the very slow class may do a batch combination of several -lookups, mkdirs, and a create for instance. - -An operation of the ordinarily slow class may, for example, write stuff or -expand files, provided the time taken to do so isn't too long. - -Operations of both types may sleep during execution, thus tying up the thread -loaned to it. - -A further class of work item is available, based on the slow work item class: - - (*) Delayed slow work items. - -These are slow work items that have a timer to defer queueing of the item for -a while. - - -THREAD-TO-CLASS ALLOCATION --------------------------- - -Not all the threads in the pool are available to work on very slow work items. -The number will be between one and one fewer than the number of active threads. -This is configurable (see the "Pool Configuration" section). - -All the threads are available to work on ordinarily slow work items, but a -percentage of the threads will prefer to work on very slow work items. - -The configuration ensures that at least one thread will be available to work on -very slow work items, and at least one thread will be available that won't work -on very slow work items at all. - - -===================== -USING SLOW WORK ITEMS -===================== - -Firstly, a module or subsystem wanting to make use of slow work items must -register its interest: - - int ret = slow_work_register_user(struct module *module); - -This will return 0 if successful, or a -ve error upon failure. The module -pointer should be the module interested in using this facility (almost -certainly THIS_MODULE). - - -Slow work items may then be set up by: - - (1) Declaring a slow_work struct type variable: - - #include <linux/slow-work.h> - - struct slow_work myitem; - - (2) Declaring the operations to be used for this item: - - struct slow_work_ops myitem_ops = { - .get_ref = myitem_get_ref, - .put_ref = myitem_put_ref, - .execute = myitem_execute, - }; - - [*] For a description of the ops, see section "Item Operations". - - (3) Initialising the item: - - slow_work_init(&myitem, &myitem_ops); - - or: - - delayed_slow_work_init(&myitem, &myitem_ops); - - or: - - vslow_work_init(&myitem, &myitem_ops); - - depending on its class. - -A suitably set up work item can then be enqueued for processing: - - int ret = slow_work_enqueue(&myitem); - -This will return a -ve error if the thread pool is unable to gain a reference -on the item, 0 otherwise, or (for delayed work): - - int ret = delayed_slow_work_enqueue(&myitem, my_jiffy_delay); - - -The items are reference counted, so there ought to be no need for a flush -operation. But as the reference counting is optional, means to cancel -existing work items are also included: - - cancel_slow_work(&myitem); - cancel_delayed_slow_work(&myitem); - -can be used to cancel pending work. The above cancel function waits for -existing work to have been executed (or prevent execution of them, depending -on timing). - - -When all a module's slow work items have been processed, and the -module has no further interest in the facility, it should unregister its -interest: - - slow_work_unregister_user(struct module *module); - -The module pointer is used to wait for all outstanding work items for that -module before completing the unregistration. This prevents the put_ref() code -from being taken away before it completes. module should almost certainly be -THIS_MODULE. - - -================ -HELPER FUNCTIONS -================ - -The slow-work facility provides a function by which it can be determined -whether or not an item is queued for later execution: - - bool queued = slow_work_is_queued(struct slow_work *work); - -If it returns false, then the item is not on the queue (it may be executing -with a requeue pending). This can be used to work out whether an item on which -another depends is on the queue, thus allowing a dependent item to be queued -after it. - -If the above shows an item on which another depends not to be queued, then the -owner of the dependent item might need to wait. However, to avoid locking up -the threads unnecessarily be sleeping in them, it can make sense under some -circumstances to return the work item to the queue, thus deferring it until -some other items have had a chance to make use of the yielded thread. - -To yield a thread and defer an item, the work function should simply enqueue -the work item again and return. However, this doesn't work if there's nothing -actually on the queue, as the thread just vacated will jump straight back into -the item's work function, thus busy waiting on a CPU. - -Instead, the item should use the thread to wait for the dependency to go away, -but rather than using schedule() or schedule_timeout() to sleep, it should use -the following function: - - bool requeue = slow_work_sleep_till_thread_needed( - struct slow_work *work, - signed long *_timeout); - -This will add a second wait and then sleep, such that it will be woken up if -either something appears on the queue that could usefully make use of the -thread - and behind which this item can be queued, or if the event the caller -set up to wait for happens. True will be returned if something else appeared -on the queue and this work function should perhaps return, of false if -something else woke it up. The timeout is as for schedule_timeout(). - -For example: - - wq = bit_waitqueue(&my_flags, MY_BIT); - init_wait(&wait); - requeue = false; - do { - prepare_to_wait(wq, &wait, TASK_UNINTERRUPTIBLE); - if (!test_bit(MY_BIT, &my_flags)) - break; - requeue = slow_work_sleep_till_thread_needed(&my_work, - &timeout); - } while (timeout > 0 && !requeue); - finish_wait(wq, &wait); - if (!test_bit(MY_BIT, &my_flags) - goto do_my_thing; - if (requeue) - return; // to slow_work - - -=============== -ITEM OPERATIONS -=============== - -Each work item requires a table of operations of type struct slow_work_ops. -Only ->execute() is required; the getting and putting of a reference and the -describing of an item are all optional. - - (*) Get a reference on an item: - - int (*get_ref)(struct slow_work *work); - - This allows the thread pool to attempt to pin an item by getting a - reference on it. This function should return 0 if the reference was - granted, or a -ve error otherwise. If an error is returned, - slow_work_enqueue() will fail. - - The reference is held whilst the item is queued and whilst it is being - executed. The item may then be requeued with the same reference held, or - the reference will be released. - - (*) Release a reference on an item: - - void (*put_ref)(struct slow_work *work); - - This allows the thread pool to unpin an item by releasing the reference on - it. The thread pool will not touch the item again once this has been - called. - - (*) Execute an item: - - void (*execute)(struct slow_work *work); - - This should perform the work required of the item. It may sleep, it may - perform disk I/O and it may wait for locks. - - (*) View an item through /proc: - - void (*desc)(struct slow_work *work, struct seq_file *m); - - If supplied, this should print to 'm' a small string describing the work - the item is to do. This should be no more than about 40 characters, and - shouldn't include a newline character. - - See the 'Viewing executing and queued items' section below. - - -================== -POOL CONFIGURATION -================== - -The slow-work thread pool has a number of configurables: - - (*) /proc/sys/kernel/slow-work/min-threads - - The minimum number of threads that should be in the pool whilst it is in - use. This may be anywhere between 2 and max-threads. - - (*) /proc/sys/kernel/slow-work/max-threads - - The maximum number of threads that should in the pool. This may be - anywhere between min-threads and 255 or NR_CPUS * 2, whichever is greater. - - (*) /proc/sys/kernel/slow-work/vslow-percentage - - The percentage of active threads in the pool that may be used to execute - very slow work items. This may be between 1 and 99. The resultant number - is bounded to between 1 and one fewer than the number of active threads. - This ensures there is always at least one thread that can process very - slow work items, and always at least one thread that won't. - - -================================== -VIEWING EXECUTING AND QUEUED ITEMS -================================== - -If CONFIG_SLOW_WORK_DEBUG is enabled, a debugfs file is made available: - - /sys/kernel/debug/slow_work/runqueue - -through which the list of work items being executed and the queues of items to -be executed may be viewed. The owner of a work item is given the chance to -add some information of its own. - -The contents look something like the following: - - THR PID ITEM ADDR FL MARK DESC - === ===== ================ == ===== ========== - 0 3005 ffff880023f52348 a 952ms FSC: OBJ17d3: LOOK - 1 3006 ffff880024e33668 2 160ms FSC: OBJ17e5 OP60d3b: Write1/Store fl=2 - 2 3165 ffff8800296dd180 a 424ms FSC: OBJ17e4: LOOK - 3 4089 ffff8800262c8d78 a 212ms FSC: OBJ17ea: CRTN - 4 4090 ffff88002792bed8 2 388ms FSC: OBJ17e8 OP60d36: Write1/Store fl=2 - 5 4092 ffff88002a0ef308 2 388ms FSC: OBJ17e7 OP60d2e: Write1/Store fl=2 - 6 4094 ffff88002abaf4b8 2 132ms FSC: OBJ17e2 OP60d4e: Write1/Store fl=2 - 7 4095 ffff88002bb188e0 a 388ms FSC: OBJ17e9: CRTN - vsq - ffff880023d99668 1 308ms FSC: OBJ17e0 OP60f91: Write1/EnQ fl=2 - vsq - ffff8800295d1740 1 212ms FSC: OBJ16be OP4d4b6: Write1/EnQ fl=2 - vsq - ffff880025ba3308 1 160ms FSC: OBJ179a OP58dec: Write1/EnQ fl=2 - vsq - ffff880024ec83e0 1 160ms FSC: OBJ17ae OP599f2: Write1/EnQ fl=2 - vsq - ffff880026618e00 1 160ms FSC: OBJ17e6 OP60d33: Write1/EnQ fl=2 - vsq - ffff880025a2a4b8 1 132ms FSC: OBJ16a2 OP4d583: Write1/EnQ fl=2 - vsq - ffff880023cbe6d8 9 212ms FSC: OBJ17eb: LOOK - vsq - ffff880024d37590 9 212ms FSC: OBJ17ec: LOOK - vsq - ffff880027746cb0 9 212ms FSC: OBJ17ed: LOOK - vsq - ffff880024d37ae8 9 212ms FSC: OBJ17ee: LOOK - vsq - ffff880024d37cb0 9 212ms FSC: OBJ17ef: LOOK - vsq - ffff880025036550 9 212ms FSC: OBJ17f0: LOOK - vsq - ffff8800250368e0 9 212ms FSC: OBJ17f1: LOOK - vsq - ffff880025036aa8 9 212ms FSC: OBJ17f2: LOOK - -In the 'THR' column, executing items show the thread they're occupying and -queued threads indicate which queue they're on. 'PID' shows the process ID of -a slow-work thread that's executing something. 'FL' shows the work item flags. -'MARK' indicates how long since an item was queued or began executing. Lastly, -the 'DESC' column permits the owner of an item to give some information. - diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index 2075bbb8b3e..d0eb696d32e 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt @@ -300,6 +300,74 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. control correctly. If you have problems regarding this, try another ALSA compliant mixer (alsamixer works). + Module snd-azt1605 + ------------------ + + Module for Aztech Sound Galaxy soundcards based on the Aztech AZT1605 + chipset. + + port - port # for BASE (0x220,0x240,0x260,0x280) + wss_port - port # for WSS (0x530,0x604,0xe80,0xf40) + irq - IRQ # for WSS (7,9,10,11) + dma1 - DMA # for WSS playback (0,1,3) + dma2 - DMA # for WSS capture (0,1), -1 = disabled (default) + mpu_port - port # for MPU-401 UART (0x300,0x330), -1 = disabled (default) + mpu_irq - IRQ # for MPU-401 UART (3,5,7,9), -1 = disabled (default) + fm_port - port # for OPL3 (0x388), -1 = disabled (default) + + This module supports multiple cards. It does not support autoprobe: port, + wss_port, irq and dma1 have to be specified. The other values are + optional. + + "port" needs to match the BASE ADDRESS jumper on the card (0x220 or 0x240) + or the value stored in the card's EEPROM for cards that have an EEPROM and + their "CONFIG MODE" jumper set to "EEPROM SETTING". The other values can + be choosen freely from the options enumerated above. + + If dma2 is specified and different from dma1, the card will operate in + full-duplex mode. When dma1=3, only dma2=0 is valid and the only way to + enable capture since only channels 0 and 1 are available for capture. + + Generic settings are "port=0x220 wss_port=0x530 irq=10 dma1=1 dma2=0 + mpu_port=0x330 mpu_irq=9 fm_port=0x388". + + Whatever IRQ and DMA channels you pick, be sure to reserve them for + legacy ISA in your BIOS. + + Module snd-azt2316 + ------------------ + + Module for Aztech Sound Galaxy soundcards based on the Aztech AZT2316 + chipset. + + port - port # for BASE (0x220,0x240,0x260,0x280) + wss_port - port # for WSS (0x530,0x604,0xe80,0xf40) + irq - IRQ # for WSS (7,9,10,11) + dma1 - DMA # for WSS playback (0,1,3) + dma2 - DMA # for WSS capture (0,1), -1 = disabled (default) + mpu_port - port # for MPU-401 UART (0x300,0x330), -1 = disabled (default) + mpu_irq - IRQ # for MPU-401 UART (5,7,9,10), -1 = disabled (default) + fm_port - port # for OPL3 (0x388), -1 = disabled (default) + + This module supports multiple cards. It does not support autoprobe: port, + wss_port, irq and dma1 have to be specified. The other values are + optional. + + "port" needs to match the BASE ADDRESS jumper on the card (0x220 or 0x240) + or the value stored in the card's EEPROM for cards that have an EEPROM and + their "CONFIG MODE" jumper set to "EEPROM SETTING". The other values can + be choosen freely from the options enumerated above. + + If dma2 is specified and different from dma1, the card will operate in + full-duplex mode. When dma1=3, only dma2=0 is valid and the only way to + enable capture since only channels 0 and 1 are available for capture. + + Generic settings are "port=0x220 wss_port=0x530 irq=10 dma1=1 dma2=0 + mpu_port=0x330 mpu_irq=9 fm_port=0x388". + + Whatever IRQ and DMA channels you pick, be sure to reserve them for + legacy ISA in your BIOS. + Module snd-aw2 -------------- @@ -1285,7 +1353,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. about this driver. Note that it has been discontinued, but the Voyetra Turtle Beach knowledge base entry for it is still available at - http://www.turtlebeach.com/site/kb_ftp/790.asp + http://www.turtlebeach.com Module snd-msnd-pinnacle ------------------------ @@ -1641,20 +1709,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. This card is also known as Audio Excel DSP 16 or Zoltrix AV302. - Module snd-sgalaxy - ------------------ - - Module for Aztech Sound Galaxy sound card. - - sbport - Port # for SB16 interface (0x220,0x240) - wssport - Port # for WSS interface (0x530,0xe80,0xf40,0x604) - irq - IRQ # (7,9,10,11) - dma1 - DMA # - - This module supports multiple cards. - - The power-management is supported. - Module snd-sscape ----------------- diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt index 1d38b0dfba9..37c6aad5e59 100644 --- a/Documentation/sound/alsa/HD-Audio-Models.txt +++ b/Documentation/sound/alsa/HD-Audio-Models.txt @@ -83,8 +83,8 @@ ALC269 ====== basic Basic preset quanta Quanta FL1 - eeepc-p703 ASUS Eeepc P703 P900A - eeepc-p901 ASUS Eeepc P901 S101 + laptop-amic Laptops with analog-mic input + laptop-dmic Laptops with digital-mic input fujitsu FSC Amilo lifebook Fujitsu Lifebook S6420 auto auto-config reading BIOS (default) @@ -109,11 +109,18 @@ ALC662/663/272 asus-mode4 ASUS asus-mode5 ASUS asus-mode6 ASUS + asus-mode7 ASUS + asus-mode8 ASUS dell Dell with ALC272 dell-zm1 Dell ZM1 with ALC272 samsung-nc10 Samsung NC10 mini notebook auto auto-config reading BIOS (default) +ALC680 +====== + base Base model (ASUS NX90) + auto auto-config reading BIOS (default) + ALC882/883/885/888/889 ====================== 3stack-dig 3-jack with SPDIF I/O @@ -282,15 +289,19 @@ Conexant 5051 hp HP Spartan laptop hp-dv6736 HP dv6736 hp-f700 HP Compaq Presario F700 + ideapad Lenovo IdeaPad laptop lenovo-x200 Lenovo X200 laptop toshiba Toshiba Satellite M300 Conexant 5066 ============= laptop Basic Laptop config (default) + hp-laptop HP laptops, e g G60 dell-laptop Dell laptops + dell-vostro Dell Vostro olpc-xo-1_5 OLPC XO 1.5 ideapad Lenovo IdeaPad U150 + thinkpad Lenovo Thinkpad STAC9200 ======== @@ -398,6 +409,7 @@ STAC92HD83* mic-ref Reference board with power management for ports dell-s14 Dell laptop hp HP laptops with (inverted) mute-LED + hp-dv7-4000 HP dv-7 4000 auto BIOS setup (default) STAC9872 @@ -410,3 +422,7 @@ Cirrus Logic CS4206/4207 mbp55 MacBook Pro 5,5 imac27 IMac 27 Inch auto BIOS setup (default) + +VIA VT17xx/VT18xx/VT20xx +======================== + auto BIOS setup (default) diff --git a/Documentation/sound/alsa/HD-Audio.txt b/Documentation/sound/alsa/HD-Audio.txt index bdafdbd3256..c82beb00763 100644 --- a/Documentation/sound/alsa/HD-Audio.txt +++ b/Documentation/sound/alsa/HD-Audio.txt @@ -57,9 +57,11 @@ 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 +`position_fix=2` means to use the position-buffer. +`position_fix=3` means to use a combination of both methods, needed +for some VIA and ATI controllers. 0 is the default value for all other +controllers, 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 @@ -562,7 +564,7 @@ compare the codec registers directly. Send a bug report either the followings: kernel-bugzilla:: - http://bugme.linux-foundation.org/ + https://bugzilla.kernel.org/ alsa-devel ML:: alsa-devel@alsa-project.org diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt index 07301de12cc..7fcd1ad96fc 100644 --- a/Documentation/sound/alsa/Procfile.txt +++ b/Documentation/sound/alsa/Procfile.txt @@ -103,6 +103,8 @@ card*/pcm*/xrun_debug bit 2 = Enable additional jiffies check bit 3 = Log hwptr update at each period interrupt bit 4 = Log hwptr update at each snd_pcm_update_hw_ptr() + bit 5 = Show last 10 positions on error + bit 6 = Do above only once When the bit 0 is set, the driver will show the messages to kernel log when an xrun is detected. The debug message is @@ -122,6 +124,12 @@ card*/pcm*/xrun_debug Bits 3 and 4 are for logging the hwptr records. Note that these will give flood of kernel messages. + When bit 5 is set, the driver logs the last 10 xrun errors and + the proc file shows each jiffies, position, period_size, + buffer_size, old_hw_ptr, and hw_ptr_base values. + + When bit 6 is set, the full xrun log is shown only once. + card*/pcm*/sub*/info The general information of this PCM sub-stream. diff --git a/Documentation/sound/alsa/alsa-parameters.txt b/Documentation/sound/alsa/alsa-parameters.txt new file mode 100644 index 00000000000..0fa40679b08 --- /dev/null +++ b/Documentation/sound/alsa/alsa-parameters.txt @@ -0,0 +1,135 @@ + ALSA Kernel Parameters + ~~~~~~~~~~~~~~~~~~~~~~ + +See Documentation/kernel-parameters.txt for general information on +specifying module parameters. + +This document may not be entirely up to date and comprehensive. The command +"modinfo -p ${modulename}" shows a current list of all parameters of a loadable +module. Loadable modules, after being loaded into the running kernel, also +reveal their parameters in /sys/module/${modulename}/parameters/. Some of these +parameters may be changed at runtime by the command +"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}". + + + snd-ad1816a= [HW,ALSA] + + snd-ad1848= [HW,ALSA] + + snd-ali5451= [HW,ALSA] + + snd-als100= [HW,ALSA] + + snd-als4000= [HW,ALSA] + + snd-azt2320= [HW,ALSA] + + snd-cmi8330= [HW,ALSA] + + snd-cmipci= [HW,ALSA] + + snd-cs4231= [HW,ALSA] + + snd-cs4232= [HW,ALSA] + + snd-cs4236= [HW,ALSA] + + snd-cs4281= [HW,ALSA] + + snd-cs46xx= [HW,ALSA] + + snd-dt019x= [HW,ALSA] + + snd-dummy= [HW,ALSA] + + snd-emu10k1= [HW,ALSA] + + snd-ens1370= [HW,ALSA] + + snd-ens1371= [HW,ALSA] + + snd-es968= [HW,ALSA] + + snd-es1688= [HW,ALSA] + + snd-es18xx= [HW,ALSA] + + snd-es1938= [HW,ALSA] + + snd-es1968= [HW,ALSA] + + snd-fm801= [HW,ALSA] + + snd-gusclassic= [HW,ALSA] + + snd-gusextreme= [HW,ALSA] + + snd-gusmax= [HW,ALSA] + + snd-hdsp= [HW,ALSA] + + snd-ice1712= [HW,ALSA] + + snd-intel8x0= [HW,ALSA] + + snd-interwave= [HW,ALSA] + + snd-interwave-stb= + [HW,ALSA] + + snd-korg1212= [HW,ALSA] + + snd-maestro3= [HW,ALSA] + + snd-mpu401= [HW,ALSA] + + snd-mtpav= [HW,ALSA] + + snd-nm256= [HW,ALSA] + + snd-opl3sa2= [HW,ALSA] + + snd-opti92x-ad1848= + [HW,ALSA] + + snd-opti92x-cs4231= + [HW,ALSA] + + snd-opti93x= [HW,ALSA] + + snd-pmac= [HW,ALSA] + + snd-rme32= [HW,ALSA] + + snd-rme96= [HW,ALSA] + + snd-rme9652= [HW,ALSA] + + snd-sb8= [HW,ALSA] + + snd-sb16= [HW,ALSA] + + snd-sbawe= [HW,ALSA] + + snd-serial= [HW,ALSA] + + snd-sgalaxy= [HW,ALSA] + + snd-sonicvibes= [HW,ALSA] + + snd-sun-amd7930= + [HW,ALSA] + + snd-sun-cs4231= [HW,ALSA] + + snd-trident= [HW,ALSA] + + snd-usb-audio= [HW,ALSA,USB] + + snd-via82xx= [HW,ALSA] + + snd-virmidi= [HW,ALSA] + + snd-wavefront= [HW,ALSA] + + snd-ymfpci= [HW,ALSA] diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/alsa/soc/DAI.txt index 0ebd7ea9706..c9679264c55 100644 --- a/Documentation/sound/alsa/soc/DAI.txt +++ b/Documentation/sound/alsa/soc/DAI.txt @@ -13,7 +13,7 @@ frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97 frame is 21uS long and is divided into 13 time slots. The AC97 specification can be found at :- -http://www.intel.com/design/chipsets/audio/ac97_r23.pdf +http://www.intel.com/p/en_US/business/design I2S diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt index 1e95342ed72..37ba3a72cb7 100644 --- a/Documentation/sound/alsa/soc/codec.txt +++ b/Documentation/sound/alsa/soc/codec.txt @@ -143,7 +143,7 @@ struct snd_soc_ops { }; Please refer to the ALSA driver PCM documentation for details. -http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm +http://www.alsa-project.org/~iwai/writing-an-alsa-driver/ 5 - DAPM description. diff --git a/Documentation/sound/alsa/soc/platform.txt b/Documentation/sound/alsa/soc/platform.txt index b681d17fc38..06d835987c6 100644 --- a/Documentation/sound/alsa/soc/platform.txt +++ b/Documentation/sound/alsa/soc/platform.txt @@ -39,7 +39,7 @@ struct snd_soc_platform { }; Please refer to the ALSA driver documentation for details of audio DMA. -http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm +http://www.alsa-project.org/~iwai/writing-an-alsa-driver/ An example DMA driver is soc/pxa/pxa2xx-pcm.c diff --git a/Documentation/sound/oss/README.OSS b/Documentation/sound/oss/README.OSS index fd42b05b2f5..c615debbf08 100644 --- a/Documentation/sound/oss/README.OSS +++ b/Documentation/sound/oss/README.OSS @@ -36,7 +36,7 @@ with OSS API. Packages "snd-util-3.8.tar.gz" and "snd-data-0.1.tar.Z" contain useful utilities to be used with this driver. -See http://www.opensound.com/ossfree/getting.html for +See http://www.opensound.com/ossfree/ for download instructions. If you are looking for the installation instructions, please @@ -1438,7 +1438,7 @@ of this driver (see http://www.4Front-tech.com/oss.html for more info). There are some common audio chipsets that are not supported yet. For example Sierra Aria and IBM Mwave. It's possible that these architectures get some support in future but I can't make any promises. Just look -at the home page (http://www.opensound.com/ossfree/new_cards.html) +at the home page (http://www.opensound.com/ossfree/) for latest info. Information about unsupported sound cards and chipsets is welcome as well @@ -1449,7 +1449,6 @@ If you have any corrections and/or comments, please contact me. Hannu Savolainen hannu@opensound.com -Personal home page: http://www.compusonic.fi/~hannu home page of OSS/Free: http://www.opensound.com/ossfree home page of commercial OSS diff --git a/Documentation/sound/oss/oss-parameters.txt b/Documentation/sound/oss/oss-parameters.txt new file mode 100644 index 00000000000..3ab391e7c29 --- /dev/null +++ b/Documentation/sound/oss/oss-parameters.txt @@ -0,0 +1,51 @@ + OSS Kernel Parameters + ~~~~~~~~~~~~~~~~~~~~~ + +See Documentation/kernel-parameters.txt for general information on +specifying module parameters. + +This document may not be entirely up to date and comprehensive. The command +"modinfo -p ${modulename}" shows a current list of all parameters of a loadable +module. Loadable modules, after being loaded into the running kernel, also +reveal their parameters in /sys/module/${modulename}/parameters/. Some of these +parameters may be changed at runtime by the command +"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}". + + + ad1848= [HW,OSS] + Format: <io>,<irq>,<dma>,<dma2>,<type> + + aedsp16= [HW,OSS] Audio Excel DSP 16 + Format: <io>,<irq>,<dma>,<mss_io>,<mpu_io>,<mpu_irq> + See also header of sound/oss/aedsp16.c. + + dmasound= [HW,OSS] Sound subsystem buffers + + mpu401= [HW,OSS] + Format: <io>,<irq> + + opl3= [HW,OSS] + Format: <io> + + pas2= [HW,OSS] Format: + <io>,<irq>,<dma>,<dma16>,<sb_io>,<sb_irq>,<sb_dma>,<sb_dma16> + + pss= [HW,OSS] Personal Sound System (ECHO ESC614) + Format: + <io>,<mss_io>,<mss_irq>,<mss_dma>,<mpu_io>,<mpu_irq> + + sscape= [HW,OSS] + Format: <io>,<irq>,<dma>,<mpu_io>,<mpu_irq> + + trix= [HW,OSS] MediaTrix AudioTrix Pro + Format: + <io>,<irq>,<dma>,<dma2>,<sb_io>,<sb_irq>,<sb_dma>,<mpu_io>,<mpu_irq> + + uart401= [HW,OSS] + Format: <io>,<irq> + + uart6850= [HW,OSS] + Format: <io>,<irq> + + waveartist= [HW,OSS] + Format: <io>,<irq>,<dma>,<dma2> diff --git a/Documentation/sparse.txt b/Documentation/sparse.txt index 9b659c79a54..4909d411635 100644 --- a/Documentation/sparse.txt +++ b/Documentation/sparse.txt @@ -1,5 +1,5 @@ Copyright 2004 Linus Torvalds -Copyright 2004 Pavel Machek <pavel@suse.cz> +Copyright 2004 Pavel Machek <pavel@ucw.cz> Copyright 2006 Bob Copeland <me@bobcopeland.com> Using sparse for typechecking diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 5fdbb612aeb..30289fab86e 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -80,8 +80,10 @@ dirty_background_bytes Contains the amount of dirty memory at which the pdflush background writeback daemon will start writeback. -If dirty_background_bytes is written, dirty_background_ratio becomes a function -of its value (dirty_background_bytes / the amount of dirtyable system memory). +Note: dirty_background_bytes is the counterpart of dirty_background_ratio. Only +one of them may be specified at a time. When one sysctl is written it is +immediately taken into account to evaluate the dirty memory limits and the +other appears as 0 when read. ============================================================== @@ -97,8 +99,10 @@ dirty_bytes Contains the amount of dirty memory at which a process generating disk writes will itself start writeback. -If dirty_bytes is written, dirty_ratio becomes a function of its value -(dirty_bytes / the amount of dirtyable system memory). +Note: dirty_bytes is the counterpart of dirty_ratio. Only one of them may be +specified at a time. When one sysctl is written it is immediately taken into +account to evaluate the dirty memory limits and the other appears as 0 when +read. Note: the minimum value allowed for dirty_bytes is two pages (in bytes); any value lower than this limit will be ignored and the old configuration will be @@ -196,7 +200,7 @@ controlled by this knob are discussed in Documentation/laptops/laptop-mode.txt. legacy_va_layout -If non-zero, this sysctl disables the new 32-bit mmap mmap layout - the kernel +If non-zero, this sysctl disables the new 32-bit mmap layout - the kernel will use the legacy (2.4) layout for all processes. ============================================================== @@ -511,7 +515,7 @@ information may not be desired. If this is set to non-zero, this information is shown whenever the OOM killer actually kills a memory-hogging task. -The default value is 0. +The default value is 1 (enabled). ============================================================== diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt index 5c17196c8fe..312e3754e8c 100644 --- a/Documentation/sysrq.txt +++ b/Documentation/sysrq.txt @@ -75,7 +75,7 @@ On all - write a character to /proc/sysrq-trigger. e.g.: 'f' - Will call oom_kill to kill a memory hog process. -'g' - Used by kgdb on ppc and sh platforms. +'g' - Used by kgdb (kernel debugger) 'h' - Will display help (actually any other key than those listed here will display help. but 'h' is easy to remember :-) @@ -110,12 +110,15 @@ On all - write a character to /proc/sysrq-trigger. e.g.: 'u' - Will attempt to remount all mounted filesystems read-only. -'v' - Dumps Voyager SMP processor info to your console. +'v' - Forcefully restores framebuffer console +'v' - Causes ETM buffer dump [ARM-specific] 'w' - Dumps tasks that are in uninterruptable (blocked) state. 'x' - Used by xmon interface on ppc/powerpc platforms. +'y' - Show global CPU Registers [SPARC-64 specific] + 'z' - Dump the ftrace buffer '0'-'9' - Sets the console log level, controlling which kernel messages diff --git a/Documentation/telephony/ixj.txt b/Documentation/telephony/ixj.txt index 44d124005ba..4fb314d5170 100644 --- a/Documentation/telephony/ixj.txt +++ b/Documentation/telephony/ixj.txt @@ -108,14 +108,9 @@ applications. 1.4 Where to get things -You can download the latest versions of the driver from: - -http://www.quicknet.net/develop.htm - -You can download the latest version of this document from: - -http://www.quicknet.net/develop.htm +Info on latest versions of the driver are here: +http://web.archive.org/web/*/http://www.quicknet.net/develop.htm 1.5 Mailing List diff --git a/Documentation/timers/hpet_example.c b/Documentation/timers/hpet_example.c index 4bfafb7bc4c..9a3e7012c19 100644 --- a/Documentation/timers/hpet_example.c +++ b/Documentation/timers/hpet_example.c @@ -97,6 +97,33 @@ hpet_open_close(int argc, const char **argv) void hpet_info(int argc, const char **argv) { + struct hpet_info info; + int fd; + + if (argc != 1) { + fprintf(stderr, "hpet_info: device-name\n"); + return; + } + + fd = open(argv[0], O_RDONLY); + if (fd < 0) { + fprintf(stderr, "hpet_info: open of %s failed\n", argv[0]); + return; + } + + if (ioctl(fd, HPET_INFO, &info) < 0) { + fprintf(stderr, "hpet_info: failed to get info\n"); + goto out; + } + + fprintf(stderr, "hpet_info: hi_irqfreq 0x%lx hi_flags 0x%lx ", + info.hi_ireqfreq, info.hi_flags); + fprintf(stderr, "hi_hpet %d hi_timer %d\n", + info.hi_hpet, info.hi_timer); + +out: + close(fd); + return; } void diff --git a/Documentation/timers/timers-howto.txt b/Documentation/timers/timers-howto.txt new file mode 100644 index 00000000000..c9ef29d2ede --- /dev/null +++ b/Documentation/timers/timers-howto.txt @@ -0,0 +1,105 @@ +delays - Information on the various kernel delay / sleep mechanisms +------------------------------------------------------------------- + +This document seeks to answer the common question: "What is the +RightWay (TM) to insert a delay?" + +This question is most often faced by driver writers who have to +deal with hardware delays and who may not be the most intimately +familiar with the inner workings of the Linux Kernel. + + +Inserting Delays +---------------- + +The first, and most important, question you need to ask is "Is my +code in an atomic context?" This should be followed closely by "Does +it really need to delay in atomic context?" If so... + +ATOMIC CONTEXT: + You must use the *delay family of functions. These + functions use the jiffie estimation of clock speed + and will busy wait for enough loop cycles to achieve + the desired delay: + + ndelay(unsigned long nsecs) + udelay(unsigned long usecs) + mdelay(unsgined long msecs) + + udelay is the generally preferred API; ndelay-level + precision may not actually exist on many non-PC devices. + + mdelay is macro wrapper around udelay, to account for + possible overflow when passing large arguments to udelay. + In general, use of mdelay is discouraged and code should + be refactored to allow for the use of msleep. + +NON-ATOMIC CONTEXT: + You should use the *sleep[_range] family of functions. + There are a few more options here, while any of them may + work correctly, using the "right" sleep function will + help the scheduler, power management, and just make your + driver better :) + + -- Backed by busy-wait loop: + udelay(unsigned long usecs) + -- Backed by hrtimers: + usleep_range(unsigned long min, unsigned long max) + -- Backed by jiffies / legacy_timers + msleep(unsigned long msecs) + msleep_interruptible(unsigned long msecs) + + Unlike the *delay family, the underlying mechanism + driving each of these calls varies, thus there are + quirks you should be aware of. + + + SLEEPING FOR "A FEW" USECS ( < ~10us? ): + * Use udelay + + - Why not usleep? + On slower systems, (embedded, OR perhaps a speed- + stepped PC!) the overhead of setting up the hrtimers + for usleep *may* not be worth it. Such an evaluation + will obviously depend on your specific situation, but + it is something to be aware of. + + SLEEPING FOR ~USECS OR SMALL MSECS ( 10us - 20ms): + * Use usleep_range + + - Why not msleep for (1ms - 20ms)? + Explained originally here: + http://lkml.org/lkml/2007/8/3/250 + msleep(1~20) may not do what the caller intends, and + will often sleep longer (~20 ms actual sleep for any + value given in the 1~20ms range). In many cases this + is not the desired behavior. + + - Why is there no "usleep" / What is a good range? + Since usleep_range is built on top of hrtimers, the + wakeup will be very precise (ish), thus a simple + usleep function would likely introduce a large number + of undesired interrupts. + + With the introduction of a range, the scheduler is + free to coalesce your wakeup with any other wakeup + that may have happened for other reasons, or at the + worst case, fire an interrupt for your upper bound. + + The larger a range you supply, the greater a chance + that you will not trigger an interrupt; this should + be balanced with what is an acceptable upper bound on + delay / performance for your specific code path. Exact + tolerances here are very situation specific, thus it + is left to the caller to determine a reasonable range. + + SLEEPING FOR LARGER MSECS ( 10ms+ ) + * Use msleep or possibly msleep_interruptible + + - What's the difference? + msleep sets the current task to TASK_UNINTERRUPTIBLE + whereas msleep_interruptible sets the current task to + TASK_INTERRUPTIBLE before scheduling the sleep. In + short, the difference is whether the sleep can be ended + early by a signal. In general, just use msleep unless + you know you have a need for the interruptible variant. diff --git a/Documentation/tomoyo.txt b/Documentation/tomoyo.txt index b3a232cae7f..200a2d37cbc 100644 --- a/Documentation/tomoyo.txt +++ b/Documentation/tomoyo.txt @@ -3,8 +3,8 @@ TOMOYO is a name-based MAC extension (LSM module) for the Linux kernel. LiveCD-based tutorials are available at -http://tomoyo.sourceforge.jp/en/1.6.x/1st-step/ubuntu8.04-live/ -http://tomoyo.sourceforge.jp/en/1.6.x/1st-step/centos5-live/ . +http://tomoyo.sourceforge.jp/1.7/1st-step/ubuntu10.04-live/ +http://tomoyo.sourceforge.jp/1.7/1st-step/centos5-live/ . Though these tutorials use non-LSM version of TOMOYO, they are useful for you to know what TOMOYO is. @@ -13,12 +13,12 @@ to know what TOMOYO is. Build the kernel with CONFIG_SECURITY_TOMOYO=y and pass "security=tomoyo" on kernel's command line. -Please see http://tomoyo.sourceforge.jp/en/2.2.x/ for details. +Please see http://tomoyo.sourceforge.jp/2.3/ for details. --- Where is documentation? --- User <-> Kernel interface documentation is available at -http://tomoyo.sourceforge.jp/en/2.2.x/policy-reference.html . +http://tomoyo.sourceforge.jp/2.3/policy-reference.html . Materials we prepared for seminars and symposiums are available at http://sourceforge.jp/projects/tomoyo/docs/?category_id=532&language_id=1 . @@ -50,6 +50,6 @@ multiple LSM modules at the same time. We feel sorry that you have to give up SELinux/SMACK/AppArmor etc. when you want to use TOMOYO. We hope that LSM becomes stackable in future. Meanwhile, you can use non-LSM -version of TOMOYO, available at http://tomoyo.sourceforge.jp/en/1.6.x/ . +version of TOMOYO, available at http://tomoyo.sourceforge.jp/1.7/ . LSM version of TOMOYO is a subset of non-LSM version of TOMOYO. We are planning to port non-LSM version's functionalities to LSM versions. diff --git a/Documentation/trace/ftrace-design.txt b/Documentation/trace/ftrace-design.txt index f1f81afee8a..dc52bd442c9 100644 --- a/Documentation/trace/ftrace-design.txt +++ b/Documentation/trace/ftrace-design.txt @@ -13,6 +13,9 @@ Note that this focuses on architecture implementation details only. If you want more explanation of a feature in terms of common code, review the common ftrace.txt file. +Ideally, everyone who wishes to retain performance while supporting tracing in +their kernel should make it all the way to dynamic ftrace support. + Prerequisites ------------- @@ -215,7 +218,7 @@ An arch may pass in a unique value (frame pointer) to both the entering and exiting of a function. On exit, the value is compared and if it does not match, then it will panic the kernel. This is largely a sanity check for bad code generation with gcc. If gcc for your port sanely updates the frame -pointer under different opitmization levels, then ignore this option. +pointer under different optimization levels, then ignore this option. However, adding support for it isn't terribly difficult. In your assembly code that calls prepare_ftrace_return(), pass the frame pointer as the 3rd argument. @@ -234,7 +237,7 @@ If you can't trace NMI functions, then skip this option. HAVE_SYSCALL_TRACEPOINTS ---------------------- +------------------------ You need very few things to get the syscalls tracing in an arch. @@ -250,12 +253,152 @@ You need very few things to get the syscalls tracing in an arch. HAVE_FTRACE_MCOUNT_RECORD ------------------------- -See scripts/recordmcount.pl for more info. +See scripts/recordmcount.pl for more info. Just fill in the arch-specific +details for how to locate the addresses of mcount call sites via objdump. +This option doesn't make much sense without also implementing dynamic ftrace. + +HAVE_DYNAMIC_FTRACE +------------------- + +You will first need HAVE_FTRACE_MCOUNT_RECORD and HAVE_FUNCTION_TRACER, so +scroll your reader back up if you got over eager. + +Once those are out of the way, you will need to implement: + - asm/ftrace.h: + - MCOUNT_ADDR + - ftrace_call_adjust() + - struct dyn_arch_ftrace{} + - asm code: + - mcount() (new stub) + - ftrace_caller() + - ftrace_call() + - ftrace_stub() + - C code: + - ftrace_dyn_arch_init() + - ftrace_make_nop() + - ftrace_make_call() + - ftrace_update_ftrace_func() + +First you will need to fill out some arch details in your asm/ftrace.h. + +Define MCOUNT_ADDR as the address of your mcount symbol similar to: + #define MCOUNT_ADDR ((unsigned long)mcount) +Since no one else will have a decl for that function, you will need to: + extern void mcount(void); + +You will also need the helper function ftrace_call_adjust(). Most people +will be able to stub it out like so: + static inline unsigned long ftrace_call_adjust(unsigned long addr) + { + return addr; + } <details to be filled> +Lastly you will need the custom dyn_arch_ftrace structure. If you need +some extra state when runtime patching arbitrary call sites, this is the +place. For now though, create an empty struct: + struct dyn_arch_ftrace { + /* No extra data needed */ + }; + +With the header out of the way, we can fill out the assembly code. While we +did already create a mcount() function earlier, dynamic ftrace only wants a +stub function. This is because the mcount() will only be used during boot +and then all references to it will be patched out never to return. Instead, +the guts of the old mcount() will be used to create a new ftrace_caller() +function. Because the two are hard to merge, it will most likely be a lot +easier to have two separate definitions split up by #ifdefs. Same goes for +the ftrace_stub() as that will now be inlined in ftrace_caller(). + +Before we get confused anymore, let's check out some pseudo code so you can +implement your own stuff in assembly: -HAVE_DYNAMIC_FTRACE ---------------------- +void mcount(void) +{ + return; +} + +void ftrace_caller(void) +{ + /* implement HAVE_FUNCTION_TRACE_MCOUNT_TEST if you desire */ + + /* save all state needed by the ABI (see paragraph above) */ + + unsigned long frompc = ...; + unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; + +ftrace_call: + ftrace_stub(frompc, selfpc); + + /* restore all state needed by the ABI */ + +ftrace_stub: + return; +} + +This might look a little odd at first, but keep in mind that we will be runtime +patching multiple things. First, only functions that we actually want to trace +will be patched to call ftrace_caller(). Second, since we only have one tracer +active at a time, we will patch the ftrace_caller() function itself to call the +specific tracer in question. That is the point of the ftrace_call label. + +With that in mind, let's move on to the C code that will actually be doing the +runtime patching. You'll need a little knowledge of your arch's opcodes in +order to make it through the next section. + +Every arch has an init callback function. If you need to do something early on +to initialize some state, this is the time to do that. Otherwise, this simple +function below should be sufficient for most people: + +int __init ftrace_dyn_arch_init(void *data) +{ + /* return value is done indirectly via data */ + *(unsigned long *)data = 0; + + return 0; +} + +There are two functions that are used to do runtime patching of arbitrary +functions. The first is used to turn the mcount call site into a nop (which +is what helps us retain runtime performance when not tracing). The second is +used to turn the mcount call site into a call to an arbitrary location (but +typically that is ftracer_caller()). See the general function definition in +linux/ftrace.h for the functions: + ftrace_make_nop() + ftrace_make_call() +The rec->ip value is the address of the mcount call site that was collected +by the scripts/recordmcount.pl during build time. + +The last function is used to do runtime patching of the active tracer. This +will be modifying the assembly code at the location of the ftrace_call symbol +inside of the ftrace_caller() function. So you should have sufficient padding +at that location to support the new function calls you'll be inserting. Some +people will be using a "call" type instruction while others will be using a +"branch" type instruction. Specifically, the function is: + ftrace_update_ftrace_func() + + +HAVE_DYNAMIC_FTRACE + HAVE_FUNCTION_GRAPH_TRACER +------------------------------------------------ + +The function grapher needs a few tweaks in order to work with dynamic ftrace. +Basically, you will need to: + - update: + - ftrace_caller() + - ftrace_graph_call() + - ftrace_graph_caller() + - implement: + - ftrace_enable_ftrace_graph_caller() + - ftrace_disable_ftrace_graph_caller() <details to be filled> +Quick notes: + - add a nop stub after the ftrace_call location named ftrace_graph_call; + stub needs to be large enough to support a call to ftrace_graph_caller() + - update ftrace_graph_caller() to work with being called by the new + ftrace_caller() since some semantics may have changed + - ftrace_enable_ftrace_graph_caller() will runtime patch the + ftrace_graph_call location with a call to ftrace_graph_caller() + - ftrace_disable_ftrace_graph_caller() will runtime patch the + ftrace_graph_call location with nops diff --git a/Documentation/trace/kmemtrace.txt b/Documentation/trace/kmemtrace.txt deleted file mode 100644 index 6308735e58c..00000000000 --- a/Documentation/trace/kmemtrace.txt +++ /dev/null @@ -1,126 +0,0 @@ - kmemtrace - Kernel Memory Tracer - - by Eduard - Gabriel Munteanu - <eduard.munteanu@linux360.ro> - -I. Introduction -=============== - -kmemtrace helps kernel developers figure out two things: -1) how different allocators (SLAB, SLUB etc.) perform -2) how kernel code allocates memory and how much - -To do this, we trace every allocation and export information to the userspace -through the relay interface. We export things such as the number of requested -bytes, the number of bytes actually allocated (i.e. including internal -fragmentation), whether this is a slab allocation or a plain kmalloc() and so -on. - -The actual analysis is performed by a userspace tool (see section III for -details on where to get it from). It logs the data exported by the kernel, -processes it and (as of writing this) can provide the following information: -- the total amount of memory allocated and fragmentation per call-site -- the amount of memory allocated and fragmentation per allocation -- total memory allocated and fragmentation in the collected dataset -- number of cross-CPU allocation and frees (makes sense in NUMA environments) - -Moreover, it can potentially find inconsistent and erroneous behavior in -kernel code, such as using slab free functions on kmalloc'ed memory or -allocating less memory than requested (but not truly failed allocations). - -kmemtrace also makes provisions for tracing on some arch and analysing the -data on another. - -II. Design and goals -==================== - -kmemtrace was designed to handle rather large amounts of data. Thus, it uses -the relay interface to export whatever is logged to userspace, which then -stores it. Analysis and reporting is done asynchronously, that is, after the -data is collected and stored. By design, it allows one to log and analyse -on different machines and different arches. - -As of writing this, the ABI is not considered stable, though it might not -change much. However, no guarantees are made about compatibility yet. When -deemed stable, the ABI should still allow easy extension while maintaining -backward compatibility. This is described further in Documentation/ABI. - -Summary of design goals: - - allow logging and analysis to be done across different machines - - be fast and anticipate usage in high-load environments (*) - - be reasonably extensible - - make it possible for GNU/Linux distributions to have kmemtrace - included in their repositories - -(*) - one of the reasons Pekka Enberg's original userspace data analysis - tool's code was rewritten from Perl to C (although this is more than a - simple conversion) - - -III. Quick usage guide -====================== - -1) Get a kernel that supports kmemtrace and build it accordingly (i.e. enable -CONFIG_KMEMTRACE). - -2) Get the userspace tool and build it: -$ git clone git://repo.or.cz/kmemtrace-user.git # current repository -$ cd kmemtrace-user/ -$ ./autogen.sh -$ ./configure -$ make - -3) Boot the kmemtrace-enabled kernel if you haven't, preferably in the -'single' runlevel (so that relay buffers don't fill up easily), and run -kmemtrace: -# '$' does not mean user, but root here. -$ mount -t debugfs none /sys/kernel/debug -$ mount -t proc none /proc -$ cd path/to/kmemtrace-user/ -$ ./kmemtraced -Wait a bit, then stop it with CTRL+C. -$ cat /sys/kernel/debug/kmemtrace/total_overruns # Check if we didn't - # overrun, should - # be zero. -$ (Optionally) [Run kmemtrace_check separately on each cpu[0-9]*.out file to - check its correctness] -$ ./kmemtrace-report - -Now you should have a nice and short summary of how the allocator performs. - -IV. FAQ and known issues -======================== - -Q: 'cat /sys/kernel/debug/kmemtrace/total_overruns' is non-zero, how do I fix -this? Should I worry? -A: If it's non-zero, this affects kmemtrace's accuracy, depending on how -large the number is. You can fix it by supplying a higher -'kmemtrace.subbufs=N' kernel parameter. ---- - -Q: kmemtrace_check reports errors, how do I fix this? Should I worry? -A: This is a bug and should be reported. It can occur for a variety of -reasons: - - possible bugs in relay code - - possible misuse of relay by kmemtrace - - timestamps being collected unorderly -Or you may fix it yourself and send us a patch. ---- - -Q: kmemtrace_report shows many errors, how do I fix this? Should I worry? -A: This is a known issue and I'm working on it. These might be true errors -in kernel code, which may have inconsistent behavior (e.g. allocating memory -with kmem_cache_alloc() and freeing it with kfree()). Pekka Enberg pointed -out this behavior may work with SLAB, but may fail with other allocators. - -It may also be due to lack of tracing in some unusual allocator functions. - -We don't want bug reports regarding this issue yet. ---- - -V. See also -=========== - -Documentation/kernel-parameters.txt -Documentation/ABI/testing/debugfs-kmemtrace - diff --git a/Documentation/trace/kprobetrace.txt b/Documentation/trace/kprobetrace.txt index ec94748ae65..5f77d94598d 100644 --- a/Documentation/trace/kprobetrace.txt +++ b/Documentation/trace/kprobetrace.txt @@ -42,7 +42,7 @@ Synopsis of kprobe_events +|-offs(FETCHARG) : Fetch memory at FETCHARG +|- offs address.(**) NAME=FETCHARG : Set NAME as the argument name of FETCHARG. FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types - (u8/u16/u32/u64/s8/s16/s32/s64) are supported. + (u8/u16/u32/u64/s8/s16/s32/s64) and string are supported. (*) only for return probe. (**) this is useful for fetching a field of data structures. diff --git a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl new file mode 100644 index 00000000000..b3e73ddb156 --- /dev/null +++ b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl @@ -0,0 +1,705 @@ +#!/usr/bin/perl +# This is a POC for reading the text representation of trace output related to +# page reclaim. It makes an attempt to extract some high-level information on +# what is going on. The accuracy of the parser may vary +# +# Example usage: trace-vmscan-postprocess.pl < /sys/kernel/debug/tracing/trace_pipe +# other options +# --read-procstat If the trace lacks process info, get it from /proc +# --ignore-pid Aggregate processes of the same name together +# +# Copyright (c) IBM Corporation 2009 +# Author: Mel Gorman <mel@csn.ul.ie> +use strict; +use Getopt::Long; + +# Tracepoint events +use constant MM_VMSCAN_DIRECT_RECLAIM_BEGIN => 1; +use constant MM_VMSCAN_DIRECT_RECLAIM_END => 2; +use constant MM_VMSCAN_KSWAPD_WAKE => 3; +use constant MM_VMSCAN_KSWAPD_SLEEP => 4; +use constant MM_VMSCAN_LRU_SHRINK_ACTIVE => 5; +use constant MM_VMSCAN_LRU_SHRINK_INACTIVE => 6; +use constant MM_VMSCAN_LRU_ISOLATE => 7; +use constant MM_VMSCAN_WRITEPAGE_FILE_SYNC => 8; +use constant MM_VMSCAN_WRITEPAGE_ANON_SYNC => 9; +use constant MM_VMSCAN_WRITEPAGE_FILE_ASYNC => 10; +use constant MM_VMSCAN_WRITEPAGE_ANON_ASYNC => 11; +use constant MM_VMSCAN_WRITEPAGE_ASYNC => 12; +use constant EVENT_UNKNOWN => 13; + +# Per-order events +use constant MM_VMSCAN_DIRECT_RECLAIM_BEGIN_PERORDER => 11; +use constant MM_VMSCAN_WAKEUP_KSWAPD_PERORDER => 12; +use constant MM_VMSCAN_KSWAPD_WAKE_PERORDER => 13; +use constant HIGH_KSWAPD_REWAKEUP_PERORDER => 14; + +# Constants used to track state +use constant STATE_DIRECT_BEGIN => 15; +use constant STATE_DIRECT_ORDER => 16; +use constant STATE_KSWAPD_BEGIN => 17; +use constant STATE_KSWAPD_ORDER => 18; + +# High-level events extrapolated from tracepoints +use constant HIGH_DIRECT_RECLAIM_LATENCY => 19; +use constant HIGH_KSWAPD_LATENCY => 20; +use constant HIGH_KSWAPD_REWAKEUP => 21; +use constant HIGH_NR_SCANNED => 22; +use constant HIGH_NR_TAKEN => 23; +use constant HIGH_NR_RECLAIMED => 24; +use constant HIGH_NR_CONTIG_DIRTY => 25; + +my %perprocesspid; +my %perprocess; +my %last_procmap; +my $opt_ignorepid; +my $opt_read_procstat; + +my $total_wakeup_kswapd; +my ($total_direct_reclaim, $total_direct_nr_scanned); +my ($total_direct_latency, $total_kswapd_latency); +my ($total_direct_nr_reclaimed); +my ($total_direct_writepage_file_sync, $total_direct_writepage_file_async); +my ($total_direct_writepage_anon_sync, $total_direct_writepage_anon_async); +my ($total_kswapd_nr_scanned, $total_kswapd_wake); +my ($total_kswapd_writepage_file_sync, $total_kswapd_writepage_file_async); +my ($total_kswapd_writepage_anon_sync, $total_kswapd_writepage_anon_async); +my ($total_kswapd_nr_reclaimed); + +# Catch sigint and exit on request +my $sigint_report = 0; +my $sigint_exit = 0; +my $sigint_pending = 0; +my $sigint_received = 0; +sub sigint_handler { + my $current_time = time; + if ($current_time - 2 > $sigint_received) { + print "SIGINT received, report pending. Hit ctrl-c again to exit\n"; + $sigint_report = 1; + } else { + if (!$sigint_exit) { + print "Second SIGINT received quickly, exiting\n"; + } + $sigint_exit++; + } + + if ($sigint_exit > 3) { + print "Many SIGINTs received, exiting now without report\n"; + exit; + } + + $sigint_received = $current_time; + $sigint_pending = 1; +} +$SIG{INT} = "sigint_handler"; + +# Parse command line options +GetOptions( + 'ignore-pid' => \$opt_ignorepid, + 'read-procstat' => \$opt_read_procstat, +); + +# Defaults for dynamically discovered regex's +my $regex_direct_begin_default = 'order=([0-9]*) may_writepage=([0-9]*) gfp_flags=([A-Z_|]*)'; +my $regex_direct_end_default = 'nr_reclaimed=([0-9]*)'; +my $regex_kswapd_wake_default = 'nid=([0-9]*) order=([0-9]*)'; +my $regex_kswapd_sleep_default = 'nid=([0-9]*)'; +my $regex_wakeup_kswapd_default = 'nid=([0-9]*) zid=([0-9]*) order=([0-9]*)'; +my $regex_lru_isolate_default = 'isolate_mode=([0-9]*) order=([0-9]*) nr_requested=([0-9]*) nr_scanned=([0-9]*) nr_taken=([0-9]*) contig_taken=([0-9]*) contig_dirty=([0-9]*) contig_failed=([0-9]*)'; +my $regex_lru_shrink_inactive_default = 'nid=([0-9]*) zid=([0-9]*) nr_scanned=([0-9]*) nr_reclaimed=([0-9]*) priority=([0-9]*) flags=([A-Z_|]*)'; +my $regex_lru_shrink_active_default = 'lru=([A-Z_]*) nr_scanned=([0-9]*) nr_rotated=([0-9]*) priority=([0-9]*)'; +my $regex_writepage_default = 'page=([0-9a-f]*) pfn=([0-9]*) flags=([A-Z_|]*)'; + +# Dyanically discovered regex +my $regex_direct_begin; +my $regex_direct_end; +my $regex_kswapd_wake; +my $regex_kswapd_sleep; +my $regex_wakeup_kswapd; +my $regex_lru_isolate; +my $regex_lru_shrink_inactive; +my $regex_lru_shrink_active; +my $regex_writepage; + +# Static regex used. Specified like this for readability and for use with /o +# (process_pid) (cpus ) ( time ) (tpoint ) (details) +my $regex_traceevent = '\s*([a-zA-Z0-9-]*)\s*(\[[0-9]*\])\s*([0-9.]*):\s*([a-zA-Z_]*):\s*(.*)'; +my $regex_statname = '[-0-9]*\s\((.*)\).*'; +my $regex_statppid = '[-0-9]*\s\(.*\)\s[A-Za-z]\s([0-9]*).*'; + +sub generate_traceevent_regex { + my $event = shift; + my $default = shift; + my $regex; + + # Read the event format or use the default + if (!open (FORMAT, "/sys/kernel/debug/tracing/events/$event/format")) { + print("WARNING: Event $event format string not found\n"); + return $default; + } else { + my $line; + while (!eof(FORMAT)) { + $line = <FORMAT>; + $line =~ s/, REC->.*//; + if ($line =~ /^print fmt:\s"(.*)".*/) { + $regex = $1; + $regex =~ s/%s/\([0-9a-zA-Z|_]*\)/g; + $regex =~ s/%p/\([0-9a-f]*\)/g; + $regex =~ s/%d/\([-0-9]*\)/g; + $regex =~ s/%ld/\([-0-9]*\)/g; + $regex =~ s/%lu/\([0-9]*\)/g; + } + } + } + + # Can't handle the print_flags stuff but in the context of this + # script, it really doesn't matter + $regex =~ s/\(REC.*\) \? __print_flags.*//; + + # Verify fields are in the right order + my $tuple; + foreach $tuple (split /\s/, $regex) { + my ($key, $value) = split(/=/, $tuple); + my $expected = shift; + if ($key ne $expected) { + print("WARNING: Format not as expected for event $event '$key' != '$expected'\n"); + $regex =~ s/$key=\((.*)\)/$key=$1/; + } + } + + if (defined shift) { + die("Fewer fields than expected in format"); + } + + return $regex; +} + +$regex_direct_begin = generate_traceevent_regex( + "vmscan/mm_vmscan_direct_reclaim_begin", + $regex_direct_begin_default, + "order", "may_writepage", + "gfp_flags"); +$regex_direct_end = generate_traceevent_regex( + "vmscan/mm_vmscan_direct_reclaim_end", + $regex_direct_end_default, + "nr_reclaimed"); +$regex_kswapd_wake = generate_traceevent_regex( + "vmscan/mm_vmscan_kswapd_wake", + $regex_kswapd_wake_default, + "nid", "order"); +$regex_kswapd_sleep = generate_traceevent_regex( + "vmscan/mm_vmscan_kswapd_sleep", + $regex_kswapd_sleep_default, + "nid"); +$regex_wakeup_kswapd = generate_traceevent_regex( + "vmscan/mm_vmscan_wakeup_kswapd", + $regex_wakeup_kswapd_default, + "nid", "zid", "order"); +$regex_lru_isolate = generate_traceevent_regex( + "vmscan/mm_vmscan_lru_isolate", + $regex_lru_isolate_default, + "isolate_mode", "order", + "nr_requested", "nr_scanned", "nr_taken", + "contig_taken", "contig_dirty", "contig_failed"); +$regex_lru_shrink_inactive = generate_traceevent_regex( + "vmscan/mm_vmscan_lru_shrink_inactive", + $regex_lru_shrink_inactive_default, + "nid", "zid", + "nr_scanned", "nr_reclaimed", "priority", + "flags"); +$regex_lru_shrink_active = generate_traceevent_regex( + "vmscan/mm_vmscan_lru_shrink_active", + $regex_lru_shrink_active_default, + "nid", "zid", + "lru", + "nr_scanned", "nr_rotated", "priority"); +$regex_writepage = generate_traceevent_regex( + "vmscan/mm_vmscan_writepage", + $regex_writepage_default, + "page", "pfn", "flags"); + +sub read_statline($) { + my $pid = $_[0]; + my $statline; + + if (open(STAT, "/proc/$pid/stat")) { + $statline = <STAT>; + close(STAT); + } + + if ($statline eq '') { + $statline = "-1 (UNKNOWN_PROCESS_NAME) R 0"; + } + + return $statline; +} + +sub guess_process_pid($$) { + my $pid = $_[0]; + my $statline = $_[1]; + + if ($pid == 0) { + return "swapper-0"; + } + + if ($statline !~ /$regex_statname/o) { + die("Failed to math stat line for process name :: $statline"); + } + return "$1-$pid"; +} + +# Convert sec.usec timestamp format +sub timestamp_to_ms($) { + my $timestamp = $_[0]; + + my ($sec, $usec) = split (/\./, $timestamp); + return ($sec * 1000) + ($usec / 1000); +} + +sub process_events { + my $traceevent; + my $process_pid; + my $cpus; + my $timestamp; + my $tracepoint; + my $details; + my $statline; + + # Read each line of the event log +EVENT_PROCESS: + while ($traceevent = <STDIN>) { + if ($traceevent =~ /$regex_traceevent/o) { + $process_pid = $1; + $timestamp = $3; + $tracepoint = $4; + + $process_pid =~ /(.*)-([0-9]*)$/; + my $process = $1; + my $pid = $2; + + if ($process eq "") { + $process = $last_procmap{$pid}; + $process_pid = "$process-$pid"; + } + $last_procmap{$pid} = $process; + + if ($opt_read_procstat) { + $statline = read_statline($pid); + if ($opt_read_procstat && $process eq '') { + $process_pid = guess_process_pid($pid, $statline); + } + } + } else { + next; + } + + # Perl Switch() sucks majorly + if ($tracepoint eq "mm_vmscan_direct_reclaim_begin") { + $timestamp = timestamp_to_ms($timestamp); + $perprocesspid{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN}++; + $perprocesspid{$process_pid}->{STATE_DIRECT_BEGIN} = $timestamp; + + $details = $5; + if ($details !~ /$regex_direct_begin/o) { + print "WARNING: Failed to parse mm_vmscan_direct_reclaim_begin as expected\n"; + print " $details\n"; + print " $regex_direct_begin\n"; + next; + } + my $order = $1; + $perprocesspid{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN_PERORDER}[$order]++; + $perprocesspid{$process_pid}->{STATE_DIRECT_ORDER} = $order; + } elsif ($tracepoint eq "mm_vmscan_direct_reclaim_end") { + # Count the event itself + my $index = $perprocesspid{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_END}; + $perprocesspid{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_END}++; + + # Record how long direct reclaim took this time + if (defined $perprocesspid{$process_pid}->{STATE_DIRECT_BEGIN}) { + $timestamp = timestamp_to_ms($timestamp); + my $order = $perprocesspid{$process_pid}->{STATE_DIRECT_ORDER}; + my $latency = ($timestamp - $perprocesspid{$process_pid}->{STATE_DIRECT_BEGIN}); + $perprocesspid{$process_pid}->{HIGH_DIRECT_RECLAIM_LATENCY}[$index] = "$order-$latency"; + } + } elsif ($tracepoint eq "mm_vmscan_kswapd_wake") { + $details = $5; + if ($details !~ /$regex_kswapd_wake/o) { + print "WARNING: Failed to parse mm_vmscan_kswapd_wake as expected\n"; + print " $details\n"; + print " $regex_kswapd_wake\n"; + next; + } + + my $order = $2; + $perprocesspid{$process_pid}->{STATE_KSWAPD_ORDER} = $order; + if (!$perprocesspid{$process_pid}->{STATE_KSWAPD_BEGIN}) { + $timestamp = timestamp_to_ms($timestamp); + $perprocesspid{$process_pid}->{MM_VMSCAN_KSWAPD_WAKE}++; + $perprocesspid{$process_pid}->{STATE_KSWAPD_BEGIN} = $timestamp; + $perprocesspid{$process_pid}->{MM_VMSCAN_KSWAPD_WAKE_PERORDER}[$order]++; + } else { + $perprocesspid{$process_pid}->{HIGH_KSWAPD_REWAKEUP}++; + $perprocesspid{$process_pid}->{HIGH_KSWAPD_REWAKEUP_PERORDER}[$order]++; + } + } elsif ($tracepoint eq "mm_vmscan_kswapd_sleep") { + + # Count the event itself + my $index = $perprocesspid{$process_pid}->{MM_VMSCAN_KSWAPD_SLEEP}; + $perprocesspid{$process_pid}->{MM_VMSCAN_KSWAPD_SLEEP}++; + + # Record how long kswapd was awake + $timestamp = timestamp_to_ms($timestamp); + my $order = $perprocesspid{$process_pid}->{STATE_KSWAPD_ORDER}; + my $latency = ($timestamp - $perprocesspid{$process_pid}->{STATE_KSWAPD_BEGIN}); + $perprocesspid{$process_pid}->{HIGH_KSWAPD_LATENCY}[$index] = "$order-$latency"; + $perprocesspid{$process_pid}->{STATE_KSWAPD_BEGIN} = 0; + } elsif ($tracepoint eq "mm_vmscan_wakeup_kswapd") { + $perprocesspid{$process_pid}->{MM_VMSCAN_WAKEUP_KSWAPD}++; + + $details = $5; + if ($details !~ /$regex_wakeup_kswapd/o) { + print "WARNING: Failed to parse mm_vmscan_wakeup_kswapd as expected\n"; + print " $details\n"; + print " $regex_wakeup_kswapd\n"; + next; + } + my $order = $3; + $perprocesspid{$process_pid}->{MM_VMSCAN_WAKEUP_KSWAPD_PERORDER}[$order]++; + } elsif ($tracepoint eq "mm_vmscan_lru_isolate") { + $details = $5; + if ($details !~ /$regex_lru_isolate/o) { + print "WARNING: Failed to parse mm_vmscan_lru_isolate as expected\n"; + print " $details\n"; + print " $regex_lru_isolate/o\n"; + next; + } + my $nr_scanned = $4; + my $nr_contig_dirty = $7; + $perprocesspid{$process_pid}->{HIGH_NR_SCANNED} += $nr_scanned; + $perprocesspid{$process_pid}->{HIGH_NR_CONTIG_DIRTY} += $nr_contig_dirty; + } elsif ($tracepoint eq "mm_vmscan_lru_shrink_inactive") { + $details = $5; + if ($details !~ /$regex_lru_shrink_inactive/o) { + print "WARNING: Failed to parse mm_vmscan_lru_shrink_inactive as expected\n"; + print " $details\n"; + print " $regex_lru_shrink_inactive/o\n"; + next; + } + my $nr_reclaimed = $4; + $perprocesspid{$process_pid}->{HIGH_NR_RECLAIMED} += $nr_reclaimed; + } elsif ($tracepoint eq "mm_vmscan_writepage") { + $details = $5; + if ($details !~ /$regex_writepage/o) { + print "WARNING: Failed to parse mm_vmscan_writepage as expected\n"; + print " $details\n"; + print " $regex_writepage\n"; + next; + } + + my $flags = $3; + my $file = 0; + my $sync_io = 0; + if ($flags =~ /RECLAIM_WB_FILE/) { + $file = 1; + } + if ($flags =~ /RECLAIM_WB_SYNC/) { + $sync_io = 1; + } + if ($sync_io) { + if ($file) { + $perprocesspid{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_SYNC}++; + } else { + $perprocesspid{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_SYNC}++; + } + } else { + if ($file) { + $perprocesspid{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_ASYNC}++; + } else { + $perprocesspid{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_ASYNC}++; + } + } + } else { + $perprocesspid{$process_pid}->{EVENT_UNKNOWN}++; + } + + if ($sigint_pending) { + last EVENT_PROCESS; + } + } +} + +sub dump_stats { + my $hashref = shift; + my %stats = %$hashref; + + # Dump per-process stats + my $process_pid; + my $max_strlen = 0; + + # Get the maximum process name + foreach $process_pid (keys %perprocesspid) { + my $len = length($process_pid); + if ($len > $max_strlen) { + $max_strlen = $len; + } + } + $max_strlen += 2; + + # Work out latencies + printf("\n") if !$opt_ignorepid; + printf("Reclaim latencies expressed as order-latency_in_ms\n") if !$opt_ignorepid; + foreach $process_pid (keys %stats) { + + if (!$stats{$process_pid}->{HIGH_DIRECT_RECLAIM_LATENCY}[0] && + !$stats{$process_pid}->{HIGH_KSWAPD_LATENCY}[0]) { + next; + } + + printf "%-" . $max_strlen . "s ", $process_pid if !$opt_ignorepid; + my $index = 0; + while (defined $stats{$process_pid}->{HIGH_DIRECT_RECLAIM_LATENCY}[$index] || + defined $stats{$process_pid}->{HIGH_KSWAPD_LATENCY}[$index]) { + + if ($stats{$process_pid}->{HIGH_DIRECT_RECLAIM_LATENCY}[$index]) { + printf("%s ", $stats{$process_pid}->{HIGH_DIRECT_RECLAIM_LATENCY}[$index]) if !$opt_ignorepid; + my ($dummy, $latency) = split(/-/, $stats{$process_pid}->{HIGH_DIRECT_RECLAIM_LATENCY}[$index]); + $total_direct_latency += $latency; + } else { + printf("%s ", $stats{$process_pid}->{HIGH_KSWAPD_LATENCY}[$index]) if !$opt_ignorepid; + my ($dummy, $latency) = split(/-/, $stats{$process_pid}->{HIGH_KSWAPD_LATENCY}[$index]); + $total_kswapd_latency += $latency; + } + $index++; + } + print "\n" if !$opt_ignorepid; + } + + # Print out process activity + printf("\n"); + printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s %8s %8s\n", "Process", "Direct", "Wokeup", "Pages", "Pages", "Pages", "Pages", "Time"); + printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s %8s %8s\n", "details", "Rclms", "Kswapd", "Scanned", "Rclmed", "Sync-IO", "ASync-IO", "Stalled"); + foreach $process_pid (keys %stats) { + + if (!$stats{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN}) { + next; + } + + $total_direct_reclaim += $stats{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN}; + $total_wakeup_kswapd += $stats{$process_pid}->{MM_VMSCAN_WAKEUP_KSWAPD}; + $total_direct_nr_scanned += $stats{$process_pid}->{HIGH_NR_SCANNED}; + $total_direct_nr_reclaimed += $stats{$process_pid}->{HIGH_NR_RECLAIMED}; + $total_direct_writepage_file_sync += $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_SYNC}; + $total_direct_writepage_anon_sync += $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_SYNC}; + $total_direct_writepage_file_async += $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_ASYNC}; + + $total_direct_writepage_anon_async += $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_ASYNC}; + + my $index = 0; + my $this_reclaim_delay = 0; + while (defined $stats{$process_pid}->{HIGH_DIRECT_RECLAIM_LATENCY}[$index]) { + my ($dummy, $latency) = split(/-/, $stats{$process_pid}->{HIGH_DIRECT_RECLAIM_LATENCY}[$index]); + $this_reclaim_delay += $latency; + $index++; + } + + printf("%-" . $max_strlen . "s %8d %10d %8u %8u %8u %8u %8.3f", + $process_pid, + $stats{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN}, + $stats{$process_pid}->{MM_VMSCAN_WAKEUP_KSWAPD}, + $stats{$process_pid}->{HIGH_NR_SCANNED}, + $stats{$process_pid}->{HIGH_NR_RECLAIMED}, + $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_SYNC} + $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_SYNC}, + $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_ASYNC} + $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_ASYNC}, + $this_reclaim_delay / 1000); + + if ($stats{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN}) { + print " "; + for (my $order = 0; $order < 20; $order++) { + my $count = $stats{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN_PERORDER}[$order]; + if ($count != 0) { + print "direct-$order=$count "; + } + } + } + if ($stats{$process_pid}->{MM_VMSCAN_WAKEUP_KSWAPD}) { + print " "; + for (my $order = 0; $order < 20; $order++) { + my $count = $stats{$process_pid}->{MM_VMSCAN_WAKEUP_KSWAPD_PERORDER}[$order]; + if ($count != 0) { + print "wakeup-$order=$count "; + } + } + } + if ($stats{$process_pid}->{HIGH_NR_CONTIG_DIRTY}) { + print " "; + my $count = $stats{$process_pid}->{HIGH_NR_CONTIG_DIRTY}; + if ($count != 0) { + print "contig-dirty=$count "; + } + } + + print "\n"; + } + + # Print out kswapd activity + printf("\n"); + printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s\n", "Kswapd", "Kswapd", "Order", "Pages", "Pages", "Pages", "Pages"); + printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s\n", "Instance", "Wakeups", "Re-wakeup", "Scanned", "Rclmed", "Sync-IO", "ASync-IO"); + foreach $process_pid (keys %stats) { + + if (!$stats{$process_pid}->{MM_VMSCAN_KSWAPD_WAKE}) { + next; + } + + $total_kswapd_wake += $stats{$process_pid}->{MM_VMSCAN_KSWAPD_WAKE}; + $total_kswapd_nr_scanned += $stats{$process_pid}->{HIGH_NR_SCANNED}; + $total_kswapd_nr_reclaimed += $stats{$process_pid}->{HIGH_NR_RECLAIMED}; + $total_kswapd_writepage_file_sync += $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_SYNC}; + $total_kswapd_writepage_anon_sync += $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_SYNC}; + $total_kswapd_writepage_file_async += $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_ASYNC}; + $total_kswapd_writepage_anon_async += $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_ASYNC}; + + printf("%-" . $max_strlen . "s %8d %10d %8u %8u %8i %8u", + $process_pid, + $stats{$process_pid}->{MM_VMSCAN_KSWAPD_WAKE}, + $stats{$process_pid}->{HIGH_KSWAPD_REWAKEUP}, + $stats{$process_pid}->{HIGH_NR_SCANNED}, + $stats{$process_pid}->{HIGH_NR_RECLAIMED}, + $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_SYNC} + $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_SYNC}, + $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_ASYNC} + $stats{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_ASYNC}); + + if ($stats{$process_pid}->{MM_VMSCAN_KSWAPD_WAKE}) { + print " "; + for (my $order = 0; $order < 20; $order++) { + my $count = $stats{$process_pid}->{MM_VMSCAN_KSWAPD_WAKE_PERORDER}[$order]; + if ($count != 0) { + print "wake-$order=$count "; + } + } + } + if ($stats{$process_pid}->{HIGH_KSWAPD_REWAKEUP}) { + print " "; + for (my $order = 0; $order < 20; $order++) { + my $count = $stats{$process_pid}->{HIGH_KSWAPD_REWAKEUP_PERORDER}[$order]; + if ($count != 0) { + print "rewake-$order=$count "; + } + } + } + printf("\n"); + } + + # Print out summaries + $total_direct_latency /= 1000; + $total_kswapd_latency /= 1000; + print "\nSummary\n"; + print "Direct reclaims: $total_direct_reclaim\n"; + print "Direct reclaim pages scanned: $total_direct_nr_scanned\n"; + print "Direct reclaim pages reclaimed: $total_direct_nr_reclaimed\n"; + print "Direct reclaim write file sync I/O: $total_direct_writepage_file_sync\n"; + print "Direct reclaim write anon sync I/O: $total_direct_writepage_anon_sync\n"; + print "Direct reclaim write file async I/O: $total_direct_writepage_file_async\n"; + print "Direct reclaim write anon async I/O: $total_direct_writepage_anon_async\n"; + print "Wake kswapd requests: $total_wakeup_kswapd\n"; + printf "Time stalled direct reclaim: %-1.2f seconds\n", $total_direct_latency; + print "\n"; + print "Kswapd wakeups: $total_kswapd_wake\n"; + print "Kswapd pages scanned: $total_kswapd_nr_scanned\n"; + print "Kswapd pages reclaimed: $total_kswapd_nr_reclaimed\n"; + print "Kswapd reclaim write file sync I/O: $total_kswapd_writepage_file_sync\n"; + print "Kswapd reclaim write anon sync I/O: $total_kswapd_writepage_anon_sync\n"; + print "Kswapd reclaim write file async I/O: $total_kswapd_writepage_file_async\n"; + print "Kswapd reclaim write anon async I/O: $total_kswapd_writepage_anon_async\n"; + printf "Time kswapd awake: %-1.2f seconds\n", $total_kswapd_latency; +} + +sub aggregate_perprocesspid() { + my $process_pid; + my $process; + undef %perprocess; + + foreach $process_pid (keys %perprocesspid) { + $process = $process_pid; + $process =~ s/-([0-9])*$//; + if ($process eq '') { + $process = "NO_PROCESS_NAME"; + } + + $perprocess{$process}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN} += $perprocesspid{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN}; + $perprocess{$process}->{MM_VMSCAN_KSWAPD_WAKE} += $perprocesspid{$process_pid}->{MM_VMSCAN_KSWAPD_WAKE}; + $perprocess{$process}->{MM_VMSCAN_WAKEUP_KSWAPD} += $perprocesspid{$process_pid}->{MM_VMSCAN_WAKEUP_KSWAPD}; + $perprocess{$process}->{HIGH_KSWAPD_REWAKEUP} += $perprocesspid{$process_pid}->{HIGH_KSWAPD_REWAKEUP}; + $perprocess{$process}->{HIGH_NR_SCANNED} += $perprocesspid{$process_pid}->{HIGH_NR_SCANNED}; + $perprocess{$process}->{HIGH_NR_RECLAIMED} += $perprocesspid{$process_pid}->{HIGH_NR_RECLAIMED}; + $perprocess{$process}->{MM_VMSCAN_WRITEPAGE_FILE_SYNC} += $perprocesspid{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_SYNC}; + $perprocess{$process}->{MM_VMSCAN_WRITEPAGE_ANON_SYNC} += $perprocesspid{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_SYNC}; + $perprocess{$process}->{MM_VMSCAN_WRITEPAGE_FILE_ASYNC} += $perprocesspid{$process_pid}->{MM_VMSCAN_WRITEPAGE_FILE_ASYNC}; + $perprocess{$process}->{MM_VMSCAN_WRITEPAGE_ANON_ASYNC} += $perprocesspid{$process_pid}->{MM_VMSCAN_WRITEPAGE_ANON_ASYNC}; + + for (my $order = 0; $order < 20; $order++) { + $perprocess{$process}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN_PERORDER}[$order] += $perprocesspid{$process_pid}->{MM_VMSCAN_DIRECT_RECLAIM_BEGIN_PERORDER}[$order]; + $perprocess{$process}->{MM_VMSCAN_WAKEUP_KSWAPD_PERORDER}[$order] += $perprocesspid{$process_pid}->{MM_VMSCAN_WAKEUP_KSWAPD_PERORDER}[$order]; + $perprocess{$process}->{MM_VMSCAN_KSWAPD_WAKE_PERORDER}[$order] += $perprocesspid{$process_pid}->{MM_VMSCAN_KSWAPD_WAKE_PERORDER}[$order]; + + } + + # Aggregate direct reclaim latencies + my $wr_index = $perprocess{$process}->{MM_VMSCAN_DIRECT_RECLAIM_END}; + my $rd_index = 0; + while (defined $perprocesspid{$process_pid}->{HIGH_DIRECT_RECLAIM_LATENCY}[$rd_index]) { + $perprocess{$process}->{HIGH_DIRECT_RECLAIM_LATENCY}[$wr_index] = $perprocesspid{$process_pid}->{HIGH_DIRECT_RECLAIM_LATENCY}[$rd_index]; + $rd_index++; + $wr_index++; + } + $perprocess{$process}->{MM_VMSCAN_DIRECT_RECLAIM_END} = $wr_index; + + # Aggregate kswapd latencies + my $wr_index = $perprocess{$process}->{MM_VMSCAN_KSWAPD_SLEEP}; + my $rd_index = 0; + while (defined $perprocesspid{$process_pid}->{HIGH_KSWAPD_LATENCY}[$rd_index]) { + $perprocess{$process}->{HIGH_KSWAPD_LATENCY}[$wr_index] = $perprocesspid{$process_pid}->{HIGH_KSWAPD_LATENCY}[$rd_index]; + $rd_index++; + $wr_index++; + } + $perprocess{$process}->{MM_VMSCAN_DIRECT_RECLAIM_END} = $wr_index; + } +} + +sub report() { + if (!$opt_ignorepid) { + dump_stats(\%perprocesspid); + } else { + aggregate_perprocesspid(); + dump_stats(\%perprocess); + } +} + +# Process events or signals until neither is available +sub signal_loop() { + my $sigint_processed; + do { + $sigint_processed = 0; + process_events(); + + # Handle pending signals if any + if ($sigint_pending) { + my $current_time = time; + + if ($sigint_exit) { + print "Received exit signal\n"; + $sigint_pending = 0; + } + if ($sigint_report) { + if ($current_time >= $sigint_received + 2) { + report(); + $sigint_report = 0; + $sigint_pending = 0; + $sigint_processed = 1; + } + } + } + } while ($sigint_pending || $sigint_processed); +} + +signal_loop(); +report(); diff --git a/Documentation/uml/UserModeLinux-HOWTO.txt b/Documentation/uml/UserModeLinux-HOWTO.txt index 628013f944c..9b7e1904db1 100644 --- a/Documentation/uml/UserModeLinux-HOWTO.txt +++ b/Documentation/uml/UserModeLinux-HOWTO.txt @@ -8,62 +8,6 @@ Table of Contents - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1. Introduction 1.1 How is User Mode Linux Different? @@ -277,8 +221,7 @@ 1. Download the latest UML patch from - the download page <http://user-mode-linux.sourceforge.net/dl- - sf.html> + the download page <http://user-mode-linux.sourceforge.net/ In this example, the file is uml-patch-2.4.0-prerelease.bz2. @@ -438,7 +381,7 @@ as modules, especially filesystems and network protocols and filters, so most symbols which need to be exported probably already are. However, if you do find symbols that need exporting, let us - <http://user-mode-linux.sourceforge.net/contacts.html> know, and + <http://user-mode-linux.sourceforge.net/> know, and they'll be "taken care of". @@ -498,8 +441,8 @@ You will need a filesystem to boot UML from. There are a number available for download from here <http://user-mode- - linux.sourceforge.net/dl-sf.html> . There are also several tools - <http://user-mode-linux.sourceforge.net/fs_making.html> which can be + linux.sourceforge.net/> . There are also several tools + <http://user-mode-linux.sourceforge.net/> which can be used to generate UML-compatible filesystem images from media. The kernel will boot up and present you with a login prompt. @@ -1236,7 +1179,7 @@ Harald's original README is here <http://user-mode-linux.source- - forge.net/text/mcast.txt> and explains these in detail, as well as + forge.net/> and explains these in detail, as well as some other issues. @@ -1311,7 +1254,7 @@ kernel. These were pointed out by Tim Robinson <timro at trkr dot net> in - <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="this uml- + <http://www.geocrawler.com/> name="this uml- user post"> . @@ -2038,7 +1981,7 @@ uml_moo is installed with the UML deb and RPM. If you didn't install UML from one of those packages, you can also get it from the UML - utilities <http://user-mode-linux.sourceforge.net/dl-sf.html#UML + utilities <http://user-mode-linux.sourceforge.net/ utilities> tar file in tools/moo. @@ -4599,7 +4542,7 @@ Michael Jennings <mikejen at hevanet.com> sent in some material which is now gracing the top of the index page <http://user-mode- - linux.sourceforge.net/index.html> of this site. + linux.sourceforge.net/> of this site. SGI <http://www.sgi.com> (and more specifically Ralf Baechle <ralf at uni-koblenz.de> ) gave me an account on oss.sgi.com diff --git a/Documentation/usb/ehci.txt b/Documentation/usb/ehci.txt index 1536b7e7513..9dcafa7d930 100644 --- a/Documentation/usb/ehci.txt +++ b/Documentation/usb/ehci.txt @@ -9,7 +9,7 @@ compatible with the USB 1.1 standard. It defines three transfer speeds: - "Low Speed" 1.5 Mbit/sec USB 1.1 only addressed full speed and low speed. High speed devices -can be used on USB 1.1 systems, but they slow down to USB 1.1 speeds. +can be used on USB 1.1 systems, but they slow down to USB 1.1 speeds. USB 1.1 devices may also be used on USB 2.0 systems. When plugged into an EHCI controller, they are given to a USB 1.1 "companion" diff --git a/Documentation/usb/gadget_multi.txt b/Documentation/usb/gadget_multi.txt new file mode 100644 index 00000000000..80f4ef0eb75 --- /dev/null +++ b/Documentation/usb/gadget_multi.txt @@ -0,0 +1,150 @@ + -*- org -*- + +* Overview + +The Multifunction Composite Gadget (or g_multi) is a composite gadget +that makes extensive use of the composite framework to provide +a... multifunction gadget. + +In it's standard configuration it provides a single USB configuration +with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and +USB Mass Storage functions. + +A CDC ECM (Ethernet) function may be turned on via a Kconfig option +and RNDIS can be turned off. If they are both enabled the gadget will +have two configurations -- one with RNDIS and another with CDC ECM[3]. + +Please not that if you use non-standard configuration (that is enable +CDC ECM) you may need to change vendor and/or product ID. + +* Host drivers + +To make use of the gadget one needs to make it work on host side -- +without that there's no hope of achieving anything with the gadget. +As one might expect, things one need to do very from system to system. + +** Linux host drivers + +Since the gadget uses standard composite framework and appears as such +to Linux host it does not need any additional drivers on Linux host +side. All the functions are handled by respective drivers developed +for them. + +This is also true for two configuration set-up with RNDIS +configuration being the first one. Linux host will use the second +configuration with CDC ECM which should work better under Linux. + +** Windows host drivers + +For the gadget two work under Windows two conditions have to be met: + +*** Detecting as composite gadget + +First of all, Windows need to detect the gadget as an USB composite +gadget which on its own have some conditions[4]. If they are met, +Windows lets USB Generic Parent Driver[5] handle the device which then +tries to much drivers for each individual interface (sort of, don't +get into too many details). + +The good news is: you do not have to worry about most of the +conditions! + +The only thing to worry is that the gadget has to have a single +configuration so a dual RNDIS and CDC ECM gadget won't work unless you +create a proper INF -- and of course, if you do submit it! + +*** Installing drivers for each function + +The other, trickier thing is making Windows install drivers for each +individual function. + +For mass storage it is trivial since Windows detect it's an interface +implementing USB Mass Storage class and selects appropriate driver. + +Things are harder with RDNIS and CDC ACM. + +**** RNDIS + +To make Windows select RNDIS drivers for the first function in the +gadget, one needs to use the [[file:linux.inf]] file provided with this +document. It "attaches" Window's RNDIS driver to the first interface +of the gadget. + +Please note, that while testing we encountered some issues[6] when +RNDIS was not the first interface. You do not need to worry abut it +unless you are trying to develop your own gadget in which case watch +out for this bug. + +**** CDC ACM + +Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM. + +**** Customising the gadget + +If you intend to hack the g_multi gadget be advised that rearranging +functions will obviously change interface numbers for each of the +functionality. As an effect provided INFs won't work since they have +interface numbers hard-coded in them (it's not hard to change those +though[7]). + +This also means, that after experimenting with g_multi and changing +provided functions one should change gadget's vendor and/or product ID +so there will be no collision with other customised gadgets or the +original gadget. + +Failing to comply may cause brain damage after wondering for hours why +things don't work as intended before realising Windows have cached +some drivers information (changing USB port may sometimes help plus +you might try using USBDeview[8] to remove the phantom device). + +**** INF testing + +Provided INF files have been tested on Windows XP SP3, Windows Vista +and Windows 7, all 32-bit versions. It should work on 64-bit versions +as well. It most likely won't work on Windows prior to Windows XP +SP2. + +** Other systems + +At this moment, drivers for any other systems have not been tested. +Knowing how MacOS is based on BSD and BSD is an Open Source it is +believed that it should (read: "I have no idea whether it will") work +out-of-the-box. + +For more exotic systems I have even less to say... + +Any testing and drivers *are* *welcome*! + +* Authors + +This document has been written by Michal Nazarewicz +([[mailto:mina86@mina86.com]]). INF files have been hacked with +support of Marek Szyprowski ([[mailto:m.szyprowski@samsung.com]]) and +Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS +template[9], Microchip's CDC ACM INF file and David Brownell's +([[mailto:dbrownell@users.sourceforge.net]]) original INF files. + +* Footnotes + +[1] Remote Network Driver Interface Specification, +[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. + +[2] Communications Device Class Abstract Control Model, spec for this +and other USB classes can be found at +[[http://www.usb.org/developers/devclass_docs/]]. + +[3] CDC Ethernet Control Model. + +[4] [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]] + +[5] [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]] + +[6] To put it in some other nice words, Windows failed to respond to +any user input. + +[7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]] +useful. + +[8] http://www.nirsoft.net/utils/usb_devices_view.html + +[9] [[http://msdn.microsoft.com/en-us/library/ff570620.aspx]] diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt index eac7df94d8e..61e67f6a20a 100644 --- a/Documentation/usb/gadget_serial.txt +++ b/Documentation/usb/gadget_serial.txt @@ -151,88 +151,23 @@ instructions below to install the host side driver. Installing the Windows Host ACM Driver -------------------------------------- -To use the Windows ACM driver you must have the files "gserial.inf" -and "usbser.sys" together in a folder on the Windows machine. - -The "gserial.inf" file is given here. - --------------------- CUT HERE -------------------- -[Version] -Signature="$Windows NT$" -Class=Ports -ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} -Provider=%LINUX% -DriverVer=08/17/2004,0.0.2.0 -; Copyright (C) 2004 Al Borchers (alborchers@steinerpoint.com) - -[Manufacturer] -%LINUX%=GSerialDeviceList - -[GSerialDeviceList] -%GSERIAL%=GSerialInstall, USB\VID_0525&PID_A4A7 - -[DestinationDirs] -DefaultDestDir=10,System32\Drivers - -[GSerialInstall] -CopyFiles=GSerialCopyFiles -AddReg=GSerialAddReg - -[GSerialCopyFiles] -usbser.sys - -[GSerialAddReg] -HKR,,DevLoader,,*ntkern -HKR,,NTMPDriver,,usbser.sys -HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" - -[GSerialInstall.Services] -AddService = usbser,0x0002,GSerialService - -[GSerialService] -DisplayName = %GSERIAL_DISPLAY_NAME% -ServiceType = 1 ; SERVICE_KERNEL_DRIVER -StartType = 3 ; SERVICE_DEMAND_START -ErrorControl = 1 ; SERVICE_ERROR_NORMAL -ServiceBinary = %10%\System32\Drivers\usbser.sys -LoadOrderGroup = Base - -[Strings] -LINUX = "Linux" -GSERIAL = "Gadget Serial" -GSERIAL_DISPLAY_NAME = "USB Gadget Serial Driver" --------------------- CUT HERE -------------------- - -The "usbser.sys" file comes with various versions of Windows. -For example, it can be found on Windows XP typically in - - C:\WINDOWS\Driver Cache\i386\driver.cab - -Or it can be found on the Windows 98SE CD in the "win98" folder -in the "DRIVER11.CAB" through "DRIVER20.CAB" cab files. You will -need the DOS "expand" program, the Cygwin "cabextract" program, or -a similar program to unpack these cab files and extract "usbser.sys". - -For example, to extract "usbser.sys" into the current directory -on Windows XP, open a DOS window and run a command like - - expand C:\WINDOWS\Driver~1\i386\driver.cab -F:usbser.sys . - -(Thanks to Nishant Kamat for pointing out this DOS command.) +To use the Windows ACM driver you must have the "linux-cdc-acm.inf" +file (provided along this document) which supports all recent versions +of Windows. When the gadget serial driver is loaded and the USB device connected to the Windows host with a USB cable, Windows should recognize the gadget serial device and ask for a driver. Tell Windows to find the -driver in the folder that contains "gserial.inf" and "usbser.sys". +driver in the folder that contains the "linux-cdc-acm.inf" file. For example, on Windows XP, when the gadget serial device is first plugged in, the "Found New Hardware Wizard" starts up. Select -"Install from a list or specific location (Advanced)", then on -the next screen select "Include this location in the search" and -enter the path or browse to the folder containing "gserial.inf" and -"usbser.sys". Windows will complain that the Gadget Serial driver -has not passed Windows Logo testing, but select "Continue anyway" -and finish the driver installation. +"Install from a list or specific location (Advanced)", then on the +next screen select "Include this location in the search" and enter the +path or browse to the folder containing the "linux-cdc-acm.inf" file. +Windows will complain that the Gadget Serial driver has not passed +Windows Logo testing, but select "Continue anyway" and finish the +driver installation. On Windows XP, in the "Device Manager" (under "Control Panel", "System", "Hardware") expand the "Ports (COM & LPT)" entry and you @@ -345,5 +280,3 @@ you should be able to send data back and forth between the gadget side and host side systems. Anything you type on the terminal window on the gadget side should appear in the terminal window on the host side and vice versa. - - diff --git a/Documentation/usb/hotplug.txt b/Documentation/usb/hotplug.txt index f53170665f3..4c945716a66 100644 --- a/Documentation/usb/hotplug.txt +++ b/Documentation/usb/hotplug.txt @@ -10,7 +10,7 @@ immediately usable. That means the system must do many things, including: - Bind a driver to that device. Bus frameworks do that using a device driver's probe() routine. - + - Tell other subsystems to configure the new device. Print queues may need to be enabled, networks brought up, disk partitions mounted, and so on. In some cases these will @@ -84,7 +84,7 @@ USB MODUTILS SUPPORT Current versions of module-init-tools will create a "modules.usbmap" file which contains the entries from each driver's MODULE_DEVICE_TABLE. Such files can be used by various user mode policy agents to make sure all the -right driver modules get loaded, either at boot time or later. +right driver modules get loaded, either at boot time or later. See <linux/usb.h> for full information about such table entries; or look at existing drivers. Each table entry describes one or more criteria to diff --git a/Documentation/usb/linux-cdc-acm.inf b/Documentation/usb/linux-cdc-acm.inf new file mode 100644 index 00000000000..612e7220fb2 --- /dev/null +++ b/Documentation/usb/linux-cdc-acm.inf @@ -0,0 +1,107 @@ +; Windows USB CDC ACM Setup File + +; Based on INF template which was: +; Copyright (c) 2000 Microsoft Corporation +; Copyright (c) 2007 Microchip Technology Inc. +; likely to be covered by the MLPL as found at: +; <http://msdn.microsoft.com/en-us/cc300389.aspx#MLPL>. +; For use only on Windows operating systems. + +[Version] +Signature="$Windows NT$" +Class=Ports +ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} +Provider=%Linux% +DriverVer=11/15/2007,5.1.2600.0 + +[Manufacturer] +%Linux%=DeviceList, NTamd64 + +[DestinationDirs] +DefaultDestDir=12 + + +;------------------------------------------------------------------------------ +; Windows 2000/XP/Vista-32bit Sections +;------------------------------------------------------------------------------ + +[DriverInstall.nt] +include=mdmcpq.inf +CopyFiles=DriverCopyFiles.nt +AddReg=DriverInstall.nt.AddReg + +[DriverCopyFiles.nt] +usbser.sys,,,0x20 + +[DriverInstall.nt.AddReg] +HKR,,DevLoader,,*ntkern +HKR,,NTMPDriver,,USBSER.sys +HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" + +[DriverInstall.nt.Services] +AddService=usbser, 0x00000002, DriverService.nt + +[DriverService.nt] +DisplayName=%SERVICE% +ServiceType=1 +StartType=3 +ErrorControl=1 +ServiceBinary=%12%\USBSER.sys + +;------------------------------------------------------------------------------ +; Vista-64bit Sections +;------------------------------------------------------------------------------ + +[DriverInstall.NTamd64] +include=mdmcpq.inf +CopyFiles=DriverCopyFiles.NTamd64 +AddReg=DriverInstall.NTamd64.AddReg + +[DriverCopyFiles.NTamd64] +USBSER.sys,,,0x20 + +[DriverInstall.NTamd64.AddReg] +HKR,,DevLoader,,*ntkern +HKR,,NTMPDriver,,USBSER.sys +HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" + +[DriverInstall.NTamd64.Services] +AddService=usbser, 0x00000002, DriverService.NTamd64 + +[DriverService.NTamd64] +DisplayName=%SERVICE% +ServiceType=1 +StartType=3 +ErrorControl=1 +ServiceBinary=%12%\USBSER.sys + + +;------------------------------------------------------------------------------ +; Vendor and Product ID Definitions +;------------------------------------------------------------------------------ +; When developing your USB device, the VID and PID used in the PC side +; application program and the firmware on the microcontroller must match. +; Modify the below line to use your VID and PID. Use the format as shown +; below. +; Note: One INF file can be used for multiple devices with different +; VID and PIDs. For each supported device, append +; ",USB\VID_xxxx&PID_yyyy" to the end of the line. +;------------------------------------------------------------------------------ +[SourceDisksFiles] +[SourceDisksNames] +[DeviceList] +%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02 + +[DeviceList.NTamd64] +%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02 + + +;------------------------------------------------------------------------------ +; String Definitions +;------------------------------------------------------------------------------ +;Modify these strings to customize your device +;------------------------------------------------------------------------------ +[Strings] +Linux = "Linux Developer Community" +DESCRIPTION = "Gadget Serial" +SERVICE = "USB RS-232 Emulation Driver" diff --git a/Documentation/usb/linux.inf b/Documentation/usb/linux.inf index 2f7217d124f..4dee9585122 100644 --- a/Documentation/usb/linux.inf +++ b/Documentation/usb/linux.inf @@ -1,200 +1,66 @@ -; MS-Windows driver config matching some basic modes of the -; Linux-USB Ethernet/RNDIS gadget firmware: -; -; - RNDIS plus CDC Ethernet ... this may be familiar as a DOCSIS -; cable modem profile, and supports most non-Microsoft USB hosts -; -; - RNDIS plus CDC Subset ... used by hardware that incapable of -; full CDC Ethernet support. -; -; Microsoft only directly supports RNDIS drivers, and bundled them into XP. -; The Microsoft "Remote NDIS USB Driver Kit" is currently found at: -; http://www.microsoft.com/whdc/hwdev/resources/HWservices/rndis.mspx - +; Based on template INF file found at +; <http://msdn.microsoft.com/en-us/library/ff570620.aspx> +; which was: +; Copyright (c) Microsoft Corporation +; and released under the MLPL as found at: +; <http://msdn.microsoft.com/en-us/cc300389.aspx#MLPL>. +; For use only on Windows operating systems. [Version] -Signature = "$CHICAGO$" +Signature = "$Windows NT$" Class = Net ClassGUID = {4d36e972-e325-11ce-bfc1-08002be10318} Provider = %Linux% -Compatible = 1 -MillenniumPreferred = .ME -DriverVer = 03/30/2004,0.0.0.0 -; catalog file would be used by WHQL -;CatalogFile = Linux.cat +DriverVer = 06/21/2006,6.0.6000.16384 [Manufacturer] -%Linux% = LinuxDevices,NT.5.1 +%Linux% = LinuxDevices,NTx86,NTamd64,NTia64 + +; Decoration for x86 architecture +[LinuxDevices.NTx86] +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00 -[LinuxDevices] -; NetChip IDs, used by both firmware modes -%LinuxDevice% = RNDIS, USB\VID_0525&PID_a4a2 +; Decoration for x64 architecture +[LinuxDevices.NTamd64] +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00 -[LinuxDevices.NT.5.1] -%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2 +; Decoration for ia64 architecture +[LinuxDevices.NTia64] +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00 +;@@@ This is the common setting for setup [ControlFlags] ExcludeFromSelect=* -; Windows 98, Windows 98 Second Edition specific sections -------- - -[RNDIS] -DeviceID = usb8023 -MaxInstance = 512 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_98, RNDIS_AddReg_Common - -[RNDIS_AddReg_98] -HKR, , DevLoader, 0, *ndis -HKR, , DeviceVxDs, 0, usb8023.sys -HKR, NDIS, LogDriverName, 0, "usb8023" -HKR, NDIS, MajorNdisVersion, 1, 5 -HKR, NDIS, MinorNdisVersion, 1, 0 -HKR, Ndi\Interfaces, DefUpper, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, DefLower, 0, "ethernet" -HKR, Ndi\Interfaces, UpperRange, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, LowerRange, 0, "ethernet" -HKR, Ndi\Install, ndis3, 0, "RNDIS_Install_98" -HKR, Ndi\Install, ndis4, 0, "RNDIS_Install_98" -HKR, Ndi\Install, ndis5, 0, "RNDIS_Install_98" -HKR, Ndi, DeviceId, 0, "USB\VID_0525&PID_a4a2" - -[RNDIS_Install_98] -CopyFiles=RNDIS_CopyFiles_98 - -[RNDIS_CopyFiles_98] -usb8023.sys, usb8023w.sys, , 0 -rndismp.sys, rndismpw.sys, , 0 - -; Windows Millennium Edition specific sections -------------------- - -[RNDIS.ME] -DeviceID = usb8023 -MaxInstance = 512 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_ME, RNDIS_AddReg_Common -Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI -BusType = 15 - -[RNDIS_AddReg_ME] -HKR, , DevLoader, 0, *ndis -HKR, , DeviceVxDs, 0, usb8023.sys -HKR, NDIS, LogDriverName, 0, "usb8023" -HKR, NDIS, MajorNdisVersion, 1, 5 -HKR, NDIS, MinorNdisVersion, 1, 0 -HKR, Ndi\Interfaces, DefUpper, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, DefLower, 0, "ethernet" -HKR, Ndi\Interfaces, UpperRange, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, LowerRange, 0, "ethernet" -HKR, Ndi\Install, ndis3, 0, "RNDIS_Install_ME" -HKR, Ndi\Install, ndis4, 0, "RNDIS_Install_ME" -HKR, Ndi\Install, ndis5, 0, "RNDIS_Install_ME" -HKR, Ndi, DeviceId, 0, "USB\VID_0525&PID_a4a2" - -[RNDIS_Install_ME] -CopyFiles=RNDIS_CopyFiles_ME - -[RNDIS_CopyFiles_ME] -usb8023.sys, usb8023m.sys, , 0 -rndismp.sys, rndismpm.sys, , 0 - -; Windows 2000 specific sections --------------------------------- - -[RNDIS.NT] -Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI -BusType = 15 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_NT, RNDIS_AddReg_Common -CopyFiles = RNDIS_CopyFiles_NT - -[RNDIS.NT.Services] -AddService = USB_RNDIS, 2, RNDIS_ServiceInst_NT, RNDIS_EventLog - -[RNDIS_CopyFiles_NT] -; no rename of files on Windows 2000, use the 'k' names as is -usb8023k.sys, , , 0 -rndismpk.sys, , , 0 - -[RNDIS_ServiceInst_NT] -DisplayName = %ServiceDisplayName% -ServiceType = 1 -StartType = 3 -ErrorControl = 1 -ServiceBinary = %12%\usb8023k.sys -LoadOrderGroup = NDIS -AddReg = RNDIS_WMI_AddReg_NT - -[RNDIS_WMI_AddReg_NT] -HKR, , MofImagePath, 0x00020000, "System32\drivers\rndismpk.sys" - -; Windows XP specific sections ----------------------------------- - +; DDInstall section +; References the in-build Netrndis.inf [RNDIS.NT.5.1] -Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI -BusType = 15 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_NT, RNDIS_AddReg_Common -; no copyfiles - the files are already in place - +Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI +BusType = 15 +; NEVER REMOVE THE FOLLOWING REFERENCE FOR NETRNDIS.INF +include = netrndis.inf +needs = Usb_Rndis.ndi +AddReg = Rndis_AddReg_Vista + +; DDInstal.Services section [RNDIS.NT.5.1.Services] -AddService = USB_RNDIS, 2, RNDIS_ServiceInst_51, RNDIS_EventLog - -[RNDIS_ServiceInst_51] -DisplayName = %ServiceDisplayName% -ServiceType = 1 -StartType = 3 -ErrorControl = 1 -ServiceBinary = %12%\usb8023.sys -LoadOrderGroup = NDIS -AddReg = RNDIS_WMI_AddReg_51 - -[RNDIS_WMI_AddReg_51] -HKR, , MofImagePath, 0x00020000, "System32\drivers\rndismp.sys" - -; Windows 2000 and Windows XP common sections -------------------- - -[RNDIS_AddReg_NT] -HKR, Ndi, Service, 0, "USB_RNDIS" -HKR, Ndi\Interfaces, UpperRange, 0, "ndis5" -HKR, Ndi\Interfaces, LowerRange, 0, "ethernet" - -[RNDIS_EventLog] -AddReg = RNDIS_EventLog_AddReg - -[RNDIS_EventLog_AddReg] -HKR, , EventMessageFile, 0x00020000, "%%SystemRoot%%\System32\netevent.dll" -HKR, , TypesSupported, 0x00010001, 7 - -; Common Sections ------------------------------------------------- - -[RNDIS_AddReg_Common] -HKR, NDI\params\NetworkAddress, ParamDesc, 0, %NetworkAddress% -HKR, NDI\params\NetworkAddress, type, 0, "edit" -HKR, NDI\params\NetworkAddress, LimitText, 0, "12" -HKR, NDI\params\NetworkAddress, UpperCase, 0, "1" -HKR, NDI\params\NetworkAddress, default, 0, " " -HKR, NDI\params\NetworkAddress, optional, 0, "1" - -[SourceDisksNames] -1=%SourceDisk%,,1 - -[SourceDisksFiles] -usb8023m.sys=1 -rndismpm.sys=1 -usb8023w.sys=1 -rndismpw.sys=1 -usb8023k.sys=1 -rndismpk.sys=1 - -[DestinationDirs] -RNDIS_CopyFiles_98 = 10, system32/drivers -RNDIS_CopyFiles_ME = 10, system32/drivers -RNDIS_CopyFiles_NT = 12 +include = netrndis.inf +needs = Usb_Rndis.ndi.Services + +; Optional registry settings. You can modify as needed. +[RNDIS_AddReg_Vista] +HKR, NDI\params\VistaProperty, ParamDesc, 0, %Vista_Property% +HKR, NDI\params\VistaProperty, type, 0, "edit" +HKR, NDI\params\VistaProperty, LimitText, 0, "12" +HKR, NDI\params\VistaProperty, UpperCase, 0, "1" +HKR, NDI\params\VistaProperty, default, 0, " " +HKR, NDI\params\VistaProperty, optional, 0, "1" + +; No sys copyfiles - the sys files are already in-build +; (part of the operating system). +; We do not support XP SP1-, 2003 SP1-, ME, 9x. [Strings] -ServiceDisplayName = "USB Remote NDIS Network Device Driver" -NetworkAddress = "Network Address" Linux = "Linux Developer Community" LinuxDevice = "Linux USB Ethernet/RNDIS Gadget" -SourceDisk = "Ethernet/RNDIS Gadget Driver Install Disk" - +Vista_Property = "Optional Vista Property" diff --git a/Documentation/usb/mtouchusb.txt b/Documentation/usb/mtouchusb.txt index e43cfffaa10..86302cd53ed 100644 --- a/Documentation/usb/mtouchusb.txt +++ b/Documentation/usb/mtouchusb.txt @@ -54,10 +54,6 @@ generic functions like calibrations, resets, and vendor information can be requested from the userspace (And the drivers would handle the vendor specific tasks). -ADDITIONAL INFORMATION/UPDATES/X CONFIGURATION EXAMPLE: - -http://groomlakelabs.com/grandamp/code/microtouch/ - TODO: Implement a control urb again to handle requests to and from the device @@ -68,7 +64,7 @@ DISCLAIMER: I am not a MicroTouch/3M employee, nor have I ever been. 3M does not support this driver! If you want touch drivers only supported within X, please go to: -http://www.3m.com/3MTouchSystems/downloads/ +http://www.3m.com/3MTouchSystems/ THANKS: diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt index fafcd472326..afe596d5f20 100644 --- a/Documentation/usb/proc_usb_info.txt +++ b/Documentation/usb/proc_usb_info.txt @@ -1,12 +1,17 @@ /proc/bus/usb filesystem output =============================== -(version 2003.05.30) +(version 2010.09.13) The usbfs filesystem for USB devices is traditionally mounted at /proc/bus/usb. It provides the /proc/bus/usb/devices file, as well as the /proc/bus/usb/BBB/DDD files. +In many modern systems the usbfs filsystem isn't used at all. Instead +USB device nodes are created under /dev/usb/ or someplace similar. The +"devices" file is available in debugfs, typically as +/sys/kernel/debug/usb/devices. + **NOTE**: If /proc/bus/usb appears empty, and a host controller driver has been linked, then you need to mount the @@ -106,8 +111,8 @@ Legend: Topology info: -T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=ddd MxCh=dd -| | | | | | | | |__MaxChildren +T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd +| | | | | | | | |__MaxChildren | | | | | | | |__Device Speed in Mbps | | | | | | |__DeviceNumber | | | | | |__Count of devices at this level @@ -120,8 +125,13 @@ T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=ddd MxCh=dd Speed may be: 1.5 Mbit/s for low speed USB 12 Mbit/s for full speed USB - 480 Mbit/s for high speed USB (added for USB 2.0) + 480 Mbit/s for high speed USB (added for USB 2.0); + also used for Wireless USB, which has no fixed speed + 5000 Mbit/s for SuperSpeed USB (added for USB 3.0) + For reasons lost in the mists of time, the Port number is always + too low by 1. For example, a device plugged into port 4 will + show up with "Port=03". Bandwidth info: B: Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd @@ -291,7 +301,7 @@ Here's an example, from a system which has a UHCI root hub, an external hub connected to the root hub, and a mouse and a serial converter connected to the external hub. -T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 +T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0 D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=0000 ProdID=0000 Rev= 0.00 @@ -301,21 +311,21 @@ C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms -T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 +T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=0451 ProdID=1446 Rev= 1.00 C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms -T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 +T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=04b4 ProdID=0001 Rev= 0.00 C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms -T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 +T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=0565 ProdID=0001 Rev= 1.08 S: Manufacturer=Peracom Networks, Inc. @@ -330,12 +340,12 @@ E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms Selecting only the "T:" and "I:" lines from this (for example, by using "procusb ti"), we have: -T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 -T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 +T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 +T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub -T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 +T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse -T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 +T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial diff --git a/Documentation/usb/usb-serial.txt b/Documentation/usb/usb-serial.txt index f4d21451025..5bd7926185e 100644 --- a/Documentation/usb/usb-serial.txt +++ b/Documentation/usb/usb-serial.txt @@ -83,7 +83,7 @@ HandSpring Visor, Palm USB, and Clié USB driver parameters. e.g. modprobe visor vendor=0x54c product=0x66 There is a webpage and mailing lists for this portion of the driver at: - http://usbvisor.sourceforge.net/ + http://sourceforge.net/projects/usbvisor/ For any questions or problems with this driver, please contact Greg Kroah-Hartman at greg@kroah.com @@ -184,7 +184,7 @@ Keyspan USA-series Serial Adapters functionality. More information is available at: - http://misc.nu/hugh/keyspan.html + http://www.carnationsoftware.com/carnation/Keyspan.html For any questions or problems with this driver, please contact Hugh Blemings at hugh@misc.nu diff --git a/Documentation/video4linux/API.html b/Documentation/video4linux/API.html index d749d41f647..d72fd2aa915 100644 --- a/Documentation/video4linux/API.html +++ b/Documentation/video4linux/API.html @@ -17,7 +17,7 @@ </tr> <tr> <td> - <a href="http://www.linuxtv.org/downloads/video4linux/API/V4L2_API">V4L2 API</a> + <a href="http://v4l2spec.bytesex.org/spec-single/v4l2.html">V4L2 API</a> </td> <td>Should be used for new projects </td> diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885 index 16ca030e118..87c46347bd6 100644 --- a/Documentation/video4linux/CARDLIST.cx23885 +++ b/Documentation/video4linux/CARDLIST.cx23885 @@ -17,9 +17,9 @@ 16 -> DVBWorld DVB-S2 2005 [0001:2005] 17 -> NetUP Dual DVB-S2 CI [1b55:2a2c] 18 -> Hauppauge WinTV-HVR1270 [0070:2211] - 19 -> Hauppauge WinTV-HVR1275 [0070:2215] - 20 -> Hauppauge WinTV-HVR1255 [0070:2251] - 21 -> Hauppauge WinTV-HVR1210 [0070:2291,0070:2295] + 19 -> Hauppauge WinTV-HVR1275 [0070:2215,0070:221d,0070:22f2] + 20 -> Hauppauge WinTV-HVR1255 [0070:2251,0070:2259,0070:22f1] + 21 -> Hauppauge WinTV-HVR1210 [0070:2291,0070:2295,0070:2299,0070:229d,0070:22f0,0070:22f3,0070:22f4,0070:22f5] 22 -> Mygica X8506 DMB-TH [14f1:8651] 23 -> Magic-Pro ProHDTV Extreme 2 [14f1:8657] 24 -> Hauppauge WinTV-HVR1850 [0070:8541] diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88 index f2510541373..42517d9121d 100644 --- a/Documentation/video4linux/CARDLIST.cx88 +++ b/Documentation/video4linux/CARDLIST.cx88 @@ -83,3 +83,4 @@ 82 -> WinFast DTV2000 H rev. J [107d:6f2b] 83 -> Prof 7301 DVB-S/S2 [b034:3034] 84 -> Samsung SMT 7020 DVB-S [18ac:dc00,18ac:dccd] + 85 -> Twinhan VP-1027 DVB-S [1822:0023] diff --git a/Documentation/video4linux/CARDLIST.em28xx b/Documentation/video4linux/CARDLIST.em28xx index 3a623aaeae5..ac2616a62fc 100644 --- a/Documentation/video4linux/CARDLIST.em28xx +++ b/Documentation/video4linux/CARDLIST.em28xx @@ -31,6 +31,7 @@ 30 -> Videology 20K14XUSB USB2.0 (em2820/em2840) 31 -> Usbgear VD204v9 (em2821) 32 -> Supercomp USB 2.0 TV (em2821) + 33 -> Elgato Video Capture (em2860) [0fd9:0033] 34 -> Terratec Cinergy A Hybrid XS (em2860) [0ccd:004f] 35 -> Typhoon DVD Maker (em2860) 36 -> NetGMBH Cam (em2860) @@ -45,7 +46,7 @@ 45 -> Pinnacle PCTV DVB-T (em2870) 46 -> Compro, VideoMate U3 (em2870) [185b:2870] 47 -> KWorld DVB-T 305U (em2880) [eb1a:e305] - 48 -> KWorld DVB-T 310U (em2880) [eb1a:e310] + 48 -> KWorld DVB-T 310U (em2880) 49 -> MSI DigiVox A/D (em2880) [eb1a:e310] 50 -> MSI DigiVox A/D II (em2880) [eb1a:e320] 51 -> Terratec Hybrid XS Secam (em2880) [0ccd:004c] @@ -72,3 +73,4 @@ 73 -> Reddo DVB-C USB TV Box (em2870) 74 -> Actionmaster/LinXcel/Digitus VC211A (em2800) 75 -> Dikom DK300 (em2882) + 76 -> KWorld PlusTV 340U or UB435-Q (ATSC) (em2870) [1b80:a340] diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 1387a69ae3a..8d9afc7d801 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -126,7 +126,7 @@ 125 -> Beholder BeholdTV 409 [0000:4090] 126 -> Beholder BeholdTV 505 FM [5ace:5050] 127 -> Beholder BeholdTV 507 FM / BeholdTV 509 FM [5ace:5070,5ace:5090] -128 -> Beholder BeholdTV Columbus TVFM [0000:5201] +128 -> Beholder BeholdTV Columbus TV/FM [0000:5201] 129 -> Beholder BeholdTV 607 FM [5ace:6070] 130 -> Beholder BeholdTV M6 [5ace:6190] 131 -> Twinhan Hybrid DTV-DVB 3056 PCI [1822:0022] @@ -178,4 +178,5 @@ 177 -> Hawell HW-404M7 178 -> Beholder BeholdTV H7 [5ace:7190] 179 -> Beholder BeholdTV A7 [5ace:7090] -180 -> Avermedia M733A [1461:4155,1461:4255] +180 -> Avermedia PCI M733A [1461:4155,1461:4255] +181 -> TechoTrend TT-budget T-3000 [13c2:2804] diff --git a/Documentation/video4linux/CQcam.txt b/Documentation/video4linux/CQcam.txt index d230878e473..8977e7ce4da 100644 --- a/Documentation/video4linux/CQcam.txt +++ b/Documentation/video4linux/CQcam.txt @@ -203,11 +203,11 @@ The V4L2 API spec: http://v4l2spec.bytesex.org/ Some web pages about the quickcams: - http://www.dkfz-heidelberg.de/Macromol/wedemann/mini-HOWTO-cqcam.html + http://www.pingouin-land.com/howto/QuickCam-HOWTO.html http://www.crynwr.com/qcpc/ QuickCam Third-Party Drivers http://www.crynwr.com/qcpc/re.html Some Reverse Engineering - http://cse.unl.edu/~cluening/gqcam/ v4l client + http://www.wirelesscouch.net/software/gqcam/ v4l client http://phobos.illtel.denver.co.us/pub/qcread/ doesn't use v4l ftp://ftp.cs.unm.edu/pub/chris/quickcam/ Has lots of drivers http://www.cs.duke.edu/~reynolds/quickcam/ Has lots of information diff --git a/Documentation/video4linux/README.cpia b/Documentation/video4linux/README.cpia index 19cd3bf2498..8a747fee661 100644 --- a/Documentation/video4linux/README.cpia +++ b/Documentation/video4linux/README.cpia @@ -185,7 +185,7 @@ THANKS (in no particular order): --------------------------------------------------------------------------- REFERENCES - 1. http://www.risc.uni-linz.ac.at/people/ppregler + 1. http://www.risc.uni-linz.ac.at/ mailto:Peter_Pregler@email.com 2. see the file COPYING in the top directory of the kernel tree 3. http://webcam.sourceforge.net/ diff --git a/Documentation/video4linux/README.ivtv b/Documentation/video4linux/README.ivtv index 73df22c40bf..42b06686eb7 100644 --- a/Documentation/video4linux/README.ivtv +++ b/Documentation/video4linux/README.ivtv @@ -10,7 +10,7 @@ Hauppauge PVR-350. NOTE: this driver requires the latest encoder firmware (version 2.06.039, size 376836 bytes). Get the firmware from here: -http://dl.ivtvdriver.org/ivtv/firmware/firmware.tar.gz +http://dl.ivtvdriver.org/ivtv/firmware/ NOTE: 'normal' TV applications do not work with this driver, you need an application that can handle MPEG input such as mplayer, xine, MythTV, diff --git a/Documentation/video4linux/Zoran b/Documentation/video4linux/Zoran index 0e89e767629..00e3f926781 100644 --- a/Documentation/video4linux/Zoran +++ b/Documentation/video4linux/Zoran @@ -174,7 +174,7 @@ and is used in Argentinia, Uruguay, an a few others We do not talk about how the audio is broadcast ! A rather good sites about the TV standards are: -http://www.sony.jp/ServiceArea/Voltage_map/ +http://www.sony.jp/support/ http://info.electronicwerkstatt.de/bereiche/fernsehtechnik/frequenzen_und_normen/Fernsehnormen/ and http://www.cabl.com/restaurant/channel.html @@ -330,7 +330,7 @@ These extensions are known as the v4l/mjpeg extensions. See zoran.h for details (structs/ioctls). Information - video4linux: -http://roadrunner.swansea.linux.org.uk/v4lapi.shtml +http://linux.bytesex.org/v4l2/API.html Documentation/video4linux/API.html /usr/include/linux/videodev.h @@ -390,7 +390,7 @@ BUZIOC_G_STATUS Get the status of the input lines (video source connected/norm). For programming example, please, look at lavrec.c and lavplay.c code in -lavtools-1.2p2 package (URL: http://www.cicese.mx/~mirsev/DC10plus/) +lavtools-1.2p2 package (URL: http://www.cicese.mx/) and the 'examples' directory in the original Buz driver distribution. Additional notes for software developers: diff --git a/Documentation/video4linux/bttv/Cards b/Documentation/video4linux/bttv/Cards index d3389655ad9..12217fc4972 100644 --- a/Documentation/video4linux/bttv/Cards +++ b/Documentation/video4linux/bttv/Cards @@ -802,7 +802,7 @@ Kworld (www.kworld.com.tw) -JTT/ Justy Corp.http://www.justy.co.jp/ (www.jtt.com.jp website down) +JTT/ Justy Corp.(http://www.jtt.ne.jp/) --------------------------------------------------------------------- JTT-02 (JTT TV) "TV watchmate pro" (bt848) @@ -828,7 +828,7 @@ Eline www.eline-net.com/ Eline Vision TVMaster / TVMaster FM (ELV-TVM/ ELV-TVM-FM) = LR26 (bt878) Eline Vision TVMaster-2000 (ELV-TVM-2000, ELV-TVM-2000-FM)= LR138 (saa713x) -Spirit http://www.spiritmodems.com.au/ +Spirit ------ Spirit TV Tuner/Video Capture Card (bt848) @@ -959,6 +959,6 @@ Asus www.asuscom.com Hoontech -------- -http://www.hoontech.com/korean/download/down_driver_list03.html +http://www.hoontech.de/ HART Vision 848 (H-ART Vision 848) HART Vision 878 (H-Art Vision 878) diff --git a/Documentation/video4linux/bttv/MAKEDEV b/Documentation/video4linux/bttv/MAKEDEV index 6c29ba43b6c..093c0cd1804 100644 --- a/Documentation/video4linux/bttv/MAKEDEV +++ b/Documentation/video4linux/bttv/MAKEDEV @@ -14,12 +14,11 @@ function makedev () { ln -s /dev/${1}0 /dev/$1 } -# see http://roadrunner.swansea.uk.linux.org/v4lapi.shtml +# see http://linux.bytesex.org/v4l2/API.html echo "*** new device names ***" makedev video 0 makedev radio 64 -makedev vtx 192 makedev vbi 224 #echo "*** old device names (for compatibility only) ***" diff --git a/Documentation/video4linux/bttv/Specs b/Documentation/video4linux/bttv/Specs index 79b9e576fe7..f32466cdae0 100644 --- a/Documentation/video4linux/bttv/Specs +++ b/Documentation/video4linux/bttv/Specs @@ -1,3 +1,3 @@ Philips http://www.Semiconductors.COM/pip/ -Conexant http://www.conexant.com/techinfo/default.asp -Micronas http://www.micronas.de/pages/product_documentation/index.html +Conexant http://www.conexant.com/ +Micronas http://www.micronas.com/en/home/index.html diff --git a/Documentation/video4linux/cx88/hauppauge-wintv-cx88-ir.txt b/Documentation/video4linux/cx88/hauppauge-wintv-cx88-ir.txt index faccee68f60..f4329a38878 100644 --- a/Documentation/video4linux/cx88/hauppauge-wintv-cx88-ir.txt +++ b/Documentation/video4linux/cx88/hauppauge-wintv-cx88-ir.txt @@ -44,7 +44,7 @@ http://www.atmel.com/dyn/resources/prod_documents/doc2817.pdf This data sheet (google search) seems to have a lovely description of the RC5 basics -http://users.pandora.be/nenya/electronics/rc5/ and more data +http://www.nenya.be/beor/electronics/rc5.htm and more data http://www.ee.washington.edu/circuit_archive/text/ir_decode.txt and even a reference to how to decode a bi-phase data stream. diff --git a/Documentation/video4linux/gspca.txt b/Documentation/video4linux/gspca.txt index f13eb036c43..6a562eeeb4c 100644 --- a/Documentation/video4linux/gspca.txt +++ b/Documentation/video4linux/gspca.txt @@ -29,8 +29,12 @@ zc3xx 041e:4029 Creative WebCam Vista Pro zc3xx 041e:4034 Creative Instant P0620 zc3xx 041e:4035 Creative Instant P0620D zc3xx 041e:4036 Creative Live ! +sq930x 041e:4038 Creative Joy-IT zc3xx 041e:403a Creative Nx Pro 2 spca561 041e:403b Creative Webcam Vista (VF0010) +sq930x 041e:403c Creative Live! Ultra +sq930x 041e:403d Creative Live! Ultra for Notebooks +sq930x 041e:4041 Creative Live! Motion zc3xx 041e:4051 Creative Live!Cam Notebook Pro (VF0250) ov519 041e:4052 Creative Live! VISTA IM zc3xx 041e:4053 Creative Live!Cam Video IM @@ -138,6 +142,7 @@ finepix 04cb:013d Fujifilm FinePix unknown model finepix 04cb:013f Fujifilm FinePix F420 sunplus 04f1:1001 JVC GC A50 spca561 04fc:0561 Flexcam 100 +spca1528 04fc:1528 Sunplus MD80 clone sunplus 04fc:500c Sunplus CA500C sunplus 04fc:504a Aiptek Mini PenCam 1.3 sunplus 04fc:504b Maxell MaxPocket LE 1.3 @@ -253,6 +258,7 @@ pac7302 093a:2620 Apollo AC-905 pac7302 093a:2621 PAC731x pac7302 093a:2622 Genius Eye 312 pac7302 093a:2624 PAC7302 +pac7302 093a:2625 Genius iSlim 310 pac7302 093a:2626 Labtec 2200 pac7302 093a:2628 Genius iLook 300 pac7302 093a:2629 Genious iSlim 300 @@ -296,12 +302,14 @@ sonixj 0c45:60fb Surfer NoName sonixj 0c45:60fc LG-LIC300 sonixj 0c45:60fe Microdia Audio sonixj 0c45:6100 PC Camera (SN9C128) +sonixj 0c45:6102 PC Camera (SN9C128) sonixj 0c45:610a PC Camera (SN9C128) sonixj 0c45:610b PC Camera (SN9C128) sonixj 0c45:610c PC Camera (SN9C128) sonixj 0c45:610e PC Camera (SN9C128) sonixj 0c45:6128 Microdia/Sonix SNP325 sonixj 0c45:612a Avant Camera +sonixj 0c45:612b Speed-Link REFLECT2 sonixj 0c45:612c Typhoon Rasy Cam 1.3MPix sonixj 0c45:6130 Sonix Pccam sonixj 0c45:6138 Sn9c120 Mo4000 @@ -362,6 +370,8 @@ sq905c 2770:9052 Disney pix micro 2 (VGA) sq905c 2770:905c All 11 known cameras with this ID sq905 2770:9120 All 24 known cameras with this ID sq905c 2770:913d All 4 known cameras with this ID +sq930x 2770:930b Sweex Motion Tracking / I-Tec iCam Tracer +sq930x 2770:930c Trust WB-3500T / NSG Robbie 2.0 spca500 2899:012c Toptro Industrial ov519 8020:ef04 ov519 spca508 8086:0110 Intel Easy PC Camera diff --git a/Documentation/video4linux/hauppauge-wintv-cx88-ir.txt b/Documentation/video4linux/hauppauge-wintv-cx88-ir.txt index faccee68f60..a2fd363c40c 100644 --- a/Documentation/video4linux/hauppauge-wintv-cx88-ir.txt +++ b/Documentation/video4linux/hauppauge-wintv-cx88-ir.txt @@ -44,7 +44,7 @@ http://www.atmel.com/dyn/resources/prod_documents/doc2817.pdf This data sheet (google search) seems to have a lovely description of the RC5 basics -http://users.pandora.be/nenya/electronics/rc5/ and more data +http://www.nenya.be/beor/electronics/rc5.htm and more data http://www.ee.washington.edu/circuit_archive/text/ir_decode.txt and even a reference to how to decode a bi-phase data stream. diff --git a/Documentation/video4linux/ibmcam.txt b/Documentation/video4linux/ibmcam.txt index 397a94eb77b..a51055211e6 100644 --- a/Documentation/video4linux/ibmcam.txt +++ b/Documentation/video4linux/ibmcam.txt @@ -27,9 +27,8 @@ SUPPORTED CAMERAS: Xirlink "C-It" camera, also known as "IBM PC Camera". The device uses proprietary ASIC (and compression method); -it is manufactured by Xirlink. See http://www.xirlink.com/ -(renamed to http://www.veo.com), http://www.ibmpccamera.com, -or http://www.c-itnow.com/ for details and pictures. +it is manufactured by Xirlink. See http://xirlinkwebcam.sourceforge.net, +http://www.ibmpccamera.com, or http://www.c-itnow.com/ for details and pictures. This very chipset ("X Chip", as marked at the factory) is used in several other cameras, and they are supported diff --git a/Documentation/video4linux/se401.txt b/Documentation/video4linux/se401.txt index 7b9d1c960a1..bd6526ec8dd 100644 --- a/Documentation/video4linux/se401.txt +++ b/Documentation/video4linux/se401.txt @@ -49,6 +49,6 @@ order to increase the throughput (and thus framerate). HELP: The latest info on this driver can be found at: -http://www.chello.nl/~j.vreeken/se401/ +http://members.chello.nl/~j.vreeken/se401/ And questions to me can be send to: pe1rxq@amsat.org diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt new file mode 100644 index 00000000000..8773778d23f --- /dev/null +++ b/Documentation/video4linux/v4l2-controls.txt @@ -0,0 +1,648 @@ +Introduction +============ + +The V4L2 control API seems simple enough, but quickly becomes very hard to +implement correctly in drivers. But much of the code needed to handle controls +is actually not driver specific and can be moved to the V4L core framework. + +After all, the only part that a driver developer is interested in is: + +1) How do I add a control? +2) How do I set the control's value? (i.e. s_ctrl) + +And occasionally: + +3) How do I get the control's value? (i.e. g_volatile_ctrl) +4) How do I validate the user's proposed control value? (i.e. try_ctrl) + +All the rest is something that can be done centrally. + +The control framework was created in order to implement all the rules of the +V4L2 specification with respect to controls in a central place. And to make +life as easy as possible for the driver developer. + +Note that the control framework relies on the presence of a struct v4l2_device +for V4L2 drivers and struct v4l2_subdev for sub-device drivers. + + +Objects in the framework +======================== + +There are two main objects: + +The v4l2_ctrl object describes the control properties and keeps track of the +control's value (both the current value and the proposed new value). + +v4l2_ctrl_handler is the object that keeps track of controls. It maintains a +list of v4l2_ctrl objects that it owns and another list of references to +controls, possibly to controls owned by other handlers. + + +Basic usage for V4L2 and sub-device drivers +=========================================== + +1) Prepare the driver: + +1.1) Add the handler to your driver's top-level struct: + + struct foo_dev { + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; + + struct foo_dev *foo; + +1.2) Initialize the handler: + + v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls); + + The second argument is a hint telling the function how many controls this + handler is expected to handle. It will allocate a hashtable based on this + information. It is a hint only. + +1.3) Hook the control handler into the driver: + +1.3.1) For V4L2 drivers do this: + + struct foo_dev { + ... + struct v4l2_device v4l2_dev; + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; + + foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler; + + Where foo->v4l2_dev is of type struct v4l2_device. + + Finally, remove all control functions from your v4l2_ioctl_ops: + vidioc_queryctrl, vidioc_querymenu, vidioc_g_ctrl, vidioc_s_ctrl, + vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls. + Those are now no longer needed. + +1.3.2) For sub-device drivers do this: + + struct foo_dev { + ... + struct v4l2_subdev sd; + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; + + foo->sd.ctrl_handler = &foo->ctrl_handler; + + Where foo->sd is of type struct v4l2_subdev. + + And set all core control ops in your struct v4l2_subdev_core_ops to these + helpers: + + .queryctrl = v4l2_subdev_queryctrl, + .querymenu = v4l2_subdev_querymenu, + .g_ctrl = v4l2_subdev_g_ctrl, + .s_ctrl = v4l2_subdev_s_ctrl, + .g_ext_ctrls = v4l2_subdev_g_ext_ctrls, + .try_ext_ctrls = v4l2_subdev_try_ext_ctrls, + .s_ext_ctrls = v4l2_subdev_s_ext_ctrls, + + Note: this is a temporary solution only. Once all V4L2 drivers that depend + on subdev drivers are converted to the control framework these helpers will + no longer be needed. + +1.4) Clean up the handler at the end: + + v4l2_ctrl_handler_free(&foo->ctrl_handler); + + +2) Add controls: + +You add non-menu controls by calling v4l2_ctrl_new_std: + + struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl, + const struct v4l2_ctrl_ops *ops, + u32 id, s32 min, s32 max, u32 step, s32 def); + +Menu controls are added by calling v4l2_ctrl_new_std_menu: + + struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl, + const struct v4l2_ctrl_ops *ops, + u32 id, s32 max, s32 skip_mask, s32 def); + +These functions are typically called right after the v4l2_ctrl_handler_init: + + v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls); + v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_BRIGHTNESS, 0, 255, 1, 128); + v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_CONTRAST, 0, 255, 1, 128); + v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_POWER_LINE_FREQUENCY, + V4L2_CID_POWER_LINE_FREQUENCY_60HZ, 0, + V4L2_CID_POWER_LINE_FREQUENCY_DISABLED); + ... + if (foo->ctrl_handler.error) { + int err = foo->ctrl_handler.error; + + v4l2_ctrl_handler_free(&foo->ctrl_handler); + return err; + } + +The v4l2_ctrl_new_std function returns the v4l2_ctrl pointer to the new +control, but if you do not need to access the pointer outside the control ops, +then there is no need to store it. + +The v4l2_ctrl_new_std function will fill in most fields based on the control +ID except for the min, max, step and default values. These are passed in the +last four arguments. These values are driver specific while control attributes +like type, name, flags are all global. The control's current value will be set +to the default value. + +The v4l2_ctrl_new_std_menu function is very similar but it is used for menu +controls. There is no min argument since that is always 0 for menu controls, +and instead of a step there is a skip_mask argument: if bit X is 1, then menu +item X is skipped. + +Note that if something fails, the function will return NULL or an error and +set ctrl_handler->error to the error code. If ctrl_handler->error was already +set, then it will just return and do nothing. This is also true for +v4l2_ctrl_handler_init if it cannot allocate the internal data structure. + +This makes it easy to init the handler and just add all controls and only check +the error code at the end. Saves a lot of repetitive error checking. + +It is recommended to add controls in ascending control ID order: it will be +a bit faster that way. + +3) Optionally force initial control setup: + + v4l2_ctrl_handler_setup(&foo->ctrl_handler); + +This will call s_ctrl for all controls unconditionally. Effectively this +initializes the hardware to the default control values. It is recommended +that you do this as this ensures that both the internal data structures and +the hardware are in sync. + +4) Finally: implement the v4l2_ctrl_ops + + static const struct v4l2_ctrl_ops foo_ctrl_ops = { + .s_ctrl = foo_s_ctrl, + }; + +Usually all you need is s_ctrl: + + static int foo_s_ctrl(struct v4l2_ctrl *ctrl) + { + struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler); + + switch (ctrl->id) { + case V4L2_CID_BRIGHTNESS: + write_reg(0x123, ctrl->val); + break; + case V4L2_CID_CONTRAST: + write_reg(0x456, ctrl->val); + break; + } + return 0; + } + +The control ops are called with the v4l2_ctrl pointer as argument. +The new control value has already been validated, so all you need to do is +to actually update the hardware registers. + +You're done! And this is sufficient for most of the drivers we have. No need +to do any validation of control values, or implement QUERYCTRL/QUERYMENU. And +G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported. + + +============================================================================== + +The remainder of this document deals with more advanced topics and scenarios. +In practice the basic usage as described above is sufficient for most drivers. + +=============================================================================== + + +Inheriting Controls +=================== + +When a sub-device is registered with a V4L2 driver by calling +v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev +and v4l2_device are set, then the controls of the subdev will become +automatically available in the V4L2 driver as well. If the subdev driver +contains controls that already exist in the V4L2 driver, then those will be +skipped (so a V4L2 driver can always override a subdev control). + +What happens here is that v4l2_device_register_subdev() calls +v4l2_ctrl_add_handler() adding the controls of the subdev to the controls +of v4l2_device. + + +Accessing Control Values +======================== + +The v4l2_ctrl struct contains these two unions: + + /* The current control value. */ + union { + s32 val; + s64 val64; + char *string; + } cur; + + /* The new control value. */ + union { + s32 val; + s64 val64; + char *string; + }; + +Within the control ops you can freely use these. The val and val64 speak for +themselves. The string pointers point to character buffers of length +ctrl->maximum + 1, and are always 0-terminated. + +In most cases 'cur' contains the current cached control value. When you create +a new control this value is made identical to the default value. After calling +v4l2_ctrl_handler_setup() this value is passed to the hardware. It is generally +a good idea to call this function. + +Whenever a new value is set that new value is automatically cached. This means +that most drivers do not need to implement the g_volatile_ctrl() op. The +exception is for controls that return a volatile register such as a signal +strength read-out that changes continuously. In that case you will need to +implement g_volatile_ctrl like this: + + static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl) + { + switch (ctrl->id) { + case V4L2_CID_BRIGHTNESS: + ctrl->cur.val = read_reg(0x123); + break; + } + } + +The 'new value' union is not used in g_volatile_ctrl. In general controls +that need to implement g_volatile_ctrl are read-only controls. + +To mark a control as volatile you have to set the is_volatile flag: + + ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...); + if (ctrl) + ctrl->is_volatile = 1; + +For try/s_ctrl the new values (i.e. as passed by the user) are filled in and +you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union +contains the current value, which you can use (but not change!) as well. + +If s_ctrl returns 0 (OK), then the control framework will copy the new final +values to the 'cur' union. + +While in g_volatile/s/try_ctrl you can access the value of all controls owned +by the same handler since the handler's lock is held. If you need to access +the value of controls owned by other handlers, then you have to be very careful +not to introduce deadlocks. + +Outside of the control ops you have to go through to helper functions to get +or set a single control value safely in your driver: + + s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl); + int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val); + +These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls +do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that +will result in a deadlock since these helpers lock the handler as well. + +You can also take the handler lock yourself: + + mutex_lock(&state->ctrl_handler.lock); + printk(KERN_INFO "String value is '%s'\n", ctrl1->cur.string); + printk(KERN_INFO "Integer value is '%s'\n", ctrl2->cur.val); + mutex_unlock(&state->ctrl_handler.lock); + + +Menu Controls +============= + +The v4l2_ctrl struct contains this union: + + union { + u32 step; + u32 menu_skip_mask; + }; + +For menu controls menu_skip_mask is used. What it does is that it allows you +to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU +implementation where you can return -EINVAL if a certain menu item is not +present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for +menu controls. + +A good example is the MPEG Audio Layer II Bitrate menu control where the +menu is a list of standardized possible bitrates. But in practice hardware +implementations will only support a subset of those. By setting the skip +mask you can tell the framework which menu items should be skipped. Setting +it to 0 means that all menu items are supported. + +You set this mask either through the v4l2_ctrl_config struct for a custom +control, or by calling v4l2_ctrl_new_std_menu(). + + +Custom Controls +=============== + +Driver specific controls can be created using v4l2_ctrl_new_custom(): + + static const struct v4l2_ctrl_config ctrl_filter = { + .ops = &ctrl_custom_ops, + .id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER, + .name = "Spatial Filter", + .type = V4L2_CTRL_TYPE_INTEGER, + .flags = V4L2_CTRL_FLAG_SLIDER, + .max = 15, + .step = 1, + }; + + ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL); + +The last argument is the priv pointer which can be set to driver-specific +private data. + +The v4l2_ctrl_config struct also has fields to set the is_private and is_volatile +flags. + +If the name field is not set, then the framework will assume this is a standard +control and will fill in the name, type and flags fields accordingly. + + +Active and Grabbed Controls +=========================== + +If you get more complex relationships between controls, then you may have to +activate and deactivate controls. For example, if the Chroma AGC control is +on, then the Chroma Gain control is inactive. That is, you may set it, but +the value will not be used by the hardware as long as the automatic gain +control is on. Typically user interfaces can disable such input fields. + +You can set the 'active' status using v4l2_ctrl_activate(). By default all +controls are active. Note that the framework does not check for this flag. +It is meant purely for GUIs. The function is typically called from within +s_ctrl. + +The other flag is the 'grabbed' flag. A grabbed control means that you cannot +change it because it is in use by some resource. Typical examples are MPEG +bitrate controls that cannot be changed while capturing is in progress. + +If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework +will return -EBUSY if an attempt is made to set this control. The +v4l2_ctrl_grab() function is typically called from the driver when it +starts or stops streaming. + + +Control Clusters +================ + +By default all controls are independent from the others. But in more +complex scenarios you can get dependencies from one control to another. +In that case you need to 'cluster' them: + + struct foo { + struct v4l2_ctrl_handler ctrl_handler; +#define AUDIO_CL_VOLUME (0) +#define AUDIO_CL_MUTE (1) + struct v4l2_ctrl *audio_cluster[2]; + ... + }; + + state->audio_cluster[AUDIO_CL_VOLUME] = + v4l2_ctrl_new_std(&state->ctrl_handler, ...); + state->audio_cluster[AUDIO_CL_MUTE] = + v4l2_ctrl_new_std(&state->ctrl_handler, ...); + v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster); + +From now on whenever one or more of the controls belonging to the same +cluster is set (or 'gotten', or 'tried'), only the control ops of the first +control ('volume' in this example) is called. You effectively create a new +composite control. Similar to how a 'struct' works in C. + +So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set +all two controls belonging to the audio_cluster: + + static int foo_s_ctrl(struct v4l2_ctrl *ctrl) + { + struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler); + + switch (ctrl->id) { + case V4L2_CID_AUDIO_VOLUME: { + struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE]; + + write_reg(0x123, mute->val ? 0 : ctrl->val); + break; + } + case V4L2_CID_CONTRAST: + write_reg(0x456, ctrl->val); + break; + } + return 0; + } + +In the example above the following are equivalent for the VOLUME case: + + ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME] + ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE] + +Note that controls in a cluster may be NULL. For example, if for some +reason mute was never added (because the hardware doesn't support that +particular feature), then mute will be NULL. So in that case we have a +cluster of 2 controls, of which only 1 is actually instantiated. The +only restriction is that the first control of the cluster must always be +present, since that is the 'master' control of the cluster. The master +control is the one that identifies the cluster and that provides the +pointer to the v4l2_ctrl_ops struct that is used for that cluster. + +Obviously, all controls in the cluster array must be initialized to either +a valid control or to NULL. + + +VIDIOC_LOG_STATUS Support +========================= + +This ioctl allow you to dump the current status of a driver to the kernel log. +The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the +value of the controls owned by the given handler to the log. You can supply a +prefix as well. If the prefix didn't end with a space, then ': ' will be added +for you. + + +Different Handlers for Different Video Nodes +============================================ + +Usually the V4L2 driver has just one control handler that is global for +all video nodes. But you can also specify different control handlers for +different video nodes. You can do that by manually setting the ctrl_handler +field of struct video_device. + +That is no problem if there are no subdevs involved but if there are, then +you need to block the automatic merging of subdev controls to the global +control handler. You do that by simply setting the ctrl_handler field in +struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer +merge subdev controls. + +After each subdev was added, you will then have to call v4l2_ctrl_add_handler +manually to add the subdev's control handler (sd->ctrl_handler) to the desired +control handler. This control handler may be specific to the video_device or +for a subset of video_device's. For example: the radio device nodes only have +audio controls, while the video and vbi device nodes share the same control +handler for the audio and video controls. + +If you want to have one handler (e.g. for a radio device node) have a subset +of another handler (e.g. for a video device node), then you should first add +the controls to the first handler, add the other controls to the second +handler and finally add the first handler to the second. For example: + + v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...); + v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...); + v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler); + +Or you can add specific controls to a handler: + + volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...); + v4l2_ctrl_add_ctrl(&radio_ctrl_handler, volume); + +What you should not do is make two identical controls for two handlers. +For example: + + v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...); + +This would be bad since muting the radio would not change the video mute +control. The rule is to have one control for each hardware 'knob' that you +can twiddle. + + +Finding Controls +================ + +Normally you have created the controls yourself and you can store the struct +v4l2_ctrl pointer into your own struct. + +But sometimes you need to find a control from another handler that you do +not own. For example, if you have to find a volume control from a subdev. + +You can do that by calling v4l2_ctrl_find: + + struct v4l2_ctrl *volume; + + volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME); + +Since v4l2_ctrl_find will lock the handler you have to be careful where you +use it. For example, this is not a good idea: + + struct v4l2_ctrl_handler ctrl_handler; + + v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...); + v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...); + +...and in video_ops.s_ctrl: + + case V4L2_CID_BRIGHTNESS: + contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST); + ... + +When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so +attempting to find another control from the same handler will deadlock. + +It is recommended not to use this function from inside the control ops. + + +Inheriting Controls +=================== + +When one control handler is added to another using v4l2_ctrl_add_handler, then +by default all controls from one are merged to the other. But a subdev might +have low-level controls that make sense for some advanced embedded system, but +not when it is used in consumer-level hardware. In that case you want to keep +those low-level controls local to the subdev. You can do this by simply +setting the 'is_private' flag of the control to 1: + + static const struct v4l2_ctrl_config ctrl_private = { + .ops = &ctrl_custom_ops, + .id = V4L2_CID_..., + .name = "Some Private Control", + .type = V4L2_CTRL_TYPE_INTEGER, + .max = 15, + .step = 1, + .is_private = 1, + }; + + ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL); + +These controls will now be skipped when v4l2_ctrl_add_handler is called. + + +V4L2_CTRL_TYPE_CTRL_CLASS Controls +================================== + +Controls of this type can be used by GUIs to get the name of the control class. +A fully featured GUI can make a dialog with multiple tabs with each tab +containing the controls belonging to a particular control class. The name of +each tab can be found by querying a special control with ID <control class | 1>. + +Drivers do not have to care about this. The framework will automatically add +a control of this type whenever the first control belonging to a new control +class is added. + + +Differences from the Spec +========================= + +There are a few places where the framework acts slightly differently from the +V4L2 Specification. Those differences are described in this section. We will +have to see whether we need to adjust the spec or not. + +1) It is no longer required to have all controls contained in a +v4l2_ext_control array be from the same control class. The framework will be +able to handle any type of control in the array. You need to set ctrl_class +to 0 in order to enable this. If ctrl_class is non-zero, then it will still +check that all controls belong to that control class. + +If you set ctrl_class to 0 and count to 0, then it will only return an error +if there are no controls at all. + +2) Clarified the way error_idx works. For get and set it will be equal to +count if nothing was done yet. If it is less than count then only the controls +up to error_idx-1 were successfully applied. + +3) When attempting to read a button control the framework will return -EACCES +instead of -EINVAL as stated in the spec. It seems to make more sense since +button controls are write-only controls. + +4) Attempting to write to a read-only control will return -EACCES instead of +-EINVAL as the spec says. + +5) The spec does not mention what should happen when you try to set/get a +control class controls. ivtv currently returns -EINVAL (indicating that the +control ID does not exist) while the framework will return -EACCES, which +makes more sense. + + +Proposals for Extensions +======================== + +Some ideas for future extensions to the spec: + +1) Add a V4L2_CTRL_FLAG_HEX to have values shown as hexadecimal instead of +decimal. Useful for e.g. video_mute_yuv. + +2) It is possible to mark in the controls array which controls have been +successfully written and which failed by for example adding a bit to the +control ID. Not sure if it is worth the effort, though. + +3) Trying to set volatile inactive controls should result in -EACCESS. + +4) Add a new flag to mark volatile controls. Any application that wants +to store the state of the controls can then skip volatile inactive controls. +Currently it is not possible to detect such controls. diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index e831aaca66f..f22f35c271f 100644 --- a/Documentation/video4linux/v4l2-framework.txt +++ b/Documentation/video4linux/v4l2-framework.txt @@ -44,8 +44,8 @@ All drivers have the following structure: 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. +3) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX and /dev/radioX) + and keeping track of device-node specific data. 4) Filehandle-specific structs containing per-filehandle data; @@ -192,6 +192,11 @@ 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. +Bridges might also need to store per-subdev private data, such as a pointer to +bridge-specific per-subdev private data. The v4l2_subdev structure provides +host private data for that purpose that can be accessed with +v4l2_get_subdev_hostdata() and v4l2_set_subdev_hostdata(). + 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. @@ -448,6 +453,10 @@ You should also set these fields: - 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. +- lock: leave to NULL if you want to do all the locking in the driver. + Otherwise you give it a pointer to a struct mutex_lock and before any + of the v4l2_file_operations is called this lock will be taken by the + core and released afterwards. - parent: you only set this if v4l2_device was registered with NULL as the parent device struct. This only happens in cases where one hardware device has multiple PCI devices that all share the same v4l2_device core. @@ -464,6 +473,22 @@ If you use v4l2_ioctl_ops, then you should set either .unlocked_ioctl or The v4l2_file_operations struct is a subset of file_operations. The main difference is that the inode argument is omitted since it is never used. +v4l2_file_operations and locking +-------------------------------- + +You can set a pointer to a mutex_lock in struct video_device. Usually this +will be either a top-level mutex or a mutex per device node. If you want +finer-grained locking then you have to set it to NULL and do you own locking. + +If a lock is specified then all file operations will be serialized on that +lock. If you use videobuf then you must pass the same lock to the videobuf +queue initialize function: if videobuf has to wait for a frame to arrive, then +it will temporarily unlock the lock and relock it afterwards. If your driver +also waits in the code, then you should do the same to allow other processes +to access the device node while the first process is waiting for something. + +The implementation of a hotplug disconnect should also take the lock before +calling v4l2_device_disconnect. video_device registration ------------------------- @@ -483,7 +508,6 @@ 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 device node number used (i.e. the X in videoX). Normally you will pass -1 @@ -547,9 +571,8 @@ 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. So after the unregister all file operations will return -an error as well, except for the ioctl and unlocked_ioctl file operations: -those will still be passed on since some buffer ioctls may still be needed. +device nodes open. So after the unregister all file operations (except +release, of course) will return an error as well. 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. diff --git a/Documentation/video4linux/w9966.txt b/Documentation/video4linux/w9966.txt index 78a651254b8..855024525fd 100644 --- a/Documentation/video4linux/w9966.txt +++ b/Documentation/video4linux/w9966.txt @@ -24,7 +24,7 @@ where every two pixels take 4 bytes. In SDL (www.libsdl.org) this format is called VIDEO_PALETTE_YUV422 (16 bpp). A minimal test application (with source) is available from: - http://hem.fyristorg.com/mogul/w9966.html + http://www.slackwaresupport.com/howtos/Webcam-HOWTO The slow framerate is due to missing DMA ECP read support in the parport drivers. I might add working EPP support later. diff --git a/Documentation/vm/highmem.txt b/Documentation/vm/highmem.txt new file mode 100644 index 00000000000..4324d24ffac --- /dev/null +++ b/Documentation/vm/highmem.txt @@ -0,0 +1,162 @@ + + ==================== + HIGH MEMORY HANDLING + ==================== + +By: Peter Zijlstra <a.p.zijlstra@chello.nl> + +Contents: + + (*) What is high memory? + + (*) Temporary virtual mappings. + + (*) Using kmap_atomic. + + (*) Cost of temporary mappings. + + (*) i386 PAE. + + +==================== +WHAT IS HIGH MEMORY? +==================== + +High memory (highmem) is used when the size of physical memory approaches or +exceeds the maximum size of virtual memory. At that point it becomes +impossible for the kernel to keep all of the available physical memory mapped +at all times. This means the kernel needs to start using temporary mappings of +the pieces of physical memory that it wants to access. + +The part of (physical) memory not covered by a permanent mapping is what we +refer to as 'highmem'. There are various architecture dependent constraints on +where exactly that border lies. + +In the i386 arch, for example, we choose to map the kernel into every process's +VM space so that we don't have to pay the full TLB invalidation costs for +kernel entry/exit. This means the available virtual memory space (4GiB on +i386) has to be divided between user and kernel space. + +The traditional split for architectures using this approach is 3:1, 3GiB for +userspace and the top 1GiB for kernel space: + + +--------+ 0xffffffff + | Kernel | + +--------+ 0xc0000000 + | | + | User | + | | + +--------+ 0x00000000 + +This means that the kernel can at most map 1GiB of physical memory at any one +time, but because we need virtual address space for other things - including +temporary maps to access the rest of the physical memory - the actual direct +map will typically be less (usually around ~896MiB). + +Other architectures that have mm context tagged TLBs can have separate kernel +and user maps. Some hardware (like some ARMs), however, have limited virtual +space when they use mm context tags. + + +========================== +TEMPORARY VIRTUAL MAPPINGS +========================== + +The kernel contains several ways of creating temporary mappings: + + (*) vmap(). This can be used to make a long duration mapping of multiple + physical pages into a contiguous virtual space. It needs global + synchronization to unmap. + + (*) kmap(). This permits a short duration mapping of a single page. It needs + global synchronization, but is amortized somewhat. It is also prone to + deadlocks when using in a nested fashion, and so it is not recommended for + new code. + + (*) kmap_atomic(). This permits a very short duration mapping of a single + page. Since the mapping is restricted to the CPU that issued it, it + performs well, but the issuing task is therefore required to stay on that + CPU until it has finished, lest some other task displace its mappings. + + kmap_atomic() may also be used by interrupt contexts, since it is does not + sleep and the caller may not sleep until after kunmap_atomic() is called. + + It may be assumed that k[un]map_atomic() won't fail. + + +================= +USING KMAP_ATOMIC +================= + +When and where to use kmap_atomic() is straightforward. It is used when code +wants to access the contents of a page that might be allocated from high memory +(see __GFP_HIGHMEM), for example a page in the pagecache. The API has two +functions, and they can be used in a manner similar to the following: + + /* Find the page of interest. */ + struct page *page = find_get_page(mapping, offset); + + /* Gain access to the contents of that page. */ + void *vaddr = kmap_atomic(page); + + /* Do something to the contents of that page. */ + memset(vaddr, 0, PAGE_SIZE); + + /* Unmap that page. */ + kunmap_atomic(vaddr); + +Note that the kunmap_atomic() call takes the result of the kmap_atomic() call +not the argument. + +If you need to map two pages because you want to copy from one page to +another you need to keep the kmap_atomic calls strictly nested, like: + + vaddr1 = kmap_atomic(page1); + vaddr2 = kmap_atomic(page2); + + memcpy(vaddr1, vaddr2, PAGE_SIZE); + + kunmap_atomic(vaddr2); + kunmap_atomic(vaddr1); + + +========================== +COST OF TEMPORARY MAPPINGS +========================== + +The cost of creating temporary mappings can be quite high. The arch has to +manipulate the kernel's page tables, the data TLB and/or the MMU's registers. + +If CONFIG_HIGHMEM is not set, then the kernel will try and create a mapping +simply with a bit of arithmetic that will convert the page struct address into +a pointer to the page contents rather than juggling mappings about. In such a +case, the unmap operation may be a null operation. + +If CONFIG_MMU is not set, then there can be no temporary mappings and no +highmem. In such a case, the arithmetic approach will also be used. + + +======== +i386 PAE +======== + +The i386 arch, under some circumstances, will permit you to stick up to 64GiB +of RAM into your 32-bit machine. This has a number of consequences: + + (*) Linux needs a page-frame structure for each page in the system and the + pageframes need to live in the permanent mapping, which means: + + (*) you can have 896M/sizeof(struct page) page-frames at most; with struct + page being 32-bytes that would end up being something in the order of 112G + worth of pages; the kernel, however, needs to store more than just + page-frames in that memory... + + (*) PAE makes your page tables larger - which slows the system down as more + data has to be accessed to traverse in TLB fills and the like. One + advantage is that PAE has more PTE bits and can provide advanced features + like NX and PAT. + +The general recommendation is that you don't use more than 8GiB on a 32-bit +machine - although more might work for you and your workload, you're pretty +much on your own - don't expect kernel developers to really care much if things +come apart. diff --git a/Documentation/vm/numa_memory_policy.txt b/Documentation/vm/numa_memory_policy.txt index 6690fc34ef6..4e7da654342 100644 --- a/Documentation/vm/numa_memory_policy.txt +++ b/Documentation/vm/numa_memory_policy.txt @@ -424,7 +424,7 @@ a command line tool, numactl(8), exists that allows one to: + set the shared policy for a shared memory segment via mbind(2) -The numactl(8) tool is packages with the run-time version of the library +The numactl(8) tool is packaged with the run-time version of the library containing the memory policy system call wrappers. Some distributions package the headers and compile-time libraries in a separate development package. diff --git a/Documentation/vm/page-types.c b/Documentation/vm/page-types.c index 66e9358e214..cc96ee2666f 100644 --- a/Documentation/vm/page-types.c +++ b/Documentation/vm/page-types.c @@ -478,7 +478,7 @@ static void prepare_hwpoison_fd(void) } if (opt_unpoison && !hwpoison_forget_fd) { - sprintf(buf, "%s/renew-pfn", hwpoison_debug_fs); + sprintf(buf, "%s/unpoison-pfn", hwpoison_debug_fs); hwpoison_forget_fd = checked_open(buf, O_WRONLY); } } @@ -694,7 +694,7 @@ static void usage(void) #endif " -l|--list Show page details in ranges\n" " -L|--list-each Show page details one by one\n" -" -N|--no-summary Don't show summay info\n" +" -N|--no-summary Don't show summary info\n" " -X|--hwpoison hwpoison pages\n" " -x|--unpoison unpoison pages\n" " -h|--help Show this usage message\n" diff --git a/Documentation/w1/masters/ds2482 b/Documentation/w1/masters/ds2482 index 299b91c7609..56f8edace6a 100644 --- a/Documentation/w1/masters/ds2482 +++ b/Documentation/w1/masters/ds2482 @@ -6,8 +6,8 @@ Supported chips: Prefix: 'ds2482' Addresses scanned: None Datasheets: - http://pdfserv.maxim-ic.com/en/ds/DS2482-100-DS2482S-100.pdf - http://pdfserv.maxim-ic.com/en/ds/DS2482-800-DS2482S-800.pdf + http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf + http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf Author: Ben Gardner <bgardner@wabtec.com> diff --git a/Documentation/w1/masters/mxc-w1 b/Documentation/w1/masters/mxc-w1 index 97f6199a7f3..38be1ad6553 100644 --- a/Documentation/w1/masters/mxc-w1 +++ b/Documentation/w1/masters/mxc-w1 @@ -5,7 +5,8 @@ Supported chips: * Freescale MX27, MX31 and probably other i.MX SoCs Datasheets: http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1 - http://www.freescale.com/files/dsp/MCIMX27.pdf?fpsp=1 + http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE= + Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation Author: Originally based on Freescale code, prepared for mainline by Sascha Hauer <s.hauer@pengutronix.de> diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq index ca722e09b6a..884dc284b21 100644 --- a/Documentation/w1/masters/omap-hdq +++ b/Documentation/w1/masters/omap-hdq @@ -7,7 +7,7 @@ Supported chips: A useful link about HDQ basics: =============================== -http://focus.ti.com/lit/an/slua408/slua408.pdf +http://focus.ti.com/lit/an/slua408a/slua408a.pdf Description: ============ diff --git a/Documentation/workqueue.txt b/Documentation/workqueue.txt new file mode 100644 index 00000000000..996a27d9b8d --- /dev/null +++ b/Documentation/workqueue.txt @@ -0,0 +1,381 @@ + +Concurrency Managed Workqueue (cmwq) + +September, 2010 Tejun Heo <tj@kernel.org> + Florian Mickler <florian@mickler.org> + +CONTENTS + +1. Introduction +2. Why cmwq? +3. The Design +4. Application Programming Interface (API) +5. Example Execution Scenarios +6. Guidelines + + +1. Introduction + +There are many cases where an asynchronous process execution context +is needed and the workqueue (wq) API is the most commonly used +mechanism for such cases. + +When such an asynchronous execution context is needed, a work item +describing which function to execute is put on a queue. An +independent thread serves as the asynchronous execution context. The +queue is called workqueue and the thread is called worker. + +While there are work items on the workqueue the worker executes the +functions associated with the work items one after the other. When +there is no work item left on the workqueue the worker becomes idle. +When a new work item gets queued, the worker begins executing again. + + +2. Why cmwq? + +In the original wq implementation, a multi threaded (MT) wq had one +worker thread per CPU and a single threaded (ST) wq had one worker +thread system-wide. A single MT wq needed to keep around the same +number of workers as the number of CPUs. The kernel grew a lot of MT +wq users over the years and with the number of CPU cores continuously +rising, some systems saturated the default 32k PID space just booting +up. + +Although MT wq wasted a lot of resource, the level of concurrency +provided was unsatisfactory. The limitation was common to both ST and +MT wq albeit less severe on MT. Each wq maintained its own separate +worker pool. A MT wq could provide only one execution context per CPU +while a ST wq one for the whole system. Work items had to compete for +those very limited execution contexts leading to various problems +including proneness to deadlocks around the single execution context. + +The tension between the provided level of concurrency and resource +usage also forced its users to make unnecessary tradeoffs like libata +choosing to use ST wq for polling PIOs and accepting an unnecessary +limitation that no two polling PIOs can progress at the same time. As +MT wq don't provide much better concurrency, users which require +higher level of concurrency, like async or fscache, had to implement +their own thread pool. + +Concurrency Managed Workqueue (cmwq) is a reimplementation of wq with +focus on the following goals. + +* Maintain compatibility with the original workqueue API. + +* Use per-CPU unified worker pools shared by all wq to provide + flexible level of concurrency on demand without wasting a lot of + resource. + +* Automatically regulate worker pool and level of concurrency so that + the API users don't need to worry about such details. + + +3. The Design + +In order to ease the asynchronous execution of functions a new +abstraction, the work item, is introduced. + +A work item is a simple struct that holds a pointer to the function +that is to be executed asynchronously. Whenever a driver or subsystem +wants a function to be executed asynchronously it has to set up a work +item pointing to that function and queue that work item on a +workqueue. + +Special purpose threads, called worker threads, execute the functions +off of the queue, one after the other. If no work is queued, the +worker threads become idle. These worker threads are managed in so +called thread-pools. + +The cmwq design differentiates between the user-facing workqueues that +subsystems and drivers queue work items on and the backend mechanism +which manages thread-pool and processes the queued work items. + +The backend is called gcwq. There is one gcwq for each possible CPU +and one gcwq to serve work items queued on unbound workqueues. + +Subsystems and drivers can create and queue work items through special +workqueue API functions as they see fit. They can influence some +aspects of the way the work items are executed by setting flags on the +workqueue they are putting the work item on. These flags include +things like CPU locality, reentrancy, concurrency limits and more. To +get a detailed overview refer to the API description of +alloc_workqueue() below. + +When a work item is queued to a workqueue, the target gcwq is +determined according to the queue parameters and workqueue attributes +and appended on the shared worklist of the gcwq. For example, unless +specifically overridden, a work item of a bound workqueue will be +queued on the worklist of exactly that gcwq that is associated to the +CPU the issuer is running on. + +For any worker pool implementation, managing the concurrency level +(how many execution contexts are active) is an important issue. cmwq +tries to keep the concurrency at a minimal but sufficient level. +Minimal to save resources and sufficient in that the system is used at +its full capacity. + +Each gcwq bound to an actual CPU implements concurrency management by +hooking into the scheduler. The gcwq is notified whenever an active +worker wakes up or sleeps and keeps track of the number of the +currently runnable workers. Generally, work items are not expected to +hog a CPU and consume many cycles. That means maintaining just enough +concurrency to prevent work processing from stalling should be +optimal. As long as there are one or more runnable workers on the +CPU, the gcwq doesn't start execution of a new work, but, when the +last running worker goes to sleep, it immediately schedules a new +worker so that the CPU doesn't sit idle while there are pending work +items. This allows using a minimal number of workers without losing +execution bandwidth. + +Keeping idle workers around doesn't cost other than the memory space +for kthreads, so cmwq holds onto idle ones for a while before killing +them. + +For an unbound wq, the above concurrency management doesn't apply and +the gcwq for the pseudo unbound CPU tries to start executing all work +items as soon as possible. The responsibility of regulating +concurrency level is on the users. There is also a flag to mark a +bound wq to ignore the concurrency management. Please refer to the +API section for details. + +Forward progress guarantee relies on that workers can be created when +more execution contexts are necessary, which in turn is guaranteed +through the use of rescue workers. All work items which might be used +on code paths that handle memory reclaim are required to be queued on +wq's that have a rescue-worker reserved for execution under memory +pressure. Else it is possible that the thread-pool deadlocks waiting +for execution contexts to free up. + + +4. Application Programming Interface (API) + +alloc_workqueue() allocates a wq. The original create_*workqueue() +functions are deprecated and scheduled for removal. alloc_workqueue() +takes three arguments - @name, @flags and @max_active. @name is the +name of the wq and also used as the name of the rescuer thread if +there is one. + +A wq no longer manages execution resources but serves as a domain for +forward progress guarantee, flush and work item attributes. @flags +and @max_active control how work items are assigned execution +resources, scheduled and executed. + +@flags: + + WQ_NON_REENTRANT + + By default, a wq guarantees non-reentrance only on the same + CPU. A work item may not be executed concurrently on the same + CPU by multiple workers but is allowed to be executed + concurrently on multiple CPUs. This flag makes sure + non-reentrance is enforced across all CPUs. Work items queued + to a non-reentrant wq are guaranteed to be executed by at most + one worker system-wide at any given time. + + WQ_UNBOUND + + Work items queued to an unbound wq are served by a special + gcwq which hosts workers which are not bound to any specific + CPU. This makes the wq behave as a simple execution context + provider without concurrency management. The unbound gcwq + tries to start execution of work items as soon as possible. + Unbound wq sacrifices locality but is useful for the following + cases. + + * Wide fluctuation in the concurrency level requirement is + expected and using bound wq may end up creating large number + of mostly unused workers across different CPUs as the issuer + hops through different CPUs. + + * Long running CPU intensive workloads which can be better + managed by the system scheduler. + + WQ_FREEZEABLE + + A freezeable wq participates in the freeze phase of the system + suspend operations. Work items on the wq are drained and no + new work item starts execution until thawed. + + WQ_MEM_RECLAIM + + All wq which might be used in the memory reclaim paths _MUST_ + have this flag set. The wq is guaranteed to have at least one + execution context regardless of memory pressure. + + WQ_HIGHPRI + + Work items of a highpri wq are queued at the head of the + worklist of the target gcwq and start execution regardless of + the current concurrency level. In other words, highpri work + items will always start execution as soon as execution + resource is available. + + Ordering among highpri work items is preserved - a highpri + work item queued after another highpri work item will start + execution after the earlier highpri work item starts. + + Although highpri work items are not held back by other + runnable work items, they still contribute to the concurrency + level. Highpri work items in runnable state will prevent + non-highpri work items from starting execution. + + This flag is meaningless for unbound wq. + + WQ_CPU_INTENSIVE + + Work items of a CPU intensive wq do not contribute to the + concurrency level. In other words, runnable CPU intensive + work items will not prevent other work items from starting + execution. This is useful for bound work items which are + expected to hog CPU cycles so that their execution is + regulated by the system scheduler. + + Although CPU intensive work items don't contribute to the + concurrency level, start of their executions is still + regulated by the concurrency management and runnable + non-CPU-intensive work items can delay execution of CPU + intensive work items. + + This flag is meaningless for unbound wq. + + WQ_HIGHPRI | WQ_CPU_INTENSIVE + + This combination makes the wq avoid interaction with + concurrency management completely and behave as a simple + per-CPU execution context provider. Work items queued on a + highpri CPU-intensive wq start execution as soon as resources + are available and don't affect execution of other work items. + +@max_active: + +@max_active determines the maximum number of execution contexts per +CPU which can be assigned to the work items of a wq. For example, +with @max_active of 16, at most 16 work items of the wq can be +executing at the same time per CPU. + +Currently, for a bound wq, the maximum limit for @max_active is 512 +and the default value used when 0 is specified is 256. For an unbound +wq, the limit is higher of 512 and 4 * num_possible_cpus(). These +values are chosen sufficiently high such that they are not the +limiting factor while providing protection in runaway cases. + +The number of active work items of a wq is usually regulated by the +users of the wq, more specifically, by how many work items the users +may queue at the same time. Unless there is a specific need for +throttling the number of active work items, specifying '0' is +recommended. + +Some users depend on the strict execution ordering of ST wq. The +combination of @max_active of 1 and WQ_UNBOUND is used to achieve this +behavior. Work items on such wq are always queued to the unbound gcwq +and only one work item can be active at any given time thus achieving +the same ordering property as ST wq. + + +5. Example Execution Scenarios + +The following example execution scenarios try to illustrate how cmwq +behave under different configurations. + + Work items w0, w1, w2 are queued to a bound wq q0 on the same CPU. + w0 burns CPU for 5ms then sleeps for 10ms then burns CPU for 5ms + again before finishing. w1 and w2 burn CPU for 5ms then sleep for + 10ms. + +Ignoring all other tasks, works and processing overhead, and assuming +simple FIFO scheduling, the following is one highly simplified version +of possible sequences of events with the original wq. + + TIME IN MSECS EVENT + 0 w0 starts and burns CPU + 5 w0 sleeps + 15 w0 wakes up and burns CPU + 20 w0 finishes + 20 w1 starts and burns CPU + 25 w1 sleeps + 35 w1 wakes up and finishes + 35 w2 starts and burns CPU + 40 w2 sleeps + 50 w2 wakes up and finishes + +And with cmwq with @max_active >= 3, + + TIME IN MSECS EVENT + 0 w0 starts and burns CPU + 5 w0 sleeps + 5 w1 starts and burns CPU + 10 w1 sleeps + 10 w2 starts and burns CPU + 15 w2 sleeps + 15 w0 wakes up and burns CPU + 20 w0 finishes + 20 w1 wakes up and finishes + 25 w2 wakes up and finishes + +If @max_active == 2, + + TIME IN MSECS EVENT + 0 w0 starts and burns CPU + 5 w0 sleeps + 5 w1 starts and burns CPU + 10 w1 sleeps + 15 w0 wakes up and burns CPU + 20 w0 finishes + 20 w1 wakes up and finishes + 20 w2 starts and burns CPU + 25 w2 sleeps + 35 w2 wakes up and finishes + +Now, let's assume w1 and w2 are queued to a different wq q1 which has +WQ_HIGHPRI set, + + TIME IN MSECS EVENT + 0 w1 and w2 start and burn CPU + 5 w1 sleeps + 10 w2 sleeps + 10 w0 starts and burns CPU + 15 w0 sleeps + 15 w1 wakes up and finishes + 20 w2 wakes up and finishes + 25 w0 wakes up and burns CPU + 30 w0 finishes + +If q1 has WQ_CPU_INTENSIVE set, + + TIME IN MSECS EVENT + 0 w0 starts and burns CPU + 5 w0 sleeps + 5 w1 and w2 start and burn CPU + 10 w1 sleeps + 15 w2 sleeps + 15 w0 wakes up and burns CPU + 20 w0 finishes + 20 w1 wakes up and finishes + 25 w2 wakes up and finishes + + +6. Guidelines + +* Do not forget to use WQ_MEM_RECLAIM if a wq may process work items + which are used during memory reclaim. Each wq with WQ_MEM_RECLAIM + set has an execution context reserved for it. If there is + dependency among multiple work items used during memory reclaim, + they should be queued to separate wq each with WQ_MEM_RECLAIM. + +* Unless strict ordering is required, there is no need to use ST wq. + +* Unless there is a specific need, using 0 for @max_active is + recommended. In most use cases, concurrency level usually stays + well under the default limit. + +* A wq serves as a domain for forward progress guarantee + (WQ_MEM_RECLAIM, flush and work item attributes. Work items which + are not involved in memory reclaim and don't need to be flushed as a + part of a group of work items, and don't require any special + attribute, can use one of the system wq. There is no difference in + execution characteristics between using a dedicated wq and a system + wq. + +* Unless work items are expected to consume a huge amount of CPU + cycles, using a bound wq is usually beneficial due to the increased + level of locality in wq operations and work item execution. diff --git a/Documentation/x86/x86_64/kernel-stacks b/Documentation/x86/x86_64/kernel-stacks index 5ad65d51fb9..a01eec5d1d0 100644 --- a/Documentation/x86/x86_64/kernel-stacks +++ b/Documentation/x86/x86_64/kernel-stacks @@ -18,9 +18,9 @@ specialized stacks contain no useful data. The main CPU stacks are: Used for external hardware interrupts. If this is the first external hardware interrupt (i.e. not a nested hardware interrupt) then the kernel switches from the current task to the interrupt stack. Like - the split thread and interrupt stacks on i386 (with CONFIG_4KSTACKS), - this gives more room for kernel interrupt processing without having - to increase the size of every per thread stack. + the split thread and interrupt stacks on i386, this gives more room + for kernel interrupt processing without having to increase the size + of every per thread stack. The interrupt stack is also used when processing a softirq. diff --git a/Documentation/x86/zero-page.txt b/Documentation/x86/zero-page.txt index feb37e17701..cf5437deda8 100644 --- a/Documentation/x86/zero-page.txt +++ b/Documentation/x86/zero-page.txt @@ -18,6 +18,7 @@ Offset Proto Name Meaning 080/010 ALL hd0_info hd0 disk parameter, OBSOLETE!! 090/010 ALL hd1_info hd1 disk parameter, OBSOLETE!! 0A0/010 ALL sys_desc_table System description table (struct sys_desc_table) +0B0/010 ALL olpc_ofw_header OLPC's OpenFirmware CIF and friends 140/080 ALL edid_info Video mode setup (struct edid_info) 1C0/020 ALL efi_info EFI 32 information (struct efi_info) 1E0/004 ALL alk_mem_k Alternative mem check, in KB diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO index 3d80e8af36e..69160779e43 100644 --- a/Documentation/zh_CN/HOWTO +++ b/Documentation/zh_CN/HOWTO @@ -112,7 +112,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 @@ -168,7 +168,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 如果你想加入内核开发社区并协助完成一些任务，却找不到从哪里开始，可以访问 “Linux内核房管员”计划： - http://janitor.kernelnewbies.org/ + http://kernelnewbies.org/KernelJanitors 这是极佳的起点。它提供一个相对简单的任务列表，列出内核代码中需要被重新 整理或者改正的地方。通过和负责这个计划的开发者们一同工作，你会学到将补丁 集成进内核的基本原理。如果还没有决定下一步要做什么的话，你还可能会得到方 @@ -515,7 +515,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 这些事情有时候做起来很难。要在任何方面都做到完美可能需要好几年时间。这是 @@ -525,7 +525,7 @@ Linux内核社区并不喜欢一下接收大段的代码。修改需要被恰当 --------------- 感谢Paolo Ciarrocchi允许“开发流程”部分基于他所写的文章 -(http://linux.tar.bz/articles/2.6-development_process)，感谢Randy +(http://www.kerneltravel.net/newbie/2.6-development_process)，感谢Randy Dunlap和Gerrit Huizenga完善了应该说和不该说的列表。感谢Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian diff --git a/Documentation/zh_CN/SubmittingDrivers b/Documentation/zh_CN/SubmittingDrivers index 5f4815c63ec..c27b0f6cdd3 100644 --- a/Documentation/zh_CN/SubmittingDrivers +++ b/Documentation/zh_CN/SubmittingDrivers @@ -165,4 +165,4 @@ Linux USB项目： http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf 内核清洁工 (Kernel Janitor): - http://janitor.kernelnewbies.org/ + http://kernelnewbies.org/KernelJanitors diff --git a/Documentation/zh_CN/SubmittingPatches b/Documentation/zh_CN/SubmittingPatches index 985c92e20b7..9a1a6e1ed09 100644 --- a/Documentation/zh_CN/SubmittingPatches +++ b/Documentation/zh_CN/SubmittingPatches @@ -83,7 +83,7 @@ Quilt: http://savannah.nongnu.org/projects/quilt Andrew Morton 的补丁脚本: -http://www.zip.com.au/~akpm/linux/patches/ +http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz 作为这些脚本的替代，quilt 是值得推荐的补丁管理工具(看上面的链接)。 2)描述你的改动。 @@ -166,7 +166,7 @@ MAITAINERS 文件里的）发送一个手册页（man-pages）补丁，或者至 人拷贝，只要它是琐碎的） 任何文件的作者/维护者对该文件的改动（例如 patch monkey 在重传模式下） -URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/> +EMAIL: trivial@kernel.org (译注，关于“琐碎补丁”的一些说明：因为原文的这一部分写得比较简单，所以不得不 违例写一下译注。"trivial"这个英文单词的本意是“琐碎的，不重要的。”但是在这里 @@ -394,7 +394,7 @@ Static inline 函数相比宏来说，是好得多的选择。Static inline 函 ---------------- 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> diff --git a/Documentation/zh_CN/sparse.txt b/Documentation/zh_CN/sparse.txt index 75992a603ae..cc144e58151 100644 --- a/Documentation/zh_CN/sparse.txt +++ b/Documentation/zh_CN/sparse.txt @@ -22,7 +22,7 @@ Documentation/sparse.txt 的中文翻译 --------------------------------------------------------------------- Copyright 2004 Linus Torvalds -Copyright 2004 Pavel Machek <pavel@suse.cz> +Copyright 2004 Pavel Machek <pavel@ucw.cz> Copyright 2006 Bob Copeland <me@bobcopeland.com> 使用 sparse 工具做类型检查 |