diff options
Diffstat (limited to 'Documentation')
577 files changed, 25039 insertions, 6431 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 8dfc6708a257..c17cd4bb2290 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -206,8 +206,8 @@ laptops/ - directory with laptop related info and laptop driver documentation. ldm.txt - a brief description of LDM (Windows Dynamic Disks). -leds-class.txt - - documents LED handling under Linux. +leds/ + - directory with info about LED handling under Linux. local_ops.txt - semantics and behavior of local atomic operations. lockdep-design.txt @@ -328,8 +328,6 @@ sysrq.txt - info on the magic SysRq key. telephony/ - directory with info on telephony (e.g. voice over IP) support. -time_interpolators.txt - - info on time interpolators. uml/ - directory with information about User Mode Linux. unicode.txt @@ -346,8 +344,6 @@ vm/ - directory with info on the Linux vm code. volatile-considered-harmful.txt - Why the "volatile" type class should not be used -voyager.txt - - guide to running Linux on the Voyager architecture. w1/ - directory with documents regarding the 1-wire (w1) subsystem. watchdog/ diff --git a/Documentation/ABI/obsolete/dv1394 b/Documentation/ABI/obsolete/dv1394 deleted file mode 100644 index 2ee36864ca10..000000000000 --- 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/obsolete/proc-pid-oom_adj b/Documentation/ABI/obsolete/proc-pid-oom_adj new file mode 100644 index 000000000000..cf63f264ce0f --- /dev/null +++ b/Documentation/ABI/obsolete/proc-pid-oom_adj @@ -0,0 +1,22 @@ +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. diff --git a/Documentation/ABI/removed/dv1394 b/Documentation/ABI/removed/dv1394 new file mode 100644 index 000000000000..c2310b6676f4 --- /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 000000000000..490aa1efc4ae --- /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 1b629622d883..000000000000 --- 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 000000000000..c39c25aee77b --- /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/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight index 4d637e1c4ff7..70302f370e7e 100644 --- a/Documentation/ABI/stable/sysfs-class-backlight +++ b/Documentation/ABI/stable/sysfs-class-backlight @@ -34,3 +34,23 @@ Contact: Richard Purdie <rpurdie@rpsys.net> Description: Maximum brightness for <backlight>. Users: HAL + +What: /sys/class/backlight/<backlight>/type +Date: September 2010 +KernelVersion: 2.6.37 +Contact: Matthew Garrett <mjg@redhat.com> +Description: + The type of interface controlled by <backlight>. + "firmware": The driver uses a standard firmware interface + "platform": The driver uses a platform-specific interface + "raw": The driver controls hardware registers directly + + In the general case, when multiple backlight + interfaces are available for a single device, firmware + control should be preferred to platform control should + be preferred to raw control. Using a firmware + interface reduces the probability of confusion with + the hardware and the OS independently updating the + backlight state. Platform interfaces are mostly a + holdover from pre-standardisation of firmware + interfaces. diff --git a/Documentation/ABI/stable/sysfs-firmware-efi-vars b/Documentation/ABI/stable/sysfs-firmware-efi-vars new file mode 100644 index 000000000000..5def20b9019e --- /dev/null +++ b/Documentation/ABI/stable/sysfs-firmware-efi-vars @@ -0,0 +1,75 @@ +What: /sys/firmware/efi/vars +Date: April 2004 +Contact: Matt Domsch <Matt_Domsch@dell.com> +Description: + This directory exposes interfaces for interactive with + EFI variables. For more information on EFI variables, + see 'Variable Services' in the UEFI specification + (section 7.2 in specification version 2.3 Errata D). + + In summary, EFI variables are named, and are classified + into separate namespaces through the use of a vendor + GUID. They also have an arbitrary binary value + associated with them. + + The efivars module enumerates these variables and + creates a separate directory for each one found. Each + directory has a name of the form "<key>-<vendor guid>" + and contains the following files: + + attributes: A read-only text file enumerating the + EFI variable flags. Potential values + include: + + EFI_VARIABLE_NON_VOLATILE + EFI_VARIABLE_BOOTSERVICE_ACCESS + EFI_VARIABLE_RUNTIME_ACCESS + EFI_VARIABLE_HARDWARE_ERROR_RECORD + EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS + + See the EFI documentation for an + explanation of each of these variables. + + data: A read-only binary file that can be read + to attain the value of the EFI variable + + guid: The vendor GUID of the variable. This + should always match the GUID in the + variable's name. + + raw_var: A binary file that can be read to obtain + a structure that contains everything + there is to know about the variable. + For structure definition see "struct + efi_variable" in the kernel sources. + + This file can also be written to in + order to update the value of a variable. + For this to work however, all fields of + the "struct efi_variable" passed must + match byte for byte with the structure + read out of the file, save for the value + portion. + + **Note** the efi_variable structure + read/written with this file contains a + 'long' type that may change widths + depending on your underlying + architecture. + + size: As ASCII representation of the size of + the variable's value. + + + In addition, two other magic binary files are provided + in the top-level directory and are used for adding and + removing variables: + + new_var: Takes a "struct efi_variable" and + instructs the EFI firmware to create a + new variable. + + del_var: Takes a "struct efi_variable" and + instructs the EFI firmware to remove any + variable that has a matching vendor GUID + and variable key name. diff --git a/Documentation/ABI/stable/thermal-notification b/Documentation/ABI/stable/thermal-notification new file mode 100644 index 000000000000..9723e8b7aeb3 --- /dev/null +++ b/Documentation/ABI/stable/thermal-notification @@ -0,0 +1,4 @@ +What: A notification mechanism for thermal related events +Description: + This interface enables notification for thermal related events. + The notification is in the form of a netlink event. diff --git a/Documentation/ABI/testing/configfs-spear-pcie-gadget b/Documentation/ABI/testing/configfs-spear-pcie-gadget new file mode 100644 index 000000000000..875988146a63 --- /dev/null +++ b/Documentation/ABI/testing/configfs-spear-pcie-gadget @@ -0,0 +1,31 @@ +What: /config/pcie-gadget +Date: Feb 2011 +KernelVersion: 2.6.37 +Contact: Pratyush Anand <pratyush.anand@st.com> +Description: + + Interface is used to configure selected dual mode PCIe controller + as device and then program its various registers to configure it + as a particular device type. + This interfaces can be used to show spear's PCIe device capability. + + Nodes are only visible when configfs is mounted. To mount configfs + in /config directory use: + # mount -t configfs none /config/ + + For nth PCIe Device Controller + /config/pcie-gadget.n/ + link ... used to enable ltssm and read its status. + int_type ...used to configure and read type of supported + interrupt + no_of_msi ... used to configure number of MSI vector needed and + to read no of MSI granted. + inta ... write 1 to assert INTA and 0 to de-assert. + send_msi ... write MSI vector to be sent. + vendor_id ... used to write and read vendor id (hex) + device_id ... used to write and read device id (hex) + bar0_size ... used to write and read bar0_size + bar0_address ... used to write and read bar0 mapped area in hex. + bar0_rw_offset ... used to write and read offset of bar0 where + bar0_data will be written or read. + bar0_data ... used to write and read data at bar0_rw_offset. diff --git a/Documentation/ABI/testing/pstore b/Documentation/ABI/testing/pstore new file mode 100644 index 000000000000..ddf451ee2a08 --- /dev/null +++ b/Documentation/ABI/testing/pstore @@ -0,0 +1,41 @@ +Where: /dev/pstore/... +Date: March 2011 +Kernel Version: 2.6.39 +Contact: tony.luck@intel.com +Description: Generic interface to platform dependent persistent storage. + + Platforms that provide a mechanism to preserve some data + across system reboots can register with this driver to + provide a generic interface to show records captured in + the dying moments. In the case of a panic the last part + of the console log is captured, but other interesting + data can also be saved. + + # mount -t pstore -o kmsg_bytes=8000 - /dev/pstore + + $ ls -l /dev/pstore + total 0 + -r--r--r-- 1 root root 7896 Nov 30 15:38 dmesg-erst-1 + + Different users of this interface will result in different + filename prefixes. Currently two are defined: + + "dmesg" - saved console log + "mce" - architecture dependent data from fatal h/w error + + Once the information in a file has been read, removing + the file will signal to the underlying persistent storage + device that it can reclaim the space for later re-use. + + $ rm /dev/pstore/dmesg-erst-1 + + The expectation is that all files in /dev/pstore + will be saved elsewhere and erased from persistent store + soon after boot to free up space ready for the next + catastrophe. + + The 'kmsg_bytes' mount option changes the target amount of + data saved on each oops/panic. Pstore saves (possibly + multiple) files based on the record size of the underlying + persistent storage until at least this amount is reached. + Default is 10 Kbytes. diff --git a/Documentation/ABI/testing/sysfs-ata b/Documentation/ABI/testing/sysfs-ata new file mode 100644 index 000000000000..0a932155cbba --- /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 000000000000..c8b3b48ec62c --- /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-css b/Documentation/ABI/testing/sysfs-bus-css index b585ec258a08..2979c40c10e9 100644 --- a/Documentation/ABI/testing/sysfs-bus-css +++ b/Documentation/ABI/testing/sysfs-bus-css @@ -29,7 +29,7 @@ Contact: Cornelia Huck <cornelia.huck@de.ibm.com> linux-s390@vger.kernel.org Description: Contains the PIM/PAM/POM values, as reported by the channel subsystem when last queried by the common I/O - layer (this implies that this attribute is not neccessarily + layer (this implies that this attribute is not necessarily in sync with the values current in the channel subsystem). Note: This is an I/O-subchannel specific attribute. Users: s390-tools, HAL diff --git a/Documentation/ABI/testing/sysfs-bus-media b/Documentation/ABI/testing/sysfs-bus-media new file mode 100644 index 000000000000..7057e574154a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-media @@ -0,0 +1,6 @@ +What: /sys/bus/media/devices/.../model +Date: January 2011 +Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> + linux-media@vger.kernel.org +Description: Contains the device model name in UTF-8. The device version is + is not be appended to the model name. diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index f979d825d112..36bf454ba855 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -145,9 +145,11 @@ 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. + given name (SMBIOS type 41 string or ACPI _DSM string) of + the PCI device. The attribute will be created only + if the firmware has given a name to the PCI device. + ACPI _DSM string name will be given priority if the + system firmware provides SMBIOS type 41 string also. Users: Userspace applications interested in knowing the firmware assigned name of the PCI device. @@ -157,12 +159,27 @@ 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. + given instance (SMBIOS type 41 device type instance) of the + PCI device. The attribute will be created only if the firmware + has given an instance number 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. + +What: /sys/bus/pci/devices/.../acpi_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 (ACPI _DSM instance number) of the PCI device. + The attribute will be created only if the firmware has given + an instance number to the PCI device. ACPI _DSM instance number + will be given priority if the system firmware provides SMBIOS + type 41 device type instance also. +Users: + Userspace applications interested in knowing the + firmware assigned instance number of the PCI + device that can help in understanding the firmware + intended order of the PCI device. diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss index 4f29e5f1ebfa..f5bb0a3bb8c0 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss +++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss @@ -59,3 +59,15 @@ Kernel Version: 2.6.31 Contact: iss_storagedev@hp.com Description: Displays the usage count (number of opens) of logical drive Y of controller X. + +Where: /sys/bus/pci/devices/<dev>/ccissX/resettable +Date: February 2011 +Kernel Version: 2.6.38 +Contact: iss_storagedev@hp.com +Description: Value of 1 indicates the controller can honor the reset_devices + kernel parameter. Value of 0 indicates reset_devices cannot be + honored. This is to allow, for example, kexec tools to be able + to warn the user if they designate an unresettable device as + a dump device, as kdump requires resetting the device in order + to work reliably. + diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd new file mode 100644 index 000000000000..fa72ccb2282e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-rbd @@ -0,0 +1,83 @@ +What: /sys/bus/rbd/ +Date: November 2010 +Contact: Yehuda Sadeh <yehuda@newdream.net>, + Sage Weil <sage@newdream.net> +Description: + +Being used for adding and removing rbd block devices. + +Usage: <mon ip addr> <options> <pool name> <rbd image name> [snap name] + + $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add + +The snapshot name can be "-" or omitted to map the image read/write. A <dev-id> +will be assigned for any registered block device. If snapshot is used, it will +be mapped read-only. + +Removal of a device: + + $ echo <dev-id> > /sys/bus/rbd/remove + +Entries under /sys/bus/rbd/devices/<dev-id>/ +-------------------------------------------- + +client_id + + The ceph unique client id that was assigned for this specific session. + +major + + The block device major number. + +name + + The name of the rbd image. + +pool + + The pool where this rbd image resides. The pool-name pair is unique + per rados system. + +size + + The size (in bytes) of the mapped block device. + +refresh + + Writing to this file will reread the image header data and set + all relevant datastructures accordingly. + +current_snap + + The current snapshot for which the device is mapped. + +create_snap + + Create a snapshot: + + $ echo <snap-name> > /sys/bus/rbd/devices/<dev-id>/snap_create + +rollback_snap + + Rolls back data to the specified snapshot. This goes over the entire + list of rados blocks and sends a rollback command to each. + + $ echo <snap-name> > /sys/bus/rbd/devices/<dev-id>/snap_rollback + +snap_* + + A directory per each snapshot + + +Entries under /sys/bus/rbd/devices/<dev-id>/snap_<snap-name> +------------------------------------------------------------- + +id + + The rados internal snapshot id assigned for this snapshot + +size + + The size of the image when this snapshot was taken. + + diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led index 9e4541d71cb6..3646ec85d513 100644 --- a/Documentation/ABI/testing/sysfs-class-led +++ b/Documentation/ABI/testing/sysfs-class-led @@ -26,3 +26,12 @@ Description: scheduler is chosen. Trigger specific parameters can appear in /sys/class/leds/<led> once a given trigger is selected. +What: /sys/class/leds/<led>/inverted +Date: January 2011 +KernelVersion: 2.6.38 +Contact: Richard Purdie <rpurdie@rpsys.net> +Description: + Invert the LED on/off state. This parameter is specific to + gpio and backlight triggers. In case of the backlight trigger, + it is useful when driving a LED which is intended to indicate + a device in a standby like state. diff --git a/Documentation/ABI/testing/sysfs-class-net-batman-adv b/Documentation/ABI/testing/sysfs-class-net-batman-adv new file mode 100644 index 000000000000..38dd762def4b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-batman-adv @@ -0,0 +1,14 @@ + +What: /sys/class/net/<iface>/batman-adv/mesh_iface +Date: May 2010 +Contact: Marek Lindner <lindner_marek@yahoo.de> +Description: + The /sys/class/net/<iface>/batman-adv/mesh_iface file + displays the batman mesh interface this <iface> + currently is associated with. + +What: /sys/class/net/<iface>/batman-adv/iface_status +Date: May 2010 +Contact: Marek Lindner <lindner_marek@yahoo.de> +Description: + Indicates the status of <iface> as it is seen by batman. diff --git a/Documentation/ABI/testing/sysfs-class-net-mesh b/Documentation/ABI/testing/sysfs-class-net-mesh new file mode 100644 index 000000000000..748fe1701d25 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-mesh @@ -0,0 +1,69 @@ + +What: /sys/class/net/<mesh_iface>/mesh/aggregated_ogms +Date: May 2010 +Contact: Marek Lindner <lindner_marek@yahoo.de> +Description: + Indicates whether the batman protocol messages of the + mesh <mesh_iface> shall be aggregated or not. + +What: /sys/class/net/<mesh_iface>/mesh/bonding +Date: June 2010 +Contact: Simon Wunderlich <siwu@hrz.tu-chemnitz.de> +Description: + Indicates whether the data traffic going through the + mesh will be sent using multiple interfaces at the + same time (if available). + +What: /sys/class/net/<mesh_iface>/mesh/fragmentation +Date: October 2010 +Contact: Andreas Langer <an.langer@gmx.de> +Description: + Indicates whether the data traffic going through the + mesh will be fragmented or silently discarded if the + packet size exceeds the outgoing interface MTU. + +What: /sys/class/net/<mesh_iface>/mesh/gw_bandwidth +Date: October 2010 +Contact: Marek Lindner <lindner_marek@yahoo.de> +Description: + Defines the bandwidth which is propagated by this + node if gw_mode was set to 'server'. + +What: /sys/class/net/<mesh_iface>/mesh/gw_mode +Date: October 2010 +Contact: Marek Lindner <lindner_marek@yahoo.de> +Description: + Defines the state of the gateway features. Can be + either 'off', 'client' or 'server'. + +What: /sys/class/net/<mesh_iface>/mesh/gw_sel_class +Date: October 2010 +Contact: Marek Lindner <lindner_marek@yahoo.de> +Description: + Defines the selection criteria this node will use + to choose a gateway if gw_mode was set to 'client'. + +What: /sys/class/net/<mesh_iface>/mesh/orig_interval +Date: May 2010 +Contact: Marek Lindner <lindner_marek@yahoo.de> +Description: + Defines the interval in milliseconds in which batman + sends its protocol messages. + +What: /sys/class/net/<mesh_iface>/mesh/hop_penalty +Date: Oct 2010 +Contact: Linus Lüssing <linus.luessing@web.de> +Description: + Defines the penalty which will be applied to an + originator message's tq-field on every hop. + +What: /sys/class/net/<mesh_iface>/mesh/vis_mode +Date: May 2010 +Contact: Marek Lindner <lindner_marek@yahoo.de> +Description: + Each batman node only maintains information about its + own local neighborhood, therefore generating graphs + showing the topology of the entire mesh is not easily + feasible without having a central instance to collect + the local topologies from all nodes. This file allows + to activate the collecting (server) mode. diff --git a/Documentation/ABI/testing/sysfs-devices-mmc b/Documentation/ABI/testing/sysfs-devices-mmc new file mode 100644 index 000000000000..5a50ab655843 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-mmc @@ -0,0 +1,21 @@ +What: /sys/devices/.../mmc_host/mmcX/mmcX:XXXX/enhanced_area_offset +Date: January 2011 +Contact: Chuanxiao Dong <chuanxiao.dong@intel.com> +Description: + Enhanced area is a new feature defined in eMMC4.4 standard. + eMMC4.4 or later card can support such feature. This kind of + area can help to improve the card performance. If the feature + is enabled, this attribute will indicate the start address of + enhanced data area. If not, this attribute will be -EINVAL. + Unit Byte. Format decimal. + +What: /sys/devices/.../mmc_host/mmcX/mmcX:XXXX/enhanced_area_size +Date: January 2011 +Contact: Chuanxiao Dong <chuanxiao.dong@intel.com> +Description: + Enhanced area is a new feature defined in eMMC4.4 standard. + eMMC4.4 or later card can support such feature. This kind of + area can help to improve the card performance. If the feature + is enabled, this attribute will indicate the size of enhanced + data area. If not, this attribute will be -EINVAL. + Unit KByte. Format decimal. diff --git a/Documentation/ABI/testing/sysfs-devices-power b/Documentation/ABI/testing/sysfs-devices-power index 6123c523bfd7..8ffbc25376a0 100644 --- a/Documentation/ABI/testing/sysfs-devices-power +++ b/Documentation/ABI/testing/sysfs-devices-power @@ -29,9 +29,8 @@ Description: "disabled" to it. For the devices that are not capable of generating system wakeup - events this file contains "\n". In that cases the user space - cannot modify the contents of this file and the device cannot be - enabled to wake up the system. + events this file is not present. In that case the device cannot + be enabled to wake up the system from sleep states. What: /sys/devices/.../power/control Date: January 2009 @@ -77,3 +76,92 @@ 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 not present. + +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 not present. + +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 not + present. + +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 not present. + +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 not present. + +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 not present. + +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 not present. + +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-ibm-rtl b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl new file mode 100644 index 000000000000..b82deeaec314 --- /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 b/Documentation/ABI/testing/sysfs-driver-hid new file mode 100644 index 000000000000..b6490e14fe83 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid @@ -0,0 +1,10 @@ +What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor + For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor + Symlink : /sys/class/hidraw/hidraw<num>/device/report_descriptor +Date: Jan 2011 +KernelVersion: 2.0.39 +Contact: Alan Ott <alan@signal11.us> +Description: When read, this file returns the device's raw binary HID + report descriptor. + This file cannot be written. +Users: HIDAPI library (http://www.signal11.us/oss/hidapi) diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-arvo b/Documentation/ABI/testing/sysfs-driver-hid-roccat-arvo new file mode 100644 index 000000000000..55e281b0071a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-arvo @@ -0,0 +1,53 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/arvo/roccatarvo<minor>/actual_profile +Date: Januar 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-5. + When read, this attribute returns the number of the actual + profile which is also the profile that's active on device startup. + When written this attribute activates the selected profile + immediately. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/arvo/roccatarvo<minor>/button +Date: Januar 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The keyboard can store short macros with consist of 1 button with + several modifier keys internally. + When written, this file lets one set the sequence for a specific + button for a specific profile. Button and profile numbers are + included in written data. The data has to be 24 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/arvo/roccatarvo<minor>/info +Date: Januar 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns some info about the device like the + installed firmware version. + The size of the data is 8 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/arvo/roccatarvo<minor>/key_mask +Date: Januar 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The keyboard lets the user deactivate 5 certain keys like the + windows and application keys, to protect the user from the outcome + of accidentally pressing them. + The integer value of this attribute has bits 0-4 set depending + on the state of the corresponding key. + When read, this file returns the current state of the buttons. + When written, the given buttons are activated/deactivated + immediately. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/arvo/roccatarvo<minor>/mode_key +Date: Januar 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The keyboard has a condensed layout without num-lock key. + Instead it uses a mode-key which activates a gaming mode where + the assignment of the number block changes. + The integer value of this attribute ranges from 0 (OFF) to 1 (ON). + When read, this file returns the actual state of the key. + When written, the key is activated/deactivated immediately. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone index 063bda7fe707..3ca3971109bf 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone @@ -1,4 +1,4 @@ -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/actual_dpi +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/actual_dpi Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: It is possible to switch the dpi setting of the mouse with the @@ -16,14 +16,16 @@ Description: It is possible to switch the dpi setting of the mouse with the 6 3200 This file is readonly. +Users: http://roccat.sourceforge.net -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/actual_profile +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/actual_profile Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: When read, this file returns the number of the actual profile. This file is readonly. +Users: http://roccat.sourceforge.net -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/firmware_version +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/firmware_version Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: When read, this file returns the raw integer version number of the @@ -32,12 +34,13 @@ Description: When read, this file returns the raw integer version number of the 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. +Users: http://roccat.sourceforge.net -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/profile[1-5] +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/profile[1-5] Date: March 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 holds informations like button + press of a button. A profile holds information like button mappings, sensitivity, the colors of the 5 leds and light effects. When read, these files return the respective profile. The @@ -47,8 +50,9 @@ Description: The mouse can store 5 profiles which can be switched by the The mouse will reject invalid data, whereas the profile number stored in the profile doesn't need to fit the number of the store. +Users: http://roccat.sourceforge.net -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/settings +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/settings Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: When read, this file returns the settings stored in the mouse. @@ -57,8 +61,9 @@ Description: When read, this file returns the settings stored in the mouse. When written, this file lets write settings back to the mouse. The data has to be 36 bytes long. The mouse will reject invalid data. +Users: http://roccat.sourceforge.net -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/startup_profile +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/startup_profile Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: The integer value of this attribute ranges from 1 to 5. @@ -66,8 +71,9 @@ Description: The integer value of this attribute ranges from 1 to 5. that's active when the mouse is powered on. When written, this file sets the number of the startup profile and the mouse activates this profile immediately. +Users: http://roccat.sourceforge.net -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/tcu +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/tcu Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: The mouse has a "Tracking Control Unit" which lets the user @@ -77,8 +83,9 @@ Description: The mouse has a "Tracking Control Unit" which lets the user Writing 0 in this file will switch the TCU off. Writing 1 in this file will start the calibration which takes around 6 seconds to complete and activates the TCU. +Users: http://roccat.sourceforge.net -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/weight +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/weight Date: March 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: The mouse can be equipped with one of four supplied weights @@ -96,3 +103,4 @@ Description: The mouse can be equipped with one of four supplied weights 4 20g This file is readonly. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus b/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus new file mode 100644 index 000000000000..326e05452da7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus @@ -0,0 +1,119 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/actual_profile +Date: October 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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/firmware_version +Date: October 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 121 means 1.21 + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/macro +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store a macro with max 500 key/button strokes + internally. + When written, this file lets one set the sequence for a specific + button for a specific profile. Button and profile numbers are + included in written data. The data has to be 2082 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/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 information about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 77 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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/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 information about button layout. + When read, these files return the respective profile buttons. + The returned data is 77 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_settings +Date: October 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 information 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 43 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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/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 information like resolution, sensitivity + and light effects. + When read, these files return the respective profile settings. + The returned data is 43 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/sensor +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse has a tracking- and a distance-control-unit. These + can be activated/deactivated and the lift-off distance can be + set. The data has to be 6 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/startup_profile +Date: October 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. + When written, this file sets the number of the startup profile + and the mouse activates this profile immediately. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written a calibration process for the tracking control unit + can be initiated/cancelled. + The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu_image +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read the mouse returns a 30x30 pixel image of the + sampled underground. This works only in the course of a + calibration process initiated with tcu. + The returned data is 1028 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus new file mode 100644 index 000000000000..20f937c9d84f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus @@ -0,0 +1,100 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_cpi +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-4. + When read, this attribute returns the number of the active + cpi level. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_profile +Date: January 2011 +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 active + profile. + When written, the mouse activates this profile immediately. + The profile that's active when powered down is the same that's + active when the mouse is powered on. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_sensitivity_x +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-10. + When read, this attribute returns the number of the actual + sensitivity in x direction. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_sensitivity_y +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-10. + When read, this attribute returns the number of the actual + sensitivity in y direction. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/firmware_version +Date: January 2011 +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 121 means 1.21 + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_buttons +Date: January 2011 +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 information about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 23 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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_buttons +Date: January 2011 +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 information about button layout. + When read, these files return the respective profile buttons. + The returned data is 23 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_settings +Date: January 2011 +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 information 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 16 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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_settings +Date: January 2011 +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 information like resolution, sensitivity + and light effects. + When read, these files return the respective profile settings. + The returned data is 16 bytes in size. + This file is readonly. +Users: http://roccat.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 000000000000..3f8de50e4ff1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra @@ -0,0 +1,107 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/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 information 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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/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 information 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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/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 information 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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/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 information about button layout. + When read, these files return the respective profile buttons. + The returned data is 19 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/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. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/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. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-samsung-laptop b/Documentation/ABI/testing/sysfs-driver-samsung-laptop new file mode 100644 index 000000000000..0a810231aad4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-samsung-laptop @@ -0,0 +1,19 @@ +What: /sys/devices/platform/samsung/performance_level +Date: January 1, 2010 +KernelVersion: 2.6.33 +Contact: Greg Kroah-Hartman <gregkh@suse.de> +Description: Some Samsung laptops have different "performance levels" + that are can be modified by a function key, and by this + sysfs file. These values don't always make a whole lot + of sense, but some users like to modify them to keep + their fans quiet at all costs. Reading from this file + will show the current performance level. Writing to the + file can change this value. + Valid options: + "silent" + "normal" + "overclock" + Note that not all laptops support all of these options. + Specifically, not all support the "overclock" option, + and it's still unknown if this value even changes + anything, other than making the user feel a bit better. diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi b/Documentation/ABI/testing/sysfs-firmware-dmi new file mode 100644 index 000000000000..ba9da9503c23 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-dmi @@ -0,0 +1,110 @@ +What: /sys/firmware/dmi/ +Date: February 2011 +Contact: Mike Waychison <mikew@google.com> +Description: + Many machines' firmware (x86 and ia64) export DMI / + SMBIOS tables to the operating system. Getting at this + information is often valuable to userland, especially in + cases where there are OEM extensions used. + + The kernel itself does not rely on the majority of the + information in these tables being correct. It equally + cannot ensure that the data as exported to userland is + without error either. + + DMI is structured as a large table of entries, where + each entry has a common header indicating the type and + length of the entry, as well as 'handle' that is + supposed to be unique amongst all entries. + + Some entries are required by the specification, but many + others are optional. In general though, users should + never expect to find a specific entry type on their + system unless they know for certain what their firmware + is doing. Machine to machine will vary. + + Multiple entries of the same type are allowed. In order + to handle these duplicate entry types, each entry is + assigned by the operating system an 'instance', which is + derived from an entry type's ordinal position. That is + to say, if there are 'N' multiple entries with the same type + 'T' in the DMI tables (adjacent or spread apart, it + doesn't matter), they will be represented in sysfs as + entries "T-0" through "T-(N-1)": + + Example entry directories: + + /sys/firmware/dmi/entries/17-0 + /sys/firmware/dmi/entries/17-1 + /sys/firmware/dmi/entries/17-2 + /sys/firmware/dmi/entries/17-3 + ... + + Instance numbers are used in lieu of the firmware + assigned entry handles as the kernel itself makes no + guarantees that handles as exported are unique, and + there are likely firmware images that get this wrong in + the wild. + + Each DMI entry in sysfs has the common header values + exported as attributes: + + handle : The 16bit 'handle' that is assigned to this + entry by the firmware. This handle may be + referred to by other entries. + length : The length of the entry, as presented in the + entry itself. Note that this is _not the + total count of bytes associated with the + entry_. This value represents the length of + the "formatted" portion of the entry. This + "formatted" region is sometimes followed by + the "unformatted" region composed of nul + terminated strings, with termination signalled + by a two nul characters in series. + raw : The raw bytes of the entry. This includes the + "formatted" portion of the entry, the + "unformatted" strings portion of the entry, + and the two terminating nul characters. + type : The type of the entry. This value is the same + as found in the directory name. It indicates + how the rest of the entry should be + interpreted. + instance: The instance ordinal of the entry for the + given type. This value is the same as found + in the parent directory name. + position: The position of the entry within the entirety + of the entirety. + + === Entry Specialization === + + Some entry types may have other information available in + sysfs. + + --- Type 15 - System Event Log --- + + This entry allows the firmware to export a log of + events the system has taken. This information is + typically backed by nvram, but the implementation + details are abstracted by this table. This entries data + is exported in the directory: + + /sys/firmware/dmi/entries/15-0/system_event_log + + and has the following attributes (documented in the + SMBIOS / DMI specification under "System Event Log (Type 15)": + + area_length + header_start_offset + data_start_offset + access_method + status + change_token + access_method_address + header_format + per_log_type_descriptor_length + type_descriptors_supported_count + + As well, the kernel exports the binary attribute: + + raw_event_log : The raw binary bits of the event log + as described by the DMI entry. diff --git a/Documentation/ABI/testing/sysfs-fs-ext4 b/Documentation/ABI/testing/sysfs-fs-ext4 index 5fb709997d96..f22ac0872ae8 100644 --- a/Documentation/ABI/testing/sysfs-fs-ext4 +++ b/Documentation/ABI/testing/sysfs-fs-ext4 @@ -48,7 +48,7 @@ Description: will have its blocks allocated out of its own unique preallocation pool. -What: /sys/fs/ext4/<disk>/inode_readahead +What: /sys/fs/ext4/<disk>/inode_readahead_blks Date: March 2008 Contact: "Theodore Ts'o" <tytso@mit.edu> Description: @@ -85,7 +85,14 @@ Date: June 2008 Contact: "Theodore Ts'o" <tytso@mit.edu> Description: Tuning parameter which (if non-zero) controls the goal - inode used by the inode allocator in p0reference to - all other allocation hueristics. This is intended for + inode used by the inode allocator in preference to + all other allocation heuristics. This is intended for debugging use only, and should be 0 on production systems. + +What: /sys/fs/ext4/<disk>/max_writeback_mb_bump +Date: September 2009 +Contact: "Theodore Ts'o" <tytso@mit.edu> +Description: + The maximum number of megabytes the writeback code will + try to write out before move on to another inode. diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module new file mode 100644 index 000000000000..cfcec3bffc0a --- /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-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop index 1d775390e856..cd9d667c3da2 100644 --- a/Documentation/ABI/testing/sysfs-platform-asus-laptop +++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop @@ -27,7 +27,7 @@ KernelVersion: 2.6.20 Contact: "Corentin Chary" <corentincj@iksaif.net> Description: Some models like the W1N have a LED display that can be - used to display several informations. + used to display several items of information. To control the LED display, use the following : echo 0x0T000DDD > /sys/devices/platform/asus_laptop/ where T control the 3 letters display, and DDD the 3 digits display. @@ -47,6 +47,20 @@ Date: January 2007 KernelVersion: 2.6.20 Contact: "Corentin Chary" <corentincj@iksaif.net> Description: - Control the bluetooth device. 1 means on, 0 means off. + Control the wlan device. 1 means on, 0 means off. This may control the led, the device or both. Users: Lapsus + +What: /sys/devices/platform/asus_laptop/wimax +Date: October 2010 +KernelVersion: 2.6.37 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Control the wimax device. 1 means on, 0 means off. + +What: /sys/devices/platform/asus_laptop/wwan +Date: October 2010 +KernelVersion: 2.6.37 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Control the wwan (3G) device. 1 means on, 0 means off. diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi new file mode 100644 index 000000000000..2e7df91620de --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi @@ -0,0 +1,31 @@ +What: /sys/devices/platform/<platform>/cpufv +Date: Oct 2010 +KernelVersion: 2.6.37 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Change CPU clock configuration (write-only). + There are three available clock configuration: + * 0 -> Super Performance Mode + * 1 -> High Performance Mode + * 2 -> Power Saving Mode + +What: /sys/devices/platform/<platform>/camera +Date: Jan 2010 +KernelVersion: 2.6.39 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Control the camera. 1 means on, 0 means off. + +What: /sys/devices/platform/<platform>/cardr +Date: Jan 2010 +KernelVersion: 2.6.39 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Control the card reader. 1 means on, 0 means off. + +What: /sys/devices/platform/<platform>/touchpad +Date: Jan 2010 +KernelVersion: 2.6.39 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Control the card touchpad. 1 means on, 0 means off. diff --git a/Documentation/ABI/testing/sysfs-platform-at91 b/Documentation/ABI/testing/sysfs-platform-at91 new file mode 100644 index 000000000000..4cc6a865ae66 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-at91 @@ -0,0 +1,25 @@ +What: /sys/devices/platform/at91_can/net/<iface>/mb0_id +Date: January 2011 +KernelVersion: 2.6.38 +Contact: Marc Kleine-Budde <kernel@pengutronix.de> +Description: + Value representing the can_id of mailbox 0. + + Default: 0x7ff (standard frame) + + Due to a chip bug (errata 50.2.6.3 & 50.3.5.3 in + "AT91SAM9263 Preliminary 6249H-ATARM-27-Jul-09") the + contents of mailbox 0 may be send under certain + conditions (even if disabled or in rx mode). + + The workaround in the errata suggests not to use the + mailbox and load it with an unused identifier. + + In order to use an extended can_id add the + CAN_EFF_FLAG (0x80000000U) to the can_id. Example: + + - standard id 0x7ff: + echo 0x7ff > /sys/class/net/can0/mb0_id + + - extended id 0x1fffffff: + echo 0x9fffffff > /sys/class/net/can0/mb0_id diff --git a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop new file mode 100644 index 000000000000..807fca2ae2a4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop @@ -0,0 +1,6 @@ +What: /sys/devices/platform/ideapad/camera_power +Date: Dec 2010 +KernelVersion: 2.6.37 +Contact: "Ike Panhc <ike.pan@canonical.com>" +Description: + Control the power of camera module. 1 means on, 0 means off. diff --git a/Documentation/ABI/testing/sysfs-platform-kim b/Documentation/ABI/testing/sysfs-platform-kim new file mode 100644 index 000000000000..c1653271872a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-kim @@ -0,0 +1,48 @@ +What: /sys/devices/platform/kim/dev_name +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + Name of the UART device at which the WL128x chip + is connected. example: "/dev/ttyS0". + The device name flows down to architecture specific board + initialization file from the SFI/ATAGS bootloader + firmware. The name exposed is read from the user-space + dameon and opens the device when install is requested. + +What: /sys/devices/platform/kim/baud_rate +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + The maximum reliable baud-rate the host can support. + Different platforms tend to have different high-speed + UART configurations, so the baud-rate needs to be set + locally and also sent across to the WL128x via a HCI-VS + command. The entry is read and made use by the user-space + daemon when the ldisc install is requested. + +What: /sys/devices/platform/kim/flow_cntrl +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + The WL128x makes use of flow control mechanism, and this + entry most often should be 1, the host's UART is required + to have the capability of flow-control, or else this + entry can be made use of for exceptions. + +What: /sys/devices/platform/kim/install +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + When one of the protocols Bluetooth, FM or GPS wants to make + use of the shared UART transport, it registers to the shared + transport driver, which will signal the user-space for opening, + configuring baud and install line discipline via this sysfs + entry. This entry would be polled upon by the user-space + daemon managing the UART, and is notified about the change + by the sysfs_notify. The value would be '1' when UART needs + to be opened/ldisc installed, and would be '0' when UART + is no more required and needs to be closed. diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power index 2875f1f74a07..194ca446ac28 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> diff --git a/Documentation/ABI/testing/sysfs-tty b/Documentation/ABI/testing/sysfs-tty new file mode 100644 index 000000000000..b138b663bf54 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-tty @@ -0,0 +1,19 @@ +What: /sys/class/tty/console/active +Date: Nov 2010 +Contact: Kay Sievers <kay.sievers@vrfy.org> +Description: + Shows the list of currently configured + console devices, like 'tty1 ttyS0'. + The last entry in the file is the active + device connected to /dev/console. + The file supports poll() to detect virtual + console switches. + +What: /sys/class/tty/tty0/active +Date: Nov 2010 +Contact: Kay Sievers <kay.sievers@vrfy.org> +Description: + Shows the currently active virtual console + device, like 'tty1'. + The file supports poll() to detect virtual + console switches. diff --git a/Documentation/Changes b/Documentation/Changes index 4fb88f15f2ef..5f4828a034e3 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -35,7 +35,7 @@ o util-linux 2.10o # fdformat --version o module-init-tools 0.9.10 # depmod -V o e2fsprogs 1.41.4 # e2fsck -V o jfsutils 1.1.3 # fsck.jfs -V -o reiserfsprogs 3.6.3 # reiserfsck -V 2>&1|grep reiserfsprogs +o reiserfsprogs 3.6.3 # reiserfsck -V o xfsprogs 2.6.0 # xfs_db -V o squashfs-tools 4.0 # mksquashfs -version o btrfs-progs 0.18 # btrfsck @@ -46,9 +46,9 @@ o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version o nfs-utils 1.0.5 # showmount --version o procps 3.2.0 # ps --version o oprofile 0.9 # oprofiled --version -o udev 081 # udevinfo -V -o grub 0.93 # grub --version -o mcelog 0.6 +o udev 081 # udevd --version +o grub 0.93 # grub --version || grub-install --version +o mcelog 0.6 # mcelog --version o iptables 1.4.2 # iptables -V diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 8bb37237ebd2..58b0bf917834 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -168,6 +168,13 @@ Do not unnecessarily use braces where a single statement will do. if (condition) action(); +and + +if (condition) + do_this(); +else + do_that(); + This does not apply if one branch of a conditional statement is a single statement. Use braces in both branches. @@ -659,7 +666,7 @@ There are a number of driver model diagnostic macros in <linux/device.h> which you should use to make sure messages are matched to the right device and driver, and are tagged with the right level: dev_err(), dev_warn(), dev_info(), and so forth. For messages that aren't associated with a -particular device, <linux/kernel.h> defines pr_debug() and pr_info(). +particular device, <linux/printk.h> defines pr_debug() and pr_info(). Coming up with good debugging messages can be quite a challenge; and once you have them, they can be a huge help for remote troubleshooting. Such @@ -819,6 +826,3 @@ language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ Kernel CodingStyle, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ --- -Last updated on 2007-July-13. - diff --git a/Documentation/DocBook/80211.tmpl b/Documentation/DocBook/80211.tmpl new file mode 100644 index 000000000000..8906648f962b --- /dev/null +++ b/Documentation/DocBook/80211.tmpl @@ -0,0 +1,574 @@ +<?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_cqm_pktloss_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_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 mac80211_tx_control_flags +!Finclude/net/mac80211.h mac80211_rate_control_flags +!Finclude/net/mac80211.h ieee80211_tx_rate +!Finclude/net/mac80211.h ieee80211_tx_info +!Finclude/net/mac80211.h ieee80211_tx_info_clear_status +!Finclude/net/mac80211.h ieee80211_rx +!Finclude/net/mac80211.h ieee80211_rx_ni +!Finclude/net/mac80211.h ieee80211_rx_irqsafe +!Finclude/net/mac80211.h ieee80211_tx_status +!Finclude/net/mac80211.h ieee80211_tx_status_ni +!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 +!Finclude/net/mac80211.h ieee80211_queue_stopped + </sect1> + </chapter> + + <chapter id="filters"> + <title>Frame filtering</title> +!Pinclude/net/mac80211.h Frame filtering +!Finclude/net/mac80211.h ieee80211_filter_flags + </chapter> + + <chapter id="workqueue"> + <title>The mac80211 workqueue</title> +!Pinclude/net/mac80211.h mac80211 workqueue +!Finclude/net/mac80211.h ieee80211_queue_work +!Finclude/net/mac80211.h ieee80211_queue_delayed_work + </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="led-support"> + <title>LED support</title> + <para> + Mac80211 supports various ways of blinking LEDs. Wherever possible, + device LEDs should be exposed as LED class devices and hooked up to + the appropriate trigger, which will then be triggered appropriately + by mac80211. + </para> +!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_tpt_blink +!Finclude/net/mac80211.h ieee80211_tpt_led_trigger_flags +!Finclude/net/mac80211.h ieee80211_create_tpt_led_trigger + </chapter> + + <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 +!Finclude/net/mac80211.h ieee80211_tkip_key_type +!Finclude/net/mac80211.h ieee80211_get_tkip_key +!Finclude/net/mac80211.h ieee80211_key_removed + </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> +!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces +!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces_atomic + </chapter> + + <chapter id="station-handling"> + <title>Station handling</title> + <para>TODO</para> +!Finclude/net/mac80211.h ieee80211_sta +!Finclude/net/mac80211.h sta_notify_cmd +!Finclude/net/mac80211.h ieee80211_find_sta +!Finclude/net/mac80211.h ieee80211_find_sta_by_ifaddr +!Finclude/net/mac80211.h ieee80211_sta_block_awake + </chapter> + + <chapter id="hardware-scan-offload"> + <title>Hardware scan offload</title> + <para>TBD</para> +!Finclude/net/mac80211.h ieee80211_scan_completed + </chapter> + + <chapter id="aggregation"> + <title>Aggregation</title> + <sect1> + <title>TX A-MPDU aggregation</title> +!Pnet/mac80211/agg-tx.c TX A-MPDU aggregation +!Cnet/mac80211/agg-tx.c + </sect1> + <sect1> + <title>RX A-MPDU aggregation</title> +!Pnet/mac80211/agg-rx.c RX A-MPDU aggregation +!Cnet/mac80211/agg-rx.c + </sect1> +!Finclude/net/mac80211.h ieee80211_ampdu_mlme_action + </chapter> + + <chapter id="smps"> + <title>Spatial Multiplexing Powersave (SMPS)</title> +!Pinclude/net/mac80211.h Spatial multiplexing power save +!Finclude/net/mac80211.h ieee80211_request_smps +!Finclude/net/mac80211.h ieee80211_smps_mode + </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="ratecontrol-api"> + <title>Rate Control API</title> + <para>TBD</para> +!Finclude/net/mac80211.h ieee80211_start_tx_ba_session +!Finclude/net/mac80211.h ieee80211_start_tx_ba_cb_irqsafe +!Finclude/net/mac80211.h ieee80211_stop_tx_ba_session +!Finclude/net/mac80211.h ieee80211_stop_tx_ba_cb_irqsafe +!Finclude/net/mac80211.h rate_control_changed +!Finclude/net/mac80211.h ieee80211_tx_rate_control +!Finclude/net/mac80211.h rate_control_send_low + </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="aggregation-internals"> + <title>Aggregation</title> +!Fnet/mac80211/sta_info.h sta_ampdu_mlme +!Fnet/mac80211/sta_info.h tid_ampdu_tx +!Fnet/mac80211/sta_info.h tid_ampdu_rx + </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 34929f24c284..8436b018c289 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 @@ -53,7 +53,9 @@ MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) build_images = mkdir -p $(objtree)/Documentation/DocBook/media/ && \ - cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(objtree)/Documentation/DocBook/media/ + cp $(srctree)/Documentation/DocBook/dvb/*.png \ + $(srctree)/Documentation/DocBook/v4l/*.gif \ + $(objtree)/Documentation/DocBook/media/ xmldoclinks: ifneq ($(objtree),$(srctree)) diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index feca0758391e..36f63d4a0a06 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -51,8 +51,13 @@ <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 @@ -212,8 +217,8 @@ X!Isound/sound_firmware.c <chapter id="uart16x50"> <title>16x50 UART Driver</title> !Iinclude/linux/serial_core.h -!Edrivers/serial/serial_core.c -!Edrivers/serial/8250.c +!Edrivers/tty/serial/serial_core.c +!Edrivers/tty/serial/8250.c </chapter> <chapter id="fbdev"> @@ -299,6 +304,10 @@ X!Idrivers/video/console/fonts.c !Edrivers/input/ff-core.c !Edrivers/input/ff-memless.c </sect1> + <sect1><title>Multitouch Library</title> +!Iinclude/linux/input/mt.h +!Edrivers/input/input-mt.c + </sect1> <sect1><title>Polled input devices</title> !Iinclude/linux/input-polldev.h !Edrivers/input/input-polldev.c diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 910c923a9b86..c27915893974 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -73,8 +73,8 @@ services. </para> <para> - The core of every DRM driver is struct drm_device. Drivers - will typically statically initialize a drm_device structure, + The core of every DRM driver is struct drm_driver. Drivers + will typically statically initialize a drm_driver structure, then pass it to drm_init() at load time. </para> @@ -84,7 +84,7 @@ <title>Driver initialization</title> <para> Before calling the DRM initialization routines, the driver must - first create and fill out a struct drm_device structure. + first create and fill out a struct drm_driver structure. </para> <programlisting> static struct drm_driver driver = { @@ -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 e3a97fdd62a6..ad8678d48916 100644 --- a/Documentation/DocBook/dvb/dvbapi.xml +++ b/Documentation/DocBook/dvb/dvbapi.xml @@ -28,7 +28,7 @@ <holder>Convergence GmbH</holder> </copyright> <copyright> - <year>2009-2010</year> + <year>2009-2011</year> <holder>Mauro Carvalho Chehab</holder> </copyright> diff --git a/Documentation/DocBook/dvb/dvbproperty.xml b/Documentation/DocBook/dvb/dvbproperty.xml index 5f57c7ccd4ba..97f397e2fb3a 100644 --- a/Documentation/DocBook/dvb/dvbproperty.xml +++ b/Documentation/DocBook/dvb/dvbproperty.xml @@ -40,7 +40,7 @@ <para>Central frequency of the channel.</para> - <para>For ISDB-T the channels are usally transmitted with an offset of 143kHz. E.g. a + <para>For ISDB-T the channels are usually transmitted with an offset of 143kHz. E.g. a valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of the channel which is 6MHz.</para> diff --git a/Documentation/DocBook/dvb/frontend.xml b/Documentation/DocBook/dvb/frontend.xml index 78d756de5906..60c6976fb311 100644 --- a/Documentation/DocBook/dvb/frontend.xml +++ b/Documentation/DocBook/dvb/frontend.xml @@ -139,7 +139,7 @@ consistently to the DiSEqC commands as described in the DiSEqC spec.</para> <section id="frontend_sec_tone"> <title>SEC continuous tone</title> -<para>The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the +<para>The continuous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to be switched consistently to the DiSEqC commands as described in the DiSEqC spec.</para> diff --git a/Documentation/DocBook/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl index 5e87ad58c0b5..f51f28531b8d 100644 --- a/Documentation/DocBook/filesystems.tmpl +++ b/Documentation/DocBook/filesystems.tmpl @@ -82,6 +82,11 @@ </sect1> </chapter> + <chapter id="fs_events"> + <title>Events based on file descriptors</title> +!Efs/eventfd.c + </chapter> + <chapter id="sysfs"> <title>The Filesystem for Exporting Kernel Objects</title> !Efs/sysfs/file.c diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl index 1448b33fd222..fb10fd08c05c 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 6899f471fb15..7160652a8736 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -93,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"> @@ -257,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 a0d479d1e1dd..67e7ab41c0a6 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) { @@ -1769,7 +1763,7 @@ as it would be on UP. There is a furthur optimization possible here: remember our original cache code, where there were no reference counts and the caller simply held the lock whenever using the object? This is still possible: if -you hold the lock, noone can delete the object, so you don't need to +you hold the lock, no one can delete the object, so you don't need to get and put the reference count. </para> diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl index 490d862c5f0d..d71b57fcf116 100644 --- a/Documentation/DocBook/kgdb.tmpl +++ b/Documentation/DocBook/kgdb.tmpl @@ -710,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> diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index 8c5411cfeaf0..cdd1bb9aac0d 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -1032,7 +1032,7 @@ and other resources, etc. <listitem> <para> This is indicated by ICRC bit in the ERROR register and - means that corruption occurred during data transfer. Upto + means that corruption occurred during data transfer. Up to ATA/ATAPI-7, the standard specifies that this bit is only applicable to UDMA transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be applicable to multiword DMA and @@ -1045,10 +1045,10 @@ and other resources, etc. <term>ABRT error during data transfer or on completion</term> <listitem> <para> - Upto ATA/ATAPI-7, the standard specifies that ABRT could be + Up to ATA/ATAPI-7, the standard specifies that ABRT could be set on ICRC errors and on cases where a device is not able to complete a command. Combined with the fact that MWDMA - and PIO transfer errors aren't allowed to use ICRC bit upto + and PIO transfer errors aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply that ABRT bit alone could indicate tranfer errors. </para> @@ -1122,7 +1122,7 @@ and other resources, etc. <para> Depending on commands, not all STATUS/ERROR bits are applicable. These non-applicable bits are marked with - "na" in the output descriptions but upto ATA/ATAPI-7 + "na" in the output descriptions but up to ATA/ATAPI-7 no definition of "na" can be found. However, ATA/ATAPI-8 draft revision 1f describes "N/A" as follows. @@ -1507,7 +1507,7 @@ and other resources, etc. <listitem> <para> - CHS set up with INITIALIZE DEVICE PARAMETERS (seldomly used) + CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used) </para> </listitem> diff --git a/Documentation/DocBook/mac80211.tmpl b/Documentation/DocBook/mac80211.tmpl deleted file mode 100644 index affb15a344a1..000000000000 --- 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 6ae97157b1c7..5d259c632cdf 100644 --- a/Documentation/DocBook/media-entities.tmpl +++ b/Documentation/DocBook/media-entities.tmpl @@ -11,6 +11,10 @@ <!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>"> <!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>"> +<!ENTITY media-func-close "<link linkend='media-func-close'><function>close()</function></link>"> +<!ENTITY media-func-ioctl "<link linkend='media-func-ioctl'><function>ioctl()</function></link>"> +<!ENTITY media-func-open "<link linkend='media-func-open'><function>open()</function></link>"> + <!-- Ioctls --> <!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>"> <!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>"> @@ -82,11 +86,24 @@ <!ENTITY VIDIOC-S-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_S_PRIORITY</constant></link>"> <!ENTITY VIDIOC-S-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_S_STD</constant></link>"> <!ENTITY VIDIOC-S-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_S_TUNER</constant></link>"> +<!ENTITY VIDIOC-SUBDEV-ENUM-FRAME-SIZE "<link linkend='vidioc-subdev-enum-frame-size'><constant>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</constant></link>"> +<!ENTITY VIDIOC-SUBDEV-ENUM-MBUS-CODE "<link linkend='vidioc-subdev-enum-mbus-code'><constant>VIDIOC_SUBDEV_ENUM_MBUS_CODE</constant></link>"> +<!ENTITY VIDIOC-SUBDEV-G-CROP "<link linkend='vidioc-subdev-g-crop'><constant>VIDIOC_SUBDEV_G_CROP</constant></link>"> +<!ENTITY VIDIOC-SUBDEV-G-FMT "<link linkend='vidioc-subdev-g-fmt'><constant>VIDIOC_SUBDEV_G_FMT</constant></link>"> +<!ENTITY VIDIOC-SUBDEV-G-FRAME-INTERVAL "<link linkend='vidioc-subdev-g-frame-interval'><constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant></link>"> +<!ENTITY VIDIOC-SUBDEV-S-CROP "<link linkend='vidioc-subdev-g-crop'><constant>VIDIOC_SUBDEV_S_CROP</constant></link>"> +<!ENTITY VIDIOC-SUBDEV-S-FMT "<link linkend='vidioc-subdev-g-fmt'><constant>VIDIOC_SUBDEV_S_FMT</constant></link>"> +<!ENTITY VIDIOC-SUBDEV-S-FRAME-INTERVAL "<link linkend='vidioc-subdev-g-frame-interval'><constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant></link>"> <!ENTITY VIDIOC-TRY-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_TRY_ENCODER_CMD</constant></link>"> <!ENTITY VIDIOC-TRY-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_TRY_EXT_CTRLS</constant></link>"> <!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>"> <!ENTITY VIDIOC-UNSUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_UNSUBSCRIBE_EVENT</constant></link>"> +<!ENTITY MEDIA-IOC-DEVICE-INFO "<link linkend='media-ioc-device-info'><constant>MEDIA_IOC_DEVICE_INFO</constant></link>"> +<!ENTITY MEDIA-IOC-ENUM-ENTITIES "<link linkend='media-ioc-enum-entities'><constant>MEDIA_IOC_ENUM_ENTITIES</constant></link>"> +<!ENTITY MEDIA-IOC-ENUM-LINKS "<link linkend='media-ioc-enum-links'><constant>MEDIA_IOC_ENUM_LINKS</constant></link>"> +<!ENTITY MEDIA-IOC-SETUP-LINK "<link linkend='media-ioc-setup-link'><constant>MEDIA_IOC_SETUP_LINK</constant></link>"> + <!-- Types --> <!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>"> @@ -98,6 +115,7 @@ <!ENTITY v4l2-field "enum <link linkend='v4l2-field'>v4l2_field</link>"> <!ENTITY v4l2-frmivaltypes "enum <link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link>"> <!ENTITY v4l2-frmsizetypes "enum <link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link>"> +<!ENTITY v4l2-mbus-pixelcode "enum <link linkend='v4l2-mbus-pixelcode'>v4l2_mbus_pixelcode</link>"> <!ENTITY v4l2-memory "enum <link linkend='v4l2-memory'>v4l2_memory</link>"> <!ENTITY v4l2-mpeg-audio-ac3-bitrate "enum <link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link>"> <!ENTITY v4l2-mpeg-audio-crc "enum <link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link>"> @@ -121,6 +139,7 @@ <!ENTITY v4l2-mpeg-video-encoding "enum <link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link>"> <!ENTITY v4l2-power-line-frequency "enum <link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link>"> <!ENTITY v4l2-priority "enum <link linkend='v4l2-priority'>v4l2_priority</link>"> +<!ENTITY v4l2-subdev-format-whence "enum <link linkend='v4l2-subdev-format-whence'>v4l2_subdev_format_whence</link>"> <!ENTITY v4l2-tuner-type "enum <link linkend='v4l2-tuner-type'>v4l2_tuner_type</link>"> <!ENTITY v4l2-preemphasis "enum <link linkend='v4l2-preemphasis'>v4l2_preemphasis</link>"> @@ -129,6 +148,7 @@ <!ENTITY v4l2-audioout "struct <link linkend='v4l2-audioout'>v4l2_audioout</link>"> <!ENTITY v4l2-bt-timings "struct <link linkend='v4l2-bt-timings'>v4l2_bt_timings</link>"> <!ENTITY v4l2-buffer "struct <link linkend='v4l2-buffer'>v4l2_buffer</link>"> +<!ENTITY v4l2-plane "struct <link linkend='v4l2-plane'>v4l2_plane</link>"> <!ENTITY v4l2-capability "struct <link linkend='v4l2-capability'>v4l2_capability</link>"> <!ENTITY v4l2-captureparm "struct <link linkend='v4l2-captureparm'>v4l2_captureparm</link>"> <!ENTITY v4l2-clip "struct <link linkend='v4l2-clip'>v4l2_clip</link>"> @@ -162,11 +182,14 @@ <!ENTITY v4l2-hw-freq-seek "struct <link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link>"> <!ENTITY v4l2-input "struct <link linkend='v4l2-input'>v4l2_input</link>"> <!ENTITY v4l2-jpegcompression "struct <link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link>"> +<!ENTITY v4l2-mbus-framefmt "struct <link linkend='v4l2-mbus-framefmt'>v4l2_mbus_framefmt</link>"> <!ENTITY v4l2-modulator "struct <link linkend='v4l2-modulator'>v4l2_modulator</link>"> <!ENTITY v4l2-mpeg-vbi-fmt-ivtv "struct <link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link>"> <!ENTITY v4l2-output "struct <link linkend='v4l2-output'>v4l2_output</link>"> <!ENTITY v4l2-outputparm "struct <link linkend='v4l2-outputparm'>v4l2_outputparm</link>"> <!ENTITY v4l2-pix-format "struct <link linkend='v4l2-pix-format'>v4l2_pix_format</link>"> +<!ENTITY v4l2-pix-format-mplane "struct <link linkend='v4l2-pix-format-mplane'>v4l2_pix_format_mplane</link>"> +<!ENTITY v4l2-plane-pix-format "struct <link linkend='v4l2-plane-pix-format'>v4l2_plane_pix_format</link>"> <!ENTITY v4l2-queryctrl "struct <link linkend='v4l2-queryctrl'>v4l2_queryctrl</link>"> <!ENTITY v4l2-querymenu "struct <link linkend='v4l2-querymenu'>v4l2_querymenu</link>"> <!ENTITY v4l2-rect "struct <link linkend='v4l2-rect'>v4l2_rect</link>"> @@ -174,6 +197,12 @@ <!ENTITY v4l2-sliced-vbi-cap "struct <link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link>"> <!ENTITY v4l2-sliced-vbi-data "struct <link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link>"> <!ENTITY v4l2-sliced-vbi-format "struct <link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link>"> +<!ENTITY v4l2-subdev-frame-interval "struct <link linkend='v4l2-subdev-frame-interval'>v4l2_subdev_frame_interval</link>"> +<!ENTITY v4l2-subdev-frame-interval-enum "struct <link linkend='v4l2-subdev-frame-interval-enum'>v4l2_subdev_frame_interval_enum</link>"> +<!ENTITY v4l2-subdev-frame-size-enum "struct <link linkend='v4l2-subdev-frame-size-enum'>v4l2_subdev_frame_size_enum</link>"> +<!ENTITY v4l2-subdev-crop "struct <link linkend='v4l2-subdev-crop'>v4l2_subdev_crop</link>"> +<!ENTITY v4l2-subdev-format "struct <link linkend='v4l2-subdev-format'>v4l2_subdev_format</link>"> +<!ENTITY v4l2-subdev-mbus-code-enum "struct <link linkend='v4l2-subdev-mbus-code-enum'>v4l2_subdev_mbus_code_enum</link>"> <!ENTITY v4l2-standard "struct <link linkend='v4l2-standard'>v4l2_standard</link>"> <!ENTITY v4l2-streamparm "struct <link linkend='v4l2-streamparm'>v4l2_streamparm</link>"> <!ENTITY v4l2-timecode "struct <link linkend='v4l2-timecode'>v4l2_timecode</link>"> @@ -181,6 +210,12 @@ <!ENTITY v4l2-vbi-format "struct <link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>"> <!ENTITY v4l2-window "struct <link linkend='v4l2-window'>v4l2_window</link>"> +<!ENTITY media-device-info "struct <link linkend='media-device-info'>media_device_info</link>"> +<!ENTITY media-entity-desc "struct <link linkend='media-entity-desc'>media_entity_desc</link>"> +<!ENTITY media-links-enum "struct <link linkend='media-links-enum'>media_links_enum</link>"> +<!ENTITY media-pad-desc "struct <link linkend='media-pad-desc'>media_pad_desc</link>"> +<!ENTITY media-link-desc "struct <link linkend='media-link-desc'>media_link_desc</link>"> + <!-- Error Codes --> <!ENTITY EACCES "<errorcode>EACCES</errorcode> error code"> <!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code"> @@ -197,11 +232,13 @@ <!ENTITY ENXIO "<errorcode>ENXIO</errorcode> error code"> <!ENTITY EMFILE "<errorcode>EMFILE</errorcode> error code"> <!ENTITY EPERM "<errorcode>EPERM</errorcode> error code"> +<!ENTITY EPIPE "<errorcode>EPIPE</errorcode> error code"> <!ENTITY ERANGE "<errorcode>ERANGE</errorcode> error code"> <!-- Subsections --> <!ENTITY sub-biblio SYSTEM "v4l/biblio.xml"> <!ENTITY sub-common SYSTEM "v4l/common.xml"> +<!ENTITY sub-planar-apis SYSTEM "v4l/planar-apis.xml"> <!ENTITY sub-compat SYSTEM "v4l/compat.xml"> <!ENTITY sub-controls SYSTEM "v4l/controls.xml"> <!ENTITY sub-dev-capture SYSTEM "v4l/dev-capture.xml"> @@ -215,6 +252,7 @@ <!ENTITY sub-dev-raw-vbi SYSTEM "v4l/dev-raw-vbi.xml"> <!ENTITY sub-dev-rds SYSTEM "v4l/dev-rds.xml"> <!ENTITY sub-dev-sliced-vbi SYSTEM "v4l/dev-sliced-vbi.xml"> +<!ENTITY sub-dev-subdev SYSTEM "v4l/dev-subdev.xml"> <!ENTITY sub-dev-teletext SYSTEM "v4l/dev-teletext.xml"> <!ENTITY sub-driver SYSTEM "v4l/driver.xml"> <!ENTITY sub-libv4l SYSTEM "v4l/libv4l.xml"> @@ -233,6 +271,8 @@ <!ENTITY sub-io SYSTEM "v4l/io.xml"> <!ENTITY sub-grey SYSTEM "v4l/pixfmt-grey.xml"> <!ENTITY sub-nv12 SYSTEM "v4l/pixfmt-nv12.xml"> +<!ENTITY sub-nv12m SYSTEM "v4l/pixfmt-nv12m.xml"> +<!ENTITY sub-nv12mt SYSTEM "v4l/pixfmt-nv12mt.xml"> <!ENTITY sub-nv16 SYSTEM "v4l/pixfmt-nv16.xml"> <!ENTITY sub-packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml"> <!ENTITY sub-packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml"> @@ -247,9 +287,13 @@ <!ENTITY sub-yuv410 SYSTEM "v4l/pixfmt-yuv410.xml"> <!ENTITY sub-yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml"> <!ENTITY sub-yuv420 SYSTEM "v4l/pixfmt-yuv420.xml"> +<!ENTITY sub-yuv420m SYSTEM "v4l/pixfmt-yuv420m.xml"> <!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"> @@ -295,6 +339,13 @@ <!ENTITY sub-reqbufs SYSTEM "v4l/vidioc-reqbufs.xml"> <!ENTITY sub-s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml"> <!ENTITY sub-streamon SYSTEM "v4l/vidioc-streamon.xml"> +<!ENTITY sub-subdev-enum-frame-interval SYSTEM "v4l/vidioc-subdev-enum-frame-interval.xml"> +<!ENTITY sub-subdev-enum-frame-size SYSTEM "v4l/vidioc-subdev-enum-frame-size.xml"> +<!ENTITY sub-subdev-enum-mbus-code SYSTEM "v4l/vidioc-subdev-enum-mbus-code.xml"> +<!ENTITY sub-subdev-formats SYSTEM "v4l/subdev-formats.xml"> +<!ENTITY sub-subdev-g-crop SYSTEM "v4l/vidioc-subdev-g-crop.xml"> +<!ENTITY sub-subdev-g-fmt SYSTEM "v4l/vidioc-subdev-g-fmt.xml"> +<!ENTITY sub-subdev-g-frame-interval SYSTEM "v4l/vidioc-subdev-g-frame-interval.xml"> <!ENTITY sub-capture-c SYSTEM "v4l/capture.c.xml"> <!ENTITY sub-keytable-c SYSTEM "v4l/keytable.c.xml"> <!ENTITY sub-v4l2grab-c SYSTEM "v4l/v4l2grab.c.xml"> @@ -318,6 +369,15 @@ <!ENTITY sub-media-entities SYSTEM "media-entities.tmpl"> <!ENTITY sub-media-indices SYSTEM "media-indices.tmpl"> +<!ENTITY sub-media-controller SYSTEM "v4l/media-controller.xml"> +<!ENTITY sub-media-open SYSTEM "v4l/media-func-open.xml"> +<!ENTITY sub-media-close SYSTEM "v4l/media-func-close.xml"> +<!ENTITY sub-media-ioctl SYSTEM "v4l/media-func-ioctl.xml"> +<!ENTITY sub-media-ioc-device-info SYSTEM "v4l/media-ioc-device-info.xml"> +<!ENTITY sub-media-ioc-enum-entities SYSTEM "v4l/media-ioc-enum-entities.xml"> +<!ENTITY sub-media-ioc-enum-links SYSTEM "v4l/media-ioc-enum-links.xml"> +<!ENTITY sub-media-ioc-setup-link SYSTEM "v4l/media-ioc-setup-link.xml"> + <!-- Function Reference --> <!ENTITY close SYSTEM "v4l/func-close.xml"> <!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml"> @@ -330,6 +390,7 @@ <!ENTITY write SYSTEM "v4l/func-write.xml"> <!ENTITY grey SYSTEM "v4l/pixfmt-grey.xml"> <!ENTITY nv12 SYSTEM "v4l/pixfmt-nv12.xml"> +<!ENTITY nv12m SYSTEM "v4l/pixfmt-nv12m.xml"> <!ENTITY nv16 SYSTEM "v4l/pixfmt-nv16.xml"> <!ENTITY packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml"> <!ENTITY packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml"> @@ -344,9 +405,13 @@ <!ENTITY yuv410 SYSTEM "v4l/pixfmt-yuv410.xml"> <!ENTITY yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml"> <!ENTITY yuv420 SYSTEM "v4l/pixfmt-yuv420.xml"> +<!ENTITY yuv420m SYSTEM "v4l/pixfmt-yuv420m.xml"> <!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 f11048d4053f..88f2cc680cc2 100644 --- a/Documentation/DocBook/media.tmpl +++ b/Documentation/DocBook/media.tmpl @@ -28,7 +28,7 @@ <title>LINUX MEDIA INFRASTRUCTURE API</title> <copyright> - <year>2009-2010</year> + <year>2009-2011</year> <holder>LinuxTV Developers</holder> </copyright> @@ -86,7 +86,7 @@ Foundation. A copy of the license is included in the chapter entitled </author> </authorgroup> <copyright> - <year>2009-2010</year> + <year>2009-2011</year> <holder>Mauro Carvalho Chehab</holder> </copyright> @@ -106,6 +106,9 @@ Foundation. A copy of the license is included in the chapter entitled &sub-remote_controllers; </chapter> </part> +<part id="media_common"> +&sub-media-controller; +</part> &sub-fdl-appendix; diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl index 020ac80d4682..6f242d5dee9a 100644 --- a/Documentation/DocBook/mtdnand.tmpl +++ b/Documentation/DocBook/mtdnand.tmpl @@ -250,7 +250,7 @@ static void board_hwcontrol(struct mtd_info *mtd, int cmd) <title>Device ready function</title> <para> If the hardware interface has the ready busy pin of the NAND chip connected to a - GPIO or other accesible I/O pin, this function is used to read back the state of the + GPIO or other accessible I/O pin, this function is used to read back the state of the pin. The function has no arguments and should return 0, if the device is busy (R/B pin is low) and 1, if the device is ready (R/B pin is high). If the hardware interface does not give access to the ready busy pin, then @@ -485,7 +485,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) Reed-Solomon library. </para> <para> - The ECC bytes must be placed immidiately after the data + The ECC bytes must be placed immediately after the data bytes in order to make the syndrome generator work. This is contrary to the usual layout used by software ECC. The separation of data and out of band area is not longer @@ -629,7 +629,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) holds the bad block table. Store a pointer to the pattern in the pattern field. Further the length of the pattern has to be stored in len and the offset in the spare area must be given - in the offs member of the nand_bbt_descr stucture. For mirrored + in the offs member of the nand_bbt_descr structure. For mirrored bad block tables different patterns are mandatory.</para></listitem> <listitem><para>Table creation</para> <para>Set the option NAND_BBT_CREATE to enable the table creation @@ -648,7 +648,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) <listitem><para>Table version control</para> <para>Set the option NAND_BBT_VERSION to enable the table version control. It's highly recommended to enable this for mirrored tables with write - support. It makes sure that the risk of loosing the bad block + support. It makes sure that the risk of losing the bad block table information is reduced to the loss of the information about the one worn out block which should be marked bad. The version is stored in 4 consecutive bytes in the spare area of the device. The position of @@ -1060,19 +1060,19 @@ data in this page</entry> <row> <entry>0x3D</entry> <entry>ECC byte 21</entry> -<entry>Error correction code byte 0 of the eigth 256 Bytes of data +<entry>Error correction code byte 0 of the eighth 256 Bytes of data in this page</entry> </row> <row> <entry>0x3E</entry> <entry>ECC byte 22</entry> -<entry>Error correction code byte 1 of the eigth 256 Bytes of data +<entry>Error correction code byte 1 of the eighth 256 Bytes of data in this page</entry> </row> <row> <entry>0x3F</entry> <entry>ECC byte 23</entry> -<entry>Error correction code byte 2 of the eigth 256 Bytes of data +<entry>Error correction code byte 2 of the eighth 256 Bytes of data in this page</entry> </row> </tbody></tgroup></informaltable> diff --git a/Documentation/DocBook/rapidio.tmpl b/Documentation/DocBook/rapidio.tmpl index 54eb26b57372..50479360d845 100644 --- a/Documentation/DocBook/rapidio.tmpl +++ b/Documentation/DocBook/rapidio.tmpl @@ -133,7 +133,6 @@ !Idrivers/rapidio/rio-sysfs.c </sect1> <sect1 id="PPC32_support"><title>PPC32 support</title> -!Earch/powerpc/sysdev/fsl_rio.c !Iarch/powerpc/sysdev/fsl_rio.c </sect1> </chapter> diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl index 53f4f8d3b810..346e552fa2cc 100644 --- a/Documentation/DocBook/regulator.tmpl +++ b/Documentation/DocBook/regulator.tmpl @@ -267,8 +267,8 @@ <sect1 id="machine-constraint"> <title>Constraints</title> <para> - As well as definining the connections the machine interface - also provides constraints definining the operations that + As well as defining the connections the machine interface + also provides constraints defining the operations that clients are allowed to perform and the parameters that may be set. This is required since generally regulator devices will offer more flexibility than it is safe to use on a given diff --git a/Documentation/DocBook/sh.tmpl b/Documentation/DocBook/sh.tmpl index d858d92cf6d9..4a38f604fa66 100644 --- a/Documentation/DocBook/sh.tmpl +++ b/Documentation/DocBook/sh.tmpl @@ -79,10 +79,6 @@ </sect2> </sect1> </chapter> - <chapter id="clk"> - <title>Clock Framework Extensions</title> -!Iinclude/linux/sh_clk.h - </chapter> <chapter id="mach"> <title>Machine Specific Interfaces</title> <sect1 id="dreamcast"> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index 4d4ce0e61e42..7c4b514d62b1 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -16,7 +16,7 @@ </orgname> <address> - <email>hjk@linutronix.de</email> + <email>hjk@hansjkoch.de</email> </address> </affiliation> </author> @@ -114,7 +114,7 @@ GPL version 2. <para>If you know of any translations for this document, or you are interested in translating it, please email me -<email>hjk@linutronix.de</email>. +<email>hjk@hansjkoch.de</email>. </para> </sect1> @@ -171,7 +171,7 @@ interested in translating it, please email me <title>Feedback</title> <para>Find something wrong with this document? (Or perhaps something right?) I would love to hear from you. Please email me at - <email>hjk@linutronix.de</email>.</para> + <email>hjk@hansjkoch.de</email>.</para> </sect1> </chapter> @@ -797,7 +797,7 @@ framework to set up sysfs files for this region. Simply leave it alone. perform some initialization. After that, your hardware starts working and will generate an interrupt as soon as it's finished, has some data available, or needs your - attention because an error occured. + attention because an error occurred. </para> <para> <filename>/dev/uioX</filename> is a read-only file. A diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl index af293606fbe3..8d57c1888dca 100644 --- a/Documentation/DocBook/usb.tmpl +++ b/Documentation/DocBook/usb.tmpl @@ -690,7 +690,7 @@ usbdev_ioctl (int fd, int ifno, unsigned request, void *param) </para><para> This request lets kernel drivers talk to user mode code through filesystem operations even when they don't create - a charactor or block special device. + a character or block special device. It's also been used to do things like ask devices what device special file should be used. Two pre-defined ioctls are used diff --git a/Documentation/DocBook/v4l/bayer.pdf b/Documentation/DocBook/v4l/bayer.pdf Binary files differnew file mode 100644 index 000000000000..905e60e6cd42 --- /dev/null +++ b/Documentation/DocBook/v4l/bayer.pdf diff --git a/Documentation/DocBook/v4l/bayer.png b/Documentation/DocBook/v4l/bayer.png Binary files differnew file mode 100644 index 000000000000..9b15fb22e817 --- /dev/null +++ b/Documentation/DocBook/v4l/bayer.png diff --git a/Documentation/DocBook/v4l/common.xml b/Documentation/DocBook/v4l/common.xml index cea23e1c4fc6..9028721438dc 100644 --- a/Documentation/DocBook/v4l/common.xml +++ b/Documentation/DocBook/v4l/common.xml @@ -100,7 +100,7 @@ linux-kernel@vger.kernel.org, 2002-11-20. --></para> <para>By convention system administrators create various character device special files with these major and minor numbers in -the <filename>/dev</filename> directory. The names recomended for the +the <filename>/dev</filename> directory. The names recommended for the different V4L2 device types are listed in <xref linkend="devices" />. </para> @@ -846,6 +846,8 @@ conversion routine or library for integration into applications.</para> </section> </section> + &sub-planar-apis; + <section id="crop"> <title>Image Cropping, Insertion and Scaling</title> diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml index 54447f0d0784..9f7cd4f25792 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 @@ -1714,8 +1711,8 @@ ioctl would enumerate the available audio inputs. An ioctl to determine the current audio input, if more than one combines with the current video input, did not exist. So <constant>VIDIOC_G_AUDIO</constant> was renamed to -<constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl will be removed in -the future. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate +<constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl was removed on +Kernel 2.6.39. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio input.</para> <para>The same changes were made to &VIDIOC-G-AUDOUT; and @@ -1729,7 +1726,7 @@ must be updated to successfully compile again.</para> <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with write-read parameter. It was changed to write-only, while the write-read version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old -ioctl will be removed in the future. Until further the "videodev" +ioctl was removed on Kernel 2.6.39. Until further the "videodev" kernel module will automatically translate to the new version, so drivers must be recompiled, but not applications.</para> </listitem> @@ -1747,7 +1744,7 @@ surface can be seen.</para> defined with write-only parameter, inconsistent with other ioctls modifying their argument. They were changed to write-read, while a <constant>_OLD</constant> suffix was added to the write-only versions. -The old ioctls will be removed in the future. Drivers and +The old ioctls were removed on Kernel 2.6.39. Drivers and applications assuming a constant parameter need an update.</para> </listitem> </orderedlist> @@ -1818,8 +1815,8 @@ yet to be addressed, for details see <xref <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined with read-only parameter. It is now defined as write-read ioctl, while the read-only version was renamed to -<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl will be removed -in the future.</para> +<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl was removed +on Kernel 2.6.39.</para> </listitem> </orderedlist> </section> @@ -2345,6 +2342,31 @@ 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> + <title>V4L2 in Linux 2.6.39</title> + <orderedlist> + <listitem> + <para>The old VIDIOC_*_OLD symbols and V4L1 support were removed.</para> + </listitem> + <listitem> + <para>Multi-planar API added. Does not affect the compatibility of + current drivers and applications. See + <link linkend="planar-apis">multi-planar API</link> + for details.</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 8408caaee276..a920ee80f640 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); } } } @@ -1239,7 +1243,7 @@ values are:</entry> </row><row><entry spanname="descr">Mutes the audio when capturing. This is not done by muting audio hardware, which can still produce a slight hiss, but in the encoder itself, guaranteeing a fixed -and reproducable audio bitstream. 0 = unmuted, 1 = muted.</entry> +and reproducible audio bitstream. 0 = unmuted, 1 = muted.</entry> </row> <row><entry></entry></row> <row id="v4l2-mpeg-video-encoding"> diff --git a/Documentation/DocBook/v4l/dev-capture.xml b/Documentation/DocBook/v4l/dev-capture.xml index 32807e43f170..2237c661f26a 100644 --- a/Documentation/DocBook/v4l/dev-capture.xml +++ b/Documentation/DocBook/v4l/dev-capture.xml @@ -18,7 +18,8 @@ files are used for video output devices.</para> <title>Querying Capabilities</title> <para>Devices supporting the video capture interface set the -<constant>V4L2_CAP_VIDEO_CAPTURE</constant> flag in the +<constant>V4L2_CAP_VIDEO_CAPTURE</constant> or +<constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant> flag in the <structfield>capabilities</structfield> field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions they may also support the <link linkend="overlay">video overlay</link> @@ -64,9 +65,11 @@ linkend="crop" />.</para> <para>To query the current image format applications set the <structfield>type</structfield> field of a &v4l2-format; to -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and call the +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and call the &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill -the &v4l2-pix-format; <structfield>pix</structfield> member of the +the &v4l2-pix-format; <structfield>pix</structfield> or the +&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the <structfield>fmt</structfield> union.</para> <para>To request different parameters applications set the @@ -84,8 +87,8 @@ adjust the parameters and finally return the actual parameters as without disabling I/O or possibly time consuming hardware preparations.</para> - <para>The contents of &v4l2-pix-format; are discussed in <xref -linkend="pixfmt" />. See also the specification of the + <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane; +are discussed in <xref linkend="pixfmt" />. See also the specification of the <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video capture devices must implement both the diff --git a/Documentation/DocBook/v4l/dev-output.xml b/Documentation/DocBook/v4l/dev-output.xml index 63c3c20e5a72..919e22c53854 100644 --- a/Documentation/DocBook/v4l/dev-output.xml +++ b/Documentation/DocBook/v4l/dev-output.xml @@ -17,7 +17,8 @@ files are used for video capture devices.</para> <title>Querying Capabilities</title> <para>Devices supporting the video output interface set the -<constant>V4L2_CAP_VIDEO_OUTPUT</constant> flag in the +<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or +<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the <structfield>capabilities</structfield> field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions they may also support the <link linkend="raw-vbi">raw VBI @@ -60,9 +61,11 @@ linkend="crop" />.</para> <para>To query the current image format applications set the <structfield>type</structfield> field of a &v4l2-format; to -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and call the +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill -the &v4l2-pix-format; <structfield>pix</structfield> member of the +the &v4l2-pix-format; <structfield>pix</structfield> or the +&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the <structfield>fmt</structfield> union.</para> <para>To request different parameters applications set the @@ -80,8 +83,8 @@ adjust the parameters and finally return the actual parameters as without disabling I/O or possibly time consuming hardware preparations.</para> - <para>The contents of &v4l2-pix-format; are discussed in <xref -linkend="pixfmt" />. See also the specification of the + <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane; +are discussed in <xref linkend="pixfmt" />. See also the specification of the <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video output devices must implement both the diff --git a/Documentation/DocBook/v4l/dev-rds.xml b/Documentation/DocBook/v4l/dev-rds.xml index 0869d701b1e5..2427f54397e7 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,32 @@ 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> + <title>RDS datastructures</title> <table frame="none" pgwide="1" id="v4l2-rds-data"> <title>struct <structname>v4l2_rds_data</structname></title> @@ -104,55 +130,65 @@ as follows:</para> <table frame="none" pgwide="1" id="v4l2-rds-block-codes"> <title>Block defines</title> - <tgroup cols="3"> + <tgroup cols="4"> <colspec colname="c1" colwidth="1*" /> <colspec colname="c2" colwidth="1*" /> - <colspec colname="c3" colwidth="5*" /> + <colspec colname="c3" colwidth="1*" /> + <colspec colname="c4" colwidth="5*" /> <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-subdev.xml b/Documentation/DocBook/v4l/dev-subdev.xml new file mode 100644 index 000000000000..05c8fefcbcbe --- /dev/null +++ b/Documentation/DocBook/v4l/dev-subdev.xml @@ -0,0 +1,313 @@ + <title>Sub-device Interface</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental">experimental</link> + interface and may change in the future.</para> + </note> + + <para>The complex nature of V4L2 devices, where hardware is often made of + several integrated circuits that need to interact with each other in a + controlled way, leads to complex V4L2 drivers. The drivers usually reflect + the hardware model in software, and model the different hardware components + as software blocks called sub-devices.</para> + + <para>V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver + implements the media device API, they will automatically inherit from media + entities. Applications will be able to enumerate the sub-devices and discover + the hardware topology using the media entities, pads and links enumeration + API.</para> + + <para>In addition to make sub-devices discoverable, drivers can also choose + to make them directly configurable by applications. When both the sub-device + driver and the V4L2 device driver support this, sub-devices will feature a + character device node on which ioctls can be called to + <itemizedlist> + <listitem><para>query, read and write sub-devices controls</para></listitem> + <listitem><para>subscribe and unsubscribe to events and retrieve them</para></listitem> + <listitem><para>negotiate image formats on individual pads</para></listitem> + </itemizedlist> + </para> + + <para>Sub-device character device nodes, conventionally named + <filename>/dev/v4l-subdev*</filename>, use major number 81.</para> + + <section> + <title>Controls</title> + <para>Most V4L2 controls are implemented by sub-device hardware. Drivers + usually merge all controls and expose them through video device nodes. + Applications can control all sub-devices through a single interface.</para> + + <para>Complex devices sometimes implement the same control in different + pieces of hardware. This situation is common in embedded platforms, where + both sensors and image processing hardware implement identical functions, + such as contrast adjustment, white balance or faulty pixels correction. As + the V4L2 controls API doesn't support several identical controls in a single + device, all but one of the identical controls are hidden.</para> + + <para>Applications can access those hidden controls through the sub-device + node with the V4L2 control API described in <xref linkend="control" />. The + ioctls behave identically as when issued on V4L2 device nodes, with the + exception that they deal only with controls implemented in the sub-device. + </para> + + <para>Depending on the driver, those controls might also be exposed through + one (or several) V4L2 device nodes.</para> + </section> + + <section> + <title>Events</title> + <para>V4L2 sub-devices can notify applications of events as described in + <xref linkend="event" />. The API behaves identically as when used on V4L2 + device nodes, with the exception that it only deals with events generated by + the sub-device. Depending on the driver, those events might also be reported + on one (or several) V4L2 device nodes.</para> + </section> + + <section id="pad-level-formats"> + <title>Pad-level Formats</title> + + <warning><para>Pad-level formats are only applicable to very complex device that + need to expose low-level format configuration to user space. Generic V4L2 + applications do <emphasis>not</emphasis> need to use the API described in + this section.</para></warning> + + <note><para>For the purpose of this section, the term + <wordasword>format</wordasword> means the combination of media bus data + format, frame width and frame height.</para></note> + + <para>Image formats are typically negotiated on video capture and output + devices using the <link linkend="crop">cropping and scaling</link> ioctls. + The driver is responsible for configuring every block in the video pipeline + according to the requested format at the pipeline input and/or + output.</para> + + <para>For complex devices, such as often found in embedded systems, + identical image sizes at the output of a pipeline can be achieved using + different hardware configurations. One such example is shown on + <xref linkend="pipeline-scaling" />, where + image scaling can be performed on both the video sensor and the host image + processing hardware.</para> + + <figure id="pipeline-scaling"> + <title>Image Format Negotiation on Pipelines</title> + <mediaobject> + <imageobject> + <imagedata fileref="pipeline.pdf" format="PS" /> + </imageobject> + <imageobject> + <imagedata fileref="pipeline.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>High quality and high speed pipeline configuration</phrase> + </textobject> + </mediaobject> + </figure> + + <para>The sensor scaler is usually of less quality than the host scaler, but + scaling on the sensor is required to achieve higher frame rates. Depending + on the use case (quality vs. speed), the pipeline must be configured + differently. Applications need to configure the formats at every point in + the pipeline explicitly.</para> + + <para>Drivers that implement the <link linkend="media-controller-intro">media + API</link> can expose pad-level image format configuration to applications. + When they do, applications can use the &VIDIOC-SUBDEV-G-FMT; and + &VIDIOC-SUBDEV-S-FMT; ioctls. to negotiate formats on a per-pad basis.</para> + + <para>Applications are responsible for configuring coherent parameters on + the whole pipeline and making sure that connected pads have compatible + formats. The pipeline is checked for formats mismatch at &VIDIOC-STREAMON; + time, and an &EPIPE; is then returned if the configuration is + invalid.</para> + + <para>Pad-level image format configuration support can be tested by calling + the &VIDIOC-SUBDEV-G-FMT; ioctl on pad 0. If the driver returns an &EINVAL; + pad-level format configuration is not supported by the sub-device.</para> + + <section> + <title>Format Negotiation</title> + + <para>Acceptable formats on pads can (and usually do) depend on a number + of external parameters, such as formats on other pads, active links, or + even controls. Finding a combination of formats on all pads in a video + pipeline, acceptable to both application and driver, can't rely on formats + enumeration only. A format negotiation mechanism is required.</para> + + <para>Central to the format negotiation mechanism are the get/set format + operations. When called with the <structfield>which</structfield> argument + set to <constant>V4L2_SUBDEV_FORMAT_TRY</constant>, the + &VIDIOC-SUBDEV-G-FMT; and &VIDIOC-SUBDEV-S-FMT; ioctls operate on a set of + formats parameters that are not connected to the hardware configuration. + Modifying those 'try' formats leaves the device state untouched (this + applies to both the software state stored in the driver and the hardware + state stored in the device itself).</para> + + <para>While not kept as part of the device state, try formats are stored + in the sub-device file handles. A &VIDIOC-SUBDEV-G-FMT; call will return + the last try format set <emphasis>on the same sub-device file + handle</emphasis>. Several applications querying the same sub-device at + the same time will thus not interact with each other.</para> + + <para>To find out whether a particular format is supported by the device, + applications use the &VIDIOC-SUBDEV-S-FMT; ioctl. Drivers verify and, if + needed, change the requested <structfield>format</structfield> based on + device requirements and return the possibly modified value. Applications + can then choose to try a different format or accept the returned value and + continue.</para> + + <para>Formats returned by the driver during a negotiation iteration are + guaranteed to be supported by the device. In particular, drivers guarantee + that a returned format will not be further changed if passed to an + &VIDIOC-SUBDEV-S-FMT; call as-is (as long as external parameters, such as + formats on other pads or links' configuration are not changed).</para> + + <para>Drivers automatically propagate formats inside sub-devices. When a + try or active format is set on a pad, corresponding formats on other pads + of the same sub-device can be modified by the driver. Drivers are free to + modify formats as required by the device. However, they should comply with + the following rules when possible: + <itemizedlist> + <listitem><para>Formats should be propagated from sink pads to source pads. + Modifying a format on a source pad should not modify the format on any + sink pad.</para></listitem> + <listitem><para>Sub-devices that scale frames using variable scaling factors + should reset the scale factors to default values when sink pads formats + are modified. If the 1:1 scaling ratio is supported, this means that + source pads formats should be reset to the sink pads formats.</para></listitem> + </itemizedlist> + </para> + + <para>Formats are not propagated across links, as that would involve + propagating them from one sub-device file handle to another. Applications + must then take care to configure both ends of every link explicitly with + compatible formats. Identical formats on the two ends of a link are + guaranteed to be compatible. Drivers are free to accept different formats + matching device requirements as being compatible.</para> + + <para><xref linkend="sample-pipeline-config" /> + shows a sample configuration sequence for the pipeline described in + <xref linkend="pipeline-scaling" /> (table + columns list entity names and pad numbers).</para> + + <table pgwide="0" frame="none" id="sample-pipeline-config"> + <title>Sample Pipeline Configuration</title> + <tgroup cols="3"> + <colspec colname="what"/> + <colspec colname="sensor-0" /> + <colspec colname="frontend-0" /> + <colspec colname="frontend-1" /> + <colspec colname="scaler-0" /> + <colspec colname="scaler-1" /> + <thead> + <row> + <entry></entry> + <entry>Sensor/0</entry> + <entry>Frontend/0</entry> + <entry>Frontend/1</entry> + <entry>Scaler/0</entry> + <entry>Scaler/1</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Initial state</entry> + <entry>2048x1536</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + </row> + <row> + <entry>Configure frontend input</entry> + <entry>2048x1536</entry> + <entry><emphasis>2048x1536</emphasis></entry> + <entry><emphasis>2046x1534</emphasis></entry> + <entry>-</entry> + <entry>-</entry> + </row> + <row> + <entry>Configure scaler input</entry> + <entry>2048x1536</entry> + <entry>2048x1536</entry> + <entry>2046x1534</entry> + <entry><emphasis>2046x1534</emphasis></entry> + <entry><emphasis>2046x1534</emphasis></entry> + </row> + <row> + <entry>Configure scaler output</entry> + <entry>2048x1536</entry> + <entry>2048x1536</entry> + <entry>2046x1534</entry> + <entry>2046x1534</entry> + <entry><emphasis>1280x960</emphasis></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + <orderedlist> + <listitem><para>Initial state. The sensor output is set to its native 3MP + resolution. Resolutions on the host frontend and scaler input and output + pads are undefined.</para></listitem> + <listitem><para>The application configures the frontend input pad resolution to + 2048x1536. The driver propagates the format to the frontend output pad. + Note that the propagated output format can be different, as in this case, + than the input format, as the hardware might need to crop pixels (for + instance when converting a Bayer filter pattern to RGB or YUV).</para></listitem> + <listitem><para>The application configures the scaler input pad resolution to + 2046x1534 to match the frontend output resolution. The driver propagates + the format to the scaler output pad.</para></listitem> + <listitem><para>The application configures the scaler output pad resolution to + 1280x960.</para></listitem> + </orderedlist> + </para> + + <para>When satisfied with the try results, applications can set the active + formats by setting the <structfield>which</structfield> argument to + <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. Active formats are changed + exactly as try formats by drivers. To avoid modifying the hardware state + during format negotiation, applications should negotiate try formats first + and then modify the active settings using the try formats returned during + the last negotiation iteration. This guarantees that the active format + will be applied as-is by the driver without being modified. + </para> + </section> + + <section> + <title>Cropping and scaling</title> + + <para>Many sub-devices support cropping frames on their input or output + pads (or possible even on both). Cropping is used to select the area of + interest in an image, typically on a video sensor or video decoder. It can + also be used as part of digital zoom implementations to select the area of + the image that will be scaled up.</para> + + <para>Crop settings are defined by a crop rectangle and represented in a + &v4l2-rect; by the coordinates of the top left corner and the rectangle + size. Both the coordinates and sizes are expressed in pixels.</para> + + <para>The crop rectangle is retrieved and set using the + &VIDIOC-SUBDEV-G-CROP; and &VIDIOC-SUBDEV-S-CROP; ioctls. Like for pad + formats, drivers store try and active crop rectangles. The format + negotiation mechanism applies to crop settings as well.</para> + + <para>On input pads, cropping is applied relatively to the current pad + format. The pad format represents the image size as received by the + sub-device from the previous block in the pipeline, and the crop rectangle + represents the sub-image that will be transmitted further inside the + sub-device for processing. The crop rectangle be entirely containted + inside the input image size.</para> + + <para>Input crop rectangle are reset to their default value when the input + image format is modified. Drivers should use the input image size as the + crop rectangle default value, but hardware requirements may prevent this. + </para> + + <para>Cropping behaviour on output pads is not defined.</para> + + </section> + </section> + + &sub-subdev-formats; diff --git a/Documentation/DocBook/v4l/dev-teletext.xml b/Documentation/DocBook/v4l/dev-teletext.xml index 76184e8ed618..414b1cfff9f4 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/func-ioctl.xml b/Documentation/DocBook/v4l/func-ioctl.xml index 00f9690e1c28..b60fd37a6295 100644 --- a/Documentation/DocBook/v4l/func-ioctl.xml +++ b/Documentation/DocBook/v4l/func-ioctl.xml @@ -34,8 +34,7 @@ <varlistentry> <term><parameter>request</parameter></term> <listitem> - <para>V4L2 ioctl request code as defined in the <link -linkend="videodev">videodev.h</link> header file, for example + <para>V4L2 ioctl request code as defined in the <filename>videodev2.h</filename> header file, for example VIDIOC_QUERYCAP.</para> </listitem> </varlistentry> @@ -57,7 +56,7 @@ file descriptor. An ioctl <parameter>request</parameter> has encoded in it whether the argument is an input, output or read/write parameter, and the size of the argument <parameter>argp</parameter> in bytes. Macros and defines specifying V4L2 ioctl requests are located -in the <link linkend="videodev">videodev.h</link> header file. +in the <filename>videodev2.h</filename> header file. Applications should use their own copy, not include the version in the kernel sources on the system they compile on. All V4L2 ioctl requests, their respective function and parameters are specified in <xref diff --git a/Documentation/DocBook/v4l/func-mmap.xml b/Documentation/DocBook/v4l/func-mmap.xml index 2e2fc3933aea..786732b64bbd 100644 --- a/Documentation/DocBook/v4l/func-mmap.xml +++ b/Documentation/DocBook/v4l/func-mmap.xml @@ -45,7 +45,10 @@ just specify a <constant>NULL</constant> pointer here.</para> <listitem> <para>Length of the memory area to map. This must be the same value as returned by the driver in the &v4l2-buffer; -<structfield>length</structfield> field.</para> +<structfield>length</structfield> field for the +single-planar API, and the same value as returned by the driver +in the &v4l2-plane; <structfield>length</structfield> field for the +multi-planar API.</para> </listitem> </varlistentry> <varlistentry> @@ -106,7 +109,10 @@ flag.</para> <listitem> <para>Offset of the buffer in device memory. This must be the same value as returned by the driver in the &v4l2-buffer; -<structfield>m</structfield> union <structfield>offset</structfield> field.</para> +<structfield>m</structfield> union <structfield>offset</structfield> field for +the single-planar API, and the same value as returned by the driver +in the &v4l2-plane; <structfield>m</structfield> union +<structfield>mem_offset</structfield> field for the multi-planar API.</para> </listitem> </varlistentry> </variablelist> diff --git a/Documentation/DocBook/v4l/func-munmap.xml b/Documentation/DocBook/v4l/func-munmap.xml index 502ed49323b0..e2c4190f9bb6 100644 --- a/Documentation/DocBook/v4l/func-munmap.xml +++ b/Documentation/DocBook/v4l/func-munmap.xml @@ -37,7 +37,8 @@ <para>Length of the mapped buffer. This must be the same value as given to <function>mmap()</function> and returned by the driver in the &v4l2-buffer; <structfield>length</structfield> -field.</para> +field for the single-planar API and in the &v4l2-plane; +<structfield>length</structfield> field for the multi-planar API.</para> </listitem> </varlistentry> </variablelist> diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml index d424886beda0..227e7ac45a06 100644 --- a/Documentation/DocBook/v4l/io.xml +++ b/Documentation/DocBook/v4l/io.xml @@ -121,18 +121,22 @@ mapped.</para> <para>Before applications can access the buffers they must map them into their address space with the &func-mmap; function. The location of the buffers in device memory can be determined with the -&VIDIOC-QUERYBUF; ioctl. The <structfield>m.offset</structfield> and -<structfield>length</structfield> returned in a &v4l2-buffer; are -passed as sixth and second parameter to the -<function>mmap()</function> function. The offset and length values -must not be modified. Remember the buffers are allocated in physical -memory, as opposed to virtual memory which can be swapped out to disk. -Applications should free the buffers as soon as possible with the -&func-munmap; function.</para> +&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the +<structfield>m.offset</structfield> and <structfield>length</structfield> +returned in a &v4l2-buffer; are passed as sixth and second parameter to the +<function>mmap()</function> function. When using the multi-planar API, +struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each +containing its own <structfield>m.offset</structfield> and +<structfield>length</structfield>. When using the multi-planar API, every +plane of every buffer has to be mapped separately, so the number of +calls to &func-mmap; should be equal to number of buffers times number of +planes in each buffer. The offset and length values must not be modified. +Remember, the buffers are allocated in physical memory, as opposed to virtual +memory, which can be swapped out to disk. Applications should free the buffers +as soon as possible with the &func-munmap; function.</para> <example> - <title>Mapping buffers</title> - + <title>Mapping buffers in the single-planar API</title> <programlisting> &v4l2-requestbuffers; reqbuf; struct { @@ -141,63 +145,145 @@ struct { } *buffers; unsigned int i; -memset (&reqbuf, 0, sizeof (reqbuf)); +memset(&reqbuf, 0, sizeof(reqbuf)); reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; reqbuf.memory = V4L2_MEMORY_MMAP; reqbuf.count = 20; if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) { if (errno == EINVAL) - printf ("Video capturing or mmap-streaming is not supported\n"); + printf("Video capturing or mmap-streaming is not supported\n"); else - perror ("VIDIOC_REQBUFS"); + perror("VIDIOC_REQBUFS"); - exit (EXIT_FAILURE); + exit(EXIT_FAILURE); } /* We want at least five buffers. */ if (reqbuf.count < 5) { /* You may need to free the buffers here. */ - printf ("Not enough buffer memory\n"); - exit (EXIT_FAILURE); + printf("Not enough buffer memory\n"); + exit(EXIT_FAILURE); } -buffers = calloc (reqbuf.count, sizeof (*buffers)); -assert (buffers != NULL); +buffers = calloc(reqbuf.count, sizeof(*buffers)); +assert(buffers != NULL); for (i = 0; i < reqbuf.count; i++) { &v4l2-buffer; buffer; - memset (&buffer, 0, sizeof (buffer)); + memset(&buffer, 0, sizeof(buffer)); buffer.type = reqbuf.type; buffer.memory = V4L2_MEMORY_MMAP; buffer.index = i; if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &buffer)) { - perror ("VIDIOC_QUERYBUF"); - exit (EXIT_FAILURE); + perror("VIDIOC_QUERYBUF"); + exit(EXIT_FAILURE); } buffers[i].length = buffer.length; /* remember for munmap() */ - buffers[i].start = mmap (NULL, buffer.length, - PROT_READ | PROT_WRITE, /* recommended */ - MAP_SHARED, /* recommended */ - fd, buffer.m.offset); + buffers[i].start = mmap(NULL, buffer.length, + PROT_READ | PROT_WRITE, /* recommended */ + MAP_SHARED, /* recommended */ + fd, buffer.m.offset); if (MAP_FAILED == buffers[i].start) { /* If you do not exit here you should unmap() and free() the buffers mapped so far. */ - perror ("mmap"); - exit (EXIT_FAILURE); + perror("mmap"); + exit(EXIT_FAILURE); + } +} + +/* Cleanup. */ + +for (i = 0; i < reqbuf.count; i++) + munmap(buffers[i].start, buffers[i].length); + </programlisting> + </example> + + <example> + <title>Mapping buffers in the multi-planar API</title> + <programlisting> +&v4l2-requestbuffers; reqbuf; +/* Our current format uses 3 planes per buffer */ +#define FMT_NUM_PLANES = 3; + +struct { + void *start[FMT_NUM_PLANES]; + size_t length[FMT_NUM_PLANES]; +} *buffers; +unsigned int i, j; + +memset(&reqbuf, 0, sizeof(reqbuf)); +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; +reqbuf.memory = V4L2_MEMORY_MMAP; +reqbuf.count = 20; + +if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 0) { + if (errno == EINVAL) + printf("Video capturing or mmap-streaming is not supported\n"); + else + perror("VIDIOC_REQBUFS"); + + exit(EXIT_FAILURE); +} + +/* We want at least five buffers. */ + +if (reqbuf.count < 5) { + /* You may need to free the buffers here. */ + printf("Not enough buffer memory\n"); + exit(EXIT_FAILURE); +} + +buffers = calloc(reqbuf.count, sizeof(*buffers)); +assert(buffers != NULL); + +for (i = 0; i < reqbuf.count; i++) { + &v4l2-buffer; buffer; + &v4l2-plane; planes[FMT_NUM_PLANES]; + + memset(&buffer, 0, sizeof(buffer)); + buffer.type = reqbuf.type; + buffer.memory = V4L2_MEMORY_MMAP; + buffer.index = i; + /* length in struct v4l2_buffer in multi-planar API stores the size + * of planes array. */ + buffer.length = FMT_NUM_PLANES; + buffer.m.planes = planes; + + if (ioctl(fd, &VIDIOC-QUERYBUF;, &buffer) < 0) { + perror("VIDIOC_QUERYBUF"); + exit(EXIT_FAILURE); + } + + /* Every plane has to be mapped separately */ + for (j = 0; j < FMT_NUM_PLANES; j++) { + buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */ + + buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length, + PROT_READ | PROT_WRITE, /* recommended */ + MAP_SHARED, /* recommended */ + fd, buffer.m.planes[j].m.offset); + + if (MAP_FAILED == buffers[i].start[j]) { + /* If you do not exit here you should unmap() and free() + the buffers and planes mapped so far. */ + perror("mmap"); + exit(EXIT_FAILURE); + } } } /* Cleanup. */ for (i = 0; i < reqbuf.count; i++) - munmap (buffers[i].start, buffers[i].length); + for (j = 0; j < FMT_NUM_PLANES; j++) + munmap(buffers[i].start[j], buffers[i].length[j]); </programlisting> </example> @@ -286,13 +372,13 @@ pointer method (not only memory mapping) is supported must be determined by calling the &VIDIOC-REQBUFS; ioctl.</para> <para>This I/O method combines advantages of the read/write and -memory mapping methods. Buffers are allocated by the application +memory mapping methods. Buffers (planes) are allocated by the application itself, and can reside for example in virtual or shared memory. Only pointers to data are exchanged, these pointers and meta-information -are passed in &v4l2-buffer;. The driver must be switched -into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the -desired buffer type. No buffers are allocated beforehands, -consequently they are not indexed and cannot be queried like mapped +are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case). +The driver must be switched into user pointer I/O mode by calling the +&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated +beforehand, consequently they are not indexed and cannot be queried like mapped buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para> <example> @@ -316,7 +402,7 @@ if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { </programlisting> </example> - <para>Buffer addresses and sizes are passed on the fly with the + <para>Buffer (plane) addresses and sizes are passed on the fly with the &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled, applications can pass different addresses and sizes at each <constant>VIDIOC_QBUF</constant> call. If required by the hardware the @@ -396,11 +482,18 @@ rest should be evident.</para> <title>Buffers</title> <para>A buffer contains data exchanged by application and -driver using one of the Streaming I/O methods. Only pointers to -buffers are exchanged, the data itself is not copied. These pointers, -together with meta-information like timestamps or field parity, are -stored in a struct <structname>v4l2_buffer</structname>, argument to -the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.</para> +driver using one of the Streaming I/O methods. In the multi-planar API, the +data is held in planes, while the buffer structure acts as a container +for the planes. Only pointers to buffers (planes) are exchanged, the data +itself is not copied. These pointers, together with meta-information like +timestamps or field parity, are stored in a struct +<structname>v4l2_buffer</structname>, argument to +the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. +In the multi-planar API, some plane-specific members of struct +<structname>v4l2_buffer</structname>, such as pointers and sizes for each +plane, are stored in struct <structname>v4l2_plane</structname> instead. +In that case, struct <structname>v4l2_buffer</structname> contains an array of +plane structures.</para> <para>Nominally timestamps refer to the first data byte transmitted. In practice however the wide range of hardware covered by the V4L2 API @@ -551,26 +644,40 @@ in accordance with the selected I/O method.</entry> <entry></entry> <entry>__u32</entry> <entry><structfield>offset</structfield></entry> - <entry>When <structfield>memory</structfield> is -<constant>V4L2_MEMORY_MMAP</constant> this is the offset of the buffer -from the start of the device memory. The value is returned by the -driver and apart of serving as parameter to the &func-mmap; function -not useful for applications. See <xref linkend="mmap" /> for details.</entry> + <entry>For the single-planar API and when +<structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this +is the offset of the buffer from the start of the device memory. The value is +returned by the driver and apart of serving as parameter to the &func-mmap; +function not useful for applications. See <xref linkend="mmap" /> for details + </entry> </row> <row> <entry></entry> <entry>unsigned long</entry> <entry><structfield>userptr</structfield></entry> - <entry>When <structfield>memory</structfield> is -<constant>V4L2_MEMORY_USERPTR</constant> this is a pointer to the -buffer (casted to unsigned long type) in virtual memory, set by the -application. See <xref linkend="userp" /> for details.</entry> + <entry>For the single-planar API and when +<structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant> +this is a pointer to the buffer (casted to unsigned long type) in virtual +memory, set by the application. See <xref linkend="userp" /> for details. + </entry> + </row> + <row> + <entry></entry> + <entry>struct v4l2_plane</entry> + <entry><structfield>*planes</structfield></entry> + <entry>When using the multi-planar API, contains a userspace pointer + to an array of &v4l2-plane;. The size of the array should be put + in the <structfield>length</structfield> field of this + <structname>v4l2_buffer</structname> structure.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>length</structfield></entry> <entry></entry> - <entry>Size of the buffer (not the payload) in bytes.</entry> + <entry>Size of the buffer (not the payload) in bytes for the + single-planar API. For the multi-planar API should contain the + number of elements in the <structfield>planes</structfield> array. + </entry> </row> <row> <entry>__u32</entry> @@ -596,6 +703,66 @@ should set this to 0.</entry> </tgroup> </table> + <table frame="none" pgwide="1" id="v4l2-plane"> + <title>struct <structname>v4l2_plane</structname></title> + <tgroup cols="4"> + &cs-ustr; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>bytesused</structfield></entry> + <entry></entry> + <entry>The number of bytes occupied by data in the plane + (its payload).</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>length</structfield></entry> + <entry></entry> + <entry>Size in bytes of the plane (not its payload).</entry> + </row> + <row> + <entry>union</entry> + <entry><structfield>m</structfield></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>mem_offset</structfield></entry> + <entry>When the memory type in the containing &v4l2-buffer; is + <constant>V4L2_MEMORY_MMAP</constant>, this is the value that + should be passed to &func-mmap;, similar to the + <structfield>offset</structfield> field in &v4l2-buffer;.</entry> + </row> + <row> + <entry></entry> + <entry>__unsigned long</entry> + <entry><structfield>userptr</structfield></entry> + <entry>When the memory type in the containing &v4l2-buffer; is + <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace + pointer to the memory allocated for this plane by an application. + </entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>data_offset</structfield></entry> + <entry></entry> + <entry>Offset in bytes to video data in the plane, if applicable. + </entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved[11]</structfield></entry> + <entry></entry> + <entry>Reserved for future use. Should be zeroed by an + application.</entry> + </row> + </tbody> + </tgroup> + </table> + <table frame="none" pgwide="1" id="v4l2-buf-type"> <title>enum v4l2_buf_type</title> <tgroup cols="3"> @@ -604,13 +771,27 @@ should set this to 0.</entry> <row> <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> <entry>1</entry> - <entry>Buffer of a video capture stream, see <xref + <entry>Buffer of a single-planar video capture stream, see <xref + linkend="capture" />.</entry> + </row> + <row> + <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> + </entry> + <entry>9</entry> + <entry>Buffer of a multi-planar video capture stream, see <xref linkend="capture" />.</entry> </row> <row> <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> <entry>2</entry> - <entry>Buffer of a video output stream, see <xref + <entry>Buffer of a single-planar video output stream, see <xref + linkend="output" />.</entry> + </row> + <row> + <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> + </entry> + <entry>10</entry> + <entry>Buffer of a multi-planar video output stream, see <xref linkend="output" />.</entry> </row> <row> diff --git a/Documentation/DocBook/v4l/libv4l.xml b/Documentation/DocBook/v4l/libv4l.xml index c14fc3db2a81..3cb10ec51929 100644 --- a/Documentation/DocBook/v4l/libv4l.xml +++ b/Documentation/DocBook/v4l/libv4l.xml @@ -140,7 +140,7 @@ and is not locked sets the cid to the scaled value. <para>int v4l2_get_control(int fd, int cid) - This function returns a value of 0 - 65535, scaled to from the actual range of the given v4l control id. when the cid does not exist, could not be -accessed for some reason, or some error occured 0 is returned. +accessed for some reason, or some error occurred 0 is returned. </para></listitem> </itemizedlist> </section> diff --git a/Documentation/DocBook/v4l/lirc_device_interface.xml b/Documentation/DocBook/v4l/lirc_device_interface.xml index 68134c0ab4d1..0e0453f39e73 100644 --- a/Documentation/DocBook/v4l/lirc_device_interface.xml +++ b/Documentation/DocBook/v4l/lirc_device_interface.xml @@ -45,7 +45,7 @@ describing an IR signal are read from the chardev.</para> <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 +an uneven number of samples. The write function must block until the data has been transmitted by the hardware.</para> </section> diff --git a/Documentation/DocBook/v4l/media-controller.xml b/Documentation/DocBook/v4l/media-controller.xml new file mode 100644 index 000000000000..2dc25e1d4089 --- /dev/null +++ b/Documentation/DocBook/v4l/media-controller.xml @@ -0,0 +1,89 @@ +<partinfo> + <authorgroup> + <author> + <firstname>Laurent</firstname> + <surname>Pinchart</surname> + <affiliation><address><email>laurent.pinchart@ideasonboard.com</email></address></affiliation> + <contrib>Initial version.</contrib> + </author> + </authorgroup> + <copyright> + <year>2010</year> + <holder>Laurent Pinchart</holder> + </copyright> + + <revhistory> + <!-- Put document revisions here, newest first. --> + <revision> + <revnumber>1.0.0</revnumber> + <date>2010-11-10</date> + <authorinitials>lp</authorinitials> + <revremark>Initial revision</revremark> + </revision> + </revhistory> +</partinfo> + +<title>Media Controller API</title> + +<chapter id="media_controller"> + <title>Media Controller</title> + + <section id="media-controller-intro"> + <title>Introduction</title> + <para>Media devices increasingly handle multiple related functions. Many USB + cameras include microphones, video capture hardware can also output video, + or SoC camera interfaces also perform memory-to-memory operations similar to + video codecs.</para> + <para>Independent functions, even when implemented in the same hardware, can + be modelled as separate devices. A USB camera with a microphone will be + presented to userspace applications as V4L2 and ALSA capture devices. The + devices' relationships (when using a webcam, end-users shouldn't have to + manually select the associated USB microphone), while not made available + directly to applications by the drivers, can usually be retrieved from + sysfs.</para> + <para>With more and more advanced SoC devices being introduced, the current + approach will not scale. Device topologies are getting increasingly complex + and can't always be represented by a tree structure. Hardware blocks are + shared between different functions, creating dependencies between seemingly + unrelated devices.</para> + <para>Kernel abstraction APIs such as V4L2 and ALSA provide means for + applications to access hardware parameters. As newer hardware expose an + increasingly high number of those parameters, drivers need to guess what + applications really require based on limited information, thereby + implementing policies that belong to userspace.</para> + <para>The media controller API aims at solving those problems.</para> + </section> + + <section id="media-controller-model"> + <title>Media device model</title> + <para>Discovering a device internal topology, and configuring it at runtime, + is one of the goals of the media controller API. To achieve this, hardware + devices are modelled as an oriented graph of building blocks called entities + connected through pads.</para> + <para>An entity is a basic media hardware or software building block. It can + correspond to a large variety of logical blocks such as physical hardware + devices (CMOS sensor for instance), logical hardware devices (a building + block in a System-on-Chip image processing pipeline), DMA channels or + physical connectors.</para> + <para>A pad is a connection endpoint through which an entity can interact + with other entities. Data (not restricted to video) produced by an entity + flows from the entity's output to one or more entity inputs. Pads should not + be confused with physical pins at chip boundaries.</para> + <para>A link is a point-to-point oriented connection between two pads, + either on the same entity or on different entities. Data flows from a source + pad to a sink pad.</para> + </section> +</chapter> + +<appendix id="media-user-func"> + <title>Function Reference</title> + <!-- Keep this alphabetically sorted. --> + &sub-media-open; + &sub-media-close; + &sub-media-ioctl; + <!-- All ioctls go here. --> + &sub-media-ioc-device-info; + &sub-media-ioc-enum-entities; + &sub-media-ioc-enum-links; + &sub-media-ioc-setup-link; +</appendix> diff --git a/Documentation/DocBook/v4l/media-func-close.xml b/Documentation/DocBook/v4l/media-func-close.xml new file mode 100644 index 000000000000..be149c802aeb --- /dev/null +++ b/Documentation/DocBook/v4l/media-func-close.xml @@ -0,0 +1,59 @@ +<refentry id="media-func-close"> + <refmeta> + <refentrytitle>media close()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>media-close</refname> + <refpurpose>Close a media device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>close</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>Closes the media device. Resources associated with the file descriptor + are freed. The device configuration remain unchanged.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>close</function> returns 0 on success. On error, -1 is + returned, and <varname>errno</varname> is set appropriately. Possible error + codes are:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EBADF</errorcode></term> + <listitem> + <para><parameter>fd</parameter> is not a valid open file descriptor. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/media-func-ioctl.xml b/Documentation/DocBook/v4l/media-func-ioctl.xml new file mode 100644 index 000000000000..bda8604de15c --- /dev/null +++ b/Documentation/DocBook/v4l/media-func-ioctl.xml @@ -0,0 +1,116 @@ +<refentry id="media-func-ioctl"> + <refmeta> + <refentrytitle>media ioctl()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>media-ioctl</refname> + <refpurpose>Control a media device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <sys/ioctl.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>void *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>Media ioctl request code as defined in the media.h header file, + for example MEDIA_IOC_SETUP_LINK.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para>Pointer to a request-specific structure.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + <para>The <function>ioctl()</function> function manipulates media device + parameters. The argument <parameter>fd</parameter> must be an open file + descriptor.</para> + <para>The ioctl <parameter>request</parameter> code specifies the media + function to be called. It has encoded in it whether the argument is an + input, output or read/write parameter, and the size of the argument + <parameter>argp</parameter> in bytes.</para> + <para>Macros and structures definitions specifying media ioctl requests and + their parameters are located in the media.h header file. All media ioctl + requests, their respective function and parameters are specified in + <xref linkend="media-user-func" />.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>ioctl()</function> returns <returnvalue>0</returnvalue> on + success. On failure, <returnvalue>-1</returnvalue> is returned, and the + <varname>errno</varname> variable is set appropriately. Generic error codes + are listed below, and request-specific error codes are listed in the + individual requests descriptions.</para> + <para>When an ioctl that takes an output or read/write parameter fails, + the parameter remains unmodified.</para> + + <variablelist> + <varlistentry> + <term><errorcode>EBADF</errorcode></term> + <listitem> + <para><parameter>fd</parameter> is not a valid open file descriptor. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EFAULT</errorcode></term> + <listitem> + <para><parameter>argp</parameter> references an inaccessible memory + area.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The <parameter>request</parameter> or the data pointed to by + <parameter>argp</parameter> is not valid. This is a very common error + code, see the individual ioctl requests listed in + <xref linkend="media-user-func" /> for actual causes.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENOMEM</errorcode></term> + <listitem> + <para>Insufficient kernel memory was available to complete the + request.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENOTTY</errorcode></term> + <listitem> + <para><parameter>fd</parameter> is not associated with a character + special device.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/media-func-open.xml b/Documentation/DocBook/v4l/media-func-open.xml new file mode 100644 index 000000000000..f7df034dc9ed --- /dev/null +++ b/Documentation/DocBook/v4l/media-func-open.xml @@ -0,0 +1,94 @@ +<refentry id="media-func-open"> + <refmeta> + <refentrytitle>media open()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>media-open</refname> + <refpurpose>Open a media device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <fcntl.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>open</function></funcdef> + <paramdef>const char *<parameter>device_name</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>device_name</parameter></term> + <listitem> + <para>Device to be opened.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para>Open flags. Access mode must be either <constant>O_RDONLY</constant> + or <constant>O_RDWR</constant>. Other flags have no effect.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>Description</title> + <para>To open a media device applications call <function>open()</function> + with the desired device name. The function has no side effects; the device + configuration remain unchanged.</para> + <para>When the device is opened in read-only mode, attemps to modify its + configuration will result in an error, and <varname>errno</varname> will be + set to <errorcode>EBADF</errorcode>.</para> + </refsect1> + <refsect1> + <title>Return Value</title> + + <para><function>open</function> returns the new file descriptor on success. + On error, -1 is returned, and <varname>errno</varname> is set appropriately. + Possible error codes are:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EACCES</errorcode></term> + <listitem> + <para>The requested access to the file is not allowed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EMFILE</errorcode></term> + <listitem> + <para>The process already has the maximum number of files open. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENFILE</errorcode></term> + <listitem> + <para>The system limit on the total number of open files has been + reached.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENOMEM</errorcode></term> + <listitem> + <para>Insufficient kernel memory was available.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENXIO</errorcode></term> + <listitem> + <para>No device corresponding to this device special file exists. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/media-ioc-device-info.xml b/Documentation/DocBook/v4l/media-ioc-device-info.xml new file mode 100644 index 000000000000..1f3237351bba --- /dev/null +++ b/Documentation/DocBook/v4l/media-ioc-device-info.xml @@ -0,0 +1,133 @@ +<refentry id="media-ioc-device-info"> + <refmeta> + <refentrytitle>ioctl MEDIA_IOC_DEVICE_INFO</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>MEDIA_IOC_DEVICE_INFO</refname> + <refpurpose>Query device information</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct media_device_info *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='media-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>MEDIA_IOC_DEVICE_INFO</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>All media devices must support the <constant>MEDIA_IOC_DEVICE_INFO</constant> + ioctl. To query device information, applications call the ioctl with a + pointer to a &media-device-info;. The driver fills the structure and returns + the information to the application. + The ioctl never fails.</para> + + <table pgwide="1" frame="none" id="media-device-info"> + <title>struct <structname>media_device_info</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>char</entry> + <entry><structfield>driver</structfield>[16]</entry> + <entry><para>Name of the driver implementing the media API as a + NUL-terminated ASCII string. The driver version is stored in the + <structfield>driver_version</structfield> field.</para> + <para>Driver specific applications can use this information to + verify the driver identity. It is also useful to work around + known bugs, or to identify drivers in error reports.</para></entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>model</structfield>[32]</entry> + <entry>Device model name as a NUL-terminated UTF-8 string. The + device version is stored in the <structfield>device_version</structfield> + field and is not be appended to the model name.</entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>serial</structfield>[40]</entry> + <entry>Serial number as a NUL-terminated ASCII string.</entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>bus_info</structfield>[32]</entry> + <entry>Location of the device in the system as a NUL-terminated + ASCII string. This includes the bus type name (PCI, USB, ...) and a + bus-specific identifier.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>media_version</structfield></entry> + <entry>Media API version, formatted with the + <constant>KERNEL_VERSION()</constant> macro.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>hw_revision</structfield></entry> + <entry>Hardware device revision in a driver-specific format.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>media_version</structfield></entry> + <entry>Media device driver version, formatted with the + <constant>KERNEL_VERSION()</constant> macro. Together with the + <structfield>driver</structfield> field this identifies a particular + driver.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[31]</entry> + <entry>Reserved for future extensions. Drivers and applications must + set this array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + <para>The <structfield>serial</structfield> and <structfield>bus_info</structfield> + fields can be used to distinguish between multiple instances of otherwise + identical hardware. The serial number takes precedence when provided and can + be assumed to be unique. If the serial number is an empty string, the + <structfield>bus_info</structfield> field can be used instead. The + <structfield>bus_info</structfield> field is guaranteed to be unique, but + can vary across reboots or device unplug/replug.</para> + </refsect1> + + <refsect1> + <title>Return value</title> + <para>This function doesn't return specific error codes.</para> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/media-ioc-enum-entities.xml b/Documentation/DocBook/v4l/media-ioc-enum-entities.xml new file mode 100644 index 000000000000..576b68b33f2c --- /dev/null +++ b/Documentation/DocBook/v4l/media-ioc-enum-entities.xml @@ -0,0 +1,308 @@ +<refentry id="media-ioc-enum-entities"> + <refmeta> + <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>MEDIA_IOC_ENUM_ENTITIES</refname> + <refpurpose>Enumerate entities and their properties</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct media_entity_desc *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='media-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>MEDIA_IOC_ENUM_ENTITIES</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + <para>To query the attributes of an entity, applications set the id field + of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES + ioctl with a pointer to this structure. The driver fills the rest of the + structure or returns an &EINVAL; when the id is invalid.</para> + <para>Entities can be enumerated by or'ing the id with the + <constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return + information about the entity with the smallest id strictly larger than the + requested one ('next entity'), or the &EINVAL; if there is none.</para> + <para>Entity IDs can be non-contiguous. Applications must + <emphasis>not</emphasis> try to enumerate entities by calling + MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para> + <para>Two or more entities that share a common non-zero + <structfield>group_id</structfield> value are considered as logically + grouped. Groups are used to report + <itemizedlist> + <listitem><para>ALSA, VBI and video nodes that carry the same media + stream</para></listitem> + <listitem><para>lens and flash controllers associated with a sensor</para></listitem> + </itemizedlist> + </para> + + <table pgwide="1" frame="none" id="media-entity-desc"> + <title>struct <structname>media_entity_desc</structname></title> + <tgroup cols="5"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>id</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity id, set by the application. When the id is or'ed with + <constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the + flag and returns the first entity with a larger id.</entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>name</structfield>[32]</entry> + <entry></entry> + <entry></entry> + <entry>Entity name as an UTF-8 NULL-terminated string.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>type</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>revision</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity revision in a driver/hardware specific format.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>group_id</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity group ID</entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>pads</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Number of pads</entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>links</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Total number of outbound links. Inbound links are not counted + in this field.</entry> + </row> + <row> + <entry>union</entry> + </row> + <row> + <entry></entry> + <entry>struct</entry> + <entry><structfield>v4l</structfield></entry> + <entry></entry> + <entry>Valid for V4L sub-devices and nodes only.</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>major</structfield></entry> + <entry>V4L device node major number. For V4L sub-devices with no + device node, set by the driver to 0.</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>minor</structfield></entry> + <entry>V4L device node minor number. For V4L sub-devices with no + device node, set by the driver to 0.</entry> + </row> + <row> + <entry></entry> + <entry>struct</entry> + <entry><structfield>fb</structfield></entry> + <entry></entry> + <entry>Valid for frame buffer nodes only.</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>major</structfield></entry> + <entry>Frame buffer device node major number.</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>minor</structfield></entry> + <entry>Frame buffer device node minor number.</entry> + </row> + <row> + <entry></entry> + <entry>struct</entry> + <entry><structfield>alsa</structfield></entry> + <entry></entry> + <entry>Valid for ALSA devices only.</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>card</structfield></entry> + <entry>ALSA card number</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>device</structfield></entry> + <entry>ALSA device number</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>subdevice</structfield></entry> + <entry>ALSA sub-device number</entry> + </row> + <row> + <entry></entry> + <entry>int</entry> + <entry><structfield>dvb</structfield></entry> + <entry></entry> + <entry>DVB card number</entry> + </row> + <row> + <entry></entry> + <entry>__u8</entry> + <entry><structfield>raw</structfield>[180]</entry> + <entry></entry> + <entry></entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="media-entity-type"> + <title>Media entity types</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_ENT_T_DEVNODE</constant></entry> + <entry>Unknown device node</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_DEVNODE_V4L</constant></entry> + <entry>V4L video, radio or vbi device node</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_DEVNODE_FB</constant></entry> + <entry>Frame buffer device node</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_DEVNODE_ALSA</constant></entry> + <entry>ALSA card</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_DEVNODE_DVB</constant></entry> + <entry>DVB card</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV</constant></entry> + <entry>Unknown V4L sub-device</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_SENSOR</constant></entry> + <entry>Video sensor</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_FLASH</constant></entry> + <entry>Flash controller</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry> + <entry>Lens controller</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="media-entity-flag"> + <title>Media entity flags</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry> + <entry>Default entity for its type. Used to discover the default + audio, VBI and video devices, the default camera sensor, ...</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The &media-entity-desc; <structfield>id</structfield> references + a non-existing entity.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/v4l/media-ioc-enum-links.xml new file mode 100644 index 000000000000..d2fc73ef8d56 --- /dev/null +++ b/Documentation/DocBook/v4l/media-ioc-enum-links.xml @@ -0,0 +1,207 @@ +<refentry id="media-ioc-enum-links"> + <refmeta> + <refentrytitle>ioctl MEDIA_IOC_ENUM_LINKS</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>MEDIA_IOC_ENUM_LINKS</refname> + <refpurpose>Enumerate all pads and links for a given entity</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct media_links_enum *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='media-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>MEDIA_IOC_ENUM_LINKS</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>To enumerate pads and/or links for a given entity, applications set + the entity field of a &media-links-enum; structure and initialize the + &media-pad-desc; and &media-link-desc; structure arrays pointed by the + <structfield>pads</structfield> and <structfield>links</structfield> fields. + They then call the MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this + structure.</para> + <para>If the <structfield>pads</structfield> field is not NULL, the driver + fills the <structfield>pads</structfield> array with information about the + entity's pads. The array must have enough room to store all the entity's + pads. The number of pads can be retrieved with the &MEDIA-IOC-ENUM-ENTITIES; + ioctl.</para> + <para>If the <structfield>links</structfield> field is not NULL, the driver + fills the <structfield>links</structfield> array with information about the + entity's outbound links. The array must have enough room to store all the + entity's outbound links. The number of outbound links can be retrieved with + the &MEDIA-IOC-ENUM-ENTITIES; ioctl.</para> + <para>Only forward links that originate at one of the entity's source pads + are returned during the enumeration process.</para> + + <table pgwide="1" frame="none" id="media-links-enum"> + <title>struct <structname>media_links_enum</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>entity</structfield></entry> + <entry>Entity id, set by the application.</entry> + </row> + <row> + <entry>struct &media-pad-desc;</entry> + <entry>*<structfield>pads</structfield></entry> + <entry>Pointer to a pads array allocated by the application. Ignored + if NULL.</entry> + </row> + <row> + <entry>struct &media-link-desc;</entry> + <entry>*<structfield>links</structfield></entry> + <entry>Pointer to a links array allocated by the application. Ignored + if NULL.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="media-pad-desc"> + <title>struct <structname>media_pad_desc</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>entity</structfield></entry> + <entry>ID of the entity this pad belongs to.</entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>index</structfield></entry> + <entry>0-based pad index.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="media-pad-flag"> + <title>Media pad flags</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_PAD_FL_SINK</constant></entry> + <entry>Input pad, relative to the entity. Input pads sink data and + are targets of links.</entry> + </row> + <row> + <entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry> + <entry>Output pad, relative to the entity. Output pads source data + and are origins of links.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="media-link-desc"> + <title>struct <structname>media_links_desc</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>struct &media-pad-desc;</entry> + <entry><structfield>source</structfield></entry> + <entry>Pad at the origin of this link.</entry> + </row> + <row> + <entry>struct &media-pad-desc;</entry> + <entry><structfield>sink</structfield></entry> + <entry>Pad at the target of this link.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="media-link-flag"> + <title>Media link flags</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry> + <entry>The link is enabled and can be used to transfer media data. + When two or more links target a sink pad, only one of them can be + enabled at a time.</entry> + </row> + <row> + <entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry> + <entry>The link enabled state can't be modified at runtime. An + immutable link is always enabled.</entry> + </row> + <row> + <entry><constant>MEDIA_LNK_FL_DYNAMIC</constant></entry> + <entry>The link enabled state can be modified during streaming. This + flag is set by drivers and is read-only for applications.</entry> + </row> + </tbody> + </tgroup> + </table> + <para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and + <constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The &media-links-enum; <structfield>id</structfield> references + a non-existing entity.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/media-ioc-setup-link.xml b/Documentation/DocBook/v4l/media-ioc-setup-link.xml new file mode 100644 index 000000000000..2331e76ded17 --- /dev/null +++ b/Documentation/DocBook/v4l/media-ioc-setup-link.xml @@ -0,0 +1,93 @@ +<refentry id="media-ioc-setup-link"> + <refmeta> + <refentrytitle>ioctl MEDIA_IOC_SETUP_LINK</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>MEDIA_IOC_SETUP_LINK</refname> + <refpurpose>Modify the properties of a link</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct media_link_desc *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='media-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>MEDIA_IOC_ENUM_LINKS</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>To change link properties applications fill a &media-link-desc; with + link identification information (source and sink pad) and the new requested + link flags. They then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to + that structure.</para> + <para>The only configurable property is the <constant>ENABLED</constant> + link flag to enable/disable a link. Links marked with the + <constant>IMMUTABLE</constant> link flag can not be enabled or disabled. + </para> + <para>Link configuration has no side effect on other links. If an enabled + link at the sink pad prevents the link from being enabled, the driver + returns with an &EBUSY;.</para> + <para>Only links marked with the <constant>DYNAMIC</constant> link flag can + be enabled/disabled while streaming media data. Attempting to enable or + disable a streaming non-dynamic link will return an &EBUSY;.</para> + <para>If the specified link can't be found the driver returns with an + &EINVAL;.</para> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> + <listitem> + <para>The link properties can't be changed because the link is + currently busy. This can be caused, for instance, by an active media + stream (audio or video) on the link. The ioctl shouldn't be retried if + no other action is performed before to fix the problem.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The &media-link-desc; references a non-existing link, or the + link is immutable and an attempt to modify its configuration was made. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/nv12mt.gif b/Documentation/DocBook/v4l/nv12mt.gif Binary files differnew file mode 100644 index 000000000000..ef2d4cf8367b --- /dev/null +++ b/Documentation/DocBook/v4l/nv12mt.gif diff --git a/Documentation/DocBook/v4l/nv12mt_example.gif b/Documentation/DocBook/v4l/nv12mt_example.gif Binary files differnew file mode 100644 index 000000000000..df81d68108ee --- /dev/null +++ b/Documentation/DocBook/v4l/nv12mt_example.gif diff --git a/Documentation/DocBook/v4l/pipeline.pdf b/Documentation/DocBook/v4l/pipeline.pdf Binary files differnew file mode 100644 index 000000000000..ee3e37f04b6a --- /dev/null +++ b/Documentation/DocBook/v4l/pipeline.pdf diff --git a/Documentation/DocBook/v4l/pipeline.png b/Documentation/DocBook/v4l/pipeline.png Binary files differnew file mode 100644 index 000000000000..f19b86c2c24d --- /dev/null +++ b/Documentation/DocBook/v4l/pipeline.png diff --git a/Documentation/DocBook/v4l/pixfmt-nv12m.xml b/Documentation/DocBook/v4l/pixfmt-nv12m.xml new file mode 100644 index 000000000000..c9e166d9ded8 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-nv12m.xml @@ -0,0 +1,154 @@ + <refentry id="V4L2-PIX-FMT-NV12M"> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_NV12M ('NV12M')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname> <constant>V4L2_PIX_FMT_NV12M</constant></refname> + <refpurpose>Variation of <constant>V4L2_PIX_FMT_NV12</constant> with planes + non contiguous in memory. </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>This is a multi-planar, two-plane version of the YUV 4:2:0 format. +The three components are separated into two sub-images or planes. +<constant>V4L2_PIX_FMT_NV12M</constant> differs from <constant>V4L2_PIX_FMT_NV12 +</constant> in that the two planes are non-contiguous in memory, i.e. the chroma +plane do not necessarily immediately follows the luma plane. +The luminance data occupies the first plane. The Y plane has one byte per pixel. +In the second plane there is a chrominance data with alternating chroma samples. +The CbCr plane is the same width, in bytes, as the Y plane (and of the image), +but is half as tall in pixels. Each CbCr pair belongs to four pixels. For example, +Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to +Y'<subscript>00</subscript>, Y'<subscript>01</subscript>, +Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. </para> + + <para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be +used only in drivers and applications that support the multi-planar API, +described in <xref linkend="planar-apis"/>. </para> + + <para>If the Y plane has pad bytes after each row, then the +CbCr plane has as many pad bytes after its rows.</para> + + <example> + <title><constant>V4L2_PIX_FMT_NV12M</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>start0 + 0:</entry> + <entry>Y'<subscript>00</subscript></entry> + <entry>Y'<subscript>01</subscript></entry> + <entry>Y'<subscript>02</subscript></entry> + <entry>Y'<subscript>03</subscript></entry> + </row> + <row> + <entry>start0 + 4:</entry> + <entry>Y'<subscript>10</subscript></entry> + <entry>Y'<subscript>11</subscript></entry> + <entry>Y'<subscript>12</subscript></entry> + <entry>Y'<subscript>13</subscript></entry> + </row> + <row> + <entry>start0 + 8:</entry> + <entry>Y'<subscript>20</subscript></entry> + <entry>Y'<subscript>21</subscript></entry> + <entry>Y'<subscript>22</subscript></entry> + <entry>Y'<subscript>23</subscript></entry> + </row> + <row> + <entry>start0 + 12:</entry> + <entry>Y'<subscript>30</subscript></entry> + <entry>Y'<subscript>31</subscript></entry> + <entry>Y'<subscript>32</subscript></entry> + <entry>Y'<subscript>33</subscript></entry> + </row> + <row> + <entry></entry> + </row> + <row> + <entry>start1 + 0:</entry> + <entry>Cb<subscript>00</subscript></entry> + <entry>Cr<subscript>00</subscript></entry> + <entry>Cb<subscript>01</subscript></entry> + <entry>Cr<subscript>01</subscript></entry> + </row> + <row> + <entry>start1 + 4:</entry> + <entry>Cb<subscript>10</subscript></entry> + <entry>Cr<subscript>10</subscript></entry> + <entry>Cb<subscript>11</subscript></entry> + <entry>Cr<subscript>11</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + + <formalpara> + <title>Color Sample Location.</title> + <para> + <informaltable frame="none"> + <tgroup cols="7" align="center"> + <tbody valign="top"> + <row> + <entry></entry> + <entry>0</entry><entry></entry><entry>1</entry><entry></entry> + <entry>2</entry><entry></entry><entry>3</entry> + </row> + <row> + <entry>0</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + <row> + <entry></entry> + <entry></entry><entry>C</entry><entry></entry><entry></entry> + <entry></entry><entry>C</entry><entry></entry> + </row> + <row> + <entry>1</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + <row> + <entry></entry> + </row> + <row> + <entry>2</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + <row> + <entry></entry> + <entry></entry><entry>C</entry><entry></entry><entry></entry> + <entry></entry><entry>C</entry><entry></entry> + </row> + <row> + <entry>3</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> + </refentry> + + <!-- +Local Variables: +mode: sgml +sgml-parent-document: "pixfmt.sgml" +indent-tabs-mode: nil +End: + --> diff --git a/Documentation/DocBook/v4l/pixfmt-nv12mt.xml b/Documentation/DocBook/v4l/pixfmt-nv12mt.xml new file mode 100644 index 000000000000..7a2855a526c1 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-nv12mt.xml @@ -0,0 +1,74 @@ + <refentry> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_NV12MT ('TM12')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname id="V4L2-PIX-FMT-NV12MT"><constant>V4L2_PIX_FMT_NV12MT +</constant></refname> + <refpurpose>Formats with ½ horizontal and vertical +chroma resolution. This format has two planes - one for luminance and one for +chrominance. Chroma samples are interleaved. The difference to +<constant>V4L2_PIX_FMT_NV12</constant> is the memory layout. Pixels are +grouped in macroblocks of 64x32 size. The order of macroblocks in memory is +also not standard. + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>This is the two-plane versions of the YUV 4:2:0 format where data +is grouped into 64x32 macroblocks. The three components are separated into two +sub-images or planes. The Y plane has one byte per pixel and pixels are grouped +into 64x32 macroblocks. The CbCr plane has the same width, in bytes, as the Y +plane (and the image), but is half as tall in pixels. The chroma plane is also +grouped into 64x32 macroblocks.</para> + <para>Width of the buffer has to be aligned to the multiple of 128, and +height alignment is 32. Every four adjactent buffers - two horizontally and two +vertically are grouped together and are located in memory in Z or flipped Z +order. </para> + <para>Layout of macroblocks in memory is presented in the following +figure.</para> + <para><figure id="nv12mt"> + <title><constant>V4L2_PIX_FMT_NV12MT</constant> macroblock Z shape +memory layout</title> + <mediaobject> + <imageobject> + <imagedata fileref="nv12mt.gif" format="GIF" /> + </imageobject> + </mediaobject> + </figure> + The requirement that width is multiple of 128 is implemented because, +the Z shape cannot be cut in half horizontally. In case the vertical resolution +of macroblocks is odd then the last row of macroblocks is arranged in a linear +order. </para> + <para>In case of chroma the layout is identical. Cb and Cr samples are +interleaved. Height of the buffer is aligned to 32. + </para> + <example> + <title>Memory layout of macroblocks in <constant>V4L2_PIX_FMT_NV12 +</constant> format pixel image - extreme case</title> + <para> + <figure id="nv12mt_ex"> + <title>Example <constant>V4L2_PIX_FMT_NV12MT</constant> memory +layout of macroblocks</title> + <mediaobject> + <imageobject> + <imagedata fileref="nv12mt_example.gif" format="GIF" /> + </imageobject> + </mediaobject> + </figure> + Memory layout of macroblocks of <constant>V4L2_PIX_FMT_NV12MT +</constant> format in most extreme case. + </para> + </example> + </refsect1> + </refentry> + + <!-- +Local Variables: +mode: sgml +sgml-parent-document: "pixfmt.sgml" +indent-tabs-mode: nil +End: + --> diff --git a/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml index 26e879231088..4db272b8a0d3 100644 --- a/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml +++ b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml @@ -739,7 +739,7 @@ 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"> + <row><!-- id="V4L2-PIX-FMT-BGR666" --> <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry> <entry>'BGRH'</entry> <entry></entry> diff --git a/Documentation/DocBook/v4l/pixfmt-srggb10.xml b/Documentation/DocBook/v4l/pixfmt-srggb10.xml new file mode 100644 index 000000000000..7b274092e60c --- /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-srggb12.xml b/Documentation/DocBook/v4l/pixfmt-srggb12.xml new file mode 100644 index 000000000000..9ba4fb690bc0 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-srggb12.xml @@ -0,0 +1,90 @@ + <refentry> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_SRGGB12 ('RG12'), + V4L2_PIX_FMT_SGRBG12 ('BA12'), + V4L2_PIX_FMT_SGBRG12 ('GB12'), + V4L2_PIX_FMT_SBGGR12 ('BG12'), + </refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname id="V4L2-PIX-FMT-SRGGB12"><constant>V4L2_PIX_FMT_SRGGB12</constant></refname> + <refname id="V4L2-PIX-FMT-SGRBG12"><constant>V4L2_PIX_FMT_SGRBG12</constant></refname> + <refname id="V4L2-PIX-FMT-SGBRG12"><constant>V4L2_PIX_FMT_SGBRG12</constant></refname> + <refname id="V4L2-PIX-FMT-SBGGR12"><constant>V4L2_PIX_FMT_SBGGR12</constant></refname> + <refpurpose>12-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 +12 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_SBGGR12</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 000000000000..2570e3be3cf1 --- /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 000000000000..d065043db8d8 --- /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-yuv420m.xml b/Documentation/DocBook/v4l/pixfmt-yuv420m.xml new file mode 100644 index 000000000000..f5d8f57495c8 --- /dev/null +++ b/Documentation/DocBook/v4l/pixfmt-yuv420m.xml @@ -0,0 +1,162 @@ + <refentry id="V4L2-PIX-FMT-YUV420M"> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_YUV420M ('YU12M')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname> <constant>V4L2_PIX_FMT_YUV420M</constant></refname> + <refpurpose>Variation of <constant>V4L2_PIX_FMT_YUV420</constant> + with planes non contiguous in memory. </refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>This is a multi-planar format, as opposed to a packed format. +The three components are separated into three sub- images or planes. + +The Y plane is first. The Y plane has one byte per pixel. The Cb data +constitutes the second plane which is half the width and half +the height of the Y plane (and of the image). Each Cb belongs to four +pixels, a two-by-two square of the image. For example, +Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, +Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and +Y'<subscript>11</subscript>. The Cr data, just like the Cb plane, is +in the third plane. </para> + + <para>If the Y plane has pad bytes after each row, then the Cb +and Cr planes have half as many pad bytes after their rows. In other +words, two Cx rows (including padding) is exactly as long as one Y row +(including padding).</para> + + <para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be +used only in drivers and applications that support the multi-planar API, +described in <xref linkend="planar-apis"/>. </para> + + <example> + <title><constant>V4L2_PIX_FMT_YVU420M</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>start0 + 0:</entry> + <entry>Y'<subscript>00</subscript></entry> + <entry>Y'<subscript>01</subscript></entry> + <entry>Y'<subscript>02</subscript></entry> + <entry>Y'<subscript>03</subscript></entry> + </row> + <row> + <entry>start0 + 4:</entry> + <entry>Y'<subscript>10</subscript></entry> + <entry>Y'<subscript>11</subscript></entry> + <entry>Y'<subscript>12</subscript></entry> + <entry>Y'<subscript>13</subscript></entry> + </row> + <row> + <entry>start0 + 8:</entry> + <entry>Y'<subscript>20</subscript></entry> + <entry>Y'<subscript>21</subscript></entry> + <entry>Y'<subscript>22</subscript></entry> + <entry>Y'<subscript>23</subscript></entry> + </row> + <row> + <entry>start0 + 12:</entry> + <entry>Y'<subscript>30</subscript></entry> + <entry>Y'<subscript>31</subscript></entry> + <entry>Y'<subscript>32</subscript></entry> + <entry>Y'<subscript>33</subscript></entry> + </row> + <row><entry></entry></row> + <row> + <entry>start1 + 0:</entry> + <entry>Cb<subscript>00</subscript></entry> + <entry>Cb<subscript>01</subscript></entry> + </row> + <row> + <entry>start1 + 2:</entry> + <entry>Cb<subscript>10</subscript></entry> + <entry>Cb<subscript>11</subscript></entry> + </row> + <row><entry></entry></row> + <row> + <entry>start2 + 0:</entry> + <entry>Cr<subscript>00</subscript></entry> + <entry>Cr<subscript>01</subscript></entry> + </row> + <row> + <entry>start2 + 2:</entry> + <entry>Cr<subscript>10</subscript></entry> + <entry>Cr<subscript>11</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + + <formalpara> + <title>Color Sample Location.</title> + <para> + <informaltable frame="none"> + <tgroup cols="7" align="center"> + <tbody valign="top"> + <row> + <entry></entry> + <entry>0</entry><entry></entry><entry>1</entry><entry></entry> + <entry>2</entry><entry></entry><entry>3</entry> + </row> + <row> + <entry>0</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + <row> + <entry></entry> + <entry></entry><entry>C</entry><entry></entry><entry></entry> + <entry></entry><entry>C</entry><entry></entry> + </row> + <row> + <entry>1</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + <row> + <entry></entry> + </row> + <row> + <entry>2</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + <row> + <entry></entry> + <entry></entry><entry>C</entry><entry></entry><entry></entry> + <entry></entry><entry>C</entry><entry></entry> + </row> + <row> + <entry>3</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> + </refentry> + + <!-- +Local Variables: +mode: sgml +sgml-parent-document: "pixfmt.sgml" +indent-tabs-mode: nil +End: + --> diff --git a/Documentation/DocBook/v4l/pixfmt.xml b/Documentation/DocBook/v4l/pixfmt.xml index c4ad0a8e42dc..c6fdcbbd1b41 100644 --- a/Documentation/DocBook/v4l/pixfmt.xml +++ b/Documentation/DocBook/v4l/pixfmt.xml @@ -2,12 +2,16 @@ <para>The V4L2 API was primarily designed for devices exchanging image data with applications. The -<structname>v4l2_pix_format</structname> structure defines the format -and layout of an image in memory. Image formats are negotiated with -the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video +<structname>v4l2_pix_format</structname> and <structname>v4l2_pix_format_mplane +</structname> structures define the format and layout of an image in memory. +The former is used with the single-planar API, while the latter is used with the +multi-planar version (see <xref linkend="planar-apis"/>). Image formats are +negotiated with the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video capturing and output, for overlay frame buffer formats see also &VIDIOC-G-FBUF;.)</para> +<section> + <title>Single-planar format structure</title> <table pgwide="1" frame="none" id="v4l2-pix-format"> <title>struct <structname>v4l2_pix_format</structname></title> <tgroup cols="3"> @@ -106,6 +110,98 @@ set this field to zero.</entry> </tbody> </tgroup> </table> +</section> + +<section> + <title>Multi-planar format structures</title> + <para>The <structname>v4l2_plane_pix_format</structname> structures define + size and layout for each of the planes in a multi-planar format. + The <structname>v4l2_pix_format_mplane</structname> structure contains + information common to all planes (such as image width and height) and + an array of <structname>v4l2_plane_pix_format</structname> structures, + describing all planes of that format.</para> + <table pgwide="1" frame="none" id="v4l2-plane-pix-format"> + <title>struct <structname>vl42_plane_pix_format</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>sizeimage</structfield></entry> + <entry>Maximum size in bytes required for image data in this plane. + </entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>bytesperline</structfield></entry> + <entry>Distance in bytes between the leftmost pixels in two adjacent + lines.</entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>reserved[7]</structfield></entry> + <entry>Reserved for future extensions. Should be zeroed by the + application.</entry> + </row> + </tbody> + </tgroup> + </table> + <table pgwide="1" frame="none" id="v4l2-pix-format-mplane"> + <title>struct <structname>v4l2_pix_format_mplane</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>width</structfield></entry> + <entry>Image width in pixels.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>height</structfield></entry> + <entry>Image height in pixels.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>pixelformat</structfield></entry> + <entry>The pixel format. Both single- and multi-planar four character +codes can be used.</entry> + </row> + <row> + <entry>&v4l2-field;</entry> + <entry><structfield>field</structfield></entry> + <entry>See &v4l2-pix-format;.</entry> + </row> + <row> + <entry>&v4l2-colorspace;</entry> + <entry><structfield>colorspace</structfield></entry> + <entry>See &v4l2-pix-format;.</entry> + </row> + <row> + <entry>&v4l2-plane-pix-format;</entry> + <entry><structfield>plane_fmt[VIDEO_MAX_PLANES]</structfield></entry> + <entry>An array of structures describing format of each plane this + pixel format consists of. The number of valid entries in this array + has to be put in the <structfield>num_planes</structfield> + field.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>num_planes</structfield></entry> + <entry>Number of planes (i.e. separate memory buffers) for this format + and the number of valid entries in the + <structfield>plane_fmt</structfield> array.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>reserved[11]</structfield></entry> + <entry>Reserved for future extensions. Should be zeroed by the + application.</entry> + </row> + </tbody> + </tgroup> + </table> +</section> <section> <title>Standard Image Formats</title> @@ -144,9 +240,17 @@ has just as many pad bytes after it as the other rows.</para> <para>In V4L2 each format has an identifier which looks like <constant>PIX_FMT_XXX</constant>, defined in the <link linkend="videodev">videodev.h</link> header file. These identifiers -represent <link linkend="v4l2-fourcc">four character codes</link> +represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link> which are also listed below, however they are not the same as those used in the Windows world.</para> + + <para>For some formats, data is stored in separate, discontiguous +memory buffers. Those formats are identified by a separate set of FourCC codes +and are referred to as "multi-planar formats". For example, a YUV422 frame is +normally stored in one memory buffer, but it can also be placed in two or three +separate buffers, with Y component in one buffer and CbCr components in another +in the 2-planar version or with each component in its own buffer in the +3-planar case. Those sub-buffers are referred to as "planes".</para> </section> <section id="colorspaces"> @@ -566,7 +670,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 +695,7 @@ information.</para> &sub-packed-yuv; &sub-grey; + &sub-y10; &sub-y16; &sub-yuyv; &sub-uyvy; @@ -596,10 +703,13 @@ information.</para> &sub-vyuy; &sub-y41p; &sub-yuv420; + &sub-yuv420m; &sub-yuv410; &sub-yuv422p; &sub-yuv411p; &sub-nv12; + &sub-nv12m; + &sub-nv12mt; &sub-nv16; </section> @@ -685,6 +795,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 +820,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 +880,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 +902,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/planar-apis.xml b/Documentation/DocBook/v4l/planar-apis.xml new file mode 100644 index 000000000000..878ce2040488 --- /dev/null +++ b/Documentation/DocBook/v4l/planar-apis.xml @@ -0,0 +1,62 @@ +<section id="planar-apis"> + <title>Single- and multi-planar APIs</title> + + <para>Some devices require data for each input or output video frame + to be placed in discontiguous memory buffers. In such cases, one + video frame has to be addressed using more than one memory address, i.e. one + pointer per "plane". A plane is a sub-buffer of the current frame. For + examples of such formats see <xref linkend="pixfmt" />.</para> + + <para>Initially, V4L2 API did not support multi-planar buffers and a set of + extensions has been introduced to handle them. Those extensions constitute + what is being referred to as the "multi-planar API".</para> + + <para>Some of the V4L2 API calls and structures are interpreted differently, + depending on whether single- or multi-planar API is being used. An application + can choose whether to use one or the other by passing a corresponding buffer + type to its ioctl calls. Multi-planar versions of buffer types are suffixed + with an `_MPLANE' string. For a list of available multi-planar buffer types + see &v4l2-buf-type;. + </para> + + <section> + <title>Multi-planar formats</title> + <para>Multi-planar API introduces new multi-planar formats. Those formats + use a separate set of FourCC codes. It is important to distinguish between + the multi-planar API and a multi-planar format. Multi-planar API calls can + handle all single-planar formats as well (as long as they are passed in + multi-planar API structures), while the single-planar API cannot + handle multi-planar formats.</para> + </section> + + <section> + <title>Calls that distinguish between single and multi-planar APIs</title> + <variablelist> + <varlistentry> + <term>&VIDIOC-QUERYCAP;</term> + <listitem><para>Two additional multi-planar capabilities are added. They can + be set together with non-multi-planar ones for devices that handle + both single- and multi-planar formats.</para></listitem> + </varlistentry> + <varlistentry> + <term>&VIDIOC-G-FMT;, &VIDIOC-S-FMT;, &VIDIOC-TRY-FMT;</term> + <listitem><para>New structures for describing multi-planar formats are added: + &v4l2-pix-format-mplane; and &v4l2-plane-pix-format;. Drivers may + define new multi-planar formats, which have distinct FourCC codes from + the existing single-planar ones.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>&VIDIOC-QBUF;, &VIDIOC-DQBUF;, &VIDIOC-QUERYBUF;</term> + <listitem><para>A new &v4l2-plane; structure for describing planes is added. + Arrays of this structure are passed in the new + <structfield>m.planes</structfield> field of &v4l2-buffer;.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>&VIDIOC-REQBUFS;</term> + <listitem><para>Will allocate multi-planar buffers as requested.</para></listitem> + </varlistentry> + </variablelist> + </section> +</section> diff --git a/Documentation/DocBook/v4l/remote_controllers.xml b/Documentation/DocBook/v4l/remote_controllers.xml index 3c3b667b28e7..160e464d44b7 100644 --- a/Documentation/DocBook/v4l/remote_controllers.xml +++ b/Documentation/DocBook/v4l/remote_controllers.xml @@ -133,7 +133,7 @@ different IR's. Due to that, V4L2 API now specifies a standard for mapping Media <row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row> <row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row> -<row><entry><emphasis role="bold">Miscelaneous keys</emphasis></entry></row> +<row><entry><emphasis role="bold">Miscellaneous keys</emphasis></entry></row> <row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row> <row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row> diff --git a/Documentation/DocBook/v4l/subdev-formats.xml b/Documentation/DocBook/v4l/subdev-formats.xml new file mode 100644 index 000000000000..7041127d6dfc --- /dev/null +++ b/Documentation/DocBook/v4l/subdev-formats.xml @@ -0,0 +1,2467 @@ +<section id="v4l2-mbus-format"> + <title>Media Bus Formats</title> + + <table pgwide="1" frame="none" id="v4l2-mbus-framefmt"> + <title>struct <structname>v4l2_mbus_framefmt</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>width</structfield></entry> + <entry>Image width, in pixels.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>height</structfield></entry> + <entry>Image height, in pixels.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>code</structfield></entry> + <entry>Format code, from &v4l2-mbus-pixelcode;.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>field</structfield></entry> + <entry>Field order, from &v4l2-field;. See + <xref linkend="field-order" /> for details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>colorspace</structfield></entry> + <entry>Image colorspace, from &v4l2-colorspace;. See + <xref linkend="colorspaces" /> for details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[7]</entry> + <entry>Reserved for future extensions. Applications and drivers must + set the array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + + <section id="v4l2-mbus-pixelcode"> + <title>Media Bus Pixel Codes</title> + + <para>The media bus pixel codes describe image formats as flowing over + physical busses (both between separate physical components and inside SoC + devices). This should not be confused with the V4L2 pixel formats that + describe, using four character codes, image formats as stored in memory. + </para> + + <para>While there is a relationship between image formats on busses and + image formats in memory (a raw Bayer image won't be magically converted to + JPEG just by storing it to memory), there is no one-to-one correspondance + between them.</para> + + <section> + <title>Packed RGB Formats</title> + + <para>Those formats transfer pixel data as red, green and blue components. + The format code is made of the following information. + <itemizedlist> + <listitem><para>The red, green and blue components order code, as encoded in a + pixel sample. Possible values are RGB and BGR.</para></listitem> + <listitem><para>The number of bits per component, for each component. The values + can be different for all components. Common values are 555 and 565.</para> + </listitem> + <listitem><para>The number of bus samples per pixel. Pixels that are wider than + the bus width must be transferred in multiple samples. Common values are + 1 and 2.</para></listitem> + <listitem><para>The bus width.</para></listitem> + <listitem><para>For formats where the total number of bits per pixel is smaller + than the number of bus samples per pixel times the bus width, a padding + value stating if the bytes are padded in their most high order bits + (PADHI) or low order bits (PADLO).</para></listitem> + <listitem><para>For formats where the number of bus samples per pixel is larger + than 1, an endianness value stating if the pixel is transferred MSB first + (BE) or LSB first (LE).</para></listitem> + </itemizedlist> + </para> + + <para>For instance, a format where pixels are encoded as 5-bits red, 5-bits + green and 5-bit blue values padded on the high bit, transferred as 2 8-bit + samples per pixel with the most significant bits (padding, red and half of + the green value) transferred first will be named + <constant>V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE</constant>. + </para> + + <para>The following tables list existing packet RGB formats.</para> + + <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-rgb"> + <title>RGB formats</title> + <tgroup cols="11"> + <colspec colname="id" align="left" /> + <colspec colname="code" align="center"/> + <colspec colname="bit" /> + <colspec colnum="4" colname="b07" align="center" /> + <colspec colnum="5" colname="b06" align="center" /> + <colspec colnum="6" colname="b05" align="center" /> + <colspec colnum="7" colname="b04" align="center" /> + <colspec colnum="8" colname="b03" align="center" /> + <colspec colnum="9" colname="b02" align="center" /> + <colspec colnum="10" colname="b01" align="center" /> + <colspec colnum="11" colname="b00" align="center" /> + <spanspec namest="b07" nameend="b00" spanname="b0" /> + <thead> + <row> + <entry>Identifier</entry> + <entry>Code</entry> + <entry></entry> + <entry spanname="b0">Data organization</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>Bit</entry> + <entry>7</entry> + <entry>6</entry> + <entry>5</entry> + <entry>4</entry> + <entry>3</entry> + <entry>2</entry> + <entry>1</entry> + <entry>0</entry> + </row> + </thead> + <tbody valign="top"> + <row id="V4L2-MBUS-FMT-RGB444-2X8-PADHI-BE"> + <entry>V4L2_MBUS_FMT_RGB444_2X8_PADHI_BE</entry> + <entry>0x1001</entry> + <entry></entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></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>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-RGB444-2X8-PADHI-LE"> + <entry>V4L2_MBUS_FMT_RGB444_2X8_PADHI_LE</entry> + <entry>0x1002</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>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-RGB555-2X8-PADHI-BE"> + <entry>V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE</entry> + <entry>0x1003</entry> + <entry></entry> + <entry>0</entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</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> + </row> + <row id="V4L2-MBUS-FMT-RGB555-2X8-PADHI-LE"> + <entry>V4L2_MBUS_FMT_RGB555_2X8_PADHI_LE</entry> + <entry>0x1004</entry> + <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</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> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>0</entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-BGR565-2X8-BE"> + <entry>V4L2_MBUS_FMT_BGR565_2X8_BE</entry> + <entry>0x1005</entry> + <entry></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>g<subscript>3</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-BGR565-2X8-LE"> + <entry>V4L2_MBUS_FMT_BGR565_2X8_LE</entry> + <entry>0x1006</entry> + <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></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>g<subscript>3</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-RGB565-2X8-BE"> + <entry>V4L2_MBUS_FMT_RGB565_2X8_BE</entry> + <entry>0x1007</entry> + <entry></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</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> + </row> + <row id="V4L2-MBUS-FMT-RGB565-2X8-LE"> + <entry>V4L2_MBUS_FMT_RGB565_2X8_LE</entry> + <entry>0x1008</entry> + <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</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> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Bayer Formats</title> + + <para>Those formats transfer pixel data as red, green and blue components. + The format code is made of the following information. + <itemizedlist> + <listitem><para>The red, green and blue components order code, as encoded in a + pixel sample. The possible values are shown in <xref + linkend="bayer-patterns" />.</para></listitem> + <listitem><para>The number of bits per pixel component. All components are + transferred on the same number of bits. Common values are 8, 10 and 12.</para> + </listitem> + <listitem><para>If the pixel components are DPCM-compressed, a mention of the + DPCM compression and the number of bits per compressed pixel component.</para> + </listitem> + <listitem><para>The number of bus samples per pixel. Pixels that are wider than + the bus width must be transferred in multiple samples. Common values are + 1 and 2.</para></listitem> + <listitem><para>The bus width.</para></listitem> + <listitem><para>For formats where the total number of bits per pixel is smaller + than the number of bus samples per pixel times the bus width, a padding + value stating if the bytes are padded in their most high order bits + (PADHI) or low order bits (PADLO).</para></listitem> + <listitem><para>For formats where the number of bus samples per pixel is larger + than 1, an endianness value stating if the pixel is transferred MSB first + (BE) or LSB first (LE).</para></listitem> + </itemizedlist> + </para> + + <para>For instance, a format with uncompressed 10-bit Bayer components + arranged in a red, green, green, blue pattern transferred as 2 8-bit + samples per pixel with the least significant bits transferred first will + be named <constant>V4L2_MBUS_FMT_SRGGB10_2X8_PADHI_LE</constant>. + </para> + + <figure id="bayer-patterns"> + <title>Bayer Patterns</title> + <mediaobject> + <imageobject> + <imagedata fileref="bayer.pdf" format="PS" /> + </imageobject> + <imageobject> + <imagedata fileref="bayer.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Bayer filter color patterns</phrase> + </textobject> + </mediaobject> + </figure> + + <para>The following table lists existing packet Bayer formats. The data + organization is given as an example for the first pixel only.</para> + + <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-bayer"> + <title>Bayer Formats</title> + <tgroup cols="15"> + <colspec colname="id" align="left" /> + <colspec colname="code" align="center"/> + <colspec colname="bit" /> + <colspec colnum="4" colname="b11" align="center" /> + <colspec colnum="5" colname="b10" align="center" /> + <colspec colnum="6" colname="b09" align="center" /> + <colspec colnum="7" colname="b08" align="center" /> + <colspec colnum="8" colname="b07" align="center" /> + <colspec colnum="9" colname="b06" align="center" /> + <colspec colnum="10" colname="b05" align="center" /> + <colspec colnum="11" colname="b04" align="center" /> + <colspec colnum="12" colname="b03" align="center" /> + <colspec colnum="13" colname="b02" align="center" /> + <colspec colnum="14" colname="b01" align="center" /> + <colspec colnum="15" colname="b00" align="center" /> + <spanspec namest="b11" nameend="b00" spanname="b0" /> + <thead> + <row> + <entry>Identifier</entry> + <entry>Code</entry> + <entry></entry> + <entry spanname="b0">Data organization</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>Bit</entry> + <entry>11</entry> + <entry>10</entry> + <entry>9</entry> + <entry>8</entry> + <entry>7</entry> + <entry>6</entry> + <entry>5</entry> + <entry>4</entry> + <entry>3</entry> + <entry>2</entry> + <entry>1</entry> + <entry>0</entry> + </row> + </thead> + <tbody valign="top"> + <row id="V4L2-MBUS-FMT-SBGGR8-1X8"> + <entry>V4L2_MBUS_FMT_SBGGR8_1X8</entry> + <entry>0x3001</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SGRBG8-1X8"> + <entry>V4L2_MBUS_FMT_SGRBG8_1X8</entry> + <entry>0x3002</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SBGGR10-DPCM8-1X8"> + <entry>V4L2_MBUS_FMT_SBGGR10_DPCM8_1X8</entry> + <entry>0x300b</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SGBRG10-DPCM8-1X8"> + <entry>V4L2_MBUS_FMT_SGBRG10_DPCM8_1X8</entry> + <entry>0x300c</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SGRBG10-DPCM8-1X8"> + <entry>V4L2_MBUS_FMT_SGRBG10_DPCM8_1X8</entry> + <entry>0x3009</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SRGGB10-DPCM8-1X8"> + <entry>V4L2_MBUS_FMT_SRGGB10_DPCM8_1X8</entry> + <entry>0x300d</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>r<subscript>7</subscript></entry> + <entry>r<subscript>6</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>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-BE"> + <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_BE</entry> + <entry>0x3003</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>b<subscript>9</subscript></entry> + <entry>b<subscript>8</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-LE"> + <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_LE</entry> + <entry>0x3004</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></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> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>b<subscript>9</subscript></entry> + <entry>b<subscript>8</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-BE"> + <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_BE</entry> + <entry>0x3005</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>b<subscript>9</subscript></entry> + <entry>b<subscript>8</subscript></entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></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> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + </row> + <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-LE"> + <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_LE</entry> + <entry>0x3006</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>b<subscript>9</subscript></entry> + <entry>b<subscript>8</subscript></entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SBGGR10-1X10"> + <entry>V4L2_MBUS_FMT_SBGGR10_1X10</entry> + <entry>0x3007</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>b<subscript>9</subscript></entry> + <entry>b<subscript>8</subscript></entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SGBRG10-1X10"> + <entry>V4L2_MBUS_FMT_SGBRG10_1X10</entry> + <entry>0x300e</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>g<subscript>9</subscript></entry> + <entry>g<subscript>8</subscript></entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SGRBG10-1X10"> + <entry>V4L2_MBUS_FMT_SGRBG10_1X10</entry> + <entry>0x300a</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>g<subscript>9</subscript></entry> + <entry>g<subscript>8</subscript></entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SRGGB10-1X10"> + <entry>V4L2_MBUS_FMT_SRGGB10_1X10</entry> + <entry>0x300f</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>r<subscript>9</subscript></entry> + <entry>r<subscript>8</subscript></entry> + <entry>r<subscript>7</subscript></entry> + <entry>r<subscript>6</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>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-SBGGR12-1X12"> + <entry>V4L2_MBUS_FMT_SBGGR12_1X12</entry> + <entry>0x3008</entry> + <entry></entry> + <entry>b<subscript>11</subscript></entry> + <entry>b<subscript>10</subscript></entry> + <entry>b<subscript>9</subscript></entry> + <entry>b<subscript>8</subscript></entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SGBRG12-1X12"> + <entry>V4L2_MBUS_FMT_SGBRG12_1X12</entry> + <entry>0x3010</entry> + <entry></entry> + <entry>g<subscript>11</subscript></entry> + <entry>g<subscript>10</subscript></entry> + <entry>g<subscript>9</subscript></entry> + <entry>g<subscript>8</subscript></entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SGRBG12-1X12"> + <entry>V4L2_MBUS_FMT_SGRBG12_1X12</entry> + <entry>0x3011</entry> + <entry></entry> + <entry>g<subscript>11</subscript></entry> + <entry>g<subscript>10</subscript></entry> + <entry>g<subscript>9</subscript></entry> + <entry>g<subscript>8</subscript></entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></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> + </row> + <row id="V4L2-MBUS-FMT-SRGGB12-1X12"> + <entry>V4L2_MBUS_FMT_SRGGB12_1X12</entry> + <entry>0x3012</entry> + <entry></entry> + <entry>r<subscript>11</subscript></entry> + <entry>r<subscript>10</subscript></entry> + <entry>r<subscript>9</subscript></entry> + <entry>r<subscript>8</subscript></entry> + <entry>r<subscript>7</subscript></entry> + <entry>r<subscript>6</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>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Packed YUV Formats</title> + + <para>Those data formats transfer pixel data as (possibly downsampled) Y, U + and V components. The format code is made of the following information. + <itemizedlist> + <listitem><para>The Y, U and V components order code, as transferred on the + bus. Possible values are YUYV, UYVY, YVYU and VYUY.</para></listitem> + <listitem><para>The number of bits per pixel component. All components are + transferred on the same number of bits. Common values are 8, 10 and 12.</para> + </listitem> + <listitem><para>The number of bus samples per pixel. Pixels that are wider than + the bus width must be transferred in multiple samples. Common values are + 1, 1.5 (encoded as 1_5) and 2.</para></listitem> + <listitem><para>The bus width. When the bus width is larger than the number of + bits per pixel component, several components are packed in a single bus + sample. The components are ordered as specified by the order code, with + components on the left of the code transferred in the high order bits. + Common values are 8 and 16.</para> + </listitem> + </itemizedlist> + </para> + + <para>For instance, a format where pixels are encoded as 8-bit YUV values + downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in the + U, Y, V, Y order will be named <constant>V4L2_MBUS_FMT_UYVY8_2X8</constant>. + </para> + + <para>The following table lisst existing packet YUV formats.</para> + + <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-yuv8"> + <title>YUV Formats</title> + <tgroup cols="23"> + <colspec colname="id" align="left" /> + <colspec colname="code" align="center"/> + <colspec colname="bit" /> + <colspec colnum="4" colname="b19" align="center" /> + <colspec colnum="5" colname="b18" align="center" /> + <colspec colnum="6" colname="b17" align="center" /> + <colspec colnum="7" colname="b16" align="center" /> + <colspec colnum="8" colname="b15" align="center" /> + <colspec colnum="9" colname="b14" align="center" /> + <colspec colnum="10" colname="b13" align="center" /> + <colspec colnum="11" colname="b12" align="center" /> + <colspec colnum="12" colname="b11" align="center" /> + <colspec colnum="13" colname="b10" align="center" /> + <colspec colnum="14" colname="b09" align="center" /> + <colspec colnum="15" colname="b08" align="center" /> + <colspec colnum="16" colname="b07" align="center" /> + <colspec colnum="17" colname="b06" align="center" /> + <colspec colnum="18" colname="b05" align="center" /> + <colspec colnum="19" colname="b04" align="center" /> + <colspec colnum="20" colname="b03" align="center" /> + <colspec colnum="21" colname="b02" align="center" /> + <colspec colnum="22" colname="b01" align="center" /> + <colspec colnum="23" colname="b00" align="center" /> + <spanspec namest="b19" nameend="b00" spanname="b0" /> + <thead> + <row> + <entry>Identifier</entry> + <entry>Code</entry> + <entry></entry> + <entry spanname="b0">Data organization</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>Bit</entry> + <entry>19</entry> + <entry>18</entry> + <entry>17</entry> + <entry>16</entry> + <entry>15</entry> + <entry>14</entry> + <entry>13</entry> + <entry>12</entry> + <entry>11</entry> + <entry>10</entry> + <entry>9</entry> + <entry>8</entry> + <entry>7</entry> + <entry>6</entry> + <entry>5</entry> + <entry>4</entry> + <entry>3</entry> + <entry>2</entry> + <entry>1</entry> + <entry>0</entry> + </row> + </thead> + <tbody valign="top"> + <row id="V4L2-MBUS-FMT-Y8-1X8"> + <entry>V4L2_MBUS_FMT_Y8_1X8</entry> + <entry>0x2001</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>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-UYVY8-1_5X8"> + <entry>V4L2_MBUS_FMT_UYVY8_1_5X8</entry> + <entry>0x2002</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>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-VYUY8-1_5X8"> + <entry>V4L2_MBUS_FMT_VYUY8_1_5X8</entry> + <entry>0x2003</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>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YUYV8-1_5X8"> + <entry>V4L2_MBUS_FMT_YUYV8_1_5X8</entry> + <entry>0x2004</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>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YVYU8-1_5X8"> + <entry>V4L2_MBUS_FMT_YVYU8_1_5X8</entry> + <entry>0x2005</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>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-UYVY8-2X8"> + <entry>V4L2_MBUS_FMT_UYVY8_2X8</entry> + <entry>0x2006</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>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-VYUY8-2X8"> + <entry>V4L2_MBUS_FMT_VYUY8_2X8</entry> + <entry>0x2007</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>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YUYV8-2X8"> + <entry>V4L2_MBUS_FMT_YUYV8_2X8</entry> + <entry>0x2008</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>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YVYU8-2X8"> + <entry>V4L2_MBUS_FMT_YVYU8_2X8</entry> + <entry>0x2009</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>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>-</entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-Y10-1X10"> + <entry>V4L2_MBUS_FMT_Y10_1X10</entry> + <entry>0x200a</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YUYV10-2X10"> + <entry>V4L2_MBUS_FMT_YUYV10_2X10</entry> + <entry>0x200b</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <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>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YVYU10-2X10"> + <entry>V4L2_MBUS_FMT_YVYU10_2X10</entry> + <entry>0x200c</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <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>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <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>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-UYVY8-1X16"> + <entry>V4L2_MBUS_FMT_UYVY8_1X16</entry> + <entry>0x200f</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-VYUY8-1X16"> + <entry>V4L2_MBUS_FMT_VYUY8_1X16</entry> + <entry>0x2010</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YUYV8-1X16"> + <entry>V4L2_MBUS_FMT_YUYV8_1X16</entry> + <entry>0x2011</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YVYU8-1X16"> + <entry>V4L2_MBUS_FMT_YVYU8_1X16</entry> + <entry>0x2012</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YUYV10-1X20"> + <entry>V4L2_MBUS_FMT_YUYV10_1X20</entry> + <entry>0x200d</entry> + <entry></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row id="V4L2-MBUS-FMT-YVYU10-1X20"> + <entry>V4L2_MBUS_FMT_YVYU10_1X20</entry> + <entry>0x200e</entry> + <entry></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>v<subscript>9</subscript></entry> + <entry>v<subscript>8</subscript></entry> + <entry>v<subscript>7</subscript></entry> + <entry>v<subscript>6</subscript></entry> + <entry>v<subscript>5</subscript></entry> + <entry>v<subscript>4</subscript></entry> + <entry>v<subscript>3</subscript></entry> + <entry>v<subscript>2</subscript></entry> + <entry>v<subscript>1</subscript></entry> + <entry>v<subscript>0</subscript></entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>y<subscript>9</subscript></entry> + <entry>y<subscript>8</subscript></entry> + <entry>y<subscript>7</subscript></entry> + <entry>y<subscript>6</subscript></entry> + <entry>y<subscript>5</subscript></entry> + <entry>y<subscript>4</subscript></entry> + <entry>y<subscript>3</subscript></entry> + <entry>y<subscript>2</subscript></entry> + <entry>y<subscript>1</subscript></entry> + <entry>y<subscript>0</subscript></entry> + <entry>u<subscript>9</subscript></entry> + <entry>u<subscript>8</subscript></entry> + <entry>u<subscript>7</subscript></entry> + <entry>u<subscript>6</subscript></entry> + <entry>u<subscript>5</subscript></entry> + <entry>u<subscript>4</subscript></entry> + <entry>u<subscript>3</subscript></entry> + <entry>u<subscript>2</subscript></entry> + <entry>u<subscript>1</subscript></entry> + <entry>u<subscript>0</subscript></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + </section> +</section> diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml index 7c3c098d5d08..a7fd76d0dac1 100644 --- a/Documentation/DocBook/v4l/v4l2.xml +++ b/Documentation/DocBook/v4l/v4l2.xml @@ -85,6 +85,17 @@ Remote Controller chapter.</contrib> </address> </affiliation> </author> + + <author> + <firstname>Pawel</firstname> + <surname>Osciak</surname> + <contrib>Designed and documented the multi-planar API.</contrib> + <affiliation> + <address> + <email>pawel AT osciak.com</email> + </address> + </affiliation> + </author> </authorgroup> <copyright> @@ -99,8 +110,11 @@ Remote Controller chapter.</contrib> <year>2007</year> <year>2008</year> <year>2009</year> + <year>2010</year> + <year>2011</year> <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin -Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab</holder> +Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, + Pawel Osciak</holder> </copyright> <legalnotice> <para>Except when explicitly stated as GPL, programming examples within @@ -110,10 +124,24 @@ 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.39</revnumber> + <date>2011-03-01</date> + <authorinitials>mcc, po</authorinitials> + <revremark>Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the <link linkend="planar-apis">multi-planar API</link>.</revremark> + </revision> + + <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> @@ -373,7 +401,7 @@ and discussions on the V4L mailing list.</revremark> </partinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 2.6.33</subtitle> + <subtitle>Revision 2.6.39</subtitle> <chapter id="common"> &sub-common; @@ -402,6 +430,7 @@ and discussions on the V4L mailing list.</revremark> <section id="radio"> &sub-dev-radio; </section> <section id="rds"> &sub-dev-rds; </section> <section id="event"> &sub-dev-event; </section> + <section id="subdev"> &sub-dev-subdev; </section> </chapter> <chapter id="driver"> @@ -469,6 +498,12 @@ and discussions on the V4L mailing list.</revremark> &sub-reqbufs; &sub-s-hw-freq-seek; &sub-streamon; + &sub-subdev-enum-frame-interval; + &sub-subdev-enum-frame-size; + &sub-subdev-enum-mbus-code; + &sub-subdev-g-crop; + &sub-subdev-g-fmt; + &sub-subdev-g-frame-interval; &sub-subscribe-event; <!-- End of ioctls. --> &sub-mmap; diff --git a/Documentation/DocBook/v4l/videodev2.h.xml b/Documentation/DocBook/v4l/videodev2.h.xml index 865b06d9e679..2b796a2ee98a 100644 --- a/Documentation/DocBook/v4l/videodev2.h.xml +++ b/Documentation/DocBook/v4l/videodev2.h.xml @@ -71,6 +71,7 @@ * Moved from videodev.h */ #define VIDEO_MAX_FRAME 32 +#define VIDEO_MAX_PLANES 8 #ifndef __KERNEL__ @@ -154,22 +155,26 @@ 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_VIDEO_CAPTURE_MPLANE = 9, + V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE = 10, 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, -}; +#define V4L2_TYPE_IS_MULTIPLANAR(type) \ + ((type) == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE \ + || (type) == V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE) + +#define V4L2_TYPE_IS_OUTPUT(type) \ + ((type) == V4L2_BUF_TYPE_VIDEO_OUTPUT \ + || (type) == V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE \ + || (type) == V4L2_BUF_TYPE_VIDEO_OVERLAY \ + || (type) == V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY \ + || (type) == V4L2_BUF_TYPE_VBI_OUTPUT \ + || (type) == V4L2_BUF_TYPE_SLICED_VBI_OUTPUT) enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> { V4L2_TUNER_RADIO = 1, @@ -256,6 +261,11 @@ struct <link linkend="v4l2-capability">v4l2_capability</link> { #define V4L2_CAP_HW_FREQ_SEEK 0x00000400 /* Can do hardware frequency seek */ #define V4L2_CAP_RDS_OUTPUT 0x00000800 /* Is an RDS encoder */ +/* Is a video capture device that supports multiplanar formats */ +#define V4L2_CAP_VIDEO_CAPTURE_MPLANE 0x00001000 +/* Is a video output device that supports multiplanar formats */ +#define V4L2_CAP_VIDEO_OUTPUT_MPLANE 0x00002000 + #define V4L2_CAP_TUNER 0x00010000 /* has a tuner */ #define V4L2_CAP_AUDIO 0x00020000 /* has audio support */ #define V4L2_CAP_RADIO 0x00040000 /* is a radio device */ @@ -288,6 +298,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 +306,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 */ @@ -326,11 +340,22 @@ struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> { #define <link linkend="V4L2-PIX-FMT-NV16">V4L2_PIX_FMT_NV16</link> v4l2_fourcc('N', 'V', '1', '6') /* 16 Y/CbCr 4:2:2 */ #define <link linkend="V4L2-PIX-FMT-NV61">V4L2_PIX_FMT_NV61</link> v4l2_fourcc('N', 'V', '6', '1') /* 16 Y/CrCb 4:2:2 */ +/* two non contiguous planes - one Y, one Cr + Cb interleaved */ +#define <link linkend="V4L2-PIX-FMT-NV12M">V4L2_PIX_FMT_NV12M</link> v4l2_fourcc('N', 'M', '1', '2') /* 12 Y/CbCr 4:2:0 */ +#define <link linkend="V4L2-PIX-FMT-NV12MT">V4L2_PIX_FMT_NV12MT</link> v4l2_fourcc('T', 'M', '1', '2') /* 12 Y/CbCr 4:2:0 64x32 macroblocks */ + +/* three non contiguous planes - Y, Cb, Cr */ +#define <link linkend="V4L2-PIX-FMT-YUV420M">V4L2_PIX_FMT_YUV420M</link> v4l2_fourcc('Y', 'M', '1', '2') /* 12 YUV420 planar */ + /* Bayer formats - see http://www.siliconimaging.com/RGB%20Bayer.htm */ #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 +371,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 +384,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 +409,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 @@ -516,6 +545,62 @@ struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> { __u32 reserved[2]; }; +/** + * struct <link linkend="v4l2-plane">v4l2_plane</link> - plane info for multi-planar buffers + * @bytesused: number of bytes occupied by data in the plane (payload) + * @length: size of this plane (NOT the payload) in bytes + * @mem_offset: when memory in the associated struct <link linkend="v4l2-buffer">v4l2_buffer</link> is + * V4L2_MEMORY_MMAP, equals the offset from the start of + * the device memory for this plane (or is a "cookie" that + * should be passed to mmap() called on the video node) + * @userptr: when memory is V4L2_MEMORY_USERPTR, a userspace pointer + * pointing to this plane + * @data_offset: offset in the plane to the start of data; usually 0, + * unless there is a header in front of the data + * + * Multi-planar buffers consist of one or more planes, e.g. an YCbCr buffer + * with two planes can have one plane for Y, and another for interleaved CbCr + * components. Each plane can reside in a separate memory buffer, or even in + * a completely separate memory node (e.g. in embedded devices). + */ +struct <link linkend="v4l2-plane">v4l2_plane</link> { + __u32 bytesused; + __u32 length; + union { + __u32 mem_offset; + unsigned long userptr; + } m; + __u32 data_offset; + __u32 reserved[11]; +}; + +/** + * struct <link linkend="v4l2-buffer">v4l2_buffer</link> - video buffer info + * @index: id number of the buffer + * @type: buffer type (type == *_MPLANE for multiplanar buffers) + * @bytesused: number of bytes occupied by data in the buffer (payload); + * unused (set to 0) for multiplanar buffers + * @flags: buffer informational flags + * @field: field order of the image in the buffer + * @timestamp: frame timestamp + * @timecode: frame timecode + * @sequence: sequence count of this frame + * @memory: the method, in which the actual video data is passed + * @offset: for non-multiplanar buffers with memory == V4L2_MEMORY_MMAP; + * offset from the start of the device memory for this plane, + * (or a "cookie" that should be passed to mmap() as offset) + * @userptr: for non-multiplanar buffers with memory == V4L2_MEMORY_USERPTR; + * a userspace pointer pointing to this buffer + * @planes: for multiplanar buffers; userspace pointer to the array of plane + * info structs for this buffer + * @length: size in bytes of the buffer (NOT its payload) for single-plane + * buffers (when type != *_MPLANE); number of elements in the + * planes array for multi-plane buffers + * @input: input number from which the video data has has been captured + * + * Contains data exchanged by application and driver using one of the Streaming + * I/O methods. + */ struct <link linkend="v4l2-buffer">v4l2_buffer</link> { __u32 index; enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; @@ -531,6 +616,7 @@ struct <link linkend="v4l2-buffer">v4l2_buffer</link> { union { __u32 offset; unsigned long userptr; + struct <link linkend="v4l2-plane">v4l2_plane</link> *planes; } m; __u32 length; __u32 input; @@ -544,6 +630,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 +1022,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 +1116,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 +1453,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 +1484,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 +1540,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) @@ -1600,12 +1707,56 @@ struct <link linkend="v4l2-mpeg-vbi-fmt-ivtv">v4l2_mpeg_vbi_fmt_ivtv</link> { * A G G R E G A T E S T R U C T U R E S */ -/* Stream data format +/** + * struct <link linkend="v4l2-plane-pix-format">v4l2_plane_pix_format</link> - additional, per-plane format definition + * @sizeimage: maximum size in bytes required for data, for which + * this plane will be used + * @bytesperline: distance in bytes between the leftmost pixels in two + * adjacent lines + */ +struct <link linkend="v4l2-plane-pix-format">v4l2_plane_pix_format</link> { + __u32 sizeimage; + __u16 bytesperline; + __u16 reserved[7]; +} __attribute__ ((packed)); + +/** + * struct <link linkend="v4l2-pix-format-mplane">v4l2_pix_format_mplane</link> - multiplanar format definition + * @width: image width in pixels + * @height: image height in pixels + * @pixelformat: little endian four character code (fourcc) + * @field: field order (for interlaced video) + * @colorspace: supplemental to pixelformat + * @plane_fmt: per-plane information + * @num_planes: number of planes for this format + */ +struct <link linkend="v4l2-pix-format-mplane">v4l2_pix_format_mplane</link> { + __u32 width; + __u32 height; + __u32 pixelformat; + enum <link linkend="v4l2-field">v4l2_field</link> field; + enum <link linkend="v4l2-colorspace">v4l2_colorspace</link> colorspace; + + struct <link linkend="v4l2-plane-pix-format">v4l2_plane_pix_format</link> plane_fmt[VIDEO_MAX_PLANES]; + __u8 num_planes; + __u8 reserved[11]; +} __attribute__ ((packed)); + +/** + * struct <link linkend="v4l2-format">v4l2_format</link> - stream data format + * @type: type of the data stream + * @pix: definition of an image format + * @pix_mp: definition of a multiplanar image format + * @win: definition of an overlaid image + * @vbi: raw VBI capture or output parameters + * @sliced: sliced VBI capture or output parameters + * @raw_data: placeholder for future extensions and custom formats */ struct <link linkend="v4l2-format">v4l2_format</link> { enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; union { struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> pix; /* V4L2_BUF_TYPE_VIDEO_CAPTURE */ + struct <link linkend="v4l2-pix-format-mplane">v4l2_pix_format_mplane</link> pix_mp; /* V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE */ struct <link linkend="v4l2-window">v4l2_window</link> win; /* V4L2_BUF_TYPE_VIDEO_OVERLAY */ struct <link linkend="v4l2-vbi-format">v4l2_vbi_format</link> vbi; /* V4L2_BUF_TYPE_VBI_CAPTURE */ struct <link linkend="v4l2-sliced-vbi-format">v4l2_sliced_vbi_format</link> sliced; /* V4L2_BUF_TYPE_SLICED_VBI_CAPTURE */ @@ -1613,7 +1764,6 @@ struct <link linkend="v4l2-format">v4l2_format</link> { } fmt; }; - /* Stream type-dependent parameters */ struct <link linkend="v4l2-streamparm">v4l2_streamparm</link> { @@ -1626,6 +1776,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 +1902,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 +1910,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,20 +1929,13 @@ 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! */ -#ifdef __OLD_VIDIOC_ -/* for compatibility, will go away some day */ -#define VIDIOC_OVERLAY_OLD _IOWR('V', 14, int) -#define VIDIOC_S_PARM_OLD _IOW('V', 22, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>) -#define VIDIOC_S_CTRL_OLD _IOW('V', 28, struct <link linkend="v4l2-control">v4l2_control</link>) -#define VIDIOC_G_AUDIO_OLD _IOWR('V', 33, struct <link linkend="v4l2-audio">v4l2_audio</link>) -#define VIDIOC_G_AUDOUT_OLD _IOWR('V', 49, struct <link linkend="v4l2-audioout">v4l2_audioout</link>) -#define VIDIOC_CROPCAP_OLD _IOR('V', 58, struct <link linkend="v4l2-cropcap">v4l2_cropcap</link>) -#endif - #define BASE_VIDIOC_PRIVATE 192 /* 192-255 are private */ #endif /* __LINUX_VIDEODEV2_H */ diff --git a/Documentation/DocBook/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml index 960d44615ca6..71d373b6d36a 100644 --- a/Documentation/DocBook/v4l/vidioc-enum-fmt.xml +++ b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml @@ -76,7 +76,9 @@ pixelformat</structfield> field.</entry> <entry>Type of the data stream, set by the application. Only these types are valid here: <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>, <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry> diff --git a/Documentation/DocBook/v4l/vidioc-g-dv-preset.xml b/Documentation/DocBook/v4l/vidioc-g-dv-preset.xml index 3c6784e132f3..d733721a7519 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 ecc19576bb8f..d5ec6abf0ce2 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-g-fmt.xml b/Documentation/DocBook/v4l/vidioc-g-fmt.xml index 7c7d1b72c40d..a4ae59b664eb 100644 --- a/Documentation/DocBook/v4l/vidioc-g-fmt.xml +++ b/Documentation/DocBook/v4l/vidioc-g-fmt.xml @@ -60,11 +60,13 @@ application.</para> <structfield>type</structfield> field of a struct <structname>v4l2_format</structname> to the respective buffer (stream) type. For example video capture devices use -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. When the application +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to this structure the driver fills the respective member of the <structfield>fmt</structfield> union. In case of video capture devices -that is the &v4l2-pix-format; <structfield>pix</structfield> member. +that is either the &v4l2-pix-format; <structfield>pix</structfield> or +the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member. When the requested buffer type is not supported drivers return an &EINVAL;.</para> @@ -134,6 +136,15 @@ devices.</entry> </row> <row> <entry></entry> + <entry>&v4l2-pix-format-mplane;</entry> + <entry><structfield>pix_mp</structfield></entry> + <entry>Definition of an image format, see <xref + linkend="pixfmt" />, used by video capture and output +devices that support the <link linkend="planar-apis">multi-planar +version of the API</link>.</entry> + </row> + <row> + <entry></entry> <entry>&v4l2-window;</entry> <entry><structfield>win</structfield></entry> <entry>Definition of an overlaid image, see <xref diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml index ab691ebf3b93..f2b11f8a4031 100644 --- a/Documentation/DocBook/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml @@ -64,7 +64,8 @@ zero to the number of buffers allocated with &VIDIOC-REQBUFS; contents of the struct <structname>v4l2_buffer</structname> returned by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is intended for output (<structfield>type</structfield> is -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also initialize the <structfield>bytesused</structfield>, <structfield>field</structfield> and @@ -75,7 +76,11 @@ supports capturing from specific video inputs and you want to specify a video input, then <structfield>flags</structfield> should be set to <constant>V4L2_BUF_FLAG_INPUT</constant> and the field <structfield>input</structfield> must be initialized to the desired input. -The <structfield>reserved</structfield> field must be set to 0. +The <structfield>reserved</structfield> field must be set to 0. When using +the <link linkend="planar-apis">multi-planar API</link>, the +<structfield>m.planes</structfield> field must contain a userspace pointer +to a filled-in array of &v4l2-plane; and the <structfield>length</structfield> +field must be set to the number of elements in that array. </para> <para>To enqueue a <link linkend="mmap">memory mapped</link> @@ -93,10 +98,13 @@ structure the driver sets the buffer applications set the <structfield>memory</structfield> field to <constant>V4L2_MEMORY_USERPTR</constant>, the <structfield>m.userptr</structfield> field to the address of the -buffer and <structfield>length</structfield> to its size. -When <constant>VIDIOC_QBUF</constant> is called with a pointer to this -structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> -flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and +buffer and <structfield>length</structfield> to its size. When the multi-planar +API is used, <structfield>m.userptr</structfield> and +<structfield>length</structfield> members of the passed array of &v4l2-plane; +have to be used instead. When <constant>VIDIOC_QBUF</constant> is called with +a pointer to this structure the driver sets the +<constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the +<constant>V4L2_BUF_FLAG_MAPPED</constant> and <constant>V4L2_BUF_FLAG_DONE</constant> flags in the <structfield>flags</structfield> field, or it returns an error code. This ioctl locks the memory pages of the buffer in physical memory, @@ -115,7 +123,9 @@ remaining fields or returns an error code. The driver may also set <constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield> field. It indicates a non-critical (recoverable) streaming error. In such case the application may continue as normal, but should be aware that data in the -dequeued buffer might be corrupted.</para> +dequeued buffer might be corrupted. When using the multi-planar API, the +planes array does not have to be passed; the <structfield>m.planes</structfield> +member must be set to NULL in that case.</para> <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the outgoing queue. When the diff --git a/Documentation/DocBook/v4l/vidioc-query-dv-preset.xml b/Documentation/DocBook/v4l/vidioc-query-dv-preset.xml index 402229ee06f6..d272f7ab91b8 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-querybuf.xml b/Documentation/DocBook/v4l/vidioc-querybuf.xml index e649805a4908..5c104d42d31c 100644 --- a/Documentation/DocBook/v4l/vidioc-querybuf.xml +++ b/Documentation/DocBook/v4l/vidioc-querybuf.xml @@ -61,6 +61,10 @@ buffer at any time after buffers have been allocated with the to the number of buffers allocated with &VIDIOC-REQBUFS; (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The <structfield>reserved</structfield> field should to set to 0. +When using the <link linkend="planar-apis">multi-planar API</link>, the +<structfield>m.planes</structfield> field must contain a userspace pointer to an +array of &v4l2-plane; and the <structfield>length</structfield> field has +to be set to the number of elements in that array. After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to this structure drivers return an error code or fill the rest of the structure.</para> @@ -70,11 +74,13 @@ the structure.</para> <constant>V4L2_BUF_FLAG_QUEUED</constant> and <constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The <structfield>memory</structfield> field will be set to the current -I/O method, the <structfield>m.offset</structfield> +I/O method. For the single-planar API, the <structfield>m.offset</structfield> contains the offset of the buffer from the start of the device memory, -the <structfield>length</structfield> field its size. The driver may -or may not set the remaining fields and flags, they are meaningless in -this context.</para> +the <structfield>length</structfield> field its size. For the multi-planar API, +fields <structfield>m.mem_offset</structfield> and +<structfield>length</structfield> in the <structfield>m.planes</structfield> +array elements will be used instead. The driver may or may not set the remaining +fields and flags, they are meaningless in this context.</para> <para>The <structname>v4l2_buffer</structname> structure is specified in <xref linkend="buffer" />.</para> diff --git a/Documentation/DocBook/v4l/vidioc-querycap.xml b/Documentation/DocBook/v4l/vidioc-querycap.xml index 6ab7e25b31b6..f29f1b86213c 100644 --- a/Documentation/DocBook/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/v4l/vidioc-querycap.xml @@ -142,16 +142,30 @@ this array to zero.</entry> <row> <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry> <entry>0x00000001</entry> - <entry>The device supports the <link + <entry>The device supports the single-planar API through the <link linkend="capture">Video Capture</link> interface.</entry> </row> <row> + <entry><constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant></entry> + <entry>0x00001000</entry> + <entry>The device supports the + <link linkend="planar-apis">multi-planar API</link> through the + <link linkend="capture">Video Capture</link> interface.</entry> + </row> + <row> <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry> <entry>0x00000002</entry> - <entry>The device supports the <link + <entry>The device supports the single-planar API through the <link linkend="output">Video Output</link> interface.</entry> </row> <row> + <entry><constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant></entry> + <entry>0x00002000</entry> + <entry>The device supports the + <link linkend="planar-apis">multi-planar API</link> through the + <link linkend="output">Video Output</link> interface.</entry> + </row> + <row> <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry> <entry>0x00000004</entry> <entry>The device supports the <link @@ -184,7 +198,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 +220,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 8e0e055ac934..0d5e8283cf32 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 14b3ec7ed75b..c30dcc4232c0 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/DocBook/v4l/vidioc-streamon.xml b/Documentation/DocBook/v4l/vidioc-streamon.xml index e42bff1f2c0a..75ed39bf4d2b 100644 --- a/Documentation/DocBook/v4l/vidioc-streamon.xml +++ b/Documentation/DocBook/v4l/vidioc-streamon.xml @@ -93,6 +93,15 @@ synchronize with other events.</para> been allocated (memory mapping) or enqueued (output) yet.</para> </listitem> </varlistentry> + <varlistentry> + <term><errorcode>EPIPE</errorcode></term> + <listitem> + <para>The driver implements <link + linkend="pad-level-formats">pad-level format configuration</link> and + the pipeline configuration is invalid. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> </refentry> diff --git a/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-interval.xml b/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-interval.xml new file mode 100644 index 000000000000..2f8f4f0a0235 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-interval.xml @@ -0,0 +1,152 @@ +<refentry id="vidioc-subdev-enum-frame-interval"> + <refmeta> + <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refname> + <refpurpose>Enumerate frame intervals</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct v4l2_subdev_frame_interval_enum * + <parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental">experimental</link> + interface and may change in the future.</para> + </note> + + <para>This ioctl lets applications enumerate available frame intervals on a + given sub-device pad. Frame intervals only makes sense for sub-devices that + can control the frame period on their own. This includes, for instance, + image sensors and TV tuners.</para> + + <para>For the common use case of image sensors, the frame intervals + available on the sub-device output pad depend on the frame format and size + on the same pad. Applications must thus specify the desired format and size + when enumerating frame intervals.</para> + + <para>To enumerate frame intervals applications initialize the + <structfield>index</structfield>, <structfield>pad</structfield>, + <structfield>code</structfield>, <structfield>width</structfield> and + <structfield>height</structfield> fields of + &v4l2-subdev-frame-interval-enum; and call the + <constant>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</constant> ioctl with a pointer + to this structure. Drivers fill the rest of the structure or return + an &EINVAL; if one of the input fields is invalid. All frame intervals are + enumerable by beginning at index zero and incrementing by one until + <errorcode>EINVAL</errorcode> is returned.</para> + + <para>Available frame intervals may depend on the current 'try' formats + at other pads of the sub-device, as well as on the current active links. See + &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para> + + <para>Sub-devices that support the frame interval enumeration ioctl should + implemented it on a single pad only. Its behaviour when supported on + multiple pads of the same sub-device is not defined.</para> + + <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval-enum"> + <title>struct <structname>v4l2_subdev_frame_interval_enum</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>index</structfield></entry> + <entry>Number of the format in the enumeration, set by the + application.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>pad</structfield></entry> + <entry>Pad number as reported by the media controller API.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>code</structfield></entry> + <entry>The media bus format code, as defined in + <xref linkend="v4l2-mbus-format" />.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>width</structfield></entry> + <entry>Frame width, in pixels.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>height</structfield></entry> + <entry>Frame height, in pixels.</entry> + </row> + <row> + <entry>&v4l2-fract;</entry> + <entry><structfield>interval</structfield></entry> + <entry>Period, in seconds, between consecutive video frames.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[9]</entry> + <entry>Reserved for future extensions. Applications and drivers must + set the array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The &v4l2-subdev-frame-interval-enum; + <structfield>pad</structfield> references a non-existing pad, one of + the <structfield>code</structfield>, <structfield>width</structfield> + or <structfield>height</structfield> fields are invalid for the given + pad or the <structfield>index</structfield> field is out of bounds. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml b/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml new file mode 100644 index 000000000000..79ce42b7c60c --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml @@ -0,0 +1,154 @@ +<refentry id="vidioc-subdev-enum-frame-size"> + <refmeta> + <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</refname> + <refpurpose>Enumerate media bus frame sizes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct v4l2_subdev_frame_size_enum * + <parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental">experimental</link> + interface and may change in the future.</para> + </note> + + <para>This ioctl allows applications to enumerate all frame sizes + supported by a sub-device on the given pad for the given media bus format. + Supported formats can be retrieved with the &VIDIOC-SUBDEV-ENUM-MBUS-CODE; + ioctl.</para> + + <para>To enumerate frame sizes applications initialize the + <structfield>pad</structfield>, <structfield>code</structfield> and + <structfield>index</structfield> fields of the + &v4l2-subdev-mbus-code-enum; and call the + <constant>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</constant> ioctl with a pointer to + the structure. Drivers fill the minimum and maximum frame sizes or return + an &EINVAL; if one of the input parameters is invalid.</para> + + <para>Sub-devices that only support discrete frame sizes (such as most + sensors) will return one or more frame sizes with identical minimum and + maximum values.</para> + + <para>Not all possible sizes in given [minimum, maximum] ranges need to be + supported. For instance, a scaler that uses a fixed-point scaling ratio + might not be able to produce every frame size between the minimum and + maximum values. Applications must use the &VIDIOC-SUBDEV-S-FMT; ioctl to + try the sub-device for an exact supported frame size.</para> + + <para>Available frame sizes may depend on the current 'try' formats at other + pads of the sub-device, as well as on the current active links and the + current values of V4L2 controls. See &VIDIOC-SUBDEV-G-FMT; for more + information about try formats.</para> + + <table pgwide="1" frame="none" id="v4l2-subdev-frame-size-enum"> + <title>struct <structname>v4l2_subdev_frame_size_enum</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>index</structfield></entry> + <entry>Number of the format in the enumeration, set by the + application.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>pad</structfield></entry> + <entry>Pad number as reported by the media controller API.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>code</structfield></entry> + <entry>The media bus format code, as defined in + <xref linkend="v4l2-mbus-format" />.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>min_width</structfield></entry> + <entry>Minimum frame width, in pixels.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>max_width</structfield></entry> + <entry>Maximum frame width, in pixels.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>min_height</structfield></entry> + <entry>Minimum frame height, in pixels.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>max_height</structfield></entry> + <entry>Maximum frame height, in pixels.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[9]</entry> + <entry>Reserved for future extensions. Applications and drivers must + set the array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The &v4l2-subdev-frame-size-enum; <structfield>pad</structfield> + references a non-existing pad, the <structfield>code</structfield> is + invalid for the given pad or the <structfield>index</structfield> + field is out of bounds.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/vidioc-subdev-enum-mbus-code.xml b/Documentation/DocBook/v4l/vidioc-subdev-enum-mbus-code.xml new file mode 100644 index 000000000000..a6b3432449f6 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-subdev-enum-mbus-code.xml @@ -0,0 +1,119 @@ +<refentry id="vidioc-subdev-enum-mbus-code"> + <refmeta> + <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_SUBDEV_ENUM_MBUS_CODE</refname> + <refpurpose>Enumerate media bus formats</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct v4l2_subdev_mbus_code_enum * + <parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>VIDIOC_SUBDEV_ENUM_MBUS_CODE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental">experimental</link> + interface and may change in the future.</para> + </note> + + <para>To enumerate media bus formats available at a given sub-device pad + applications initialize the <structfield>pad</structfield> and + <structfield>index</structfield> fields of &v4l2-subdev-mbus-code-enum; and + call the <constant>VIDIOC_SUBDEV_ENUM_MBUS_CODE</constant> ioctl with a + pointer to this structure. Drivers fill the rest of the structure or return + an &EINVAL; if either the <structfield>pad</structfield> or + <structfield>index</structfield> are invalid. All media bus formats are + enumerable by beginning at index zero and incrementing by one until + <errorcode>EINVAL</errorcode> is returned.</para> + + <para>Available media bus formats may depend on the current 'try' formats + at other pads of the sub-device, as well as on the current active links. See + &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para> + + <table pgwide="1" frame="none" id="v4l2-subdev-mbus-code-enum"> + <title>struct <structname>v4l2_subdev_mbus_code_enum</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>pad</structfield></entry> + <entry>Pad number as reported by the media controller API.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>index</structfield></entry> + <entry>Number of the format in the enumeration, set by the + application.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>code</structfield></entry> + <entry>The media bus format code, as defined in + <xref linkend="v4l2-mbus-format" />.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[9]</entry> + <entry>Reserved for future extensions. Applications and drivers must + set the array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The &v4l2-subdev-mbus-code-enum; <structfield>pad</structfield> + references a non-existing pad, or the <structfield>index</structfield> + field is out of bounds.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/vidioc-subdev-g-crop.xml b/Documentation/DocBook/v4l/vidioc-subdev-g-crop.xml new file mode 100644 index 000000000000..06197323a8cc --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-subdev-g-crop.xml @@ -0,0 +1,155 @@ +<refentry id="vidioc-subdev-g-crop"> + <refmeta> + <refentrytitle>ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_SUBDEV_G_CROP</refname> + <refname>VIDIOC_SUBDEV_S_CROP</refname> + <refpurpose>Get or set the crop rectangle on a subdev pad</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct v4l2_subdev_crop *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>const struct v4l2_subdev_crop *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental">experimental</link> + interface and may change in the future.</para> + </note> + + <para>To retrieve the current crop rectangle applications set the + <structfield>pad</structfield> field of a &v4l2-subdev-crop; to the + desired pad number as reported by the media API and the + <structfield>which</structfield> field to + <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. They then call the + <constant>VIDIOC_SUBDEV_G_CROP</constant> ioctl with a pointer to this + structure. The driver fills the members of the <structfield>rect</structfield> + field or returns &EINVAL; if the input arguments are invalid, or if cropping + is not supported on the given pad.</para> + + <para>To change the current crop rectangle applications set both the + <structfield>pad</structfield> and <structfield>which</structfield> fields + and all members of the <structfield>rect</structfield> field. They then call + the <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctl with a pointer to this + structure. The driver verifies the requested crop rectangle, adjusts it + based on the hardware capabilities and configures the device. Upon return + the &v4l2-subdev-crop; contains the current format as would be returned + by a <constant>VIDIOC_SUBDEV_G_CROP</constant> call.</para> + + <para>Applications can query the device capabilities by setting the + <structfield>which</structfield> to + <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' crop + rectangles are not applied to the device by the driver, but are mangled + exactly as active crop rectangles and stored in the sub-device file handle. + Two applications querying the same sub-device would thus not interact with + each other.</para> + + <para>Drivers must not return an error solely because the requested crop + rectangle doesn't match the device capabilities. They must instead modify + the rectangle to match what the hardware can provide. The modified format + should be as close as possible to the original request.</para> + + <table pgwide="1" frame="none" id="v4l2-subdev-crop"> + <title>struct <structname>v4l2_subdev_crop</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>pad</structfield></entry> + <entry>Pad number as reported by the media framework.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>which</structfield></entry> + <entry>Crop rectangle to get or set, from + &v4l2-subdev-format-whence;.</entry> + </row> + <row> + <entry>&v4l2-rect;</entry> + <entry><structfield>rect</structfield></entry> + <entry>Crop rectangle boundaries, in pixels.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[8]</entry> + <entry>Reserved for future extensions. Applications and drivers must + set the array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> + <listitem> + <para>The crop rectangle can't be changed because the pad is currently + busy. This can be caused, for instance, by an active video stream on + the pad. The ioctl must not be retried without performing another + action to fix the problem first. Only returned by + <constant>VIDIOC_SUBDEV_S_CROP</constant></para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The &v4l2-subdev-crop; <structfield>pad</structfield> + references a non-existing pad, the <structfield>which</structfield> + field references a non-existing format, or cropping is not supported + on the given subdev pad.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/vidioc-subdev-g-fmt.xml b/Documentation/DocBook/v4l/vidioc-subdev-g-fmt.xml new file mode 100644 index 000000000000..f367c570c530 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-subdev-g-fmt.xml @@ -0,0 +1,180 @@ +<refentry id="vidioc-subdev-g-fmt"> + <refmeta> + <refentrytitle>ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_SUBDEV_G_FMT</refname> + <refname>VIDIOC_SUBDEV_S_FMT</refname> + <refpurpose>Get or set the data format on a subdev pad</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct v4l2_subdev_format *<parameter>argp</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental">experimental</link> + interface and may change in the future.</para> + </note> + + <para>These ioctls are used to negotiate the frame format at specific + subdev pads in the image pipeline.</para> + + <para>To retrieve the current format applications set the + <structfield>pad</structfield> field of a &v4l2-subdev-format; to the + desired pad number as reported by the media API and the + <structfield>which</structfield> field to + <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. When they call the + <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl with a pointer to this + structure the driver fills the members of the <structfield>format</structfield> + field.</para> + + <para>To change the current format applications set both the + <structfield>pad</structfield> and <structfield>which</structfield> fields + and all members of the <structfield>format</structfield> field. When they + call the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl with a pointer to this + structure the driver verifies the requested format, adjusts it based on the + hardware capabilities and configures the device. Upon return the + &v4l2-subdev-format; contains the current format as would be returned by a + <constant>VIDIOC_SUBDEV_G_FMT</constant> call.</para> + + <para>Applications can query the device capabilities by setting the + <structfield>which</structfield> to + <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' formats are not + applied to the device by the driver, but are changed exactly as active + formats and stored in the sub-device file handle. Two applications querying + the same sub-device would thus not interact with each other.</para> + + <para>For instance, to try a format at the output pad of a sub-device, + applications would first set the try format at the sub-device input with the + <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl. They would then either + retrieve the default format at the output pad with the + <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl, or set the desired output + pad format with the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl and check + the returned value.</para> + + <para>Try formats do not depend on active formats, but can depend on the + current links configuration or sub-device controls value. For instance, a + low-pass noise filter might crop pixels at the frame boundaries, modifying + its output frame size.</para> + + <para>Drivers must not return an error solely because the requested format + doesn't match the device capabilities. They must instead modify the format + to match what the hardware can provide. The modified format should be as + close as possible to the original request.</para> + + <table pgwide="1" frame="none" id="v4l2-subdev-format"> + <title>struct <structname>v4l2_subdev_format</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>pad</structfield></entry> + <entry>Pad number as reported by the media controller API.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>which</structfield></entry> + <entry>Format to modified, from &v4l2-subdev-format-whence;.</entry> + </row> + <row> + <entry>&v4l2-mbus-framefmt;</entry> + <entry><structfield>format</structfield></entry> + <entry>Definition of an image format, see <xref + linkend="v4l2-mbus-framefmt" /> for details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[8]</entry> + <entry>Reserved for future extensions. Applications and drivers must + set the array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="v4l2-subdev-format-whence"> + <title>enum <structname>v4l2_subdev_format_whence</structname></title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry>V4L2_SUBDEV_FORMAT_TRY</entry> + <entry>0</entry> + <entry>Try formats, used for querying device capabilities.</entry> + </row> + <row> + <entry>V4L2_SUBDEV_FORMAT_ACTIVE</entry> + <entry>1</entry> + <entry>Active formats, applied to the hardware.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> + <listitem> + <para>The format can't be changed because the pad is currently busy. + This can be caused, for instance, by an active video stream on the + pad. The ioctl must not be retried without performing another action + to fix the problem first. Only returned by + <constant>VIDIOC_SUBDEV_S_FMT</constant></para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The &v4l2-subdev-format; <structfield>pad</structfield> + references a non-existing pad, or the <structfield>which</structfield> + field references a non-existing format.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/v4l/vidioc-subdev-g-frame-interval.xml b/Documentation/DocBook/v4l/vidioc-subdev-g-frame-interval.xml new file mode 100644 index 000000000000..0bc3ea22d31f --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-subdev-g-frame-interval.xml @@ -0,0 +1,141 @@ +<refentry id="vidioc-subdev-g-frame-interval"> + <refmeta> + <refentrytitle>ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_SUBDEV_G_FRAME_INTERVAL</refname> + <refname>VIDIOC_SUBDEV_S_FRAME_INTERVAL</refname> + <refpurpose>Get or set the frame interval on a subdev pad</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct v4l2_subdev_frame_interval *<parameter>argp</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental">experimental</link> + interface and may change in the future.</para> + </note> + + <para>These ioctls are used to get and set the frame interval at specific + subdev pads in the image pipeline. The frame interval only makes sense for + sub-devices that can control the frame period on their own. This includes, + for instance, image sensors and TV tuners. Sub-devices that don't support + frame intervals must not implement these ioctls.</para> + + <para>To retrieve the current frame interval applications set the + <structfield>pad</structfield> field of a &v4l2-subdev-frame-interval; to + the desired pad number as reported by the media controller API. When they + call the <constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant> ioctl with a + pointer to this structure the driver fills the members of the + <structfield>interval</structfield> field.</para> + + <para>To change the current frame interval applications set both the + <structfield>pad</structfield> field and all members of the + <structfield>interval</structfield> field. When they call the + <constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant> ioctl with a pointer to + this structure the driver verifies the requested interval, adjusts it based + on the hardware capabilities and configures the device. Upon return the + &v4l2-subdev-frame-interval; contains the current frame interval as would be + returned by a <constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant> call. + </para> + + <para>Drivers must not return an error solely because the requested interval + doesn't match the device capabilities. They must instead modify the interval + to match what the hardware can provide. The modified interval should be as + close as possible to the original request.</para> + + <para>Sub-devices that support the frame interval ioctls should implement + them on a single pad only. Their behaviour when supported on multiple pads + of the same sub-device is not defined.</para> + + <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval"> + <title>struct <structname>v4l2_subdev_frame_interval</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>pad</structfield></entry> + <entry>Pad number as reported by the media controller API.</entry> + </row> + <row> + <entry>&v4l2-fract;</entry> + <entry><structfield>interval</structfield></entry> + <entry>Period, in seconds, between consecutive video frames.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[9]</entry> + <entry>Reserved for future extensions. Applications and drivers must + set the array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> + <listitem> + <para>The frame interval can't be changed because the pad is currently + busy. This can be caused, for instance, by an active video stream on + the pad. The ioctl must not be retried without performing another + action to fix the problem first. Only returned by + <constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant></para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The &v4l2-subdev-frame-interval; <structfield>pad</structfield> + references a non-existing pad, or the pad doesn't support frame + intervals.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl index 0ba149de2608..58ced2346e67 100644 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl @@ -4784,7 +4784,7 @@ struct _snd_pcm_runtime { FM registers can be directly accessed through the direct-FM API, defined in <filename><sound/asound_fm.h></filename>. In ALSA native mode, FM registers are accessed through - the Hardware-Dependant Device direct-FM extension API, whereas in + the Hardware-Dependent Device direct-FM extension API, whereas in OSS compatible mode, FM registers can be accessed with the OSS direct-FM compatible API in <filename>/dev/dmfmX</filename> device. </para> diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt index 69dd29ed824e..b2bea15137d2 100644 --- a/Documentation/IPMI.txt +++ b/Documentation/IPMI.txt @@ -533,6 +533,33 @@ completion during sending a panic event. Other Pieces ------------ +Get the detailed info related with the IPMI device +-------------------------------------------------- + +Some users need more detailed information about a device, like where +the address came from or the raw base device for the IPMI interface. +You can use the IPMI smi_watcher to catch the IPMI interfaces as they +come or go, and to grab the information, you can use the function +ipmi_get_smi_info(), which returns the following structure: + +struct ipmi_smi_info { + enum ipmi_addr_src addr_src; + struct device *dev; + union { + struct { + void *acpi_handle; + } acpi_info; + } addr_info; +}; + +Currently special info for only for SI_ACPI address sources is +returned. Others may be added as necessary. + +Note that the dev pointer is included in the above structure, and +assuming ipmi_smi_get_info returns success, you must call put_device +on the dev pointer. + + Watchdog -------- diff --git a/Documentation/Makefile b/Documentation/Makefile index 6fc7ea1d1f9d..9b4bc5c76f33 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,3 +1,3 @@ obj-m := DocBook/ accounting/ auxdisplay/ connector/ \ filesystems/ filesystems/configfs/ ia64/ laptops/ networking/ \ - pcmcia/ spi/ timers/ video4linux/ vm/ watchdog/src/ + pcmcia/ spi/ timers/ vm/ watchdog/src/ diff --git a/Documentation/PCI/MSI-HOWTO.txt b/Documentation/PCI/MSI-HOWTO.txt index dcf7acc720e1..3f5e0b09bed5 100644 --- a/Documentation/PCI/MSI-HOWTO.txt +++ b/Documentation/PCI/MSI-HOWTO.txt @@ -253,8 +253,8 @@ In constrast, MSI is restricted to a maximum of 32 interrupts (and must be a power of two). In addition, the MSI interrupt vectors must be allocated consecutively, so the system may not be able to allocate as many vectors for MSI as it could for MSI-X. On some platforms, MSI -interrupts must all be targetted at the same set of CPUs whereas MSI-X -interrupts can all be targetted at different CPUs. +interrupts must all be targeted at the same set of CPUs whereas MSI-X +interrupts can all be targeted at different CPUs. 4.5.2 Spinlocks diff --git a/Documentation/RCU/00-INDEX b/Documentation/RCU/00-INDEX index 71b6f500ddb9..1d7a885761f5 100644 --- a/Documentation/RCU/00-INDEX +++ b/Documentation/RCU/00-INDEX @@ -21,7 +21,7 @@ rcu.txt RTFP.txt - List of RCU papers (bibliography) going back to 1980. stallwarn.txt - - RCU CPU stall warnings (CONFIG_RCU_CPU_STALL_DETECTOR) + - RCU CPU stall warnings (module parameter rcu_cpu_stall_suppress) torture.txt - RCU Torture Test Operation (CONFIG_RCU_TORTURE_TEST) trace.txt diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt index 790d1a812376..0c134f8afc6f 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 44c6dcc93d6d..4e959208f736 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -1,22 +1,25 @@ Using RCU's CPU Stall Detector -The CONFIG_RCU_CPU_STALL_DETECTOR kernel config parameter enables -RCU's CPU stall detector, which detects conditions that unduly delay -RCU grace periods. The stall detector's idea of what constitutes -"unduly delayed" is controlled by a set of C preprocessor macros: +The rcu_cpu_stall_suppress module parameter enables RCU's CPU stall +detector, which detects conditions that unduly delay RCU grace periods. +This module parameter enables CPU stall detection by default, but +may be overridden via boot-time parameter or at runtime via sysfs. +The stall detector's idea of what constitutes "unduly delayed" is +controlled by a set of kernel configuration variables and cpp macros: -RCU_SECONDS_TILL_STALL_CHECK +CONFIG_RCU_CPU_STALL_TIMEOUT - This macro defines the period of time that RCU will wait from - the beginning of a grace period until it issues an RCU CPU - stall warning. This time period is normally ten seconds. + This kernel configuration parameter defines the period of time + that RCU will wait from the beginning of a grace period until it + issues an RCU CPU stall warning. This time period is normally + ten seconds. RCU_SECONDS_TILL_STALL_RECHECK This macro defines the period of time that RCU will wait after issuing a stall warning until it issues another stall warning - for the same stall. This time period is normally set to thirty - seconds. + for the same stall. This time period is normally set to three + times the check interval plus thirty seconds. RCU_STALL_RAT_DELAY @@ -80,6 +83,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 efd8cc95c06b..5a704ffd0bbc 100644 --- a/Documentation/RCU/trace.txt +++ b/Documentation/RCU/trace.txt @@ -1,39 +1,43 @@ CONFIG_RCU_TRACE debugfs Files and Formats -The rcutree implementation of RCU provides debugfs trace output that -summarizes counters and state. This information is useful for debugging -RCU itself, and can sometimes also help to debug abuses of RCU. -The following sections describe the debugfs files and formats. +The rcutree and rcutiny implementations of RCU provide debugfs trace +output that summarizes counters and state. This information is useful for +debugging RCU itself, and can sometimes also help to debug abuses of RCU. +The following sections describe the debugfs files and formats, first +for rcutree and next for rcutiny. -Hierarchical RCU debugfs Files and Formats +CONFIG_TREE_RCU and CONFIG_TREE_PREEMPT_RCU debugfs Files and Formats -This implementation of RCU provides three debugfs files under the +These implementations of RCU provides five debugfs files under the top-level directory RCU: rcu/rcudata (which displays fields in struct -rcu_data), rcu/rcugp (which displays grace-period counters), and -rcu/rcuhier (which displays the struct rcu_node hierarchy). +rcu_data), rcu/rcudata.csv (which is a .csv spreadsheet version of +rcu/rcudata), rcu/rcugp (which displays grace-period counters), +rcu/rcuhier (which displays the struct rcu_node hierarchy), and +rcu/rcu_pending (which displays counts of the reasons that the +rcu_pending() function decided that there was core RCU work to do). The output of "cat rcu/rcudata" looks as follows: rcu_sched: - 0 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=10951/1 dn=0 df=1101 of=0 ri=36 ql=0 b=10 - 1 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=16117/1 dn=0 df=1015 of=0 ri=0 ql=0 b=10 - 2 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=1445/1 dn=0 df=1839 of=0 ri=0 ql=0 b=10 - 3 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=6681/1 dn=0 df=1545 of=0 ri=0 ql=0 b=10 - 4 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=1003/1 dn=0 df=1992 of=0 ri=0 ql=0 b=10 - 5 c=17829 g=17830 pq=1 pqc=17829 qp=1 dt=3887/1 dn=0 df=3331 of=0 ri=4 ql=2 b=10 - 6 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=859/1 dn=0 df=3224 of=0 ri=0 ql=0 b=10 - 7 c=17829 g=17830 pq=0 pqc=17829 qp=1 dt=3761/1 dn=0 df=1818 of=0 ri=0 ql=2 b=10 + 0 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=10951/1/0 df=1101 of=0 ri=36 ql=0 b=10 + 1 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=16117/1/0 df=1015 of=0 ri=0 ql=0 b=10 + 2 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=1445/1/0 df=1839 of=0 ri=0 ql=0 b=10 + 3 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=6681/1/0 df=1545 of=0 ri=0 ql=0 b=10 + 4 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=1003/1/0 df=1992 of=0 ri=0 ql=0 b=10 + 5 c=17829 g=17830 pq=1 pqc=17829 qp=1 dt=3887/1/0 df=3331 of=0 ri=4 ql=2 b=10 + 6 c=17829 g=17829 pq=1 pqc=17829 qp=0 dt=859/1/0 df=3224 of=0 ri=0 ql=0 b=10 + 7 c=17829 g=17830 pq=0 pqc=17829 qp=1 dt=3761/1/0 df=1818 of=0 ri=0 ql=2 b=10 rcu_bh: - 0 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=10951/1 dn=0 df=0 of=0 ri=0 ql=0 b=10 - 1 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=16117/1 dn=0 df=13 of=0 ri=0 ql=0 b=10 - 2 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=1445/1 dn=0 df=15 of=0 ri=0 ql=0 b=10 - 3 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=6681/1 dn=0 df=9 of=0 ri=0 ql=0 b=10 - 4 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=1003/1 dn=0 df=15 of=0 ri=0 ql=0 b=10 - 5 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=3887/1 dn=0 df=15 of=0 ri=0 ql=0 b=10 - 6 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=859/1 dn=0 df=15 of=0 ri=0 ql=0 b=10 - 7 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=3761/1 dn=0 df=15 of=0 ri=0 ql=0 b=10 + 0 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=10951/1/0 df=0 of=0 ri=0 ql=0 b=10 + 1 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=16117/1/0 df=13 of=0 ri=0 ql=0 b=10 + 2 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=1445/1/0 df=15 of=0 ri=0 ql=0 b=10 + 3 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=6681/1/0 df=9 of=0 ri=0 ql=0 b=10 + 4 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=1003/1/0 df=15 of=0 ri=0 ql=0 b=10 + 5 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=3887/1/0 df=15 of=0 ri=0 ql=0 b=10 + 6 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=859/1/0 df=15 of=0 ri=0 ql=0 b=10 + 7 c=-275 g=-275 pq=1 pqc=-275 qp=0 dt=3761/1/0 df=15 of=0 ri=0 ql=0 b=10 The first section lists the rcu_data structures for rcu_sched, the second for rcu_bh. Note that CONFIG_TREE_PREEMPT_RCU kernels will have an @@ -81,18 +85,10 @@ o "qp" indicates that RCU still expects a quiescent state from o "dt" is the current value of the dyntick counter that is incremented when entering or leaving dynticks idle state, either by the - scheduler or by irq. The number after the "/" is the interrupt - nesting depth when in dyntick-idle state, or one greater than - the interrupt-nesting depth otherwise. - - This field is displayed only for CONFIG_NO_HZ kernels. - -o "dn" is the current value of the dyntick counter that is incremented - when entering or leaving dynticks idle state via NMI. If both - the "dt" and "dn" values are even, then this CPU is in dynticks - idle mode and may be ignored by RCU. If either of these two - counters is odd, then RCU must be alert to the possibility of - an RCU read-side critical section running on this CPU. + scheduler or by irq. The number after the first "/" is the + interrupt nesting depth when in dyntick-idle state, or one + greater than the interrupt-nesting depth otherwise. The number + after the second "/" is the NMI nesting depth. This field is displayed only for CONFIG_NO_HZ kernels. @@ -125,6 +121,18 @@ 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. These orphaned callbacks have been moved + to an arbitrarily chosen online CPU. + +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. @@ -157,15 +165,15 @@ o "gpnum" is the number of grace periods that have started. It is The output of "cat rcu/rcuhier" looks as follows, with very long lines: -c=6902 g=6903 s=2 jfq=3 j=72c7 nfqs=13142/nfqsng=0(13142) fqlh=6 oqlen=0 -1/1 .>. 0:127 ^0 -3/3 .>. 0:35 ^0 0/0 .>. 36:71 ^1 0/0 .>. 72:107 ^2 0/0 .>. 108:127 ^3 -3/3f .>. 0:5 ^0 2/3 .>. 6:11 ^1 0/0 .>. 12:17 ^2 0/0 .>. 18:23 ^3 0/0 .>. 24:29 ^4 0/0 .>. 30:35 ^5 0/0 .>. 36:41 ^0 0/0 .>. 42:47 ^1 0/0 .>. 48:53 ^2 0/0 .>. 54:59 ^3 0/0 .>. 60:65 ^4 0/0 .>. 66:71 ^5 0/0 .>. 72:77 ^0 0/0 .>. 78:83 ^1 0/0 .>. 84:89 ^2 0/0 .>. 90:95 ^3 0/0 .>. 96:101 ^4 0/0 .>. 102:107 ^5 0/0 .>. 108:113 ^0 0/0 .>. 114:119 ^1 0/0 .>. 120:125 ^2 0/0 .>. 126:127 ^3 +c=6902 g=6903 s=2 jfq=3 j=72c7 nfqs=13142/nfqsng=0(13142) fqlh=6 +1/1 ..>. 0:127 ^0 +3/3 ..>. 0:35 ^0 0/0 ..>. 36:71 ^1 0/0 ..>. 72:107 ^2 0/0 ..>. 108:127 ^3 +3/3f ..>. 0:5 ^0 2/3 ..>. 6:11 ^1 0/0 ..>. 12:17 ^2 0/0 ..>. 18:23 ^3 0/0 ..>. 24:29 ^4 0/0 ..>. 30:35 ^5 0/0 ..>. 36:41 ^0 0/0 ..>. 42:47 ^1 0/0 ..>. 48:53 ^2 0/0 ..>. 54:59 ^3 0/0 ..>. 60:65 ^4 0/0 ..>. 66:71 ^5 0/0 ..>. 72:77 ^0 0/0 ..>. 78:83 ^1 0/0 ..>. 84:89 ^2 0/0 ..>. 90:95 ^3 0/0 ..>. 96:101 ^4 0/0 ..>. 102:107 ^5 0/0 ..>. 108:113 ^0 0/0 ..>. 114:119 ^1 0/0 ..>. 120:125 ^2 0/0 ..>. 126:127 ^3 rcu_bh: -c=-226 g=-226 s=1 jfq=-5701 j=72c7 nfqs=88/nfqsng=0(88) fqlh=0 oqlen=0 -0/1 .>. 0:127 ^0 -0/3 .>. 0:35 ^0 0/0 .>. 36:71 ^1 0/0 .>. 72:107 ^2 0/0 .>. 108:127 ^3 -0/3f .>. 0:5 ^0 0/3 .>. 6:11 ^1 0/0 .>. 12:17 ^2 0/0 .>. 18:23 ^3 0/0 .>. 24:29 ^4 0/0 .>. 30:35 ^5 0/0 .>. 36:41 ^0 0/0 .>. 42:47 ^1 0/0 .>. 48:53 ^2 0/0 .>. 54:59 ^3 0/0 .>. 60:65 ^4 0/0 .>. 66:71 ^5 0/0 .>. 72:77 ^0 0/0 .>. 78:83 ^1 0/0 .>. 84:89 ^2 0/0 .>. 90:95 ^3 0/0 .>. 96:101 ^4 0/0 .>. 102:107 ^5 0/0 .>. 108:113 ^0 0/0 .>. 114:119 ^1 0/0 .>. 120:125 ^2 0/0 .>. 126:127 ^3 +c=-226 g=-226 s=1 jfq=-5701 j=72c7 nfqs=88/nfqsng=0(88) fqlh=0 +0/1 ..>. 0:127 ^0 +0/3 ..>. 0:35 ^0 0/0 ..>. 36:71 ^1 0/0 ..>. 72:107 ^2 0/0 ..>. 108:127 ^3 +0/3f ..>. 0:5 ^0 0/3 ..>. 6:11 ^1 0/0 ..>. 12:17 ^2 0/0 ..>. 18:23 ^3 0/0 ..>. 24:29 ^4 0/0 ..>. 30:35 ^5 0/0 ..>. 36:41 ^0 0/0 ..>. 42:47 ^1 0/0 ..>. 48:53 ^2 0/0 ..>. 54:59 ^3 0/0 ..>. 60:65 ^4 0/0 ..>. 66:71 ^5 0/0 ..>. 72:77 ^0 0/0 ..>. 78:83 ^1 0/0 ..>. 84:89 ^2 0/0 ..>. 90:95 ^3 0/0 ..>. 96:101 ^4 0/0 ..>. 102:107 ^5 0/0 ..>. 108:113 ^0 0/0 ..>. 114:119 ^1 0/0 ..>. 120:125 ^2 0/0 ..>. 126:127 ^3 This is once again split into "rcu_sched" and "rcu_bh" portions, and CONFIG_TREE_PREEMPT_RCU kernels will again have an additional @@ -180,7 +188,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(). @@ -201,11 +209,6 @@ o "fqlh" is the number of calls to force_quiescent_state() that exited immediately (without even being counted in nfqs above) due to contention on ->fqslock. -o "oqlen" is the number of callbacks on the "orphan" callback - list. RCU callbacks are placed on this list by CPUs going - offline, and are "adopted" either by the CPU helping the outgoing - CPU or by the next rcu_barrier*() call, whichever comes first. - o Each element of the form "1/1 0:127 ^0" represents one struct rcu_node. Each line represents one level of the hierarchy, from root to leaves. It is best to think of the rcu_data structures @@ -229,13 +232,20 @@ o Each element of the form "1/1 0:127 ^0" represents one struct current grace period. o The characters separated by the ">" indicate the state - of the blocked-tasks lists. A "T" preceding the ">" + of the blocked-tasks lists. A "G" preceding the ">" indicates that at least one task blocked in an RCU read-side critical section blocks the current grace - period, while a "." preceding the ">" indicates otherwise. - The character following the ">" indicates similarly for - the next grace period. A "T" should appear in this - field only for rcu-preempt. + period, while a "E" preceding the ">" indicates that + at least one task blocked in an RCU read-side critical + section blocks the current expedited grace period. + A "T" character following the ">" indicates that at + least one task is blocked within an RCU read-side + critical section, regardless of whether any current + grace period (expedited or normal) is inconvenienced. + A "." character appears if the corresponding condition + does not hold, so that "..>." indicates that no tasks + are blocked. In contrast, "GE>T" indicates maximal + inconvenience from blocked tasks. o The numbers separated by the ":" are the range of CPUs served by this struct rcu_node. This can be helpful @@ -315,3 +325,115 @@ o "nn" is the number of times that this CPU needed nothing. Alert readers will note that the rcu "nn" number for a given CPU very closely matches the rcu_bh "np" number for that same CPU. This is due to short-circuit evaluation in rcu_pending(). + + +CONFIG_TINY_RCU and CONFIG_TINY_PREEMPT_RCU debugfs Files and Formats + +These implementations of RCU provides a single debugfs file under the +top-level directory RCU, namely rcu/rcudata, which displays fields in +rcu_bh_ctrlblk, rcu_sched_ctrlblk and, for CONFIG_TINY_PREEMPT_RCU, +rcu_preempt_ctrlblk. + +The output of "cat rcu/rcudata" is as follows: + +rcu_preempt: qlen=24 gp=1097669 g197/p197/c197 tasks=... + ttb=. btg=no ntb=184 neb=0 nnb=183 j=01f7 bt=0274 + normal balk: nt=1097669 gt=0 bt=371 b=0 ny=25073378 nos=0 + exp balk: bt=0 nos=0 +rcu_sched: qlen: 0 +rcu_bh: qlen: 0 + +This is split into rcu_preempt, rcu_sched, and rcu_bh sections, with the +rcu_preempt section appearing only in CONFIG_TINY_PREEMPT_RCU builds. +The last three lines of the rcu_preempt section appear only in +CONFIG_RCU_BOOST kernel builds. The fields are as follows: + +o "qlen" is the number of RCU callbacks currently waiting either + for an RCU grace period or waiting to be invoked. This is the + only field present for rcu_sched and rcu_bh, due to the + short-circuiting of grace period in those two cases. + +o "gp" is the number of grace periods that have completed. + +o "g197/p197/c197" displays the grace-period state, with the + "g" number being the number of grace periods that have started + (mod 256), the "p" number being the number of grace periods + that the CPU has responded to (also mod 256), and the "c" + number being the number of grace periods that have completed + (once again mode 256). + + Why have both "gp" and "g"? Because the data flowing into + "gp" is only present in a CONFIG_RCU_TRACE kernel. + +o "tasks" is a set of bits. The first bit is "T" if there are + currently tasks that have recently blocked within an RCU + read-side critical section, the second bit is "N" if any of the + aforementioned tasks are blocking the current RCU grace period, + and the third bit is "E" if any of the aforementioned tasks are + blocking the current expedited grace period. Each bit is "." + if the corresponding condition does not hold. + +o "ttb" is a single bit. It is "B" if any of the blocked tasks + need to be priority boosted and "." otherwise. + +o "btg" indicates whether boosting has been carried out during + the current grace period, with "exp" indicating that boosting + is in progress for an expedited grace period, "no" indicating + that boosting has not yet started for a normal grace period, + "begun" indicating that boosting has bebug for a normal grace + period, and "done" indicating that boosting has completed for + a normal grace period. + +o "ntb" is the total number of tasks subjected to RCU priority boosting + periods since boot. + +o "neb" is the number of expedited grace periods that have had + to resort to RCU priority boosting since boot. + +o "nnb" is the number of normal grace periods that have had + to resort to RCU priority boosting since boot. + +o "j" is the low-order 12 bits of the jiffies counter in hexadecimal. + +o "bt" is the low-order 12 bits of the value that the jiffies counter + will have at the next time that boosting is scheduled to begin. + +o In the line beginning with "normal balk", the fields are as follows: + + o "nt" is the number of times that the system balked from + boosting because there were no blocked tasks to boost. + Note that the system will balk from boosting even if the + grace period is overdue when the currently running task + is looping within an RCU read-side critical section. + There is no point in boosting in this case, because + boosting a running task won't make it run any faster. + + o "gt" is the number of times that the system balked + from boosting because, although there were blocked tasks, + none of them were preventing the current grace period + from completing. + + o "bt" is the number of times that the system balked + from boosting because boosting was already in progress. + + o "b" is the number of times that the system balked from + boosting because boosting had already completed for + the grace period in question. + + o "ny" is the number of times that the system balked from + boosting because it was not yet time to start boosting + the grace period in question. + + o "nos" is the number of times that the system balked from + boosting for inexplicable ("not otherwise specified") + reasons. This can actually happen due to races involving + increments of the jiffies counter. + +o In the line beginning with "exp balk", the fields are as follows: + + o "bt" is the number of times that the system balked from + boosting because there were no blocked tasks to boost. + + o "nos" is the number of times that the system balked from + boosting for inexplicable ("not otherwise specified") + reasons. diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index cfaac34c4557..6ef692667e2f 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt @@ -849,6 +849,37 @@ All: lockdep-checked RCU-protected pointer access See the comment headers in the source code (or the docbook generated from them) for more information. +However, given that there are no fewer than four families of RCU APIs +in the Linux kernel, how do you choose which one to use? The following +list can be helpful: + +a. Will readers need to block? If so, you need SRCU. + +b. What about the -rt patchset? If readers would need to block + in an non-rt kernel, you need SRCU. If readers would block + in a -rt kernel, but not in a non-rt kernel, SRCU is not + necessary. + +c. Do you need to treat NMI handlers, hardirq handlers, + and code segments with preemption disabled (whether + via preempt_disable(), local_irq_save(), local_bh_disable(), + or some other mechanism) as if they were explicit RCU readers? + If so, you need RCU-sched. + +d. Do you need RCU grace periods to complete even in the face + of softirq monopolization of one or more of the CPUs? For + example, is your code subject to network-based denial-of-service + attacks? If so, you need RCU-bh. + +e. Is your workload too update-intensive for normal use of + RCU, but inappropriate for other synchronization mechanisms? + If so, consider SLAB_DESTROY_BY_RCU. But please be careful! + +f. Otherwise, use RCU. + +Of course, this all assumes that you have determined that RCU is in fact +the right tool for your job. + 8. ANSWERS TO QUICK QUIZZES diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs index 26c3b3635d9f..a660d494c8ed 100644 --- a/Documentation/SecurityBugs +++ b/Documentation/SecurityBugs @@ -28,7 +28,7 @@ expect these delays to be short, measurable in days, not weeks or months. A disclosure date is negotiated by the security team working with the bug submitter as well as vendors. However, the kernel security team holds the final say when setting a disclosure date. The timeframe for -disclosure is from immediate (esp. if it's already publically known) +disclosure is from immediate (esp. if it's already publicly known) to a few weeks. As a basic default policy, we expect report date to disclosure date to be on the order of 7 days. diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index 38d2aab59cac..319baa8b60dd 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -101,7 +101,7 @@ PM support: Since Linux is used on many portable and desktop systems, your complete overview of the power management issues related to drivers see Documentation/power/devices.txt . -Control: In general if there is active maintainance of a driver by +Control: In general if there is active maintenance of a driver by the author then patches will be redirected to them unless they are totally obvious and without need of checking. If you want to be the contact and update point for the diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 689e2371095c..e439cd0d3375 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -729,7 +729,7 @@ Linus Torvalds's mail on the canonical patch format: <http://lkml.org/lkml/2005/4/7/183> Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversal changes in. + Some strategies to get difficult or controversial changes in. http://halobates.de/on-submitting-patches.pdf -- diff --git a/Documentation/accounting/getdelays.c b/Documentation/accounting/getdelays.c index 6e25c2659e0a..e9c77788a39d 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)); @@ -482,6 +516,7 @@ int main(int argc, char *argv[]) default: fprintf(stderr, "Unknown nla_type %d\n", na->nla_type); + case TASKSTATS_TYPE_NULL: break; } na = (struct nlattr *) (GENLMSG_DATA(&msg) + len); diff --git a/Documentation/acpi/apei/output_format.txt b/Documentation/acpi/apei/output_format.txt new file mode 100644 index 000000000000..0c49c197c47a --- /dev/null +++ b/Documentation/acpi/apei/output_format.txt @@ -0,0 +1,147 @@ + APEI output format + ~~~~~~~~~~~~~~~~~~ + +APEI uses printk as hardware error reporting interface, the output +format is as follow. + +<error record> := +APEI generic hardware error status +severity: <integer>, <severity string> +section: <integer>, severity: <integer>, <severity string> +flags: <integer> +<section flags strings> +fru_id: <uuid string> +fru_text: <string> +section_type: <section type string> +<section data> + +<severity string>* := recoverable | fatal | corrected | info + +<section flags strings># := +[primary][, containment warning][, reset][, threshold exceeded]\ +[, resource not accessible][, latent error] + +<section type string> := generic processor error | memory error | \ +PCIe error | unknown, <uuid string> + +<section data> := +<generic processor section data> | <memory section data> | \ +<pcie section data> | <null> + +<generic processor section data> := +[processor_type: <integer>, <proc type string>] +[processor_isa: <integer>, <proc isa string>] +[error_type: <integer> +<proc error type strings>] +[operation: <integer>, <proc operation string>] +[flags: <integer> +<proc flags strings>] +[level: <integer>] +[version_info: <integer>] +[processor_id: <integer>] +[target_address: <integer>] +[requestor_id: <integer>] +[responder_id: <integer>] +[IP: <integer>] + +<proc type string>* := IA32/X64 | IA64 + +<proc isa string>* := IA32 | IA64 | X64 + +<processor error type strings># := +[cache error][, TLB error][, bus error][, micro-architectural error] + +<proc operation string>* := unknown or generic | data read | data write | \ +instruction execution + +<proc flags strings># := +[restartable][, precise IP][, overflow][, corrected] + +<memory section data> := +[error_status: <integer>] +[physical_address: <integer>] +[physical_address_mask: <integer>] +[node: <integer>] +[card: <integer>] +[module: <integer>] +[bank: <integer>] +[device: <integer>] +[row: <integer>] +[column: <integer>] +[bit_position: <integer>] +[requestor_id: <integer>] +[responder_id: <integer>] +[target_id: <integer>] +[error_type: <integer>, <mem error type string>] + +<mem error type string>* := +unknown | no error | single-bit ECC | multi-bit ECC | \ +single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \ +target abort | parity error | watchdog timeout | invalid address | \ +mirror Broken | memory sparing | scrub corrected error | \ +scrub uncorrected error + +<pcie section data> := +[port_type: <integer>, <pcie port type string>] +[version: <integer>.<integer>] +[command: <integer>, status: <integer>] +[device_id: <integer>:<integer>:<integer>.<integer> +slot: <integer> +secondary_bus: <integer> +vendor_id: <integer>, device_id: <integer> +class_code: <integer>] +[serial number: <integer>, <integer>] +[bridge: secondary_status: <integer>, control: <integer>] +[aer_status: <integer>, aer_mask: <integer> +<aer status string> +[aer_uncor_severity: <integer>] +aer_layer=<aer layer string>, aer_agent=<aer agent string> +aer_tlp_header: <integer> <integer> <integer> <integer>] + +<pcie port type string>* := PCIe end point | legacy PCI end point | \ +unknown | unknown | root port | upstream switch port | \ +downstream switch port | PCIe to PCI/PCI-X bridge | \ +PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \ +root complex event collector + +if section severity is fatal or recoverable +<aer status string># := +unknown | unknown | unknown | unknown | Data Link Protocol | \ +unknown | unknown | unknown | unknown | unknown | unknown | unknown | \ +Poisoned TLP | Flow Control Protocol | Completion Timeout | \ +Completer Abort | Unexpected Completion | Receiver Overflow | \ +Malformed TLP | ECRC | Unsupported Request +else +<aer status string># := +Receiver Error | unknown | unknown | unknown | unknown | unknown | \ +Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \ +Replay Timer Timeout | Advisory Non-Fatal +fi + +<aer layer string> := +Physical Layer | Data Link Layer | Transaction Layer + +<aer agent string> := +Receiver ID | Requester ID | Completer ID | Transmitter ID + +Where, [] designate corresponding content is optional + +All <field string> description with * has the following format: + +field: <integer>, <field string> + +Where value of <integer> should be the position of "string" in <field +string> description. Otherwise, <field string> will be "unknown". + +All <field strings> description with # has the following format: + +field: <integer> +<field strings> + +Where each string in <fields strings> corresponding to one set bit of +<integer>. The bit position is the position of "string" in <field +strings> description. + +For more detailed explanation of every field, please refer to UEFI +specification version 2.3 or later, section Appendix N: Common +Platform Error Record. diff --git a/Documentation/arm/00-INDEX b/Documentation/arm/00-INDEX index 7f5fc3ba9c91..91c24a1e8a9e 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 @@ -32,3 +34,5 @@ memory.txt - description of the virtual memory layout nwfpe/ - NWFPE floating point emulator documentation +swp_emulation + - SWP/SWPB emulation handler/logging description diff --git a/Documentation/arm/IXP4xx b/Documentation/arm/IXP4xx index 133c5fa6c7a1..7b9351f2f555 100644 --- a/Documentation/arm/IXP4xx +++ b/Documentation/arm/IXP4xx @@ -36,7 +36,7 @@ Linux currently supports the following features on the IXP4xx chips: - Timers (watchdog, OS) The following components of the chips are not supported by Linux and -require the use of Intel's propietary CSR softare: +require the use of Intel's proprietary CSR softare: - USB device interface - Network interfaces (HSS, Utopia, NPEs, etc) @@ -47,7 +47,7 @@ software from: http://developer.intel.com/design/network/products/npfamily/ixp425.htm -DO NOT POST QUESTIONS TO THE LINUX MAILING LISTS REGARDING THE PROPIETARY +DO NOT POST QUESTIONS TO THE LINUX MAILING LISTS REGARDING THE PROPRIETARY SOFTWARE. There are several websites that provide directions/pointers on using diff --git a/Documentation/arm/OMAP/DSS b/Documentation/arm/OMAP/DSS index 0af0e9eed5d6..888ae7b83ae4 100644 --- a/Documentation/arm/OMAP/DSS +++ b/Documentation/arm/OMAP/DSS @@ -255,9 +255,10 @@ framebuffer parameters. Kernel boot arguments --------------------- -vram=<size> - - Amount of total VRAM to preallocate. For example, "10M". omapfb - allocates memory for framebuffers from VRAM. +vram=<size>[,<physaddr>] + - Amount of total VRAM to preallocate and optionally a physical start + memory address. For example, "10M". omapfb allocates memory for + framebuffers from VRAM. omapfb.mode=<display>:<mode>[,...] - Default video mode for specified displays. For example, diff --git a/Documentation/arm/OMAP/omap_pm b/Documentation/arm/OMAP/omap_pm index 5389440aade3..9012bb039094 100644 --- a/Documentation/arm/OMAP/omap_pm +++ b/Documentation/arm/OMAP/omap_pm @@ -127,3 +127,28 @@ implementation needs: 10. (*pdata->cpu_set_freq)(unsigned long f) 11. (*pdata->cpu_get_freq)(void) + +Customizing OPP for platform +============================ +Defining CONFIG_PM should enable OPP layer for the silicon +and the registration of OPP table should take place automatically. +However, in special cases, the default OPP table may need to be +tweaked, for e.g.: + * enable default OPPs which are disabled by default, but which + could be enabled on a platform + * Disable an unsupported OPP on the platform + * Define and add a custom opp table entry +in these cases, the board file needs to do additional steps as follows: +arch/arm/mach-omapx/board-xyz.c + #include "pm.h" + .... + static void __init omap_xyz_init_irq(void) + { + .... + /* Initialize the default table */ + omapx_opp_init(); + /* Do customization to the defaults */ + .... + } +NOTE: omapx_opp_init will be omap3_opp_init or as required +based on the omap family. diff --git a/Documentation/arm/SA1100/FreeBird b/Documentation/arm/SA1100/FreeBird index fb23b770aaf4..ab9193663b2b 100644 --- a/Documentation/arm/SA1100/FreeBird +++ b/Documentation/arm/SA1100/FreeBird @@ -1,6 +1,6 @@ -Freebird-1.1 is produced by Legned(C) ,Inc. +Freebird-1.1 is produced by Legend(C), Inc. http://web.archive.org/web/*/http://www.legend.com.cn -and software/linux mainatined by Coventive(C),Inc. +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/SH-Mobile/Makefile b/Documentation/arm/SH-Mobile/Makefile new file mode 100644 index 000000000000..8771d832cf8c --- /dev/null +++ b/Documentation/arm/SH-Mobile/Makefile @@ -0,0 +1,8 @@ +BIN := vrl4 + +.PHONY: all +all: $(BIN) + +.PHONY: clean +clean: + rm -f *.o $(BIN) diff --git a/Documentation/arm/SH-Mobile/vrl4.c b/Documentation/arm/SH-Mobile/vrl4.c new file mode 100644 index 000000000000..e8a191358ad2 --- /dev/null +++ b/Documentation/arm/SH-Mobile/vrl4.c @@ -0,0 +1,169 @@ +/* + * vrl4 format generator + * + * Copyright (C) 2010 Simon Horman + * + * This file is subject to the terms and conditions of the GNU General Public + * License. See the file "COPYING" in the main directory of this archive + * for more details. + */ + +/* + * usage: vrl4 < zImage > out + * dd if=out of=/dev/sdx bs=512 seek=1 # Write the image to sector 1 + * + * Reads a zImage from stdin and writes a vrl4 image to stdout. + * In practice this means writing a padded vrl4 header to stdout followed + * by the zImage. + * + * The padding places the zImage at ALIGN bytes into the output. + * The vrl4 uses ALIGN + START_BASE as the start_address. + * This is where the mask ROM will jump to after verifying the header. + * + * The header sets copy_size to min(sizeof(zImage), MAX_BOOT_PROG_LEN) + ALIGN. + * That is, the mask ROM will load the padded header (ALIGN bytes) + * And then MAX_BOOT_PROG_LEN bytes of the image, or the entire image, + * whichever is smaller. + * + * The zImage is not modified in any way. + */ + +#define _BSD_SOURCE +#include <endian.h> +#include <unistd.h> +#include <stdint.h> +#include <stdio.h> +#include <errno.h> + +struct hdr { + uint32_t magic1; + uint32_t reserved1; + uint32_t magic2; + uint32_t reserved2; + uint16_t copy_size; + uint16_t boot_options; + uint32_t reserved3; + uint32_t start_address; + uint32_t reserved4; + uint32_t reserved5; + char reserved6[308]; +}; + +#define DECLARE_HDR(h) \ + struct hdr (h) = { \ + .magic1 = htole32(0xea000000), \ + .reserved1 = htole32(0x56), \ + .magic2 = htole32(0xe59ff008), \ + .reserved3 = htole16(0x1) } + +/* Align to 512 bytes, the MMCIF sector size */ +#define ALIGN_BITS 9 +#define ALIGN (1 << ALIGN_BITS) + +#define START_BASE 0xe55b0000 + +/* + * With an alignment of 512 the header uses the first sector. + * There is a 128 sector (64kbyte) limit on the data loaded by the mask ROM. + * So there are 127 sectors left for the boot programme. But in practice + * Only a small portion of a zImage is needed, 16 sectors should be more + * than enough. + * + * Note that this sets how much of the zImage is copied by the mask ROM. + * The entire zImage is present after the header and is loaded + * by the code in the boot program (which is the first portion of the zImage). + */ +#define MAX_BOOT_PROG_LEN (16 * 512) + +#define ROUND_UP(x) ((x + ALIGN - 1) & ~(ALIGN - 1)) + +ssize_t do_read(int fd, void *buf, size_t count) +{ + size_t offset = 0; + ssize_t l; + + while (offset < count) { + l = read(fd, buf + offset, count - offset); + if (!l) + break; + if (l < 0) { + if (errno == EAGAIN || errno == EWOULDBLOCK) + continue; + perror("read"); + return -1; + } + offset += l; + } + + return offset; +} + +ssize_t do_write(int fd, const void *buf, size_t count) +{ + size_t offset = 0; + ssize_t l; + + while (offset < count) { + l = write(fd, buf + offset, count - offset); + if (l < 0) { + if (errno == EAGAIN || errno == EWOULDBLOCK) + continue; + perror("write"); + return -1; + } + offset += l; + } + + return offset; +} + +ssize_t write_zero(int fd, size_t len) +{ + size_t i = len; + + while (i--) { + const char x = 0; + if (do_write(fd, &x, 1) < 0) + return -1; + } + + return len; +} + +int main(void) +{ + DECLARE_HDR(hdr); + char boot_program[MAX_BOOT_PROG_LEN]; + size_t aligned_hdr_len, alligned_prog_len; + ssize_t prog_len; + + prog_len = do_read(0, boot_program, sizeof(boot_program)); + if (prog_len <= 0) + return -1; + + aligned_hdr_len = ROUND_UP(sizeof(hdr)); + hdr.start_address = htole32(START_BASE + aligned_hdr_len); + alligned_prog_len = ROUND_UP(prog_len); + hdr.copy_size = htole16(aligned_hdr_len + alligned_prog_len); + + if (do_write(1, &hdr, sizeof(hdr)) < 0) + return -1; + if (write_zero(1, aligned_hdr_len - sizeof(hdr)) < 0) + return -1; + + if (do_write(1, boot_program, prog_len) < 0) + return 1; + + /* Write out the rest of the kernel */ + while (1) { + prog_len = do_read(0, boot_program, sizeof(boot_program)); + if (prog_len < 0) + return 1; + if (prog_len == 0) + break; + if (do_write(1, boot_program, prog_len) < 0) + return 1; + } + + return 0; +} diff --git a/Documentation/arm/SH-Mobile/zboot-rom-mmcif.txt b/Documentation/arm/SH-Mobile/zboot-rom-mmcif.txt new file mode 100644 index 000000000000..efff8ae2713d --- /dev/null +++ b/Documentation/arm/SH-Mobile/zboot-rom-mmcif.txt @@ -0,0 +1,29 @@ +ROM-able zImage boot from MMC +----------------------------- + +An ROM-able zImage compiled with ZBOOT_ROM_MMCIF may be written to MMC and +SuperH Mobile ARM will to boot directly from the MMCIF hardware block. + +This is achieved by the mask ROM loading the first portion of the image into +MERAM and then jumping to it. This portion contains loader code which +copies the entire image to SDRAM and jumps to it. From there the zImage +boot code proceeds as normal, uncompressing the image into its final +location and then jumping to it. + +This code has been tested on an AP4EB board using the developer 1A eMMC +boot mode which is configured using the following jumper settings. +The board used for testing required a patched mask ROM in order for +this mode to function. + + 8 7 6 5 4 3 2 1 + x|x|x|x|x| |x| +S4 -+-+-+-+-+-+-+- + | | | | |x| |x on + +The zImage must be written to the MMC card at sector 1 (512 bytes) in +vrl4 format. A utility vrl4 is supplied to accomplish this. + +e.g. + vrl4 < zImage | dd of=/dev/sdX bs=512 seek=1 + +A dual-voltage MMC 4.0 card was used for testing. diff --git a/Documentation/arm/Samsung-S3C24XX/Suspend.txt b/Documentation/arm/Samsung-S3C24XX/Suspend.txt index 7edd0e2e6c5b..1ca63b3e5635 100644 --- a/Documentation/arm/Samsung-S3C24XX/Suspend.txt +++ b/Documentation/arm/Samsung-S3C24XX/Suspend.txt @@ -116,7 +116,7 @@ Configuration Allows the entire memory to be checksummed before and after the suspend to see if there has been any corruption of the contents. - Note, the time to calculate the CRC is dependant on the CPU speed + Note, the time to calculate the CRC is dependent on the CPU speed and the size of memory. For an 64Mbyte RAM area on an 200MHz S3C2410, this can take approximately 4 seconds to complete. diff --git a/Documentation/arm/Samsung/GPIO.txt b/Documentation/arm/Samsung/GPIO.txt index 05850c62abeb..513f2562c1a3 100644 --- a/Documentation/arm/Samsung/GPIO.txt +++ b/Documentation/arm/Samsung/GPIO.txt @@ -5,7 +5,7 @@ Introduction ------------ This outlines the Samsung GPIO implementation and the architecture -specfic calls provided alongisde the drivers/gpio core. +specific calls provided alongisde the drivers/gpio core. S3C24XX (Legacy) diff --git a/Documentation/arm/Sharp-LH/ADC-LH7-Touchscreen b/Documentation/arm/Sharp-LH/ADC-LH7-Touchscreen deleted file mode 100644 index dc460f055647..000000000000 --- a/Documentation/arm/Sharp-LH/ADC-LH7-Touchscreen +++ /dev/null @@ -1,61 +0,0 @@ -README on the ADC/Touchscreen Controller -======================================== - -The LH79524 and LH7A404 include a built-in Analog to Digital -controller (ADC) that is used to process input from a touchscreen. -The driver only implements a four-wire touch panel protocol. - -The touchscreen driver is maintenance free except for the pen-down or -touch threshold. Some resistive displays and board combinations may -require tuning of this threshold. The driver exposes some of its -internal state in the sys filesystem. If the kernel is configured -with it, CONFIG_SYSFS, and sysfs is mounted at /sys, there will be a -directory - - /sys/devices/platform/adc-lh7.0 - -containing these files. - - -r--r--r-- 1 root root 4096 Jan 1 00:00 samples - -rw-r--r-- 1 root root 4096 Jan 1 00:00 threshold - -r--r--r-- 1 root root 4096 Jan 1 00:00 threshold_range - -The threshold is the current touch threshold. It defaults to 750 on -most targets. - - # cat threshold - 750 - -The threshold_range contains the range of valid values for the -threshold. Values outside of this range will be silently ignored. - - # cat threshold_range - 0 1023 - -To change the threshold, write a value to the threshold file. - - # echo 500 > threshold - # cat threshold - 500 - -The samples file contains the most recently sampled values from the -ADC. There are 12. Below are typical of the last sampled values when -the pen has been released. The first two and last two samples are for -detecting whether or not the pen is down. The third through sixth are -X coordinate samples. The seventh through tenth are Y coordinate -samples. - - # cat samples - 1023 1023 0 0 0 0 530 529 530 529 1023 1023 - -To determine a reasonable threshold, press on the touch panel with an -appropriate stylus and read the values from samples. - - # cat samples - 1023 676 92 103 101 102 855 919 922 922 1023 679 - -The first and eleventh samples are discarded. Thus, the important -values are the second and twelfth which are used to determine if the -pen is down. When both are below the threshold, the driver registers -that the pen is down. When either is above the threshold, it -registers then pen is up. diff --git a/Documentation/arm/Sharp-LH/CompactFlash b/Documentation/arm/Sharp-LH/CompactFlash deleted file mode 100644 index 8616d877df9e..000000000000 --- a/Documentation/arm/Sharp-LH/CompactFlash +++ /dev/null @@ -1,32 +0,0 @@ -README on the Compact Flash for Card Engines -============================================ - -There are three challenges in supporting the CF interface of the Card -Engines. First, every IO operation must be followed with IO to -another memory region. Second, the slot is wired for one-to-one -address mapping *and* it is wired for 16 bit access only. Second, the -interrupt request line from the CF device isn't wired. - -The IOBARRIER issue is covered in README.IOBARRIER. This isn't an -onerous problem. Enough said here. - -The addressing issue is solved in the -arch/arm/mach-lh7a40x/ide-lpd7a40x.c file with some awkward -work-arounds. We implement a special SELECT_DRIVE routine that is -called before the IDE driver performs its own SELECT_DRIVE. Our code -recognizes that the SELECT register cannot be modified without also -writing a command. It send an IDLE_IMMEDIATE command on selecting a -drive. The function also prevents drive select to the slave drive -since there can be only one. The awkward part is that the IDE driver, -even though we have a select procedure, also attempts to change the -drive by writing directly the SELECT register. This attempt is -explicitly blocked by the OUTB function--not pretty, but effective. - -The lack of interrupts is a more serious problem. Even though the CF -card is fast when compared to a normal IDE device, we don't know that -the CF is really flash. A user could use one of the very small hard -drives being shipped with a CF interface. The IDE code includes a -check for interfaces that lack an IRQ. In these cases, submitting a -command to the IDE controller is followed by a call to poll for -completion. If the device isn't immediately ready, it schedules a -timer to poll again later. diff --git a/Documentation/arm/Sharp-LH/IOBarrier b/Documentation/arm/Sharp-LH/IOBarrier deleted file mode 100644 index 2e953e228f4d..000000000000 --- a/Documentation/arm/Sharp-LH/IOBarrier +++ /dev/null @@ -1,45 +0,0 @@ -README on the IOBARRIER for CardEngine IO -========================================= - -Due to an unfortunate oversight when the Card Engines were designed, -the signals that control access to some peripherals, most notably the -SMC91C9111 ethernet controller, are not properly handled. - -The symptom is that some back to back IO with the peripheral returns -unreliable data. With the SMC chip, you'll see errors about the bank -register being 'screwed'. - -The cause is that the AEN signal to the SMC chip does not transition -for every memory access. It is driven through the CPLD from the CS7 -line of the CPU's static memory controller which is optimized to -eliminate unnecessary transitions. Yet, the SMC requires a transition -for every write access. The Sharp website has more information about -the effect this power-conserving feature has on peripheral -interfacing. - -The solution is to follow every write access to the SMC chip with an -access to another memory region that will force the CPU to release the -chip select line. It is important to guarantee that this access -forces the CPU off-chip. We map a page of SDRAM as if it were an -uncacheable IO device and read from it after every SMC IO write -operation. - - SMC IO - BARRIER IO - -Only this sequence is important. It does not matter that there is no -BARRIER IO before the access to the SMC chip because the AEN latch -only needs occurs after the SMC IO write cycle. The routines that -implement this work-around make an additional concession which is to -disable interrupts during the IO sequence. Other hardware devices -(the LogicPD CPLD) have registers in the same physical memory -region as the SMC chip. An interrupt might allow an access to one of -those registers while SMC IO is being performed. - -You might be tempted to think that we have to access another device -attached to the static memory controller, but the empirical evidence -indicates that this is not so. Mapping 0x00000000 (flash) and -0xc0000000 (SDRAM) appear to have the same effect. Using SDRAM seems -to be faster. Choosing to access an undecoded memory region is not -desirable as there is no way to know how that chip select will be used -in the future. diff --git a/Documentation/arm/Sharp-LH/KEV7A400 b/Documentation/arm/Sharp-LH/KEV7A400 deleted file mode 100644 index be32b14cd535..000000000000 --- a/Documentation/arm/Sharp-LH/KEV7A400 +++ /dev/null @@ -1,8 +0,0 @@ -README on Implementing Linux for Sharp's KEV7a400 -================================================= - -This product has been discontinued by Sharp. For the time being, the -partially implemented code remains in the kernel. At some point in -the future, either the code will be finished or it will be removed -completely. This depends primarily on how many of the development -boards are in the field. diff --git a/Documentation/arm/Sharp-LH/LCDPanels b/Documentation/arm/Sharp-LH/LCDPanels deleted file mode 100644 index fb1b21c2f2f4..000000000000 --- a/Documentation/arm/Sharp-LH/LCDPanels +++ /dev/null @@ -1,59 +0,0 @@ -README on the LCD Panels -======================== - -Configuration options for several LCD panels, available from Logic PD, -are included in the kernel source. This README will help you -understand the configuration data and give you some guidance for -adding support for other panels if you wish. - - -lcd-panels.h ------------- - -There is no way, at present, to detect which panel is attached to the -system at runtime. Thus the kernel configuration is static. The file -arch/arm/mach-ld7a40x/lcd-panels.h (or similar) defines all of the -panel specific parameters. - -It should be possible for this data to be shared among several device -families. The current layout may be insufficiently general, but it is -amenable to improvement. - - -PIXEL_CLOCK ------------ - -The panel data sheets will give a range of acceptable pixel clocks. -The fundamental LCDCLK input frequency is divided down by a PCD -constant in field '.tim2'. It may happen that it is impossible to set -the pixel clock within this range. A clock which is too slow will -tend to flicker. For the highest quality image, set the clock as high -as possible. - - -MARGINS -------- - -These values may be difficult to glean from the panel data sheet. In -the case of the Sharp panels, the upper margin is explicitly called -out as a specific number of lines from the top of the frame. The -other values may not matter as much as the panels tend to -automatically center the image. - - -Sync Sense ----------- - -The sense of the hsync and vsync pulses may be called out in the data -sheet. On one panel, the sense of these pulses determine the height -of the visible region on the panel. Most of the Sharp panels use -negative sense sync pulses set by the TIM2_IHS and TIM2_IVS bits in -'.tim2'. - - -Pel Layout ----------- - -The Sharp color TFT panels are all configured for 16 bit direct color -modes. The amba-lcd driver sets the pel mode to 565 for 5 bits of -each red and blue and 6 bits of green. diff --git a/Documentation/arm/Sharp-LH/LPD7A400 b/Documentation/arm/Sharp-LH/LPD7A400 deleted file mode 100644 index 3275b453bfdf..000000000000 --- a/Documentation/arm/Sharp-LH/LPD7A400 +++ /dev/null @@ -1,15 +0,0 @@ -README on Implementing Linux for the Logic PD LPD7A400-10 -========================================================= - -- CPLD memory mapping - - The board designers chose to use high address lines for controlling - access to the CPLD registers. It turns out to be a big waste - because we're using an MMU and must map IO space into virtual - memory. The result is that we have to make a mapping for every - register. - -- Serial Console - - It may be OK not to use the serial console option if the user passes - the console device name to the kernel. This deserves some exploration. diff --git a/Documentation/arm/Sharp-LH/LPD7A40X b/Documentation/arm/Sharp-LH/LPD7A40X deleted file mode 100644 index 8c29a27e208f..000000000000 --- a/Documentation/arm/Sharp-LH/LPD7A40X +++ /dev/null @@ -1,16 +0,0 @@ -README on Implementing Linux for the Logic PD LPD7A40X-10 -========================================================= - -- CPLD memory mapping - - The board designers chose to use high address lines for controlling - access to the CPLD registers. It turns out to be a big waste - because we're using an MMU and must map IO space into virtual - memory. The result is that we have to make a mapping for every - register. - -- Serial Console - - It may be OK not to use the serial console option if the user passes - the console device name to the kernel. This deserves some exploration. - diff --git a/Documentation/arm/Sharp-LH/SDRAM b/Documentation/arm/Sharp-LH/SDRAM deleted file mode 100644 index 93ddc23c2faa..000000000000 --- a/Documentation/arm/Sharp-LH/SDRAM +++ /dev/null @@ -1,51 +0,0 @@ -README on the SDRAM Controller for the LH7a40X -============================================== - -The standard configuration for the SDRAM controller generates a sparse -memory array. The precise layout is determined by the SDRAM chips. A -default kernel configuration assembles the discontiguous memory -regions into separate memory nodes via the NUMA (Non-Uniform Memory -Architecture) facilities. In this default configuration, the kernel -is forgiving about the precise layout. As long as it is given an -accurate picture of available memory by the bootloader the kernel will -execute correctly. - -The SDRC supports a mode where some of the chip select lines are -swapped in order to make SDRAM look like a synchronous ROM. Setting -this bit means that the RAM will present as a contiguous array. Some -programmers prefer this to the discontiguous layout. Be aware that -may be a penalty for this feature where some some configurations of -memory are significantly reduced; i.e. 64MiB of RAM appears as only 32 -MiB. - -There are a couple of configuration options to override the default -behavior. When the SROMLL bit is set and memory appears as a -contiguous array, there is no reason to support NUMA. -CONFIG_LH7A40X_CONTIGMEM disables NUMA support. When physical memory -is discontiguous, the memory tables are organized such that there are -two banks per nodes with a small gap between them. This layout wastes -some kernel memory for page tables representing non-existent memory. -CONFIG_LH7A40X_ONE_BANK_PER_NODE optimizes the node tables such that -there are no gaps. These options control the low level organization -of the memory management tables in ways that may prevent the kernel -from booting or may cause the kernel to allocated excessively large -page tables. Be warned. Only change these options if you know what -you are doing. The default behavior is a reasonable compromise that -will suit all users. - --- - -A typical 32MiB system with the default configuration options will -find physical memory managed as follows. - - node 0: 0xc0000000 4MiB - 0xc1000000 4MiB - node 1: 0xc4000000 4MiB - 0xc5000000 4MiB - node 2: 0xc8000000 4MiB - 0xc9000000 4MiB - node 3: 0xcc000000 4MiB - 0xcd000000 4MiB - -Setting CONFIG_LH7A40X_ONE_BANK_PER_NODE will put each bank into a -separate node. diff --git a/Documentation/arm/Sharp-LH/VectoredInterruptController b/Documentation/arm/Sharp-LH/VectoredInterruptController deleted file mode 100644 index 23047e9861ee..000000000000 --- a/Documentation/arm/Sharp-LH/VectoredInterruptController +++ /dev/null @@ -1,80 +0,0 @@ -README on the Vectored Interrupt Controller of the LH7A404 -========================================================== - -The 404 revision of the LH7A40X series comes with two vectored -interrupts controllers. While the kernel does use some of the -features of these devices, it is far from the purpose for which they -were designed. - -When this README was written, the implementation of the VICs was in -flux. It is possible that some details, especially with priorities, -will change. - -The VIC support code is inspired by routines written by Sharp. - - -Priority Control ----------------- - -The significant reason for using the VIC's vectoring is to control -interrupt priorities. There are two tables in -arch/arm/mach-lh7a40x/irq-lh7a404.c that look something like this. - - static unsigned char irq_pri_vic1[] = { IRQ_GPIO3INTR, }; - static unsigned char irq_pri_vic2[] = { - IRQ_T3UI, IRQ_GPIO7INTR, - IRQ_UART1INTR, IRQ_UART2INTR, IRQ_UART3INTR, }; - -The initialization code reads these tables and inserts a vector -address and enable for each indicated IRQ. Vectored interrupts have -higher priority than non-vectored interrupts. So, on VIC1, -IRQ_GPIO3INTR will be served before any other non-FIQ interrupt. Due -to the way that the vectoring works, IRQ_T3UI is the next highest -priority followed by the other vectored interrupts on VIC2. After -that, the non-vectored interrupts are scanned in VIC1 then in VIC2. - - -ISR ---- - -The interrupt service routine macro get_irqnr() in -arch/arm/kernel/entry-armv.S scans the VICs for the next active -interrupt. The vectoring makes this code somewhat larger than it was -before using vectoring (refer to the LH7A400 implementation). In the -case where an interrupt is vectored, the implementation will tend to -be faster than the non-vectored version. However, the worst-case path -is longer. - -It is worth noting that at present, there is no need to read -VIC2_VECTADDR because the register appears to be shared between the -controllers. The code is written such that if this changes, it ought -to still work properly. - - -Vector Addresses ----------------- - -The proper use of the vectoring hardware would jump to the ISR -specified by the vectoring address. Linux isn't structured to take -advantage of this feature, though it might be possible to change -things to support it. - -In this implementation, the vectoring address is used to speed the -search for the active IRQ. The address is coded such that the lowest -6 bits store the IRQ number for vectored interrupts. These numbers -correspond to the bits in the interrupt status registers. IRQ zero is -the lowest interrupt bit in VIC1. IRQ 32 is the lowest interrupt bit -in VIC2. Because zero is a valid IRQ number and because we cannot -detect whether or not there is a valid vectoring address if that -address is zero, the eigth bit (0x100) is set for vectored interrupts. -The address for IRQ 0x18 (VIC2) is 0x118. Only the ninth bit is set -for the default handler on VIC1 and only the tenth bit is set for the -default handler on VIC2. - -In other words. - - 0x000 - no active interrupt - 0x1ii - vectored interrupt 0xii - 0x2xx - unvectored interrupt on VIC1 (xx is don't care) - 0x4xx - unvectored interrupt on VIC2 (xx is don't care) - diff --git a/Documentation/arm/msm/gpiomux.txt b/Documentation/arm/msm/gpiomux.txt new file mode 100644 index 000000000000..67a81620adf6 --- /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/swp_emulation b/Documentation/arm/swp_emulation new file mode 100644 index 000000000000..af903d22fd93 --- /dev/null +++ b/Documentation/arm/swp_emulation @@ -0,0 +1,27 @@ +Software emulation of deprecated SWP instruction (CONFIG_SWP_EMULATE) +--------------------------------------------------------------------- + +ARMv6 architecture deprecates use of the SWP/SWPB instructions, and recommeds +moving to the load-locked/store-conditional instructions LDREX and STREX. + +ARMv7 multiprocessing extensions introduce the ability to disable these +instructions, triggering an undefined instruction exception when executed. +Trapped instructions are emulated using an LDREX/STREX or LDREXB/STREXB +sequence. If a memory access fault (an abort) occurs, a segmentation fault is +signalled to the triggering process. + +/proc/cpu/swp_emulation holds some statistics/information, including the PID of +the last process to trigger the emulation to be invocated. For example: +--- +Emulated SWP: 12 +Emulated SWPB: 0 +Aborted SWP{B}: 1 +Last process: 314 +--- + +NOTE: when accessing uncached shared regions, LDREX/STREX rely on an external +transaction monitoring block called a global monitor to maintain update +atomicity. If your system does not implement a global monitor, this option can +cause programs that perform SWP operations to uncached memory to deadlock, as +the STREX operation will always fail. + diff --git a/Documentation/block/00-INDEX b/Documentation/block/00-INDEX index a406286f6f3e..d111e3b23db0 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 2c2f24f634e4..000000000000 --- 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 b9a83dd24732..c6d84cfd2f56 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -497,7 +497,7 @@ The scatter gather list is in the form of an array of <page, offset, len> entries with their corresponding dma address mappings filled in at the appropriate time. As an optimization, contiguous physical pages can be covered by a single entry where <page> refers to the first page and <len> -covers the range of pages (upto 16 contiguous pages could be covered this +covers the range of pages (up to 16 contiguous pages could be covered this way). There is a helper routine (blk_rq_map_sg) which drivers can use to build the sg list. @@ -565,7 +565,7 @@ struct request { . int tag; /* command tag associated with request */ void *special; /* same as before */ - char *buffer; /* valid only for low memory buffers upto + char *buffer; /* valid only for low memory buffers up to current_nr_sectors */ . . @@ -963,11 +963,6 @@ elevator_dispatch_fn* fills the dispatch queue with ready requests. elevator_add_req_fn* called to add a new request into the scheduler -elevator_queue_empty_fn returns true if the merge queue is empty. - Drivers shouldn't use this, but rather check - if elv_next_request is NULL (without losing the - request if one exists!) - elevator_former_req_fn elevator_latter_req_fn These return the request before or after the one specified in disk sort order. Used by the diff --git a/Documentation/block/switching-sched.txt b/Documentation/block/switching-sched.txt index d5af3f630814..71cfbdc0f74d 100644 --- a/Documentation/block/switching-sched.txt +++ b/Documentation/block/switching-sched.txt @@ -16,7 +16,7 @@ you can do so by typing: As of the Linux 2.6.10 kernel, it is now possible to change the IO scheduler for a given block device on the fly (thus making it possible, for instance, to set the CFQ scheduler for the system default, but -set a specific device to use the anticipatory or noop schedulers - which +set a specific device to use the deadline or noop schedulers - which can improve that device's throughput). To set a specific scheduler, simply do this: @@ -31,7 +31,7 @@ a "cat /sys/block/DEV/queue/scheduler" - the list of valid names will be displayed, with the currently selected scheduler in brackets: # cat /sys/block/hda/queue/scheduler -noop anticipatory deadline [cfq] -# echo anticipatory > /sys/block/hda/queue/scheduler +noop deadline [cfq] +# echo deadline > /sys/block/hda/queue/scheduler # cat /sys/block/hda/queue/scheduler -noop [anticipatory] deadline cfq +noop [deadline] cfq diff --git a/Documentation/block/writeback_cache_control.txt b/Documentation/block/writeback_cache_control.txt new file mode 100644 index 000000000000..83407d36630a --- /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/cgroups/blkio-controller.txt b/Documentation/cgroups/blkio-controller.txt index 6919d62591d9..465351d4cf85 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,62 @@ 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. + +Hierarchical Cgroups +==================== +- Currently none of the IO control policy supports hierarhical groups. But + cgroup interface does allow creation of hierarhical cgroups and internally + IO policies treat them as flat hierarchy. + + So this patch will allow creation of cgroup hierarhcy but at the backend + everything will be treated as flat. So if somebody created a hierarchy like + as follows. + + root + / \ + test1 test2 + | + test3 + + CFQ and throttling will practically treat all groups at same level. + + pivot + / | \ \ + root test1 test2 test3 + + Down the line we can implement hierarchical accounting/control support + and also introduce a new cgroup file "use_hierarchy" which will control + whether cgroup hierarchy is viewed as flat or hierarchical by the policy.. + This is how memory controller also has implemented the things. + Various user visible config options =================================== CONFIG_BLK_CGROUP @@ -68,13 +129,18 @@ 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. (See blkio.weight_device). - Currently allowed range of weights is from 100 to 1000. + Currently allowed range of weights is from 10 to 1000. - blkio.weight_device - One can specify per cgroup per device rules using this interface. @@ -210,40 +276,73 @@ 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. 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 -means that if group_isolation=0, expect fairness for sequential workload -only. Set group_isolation=1 to see fairness for random IO workload also. - -Generally CFQ will put random seeky workload in sync-noidle category. CFQ -will disable idling on these queues and it does a collective idling on group -of such queues. Generally these are slow moving queues and if there is a -sync-noidle service tree in each group, that group gets exclusive access to -disk for certain period. That means it will bring the throughput down if -group does not have enough IO to drive deeper queue depths and utilize disk -capacity to the fullest in the slice allocated to it. But the flip side is -that even a random reader should get better latencies and overall throughput -if there are lots of sequential readers/sync-idle workload running in the -system. - -If group_isolation=0, then CFQ automatically moves all the random seeky queues -in the root group. That means there will be no service differentiation for -that kind of workload. This leads to better throughput as we do collective -idling on root sync-noidle tree. - -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. diff --git a/Documentation/cgroups/cgroup_event_listener.c b/Documentation/cgroups/cgroup_event_listener.c index 8c2bfc4a6358..3e082f96dc12 100644 --- a/Documentation/cgroups/cgroup_event_listener.c +++ b/Documentation/cgroups/cgroup_event_listener.c @@ -91,7 +91,7 @@ int main(int argc, char **argv) if (ret == -1) { perror("cgroup.event_control " - "is not accessable any more"); + "is not accessible any more"); break; } diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroups/cgroups.txt index b34823ff1646..aedf1bd02fdd 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 @@ -109,22 +110,22 @@ university server with various users - students, professors, system tasks etc. The resource planning for this server could be along the following lines: - CPU : Top cpuset + CPU : "Top cpuset" / \ CPUSet1 CPUSet2 - | | - (Profs) (Students) + | | + (Professors) (Students) In addition (system tasks) are attached to topcpuset (so that they can run anywhere) with a limit of 20% - Memory : Professors (50%), students (30%), system (20%) + Memory : Professors (50%), Students (30%), system (20%) - Disk : Prof (50%), students (30%), system (20%) + Disk : Professors (50%), Students (30%), system (20%) Network : WWW browsing (20%), Network File System (60%), others (20%) / \ - Prof (15%) students (5%) + Professors (15%) students (5%) Browsers like Firefox/Lynx go into the WWW network class, while (k)nfsd go into NFS network class. @@ -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 @@ -339,19 +349,23 @@ To mount a cgroup hierarchy with all available subsystems, type: The "xxx" is not interpreted by the cgroup code, but will appear in /proc/mounts so may be any useful identifying string that you like. +Note: Some subsystems do not work without some user input first. For instance, +if cpusets are enabled the user will have to populate the cpus and mems files +for each new cgroup created before that group can be used. + To mount a cgroup hierarchy with just the cpuset and memory subsystems, type: # mount -t cgroup -o cpuset,memory hier1 /dev/cgroup To change the set of subsystems bound to a mounted hierarchy, just remount with different options: -# mount -o remount,cpuset,ns hier1 /dev/cgroup +# mount -o remount,cpuset,blkio hier1 /dev/cgroup -Now memory is removed from the hierarchy and ns is added. +Now memory is removed from the hierarchy and blkio is added. -Note this will add ns to the hierarchy but won't remove memory or +Note this will add blkio to the hierarchy but won't remove memory or cpuset, because the new options are appended to the old ones: -# mount -o remount,ns /dev/cgroup +# mount -o remount,blkio /dev/cgroup To Specify a hierarchy's release_agent: # mount -t cgroup -o cpuset,release_agent="/sbin/cpuset_release_agent" \ @@ -416,6 +430,14 @@ You can attach the current shell task by echoing 0: # echo 0 > tasks +Note: Since every task is always a member of exactly one cgroup in each +mounted hierarchy, to remove a task from its current cgroup you must +move it into a new cgroup (possibly the root cgroup) by writing to the +new cgroup's tasks file. + +Note: If the ns cgroup is active, moving a process to another cgroup can +fail. + 2.3 Mounting hierarchies by name -------------------------------- diff --git a/Documentation/cgroups/cpusets.txt b/Documentation/cgroups/cpusets.txt index 5d0d5692a365..98a30829af7a 100644 --- a/Documentation/cgroups/cpusets.txt +++ b/Documentation/cgroups/cpusets.txt @@ -693,7 +693,7 @@ There are ways to query or modify cpusets: - via the C library libcgroup. (http://sourceforge.net/projects/libcg/) - via the python application cset. - (http://developer.novell.com/wiki/index.php/Cpuset) + (http://code.google.com/p/cpuset/) The sched_setaffinity calls can also be done at the shell prompt using SGI's runon or Robert Love's taskset. The mbind and set_mempolicy @@ -725,13 +725,14 @@ Now you want to do something with this cpuset. In this directory you can find several files: # ls -cpuset.cpu_exclusive cpuset.memory_spread_slab -cpuset.cpus cpuset.mems -cpuset.mem_exclusive cpuset.sched_load_balance -cpuset.mem_hardwall cpuset.sched_relax_domain_level -cpuset.memory_migrate notify_on_release -cpuset.memory_pressure tasks -cpuset.memory_spread_page +cgroup.clone_children cpuset.memory_pressure +cgroup.event_control cpuset.memory_spread_page +cgroup.procs cpuset.memory_spread_slab +cpuset.cpu_exclusive cpuset.mems +cpuset.cpus cpuset.sched_load_balance +cpuset.mem_exclusive cpuset.sched_relax_domain_level +cpuset.mem_hardwall notify_on_release +cpuset.memory_migrate tasks Reading them will give you information about the state of this cpuset: the CPUs and Memory Nodes it can use, the processes that are using diff --git a/Documentation/cgroups/memcg_test.txt b/Documentation/cgroups/memcg_test.txt index b7eececfb195..fc8fa97a09ac 100644 --- a/Documentation/cgroups/memcg_test.txt +++ b/Documentation/cgroups/memcg_test.txt @@ -398,7 +398,7 @@ Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y. written to move_charge_at_immigrate. 9.10 Memory thresholds - Memory controler implements memory thresholds using cgroups notification + Memory controller implements memory thresholds using cgroups notification API. You can use Documentation/cgroups/cgroup_event_listener.c to test it. diff --git a/Documentation/cgroups/memory.txt b/Documentation/cgroups/memory.txt index 7781857dc940..b6ed61c95856 100644 --- a/Documentation/cgroups/memory.txt +++ b/Documentation/cgroups/memory.txt @@ -485,8 +485,9 @@ The feature can be disabled by # echo 0 > memory.use_hierarchy -NOTE1: Enabling/disabling will fail if the cgroup already has other - cgroups created below it. +NOTE1: Enabling/disabling will fail if either the cgroup already has other + cgroups created below it, or if the parent cgroup has use_hierarchy + enabled. NOTE2: When panic_on_oom is set to "2", the whole system will panic in case of an OOM event in any cgroup. diff --git a/Documentation/coccinelle.txt b/Documentation/coccinelle.txt index cd2b02837066..96b690348ba1 100644 --- a/Documentation/coccinelle.txt +++ b/Documentation/coccinelle.txt @@ -24,6 +24,9 @@ of many distributions, e.g. : 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 @@ -33,6 +36,10 @@ as a regular user, and install it with sudo make install +The semantic patches in the kernel will work best with Coccinelle version +0.2.4 or later. Using earlier versions may incur some parse errors in the +semantic patch code, but any results that are obtained should still be +correct. Using Coccinelle on the Linux kernel ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -41,20 +48,22 @@ 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: report, patch, context, and org. The mode to +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 -'patch' proposes a fix, when possible. - '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. +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: @@ -68,9 +77,9 @@ To produce patches, run: The coccicheck target applies every semantic patch available in the -subdirectories of 'scripts/coccinelle' to the entire Linux kernel. +sub-directories of 'scripts/coccinelle' to the entire Linux kernel. -For each semantic patch, a changelog message is proposed. It gives a +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. @@ -93,12 +102,35 @@ 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 -subdirectories of 'scripts/coccinelle/'. +sub-directories of 'scripts/coccinelle/'. Detailed description of the 'report' mode @@ -111,7 +143,7 @@ Example: Running - make coccicheck MODE=report COCCI=scripts/coccinelle/err_cast.cocci + make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci will execute the following part of the SmPL script. @@ -149,7 +181,7 @@ identified. Example: Running - make coccicheck MODE=patch COCCI=scripts/coccinelle/err_cast.cocci + make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci will execute the following part of the SmPL script. @@ -193,7 +225,7 @@ NOTE: The diff-like output generated is NOT an applicable patch. The Example: Running - make coccicheck MODE=context COCCI=scripts/coccinelle/err_cast.cocci + make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci will execute the following part of the SmPL script. @@ -228,7 +260,7 @@ diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing Example: Running - make coccicheck MODE=org COCCI=scripts/coccinelle/err_cast.cocci + make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci will execute the following part of the SmPL script. diff --git a/Documentation/cpu-freq/governors.txt b/Documentation/cpu-freq/governors.txt index 737988fca64d..e74d0a2eb1cf 100644 --- a/Documentation/cpu-freq/governors.txt +++ b/Documentation/cpu-freq/governors.txt @@ -158,6 +158,17 @@ intensive calculation on your laptop that you do not care how long it takes to complete as you can 'nice' it and prevent it from taking part in the deciding process of whether to increase your CPU frequency. +sampling_down_factor: this parameter controls the rate at which the +kernel makes a decision on when to decrease the frequency while running +at top speed. When set to 1 (the default) decisions to reevaluate load +are made at the same interval regardless of current clock speed. But +when set to greater than 1 (e.g. 100) it acts as a multiplier for the +scheduling interval for reevaluating load when the CPU is at its top +speed due to high load. This improves performance by reducing the overhead +of load evaluation and helping the CPU stay at its top speed when truly +busy, rather than shifting back and forth in speed. This tunable has no +effect on behavior at lower speeds/lower CPU loads. + 2.5 Conservative ---------------- diff --git a/Documentation/cpu-hotplug.txt b/Documentation/cpu-hotplug.txt index 45d5a217484f..a20bfd415e41 100644 --- a/Documentation/cpu-hotplug.txt +++ b/Documentation/cpu-hotplug.txt @@ -196,7 +196,7 @@ the state as 0 when a cpu if offline and 1 when its online. #To display the current cpu state. #cat /sys/devices/system/cpu/cpuX/online -Q: Why cant i remove CPU0 on some systems? +Q: Why can't i remove CPU0 on some systems? A: Some architectures may have some special dependency on a certain CPU. For e.g in IA64 platforms we have ability to sent platform interrupts to the diff --git a/Documentation/cputopology.txt b/Documentation/cputopology.txt index f1c5c4bccd3e..902d3151f527 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/dell_rbu.txt b/Documentation/dell_rbu.txt index 15174985ad08..d262e22bddec 100644 --- a/Documentation/dell_rbu.txt +++ b/Documentation/dell_rbu.txt @@ -62,7 +62,7 @@ image file and then arrange all these packets back to back in to one single file. This file is then copied to /sys/class/firmware/dell_rbu/data. Once this file gets to the driver, the driver extracts packet_size data from -the file and spreads it accross the physical memory in contiguous packet_sized +the file and spreads it across the physical memory in contiguous packet_sized space. This method makes sure that all the packets get to the driver in a single operation. diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro index 8cc2cba2b10d..9b614480aa84 100644 --- a/Documentation/development-process/1.Intro +++ b/Documentation/development-process/1.Intro @@ -56,13 +56,13 @@ information on kernel development. 1.2: WHAT THIS DOCUMENT IS ABOUT -The Linux kernel, at over 6 million lines of code and well over 1000 active -contributors, is one of the largest and most active free software projects -in existence. Since its humble beginning in 1991, this kernel has evolved -into a best-of-breed operating system component which runs on pocket-sized -digital music players, desktop PCs, the largest supercomputers in -existence, and all types of systems in between. It is a robust, efficient, -and scalable solution for almost any situation. +The Linux kernel, at over 8 million lines of code and well over 1000 +contributors to each release, is one of the largest and most active free +software projects in existence. Since its humble beginning in 1991, this +kernel has evolved into a best-of-breed operating system component which +runs on pocket-sized digital music players, desktop PCs, the largest +supercomputers in existence, and all types of systems in between. It is a +robust, efficient, and scalable solution for almost any situation. With the growth of Linux has come an increase in the number of developers (and companies) wishing to participate in its development. Hardware @@ -115,7 +115,7 @@ This document was written by Jonathan Corbet, corbet@lwn.net. It has been improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and -Jochen Voß. +Jochen Voß. This work was supported by the Linux Foundation; thanks especially to Amanda McPherson, who saw the value of this effort and made it all happen. @@ -221,7 +221,7 @@ include: - Everything that was said above about code review applies doubly to closed-source code. Since this code is not available at all, it cannot have been reviewed by the community and will, beyond doubt, have serious - problems. + problems. Makers of embedded systems, in particular, may be tempted to disregard much of what has been said in this section in the belief that they are shipping diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process index 97726eba6102..4823577c6509 100644 --- a/Documentation/development-process/2.Process +++ b/Documentation/development-process/2.Process @@ -14,16 +14,15 @@ The kernel developers use a loosely time-based release process, with a new major kernel release happening every two or three months. The recent release history looks like this: - 2.6.26 July 13, 2008 - 2.6.25 April 16, 2008 - 2.6.24 January 24, 2008 - 2.6.23 October 9, 2007 - 2.6.22 July 8, 2007 - 2.6.21 April 25, 2007 - 2.6.20 February 4, 2007 + 2.6.38 March 14, 2011 + 2.6.37 January 4, 2011 + 2.6.36 October 20, 2010 + 2.6.35 August 1, 2010 + 2.6.34 May 15, 2010 + 2.6.33 February 24, 2010 Every 2.6.x release is a major kernel release with new features, internal -API changes, and more. A typical 2.6 release can contain over 10,000 +API changes, and more. A typical 2.6 release can contain nearly 10,000 changesets with changes to several hundred thousand lines of code. 2.6 is thus the leading edge of Linux kernel development; the kernel uses a rolling development model which is continually integrating major changes. @@ -42,13 +41,13 @@ merge window do not come out of thin air; they have been collected, tested, and staged ahead of time. How that process works will be described in detail later on). -The merge window lasts for two weeks. At the end of this time, Linus -Torvalds will declare that the window is closed and release the first of -the "rc" kernels. For the kernel which is destined to be 2.6.26, for -example, the release which happens at the end of the merge window will be -called 2.6.26-rc1. The -rc1 release is the signal that the time to merge -new features has passed, and that the time to stabilize the next kernel has -begun. +The merge window lasts for approximately two weeks. At the end of this +time, Linus Torvalds will declare that the window is closed and release the +first of the "rc" kernels. For the kernel which is destined to be 2.6.40, +for example, the release which happens at the end of the merge window will +be called 2.6.40-rc1. The -rc1 release is the signal that the time to +merge new features has passed, and that the time to stabilize the next +kernel has begun. Over the next six to ten weeks, only patches which fix problems should be submitted to the mainline. On occasion a more significant change will be @@ -66,20 +65,19 @@ will get up to somewhere between -rc6 and -rc9 before the kernel is considered to be sufficiently stable and the final 2.6.x release is made. At that point the whole process starts over again. -As an example, here is how the 2.6.25 development cycle went (all dates in -2008): - - January 24 2.6.24 stable release - February 10 2.6.25-rc1, merge window closes - February 15 2.6.25-rc2 - February 24 2.6.25-rc3 - March 4 2.6.25-rc4 - March 9 2.6.25-rc5 - March 16 2.6.25-rc6 - March 25 2.6.25-rc7 - April 1 2.6.25-rc8 - April 11 2.6.25-rc9 - April 16 2.6.25 stable release +As an example, here is how the 2.6.38 development cycle went (all dates in +2011): + + January 4 2.6.37 stable release + January 18 2.6.38-rc1, merge window closes + January 21 2.6.38-rc2 + February 1 2.6.38-rc3 + February 7 2.6.38-rc4 + February 15 2.6.38-rc5 + February 21 2.6.38-rc6 + March 1 2.6.38-rc7 + March 7 2.6.38-rc8 + March 14 2.6.38 stable release How do the developers decide when to close the development cycle and create the stable release? The most significant metric used is the list of @@ -87,7 +85,7 @@ regressions from previous releases. No bugs are welcome, but those which break systems which worked in the past are considered to be especially serious. For this reason, patches which cause regressions are looked upon unfavorably and are quite likely to be reverted during the stabilization -period. +period. The developers' goal is to fix all known regressions before the stable release is made. In the real world, this kind of perfection is hard to @@ -99,26 +97,34 @@ kernels go out with a handful of known regressions though, hopefully, none of them are serious. Once a stable release is made, its ongoing maintenance is passed off to the -"stable team," currently comprised of Greg Kroah-Hartman and Chris Wright. -The stable team will release occasional updates to the stable release using -the 2.6.x.y numbering scheme. To be considered for an update release, a -patch must (1) fix a significant bug, and (2) already be merged into the -mainline for the next development kernel. Continuing our 2.6.25 example, -the history (as of this writing) is: - - May 1 2.6.25.1 - May 6 2.6.25.2 - May 9 2.6.25.3 - May 15 2.6.25.4 - June 7 2.6.25.5 - June 9 2.6.25.6 - June 16 2.6.25.7 - June 21 2.6.25.8 - June 24 2.6.25.9 - -Stable updates for a given kernel are made for approximately six months; -after that, the maintenance of stable releases is solely the responsibility -of the distributors which have shipped that particular kernel. +"stable team," currently consisting of Greg Kroah-Hartman. The stable team +will release occasional updates to the stable release using the 2.6.x.y +numbering scheme. To be considered for an update release, a patch must (1) +fix a significant bug, and (2) already be merged into the mainline for the +next development kernel. Kernels will typically receive stable updates for +a little more than one development cycle past their initial release. So, +for example, the 2.6.36 kernel's history looked like: + + October 10 2.6.36 stable release + November 22 2.6.36.1 + December 9 2.6.36.2 + January 7 2.6.36.3 + February 17 2.6.36.4 + +2.6.36.4 was the final stable update for the 2.6.36 release. + +Some kernels are designated "long term" kernels; they will receive support +for a longer period. As of this writing, the current long term kernels +and their maintainers are: + + 2.6.27 Willy Tarreau (Deep-frozen stable kernel) + 2.6.32 Greg Kroah-Hartman + 2.6.35 Andi Kleen (Embedded flag kernel) + +The selection of a kernel for long-term support is purely a matter of a +maintainer having the need and the time to maintain that release. There +are no known plans for long-term support for any specific upcoming +release. 2.2: THE LIFECYCLE OF A PATCH @@ -130,7 +136,7 @@ each patch implements a change which is desirable to have in the mainline. This process can happen quickly for minor fixes, or, in the case of large and controversial changes, go on for years. Much developer frustration comes from a lack of understanding of this process or from attempts to -circumvent it. +circumvent it. In the hopes of reducing that frustration, this document will describe how a patch gets into the kernel. What follows below is an introduction which @@ -154,7 +160,7 @@ The stages that a patch goes through are, generally: inclusion, it should be accepted by a relevant subsystem maintainer - though this acceptance is not a guarantee that the patch will make it all the way to the mainline. The patch will show up in the maintainer's - subsystem tree and into the staging trees (described below). When the + subsystem tree and into the -next trees (described below). When the process works, this step leads to more extensive review of the patch and the discovery of any problems resulting from the integration of this patch with work being done by others. @@ -193,8 +199,8 @@ involved. 2.3: HOW PATCHES GET INTO THE KERNEL There is exactly one person who can merge patches into the mainline kernel -repository: Linus Torvalds. But, of the over 12,000 patches which went -into the 2.6.25 kernel, only 250 (around 2%) were directly chosen by Linus +repository: Linus Torvalds. But, of the over 9,500 patches which went +into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus himself. The kernel project has long since grown to a size where no single developer could possibly inspect and select every patch unassisted. The way the kernel developers have addressed this growth is through the use of @@ -229,14 +235,14 @@ first in trees dedicated to network device drivers, wireless networking, etc. This chain of repositories can be arbitrarily long, though it rarely exceeds two or three links. Since each maintainer in the chain trusts those managing lower-level trees, this process is known as the "chain of -trust." +trust." Clearly, in a system like this, getting patches into the kernel depends on finding the right maintainer. Sending patches directly to Linus is not normally the right way to go. -2.4: STAGING TREES +2.4: NEXT TREES The chain of subsystem trees guides the flow of patches into the kernel, but it also raises an interesting question: what if somebody wants to look @@ -250,11 +256,11 @@ changes land in the mainline kernel. One could pull changes from all of the interesting subsystem trees, but that would be a big and error-prone job. -The answer comes in the form of staging trees, where subsystem trees are +The answer comes in the form of -next trees, where subsystem trees are collected for testing and review. The older of these trees, maintained by Andrew Morton, is called "-mm" (for memory management, which is how it got started). The -mm tree integrates patches from a long list of subsystem -trees; it also has some patches aimed at helping with debugging. +trees; it also has some patches aimed at helping with debugging. Beyond that, -mm contains a significant collection of patches which have been selected by Andrew directly. These patches may have been posted on a @@ -264,8 +270,8 @@ subsystem tree of last resort; if there is no other obvious path for a patch into the mainline, it is likely to end up in -mm. Miscellaneous patches which accumulate in -mm will eventually either be forwarded on to an appropriate subsystem tree or be sent directly to Linus. In a typical -development cycle, approximately 10% of the patches going into the mainline -get there via -mm. +development cycle, approximately 5-10% of the patches going into the +mainline get there via -mm. The current -mm patch is available in the "mmotm" (-mm of the moment) directory at: @@ -275,7 +281,7 @@ directory at: Use of the MMOTM tree is likely to be a frustrating experience, though; there is a definite chance that it will not even compile. -The other staging tree, started more recently, is linux-next, maintained by +The primary tree for next-cycle patch merging is linux-next, maintained by Stephen Rothwell. The linux-next tree is, by design, a snapshot of what the mainline is expected to look like after the next merge window closes. Linux-next trees are announced on the linux-kernel and linux-next mailing @@ -287,27 +293,37 @@ Some information about linux-next has been gathered at: http://linux.f-seidel.de/linux-next/pmwiki/ -How the linux-next tree will fit into the development process is still -changing. As of this writing, the first full development cycle involving -linux-next (2.6.26) is coming to an end; thus far, it has proved to be a -valuable resource for finding and fixing integration problems before the -beginning of the merge window. See http://lwn.net/Articles/287155/ for -more information on how linux-next has worked to set up the 2.6.27 merge -window. - -Some developers have begun to suggest that linux-next should be used as the -target for future development as well. The linux-next tree does tend to be -far ahead of the mainline and is more representative of the tree into which -any new work will be merged. The downside to this idea is that the -volatility of linux-next tends to make it a difficult development target. -See http://lwn.net/Articles/289013/ for more information on this topic, and -stay tuned; much is still in flux where linux-next is involved. - -Besides the mmotm and linux-next trees, the kernel source tree now contains -the drivers/staging/ directory and many sub-directories for drivers or -filesystems that are on their way to being added to the kernel tree -proper, but they remain in drivers/staging/ while they still need more -work. +Linux-next has become an integral part of the kernel development process; +all patches merged during a given merge window should really have found +their way into linux-next some time before the merge window opens. + + +2.4.1: STAGING TREES + +The kernel source tree contains the drivers/staging/ directory, where +many sub-directories for drivers or filesystems that are on their way to +being added to the kernel tree live. They remain in drivers/staging while +they still need more work; once complete, they can be moved into the +kernel proper. This is a way to keep track of drivers that aren't +up to Linux kernel coding or quality standards, but people may want to use +them and track development. + +Greg Kroah-Hartman currently maintains the staging tree. Drivers that +still need work are sent to him, with each driver having its own +subdirectory in drivers/staging/. Along with the driver source files, a +TODO file should be present in the directory as well. The TODO file lists +the pending work that the driver needs for acceptance into the kernel +proper, as well as a list of people that should be Cc'd for any patches to +the driver. Current rules require that drivers contributed to staging +must, at a minimum, compile properly. + +Staging can be a relatively easy way to get new drivers into the mainline +where, with luck, they will come to the attention of other developers and +improve quickly. Entry into staging is not the end of the story, though; +code in staging which is not seeing regular progress will eventually be +removed. Distributors also tend to be relatively reluctant to enable +staging drivers. So staging is, at best, a stop on the way toward becoming +a proper mainline driver. 2.5: TOOLS @@ -334,11 +350,7 @@ page at: http://git-scm.com/ -That page has pointers to documentation and tutorials. One should be -aware, in particular, of the Kernel Hacker's Guide to git, which has -information specific to kernel development: - - http://linux.yyz.us/git-howto.html +That page has pointers to documentation and tutorials. Among the kernel developers who do not use git, the most popular choice is almost certainly Mercurial: @@ -395,7 +407,7 @@ There are a few hints which can help with linux-kernel survival: important to filter on both the topic of interest (though note that long-running conversations can drift away from the original subject without changing the email subject line) and the people who are - participating. + participating. - Do not feed the trolls. If somebody is trying to stir up an angry response, ignore them. diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage index 307a159a70ca..f87ba7b3fbac 100644 --- a/Documentation/development-process/3.Early-stage +++ b/Documentation/development-process/3.Early-stage @@ -110,8 +110,8 @@ the kernel community's standards. Some examples include: - The AppArmor security module made use of internal virtual filesystem data structures in ways which were considered to be unsafe and - unreliable. This code has since been significantly reworked, but - remains outside of the mainline. + unreliable. This concern (among others) kept AppArmor out of the + mainline for years. In each of these cases, a great deal of pain and extra work could have been avoided with some early discussion with the kernel developers. @@ -138,6 +138,19 @@ patches, and who, if anybody, is attaching Signed-off-by lines to those patches. Those are the people who will be best placed to help with a new development project. +The task of finding the right maintainer is sometimes challenging enough +that the kernel developers have added a script to ease the process: + + .../scripts/get_maintainer.pl + +This script will return the current maintainer(s) for a given file or +directory when given the "-f" option. If passed a patch on the +command line, it will list the maintainers who should probably receive +copies of the patch. There are a number of options regulating how hard +get_maintainer.pl will search for maintainers; please be careful about +using the more aggressive options as you may end up including developers +who have no real interest in the code you are modifying. + If all else fails, talking to Andrew Morton can be an effective way to track down a maintainer for a specific piece of code. @@ -155,11 +168,15 @@ reaction, but, instead, little or no reaction at all. The sad truth of the matter is (1) kernel developers tend to be busy, (2) there is no shortage of people with grand plans and little code (or even prospect of code) to back them up, and (3) nobody is obligated to review or comment on ideas -posted by others. If a request-for-comments posting yields little in the -way of comments, do not assume that it means there is no interest in the -project. Unfortunately, you also cannot assume that there are no problems -with your idea. The best thing to do in this situation is to proceed, -keeping the community informed as you go. +posted by others. Beyond that, high-level designs often hide problems +which are only reviewed when somebody actually tries to implement those +designs; for that reason, kernel developers would rather see the code. + +If a request-for-comments posting yields little in the way of comments, do +not assume that it means there is no interest in the project. +Unfortunately, you also cannot assume that there are no problems with your +idea. The best thing to do in this situation is to proceed, keeping the +community informed as you go. 3.5: GETTING OFFICIAL BUY-IN diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding index 2278693c8ffa..f3f1a469443c 100644 --- a/Documentation/development-process/4.Coding +++ b/Documentation/development-process/4.Coding @@ -131,6 +131,11 @@ classic time/space tradeoff taught in beginning data structures classes often does not apply to contemporary hardware. Space *is* time, in that a larger program will run slower than one which is more compact. +More recent compilers take an increasingly active role in deciding whether +a given function should actually be inlined or not. So the liberal +placement of "inline" keywords may not just be excessive; it could also be +irrelevant. + * Locking @@ -285,6 +290,13 @@ 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. +The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide +variety of potential coding problems; it can also propose fixes for those +problems. Quite a few "semantic patches" for the kernel have been packaged +under the scripts/coccinelle directory; running "make coccicheck" will run +through those semantic patches and report on any problems found. See +Documentation/coccinelle.txt for more information. + Other kinds of portability errors are best found by compiling your code for other architectures. If you do not happen to have an S/390 system or a Blackfin development board handy, you can still perform the compilation @@ -308,7 +320,9 @@ The first piece of documentation for any patch is its associated changelog. Log entries should describe the problem being solved, the form of the solution, the people who worked on the patch, any relevant effects on performance, and anything else that might be needed to -understand the patch. +understand the patch. Be sure that the changelog says *why* the patch is +worth applying; a surprising number of developers fail to provide that +information. Any code which adds a new user-space interface - including new sysfs or /proc files - should include documentation of that interface which enables @@ -321,7 +335,7 @@ boot-time parameters. Any patch which adds new parameters should add the appropriate entries to this file. Any new configuration options must be accompanied by help text which -clearly explains the options and when the user might want to select them. +clearly explains the options and when the user might want to select them. Internal API information for many subsystems is documented by way of specially-formatted comments; these comments can be extracted and formatted @@ -372,7 +386,8 @@ which is broken by the change. For a widely-used function, this duty can lead to literally hundreds or thousands of changes - many of which are likely to conflict with work being done by other developers. Needless to say, this can be a large job, so it is best to be sure that the -justification is solid. +justification is solid. Note that the Coccinelle tool can help with +wide-ranging API changes. When making an incompatible API change, one should, whenever possible, ensure that code which has not been updated is caught by the compiler. diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting index f622c1e9f0f9..903a2546f138 100644 --- a/Documentation/development-process/5.Posting +++ b/Documentation/development-process/5.Posting @@ -60,12 +60,15 @@ even in the short term. Patches must be prepared against a specific version of the kernel. As a general rule, a patch should be based on the current mainline as found in -Linus's git tree. It may become necessary to make versions against -mm, -linux-next, or a subsystem tree, though, to facilitate wider testing and -review. Depending on the area of your patch and what is going on -elsewhere, basing a patch against these other trees can require a -significant amount of work resolving conflicts and dealing with API -changes. +Linus's git tree. When basing on mainline, start with a well-known release +point - a stable or -rc release - rather than branching off the mainline at +an arbitrary spot. + +It may become necessary to make versions against -mm, linux-next, or a +subsystem tree, though, to facilitate wider testing and review. Depending +on the area of your patch and what is going on elsewhere, basing a patch +against these other trees can require a significant amount of work +resolving conflicts and dealing with API changes. Only the most simple changes should be formatted as a single patch; everything else should be made as a logical series of changes. Splitting @@ -100,11 +103,11 @@ rules of thumb, however, which can help considerably: result is a broken kernel, you will make life harder for developers and users who are engaging in the noble work of tracking down problems. - - Do not overdo it, though. One developer recently posted a set of edits + - Do not overdo it, though. One developer once posted a set of edits to a single file as 500 separate patches - an act which did not make him the most popular person on the kernel mailing list. A single patch can be reasonably large as long as it still contains a single *logical* - change. + change. - It can be tempting to add a whole new infrastructure with a series of patches, but to leave that infrastructure unused until the final patch @@ -162,7 +165,8 @@ To that end, the summary line should describe the effects of and motivation for the change as well as possible given the one-line constraint. The detailed description can then amplify on those topics and provide any needed additional information. If the patch fixes a bug, cite the commit -which introduced the bug if possible. If a problem is associated with +which introduced the bug if possible (and please provide both the commit ID +and the title when citing commits). If a problem is associated with specific log or compiler output, include that output to help others searching for a solution to the same problem. If the change is meant to support other changes coming in later patch, say so. If internal APIs are @@ -230,7 +234,7 @@ take care of: which have had gratuitous white-space changes or line wrapping performed by the mail client will not apply at the other end, and often will not be examined in any detail. If there is any doubt at all, mail the patch - to yourself and convince yourself that it shows up intact. + to yourself and convince yourself that it shows up intact. Documentation/email-clients.txt has some helpful hints on making specific mail clients work for sending patches. @@ -287,7 +291,7 @@ something like: where "nn" is the ordinal number of the patch, "mm" is the total number of patches in the series, and "subsys" is the name of the affected subsystem. -Clearly, nn/mm can be omitted for a single, standalone patch. +Clearly, nn/mm can be omitted for a single, standalone patch. If you have a significant series of patches, it is customary to send an introductory description as part zero. This convention is not universally @@ -299,5 +303,5 @@ In general, the second and following parts of a multi-part patch should be sent as a reply to the first part so that they all thread together at the receiving end. Tools like git and quilt have commands to mail out a set of patches with the proper threading. If you have a long series, though, and -are using git, please provide the --no-chain-reply-to option to avoid +are using git, please stay away from the --chain-reply-to option to avoid creating exceptionally deep nesting. diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough index a8fba3d83a85..41d324a9420d 100644 --- a/Documentation/development-process/6.Followthrough +++ b/Documentation/development-process/6.Followthrough @@ -66,6 +66,11 @@ be easy to become blinded by your own solution to a problem to the point that you don't realize that something is fundamentally wrong or, perhaps, you're not even solving the right problem. +Andrew Morton has suggested that every review comment which does not result +in a code change should result in an additional code comment instead; that +can help future reviewers avoid the questions which came up the first time +around. + One fatal mistake is to ignore review comments in the hope that they will go away. They will not go away. If you repost code without having responded to the comments you got the time before, you're likely to find @@ -100,7 +105,7 @@ entry into a subsystem maintainer's tree. How that works varies from one subsystem to the next; each maintainer has his or her own way of doing things. In particular, there may be more than one tree - one, perhaps, dedicated to patches planned for the next merge window, and another for -longer-term work. +longer-term work. For patches applying to areas for which there is no obvious subsystem tree (memory management patches, for example), the default tree often ends up @@ -109,11 +114,10 @@ through the -mm tree. Inclusion into a subsystem tree can bring a higher level of visibility to a patch. Now other developers working with that tree will get the patch by -default. Subsystem trees typically feed into -mm and linux-next as well, -making their contents visible to the development community as a whole. At -this point, there's a good chance that you will get more comments from a -new set of reviewers; these comments need to be answered as in the previous -round. +default. Subsystem trees typically feed linux-next as well, making their +contents visible to the development community as a whole. At this point, +there's a good chance that you will get more comments from a new set of +reviewers; these comments need to be answered as in the previous round. What may also happen at this point, depending on the nature of your patch, is that conflicts with work being done by others turn up. In the worst diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics index 837179447e17..26dc3fa196e4 100644 --- a/Documentation/development-process/7.AdvancedTopics +++ b/Documentation/development-process/7.AdvancedTopics @@ -119,7 +119,7 @@ can affect your ability to get trees pulled in the future. Quoting Linus: to trust things *without* then having to go and check every individual change by hand. -(http://lwn.net/Articles/224135/). +(http://lwn.net/Articles/224135/). To avoid this kind of situation, ensure that all patches within a given branch stick closely to the associated topic; a "driver fixes" branch @@ -138,7 +138,7 @@ When requesting a pull, be sure to give all the relevant information: where your tree is, what branch to pull, and what changes will result from the pull. The git request-pull command can be helpful in this regard; it will format the request as other developers expect, and will also check to be -sure that you have remembered to push those changes to the public server. +sure that you have remembered to push those changes to the public server. 7.2: REVIEWING PATCHES diff --git a/Documentation/device-mapper/dm-crypt.txt b/Documentation/device-mapper/dm-crypt.txt index 524de926290d..6b5c42dbbe84 100644 --- a/Documentation/device-mapper/dm-crypt.txt +++ b/Documentation/device-mapper/dm-crypt.txt @@ -8,7 +8,7 @@ Parameters: <cipher> <key> <iv_offset> <device path> <offset> <cipher> Encryption cipher and an optional IV generation mode. - (In format cipher-chainmode-ivopts:ivmode). + (In format cipher[:keycount]-chainmode-ivopts:ivmode). Examples: des aes-cbc-essiv:sha256 @@ -20,6 +20,11 @@ Parameters: <cipher> <key> <iv_offset> <device path> <offset> Key used for encryption. It is encoded as a hexadecimal number. You can only use key sizes that are valid for the selected cipher. +<keycount> + Multi-key compatibility mode. You can define <keycount> keys and + then sectors are encrypted according to their offsets (sector 0 uses key0; + sector 1 uses key1 etc.). <keycount> must be a power of two. + <iv_offset> The IV offset is a sector count that is added to the sector number before creating the IV. @@ -36,7 +41,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://clemens.endorphin.org/cryptography +http://code.google.com/p/cryptsetup/ [[ #!/bin/sh diff --git a/Documentation/device-mapper/dm-flakey.txt b/Documentation/device-mapper/dm-flakey.txt new file mode 100644 index 000000000000..c8efdfd19a65 --- /dev/null +++ b/Documentation/device-mapper/dm-flakey.txt @@ -0,0 +1,17 @@ +dm-flakey +========= + +This target is the same as the linear target except that it returns I/O +errors periodically. It's been found useful in simulating failing +devices for testing purposes. + +Starting from the time the table is loaded, the device is available for +<up interval> seconds, then returns errors for <down interval> seconds, +and then this cycle repeats. + +Parameters: <dev path> <offset> <up interval> <down interval> + <dev path>: Full pathname to the underlying block-device, or a + "major:minor" device-number. + <offset>: Starting sector within the device. + <up interval>: Number of seconds device is available. + <down interval>: Number of seconds device returns errors. diff --git a/Documentation/device-mapper/dm-raid.txt b/Documentation/device-mapper/dm-raid.txt new file mode 100644 index 000000000000..33b6b7071ac8 --- /dev/null +++ b/Documentation/device-mapper/dm-raid.txt @@ -0,0 +1,70 @@ +Device-mapper RAID (dm-raid) is a bridge from DM to MD. It +provides a way to use device-mapper interfaces to access the MD RAID +drivers. + +As with all device-mapper targets, the nominal public interfaces are the +constructor (CTR) tables and the status outputs (both STATUSTYPE_INFO +and STATUSTYPE_TABLE). The CTR table looks like the following: + +1: <s> <l> raid \ +2: <raid_type> <#raid_params> <raid_params> \ +3: <#raid_devs> <meta_dev1> <dev1> .. <meta_devN> <devN> + +Line 1 contains the standard first three arguments to any device-mapper +target - the start, length, and target type fields. The target type in +this case is "raid". + +Line 2 contains the arguments that define the particular raid +type/personality/level, the required arguments for that raid type, and +any optional arguments. Possible raid types include: raid4, raid5_la, +raid5_ls, raid5_rs, raid6_zr, raid6_nr, and raid6_nc. (raid1 is +planned for the future.) The list of required and optional parameters +is the same for all the current raid types. The required parameters are +positional, while the optional parameters are given as key/value pairs. +The possible parameters are as follows: + <chunk_size> Chunk size in sectors. + [[no]sync] Force/Prevent RAID initialization + [rebuild <idx>] Rebuild the drive indicated by the index + [daemon_sleep <ms>] Time between bitmap daemon work to clear bits + [min_recovery_rate <kB/sec/disk>] Throttle RAID initialization + [max_recovery_rate <kB/sec/disk>] Throttle RAID initialization + [max_write_behind <sectors>] See '-write-behind=' (man mdadm) + [stripe_cache <sectors>] Stripe cache size for higher RAIDs + +Line 3 contains the list of devices that compose the array in +metadata/data device pairs. If the metadata is stored separately, a '-' +is given for the metadata device position. If a drive has failed or is +missing at creation time, a '-' can be given for both the metadata and +data drives for a given position. + +NB. Currently all metadata devices must be specified as '-'. + +Examples: +# RAID4 - 4 data drives, 1 parity +# No metadata devices specified to hold superblock/bitmap info +# Chunk size of 1MiB +# (Lines separated for easy reading) +0 1960893648 raid \ + raid4 1 2048 \ + 5 - 8:17 - 8:33 - 8:49 - 8:65 - 8:81 + +# RAID4 - 4 data drives, 1 parity (no metadata devices) +# Chunk size of 1MiB, force RAID initialization, +# min recovery rate at 20 kiB/sec/disk +0 1960893648 raid \ + raid4 4 2048 min_recovery_rate 20 sync\ + 5 - 8:17 - 8:33 - 8:49 - 8:65 - 8:81 + +Performing a 'dmsetup table' should display the CTR table used to +construct the mapping (with possible reordering of optional +parameters). + +Performing a 'dmsetup status' will yield information on the state and +health of the array. The output is as follows: +1: <s> <l> raid \ +2: <raid_type> <#devices> <1 health char for each dev> <resync_ratio> + +Line 1 is standard DM output. Line 2 is best shown by example: + 0 1960893648 raid raid4 5 AAAAA 2/490221568 +Here we can see the RAID type is raid4, there are 5 devices - all of +which are 'A'live, and the array is 2/490221568 complete with recovery. diff --git a/Documentation/device-mapper/dm-service-time.txt b/Documentation/device-mapper/dm-service-time.txt index 7d00668e97bb..fb1d4a0cf122 100644 --- a/Documentation/device-mapper/dm-service-time.txt +++ b/Documentation/device-mapper/dm-service-time.txt @@ -37,7 +37,7 @@ Algorithm ========= dm-service-time adds the I/O size to 'in-flight-size' when the I/O is -dispatched and substracts when completed. +dispatched and subtracts when completed. Basically, dm-service-time selects a path having minimum service time which is calculated by: diff --git a/Documentation/devices.txt b/Documentation/devices.txt index d0d1df6cb5de..eccffe715229 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 @@ -1495,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 @@ -2519,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 @@ -2553,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 diff --git a/Documentation/devicetree/00-INDEX b/Documentation/devicetree/00-INDEX new file mode 100644 index 000000000000..b78f691fd847 --- /dev/null +++ b/Documentation/devicetree/00-INDEX @@ -0,0 +1,10 @@ +Documentation for device trees, a data structure by which bootloaders pass +hardware layout to Linux in a device-independent manner, simplifying hardware +probing. This subsystem is maintained by Grant Likely +<grant.likely@secretlab.ca> and has a mailing list at +https://lists.ozlabs.org/listinfo/devicetree-discuss + +00-INDEX + - this file +booting-without-of.txt + - Booting Linux without Open Firmware, describes history and format of device trees. diff --git a/Documentation/powerpc/dts-bindings/fsl/sata.txt b/Documentation/devicetree/bindings/ata/fsl-sata.txt index b46bcf46c3d8..b46bcf46c3d8 100644 --- a/Documentation/powerpc/dts-bindings/fsl/sata.txt +++ b/Documentation/devicetree/bindings/ata/fsl-sata.txt diff --git a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt new file mode 100644 index 000000000000..bf57ecd5d73a --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt @@ -0,0 +1,397 @@ +===================================================================== +SEC 4 Device Tree Binding +Copyright (C) 2008-2011 Freescale Semiconductor Inc. + + CONTENTS + -Overview + -SEC 4 Node + -Job Ring Node + -Run Time Integrity Check (RTIC) Node + -Run Time Integrity Check (RTIC) Memory Node + -Secure Non-Volatile Storage (SNVS) Node + -Full Example + +NOTE: the SEC 4 is also known as Freescale's Cryptographic Accelerator +Accelerator and Assurance Module (CAAM). + +===================================================================== +Overview + +DESCRIPTION + +SEC 4 h/w can process requests from 2 types of sources. +1. DPAA Queue Interface (HW interface between Queue Manager & SEC 4). +2. Job Rings (HW interface between cores & SEC 4 registers). + +High Speed Data Path Configuration: + +HW interface between QM & SEC 4 and also BM & SEC 4, on DPAA-enabled parts +such as the P4080. The number of simultaneous dequeues the QI can make is +equal to the number of Descriptor Controller (DECO) engines in a particular +SEC version. E.g., the SEC 4.0 in the P4080 has 5 DECOs and can thus +dequeue from 5 subportals simultaneously. + +Job Ring Data Path Configuration: + +Each JR is located on a separate 4k page, they may (or may not) be made visible +in the memory partition devoted to a particular core. The P4080 has 4 JRs, so +up to 4 JRs can be configured; and all 4 JRs process requests in parallel. + +===================================================================== +SEC 4 Node + +Description + + Node defines the base address of the SEC 4 block. + This block specifies the address range of all global + configuration registers for the SEC 4 block. It + also receives interrupts from the Run Time Integrity Check + (RTIC) function within the SEC 4 block. + +PROPERTIES + + - compatible + Usage: required + Value type: <string> + Definition: Must include "fsl,sec-v4.0" + + - #address-cells + Usage: required + Value type: <u32> + Definition: A standard property. Defines the number of cells + for representing physical addresses in child nodes. + + - #size-cells + Usage: required + Value type: <u32> + Definition: A standard property. Defines the number of cells + for representing the size of physical addresses in + child nodes. + + - reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies the physical + address and length of the SEC4 configuration registers. + registers + + - ranges + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies the physical address + range of the SEC 4.0 register space (-SNVS not included). A + triplet that includes the child address, parent address, & + length. + + - interrupts + Usage: required + Value type: <prop_encoded-array> + Definition: Specifies the interrupts generated by this + device. The value of the interrupts property + consists of one interrupt specifier. The format + of the specifier is defined by the binding document + describing the node's interrupt parent. + + - interrupt-parent + Usage: (required if interrupt property is defined) + Value type: <phandle> + Definition: A single <phandle> value that points + to the interrupt parent to which the child domain + is being mapped. + + Note: All other standard properties (see the ePAPR) are allowed + but are optional. + + +EXAMPLE + crypto@300000 { + compatible = "fsl,sec-v4.0"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x300000 0x10000>; + ranges = <0 0x300000 0x10000>; + interrupt-parent = <&mpic>; + interrupts = <92 2>; + }; + +===================================================================== +Job Ring (JR) Node + + Child of the crypto node defines data processing interface to SEC 4 + across the peripheral bus for purposes of processing + cryptographic descriptors. The specified address + range can be made visible to one (or more) cores. + The interrupt defined for this node is controlled within + the address range of this node. + + - compatible + Usage: required + Value type: <string> + Definition: Must include "fsl,sec-v4.0-job-ring" + + - reg + Usage: required + Value type: <prop-encoded-array> + Definition: Specifies a two JR parameters: an offset from + the parent physical address and the length the JR registers. + + - fsl,liodn + Usage: optional-but-recommended + Value type: <prop-encoded-array> + Definition: + Specifies the LIODN to be used in conjunction with + the ppid-to-liodn table that specifies the PPID to LIODN mapping. + Needed if the PAMU is used. Value is a 12 bit value + where value is a LIODN ID for this JR. This property is + normally set by boot firmware. + + - interrupts + Usage: required + Value type: <prop_encoded-array> + Definition: Specifies the interrupts generated by this + device. The value of the interrupts property + consists of one interrupt specifier. The format + of the specifier is defined by the binding document + describing the node's interrupt parent. + + - interrupt-parent + Usage: (required if interrupt property is defined) + Value type: <phandle> + Definition: A single <phandle> value that points + to the interrupt parent to which the child domain + is being mapped. + +EXAMPLE + jr@1000 { + compatible = "fsl,sec-v4.0-job-ring"; + reg = <0x1000 0x1000>; + fsl,liodn = <0x081>; + interrupt-parent = <&mpic>; + interrupts = <88 2>; + }; + + +===================================================================== +Run Time Integrity Check (RTIC) Node + + Child node of the crypto node. Defines a register space that + contains up to 5 sets of addresses and their lengths (sizes) that + will be checked at run time. After an initial hash result is + calculated, these addresses are checked by HW to monitor any + change. If any memory is modified, a Security Violation is + triggered (see SNVS definition). + + + - compatible + Usage: required + Value type: <string> + Definition: Must include "fsl,sec-v4.0-rtic". + + - #address-cells + Usage: required + Value type: <u32> + Definition: A standard property. Defines the number of cells + for representing physical addresses in child nodes. Must + have a value of 1. + + - #size-cells + Usage: required + Value type: <u32> + Definition: A standard property. Defines the number of cells + for representing the size of physical addresses in + child nodes. Must have a value of 1. + + - reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies a two parameters: + an offset from the parent physical address and the length + the SEC4 registers. + + - ranges + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies the physical address + range of the SEC 4 register space (-SNVS not included). A + triplet that includes the child address, parent address, & + length. + +EXAMPLE + rtic@6000 { + compatible = "fsl,sec-v4.0-rtic"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x6000 0x100>; + ranges = <0x0 0x6100 0xe00>; + }; + +===================================================================== +Run Time Integrity Check (RTIC) Memory Node + A child node that defines individual RTIC memory regions that are used to + perform run-time integrity check of memory areas that should not modified. + The node defines a register that contains the memory address & + length (combined) and a second register that contains the hash result + in big endian format. + + - compatible + Usage: required + Value type: <string> + Definition: Must include "fsl,sec-v4.0-rtic-memory". + + - reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies two parameters: + an offset from the parent physical address and the length: + + 1. The location of the RTIC memory address & length registers. + 2. The location RTIC hash result. + + - fsl,rtic-region + Usage: optional-but-recommended + Value type: <prop-encoded-array> + Definition: + Specifies the HW address (36 bit address) for this region + followed by the length of the HW partition to be checked; + the address is represented as a 64 bit quantity followed + by a 32 bit length. + + - fsl,liodn + Usage: optional-but-recommended + Value type: <prop-encoded-array> + Definition: + Specifies the LIODN to be used in conjunction with + the ppid-to-liodn table that specifies the PPID to LIODN + mapping. Needed if the PAMU is used. Value is a 12 bit value + where value is a LIODN ID for this RTIC memory region. This + property is normally set by boot firmware. + +EXAMPLE + rtic-a@0 { + compatible = "fsl,sec-v4.0-rtic-memory"; + reg = <0x00 0x20 0x100 0x80>; + fsl,liodn = <0x03c>; + fsl,rtic-region = <0x12345678 0x12345678 0x12345678>; + }; + +===================================================================== +Secure Non-Volatile Storage (SNVS) Node + + Node defines address range and the associated + interrupt for the SNVS function. This function + monitors security state information & reports + security violations. + + - compatible + Usage: required + Value type: <string> + Definition: Must include "fsl,sec-v4.0-mon". + + - reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies the physical + address and length of the SEC4 configuration + registers. + + - interrupts + Usage: required + Value type: <prop_encoded-array> + Definition: Specifies the interrupts generated by this + device. The value of the interrupts property + consists of one interrupt specifier. The format + of the specifier is defined by the binding document + describing the node's interrupt parent. + + - interrupt-parent + Usage: (required if interrupt property is defined) + Value type: <phandle> + Definition: A single <phandle> value that points + to the interrupt parent to which the child domain + is being mapped. + +EXAMPLE + sec_mon@314000 { + compatible = "fsl,sec-v4.0-mon"; + reg = <0x314000 0x1000>; + interrupt-parent = <&mpic>; + interrupts = <93 2>; + }; + +===================================================================== +FULL EXAMPLE + + crypto: crypto@300000 { + compatible = "fsl,sec-v4.0"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x300000 0x10000>; + ranges = <0 0x300000 0x10000>; + interrupt-parent = <&mpic>; + interrupts = <92 2>; + + sec_jr0: jr@1000 { + compatible = "fsl,sec-v4.0-job-ring"; + reg = <0x1000 0x1000>; + interrupt-parent = <&mpic>; + interrupts = <88 2>; + }; + + sec_jr1: jr@2000 { + compatible = "fsl,sec-v4.0-job-ring"; + reg = <0x2000 0x1000>; + interrupt-parent = <&mpic>; + interrupts = <89 2>; + }; + + sec_jr2: jr@3000 { + compatible = "fsl,sec-v4.0-job-ring"; + reg = <0x3000 0x1000>; + interrupt-parent = <&mpic>; + interrupts = <90 2>; + }; + + sec_jr3: jr@4000 { + compatible = "fsl,sec-v4.0-job-ring"; + reg = <0x4000 0x1000>; + interrupt-parent = <&mpic>; + interrupts = <91 2>; + }; + + rtic@6000 { + compatible = "fsl,sec-v4.0-rtic"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x6000 0x100>; + ranges = <0x0 0x6100 0xe00>; + + rtic_a: rtic-a@0 { + compatible = "fsl,sec-v4.0-rtic-memory"; + reg = <0x00 0x20 0x100 0x80>; + }; + + rtic_b: rtic-b@20 { + compatible = "fsl,sec-v4.0-rtic-memory"; + reg = <0x20 0x20 0x200 0x80>; + }; + + rtic_c: rtic-c@40 { + compatible = "fsl,sec-v4.0-rtic-memory"; + reg = <0x40 0x20 0x300 0x80>; + }; + + rtic_d: rtic-d@60 { + compatible = "fsl,sec-v4.0-rtic-memory"; + reg = <0x60 0x20 0x500 0x80>; + }; + }; + }; + + sec_mon: sec_mon@314000 { + compatible = "fsl,sec-v4.0-mon"; + reg = <0x314000 0x1000>; + interrupt-parent = <&mpic>; + interrupts = <93 2>; + }; + +===================================================================== diff --git a/Documentation/devicetree/bindings/eeprom.txt b/Documentation/devicetree/bindings/eeprom.txt new file mode 100644 index 000000000000..4342c10de1bf --- /dev/null +++ b/Documentation/devicetree/bindings/eeprom.txt @@ -0,0 +1,28 @@ +EEPROMs (I2C) + +Required properties: + + - compatible : should be "<manufacturer>,<type>" + If there is no specific driver for <manufacturer>, a generic + driver based on <type> is selected. Possible types are: + 24c00, 24c01, 24c02, 24c04, 24c08, 24c16, 24c32, 24c64, + 24c128, 24c256, 24c512, 24c1024, spd + + - reg : the I2C address of the EEPROM + +Optional properties: + + - pagesize : the length of the pagesize for writing. Please consult the + manual of your device, that value varies a lot. A wrong value + may result in data loss! If not specified, a safety value of + '1' is used which will be very slow. + + - read-only: this parameterless property disables writes to the eeprom + +Example: + +eeprom@52 { + compatible = "atmel,24c32"; + reg = <0x52>; + pagesize = <32>; +}; diff --git a/Documentation/devicetree/bindings/fb/sm501fb.txt b/Documentation/devicetree/bindings/fb/sm501fb.txt new file mode 100644 index 000000000000..9d9f0098092b --- /dev/null +++ b/Documentation/devicetree/bindings/fb/sm501fb.txt @@ -0,0 +1,34 @@ +* SM SM501 + +The SM SM501 is a LCD controller, with proper hardware, it can also +drive DVI monitors. + +Required properties: +- compatible : should be "smi,sm501". +- reg : contain two entries: + - First entry: System Configuration register + - Second entry: IO space (Display Controller register) +- interrupts : SMI interrupt to the cpu should be described here. +- interrupt-parent : the phandle for the interrupt controller that + services interrupts for this device. + +Optional properties: +- mode : select a video mode: + <xres>x<yres>[-<bpp>][@<refresh>] +- edid : verbatim EDID data block describing attached display. + Data from the detailed timing descriptor will be used to + program the display controller. +- little-endian: available on big endian systems, to + set different foreign endian. +- big-endian: available on little endian systems, to + set different foreign endian. + +Example for MPC5200: + display@1,0 { + compatible = "smi,sm501"; + reg = <1 0x00000000 0x00800000 + 1 0x03e00000 0x00200000>; + interrupts = <1 1 3>; + mode = "640x480-32@60"; + edid = [edid-data]; + }; diff --git a/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt b/Documentation/devicetree/bindings/gpio/8xxx_gpio.txt index b0019eb5330e..b0019eb5330e 100644 --- a/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt +++ b/Documentation/devicetree/bindings/gpio/8xxx_gpio.txt diff --git a/Documentation/powerpc/dts-bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index edaa84d288a1..edaa84d288a1 100644 --- a/Documentation/powerpc/dts-bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt diff --git a/Documentation/powerpc/dts-bindings/gpio/led.txt b/Documentation/devicetree/bindings/gpio/led.txt index 064db928c3c1..064db928c3c1 100644 --- a/Documentation/powerpc/dts-bindings/gpio/led.txt +++ b/Documentation/devicetree/bindings/gpio/led.txt diff --git a/Documentation/devicetree/bindings/hwmon/ads1015.txt b/Documentation/devicetree/bindings/hwmon/ads1015.txt new file mode 100644 index 000000000000..918a507d1159 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ads1015.txt @@ -0,0 +1,73 @@ +ADS1015 (I2C) + +This device is a 12-bit A-D converter with 4 inputs. + +The inputs can be used single ended or in certain differential combinations. + +For configuration all possible combinations are mapped to 8 channels: + 0: Voltage over AIN0 and AIN1. + 1: Voltage over AIN0 and AIN3. + 2: Voltage over AIN1 and AIN3. + 3: Voltage over AIN2 and AIN3. + 4: Voltage over AIN0 and GND. + 5: Voltage over AIN1 and GND. + 6: Voltage over AIN2 and GND. + 7: Voltage over AIN3 and GND. + +Each channel can be configured individually: + - pga is the programmable gain amplifier (values are full scale) + 0: +/- 6.144 V + 1: +/- 4.096 V + 2: +/- 2.048 V (default) + 3: +/- 1.024 V + 4: +/- 0.512 V + 5: +/- 0.256 V + - data_rate in samples per second + 0: 128 + 1: 250 + 2: 490 + 3: 920 + 4: 1600 (default) + 5: 2400 + 6: 3300 + +1) The /ads1015 node + + Required properties: + + - compatible : must be "ti,ads1015" + - reg : I2C bus address of the device + - #address-cells : must be <1> + - #size-cells : must be <0> + + The node contains child nodes for each channel that the platform uses. + + Example ADS1015 node: + + ads1015@49 { + compatible = "ti,ads1015"; + reg = <0x49>; + #address-cells = <1>; + #size-cells = <0>; + + [ child node definitions... ] + } + +2) channel nodes + + Required properties: + + - reg : the channel number + + Optional properties: + + - ti,gain : the programmable gain amplifier setting + - ti,datarate : the converter data rate + + Example ADS1015 channel node: + + channel@4 { + reg = <4>; + ti,gain = <3>; + ti,datarate = <5>; + }; diff --git a/Documentation/devicetree/bindings/i2c/ce4100-i2c.txt b/Documentation/devicetree/bindings/i2c/ce4100-i2c.txt new file mode 100644 index 000000000000..569b16248514 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/ce4100-i2c.txt @@ -0,0 +1,93 @@ +CE4100 I2C +---------- + +CE4100 has one PCI device which is described as the I2C-Controller. This +PCI device has three PCI-bars, each bar contains a complete I2C +controller. So we have a total of three independent I2C-Controllers +which share only an interrupt line. +The driver is probed via the PCI-ID and is gathering the information of +attached devices from the devices tree. +Grant Likely recommended to use the ranges property to map the PCI-Bar +number to its physical address and to use this to find the child nodes +of the specific I2C controller. This were his exact words: + + Here's where the magic happens. Each entry in + ranges describes how the parent pci address space + (middle group of 3) is translated to the local + address space (first group of 2) and the size of + each range (last cell). In this particular case, + the first cell of the local address is chosen to be + 1:1 mapped to the BARs, and the second is the + offset from be base of the BAR (which would be + non-zero if you had 2 or more devices mapped off + the same BAR) + + ranges allows the address mapping to be described + in a way that the OS can interpret without + requiring custom device driver code. + +This is an example which is used on FalconFalls: +------------------------------------------------ + i2c-controller@b,2 { + #address-cells = <2>; + #size-cells = <1>; + compatible = "pci8086,2e68.2", + "pci8086,2e68", + "pciclass,ff0000", + "pciclass,ff00"; + + reg = <0x15a00 0x0 0x0 0x0 0x0>; + interrupts = <16 1>; + + /* as described by Grant, the first number in the group of + * three is the bar number followed by the 64bit bar address + * followed by size of the mapping. The bar address + * requires also a valid translation in parents ranges + * property. + */ + ranges = <0 0 0x02000000 0 0xdffe0500 0x100 + 1 0 0x02000000 0 0xdffe0600 0x100 + 2 0 0x02000000 0 0xdffe0700 0x100>; + + i2c@0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "intel,ce4100-i2c-controller"; + + /* The first number in the reg property is the + * number of the bar + */ + reg = <0 0 0x100>; + + /* This I2C controller has no devices */ + }; + + i2c@1 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "intel,ce4100-i2c-controller"; + reg = <1 0 0x100>; + + /* This I2C controller has one gpio controller */ + gpio@26 { + #gpio-cells = <2>; + compatible = "ti,pcf8575"; + reg = <0x26>; + gpio-controller; + }; + }; + + i2c@2 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "intel,ce4100-i2c-controller"; + reg = <2 0 0x100>; + + gpio@26 { + #gpio-cells = <2>; + compatible = "ti,pcf8575"; + reg = <0x26>; + gpio-controller; + }; + }; + }; diff --git a/Documentation/powerpc/dts-bindings/fsl/i2c.txt b/Documentation/devicetree/bindings/i2c/fsl-i2c.txt index 1eacd6b20ed5..1eacd6b20ed5 100644 --- a/Documentation/powerpc/dts-bindings/fsl/i2c.txt +++ b/Documentation/devicetree/bindings/i2c/fsl-i2c.txt diff --git a/Documentation/powerpc/dts-bindings/marvell.txt b/Documentation/devicetree/bindings/marvell.txt index f1533d91953a..f1533d91953a 100644 --- a/Documentation/powerpc/dts-bindings/marvell.txt +++ b/Documentation/devicetree/bindings/marvell.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/esdhc.txt b/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt index 64bcb8be973c..64bcb8be973c 100644 --- a/Documentation/powerpc/dts-bindings/fsl/esdhc.txt +++ b/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt diff --git a/Documentation/powerpc/dts-bindings/mmc-spi-slot.txt b/Documentation/devicetree/bindings/mmc/mmc-spi-slot.txt index c39ac2891951..89a0084df2f7 100644 --- a/Documentation/powerpc/dts-bindings/mmc-spi-slot.txt +++ b/Documentation/devicetree/bindings/mmc/mmc-spi-slot.txt @@ -7,8 +7,13 @@ Required properties: - voltage-ranges : two cells are required, first cell specifies minimum slot voltage (mV), second cell specifies maximum slot voltage (mV). Several ranges could be specified. -- gpios : (optional) may specify GPIOs in this order: Card-Detect GPIO, + +Optional properties: +- gpios : may specify GPIOs in this order: Card-Detect GPIO, Write-Protect GPIO. +- interrupts : the interrupt of a card detect interrupt. +- interrupt-parent : the phandle for the interrupt controller that + services interrupts for this device. Example: @@ -20,4 +25,6 @@ Example: &qe_pio_d 15 0>; voltage-ranges = <3300 3300>; spi-max-frequency = <50000000>; + interrupts = <42>; + interrupt-parent = <&PIC>; }; diff --git a/Documentation/powerpc/dts-bindings/fsl/upm-nand.txt b/Documentation/devicetree/bindings/mtd/fsl-upm-nand.txt index a48b2cadc7f0..00f1f546b32e 100644 --- a/Documentation/powerpc/dts-bindings/fsl/upm-nand.txt +++ b/Documentation/devicetree/bindings/mtd/fsl-upm-nand.txt @@ -15,7 +15,7 @@ Optional properties: - gpios : may specify optional GPIOs connected to the Ready-Not-Busy pins (R/B#). For multi-chip devices, "n" GPIO definitions are required according to the number of chips. -- chip-delay : chip dependent delay for transfering data from array to +- chip-delay : chip dependent delay for transferring data from array to read registers (tR). Required if property "gpios" is not used (R/B# pins not connected). diff --git a/Documentation/powerpc/dts-bindings/mtd-physmap.txt b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt index 80152cb567d9..80152cb567d9 100644 --- a/Documentation/powerpc/dts-bindings/mtd-physmap.txt +++ b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/can.txt b/Documentation/devicetree/bindings/net/can/mpc5xxx-mscan.txt index 2fa4fcd38fd6..2fa4fcd38fd6 100644 --- a/Documentation/powerpc/dts-bindings/fsl/can.txt +++ b/Documentation/devicetree/bindings/net/can/mpc5xxx-mscan.txt diff --git a/Documentation/powerpc/dts-bindings/can/sja1000.txt b/Documentation/devicetree/bindings/net/can/sja1000.txt index d6d209ded937..c2dbcec0ee31 100644 --- a/Documentation/powerpc/dts-bindings/can/sja1000.txt +++ b/Documentation/devicetree/bindings/net/can/sja1000.txt @@ -39,7 +39,7 @@ Optional properties: - nxp,no-comparator-bypass : Allows to disable the CAN input comperator. -For futher information, please have a look to the SJA1000 data sheet. +For further information, please have a look to the SJA1000 data sheet. Examples: diff --git a/Documentation/powerpc/dts-bindings/fsl/tsec.txt b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt index edb7ae19e868..edb7ae19e868 100644 --- a/Documentation/powerpc/dts-bindings/fsl/tsec.txt +++ b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt diff --git a/Documentation/powerpc/dts-bindings/gpio/mdio.txt b/Documentation/devicetree/bindings/net/mdio-gpio.txt index bc9549529014..bc9549529014 100644 --- a/Documentation/powerpc/dts-bindings/gpio/mdio.txt +++ b/Documentation/devicetree/bindings/net/mdio-gpio.txt diff --git a/Documentation/powerpc/dts-bindings/phy.txt b/Documentation/devicetree/bindings/net/phy.txt index bb8c742eb8c5..bb8c742eb8c5 100644 --- a/Documentation/powerpc/dts-bindings/phy.txt +++ b/Documentation/devicetree/bindings/net/phy.txt diff --git a/Documentation/devicetree/bindings/open-pic.txt b/Documentation/devicetree/bindings/open-pic.txt new file mode 100644 index 000000000000..909a902dff85 --- /dev/null +++ b/Documentation/devicetree/bindings/open-pic.txt @@ -0,0 +1,98 @@ +* Open PIC Binding + +This binding specifies what properties must be available in the device tree +representation of an Open PIC compliant interrupt controller. This binding is +based on the binding defined for Open PIC in [1] and is a superset of that +binding. + +Required properties: + + NOTE: Many of these descriptions were paraphrased here from [1] to aid + readability. + + - compatible: Specifies the compatibility list for the PIC. The type + shall be <string> and the value shall include "open-pic". + + - reg: Specifies the base physical address(s) and size(s) of this + PIC's addressable register space. The type shall be <prop-encoded-array>. + + - interrupt-controller: The presence of this property identifies the node + as an Open PIC. No property value shall be defined. + + - #interrupt-cells: Specifies the number of cells needed to encode an + interrupt source. The type shall be a <u32> and the value shall be 2. + + - #address-cells: Specifies the number of cells needed to encode an + address. The type shall be <u32> and the value shall be 0. As such, + 'interrupt-map' nodes do not have to specify a parent unit address. + +Optional properties: + + - pic-no-reset: The presence of this property indicates that the PIC + shall not be reset during runtime initialization. No property value shall + be defined. The presence of this property also mandates that any + initialization related to interrupt sources shall be limited to sources + explicitly referenced in the device tree. + +* Interrupt Specifier Definition + + Interrupt specifiers consists of 2 cells encoded as + follows: + + - <1st-cell>: The interrupt-number that identifies the interrupt source. + + - <2nd-cell>: The level-sense information, encoded as follows: + 0 = low-to-high edge triggered + 1 = active low level-sensitive + 2 = active high level-sensitive + 3 = high-to-low edge triggered + +* Examples + +Example 1: + + /* + * An Open PIC interrupt controller + */ + mpic: pic@40000 { + // This is an interrupt controller node. + interrupt-controller; + + // No address cells so that 'interrupt-map' nodes which reference + // this Open PIC node do not need a parent address specifier. + #address-cells = <0>; + + // Two cells to encode interrupt sources. + #interrupt-cells = <2>; + + // Offset address of 0x40000 and size of 0x40000. + reg = <0x40000 0x40000>; + + // Compatible with Open PIC. + compatible = "open-pic"; + + // The PIC shall not be reset. + pic-no-reset; + }; + +Example 2: + + /* + * An interrupt generating device that is wired to an Open PIC. + */ + serial0: serial@4500 { + // Interrupt source '42' that is active high level-sensitive. + // Note that there are only two cells as specified in the interrupt + // parent's '#interrupt-cells' property. + interrupts = <42 2>; + + // The interrupt controller that this device is wired to. + interrupt-parent = <&mpic>; + }; + +* References + +[1] Power.org (TM) Standard for Embedded Power Architecture (TM) Platform + Requirements (ePAPR), Version 1.0, July 2008. + (http://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf) + diff --git a/Documentation/powerpc/dts-bindings/fsl/83xx-512x-pci.txt b/Documentation/devicetree/bindings/pci/83xx-512x-pci.txt index 35a465362408..35a465362408 100644 --- a/Documentation/powerpc/dts-bindings/fsl/83xx-512x-pci.txt +++ b/Documentation/devicetree/bindings/pci/83xx-512x-pci.txt diff --git a/Documentation/devicetree/bindings/powerpc/4xx/cpm.txt b/Documentation/devicetree/bindings/powerpc/4xx/cpm.txt new file mode 100644 index 000000000000..ee459806d35e --- /dev/null +++ b/Documentation/devicetree/bindings/powerpc/4xx/cpm.txt @@ -0,0 +1,52 @@ +PPC4xx Clock Power Management (CPM) node + +Required properties: + - compatible : compatible list, currently only "ibm,cpm" + - dcr-access-method : "native" + - dcr-reg : < DCR register range > + +Optional properties: + - er-offset : All 4xx SoCs with a CPM controller have + one of two different order for the CPM + registers. Some have the CPM registers + in the following order (ER,FR,SR). The + others have them in the following order + (SR,ER,FR). For the second case set + er-offset = <1>. + - unused-units : specifier consist of one cell. For each + bit in the cell, the corresponding bit + in CPM will be set to turn off unused + devices. + - idle-doze : specifier consist of one cell. For each + bit in the cell, the corresponding bit + in CPM will be set to turn off unused + devices. This is usually just CPM[CPU]. + - standby : specifier consist of one cell. For each + bit in the cell, the corresponding bit + in CPM will be set on standby and + restored on resume. + - suspend : specifier consist of one cell. For each + bit in the cell, the corresponding bit + in CPM will be set on suspend (mem) and + restored on resume. Note, for standby + and suspend the corresponding bits can + be different or the same. Usually for + standby only class 2 and 3 units are set. + However, the interface does not care. + If they are the same, the additional + power saving will be seeing if support + is available to put the DDR in self + refresh mode and any additional power + saving techniques for the specific SoC. + +Example: + CPM0: cpm { + compatible = "ibm,cpm"; + dcr-access-method = "native"; + dcr-reg = <0x160 0x003>; + er-offset = <0>; + unused-units = <0x00000100>; + idle-doze = <0x02000000>; + standby = <0xfeff0000>; + suspend = <0xfeff791d>; +}; diff --git a/Documentation/powerpc/dts-bindings/4xx/emac.txt b/Documentation/devicetree/bindings/powerpc/4xx/emac.txt index 2161334a7ca5..2161334a7ca5 100644 --- a/Documentation/powerpc/dts-bindings/4xx/emac.txt +++ b/Documentation/devicetree/bindings/powerpc/4xx/emac.txt diff --git a/Documentation/powerpc/dts-bindings/4xx/ndfc.txt b/Documentation/devicetree/bindings/powerpc/4xx/ndfc.txt index 869f0b5f16e8..869f0b5f16e8 100644 --- a/Documentation/powerpc/dts-bindings/4xx/ndfc.txt +++ b/Documentation/devicetree/bindings/powerpc/4xx/ndfc.txt diff --git a/Documentation/powerpc/dts-bindings/4xx/ppc440spe-adma.txt b/Documentation/devicetree/bindings/powerpc/4xx/ppc440spe-adma.txt index 515ebcf1b97d..515ebcf1b97d 100644 --- a/Documentation/powerpc/dts-bindings/4xx/ppc440spe-adma.txt +++ b/Documentation/devicetree/bindings/powerpc/4xx/ppc440spe-adma.txt diff --git a/Documentation/powerpc/dts-bindings/4xx/reboot.txt b/Documentation/devicetree/bindings/powerpc/4xx/reboot.txt index d7217260589c..d7217260589c 100644 --- a/Documentation/powerpc/dts-bindings/4xx/reboot.txt +++ b/Documentation/devicetree/bindings/powerpc/4xx/reboot.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/board.txt b/Documentation/devicetree/bindings/powerpc/fsl/board.txt index 39e941515a36..39e941515a36 100644 --- a/Documentation/powerpc/dts-bindings/fsl/board.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/board.txt diff --git a/Documentation/devicetree/bindings/powerpc/fsl/cache_sram.txt b/Documentation/devicetree/bindings/powerpc/fsl/cache_sram.txt new file mode 100644 index 000000000000..781955f5217d --- /dev/null +++ b/Documentation/devicetree/bindings/powerpc/fsl/cache_sram.txt @@ -0,0 +1,20 @@ +* Freescale PQ3 and QorIQ based Cache SRAM + +Freescale's mpc85xx and some QorIQ platforms provide an +option of configuring a part of (or full) cache memory +as SRAM. This cache SRAM representation in the device +tree should be done as under:- + +Required properties: + +- compatible : should be "fsl,p2020-cache-sram" +- fsl,cache-sram-ctlr-handle : points to the L2 controller +- reg : offset and length of the cache-sram. + +Example: + +cache-sram@fff00000 { + fsl,cache-sram-ctlr-handle = <&L2>; + reg = <0 0xfff00000 0 0x10000>; + compatible = "fsl,p2020-cache-sram"; +}; diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/cpm.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm.txt index 160c752484b4..160c752484b4 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/cpm.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/cpm/brg.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/brg.txt index 4c7d45eaf025..4c7d45eaf025 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/cpm/brg.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/brg.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/cpm/i2c.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/i2c.txt index 87bc6048667e..87bc6048667e 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/cpm/i2c.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/i2c.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/cpm/pic.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/pic.txt index 8e3ee1681618..8e3ee1681618 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/cpm/pic.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/pic.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/cpm/usb.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/usb.txt index 74bfda4bb824..74bfda4bb824 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/cpm/usb.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/usb.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/gpio.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/gpio.txt index 349f79fd7076..349f79fd7076 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/gpio.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/gpio.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/network.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/network.txt index 0e4269446580..0e4269446580 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/network.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/network.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe.txt index 4f8930263dd9..4f8930263dd9 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe/firmware.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/firmware.txt index 249db3a15d15..249db3a15d15 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe/firmware.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/firmware.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe/par_io.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/par_io.txt index 60984260207b..60984260207b 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe/par_io.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/par_io.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe/pincfg.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/pincfg.txt index c5b43061db3a..c5b43061db3a 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe/pincfg.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/pincfg.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe/ucc.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/ucc.txt index e47734bee3f0..e47734bee3f0 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe/ucc.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/ucc.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe/usb.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/usb.txt index 9ccd5f30405b..9ccd5f30405b 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/qe/usb.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/usb.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/serial.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/serial.txt index 2ea76d9d137c..2ea76d9d137c 100644 --- a/Documentation/powerpc/dts-bindings/fsl/cpm_qe/serial.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/serial.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/diu.txt b/Documentation/devicetree/bindings/powerpc/fsl/diu.txt index b66cb6d31d69..b66cb6d31d69 100644 --- a/Documentation/powerpc/dts-bindings/fsl/diu.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/diu.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/dma.txt b/Documentation/devicetree/bindings/powerpc/fsl/dma.txt index 2a4b4bce6110..2a4b4bce6110 100644 --- a/Documentation/powerpc/dts-bindings/fsl/dma.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/dma.txt diff --git a/Documentation/powerpc/dts-bindings/ecm.txt b/Documentation/devicetree/bindings/powerpc/fsl/ecm.txt index f514f29c67d6..f514f29c67d6 100644 --- a/Documentation/powerpc/dts-bindings/ecm.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/ecm.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/gtm.txt b/Documentation/devicetree/bindings/powerpc/fsl/gtm.txt index 9a33efded4bc..9a33efded4bc 100644 --- a/Documentation/powerpc/dts-bindings/fsl/gtm.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/gtm.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/guts.txt b/Documentation/devicetree/bindings/powerpc/fsl/guts.txt index 9e7a2417dac5..9e7a2417dac5 100644 --- a/Documentation/powerpc/dts-bindings/fsl/guts.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/guts.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/lbc.txt b/Documentation/devicetree/bindings/powerpc/fsl/lbc.txt index 3300fec501c5..3300fec501c5 100644 --- a/Documentation/powerpc/dts-bindings/fsl/lbc.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/lbc.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/mcm.txt b/Documentation/devicetree/bindings/powerpc/fsl/mcm.txt index 4ceda9b3b413..4ceda9b3b413 100644 --- a/Documentation/powerpc/dts-bindings/fsl/mcm.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/mcm.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/mcu-mpc8349emitx.txt b/Documentation/devicetree/bindings/powerpc/fsl/mcu-mpc8349emitx.txt index 0f766333b6eb..0f766333b6eb 100644 --- a/Documentation/powerpc/dts-bindings/fsl/mcu-mpc8349emitx.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/mcu-mpc8349emitx.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/mpc5121-psc.txt b/Documentation/devicetree/bindings/powerpc/fsl/mpc5121-psc.txt index 8832e8798912..8832e8798912 100644 --- a/Documentation/powerpc/dts-bindings/fsl/mpc5121-psc.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/mpc5121-psc.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/mpc5200.txt b/Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt index 4ccb2cd5df94..4ccb2cd5df94 100644 --- a/Documentation/powerpc/dts-bindings/fsl/mpc5200.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt diff --git a/Documentation/devicetree/bindings/powerpc/fsl/mpic.txt b/Documentation/devicetree/bindings/powerpc/fsl/mpic.txt new file mode 100644 index 000000000000..4f6145859aab --- /dev/null +++ b/Documentation/devicetree/bindings/powerpc/fsl/mpic.txt @@ -0,0 +1,211 @@ +===================================================================== +Freescale MPIC Interrupt Controller Node +Copyright (C) 2010,2011 Freescale Semiconductor Inc. +===================================================================== + +The Freescale MPIC interrupt controller is found on all PowerQUICC +and QorIQ processors and is compatible with the Open PIC. The +notable difference from Open PIC binding is the addition of 2 +additional cells in the interrupt specifier defining interrupt type +information. + +PROPERTIES + + - compatible + Usage: required + Value type: <string> + Definition: Shall include "fsl,mpic". Freescale MPIC + controllers compatible with this binding have Block + Revision Registers BRR1 and BRR2 at offset 0x0 and + 0x10 in the MPIC. + + - reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies the physical + offset and length of the device's registers within the + CCSR address space. + + - interrupt-controller + Usage: required + Value type: <empty> + Definition: Specifies that this node is an interrupt + controller + + - #interrupt-cells + Usage: required + Value type: <u32> + Definition: Shall be 2 or 4. A value of 2 means that interrupt + specifiers do not contain the interrupt-type or type-specific + information cells. + + - #address-cells + Usage: required + Value type: <u32> + Definition: Shall be 0. + + - pic-no-reset + Usage: optional + Value type: <empty> + Definition: The presence of this property specifies that the + MPIC must not be reset by the client program, and that + the boot program has initialized all interrupt source + configuration registers to a sane state-- masked or + directed at other cores. This ensures that the client + program will not receive interrupts for sources not belonging + to the client. The presence of this property also mandates + that any initialization related to interrupt sources shall + be limited to sources explicitly referenced in the device tree. + +INTERRUPT SPECIFIER DEFINITION + + Interrupt specifiers consists of 4 cells encoded as + follows: + + <1st-cell> interrupt-number + + Identifies the interrupt source. The meaning + depends on the type of interrupt. + + Note: If the interrupt-type cell is undefined + (i.e. #interrupt-cells = 2), this cell + should be interpreted the same as for + interrupt-type 0-- i.e. an external or + normal SoC device interrupt. + + <2nd-cell> level-sense information, encoded as follows: + 0 = low-to-high edge triggered + 1 = active low level-sensitive + 2 = active high level-sensitive + 3 = high-to-low edge triggered + + <3rd-cell> interrupt-type + + The following types are supported: + + 0 = external or normal SoC device interrupt + + The interrupt-number cell contains + the SoC device interrupt number. The + type-specific cell is undefined. The + interrupt-number is derived from the + MPIC a block of registers referred to as + the "Interrupt Source Configuration Registers". + Each source has 32-bytes of registers + (vector/priority and destination) in this + region. So interrupt 0 is at offset 0x0, + interrupt 1 is at offset 0x20, and so on. + + 1 = error interrupt + + The interrupt-number cell contains + the SoC device interrupt number for + the error interrupt. The type-specific + cell identifies the specific error + interrupt number. + + 2 = MPIC inter-processor interrupt (IPI) + + The interrupt-number cell identifies + the MPIC IPI number. The type-specific + cell is undefined. + + 3 = MPIC timer interrupt + + The interrupt-number cell identifies + the MPIC timer number. The type-specific + cell is undefined. + + <4th-cell> type-specific information + + The type-specific cell is encoded as follows: + + - For interrupt-type 1 (error interrupt), + the type-specific cell contains the + bit number of the error interrupt in the + Error Interrupt Summary Register. + +EXAMPLE 1 + /* + * mpic interrupt controller with 4 cells per specifier + */ + mpic: pic@40000 { + compatible = "fsl,mpic"; + interrupt-controller; + #interrupt-cells = <4>; + #address-cells = <0>; + reg = <0x40000 0x40000>; + }; + +EXAMPLE 2 + /* + * The MPC8544 I2C controller node has an internal + * interrupt number of 27. As per the reference manual + * this corresponds to interrupt source configuration + * registers at 0x5_0560. + * + * The interrupt source configuration registers begin + * at 0x5_0000. + * + * To compute the interrupt specifier interrupt number + * + * 0x560 >> 5 = 43 + * + * The interrupt source configuration registers begin + * at 0x5_0000, and so the i2c vector/priority registers + * are at 0x5_0560. + */ + i2c@3000 { + #address-cells = <1>; + #size-cells = <0>; + cell-index = <0>; + compatible = "fsl-i2c"; + reg = <0x3000 0x100>; + interrupts = <43 2>; + interrupt-parent = <&mpic>; + dfsrr; + }; + + +EXAMPLE 3 + /* + * Definition of a node defining the 4 + * MPIC IPI interrupts. Note the interrupt + * type of 2. + */ + ipi@410a0 { + compatible = "fsl,mpic-ipi"; + reg = <0x40040 0x10>; + interrupts = <0 0 2 0 + 1 0 2 0 + 2 0 2 0 + 3 0 2 0>; + }; + +EXAMPLE 4 + /* + * Definition of a node defining the MPIC + * global timers. Note the interrupt + * type of 3. + */ + timer0: timer@41100 { + compatible = "fsl,mpic-global-timer"; + reg = <0x41100 0x100>; + interrupts = <0 0 3 0 + 1 0 3 0 + 2 0 3 0 + 3 0 3 0>; + }; + +EXAMPLE 5 + /* + * Definition of an error interrupt (interrupt type 1). + * SoC interrupt number is 16 and the specific error + * interrupt bit in the error interrupt summary register + * is 23. + */ + memory-controller@8000 { + compatible = "fsl,p4080-memory-controller"; + reg = <0x8000 0x1000>; + interrupts = <16 2 1 23>; + }; diff --git a/Documentation/powerpc/dts-bindings/fsl/msi-pic.txt b/Documentation/devicetree/bindings/powerpc/fsl/msi-pic.txt index bcc30bac6831..70558c3f3682 100644 --- a/Documentation/powerpc/dts-bindings/fsl/msi-pic.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/msi-pic.txt @@ -5,14 +5,21 @@ Required properties: first is "fsl,CHIP-msi", where CHIP is the processor(mpc8610, mpc8572, etc.) and the second is "fsl,mpic-msi" or "fsl,ipic-msi" depending on the parent type. + - reg : should contain the address and the length of the shared message interrupt register set. + - msi-available-ranges: use <start count> style section to define which msi interrupt can be used in the 256 msi interrupts. This property is optional, without this, all the 256 MSI interrupts can be used. + Each available range must begin and end on a multiple of 32 (i.e. + no splitting an individual MSI register or the associated PIC interrupt). + - interrupts : each one of the interrupts here is one entry per 32 MSIs, and routed to the host interrupt controller. the interrupts should - be set as edge sensitive. + be set as edge sensitive. If msi-available-ranges is present, only + the interrupts that correspond to available ranges shall be present. + - interrupt-parent: the phandle for the interrupt controller that services interrupts for this device. for 83xx cpu, the interrupts are routed to IPIC, and for 85xx/86xx cpu the interrupts are routed diff --git a/Documentation/powerpc/dts-bindings/fsl/pmc.txt b/Documentation/devicetree/bindings/powerpc/fsl/pmc.txt index 07256b7ffcaa..07256b7ffcaa 100644 --- a/Documentation/powerpc/dts-bindings/fsl/pmc.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/pmc.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/sec.txt b/Documentation/devicetree/bindings/powerpc/fsl/sec.txt index 2b6f2d45c45a..2b6f2d45c45a 100644 --- a/Documentation/powerpc/dts-bindings/fsl/sec.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/sec.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/ssi.txt b/Documentation/devicetree/bindings/powerpc/fsl/ssi.txt index 5ff76c9c57d2..5ff76c9c57d2 100644 --- a/Documentation/powerpc/dts-bindings/fsl/ssi.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/ssi.txt diff --git a/Documentation/powerpc/dts-bindings/nintendo/gamecube.txt b/Documentation/devicetree/bindings/powerpc/nintendo/gamecube.txt index b558585b1aaf..b558585b1aaf 100644 --- a/Documentation/powerpc/dts-bindings/nintendo/gamecube.txt +++ b/Documentation/devicetree/bindings/powerpc/nintendo/gamecube.txt diff --git a/Documentation/powerpc/dts-bindings/nintendo/wii.txt b/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt index a7e155a023b8..a7e155a023b8 100644 --- a/Documentation/powerpc/dts-bindings/nintendo/wii.txt +++ b/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt diff --git a/Documentation/devicetree/bindings/rtc/rtc-cmos.txt b/Documentation/devicetree/bindings/rtc/rtc-cmos.txt new file mode 100644 index 000000000000..7382989b3052 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/rtc-cmos.txt @@ -0,0 +1,28 @@ + Motorola mc146818 compatible RTC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Required properties: + - compatible : "motorola,mc146818" + - reg : should contain registers location and length. + +Optional properties: + - interrupts : should contain interrupt. + - interrupt-parent : interrupt source phandle. + - ctrl-reg : Contains the initial value of the control register also + called "Register B". + - freq-reg : Contains the initial value of the frequency register also + called "Regsiter A". + +"Register A" and "B" are usually initialized by the firmware (BIOS for +instance). If this is not done, it can be performed by the driver. + +ISA Example: + + rtc@70 { + compatible = "motorola,mc146818"; + interrupts = <8 3>; + interrupt-parent = <&ioapic1>; + ctrl-reg = <2>; + freq-reg = <0x26>; + reg = <1 0x70 2>; + }; diff --git a/Documentation/devicetree/bindings/serial/altera_jtaguart.txt b/Documentation/devicetree/bindings/serial/altera_jtaguart.txt new file mode 100644 index 000000000000..c152f65f9a28 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/altera_jtaguart.txt @@ -0,0 +1,4 @@ +Altera JTAG UART + +Required properties: +- compatible : should be "ALTR,juart-1.0" diff --git a/Documentation/devicetree/bindings/serial/altera_uart.txt b/Documentation/devicetree/bindings/serial/altera_uart.txt new file mode 100644 index 000000000000..71cae3f70100 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/altera_uart.txt @@ -0,0 +1,7 @@ +Altera UART + +Required properties: +- compatible : should be "ALTR,uart-1.0" + +Optional properties: +- clock-frequency : frequency of the clock input to the UART diff --git a/Documentation/devicetree/bindings/serio/altera_ps2.txt b/Documentation/devicetree/bindings/serio/altera_ps2.txt new file mode 100644 index 000000000000..4d9eecc2ef7d --- /dev/null +++ b/Documentation/devicetree/bindings/serio/altera_ps2.txt @@ -0,0 +1,4 @@ +Altera UP PS/2 controller + +Required properties: +- compatible : should be "ALTR,ps2-1.0". diff --git a/Documentation/powerpc/dts-bindings/fsl/spi.txt b/Documentation/devicetree/bindings/spi/fsl-spi.txt index 80510c018eea..777abd7399d5 100644 --- a/Documentation/powerpc/dts-bindings/fsl/spi.txt +++ b/Documentation/devicetree/bindings/spi/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/spi-bus.txt b/Documentation/devicetree/bindings/spi/spi-bus.txt index e782add2e457..e782add2e457 100644 --- a/Documentation/powerpc/dts-bindings/spi-bus.txt +++ b/Documentation/devicetree/bindings/spi/spi-bus.txt diff --git a/Documentation/devicetree/bindings/spi/spi_altera.txt b/Documentation/devicetree/bindings/spi/spi_altera.txt new file mode 100644 index 000000000000..dda375943506 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi_altera.txt @@ -0,0 +1,4 @@ +Altera SPI + +Required properties: +- compatible : should be "ALTR,spi-1.0". diff --git a/Documentation/devicetree/bindings/spi/spi_oc_tiny.txt b/Documentation/devicetree/bindings/spi/spi_oc_tiny.txt new file mode 100644 index 000000000000..d95c0b367a04 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi_oc_tiny.txt @@ -0,0 +1,12 @@ +OpenCores tiny SPI + +Required properties: +- compatible : should be "opencores,tiny-spi-rtlsvn2". +- gpios : should specify GPIOs used for chipselect. +Optional properties: +- clock-frequency : input clock frequency to the core. +- baud-width: width, in bits, of the programmable divider used to scale + the input clock to SCLK. + +The clock-frequency and baud-width properties are needed only if the divider +is programmable. They are not needed if the divider is fixed. diff --git a/Documentation/powerpc/dts-bindings/fsl/usb.txt b/Documentation/devicetree/bindings/usb/fsl-usb.txt index b00152402694..bd5723f0b67e 100644 --- a/Documentation/powerpc/dts-bindings/fsl/usb.txt +++ b/Documentation/devicetree/bindings/usb/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/dts-bindings/usb-ehci.txt b/Documentation/devicetree/bindings/usb/usb-ehci.txt index fa18612f757b..fa18612f757b 100644 --- a/Documentation/powerpc/dts-bindings/usb-ehci.txt +++ b/Documentation/devicetree/bindings/usb/usb-ehci.txt diff --git a/Documentation/devicetree/bindings/x86/ce4100.txt b/Documentation/devicetree/bindings/x86/ce4100.txt new file mode 100644 index 000000000000..b49ae593a60b --- /dev/null +++ b/Documentation/devicetree/bindings/x86/ce4100.txt @@ -0,0 +1,38 @@ +CE4100 Device Tree Bindings +--------------------------- + +The CE4100 SoC uses for in core peripherals the following compatible +format: <vendor>,<chip>-<device>. +Many of the "generic" devices like HPET or IO APIC have the ce4100 +name in their compatible property because they first appeared in this +SoC. + +The CPU node +------------ + cpu@0 { + device_type = "cpu"; + compatible = "intel,ce4100"; + reg = <0>; + lapic = <&lapic0>; + }; + +The reg property describes the CPU number. The lapic property points to +the local APIC timer. + +The SoC node +------------ + +This node describes the in-core peripherals. Required property: + compatible = "intel,ce4100-cp"; + +The PCI node +------------ +This node describes the PCI bus on the SoC. Its property should be + compatible = "intel,ce4100-pci", "pci"; + +If the OS is using the IO-APIC for interrupt routing then the reported +interrupt numbers for devices is no longer true. In order to obtain the +correct interrupt number, the child node which represents the device has +to contain the interrupt property. Besides the interrupt property it has +to contain at least the reg property containing the PCI bus address and +compatible property according to "PCI Bus Binding Revision 2.1". diff --git a/Documentation/devicetree/bindings/x86/interrupt.txt b/Documentation/devicetree/bindings/x86/interrupt.txt new file mode 100644 index 000000000000..7d19f494f19a --- /dev/null +++ b/Documentation/devicetree/bindings/x86/interrupt.txt @@ -0,0 +1,26 @@ +Interrupt chips +--------------- + +* Intel I/O Advanced Programmable Interrupt Controller (IO APIC) + + Required properties: + -------------------- + compatible = "intel,ce4100-ioapic"; + #interrupt-cells = <2>; + + Device's interrupt property: + + interrupts = <P S>; + + The first number (P) represents the interrupt pin which is wired to the + IO APIC. The second number (S) represents the sense of interrupt which + should be configured and can be one of: + 0 - Edge Rising + 1 - Level Low + 2 - Level High + 3 - Edge Falling + +* Local APIC + Required property: + + compatible = "intel,ce4100-lapic"; diff --git a/Documentation/devicetree/bindings/x86/timer.txt b/Documentation/devicetree/bindings/x86/timer.txt new file mode 100644 index 000000000000..c688af58e3bd --- /dev/null +++ b/Documentation/devicetree/bindings/x86/timer.txt @@ -0,0 +1,6 @@ +Timers +------ + +* High Precision Event Timer (HPET) + Required property: + compatible = "intel,ce4100-hpet"; diff --git a/Documentation/powerpc/dts-bindings/xilinx.txt b/Documentation/devicetree/bindings/xilinx.txt index 299d0923537b..299d0923537b 100644 --- a/Documentation/powerpc/dts-bindings/xilinx.txt +++ b/Documentation/devicetree/bindings/xilinx.txt diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt index 302db5da49b3..50619a0720a8 100644 --- a/Documentation/powerpc/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.txt @@ -13,7 +13,7 @@ Table of Contents I - Introduction 1) Entry point for arch/powerpc - 2) Board support + 2) Entry point for arch/x86 II - The DT block format 1) Header @@ -41,13 +41,6 @@ Table of Contents VI - System-on-a-chip devices and nodes 1) Defining child nodes of an SOC 2) Representing devices without a current OF specification - a) PHY nodes - b) Interrupt controllers - c) 4xx/Axon EMAC ethernet nodes - d) Xilinx IP cores - e) USB EHCI controllers - f) MDIO on GPIOs - g) SPI busses VII - Specifying interrupt information for devices 1) interrupts property @@ -123,7 +116,7 @@ Revision Information I - Introduction ================ -During the recent development of the Linux/ppc64 kernel, and more +During the development of the Linux/ppc64 kernel, and more specifically, the addition of new platform types outside of the old IBM pSeries/iSeries pair, it was decided to enforce some strict rules regarding the kernel entry and bootloader <-> kernel interfaces, in @@ -131,7 +124,7 @@ order to avoid the degeneration that had become the ppc32 kernel entry point and the way a new platform should be added to the kernel. The legacy iSeries platform breaks those rules as it predates this scheme, but no new board support will be accepted in the main tree that -doesn't follows them properly. In addition, since the advent of the +doesn't follow them properly. In addition, since the advent of the arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit platforms and 32-bit platforms which move into arch/powerpc will be required to use these rules as well. @@ -145,8 +138,8 @@ and properties to be present. This will be described in detail in section III, but, for example, the kernel does not require you to create a node for every PCI device in the system. It is a requirement to have a node for PCI host bridges in order to provide interrupt -routing informations and memory/IO ranges, among others. It is also -recommended to define nodes for on chip devices and other busses that +routing information and memory/IO ranges, among others. It is also +recommended to define nodes for on chip devices and other buses that don't specifically fit in an existing OF specification. This creates a great flexibility in the way the kernel can then probe those and match drivers to device, without having to hard code all sorts of tables. It @@ -158,7 +151,7 @@ it with special cases. 1) Entry point for arch/powerpc ------------------------------- - There is one and one single entry point to the kernel, at the start + There is one single entry point to the kernel, at the start of the kernel image. That entry point supports two calling conventions: @@ -210,12 +203,6 @@ it with special cases. with all CPUs. The way to do that with method b) will be described in a later revision of this document. - -2) Board support ----------------- - -64-bit kernels: - Board supports (platforms) are not exclusive config options. An arbitrary set of board supports can be built in a single kernel image. The kernel will "know" what set of functions to use for a @@ -234,48 +221,30 @@ it with special cases. containing the various callbacks that the generic code will use to get to your platform specific code - c) Add a reference to your "ppc_md" structure in the - "machines" table in arch/powerpc/kernel/setup_64.c if you are - a 64-bit platform. - - d) request and get assigned a platform number (see PLATFORM_* - constants in arch/powerpc/include/asm/processor.h - -32-bit embedded kernels: - - Currently, board support is essentially an exclusive config option. - The kernel is configured for a single platform. Part of the reason - for this is to keep kernels on embedded systems small and efficient; - part of this is due to the fact the code is already that way. In the - future, a kernel may support multiple platforms, but only if the + A kernel image may support multiple platforms, but only if the platforms feature the same core architecture. A single kernel build cannot support both configurations with Book E and configurations with classic Powerpc architectures. - 32-bit embedded platforms that are moved into arch/powerpc using a - flattened device tree should adopt the merged tree practice of - setting ppc_md up dynamically, even though the kernel is currently - built with support for only a single platform at a time. This allows - unification of the setup code, and will make it easier to go to a - multiple-platform-support model in the future. - -NOTE: I believe the above will be true once Ben's done with the merge -of the boot sequences.... someone speak up if this is wrong! - - To add a 32-bit embedded platform support, follow the instructions - for 64-bit platforms above, with the exception that the Kconfig - option should be set up such that the kernel builds exclusively for - the platform selected. The processor type for the platform should - enable another config option to select the specific board - supported. - -NOTE: If Ben doesn't merge the setup files, may need to change this to -point to setup_32.c +2) Entry point for arch/x86 +------------------------------- + There is one single 32bit entry point to the kernel at code32_start, + the decompressor (the real mode entry point goes to the same 32bit + entry point once it switched into protected mode). That entry point + supports one calling convention which is documented in + Documentation/x86/boot.txt + The physical pointer to the device-tree block (defined in chapter II) + is passed via setup_data which requires at least boot protocol 2.09. + The type filed is defined as - I will describe later the boot process and various callbacks that - your platform should implement. + #define SETUP_DTB 2 + This device-tree is used as an extension to the "boot page". As such it + does not parse / consider data which is already covered by the boot + page. This includes memory size, reserved ranges, command line arguments + or initrd address. It simply holds information which can not be retrieved + otherwise like interrupt routing or a list of devices behind an I2C bus. II - The DT block format ======================== @@ -300,8 +269,8 @@ the block to RAM before passing it to the kernel. 1) Header --------- - The kernel is entered with r3 pointing to an area of memory that is - roughly described in arch/powerpc/include/asm/prom.h by the structure + The kernel is passed the physical address pointing to an area of memory + that is roughly described in include/linux/of_fdt.h by the structure boot_param_header: struct boot_param_header { @@ -339,7 +308,7 @@ struct boot_param_header { All values in this header are in big endian format, the various fields in this header are defined more precisely below. All "offset" values are in bytes from the start of the header; that is - from the value of r3. + from the physical base address of the device tree block. - magic @@ -416,7 +385,7 @@ struct boot_param_header { among others, by kexec. If you are on an SMP system, this value should match the content of the "reg" property of the CPU node in the device-tree corresponding to the CPU calling the kernel entry - point (see further chapters for more informations on the required + point (see further chapters for more information on the required device-tree contents) - size_dt_strings @@ -437,7 +406,7 @@ struct boot_param_header { ------------------------------ - r3 -> | struct boot_param_header | + base -> | struct boot_param_header | ------------------------------ | (alignment gap) (*) | ------------------------------ @@ -457,7 +426,7 @@ struct boot_param_header { -----> ------------------------------ | | - --- (r3 + totalsize) + --- (base + totalsize) (*) The alignment gaps are not necessarily present; their presence and size are dependent on the various alignment requirements of @@ -500,7 +469,7 @@ the device-tree structure. It is typically used to represent "path" in the device-tree. More details about the actual format of these will be below. -The kernel powerpc generic code does not make any formal use of the +The kernel generic code does not make any formal use of the unit address (though some board support code may do) so the only real requirement here for the unit address is to ensure uniqueness of the node unit name at a given level of the tree. Nodes with no notion @@ -518,20 +487,21 @@ path to the root node is "/". Every node which actually represents an actual device (that is, a node which isn't only a virtual "container" for more nodes, like "/cpus" -is) is also required to have a "device_type" property indicating the -type of node . +is) is also required to have a "compatible" property indicating the +specific hardware and an optional list of devices it is fully +backwards compatible with. Finally, every node that can be referenced from a property in another -node is required to have a "linux,phandle" property. Real open -firmware implementations provide a unique "phandle" value for every -node that the "prom_init()" trampoline code turns into -"linux,phandle" properties. However, this is made optional if the -flattened device tree is used directly. An example of a node +node is required to have either a "phandle" or a "linux,phandle" +property. Real Open Firmware implementations provide a unique +"phandle" value for every node that the "prom_init()" trampoline code +turns into "linux,phandle" properties. However, this is made optional +if the flattened device tree is used directly. An example of a node referencing another node via "phandle" is when laying out the interrupt tree which will be described in a further version of this document. -This "linux, phandle" property is a 32-bit value that uniquely +The "phandle" property is a 32-bit value that uniquely identifies a node. You are free to use whatever values or system of values, internal pointers, or whatever to generate these, the only requirement is that every node for which you provide that property has @@ -583,7 +553,7 @@ looks like in practice. This tree is almost a minimal tree. It pretty much contains the minimal set of required nodes and properties to boot a linux kernel; -that is, some basic model informations at the root, the CPUs, and the +that is, some basic model information at the root, the CPUs, and the physical memory layout. It also includes misc information passed through /chosen, like in this example, the platform type (mandatory) and the kernel command line arguments (optional). @@ -694,7 +664,7 @@ made of 3 cells, the bottom two containing the actual address itself while the top cell contains address space indication, flags, and pci bus & device numbers. -For busses that support dynamic allocation, it's the accepted practice +For buses that support dynamic allocation, it's the accepted practice to then not provide the address in "reg" (keep it 0) though while providing a flag indicating the address is dynamically allocated, and then, to provide a separate "assigned-addresses" property that @@ -711,7 +681,7 @@ prom_parse.c file of the recent kernels for your bus type. The "reg" property only defines addresses and sizes (if #size-cells is non-0) within a given bus. In order to translate addresses upward (that is into parent bus addresses, and possibly into CPU physical -addresses), all busses must contain a "ranges" property. If the +addresses), all buses must contain a "ranges" property. If the "ranges" property is missing at a given level, it's assumed that translation isn't possible, i.e., the registers are not visible on the parent bus. The format of the "ranges" property for a bus is a list @@ -727,9 +697,9 @@ example, for a PCI host controller, that would be a CPU address. For a PCI<->ISA bridge, that would be a PCI address. It defines the base address in the parent bus where the beginning of that range is mapped. -For a new 64-bit powerpc board, I recommend either the 2/2 format or +For new 64-bit board support, I recommend either the 2/2 format or Apple's 2/1 format which is slightly more compact since sizes usually -fit in a single 32-bit word. New 32-bit powerpc boards should use a +fit in a single 32-bit word. New 32-bit board support should use a 1/1 format, unless the processor supports physical addresses greater than 32-bits, in which case a 2/1 format is recommended. @@ -754,7 +724,7 @@ of their actual names. While earlier users of Open Firmware like OldWorld macintoshes tended to use the actual device name for the "name" property, it's nowadays considered a good practice to use a name that is closer to the device -class (often equal to device_type). For example, nowadays, ethernet +class (often equal to device_type). For example, nowadays, Ethernet controllers are named "ethernet", an additional "model" property defining precisely the chip type/model, and "compatible" property defining the family in case a single driver can driver more than one @@ -772,7 +742,7 @@ is present). 4) Note about node and property names and character set ------------------------------------------------------- -While open firmware provides more flexible usage of 8859-1, this +While Open Firmware provides more flexible usage of 8859-1, this specification enforces more strict rules. Nodes and properties should be comprised only of ASCII characters 'a' to 'z', '0' to '9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally @@ -792,7 +762,7 @@ address which can extend beyond that limit. -------------------------------- These are all that are currently required. However, it is strongly recommended that you expose PCI host bridges as documented in the - PCI binding to open firmware, and your interrupt tree as documented + PCI binding to Open Firmware, and your interrupt tree as documented in OF interrupt tree specification. a) The root node @@ -802,20 +772,12 @@ address which can extend beyond that limit. - model : this is your board name/model - #address-cells : address representation for "root" devices - #size-cells: the size representation for "root" devices - - device_type : This property shouldn't be necessary. However, if - you decide to create a device_type for your root node, make sure it - is _not_ "chrp" unless your platform is a pSeries or PAPR compliant - one for 64-bit, or a CHRP-type machine for 32-bit as this will - matched by the kernel this way. - - Additionally, some recommended properties are: - - compatible : the board "family" generally finds its way here, for example, if you have 2 board models with a similar layout, that typically get driven by the same platform code in the - kernel, you would use a different "model" property but put a - value in "compatible". The kernel doesn't directly use that - value but it is generally useful. + kernel, you would specify the exact board model in the + compatible property followed by an entry that represents the SoC + model. The root node is also generally where you add additional properties specific to your board like the serial number if any, that sort of @@ -841,8 +803,11 @@ address which can extend beyond that limit. So under /cpus, you are supposed to create a node for every CPU on the machine. There is no specific restriction on the name of the - CPU, though It's common practice to call it PowerPC,<name>. For + CPU, though it's common to call it <architecture>,<core>. For example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX. + However, the Generic Names convention suggests that it would be + better to simply use 'cpu' for each cpu node and use the compatible + property to identify the specific cpu core. Required properties: @@ -923,7 +888,7 @@ compatibility. e) The /chosen node - This node is a bit "special". Normally, that's where open firmware + This node is a bit "special". Normally, that's where Open Firmware puts some variable environment information, like the arguments, or the default input/output devices. @@ -940,11 +905,7 @@ compatibility. console device if any. Typically, if you have serial devices on your board, you may want to put the full path to the one set as the default console in the firmware here, for the kernel to pick - it up as its own default console. If you look at the function - set_preferred_console() in arch/ppc64/kernel/setup.c, you'll see - that the kernel tries to find out the default console and has - knowledge of various types like 8250 serial ports. You may want - to extend this function to add your own. + it up as its own default console. Note that u-boot creates and fills in the chosen node for platforms that use it. @@ -955,23 +916,23 @@ compatibility. f) the /soc<SOCname> node - This node is used to represent a system-on-a-chip (SOC) and must be - present if the processor is a SOC. The top-level soc node contains - information that is global to all devices on the SOC. The node name - should contain a unit address for the SOC, which is the base address - of the memory-mapped register set for the SOC. The name of an soc + This node is used to represent a system-on-a-chip (SoC) and must be + present if the processor is a SoC. The top-level soc node contains + information that is global to all devices on the SoC. The node name + should contain a unit address for the SoC, which is the base address + of the memory-mapped register set for the SoC. The name of an SoC node should start with "soc", and the remainder of the name should represent the part number for the soc. For example, the MPC8540's soc node would be called "soc8540". Required properties: - - device_type : Should be "soc" - ranges : Should be defined as specified in 1) to describe the - translation of SOC addresses for memory mapped SOC registers. - - bus-frequency: Contains the bus frequency for the SOC node. + translation of SoC addresses for memory mapped SoC registers. + - bus-frequency: Contains the bus frequency for the SoC node. Typically, the value of this field is filled in by the boot loader. + - compatible : Exact model of the SoC Recommended properties: @@ -1025,7 +986,7 @@ dtc source code can be found at WARNING: This version is still in early development stage; the resulting device-tree "blobs" have not yet been validated with the -kernel. The current generated bloc lacks a useful reserve map (it will +kernel. The current generated block lacks a useful reserve map (it will be fixed to generate an empty one, it's up to the bootloader to fill it up) among others. The error handling needs work, bugs are lurking, etc... @@ -1098,7 +1059,7 @@ supported currently at the toplevel. * an arbitrary array of bytes */ - childnode@addresss { /* define a child node named "childnode" + childnode@address { /* define a child node named "childnode" * whose unit name is "childnode at * address" */ @@ -1155,12 +1116,13 @@ while all this has been defined and implemented. - An example of code for iterating nodes & retrieving properties directly from the flattened tree format can be found in the kernel - file arch/ppc64/kernel/prom.c, look at scan_flat_dt() function, + file drivers/of/fdt.c. Look at the of_scan_flat_dt() function, its usage in early_init_devtree(), and the corresponding various early_init_dt_scan_*() callbacks. That code can be re-used in a GPL bootloader, and as the author of that code, I would be happy to discuss possible free licensing to any vendor who wishes to integrate all or part of this code into a non-GPL bootloader. + (reference needed; who is 'I' here? ---gcl Jan 31, 2011) @@ -1203,18 +1165,19 @@ MPC8540. 2) Representing devices without a current OF specification ---------------------------------------------------------- -Currently, there are many devices on SOCs that do not have a standard -representation pre-defined as part of the open firmware -specifications, mainly because the boards that contain these SOCs are -not currently booted using open firmware. This section contains -descriptions for the SOC devices for which new nodes have been -defined; this list will expand as more and more SOC-containing -platforms are moved over to use the flattened-device-tree model. +Currently, there are many devices on SoCs that do not have a standard +representation defined as part of the Open Firmware specifications, +mainly because the boards that contain these SoCs are not currently +booted using Open Firmware. Binding documentation for new devices +should be added to the Documentation/devicetree/bindings directory. +That directory will expand as device tree support is added to more and +more SoCs. + VII - Specifying interrupt information for devices =================================================== -The device tree represents the busses and devices of a hardware +The device tree represents the buses and devices of a hardware system in a form similar to the physical bus topology of the hardware. diff --git a/Documentation/dontdiff b/Documentation/dontdiff index d9bcffd59433..470d3dba1a69 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -62,6 +62,10 @@ aic7*reg_print.c* aic7*seq.h* aicasm aicdb.h* +altivec1.c +altivec2.c +altivec4.c +altivec8.c asm-offsets.h asm_offsets.h autoconf.h* @@ -76,6 +80,7 @@ btfixupprep build bvmlinux bzImage* +capflags.c classlist.h* comp*.log compile.h* @@ -94,6 +99,7 @@ devlist.h* docproc elf2ecoff elfconfig.h* +evergreen_reg_safe.h fixdep flask.h fore200e_mkfirm @@ -108,9 +114,16 @@ genksyms *_gray256.c ihex2fw ikconfig.h* +inat-tables.c initramfs_data.cpio initramfs_data.cpio.gz initramfs_list +int16.c +int1.c +int2.c +int32.c +int4.c +int8.c kallsyms kconfig keywords.c @@ -140,6 +153,7 @@ mkprep mktables mktree modpost +modules.builtin modules.order modversions.h* ncscope.* @@ -153,14 +167,23 @@ pca200e.bin pca200e_ecd.bin2 piggy.gz piggyback +piggy.S pnmtologo ppc_defs.h* pss_boot.h qconf +r100_reg_safe.h +r200_reg_safe.h +r300_reg_safe.h +r420_reg_safe.h +r600_reg_safe.h raid6altivec*.c raid6int*.c raid6tables.c relocs +rn50_reg_safe.h +rs600_reg_safe.h +rv515_reg_safe.h series setup setup.bin @@ -169,6 +192,7 @@ sImage sm_tbl* split-include syscalltab.h +tables.c tags tftpboot.img timeconst.h @@ -190,6 +214,7 @@ vmlinux vmlinux-* vmlinux.aout vmlinux.lds +voffset.h vsyscall.lds vsyscall_32.lds wanxlfw.inc @@ -200,3 +225,4 @@ wakeup.elf wakeup.lds zImage* zconf.hash.c +zoffset.h diff --git a/Documentation/driver-model/interface.txt b/Documentation/driver-model/interface.txt deleted file mode 100644 index c66912bfe866..000000000000 --- a/Documentation/driver-model/interface.txt +++ /dev/null @@ -1,129 +0,0 @@ - -Device Interfaces - -Introduction -~~~~~~~~~~~~ - -Device interfaces are the logical interfaces of device classes that correlate -directly to userspace interfaces, like device nodes. - -Each device class may have multiple interfaces through which you can -access the same device. An input device may support the mouse interface, -the 'evdev' interface, and the touchscreen interface. A SCSI disk would -support the disk interface, the SCSI generic interface, and possibly a raw -device interface. - -Device interfaces are registered with the class they belong to. As devices -are added to the class, they are added to each interface registered with -the class. The interface is responsible for determining whether the device -supports the interface or not. - - -Programming Interface -~~~~~~~~~~~~~~~~~~~~~ - -struct device_interface { - char * name; - rwlock_t lock; - u32 devnum; - struct device_class * devclass; - - struct list_head node; - struct driver_dir_entry dir; - - int (*add_device)(struct device *); - int (*add_device)(struct intf_data *); -}; - -int interface_register(struct device_interface *); -void interface_unregister(struct device_interface *); - - -An interface must specify the device class it belongs to. It is added -to that class's list of interfaces on registration. - - -Interfaces can be added to a device class at any time. Whenever it is -added, each device in the class is passed to the interface's -add_device callback. When an interface is removed, each device is -removed from the interface. - - -Devices -~~~~~~~ -Once a device is added to a device class, it is added to each -interface that is registered with the device class. The class -is expected to place a class-specific data structure in -struct device::class_data. The interface can use that (along with -other fields of struct device) to determine whether or not the driver -and/or device support that particular interface. - - -Data -~~~~ - -struct intf_data { - struct list_head node; - struct device_interface * intf; - struct device * dev; - u32 intf_num; -}; - -int interface_add_data(struct interface_data *); - -The interface is responsible for allocating and initializing a struct -intf_data and calling interface_add_data() to add it to the device's list -of interfaces it belongs to. This list will be iterated over when the device -is removed from the class (instead of all possible interfaces for a class). -This structure should probably be embedded in whatever per-device data -structure the interface is allocating anyway. - -Devices are enumerated within the interface. This happens in interface_add_data() -and the enumerated value is stored in the struct intf_data for that device. - -sysfs -~~~~~ -Each interface is given a directory in the directory of the device -class it belongs to: - -Interfaces get a directory in the class's directory as well: - - class/ - `-- input - |-- devices - |-- drivers - |-- mouse - `-- evdev - -When a device is added to the interface, a symlink is created that points -to the device's directory in the physical hierarchy: - - class/ - `-- input - |-- devices - | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ - |-- drivers - | `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/ - |-- mouse - | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ - `-- evdev - `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ - - -Future Plans -~~~~~~~~~~~~ -A device interface is correlated directly with a userspace interface -for a device, specifically a device node. For instance, a SCSI disk -exposes at least two interfaces to userspace: the standard SCSI disk -interface and the SCSI generic interface. It might also export a raw -device interface. - -Many interfaces have a major number associated with them and each -device gets a minor number. Or, multiple interfaces might share one -major number, and each will receive a range of minor numbers (like in -the case of input devices). - -These major and minor numbers could be stored in the interface -structure. Major and minor allocations could happen when the interface -is registered with the class, or via a helper function. - diff --git a/Documentation/dvb/README.dvb-usb b/Documentation/dvb/README.dvb-usb index c8238e44ed6b..c4d963a67d6f 100644 --- a/Documentation/dvb/README.dvb-usb +++ b/Documentation/dvb/README.dvb-usb @@ -138,7 +138,7 @@ Hotplug is able to load the driver, when it is needed (because you plugged in the device). If you want to enable debug output, you have to load the driver manually and -from withing the dvb-kernel cvs repository. +from within the dvb-kernel cvs repository. first have a look, which debug level are available: diff --git a/Documentation/dvb/ci.txt b/Documentation/dvb/ci.txt index 4a0c2b56e690..6c3bda50f7dc 100644 --- a/Documentation/dvb/ci.txt +++ b/Documentation/dvb/ci.txt @@ -47,7 +47,7 @@ so on. * CI modules that are supported ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The CI module support is largely dependant upon the firmware on the cards +The CI module support is largely dependent upon the firmware on the cards Some cards do support almost all of the available CI modules. There is nothing much that can be done in order to make additional CI modules working with these cards. diff --git a/Documentation/dvb/faq.txt b/Documentation/dvb/faq.txt index 121832e5d899..97b1373f2428 100644 --- a/Documentation/dvb/faq.txt +++ b/Documentation/dvb/faq.txt @@ -106,7 +106,7 @@ Some very frequently asked questions about linuxtv-dvb 5. The dvb_net device doesn't give me any packets at all Run tcpdump on the dvb0_0 interface. This sets the interface - into promiscous mode so it accepts any packets from the PID + into promiscuous mode so it accepts any packets from the PID you have configured with the dvbnet utility. Check if there are any packets with the IP addr and MAC addr you have configured with ifconfig. diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware index 350959f4e41b..3348d313fbe0 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", "az6027"); + "af9015", "ngene", "az6027", "lme2510_lg", "lme2510c_s7395", + "lme2510c_s7395_old"); # Check args syntax() if (scalar(@ARGV) != 1); @@ -555,6 +556,9 @@ sub ngene { my $hash1 = "d798d5a757121174f0dbc5f2833c0c85"; my $file2 = "ngene_17.fw"; my $hash2 = "26b687136e127b8ac24b81e0eeafc20b"; + my $url2 = "http://l4m-daten.de/downloads/firmware/dvb-s2/linux/all/"; + my $file3 = "ngene_18.fw"; + my $hash3 = "ebce3ea769a53e3e0b0197c3b3f127e3"; checkstandard(); @@ -564,7 +568,10 @@ sub ngene { wgetfile($file2, $url . $file2); verify($file2, $hash2); - "$file1, $file2"; + wgetfile($file3, $url2 . $file3); + verify($file3, $hash3); + + "$file1, $file2, $file3"; } sub az6027{ @@ -584,6 +591,49 @@ sub az6027{ $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 000000000000..10b5f0411386 --- /dev/null +++ b/Documentation/dvb/lmedm04.txt @@ -0,0 +1,70 @@ +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/drivers + +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/drivers + +dd if=US280D.sys ibs=1 skip=42360 count=3924 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 + +--------------------------------------------------------------------- + +The Sharp 0194 tuner driver can be found in windows/system32/drivers + +US290D.sys (dated 09 Apr 2009) + +For LME2510 +dd if=US290D.sys ibs=1 skip=36856 count=3976 of=dvb-usb-lme2510-s0194.fw + + +For LME2510C +dd if=US290D.sys ibs=1 skip=33152 count=3697 of=dvb-usb-lme2510c-s0194.fw + + +Copy the firmware file(s) to /lib/firmware diff --git a/Documentation/dvb/udev.txt b/Documentation/dvb/udev.txt index 68ee224b6aae..412305b7c557 100644 --- a/Documentation/dvb/udev.txt +++ b/Documentation/dvb/udev.txt @@ -1,7 +1,7 @@ The DVB subsystem currently registers to the sysfs subsystem using the "class_simple" interface. -This means that only the basic informations like module loading parameters +This means that only the basic information like module loading parameters are presented through sysfs. Other things that might be interesting are currently *not* available. diff --git a/Documentation/dynamic-debug-howto.txt b/Documentation/dynamic-debug-howto.txt index 674c5663d346..f959909d7154 100644 --- a/Documentation/dynamic-debug-howto.txt +++ b/Documentation/dynamic-debug-howto.txt @@ -6,7 +6,7 @@ This document describes how to use the dynamic debug (ddebug) feature. Dynamic debug is designed to allow you to dynamically enable/disable kernel code to obtain additional kernel information. Currently, if -CONFIG_DYNAMIC_DEBUG is set, then all pr_debug()/dev_debug() calls can be +CONFIG_DYNAMIC_DEBUG is set, then all pr_debug()/dev_dbg() calls can be dynamically enabled per-callsite. Dynamic debug has even more useful features: @@ -24,9 +24,9 @@ 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 +The behaviour of pr_debug()/dev_dbg()s are controlled via writing to a control file in the 'debugfs' filesystem. Thus, you must first mount the debugfs filesystem, in order to make use of this feature. Subsequently, we refer to the control file as: <debugfs>/dynamic_debug/control. For example, if you want to @@ -205,12 +205,40 @@ of the characters: The flags are: +f + Include the function name in the printed message +l + Include line number in the printed message +m + Include module name in the printed message p Causes a printk() message to be emitted to dmesg +t + Include thread ID in messages not generated from interrupt context -Note the regexp ^[-+=][scp]+$ matches a flags specification. +Note the regexp ^[-+=][flmpt]+$ matches a flags specification. Note also that there is no convenient syntax to remove all -the flags at once, you need to use "-psc". +the flags at once, you need to use "-flmpt". + + +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/edac.txt b/Documentation/edac.txt index 0b875e8da969..249822cde82b 100644 --- a/Documentation/edac.txt +++ b/Documentation/edac.txt @@ -196,7 +196,7 @@ csrow3. The representation of the above is reflected in the directory tree in EDAC's sysfs interface. Starting in directory /sys/devices/system/edac/mc each memory controller will be represented -by its own 'mcX' directory, where 'X" is the index of the MC. +by its own 'mcX' directory, where 'X' is the index of the MC. ..../edac/mc/ @@ -207,7 +207,7 @@ by its own 'mcX' directory, where 'X" is the index of the MC. .... Under each 'mcX' directory each 'csrowX' is again represented by a -'csrowX', where 'X" is the csrow index: +'csrowX', where 'X' is the csrow index: .../mc/mc0/ @@ -232,7 +232,7 @@ EDAC control and attribute files. In 'mcX' directories are EDAC control and attribute files for -this 'X" instance of the memory controllers: +this 'X' instance of the memory controllers: Counter reset control file: @@ -311,7 +311,7 @@ Total Correctable Errors count attribute file: 'ce_noinfo_count' This attribute file displays the number of CEs that - have occurred wherewith no informations as to which DIMM slot + have occurred wherewith no information as to which DIMM slot is having errors. Memory is handicapped, but operational, yet no information is available to indicate which slot the failing memory is in. This count field should be also @@ -343,7 +343,7 @@ Sdram memory scrubbing rate: 'csrowX' DIRECTORIES In the 'csrowX' directories are EDAC control and attribute files for -this 'X" instance of csrow: +this 'X' instance of csrow: Total Uncorrectable Errors count attribute file: @@ -741,7 +741,7 @@ were done at i7core_edac driver. This chapter will cover those differences As EDAC API maps the minimum unity is csrows, the driver sequencially maps channel/dimm into different csrows. - For example, suposing the following layout: + For example, supposing the following layout: Ch0 phy rd0, wr0 (0x063f4031): 2 ranks, UDIMMs dimm 0 1024 Mb offset: 0, bank: 8, rank: 1, row: 0x4000, col: 0x400 dimm 1 1024 Mb offset: 4, bank: 8, rank: 1, row: 0x4000, col: 0x400 diff --git a/Documentation/eisa.txt b/Documentation/eisa.txt index f297fc1202ae..38cf0c7b559f 100644 --- a/Documentation/eisa.txt +++ b/Documentation/eisa.txt @@ -84,7 +84,7 @@ struct eisa_driver { id_table : an array of NULL terminated EISA id strings, followed by an empty string. Each string can - optionally be paired with a driver-dependant value + optionally be paired with a driver-dependent value (driver_data). driver : a generic driver, such as described in diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt index 945ff3fda433..a0b58e29f911 100644 --- a/Documentation/email-clients.txt +++ b/Documentation/email-clients.txt @@ -104,6 +104,13 @@ Then from the "Message" menu item, select insert file and choose your patch. As an added bonus you can customise the message creation toolbar menu and put the "insert file" icon there. +Make the the composer window wide enough so that no lines wrap. As of +KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending +the email if the lines wrap in the composer window. Having word wrapping +disabled in the Options menu isn't enough. Thus, if your patch has very +long lines, you must make the composer window very wide before sending +the email. See: https://bugs.kde.org/show_bug.cgi?id=174034 + You can safely GPG sign attachments, but inlined text is preferred for patches so do not GPG sign them. Signing patches that have been inserted as inlined text will make them tricky to extract from their 7-bit encoding. @@ -179,26 +186,8 @@ Sylpheed (GUI) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Thunderbird (GUI) -By default, thunderbird likes to mangle text, but there are ways to -coerce it into being nice. - -- Under account settings, composition and addressing, uncheck "Compose - messages in HTML format". - -- Edit your Thunderbird config settings to tell it not to wrap lines: - user_pref("mailnews.wraplength", 0); - -- Edit your Thunderbird config settings so that it won't use format=flowed: - user_pref("mailnews.send_plaintext_flowed", false); - -- You need to get Thunderbird into preformat mode: -. If you compose HTML messages by default, it's not too hard. Just select - "Preformat" from the drop-down box just under the subject line. -. If you compose in text by default, you have to tell it to compose a new - message in HTML (just as a one-off), and then force it from there back to - text, else it will wrap lines. To do this, use shift-click on the Write - icon to compose to get HTML compose mode, then select "Preformat" from - the drop-down box just under the subject line. +Thunderbird is an Outlook clone that likes to mangle text, but there are ways +to coerce it into behaving. - Allows use of an external editor: The easiest thing to do with Thunderbird and patches is to use an @@ -208,6 +197,27 @@ coerce it into being nice. View->Toolbars->Customize... and finally just click on it when in the Compose dialog. +To beat some sense out of the internal editor, do this: + +- Under account settings, composition and addressing, uncheck "Compose + messages in HTML format". + +- Edit your Thunderbird config settings so that it won't use format=flowed. + Go to "edit->preferences->advanced->config editor" to bring up the + thunderbird's registry editor, and set "mailnews.send_plaintext_flowed" to + "false". + +- Enable "preformat" mode: Shft-click on the Write icon to bring up the HTML + composer, select "Preformat" from the drop-down box just under the subject + line, then close the message without saving. (This setting also applies to + the text composer, but the only control for it is in the HTML composer.) + +- Install the "toggle wordwrap" extension. Download the file from: + https://addons.mozilla.org/thunderbird/addon/2351/ + Then go to "tools->add ons", select "install" at the bottom of the screen, + and browse to where you saved the .xul file. This adds an "Enable + Wordwrap" entry under the Options menu of the message composer. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ TkRat (GUI) diff --git a/Documentation/fb/00-INDEX b/Documentation/fb/00-INDEX index a618fd99c9f0..30a70542e823 100644 --- a/Documentation/fb/00-INDEX +++ b/Documentation/fb/00-INDEX @@ -4,33 +4,41 @@ please mail me. Geert Uytterhoeven <geert@linux-m68k.org> 00-INDEX - - this file + - this file. arkfb.txt - info on the fbdev driver for ARK Logic chips. aty128fb.txt - info on the ATI Rage128 frame buffer driver. cirrusfb.txt - info on the driver for Cirrus Logic chipsets. +cmap_xfbdev.txt + - an introduction to fbdev's cmap structures. deferred_io.txt - an introduction to deferred IO. +efifb.txt + - info on the EFI platform driver for Intel based Apple computers. +ep93xx-fb.txt + - info on the driver for EP93xx LCD controller. fbcon.txt - intro to and usage guide for the framebuffer console (fbcon). framebuffer.txt - introduction to frame buffer devices. -imacfb.txt - - info on the generic EFI platform driver for Intel based Macs. +gxfb.txt + - info on the framebuffer driver for AMD Geode GX2 based processors. intel810.txt - documentation for the Intel 810/815 framebuffer driver. intelfb.txt - docs for Intel 830M/845G/852GM/855GM/865G/915G/945G fb driver. internals.txt - quick overview of frame buffer device internals. +lxfb.txt + - info on the framebuffer driver for AMD Geode LX based processors. matroxfb.txt - info on the Matrox framebuffer driver for Alpha, Intel and PPC. +metronomefb.txt + - info on the driver for the Metronome display controller. modedb.txt - info on the video mode database. -matroxfb.txt - - info on the Matrox frame buffer driver. pvr2fb.txt - info on the PowerVR 2 frame buffer driver. pxafb.txt @@ -39,13 +47,23 @@ s3fb.txt - info on the fbdev driver for S3 Trio/Virge chips. sa1100fb.txt - information about the driver for the SA-1100 LCD controller. +sh7760fb.txt + - info on the SH7760/SH7763 integrated LCDC Framebuffer driver. sisfb.txt - info on the framebuffer device driver for various SiS chips. sstfb.txt - info on the frame buffer driver for 3dfx' Voodoo Graphics boards. tgafb.txt - - info on the TGA (DECChip 21030) frame buffer driver + - info on the TGA (DECChip 21030) frame buffer driver. +tridentfb.txt + info on the framebuffer driver for some Trident chip based cards. +uvesafb.txt + - info on the userspace VESA (VBE2+ compliant) frame buffer device. vesafb.txt - - info on the VESA frame buffer device + - info on the VESA frame buffer device. +viafb.modes + - list of modes for VIA Integration Graphic Chip. +viafb.txt + - info on the VIA Integration Graphic Chip console framebuffer driver. vt8623fb.txt - info on the fb driver for the graphics core in VIA VT8623 chipsets. diff --git a/Documentation/fb/sm501.txt b/Documentation/fb/sm501.txt new file mode 100644 index 000000000000..8d17aebd2648 --- /dev/null +++ b/Documentation/fb/sm501.txt @@ -0,0 +1,10 @@ +Configuration: + +You can pass the following kernel command line options to sm501 videoframebuffer: + + sm501fb.bpp= SM501 Display driver: + Specifiy bits-per-pixel if not specified by 'mode' + + sm501fb.mode= SM501 Display driver: + Specify resolution as + "<xres>x<yres>[-<bpp>][@<refresh>]" diff --git a/Documentation/fb/udlfb.txt b/Documentation/fb/udlfb.txt new file mode 100644 index 000000000000..7fdde2a02a27 --- /dev/null +++ b/Documentation/fb/udlfb.txt @@ -0,0 +1,144 @@ + +What is udlfb? +=============== + +This is a driver for DisplayLink USB 2.0 era graphics chips. + +DisplayLink chips provide simple hline/blit operations with some compression, +pairing that with a hardware framebuffer (16MB) on the other end of the +USB wire. That hardware framebuffer is able to drive the VGA, DVI, or HDMI +monitor with no CPU involvement until a pixel has to change. + +The CPU or other local resource does all the rendering; optinally compares the +result with a local shadow of the remote hardware framebuffer to identify +the minimal set of pixels that have changed; and compresses and sends those +pixels line-by-line via USB bulk transfers. + +Because of the efficiency of bulk transfers and a protocol on top that +does not require any acks - the effect is very low latency that +can support surprisingly high resolutions with good performance for +non-gaming and non-video applications. + +Mode setting, EDID read, etc are other bulk or control transfers. Mode +setting is very flexible - able to set nearly arbitrary modes from any timing. + +Advantages of USB graphics in general: + + * Ability to add a nearly arbitrary number of displays to any USB 2.0 + capable system. On Linux, number of displays is limited by fbdev interface + (FB_MAX is currently 32). Of course, all USB devices on the same + host controller share the same 480Mbs USB 2.0 interface. + +Advantages of supporting DisplayLink chips with kernel framebuffer interface: + + * The actual hardware functionality of DisplayLink chips matches nearly + one-to-one with the fbdev interface, making the driver quite small and + tight relative to the functionality it provides. + * X servers and other applications can use the standard fbdev interface + from user mode to talk to the device, without needing to know anything + about USB or DisplayLink's protocol at all. A "displaylink" X driver + and a slightly modified "fbdev" X driver are among those that already do. + +Disadvantages: + + * Fbdev's mmap interface assumes a real hardware framebuffer is mapped. + In the case of USB graphics, it is just an allocated (virtual) buffer. + Writes need to be detected and encoded into USB bulk transfers by the CPU. + Accurate damage/changed area notifications work around this problem. + In the future, hopefully fbdev will be enhanced with an small standard + interface to allow mmap clients to report damage, for the benefit + of virtual or remote framebuffers. + * Fbdev does not arbitrate client ownership of the framebuffer well. + * Fbcon assumes the first framebuffer it finds should be consumed for console. + * It's not clear what the future of fbdev is, given the rise of KMS/DRM. + +How to use it? +============== + +Udlfb, when loaded as a module, will match against all USB 2.0 generation +DisplayLink chips (Alex and Ollie family). It will then attempt to read the EDID +of the monitor, and set the best common mode between the DisplayLink device +and the monitor's capabilities. + +If the DisplayLink device is successful, it will paint a "green screen" which +means that from a hardware and fbdev software perspective, everything is good. + +At that point, a /dev/fb? interface will be present for user-mode applications +to open and begin writing to the framebuffer of the DisplayLink device using +standard fbdev calls. Note that if mmap() is used, by default the user mode +application must send down damage notifcations to trigger repaints of the +changed regions. Alternatively, udlfb can be recompiled with experimental +defio support enabled, to support a page-fault based detection mechanism +that can work without explicit notifcation. + +The most common client of udlfb is xf86-video-displaylink or a modified +xf86-video-fbdev X server. These servers have no real DisplayLink specific +code. They write to the standard framebuffer interface and rely on udlfb +to do its thing. The one extra feature they have is the ability to report +rectangles from the X DAMAGE protocol extension down to udlfb via udlfb's +damage interface (which will hopefully be standardized for all virtual +framebuffers that need damage info). These damage notifications allow +udlfb to efficiently process the changed pixels. + +Module Options +============== + +Special configuration for udlfb is usually unnecessary. There are a few +options, however. + +From the command line, pass options to modprobe +modprobe udlfb defio=1 console=1 + +Or for permanent option, create file like /etc/modprobe.d/options with text +options udlfb defio=1 console=1 + +Accepted options: + +fb_defio Make use of the fb_defio (CONFIG_FB_DEFERRED_IO) kernel + module to track changed areas of the framebuffer by page faults. + Standard fbdev applications that use mmap but that do not + report damage, may be able to work with this enabled. + Disabled by default because of overhead and other issues. + +console Allow fbcon to attach to udlfb provided framebuffers. This + is disabled by default because fbcon will aggressively consume + the first framebuffer it finds, which isn't usually what the + user wants in the case of USB displays. + +Sysfs Attributes +================ + +Udlfb creates several files in /sys/class/graphics/fb? +Where ? is the sequential framebuffer id of the particular DisplayLink device + +edid If a valid EDID blob is written to this file (typically + by a udev rule), then udlfb will use this EDID as a + backup in case reading the actual EDID of the monitor + attached to the DisplayLink device fails. This is + especially useful for fixed panels, etc. that cannot + communicate their capabilities via EDID. Reading + this file returns the current EDID of the attached + monitor (or last backup value written). This is + useful to get the EDID of the attached monitor, + which can be passed to utilities like parse-edid. + +metrics_bytes_rendered 32-bit count of pixel bytes rendered + +metrics_bytes_identical 32-bit count of how many of those bytes were found to be + unchanged, based on a shadow framebuffer check + +metrics_bytes_sent 32-bit count of how many bytes were transferred over + USB to communicate the resulting changed pixels to the + hardware. Includes compression and protocol overhead + +metrics_cpu_kcycles_used 32-bit count of CPU cycles used in processing the + above pixels (in thousands of cycles). + +metrics_reset Write-only. Any write to this file resets all metrics + above to zero. Note that the 32-bit counters above + roll over very quickly. To get reliable results, design + performance tests to start and finish in a very short + period of time (one minute or less is safe). + +-- +Bernie Thompson <bernie@plugable.com> diff --git a/Documentation/fb/viafb.txt b/Documentation/fb/viafb.txt index f3e046a6a987..444e34b52ae1 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 ',' separated 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 ',' separated 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 842aa9de84a6..b2317b293391 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -4,7 +4,7 @@ exactly is going away, why it is happening, and who is going to be doing the work. When the feature is removed from the kernel, it should also be removed from this file. ---------------------------- +---------------------------- What: PRISM54 When: 2.6.34 @@ -97,25 +97,6 @@ Who: Pavel Machek <pavel@ucw.cz> --------------------------- -What: Video4Linux API 1 ioctls and from Video devices. -When: July 2009 -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 - series. The old API have lots of drawbacks and don't provide enough - means to work with all video and audio standards. The newer API is - already available on the main drivers and should be used instead. - Newer drivers should use v4l_compat_translate_ioctl function to handle - old calls, replacing to newer ones. - Decoder iocts are using internally to allow video drivers to - communicate with video decoders. This should also be improved to allow - V4L2 calls being translated into compatible internal ioctls. - Compatibility ioctls will be provided, for a while, via - v4l1-compat module. -Who: Mauro Carvalho Chehab <mchehab@infradead.org> - ---------------------------- - What: sys_sysctl When: September 2010 Option: CONFIG_SYSCTL_SYSCALL @@ -176,6 +157,20 @@ Why: /proc/<pid>/oom_adj allows userspace to influence the oom killer's --------------------------- +What: CS5535/CS5536 obsolete GPIO driver +When: June 2011 +Files: drivers/staging/cs5535_gpio/* +Check: drivers/staging/cs5535_gpio/cs5535_gpio.c +Why: A newer driver replaces this; it is drivers/gpio/cs5535-gpio.c, and + integrates with the Linux GPIO subsystem. The old driver has been + moved to staging, and will be removed altogether around 2.6.40. + Please test the new driver, and ensure that the functionality you + need and any bugfixes from the old driver are available in the new + one. +Who: Andres Salomon <dilinger@queued.net> + +-------------------------- + What: remove EXPORT_SYMBOL(kernel_thread) When: August 2006 Files: arch/*/kernel/*_ksyms.c @@ -217,11 +212,14 @@ Who: Zhang Rui <rui.zhang@intel.com> --------------------------- -What: /proc/acpi/button -When: August 2007 -Why: /proc/acpi/button has been replaced by events to the input layer - since 2.6.20. -Who: Len Brown <len.brown@intel.com> +What: CONFIG_ACPI_PROCFS_POWER +When: 2.6.39 +Why: sysfs I/F for ACPI power devices, including AC and Battery, + has been working in upstream kenrel since 2.6.24, Sep 2007. + In 2.6.37, we make the sysfs I/F always built in and this option + disabled by default. + Remove this option and the ACPI power procfs interface in 2.6.39. +Who: Zhang Rui <rui.zhang@intel.com> --------------------------- @@ -315,14 +313,6 @@ Who: Dave Jones <davej@redhat.com>, Matthew Garrett <mjg@redhat.com> ----------------------------- -What: __do_IRQ all in one fits nothing interrupt handler -When: 2.6.32 -Why: __do_IRQ was kept for easy migration to the type flow handlers. - More than two years of migration time is enough. -Who: Thomas Gleixner <tglx@linutronix.de> - ------------------------------ - What: fakephp and associated sysfs files in /sys/bus/pci/slots/ When: 2011 Why: In 2.6.27, the semantics of /sys/bus/pci/slots was redefined to @@ -386,54 +376,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 - only features that really need multiple path to guess what's - the right method name on a specific laptop. - - Removing them will allow to remove a lot of code an significantly - clean the drivers. - - This will affect the backlight code which won't be able to know - if the backlight is on or off. The platform display file will also be - write only (like the one in eeepc-laptop). - - This should'nt affect a lot of user because they usually know - when their display is on or off. - -Who: Corentin Chary <corentin.chary@gmail.com> - ----------------------------- - What: sysfs-class-rfkill state file When: Feb 2014 Files: net/rfkill/core.c @@ -452,16 +394,6 @@ Who: anybody or Florian Mickler <florian@mickler.org> ---------------------------- -What: capifs -When: February 2011 -Files: drivers/isdn/capi/capifs.* -Why: udev fully replaces this special file system that only contains CAPI - NCCI TTY device nodes. User space (pppdcapiplugin) works without - noticing the difference. -Who: Jan Kiszka <jan.kiszka@web.de> - ----------------------------- - What: KVM paravirt mmu host support When: January 2011 Why: The paravirt mmu host support is slower than non-paravirt mmu, both @@ -498,29 +430,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 @@ -530,16 +439,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 @@ -564,3 +463,99 @@ 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> + +---------------------------- + +What: cancel_rearming_delayed_work[queue]() +When: 2.6.39 + +Why: The functions have been superceded by cancel_delayed_work_sync() + quite some time ago. The conversion is trivial and there is no + in-kernel user left. +Who: Tejun Heo <tj@kernel.org> + +---------------------------- + +What: Legacy, non-standard chassis intrusion detection interface. +When: June 2011 +Why: The adm9240, w83792d and w83793 hardware monitoring drivers have + legacy interfaces for chassis intrusion detection. A standard + interface has been added to each driver, so the legacy interface + can be removed. +Who: Jean Delvare <khali@linux-fr.org> + +---------------------------- + +What: xt_connlimit rev 0 +When: 2012 +Who: Jan Engelhardt <jengelh@medozas.de> +Files: net/netfilter/xt_connlimit.c + +---------------------------- + +What: noswapaccount kernel command line parameter +When: 2.6.40 +Why: The original implementation of memsw feature enabled by + CONFIG_CGROUP_MEM_RES_CTLR_SWAP could be disabled by the noswapaccount + kernel parameter (introduced in 2.6.29-rc1). Later on, this decision + turned out to be not ideal because we cannot have the feature compiled + in and disabled by default and let only interested to enable it + (e.g. general distribution kernels might need it). Therefore we have + added swapaccount[=0|1] parameter (introduced in 2.6.37) which provides + the both possibilities. If we remove noswapaccount we will have + less command line parameters with the same functionality and we + can also cleanup the parameter handling a bit (). +Who: Michal Hocko <mhocko@suse.cz> + +---------------------------- + +What: ipt_addrtype match include file +When: 2012 +Why: superseded by xt_addrtype +Who: Florian Westphal <fw@strlen.de> +Files: include/linux/netfilter_ipv4/ipt_addrtype.h + +---------------------------- + +What: i2c_driver.attach_adapter + i2c_driver.detach_adapter +When: September 2011 +Why: These legacy callbacks should no longer be used as i2c-core offers + a variety of preferable alternative ways to instantiate I2C devices. +Who: Jean Delvare <khali@linux-fr.org> + +---------------------------- diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX index 4303614b5add..8c624a18f67d 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 f9765e8cf086..b22abba78fed 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 diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index 2db4283efa8d..61b31acb9176 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -9,24 +9,30 @@ be able to use diff(1). --------------------------- dentry_operations -------------------------- prototypes: - int (*d_revalidate)(struct dentry *, int); - int (*d_hash) (struct dentry *, struct qstr *); - int (*d_compare) (struct dentry *, struct qstr *, struct qstr *); + int (*d_revalidate)(struct dentry *, struct nameidata *); + int (*d_hash)(const struct dentry *, const struct inode *, + struct qstr *); + int (*d_compare)(const struct dentry *, const struct inode *, + const struct dentry *, const struct inode *, + unsigned int, const char *, const struct qstr *); int (*d_delete)(struct dentry *); void (*d_release)(struct dentry *); void (*d_iput)(struct dentry *, struct inode *); char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen); + struct vfsmount *(*d_automount)(struct path *path); + int (*d_manage)(struct dentry *, bool); locking rules: - none have BKL - dcache_lock rename_lock ->d_lock may block -d_revalidate: no no no yes -d_hash no no no yes -d_compare: no yes no no -d_delete: yes no yes no -d_release: no no no yes -d_iput: no no no yes + rename_lock ->d_lock may block rcu-walk +d_revalidate: no no yes (ref-walk) maybe +d_hash no no no maybe +d_compare: yes no no maybe +d_delete: no yes no no +d_release: no no yes no +d_iput: no no yes no d_dname: no no no no +d_automount: no no yes no +d_manage: no no yes (ref-walk) maybe --------------------------- inode_operations --------------------------- prototypes: @@ -42,18 +48,22 @@ ata *); int (*rename) (struct inode *, struct dentry *, struct inode *, struct dentry *); int (*readlink) (struct dentry *, char __user *,int); - int (*follow_link) (struct dentry *, struct nameidata *); + void * (*follow_link) (struct dentry *, struct nameidata *); + void (*put_link) (struct dentry *, struct nameidata *, void *); void (*truncate) (struct inode *); - int (*permission) (struct inode *, int, struct nameidata *); + int (*permission) (struct inode *, int, unsigned int); + int (*check_acl)(struct inode *, int, unsigned int); int (*setattr) (struct dentry *, struct iattr *); int (*getattr) (struct vfsmount *, struct dentry *, struct kstat *); int (*setxattr) (struct dentry *, const char *,const void *,size_t,int); ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t); ssize_t (*listxattr) (struct dentry *, char *, size_t); int (*removexattr) (struct dentry *, const char *); + void (*truncate_range)(struct inode *, loff_t, loff_t); + int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len); locking rules: - all may block, none have BKL + all may block i_mutex(inode) lookup: yes create: yes @@ -66,19 +76,23 @@ rmdir: yes (both) (see below) rename: yes (all) (see below) readlink: no follow_link: no +put_link: no truncate: yes (see below) setattr: yes -permission: no +permission: no (may not block if called in rcu-walk mode) +check_acl: no getattr: no setxattr: yes getxattr: no listxattr: no removexattr: yes +truncate_range: yes +fiemap: no Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_mutex on victim. cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem. ->truncate() is never called directly - it's a callback, not a -method. It's called by vmtruncate() - library function normally used by +method. It's called by vmtruncate() - deprecated library function used by ->setattr(). Locking information above applies to that call (i.e. is inherited from ->setattr() - vmtruncate() is used when ATTR_SIZE had been passed). @@ -91,7 +105,7 @@ prototypes: struct inode *(*alloc_inode)(struct super_block *sb); void (*destroy_inode)(struct inode *); void (*dirty_inode) (struct inode *); - int (*write_inode) (struct inode *, int); + int (*write_inode) (struct inode *, struct writeback_control *wbc); int (*drop_inode) (struct inode *); void (*evict_inode) (struct inode *); void (*put_super) (struct super_block *); @@ -105,16 +119,16 @@ prototypes: 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); + int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t); locking rules: All may block [not true, see below] - None have BKL s_umount alloc_inode: destroy_inode: dirty_inode: (must not sleep) write_inode: -drop_inode: !!!inode_lock!!! +drop_inode: !!!inode->i_lock!!! evict_inode: put_super: write write_super: read @@ -127,6 +141,7 @@ umount_begin: no show_options: no (namespace_sem) quota_read: no (see below) quota_write: no (see below) +bdev_try_to_free_page: no (see below) ->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 @@ -139,19 +154,23 @@ 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 writes to quota files with quotas on). For other details about locking see also dquot_operations section. +->bdev_try_to_free_page is called from the ->releasepage handler of +the block device inode. See there for more details. --------------------------- file_system_type --------------------------- prototypes: int (*get_sb) (struct file_system_type *, int, const char *, void *, struct vfsmount *); + struct dentry *(*mount) (struct file_system_type *, int, + const char *, void *); void (*kill_sb) (struct super_block *); locking rules: - may block BKL -get_sb yes no -kill_sb yes no + may block +mount yes +kill_sb yes -->get_sb() returns error or 0 with locked superblock attached to the vfsmount -(exclusive on ->s_umount). +->mount() returns ERR_PTR or the root dentry; its superblock should be locked +on return. ->kill_sb() takes a write-locked superblock, does all shutdown work on it, unlocks and drops the reference. @@ -173,28 +192,38 @@ prototypes: sector_t (*bmap)(struct address_space *, sector_t); int (*invalidatepage) (struct page *, unsigned long); int (*releasepage) (struct page *, int); + void (*freepage)(struct page *); int (*direct_IO)(int, struct kiocb *, const struct iovec *iov, loff_t offset, unsigned long nr_segs); - int (*launder_page) (struct page *); + int (*get_xip_mem)(struct address_space *, pgoff_t, int, void **, + unsigned long *); + int (*migratepage)(struct address_space *, struct page *, struct page *); + int (*launder_page)(struct page *); + int (*is_partially_uptodate)(struct page *, read_descriptor_t *, unsigned long); + int (*error_remove_page)(struct address_space *, struct page *); locking rules: - All except set_page_dirty may block - - BKL PageLocked(page) i_mutex -writepage: no yes, unlocks (see below) -readpage: no yes, unlocks -sync_page: no maybe -writepages: no -set_page_dirty no no -readpages: no -write_begin: no locks the page yes -write_end: no yes, unlocks yes -perform_write: no n/a yes -bmap: no -invalidatepage: no yes -releasepage: no yes -direct_IO: no -launder_page: no yes + All except set_page_dirty and freepage may block + + PageLocked(page) i_mutex +writepage: yes, unlocks (see below) +readpage: yes, unlocks +sync_page: maybe +writepages: +set_page_dirty no +readpages: +write_begin: locks the page yes +write_end: yes, unlocks yes +bmap: +invalidatepage: yes +releasepage: yes +freepage: yes +direct_IO: +get_xip_mem: maybe +migratepage: yes (both) +launder_page: yes +is_partially_uptodate: yes +error_remove_page: yes ->write_begin(), ->write_end(), ->sync_page() and ->readpage() may be called from the request handler (/dev/loop). @@ -274,9 +303,8 @@ under spinlock (it cannot block) and is sometimes called with the page not locked. ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some -filesystems and by the swapper. The latter will eventually go away. All -instances do not actually need the BKL. Please, keep it that way and don't -breed new callers. +filesystems and by the swapper. The latter will eventually go away. Please, +keep it that way and don't breed new callers. ->invalidatepage() is called when the filesystem must attempt to drop some or all of the buffers from the page when it is being truncated. It @@ -288,55 +316,44 @@ buffers from the page in preparation for freeing it. It returns zero to indicate that the buffers are (or may be) freeable. If ->releasepage is zero, the kernel assumes that the fs has no private interest in the buffers. + ->freepage() is called when the kernel is done dropping the page +from the page cache. + ->launder_page() may be called prior to releasing a page if it is still found to be dirty. It returns zero if the page was successfully cleaned, or an error value if not. Note that in order to prevent the page getting mapped back in and redirtied, it needs to be kept locked across the entire operation. - Note: currently almost all instances of address_space methods are -using BKL for internal serialization and that's one of the worst sources -of contention. Normally they are calling library functions (in fs/buffer.c) -and pass foo_get_block() as a callback (on local block-based filesystems, -indeed). BKL is not needed for library stuff and is usually taken by -foo_get_block(). It's an overkill, since block bitmaps can be protected by -internal fs locking and real critical areas are much smaller than the areas -filesystems protect now. - ----------------------- file_lock_operations ------------------------------ prototypes: - void (*fl_insert)(struct file_lock *); /* lock insertion callback */ - void (*fl_remove)(struct file_lock *); /* lock removal callback */ void (*fl_copy_lock)(struct file_lock *, struct file_lock *); void (*fl_release_private)(struct file_lock *); locking rules: - BKL may block -fl_insert: yes no -fl_remove: yes no -fl_copy_lock: yes no -fl_release_private: yes yes + file_lock_lock may block +fl_copy_lock: yes no +fl_release_private: maybe no ----------------------- lock_manager_operations --------------------------- 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 *); + int (*fl_grant)(struct file_lock *, struct file_lock *, int); void (*fl_release_private)(struct file_lock *); void (*fl_break)(struct file_lock *); /* break_lease callback */ + int (*fl_change)(struct file_lock **, int); 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 - - Currently only NFSD and NLM provide instances of this class. None of the -them block. If you have out-of-tree instances - please, show up. Locking -in that area will change. + file_lock_lock may block +fl_compare_owner: yes no +fl_notify: yes no +fl_grant: no no +fl_release_private: maybe no +fl_break: yes no +fl_change yes no + --------------------------- buffer_head ----------------------------------- prototypes: void (*b_end_io)(struct buffer_head *bh, int uptodate); @@ -349,21 +366,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 -media_changed: no no -revalidate_disk: no no + bd_mutex +open: yes +release: yes +ioctl: no +compat_ioctl: no +direct_access: no +media_changed: no +unlock_native_capacity: no +revalidate_disk: no +getgeo: no +swap_slot_free_notify: 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: @@ -395,34 +427,22 @@ prototypes: unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long); int (*check_flags)(int); + int (*flock) (struct file *, int, struct file_lock *); + ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, + size_t, unsigned int); + ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, + size_t, unsigned int); + int (*setlease)(struct file *, long, struct file_lock **); + long (*fallocate)(struct file *, int, loff_t, loff_t); }; locking rules: - All may block. - BKL -llseek: no (see below) -read: no -aio_read: no -write: no -aio_write: no -readdir: no -poll: no -unlocked_ioctl: no -compat_ioctl: no -mmap: no -open: no -flush: no -release: no -fsync: no (see below) -aio_fsync: no -fasync: no -lock: yes -readv: no -writev: no -sendfile: no -sendpage: no -get_unmapped_area: no -check_flags: no + All may block except for ->setlease. + No VFS locks held on entry except for ->fsync and ->setlease. + +->fsync() has i_mutex on inode. + +->setlease has the file_list_lock held and must not sleep. ->llseek() locking has moved from llseek to the individual llseek implementations. If your fs is not using generic_file_llseek, you @@ -432,17 +452,10 @@ mutex or just to use i_size_read() instead. Note: this does not protect the file->f_pos against concurrent modifications since this is something the userspace has to take care about. -Note: ext2_release() was *the* source of contention on fs-intensive -loads and dropping BKL on ->release() helps to get rid of that (we still -grab BKL for cases when we close a file that had been opened r/w, but that -can and should be done using the internal locking with smaller critical areas). -Current worst offender is ext2_get_block()... - -->fasync() is called without BKL protection, and is responsible for -maintaining the FASYNC bit in filp->f_flags. Most instances call -fasync_helper(), which does that maintenance, so it's not normally -something one needs to worry about. Return values > 0 will be mapped to -zero in the VFS layer. +->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags. +Most instances call fasync_helper(), which does that maintenance, so it's +not normally something one needs to worry about. Return values > 0 will be +mapped to zero in the VFS layer. ->readdir() and ->ioctl() on directories must be changed. Ideally we would move ->readdir() to inode_operations and use a separate method for directory @@ -453,8 +466,6 @@ components. And there are other reasons why the current interface is a mess... ->read on directories probably must go away - we should just enforce -EISDIR in sys_read() and friends. -->fsync() has i_mutex on inode. - --------------------------- dquot_operations ------------------------------- prototypes: int (*write_dquot) (struct dquot *); @@ -489,12 +500,12 @@ prototypes: int (*access)(struct vm_area_struct *, unsigned long, void*, int, int); locking rules: - BKL mmap_sem PageLocked(page) -open: no yes -close: no yes -fault: no yes can return with page locked -page_mkwrite: no yes can return with page locked -access: no yes + mmap_sem PageLocked(page) +open: yes +close: yes +fault: yes can return with page locked +page_mkwrite: yes can return with page locked +access: yes ->fault() is called when a previously not present pte is about to be faulted in. The filesystem must find and return the page associated @@ -521,6 +532,3 @@ VM_IO | VM_PFNMAP VMAs. (if you break something or notice that it is broken and do not fix it yourself - at least put it here) - -ipc/shm.c::shm_delete() - may need BKL. -->read() and ->write() in many drivers are (probably) missing BKL. diff --git a/Documentation/filesystems/adfs.txt b/Documentation/filesystems/adfs.txt index 9e8811f92b84..5949766353f7 100644 --- a/Documentation/filesystems/adfs.txt +++ b/Documentation/filesystems/adfs.txt @@ -9,6 +9,9 @@ Mount options for ADFS will be nnn. Default 0700. othmask=nnn The permission mask for ADFS 'other' permissions will be nnn. Default 0077. + ftsuffix=n When ftsuffix=0, no file type suffix will be applied. + When ftsuffix=1, a hexadecimal suffix corresponding to + the RISC OS file type will be added. Default 0. Mapping of ADFS permissions to Linux permissions ------------------------------------------------ @@ -55,3 +58,18 @@ Mapping of ADFS permissions to Linux permissions You can therefore tailor the permission translation to whatever you desire the permissions should be under Linux. + +RISC OS file type suffix +------------------------ + + RISC OS file types are stored in bits 19..8 of the file load address. + + To enable non-RISC OS systems to be used to store files without losing + file type information, a file naming convention was devised (initially + for use with NFS) such that a hexadecimal suffix of the form ,xyz + denoted the file type: e.g. BasicFile,ffb is a BASIC (0xffb) file. This + naming convention is now also used by RISC OS emulators such as RPCEmu. + + Mounting an ADFS disc with option ftsuffix=1 will cause appropriate file + type suffixes to be appended to file names read from a directory. If the + ftsuffix option is zero or omitted, no file type suffixes will be added. diff --git a/Documentation/filesystems/autofs4-mount-control.txt b/Documentation/filesystems/autofs4-mount-control.txt index 51986bf08a4d..4c95935cbcf4 100644 --- a/Documentation/filesystems/autofs4-mount-control.txt +++ b/Documentation/filesystems/autofs4-mount-control.txt @@ -309,7 +309,7 @@ ioctlfd field set to the descriptor obtained from the open call. AUTOFS_DEV_IOCTL_TIMEOUT_CMD ---------------------------- -Set the expire timeout for mounts withing an autofs mount point. +Set the expire timeout for mounts within an autofs mount point. The call requires an initialized struct autofs_dev_ioctl with the ioctlfd field set to the descriptor obtained from the open call. diff --git a/Documentation/filesystems/caching/netfs-api.txt b/Documentation/filesystems/caching/netfs-api.txt index 1902c57b72ef..a167ab876c35 100644 --- a/Documentation/filesystems/caching/netfs-api.txt +++ b/Documentation/filesystems/caching/netfs-api.txt @@ -95,7 +95,7 @@ restraints as possible on how an index is structured and where it is placed in the tree. The netfs can even mix indices and data files at the same level, but it's not recommended. -Each index entry consists of a key of indeterminate length plus some auxilliary +Each index entry consists of a key of indeterminate length plus some auxiliary data, also of indeterminate length. There are some limits on indices: @@ -203,23 +203,23 @@ This has the following fields: If the function is absent, a file size of 0 is assumed. - (6) A function to retrieve auxilliary data from the netfs [optional]. + (6) A function to retrieve auxiliary data from the netfs [optional]. This function will be called with the netfs data that was passed to the - cookie acquisition function and the maximum length of auxilliary data that - it may provide. It should write the auxilliary data into the given buffer + cookie acquisition function and the maximum length of auxiliary data that + it may provide. It should write the auxiliary data into the given buffer and return the quantity it wrote. - If this function is absent, the auxilliary data length will be set to 0. + If this function is absent, the auxiliary data length will be set to 0. - The length of the auxilliary data buffer may be dependent on the key + The length of the auxiliary data buffer may be dependent on the key length. A netfs mustn't rely on being able to provide more than 400 bytes for both. - (7) A function to check the auxilliary data [optional]. + (7) A function to check the auxiliary data [optional]. This function will be called to check that a match found in the cache for - this object is valid. For instance with AFS it could check the auxilliary + this object is valid. For instance with AFS it could check the auxiliary data against the data version number returned by the server to determine whether the index entry in a cache is still valid. @@ -232,7 +232,7 @@ This has the following fields: (*) FSCACHE_CHECKAUX_NEEDS_UPDATE - the entry requires update (*) FSCACHE_CHECKAUX_OBSOLETE - the entry should be deleted - This function can also be used to extract data from the auxilliary data in + This function can also be used to extract data from the auxiliary data in the cache and copy it into the netfs's structures. (8) A pair of functions to manage contexts for the completion callback diff --git a/Documentation/filesystems/configfs/configfs.txt b/Documentation/filesystems/configfs/configfs.txt index fabcb0e00f25..dd57bb6bb390 100644 --- a/Documentation/filesystems/configfs/configfs.txt +++ b/Documentation/filesystems/configfs/configfs.txt @@ -409,7 +409,7 @@ As a consequence of this, default_groups cannot be removed directly via rmdir(2). They also are not considered when rmdir(2) on the parent group is checking for children. -[Dependant Subsystems] +[Dependent Subsystems] Sometimes other drivers depend on particular configfs items. For example, ocfs2 mounts depend on a heartbeat region item. If that diff --git a/Documentation/filesystems/configfs/configfs_example_explicit.c b/Documentation/filesystems/configfs/configfs_example_explicit.c index d428cc9f07f3..fd53869f5633 100644 --- a/Documentation/filesystems/configfs/configfs_example_explicit.c +++ b/Documentation/filesystems/configfs/configfs_example_explicit.c @@ -89,7 +89,7 @@ static ssize_t childless_storeme_write(struct childless *childless, char *p = (char *) page; tmp = simple_strtoul(p, &p, 10); - if (!p || (*p && (*p != '\n'))) + if ((*p != '\0') && (*p != '\n')) return -EINVAL; if (tmp > INT_MAX) diff --git a/Documentation/filesystems/dentry-locking.txt b/Documentation/filesystems/dentry-locking.txt deleted file mode 100644 index 79334ed5daa7..000000000000 --- a/Documentation/filesystems/dentry-locking.txt +++ /dev/null @@ -1,174 +0,0 @@ -RCU-based dcache locking model -============================== - -On many workloads, the most common operation on dcache is to look up a -dentry, given a parent dentry and the name of the child. Typically, -for every open(), stat() etc., the dentry corresponding to the -pathname will be looked up by walking the tree starting with the first -component of the pathname and using that dentry along with the next -component to look up the next level and so on. Since it is a frequent -operation for workloads like multiuser environments and web servers, -it is important to optimize this path. - -Prior to 2.5.10, dcache_lock was acquired in d_lookup and thus in -every component during path look-up. Since 2.5.10 onwards, fast-walk -algorithm changed this by holding the dcache_lock at the beginning and -walking as many cached path component dentries as possible. This -significantly decreases the number of acquisition of -dcache_lock. However it also increases the lock hold time -significantly and affects performance in large SMP machines. Since -2.5.62 kernel, dcache has been using a new locking model that uses RCU -to make dcache look-up lock-free. - -The current dcache locking model is not very different from the -existing dcache locking model. Prior to 2.5.62 kernel, dcache_lock -protected the hash chain, d_child, d_alias, d_lru lists as well as -d_inode and several other things like mount look-up. RCU-based changes -affect only the way the hash chain is protected. For everything else -the dcache_lock must be taken for both traversing as well as -updating. The hash chain updates too take the dcache_lock. The -significant change is the way d_lookup traverses the hash chain, it -doesn't acquire the dcache_lock for this and rely on RCU to ensure -that the dentry has not been *freed*. - - -Dcache locking details -====================== - -For many multi-user workloads, open() and stat() on files are very -frequently occurring operations. Both involve walking of path names to -find the dentry corresponding to the concerned file. In 2.4 kernel, -dcache_lock was held during look-up of each path component. Contention -and cache-line bouncing of this global lock caused significant -scalability problems. With the introduction of RCU in Linux kernel, -this was worked around by making the look-up of path components during -path walking lock-free. - - -Safe lock-free look-up of dcache hash table -=========================================== - -Dcache is a complex data structure with the hash table entries also -linked together in other lists. In 2.4 kernel, dcache_lock protected -all the lists. We applied RCU only on hash chain walking. The rest of -the lists are still protected by dcache_lock. Some of the important -changes are : - -1. The deletion from hash chain is done using hlist_del_rcu() macro - which doesn't initialize next pointer of the deleted dentry and - this allows us to walk safely lock-free while a deletion is - happening. - -2. Insertion of a dentry into the hash table is done using - hlist_add_head_rcu() which take care of ordering the writes - the - writes to the dentry must be visible before the dentry is - inserted. This works in conjunction with hlist_for_each_rcu(), - which has since been replaced by hlist_for_each_entry_rcu(), while - walking the hash chain. The only requirement is that all - initialization to the dentry must be done before - hlist_add_head_rcu() since we don't have dcache_lock protection - while traversing the hash chain. This isn't different from the - existing code. - -3. The dentry looked up without holding dcache_lock by cannot be - returned for walking if it is unhashed. It then may have a NULL - d_inode or other bogosity since RCU doesn't protect the other - fields in the dentry. We therefore use a flag DCACHE_UNHASHED to - indicate unhashed dentries and use this in conjunction with a - per-dentry lock (d_lock). Once looked up without the dcache_lock, - we acquire the per-dentry lock (d_lock) and check if the dentry is - unhashed. If so, the look-up is failed. If not, the reference count - of the dentry is increased and the dentry is returned. - -4. Once a dentry is looked up, it must be ensured during the path walk - for that component it doesn't go away. In pre-2.5.10 code, this was - done holding a reference to the dentry. dcache_rcu does the same. - In some sense, dcache_rcu path walking looks like the pre-2.5.10 - version. - -5. All dentry hash chain updates must take the dcache_lock as well as - the per-dentry lock in that order. dput() does this to ensure that - a dentry that has just been looked up in another CPU doesn't get - deleted before dget() can be done on it. - -6. There are several ways to do reference counting of RCU protected - objects. One such example is in ipv4 route cache where deferred - freeing (using call_rcu()) is done as soon as the reference count - goes to zero. This cannot be done in the case of dentries because - tearing down of dentries require blocking (dentry_iput()) which - isn't supported from RCU callbacks. Instead, tearing down of - dentries happen synchronously in dput(), but actual freeing happens - later when RCU grace period is over. This allows safe lock-free - walking of the hash chains, but a matched dentry may have been - partially torn down. The checking of DCACHE_UNHASHED flag with - d_lock held detects such dentries and prevents them from being - returned from look-up. - - -Maintaining POSIX rename semantics -================================== - -Since look-up of dentries is lock-free, it can race against a -concurrent rename operation. For example, during rename of file A to -B, look-up of either A or B must succeed. So, if look-up of B happens -after A has been removed from the hash chain but not added to the new -hash chain, it may fail. Also, a comparison while the name is being -written concurrently by a rename may result in false positive matches -violating rename semantics. Issues related to race with rename are -handled as described below : - -1. Look-up can be done in two ways - d_lookup() which is safe from - simultaneous renames and __d_lookup() which is not. If - __d_lookup() fails, it must be followed up by a d_lookup() to - correctly determine whether a dentry is in the hash table or - not. d_lookup() protects look-ups using a sequence lock - (rename_lock). - -2. The name associated with a dentry (d_name) may be changed if a - rename is allowed to happen simultaneously. To avoid memcmp() in - __d_lookup() go out of bounds due to a rename and false positive - comparison, the name comparison is done while holding the - per-dentry lock. This prevents concurrent renames during this - operation. - -3. Hash table walking during look-up may move to a different bucket as - the current dentry is moved to a different bucket due to rename. - But we use hlists in dcache hash table and they are - null-terminated. So, even if a dentry moves to a different bucket, - hash chain walk will terminate. [with a list_head list, it may not - since termination is when the list_head in the original bucket is - reached]. Since we redo the d_parent check and compare name while - holding d_lock, lock-free look-up will not race against d_move(). - -4. There can be a theoretical race when a dentry keeps coming back to - original bucket due to double moves. Due to this look-up may - consider that it has never moved and can end up in a infinite loop. - But this is not any worse that theoretical livelocks we already - have in the kernel. - - -Important guidelines for filesystem developers related to dcache_rcu -==================================================================== - -1. Existing dcache interfaces (pre-2.5.62) exported to filesystem - don't change. Only dcache internal implementation changes. However - filesystems *must not* delete from the dentry hash chains directly - using the list macros like allowed earlier. They must use dcache - APIs like d_drop() or __d_drop() depending on the situation. - -2. d_flags is now protected by a per-dentry lock (d_lock). All access - to d_flags must be protected by it. - -3. For a hashed dentry, checking of d_count needs to be protected by - d_lock. - - -Papers and other documentation on dcache locking -================================================ - -1. Scaling dcache with RCU (http://linuxjournal.com/article.php?sid=7124). - -2. http://lse.sourceforge.net/locking/dcache/dcache.html - - - diff --git a/Documentation/filesystems/exofs.txt b/Documentation/filesystems/exofs.txt index abd2a9b5b787..23583a136975 100644 --- a/Documentation/filesystems/exofs.txt +++ b/Documentation/filesystems/exofs.txt @@ -104,7 +104,15 @@ Where: exofs specific options: Options are separated by commas (,) pid=<integer> - The partition number to mount/create as container of the filesystem. - This option is mandatory. + This option is mandatory. integer can be + Hex by pre-pending an 0x to the number. + osdname=<id> - Mount by a device's osdname. + osdname is usually a 36 character uuid of the + form "d2683732-c906-4ee1-9dbd-c10c27bb40df". + It is one of the device's uuid specified in the + mkfs.exofs format command. + If this option is specified then the /dev/osdX + above can be empty and is ignored. to=<integer> - Timeout in ticks for a single command. default is (60 * HZ) [for debugging only] diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt index e1def1786e50..c79ec58fd7f6 100644 --- a/Documentation/filesystems/ext4.txt +++ b/Documentation/filesystems/ext4.txt @@ -97,7 +97,7 @@ Note: More extensive information for getting started with ext4 can be * Inode allocation using large virtual block groups via flex_bg * delayed allocation * large block (up to pagesize) support -* efficent new ordered mode in JBD2 and ext4(avoid using buffer head to force +* efficient new ordered mode in JBD2 and ext4(avoid using buffer head to force the ordering) [1] Filesystems with a block size of 1k may see a limit imposed by the @@ -106,7 +106,7 @@ directory hash tree having a maximum depth of two. 2.2 Candidate features for future inclusion * Online defrag (patches available but not well tested) -* reduced mke2fs time via lazy itable initialization in conjuction with +* reduced mke2fs time via lazy itable initialization in conjunction with the uninit_bg feature (capability to do this is available in e2fsprogs but a kernel thread to do lazy zeroing of unused inode table blocks after filesystem is first mounted is required for safety) @@ -353,12 +353,61 @@ noauto_da_alloc replacing existing files via patterns such as system crashes before the delayed allocation blocks are forced to disk. -discard Controls whether ext4 should issue discard/TRIM +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 and sparse/thinly-provisioned LUNs, but it is off by default until sufficient testing has been done. +nouid32 Disables 32-bit UIDs and GIDs. This is for + interoperability with older kernels which only + store and expect 16-bit values. + +resize Allows to resize filesystem to the end of the last + existing block group, further resize has to be done + with resize2fs either online, or offline. It can be + used only with conjunction with remount. + +block_validity This options allows to enables/disables the in-kernel +noblock_validity facility for tracking filesystem metadata blocks + within internal data structures. This allows multi- + block allocator and other routines to quickly locate + extents which might overlap with filesystem metadata + blocks. This option is intended for debugging + purposes and since it negatively affects the + performance, it is off by default. + +dioread_lock Controls whether or not ext4 should use the DIO read +dioread_nolock locking. If the dioread_nolock option is specified + ext4 will allocate uninitialized extent before buffer + write and convert the extent to initialized after IO + completes. This approach allows ext4 code to avoid + using inode mutex, which improves scalability on high + speed storages. However this does not work with nobh + option and the mount will fail. Nor does it work with + data journaling and dioread_nolock option will be + ignored with kernel warning. Note that dioread_nolock + code path is only used for extent-based files. + Because of the restrictions this options comprises + it is off by default (e.g. dioread_lock). + +i_version Enable 64-bit inode version support. This option is + off by default. + Data Mode ========= There are 3 different data modes: @@ -386,6 +435,176 @@ needs to be read from and written to disk at the same time where it outperforms all others modes. Currently ext4 does not have delayed allocation support if this data journalling mode is selected. +/proc entries +============= + +Information about mounted ext4 file systems can be found in +/proc/fs/ext4. Each mounted filesystem will have a directory in +/proc/fs/ext4 based on its device name (i.e., /proc/fs/ext4/hdc or +/proc/fs/ext4/dm-0). The files in each per-device directory are shown +in table below. + +Files in /proc/fs/ext4/<devname> +.............................................................................. + File Content + mb_groups details of multiblock allocator buddy cache of free blocks +.............................................................................. + +/sys entries +============ + +Information about mounted ext4 file systems can be found in +/sys/fs/ext4. Each mounted filesystem will have a directory in +/sys/fs/ext4 based on its device name (i.e., /sys/fs/ext4/hdc or +/sys/fs/ext4/dm-0). The files in each per-device directory are shown +in table below. + +Files in /sys/fs/ext4/<devname> +(see also Documentation/ABI/testing/sysfs-fs-ext4) +.............................................................................. + File Content + + delayed_allocation_blocks This file is read-only and shows the number of + blocks that are dirty in the page cache, but + which do not have their location in the + filesystem allocated yet. + + inode_goal Tuning parameter which (if non-zero) controls + the goal inode used by the inode allocator in + preference to all other allocation heuristics. + This is intended for debugging use only, and + should be 0 on production systems. + + inode_readahead_blks Tuning parameter which controls the maximum + number of inode table blocks that ext4's inode + table readahead algorithm will pre-read into + the buffer cache + + lifetime_write_kbytes This file is read-only and shows the number of + kilobytes of data that have been written to this + filesystem since it was created. + + max_writeback_mb_bump The maximum number of megabytes the writeback + code will try to write out before move on to + another inode. + + mb_group_prealloc The multiblock allocator will round up allocation + requests to a multiple of this tuning parameter if + the stripe size is not set in the ext4 superblock + + mb_max_to_scan The maximum number of extents the multiblock + allocator will search to find the best extent + + mb_min_to_scan The minimum number of extents the multiblock + allocator will search to find the best extent + + mb_order2_req Tuning parameter which controls the minimum size + for requests (as a power of 2) where the buddy + cache is used + + mb_stats Controls whether the multiblock allocator should + collect statistics, which are shown during the + unmount. 1 means to collect statistics, 0 means + not to collect statistics + + mb_stream_req Files which have fewer blocks than this tunable + parameter will have their blocks allocated out + of a block group specific preallocation pool, so + that small files are packed closely together. + Each large file will have its blocks allocated + out of its own unique preallocation pool. + + session_write_kbytes This file is read-only and shows the number of + kilobytes of data that have been written to this + filesystem since it was mounted. +.............................................................................. + +Ioctls +====== + +There is some Ext4 specific functionality which can be accessed by applications +through the system call interfaces. The list of all Ext4 specific ioctls are +shown in the table below. + +Table of Ext4 specific ioctls +.............................................................................. + Ioctl Description + EXT4_IOC_GETFLAGS Get additional attributes associated with inode. + The ioctl argument is an integer bitfield, with + bit values described in ext4.h. This ioctl is an + alias for FS_IOC_GETFLAGS. + + EXT4_IOC_SETFLAGS Set additional attributes associated with inode. + The ioctl argument is an integer bitfield, with + bit values described in ext4.h. This ioctl is an + alias for FS_IOC_SETFLAGS. + + EXT4_IOC_GETVERSION + EXT4_IOC_GETVERSION_OLD + Get the inode i_generation number stored for + each inode. The i_generation number is normally + changed only when new inode is created and it is + particularly useful for network filesystems. The + '_OLD' version of this ioctl is an alias for + FS_IOC_GETVERSION. + + EXT4_IOC_SETVERSION + EXT4_IOC_SETVERSION_OLD + Set the inode i_generation number stored for + each inode. The '_OLD' version of this ioctl + is an alias for FS_IOC_SETVERSION. + + EXT4_IOC_GROUP_EXTEND This ioctl has the same purpose as the resize + mount option. It allows to resize filesystem + to the end of the last existing block group, + further resize has to be done with resize2fs, + either online, or offline. The argument points + to the unsigned logn number representing the + filesystem new block count. + + EXT4_IOC_MOVE_EXT Move the block extents from orig_fd (the one + this ioctl is pointing to) to the donor_fd (the + one specified in move_extent structure passed + as an argument to this ioctl). Then, exchange + inode metadata between orig_fd and donor_fd. + This is especially useful for online + defragmentation, because the allocator has the + opportunity to allocate moved blocks better, + ideally into one contiguous extent. + + EXT4_IOC_GROUP_ADD Add a new group descriptor to an existing or + new group descriptor block. The new group + descriptor is described by ext4_new_group_input + structure, which is passed as an argument to + this ioctl. This is especially useful in + conjunction with EXT4_IOC_GROUP_EXTEND, + which allows online resize of the filesystem + to the end of the last existing block group. + Those two ioctls combined is used in userspace + online resize tool (e.g. resize2fs). + + EXT4_IOC_MIGRATE This ioctl operates on the filesystem itself. + It converts (migrates) ext3 indirect block mapped + inode to ext4 extent mapped inode by walking + through indirect block mapping of the original + inode and converting contiguous block ranges + into ext4 extents of the temporary inode. Then, + inodes are swapped. This ioctl might help, when + migrating from ext3 to ext4 filesystem, however + suggestion is to create fresh ext4 filesystem + and copy data from the backup. Note, that + filesystem has to support extents for this ioctl + to work. + + EXT4_IOC_ALLOC_DA_BLKS Force all of the delay allocated blocks to be + allocated to preserve application-expected ext3 + behaviour. Note that this will also start + triggering a write of the data blocks, but this + behaviour may change in the future as it is + not necessary and has been done this way only + for sake of simplicity. +.............................................................................. + References ========== diff --git a/Documentation/filesystems/gfs2-uevents.txt b/Documentation/filesystems/gfs2-uevents.txt index fd966dc9979a..d81889669293 100644 --- a/Documentation/filesystems/gfs2-uevents.txt +++ b/Documentation/filesystems/gfs2-uevents.txt @@ -62,7 +62,7 @@ be fixed. The REMOVE uevent is generated at the end of an unsuccessful mount or at the end of a umount of the filesystem. All REMOVE uevents will -have been preceeded by at least an ADD uevent for the same fileystem, +have been preceded by at least an ADD uevent for the same fileystem, and unlike the other uevents is generated automatically by the kernel's kobject subsystem. diff --git a/Documentation/filesystems/gfs2.txt b/Documentation/filesystems/gfs2.txt index 0b59c0200912..4cda926628aa 100644 --- a/Documentation/filesystems/gfs2.txt +++ b/Documentation/filesystems/gfs2.txt @@ -11,7 +11,7 @@ their I/O so file system consistency is maintained. One of the nifty features of GFS is perfect consistency -- changes made to the file system on one machine show up immediately on all other machines in the cluster. -GFS uses interchangable inter-node locking mechanisms, the currently +GFS uses interchangeable inter-node locking mechanisms, the currently supported mechanisms are: lock_nolock -- allows gfs to be used as a local file system diff --git a/Documentation/filesystems/nfs/00-INDEX b/Documentation/filesystems/nfs/00-INDEX index 2f68cd688769..a57e12411d2a 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 000000000000..b9b4192ea8b5 --- /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 f2430a7974e1..90c71c6f0d00 100644 --- a/Documentation/filesystems/nfs/nfsroot.txt +++ b/Documentation/filesystems/nfs/nfsroot.txt @@ -159,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 000000000000..983e14abe7e9 --- /dev/null +++ b/Documentation/filesystems/nfs/pnfs.txt @@ -0,0 +1,55 @@ +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. + +lseg +---- +lseg maintains an extra reference corresponding to the NFS_LSEG_VALID +bit which holds it in the pnfs_layout_hdr's list. When the final lseg +is removed from the pnfs_layout_hdr's list, the NFS_LAYOUT_DESTROYED +bit is set, preventing any new lsegs from being added. diff --git a/Documentation/filesystems/ntfs.txt b/Documentation/filesystems/ntfs.txt index ac2a261c5f7d..791af8dac065 100644 --- a/Documentation/filesystems/ntfs.txt +++ b/Documentation/filesystems/ntfs.txt @@ -350,7 +350,7 @@ Note the "Should sync?" parameter "nosync" means that the two mirrors are already in sync which will be the case on a clean shutdown of Windows. If the mirrors are not clean, you can specify the "sync" option instead of "nosync" and the Device-Mapper driver will then copy the entirety of the "Source Device" -to the "Target Device" or if you specified multipled target devices to all of +to the "Target Device" or if you specified multiple target devices to all of them. Once you have your table, save it in a file somewhere (e.g. /etc/ntfsvolume1), @@ -457,6 +457,11 @@ ChangeLog Note, a technical ChangeLog aimed at kernel hackers is in fs/ntfs/ChangeLog. +2.1.30: + - Fix writev() (it kept writing the first segment over and over again + instead of moving onto subsequent segments). + - Fix crash in ntfs_mft_record_alloc() when mapping the new extent mft + record failed. 2.1.29: - Fix a deadlock when mounting read-write. 2.1.28: diff --git a/Documentation/filesystems/ocfs2.txt b/Documentation/filesystems/ocfs2.txt index 1f7ae144f6d8..9ed920a8cd79 100644 --- a/Documentation/filesystems/ocfs2.txt +++ b/Documentation/filesystems/ocfs2.txt @@ -80,10 +80,17 @@ user_xattr (*) Enables Extended User Attributes. nouser_xattr Disables Extended User Attributes. acl Enables POSIX Access Control Lists support. noacl (*) Disables POSIX Access Control Lists support. -resv_level=2 (*) Set how agressive allocation reservations will be. +resv_level=2 (*) Set how aggressive allocation reservations will be. Valid values are between 0 (reservations off) to 8 (maximum space for reservations). 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/path-lookup.txt b/Documentation/filesystems/path-lookup.txt new file mode 100644 index 000000000000..3571667c7105 --- /dev/null +++ b/Documentation/filesystems/path-lookup.txt @@ -0,0 +1,382 @@ +Path walking and name lookup locking +==================================== + +Path resolution is the finding a dentry corresponding to a path name string, by +performing a path walk. Typically, for every open(), stat() etc., the path name +will be resolved. Paths are resolved by walking the namespace tree, starting +with the first component of the pathname (eg. root or cwd) with a known dentry, +then finding the child of that dentry, which is named the next component in the +path string. Then repeating the lookup from the child dentry and finding its +child with the next element, and so on. + +Since it is a frequent operation for workloads like multiuser environments and +web servers, it is important to optimize this code. + +Path walking synchronisation history: +Prior to 2.5.10, dcache_lock was acquired in d_lookup (dcache hash lookup) and +thus in every component during path look-up. Since 2.5.10 onwards, fast-walk +algorithm changed this by holding the dcache_lock at the beginning and walking +as many cached path component dentries as possible. This significantly +decreases the number of acquisition of dcache_lock. However it also increases +the lock hold time significantly and affects performance in large SMP machines. +Since 2.5.62 kernel, dcache has been using a new locking model that uses RCU to +make dcache look-up lock-free. + +All the above algorithms required taking a lock and reference count on the +dentry that was looked up, so that may be used as the basis for walking the +next path element. This is inefficient and unscalable. It is inefficient +because of the locks and atomic operations required for every dentry element +slows things down. It is not scalable because many parallel applications that +are path-walk intensive tend to do path lookups starting from a common dentry +(usually, the root "/" or current working directory). So contention on these +common path elements causes lock and cacheline queueing. + +Since 2.6.38, RCU is used to make a significant part of the entire path walk +(including dcache look-up) completely "store-free" (so, no locks, atomics, or +even stores into cachelines of common dentries). This is known as "rcu-walk" +path walking. + +Path walking overview +===================== + +A name string specifies a start (root directory, cwd, fd-relative) and a +sequence of elements (directory entry names), which together refer to a path in +the namespace. A path is represented as a (dentry, vfsmount) tuple. The name +elements are sub-strings, separated by '/'. + +Name lookups will want to find a particular path that a name string refers to +(usually the final element, or parent of final element). This is done by taking +the path given by the name's starting point (which we know in advance -- eg. +current->fs->cwd or current->fs->root) as the first parent of the lookup. Then +iteratively for each subsequent name element, look up the child of the current +parent with the given name and if it is not the desired entry, make it the +parent for the next lookup. + +A parent, of course, must be a directory, and we must have appropriate +permissions on the parent inode to be able to walk into it. + +Turning the child into a parent for the next lookup requires more checks and +procedures. Symlinks essentially substitute the symlink name for the target +name in the name string, and require some recursive path walking. Mount points +must be followed into (thus changing the vfsmount that subsequent path elements +refer to), switching from the mount point path to the root of the particular +mounted vfsmount. These behaviours are variously modified depending on the +exact path walking flags. + +Path walking then must, broadly, do several particular things: +- find the start point of the walk; +- perform permissions and validity checks on inodes; +- perform dcache hash name lookups on (parent, name element) tuples; +- traverse mount points; +- traverse symlinks; +- lookup and create missing parts of the path on demand. + +Safe store-free look-up of dcache hash table +============================================ + +Dcache name lookup +------------------ +In order to lookup a dcache (parent, name) tuple, we take a hash on the tuple +and use that to select a bucket in the dcache-hash table. The list of entries +in that bucket is then walked, and we do a full comparison of each entry +against our (parent, name) tuple. + +The hash lists are RCU protected, so list walking is not serialised with +concurrent updates (insertion, deletion from the hash). This is a standard RCU +list application with the exception of renames, which will be covered below. + +Parent and name members of a dentry, as well as its membership in the dcache +hash, and its inode are protected by the per-dentry d_lock spinlock. A +reference is taken on the dentry (while the fields are verified under d_lock), +and this stabilises its d_inode pointer and actual inode. This gives a stable +point to perform the next step of our path walk against. + +These members are also protected by d_seq seqlock, although this offers +read-only protection and no durability of results, so care must be taken when +using d_seq for synchronisation (see seqcount based lookups, below). + +Renames +------- +Back to the rename case. In usual RCU protected lists, the only operations that +will happen to an object is insertion, and then eventually removal from the +list. The object will not be reused until an RCU grace period is complete. +This ensures the RCU list traversal primitives can run over the object without +problems (see RCU documentation for how this works). + +However when a dentry is renamed, its hash value can change, requiring it to be +moved to a new hash list. Allocating and inserting a new alias would be +expensive and also problematic for directory dentries. Latency would be far to +high to wait for a grace period after removing the dentry and before inserting +it in the new hash bucket. So what is done is to insert the dentry into the +new list immediately. + +However, when the dentry's list pointers are updated to point to objects in the +new list before waiting for a grace period, this can result in a concurrent RCU +lookup of the old list veering off into the new (incorrect) list and missing +the remaining dentries on the list. + +There is no fundamental problem with walking down the wrong list, because the +dentry comparisons will never match. However it is fatal to miss a matching +dentry. So a seqlock is used to detect when a rename has occurred, and so the +lookup can be retried. + + 1 2 3 + +---+ +---+ +---+ +hlist-->| N-+->| N-+->| N-+-> +head <--+-P |<-+-P |<-+-P | + +---+ +---+ +---+ + +Rename of dentry 2 may require it deleted from the above list, and inserted +into a new list. Deleting 2 gives the following list. + + 1 3 + +---+ +---+ (don't worry, the longer pointers do not +hlist-->| N-+-------->| N-+-> impose a measurable performance overhead +head <--+-P |<--------+-P | on modern CPUs) + +---+ +---+ + ^ 2 ^ + | +---+ | + | | N-+----+ + +----+-P | + +---+ + +This is a standard RCU-list deletion, which leaves the deleted object's +pointers intact, so a concurrent list walker that is currently looking at +object 2 will correctly continue to object 3 when it is time to traverse the +next object. + +However, when inserting object 2 onto a new list, we end up with this: + + 1 3 + +---+ +---+ +hlist-->| N-+-------->| N-+-> +head <--+-P |<--------+-P | + +---+ +---+ + 2 + +---+ + | N-+----> + <----+-P | + +---+ + +Because we didn't wait for a grace period, there may be a concurrent lookup +still at 2. Now when it follows 2's 'next' pointer, it will walk off into +another list without ever having checked object 3. + +A related, but distinctly different, issue is that of rename atomicity versus +lookup operations. If a file is renamed from 'A' to 'B', a lookup must only +find either 'A' or 'B'. So if a lookup of 'A' returns NULL, a subsequent lookup +of 'B' must succeed (note the reverse is not true). + +Between deleting the dentry from the old hash list, and inserting it on the new +hash list, a lookup may find neither 'A' nor 'B' matching the dentry. The same +rename seqlock is also used to cover this race in much the same way, by +retrying a negative lookup result if a rename was in progress. + +Seqcount based lookups +---------------------- +In refcount based dcache lookups, d_lock is used to serialise access to +the dentry, stabilising it while comparing its name and parent and then +taking a reference count (the reference count then gives a stable place to +start the next part of the path walk from). + +As explained above, we would like to do path walking without taking locks or +reference counts on intermediate dentries along the path. To do this, a per +dentry seqlock (d_seq) is used to take a "coherent snapshot" of what the dentry +looks like (its name, parent, and inode). That snapshot is then used to start +the next part of the path walk. When loading the coherent snapshot under d_seq, +care must be taken to load the members up-front, and use those pointers rather +than reloading from the dentry later on (otherwise we'd have interesting things +like d_inode going NULL underneath us, if the name was unlinked). + +Also important is to avoid performing any destructive operations (pretty much: +no non-atomic stores to shared data), and to recheck the seqcount when we are +"done" with the operation. Retry or abort if the seqcount does not match. +Avoiding destructive or changing operations means we can easily unwind from +failure. + +What this means is that a caller, provided they are holding RCU lock to +protect the dentry object from disappearing, can perform a seqcount based +lookup which does not increment the refcount on the dentry or write to +it in any way. This returned dentry can be used for subsequent operations, +provided that d_seq is rechecked after that operation is complete. + +Inodes are also rcu freed, so the seqcount lookup dentry's inode may also be +queried for permissions. + +With this two parts of the puzzle, we can do path lookups without taking +locks or refcounts on dentry elements. + +RCU-walk path walking design +============================ + +Path walking code now has two distinct modes, ref-walk and rcu-walk. ref-walk +is the traditional[*] way of performing dcache lookups using d_lock to +serialise concurrent modifications to the dentry and take a reference count on +it. ref-walk is simple and obvious, and may sleep, take locks, etc while path +walking is operating on each dentry. rcu-walk uses seqcount based dentry +lookups, and can perform lookup of intermediate elements without any stores to +shared data in the dentry or inode. rcu-walk can not be applied to all cases, +eg. if the filesystem must sleep or perform non trivial operations, rcu-walk +must be switched to ref-walk mode. + +[*] RCU is still used for the dentry hash lookup in ref-walk, but not the full + path walk. + +Where ref-walk uses a stable, refcounted ``parent'' to walk the remaining +path string, rcu-walk uses a d_seq protected snapshot. When looking up a +child of this parent snapshot, we open d_seq critical section on the child +before closing d_seq critical section on the parent. This gives an interlocking +ladder of snapshots to walk down. + + + proc 101 + /----------------\ + / comm: "vi" \ + / fs.root: dentry0 \ + \ fs.cwd: dentry2 / + \ / + \----------------/ + +So when vi wants to open("/home/npiggin/test.c", O_RDWR), then it will +start from current->fs->root, which is a pinned dentry. Alternatively, +"./test.c" would start from cwd; both names refer to the same path in +the context of proc101. + + dentry 0 + +---------------------+ rcu-walk begins here, we note d_seq, check the + | name: "/" | inode's permission, and then look up the next + | inode: 10 | path element which is "home"... + | children:"home", ...| + +---------------------+ + | + dentry 1 V + +---------------------+ ... which brings us here. We find dentry1 via + | name: "home" | hash lookup, then note d_seq and compare name + | inode: 678 | string and parent pointer. When we have a match, + | children:"npiggin" | we now recheck the d_seq of dentry0. Then we + +---------------------+ check inode and look up the next element. + | + dentry2 V + +---------------------+ Note: if dentry0 is now modified, lookup is + | name: "npiggin" | not necessarily invalid, so we need only keep a + | inode: 543 | parent for d_seq verification, and grandparents + | children:"a.c", ... | can be forgotten. + +---------------------+ + | + dentry3 V + +---------------------+ At this point we have our destination dentry. + | name: "a.c" | We now take its d_lock, verify d_seq of this + | inode: 14221 | dentry. If that checks out, we can increment + | children:NULL | its refcount because we're holding d_lock. + +---------------------+ + +Taking a refcount on a dentry from rcu-walk mode, by taking its d_lock, +re-checking its d_seq, and then incrementing its refcount is called +"dropping rcu" or dropping from rcu-walk into ref-walk mode. + +It is, in some sense, a bit of a house of cards. If the seqcount check of the +parent snapshot fails, the house comes down, because we had closed the d_seq +section on the grandparent, so we have nothing left to stand on. In that case, +the path walk must be fully restarted (which we do in ref-walk mode, to avoid +live locks). It is costly to have a full restart, but fortunately they are +quite rare. + +When we reach a point where sleeping is required, or a filesystem callout +requires ref-walk, then instead of restarting the walk, we attempt to drop rcu +at the last known good dentry we have. Avoiding a full restart in ref-walk in +these cases is fundamental for performance and scalability because blocking +operations such as creates and unlinks are not uncommon. + +The detailed design for rcu-walk is like this: +* LOOKUP_RCU is set in nd->flags, which distinguishes rcu-walk from ref-walk. +* Take the RCU lock for the entire path walk, starting with the acquiring + of the starting path (eg. root/cwd/fd-path). So now dentry refcounts are + not required for dentry persistence. +* synchronize_rcu is called when unregistering a filesystem, so we can + access d_ops and i_ops during rcu-walk. +* Similarly take the vfsmount lock for the entire path walk. So now mnt + refcounts are not required for persistence. Also we are free to perform mount + lookups, and to assume dentry mount points and mount roots are stable up and + down the path. +* Have a per-dentry seqlock to protect the dentry name, parent, and inode, + so we can load this tuple atomically, and also check whether any of its + members have changed. +* Dentry lookups (based on parent, candidate string tuple) recheck the parent + sequence after the child is found in case anything changed in the parent + during the path walk. +* inode is also RCU protected so we can load d_inode and use the inode for + limited things. +* i_mode, i_uid, i_gid can be tested for exec permissions during path walk. +* i_op can be loaded. +* When the destination dentry is reached, drop rcu there (ie. take d_lock, + verify d_seq, increment refcount). +* If seqlock verification fails anywhere along the path, do a full restart + of the path lookup in ref-walk mode. -ECHILD tends to be used (for want of + a better errno) to signal an rcu-walk failure. + +The cases where rcu-walk cannot continue are: +* NULL dentry (ie. any uncached path element) +* Following links + +It may be possible eventually to make following links rcu-walk aware. + +Uncached path elements will always require dropping to ref-walk mode, at the +very least because i_mutex needs to be grabbed, and objects allocated. + +Final note: +"store-free" path walking is not strictly store free. We take vfsmount lock +and refcounts (both of which can be made per-cpu), and we also store to the +stack (which is essentially CPU-local), and we also have to take locks and +refcount on final dentry. + +The point is that shared data, where practically possible, is not locked +or stored into. The result is massive improvements in performance and +scalability of path resolution. + + +Interesting statistics +====================== + +The following table gives rcu lookup statistics for a few simple workloads +(2s12c24t Westmere, debian non-graphical system). Ungraceful are attempts to +drop rcu that fail due to d_seq failure and requiring the entire path lookup +again. Other cases are successful rcu-drops that are required before the final +element, nodentry for missing dentry, revalidate for filesystem revalidate +routine requiring rcu drop, permission for permission check requiring drop, +and link for symlink traversal requiring drop. + + rcu-lookups restart nodentry link revalidate permission +bootup 47121 0 4624 1010 10283 7852 +dbench 25386793 0 6778659(26.7%) 55 549 1156 +kbuild 2696672 10 64442(2.3%) 108764(4.0%) 1 1590 +git diff 39605 0 28 2 0 106 +vfstest 24185492 4945 708725(2.9%) 1076136(4.4%) 0 2651 + +What this shows is that failed rcu-walk lookups, ie. ones that are restarted +entirely with ref-walk, are quite rare. Even the "vfstest" case which +specifically has concurrent renames/mkdir/rmdir/ creat/unlink/etc to exercise +such races is not showing a huge amount of restarts. + +Dropping from rcu-walk to ref-walk mean that we have encountered a dentry where +the reference count needs to be taken for some reason. This is either because +we have reached the target of the path walk, or because we have encountered a +condition that can't be resolved in rcu-walk mode. Ideally, we drop rcu-walk +only when we have reached the target dentry, so the other statistics show where +this does not happen. + +Note that a graceful drop from rcu-walk mode due to something such as the +dentry not existing (which can be common) is not necessarily a failure of +rcu-walk scheme, because some elements of the path may have been walked in +rcu-walk mode. The further we get from common path elements (such as cwd or +root), the less contended the dentry is likely to be. The closer we are to +common path elements, the more likely they will exist in dentry cache. + + +Papers and other documentation on dcache locking +================================================ + +1. Scaling dcache with RCU (http://linuxjournal.com/article.php?sid=7124). + +2. http://lse.sourceforge.net/locking/dcache/dcache.html + + diff --git a/Documentation/filesystems/pohmelfs/network_protocol.txt b/Documentation/filesystems/pohmelfs/network_protocol.txt index 40ea6c295afb..65e03dd44823 100644 --- a/Documentation/filesystems/pohmelfs/network_protocol.txt +++ b/Documentation/filesystems/pohmelfs/network_protocol.txt @@ -20,7 +20,7 @@ Commands can be embedded into transaction command (which in turn has own command so one can extend protocol as needed without breaking backward compatibility as long as old commands are supported. All string lengths include tail 0 byte. -All commans are transfered over the network in big-endian. CPU endianess is used at the end peers. +All commands are transferred over the network in big-endian. CPU endianess is used at the end peers. @cmd - command number, which specifies command to be processed. Following commands are used currently: diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index b12c89538680..6e29954851a2 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -216,7 +216,6 @@ had ->revalidate()) add calls in ->follow_link()/->readlink(). ->d_parent changes are not protected by BKL anymore. Read access is safe if at least one of the following is true: * filesystem has no cross-directory rename() - * dcache_lock is held * we know that parent had been locked (e.g. we are looking at ->d_parent of ->lookup() argument). * we are called from ->rename(). @@ -299,11 +298,14 @@ 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. + + ->drop_inode() returns int now; it's called on final iput() with +inode->i_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 @@ -318,3 +320,90 @@ 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. + +--- +[mandatory] + + .d_delete() now only advises the dcache as to whether or not to cache +unreferenced dentries, and is now only called when the dentry refcount goes to +0. Even on 0 refcount transition, it must be able to tolerate being called 0, +1, or more times (eg. constant, idempotent). + +--- +[mandatory] + + .d_compare() calling convention and locking rules are significantly +changed. Read updated documentation in Documentation/filesystems/vfs.txt (and +look at examples of other filesystems) for guidance. + +--- +[mandatory] + + .d_hash() calling convention and locking rules are significantly +changed. Read updated documentation in Documentation/filesystems/vfs.txt (and +look at examples of other filesystems) for guidance. + +--- +[mandatory] + dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c +for details of what locks to replace dcache_lock with in order to protect +particular things. Most of the time, a filesystem only needs ->d_lock, which +protects *all* the dcache state of a given dentry. + +-- +[mandatory] + + Filesystems must RCU-free their inodes, if they can have been accessed +via rcu-walk path walk (basically, if the file can have had a path name in the +vfs namespace). + + i_dentry and i_rcu share storage in a union, and the vfs expects +i_dentry to be reinitialized before it is freed, so an: + + INIT_LIST_HEAD(&inode->i_dentry); + +must be done in the RCU callback. + +-- +[recommended] + vfs now tries to do path walking in "rcu-walk mode", which avoids +atomic operations and scalability hazards on dentries and inodes (see +Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes +(above) are examples of the changes required to support this. For more complex +filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so +no changes are required to the filesystem. However, this is costly and loses +the benefits of rcu-walk mode. We will begin to add filesystem callbacks that +are rcu-walk aware, shown below. Filesystems should take advantage of this +where possible. + +-- +[mandatory] + d_revalidate is a callback that is made on every path element (if +the filesystem provides it), which requires dropping out of rcu-walk mode. This +may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be +returned if the filesystem cannot handle rcu-walk. See +Documentation/filesystems/vfs.txt for more details. + + permission and check_acl are inode permission checks that are called +on many or all directory inodes on the way down a path walk (to check for +exec permission). These must now be rcu-walk aware (flags & IPERM_FLAG_RCU). +See Documentation/filesystems/vfs.txt for more details. + +-- +[mandatory] + In ->fallocate() you must check the mode option passed in. If your +filesystem does not support hole punching (deallocating space in the middle of a +file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode. +Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set, +so the i_size should not change when hole punching, even when puching the end of +a file off. + +-- +[mandatory] + +-- +[mandatory] + ->get_sb() is gone. Switch to use of ->mount(). Typically it's just +a matter of switching from calling get_sb_... to mount_... and changing the +function type. If you were doing it manually, just switch from setting ->mnt_root +to some pointer to returning that pointer. On errors return ERR_PTR(...). diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index a6aca8740883..b0b814d75ca1 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -136,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 @@ -370,17 +371,25 @@ 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. +Locked: 374 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 +(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. @@ -397,6 +406,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 --------------- @@ -531,7 +543,7 @@ just those considered 'most important'. The new vectors are: their statistics are used by kernel developers and interested users to determine the occurrence of interrupts of the given type. -The above IRQ vectors are displayed only when relevent. For example, +The above IRQ vectors are displayed only when relevant. For example, the threshold vector does not exist on x86_64 platforms. Others are suppressed when the system is a uniprocessor. As of this writing, only i386 and x86_64 platforms support the new IRQ vector displays. @@ -659,6 +671,8 @@ varies by architecture and compile options. The following is from a > cat /proc/meminfo +The "Locked" indicates whether the mapping is locked in memory or not. + MemTotal: 16344972 kB MemFree: 13634064 kB @@ -1170,6 +1184,30 @@ Table 1-12: Files in /proc/fs/ext4/<devname> mb_groups details of multiblock allocator buddy cache of free blocks .............................................................................. +2.0 /proc/consoles +------------------ +Shows registered system console lines. + +To see which character device lines are currently used for the system console +/dev/console, you may simply look into the file /proc/consoles: + + > cat /proc/consoles + tty0 -WU (ECp) 4:7 + ttyS0 -W- (Ep) 4:64 + +The columns are: + + device name of the device + operations R = can do read operations + W = can do write operations + U = can do unblank + flags E = it is enabled + C = it is preferred console + B = it is primary boot console + p = it is used for printk buffer + b = it is not a TTY but a Braille device + a = it is safe to use when cpu is offline + major:minor major and minor number of the device separated by a colon ------------------------------------------------------------------------------ Summary @@ -1285,11 +1323,15 @@ 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. +The value of /proc/<pid>/oom_score_adj may be reduced no lower than the last +value set by a CAP_SYS_RESOURCE process. To reduce the value any lower +requires CAP_SYS_RESOURCE. + 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 +generation children with separate address spaces instead, if possible. This avoids servers and important system daemons from being killed and loses the minimal amount of work. diff --git a/Documentation/filesystems/romfs.txt b/Documentation/filesystems/romfs.txt index 2d2a7b2a16b9..e2b07cc9120a 100644 --- a/Documentation/filesystems/romfs.txt +++ b/Documentation/filesystems/romfs.txt @@ -17,8 +17,7 @@ comparison, an actual rescue disk used up 3202 blocks with ext2, while with romfs, it needed 3079 blocks. To create such a file system, you'll need a user program named -genromfs. It is available via anonymous ftp on sunsite.unc.edu and -its mirrors, in the /pub/Linux/system/recovery/ directory. +genromfs. It is available on http://romfs.sourceforge.net/ As the name suggests, romfs could be also used (space-efficiently) on various read-only media, like (E)EPROM disks if someone will have the diff --git a/Documentation/filesystems/sharedsubtree.txt b/Documentation/filesystems/sharedsubtree.txt index fc0e39af43c3..4ede421c9687 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 194fb0decd2c..000000000000 --- 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 66699afd66ca..d4d41465a0b1 100644 --- a/Documentation/filesystems/squashfs.txt +++ b/Documentation/filesystems/squashfs.txt @@ -59,12 +59,15 @@ obtained from this site also. 3. SQUASHFS FILESYSTEM DESIGN ----------------------------- -A squashfs filesystem consists of a maximum of eight parts, packed together on a byte -alignment: +A squashfs filesystem consists of a maximum of nine parts, packed together on a +byte alignment: --------------- | superblock | |---------------| + | compression | + | options | + |---------------| | datablocks | | & fragments | |---------------| @@ -91,7 +94,14 @@ the source directory, and checked for duplicates. Once all file data has been written the completed inode, directory, fragment, export and uid/gid lookup tables are written. -3.1 Inodes +3.1 Compression options +----------------------- + +Compressors can optionally support compression specific options (e.g. +dictionary size). If non-default compression options have been used, then +these are stored here. + +3.2 Inodes ---------- Metadata (inodes and directories) are compressed in 8Kbyte blocks. Each @@ -114,7 +124,7 @@ directory inode are defined: inodes optimised for frequently occurring regular files and directories, and extended types where extra information has to be stored. -3.2 Directories +3.3 Directories --------------- Like inodes, directories are packed into compressed metadata blocks, stored @@ -144,7 +154,7 @@ decompressed to do a lookup irrespective of the length of the directory. This scheme has the advantage that it doesn't require extra memory overhead and doesn't require much extra storage on disk. -3.3 File data +3.4 File data ------------- Regular files consist of a sequence of contiguous compressed blocks, and/or a @@ -163,7 +173,7 @@ Larger files use multiple slots, with 1.75 TiB files using all 8 slots. The index cache is designed to be memory efficient, and by default uses 16 KiB. -3.4 Fragment lookup table +3.5 Fragment lookup table ------------------------- Regular files can contain a fragment index which is mapped to a fragment @@ -173,7 +183,7 @@ A second index table is used to locate these. This second index table for speed of access (and because it is small) is read at mount time and cached in memory. -3.5 Uid/gid lookup table +3.6 Uid/gid lookup table ------------------------ For space efficiency regular files store uid and gid indexes, which are @@ -182,7 +192,7 @@ stored compressed into metadata blocks. A second index table is used to locate these. This second index table for speed of access (and because it is small) is read at mount time and cached in memory. -3.6 Export table +3.7 Export table ---------------- To enable Squashfs filesystems to be exportable (via NFS etc.) filesystems @@ -196,7 +206,7 @@ This table is stored compressed into metadata blocks. A second index table is used to locate these. This second index table for speed of access (and because it is small) is read at mount time and cached in memory. -3.7 Xattr table +3.8 Xattr table --------------- The xattr table contains extended attributes for each inode. The xattrs @@ -209,7 +219,7 @@ or if it is stored out of line (in which case the value field stores a reference to where the actual value is stored). This allows large values to be stored out of line improving scanning and lookup performance and it also allows values to be de-duplicated, the value being stored once, and -all other occurences holding an out of line reference to that value. +all other occurrences holding an out of line reference to that value. The xattr lists are packed into compressed 8K metadata blocks. To reduce overhead in inodes, rather than storing the on-disk diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 5d1335faec2d..597f728e7b4e 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -39,10 +39,12 @@ userspace. Top-level directories in sysfs represent the common ancestors of object hierarchies; i.e. the subsystems the objects belong to. -Sysfs internally stores the kobject that owns the directory in the -->d_fsdata pointer of the directory's dentry. This allows sysfs to do -reference counting directly on the kobject when the file is opened and -closed. +Sysfs internally stores a pointer to the kobject that implements a +directory in the sysfs_dirent object associated with the directory. In +the past this kobject pointer has been used by sysfs to do reference +counting directly on the kobject whenever the file is opened or closed. +With the current sysfs implementation the kobject reference count is +only modified directly by the function sysfs_schedule_callback(). Attributes @@ -60,7 +62,7 @@ values of the same type. Mixing types, expressing multiple lines of data, and doing fancy formatting of data is heavily frowned upon. Doing these things may get -you publically humiliated and your code rewritten without notice. +you publicly humiliated and your code rewritten without notice. An attribute definition is simply: @@ -208,9 +210,9 @@ Other notes: is 4096. - show() methods should return the number of bytes printed into the - buffer. This is the return value of snprintf(). + buffer. This is the return value of scnprintf(). -- show() should always use snprintf(). +- show() should always use scnprintf(). - store() should return the number of bytes used from the buffer. If the entire buffer has been used, just return the count argument. @@ -229,7 +231,7 @@ A very simple (and naive) implementation of a device attribute is: static ssize_t show_name(struct device *dev, struct device_attribute *attr, char *buf) { - return snprintf(buf, PAGE_SIZE, "%s\n", dev->name); + return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name); } static ssize_t store_name(struct device *dev, struct device_attribute *attr, diff --git a/Documentation/filesystems/ubifs.txt b/Documentation/filesystems/ubifs.txt index 12fedb7834c6..d7b13b01e980 100644 --- a/Documentation/filesystems/ubifs.txt +++ b/Documentation/filesystems/ubifs.txt @@ -82,12 +82,12 @@ Mount options bulk_read read more in one go to take advantage of flash media that read faster sequentially no_bulk_read (*) do not bulk-read -no_chk_data_crc skip checking of CRCs on data nodes in order to +no_chk_data_crc (*) skip checking of CRCs on data nodes in order to improve read performance. Use this option only if the flash media is highly reliable. The effect of this option is that corruption of the contents of a file can go unnoticed. -chk_data_crc (*) do not skip checking CRCs on data nodes +chk_data_crc do not skip checking CRCs on data nodes compr=none override default compressor and set it to "none" compr=lzo override default compressor and set it to "lzo" compr=zlib override default compressor and set it to "zlib" diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index ed7e5efc06d8..21a7dc467bba 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -95,10 +95,11 @@ functions: extern int unregister_filesystem(struct file_system_type *); The passed struct file_system_type describes your filesystem. When a -request is made to mount a device onto a directory in your filespace, -the VFS will call the appropriate get_sb() method for the specific -filesystem. The dentry for the mount point will then be updated to -point to the root inode for the new filesystem. +request is made to mount a filesystem onto a directory in your namespace, +the VFS will call the appropriate mount() method for the specific +filesystem. New vfsmount referring to the tree returned by ->mount() +will be attached to the mountpoint, so that when pathname resolution +reaches the mountpoint it will jump into the root of that vfsmount. You can see all filesystems that are registered to the kernel in the file /proc/filesystems. @@ -107,14 +108,14 @@ file /proc/filesystems. struct file_system_type ----------------------- -This describes the filesystem. As of kernel 2.6.22, the following +This describes the filesystem. As of kernel 2.6.39, the following members are defined: struct file_system_type { const char *name; int fs_flags; - int (*get_sb) (struct file_system_type *, int, - const char *, void *, struct vfsmount *); + struct dentry (*mount) (struct file_system_type *, int, + const char *, void *); void (*kill_sb) (struct super_block *); struct module *owner; struct file_system_type * next; @@ -128,11 +129,11 @@ struct file_system_type { fs_flags: various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.) - get_sb: the method to call when a new instance of this + mount: the method to call when a new instance of this filesystem should be mounted kill_sb: the method to call when an instance of this filesystem - should be unmounted + should be shut down owner: for internal VFS use: you should initialize this to THIS_MODULE in most cases. @@ -141,7 +142,7 @@ struct file_system_type { s_lock_key, s_umount_key: lockdep-specific -The get_sb() method has the following arguments: +The mount() method has the following arguments: struct file_system_type *fs_type: describes the filesystem, partly initialized by the specific filesystem code @@ -153,32 +154,39 @@ The get_sb() method has the following arguments: void *data: arbitrary mount options, usually comes as an ASCII string (see "Mount Options" section) - struct vfsmount *mnt: a vfs-internal representation of a mount point +The mount() method must return the root dentry of the tree requested by +caller. An active reference to its superblock must be grabbed and the +superblock must be locked. On failure it should return ERR_PTR(error). -The get_sb() method must determine if the block device specified -in the dev_name and fs_type contains a filesystem of the type the method -supports. If it succeeds in opening the named block device, it initializes a -struct super_block descriptor for the filesystem contained by the block device. -On failure it returns an error. +The arguments match those of mount(2) and their interpretation +depends on filesystem type. E.g. for block filesystems, dev_name is +interpreted as block device name, that device is opened and if it +contains a suitable filesystem image the method creates and initializes +struct super_block accordingly, returning its root dentry to caller. + +->mount() may choose to return a subtree of existing filesystem - it +doesn't have to create a new one. The main result from the caller's +point of view is a reference to dentry at the root of (sub)tree to +be attached; creation of new superblock is a common side effect. The most interesting member of the superblock structure that the -get_sb() method fills in is the "s_op" field. This is a pointer to +mount() method fills in is the "s_op" field. This is a pointer to a "struct super_operations" which describes the next level of the filesystem implementation. -Usually, a filesystem uses one of the generic get_sb() implementations -and provides a fill_super() method instead. The generic methods are: +Usually, a filesystem uses one of the generic mount() implementations +and provides a fill_super() callback instead. The generic variants are: - get_sb_bdev: mount a filesystem residing on a block device + mount_bdev: mount a filesystem residing on a block device - get_sb_nodev: mount a filesystem that is not backed by a device + mount_nodev: mount a filesystem that is not backed by a device - get_sb_single: mount a filesystem which shares the instance between + mount_single: mount a filesystem which shares the instance between all mounts -A fill_super() method implementation has the following arguments: +A fill_super() callback implementation has the following arguments: - struct super_block *sb: the superblock structure. The method fill_super() + struct super_block *sb: the superblock structure. The callback must initialize this properly. void *data: arbitrary mount options, usually comes as an ASCII @@ -246,7 +254,7 @@ or bottom half). should be synchronous or not, not all filesystems check this flag. drop_inode: called when the last access to the inode is dropped, - with the inode_lock spinlock held. + with the inode->i_lock spinlock held. This method should be either NULL (normal UNIX filesystem semantics) or "generic_delete_inode" (for filesystems that do not @@ -325,7 +333,8 @@ struct inode_operations { void * (*follow_link) (struct dentry *, struct nameidata *); void (*put_link) (struct dentry *, struct nameidata *, void *); void (*truncate) (struct inode *); - int (*permission) (struct inode *, int, struct nameidata *); + int (*permission) (struct inode *, int, unsigned int); + int (*check_acl)(struct inode *, int, unsigned int); int (*setattr) (struct dentry *, struct iattr *); int (*getattr) (struct vfsmount *mnt, struct dentry *, struct kstat *); int (*setxattr) (struct dentry *, const char *,const void *,size_t,int); @@ -414,6 +423,13 @@ otherwise noted. permission: called by the VFS to check for access rights on a POSIX-like filesystem. + May be called in rcu-walk mode (flags & IPERM_FLAG_RCU). If in rcu-walk + mode, the filesystem must check the permission without blocking or + storing to the inode. + + If a situation is encountered that rcu-walk cannot handle, return + -ECHILD and it will be called again in ref-walk mode. + setattr: called by the VFS to set attributes for a file. This method is called by chmod(2) and related system calls. @@ -534,6 +550,7 @@ struct address_space_operations { sector_t (*bmap)(struct address_space *, sector_t); int (*invalidatepage) (struct page *, unsigned long); int (*releasepage) (struct page *, int); + void (*freepage)(struct page *); ssize_t (*direct_IO)(int, struct kiocb *, const struct iovec *iov, loff_t offset, unsigned long nr_segs); struct page* (*get_xip_page)(struct address_space *, sector_t, @@ -660,11 +677,10 @@ struct address_space_operations { releasepage: releasepage is called on PagePrivate pages to indicate that the page should be freed if possible. ->releasepage should remove any private data from the page and clear the - PagePrivate flag. It may also remove the page from the - address_space. If this fails for some reason, it may indicate - failure with a 0 return value. - This is used in two distinct though related cases. The first - is when the VM finds a clean page with no active users and + PagePrivate flag. If releasepage() fails for some reason, it must + indicate failure with a 0 return value. + releasepage() is used in two distinct though related cases. The + first is when the VM finds a clean page with no active users and wants to make it a free page. If ->releasepage succeeds, the page will be removed from the address_space and become free. @@ -679,6 +695,12 @@ struct address_space_operations { need to ensure this. Possibly it can clear the PageUptodate bit if it cannot free private data yet. + freepage: freepage is called once the page is no longer visible in + the page cache in order to allow the cleanup of any private + data. Since it may be called by the memory reclaimer, it + should not assume that the original address_space mapping still + exists, and it should not block. + direct_IO: called by the generic read/write routines to perform direct_IO - that is IO requests which bypass the page cache and transfer data directly between the storage and the @@ -841,12 +863,17 @@ defined: struct dentry_operations { int (*d_revalidate)(struct dentry *, struct nameidata *); - int (*d_hash) (struct dentry *, struct qstr *); - int (*d_compare) (struct dentry *, struct qstr *, struct qstr *); - int (*d_delete)(struct dentry *); + int (*d_hash)(const struct dentry *, const struct inode *, + struct qstr *); + int (*d_compare)(const struct dentry *, const struct inode *, + const struct dentry *, const struct inode *, + unsigned int, const char *, const struct qstr *); + int (*d_delete)(const struct dentry *); void (*d_release)(struct dentry *); void (*d_iput)(struct dentry *, struct inode *); char *(*d_dname)(struct dentry *, char *, int); + struct vfsmount *(*d_automount)(struct path *); + int (*d_manage)(struct dentry *, bool); }; d_revalidate: called when the VFS needs to revalidate a dentry. This @@ -854,13 +881,45 @@ struct dentry_operations { dcache. Most filesystems leave this as NULL, because all their dentries in the dcache are valid - d_hash: called when the VFS adds a dentry to the hash table + d_revalidate may be called in rcu-walk mode (nd->flags & LOOKUP_RCU). + If in rcu-walk mode, the filesystem must revalidate the dentry without + blocking or storing to the dentry, d_parent and d_inode should not be + used without care (because they can go NULL), instead nd->inode should + be used. + + If a situation is encountered that rcu-walk cannot handle, return + -ECHILD and it will be called again in ref-walk mode. + + d_hash: called when the VFS adds a dentry to the hash table. The first + dentry passed to d_hash is the parent directory that the name is + to be hashed into. The inode is the dentry's inode. - d_compare: called when a dentry should be compared with another + Same locking and synchronisation rules as d_compare regarding + what is safe to dereference etc. - d_delete: called when the last reference to a dentry is - deleted. This means no-one is using the dentry, however it is - still valid and in the dcache + d_compare: called to compare a dentry name with a given name. The first + dentry is the parent of the dentry to be compared, the second is + the parent's inode, then the dentry and inode (may be NULL) of the + child dentry. len and name string are properties of the dentry to be + compared. qstr is the name to compare it with. + + Must be constant and idempotent, and should not take locks if + possible, and should not or store into the dentry or inodes. + Should not dereference pointers outside the dentry or inodes without + lots of care (eg. d_parent, d_inode, d_name should not be used). + + However, our vfsmount is pinned, and RCU held, so the dentries and + inodes won't disappear, neither will our sb or filesystem module. + ->i_sb and ->d_sb may be used. + + It is a tricky calling convention because it needs to be called under + "rcu-walk", ie. without any locks or references on things. + + d_delete: called when the last reference to a dentry is dropped and the + dcache is deciding whether or not to cache it. Return 1 to delete + immediately, or 0 to cache the dentry. Default is NULL which means to + always cache a reachable dentry. d_delete must be constant and + idempotent. d_release: called when a dentry is really deallocated @@ -881,6 +940,43 @@ struct dentry_operations { at the end of the buffer, and returns a pointer to the first char. dynamic_dname() helper function is provided to take care of this. + d_automount: called when an automount dentry is to be traversed (optional). + This should create a new VFS mount record and return the record to the + caller. The caller is supplied with a path parameter giving the + automount directory to describe the automount target and the parent + VFS mount record to provide inheritable mount parameters. NULL should + be returned if someone else managed to make the automount first. If + the vfsmount creation failed, then an error code should be returned. + If -EISDIR is returned, then the directory will be treated as an + ordinary directory and returned to pathwalk to continue walking. + + If a vfsmount is returned, the caller will attempt to mount it on the + mountpoint and will remove the vfsmount from its expiration list in + the case of failure. The vfsmount should be returned with 2 refs on + it to prevent automatic expiration - the caller will clean up the + additional ref. + + This function is only used if DCACHE_NEED_AUTOMOUNT is set on the + dentry. This is set by __d_instantiate() if S_AUTOMOUNT is set on the + inode being added. + + d_manage: called to allow the filesystem to manage the transition from a + dentry (optional). This allows autofs, for example, to hold up clients + waiting to explore behind a 'mountpoint' whilst letting the daemon go + past and construct the subtree there. 0 should be returned to let the + calling process continue. -EISDIR can be returned to tell pathwalk to + use this directory as an ordinary directory and to ignore anything + mounted on it and not to check the automount flag. Any other error + code will abort pathwalk completely. + + If the 'rcu_walk' parameter is true, then the caller is doing a + pathwalk in RCU-walk mode. Sleeping is not permitted in this mode, + and the caller can be asked to leave it and call again by returing + -ECHILD. + + This function is only used if DCACHE_MANAGE_TRANSIT is set on the + dentry being transited from. + Example : static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen) @@ -904,14 +1000,11 @@ manipulate dentries: the usage count) dput: close a handle for a dentry (decrements the usage count). If - the usage count drops to 0, the "d_delete" method is called - and the dentry is placed on the unused list if the dentry is - still in its parents hash list. Putting the dentry on the - unused list just means that if the system needs some RAM, it - goes through the unused list of dentries and deallocates them. - If the dentry has already been unhashed and the usage count - drops to 0, in this case the dentry is deallocated after the - "d_delete" method is called + the usage count drops to 0, and the dentry is still in its + parent's hash, the "d_delete" method is called to check whether + it should be cached. If it should not be cached, or if the dentry + is not hashed, it is deleted. Otherwise cached dentries are put + into an LRU list to be reclaimed on memory shortage. d_drop: this unhashes a dentry from its parents hash list. A subsequent call to dput() will deallocate the dentry if its diff --git a/Documentation/filesystems/xfs-delayed-logging-design.txt b/Documentation/filesystems/xfs-delayed-logging-design.txt index 96d0df28bed3..2ce36439c09f 100644 --- a/Documentation/filesystems/xfs-delayed-logging-design.txt +++ b/Documentation/filesystems/xfs-delayed-logging-design.txt @@ -42,7 +42,7 @@ the aggregation of all the previous changes currently held only in the log. This relogging technique also allows objects to be moved forward in the log so that an object being relogged does not prevent the tail of the log from ever moving forward. This can be seen in the table above by the changing -(increasing) LSN of each subsquent transaction - the LSN is effectively a +(increasing) LSN of each subsequent transaction - the LSN is effectively a direct encoding of the location in the log of the transaction. This relogging is also used to implement long-running, multiple-commit @@ -338,7 +338,7 @@ the same time another transaction modifies the item and inserts the log item into the new CIL, then checkpoint transaction commit code cannot use log items to store the list of log vectors that need to be written into the transaction. Hence log vectors need to be able to be chained together to allow them to be -detatched from the log items. That is, when the CIL is flushed the memory +detached from the log items. That is, when the CIL is flushed the memory buffer and log vector attached to each log item needs to be attached to the checkpoint context so that the log item can be released. In diagrammatic form, the CIL would look like this before the flush: @@ -577,7 +577,7 @@ only becomes unpinned when all the transactions complete and there are no pending transactions. Thus the pinning and unpinning of a log item is symmetric as there is a 1:1 relationship with transaction commit and log item completion. -For delayed logging, however, we have an assymetric transaction commit to +For delayed logging, however, we have an asymmetric transaction commit to completion relationship. Every time an object is relogged in the CIL it goes through the commit process without a corresponding completion being registered. That is, we now have a many-to-one relationship between transaction commit and @@ -780,7 +780,7 @@ With delayed logging, there are new steps inserted into the life cycle: From this, it can be seen that the only life cycle differences between the two logging methods are in the middle of the life cycle - they still have the same beginning and end and execution constraints. The only differences are in the -commiting of the log items to the log itself and the completion processing. +committing of the log items to the log itself and the completion processing. Hence delayed logging should not introduce any constraints on log item behaviour, allocation or freeing that don't already exist. @@ -791,21 +791,3 @@ mount option. Fundamentally, there is no reason why the log manager would not be able to swap methods automatically and transparently depending on load characteristics, but this should not be necessary if delayed logging works as designed. - -Roadmap: - -2.6.37 Remove experimental tag from mount option - => should be roughly 6 months after initial merge - => enough time to: - => gain confidence and fix problems reported by early - adopters (a.k.a. guinea pigs) - => address worst performance regressions and undesired - behaviours - => start tuning/optimising code for parallelism - => start tuning/optimising algorithms consuming - excessive CPU time - -2.6.39 Switch default mount option to use delayed logging - => should be roughly 12 months after initial merge - => enough time to shake out remaining problems before next round of - enterprise distro kernel rebases diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt index 9633da01ff46..792faa3c06cf 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio.txt @@ -617,6 +617,16 @@ and have the following read/write attributes: is configured as an output, this value may be written; any nonzero value is treated as high. + If the pin can be configured as interrupt-generating interrupt + and if it has been configured to generate interrupts (see the + description of "edge"), you can poll(2) on that file and + poll(2) will return whenever the interrupt was triggered. If + you use poll(2), set the events POLLPRI and POLLERR. If you + use select(2), set the file descriptor in exceptfds. After + poll(2) returns, either lseek(2) to the beginning of the sysfs + file and read the new value or close the file and re-open it + to read the value. + "edge" ... reads as either "none", "rising", "falling", or "both". Write these strings to select the signal edge(s) that will make poll(2) on the "value" file return. diff --git a/Documentation/usb/hiddev.txt b/Documentation/hid/hiddev.txt index 6e8c9f1d2f22..6e8c9f1d2f22 100644 --- a/Documentation/usb/hiddev.txt +++ b/Documentation/hid/hiddev.txt diff --git a/Documentation/hid/hidraw.txt b/Documentation/hid/hidraw.txt new file mode 100644 index 000000000000..029e6cb9a7e8 --- /dev/null +++ b/Documentation/hid/hidraw.txt @@ -0,0 +1,119 @@ + HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices + ================================================================== + +The hidraw driver provides a raw interface to USB and Bluetooth Human +Interface Devices (HIDs). It differs from hiddev in that reports sent and +received are not parsed by the HID parser, but are sent to and received from +the device unmodified. + +Hidraw should be used if the userspace application knows exactly how to +communicate with the hardware device, and is able to construct the HID +reports manually. This is often the case when making userspace drivers for +custom HID devices. + +Hidraw is also useful for communicating with non-conformant HID devices +which send and receive data in a way that is inconsistent with their report +descriptors. Because hiddev parses reports which are sent and received +through it, checking them against the device's report descriptor, such +communication with these non-conformant devices is impossible using hiddev. +Hidraw is the only alternative, short of writing a custom kernel driver, for +these non-conformant devices. + +A benefit of hidraw is that its use by userspace applications is independent +of the underlying hardware type. Currently, Hidraw is implemented for USB +and Bluetooth. In the future, as new hardware bus types are developed which +use the HID specification, hidraw will be expanded to add support for these +new bus types. + +Hidraw uses a dynamic major number, meaning that udev should be relied on to +create hidraw device nodes. Udev will typically create the device nodes +directly under /dev (eg: /dev/hidraw0). As this location is distribution- +and udev rule-dependent, applications should use libudev to locate hidraw +devices attached to the system. There is a tutorial on libudev with a +working example at: + http://www.signal11.us/oss/udev/ + +The HIDRAW API +--------------- + +read() +------- +read() will read a queued report received from the HID device. On USB +devices, the reports read using read() are the reports sent from the device +on the INTERRUPT IN endpoint. By default, read() will block until there is +a report available to be read. read() can be made non-blocking, by passing +the O_NONBLOCK flag to open(), or by setting the O_NONBLOCK flag using +fcntl(). + +On a device which uses numbered reports, the first byte of the returned data +will be the report number; the report data follows, beginning in the second +byte. For devices which do not use numbered reports, the report data +will begin at the first byte. + +write() +-------- +The write() function will write a report to the device. For USB devices, if +the device has an INTERRUPT OUT endpoint, the report will be sent on that +endpoint. If it does not, the report will be sent over the control endpoint, +using a SET_REPORT transfer. + +The first byte of the buffer passed to write() should be set to the report +number. If the device does not use numbered reports, the first byte should +be set to 0. The report data itself should begin at the second byte. + +ioctl() +-------- +Hidraw supports the following ioctls: + +HIDIOCGRDESCSIZE: Get Report Descriptor Size +This ioctl will get the size of the device's report descriptor. + +HIDIOCGRDESC: Get Report Descriptor +This ioctl returns the device's report descriptor using a +hidraw_report_descriptor struct. Make sure to set the size field of the +hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE. + +HIDIOCGRAWINFO: Get Raw Info +This ioctl will return a hidraw_devinfo struct containing the bus type, the +vendor ID (VID), and product ID (PID) of the device. The bus type can be one +of: + BUS_USB + BUS_HIL + BUS_BLUETOOTH + BUS_VIRTUAL +which are defined in linux/input.h. + +HIDIOCGRAWNAME(len): Get Raw Name +This ioctl returns a string containing the vendor and product strings of +the device. The returned string is Unicode, UTF-8 encoded. + +HIDIOCGRAWPHYS(len): Get Physical Address +This ioctl returns a string representing the physical address of the device. +For USB devices, the string contains the physical path to the device (the +USB controller, hubs, ports, etc). For Bluetooth devices, the string +contains the hardware (MAC) address of the device. + +HIDIOCSFEATURE(len): Send a Feature Report +This ioctl will send a feature report to the device. Per the HID +specification, feature reports are always sent using the control endpoint. +Set the first byte of the supplied buffer to the report number. For devices +which do not use numbered reports, set the first byte to 0. The report data +begins in the second byte. Make sure to set len accordingly, to one more +than the length of the report (to account for the report number). + +HIDIOCGFEATURE(len): Get a Feature Report +This ioctl will request a feature report from the device using the control +endpoint. The first byte of the supplied buffer should be set to the report +number of the requested report. For devices which do not use numbered +reports, set the first byte to 0. The report will be returned starting at +the first byte of the buffer (ie: the report number is not returned). + +Example +--------- +In samples/, find hid-example.c, which shows examples of read(), write(), +and all the ioctls for hidraw. The code may be used by anyone for any +purpose, and can serve as a starting point for developing applications using +hidraw. + +Document by: + Alan Ott <alan@signal11.us>, Signal 11 Software diff --git a/Documentation/hwmon/abituguru b/Documentation/hwmon/abituguru index 5eb3b9d5f0d5..915f32063a26 100644 --- a/Documentation/hwmon/abituguru +++ b/Documentation/hwmon/abituguru @@ -78,7 +78,7 @@ motherboards (most modern Abit motherboards). The first and second revision of the uGuru chip in reality is a Winbond W83L950D in disguise (despite Abit claiming it is "a new microprocessor -designed by the ABIT Engineers"). Unfortunatly this doesn't help since the +designed by the ABIT Engineers"). Unfortunately this doesn't help since the W83L950D is a generic microcontroller with a custom Abit application running on it. diff --git a/Documentation/hwmon/abituguru-datasheet b/Documentation/hwmon/abituguru-datasheet index d9251efdcec7..8d2be8a0b1e3 100644 --- a/Documentation/hwmon/abituguru-datasheet +++ b/Documentation/hwmon/abituguru-datasheet @@ -5,9 +5,9 @@ First of all, what I know about uGuru is no fact based on any help, hints or datasheet from Abit. The data I have got on uGuru have I assembled through my weak knowledge in "backwards engineering". And just for the record, you may have noticed uGuru isn't a chip developed by -Abit, as they claim it to be. It's realy just an microprocessor (uC) created by +Abit, as they claim it to be. It's really just an microprocessor (uC) created by Winbond (W83L950D). And no, reading the manual for this specific uC or -mailing Windbond for help won't give any usefull data about uGuru, as it is +mailing Windbond for help won't give any useful data about uGuru, as it is the program inside the uC that is responding to calls. Olle Sandberg <ollebull@gmail.com>, 2005-05-25 @@ -41,7 +41,7 @@ later on attached again data-port will hold 0x08, more about this later. After wider testing of the Linux kernel driver some variants of the uGuru have turned up which will hold 0x00 instead of 0xAC at the CMD port, thus we also -have to test CMD for two different values. On these uGuru's DATA will initally +have to test CMD for two different values. On these uGuru's DATA will initially hold 0x09 and will only hold 0x08 after reading CMD first, so CMD must be read first! @@ -308,5 +308,5 @@ the voltage / clock programming out, I tried reading and only reading banks resulted in a _permanent_ reprogramming of the voltages, luckily I had the sensors part configured so that it would shutdown my system on any out of spec voltages which proprably safed my computer (after a reboot I managed to -immediatly enter the bios and reload the defaults). This probably means that +immediately enter the bios and reload the defaults). This probably means that the read/write cycle for the non sensor part is different from the sensor part. diff --git a/Documentation/hwmon/abituguru3 b/Documentation/hwmon/abituguru3 index fa598aac22fa..a6ccfe4bb6aa 100644 --- a/Documentation/hwmon/abituguru3 +++ b/Documentation/hwmon/abituguru3 @@ -47,7 +47,7 @@ This driver supports the hardware monitoring features of the third revision of the Abit uGuru chip, found on recent Abit uGuru featuring motherboards. The 3rd revision of the uGuru chip in reality is a Winbond W83L951G. -Unfortunatly this doesn't help since the W83L951G is a generic microcontroller +Unfortunately this doesn't help since the W83L951G is a generic microcontroller with a custom Abit application running on it. Despite Abit not releasing any information regarding the uGuru revision 3, diff --git a/Documentation/hwmon/adm9240 b/Documentation/hwmon/adm9240 index 2c6f1fed4618..36e8ec6aa868 100644 --- a/Documentation/hwmon/adm9240 +++ b/Documentation/hwmon/adm9240 @@ -155,7 +155,7 @@ connected to a normally open switch. The ADM9240 provides an internal open drain on this line, and may output a 20 ms active low pulse to reset an external Chassis Intrusion latch. -Clear the CI latch by writing value 1 to the sysfs chassis_clear file. +Clear the CI latch by writing value 0 to the sysfs intrusion0_alarm file. Alarm flags reported as 16-bit word diff --git a/Documentation/hwmon/ads1015 b/Documentation/hwmon/ads1015 new file mode 100644 index 000000000000..f6fe9c203733 --- /dev/null +++ b/Documentation/hwmon/ads1015 @@ -0,0 +1,72 @@ +Kernel driver ads1015 +===================== + +Supported chips: + * Texas Instruments ADS1015 + Prefix: 'ads1015' + Datasheet: Publicly available at the Texas Instruments website : + http://focus.ti.com/lit/ds/symlink/ads1015.pdf + +Authors: + Dirk Eibach, Guntermann & Drunck GmbH <eibach@gdsys.de> + +Description +----------- + +This driver implements support for the Texas Instruments ADS1015. + +This device is a 12-bit A-D converter with 4 inputs. + +The inputs can be used single ended or in certain differential combinations. + +The inputs can be made available by 8 sysfs input files in0_input - in7_input: +in0: Voltage over AIN0 and AIN1. +in1: Voltage over AIN0 and AIN3. +in2: Voltage over AIN1 and AIN3. +in3: Voltage over AIN2 and AIN3. +in4: Voltage over AIN0 and GND. +in5: Voltage over AIN1 and GND. +in6: Voltage over AIN2 and GND. +in7: Voltage over AIN3 and GND. + +Which inputs are available can be configured using platform data or devicetree. + +By default all inputs are exported. + +Platform Data +------------- + +In linux/i2c/ads1015.h platform data is defined, channel_data contains +configuration data for the used input combinations: +- pga is the programmable gain amplifier (values are full scale) + 0: +/- 6.144 V + 1: +/- 4.096 V + 2: +/- 2.048 V + 3: +/- 1.024 V + 4: +/- 0.512 V + 5: +/- 0.256 V +- data_rate in samples per second + 0: 128 + 1: 250 + 2: 490 + 3: 920 + 4: 1600 + 5: 2400 + 6: 3300 + +Example: +struct ads1015_platform_data data = { + .channel_data = { + [2] = { .enabled = true, .pga = 1, .data_rate = 0 }, + [4] = { .enabled = true, .pga = 4, .data_rate = 5 }, + } +}; + +In this case only in2_input (FS +/- 4.096 V, 128 SPS) and in4_input +(FS +/- 0.512 V, 2400 SPS) would be created. + +Devicetree +---------- + +Configuration is also possible via devicetree: +Documentation/devicetree/bindings/hwmon/ads1015.txt diff --git a/Documentation/hwmon/ads7828 b/Documentation/hwmon/ads7828 index 75bc4beaf447..2bbebe6f771f 100644 --- a/Documentation/hwmon/ads7828 +++ b/Documentation/hwmon/ads7828 @@ -9,7 +9,7 @@ Supported chips: http://focus.ti.com/lit/ds/symlink/ads7828.pdf Authors: - Steve Hardy <steve@linuxrealtime.co.uk> + Steve Hardy <shardy@redhat.com> Module Parameters ----------------- diff --git a/Documentation/hwmon/dme1737 b/Documentation/hwmon/dme1737 index fc5df7654d63..4d2935145a1c 100644 --- a/Documentation/hwmon/dme1737 +++ b/Documentation/hwmon/dme1737 @@ -42,7 +42,7 @@ Description This driver implements support for the hardware monitoring capabilities of the SMSC DME1737 and Asus A8000 (which are the same), SMSC SCH5027, SCH311x, and SCH5127 Super-I/O chips. These chips feature monitoring of 3 temp sensors -temp[1-3] (2 remote diodes and 1 internal), 7 voltages in[0-6] (6 external and +temp[1-3] (2 remote diodes and 1 internal), 8 voltages in[0-7] (7 external and 1 internal) and up to 6 fan speeds fan[1-6]. Additionally, the chips implement up to 5 PWM outputs pwm[1-3,5-6] for controlling fan speeds both manually and automatically. @@ -105,6 +105,7 @@ SCH5127: in4: V1_IN 0V - 1.5V in5: VTR (+3.3V standby) 0V - 4.38V in6: Vbat (+3.0V) 0V - 4.38V + in7: Vtrip (+1.5V) 0V - 1.99V Each voltage input has associated min and max limits which trigger an alarm when crossed. @@ -217,10 +218,10 @@ cpu0_vid RO CPU core reference voltage in vrm RW Voltage regulator module version number. -in[0-6]_input RO Measured voltage in millivolts. -in[0-6]_min RW Low limit for voltage input. -in[0-6]_max RW High limit for voltage input. -in[0-6]_alarm RO Voltage input alarm. Returns 1 if +in[0-7]_input RO Measured voltage in millivolts. +in[0-7]_min RW Low limit for voltage input. +in[0-7]_max RW High limit for voltage input. +in[0-7]_alarm RO Voltage input alarm. Returns 1 if voltage input is or went outside the associated min-max range, 0 otherwise. @@ -324,3 +325,4 @@ fan5 opt opt pwm5 opt opt fan6 opt opt pwm6 opt opt +in7 yes diff --git a/Documentation/hwmon/ds620 b/Documentation/hwmon/ds620 new file mode 100644 index 000000000000..1fbe3cd916cc --- /dev/null +++ b/Documentation/hwmon/ds620 @@ -0,0 +1,34 @@ +Kernel driver ds620 +=================== + +Supported chips: + * Dallas Semiconductor DS620 + Prefix: 'ds620' + Datasheet: Publicly available at the Dallas Semiconductor website + http://www.dalsemi.com/ + +Authors: + Roland Stigge <stigge@antcom.de> + based on ds1621.c by + Christian W. Zuckschwerdt <zany@triq.net> + +Description +----------- + +The DS620 is a (one instance) digital thermometer and thermostat. It has both +high and low temperature limits which can be user defined (i.e. programmed +into non-volatile on-chip registers). Temperature range is -55 degree Celsius +to +125. Between 0 and 70 degree Celsius, accuracy is 0.5 Kelvin. The value +returned via sysfs displays post decimal positions. + +The thermostat function works as follows: When configured via platform_data +(struct ds620_platform_data) .pomode == 0 (default), the thermostat output pin +PO is always low. If .pomode == 1, the thermostat is in PO_LOW mode. I.e., the +output pin PO becomes active when the temperature falls below temp1_min and +stays active until the temperature goes above temp1_max. + +Likewise, with .pomode == 2, the thermostat is in PO_HIGH mode. I.e., the PO +output pin becomes active when the temperature goes above temp1_max and stays +active until the temperature falls below temp1_min. + +The PO output pin of the DS620 operates active-low. diff --git a/Documentation/hwmon/f71882fg b/Documentation/hwmon/f71882fg index a7952c2bd959..df02245d1419 100644 --- a/Documentation/hwmon/f71882fg +++ b/Documentation/hwmon/f71882fg @@ -2,6 +2,10 @@ Kernel driver f71882fg ====================== Supported chips: + * Fintek F71808E + Prefix: 'f71808e' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Not public * Fintek F71858FG Prefix: 'f71858fg' Addresses scanned: none, address read from Super I/O config space @@ -10,6 +14,10 @@ Supported chips: Prefix: 'f71862fg' Addresses scanned: none, address read from Super I/O config space Datasheet: Available from the Fintek website + * Fintek F71869F and F71869E + Prefix: 'f71869' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website * Fintek F71882FG and F71883FG Prefix: 'f71882fg' Addresses scanned: none, address read from Super I/O config space @@ -17,11 +25,30 @@ Supported chips: * Fintek F71889FG Prefix: 'f71889fg' Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website + * Fintek F71889ED + Prefix: 'f71889ed' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Should become available on the Fintek website soon + * Fintek F71889A + Prefix: 'f71889a' + Addresses scanned: none, address read from Super I/O config space Datasheet: Should become available on the Fintek website soon * Fintek F8000 Prefix: 'f8000' Addresses scanned: none, address read from Super I/O config space Datasheet: Not public + * Fintek F81801U + Prefix: 'f71889fg' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Not public + Note: This is the 64-pin variant of the F71889FG, they have the + same device ID and are fully compatible as far as hardware + monitoring is concerned. + * Fintek F81865F + Prefix: 'f81865f' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website Author: Hans de Goede <hdegoede@redhat.com> @@ -29,9 +56,9 @@ Author: Hans de Goede <hdegoede@redhat.com> Description ----------- -Fintek F718xxFG/F8000 Super I/O chips include complete hardware monitoring -capabilities. They can monitor up to 9 voltages (3 for the F8000), 4 fans and -3 temperature sensors. +Fintek F718xx/F8000 Super I/O chips include complete hardware monitoring +capabilities. They can monitor up to 9 voltages, 4 fans and 3 temperature +sensors. These chips also have fan controlling features, using either DC or PWM, in three different modes (one manual, two automatic). @@ -99,5 +126,5 @@ Writing an unsupported mode will result in an invalid parameter error. The fan speed is regulated to keep the temp the fan is mapped to between temp#_auto_point2_temp and temp#_auto_point3_temp. -Both of the automatic modes require that pwm1 corresponds to fan1, pwm2 to +All of the automatic modes require that pwm1 corresponds to fan1, pwm2 to fan2 and pwm3 to fan3. diff --git a/Documentation/hwmon/it87 b/Documentation/hwmon/it87 index 8d08bf0d38ed..38425f0f2645 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 index 0e76ef12e4c6..a22ecf48f255 100644 --- a/Documentation/hwmon/jc42 +++ b/Documentation/hwmon/jc42 @@ -51,7 +51,8 @@ Supported chips: * JEDEC JC 42.4 compliant temperature sensor chips Prefix: 'jc42' Addresses scanned: I2C 0x18 - 0x1f - Datasheet: - + Datasheet: + http://www.jedec.org/sites/default/files/docs/4_01_04R19.pdf Author: Guenter Roeck <guenter.roeck@ericsson.com> @@ -60,7 +61,11 @@ Author: Description ----------- -This driver implements support for JEDEC JC 42.4 compliant temperature sensors. +This driver implements support for JEDEC JC 42.4 compliant temperature sensors, +which are used on many DDR3 memory modules for mobile devices and servers. Some +systems use the sensor to prevent memory overheating by automatically throttling +the memory controller. + The driver auto-detects the chips listed above, but can be manually instantiated to support other JC 42.4 compliant chips. @@ -81,15 +86,19 @@ 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. +If the BIOS has configured the sensor for automatic temperature management, it +is likely that it has locked the registers, i.e., that the temperature limits +cannot be changed. + Sysfs entries ------------- temp1_input Temperature (RO) -temp1_min Minimum temperature (RW) -temp1_max Maximum temperature (RW) -temp1_crit Critical high temperature (RW) +temp1_min Minimum temperature (RO or RW) +temp1_max Maximum temperature (RO or RW) +temp1_crit Critical high temperature (RO or RW) -temp1_crit_hyst Critical hysteresis temperature (RW) +temp1_crit_hyst Critical hysteresis temperature (RO or RW) temp1_max_hyst Maximum hysteresis temperature (RO) temp1_min_alarm Temperature low alarm diff --git a/Documentation/hwmon/k10temp b/Documentation/hwmon/k10temp index 6526eee525a6..0393c89277c0 100644 --- a/Documentation/hwmon/k10temp +++ b/Documentation/hwmon/k10temp @@ -9,6 +9,9 @@ Supported chips: Socket S1G3: Athlon II, Sempron, Turion II * AMD Family 11h processors: Socket S1G2: Athlon (X2), Sempron (X2), Turion X2 (Ultra) +* AMD Family 12h processors: "Llano" +* AMD Family 14h processors: "Brazos" (C/E/G-Series) +* AMD Family 15h processors: "Bulldozer" Prefix: 'k10temp' Addresses scanned: PCI space @@ -17,10 +20,14 @@ Supported chips: http://support.amd.com/us/Processor_TechDocs/31116.pdf BIOS and Kernel Developer's Guide (BKDG) for AMD Family 11h Processors: http://support.amd.com/us/Processor_TechDocs/41256.pdf + BIOS and Kernel Developer's Guide (BKDG) for AMD Family 14h Models 00h-0Fh Processors: + http://support.amd.com/us/Processor_TechDocs/43170.pdf Revision Guide for AMD Family 10h Processors: http://support.amd.com/us/Processor_TechDocs/41322.pdf Revision Guide for AMD Family 11h Processors: http://support.amd.com/us/Processor_TechDocs/41788.pdf + Revision Guide for AMD Family 14h Models 00h-0Fh Processors: + http://support.amd.com/us/Processor_TechDocs/47534.pdf AMD Family 11h Processor Power and Thermal Data Sheet for Notebooks: http://support.amd.com/us/Processor_TechDocs/43373.pdf AMD Family 10h Server and Workstation Processor Power and Thermal Data Sheet: @@ -34,7 +41,7 @@ Description ----------- This driver permits reading of the internal temperature sensor of AMD -Family 10h and 11h processors. +Family 10h/11h/12h/14h/15h processors. All these processors have a sensor, but on those for Socket F or AM2+, the sensor may return inconsistent values (erratum 319). The driver diff --git a/Documentation/hwmon/lineage-pem b/Documentation/hwmon/lineage-pem new file mode 100644 index 000000000000..2ba5ed126858 --- /dev/null +++ b/Documentation/hwmon/lineage-pem @@ -0,0 +1,77 @@ +Kernel driver lineage-pem +========================= + +Supported devices: + * Lineage Compact Power Line Power Entry Modules + Prefix: 'lineage-pem' + Addresses scanned: - + Documentation: + http://www.lineagepower.com/oem/pdf/CPLI2C.pdf + +Author: Guenter Roeck <guenter.roeck@ericsson.com> + + +Description +----------- + +This driver supports various Lineage Compact Power Line DC/DC and AC/DC +converters such as CP1800, CP2000AC, CP2000DC, CP2100DC, and others. + +Lineage CPL power entry modules are nominally PMBus compliant. However, most +standard PMBus commands are not supported. Specifically, all hardware monitoring +and status reporting commands are non-standard. For this reason, a standard +PMBus driver can not be used. + + +Usage Notes +----------- + +This driver does not probe for Lineage CPL 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 a Lineage PEM at address 0x40 +on I2C bus #1: +$ modprobe lineage-pem +$ echo lineage-pem 0x40 > /sys/bus/i2c/devices/i2c-1/new_device + +All Lineage CPL power entry modules have a built-in I2C bus master selector +(PCA9541). To ensure device access, this driver should only be used as client +driver to the pca9541 I2C master selector driver. + + +Sysfs entries +------------- + +All Lineage CPL devices report output voltage and device temperature as well as +alarms for output voltage, temperature, input voltage, input current, input power, +and fan status. + +Input voltage, input current, input power, and fan speed measurement is only +supported on newer devices. The driver detects if those attributes are supported, +and only creates respective sysfs entries if they are. + +in1_input Output voltage (mV) +in1_min_alarm Output undervoltage alarm +in1_max_alarm Output overvoltage alarm +in1_crit Output voltage critical alarm + +in2_input Input voltage (mV, optional) +in2_alarm Input voltage alarm + +curr1_input Input current (mA, optional) +curr1_alarm Input overcurrent alarm + +power1_input Input power (uW, optional) +power1_alarm Input power alarm + +fan1_input Fan 1 speed (rpm, optional) +fan2_input Fan 2 speed (rpm, optional) +fan3_input Fan 3 speed (rpm, optional) + +temp1_input +temp1_max +temp1_crit +temp1_alarm +temp1_crit_alarm +temp1_fault diff --git a/Documentation/hwmon/lm75 b/Documentation/hwmon/lm75 index 8e6356fe05d7..a1790401fdde 100644 --- a/Documentation/hwmon/lm75 +++ b/Documentation/hwmon/lm75 @@ -7,6 +7,11 @@ Supported chips: Addresses scanned: I2C 0x48 - 0x4f Datasheet: Publicly available at the National Semiconductor website http://www.national.com/ + * National Semiconductor LM75A + Prefix: 'lm75a' + Addresses scanned: I2C 0x48 - 0x4f + Datasheet: Publicly available at the National Semiconductor website + http://www.national.com/ * Dallas Semiconductor DS75 Prefix: 'lm75' Addresses scanned: I2C 0x48 - 0x4f diff --git a/Documentation/hwmon/lm85 b/Documentation/hwmon/lm85 index b98e0e0d1910..7c49feaa79d2 100644 --- a/Documentation/hwmon/lm85 +++ b/Documentation/hwmon/lm85 @@ -14,6 +14,10 @@ Supported chips: Prefix: 'adt7463' Addresses scanned: I2C 0x2c, 0x2d, 0x2e 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 @@ -22,6 +26,14 @@ Supported chips: Prefix: 'emc6d102' Addresses scanned: I2C 0x2c, 0x2d, 0x2e Datasheet: http://www.smsc.com/main/catalog/emc6d102.html + * SMSC EMC6D103 + Prefix: 'emc6d103' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.smsc.com/main/catalog/emc6d103.html + * SMSC EMC6D103S + Prefix: 'emc6d103s' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.smsc.com/main/catalog/emc6d103s.html Authors: Philip Pokorny <ppokorny@penguincomputing.com>, @@ -34,7 +46,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 +99,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. @@ -110,9 +130,11 @@ to be register compatible. The EMC6D100 offers all the features of the EMC6D101 plus additional voltage monitoring and system control features. Unfortunately it is not possible to distinguish between the package versions on register level so these additional voltage inputs may read -zero. The EMC6D102 features addtional ADC bits thus extending precision +zero. EMC6D102 and EMC6D103 feature additional ADC bits thus extending precision of voltage and temperature channels. +SMSC EMC6D103S is similar to EMC6D103, but does not support pwm#_auto_pwm_minctl +and temp#_auto_temp_off. Hardware Configurations ----------------------- @@ -125,17 +147,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 +223,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 6a03dd4bcc94..f3efd18e87f4 100644 --- a/Documentation/hwmon/lm90 +++ b/Documentation/hwmon/lm90 @@ -32,6 +32,16 @@ Supported chips: Addresses scanned: I2C 0x4c and 0x4d Datasheet: Publicly available at the ON Semiconductor website http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461 + * Analog Devices ADT7461A + Prefix: 'adt7461a' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: Publicly available at the ON Semiconductor website + http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461A + * ON Semiconductor NCT1008 + Prefix: 'nct1008' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: Publicly available at the ON Semiconductor website + http://www.onsemi.com/PowerSolutions/product.do?id=NCT1008 * Maxim MAX6646 Prefix: 'max6646' Addresses scanned: I2C 0x4d @@ -63,8 +73,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 +94,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 +126,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 @@ -133,7 +159,7 @@ ADM1032: * ALERT is triggered by open remote sensor. * SMBus PEC support for Write Byte and Receive Byte transactions. -ADT7461: +ADT7461, ADT7461A, NCT1008: * Extended temperature range (breaks compatibility) * Lower resolution for remote temperature @@ -151,11 +177,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 @@ -169,9 +205,9 @@ are exported, one for each channel, but these values are of course linked. Only the local hysteresis can be set from user-space, and the same delta applies to the remote hysteresis. -The lm90 driver will not update its values more frequently than every -other second; reading them more often will do no harm, but will return -'old' values. +The lm90 driver will not update its values more frequently than configured with +the update_interval attribute; reading them more often will do no harm, but will +return 'old' values. SMBus Alert Support ------------------- @@ -179,11 +215,12 @@ SMBus Alert Support This driver has basic support for SMBus alert. When an alert is received, the status register is read and the faulty temperature channel is logged. -The Analog Devices chips (ADM1032 and ADT7461) do not implement the SMBus -alert protocol properly so additional care is needed: the ALERT output is -disabled when an alert is received, and is re-enabled only when the alarm -is gone. Otherwise the chip would block alerts from other chips in the bus -as long as the alarm is active. +The Analog Devices chips (ADM1032, ADT7461 and ADT7461A) and ON +Semiconductor chips (NCT1008) do not implement the SMBus alert protocol +properly so additional care is needed: the ALERT output is disabled when +an alert is received, and is re-enabled only when the alarm is gone. +Otherwise the chip would block alerts from other chips in the bus as long +as the alarm is active. PEC Support ----------- diff --git a/Documentation/hwmon/lm93 b/Documentation/hwmon/lm93 index ac711f357faf..f3b2ad2ceb01 100644 --- a/Documentation/hwmon/lm93 +++ b/Documentation/hwmon/lm93 @@ -6,12 +6,16 @@ Supported chips: Prefix 'lm93' Addresses scanned: I2C 0x2c-0x2e Datasheet: http://www.national.com/ds.cgi/LM/LM93.pdf + * National Semiconductor LM94 + Prefix 'lm94' + Addresses scanned: I2C 0x2c-0x2e + Datasheet: http://www.national.com/ds.cgi/LM/LM94.pdf Authors: Mark M. Hoffman <mhoffman@lightlink.com> Ported to 2.6 by Eric J. Bowersox <ericb@aspsys.com> Adapted to 2.6.20 by Carsten Emde <ce@osadl.org> - Modified for mainline integration by Hans J. Koch <hjk@linutronix.de> + Modified for mainline integration by Hans J. Koch <hjk@hansjkoch.de> Module Parameters ----------------- @@ -56,6 +60,9 @@ previous motherboard management ASICs and uses some of the LM85's features for dynamic Vccp monitoring and PROCHOT. It is designed to monitor a dual processor Xeon class motherboard with a minimum of external components. +LM94 is also supported in LM93 compatible mode. Extra sensors and features of +LM94 are not supported. + User Interface -------------- diff --git a/Documentation/hwmon/ltc4151 b/Documentation/hwmon/ltc4151 new file mode 100644 index 000000000000..43c667e6677a --- /dev/null +++ b/Documentation/hwmon/ltc4151 @@ -0,0 +1,47 @@ +Kernel driver ltc4151 +===================== + +Supported chips: + * Linear Technology LTC4151 + Prefix: 'ltc4151' + Addresses scanned: - + Datasheet: + http://www.linear.com/docs/Datasheet/4151fc.pdf + +Author: Per Dalen <per.dalen@appeartv.com> + + +Description +----------- + +The LTC4151 is a High Voltage I2C Current and Voltage Monitor. + + +Usage Notes +----------- + +This driver does not probe for LTC4151 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 LTC4151 at address 0x6f +on I2C bus #0: +# modprobe ltc4151 +# echo ltc4151 0x6f > /sys/bus/i2c/devices/i2c-0/new_device + + +Sysfs entries +------------- + +Voltage readings provided by this driver are reported as obtained from the ADIN +and VIN registers. + +Current reading provided by this driver is reported as obtained from the Current +Sense register. The reported value assumes that a 1 mOhm sense resistor is +installed. + +in1_input VDIN voltage (mV) + +in2_input ADIN voltage (mV) + +curr1_input SENSE current (mA) diff --git a/Documentation/hwmon/ltc4261 b/Documentation/hwmon/ltc4261 new file mode 100644 index 000000000000..eba2e2c4b94d --- /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/max6639 b/Documentation/hwmon/max6639 new file mode 100644 index 000000000000..dc49f8be7167 --- /dev/null +++ b/Documentation/hwmon/max6639 @@ -0,0 +1,49 @@ +Kernel driver max6639 +===================== + +Supported chips: + * Maxim MAX6639 + Prefix: 'max6639' + Addresses scanned: I2C 0x2c, 0x2e, 0x2f + Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6639.pdf + +Authors: + He Changqing <hechangqing@semptian.com> + Roland Stigge <stigge@antcom.de> + +Description +----------- + +This driver implements support for the Maxim MAX6639. This chip is a 2-channel +temperature monitor with dual PWM fan speed controller. It can monitor its own +temperature and one external diode-connected transistor or two external +diode-connected transistors. + +The following device attributes are implemented via sysfs: + +Attribute R/W Contents +---------------------------------------------------------------------------- +temp1_input R Temperature channel 1 input (0..150 C) +temp2_input R Temperature channel 2 input (0..150 C) +temp1_fault R Temperature channel 1 diode fault +temp2_fault R Temperature channel 2 diode fault +temp1_max RW Set THERM temperature for input 1 + (in C, see datasheet) +temp2_max RW Set THERM temperature for input 2 +temp1_crit RW Set ALERT temperature for input 1 +temp2_crit RW Set ALERT temperature for input 2 +temp1_emergency RW Set OT temperature for input 1 + (in C, see datasheet) +temp2_emergency RW Set OT temperature for input 2 +pwm1 RW Fan 1 target duty cycle (0..255) +pwm2 RW Fan 2 target duty cycle (0..255) +fan1_input R TACH1 fan tachometer input (in RPM) +fan2_input R TACH2 fan tachometer input (in RPM) +fan1_fault R Fan 1 fault +fan2_fault R Fan 2 fault +temp1_max_alarm R Alarm on THERM temperature on channel 1 +temp2_max_alarm R Alarm on THERM temperature on channel 2 +temp1_crit_alarm R Alarm on ALERT temperature on channel 1 +temp2_crit_alarm R Alarm on ALERT temperature on channel 2 +temp1_emergency_alarm R Alarm on OT temperature on channel 1 +temp2_emergency_alarm R Alarm on OT temperature on channel 2 diff --git a/Documentation/hwmon/max6642 b/Documentation/hwmon/max6642 new file mode 100644 index 000000000000..afbd3e4942e2 --- /dev/null +++ b/Documentation/hwmon/max6642 @@ -0,0 +1,21 @@ +Kernel driver max6642 +===================== + +Supported chips: + * Maxim MAX6642 + Prefix: 'max6642' + Addresses scanned: I2C 0x48-0x4f + Datasheet: Publicly available at the Maxim website + http://datasheets.maxim-ic.com/en/ds/MAX6642.pdf + +Authors: + Per Dalen <per.dalen@appeartv.com> + +Description +----------- + +The MAX6642 is a digital temperature sensor. It senses its own temperature as +well as the temperature on one external diode. + +All temperature values are given in degrees Celsius. Resolution +is 0.25 degree for the local temperature and for the remote temperature. diff --git a/Documentation/hwmon/max6650 b/Documentation/hwmon/max6650 index 8be7beb9e3e8..c565650fcfc6 100644 --- a/Documentation/hwmon/max6650 +++ b/Documentation/hwmon/max6650 @@ -8,7 +8,7 @@ Supported chips: Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6650-MAX6651.pdf Authors: - Hans J. Koch <hjk@linutronix.de> + Hans J. Koch <hjk@hansjkoch.de> John Morris <john.morris@spirentcom.com> Claus Gindhart <claus.gindhart@kontron.com> diff --git a/Documentation/hwmon/pcf8591 b/Documentation/hwmon/pcf8591 index e76a7892f68e..ac020b3bb7b3 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/pmbus b/Documentation/hwmon/pmbus new file mode 100644 index 000000000000..dc4933e96344 --- /dev/null +++ b/Documentation/hwmon/pmbus @@ -0,0 +1,215 @@ +Kernel driver pmbus +==================== + +Supported chips: + * Ericsson BMR45X series + DC/DC Converter + Prefixes: 'bmr450', 'bmr451', 'bmr453', 'bmr454' + Addresses scanned: - + Datasheet: + http://archive.ericsson.net/service/internet/picov/get?DocNo=28701-EN/LZT146395 + * Linear Technology LTC2978 + Octal PMBus Power Supply Monitor and Controller + Prefix: 'ltc2978' + Addresses scanned: - + Datasheet: http://cds.linear.com/docs/Datasheet/2978fa.pdf + * Maxim MAX16064 + Quad Power-Supply Controller + Prefix: 'max16064' + Addresses scanned: - + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX16064.pdf + * Maxim MAX34440 + PMBus 6-Channel Power-Supply Manager + Prefixes: 'max34440' + Addresses scanned: - + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX34440.pdf + * Maxim MAX34441 + PMBus 5-Channel Power-Supply Manager and Intelligent Fan Controller + Prefixes: 'max34441' + Addresses scanned: - + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX34441.pdf + * Maxim MAX8688 + Digital Power-Supply Controller/Monitor + Prefix: 'max8688' + Addresses scanned: - + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX8688.pdf + * Generic PMBus devices + Prefix: 'pmbus' + Addresses scanned: - + Datasheet: n.a. + +Author: Guenter Roeck <guenter.roeck@ericsson.com> + + +Description +----------- + +This driver supports hardware montoring for various PMBus compliant devices. +It supports voltage, current, power, and temperature sensors as supported +by the device. + +Each monitored channel has its own high and low limits, plus a critical +limit. + +Fan support will be added in a later version of this driver. + + +Usage Notes +----------- + +This driver does not probe for PMBus devices, since there is no register +which can be safely used to identify the chip (The MFG_ID register is not +supported by all chips), and since there is no well defined address range for +PMBus devices. You will have to instantiate the devices explicitly. + +Example: the following will load the driver for an LTC2978 at address 0x60 +on I2C bus #1: +$ modprobe pmbus +$ echo ltc2978 0x60 > /sys/bus/i2c/devices/i2c-1/new_device + + +Platform data support +--------------------- + +Support for additional PMBus chips can be added by defining chip parameters in +a new chip specific driver file. For example, (untested) code to add support for +Emerson DS1200 power modules might look as follows. + +static struct pmbus_driver_info ds1200_info = { + .pages = 1, + /* Note: All other sensors are in linear mode */ + .direct[PSC_VOLTAGE_OUT] = true, + .direct[PSC_TEMPERATURE] = true, + .direct[PSC_CURRENT_OUT] = true, + .m[PSC_VOLTAGE_IN] = 1, + .b[PSC_VOLTAGE_IN] = 0, + .R[PSC_VOLTAGE_IN] = 3, + .m[PSC_VOLTAGE_OUT] = 1, + .b[PSC_VOLTAGE_OUT] = 0, + .R[PSC_VOLTAGE_OUT] = 3, + .m[PSC_TEMPERATURE] = 1, + .b[PSC_TEMPERATURE] = 0, + .R[PSC_TEMPERATURE] = 3, + .func[0] = PMBUS_HAVE_VIN | PMBUS_HAVE_IIN | PMBUS_HAVE_STATUS_INPUT + | PMBUS_HAVE_VOUT | PMBUS_HAVE_STATUS_VOUT + | PMBUS_HAVE_IOUT | PMBUS_HAVE_STATUS_IOUT + | PMBUS_HAVE_PIN | PMBUS_HAVE_POUT + | PMBUS_HAVE_TEMP | PMBUS_HAVE_STATUS_TEMP + | PMBUS_HAVE_FAN12 | PMBUS_HAVE_STATUS_FAN12, +}; + +static int ds1200_probe(struct i2c_client *client, + const struct i2c_device_id *id) +{ + return pmbus_do_probe(client, id, &ds1200_info); +} + +static int ds1200_remove(struct i2c_client *client) +{ + return pmbus_do_remove(client); +} + +static const struct i2c_device_id ds1200_id[] = { + {"ds1200", 0}, + {} +}; + +MODULE_DEVICE_TABLE(i2c, ds1200_id); + +/* This is the driver that will be inserted */ +static struct i2c_driver ds1200_driver = { + .driver = { + .name = "ds1200", + }, + .probe = ds1200_probe, + .remove = ds1200_remove, + .id_table = ds1200_id, +}; + +static int __init ds1200_init(void) +{ + return i2c_add_driver(&ds1200_driver); +} + +static void __exit ds1200_exit(void) +{ + i2c_del_driver(&ds1200_driver); +} + + +Sysfs entries +------------- + +When probing the chip, the driver identifies which PMBus registers are +supported, and determines available sensors from this information. +Attribute files only exist if respective sensors are suported by the chip. +Labels are provided to inform the user about the sensor associated with +a given sysfs entry. + +The following attributes are supported. Limits are read-write; all other +attributes are read-only. + +inX_input Measured voltage. From READ_VIN or READ_VOUT register. +inX_min Minimum Voltage. + From VIN_UV_WARN_LIMIT or VOUT_UV_WARN_LIMIT register. +inX_max Maximum voltage. + From VIN_OV_WARN_LIMIT or VOUT_OV_WARN_LIMIT register. +inX_lcrit Critical minimum Voltage. + From VIN_UV_FAULT_LIMIT or VOUT_UV_FAULT_LIMIT register. +inX_crit Critical maximum voltage. + From VIN_OV_FAULT_LIMIT or VOUT_OV_FAULT_LIMIT register. +inX_min_alarm Voltage low alarm. From VOLTAGE_UV_WARNING status. +inX_max_alarm Voltage high alarm. From VOLTAGE_OV_WARNING status. +inX_lcrit_alarm Voltage critical low alarm. + From VOLTAGE_UV_FAULT status. +inX_crit_alarm Voltage critical high alarm. + From VOLTAGE_OV_FAULT status. +inX_label "vin", "vcap", or "voutY" + +currX_input Measured current. From READ_IIN or READ_IOUT register. +currX_max Maximum current. + From IIN_OC_WARN_LIMIT or IOUT_OC_WARN_LIMIT register. +currX_lcrit Critical minimum output current. + From IOUT_UC_FAULT_LIMIT register. +currX_crit Critical maximum current. + From IIN_OC_FAULT_LIMIT or IOUT_OC_FAULT_LIMIT register. +currX_alarm Current high alarm. + From IIN_OC_WARNING or IOUT_OC_WARNING status. +currX_lcrit_alarm Output current critical low alarm. + From IOUT_UC_FAULT status. +currX_crit_alarm Current critical high alarm. + From IIN_OC_FAULT or IOUT_OC_FAULT status. +currX_label "iin" or "vinY" + +powerX_input Measured power. From READ_PIN or READ_POUT register. +powerX_cap Output power cap. From POUT_MAX register. +powerX_max Power limit. From PIN_OP_WARN_LIMIT or + POUT_OP_WARN_LIMIT register. +powerX_crit Critical output power limit. + From POUT_OP_FAULT_LIMIT register. +powerX_alarm Power high alarm. + From PIN_OP_WARNING or POUT_OP_WARNING status. +powerX_crit_alarm Output power critical high alarm. + From POUT_OP_FAULT status. +powerX_label "pin" or "poutY" + +tempX_input Measured tempererature. + From READ_TEMPERATURE_X register. +tempX_min Mimimum tempererature. From UT_WARN_LIMIT register. +tempX_max Maximum tempererature. From OT_WARN_LIMIT register. +tempX_lcrit Critical low tempererature. + From UT_FAULT_LIMIT register. +tempX_crit Critical high tempererature. + From OT_FAULT_LIMIT register. +tempX_min_alarm Chip temperature low alarm. Set by comparing + READ_TEMPERATURE_X with UT_WARN_LIMIT if + TEMP_UT_WARNING status is set. +tempX_max_alarm Chip temperature high alarm. Set by comparing + READ_TEMPERATURE_X with OT_WARN_LIMIT if + TEMP_OT_WARNING status is set. +tempX_lcrit_alarm Chip temperature critical low alarm. Set by comparing + READ_TEMPERATURE_X with UT_FAULT_LIMIT if + TEMP_UT_FAULT status is set. +tempX_crit_alarm Chip temperature critical high alarm. Set by comparing + READ_TEMPERATURE_X with OT_FAULT_LIMIT if + TEMP_OT_FAULT status is set. diff --git a/Documentation/hwmon/sch5627 b/Documentation/hwmon/sch5627 new file mode 100644 index 000000000000..446a054e4912 --- /dev/null +++ b/Documentation/hwmon/sch5627 @@ -0,0 +1,22 @@ +Kernel driver sch5627 +===================== + +Supported chips: + * SMSC SCH5627 + Prefix: 'sch5627' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Application Note available upon request + +Author: Hans de Goede <hdegoede@redhat.com> + + +Description +----------- + +SMSC SCH5627 Super I/O chips include complete hardware monitoring +capabilities. They can monitor up to 5 voltages, 4 fans and 8 temperatures. + +The hardware monitoring part of the SMSC SCH5627 is accessed by talking +through an embedded microcontroller. An application note describing the +protocol for communicating with the microcontroller is available upon +request. Please mail me if you want a copy. diff --git a/Documentation/hwmon/sht21 b/Documentation/hwmon/sht21 new file mode 100644 index 000000000000..db17fda45c3e --- /dev/null +++ b/Documentation/hwmon/sht21 @@ -0,0 +1,49 @@ +Kernel driver sht21 +=================== + +Supported chips: + * Sensirion SHT21 + Prefix: 'sht21' + Addresses scanned: none + Datasheet: Publicly available at the Sensirion website + http://www.sensirion.com/en/pdf/product_information/Datasheet-humidity-sensor-SHT21.pdf + + * Sensirion SHT25 + Prefix: 'sht21' + Addresses scanned: none + Datasheet: Publicly available at the Sensirion website + http://www.sensirion.com/en/pdf/product_information/Datasheet-humidity-sensor-SHT25.pdf + +Author: + Urs Fleisch <urs.fleisch@sensirion.com> + +Description +----------- + +The SHT21 and SHT25 are humidity and temperature sensors in a DFN package of +only 3 x 3 mm footprint and 1.1 mm height. The difference between the two +devices is the higher level of precision of the SHT25 (1.8% relative humidity, +0.2 degree Celsius) compared with the SHT21 (2.0% relative humidity, +0.3 degree Celsius). + +The devices communicate with the I2C protocol. All sensors are set to the same +I2C address 0x40, so an entry with I2C_BOARD_INFO("sht21", 0x40) can be used +in the board setup code. + +sysfs-Interface +--------------- + +temp1_input - temperature input +humidity1_input - humidity input + +Notes +----- + +The driver uses the default resolution settings of 12 bit for humidity and 14 +bit for temperature, which results in typical measurement times of 22 ms for +humidity and 66 ms for temperature. To keep self heating below 0.1 degree +Celsius, the device should not be active for more than 10% of the time, +e.g. maximum two measurements per second at the given resolution. + +Different resolutions, the on-chip heater, using the CRC checksum and reading +the serial number are not supported yet. diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface index 48ceabedf55d..8f63c244f1aa 100644 --- a/Documentation/hwmon/sysfs-interface +++ b/Documentation/hwmon/sysfs-interface @@ -187,6 +187,17 @@ fan[1-*]_div Fan divisor. Note that this is actually an internal clock divisor, which affects the measurable speed range, not the read value. +fan[1-*]_pulses Number of tachometer pulses per fan revolution. + Integer value, typically between 1 and 4. + RW + This value is a characteristic of the fan connected to the + device's input, so it has to be set in accordance with the fan + model. + Should only be created if the chip has a register to configure + the number of pulses. In the absence of such a register (and + thus attribute) the value assumed by all devices is 2 pulses + per fan revolution. + fan[1-*]_target Desired fan speed Unit: revolution/min (RPM) @@ -309,6 +320,20 @@ 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 @@ -370,10 +395,20 @@ curr[1-*]_min Current min value. Unit: milliampere RW +curr[1-*]_lcrit Current critical low value + Unit: milliampere + RW + +curr[1-*]_crit Current critical high value. + Unit: milliampere + RW + curr[1-*]_input Current input value Unit: milliampere RO +Also see the Alarms section for status flags associated with currents. + ********* * Power * ********* @@ -436,13 +471,6 @@ power[1-*]_accuracy Accuracy of the power meter. Unit: Percent RO -power[1-*]_alarm 1 if the system is drawing more power than the - cap allows; 0 otherwise. A poll notification is - sent to this file when the power use exceeds the - cap. This file only appears if the cap is known - to be enforced by hardware. - RO - power[1-*]_cap If power use rises above this limit, the system should take action to reduce power use. A poll notification is sent to this file if the @@ -465,6 +493,20 @@ power[1-*]_cap_min Minimum cap that can be set. Unit: microWatt RO +power[1-*]_max Maximum power. + Unit: microWatt + RW + +power[1-*]_crit Critical maximum power. + If power rises to or above this limit, the + system is expected take drastic action to reduce + power consumption, such as a system shutdown or + a forced powerdown of some devices. + Unit: microWatt + RW + +Also see the Alarms section for status flags associated with power readings. + ********** * Energy * ********** @@ -474,6 +516,15 @@ energy[1-*]_input Cumulative energy use RO +************ +* Humidity * +************ + +humidity[1-*]_input Humidity + Unit: milli-percent (per cent mille, pcm) + RO + + ********** * Alarms * ********** @@ -487,6 +538,7 @@ implementation. in[0-*]_alarm curr[1-*]_alarm +power[1-*]_alarm fan[1-*]_alarm temp[1-*]_alarm Channel alarm @@ -498,13 +550,22 @@ OR in[0-*]_min_alarm in[0-*]_max_alarm +in[0-*]_lcrit_alarm +in[0-*]_crit_alarm curr[1-*]_min_alarm curr[1-*]_max_alarm +curr[1-*]_lcrit_alarm +curr[1-*]_crit_alarm +power[1-*]_cap_alarm +power[1-*]_max_alarm +power[1-*]_crit_alarm fan[1-*]_min_alarm fan[1-*]_max_alarm temp[1-*]_min_alarm temp[1-*]_max_alarm +temp[1-*]_lcrit_alarm temp[1-*]_crit_alarm +temp[1-*]_emergency_alarm Limit alarm 0: no alarm 1: alarm @@ -518,7 +579,7 @@ channel should not be trusted. fan[1-*]_fault temp[1-*]_fault Input fault condition - 0: no fault occured + 0: no fault occurred 1: fault condition RO diff --git a/Documentation/hwmon/twl4030-madc-hwmon b/Documentation/hwmon/twl4030-madc-hwmon new file mode 100644 index 000000000000..ef7984317cec --- /dev/null +++ b/Documentation/hwmon/twl4030-madc-hwmon @@ -0,0 +1,45 @@ +Kernel driver twl4030-madc +========================= + +Supported chips: + * Texas Instruments TWL4030 + Prefix: 'twl4030-madc' + + +Authors: + J Keerthy <j-keerthy@ti.com> + +Description +----------- + +The Texas Instruments TWL4030 is a Power Management and Audio Circuit. Among +other things it contains a 10-bit A/D converter MADC. The converter has 16 +channels which can be used in different modes. + + +See this table for the meaning of the different channels + +Channel Signal +------------------------------------------ +0 Battery type(BTYPE) +1 BCI: Battery temperature (BTEMP) +2 GP analog input +3 GP analog input +4 GP analog input +5 GP analog input +6 GP analog input +7 GP analog input +8 BCI: VBUS voltage(VBUS) +9 Backup Battery voltage (VBKP) +10 BCI: Battery charger current (ICHG) +11 BCI: Battery charger voltage (VCHG) +12 BCI: Main battery voltage (VBAT) +13 Reserved +14 Reserved +15 VRUSB Supply/Speaker left/Speaker right polarization level + + +The Sysfs nodes will represent the voltage in the units of mV, +the temperature channel shows the converted temperature in +degree celcius. The Battery charging current channel represents +battery charging current in mA. diff --git a/Documentation/hwmon/w83627ehf b/Documentation/hwmon/w83627ehf index 13d556112fc0..76ffef94ed75 100644 --- a/Documentation/hwmon/w83627ehf +++ b/Documentation/hwmon/w83627ehf @@ -5,13 +5,11 @@ Supported chips: * Winbond W83627EHF/EHG (ISA access ONLY) Prefix: 'w83627ehf' Addresses scanned: ISA address retrieved from Super I/O registers - Datasheet: - http://www.nuvoton.com.tw/NR/rdonlyres/A6A258F0-F0C9-4F97-81C0-C4D29E7E943E/0/W83627EHF.pdf + Datasheet: not available * Winbond W83627DHG Prefix: 'w83627dhg' Addresses scanned: ISA address retrieved from Super I/O registers - Datasheet: - http://www.nuvoton.com.tw/NR/rdonlyres/7885623D-A487-4CF9-A47F-30C5F73D6FE6/0/W83627DHG.pdf + Datasheet: not available * Winbond W83627DHG-P Prefix: 'w83627dhg' Addresses scanned: ISA address retrieved from Super I/O registers @@ -24,6 +22,14 @@ Supported chips: Prefix: 'w83667hg' Addresses scanned: ISA address retrieved from Super I/O registers Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6775F/W83667HG-I + Prefix: 'nct6775' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6776F + Prefix: 'nct6776' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request Authors: Jean Delvare <khali@linux-fr.org> @@ -36,19 +42,28 @@ Description ----------- This driver implements support for the Winbond W83627EHF, W83627EHG, -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 -VID (6 pins for the 627EHF/EHG, 8 pins for the 627DHG and 667HG), alarms -with beep warnings (control unimplemented), and some automatic fan -regulation strategies (plus manual fan control mode). +W83627DHG, W83627DHG-P, W83667HG, W83667HG-B, W83667HG-I (NCT6775F), +and NCT6776F super I/O chips. We will refer to them collectively as +Winbond chips. + +The chips implement three temperature sensors (up to four for 667HG-B, and nine +for NCT6775F and NCT6776F), five fan rotation speed sensors, ten analog voltage +sensors (only nine for the 627DHG), one VID (6 pins for the 627EHF/EHG, 8 pins +for the 627DHG and 667HG), alarms with beep warnings (control unimplemented), +and some automatic fan regulation strategies (plus manual fan control mode). + +The temperature sensor sources on W82677HG-B, NCT6775F, and NCT6776F are +configurable. temp4 and higher attributes are only reported if its temperature +source differs from the temperature sources of the already reported temperature +sensors. The configured source for each of the temperature sensors is provided +in tempX_label. Temperatures are measured in degrees Celsius and measurement resolution is 1 -degC for temp1 and 0.5 degC for temp2 and temp3. An alarm is triggered when -the temperature gets higher than high limit; it stays on until the temperature -falls below the hysteresis value. +degC for temp1 and and 0.5 degC for temp2 and temp3. For temp4 and higher, +resolution is 1 degC for W83667HG-B and 0.0 degC for NCT6775F and NCT6776F. +An alarm is triggered when the temperature gets higher than high limit; +it stays on until the temperature falls below the hysteresis value. +Alarms are only supported for temp1, temp2, and temp3. 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 @@ -80,7 +95,8 @@ prog -> pwm4 (not on 667HG and 667HG-B; the programmable setting is not name - this is a standard hwmon device entry. For the W83627EHF and W83627EHG, it is set to "w83627ehf", for the W83627DHG it is set to "w83627dhg", - and for the W83667HG it is set to "w83667hg". + for the W83667HG and W83667HG-B it is set to "w83667hg", for NCT6775F it + is set to "nct6775", and for NCT6776F it is set to "nct6776". pwm[1-4] - this file stores PWM duty cycle or DC value (fan speed) in range: 0 (stop) to 255 (full) @@ -90,6 +106,18 @@ pwm[1-4]_enable - this file controls mode of fan/temperature control: * 2 "Thermal Cruise" mode * 3 "Fan Speed Cruise" mode * 4 "Smart Fan III" mode + * 5 "Smart Fan IV" mode + + SmartFan III mode is not supported on NCT6776F. + + SmartFan IV mode is configurable only if it was configured at system + startup, and is only supported for W83677HG-B, NCT6775F, and NCT6776F. + SmartFan IV operational parameters can not be configured at this time, + and the various pwm attributes are not used in SmartFan IV mode. + The attributes can be written to, which is useful if you plan to + configure the system for a different pwm mode. However, the information + returned when reading pwm attributes is unrelated to SmartFan IV + operation. pwm[1-4]_mode - controls if output is PWM or DC level * 0 DC output (0 - 12v) diff --git a/Documentation/hwmon/w83627hf b/Documentation/hwmon/w83627hf index fb145e5e722a..8432e1118173 100644 --- a/Documentation/hwmon/w83627hf +++ b/Documentation/hwmon/w83627hf @@ -91,3 +91,25 @@ isaset -y -f 0x2e 0xaa The above sequence assumes a Super-I/O config space at 0x2e/0x2f, but 0x4e/0x4f is also possible. + +Voltage pin mapping +------------------- + +Here is a summary of the voltage pin mapping for the W83627THF. This +can be useful to convert data provided by board manufacturers into +working libsensors configuration statements. + + W83627THF | + Pin | Name | Register | Sysfs attribute +----------------------------------------------------- + 100 | CPUVCORE | 20h | in0 + 99 | VIN0 | 21h | in1 + 98 | VIN1 | 22h | in2 + 97 | VIN2 | 24h | in4 + 114 | AVCC | 23h | in3 + 61 | 5VSB | 50h (bank 5) | in7 + 74 | VBAT | 51h (bank 5) | in8 + +For other supported devices, you'll have to take the hard path and +look up the information in the datasheet yourself (and then add it +to this document please.) diff --git a/Documentation/hwmon/w83781d b/Documentation/hwmon/w83781d index ecbc1e4574b4..129b0a3b555b 100644 --- a/Documentation/hwmon/w83781d +++ b/Documentation/hwmon/w83781d @@ -403,7 +403,7 @@ found out the following values do work as a form of coarse pwm: 0x80 - seems to turn fans off after some time(1-2 minutes)... might be some form of auto-fan-control based on temp? hmm (Qfan? this mobo is an -old ASUS, it isn't marketed as Qfan. Maybe some beta pre-attemp at Qfan +old ASUS, it isn't marketed as Qfan. Maybe some beta pre-attempt at Qfan that was dropped at the BIOS) 0x81 - off 0x82 - slightly "on-ner" than off, but my fans do not get to move. I can diff --git a/Documentation/hwmon/w83791d b/Documentation/hwmon/w83791d index 5663e491655c..90387c3540f7 100644 --- a/Documentation/hwmon/w83791d +++ b/Documentation/hwmon/w83791d @@ -93,7 +93,7 @@ The sysfs interface to the beep bitmask has migrated from the original legacy method of a single sysfs beep_mask file to a newer method using multiple *_beep files as described in .../Documentation/hwmon/sysfs-interface. -A similar change has occured for the bitmap corresponding to the alarms. The +A similar change has occurred for the bitmap corresponding to the alarms. The original legacy method used a single sysfs alarms file containing a bitmap of triggered alarms. The newer method uses multiple sysfs *_alarm files (again following the pattern described in sysfs-interface). diff --git a/Documentation/hwmon/w83793 b/Documentation/hwmon/w83793 index 51171a83165b..6cc5f639b721 100644 --- a/Documentation/hwmon/w83793 +++ b/Documentation/hwmon/w83793 @@ -92,7 +92,7 @@ This driver implements support for Winbond W83793G/W83793R chips. * Chassis If the case open alarm triggers, it will stay in this state unless cleared - by any write to the sysfs file "chassis". + by writing 0 to the sysfs file "intrusion0_alarm". * VID and VRM The VRM version is detected automatically, don't modify the it unless you diff --git a/Documentation/hwmon/w83795 b/Documentation/hwmon/w83795 new file mode 100644 index 000000000000..9f160371f463 --- /dev/null +++ b/Documentation/hwmon/w83795 @@ -0,0 +1,127 @@ +Kernel driver w83795 +==================== + +Supported chips: + * Winbond/Nuvoton W83795G + Prefix: 'w83795g' + Addresses scanned: I2C 0x2c - 0x2f + Datasheet: Available for download on nuvoton.com + * Winbond/Nuvoton W83795ADG + Prefix: 'w83795adg' + Addresses scanned: I2C 0x2c - 0x2f + Datasheet: Available for download on nuvoton.com + +Authors: + Wei Song (Nuvoton) + Jean Delvare <khali@linux-fr.org> + + +Pin mapping +----------- + +Here is a summary of the pin mapping for the W83795G and W83795ADG. +This can be useful to convert data provided by board manufacturers +into working libsensors configuration statements. + + W83795G | + Pin | Name | Register | Sysfs attribute +------------------------------------------------------------------ + 13 | VSEN1 (VCORE1) | 10h | in0 + 14 | VSEN2 (VCORE2) | 11h | in1 + 15 | VSEN3 (VCORE3) | 12h | in2 + 16 | VSEN4 | 13h | in3 + 17 | VSEN5 | 14h | in4 + 18 | VSEN6 | 15h | in5 + 19 | VSEN7 | 16h | in6 + 20 | VSEN8 | 17h | in7 + 21 | VSEN9 | 18h | in8 + 22 | VSEN10 | 19h | in9 + 23 | VSEN11 | 1Ah | in10 + 28 | VTT | 1Bh | in11 + 24 | 3VDD | 1Ch | in12 + 25 | 3VSB | 1Dh | in13 + 26 | VBAT | 1Eh | in14 + 3 | VSEN12/TR5 | 1Fh | in15/temp5 + 4 | VSEN13/TR5 | 20h | in16/temp6 + 5/ 6 | VDSEN14/TR1/TD1 | 21h | in17/temp1 + 7/ 8 | VDSEN15/TR2/TD2 | 22h | in18/temp2 + 9/ 10 | VDSEN16/TR3/TD3 | 23h | in19/temp3 + 11/ 12 | VDSEN17/TR4/TD4 | 24h | in20/temp4 + 40 | FANIN1 | 2Eh | fan1 + 42 | FANIN2 | 2Fh | fan2 + 44 | FANIN3 | 30h | fan3 + 46 | FANIN4 | 31h | fan4 + 48 | FANIN5 | 32h | fan5 + 50 | FANIN6 | 33h | fan6 + 52 | FANIN7 | 34h | fan7 + 54 | FANIN8 | 35h | fan8 + 57 | FANIN9 | 36h | fan9 + 58 | FANIN10 | 37h | fan10 + 59 | FANIN11 | 38h | fan11 + 60 | FANIN12 | 39h | fan12 + 31 | FANIN13 | 3Ah | fan13 + 35 | FANIN14 | 3Bh | fan14 + 41 | FANCTL1 | 10h (bank 2) | pwm1 + 43 | FANCTL2 | 11h (bank 2) | pwm2 + 45 | FANCTL3 | 12h (bank 2) | pwm3 + 47 | FANCTL4 | 13h (bank 2) | pwm4 + 49 | FANCTL5 | 14h (bank 2) | pwm5 + 51 | FANCTL6 | 15h (bank 2) | pwm6 + 53 | FANCTL7 | 16h (bank 2) | pwm7 + 55 | FANCTL8 | 17h (bank 2) | pwm8 + 29/ 30 | PECI/TSI (DTS1) | 26h | temp7 + 29/ 30 | PECI/TSI (DTS2) | 27h | temp8 + 29/ 30 | PECI/TSI (DTS3) | 28h | temp9 + 29/ 30 | PECI/TSI (DTS4) | 29h | temp10 + 29/ 30 | PECI/TSI (DTS5) | 2Ah | temp11 + 29/ 30 | PECI/TSI (DTS6) | 2Bh | temp12 + 29/ 30 | PECI/TSI (DTS7) | 2Ch | temp13 + 29/ 30 | PECI/TSI (DTS8) | 2Dh | temp14 + 27 | CASEOPEN# | 46h | intrusion0 + + W83795ADG | + Pin | Name | Register | Sysfs attribute +------------------------------------------------------------------ + 10 | VSEN1 (VCORE1) | 10h | in0 + 11 | VSEN2 (VCORE2) | 11h | in1 + 12 | VSEN3 (VCORE3) | 12h | in2 + 13 | VSEN4 | 13h | in3 + 14 | VSEN5 | 14h | in4 + 15 | VSEN6 | 15h | in5 + 16 | VSEN7 | 16h | in6 + 17 | VSEN8 | 17h | in7 + 22 | VTT | 1Bh | in11 + 18 | 3VDD | 1Ch | in12 + 19 | 3VSB | 1Dh | in13 + 20 | VBAT | 1Eh | in14 + 48 | VSEN12/TR5 | 1Fh | in15/temp5 + 1 | VSEN13/TR5 | 20h | in16/temp6 + 2/ 3 | VDSEN14/TR1/TD1 | 21h | in17/temp1 + 4/ 5 | VDSEN15/TR2/TD2 | 22h | in18/temp2 + 6/ 7 | VDSEN16/TR3/TD3 | 23h | in19/temp3 + 8/ 9 | VDSEN17/TR4/TD4 | 24h | in20/temp4 + 32 | FANIN1 | 2Eh | fan1 + 34 | FANIN2 | 2Fh | fan2 + 36 | FANIN3 | 30h | fan3 + 37 | FANIN4 | 31h | fan4 + 38 | FANIN5 | 32h | fan5 + 39 | FANIN6 | 33h | fan6 + 40 | FANIN7 | 34h | fan7 + 41 | FANIN8 | 35h | fan8 + 43 | FANIN9 | 36h | fan9 + 44 | FANIN10 | 37h | fan10 + 45 | FANIN11 | 38h | fan11 + 46 | FANIN12 | 39h | fan12 + 24 | FANIN13 | 3Ah | fan13 + 28 | FANIN14 | 3Bh | fan14 + 33 | FANCTL1 | 10h (bank 2) | pwm1 + 35 | FANCTL2 | 11h (bank 2) | pwm2 + 23 | PECI (DTS1) | 26h | temp7 + 23 | PECI (DTS2) | 27h | temp8 + 23 | PECI (DTS3) | 28h | temp9 + 23 | PECI (DTS4) | 29h | temp10 + 23 | PECI (DTS5) | 2Ah | temp11 + 23 | PECI (DTS6) | 2Bh | temp12 + 23 | PECI (DTS7) | 2Ch | temp13 + 23 | PECI (DTS8) | 2Dh | temp14 + 21 | CASEOPEN# | 46h | intrusion0 diff --git a/Documentation/hwspinlock.txt b/Documentation/hwspinlock.txt new file mode 100644 index 000000000000..7dcd1a4e726c --- /dev/null +++ b/Documentation/hwspinlock.txt @@ -0,0 +1,293 @@ +Hardware Spinlock Framework + +1. Introduction + +Hardware spinlock modules provide hardware assistance for synchronization +and mutual exclusion between heterogeneous processors and those not operating +under a single, shared operating system. + +For example, OMAP4 has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP, +each of which is running a different Operating System (the master, A9, +is usually running Linux and the slave processors, the M3 and the DSP, +are running some flavor of RTOS). + +A generic hwspinlock framework allows platform-independent drivers to use +the hwspinlock device in order to access data structures that are shared +between remote processors, that otherwise have no alternative mechanism +to accomplish synchronization and mutual exclusion operations. + +This is necessary, for example, for Inter-processor communications: +on OMAP4, cpu-intensive multimedia tasks are offloaded by the host to the +remote M3 and/or C64x+ slave processors (by an IPC subsystem called Syslink). + +To achieve fast message-based communications, a minimal kernel support +is needed to deliver messages arriving from a remote processor to the +appropriate user process. + +This communication is based on simple data structures that is shared between +the remote processors, and access to it is synchronized using the hwspinlock +module (remote processor directly places new messages in this shared data +structure). + +A common hwspinlock interface makes it possible to have generic, platform- +independent, drivers. + +2. User API + + struct hwspinlock *hwspin_lock_request(void); + - dynamically assign an hwspinlock and return its address, or NULL + in case an unused hwspinlock isn't available. Users of this + API will usually want to communicate the lock's id to the remote core + before it can be used to achieve synchronization. + Can be called from an atomic context (this function will not sleep) but + not from within interrupt context. + + struct hwspinlock *hwspin_lock_request_specific(unsigned int id); + - assign a specific hwspinlock id and return its address, or NULL + if that hwspinlock is already in use. Usually board code will + be calling this function in order to reserve specific hwspinlock + ids for predefined purposes. + Can be called from an atomic context (this function will not sleep) but + not from within interrupt context. + + int hwspin_lock_free(struct hwspinlock *hwlock); + - free a previously-assigned hwspinlock; returns 0 on success, or an + appropriate error code on failure (e.g. -EINVAL if the hwspinlock + is already free). + Can be called from an atomic context (this function will not sleep) but + not from within interrupt context. + + int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int timeout); + - lock a previously-assigned hwspinlock with a timeout limit (specified in + msecs). If the hwspinlock is already taken, the function will busy loop + waiting for it to be released, but give up when the timeout elapses. + Upon a successful return from this function, preemption is disabled so + the caller must not sleep, and is advised to release the hwspinlock as + soon as possible, in order to minimize remote cores polling on the + hardware interconnect. + Returns 0 when successful and an appropriate error code otherwise (most + notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs). + The function will never sleep. + + int hwspin_lock_timeout_irq(struct hwspinlock *hwlock, unsigned int timeout); + - lock a previously-assigned hwspinlock with a timeout limit (specified in + msecs). If the hwspinlock is already taken, the function will busy loop + waiting for it to be released, but give up when the timeout elapses. + Upon a successful return from this function, preemption and the local + interrupts are disabled, so the caller must not sleep, and is advised to + release the hwspinlock as soon as possible. + Returns 0 when successful and an appropriate error code otherwise (most + notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs). + The function will never sleep. + + int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock, unsigned int to, + unsigned long *flags); + - lock a previously-assigned hwspinlock with a timeout limit (specified in + msecs). If the hwspinlock is already taken, the function will busy loop + waiting for it to be released, but give up when the timeout elapses. + Upon a successful return from this function, preemption is disabled, + local interrupts are disabled and their previous state is saved at the + given flags placeholder. The caller must not sleep, and is advised to + release the hwspinlock as soon as possible. + Returns 0 when successful and an appropriate error code otherwise (most + notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs). + The function will never sleep. + + int hwspin_trylock(struct hwspinlock *hwlock); + - attempt to lock a previously-assigned hwspinlock, but immediately fail if + it is already taken. + Upon a successful return from this function, preemption is disabled so + caller must not sleep, and is advised to release the hwspinlock as soon as + possible, in order to minimize remote cores polling on the hardware + interconnect. + Returns 0 on success and an appropriate error code otherwise (most + notably -EBUSY if the hwspinlock was already taken). + The function will never sleep. + + int hwspin_trylock_irq(struct hwspinlock *hwlock); + - attempt to lock a previously-assigned hwspinlock, but immediately fail if + it is already taken. + Upon a successful return from this function, preemption and the local + interrupts are disabled so caller must not sleep, and is advised to + release the hwspinlock as soon as possible. + Returns 0 on success and an appropriate error code otherwise (most + notably -EBUSY if the hwspinlock was already taken). + The function will never sleep. + + int hwspin_trylock_irqsave(struct hwspinlock *hwlock, unsigned long *flags); + - attempt to lock a previously-assigned hwspinlock, but immediately fail if + it is already taken. + Upon a successful return from this function, preemption is disabled, + the local interrupts are disabled and their previous state is saved + at the given flags placeholder. The caller must not sleep, and is advised + to release the hwspinlock as soon as possible. + Returns 0 on success and an appropriate error code otherwise (most + notably -EBUSY if the hwspinlock was already taken). + The function will never sleep. + + void hwspin_unlock(struct hwspinlock *hwlock); + - unlock a previously-locked hwspinlock. Always succeed, and can be called + from any context (the function never sleeps). Note: code should _never_ + unlock an hwspinlock which is already unlocked (there is no protection + against this). + + void hwspin_unlock_irq(struct hwspinlock *hwlock); + - unlock a previously-locked hwspinlock and enable local interrupts. + The caller should _never_ unlock an hwspinlock which is already unlocked. + Doing so is considered a bug (there is no protection against this). + Upon a successful return from this function, preemption and local + interrupts are enabled. This function will never sleep. + + void + hwspin_unlock_irqrestore(struct hwspinlock *hwlock, unsigned long *flags); + - unlock a previously-locked hwspinlock. + The caller should _never_ unlock an hwspinlock which is already unlocked. + Doing so is considered a bug (there is no protection against this). + Upon a successful return from this function, preemption is reenabled, + and the state of the local interrupts is restored to the state saved at + the given flags. This function will never sleep. + + int hwspin_lock_get_id(struct hwspinlock *hwlock); + - retrieve id number of a given hwspinlock. This is needed when an + hwspinlock is dynamically assigned: before it can be used to achieve + mutual exclusion with a remote cpu, the id number should be communicated + to the remote task with which we want to synchronize. + Returns the hwspinlock id number, or -EINVAL if hwlock is null. + +3. Typical usage + +#include <linux/hwspinlock.h> +#include <linux/err.h> + +int hwspinlock_example1(void) +{ + struct hwspinlock *hwlock; + int ret; + + /* dynamically assign a hwspinlock */ + hwlock = hwspin_lock_request(); + if (!hwlock) + ... + + id = hwspin_lock_get_id(hwlock); + /* probably need to communicate id to a remote processor now */ + + /* take the lock, spin for 1 sec if it's already taken */ + ret = hwspin_lock_timeout(hwlock, 1000); + if (ret) + ... + + /* + * we took the lock, do our thing now, but do NOT sleep + */ + + /* release the lock */ + hwspin_unlock(hwlock); + + /* free the lock */ + ret = hwspin_lock_free(hwlock); + if (ret) + ... + + return ret; +} + +int hwspinlock_example2(void) +{ + struct hwspinlock *hwlock; + int ret; + + /* + * assign a specific hwspinlock id - this should be called early + * by board init code. + */ + hwlock = hwspin_lock_request_specific(PREDEFINED_LOCK_ID); + if (!hwlock) + ... + + /* try to take it, but don't spin on it */ + ret = hwspin_trylock(hwlock); + if (!ret) { + pr_info("lock is already taken\n"); + return -EBUSY; + } + + /* + * we took the lock, do our thing now, but do NOT sleep + */ + + /* release the lock */ + hwspin_unlock(hwlock); + + /* free the lock */ + ret = hwspin_lock_free(hwlock); + if (ret) + ... + + return ret; +} + + +4. API for implementors + + int hwspin_lock_register(struct hwspinlock *hwlock); + - to be called from the underlying platform-specific implementation, in + order to register a new hwspinlock instance. Can be called from an atomic + context (this function will not sleep) but not from within interrupt + context. Returns 0 on success, or appropriate error code on failure. + + struct hwspinlock *hwspin_lock_unregister(unsigned int id); + - to be called from the underlying vendor-specific implementation, in order + to unregister an existing (and unused) hwspinlock instance. + Can be called from an atomic context (will not sleep) but not from + within interrupt context. + Returns the address of hwspinlock on success, or NULL on error (e.g. + if the hwspinlock is sill in use). + +5. struct hwspinlock + +This struct represents an hwspinlock instance. It is registered by the +underlying hwspinlock implementation using the hwspin_lock_register() API. + +/** + * struct hwspinlock - vendor-specific hwspinlock implementation + * + * @dev: underlying device, will be used with runtime PM api + * @ops: vendor-specific hwspinlock handlers + * @id: a global, unique, system-wide, index of the lock. + * @lock: initialized and used by hwspinlock core + * @owner: underlying implementation module, used to maintain module ref count + */ +struct hwspinlock { + struct device *dev; + const struct hwspinlock_ops *ops; + int id; + spinlock_t lock; + struct module *owner; +}; + +The underlying implementation is responsible to assign the dev, ops, id and +owner members. The lock member, OTOH, is initialized and used by the hwspinlock +core. + +6. Implementation callbacks + +There are three possible callbacks defined in 'struct hwspinlock_ops': + +struct hwspinlock_ops { + int (*trylock)(struct hwspinlock *lock); + void (*unlock)(struct hwspinlock *lock); + void (*relax)(struct hwspinlock *lock); +}; + +The first two callbacks are mandatory: + +The ->trylock() callback should make a single attempt to take the lock, and +return 0 on failure and 1 on success. This callback may _not_ sleep. + +The ->unlock() callback releases the lock. It always succeed, and it, too, +may _not_ sleep. + +The ->relax() callback is optional. It is called by hwspinlock core while +spinning on a lock, and can be used by the underlying implementation to force +a delay between two successive invocations of ->trylock(). It may _not_ sleep. diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c new file mode 100644 index 000000000000..30fe4bb9a069 --- /dev/null +++ b/Documentation/i2c/busses/i2c-diolan-u2c @@ -0,0 +1,26 @@ +Kernel driver i2c-diolan-u2c + +Supported adapters: + * Diolan U2C-12 I2C-USB adapter + Documentation: + http://www.diolan.com/i2c/u2c12.html + +Author: Guenter Roeck <guenter.roeck@ericsson.com> + +Description +----------- + +This is the driver for the Diolan U2C-12 USB-I2C adapter. + +The Diolan U2C-12 I2C-USB Adapter provides a low cost solution to connect +a computer to I2C slave devices using a USB interface. It also supports +connectivity to SPI devices. + +This driver only supports the I2C interface of U2C-12. The driver does not use +interrupts. + + +Module parameters +----------------- + +* frequency: I2C bus frequency diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index e307914a3eda..6df69765ccb7 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -15,10 +15,15 @@ Supported adapters: * Intel 82801I (ICH9) * Intel EP80579 (Tolapai) * Intel 82801JI (ICH10) - * Intel 3400/5 Series (PCH) - * Intel Cougar Point (PCH) + * Intel 5/3400 Series (PCH) + * Intel 6 Series (PCH) + * Intel Patsburg (PCH) + * Intel DH89xxCC (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-parport-light b/Documentation/i2c/busses/i2c-parport-light index bdc9cbb2e0f2..c22ee063e1e5 100644 --- a/Documentation/i2c/busses/i2c-parport-light +++ b/Documentation/i2c/busses/i2c-parport-light @@ -4,7 +4,7 @@ Author: Jean Delvare <khali@linux-fr.org> This driver is a light version of i2c-parport. It doesn't depend on the parport driver, and uses direct I/O access instead. This might be -prefered on embedded systems where wasting memory for the clean but heavy +preferred on embedded systems where wasting memory for the clean but heavy parport handling is not an option. The drawback is a reduced portability and the impossibility to daisy-chain other parallel port devices. diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x index 70e6a0cc1e15..0b979f3252a4 100644 --- a/Documentation/i2c/busses/i2c-sis96x +++ b/Documentation/i2c/busses/i2c-sis96x @@ -35,7 +35,7 @@ or perhaps this... (kernel versions later than 2.4.18 may fill in the "Unknown"s) -If you cant see it please look on quirk_sis_96x_smbus +If you can't see it please look on quirk_sis_96x_smbus (drivers/pci/quirks.c) (also if southbridge detection fails) I suspect that this driver could be made to work for the following SiS diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm index 9146e33be6dd..63f62bcbf592 100644 --- a/Documentation/i2c/busses/i2c-taos-evm +++ b/Documentation/i2c/busses/i2c-taos-evm @@ -13,7 +13,7 @@ Currently supported devices are: * TAOS TSL2550 EVM -For addtional information on TAOS products, please see +For additional information on TAOS products, please see http://www.taosinc.com/ diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices index 87da405a8597..9edb75d8c9b9 100644 --- a/Documentation/i2c/instantiating-devices +++ b/Documentation/i2c/instantiating-devices @@ -100,7 +100,7 @@ static int __devinit usb_hcd_pnx4008_probe(struct platform_device *pdev) (...) i2c_adap = i2c_get_adapter(2); memset(&i2c_info, 0, sizeof(struct i2c_board_info)); - strlcpy(i2c_info.name, "isp1301_pnx", I2C_NAME_SIZE); + strlcpy(i2c_info.type, "isp1301_pnx", I2C_NAME_SIZE); isp1301_i2c_client = i2c_new_probed_device(i2c_adap, &i2c_info, normal_i2c, NULL); i2c_put_adapter(i2c_adap); diff --git a/Documentation/i2c/muxes/gpio-i2cmux b/Documentation/i2c/muxes/gpio-i2cmux new file mode 100644 index 000000000000..811cd78d4cdc --- /dev/null +++ b/Documentation/i2c/muxes/gpio-i2cmux @@ -0,0 +1,65 @@ +Kernel driver gpio-i2cmux + +Author: Peter Korsgaard <peter.korsgaard@barco.com> + +Description +----------- + +gpio-i2cmux is an i2c mux driver providing access to I2C bus segments +from a master I2C bus and a hardware MUX controlled through GPIO pins. + +E.G.: + + ---------- ---------- Bus segment 1 - - - - - + | | SCL/SDA | |-------------- | | + | |------------| | + | | | | Bus segment 2 | | + | Linux | GPIO 1..N | MUX |--------------- Devices + | |------------| | | | + | | | | Bus segment M + | | | |---------------| | + ---------- ---------- - - - - - + +SCL/SDA of the master I2C bus is multiplexed to bus segment 1..M +according to the settings of the GPIO pins 1..N. + +Usage +----- + +gpio-i2cmux uses the platform bus, so you need to provide a struct +platform_device with the platform_data pointing to a struct +gpio_i2cmux_platform_data with the I2C adapter number of the master +bus, the number of bus segments to create and the GPIO pins used +to control it. See include/linux/gpio-i2cmux.h for details. + +E.G. something like this for a MUX providing 4 bus segments +controlled through 3 GPIO pins: + +#include <linux/gpio-i2cmux.h> +#include <linux/platform_device.h> + +static const unsigned myboard_gpiomux_gpios[] = { + AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24 +}; + +static const unsigned myboard_gpiomux_values[] = { + 0, 1, 2, 3 +}; + +static struct gpio_i2cmux_platform_data myboard_i2cmux_data = { + .parent = 1, + .base_nr = 2, /* optional */ + .values = myboard_gpiomux_values, + .n_values = ARRAY_SIZE(myboard_gpiomux_values), + .gpios = myboard_gpiomux_gpios, + .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios), + .idle = 4, /* optional */ +}; + +static struct platform_device myboard_i2cmux = { + .name = "gpio-i2cmux", + .id = 0, + .dev = { + .platform_data = &myboard_i2cmux_data, + }, +}; diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients index 9a45f9bb6a25..d6991625c407 100644 --- a/Documentation/i2c/upgrading-clients +++ b/Documentation/i2c/upgrading-clients @@ -61,7 +61,7 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind) return 0; } -static int __devexit example_detach(struct i2c_client *client) +static int example_detach(struct i2c_client *client) { struct example_state *state = i2c_get_clientdata(client); @@ -81,7 +81,7 @@ static struct i2c_driver example_driver = { .name = "example", }, .attach_adapter = example_attach_adapter, - .detach_client = __devexit_p(example_detach), + .detach_client = example_detach, .suspend = example_suspend, .resume = example_resume, }; @@ -93,7 +93,7 @@ Updating the client The new style binding model will check against a list of supported devices and their associated address supplied by the code registering the busses. This means that the driver .attach_adapter and -.detach_adapter methods can be removed, along with the addr_data, +.detach_client methods can be removed, along with the addr_data, as follows: - static struct i2c_driver example_driver; @@ -110,14 +110,14 @@ as follows: static struct i2c_driver example_driver = { - .attach_adapter = example_attach_adapter, -- .detach_client = __devexit_p(example_detach), +- .detach_client = example_detach, } Add the probe and remove methods to the i2c_driver, as so: static struct i2c_driver example_driver = { + .probe = example_probe, -+ .remove = __devexit_p(example_remove), ++ .remove = example_remove, } Change the example_attach method to accept the new parameters @@ -199,8 +199,8 @@ to delete the i2c_detach_client call. It is possible that you can also remove the ret variable as it is not not needed for any of the core functions. -- static int __devexit example_detach(struct i2c_client *client) -+ static int __devexit example_remove(struct i2c_client *client) +- static int example_detach(struct i2c_client *client) ++ static int example_remove(struct i2c_client *client) { struct example_state *state = i2c_get_clientdata(client); @@ -253,7 +253,7 @@ static int example_probe(struct i2c_client *client, return 0; } -static int __devexit example_remove(struct i2c_client *client) +static int example_remove(struct i2c_client *client) { struct example_state *state = i2c_get_clientdata(client); @@ -275,7 +275,7 @@ static struct i2c_driver example_driver = { }, .id_table = example_idtable, .probe = example_probe, - .remove = __devexit_p(example_remove), + .remove = example_remove, .suspend = example_suspend, .resume = example_resume, }; diff --git a/Documentation/i2o/README b/Documentation/i2o/README index 0ebf58c73f54..ee91e2626ff0 100644 --- a/Documentation/i2o/README +++ b/Documentation/i2o/README @@ -53,7 +53,7 @@ Symbios Logic (Now LSI) BoxHill Corporation Loan of initial FibreChannel disk array used for development work. -European Comission +European Commission Funding the work done by the University of Helsinki SysKonnect diff --git a/Documentation/ia64/aliasing-test.c b/Documentation/ia64/aliasing-test.c index 3dfb76ca6931..5caa2af33207 100644 --- a/Documentation/ia64/aliasing-test.c +++ b/Documentation/ia64/aliasing-test.c @@ -177,7 +177,7 @@ static int scan_rom(char *path, char *file) /* * It's OK if the ROM is unreadable. Maybe there - * is no ROM, or some other error ocurred. The + * is no ROM, or some other error occurred. The * important thing is that no MCA happened. */ if (rc > 0) diff --git a/Documentation/input/cma3000_d0x.txt b/Documentation/input/cma3000_d0x.txt new file mode 100644 index 000000000000..29d088db4afd --- /dev/null +++ b/Documentation/input/cma3000_d0x.txt @@ -0,0 +1,115 @@ +Kernel driver for CMA3000-D0x +============================ + +Supported chips: +* VTI CMA3000-D0x +Datasheet: + CMA3000-D0X Product Family Specification 8281000A.02.pdf + <http://www.vti.fi/en/> + +Author: Hemanth V <hemanthv@ti.com> + + +Description +----------- +CMA3000 Tri-axis accelerometer supports Motion detect, Measurement and +Free fall modes. + +Motion Detect Mode: Its the low power mode where interrupts are generated only +when motion exceeds the defined thresholds. + +Measurement Mode: This mode is used to read the acceleration data on X,Y,Z +axis and supports 400, 100, 40 Hz sample frequency. + +Free fall Mode: This mode is intended to save system resources. + +Threshold values: Chip supports defining threshold values for above modes +which includes time and g value. Refer product specifications for more details. + +CMA3000 chip supports mutually exclusive I2C and SPI interfaces for +communication, currently the driver supports I2C based communication only. +Initial configuration for bus mode is set in non volatile memory and can later +be modified through bus interface command. + +Driver reports acceleration data through input subsystem. It generates ABS_MISC +event with value 1 when free fall is detected. + +Platform data need to be configured for initial default values. + +Platform Data +------------- +fuzz_x: Noise on X Axis + +fuzz_y: Noise on Y Axis + +fuzz_z: Noise on Z Axis + +g_range: G range in milli g i.e 2000 or 8000 + +mode: Default Operating mode + +mdthr: Motion detect g range threshold value + +mdfftmr: Motion detect and free fall time threshold value + +ffthr: Free fall g range threshold value + +Input Interface +-------------- +Input driver version is 1.0.0 +Input device ID: bus 0x18 vendor 0x0 product 0x0 version 0x0 +Input device name: "cma3000-accelerometer" +Supported events: + Event type 0 (Sync) + Event type 3 (Absolute) + Event code 0 (X) + Value 47 + Min -8000 + Max 8000 + Fuzz 200 + Event code 1 (Y) + Value -28 + Min -8000 + Max 8000 + Fuzz 200 + Event code 2 (Z) + Value 905 + Min -8000 + Max 8000 + Fuzz 200 + Event code 40 (Misc) + Value 0 + Min 0 + Max 1 + Event type 4 (Misc) + + +Register/Platform parameters Description +---------------------------------------- + +mode: + 0: power down mode + 1: 100 Hz Measurement mode + 2: 400 Hz Measurement mode + 3: 40 Hz Measurement mode + 4: Motion Detect mode (default) + 5: 100 Hz Free fall mode + 6: 40 Hz Free fall mode + 7: Power off mode + +grange: + 2000: 2000 mg or 2G Range + 8000: 8000 mg or 8G Range + +mdthr: + X: X * 71mg (8G Range) + X: X * 18mg (2G Range) + +mdfftmr: + X: (X & 0x70) * 100 ms (MDTMR) + (X & 0x0F) * 2.5 ms (FFTMR 400 Hz) + (X & 0x0F) * 10 ms (FFTMR 100 Hz) + +ffthr: + X: (X >> 2) * 18mg (2G Range) + X: (X & 0x0F) * 71 mg (8G Range) diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.txt index ded4d5f53109..b3867bf49f8f 100644 --- a/Documentation/input/ff.txt +++ b/Documentation/input/ff.txt @@ -49,7 +49,9 @@ This information is subject to change. #include <linux/input.h> #include <sys/ioctl.h> -unsigned long features[1 + FF_MAX/sizeof(unsigned long)]; +#define BITS_TO_LONGS(x) \ + (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long))) +unsigned long features[BITS_TO_LONGS(FF_CNT)]; int ioctl(int file_descriptor, int request, unsigned long *features); "request" must be EVIOCGBIT(EV_FF, size of features array in bytes ) diff --git a/Documentation/input/joystick-parport.txt b/Documentation/input/joystick-parport.txt index 1c856f32ff2c..56870c70a796 100644 --- a/Documentation/input/joystick-parport.txt +++ b/Documentation/input/joystick-parport.txt @@ -272,7 +272,7 @@ if you want to use gamecon.c. Also, the connection is a bit more complex. You'll need a bunch of diodes, and one pullup resistor. First, you connect the Directions and the button -the same as for db9, however with the diodes inbetween. +the same as for db9, however with the diodes between. Diodes (pin 2) -----|<|----> Up diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index bdcba154b83e..71536e78406f 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -1,6 +1,6 @@ Multi-touch (MT) Protocol ------------------------- - Copyright (C) 2009 Henrik Rydberg <rydberg@euromail.se> + Copyright (C) 2009-2010 Henrik Rydberg <rydberg@euromail.se> Introduction @@ -161,19 +161,24 @@ 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 contact pressure. For pressure-based devices, ABS_MT_PRESSURE may be used to provide the pressure on the contact area -instead. +instead. Devices capable of contact hovering can use ABS_MT_DISTANCE to +indicate the distance between the contact and the surface. 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. +For type A devices, further specification of the touch shape is possible +via ABS_MT_BLOB_ID. + The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a -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 contact tracking from hardware [5]. +finger or a pen or something else. Finally, the ABS_MT_TRACKING_ID event +may be used to track identified contacts over time [5]. + +In the type B protocol, ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID are +implicitly handled by input core; drivers should instead call +input_mt_report_slot_state(). Event Semantics @@ -213,6 +218,12 @@ The pressure, in arbitrary units, on the contact area. May be used instead of TOUCH and WIDTH for pressure-based devices or any device with a spatial signal intensity distribution. +ABS_MT_DISTANCE + +The distance, in surface units, between the contact and the surface. Zero +distance means the contact is touching the surface. A positive number means +the contact is hovering above the surface. + ABS_MT_ORIENTATION The orientation of the ellipse. The value should describe a signed quarter @@ -240,21 +251,24 @@ ABS_MT_TOOL_TYPE The type of approaching tool. A lot of kernel drivers cannot distinguish between different tool types, such as a finger or a pen. In such cases, the event should be omitted. The protocol currently supports MT_TOOL_FINGER and -MT_TOOL_PEN [2]. +MT_TOOL_PEN [2]. For type B devices, this event is handled by input core; +drivers should instead use input_mt_report_slot_state(). ABS_MT_BLOB_ID The BLOB_ID groups several packets together into one arbitrarily shaped -contact. This is a low-level anonymous grouping for type A devices, and +contact. The sequence of points forms a polygon which defines the shape of +the 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]. 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. +[5]. 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. For type B devices, this event is handled by input core; drivers +should instead use input_mt_report_slot_state(). Event Computation @@ -301,18 +315,19 @@ and with ORIENTATION, one can detect twisting of fingers. Notes ----- -In order to stay compatible with existing applications, the data -reported in a finger packet must not be recognized as single-touch -events. In addition, all finger data must bypass input filtering, -since subsequent events of the same type refer to different fingers. +In order to stay compatible with existing applications, the data reported +in a finger packet must not be recognized as single-touch events. + +For type A devices, all finger data bypasses input filtering, since +subsequent events of the same type refer to different fingers. -The first kernel driver to utilize the MT protocol is the bcm5974 driver, -where examples can be found. +For example usage of the type A protocol, see the bcm5974 driver. For +example usage of the type B protocol, see the hid-egalax driver. [1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the difference between the contact position and the approaching tool position could be used to derive tilt. [2] The list can of course be extended. -[3] Multitouch X driver project: http://bitmath.org/code/multitouch/. +[3] The mtdev project: http://bitmath.org/code/mtdev/. [4] See the section on event computation. [5] See the section on finger tracking. diff --git a/Documentation/input/ntrig.txt b/Documentation/input/ntrig.txt new file mode 100644 index 000000000000..be1fd981f73f --- /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/rotary-encoder.txt b/Documentation/input/rotary-encoder.txt index 8b4129de1d2d..943e8f6f2b15 100644 --- a/Documentation/input/rotary-encoder.txt +++ b/Documentation/input/rotary-encoder.txt @@ -46,7 +46,7 @@ c) Falling edge on channel A, channel B in high state d) Falling edge on channel B, channel A in low state Parking position. If the encoder enters this state, a full transition - should have happend, unless it flipped back on half the way. The + should have happened, unless it flipped back on half the way. The 'armed' state tells us about that. 2. Platform requirements diff --git a/Documentation/input/walkera0701.txt b/Documentation/input/walkera0701.txt index 8f4289efc5c4..561385d38482 100644 --- a/Documentation/input/walkera0701.txt +++ b/Documentation/input/walkera0701.txt @@ -77,7 +77,7 @@ pulse length: 24 bin+oct values + 1 bin value = 24*4+1 bits = 97 bits -(Warning, pulses on ACK ar inverted by transistor, irq is rised up on sync +(Warning, pulses on ACK are inverted by transistor, irq is raised up on sync to bin change or octal value to bin change). Binary data representations: diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 33223ff121d8..a0a5d82b6b0b 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -133,6 +133,7 @@ Code Seq#(hex) Include File Comments 'H' C0-DF net/bluetooth/hidp/hidp.h conflict! 'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict! 'H' C0-DF net/bluetooth/bnep/bnep.h conflict! +'H' F1 linux/hid-roccat.h <mailto:erazor_de@users.sourceforge.net> 'I' all linux/isdn.h conflict! 'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict! 'I' 40-4F linux/mISDNif.h conflict! @@ -155,7 +156,6 @@ Code Seq#(hex) Include File Comments 'Q' all linux/soundcard.h 'R' 00-1F linux/random.h conflict! 'R' 01 linux/rfkill.h conflict! -'R' 01-0F media/rds.h conflict! 'R' C0-DF net/bluetooth/rfcomm.h 'S' all linux/cdrom.h conflict! 'S' 80-81 scsi/scsi_ioctl.h conflict! @@ -194,7 +194,6 @@ Code Seq#(hex) Include File Comments <http://lrcwww.epfl.ch/> 'b' 00-FF conflict! bit3 vme host bridge <mailto:natalia@nikhefk.nikhef.nl> -'b' 00-0F media/bt819.h conflict! 'c' all linux/cm4000_cs.h conflict! 'c' 00-7F linux/comstats.h conflict! 'c' 00-7F linux/coda.h conflict! @@ -249,7 +248,7 @@ Code Seq#(hex) Include File Comments 'p' 40-7F linux/nvram.h 'p' 80-9F linux/ppdev.h user-space parport <mailto:tim@cyberelk.net> -'p' A1-A4 linux/pps.h LinuxPPS +'p' A1-A5 linux/pps.h LinuxPPS <mailto:giometti@linux.it> 'q' 00-1F linux/serio.h 'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK @@ -259,15 +258,12 @@ Code Seq#(hex) Include File Comments '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 -'v' all linux/videodev.h conflict! +'u' 00-1F linux/smb_fs.h gone 'v' 00-1F linux/ext2_fs.h conflict! 'v' 00-1F linux/fs.h conflict! 'v' 00-0F linux/sonypi.h conflict! -'v' C0-CF drivers/media/video/ov511.h conflict! 'v' C0-DF media/pwc-ioctl.h conflict! 'v' C0-FF linux/meye.h conflict! -'v' C0-CF drivers/media/video/zoran/zoran.h conflict! 'v' D0-DF drivers/media/video/cpia2/cpia2dev.h conflict! 'w' all CERN SCI driver 'y' 00-1F packet based user level communications @@ -277,9 +273,8 @@ Code Seq#(hex) Include File Comments 'z' 40-7F CAN bus card conflict! <mailto:oe@port.de> 'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict! +'|' 00-7F linux/media.h 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 0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range diff --git a/Documentation/iostats.txt b/Documentation/iostats.txt index 59a69ec67c40..c76c21d87e85 100644 --- a/Documentation/iostats.txt +++ b/Documentation/iostats.txt @@ -1,8 +1,6 @@ I/O statistics fields --------------- -Last modified Sep 30, 2003 - Since 2.4.20 (and some versions before, with patches), and 2.5.45, more extensive disk statistics have been introduced to help measure disk activity. Tools such as sar and iostat typically interpret these and do @@ -46,11 +44,12 @@ the above example, the first field of statistics would be 446216. By contrast, in 2.6 if you look at /sys/block/hda/stat, you'll find just the eleven fields, beginning with 446216. If you look at /proc/diskstats, the eleven fields will be preceded by the major and -minor device numbers, and device name. Each of these formats provide +minor device numbers, and device name. Each of these formats provides eleven fields of statistics, each meaning exactly the same things. All fields except field 9 are cumulative since boot. Field 9 should -go to zero as I/Os complete; all others only increase. Yes, these are -32 bit unsigned numbers, and on a very busy or long-lived system they +go to zero as I/Os complete; all others only increase (unless they +overflow and wrap). Yes, these are (32-bit or 64-bit) unsigned long +(native word size) numbers, and on a very busy or long-lived system they may wrap. Applications should be prepared to deal with that; unless your observations are measured in large numbers of minutes or hours, they should not wrap twice before you notice them. @@ -81,7 +80,7 @@ Field 9 -- # of I/Os currently in progress The only field that should go to zero. Incremented as requests are given to appropriate struct request_queue and decremented as they finish. Field 10 -- # of milliseconds spent doing I/Os - This field is increases so long as field 9 is nonzero. + This field increases so long as field 9 is nonzero. Field 11 -- weighted # of milliseconds spent doing I/Os This field is incremented at each I/O start, I/O completion, I/O merge, or read of these stats by the number of I/Os in progress @@ -96,11 +95,11 @@ introduced when changes collide, so (for instance) adding up all the read I/Os issued per partition should equal those made to the disks ... but due to the lack of locking it may only be very close. -In 2.6, there are counters for each cpu, which made the lack of locking -almost a non-issue. When the statistics are read, the per-cpu counters -are summed (possibly overflowing the unsigned 32-bit variable they are +In 2.6, there are counters for each CPU, which make the lack of locking +almost a non-issue. When the statistics are read, the per-CPU counters +are summed (possibly overflowing the unsigned long variable they are summed to) and the result given to the user. There is no convenient -user interface for accessing the per-cpu counters themselves. +user interface for accessing the per-CPU counters themselves. Disks vs Partitions ------------------- diff --git a/Documentation/irqflags-tracing.txt b/Documentation/irqflags-tracing.txt index 6a444877ee0b..67aa71e73035 100644 --- a/Documentation/irqflags-tracing.txt +++ b/Documentation/irqflags-tracing.txt @@ -53,5 +53,5 @@ implementation in an architecture: lockdep will detect that and will turn itself off. I.e. the lock validator will still be reliable. There should be no crashes due to irq-tracing bugs. (except if the assembly changes break other code by modifying conditions or registers that -shouldnt be) +shouldn't be) diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI index 309eb5ed942b..1688b5a1fd77 100644 --- a/Documentation/isdn/INTERFACE.CAPI +++ b/Documentation/isdn/INTERFACE.CAPI @@ -240,7 +240,7 @@ Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert messages between their transport encoding described in the CAPI 2.0 standard and their _cmsg structure representation. Note that capi_cmsg2message() does not know or check the size of its destination buffer. The caller must make -sure it is big enough to accomodate the resulting CAPI message. +sure it is big enough to accommodate the resulting CAPI message. 5. Lower Layer Interface Functions diff --git a/Documentation/kbuild/kbuild.txt b/Documentation/kbuild/kbuild.txt index 1e5165aa9e4e..7c2a89ba674c 100644 --- a/Documentation/kbuild/kbuild.txt +++ b/Documentation/kbuild/kbuild.txt @@ -26,11 +26,11 @@ Additional options to the assembler (for built-in and modules). AFLAGS_MODULE -------------------------------------------------- -Addtional module specific options to use for $(AS). +Additional module specific options to use for $(AS). AFLAGS_KERNEL -------------------------------------------------- -Addtional options for $(AS) when used for assembler +Additional options for $(AS) when used for assembler code for code that is compiled as built-in. KCFLAGS @@ -39,12 +39,12 @@ Additional options to the C compiler (for built-in and modules). CFLAGS_KERNEL -------------------------------------------------- -Addtional options for $(CC) when used to compile +Additional options for $(CC) when used to compile code that is compiled as built-in. CFLAGS_MODULE -------------------------------------------------- -Addtional module specific options to use for $(CC). +Additional module specific options to use for $(CC). LDFLAGS_MODULE -------------------------------------------------- @@ -73,6 +73,14 @@ Specify the output directory when building the kernel. The output directory can also be specified using "O=...". Setting "O=..." takes precedence over KBUILD_OUTPUT. +KBUILD_DEBARCH +-------------------------------------------------- +For the deb-pkg target, allows overriding the normal heuristics deployed by +deb-pkg. Normally deb-pkg attempts to guess the right architecture based on +the UTS_MACHINE variable, and on some architectures also the kernel config. +The value of KBUILD_DEBARCH is assumed (not checked) to be a valid Debian +architecture. + ARCH -------------------------------------------------- Set ARCH to the architecture to be built. @@ -138,7 +146,7 @@ INSTALL_MOD_STRIP INSTALL_MOD_STRIP, if defined, will cause modules to be stripped after they are installed. If INSTALL_MOD_STRIP is '1', then the default option --strip-debug will be used. Otherwise, -INSTALL_MOD_STRIP will used as the options to the strip command. +INSTALL_MOD_STRIP value will be used as the options to the strip command. INSTALL_FW_PATH -------------------------------------------------- @@ -188,3 +196,8 @@ to be included in the databases, separated by blank space. E.g.: To get all available archs you can also specify all. E.g.: $ make ALLSOURCE_ARCHS=all tags + +KBUILD_ENABLE_EXTRA_GCC_CHECKS +-------------------------------------------------- +If enabled over the make command line with "W=1", it turns on additional +gcc -W... options for more extensive build-time checking. diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt index b472e4e0ba67..b507d61fd41c 100644 --- a/Documentation/kbuild/kconfig-language.txt +++ b/Documentation/kbuild/kconfig-language.txt @@ -112,7 +112,6 @@ applicable everywhere (see syntax). (no prompts anywhere) and for symbols with no dependencies. That will limit the usefulness but on the other hand avoid the illegal configurations all over. - kconfig should one day warn about such things. - numerical ranges: "range" <symbol> <symbol> ["if" <expr>] This allows to limit the range of possible input values for int @@ -268,7 +267,7 @@ separate list of options. choices: - "choice" + "choice" [symbol] <choice options> <choice block> "endchoice" @@ -282,6 +281,10 @@ single driver can be compiled/loaded into the kernel, but all drivers can be compiled as modules. A choice accepts another option "optional", which allows to set the choice to 'n' and no entry needs to be selected. +If no [symbol] is associated with a choice, then you can not have multiple +definitions of that choice. If a [symbol] is associated to the choice, +then you may define the same choice (ie. with the same entries) in another +place. comment: @@ -322,7 +325,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/makefiles.txt b/Documentation/kbuild/makefiles.txt index c787ae512120..5d145bb443c0 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -776,6 +776,13 @@ This will delete the directory debian, including all subdirectories. Kbuild will assume the directories to be in the same relative path as the Makefile if no absolute path is specified (path does not start with '/'). +To exclude certain files from make clean, use the $(no-clean-files) variable. +This is only a special case used in the top level Kbuild file: + + Example: + #Kbuild + no-clean-files := $(bounds-file) $(offsets-file) + Usually kbuild descends down in subdirectories due to "obj-* := dir/", but in the architecture makefiles where the kbuild infrastructure is not sufficient this sometimes needs to be explicit. @@ -1129,6 +1136,21 @@ When kbuild executes, the following steps are followed (roughly): resulting in the target file being recompiled for no obvious reason. + dtc + Create flattend device tree blob object suitable for linking + into vmlinux. Device tree blobs linked into vmlinux are placed + in an init section in the image. Platform code *must* copy the + blob to non-init memory prior to calling unflatten_device_tree(). + + Example: + #arch/x86/platform/ce4100/Makefile + clean-files := *dtb.S + + DTC_FLAGS := -p 1024 + obj-y += foo.dtb.o + + $(obj)/%.dtb: $(src)/%.dts + $(call cmd,dtc) --- 6.7 Custom kbuild commands @@ -1303,7 +1325,8 @@ The top Makefile exports the following variables: If this variable is specified, will cause modules to be stripped after they are installed. If INSTALL_MOD_STRIP is '1', then the default option --strip-debug will be used. Otherwise, - INSTALL_MOD_STRIP will used as the option(s) to the strip command. + INSTALL_MOD_STRIP value will be used as the option(s) to the strip + command. === 9 Makefile language diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.txt index 0767cf69c69e..3fb39e0116b4 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/kdump/kdump.txt b/Documentation/kdump/kdump.txt index cab61d842259..7a9e0b4b2903 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -65,18 +65,21 @@ Install kexec-tools 2) Download the kexec-tools user-space package from the following URL: -http://www.kernel.org/pub/linux/kernel/people/horms/kexec-tools/kexec-tools.tar.gz +http://kernel.org/pub/linux/utils/kernel/kexec/kexec-tools.tar.gz This is a symlink to the latest version. The latest kexec-tools git tree is available at: -git://git.kernel.org/pub/scm/linux/kernel/git/horms/kexec-tools.git -or -http://www.kernel.org/git/?p=linux/kernel/git/horms/kexec-tools.git +git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git +and +http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git + +There is also a gitweb interface available at +http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git More information about kexec-tools can be found at -http://www.kernel.org/pub/linux/kernel/people/horms/kexec-tools/README.html +http://www.kernel.org/pub/linux/utils/kernel/kexec/README.html 3) Unpack the tarball with the tar command, as follows: @@ -439,6 +442,6 @@ To Do Contact ======= -Vivek Goyal (vgoyal@in.ibm.com) +Vivek Goyal (vgoyal@redhat.com) Maneesh Soni (maneesh@in.ibm.com) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 715eaaf1519d..9a8674629a07 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -537,7 +537,7 @@ Notes: Further information in http://www.oreilly.com/catalog/linuxdrive2/ - * Title: "Linux Device Drivers, 3nd Edition" + * Title: "Linux Device Drivers, 3rd Edition" Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman Publisher: O'Reilly & Associates. Date: 2005. @@ -592,14 +592,6 @@ Pages: 600. ISBN: 0-13-101908-2 - * Title: "The Design and Implementation of the 4.4 BSD UNIX - Operating System" - Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, - John S. Quarterman. - Publisher: Addison-Wesley. - Date: 1996. - ISBN: 0-201-54979-4 - * Title: "Programming for the real world - POSIX.4" Author: Bill O. Gallmeister. Publisher: O'Reilly & Associates, Inc.. @@ -610,28 +602,13 @@ POSIX. Good reference. * Title: "UNIX Systems for Modern Architectures: Symmetric - Multiprocesssing and Caching for Kernel Programmers" + Multiprocessing and Caching for Kernel Programmers" Author: Curt Schimmel. Publisher: Addison Wesley. Date: June, 1994. Pages: 432. ISBN: 0-201-63338-8 - * Title: "The Design and Implementation of the 4.3 BSD UNIX - Operating System" - Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J. - Karels, John S. Quarterman. - Publisher: Addison-Wesley. - Date: 1989 (reprinted with corrections on October, 1990). - ISBN: 0-201-06196-1 - - * Title: "The Design of the UNIX Operating System" - Author: Maurice J. Bach. - Publisher: Prentice Hall. - Date: 1986. - Pages: 471. - ISBN: 0-13-201757-1 - MISCELLANEOUS: * Name: linux/Documentation diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 8dd7248508a9..d09e0c9b5189 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -44,6 +44,7 @@ parameter is applicable: AX25 Appropriate AX.25 support is enabled. BLACKFIN Blackfin architecture is enabled. DRM Direct Rendering Management support is enabled. + DYNAMIC_DEBUG Build in debug messages and enable them at runtime EDD BIOS Enhanced Disk Drive Services (EDD) is enabled EFI EFI Partitioning (GPT) is enabled EIDE EIDE/ATAPI support is enabled. @@ -143,6 +144,11 @@ a fixed number of characters. This limit depends on the architecture and is between 256 and 4096 characters. It is defined in the file ./include/asm/setup.h as COMMAND_LINE_SIZE. +Finally, the [KMG] suffix is commonly described after a number of kernel +parameter values. These 'K', 'M', and 'G' letters represent the _binary_ +multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30 +bytes respectively. Such letter suffixes can also be entirely omitted. + acpi= [HW,ACPI,X86] Advanced Configuration and Power Interface @@ -198,11 +204,6 @@ and is between 256 and 4096 characters. It is defined in the file unusable. The "log_buf_len" parameter may be useful if you need to capture more output. - acpi_display_output= [HW,ACPI] - acpi_display_output=vendor - acpi_display_output=video - See above. - acpi_irq_balance [HW,ACPI] ACPI will balance active IRQs default in APIC mode @@ -402,6 +403,10 @@ 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 + bulk_remove=off [PPC] This parameter disables the use of the pSeries + firmware feature for flushing multiple hpte entries + at a time. + c101= [NET] Moxa C101 synchronous serial card cachesize= [BUGS=X86-32] Override level 2 CPU cache size detection. @@ -455,7 +460,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 @@ -541,20 +546,27 @@ and is between 256 and 4096 characters. It is defined in the file /proc/<pid>/coredump_filter. See also Documentation/filesystems/proc.txt. + cpuidle.off=1 [CPU_IDLE] + disable the cpuidle sub-system + cpcihp_generic= [HW,PCI] Generic port I/O CompactPCI driver Format: <first_slot>,<last_slot>,<port>,<enum_bit>[,<debug>] - crashkernel=nn[KMG]@ss[KMG] - [KNL] Reserve a chunk of physical memory to - hold a kernel to switch to with kexec on panic. + crashkernel=size[KMG][@offset[KMG]] + [KNL] Using kexec, Linux can switch to a 'crash kernel' + upon panic. This parameter reserves the physical + memory region [offset, offset + size] for that kernel + image. If '@offset' is omitted, then a suitable offset + is selected automatically. Check + Documentation/kdump/kdump.txt for further details. crashkernel=range1:size1[,range2:size2,...][@offset] [KNL] Same as above, but depends on the memory in the running system. The syntax of range is start-[end] where start and end are both a memory unit (amount[KMG]). See also - Documentation/kdump/kdump.txt for a example. + Documentation/kdump/kdump.txt for an example. cs89x0_dma= [HW,NET] Format: <dma> @@ -570,6 +582,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= @@ -613,6 +629,10 @@ and is between 256 and 4096 characters. It is defined in the file disable= [IPV6] See Documentation/networking/ipv6.txt. + disable_ddw [PPC/PSERIES] + Disable Dynamic DMA Window support. Use this if + to workaround buggy firmware. + disable_ipv6= [IPV6] See Documentation/networking/ipv6.txt. @@ -650,11 +670,6 @@ and is between 256 and 4096 characters. It is defined in the file dscc4.setup= [NET] - dynamic_printk Enables pr_debug()/dev_dbg() calls if - CONFIG_DYNAMIC_PRINTK_DEBUG has been enabled. - These can also be switched on/off via - <debugfs>/dynamic_printk/modules - earlycon= [KNL] Output early console device and options. uart[8250],io,<addr>[,options] uart[8250],mmio,<addr>[,options] @@ -687,7 +702,7 @@ and is between 256 and 4096 characters. It is defined in the file ekgdboc= [X86,KGDB] Allow early kernel console debugging ekgdboc=kbd - This is desgined to be used in conjunction with + This is designed to be used in conjunction with the boot argument: earlyprintk=vga edd= [EDD] @@ -701,7 +716,7 @@ and is between 256 and 4096 characters. It is defined in the file arch/x86/kernel/cpu/cpufreq/elanfreq.c. elevator= [IOSCHED] - Format: {"anticipatory" | "cfq" | "deadline" | "noop"} + Format: {"cfq" | "deadline" | "noop"} See Documentation/block/as-iosched.txt and Documentation/block/deadline-iosched.txt for details. @@ -860,6 +875,12 @@ and is between 256 and 4096 characters. It is defined in the file If specified, z/VM IUCV HVC accepts connections from listed z/VM user IDs only. + keep_bootcon [KNL] + Do not unregister boot console at start. This is only + useful for debugging when something happens in the window + between unregistering the boot console and initializing + the real console. + i2c_bus= [HW] Override the default board specific I2C bus speed or register an additional I2C bus that is not registered from board initialization code. @@ -879,6 +900,7 @@ 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.notimeout [HW] Ignore timeout condition signalled by conroller i8042.reset [HW] Reset the controller during init and cleanup i8042.unlock [HW] Unlock (ignore) the keylock @@ -908,16 +930,11 @@ and is between 256 and 4096 characters. It is defined in the file Claim all unknown PCI IDE storage controllers. idle= [X86] - Format: idle=poll, idle=mwait, idle=halt, idle=nomwait + Format: idle=poll, idle=halt, idle=nomwait Poll forces a polling idle loop that can slightly improve the performance of waking up a idle CPU, but will use a lot of power and make the system run hot. Not recommended. - idle=mwait: On systems which support MONITOR/MWAIT but - the kernel chose to not use it because it doesn't save - as much power as a normal idle loop, use the - MONITOR/MWAIT idle loop anyways. Performance should be - the same as idle=poll. idle=halt: Halt is forced to be used for CPU idle. In such case C2/C3 won't be used again. idle=nomwait: Disable mwait for CPU C-states @@ -1126,9 +1143,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 @@ -1258,10 +1279,9 @@ and is between 256 and 4096 characters. It is defined in the file 6 (KERN_INFO) informational 7 (KERN_DEBUG) debug-level messages - log_buf_len=n Sets the size of the printk ring buffer, in bytes. - Format: { n | nk | nM } - n must be a power of two. The default size - is set in the kernel config file. + log_buf_len=n[KMG] Sets the size of the printk ring buffer, + in bytes. n must be a power of two. The default + size is set in the kernel config file. logo.nologo [FB] Disables display of the built-in Linux logo. This may be used to provide more screen space for @@ -1481,6 +1501,10 @@ and is between 256 and 4096 characters. It is defined in the file mtdparts= [MTD] See drivers/mtd/cmdlinepart.c. + multitce=off [PPC] This parameter disables the use of the pSeries + firmware feature for updating multiple TCE entries + at a time. + onenand.bdry= [HW,MTD] Flex-OneNAND Boundary Configuration Format: [die0_boundary][,die0_lock][,die1_boundary][,die1_lock] @@ -1532,12 +1556,15 @@ and is between 256 and 4096 characters. It is defined in the file 1 to enable accounting 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. @@ -1561,26 +1588,27 @@ and is between 256 and 4096 characters. It is defined in the file of returning the full 64-bit number. The default is to return 64-bit inode numbers. + nfs.nfs4_disable_idmapping= + [NFSv4] When set, this option disables the NFSv4 + idmapper on the client, but only if the mount + is using the 'sec=sys' security flavour. This may + make migration from legacy NFSv2/v3 systems easier + provided that the server has the appropriate support. + The default is to always enable NFSv4 idmapping. + nmi_debug= [KNL,AVR32,SH] Specify one or more actions to take when a NMI is triggered. Format: [state][,regs][,debounce][,die] nmi_watchdog= [KNL,BUGS=X86] Debugging features for SMP kernels - Format: [panic,][num] - Valid num: 0,1,2 + Format: [panic,][nopanic,][num] + Valid num: 0 0 - turn nmi_watchdog off - 1 - use the IO-APIC timer for the NMI watchdog - 2 - use the local APIC for the NMI watchdog using - a performance counter. Note: This will use one - performance counter and the local APIC's performance - vector. When panic is specified, panic when an NMI watchdog - timeout occurs. + timeout occurs (or 'nopanic' to override the opposite + default). This is useful when you use a panic=... timeout and need the box quickly up again. - Instead of 1 and 2 it is possible to use the following - symbolic names: lapic and ioapic - Example: nmi_watchdog=2 or nmi_watchdog=panic,lapic netpoll.carrier_timeout= [NET] Specifies amount of time (in seconds) that @@ -1610,6 +1638,8 @@ and is between 256 and 4096 characters. It is defined in the file noapic [SMP,APIC] Tells the kernel to not make use of any IOAPICs that may be present in the system. + noautogroup Disable scheduler automatic task group creation. + nobats [PPC] Do not use BATs for mapping kernel lowmem on "Classic" PPC cores. @@ -1653,10 +1683,6 @@ and is between 256 and 4096 characters. It is defined in the file wfi(ARM) instruction doesn't work correctly and not to use it. This is also useful when using JTAG debugger. - no-hlt [BUGS=X86-32] Tells the kernel that the hlt - instruction doesn't work correctly and not to - use it. - no_file_caps Tells the kernel not to honor file capabilities. The only way then for a file to be executed with privilege is to be setuid root or executed by root. @@ -1693,6 +1719,11 @@ and is between 256 and 4096 characters. It is defined in the file nojitter [IA64] Disables jitter checking for ITC timers. + no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver + + no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page + fault handling. + nolapic [X86-32,APIC] Do not enable or use the local APIC. nolapic_timer [X86-32,APIC] Do not use the local APIC timer. @@ -1713,7 +1744,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 @@ -1745,7 +1776,7 @@ 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. + nowatchdog [KNL] Disable the lockup detector (NMI watchdog). nowb [ARM] @@ -1795,10 +1826,17 @@ and is between 256 and 4096 characters. It is defined in the file perfmon on Intel CPUs instead of the CPU specific event set. + oops=panic Always panic on oopses. Default is to just kill the + process, but there is a small probability of + deadlocking the machine. + This will also cause panics on machine check exceptions. + Useful together with panic=30 to trigger a reboot. + OSS [HW,OSS] See Documentation/sound/oss/oss-parameters.txt - panic= [KNL] Kernel behaviour on panic + panic= [KNL] Kernel behaviour on panic: delay <timeout> + seconds before rebooting Format: <timeout> parkbd.port= [HW] Parallel port number the keyboard adapter is @@ -2153,6 +2191,11 @@ 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. @@ -2165,6 +2208,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] @@ -2291,6 +2339,7 @@ and is between 256 and 4096 characters. It is defined in the file softlockup_panic= [KNL] Should the soft-lockup detector generate panics. + Format: <integer> sonypi.*= [HW] Sony Programmable I/O Control Device driver See Documentation/sonypi.txt @@ -2356,10 +2405,24 @@ and is between 256 and 4096 characters. It is defined in the file improve throughput, but will also increase the amount of memory reserved for use by the client. + swapaccount[=0|1] + [KNL] Enable accounting of swap in memory resource + controller if no parameter or 1 is given or disable + it if 0 is given (See Documentation/cgroups/memory.txt) + swiotlb= [IA-64] Number of I/O TLB slabs switches= [HW,M68k] + 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] Ignore sysrq setting - this boot parameter will @@ -2402,13 +2465,17 @@ and is between 256 and 4096 characters. It is defined in the file <deci-seconds>: poll all this frequency 0: no polling (default) + threadirqs [KNL] + Force threading of all interrupt handlers except those + marked explicitely IRQF_NO_THREAD. + 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 + topology information if the hardware supports this. + The scheduler will make use of this information and e.g. base its process migration decisions on it. - Default is off. + Default is on. tp720= [HW,PS2] @@ -2429,12 +2496,17 @@ and is between 256 and 4096 characters. It is defined in the file to facilitate early boot debugging. See also Documentation/trace/events.txt - tsc= Disable clocksource-must-verify flag for TSC. + tsc= Disable clocksource stability checks 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. + disables clocksource verification at runtime, as well + as the stability checks done at bootup. 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 @@ -2454,8 +2526,7 @@ and is between 256 and 4096 characters. It is defined in the file reported either. unknown_nmi_panic - [X86] - Set unknown_nmi_panic=1 early on boot. + [X86] Cause panic on unknown NMI. usbcore.autosuspend= [USB] The autosuspend time delay (in seconds) used diff --git a/Documentation/keys-request-key.txt b/Documentation/keys-request-key.txt index 09b55e461740..69686ad12c66 100644 --- a/Documentation/keys-request-key.txt +++ b/Documentation/keys-request-key.txt @@ -127,14 +127,15 @@ This is because process A's keyrings can't simply be attached to of them, and (b) it requires the same UID/GID/Groups all the way through. -====================== -NEGATIVE INSTANTIATION -====================== +==================================== +NEGATIVE INSTANTIATION AND REJECTION +==================================== Rather than instantiating a key, it is possible for the possessor of an authorisation key to negatively instantiate a key that's under construction. This is a short duration placeholder that causes any attempt at re-requesting -the key whilst it exists to fail with error ENOKEY. +the key whilst it exists to fail with error ENOKEY if negated or the specified +error if rejected. This is provided to prevent excessive repeated spawning of /sbin/request-key processes for a key that will never be obtainable. diff --git a/Documentation/keys-trusted-encrypted.txt b/Documentation/keys-trusted-encrypted.txt new file mode 100644 index 000000000000..8fb79bc1ac4b --- /dev/null +++ b/Documentation/keys-trusted-encrypted.txt @@ -0,0 +1,145 @@ + Trusted and Encrypted Keys + +Trusted and Encrypted Keys are two new key types added to the existing kernel +key ring service. Both of these new types are variable length symmetic keys, +and in both cases all keys are created in the kernel, and user space sees, +stores, and loads only encrypted blobs. Trusted Keys require the availability +of a Trusted Platform Module (TPM) chip for greater security, while Encrypted +Keys can be used on any system. All user level blobs, are displayed and loaded +in hex ascii for convenience, and are integrity verified. + +Trusted Keys use a TPM both to generate and to seal the keys. Keys are sealed +under a 2048 bit RSA key in the TPM, and optionally sealed to specified PCR +(integrity measurement) values, and only unsealed by the TPM, if PCRs and blob +integrity verifications match. A loaded Trusted Key can be updated with new +(future) PCR values, so keys are easily migrated to new pcr values, such as +when the kernel and initramfs are updated. The same key can have many saved +blobs under different PCR values, so multiple boots are easily supported. + +By default, trusted keys are sealed under the SRK, which has the default +authorization value (20 zeros). This can be set at takeownership time with the +trouser's utility: "tpm_takeownership -u -z". + +Usage: + keyctl add trusted name "new keylen [options]" ring + keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring + keyctl update key "update [options]" + keyctl print keyid + + options: + keyhandle= ascii hex value of sealing key default 0x40000000 (SRK) + keyauth= ascii hex auth for sealing key default 0x00...i + (40 ascii zeros) + blobauth= ascii hex auth for sealed data default 0x00... + (40 ascii zeros) + blobauth= ascii hex auth for sealed data default 0x00... + (40 ascii zeros) + pcrinfo= ascii hex of PCR_INFO or PCR_INFO_LONG (no default) + pcrlock= pcr number to be extended to "lock" blob + migratable= 0|1 indicating permission to reseal to new PCR values, + default 1 (resealing allowed) + +"keyctl print" returns an ascii hex copy of the sealed key, which is in standard +TPM_STORED_DATA format. The key length for new keys are always in bytes. +Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit +within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding. + +Encrypted keys do not depend on a TPM, and are faster, as they use AES for +encryption/decryption. New keys are created from kernel generated random +numbers, and are encrypted/decrypted using a specified 'master' key. The +'master' key can either be a trusted-key or user-key type. The main +disadvantage of encrypted keys is that if they are not rooted in a trusted key, +they are only as secure as the user key encrypting them. The master user key +should therefore be loaded in as secure a way as possible, preferably early in +boot. + +Usage: + keyctl add encrypted name "new key-type:master-key-name keylen" ring + keyctl add encrypted name "load hex_blob" ring + keyctl update keyid "update key-type:master-key-name" + +where 'key-type' is either 'trusted' or 'user'. + +Examples of trusted and encrypted key usage: + +Create and save a trusted key named "kmk" of length 32 bytes: + + $ keyctl add trusted kmk "new 32" @u + 440502848 + + $ keyctl show + Session Keyring + -3 --alswrv 500 500 keyring: _ses + 97833714 --alswrv 500 -1 \_ keyring: _uid.500 + 440502848 --alswrv 500 500 \_ trusted: kmk + + $ keyctl print 440502848 + 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 + 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b + 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 + a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec + d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d + dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 + f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b + e4a8aea2b607ec96931e6f4d4fe563ba + + $ keyctl pipe 440502848 > kmk.blob + +Load a trusted key from the saved blob: + + $ keyctl add trusted kmk "load `cat kmk.blob`" @u + 268728824 + + $ keyctl print 268728824 + 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 + 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b + 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 + a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec + d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d + dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 + f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b + e4a8aea2b607ec96931e6f4d4fe563ba + +Reseal a trusted key under new pcr values: + + $ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`" + $ keyctl print 268728824 + 010100000000002c0002800093c35a09b70fff26e7a98ae786c641e678ec6ffb6b46d805 + 77c8a6377aed9d3219c6dfec4b23ffe3000001005d37d472ac8a44023fbb3d18583a4f73 + d3a076c0858f6f1dcaa39ea0f119911ff03f5406df4f7f27f41da8d7194f45c9f4e00f2e + df449f266253aa3f52e55c53de147773e00f0f9aca86c64d94c95382265968c354c5eab4 + 9638c5ae99c89de1e0997242edfb0b501744e11ff9762dfd951cffd93227cc513384e7e6 + e782c29435c7ec2edafaa2f4c1fe6e7a781b59549ff5296371b42133777dcc5b8b971610 + 94bc67ede19e43ddb9dc2baacad374a36feaf0314d700af0a65c164b7082401740e489c9 + 7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef + df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8 + +Create and save an encrypted key "evm" using the above trusted key "kmk": + + $ keyctl add encrypted evm "new trusted:kmk 32" @u + 159771175 + + $ keyctl print 159771175 + trusted:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b382dbbc55 + be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e024717c64 + 5972dcb82ab2dde83376d82b2e3c09ffc + + $ keyctl pipe 159771175 > evm.blob + +Load an encrypted key "evm" from saved blob: + + $ keyctl add encrypted evm "load `cat evm.blob`" @u + 831684262 + + $ keyctl print 831684262 + trusted:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b382dbbc55 + be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e024717c64 + 5972dcb82ab2dde83376d82b2e3c09ffc + + +The initial consumer of trusted keys is EVM, which at boot time needs a high +quality symmetric key for HMAC protection of file metadata. The use of a +trusted key provides strong guarantees that the EVM key has not been +compromised by a user level problem, and when sealed to specific boot PCR +values, protects against boot and offline attacks. Other uses for trusted and +encrypted keys, such as for disk and file encryption are anticipated. diff --git a/Documentation/keys.txt b/Documentation/keys.txt index e4dbbdb1bd96..6523a9e6f293 100644 --- a/Documentation/keys.txt +++ b/Documentation/keys.txt @@ -637,6 +637,9 @@ The keyctl syscall functions are: long keyctl(KEYCTL_INSTANTIATE, key_serial_t key, const void *payload, size_t plen, key_serial_t keyring); + long keyctl(KEYCTL_INSTANTIATE_IOV, key_serial_t key, + const struct iovec *payload_iov, unsigned ioc, + key_serial_t keyring); If the kernel calls back to userspace to complete the instantiation of a key, userspace should use this call to supply data for the key before the @@ -652,11 +655,16 @@ The keyctl syscall functions are: The payload and plen arguments describe the payload data as for add_key(). + The payload_iov and ioc arguments describe the payload data in an iovec + array instead of a single buffer. + (*) Negatively instantiate a partially constructed key. long keyctl(KEYCTL_NEGATE, key_serial_t key, unsigned timeout, key_serial_t keyring); + long keyctl(KEYCTL_REJECT, key_serial_t key, + unsigned timeout, unsigned error, key_serial_t keyring); If the kernel calls back to userspace to complete the instantiation of a key, userspace should use this call mark the key as negative before the @@ -669,6 +677,10 @@ The keyctl syscall functions are: that keyring, however all the constraints applying in KEYCTL_LINK apply in this case too. + If the key is rejected, future searches for it will return the specified + error code until the rejected key expires. Negating the key is the same + as rejecting the key with ENOKEY as the error code. + (*) Set the default request-key destination keyring. @@ -1062,6 +1074,13 @@ The structure has a number of fields, some of which are mandatory: viable. + (*) int (*vet_description)(const char *description); + + This optional method is called to vet a key description. If the key type + doesn't approve of the key description, it may return an error, otherwise + it should return 0. + + (*) int (*instantiate)(struct key *key, const void *data, size_t datalen); This method is called to attach a payload to a key during construction. @@ -1231,10 +1250,11 @@ hand the request off to (perhaps a path held in placed in another key by, for example, the KDE desktop manager). The program (or whatever it calls) should finish construction of the key by -calling KEYCTL_INSTANTIATE, which also permits it to cache the key in one of -the keyrings (probably the session ring) before returning. Alternatively, the -key can be marked as negative with KEYCTL_NEGATE; this also permits the key to -be cached in one of the keyrings. +calling KEYCTL_INSTANTIATE or KEYCTL_INSTANTIATE_IOV, which also permits it to +cache the key in one of the keyrings (probably the session ring) before +returning. Alternatively, the key can be marked as negative with KEYCTL_NEGATE +or KEYCTL_REJECT; this also permits the key to be cached in one of the +keyrings. If it returns with the key remaining in the unconstructed state, the key will be marked as being negative, it will be added to the session keyring, and an diff --git a/Documentation/kmemleak.txt b/Documentation/kmemleak.txt index 34f6638aa5ac..090e6ee04536 100644 --- a/Documentation/kmemleak.txt +++ b/Documentation/kmemleak.txt @@ -11,6 +11,7 @@ with the difference that the orphan objects are not freed but only reported via /sys/kernel/debug/kmemleak. A similar method is used by the Valgrind tool (memcheck --leak-check) to detect the memory leaks in user-space applications. +Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze and tile. Usage ----- @@ -178,5 +179,4 @@ block doesn't need to be freed (some cases in the init_call functions), the pointer is calculated by other methods than the usual container_of macro or the pointer is stored in a location not scanned by kmemleak. -Page allocations and ioremap are not tracked. Only the ARM and x86 -architectures are currently supported. +Page allocations and ioremap are not tracked. diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index e3a55b6091e9..ab5189ae3428 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -391,8 +391,8 @@ bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에 bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다) 에 등록하면 된다. - http://lists.osdl.org/mailman/listinfo/bugme-new - http://lists.osdl.org/mailman/listinfo/bugme-janitors + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt index 1762b81fcdf2..0cfb00fd86ff 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/kprobes.txt @@ -542,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 @@ -596,7 +598,7 @@ a 5-byte jump instruction. So there are several limitations. a) The instructions in DCR must be relocatable. b) The instructions in DCR must not include a call instruction. c) JTPR must not be targeted by any jump or call instruction. -d) DCR must not straddle the border betweeen functions. +d) DCR must not straddle the border between functions. Anyway, these limitations are checked by the in-kernel instruction decoder, so you don't need to worry about that. diff --git a/Documentation/kref.txt b/Documentation/kref.txt index ae203f91ee9b..48ba715d5a63 100644 --- a/Documentation/kref.txt +++ b/Documentation/kref.txt @@ -156,7 +156,7 @@ static struct my_data *get_entry() struct my_data *entry = NULL; mutex_lock(&mutex); if (!list_empty(&q)) { - entry = container_of(q.next, struct my_q_entry, link); + entry = container_of(q.next, struct my_data, link); kref_get(&entry->refcount); } mutex_unlock(&mutex); diff --git a/Documentation/kvm/api.txt b/Documentation/kvm/api.txt index 5f5b64982b1a..1b9eaa7e8856 100644 --- a/Documentation/kvm/api.txt +++ b/Documentation/kvm/api.txt @@ -166,7 +166,7 @@ Returns: 0 on success, -1 on error This ioctl is obsolete and has been removed. -4.6 KVM_CREATE_VCPU +4.7 KVM_CREATE_VCPU Capability: basic Architectures: all @@ -177,7 +177,7 @@ Returns: vcpu fd on success, -1 on error This API adds a vcpu to a virtual machine. The vcpu id is a small integer in the range [0, max_vcpus). -4.7 KVM_GET_DIRTY_LOG (vm ioctl) +4.8 KVM_GET_DIRTY_LOG (vm ioctl) Capability: basic Architectures: x86 @@ -200,7 +200,7 @@ since the last call to this ioctl. Bit 0 is the first page in the memory slot. Ensure the entire structure is cleared to avoid padding issues. -4.8 KVM_SET_MEMORY_ALIAS +4.9 KVM_SET_MEMORY_ALIAS Capability: basic Architectures: x86 @@ -210,7 +210,7 @@ Returns: 0 (success), -1 (error) This ioctl is obsolete and has been removed. -4.9 KVM_RUN +4.10 KVM_RUN Capability: basic Architectures: all @@ -226,7 +226,7 @@ obtained by mmap()ing the vcpu fd at offset 0, with the size given by KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct kvm_run' (see below). -4.10 KVM_GET_REGS +4.11 KVM_GET_REGS Capability: basic Architectures: all @@ -246,7 +246,7 @@ struct kvm_regs { __u64 rip, rflags; }; -4.11 KVM_SET_REGS +4.12 KVM_SET_REGS Capability: basic Architectures: all @@ -258,7 +258,7 @@ Writes the general purpose registers into the vcpu. See KVM_GET_REGS for the data structure. -4.12 KVM_GET_SREGS +4.13 KVM_GET_SREGS Capability: basic Architectures: x86 @@ -283,7 +283,7 @@ interrupt_bitmap is a bitmap of pending external interrupts. At most one bit may be set. This interrupt has been acknowledged by the APIC but not yet injected into the cpu core. -4.13 KVM_SET_SREGS +4.14 KVM_SET_SREGS Capability: basic Architectures: x86 @@ -294,7 +294,7 @@ Returns: 0 on success, -1 on error Writes special registers into the vcpu. See KVM_GET_SREGS for the data structures. -4.14 KVM_TRANSLATE +4.15 KVM_TRANSLATE Capability: basic Architectures: x86 @@ -317,16 +317,16 @@ struct kvm_translation { __u8 pad[5]; }; -4.15 KVM_INTERRUPT +4.16 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 { @@ -334,9 +334,38 @@ struct kvm_interrupt { __u32 irq; }; +X86: + Note 'irq' is an interrupt vector, not an interrupt pin or line. -4.16 KVM_DEBUG_GUEST +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.17 KVM_DEBUG_GUEST Capability: basic Architectures: none @@ -346,7 +375,7 @@ Returns: -1 on error Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead. -4.17 KVM_GET_MSRS +4.18 KVM_GET_MSRS Capability: basic Architectures: x86 @@ -374,7 +403,7 @@ Application code should set the 'nmsrs' member (which indicates the size of the entries array) and the 'index' member of each array entry. kvm will fill in the 'data' member. -4.18 KVM_SET_MSRS +4.19 KVM_SET_MSRS Capability: basic Architectures: x86 @@ -389,7 +418,7 @@ Application code should set the 'nmsrs' member (which indicates the size of the entries array), and the 'index' and 'data' members of each array entry. -4.19 KVM_SET_CPUID +4.20 KVM_SET_CPUID Capability: basic Architectures: x86 @@ -417,7 +446,7 @@ struct kvm_cpuid { struct kvm_cpuid_entry entries[0]; }; -4.20 KVM_SET_SIGNAL_MASK +4.21 KVM_SET_SIGNAL_MASK Capability: basic Architectures: x86 @@ -439,7 +468,7 @@ struct kvm_signal_mask { __u8 sigset[0]; }; -4.21 KVM_GET_FPU +4.22 KVM_GET_FPU Capability: basic Architectures: x86 @@ -464,7 +493,7 @@ struct kvm_fpu { __u32 pad2; }; -4.22 KVM_SET_FPU +4.23 KVM_SET_FPU Capability: basic Architectures: x86 @@ -489,7 +518,7 @@ struct kvm_fpu { __u32 pad2; }; -4.23 KVM_CREATE_IRQCHIP +4.24 KVM_CREATE_IRQCHIP Capability: KVM_CAP_IRQCHIP Architectures: x86, ia64 @@ -502,7 +531,7 @@ ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a local APIC. IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23 only go to the IOAPIC. On ia64, a IOSAPIC is created. -4.24 KVM_IRQ_LINE +4.25 KVM_IRQ_LINE Capability: KVM_CAP_IRQCHIP Architectures: x86, ia64 @@ -523,7 +552,7 @@ struct kvm_irq_level { __u32 level; /* 0 or 1 */ }; -4.25 KVM_GET_IRQCHIP +4.26 KVM_GET_IRQCHIP Capability: KVM_CAP_IRQCHIP Architectures: x86, ia64 @@ -544,7 +573,7 @@ struct kvm_irqchip { } chip; }; -4.26 KVM_SET_IRQCHIP +4.27 KVM_SET_IRQCHIP Capability: KVM_CAP_IRQCHIP Architectures: x86, ia64 @@ -565,7 +594,7 @@ struct kvm_irqchip { } chip; }; -4.27 KVM_XEN_HVM_CONFIG +4.28 KVM_XEN_HVM_CONFIG Capability: KVM_CAP_XEN_HVM Architectures: x86 @@ -589,7 +618,7 @@ struct kvm_xen_hvm_config { __u8 pad2[30]; }; -4.27 KVM_GET_CLOCK +4.29 KVM_GET_CLOCK Capability: KVM_CAP_ADJUST_CLOCK Architectures: x86 @@ -607,7 +636,7 @@ struct kvm_clock_data { __u32 pad[9]; }; -4.28 KVM_SET_CLOCK +4.30 KVM_SET_CLOCK Capability: KVM_CAP_ADJUST_CLOCK Architectures: x86 @@ -625,7 +654,7 @@ struct kvm_clock_data { __u32 pad[9]; }; -4.29 KVM_GET_VCPU_EVENTS +4.31 KVM_GET_VCPU_EVENTS Capability: KVM_CAP_VCPU_EVENTS Extended by: KVM_CAP_INTR_SHADOW @@ -664,7 +693,7 @@ struct kvm_vcpu_events { KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that interrupt.shadow contains a valid state. Otherwise, this field is undefined. -4.30 KVM_SET_VCPU_EVENTS +4.32 KVM_SET_VCPU_EVENTS Capability: KVM_CAP_VCPU_EVENTS Extended by: KVM_CAP_INTR_SHADOW @@ -690,7 +719,7 @@ If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in the flags field to signal that interrupt.shadow contains a valid state and shall be written into the VCPU. -4.32 KVM_GET_DEBUGREGS +4.33 KVM_GET_DEBUGREGS Capability: KVM_CAP_DEBUGREGS Architectures: x86 @@ -708,7 +737,7 @@ struct kvm_debugregs { __u64 reserved[9]; }; -4.33 KVM_SET_DEBUGREGS +4.34 KVM_SET_DEBUGREGS Capability: KVM_CAP_DEBUGREGS Architectures: x86 @@ -721,7 +750,7 @@ Writes debug registers into the vcpu. See KVM_GET_DEBUGREGS for the data structure. The flags field is unused yet and must be cleared on entry. -4.34 KVM_SET_USER_MEMORY_REGION +4.35 KVM_SET_USER_MEMORY_REGION Capability: KVM_CAP_USER_MEM Architectures: all @@ -767,7 +796,7 @@ It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl. The KVM_SET_MEMORY_REGION does not allow fine grained control over memory allocation and is deprecated. -4.35 KVM_SET_TSS_ADDR +4.36 KVM_SET_TSS_ADDR Capability: KVM_CAP_SET_TSS_ADDR Architectures: x86 @@ -785,7 +814,7 @@ 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.36 KVM_ENABLE_CAP +4.37 KVM_ENABLE_CAP Capability: KVM_CAP_ENABLE_CAP Architectures: ppc @@ -820,7 +849,7 @@ function properly, this is the place to put them. __u8 pad[64]; }; -4.37 KVM_GET_MP_STATE +4.38 KVM_GET_MP_STATE Capability: KVM_CAP_MP_STATE Architectures: x86, ia64 @@ -845,12 +874,12 @@ Possible values are: - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and is waiting for an interrupt - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector - accesible via KVM_GET_VCPU_EVENTS) + accessible via KVM_GET_VCPU_EVENTS) This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel irqchip, the multiprocessing state must be maintained by userspace. -4.38 KVM_SET_MP_STATE +4.39 KVM_SET_MP_STATE Capability: KVM_CAP_MP_STATE Architectures: x86, ia64 @@ -864,7 +893,7 @@ 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 +4.40 KVM_SET_IDENTITY_MAP_ADDR Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR Architectures: x86 @@ -882,7 +911,7 @@ 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 +4.41 KVM_SET_BOOT_CPU_ID Capability: KVM_CAP_SET_BOOT_CPU_ID Architectures: x86, ia64 @@ -894,7 +923,7 @@ 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 +4.42 KVM_GET_XSAVE Capability: KVM_CAP_XSAVE Architectures: x86 @@ -908,7 +937,7 @@ struct kvm_xsave { This ioctl would copy current vcpu's xsave struct to the userspace. -4.42 KVM_SET_XSAVE +4.43 KVM_SET_XSAVE Capability: KVM_CAP_XSAVE Architectures: x86 @@ -922,7 +951,7 @@ struct kvm_xsave { This ioctl would copy userspace's xsave struct to the kernel. -4.43 KVM_GET_XCRS +4.44 KVM_GET_XCRS Capability: KVM_CAP_XCRS Architectures: x86 @@ -945,7 +974,7 @@ struct kvm_xcrs { This ioctl would copy current vcpu's xcrs to the userspace. -4.44 KVM_SET_XCRS +4.45 KVM_SET_XCRS Capability: KVM_CAP_XCRS Architectures: x86 @@ -968,7 +997,7 @@ struct kvm_xcrs { This ioctl would set vcpu's xcr to the value userspace specified. -4.45 KVM_GET_SUPPORTED_CPUID +4.46 KVM_GET_SUPPORTED_CPUID Capability: KVM_CAP_EXT_CPUID Architectures: x86 @@ -1013,8 +1042,9 @@ 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. The fields in each entry -are defined as follows: +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 @@ -1032,6 +1062,230 @@ are defined as follows: eax, ebx, ecx, edx: the values returned by the cpuid instruction for this function/index combination +4.47 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. + +4.48 KVM_ASSIGN_PCI_DEVICE + +Capability: KVM_CAP_DEVICE_ASSIGNMENT +Architectures: x86 ia64 +Type: vm ioctl +Parameters: struct kvm_assigned_pci_dev (in) +Returns: 0 on success, -1 on error + +Assigns a host PCI device to the VM. + +struct kvm_assigned_pci_dev { + __u32 assigned_dev_id; + __u32 busnr; + __u32 devfn; + __u32 flags; + __u32 segnr; + union { + __u32 reserved[11]; + }; +}; + +The PCI device is specified by the triple segnr, busnr, and devfn. +Identification in succeeding service requests is done via assigned_dev_id. The +following flags are specified: + +/* Depends on KVM_CAP_IOMMU */ +#define KVM_DEV_ASSIGN_ENABLE_IOMMU (1 << 0) + +4.49 KVM_DEASSIGN_PCI_DEVICE + +Capability: KVM_CAP_DEVICE_DEASSIGNMENT +Architectures: x86 ia64 +Type: vm ioctl +Parameters: struct kvm_assigned_pci_dev (in) +Returns: 0 on success, -1 on error + +Ends PCI device assignment, releasing all associated resources. + +See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is +used in kvm_assigned_pci_dev to identify the device. + +4.50 KVM_ASSIGN_DEV_IRQ + +Capability: KVM_CAP_ASSIGN_DEV_IRQ +Architectures: x86 ia64 +Type: vm ioctl +Parameters: struct kvm_assigned_irq (in) +Returns: 0 on success, -1 on error + +Assigns an IRQ to a passed-through device. + +struct kvm_assigned_irq { + __u32 assigned_dev_id; + __u32 host_irq; + __u32 guest_irq; + __u32 flags; + union { + struct { + __u32 addr_lo; + __u32 addr_hi; + __u32 data; + } guest_msi; + __u32 reserved[12]; + }; +}; + +The following flags are defined: + +#define KVM_DEV_IRQ_HOST_INTX (1 << 0) +#define KVM_DEV_IRQ_HOST_MSI (1 << 1) +#define KVM_DEV_IRQ_HOST_MSIX (1 << 2) + +#define KVM_DEV_IRQ_GUEST_INTX (1 << 8) +#define KVM_DEV_IRQ_GUEST_MSI (1 << 9) +#define KVM_DEV_IRQ_GUEST_MSIX (1 << 10) + +It is not valid to specify multiple types per host or guest IRQ. However, the +IRQ type of host and guest can differ or can even be null. + +4.51 KVM_DEASSIGN_DEV_IRQ + +Capability: KVM_CAP_ASSIGN_DEV_IRQ +Architectures: x86 ia64 +Type: vm ioctl +Parameters: struct kvm_assigned_irq (in) +Returns: 0 on success, -1 on error + +Ends an IRQ assignment to a passed-through device. + +See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified +by assigned_dev_id, flags must correspond to the IRQ type specified on +KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed. + +4.52 KVM_SET_GSI_ROUTING + +Capability: KVM_CAP_IRQ_ROUTING +Architectures: x86 ia64 +Type: vm ioctl +Parameters: struct kvm_irq_routing (in) +Returns: 0 on success, -1 on error + +Sets the GSI routing table entries, overwriting any previously set entries. + +struct kvm_irq_routing { + __u32 nr; + __u32 flags; + struct kvm_irq_routing_entry entries[0]; +}; + +No flags are specified so far, the corresponding field must be set to zero. + +struct kvm_irq_routing_entry { + __u32 gsi; + __u32 type; + __u32 flags; + __u32 pad; + union { + struct kvm_irq_routing_irqchip irqchip; + struct kvm_irq_routing_msi msi; + __u32 pad[8]; + } u; +}; + +/* gsi routing entry types */ +#define KVM_IRQ_ROUTING_IRQCHIP 1 +#define KVM_IRQ_ROUTING_MSI 2 + +No flags are specified so far, the corresponding field must be set to zero. + +struct kvm_irq_routing_irqchip { + __u32 irqchip; + __u32 pin; +}; + +struct kvm_irq_routing_msi { + __u32 address_lo; + __u32 address_hi; + __u32 data; + __u32 pad; +}; + +4.53 KVM_ASSIGN_SET_MSIX_NR + +Capability: KVM_CAP_DEVICE_MSIX +Architectures: x86 ia64 +Type: vm ioctl +Parameters: struct kvm_assigned_msix_nr (in) +Returns: 0 on success, -1 on error + +Set the number of MSI-X interrupts for an assigned device. This service can +only be called once in the lifetime of an assigned device. + +struct kvm_assigned_msix_nr { + __u32 assigned_dev_id; + __u16 entry_nr; + __u16 padding; +}; + +#define KVM_MAX_MSIX_PER_DEV 256 + +4.54 KVM_ASSIGN_SET_MSIX_ENTRY + +Capability: KVM_CAP_DEVICE_MSIX +Architectures: x86 ia64 +Type: vm ioctl +Parameters: struct kvm_assigned_msix_entry (in) +Returns: 0 on success, -1 on error + +Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting +the GSI vector to zero means disabling the interrupt. + +struct kvm_assigned_msix_entry { + __u32 assigned_dev_id; + __u32 gsi; + __u16 entry; /* The index of entry in the MSI-X table */ + __u16 padding[3]; +}; + +4.54 KVM_SET_TSC_KHZ + +Capability: KVM_CAP_TSC_CONTROL +Architectures: x86 +Type: vcpu ioctl +Parameters: virtual tsc_khz +Returns: 0 on success, -1 on error + +Specifies the tsc frequency for the virtual machine. The unit of the +frequency is KHz. + +4.55 KVM_GET_TSC_KHZ + +Capability: KVM_CAP_GET_TSC_KHZ +Architectures: x86 +Type: vcpu ioctl +Parameters: none +Returns: virtual tsc-khz on success, negative value on error + +Returns the tsc frequency of the guest. The unit of the return value is +KHz. If the host has unstable tsc this ioctl returns -EIO instead as an +error. + 5. The kvm_run structure Application code obtains a pointer to the kvm_run structure by diff --git a/Documentation/kvm/cpuid.txt b/Documentation/kvm/cpuid.txt index 14a12ea92b7f..882068538c9c 100644 --- a/Documentation/kvm/cpuid.txt +++ b/Documentation/kvm/cpuid.txt @@ -36,6 +36,9 @@ KVM_FEATURE_MMU_OP || 2 || deprecated. KVM_FEATURE_CLOCKSOURCE2 || 3 || kvmclock available at msrs || || 0x4b564d00 and 0x4b564d01 ------------------------------------------------------------------------------ +KVM_FEATURE_ASYNC_PF || 4 || async pf can be enabled by + || || writing to msr 0x4b564d02 +------------------------------------------------------------------------------ KVM_FEATURE_CLOCKSOURCE_STABLE_BIT || 24 || host will warn if no guest-side || || per-cpu warps are expected in || || kvmclock. diff --git a/Documentation/kvm/locking.txt b/Documentation/kvm/locking.txt new file mode 100644 index 000000000000..3b4cd3bf5631 --- /dev/null +++ b/Documentation/kvm/locking.txt @@ -0,0 +1,25 @@ +KVM Lock Overview +================= + +1. Acquisition Orders +--------------------- + +(to be written) + +2. Reference +------------ + +Name: kvm_lock +Type: raw_spinlock +Arch: any +Protects: - vm_list + - hardware virtualization enable/disable +Comment: 'raw' because hardware enabling/disabling must be atomic /wrt + migration. + +Name: kvm_arch::tsc_write_lock +Type: raw_spinlock +Arch: x86 +Protects: - kvm_arch::{last_tsc_write,last_tsc_nsec,last_tsc_offset} + - tsc offset in vmcb +Comment: 'raw' because updating the tsc offsets must not be preempted. diff --git a/Documentation/kvm/mmu.txt b/Documentation/kvm/mmu.txt index 142cc5136650..f46aa58389ca 100644 --- a/Documentation/kvm/mmu.txt +++ b/Documentation/kvm/mmu.txt @@ -23,7 +23,7 @@ The mmu code attempts to satisfy the following requirements: and framebuffer-based displays - footprint: keep the amount of pinned kernel memory low (most memory should be shrinkable) -- reliablity: avoid multipage or GFP_ATOMIC allocations +- reliability: avoid multipage or GFP_ATOMIC allocations Acronyms ======== diff --git a/Documentation/kvm/msr.txt b/Documentation/kvm/msr.txt index 8ddcfe84c09a..d079aed27e03 100644 --- a/Documentation/kvm/msr.txt +++ b/Documentation/kvm/msr.txt @@ -3,7 +3,6 @@ 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, @@ -151,3 +150,38 @@ MSR_KVM_SYSTEM_TIME: 0x12 return PRESENT; } else return NON_PRESENT; + +MSR_KVM_ASYNC_PF_EN: 0x4b564d02 + data: Bits 63-6 hold 64-byte aligned physical address of a + 64 byte memory area which must be in guest RAM and must be + zeroed. Bits 5-2 are reserved and should be zero. Bit 0 is 1 + when asynchronous page faults are enabled on the vcpu 0 when + disabled. Bit 2 is 1 if asynchronous page faults can be injected + when vcpu is in cpl == 0. + + First 4 byte of 64 byte memory location will be written to by + the hypervisor at the time of asynchronous page fault (APF) + injection to indicate type of asynchronous page fault. Value + of 1 means that the page referred to by the page fault is not + present. Value 2 means that the page is now available. Disabling + interrupt inhibits APFs. Guest must not enable interrupt + before the reason is read, or it may be overwritten by another + APF. Since APF uses the same exception vector as regular page + fault guest must reset the reason to 0 before it does + something that can generate normal page fault. If during page + fault APF reason is 0 it means that this is regular page + fault. + + During delivery of type 1 APF cr2 contains a token that will + be used to notify a guest when missing page becomes + available. When page becomes available type 2 APF is sent with + cr2 set to the token associated with the page. There is special + kind of token 0xffffffff which tells vcpu that it should wake + up all processes waiting for APFs and no individual type 2 APFs + will be sent. + + If APF is disabled while there are outstanding APFs, they will + not be delivered. + + Currently type 2 APF will be always delivered on the same vcpu as + type 1 was, but guest should not rely on that. diff --git a/Documentation/kvm/ppc-pv.txt b/Documentation/kvm/ppc-pv.txt new file mode 100644 index 000000000000..3ab969c59046 --- /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 accommodate 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/timekeeping.txt b/Documentation/kvm/timekeeping.txt new file mode 100644 index 000000000000..df8946377cb6 --- /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 initially 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/asus-laptop.txt b/Documentation/laptops/asus-laptop.txt index c1c5be84e4b1..803e51f6768b 100644 --- a/Documentation/laptops/asus-laptop.txt +++ b/Documentation/laptops/asus-laptop.txt @@ -61,7 +61,7 @@ Usage Hotkeys are also reported as input keys (like keyboards) you can check which key are supported using "xev" under X11. - You can get informations on the version of your DSDT table by reading the + You can get information on the version of your DSDT table by reading the /sys/devices/platform/asus-laptop/infos entry. If you have a question or a bug report to do, please include the output of this entry. @@ -178,7 +178,7 @@ LED display ----------- Some models like the W1N have a LED display that can be used to display - several informations. + several items of information. LED display works for the following models: W1000N diff --git a/Documentation/hwmon/hpfall.c b/Documentation/laptops/hpfall.c index a4a8fc5d05d4..a4a8fc5d05d4 100644 --- a/Documentation/hwmon/hpfall.c +++ b/Documentation/laptops/hpfall.c diff --git a/Documentation/laptops/sony-laptop.txt b/Documentation/laptops/sony-laptop.txt index 23ce7d350d1a..2bd4e82e5d9f 100644 --- a/Documentation/laptops/sony-laptop.txt +++ b/Documentation/laptops/sony-laptop.txt @@ -14,7 +14,8 @@ Some models report hotkeys through the SNC or SPIC devices, such events are reported both through the ACPI subsystem as acpi events and through the INPUT subsystem. See the logs of acpid or /proc/acpi/event and /proc/bus/input/devices to find out what those events are and which input -devices are created by the driver. +devices are created by the driver. Additionally, loading the driver with the +debug option will report all events in the kernel log. Backlight control: ------------------ @@ -64,6 +65,16 @@ powers off the sound card, # echo "1" > /sys/devices/platform/sony-laptop/audiopower powers on the sound card. + +RFkill control: +--------------- +More recent Vaio models expose a consistent set of ACPI methods to +control radio frequency emitting devices. If you are a lucky owner of +such a laptop you will find the necessary rfkill devices under +/sys/class/rfkill. Check those starting with sony-* in + # grep . /sys/class/rfkill/*/{state,name} + + Development: ------------ @@ -75,8 +86,21 @@ pass the option 'debug=1'. REPEAT: DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS. In your kernel logs you will find the list of all ACPI methods -the SNC device has on your laptop. You can see the GCDP/GCDP methods -used to pwer on/off the CD drive, but there are others. +the SNC device has on your laptop. + +* For new models you will see a long list of meaningless method names, +reading the DSDT table source should reveal that: +(1) the SNC device uses an internal capability lookup table +(2) SN00 is used to find values in the lookup table +(3) SN06 and SN07 are used to call into the real methods based on + offsets you can obtain iterating the table using SN00 +(4) SN02 used to enable events. +Some values in the capability lookup table are more or less known, see +the code for all sony_call_snc_handle calls, others are more obscure. + +* For old models you can see the GCDP/GCDP methods used to pwer on/off +the CD drive, but there are others and they are usually different from +model to model. I HAVE NO IDEA WHAT THOSE METHODS DO. @@ -108,9 +132,8 @@ Bugs/Limitations: laptop, including permanent damage. * The sony-laptop and sonypi drivers do not interact at all. In the - future, sonypi could use sony-laptop to do (part of) its business. + future, sonypi will be removed and replaced by sony-laptop. * spicctrl, which is the userspace tool used to communicate with the - sonypi driver (through /dev/sonypi) does not try to use the - sony-laptop driver. In the future, spicctrl could try sonypi first, - and if it isn't present, try sony-laptop instead. + sonypi driver (through /dev/sonypi) is deprecated as well since all + its features are now available under the sysfs tree via sony-laptop. diff --git a/Documentation/leds/00-INDEX b/Documentation/leds/00-INDEX new file mode 100644 index 000000000000..29f481df32c7 --- /dev/null +++ b/Documentation/leds/00-INDEX @@ -0,0 +1,8 @@ +leds-class.txt + - documents LED handling under Linux. +leds-lp3944.txt + - notes on how to use the leds-lp3944 driver. +leds-lp5521.txt + - notes on how to use the leds-lp5521 driver. +leds-lp5523.txt + - notes on how to use the leds-lp5523 driver. diff --git a/Documentation/leds-class.txt b/Documentation/leds/leds-class.txt index 8fd5ca2ae32d..4996586e27e8 100644 --- a/Documentation/leds-class.txt +++ b/Documentation/leds/leds-class.txt @@ -60,15 +60,18 @@ Hardware accelerated blink of LEDs Some LEDs can be programmed to blink without any CPU interaction. To support this feature, a LED driver can optionally implement the -blink_set() function (see <linux/leds.h>). If implemented, triggers can -attempt to use it before falling back to software timers. The blink_set() -function should return 0 if the blink setting is supported, or -EINVAL -otherwise, which means that LED blinking will be handled by software. +blink_set() function (see <linux/leds.h>). To set an LED to blinking, +however, it is better to use use the API function led_blink_set(), +as it will check and implement software fallback if necessary. -The blink_set() function should choose a user friendly blinking -value if it is called with *delay_on==0 && *delay_off==0 parameters. In -this case the driver should give back the chosen value through delay_on -and delay_off parameters to the leds subsystem. +To turn off blinking again, use the API function led_brightness_set() +as that will not just set the LED brightness but also stop any software +timers that may have been required for blinking. + +The blink_set() function should choose a user friendly blinking value +if it is called with *delay_on==0 && *delay_off==0 parameters. In this +case the driver should give back the chosen value through delay_on and +delay_off parameters to the leds subsystem. Setting the brightness to zero with brightness_set() callback function should completely turn off the LED and cancel the previously programmed @@ -92,4 +95,3 @@ There are a number of cases where a trigger might only be mappable to a particular LED (ACPI?). The addition of triggers provided by the LED driver should cover this option and be possible to add without breaking the current interface. - diff --git a/Documentation/leds-lp3944.txt b/Documentation/leds/leds-lp3944.txt index c6eda18b15ef..c6eda18b15ef 100644 --- a/Documentation/leds-lp3944.txt +++ b/Documentation/leds/leds-lp3944.txt diff --git a/Documentation/leds/leds-lp5521.txt b/Documentation/leds/leds-lp5521.txt new file mode 100644 index 000000000000..c4d8d151e0fe --- /dev/null +++ b/Documentation/leds/leds-lp5521.txt @@ -0,0 +1,88 @@ +Kernel driver for lp5521 +======================== + +* National Semiconductor LP5521 led driver chip +* Datasheet: http://www.national.com/pf/LP/LP5521.html + +Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo +Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com) + +Description +----------- + +LP5521 can drive up to 3 channels. Leds can be controlled directly via +the led class control interface. Channels have generic names: +lp5521:channelx, where x is 0 .. 2 + +All three channels can be also controlled using the engine micro programs. +More details of the instructions can be found from the public data sheet. + +Control interface for the engines: +x is 1 .. 3 +enginex_mode : disabled, load, run +enginex_load : store program (visible only in engine load mode) + +Example (start to blink the channel 2 led): +cd /sys/class/leds/lp5521:channel2/device +echo "load" > engine3_mode +echo "037f4d0003ff6000" > engine3_load +echo "run" > engine3_mode + +stop the engine: +echo "disabled" > engine3_mode + +sysfs contains a selftest entry. +The test communicates with the chip and checks that +the clock mode is automatically set to the requested one. + +Each channel has its own led current settings. +/sys/class/leds/lp5521:channel0/led_current - RW +/sys/class/leds/lp5521:channel0/max_current - RO +Format: 10x mA i.e 10 means 1.0 mA + +example platform data: + +Note: chan_nr can have values between 0 and 2. + +static struct lp5521_led_config lp5521_led_config[] = { + { + .chan_nr = 0, + .led_current = 50, + .max_current = 130, + }, { + .chan_nr = 1, + .led_current = 0, + .max_current = 130, + }, { + .chan_nr = 2, + .led_current = 0, + .max_current = 130, + } +}; + +static int lp5521_setup(void) +{ + /* setup HW resources */ +} + +static void lp5521_release(void) +{ + /* Release HW resources */ +} + +static void lp5521_enable(bool state) +{ + /* Control of chip enable signal */ +} + +static struct lp5521_platform_data lp5521_platform_data = { + .led_config = lp5521_led_config, + .num_channels = ARRAY_SIZE(lp5521_led_config), + .clock_mode = LP5521_CLOCK_EXT, + .setup_resources = lp5521_setup, + .release_resources = lp5521_release, + .enable = lp5521_enable, +}; + +If the current is set to 0 in the platform data, that channel is +disabled and it is not visible in the sysfs. diff --git a/Documentation/leds/leds-lp5523.txt b/Documentation/leds/leds-lp5523.txt new file mode 100644 index 000000000000..fad2feb8b7ce --- /dev/null +++ b/Documentation/leds/leds-lp5523.txt @@ -0,0 +1,83 @@ +Kernel driver for lp5523 +======================== + +* National Semiconductor LP5523 led driver chip +* Datasheet: http://www.national.com/pf/LP/LP5523.html + +Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo +Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com) + +Description +----------- +LP5523 can drive up to 9 channels. Leds can be controlled directly via +the led class control interface. Channels have generic names: +lp5523:channelx where x is 0...8 + +The chip provides 3 engines. Each engine can control channels without +interaction from the main CPU. Details of the micro engine code can be found +from the public data sheet. Leds can be muxed to different channels. + +Control interface for the engines: +x is 1 .. 3 +enginex_mode : disabled, load, run +enginex_load : microcode load (visible only in load mode) +enginex_leds : led mux control (visible only in load mode) + +cd /sys/class/leds/lp5523:channel2/device +echo "load" > engine3_mode +echo "9d80400004ff05ff437f0000" > engine3_load +echo "111111111" > engine3_leds +echo "run" > engine3_mode + +sysfs contains a selftest entry. It measures each channel +voltage level and checks if it looks reasonable. If the level is too high, +the led is missing; if the level is too low, there is a short circuit. + +Selftest uses always the current from the platform data. + +Each channel contains led current settings. +/sys/class/leds/lp5523:channel2/led_current - RW +/sys/class/leds/lp5523:channel2/max_current - RO +Format: 10x mA i.e 10 means 1.0 mA + +Example platform data: + +Note - chan_nr can have values between 0 and 8. + +static struct lp5523_led_config lp5523_led_config[] = { + { + .chan_nr = 0, + .led_current = 50, + .max_current = 130, + }, +... + }, { + .chan_nr = 8, + .led_current = 50, + .max_current = 130, + } +}; + +static int lp5523_setup(void) +{ + /* Setup HW resources */ +} + +static void lp5523_release(void) +{ + /* Release HW resources */ +} + +static void lp5523_enable(bool state) +{ + /* Control chip enable signal */ +} + +static struct lp5523_platform_data lp5523_platform_data = { + .led_config = lp5523_led_config, + .num_channels = ARRAY_SIZE(lp5523_led_config), + .clock_mode = LP5523_CLOCK_EXT, + .setup_resources = lp5523_setup, + .release_resources = lp5523_release, + .enable = lp5523_enable, +}; diff --git a/Documentation/lguest/lguest.c b/Documentation/lguest/lguest.c index 8a6a8c6d4980..d9da7e148538 100644 --- a/Documentation/lguest/lguest.c +++ b/Documentation/lguest/lguest.c @@ -39,6 +39,9 @@ #include <limits.h> #include <stddef.h> #include <signal.h> +#include <pwd.h> +#include <grp.h> + #include <linux/virtio_config.h> #include <linux/virtio_net.h> #include <linux/virtio_blk.h> @@ -298,20 +301,27 @@ static void *map_zeroed_pages(unsigned int num) /* * We use a private mapping (ie. if we write to the page, it will be - * copied). + * copied). We allocate an extra two pages PROT_NONE to act as guard + * pages against read/write attempts that exceed allocated space. */ - addr = mmap(NULL, getpagesize() * num, - PROT_READ|PROT_WRITE|PROT_EXEC, MAP_PRIVATE, fd, 0); + addr = mmap(NULL, getpagesize() * (num+2), + PROT_NONE, MAP_PRIVATE, fd, 0); + if (addr == MAP_FAILED) err(1, "Mmapping %u pages of /dev/zero", num); + if (mprotect(addr + getpagesize(), getpagesize() * num, + PROT_READ|PROT_WRITE) == -1) + err(1, "mprotect rw %u pages failed", num); + /* * One neat mmap feature is that you can close the fd, and it * stays mapped. */ close(fd); - return addr; + /* Return address after PROT_NONE page */ + return addr + getpagesize(); } /* Get some more pages for a device. */ @@ -343,7 +353,7 @@ static void map_at(int fd, void *addr, unsigned long offset, unsigned long len) * done to it. This allows us to share untouched memory between * Guests. */ - if (mmap(addr, len, PROT_READ|PROT_WRITE|PROT_EXEC, + if (mmap(addr, len, PROT_READ|PROT_WRITE, MAP_FIXED|MAP_PRIVATE, fd, offset) != MAP_FAILED) return; @@ -573,10 +583,10 @@ static void *_check_pointer(unsigned long addr, unsigned int size, unsigned int line) { /* - * We have to separately check addr and addr+size, because size could - * be huge and addr + size might wrap around. + * Check if the requested address and size exceeds the allocated memory, + * or addr + size wraps around. */ - if (addr >= guest_limit || addr + size >= guest_limit) + if ((addr + size) > guest_limit || (addr + size) < addr) errx(1, "%s:%i: Invalid address %#lx", __FILE__, line, addr); /* * We return a pointer for the caller's convenience, now we know it's @@ -1640,15 +1650,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. */ @@ -1680,6 +1681,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 { @@ -1703,15 +1711,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); } @@ -1736,8 +1735,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); @@ -1883,6 +1882,8 @@ static struct option opts[] = { { "block", 1, NULL, 'b' }, { "rng", 0, NULL, 'r' }, { "initrd", 1, NULL, 'i' }, + { "username", 1, NULL, 'u' }, + { "chroot", 1, NULL, 'c' }, { NULL }, }; static void usage(void) @@ -1905,6 +1906,12 @@ int main(int argc, char *argv[]) /* If they specify an initrd file to load. */ const char *initrd_name = NULL; + /* Password structure for initgroups/setres[gu]id */ + struct passwd *user_details = NULL; + + /* Directory to chroot to */ + char *chroot_path = NULL; + /* Save the args: we "reboot" by execing ourselves again. */ main_args = argv; @@ -1961,6 +1968,14 @@ int main(int argc, char *argv[]) case 'i': initrd_name = optarg; break; + case 'u': + user_details = getpwnam(optarg); + if (!user_details) + err(1, "getpwnam failed, incorrect username?"); + break; + case 'c': + chroot_path = optarg; + break; default: warnx("Unknown argument %s", argv[optind]); usage(); @@ -2032,6 +2047,37 @@ int main(int argc, char *argv[]) /* If we exit via err(), this kills all the threads, restores tty. */ atexit(cleanup_devices); + /* If requested, chroot to a directory */ + if (chroot_path) { + if (chroot(chroot_path) != 0) + err(1, "chroot(\"%s\") failed", chroot_path); + + if (chdir("/") != 0) + err(1, "chdir(\"/\") failed"); + + verbose("chroot done\n"); + } + + /* If requested, drop privileges */ + if (user_details) { + uid_t u; + gid_t g; + + u = user_details->pw_uid; + g = user_details->pw_gid; + + if (initgroups(user_details->pw_name, g) != 0) + err(1, "initgroups failed"); + + if (setresgid(g, g, g) != 0) + err(1, "setresgid failed"); + + if (setresuid(u, u, u) != 0) + err(1, "setresuid failed"); + + verbose("Dropping privileges completed\n"); + } + /* Finally, run the Guest. This doesn't return. */ run_guest(); } diff --git a/Documentation/lguest/lguest.txt b/Documentation/lguest/lguest.txt index efb3a6a045a2..dad99978a6a8 100644 --- a/Documentation/lguest/lguest.txt +++ b/Documentation/lguest/lguest.txt @@ -111,8 +111,16 @@ Running Lguest: Then use --tunnet=bridge:lg0 when launching the guest. - See http://linux-net.osdl.org/index.php/Bridge for general information - on how to get bridging working. + See: + + http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge + + for general information on how to get bridging to work. + +- Random number generation. Using the --rng option will provide a + /dev/hwrng in the guest that will read from the host's /dev/random. + Use this option in conjunction with rng-tools (see ../hw_random.txt) + to provide entropy to the guest kernel's /dev/random. There is a helpful mailing list at http://ozlabs.org/mailman/listinfo/lguest diff --git a/Documentation/magic-number.txt b/Documentation/magic-number.txt index 505f19607542..4b12abcb2ad3 100644 --- a/Documentation/magic-number.txt +++ b/Documentation/magic-number.txt @@ -150,7 +150,7 @@ NBD_REPLY_MAGIC 0x96744668 nbd_reply include/linux/nbd.h STL_BOARDMAGIC 0xa2267f52 stlbrd include/linux/stallion.h ENI155_MAGIC 0xa54b872d midway_eprom drivers/atm/eni.h SCI_MAGIC 0xbabeface gs_port drivers/char/sh-sci.h -CODA_MAGIC 0xC0DAC0DA coda_file_info include/linux/coda_fs_i.h +CODA_MAGIC 0xC0DAC0DA coda_file_info fs/coda/coda_fs_i.h DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram drivers/scsi/gdth.h STLI_PORTMAGIC 0xe671c7a1 stliport include/linux/istallion.h YAM_MAGIC 0xF10A7654 yam_port drivers/net/hamradio/yam.c diff --git a/Documentation/make/headers_install.txt b/Documentation/make/headers_install.txt index f2481cabffcb..951eb9f1e040 100644 --- a/Documentation/make/headers_install.txt +++ b/Documentation/make/headers_install.txt @@ -39,8 +39,9 @@ INSTALL_HDR_PATH indicates where to install the headers. It defaults to The command "make headers_install_all" exports headers for all architectures simultaneously. (This is mostly of interest to distribution maintainers, who create an architecture-independent tarball from the resulting include -directory.) Remember to provide the appropriate linux/asm directory via "mv" -or "ln -s" before building a C library with headers exported this way. +directory.) You also can use HDR_ARCH_LIST to specify list of architectures. +Remember to provide the appropriate linux/asm directory via "mv" or "ln -s" +before building a C library with headers exported this way. The kernel header export infrastructure is maintained by David Woodhouse <dwmw2@infradead.org>. diff --git a/Documentation/media-framework.txt b/Documentation/media-framework.txt new file mode 100644 index 000000000000..76a2087db205 --- /dev/null +++ b/Documentation/media-framework.txt @@ -0,0 +1,353 @@ +Linux kernel media framework +============================ + +This document describes the Linux kernel media framework, its data structures, +functions and their usage. + + +Introduction +------------ + +The media controller API is documented in DocBook format in +Documentation/DocBook/v4l/media-controller.xml. This document will focus on +the kernel-side implementation of the media framework. + + +Abstract media device model +--------------------------- + +Discovering a device internal topology, and configuring it at runtime, is one +of the goals of the media framework. To achieve this, hardware devices are +modeled as an oriented graph of building blocks called entities connected +through pads. + +An entity is a basic media hardware building block. It can correspond to +a large variety of logical blocks such as physical hardware devices +(CMOS sensor for instance), logical hardware devices (a building block +in a System-on-Chip image processing pipeline), DMA channels or physical +connectors. + +A pad is a connection endpoint through which an entity can interact with +other entities. Data (not restricted to video) produced by an entity +flows from the entity's output to one or more entity inputs. Pads should +not be confused with physical pins at chip boundaries. + +A link is a point-to-point oriented connection between two pads, either +on the same entity or on different entities. Data flows from a source +pad to a sink pad. + + +Media device +------------ + +A media device is represented by a struct media_device instance, defined in +include/media/media-device.h. Allocation of the structure is handled by the +media device driver, usually by embedding the media_device instance in a +larger driver-specific structure. + +Drivers register media device instances by calling + + media_device_register(struct media_device *mdev); + +The caller is responsible for initializing the media_device structure before +registration. The following fields must be set: + + - dev must point to the parent device (usually a pci_dev, usb_interface or + platform_device instance). + + - model must be filled with the device model name as a NUL-terminated UTF-8 + string. The device/model revision must not be stored in this field. + +The following fields are optional: + + - serial is a unique serial number stored as a NUL-terminated ASCII string. + The field is big enough to store a GUID in text form. If the hardware + doesn't provide a unique serial number this field must be left empty. + + - bus_info represents the location of the device in the system as a + NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to + "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices, + the usb_make_path() function must be used. This field is used by + applications to distinguish between otherwise identical devices that don't + provide a serial number. + + - hw_revision is the hardware device revision in a driver-specific format. + When possible the revision should be formatted with the KERNEL_VERSION + macro. + + - driver_version is formatted with the KERNEL_VERSION macro. The version + minor must be incremented when new features are added to the userspace API + without breaking binary compatibility. The version major must be + incremented when binary compatibility is broken. + +Upon successful registration a character device named media[0-9]+ is created. +The device major and minor numbers are dynamic. The model name is exported as +a sysfs attribute. + +Drivers unregister media device instances by calling + + media_device_unregister(struct media_device *mdev); + +Unregistering a media device that hasn't been registered is *NOT* safe. + + +Entities, pads and links +------------------------ + +- Entities + +Entities are represented by a struct media_entity instance, defined in +include/media/media-entity.h. The structure is usually embedded into a +higher-level structure, such as a v4l2_subdev or video_device instance, +although drivers can allocate entities directly. + +Drivers initialize entities by calling + + media_entity_init(struct media_entity *entity, u16 num_pads, + struct media_pad *pads, u16 extra_links); + +The media_entity name, type, flags, revision and group_id fields can be +initialized before or after calling media_entity_init. Entities embedded in +higher-level standard structures can have some of those fields set by the +higher-level framework. + +As the number of pads is known in advance, the pads array is not allocated +dynamically but is managed by the entity driver. Most drivers will embed the +pads array in a driver-specific structure, avoiding dynamic allocation. + +Drivers must set the direction of every pad in the pads array before calling +media_entity_init. The function will initialize the other pads fields. + +Unlike the number of pads, the total number of links isn't always known in +advance by the entity driver. As an initial estimate, media_entity_init +pre-allocates a number of links equal to the number of pads plus an optional +number of extra links. The links array will be reallocated if it grows beyond +the initial estimate. + +Drivers register entities with a media device by calling + + media_device_register_entity(struct media_device *mdev, + struct media_entity *entity); + +Entities are identified by a unique positive integer ID. Drivers can provide an +ID by filling the media_entity id field prior to registration, or request the +media controller framework to assign an ID automatically. Drivers that provide +IDs manually must ensure that all IDs are unique. IDs are not guaranteed to be +contiguous even when they are all assigned automatically by the framework. + +Drivers unregister entities by calling + + media_device_unregister_entity(struct media_entity *entity); + +Unregistering an entity will not change the IDs of the other entities, and the +ID will never be reused for a newly registered entity. + +When a media device is unregistered, all its entities are unregistered +automatically. No manual entities unregistration is then required. + +Drivers free resources associated with an entity by calling + + media_entity_cleanup(struct media_entity *entity); + +This function must be called during the cleanup phase after unregistering the +entity. Note that the media_entity instance itself must be freed explicitly by +the driver if required. + +Entities have flags that describe the entity capabilities and state. + + MEDIA_ENT_FL_DEFAULT indicates the default entity for a given type. + This can be used to report the default audio and video devices or the + default camera sensor. + +Logical entity groups can be defined by setting the group ID of all member +entities to the same non-zero value. An entity group serves no purpose in the +kernel, but is reported to userspace during entities enumeration. The group_id +field belongs to the media device driver and must not by touched by entity +drivers. + +Media device drivers should define groups if several entities are logically +bound together. Example usages include reporting + + - ALSA, VBI and video nodes that carry the same media stream + - lens and flash controllers associated with a sensor + +- Pads + +Pads are represented by a struct media_pad instance, defined in +include/media/media-entity.h. Each entity stores its pads in a pads array +managed by the entity driver. Drivers usually embed the array in a +driver-specific structure. + +Pads are identified by their entity and their 0-based index in the pads array. +Both information are stored in the media_pad structure, making the media_pad +pointer the canonical way to store and pass link references. + +Pads have flags that describe the pad capabilities and state. + + MEDIA_PAD_FL_SINK indicates that the pad supports sinking data. + MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data. + +One and only one of MEDIA_PAD_FL_SINK and MEDIA_PAD_FL_SOURCE must be set for +each pad. + +- Links + +Links are represented by a struct media_link instance, defined in +include/media/media-entity.h. Each entity stores all links originating at or +targeting any of its pads in a links array. A given link is thus stored +twice, once in the source entity and once in the target entity. The array is +pre-allocated and grows dynamically as needed. + +Drivers create links by calling + + media_entity_create_link(struct media_entity *source, u16 source_pad, + struct media_entity *sink, u16 sink_pad, + u32 flags); + +An entry in the link array of each entity is allocated and stores pointers +to source and sink pads. + +Links have flags that describe the link capabilities and state. + + MEDIA_LNK_FL_ENABLED indicates that the link is enabled and can be used + to transfer media data. When two or more links target a sink pad, only + one of them can be enabled at a time. + MEDIA_LNK_FL_IMMUTABLE indicates that the link enabled state can't be + modified at runtime. If MEDIA_LNK_FL_IMMUTABLE is set, then + MEDIA_LNK_FL_ENABLED must also be set since an immutable link is always + enabled. + + +Graph traversal +--------------- + +The media framework provides APIs to iterate over entities in a graph. + +To iterate over all entities belonging to a media device, drivers can use the +media_device_for_each_entity macro, defined in include/media/media-device.h. + + struct media_entity *entity; + + media_device_for_each_entity(entity, mdev) { + /* entity will point to each entity in turn */ + ... + } + +Drivers might also need to iterate over all entities in a graph that can be +reached only through enabled links starting at a given entity. The media +framework provides a depth-first graph traversal API for that purpose. + +Note that graphs with cycles (whether directed or undirected) are *NOT* +supported by the graph traversal API. To prevent infinite loops, the graph +traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH, +currently defined as 16. + +Drivers initiate a graph traversal by calling + + media_entity_graph_walk_start(struct media_entity_graph *graph, + struct media_entity *entity); + +The graph structure, provided by the caller, is initialized to start graph +traversal at the given entity. + +Drivers can then retrieve the next entity by calling + + media_entity_graph_walk_next(struct media_entity_graph *graph); + +When the graph traversal is complete the function will return NULL. + +Graph traversal can be interrupted at any moment. No cleanup function call is +required and the graph structure can be freed normally. + +Helper functions can be used to find a link between two given pads, or a pad +connected to another pad through an enabled link + + media_entity_find_link(struct media_pad *source, + struct media_pad *sink); + + media_entity_remote_source(struct media_pad *pad); + +Refer to the kerneldoc documentation for more information. + + +Use count and power handling +---------------------------- + +Due to the wide differences between drivers regarding power management needs, +the media controller does not implement power management. However, the +media_entity structure includes a use_count field that media drivers can use to +track the number of users of every entity for power management needs. + +The use_count field is owned by media drivers and must not be touched by entity +drivers. Access to the field must be protected by the media device graph_mutex +lock. + + +Links setup +----------- + +Link properties can be modified at runtime by calling + + media_entity_setup_link(struct media_link *link, u32 flags); + +The flags argument contains the requested new link flags. + +The only configurable property is the ENABLED link flag to enable/disable a +link. Links marked with the IMMUTABLE link flag can not be enabled or disabled. + +When a link is enabled or disabled, the media framework calls the +link_setup operation for the two entities at the source and sink of the link, +in that order. If the second link_setup call fails, another link_setup call is +made on the first entity to restore the original link flags. + +Media device drivers can be notified of link setup operations by setting the +media_device::link_notify pointer to a callback function. If provided, the +notification callback will be called before enabling and after disabling +links. + +Entity drivers must implement the link_setup operation if any of their links +is non-immutable. The operation must either configure the hardware or store +the configuration information to be applied later. + +Link configuration must not have any side effect on other links. If an enabled +link at a sink pad prevents another link at the same pad from being disabled, +the link_setup operation must return -EBUSY and can't implicitly disable the +first enabled link. + + +Pipelines and media streams +--------------------------- + +When starting streaming, drivers must notify all entities in the pipeline to +prevent link states from being modified during streaming by calling + + media_entity_pipeline_start(struct media_entity *entity, + struct media_pipeline *pipe); + +The function will mark all entities connected to the given entity through +enabled links, either directly or indirectly, as streaming. + +The media_pipeline instance pointed to by the pipe argument will be stored in +every entity in the pipeline. Drivers should embed the media_pipeline structure +in higher-level pipeline structures and can then access the pipeline through +the media_entity pipe field. + +Calls to media_entity_pipeline_start() can be nested. The pipeline pointer must +be identical for all nested calls to the function. + +When stopping the stream, drivers must notify the entities with + + media_entity_pipeline_stop(struct media_entity *entity); + +If multiple calls to media_entity_pipeline_start() have been made the same +number of media_entity_pipeline_stop() calls are required to stop streaming. The +media_entity pipe field is reset to NULL on the last nested stop call. + +Link configuration will fail with -EBUSY by default if either end of the link is +a streaming entity. Links that can be modified while streaming must be marked +with the MEDIA_LNK_FL_DYNAMIC flag. + +If other operations need to be disallowed on streaming entities (such as +changing entities configuration parameters) drivers can explicitly check the +media_entity stream_count field to find out if an entity is streaming. This +operation must be done with the media_device graph_mutex held. diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 631ad2f1b229..f0d3a8026a56 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -21,6 +21,7 @@ Contents: - SMP barrier pairing. - Examples of memory barrier sequences. - Read memory barriers vs load speculation. + - Transitivity (*) Explicit kernel barriers. @@ -959,6 +960,63 @@ the speculation will be cancelled and the value reloaded: retrieved : : +-------+ +TRANSITIVITY +------------ + +Transitivity is a deeply intuitive notion about ordering that is not +always provided by real computer systems. The following example +demonstrates transitivity (also called "cumulativity"): + + CPU 1 CPU 2 CPU 3 + ======================= ======================= ======================= + { X = 0, Y = 0 } + STORE X=1 LOAD X STORE Y=1 + <general barrier> <general barrier> + LOAD Y LOAD X + +Suppose that CPU 2's load from X returns 1 and its load from Y returns 0. +This indicates that CPU 2's load from X in some sense follows CPU 1's +store to X and that CPU 2's load from Y in some sense preceded CPU 3's +store to Y. The question is then "Can CPU 3's load from X return 0?" + +Because CPU 2's load from X in some sense came after CPU 1's store, it +is natural to expect that CPU 3's load from X must therefore return 1. +This expectation is an example of transitivity: if a load executing on +CPU A follows a load from the same variable executing on CPU B, then +CPU A's load must either return the same value that CPU B's load did, +or must return some later value. + +In the Linux kernel, use of general memory barriers guarantees +transitivity. Therefore, in the above example, if CPU 2's load from X +returns 1 and its load from Y returns 0, then CPU 3's load from X must +also return 1. + +However, transitivity is -not- guaranteed for read or write barriers. +For example, suppose that CPU 2's general barrier in the above example +is changed to a read barrier as shown below: + + CPU 1 CPU 2 CPU 3 + ======================= ======================= ======================= + { X = 0, Y = 0 } + STORE X=1 LOAD X STORE Y=1 + <read barrier> <general barrier> + LOAD Y LOAD X + +This substitution destroys transitivity: in this example, it is perfectly +legal for CPU 2's load from X to return 1, its load from Y to return 0, +and CPU 3's load from X to return 0. + +The key point is that although CPU 2's read barrier orders its pair +of loads, it does not guarantee to order CPU 1's store. Therefore, if +this example runs on a system where CPUs 1 and 2 share a store buffer +or a level of cache, CPU 2 might have early access to CPU 1's writes. +General barriers are therefore required to ensure that all CPUs agree +on the combined order of CPU 1's and CPU 2's accesses. + +To reiterate, if your code requires transitivity, use general barriers +throughout. + + ======================== EXPLICIT KERNEL BARRIERS ======================== diff --git a/Documentation/memory-hotplug.txt b/Documentation/memory-hotplug.txt index 57e7e9cc1870..8f485d72cf25 100644 --- a/Documentation/memory-hotplug.txt +++ b/Documentation/memory-hotplug.txt @@ -126,36 +126,51 @@ config options. -------------------------------- 4 sysfs files for memory hotplug -------------------------------- -All sections have their device information under /sys/devices/system/memory as +All sections have their device information in sysfs. Each section is part of +a memory block under /sys/devices/system/memory as /sys/devices/system/memory/memoryXXX -(XXX is section id.) +(XXX is the section id.) -Now, XXX is defined as start_address_of_section / section_size. +Now, XXX is defined as (start_address_of_section / section_size) of the first +section contained in the memory block. The files 'phys_index' and +'end_phys_index' under each directory report the beginning and end section id's +for the memory block covered by the sysfs directory. It is expected that all +memory sections in this range are present and no memory holes exist in the +range. Currently there is no way to determine if there is a memory hole, but +the existence of one should not affect the hotplug capabilities of the memory +block. For example, assume 1GiB section size. A device for a memory starting at 0x100000000 is /sys/device/system/memory/memory4 (0x100000000 / 1Gib = 4) This device covers address range [0x100000000 ... 0x140000000) -Under each section, you can see 4 files. +Under each section, you can see 4 or 5 files, the end_phys_index file being +a recent addition and not present on older kernels. -/sys/devices/system/memory/memoryXXX/phys_index +/sys/devices/system/memory/memoryXXX/start_phys_index +/sys/devices/system/memory/memoryXXX/end_phys_index /sys/devices/system/memory/memoryXXX/phys_device /sys/devices/system/memory/memoryXXX/state /sys/devices/system/memory/memoryXXX/removable -'phys_index' : read-only and contains section id, same as XXX. -'state' : read-write - at read: contains online/offline state of memory. - at write: user can specify "online", "offline" command -'phys_device': read-only: designed to show the name of physical memory device. - This is not well implemented now. -'removable' : read-only: contains an integer value indicating - whether the memory section is removable or not - removable. A value of 1 indicates that the memory - section is removable and a value of 0 indicates that - it is not removable. +'phys_index' : read-only and contains section id of the first section + in the memory block, same as XXX. +'end_phys_index' : read-only and contains section id of the last section + in the memory block. +'state' : read-write + at read: contains online/offline state of memory. + at write: user can specify "online", "offline" command + which will be performed on al sections in the block. +'phys_device' : read-only: designed to show the name of physical memory + device. This is not well implemented now. +'removable' : read-only: contains an integer value indicating + whether the memory block is removable or not + removable. A value of 1 indicates that the memory + block is removable and a value of 0 indicates that + it is not removable. A memory block is removable only if + every section in the block is removable. NOTE: These directories/files appear after physical memory hotplug phase. diff --git a/Documentation/mips/AU1xxx_IDE.README b/Documentation/mips/AU1xxx_IDE.README index 8ace35ebdcd5..cc887ecfd6eb 100644 --- a/Documentation/mips/AU1xxx_IDE.README +++ b/Documentation/mips/AU1xxx_IDE.README @@ -39,13 +39,13 @@ Note: for more information, please refer "AMD Alchemy Au1200/Au1550 IDE Interface and Linux Device Driver" Application Note. -FILES, CONFIGS AND COMPATABILITY +FILES, CONFIGS AND COMPATIBILITY -------------------------------- Two files are introduced: a) 'arch/mips/include/asm/mach-au1x00/au1xxx_ide.h' - containes : struct _auide_hwif + contains : struct _auide_hwif timing parameters for PIO mode 0/1/2/3/4 timing parameters for MWDMA 0/1/2 diff --git a/Documentation/misc-devices/apds990x.txt b/Documentation/misc-devices/apds990x.txt new file mode 100644 index 000000000000..d5408cade32f --- /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 000000000000..7d64c014dc70 --- /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/ics932s401 b/Documentation/misc-devices/ics932s401 index 07a739f406d8..bdac67ff6e3f 100644 --- a/Documentation/misc-devices/ics932s401 +++ b/Documentation/misc-devices/ics932s401 @@ -5,7 +5,7 @@ Supported chips: * IDT ICS932S401 Prefix: 'ics932s401' Addresses scanned: I2C 0x69 - Datasheet: Publically available at the IDT website + Datasheet: Publicly available at the IDT website Author: Darrick J. Wong diff --git a/Documentation/hwmon/lis3lv02d b/Documentation/misc-devices/lis3lv02d index 06534f25e643..f1a4ec840f86 100644 --- a/Documentation/hwmon/lis3lv02d +++ b/Documentation/misc-devices/lis3lv02d @@ -17,8 +17,8 @@ Description This driver provides support for the accelerometer found in various HP laptops sporting the feature officially called "HP Mobile Data Protection System 3D" or "HP 3D DriveGuard". It detects automatically laptops with this sensor. Known -models (full list can be found in drivers/hwmon/hp_accel.c) will have their -axis automatically oriented on standard way (eg: you can directly play +models (full list can be found in drivers/platform/x86/hp_accel.c) will have +their axis automatically oriented on standard way (eg: you can directly play neverball). The accelerometer data is readable via /sys/devices/platform/lis3lv02d. Reported values are scaled to mg values (1/1000th of earth gravity). diff --git a/Documentation/misc-devices/spear-pcie-gadget.txt b/Documentation/misc-devices/spear-pcie-gadget.txt new file mode 100644 index 000000000000..02c13ef5e908 --- /dev/null +++ b/Documentation/misc-devices/spear-pcie-gadget.txt @@ -0,0 +1,130 @@ +Spear PCIe Gadget Driver: + +Author +============= +Pratyush Anand (pratyush.anand@st.com) + +Location +============ +driver/misc/spear13xx_pcie_gadget.c + +Supported Chip: +=================== +SPEAr1300 +SPEAr1310 + +Menuconfig option: +========================== +Device Drivers + Misc devices + PCIe gadget support for SPEAr13XX platform +purpose +=========== +This driver has several nodes which can be read/written by configfs interface. +Its main purpose is to configure selected dual mode PCIe controller as device +and then program its various registers to configure it as a particular device +type. This driver can be used to show spear's PCIe device capability. + +Description of different nodes: +================================= + +read behavior of nodes: +------------------------------ +link :gives ltssm status. +int_type :type of supported interrupt +no_of_msi :zero if MSI is not enabled by host. A positive value is the + number of MSI vector granted. +vendor_id :returns programmed vendor id (hex) +device_id :returns programmed device id(hex) +bar0_size: :returns size of bar0 in hex. +bar0_address :returns address of bar0 mapped area in hex. +bar0_rw_offset :returns offset of bar0 for which bar0_data will return value. +bar0_data :returns data at bar0_rw_offset. + +write behavior of nodes: +------------------------------ +link :write UP to enable ltsmm DOWN to disable +int_type :write interrupt type to be configured and (int_type could be + INTA, MSI or NO_INT). Select MSI only when you have programmed + no_of_msi node. +no_of_msi :number of MSI vector needed. +inta :write 1 to assert INTA and 0 to de-assert. +send_msi :write MSI vector to be sent. +vendor_id :write vendor id(hex) to be programmed. +device_id :write device id(hex) to be programmed. +bar0_size :write size of bar0 in hex. default bar0 size is 1000 (hex) + bytes. +bar0_address :write address of bar0 mapped area in hex. (default mapping of + bar0 is SYSRAM1(E0800000). Always program bar size before bar + address. Kernel might modify bar size and address for alignment, so + read back bar size and address after writing to cross check. +bar0_rw_offset :write offset of bar0 for which bar0_data will write value. +bar0_data :write data to be written at bar0_rw_offset. + +Node programming example +=========================== +Program all PCIe registers in such a way that when this device is connected +to the PCIe host, then host sees this device as 1MB RAM. +#mount -t configfs none /Config +For nth PCIe Device Controller +# cd /config/pcie_gadget.n/ +Now you have all the nodes in this directory. +program vendor id as 0x104a +# echo 104A >> vendor_id + +program device id as 0xCD80 +# echo CD80 >> device_id + +program BAR0 size as 1MB +# echo 100000 >> bar0_size + +check for programmed bar0 size +# cat bar0_size + +Program BAR0 Address as DDR (0x2100000). This is the physical address of +memory, which is to be made visible to PCIe host. Similarly any other peripheral +can also be made visible to PCIe host. E.g., if you program base address of UART +as BAR0 address then when this device will be connected to a host, it will be +visible as UART. +# echo 2100000 >> bar0_address + +program interrupt type : INTA +# echo INTA >> int_type + +go for link up now. +# echo UP >> link + +It will have to be insured that, once link up is done on gadget, then only host +is initialized and start to search PCIe devices on its port. + +/*wait till link is up*/ +# cat link +wait till it returns UP. + +To assert INTA +# echo 1 >> inta + +To de-assert INTA +# echo 0 >> inta + +if MSI is to be used as interrupt, program no of msi vector needed (say4) +# echo 4 >> no_of_msi + +select MSI as interrupt type +# echo MSI >> int_type + +go for link up now +# echo UP >> link + +wait till link is up +# cat link +An application can repetitively read this node till link is found UP. It can +sleep between two read. + +wait till msi is enabled +# cat no_of_msi +Should return 4 (number of requested MSI vector) + +to send msi vector 2 +# echo 2 >> send_msi +#cd - diff --git a/Documentation/networking/00-INDEX b/Documentation/networking/00-INDEX index fe5c099b8fc8..4edd78dfb362 100644 --- a/Documentation/networking/00-INDEX +++ b/Documentation/networking/00-INDEX @@ -40,8 +40,6 @@ decnet.txt - info on using the DECnet networking layer in Linux. depca.txt - the Digital DEPCA/EtherWORKS DE1?? and DE2?? LANCE Ethernet driver -dgrs.txt - - the Digi International RightSwitch SE-X Ethernet driver dmfe.txt - info on the Davicom DM9102(A)/DM9132/DM9801 fast ethernet driver. e100.txt @@ -50,8 +48,6 @@ e1000.txt - info on Intel's E1000 line of gigabit ethernet boards eql.txt - serial IP load balancing -ethertap.txt - - the Ethertap user space packet reception and transmission driver ewrk3.txt - the Digital EtherWORKS 3 DE203/4/5 Ethernet driver filter.txt @@ -104,8 +100,6 @@ tuntap.txt - TUN/TAP device driver, allowing user space Rx/Tx of packets. vortex.txt - info on using 3Com Vortex (3c590, 3c592, 3c595, 3c597) Ethernet cards. -wavelan.txt - - AT&T GIS (nee NCR) WaveLAN card: An Ethernet-like radio transceiver x25.txt - general info on X.25 development. x25-iface.txt diff --git a/Documentation/networking/3c359.txt b/Documentation/networking/3c359.txt index 4af8071a6d18..dadfe8147ab8 100644 --- a/Documentation/networking/3c359.txt +++ b/Documentation/networking/3c359.txt @@ -45,7 +45,7 @@ debugging messages on, that must be done by modified the source code. Variable MTU size: -The driver can handle a MTU size upto either 4500 or 18000 depending upon +The driver can handle a MTU size up to either 4500 or 18000 depending upon ring speed. The driver also changes the size of the receive buffers as part of the mtu re-sizing, so if you set mtu = 18000, you will need to be able to allocate 16 * (sk_buff with 18000 buffer size) call it 18500 bytes per ring diff --git a/Documentation/networking/LICENSE.qlcnic b/Documentation/networking/LICENSE.qlcnic new file mode 100644 index 000000000000..29ad4b106420 --- /dev/null +++ b/Documentation/networking/LICENSE.qlcnic @@ -0,0 +1,327 @@ +Copyright (c) 2009-2010 QLogic Corporation +QLogic Linux qlcnic NIC Driver + +This program includes a device driver for Linux 2.6 that may be +distributed with QLogic hardware specific firmware binary file. +You may modify and redistribute the device driver code under the +GNU General Public License (a copy of which is attached hereto as +Exhibit A) published by the Free Software Foundation (version 2). + +You may redistribute the hardware specific firmware binary file +under the following terms: + + 1. Redistribution of source code (only if applicable), + must retain the above copyright notice, this list of + conditions and the following disclaimer. + + 2. Redistribution in binary form must reproduce the above + copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other + materials provided with the distribution. + + 3. The name of QLogic Corporation may not be used to + endorse or promote products derived from this software + without specific prior written permission + +REGARDLESS OF WHAT LICENSING MECHANISM IS USED OR APPLICABLE, +THIS PROGRAM IS PROVIDED BY QLOGIC CORPORATION "AS IS'' AND ANY +EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR +BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED +TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. + +USER ACKNOWLEDGES AND AGREES THAT USE OF THIS PROGRAM WILL NOT +CREATE OR GIVE GROUNDS FOR A LICENSE BY IMPLICATION, ESTOPPEL, OR +OTHERWISE IN ANY INTELLECTUAL PROPERTY RIGHTS (PATENT, COPYRIGHT, +TRADE SECRET, MASK WORK, OR OTHER PROPRIETARY RIGHT) EMBODIED IN +ANY OTHER QLOGIC HARDWARE OR SOFTWARE EITHER SOLELY OR IN +COMBINATION WITH THIS PROGRAM. + + +EXHIBIT A + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. diff --git a/Documentation/networking/Makefile b/Documentation/networking/Makefile index 5aba7a33aeeb..24c308dd3fd1 100644 --- a/Documentation/networking/Makefile +++ b/Documentation/networking/Makefile @@ -4,6 +4,8 @@ obj- := dummy.o # List of programs to build hostprogs-y := ifenslave +HOSTCFLAGS_ifenslave.o += -I$(objtree)/usr/include + # Tell kbuild to always build the programs always := $(hostprogs-y) diff --git a/Documentation/networking/README.ipw2200 b/Documentation/networking/README.ipw2200 index 616a8e540b0b..b7658bed4906 100644 --- a/Documentation/networking/README.ipw2200 +++ b/Documentation/networking/README.ipw2200 @@ -256,7 +256,7 @@ You can set the debug level via: Where $VALUE would be a number in the case of this sysfs entry. The input to sysfs files does not have to be a number. For example, the -firmware loader used by hotplug utilizes sysfs entries for transfering +firmware loader used by hotplug utilizes sysfs entries for transferring the firmware image from user space into the driver. The Intel(R) PRO/Wireless 2915ABG Driver for Linux exposes sysfs entries diff --git a/Documentation/networking/batman-adv.txt b/Documentation/networking/batman-adv.txt new file mode 100644 index 000000000000..ee496eb2f4a6 --- /dev/null +++ b/Documentation/networking/batman-adv.txt @@ -0,0 +1,240 @@ +[state: 27-01-2011] + +BATMAN-ADV +---------- + +Batman advanced is a new approach to wireless networking which +does no longer operate on the IP basis. Unlike the batman daemon, +which exchanges information using UDP packets and sets routing +tables, batman-advanced operates on ISO/OSI Layer 2 only and uses +and routes (or better: bridges) Ethernet Frames. It emulates a +virtual network switch of all nodes participating. Therefore all +nodes appear to be link local, thus all higher operating proto- +cols won't be affected by any changes within the network. You can +run almost any protocol above batman advanced, prominent examples +are: IPv4, IPv6, DHCP, IPX. + +Batman advanced was implemented as a Linux kernel driver to re- +duce the overhead to a minimum. It does not depend on any (other) +network driver, and can be used on wifi as well as ethernet lan, +vpn, etc ... (anything with ethernet-style layer 2). + +CONFIGURATION +------------- + +Load the batman-adv module into your kernel: + +# insmod batman-adv.ko + +The module is now waiting for activation. You must add some in- +terfaces on which batman can operate. After loading the module +batman advanced will scan your systems interfaces to search for +compatible interfaces. Once found, it will create subfolders in +the /sys directories of each supported interface, e.g. + +# ls /sys/class/net/eth0/batman_adv/ +# iface_status mesh_iface + +If an interface does not have the "batman_adv" subfolder it prob- +ably is not supported. Not supported interfaces are: loopback, +non-ethernet and batman's own interfaces. + +Note: After the module was loaded it will continuously watch for +new interfaces to verify the compatibility. There is no need to +reload the module if you plug your USB wifi adapter into your ma- +chine after batman advanced was initially loaded. + +To activate a given interface simply write "bat0" into its +"mesh_iface" file inside the batman_adv subfolder: + +# echo bat0 > /sys/class/net/eth0/batman_adv/mesh_iface + +Repeat this step for all interfaces you wish to add. Now batman +starts using/broadcasting on this/these interface(s). + +By reading the "iface_status" file you can check its status: + +# cat /sys/class/net/eth0/batman_adv/iface_status +# active + +To deactivate an interface you have to write "none" into its +"mesh_iface" file: + +# echo none > /sys/class/net/eth0/batman_adv/mesh_iface + + +All mesh wide settings can be found in batman's own interface +folder: + +# ls /sys/class/net/bat0/mesh/ +# aggregated_ogms gw_bandwidth hop_penalty +# bonding gw_mode orig_interval +# fragmentation gw_sel_class vis_mode + + +There is a special folder for debugging information: + +# ls /sys/kernel/debug/batman_adv/bat0/ +# gateways socket transtable_global vis_data +# originators softif_neigh transtable_local + + +Some of the files contain all sort of status information regard- +ing the mesh network. For example, you can view the table of +originators (mesh participants) with: + +# cat /sys/kernel/debug/batman_adv/bat0/originators + +Other files allow to change batman's behaviour to better fit your +requirements. For instance, you can check the current originator +interval (value in milliseconds which determines how often batman +sends its broadcast packets): + +# cat /sys/class/net/bat0/mesh/orig_interval +# 1000 + +and also change its value: + +# echo 3000 > /sys/class/net/bat0/mesh/orig_interval + +In very mobile scenarios, you might want to adjust the originator +interval to a lower value. This will make the mesh more respon- +sive to topology changes, but will also increase the overhead. + + +USAGE +----- + +To make use of your newly created mesh, batman advanced provides +a new interface "bat0" which you should use from this point on. +All interfaces added to batman advanced are not relevant any +longer because batman handles them for you. Basically, one "hands +over" the data by using the batman interface and batman will make +sure it reaches its destination. + +The "bat0" interface can be used like any other regular inter- +face. It needs an IP address which can be either statically con- +figured or dynamically (by using DHCP or similar services): + +# NodeA: ifconfig bat0 192.168.0.1 +# NodeB: ifconfig bat0 192.168.0.2 +# NodeB: ping 192.168.0.1 + +Note: In order to avoid problems remove all IP addresses previ- +ously assigned to interfaces now used by batman advanced, e.g. + +# ifconfig eth0 0.0.0.0 + + +VISUALIZATION +------------- + +If you want topology visualization, at least one mesh node must +be configured as VIS-server: + +# echo "server" > /sys/class/net/bat0/mesh/vis_mode + +Each node is either configured as "server" or as "client" (de- +fault: "client"). Clients send their topology data to the server +next to them, and server synchronize with other servers. If there +is no server configured (default) within the mesh, no topology +information will be transmitted. With these "synchronizing +servers", there can be 1 or more vis servers sharing the same (or +at least very similar) data. + +When configured as server, you can get a topology snapshot of +your mesh: + +# cat /sys/kernel/debug/batman_adv/bat0/vis_data + +This raw output is intended to be easily parsable and convertable +with other tools. Have a look at the batctl README if you want a +vis output in dot or json format for instance and how those out- +puts could then be visualised in an image. + +The raw format consists of comma separated values per entry where +each entry is giving information about a certain source inter- +face. Each entry can/has to have the following values: +-> "mac" - mac address of an originator's source interface + (each line begins with it) +-> "TQ mac value" - src mac's link quality towards mac address + of a neighbor originator's interface which + is being used for routing +-> "HNA mac" - HNA announced by source mac +-> "PRIMARY" - this is a primary interface +-> "SEC mac" - secondary mac address of source + (requires preceding PRIMARY) + +The TQ value has a range from 4 to 255 with 255 being the best. +The HNA entries are showing which hosts are connected to the mesh +via bat0 or being bridged into the mesh network. The PRIMARY/SEC +values are only applied on primary interfaces + + +LOGGING/DEBUGGING +----------------- + +All error messages, warnings and information messages are sent to +the kernel log. Depending on your operating system distribution +this can be read in one of a number of ways. Try using the com- +mands: dmesg, logread, or looking in the files /var/log/kern.log +or /var/log/syslog. All batman-adv messages are prefixed with +"batman-adv:" So to see just these messages try + +# dmesg | grep batman-adv + +When investigating problems with your mesh network it is some- +times necessary to see more detail debug messages. This must be +enabled when compiling the batman-adv module. When building bat- +man-adv as part of kernel, use "make menuconfig" and enable the +option "B.A.T.M.A.N. debugging". + +Those additional debug messages can be accessed using a special +file in debugfs + +# cat /sys/kernel/debug/batman_adv/bat0/log + +The additional debug output is by default disabled. It can be en- +abled during run time. Following log_levels are defined: + +0 - All debug output disabled +1 - Enable messages related to routing / flooding / broadcasting +2 - Enable route or hna added / changed / deleted +3 - Enable all messages + +The debug output can be changed at runtime using the file +/sys/class/net/bat0/mesh/log_level. e.g. + +# echo 2 > /sys/class/net/bat0/mesh/log_level + +will enable debug messages for when routes or HNAs change. + + +BATCTL +------ + +As batman advanced operates on layer 2 all hosts participating in +the virtual switch are completely transparent for all protocols +above layer 2. Therefore the common diagnosis tools do not work +as expected. To overcome these problems batctl was created. At +the moment the batctl contains ping, traceroute, tcpdump and +interfaces to the kernel module settings. + +For more information, please see the manpage (man batctl). + +batctl is available on http://www.open-mesh.org/ + + +CONTACT +------- + +Please send us comments, experiences, questions, anything :) + +IRC: #batman on irc.freenode.org +Mailing-list: b.a.t.m.a.n@open-mesh.org (optional subscription + at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n) + +You can also contact the Authors: + +Marek Lindner <lindner_marek@yahoo.de> +Simon Wunderlich <siwu@hrz.tu-chemnitz.de> diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt index d2b62b71b617..e27202bb8d75 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.txt @@ -49,7 +49,8 @@ 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 +3.5 Configuration with Interfaces Support +3.6 Overriding Configuration for Special Cases 4. Querying Bonding Configuration 4.1 Bonding Configuration @@ -161,8 +162,8 @@ onwards) do not have /usr/include/linux symbolically linked to the default kernel source include directory. SECOND IMPORTANT NOTE: - If you plan to configure bonding using sysfs, you do not need -to use ifenslave. + If you plan to configure bonding using sysfs or using the +/etc/network/interfaces file, you do not need to use ifenslave. 2. Bonding Driver Options ========================= @@ -367,7 +368,7 @@ fail_over_mac gratuitous ARP is lost, communication may be disrupted. - When this policy is used in conjuction with the mii + When this policy is used in conjunction with the mii monitor, devices which assert link up prior to being able to actually transmit and receive are particularly susceptible to loss of the gratuitous ARP, and an @@ -765,28 +766,40 @@ 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 ============================== You can configure bonding using either your distro's network initialization scripts, or manually using either ifenslave or the -sysfs interface. Distros generally use one of two packages for the -network initialization scripts: initscripts or sysconfig. Recent -versions of these packages have support for bonding, while older +sysfs interface. Distros generally use one of three packages for the +network initialization scripts: initscripts, sysconfig or interfaces. +Recent versions of these packages have support for bonding, while older versions do not. We will first describe the options for configuring bonding for -distros using versions of initscripts and sysconfig with full or -partial support for bonding, then provide information on enabling +distros using versions of initscripts, sysconfig and interfaces with full +or partial support for bonding, then provide information on enabling bonding without support from the network initialization scripts (i.e., older versions of initscripts or sysconfig). - If you're unsure whether your distro uses sysconfig or -initscripts, or don't know if it's new enough, have no fear. + If you're unsure whether your distro uses sysconfig, +initscripts or interfaces, or don't know if it's new enough, have no fear. Determining this is fairly straightforward. - First, issue the command: + First, look for a file called interfaces in /etc/network directory. +If this file is present in your system, then your system use interfaces. See +Configuration with Interfaces Support. + + Else, issue the command: $ rpm -qf /sbin/ifup @@ -1319,8 +1332,62 @@ 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 -3.5 Overriding Configuration for Special Cases +3.5 Configuration with Interfaces Support +----------------------------------------- + + This section applies to distros which use /etc/network/interfaces file +to describe network interface configuration, most notably Debian and it's +derivatives. + + The ifup and ifdown commands on Debian don't support bonding out of +the box. The ifenslave-2.6 package should be installed to provide bonding +support. Once installed, this package will provide bond-* options to be used +into /etc/network/interfaces. + + Note that ifenslave-2.6 package will load the bonding module and use +the ifenslave command when appropriate. + +Example Configurations +---------------------- + +In /etc/network/interfaces, the following stanza will configure bond0, in +active-backup mode, with eth0 and eth1 as slaves. + +auto bond0 +iface bond0 inet dhcp + bond-slaves eth0 eth1 + bond-mode active-backup + bond-miimon 100 + bond-primary eth0 eth1 + +If the above configuration doesn't work, you might have a system using +upstart for system startup. This is most notably true for recent +Ubuntu versions. The following stanza in /etc/network/interfaces will +produce the same result on those systems. + +auto bond0 +iface bond0 inet dhcp + bond-slaves none + bond-mode active-backup + bond-miimon 100 + +auto eth0 +iface eth0 inet manual + bond-master bond0 + bond-primary eth0 eth1 + +auto eth1 +iface eth1 inet manual + bond-master bond0 + bond-primary eth0 eth1 + +For a full list of bond-* supported options in /etc/network/interfaces and some +more advanced examples tailored to you particular distros, see the files in +/usr/share/doc/ifenslave-2.6. + +3.6 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 @@ -2491,18 +2558,15 @@ enslaved. 16. Resources and Links ======================= -The latest version of the bonding driver can be found in the latest + The latest version of the bonding driver can be found in the latest version of the linux kernel, found on http://kernel.org -The latest version of this document can be found in either the latest -kernel source (named Documentation/networking/bonding.txt), or on the -bonding sourceforge site: - -http://www.sourceforge.net/projects/bonding + The latest version of this document can be found in the latest kernel +source (named Documentation/networking/bonding.txt). -Discussions regarding the bonding driver take place primarily on the -bonding-devel mailing list, hosted at sourceforge.net. If you have -questions or problems, post them to the list. The list address is: + Discussions regarding the usage of the bonding driver take place on the +bonding-devel mailing list, hosted at sourceforge.net. If you have questions or +problems, post them to the list. The list address is: bonding-devel@lists.sourceforge.net @@ -2511,6 +2575,17 @@ be found at: https://lists.sourceforge.net/lists/listinfo/bonding-devel + Discussions regarding the developpement of the bonding driver take place +on the main Linux network mailing list, hosted at vger.kernel.org. The list +address is: + +netdev@vger.kernel.org + + The administrative interface (to subscribe or unsubscribe) can +be found at: + +http://vger.kernel.org/vger-lists.html#netdev + Donald Becker's Ethernet Drivers and diag programs may be found at : - http://web.archive.org/web/*/http://www.scyld.com/network/ diff --git a/Documentation/networking/bridge.txt b/Documentation/networking/bridge.txt index bec69a8a1697..a7ba5e4e2c91 100644 --- a/Documentation/networking/bridge.txt +++ b/Documentation/networking/bridge.txt @@ -1,8 +1,8 @@ In order to use the Ethernet bridging functionality, you'll need the userspace tools. These programs and documentation are available -at http://www.linux-foundation.org/en/Net:Bridge. The download page is +at http://www.linuxfoundation.org/en/Net:Bridge. The download page is http://prdownloads.sourceforge.net/bridge. If you still have questions, don't hesitate to post to the mailing list -(more info http://lists.osdl.org/mailman/listinfo/bridge). +(more info https://lists.linux-foundation.org/mailman/listinfo/bridge). diff --git a/Documentation/networking/caif/Linux-CAIF.txt b/Documentation/networking/caif/Linux-CAIF.txt index 7fe7a9a33a4f..e52fd62bef3a 100644 --- a/Documentation/networking/caif/Linux-CAIF.txt +++ b/Documentation/networking/caif/Linux-CAIF.txt @@ -136,7 +136,7 @@ The CAIF Protocol implementation contains: - CFMUX CAIF Mux layer. Handles multiplexing between multiple physical bearers and multiple channels such as VEI, Datagram, etc. The MUX keeps track of the existing CAIF Channels and - Physical Instances and selects the apropriate instance based + Physical Instances and selects the appropriate instance based on Channel-Id and Physical-ID. - CFFRML CAIF Framing layer. Handles Framing i.e. Frame length diff --git a/Documentation/networking/caif/spi_porting.txt b/Documentation/networking/caif/spi_porting.txt index 61d7c9247453..9efd0687dc4c 100644 --- a/Documentation/networking/caif/spi_porting.txt +++ b/Documentation/networking/caif/spi_porting.txt @@ -32,7 +32,7 @@ the physical hardware, both with regard to SPI and to GPIOs. 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 + both physical and logical addresses, 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. @@ -150,7 +150,7 @@ static int sspi_init_xfer(struct cfspi_xfer *xfer, struct cfspi_dev *dev) 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 + * the master that you are ready to receive the data from the master * SPI. If xfer is false then you should de-assert SPI_INT to indicate * that the transfer is done. */ diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt index cd79735013f9..56ca3b75376e 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) @@ -239,7 +240,7 @@ solution for a couple of reasons: the user application using the common CAN filter mechanisms. Inside this filter definition the (interested) type of errors may be selected. The reception of error frames is disabled by default. - The format of the CAN error frame is briefly decribed in the Linux + The format of the CAN error frame is briefly described in the Linux header file "include/linux/can/error.h". 4. How to use Socket CAN @@ -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 a62fdf7a6bff..d718bc2ff1cf 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,22 +31,41 @@ 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. The known bugs are at: - http://linux-net.osdl.org/index.php/TODO#DCCP + http://www.linuxfoundation.org/collaborate/workgroups/networking/todo#DCCP For more up-to-date versions of the DCCP implementation, please consider using the experimental DCCP test tree; instructions for checking this out are on: -http://linux-net.osdl.org/index.php/DCCP_Testing#Experimental_DCCP_source_tree +http://www.linuxfoundation.org/collaborate/workgroups/networking/dccp_testing#Experimental_DCCP_source_tree Socket options ============== +DCCP_SOCKOPT_QPOLICY_ID sets the dequeuing policy for outgoing packets. It takes +a policy ID as argument and can only be set before the connection (i.e. changes +during an established connection are not supported). Currently, two policies are +defined: the "simple" policy (DCCPQ_POLICY_SIMPLE), which does nothing special, +and a priority-based variant (DCCPQ_POLICY_PRIO). The latter allows to pass an +u32 priority value as ancillary data to sendmsg(), where higher numbers indicate +a higher packet priority (similar to SO_PRIORITY). This ancillary data needs to +be formatted using a cmsg(3) message header filled in as follows: + cmsg->cmsg_level = SOL_DCCP; + cmsg->cmsg_type = DCCP_SCM_PRIORITY; + cmsg->cmsg_len = CMSG_LEN(sizeof(uint32_t)); /* or CMSG_LEN(4) */ + +DCCP_SOCKOPT_QPOLICY_TXQLEN sets the maximum length of the output queue. A zero +value is always interpreted as unbounded queue length. If different from zero, +the interpretation of this parameter depends on the current dequeuing policy +(see above): the "simple" policy will enforce a fixed queue size by returning +EAGAIN, whereas the "prio" policy enforces a fixed queue length by dropping the +lowest-priority packet first. The default value for this parameter is +initialised from /proc/sys/net/dccp/default/tx_qlen. 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, @@ -112,6 +133,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 @@ -145,6 +167,7 @@ rx_ccid = 2 seq_window = 100 The initial sequence window (sec. 7.5.2) of the sender. This influences the local ackno validity and the remote seqno validity windows (7.5.1). + Values in the range Wmin = 32 (RFC 4340, 7.5.2) up to 2^32-1 can be set. tx_qlen = 5 The size of the transmit buffer in packets. A value of 0 corresponds @@ -155,15 +178,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/dns_resolver.txt b/Documentation/networking/dns_resolver.txt index aefd1e681804..04ca06325b08 100644 --- a/Documentation/networking/dns_resolver.txt +++ b/Documentation/networking/dns_resolver.txt @@ -61,7 +61,6 @@ 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 ===== @@ -104,6 +103,14 @@ implemented in the module can be called after doing: returned also. +=============================== +READING DNS KEYS FROM USERSPACE +=============================== + +Keys of dns_resolver type can be read from userspace using keyctl_read() or +"keyctl read/print/pipe". + + ========= MECHANISM ========= diff --git a/Documentation/networking/e100.txt b/Documentation/networking/e100.txt index 944aa55e79f8..162f323a7a1f 100644 --- a/Documentation/networking/e100.txt +++ b/Documentation/networking/e100.txt @@ -72,7 +72,7 @@ Tx Descriptors: Number of transmit descriptors. A transmit descriptor is a data ethtool -G eth? tx n, where n is the number of desired tx descriptors. Speed/Duplex: The driver auto-negotiates the link speed and duplex settings by - default. Ethtool can be used as follows to force speed/duplex. + default. The ethtool utility can be used as follows to force speed/duplex. ethtool -s eth? autoneg off speed {10|100} duplex {full|half} @@ -126,30 +126,21 @@ Additional Configurations ------- The driver utilizes the ethtool interface for driver configuration and - diagnostics, as well as displaying statistical information. Ethtool + diagnostics, as well as displaying statistical information. The ethtool version 1.6 or later is required for this functionality. 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. - + http://ftp.kernel.org/pub/software/network/ethtool/ Enabling Wake on LAN* (WoL) --------------------------- - WoL is provided through the Ethtool* utility. Ethtool is included with Red - Hat* 8.0. 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 Ethtool man page. + WoL is provided 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 e100 driver must be loaded when shutting down or rebooting the system. - NAPI ---- diff --git a/Documentation/networking/e1000.txt b/Documentation/networking/e1000.txt index 2df71861e578..71ca95855671 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,185 +423,28 @@ 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 - diagnostics, as well as displaying statistical information. Ethtool + diagnostics, as well as displaying statistical information. The ethtool version 1.6 or later is required for this functionality. 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. + http://ftp.kernel.org/pub/software/network/ethtool/ 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 000000000000..97b5ba942ebf --- /dev/null +++ b/Documentation/networking/e1000e.txt @@ -0,0 +1,306 @@ +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 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. + +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 + +If set to 1, configure the hardware to ignore all write/erase cycles to the +GbE region in the ICHx NVM (in order to prevent accidental corruption of the +NVM). This feature can be disabled by setting the parameter to 0 during initial +driver load. +NOTE: The machine must be power cycled (full off/on) when enabling NVM writes +via setting the parameter to zero. Once the NVM has been locked (via the +parameter at 1 when the driver loads) it cannot be unlocked except via power +cycle. + +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://ftp.kernel.org/pub/software/network/ethtool/ + + 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/generic_netlink.txt b/Documentation/networking/generic_netlink.txt index d4f8b8b9b53c..3e071115ca90 100644 --- a/Documentation/networking/generic_netlink.txt +++ b/Documentation/networking/generic_netlink.txt @@ -1,3 +1,3 @@ A wiki document on how to use Generic Netlink can be found here: - * http://linux-net.osdl.org/index.php/Generic_Netlink_HOWTO + * http://www.linuxfoundation.org/collaborate/workgroups/networking/generic_netlink_howto diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.txt index 23c995e64032..f41ea2405220 100644 --- a/Documentation/networking/ieee802154.txt +++ b/Documentation/networking/ieee802154.txt @@ -9,7 +9,7 @@ The Linux-ZigBee project goal is to provide complete implementation of IEEE 802.15.4 / ZigBee / 6LoWPAN protocols. IEEE 802.15.4 is a stack of protocols for organizing Low-Rate Wireless Personal Area Networks. -Currently only IEEE 802.15.4 layer is implemented. We have choosen +Currently only IEEE 802.15.4 layer is implemented. We have chosen to use plain Berkeley socket API, the generic Linux networking stack to transfer IEEE 802.15.4 messages and a special protocol over genetlink for configuration/management diff --git a/Documentation/networking/igb.txt b/Documentation/networking/igb.txt index ab2d71831892..98953c0d5342 100644 --- a/Documentation/networking/igb.txt +++ b/Documentation/networking/igb.txt @@ -36,6 +36,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 ========================= @@ -60,15 +61,16 @@ Additional Configurations Ethtool ------- The driver utilizes the ethtool interface for driver configuration and - diagnostics, as well as displaying statistical information. + diagnostics, as well as displaying statistical information. The latest + version of ethtool can be found at: - http://sourceforge.net/projects/gkernel. + http://ftp.kernel.org/pub/software/network/ethtool/ Enabling Wake on LAN* (WoL) --------------------------- - WoL is configured through the Ethtool* utility. + WoL is configured through the ethtool* utility. - For instructions on enabling WoL with Ethtool, refer to the Ethtool man page. + 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 @@ -91,31 +93,6 @@ Additional Configurations 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 ======= diff --git a/Documentation/networking/igbvf.txt b/Documentation/networking/igbvf.txt index 056028138d9c..cbfe4ee65533 100644 --- a/Documentation/networking/igbvf.txt +++ b/Documentation/networking/igbvf.txt @@ -58,9 +58,11 @@ Additional Configurations Ethtool ------- The driver utilizes the ethtool interface for driver configuration and - diagnostics, as well as displaying statistical information. + diagnostics, as well as displaying statistical information. The ethtool + version 3.0 or later is required for this functionality, although we + strongly recommend downloading the latest version at: - http://sourceforge.net/projects/gkernel. + http://ftp.kernel.org/pub/software/network/ethtool/ Support ======= diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index f350c69b2bb4..d3d653a5f9b9 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -11,7 +11,9 @@ ip_forward - BOOLEAN for routers) ip_default_ttl - INTEGER - default 64 + Default value of TTL field (Time To Live) for outgoing (but not + forwarded) IP packets. Should be between 1 and 255 inclusive. + Default: 64 (as recommended by RFC1700) ip_no_pmtu_disc - BOOLEAN Disable Path MTU Discovery. @@ -20,6 +22,15 @@ ip_no_pmtu_disc - BOOLEAN min_pmtu - INTEGER default 562 - minimum discovered Path MTU +route/max_size - INTEGER + Maximum number of routes allowed in the kernel. Increase + this when using large numbers of interfaces and/or routes. + +neigh/default/gc_thresh3 - INTEGER + Maximum number of neighbor entries allowed. Increase this + when using large numbers of interfaces and when communicating + with large numbers of directly-connected peers. + mtu_expires - INTEGER Time, in seconds, that cached PMTU information is kept. @@ -135,6 +146,7 @@ tcp_adv_win_scale - INTEGER Count buffering overhead as bytes/2^tcp_adv_win_scale (if tcp_adv_win_scale > 0) or bytes-bytes/2^(-tcp_adv_win_scale), if it is <= 0. + Possible values are [-31, 31], inclusive. Default: 2 tcp_allowed_congestion_control - STRING @@ -175,7 +187,7 @@ tcp_cookie_size - INTEGER tcp_dsack - BOOLEAN Allows TCP to send "duplicate" SACKs. -tcp_ecn - BOOLEAN +tcp_ecn - INTEGER Enable Explicit Congestion Notification (ECN) in TCP. ECN is only used when both ends of the TCP flow support it. It is useful to avoid losses due to congestion (when the bottleneck router supports @@ -268,6 +280,17 @@ tcp_max_orphans - INTEGER more aggressively. Let me to remind again: each orphan eats up to ~64K of unswappable memory. +tcp_max_ssthresh - INTEGER + Limited Slow-Start for TCP with large congestion windows (cwnd) defined in + RFC3742. Limited slow-start is a mechanism to limit growth of the cwnd + on the region where cwnd is larger than tcp_max_ssthresh. TCP increases cwnd + by at most tcp_max_ssthresh segments, and by at least tcp_max_ssthresh/2 + segments per RTT when the cwnd is above tcp_max_ssthresh. + If TCP connection increased cwnd to thousands (or tens of thousands) segments, + and thousands of packets were being dropped during slow-start, you can set + tcp_max_ssthresh to improve performance for new TCP connection. + Default: 0 (off) + tcp_max_syn_backlog - INTEGER Maximal number of remembered connection requests, which are still did not receive an acknowledgment from connecting client. @@ -698,10 +721,28 @@ igmp_max_memberships - INTEGER Change the maximum number of multicast groups we can subscribe to. Default: 20 -conf/interface/* changes special settings per interface (where "interface" is - the name of your network interface) -conf/all/* is special, changes the settings for all interfaces + Theoretical maximum value is bounded by having to send a membership + report in a single datagram (i.e. the report can't span multiple + datagrams, or risk confusing the switch and leaving groups you don't + intend to). + + The number of supported groups 'M' is bounded by the number of group + report entries you can fit into a single datagram of 65535 bytes. + + M = 65536-sizeof (ip header)/(sizeof(Group record)) + + Group records are variable length, with a minimum of 12 bytes. + So net.ipv4.igmp_max_memberships should not be set higher than: + + (65536-24) / 12 = 5459 + + The value 5459 assumes no IP header options, so in practice + this number may be lower. + conf/interface/* changes special settings per interface (where + "interface" is the name of your network interface) + + conf/all/* is special, changes the settings for all interfaces log_martians - BOOLEAN Log packets with impossible addresses to kernel log. @@ -1014,6 +1055,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 +1122,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 +1137,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/ixgb.txt b/Documentation/networking/ixgb.txt index a0d0ffb5e584..e196f16df313 100644 --- a/Documentation/networking/ixgb.txt +++ b/Documentation/networking/ixgb.txt @@ -309,15 +309,15 @@ Additional Configurations Ethtool ------- The driver utilizes the ethtool interface for driver configuration and - diagnostics, as well as displaying statistical information. Ethtool + diagnostics, as well as displaying statistical information. The ethtool version 1.6 or later is required for this functionality. The latest release of ethtool can be found from - http://sourceforge.net/projects/gkernel + http://ftp.kernel.org/pub/software/network/ethtool/ - 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 - to the latest version. + NOTE: The ethtool version 1.6 only supports a limited set of ethtool options. + Support for a more complete ethtool feature set can be enabled by + upgrading to the latest version. NAPI diff --git a/Documentation/networking/ixgbe.txt b/Documentation/networking/ixgbe.txt index eeb68685c788..af77ed3c4172 100644 --- a/Documentation/networking/ixgbe.txt +++ b/Documentation/networking/ixgbe.txt @@ -1,107 +1,126 @@ Linux Base Driver for 10 Gigabit PCI Express Intel(R) Network Connection ======================================================================== -March 10, 2009 - +Intel Gigabit Linux driver. +Copyright(c) 1999 - 2010 Intel Corporation. Contents ======== -- In This Release - Identifying Your Adapter -- Building and Installation - Additional Configurations +- Performance Tuning +- Known Issues - Support +Identifying Your Adapter +======================== +The driver in this release is compatible with 82598 and 82599-based Intel +Network Connections. -In This Release -=============== +For more information on how to identify your adapter, go to the Adapter & +Driver ID Guide at: -This file describes the ixgbe Linux Base Driver for the 10 Gigabit PCI -Express Intel(R) Network Connection. This driver includes support for -Itanium(R)2-based systems. + http://support.intel.com/support/network/sb/CS-012904.htm -For questions related to hardware requirements, refer to the documentation -supplied with your 10 Gigabit adapter. All hardware requirements listed apply -to use with Linux. +SFP+ Devices with Pluggable Optics +---------------------------------- -The following features are available in this kernel: - - Native VLANs - - Channel Bonding (teaming) - - SNMP - - Generic Receive Offload - - Data Center Bridging +82599-BASED ADAPTERS -Channel Bonding documentation can be found in the Linux kernel source: -/Documentation/networking/bonding.txt +NOTES: If your 82599-based Intel(R) Network Adapter came with Intel optics, or +is an Intel(R) Ethernet Server Adapter X520-2, then it only supports Intel +optics and/or the direct attach cables listed below. -Ethtool, lspci, and ifconfig can be used to display device and driver -specific information. +When 82599-based SFP+ devices are connected back to back, they should be set to +the same Speed setting via ethtool. Results may vary if you mix speed settings. +82598-based adapters support all passive direct attach cables that comply +with SFF-8431 v4.1 and SFF-8472 v10.4 specifications. Active direct attach +cables are not supported. +Supplier Type Part Numbers -Identifying Your Adapter -======================== +SR Modules +Intel DUAL RATE 1G/10G SFP+ SR (bailed) FTLX8571D3BCV-IT +Intel DUAL RATE 1G/10G SFP+ SR (bailed) AFBR-703SDDZ-IN1 +Intel DUAL RATE 1G/10G SFP+ SR (bailed) AFBR-703SDZ-IN2 +LR Modules +Intel DUAL RATE 1G/10G SFP+ LR (bailed) FTLX1471D3BCV-IT +Intel DUAL RATE 1G/10G SFP+ LR (bailed) AFCT-701SDDZ-IN1 +Intel DUAL RATE 1G/10G SFP+ LR (bailed) AFCT-701SDZ-IN2 -This driver supports devices based on the 82598 controller and the 82599 -controller. +The following is a list of 3rd party SFP+ modules and direct attach cables that +have received some testing. Not all modules are applicable to all devices. -For specific information on identifying which adapter you have, please visit: +Supplier Type Part Numbers - http://support.intel.com/support/network/sb/CS-008441.htm +Finisar SFP+ SR bailed, 10g single rate FTLX8571D3BCL +Avago SFP+ SR bailed, 10g single rate AFBR-700SDZ +Finisar SFP+ LR bailed, 10g single rate FTLX1471D3BCL +Finisar DUAL RATE 1G/10G SFP+ SR (No Bail) FTLX8571D3QCV-IT +Avago DUAL RATE 1G/10G SFP+ SR (No Bail) AFBR-703SDZ-IN1 +Finisar DUAL RATE 1G/10G SFP+ LR (No Bail) FTLX1471D3QCV-IT +Avago DUAL RATE 1G/10G SFP+ LR (No Bail) AFCT-701SDZ-IN1 +Finistar 1000BASE-T SFP FCLF8522P2BTL +Avago 1000BASE-T SFP ABCU-5710RZ -Building and Installation -========================= +82599-based adapters support all passive and active limiting direct attach +cables that comply with SFF-8431 v4.1 and SFF-8472 v10.4 specifications. -select m for "Intel(R) 10GbE PCI Express adapters support" located at: - Location: - -> Device Drivers - -> Network device support (NETDEVICES [=y]) - -> Ethernet (10000 Mbit) (NETDEV_10000 [=y]) +Laser turns off for SFP+ when ifconfig down +------------------------------------------- +"ifconfig down" turns off the laser for 82599-based SFP+ fiber adapters. +"ifconfig up" turns on the later. -1. make modules & make modules_install -2. Load the module: +82598-BASED ADAPTERS -# modprobe ixgbe +NOTES for 82598-Based Adapters: +- Intel(R) Network Adapters that support removable optical modules only support + their original module type (i.e., the Intel(R) 10 Gigabit SR Dual Port + Express Module only supports SR optical modules). If you plug in a different + type of module, the driver will not load. +- Hot Swapping/hot plugging optical modules is not supported. +- Only single speed, 10 gigabit modules are supported. +- LAN on Motherboard (LOMs) may support DA, SR, or LR modules. Other module + types are not supported. Please see your system documentation for details. - The insmod command can be used if the full - path to the driver module is specified. For example: +The following is a list of 3rd party SFP+ modules and direct attach cables that +have received some testing. Not all modules are applicable to all devices. - insmod /lib/modules/<KERNEL VERSION>/kernel/drivers/net/ixgbe/ixgbe.ko +Supplier Type Part Numbers - With 2.6 based kernels also make sure that older ixgbe drivers are - removed from the kernel, before loading the new module: +Finisar SFP+ SR bailed, 10g single rate FTLX8571D3BCL +Avago SFP+ SR bailed, 10g single rate AFBR-700SDZ +Finisar SFP+ LR bailed, 10g single rate FTLX1471D3BCL - rmmod ixgbe; modprobe ixgbe +82598-based adapters support all passive direct attach cables that comply +with SFF-8431 v4.1 and SFF-8472 v10.4 specifications. Active direct attach +cables are not supported. -3. Assign an IP address to the interface by entering the following, where - x is the interface number: - ifconfig ethx <IP_address> +Flow Control +------------ +Ethernet Flow Control (IEEE 802.3x) can be configured with ethtool to enable +receiving and transmitting pause frames for ixgbe. When TX is enabled, PAUSE +frames are generated when the receive packet buffer crosses a predefined +threshold. When rx is enabled, the transmit unit will halt for the time delay +specified when a PAUSE frame is received. -4. Verify that the interface works. Enter the following, where <IP_address> - is the IP address for another machine on the same subnet as the interface - that is being tested: +Flow Control is enabled by default. If you want to disable a flow control +capable link partner, use ethtool: - ping <IP_address> + ethtool -A eth? autoneg off RX off TX off +NOTE: For 82598 backplane cards entering 1 gig mode, flow control default +behavior is changed to off. Flow control in 1 gig mode on these devices can +lead to Tx hangs. Additional Configurations ========================= - 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 ------------ The driver supports Jumbo Frames for all adapters. Jumbo Frames support is @@ -123,13 +142,8 @@ Additional Configurations other protocols besides TCP. It's also safe to use with configurations that are problematic for LRO, namely bridging and iSCSI. - GRO is enabled by default in the driver. Future versions of ethtool will - support disabling and re-enabling GRO on the fly. - - Data Center Bridging, aka DCB ----------------------------- - DCB is a configuration Quality of Service implementation in hardware. It uses the VLAN priority tag (802.1p) to filter traffic. That means that there are 8 different priorities that traffic can be filtered into. @@ -163,24 +177,71 @@ Additional Configurations http://e1000.sf.net - Ethtool ------- The driver utilizes the ethtool interface for driver configuration and - diagnostics, as well as displaying statistical information. Ethtool - version 3.0 or later is required for this functionality. + diagnostics, as well as displaying statistical information. The latest + ethtool version is required for this functionality. The latest release of ethtool can be found from - http://sourceforge.net/projects/gkernel. + http://ftp.kernel.org/pub/software/network/ethtool/ - - NAPI + FCoE ---- + This release of the ixgbe driver contains new code to enable users to use + Fiber Channel over Ethernet (FCoE) and Data Center Bridging (DCB) + functionality that is supported by the 82598-based hardware. This code has + no default effect on the regular driver operation, and configuring DCB and + FCoE is outside the scope of this driver README. Refer to + http://www.open-fcoe.org/ for FCoE project information and contact + e1000-eedc@lists.sourceforge.net for DCB information. + + MAC and VLAN anti-spoofing feature + ---------------------------------- + When a malicious driver attempts to send a spoofed packet, it is dropped by + the hardware and not transmitted. An interrupt is sent to the PF driver + notifying it of the spoof attempt. + + When a spoofed packet is detected the PF driver will send the following + message to the system log (displayed by the "dmesg" command): + + Spoof event(s) detected on VF (n) + + Where n=the VF that attempted to do the spoofing. + + +Performance Tuning +================== + +An excellent article on performance tuning can be found at: + +http://www.redhat.com/promo/summit/2008/downloads/pdf/Thursday/Mark_Wagner.pdf + + +Known Issues +============ + + Enabling SR-IOV in a 32-bit Microsoft* Windows* Server 2008 Guest OS using + Intel (R) 82576-based GbE or Intel (R) 82599-based 10GbE controller under KVM + ----------------------------------------------------------------------------- + KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This + includes traditional PCIe devices, as well as SR-IOV-capable devices using + Intel 82576-based and 82599-based controllers. + + While direct assignment of a PCIe device or an SR-IOV Virtual Function (VF) + to a Linux-based VM running 2.6.32 or later kernel works fine, there is a + known issue with Microsoft Windows Server 2008 VM that results in a "yellow + bang" error. This problem is within the KVM VMM itself, not the Intel driver, + or the SR-IOV logic of the VMM, but rather that KVM emulates an older CPU + model for the guests, and this older CPU model does not support MSI-X + interrupts, which is a requirement for Intel SR-IOV. - NAPI (Rx polling mode) is supported in the ixgbe driver. NAPI is enabled - by default in the driver. + If you wish to use the Intel 82576 or 82599-based controllers in SR-IOV mode + with KVM and a Microsoft Windows Server 2008 guest try the following + workaround. The workaround is to tell KVM to emulate a different model of CPU + when using qemu to create the KVM guest: - See www.cyberus.ca/~hadi/usenix-paper.tgz for more information on NAPI. + "-cpu qemu64,model=13" Support diff --git a/Documentation/networking/ixgbevf.txt b/Documentation/networking/ixgbevf.txt index 19015de6725f..5a91a41fa946 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,15 +30,11 @@ 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 ============================ - Unloading Physical Function (PF) Driver Causes System Reboots When VM is - Running and VF is Loaded on the VM - ------------------------------------------------------------------------ - Do not unload the PF driver (ixgbe) while VFs are assigned to guests. Support ======= @@ -57,34 +50,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/olympic.txt b/Documentation/networking/olympic.txt index c65a94010ea8..b95b5bf96751 100644 --- a/Documentation/networking/olympic.txt +++ b/Documentation/networking/olympic.txt @@ -65,7 +65,7 @@ together. Variable MTU size: -The driver can handle a MTU size upto either 4500 or 18000 depending upon +The driver can handle a MTU size up to either 4500 or 18000 depending upon ring speed. The driver also changes the size of the receive buffers as part of the mtu re-sizing, so if you set mtu = 18000, you will need to be able to allocate 16 * (sk_buff with 18000 buffer size) call it 18500 bytes per ring diff --git a/Documentation/networking/packet_mmap.txt b/Documentation/networking/packet_mmap.txt index 073894d1c093..4acea6603720 100644 --- a/Documentation/networking/packet_mmap.txt +++ b/Documentation/networking/packet_mmap.txt @@ -223,7 +223,7 @@ we will get the following buffer structure: A frame can be of any size with the only condition it can fit in a block. A block can only hold an integer number of frames, or in other words, a frame cannot -be spawned accross two blocks, so there are some details you have to take into +be spawned across two blocks, so there are some details you have to take into account when choosing the frame_size. See "Mapping and use of the circular buffer (ring)". diff --git a/Documentation/networking/phonet.txt b/Documentation/networking/phonet.txt index 6e8ce09f9c73..81003581f47a 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 -------------------- @@ -138,9 +154,28 @@ connections, one per accept()'d socket. write(cfd, msg, msglen); } -Connections are established between two endpoints by a "third party" -application. This means that both endpoints are passive; so connect() -is not possible. +Connections are traditionally established between two endpoints by a +"third party" application. This means that both endpoints are passive. + + +As of Linux kernel version 2.6.39, it is also possible to connect +two endpoints directly, using connect() on the active side. This is +intended to support the newer Nokia Wireless Modem API, as found in +e.g. the Nokia Slim Modem in the ST-Ericsson U8500 platform: + + struct sockaddr_spn spn; + int fd; + + fd = socket(PF_PHONET, SOCK_SEQPACKET, PN_PROTO_PIPE); + memset(&spn, 0, sizeof(spn)); + spn.spn_family = AF_PHONET; + spn.spn_obj = ...; + spn.spn_dev = ...; + spn.spn_resource = 0xD9; + connect(fd, (struct sockaddr *)&spn, sizeof(spn)); + /* normal I/O here ... */ + close(fd); + WARNING: When polling a connected pipe socket for writability, there is an @@ -165,6 +200,10 @@ The pipe protocol provides two socket options at the SOL_PNPIPE level: interface index of the network interface created by PNPIPE_ENCAP, or zero if encapsulation is off. + PNPIPE_HANDLE is a read-only integer value. It contains the underlying + identifier ("pipe handle") of the pipe. This is only defined for + socket descriptors that are already connected or being connected. + Authors ------- diff --git a/Documentation/networking/phy.txt b/Documentation/networking/phy.txt index 88bb71b46da4..9eb1ba52013d 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/s2io.txt b/Documentation/networking/s2io.txt index 9d4e0f4df5a8..4be0c039edbc 100644 --- a/Documentation/networking/s2io.txt +++ b/Documentation/networking/s2io.txt @@ -37,7 +37,7 @@ To associate an interface with a physical adapter use "ethtool -p <ethX>". The corresponding adapter's LED will blink multiple times. 3. Features supported: -a. Jumbo frames. Xframe I/II supports MTU upto 9600 bytes, +a. Jumbo frames. Xframe I/II supports MTU up to 9600 bytes, modifiable using ifconfig command. b. Offloads. Supports checksum offload(TCP/UDP/IP) on transmit @@ -49,7 +49,7 @@ significant performance improvement on certain platforms(SGI Altix, IBM xSeries). d. MSI/MSI-X. Can be enabled on platforms which support this feature -(IA64, Xeon) resulting in noticeable performance improvement(upto 7% +(IA64, Xeon) resulting in noticeable performance improvement(up to 7% on certain platforms). e. Statistics. Comprehensive MAC-level and software statistics displayed diff --git a/Documentation/networking/stmmac.txt b/Documentation/networking/stmmac.txt index 7ee770b5ef5f..80a7a3454902 100644 --- a/Documentation/networking/stmmac.txt +++ b/Documentation/networking/stmmac.txt @@ -7,7 +7,7 @@ This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers (Synopsys IP blocks); it has been fully tested on STLinux platforms. Currently this network device driver is for all STM embedded MAC/GMAC -(7xxx SoCs). +(7xxx SoCs). Other platforms start using it i.e. ARM SPEAr. DWC Ether MAC 10/100/1000 Universal version 3.41a and DWC Ether MAC 10/100 Universal version 4.0 have been used for developing the first code @@ -95,9 +95,14 @@ Several information came from the platform; please refer to the driver's Header file in include/linux directory. struct plat_stmmacenet_data { - int bus_id; - int pbl; - int has_gmac; + int bus_id; + int pbl; + int clk_csr; + int has_gmac; + int enh_desc; + int tx_coe; + int bugged_jumbo; + int pmt; void (*fix_mac_speed)(void *priv, unsigned int speed); void (*bus_setup)(unsigned long ioaddr); #ifdef CONFIG_STM_DRIVERS @@ -114,6 +119,12 @@ Where: registers (on STM platforms); - has_gmac: GMAC core is on board (get it at run-time in the next step); - bus_id: bus identifier. +- tx_coe: core is able to perform the tx csum in HW. +- enh_desc: if sets the MAC will use the enhanced descriptor structure. +- clk_csr: CSR Clock range selection. +- bugged_jumbo: some HWs are not able to perform the csum in HW for + over-sized frames due to limited buffer sizes. Setting this + flag the csum will be done in SW on JUMBO frames. struct plat_stmmacphy_data { int bus_id; @@ -131,13 +142,28 @@ Where: - interface: physical MII interface mode; - phy_reset: hook to reset HW function. +SOURCES: +- Kconfig +- Makefile +- stmmac_main.c: main network device driver; +- stmmac_mdio.c: mdio functions; +- stmmac_ethtool.c: ethtool support; +- stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts + Only tested on ST40 platforms based. +- stmmac.h: private driver structure; +- common.h: common definitions and VFTs; +- descs.h: descriptor structure definitions; +- dwmac1000_core.c: GMAC core functions; +- dwmac1000_dma.c: dma functions for the GMAC chip; +- dwmac1000.h: specific header file for the GMAC; +- dwmac100_core: MAC 100 core and dma code; +- dwmac100_dma.c: dma funtions for the MAC chip; +- dwmac1000.h: specific header file for the MAC; +- dwmac_lib.c: generic DMA functions shared among chips +- enh_desc.c: functions for handling enhanced descriptors +- norm_desc.c: functions for handling normal descriptors + TODO: -- Continue to make the driver more generic and suitable for other Synopsys - Ethernet controllers used on other architectures (i.e. ARM). -- 10G controllers are not supported. -- MAC uses Normal descriptors and GMAC uses enhanced ones. - This is a limit that should be reviewed. MAC could want to - use the enhanced structure. -- Checksumming: Rx/Tx csum is done in HW in case of GMAC only. +- XGMAC controller is not supported. - Review the timer optimisation code to use an embedded device that seems to be available in new chip generations. diff --git a/Documentation/networking/tc-actions-env-rules.txt b/Documentation/networking/tc-actions-env-rules.txt index dcadf6f88e34..70d6cf608251 100644 --- a/Documentation/networking/tc-actions-env-rules.txt +++ b/Documentation/networking/tc-actions-env-rules.txt @@ -1,5 +1,5 @@ -The "enviromental" rules for authors of any new tc actions are: +The "environmental" rules for authors of any new tc actions are: 1) If you stealeth or borroweth any packet thou shalt be branching from the righteous path and thou shalt cloneth. @@ -20,7 +20,7 @@ this way any action downstream can stomp on the packet. 3) Dropping packets you don't own is a no-no. You simply return TC_ACT_SHOT to the caller and they will drop it. -The "enviromental" rules for callers of actions (qdiscs etc) are: +The "environmental" rules for callers of actions (qdiscs etc) are: *) Thou art responsible for freeing anything returned as being TC_ACT_SHOT/STOLEN/QUEUED. If none of TC_ACT_SHOT/STOLEN/QUEUED is diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt index e8c8f4f06c67..98097d8cb910 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/nfc/nfc-pn544.txt b/Documentation/nfc/nfc-pn544.txt new file mode 100644 index 000000000000..2fcac9f5996e --- /dev/null +++ b/Documentation/nfc/nfc-pn544.txt @@ -0,0 +1,114 @@ +Kernel driver for the NXP Semiconductors PN544 Near Field +Communication chip + +Author: Jari Vanhala +Contact: Matti Aaltonen (matti.j.aaltonen at nokia.com) + +General +------- + +The PN544 is an integrated transmission module for contactless +communication. The driver goes under drives/nfc/ and is compiled as a +module named "pn544". It registers a misc device and creates a device +file named "/dev/pn544". + +Host Interfaces: I2C, SPI and HSU, this driver supports currently only I2C. + +The Interface +------------- + +The driver offers a sysfs interface for a hardware test and an IOCTL +interface for selecting between two operating modes. There are read, +write and poll functions for transferring messages. The two operating +modes are the normal (HCI) mode and the firmware update mode. + +PN544 is controlled by sending messages from the userspace to the +chip. The main function of the driver is just to pass those messages +without caring about the message content. + + +Protocols +--------- + +In the normal (HCI) mode and in the firmware update mode read and +write functions behave a bit differently because the message formats +or the protocols are different. + +In the normal (HCI) mode the protocol used is derived from the ETSI +HCI specification. The firmware is updated using a specific protocol, +which is different from HCI. + +HCI messages consist of an eight bit header and the message body. The +header contains the message length. Maximum size for an HCI message is +33. In HCI mode sent messages are tested for a correct +checksum. Firmware update messages have the length in the second (MSB) +and third (LSB) bytes of the message. The maximum FW message length is +1024 bytes. + +For the ETSI HCI specification see +http://www.etsi.org/WebSite/Technologies/ProtocolSpecification.aspx + +The Hardware Test +----------------- + +The idea of the test is that it can performed by reading from the +corresponding sysfs file. The test is implemented in the board file +and it should test that PN544 can be put into the firmware update +mode. If the test is not implemented the sysfs file does not get +created. + +Example: +> cat /sys/module/pn544/drivers/i2c\:pn544/3-002b/nfc_test +1 + +Normal Operation +---------------- + +PN544 is powered up when the device file is opened, otherwise it's +turned off. Only one instance can use the device at a time. + +Userspace applications control PN544 with HCI messages. The hardware +sends an interrupt when data is available for reading. Data is +physically read when the read function is called by a userspace +application. Poll() checks the read interrupt state. Configuration and +self testing are also done from the userspace using read and write. + +Example platform data: + +static int rx71_pn544_nfc_request_resources(struct i2c_client *client) +{ + /* Get and setup the HW resources for the device */ +} + +static void rx71_pn544_nfc_free_resources(void) +{ + /* Release the HW resources */ +} + +static void rx71_pn544_nfc_enable(int fw) +{ + /* Turn the device on */ +} + +static int rx71_pn544_nfc_test(void) +{ + /* + * Put the device into the FW update mode + * and then back to the normal mode. + * Check the behavior and return one on success, + * zero on failure. + */ +} + +static void rx71_pn544_nfc_disable(void) +{ + /* turn the power off */ +} + +static struct pn544_nfc_platform_data rx71_nfc_data = { + .request_resources = rx71_pn544_nfc_request_resources, + .free_resources = rx71_pn544_nfc_free_resources, + .enable = rx71_pn544_nfc_enable, + .test = rx71_pn544_nfc_test, + .disable = rx71_pn544_nfc_disable, +}; diff --git a/Documentation/pcmcia/driver-changes.txt b/Documentation/pcmcia/driver-changes.txt index 26c0f9c00545..dd04361dd361 100644 --- a/Documentation/pcmcia/driver-changes.txt +++ b/Documentation/pcmcia/driver-changes.txt @@ -1,4 +1,29 @@ 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 diff --git a/Documentation/power/00-INDEX b/Documentation/power/00-INDEX index fb742c213c9e..45e9d4a91284 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/devices.txt b/Documentation/power/devices.txt index 57080cd74575..1971bcf48a60 100644 --- a/Documentation/power/devices.txt +++ b/Documentation/power/devices.txt @@ -1,6 +1,6 @@ Device Power Management -Copyright (c) 2010 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. +Copyright (c) 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. Copyright (c) 2010 Alan Stern <stern@rowland.harvard.edu> @@ -159,18 +159,18 @@ matter, and the kernel is responsible for keeping track of it. By contrast, whether or not a wakeup-capable device should issue wakeup events is a policy decision, and it is managed by user space through a sysfs attribute: the power/wakeup file. User space can write the strings "enabled" or "disabled" to -set or clear the should_wakeup flag, respectively. Reads from the file will -return the corresponding string if can_wakeup is true, but if can_wakeup is -false then reads will return an empty string, to indicate that the device -doesn't support wakeup events. (But even though the file appears empty, writes -will still affect the should_wakeup flag.) +set or clear the "should_wakeup" flag, respectively. This file is only present +for wakeup-capable devices (i.e. devices whose "can_wakeup" flags are set) +and is created (or removed) by device_set_wakeup_capable(). Reads from the +file will return the corresponding string. The device_may_wakeup() routine returns true only if both flags are set. -Drivers should check this routine when putting devices in a low-power state -during a system sleep transition, to see whether or not to enable the devices' -wakeup mechanisms. However for runtime power management, wakeup events should -be enabled whenever the device and driver both support them, regardless of the -should_wakeup flag. +This information is used by subsystems, like the PCI bus type code, to see +whether or not to enable the devices' wakeup mechanisms. If device wakeup +mechanisms are enabled or disabled directly by drivers, they also should use +device_may_wakeup() to decide what to do during a system sleep transition. +However for runtime power management, wakeup events should be enabled whenever +the device and driver both support them, regardless of the should_wakeup flag. /sys/devices/.../power/control files @@ -249,23 +249,18 @@ various phases always run after tasks have been frozen and before they are unfrozen. Furthermore, the *_noirq phases run at a time when IRQ handlers have been disabled (except for those marked with the IRQ_WAKEUP flag). -Most phases use bus, type, and class callbacks (that is, methods defined in -dev->bus->pm, dev->type->pm, and dev->class->pm). The prepare and complete -phases are exceptions; they use only bus callbacks. When multiple callbacks -are used in a phase, they are invoked in the order: <class, type, bus> during -power-down transitions and in the opposite order during power-up transitions. -For example, during the suspend phase the PM core invokes - - dev->class->pm.suspend(dev); - dev->type->pm.suspend(dev); - dev->bus->pm.suspend(dev); - -before moving on to the next device, whereas during the resume phase the core -invokes - - dev->bus->pm.resume(dev); - dev->type->pm.resume(dev); - dev->class->pm.resume(dev); +All phases use bus, type, or class callbacks (that is, methods defined in +dev->bus->pm, dev->type->pm, or dev->class->pm). These callbacks are mutually +exclusive, so if the device type provides a struct dev_pm_ops object pointed to +by its pm field (i.e. both dev->type and dev->type->pm are defined), the +callbacks included in that object (i.e. dev->type->pm) will be used. Otherwise, +if the class provides a struct dev_pm_ops object pointed to by its pm field +(i.e. both dev->class and dev->class->pm are defined), the PM core will use the +callbacks from that object (i.e. dev->class->pm). Finally, if the pm fields of +both the device type and class objects are NULL (or those objects do not exist), +the callbacks provided by the bus (that is, the callbacks from dev->bus->pm) +will be used (this allows device types to override callbacks provided by bus +types or classes if necessary). These callbacks may in turn invoke device- or driver-specific methods stored in dev->driver->pm, but they don't have to. @@ -372,7 +367,7 @@ Drivers need to be able to handle hardware which has been reset since the suspend methods were called, for example by complete reinitialization. This may be the hardest part, and the one most protected by NDA'd documents and chip errata. It's simplest if the hardware state hasn't changed since -the suspend was carried out, but that can't be guaranteed (in fact, it ususally +the suspend was carried out, but that can't be guaranteed (in fact, it usually is not the case). Drivers must also be prepared to notice that the device has been removed @@ -507,6 +502,49 @@ routines. Nevertheless, different callback pointers are used in case there is a situation where it actually matters. +Device Power Domains +-------------------- +Sometimes devices share reference clocks or other power resources. In those +cases it generally is not possible to put devices into low-power states +individually. Instead, a set of devices sharing a power resource can be put +into a low-power state together at the same time by turning off the shared +power resource. Of course, they also need to be put into the full-power state +together, by turning the shared power resource on. A set of devices with this +property is often referred to as a power domain. + +Support for power domains is provided through the pwr_domain field of struct +device. This field is a pointer to an object of type struct dev_power_domain, +defined in include/linux/pm.h, providing a set of power management callbacks +analogous to the subsystem-level and device driver callbacks that are executed +for the given device during all power transitions, in addition to the respective +subsystem-level callbacks. Specifically, the power domain "suspend" callbacks +(i.e. ->runtime_suspend(), ->suspend(), ->freeze(), ->poweroff(), etc.) are +executed after the analogous subsystem-level callbacks, while the power domain +"resume" callbacks (i.e. ->runtime_resume(), ->resume(), ->thaw(), ->restore, +etc.) are executed before the analogous subsystem-level callbacks. Error codes +returned by the "suspend" and "resume" power domain callbacks are ignored. + +Power domain ->runtime_idle() callback is executed before the subsystem-level +->runtime_idle() callback and the result returned by it is not ignored. Namely, +if it returns error code, the subsystem-level ->runtime_idle() callback will not +be called and the helper function rpm_idle() executing it will return error +code. This mechanism is intended to help platforms where saving device state +is a time consuming operation and should only be carried out if all devices +in the power domain are idle, before turning off the shared power resource(s). +Namely, the power domain ->runtime_idle() callback may return error code until +the pm_runtime_idle() helper (or its asychronous version) has been called for +all devices in the power domain (it is recommended that the returned error code +be -EBUSY in those cases), preventing the subsystem-level ->runtime_idle() +callback from being run prematurely. + +The support for device power domains is only relevant to platforms needing to +use the same subsystem-level (e.g. platform bus type) and device driver power +management callbacks in many different power domain configurations and wanting +to avoid incorporating the support for power domains into the subsystem-level +callbacks. The other platforms need not implement it or take it into account +in any way. + + System Devices -------------- System devices (sysdevs) follow a slightly different API, which can be found in diff --git a/Documentation/power/drivers-testing.txt b/Documentation/power/drivers-testing.txt index 7f7a737f7f9f..638afdf4d6b8 100644 --- a/Documentation/power/drivers-testing.txt +++ b/Documentation/power/drivers-testing.txt @@ -23,10 +23,10 @@ Once you have resolved the suspend/resume-related problems with your test system without the new driver, you are ready to test it: a) Build the driver as a module, load it and try the test modes of hibernation - (see: Documents/power/basic-pm-debugging.txt, 1). + (see: Documentation/power/basic-pm-debugging.txt, 1). b) Load the driver and attempt to hibernate in the "reboot", "shutdown" and - "platform" modes (see: Documents/power/basic-pm-debugging.txt, 1). + "platform" modes (see: Documentation/power/basic-pm-debugging.txt, 1). c) Compile the driver directly into the kernel and try the test modes of hibernation. @@ -34,12 +34,12 @@ c) Compile the driver directly into the kernel and try the test modes of d) Attempt to hibernate with the driver compiled directly into the kernel in the "reboot", "shutdown" and "platform" modes. -e) Try the test modes of suspend (see: Documents/power/basic-pm-debugging.txt, +e) Try the test modes of suspend (see: Documentation/power/basic-pm-debugging.txt, 2). [As far as the STR tests are concerned, it should not matter whether or not the driver is built as a module.] f) Attempt to suspend to RAM using the s2ram tool with the driver loaded - (see: Documents/power/basic-pm-debugging.txt, 2). + (see: Documentation/power/basic-pm-debugging.txt, 2). Each of the above tests should be repeated several times and the STD tests should be mixed with the STR tests. If any of them fails, the driver cannot be diff --git a/Documentation/power/interface.txt b/Documentation/power/interface.txt index e67211fe0ee2..c537834af005 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/notifiers.txt b/Documentation/power/notifiers.txt index ae1b7ec07684..cf980709122a 100644 --- a/Documentation/power/notifiers.txt +++ b/Documentation/power/notifiers.txt @@ -24,7 +24,7 @@ PM_HIBERNATION_PREPARE The system is going to hibernate or suspend, tasks will be frozen immediately. PM_POST_HIBERNATION The system memory state has been restored from a - hibernation image or an error occured during the + hibernation image or an error occurred during the hibernation. Device drivers' .resume() callbacks have been executed and tasks have been thawed. @@ -38,7 +38,7 @@ PM_POST_RESTORE An error occurred during the hibernation restore. PM_SUSPEND_PREPARE The system is preparing for a suspend. -PM_POST_SUSPEND The system has just resumed or an error occured during +PM_POST_SUSPEND The system has just resumed or an error occurred during the suspend. Device drivers' .resume() callbacks have been executed and tasks have been thawed. diff --git a/Documentation/power/opp.txt b/Documentation/power/opp.txt new file mode 100644 index 000000000000..5ae70a12c1e2 --- /dev/null +++ b/Documentation/power/opp.txt @@ -0,0 +1,378 @@ +*=============* +* 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 -> + +Architectures that provide a SoC framework for OPP should select ARCH_HAS_OPP +to make the OPP layer available. + +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 can't 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/runtime_pm.txt b/Documentation/power/runtime_pm.txt index 55b859b3bc72..654097b130b4 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) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. +(C) 2010 Alan Stern <stern@rowland.harvard.edu> 1. Introduction @@ -43,11 +44,21 @@ struct dev_pm_ops { }; The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks are -executed by the PM core for either the bus type, or device type (if the bus -type's callback is not defined), or device class (if the bus type's and device -type's callbacks are not defined) of given device. The bus type, device type -and device class callbacks are referred to as subsystem-level callbacks in what -follows. +executed by the PM core for either the device type, or the class (if the device +type's struct dev_pm_ops object does not exist), or the bus type (if the +device type's and class' struct dev_pm_ops objects do not exist) of the given +device (this allows device types to override callbacks provided by bus types or +classes if necessary). The bus type, device type and class callbacks are +referred to as subsystem-level callbacks in what follows. + +By default, the callbacks are always invoked in process context with interrupts +enabled. However, subsystems can use the pm_runtime_irq_safe() helper function +to tell the PM core that a device's ->runtime_suspend() and ->runtime_resume() +callbacks should be invoked in atomic context with interrupts disabled +(->runtime_idle() is still invoked the default way). This implies that these +callback routines must not block or sleep, but it also means that the +synchronous helper functions listed at the end of Section 4 can be used within +an interrupt handler or in an atomic context. The subsystem-level suspend callback is _entirely_ _responsible_ for handling the suspend of the device as appropriate, which may, but need not include @@ -157,7 +168,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 +177,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 +242,32 @@ 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 irq_safe; + - indicates that the ->runtime_suspend() and ->runtime_resume() callbacks + will be invoked with the spinlock held and interrupts disabled + + 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 +293,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 +311,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 +347,24 @@ 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_suspend(struct device *dev); + - decrement the device's usage counter; if the result is 0 then run + pm_runtime_suspend(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 @@ -336,8 +397,8 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: zero) bool pm_runtime_suspended(struct device *dev); - - return true if the device's runtime PM status is 'suspended', or false - otherwise + - return true if the device's runtime PM status is 'suspended' and its + 'power.disable_depth' field is equal to zero, or false otherwise void pm_runtime_allow(struct device *dev); - set the power.runtime_auto flag for the device and decrease its usage @@ -349,19 +410,65 @@ 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_irq_safe(struct device *dev); + - set the power.irq_safe flag for the device, causing the runtime-PM + suspend and resume callbacks (but not the idle callback) to be invoked + with interrupts disabled + + 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() + +If pm_runtime_irq_safe() has been called for a device then the following helper +functions may also be used in interrupt context: + +pm_runtime_suspend() +pm_runtime_autosuspend() +pm_runtime_resume() +pm_runtime_get_sync() +pm_runtime_put_sync_suspend() 5. Run-time PM Initialization, Device Probing and Removal @@ -524,3 +631,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 514b94fc931e..1bdfa0443773 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/states.txt b/Documentation/power/states.txt index 34800cc521bf..4416b28630df 100644 --- a/Documentation/power/states.txt +++ b/Documentation/power/states.txt @@ -62,12 +62,12 @@ setup via another operating system for it to use. Despite the inconvenience, this method requires minimal work by the kernel, since the firmware will also handle restoring memory contents on resume. -For suspend-to-disk, a mechanism called swsusp called 'swsusp' (Swap -Suspend) is used to write memory contents to free swap space. -swsusp has some restrictive requirements, but should work in most -cases. Some, albeit outdated, documentation can be found in -Documentation/power/swsusp.txt. Alternatively, userspace can do most -of the actual suspend to disk work, see userland-swsusp.txt. +For suspend-to-disk, a mechanism called 'swsusp' (Swap Suspend) is used +to write memory contents to free swap space. swsusp has some restrictive +requirements, but should work in most cases. Some, albeit outdated, +documentation can be found in Documentation/power/swsusp.txt. +Alternatively, userspace can do most of the actual suspend to disk work, +see userland-swsusp.txt. Once memory state is written to disk, the system may either enter a low-power state (like ACPI S4), or it may simply power down. Powering diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt index 9d60ab717a7b..ac190cf1963e 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. @@ -191,7 +192,7 @@ Q: There don't seem to be any generally useful behavioral distinctions between SUSPEND and FREEZE. A: Doing SUSPEND when you are asked to do FREEZE is always correct, -but it may be unneccessarily slow. If you want your driver to stay simple, +but it may be unnecessarily slow. If you want your driver to stay simple, slowness may not matter to you. It can always be fixed later. For devices like disk it does matter, you do not want to spindown for @@ -236,7 +237,7 @@ disk. Whole sequence goes like running system, user asks for suspend-to-disk - user processes are stopped (in common case there are none, but with resume-from-initrd, noone knows) + user processes are stopped (in common case there are none, but with resume-from-initrd, no one knows) read image from disk diff --git a/Documentation/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.txt index 81680f9f5909..1101bee4e822 100644 --- a/Documentation/power/userland-swsusp.txt +++ b/Documentation/power/userland-swsusp.txt @@ -98,7 +98,7 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to The device's read() operation can be used to transfer the snapshot image from the kernel. It has the following limitations: - you cannot read() more than one virtual memory page at a time -- read()s accross page boundaries are impossible (ie. if ypu read() 1/2 of +- read()s across page boundaries are impossible (ie. if ypu read() 1/2 of a page in the previous call, you will only be able to read() _at_ _most_ 1/2 of the page in the next call) @@ -137,7 +137,7 @@ mechanism and the userland utilities using the interface SHOULD use additional means, such as checksums, to ensure the integrity of the snapshot image. The suspending and resuming utilities MUST lock themselves in memory, -preferrably using mlockall(), before calling SNAPSHOT_FREEZE. +preferably using mlockall(), before calling SNAPSHOT_FREEZE. The suspending utility MUST check the value stored by SNAPSHOT_CREATE_IMAGE in the memory location pointed to by the last argument of ioctl() and proceed @@ -147,7 +147,7 @@ in accordance with it: (a) The suspending utility MUST NOT close the snapshot device _unless_ the whole suspend procedure is to be cancelled, in which case, if the snapshot image has already been saved, the - suspending utility SHOULD destroy it, preferrably by zapping + suspending utility SHOULD destroy it, preferably by zapping its header. If the suspend is not to be cancelled, the system MUST be powered off or rebooted after the snapshot image has been saved. diff --git a/Documentation/powerpc/00-INDEX b/Documentation/powerpc/00-INDEX index e3960b8c8689..5620fb5ac425 100644 --- a/Documentation/powerpc/00-INDEX +++ b/Documentation/powerpc/00-INDEX @@ -5,8 +5,6 @@ please mail me. 00-INDEX - this file -booting-without-of.txt - - Booting the Linux/ppc kernel without Open Firmware cpu_features.txt - info on how we support a variety of CPUs with minimal compile-time options. @@ -16,8 +14,6 @@ hvcs.txt - IBM "Hypervisor Virtual Console Server" Installation Guide mpc52xx.txt - Linux 2.6.x on MPC52xx family -mpc52xx-device-tree-bindings.txt - - MPC5200 Device Tree Bindings sound.txt - info on sound support under Linux/PPC zImage_layout.txt diff --git a/Documentation/powerpc/dts-bindings/fsl/mpic.txt b/Documentation/powerpc/dts-bindings/fsl/mpic.txt deleted file mode 100644 index 71e39cf3215b..000000000000 --- a/Documentation/powerpc/dts-bindings/fsl/mpic.txt +++ /dev/null @@ -1,42 +0,0 @@ -* OpenPIC and its interrupt numbers on Freescale's e500/e600 cores - -The OpenPIC specification does not specify which interrupt source has to -become which interrupt number. This is up to the software implementation -of the interrupt controller. The only requirement is that every -interrupt source has to have an unique interrupt number / vector number. -To accomplish this the current implementation assigns the number zero to -the first source, the number one to the second source and so on until -all interrupt sources have their unique number. -Usually the assigned vector number equals the interrupt number mentioned -in the documentation for a given core / CPU. This is however not true -for the e500 cores (MPC85XX CPUs) where the documentation distinguishes -between internal and external interrupt sources and starts counting at -zero for both of them. - -So what to write for external interrupt source X or internal interrupt -source Y into the device tree? Here is an example: - -The memory map for the interrupt controller in the MPC8544[0] shows, -that the first interrupt source starts at 0x5_0000 (PIC Register Address -Map-Interrupt Source Configuration Registers). This source becomes the -number zero therefore: - External interrupt 0 = interrupt number 0 - External interrupt 1 = interrupt number 1 - External interrupt 2 = interrupt number 2 - ... -Every interrupt number allocates 0x20 bytes register space. So to get -its number it is sufficient to shift the lower 16bits to right by five. -So for the external interrupt 10 we have: - 0x0140 >> 5 = 10 - -After the external sources, the internal sources follow. The in core I2C -controller on the MPC8544 for instance has the internal source number -27. Oo obtain its interrupt number we take the lower 16bits of its memory -address (0x5_0560) and shift it right: - 0x0560 >> 5 = 43 - -Therefore the I2C device node for the MPC8544 CPU has to have the -interrupt number 43 specified in the device tree. - -[0] MPC8544E PowerQUICCTM III, Integrated Host Processor Family Reference Manual - MPC8544ERM Rev. 1 10/2007 diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.txt index 6d8be3468d7d..a730ca5a07f8 100644 --- a/Documentation/powerpc/hvcs.txt +++ b/Documentation/powerpc/hvcs.txt @@ -528,7 +528,7 @@ this driver assignment of hotplug added vty-servers may be in a different order than how they would be exposed on module load. Rebooting or reloading the module after dynamic addition may result in the /dev/hvcs* and vty-server coupling changing if a vty-server adapter was added in a -slot inbetween two other vty-server adapters. Refer to the section above +slot between two other vty-server adapters. Refer to the section above on how to determine which vty-server goes with which /dev/hvcs* node. Hint; look at the sysfs "index" attribute for the vty-server. diff --git a/Documentation/pps/pps.txt b/Documentation/pps/pps.txt index 125f4ab48998..d35dcdd82ff6 100644 --- a/Documentation/pps/pps.txt +++ b/Documentation/pps/pps.txt @@ -170,3 +170,49 @@ and the run ppstest as follow: Please, note that to compile userland programs you need the file timepps.h (see Documentation/pps/). + + +Generators +---------- + +Sometimes one needs to be able not only to catch PPS signals but to produce +them also. For example, running a distributed simulation, which requires +computers' clock to be synchronized very tightly. One way to do this is to +invent some complicated hardware solutions but it may be neither necessary +nor affordable. The cheap way is to load a PPS generator on one of the +computers (master) and PPS clients on others (slaves), and use very simple +cables to deliver signals using parallel ports, for example. + +Parallel port cable pinout: +pin name master slave +1 STROBE *------ * +2 D0 * | * +3 D1 * | * +4 D2 * | * +5 D3 * | * +6 D4 * | * +7 D5 * | * +8 D6 * | * +9 D7 * | * +10 ACK * ------* +11 BUSY * * +12 PE * * +13 SEL * * +14 AUTOFD * * +15 ERROR * * +16 INIT * * +17 SELIN * * +18-25 GND *-----------* + +Please note that parallel port interrupt occurs only on high->low transition, +so it is used for PPS assert edge. PPS clear edge can be determined only +using polling in the interrupt handler which actually can be done way more +precisely because interrupt handling delays can be quite big and random. So +current parport PPS generator implementation (pps_gen_parport module) is +geared towards using the clear edge for time synchronization. + +Clear edge polling is done with disabled interrupts so it's better to select +delay between assert and clear edge as small as possible to reduce system +latencies. But if it is too small slave won't be able to capture clear edge +transition. The default of 30us should be good enough in most situations. +The delay can be selected using 'delay' pps_gen_parport module parameter. diff --git a/Documentation/rapidio/rapidio.txt b/Documentation/rapidio/rapidio.txt new file mode 100644 index 000000000000..be70ee15f8ca --- /dev/null +++ b/Documentation/rapidio/rapidio.txt @@ -0,0 +1,173 @@ + The Linux RapidIO Subsystem + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The RapidIO standard is a packet-based fabric interconnect standard designed for +use in embedded systems. Development of the RapidIO standard is directed by the +RapidIO Trade Association (RTA). The current version of the RapidIO specification +is publicly available for download from the RTA web-site [1]. + +This document describes the basics of the Linux RapidIO subsystem and provides +information on its major components. + +1 Overview +---------- + +Because the RapidIO subsystem follows the Linux device model it is integrated +into the kernel similarly to other buses by defining RapidIO-specific device and +bus types and registering them within the device model. + +The Linux RapidIO subsystem is architecture independent and therefore defines +architecture-specific interfaces that provide support for common RapidIO +subsystem operations. + +2. Core Components +------------------ + +A typical RapidIO network is a combination of endpoints and switches. +Each of these components is represented in the subsystem by an associated data +structure. The core logical components of the RapidIO subsystem are defined +in include/linux/rio.h file. + +2.1 Master Port + +A master port (or mport) is a RapidIO interface controller that is local to the +processor executing the Linux code. A master port generates and receives RapidIO +packets (transactions). In the RapidIO subsystem each master port is represented +by a rio_mport data structure. This structure contains master port specific +resources such as mailboxes and doorbells. The rio_mport also includes a unique +host device ID that is valid when a master port is configured as an enumerating +host. + +RapidIO master ports are serviced by subsystem specific mport device drivers +that provide functionality defined for this subsystem. To provide a hardware +independent interface for RapidIO subsystem operations, rio_mport structure +includes rio_ops data structure which contains pointers to hardware specific +implementations of RapidIO functions. + +2.2 Device + +A RapidIO device is any endpoint (other than mport) or switch in the network. +All devices are presented in the RapidIO subsystem by corresponding rio_dev data +structure. Devices form one global device list and per-network device lists +(depending on number of available mports and networks). + +2.3 Switch + +A RapidIO switch is a special class of device that routes packets between its +ports towards their final destination. The packet destination port within a +switch is defined by an internal routing table. A switch is presented in the +RapidIO subsystem by rio_dev data structure expanded by additional rio_switch +data structure, which contains switch specific information such as copy of the +routing table and pointers to switch specific functions. + +The RapidIO subsystem defines the format and initialization method for subsystem +specific switch drivers that are designed to provide hardware-specific +implementation of common switch management routines. + +2.4 Network + +A RapidIO network is a combination of interconnected endpoint and switch devices. +Each RapidIO network known to the system is represented by corresponding rio_net +data structure. This structure includes lists of all devices and local master +ports that form the same network. It also contains a pointer to the default +master port that is used to communicate with devices within the network. + +3. Subsystem Initialization +--------------------------- + +In order to initialize the RapidIO subsystem, a platform must initialize and +register at least one master port within the RapidIO network. To register mport +within the subsystem controller driver initialization code calls function +rio_register_mport() for each available master port. After all active master +ports are registered with a RapidIO subsystem, the rio_init_mports() routine +is called to perform enumeration and discovery. + +In the current PowerPC-based implementation a subsys_initcall() is specified to +perform controller initialization and mport registration. At the end it directly +calls rio_init_mports() to execute RapidIO enumeration and discovery. + +4. Enumeration and Discovery +---------------------------- + +When rio_init_mports() is called it scans a list of registered master ports and +calls an enumeration or discovery routine depending on the configured role of a +master port: host or agent. + +Enumeration is performed by a master port if it is configured as a host port by +assigning a host device ID greater than or equal to zero. A host device ID is +assigned to a master port through the kernel command line parameter "riohdid=", +or can be configured in a platform-specific manner. If the host device ID for +a specific master port is set to -1, the discovery process will be performed +for it. + +The enumeration and discovery routines use RapidIO maintenance transactions +to access the configuration space of devices. + +The enumeration process is implemented according to the enumeration algorithm +outlined in the RapidIO Interconnect Specification: Annex I [1]. + +The enumeration process traverses the network using a recursive depth-first +algorithm. When a new device is found, the enumerator takes ownership of that +device by writing into the Host Device ID Lock CSR. It does this to ensure that +the enumerator has exclusive right to enumerate the device. If device ownership +is successfully acquired, the enumerator allocates a new rio_dev structure and +initializes it according to device capabilities. + +If the device is an endpoint, a unique device ID is assigned to it and its value +is written into the device's Base Device ID CSR. + +If the device is a switch, the enumerator allocates an additional rio_switch +structure to store switch specific information. Then the switch's vendor ID and +device ID are queried against a table of known RapidIO switches. Each switch +table entry contains a pointer to a switch-specific initialization routine that +initializes pointers to the rest of switch specific operations, and performs +hardware initialization if necessary. A RapidIO switch does not have a unique +device ID; it relies on hopcount and routing for device ID of an attached +endpoint if access to its configuration registers is required. If a switch (or +chain of switches) does not have any endpoint (except enumerator) attached to +it, a fake device ID will be assigned to configure a route to that switch. +In the case of a chain of switches without endpoint, one fake device ID is used +to configure a route through the entire chain and switches are differentiated by +their hopcount value. + +For both endpoints and switches the enumerator writes a unique component tag +into device's Component Tag CSR. That unique value is used by the error +management notification mechanism to identify a device that is reporting an +error management event. + +Enumeration beyond a switch is completed by iterating over each active egress +port of that switch. For each active link, a route to a default device ID +(0xFF for 8-bit systems and 0xFFFF for 16-bit systems) is temporarily written +into the routing table. The algorithm recurs by calling itself with hopcount + 1 +and the default device ID in order to access the device on the active port. + +After the host has completed enumeration of the entire network it releases +devices by clearing device ID locks (calls rio_clear_locks()). For each endpoint +in the system, it sets the Master Enable bit in the Port General Control CSR +to indicate that enumeration is completed and agents are allowed to execute +passive discovery of the network. + +The discovery process is performed by agents and is similar to the enumeration +process that is described above. However, the discovery process is performed +without changes to the existing routing because agents only gather information +about RapidIO network structure and are building an internal map of discovered +devices. This way each Linux-based component of the RapidIO subsystem has +a complete view of the network. The discovery process can be performed +simultaneously by several agents. After initializing its RapidIO master port +each agent waits for enumeration completion by the host for the configured wait +time period. If this wait time period expires before enumeration is completed, +an agent skips RapidIO discovery and continues with remaining kernel +initialization. + +5. References +------------- + +[1] RapidIO Trade Association. RapidIO Interconnect Specifications. + http://www.rapidio.org. +[2] Rapidio TA. Technology Comparisons. + http://www.rapidio.org/education/technology_comparisons/ +[3] RapidIO support for Linux. + http://lwn.net/Articles/139118/ +[4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005 + http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf diff --git a/Documentation/rapidio/sysfs.txt b/Documentation/rapidio/sysfs.txt new file mode 100644 index 000000000000..97f71ce575d6 --- /dev/null +++ b/Documentation/rapidio/sysfs.txt @@ -0,0 +1,90 @@ + RapidIO sysfs Files + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Device Subdirectories +------------------------ + +For each RapidIO device, the RapidIO subsystem creates files in an individual +subdirectory with the following name, /sys/bus/rapidio/devices/<device_name>. + +The format of device_name is "nn:d:iiii", where: + +nn - two-digit hexadecimal ID of RapidIO network where the device resides +d - device typr: 'e' - for endpoint or 's' - for switch +iiii - four-digit device destID for endpoints, or switchID for switches + +For example, below is a list of device directories that represents a typical +RapidIO network with one switch, one host, and two agent endpoints, as it is +seen by the enumerating host (destID = 1): + +/sys/bus/rapidio/devices/00:e:0000 +/sys/bus/rapidio/devices/00:e:0002 +/sys/bus/rapidio/devices/00:s:0001 + +NOTE: An enumerating or discovering endpoint does not create a sysfs entry for +itself, this is why an endpoint with destID=1 is not shown in the list. + +2. Attributes Common for All Devices +------------------------------------ + +Each device subdirectory contains the following informational read-only files: + + did - returns the device identifier + vid - returns the device vendor identifier +device_rev - returns the device revision level + asm_did - returns identifier for the assembly containing the device + asm_rev - returns revision level of the assembly containing the device + asm_vid - returns vendor identifier of the assembly containing the device + destid - returns device destination ID assigned by the enumeration routine + (see 4.1 for switch specific details) + lprev - returns name of previous device (switch) on the path to the device + that that owns this attribute + +In addition to the files listed above, each device has a binary attribute file +that allows read/write access to the device configuration registers using +the RapidIO maintenance transactions: + + config - reads from and writes to the device configuration registers. + +This attribute is similar in behavior to the "config" attribute of PCI devices +and provides an access to the RapidIO device registers using standard file read +and write operations. + +3. Endpoint Device Attributes +----------------------------- + +Currently Linux RapidIO subsystem does not create any endpoint specific sysfs +attributes. It is possible that RapidIO master port drivers and endpoint device +drivers will add their device-specific sysfs attributes but such attributes are +outside the scope of this document. + +4. Switch Device Attributes +--------------------------- + +RapidIO switches have additional attributes in sysfs. RapidIO subsystem supports +common and device-specific sysfs attributes for switches. Because switches are +integrated into the RapidIO subsystem, it offers a method to create +device-specific sysfs attributes by specifying a callback function that may be +set by the switch initialization routine during enumeration or discovery process. + +4.1 Common Switch Attributes + + routes - reports switch routing information in "destID port" format. This + attribute reports only valid routing table entries, one line for + each entry. + destid - device destination ID that defines a route to the switch + hopcount - number of hops on the path to the switch + lnext - returns names of devices linked to the switch except one of a device + linked to the ingress port (reported as "lprev"). This is an array + names with number of lines equal to number of ports in switch. If + a switch port has no attached device, returns "null" instead of + a device name. + +4.2 Device-specific Switch Attributes + +Device-specific switch attributes are listed for each RapidIO switch driver +that exports additional attributes. + +IDT_GEN2: + errlog - reads contents of device error log until it is empty. diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt index 221f38be98f4..19f8278c3854 100644 --- a/Documentation/rbtree.txt +++ b/Documentation/rbtree.txt @@ -21,8 +21,8 @@ three rotations, respectively, to balance the tree), with slightly slower To quote Linux Weekly News: There are a number of red-black trees in use in the kernel. - The anticipatory, deadline, and CFQ I/O schedulers all employ - rbtrees to track requests; the packet CD/DVD driver does the same. + The deadline and CFQ I/O schedulers employ rbtrees to + track requests; the packet CD/DVD driver does the same. The high-resolution timer code uses an rbtree to organize outstanding timer requests. The ext3 filesystem tracks directory entries in a red-black tree. Virtual memory areas (VMAs) are tracked with red-black diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index 9104c1062084..250160469d83 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -178,38 +178,29 @@ RTC class framework, but can't be supported by the older driver. setting the longer alarm time and enabling its IRQ using a single request (using the same model as EFI firmware). - * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, it probably - also offers update IRQs whenever the "seconds" counter changes. - If needed, the RTC framework can emulate this mechanism. + * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, the RTC framework + will emulate this mechanism. - * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... another - feature often accessible with an IRQ line is a periodic IRQ, issued - at settable frequencies (usually 2^N Hz). + * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... these icotls + are emulated via a kernel hrtimer. In many cases, the RTC alarm can be a system wake event, used to force Linux out of a low power sleep state (or hibernation) back to a fully operational state. For example, a system could enter a deep power saving state until it's time to execute some scheduled tasks. -Note that many of these ioctls need not actually be implemented by your -driver. The common rtc-dev interface handles many of these nicely if your -driver returns ENOIOCTLCMD. Some common examples: +Note that many of these ioctls are handled by the common rtc-dev interface. +Some common examples: * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be called with appropriate values. - * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: the - set_alarm/read_alarm functions will be called. + * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: gets or sets + the alarm rtc_timer. May call the set_alarm driver function. - * RTC_IRQP_SET, RTC_IRQP_READ: the irq_set_freq function will be called - to set the frequency while the framework will handle the read for you - since the frequency is stored in the irq_freq member of the rtc_device - structure. Your driver needs to initialize the irq_freq member during - init. Make sure you check the requested frequency is in range of your - hardware in the irq_set_freq function. If it isn't, return -EINVAL. If - you cannot actually change the frequency, do not define irq_set_freq. + * RTC_IRQP_SET, RTC_IRQP_READ: These are emulated by the generic code. - * RTC_PIE_ON, RTC_PIE_OFF: the irq_set_state function will be called. + * RTC_PIE_ON, RTC_PIE_OFF: These are also emulated by the generic code. If all else fails, check out the rtc-test.c driver! diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt index 86f9f74b2b34..efe998becc5b 100644 --- a/Documentation/s390/Debugging390.txt +++ b/Documentation/s390/Debugging390.txt @@ -2273,7 +2273,7 @@ IP forwarding is on. There is a lot of useful info in here best found by going in & having a look around, so I'll take you through some entries I consider important. -All the processes running on the machine have there own entry defined by +All the processes running on the machine have their own entry defined by /proc/<pid> So lets have a look at the init process cd /proc/1 diff --git a/Documentation/scheduler/00-INDEX b/Documentation/scheduler/00-INDEX index 3c00c9c3219e..d2651c47ae27 100644 --- a/Documentation/scheduler/00-INDEX +++ b/Documentation/scheduler/00-INDEX @@ -3,7 +3,7 @@ sched-arch.txt - CPU Scheduler implementation hints for architecture specific code. sched-design-CFS.txt - - goals, design and implementation of the Complete Fair Scheduler. + - goals, design and implementation of the Completely Fair Scheduler. sched-domains.txt - information on scheduling domains. sched-nice-design.txt diff --git a/Documentation/scheduler/sched-design-CFS.txt b/Documentation/scheduler/sched-design-CFS.txt index 8239ebbcddce..99961993257a 100644 --- a/Documentation/scheduler/sched-design-CFS.txt +++ b/Documentation/scheduler/sched-design-CFS.txt @@ -164,7 +164,7 @@ This is the (partial) list of the hooks: It puts the scheduling entity (task) into the red-black tree and increments the nr_running variable. - - dequeue_tree(...) + - dequeue_task(...) When a task is no longer runnable, this function is called to keep the corresponding scheduling entity out of the red-black tree. It decrements @@ -195,11 +195,6 @@ This is the (partial) list of the hooks: This function is mostly called from time tick functions; it might lead to process switch. This drives the running preemption. - - task_new(...) - - The core scheduler gives the scheduling module an opportunity to manage new - task startup. The CFS scheduling module uses it for group scheduling, while - the scheduling module for a real-time task does not use it. diff --git a/Documentation/scheduler/sched-domains.txt b/Documentation/scheduler/sched-domains.txt index 373ceacc367e..b7ee379b651b 100644 --- a/Documentation/scheduler/sched-domains.txt +++ b/Documentation/scheduler/sched-domains.txt @@ -1,8 +1,7 @@ -Each CPU has a "base" scheduling domain (struct sched_domain). These are -accessed via cpu_sched_domain(i) and this_sched_domain() macros. The domain +Each CPU has a "base" scheduling domain (struct sched_domain). The domain hierarchy is built from these base domains via the ->parent pointer. ->parent -MUST be NULL terminated, and domain structures should be per-CPU as they -are locklessly updated. +MUST be NULL terminated, and domain structures should be per-CPU as they are +locklessly updated. Each scheduling domain spans a number of CPUs (stored in the ->span field). A domain's span MUST be a superset of it child's span (this restriction could @@ -26,11 +25,26 @@ is treated as one entity. The load of a group is defined as the sum of the load of each of its member CPUs, and only when the load of a group becomes out of balance are tasks moved between groups. -In kernel/sched.c, rebalance_tick is run periodically on each CPU. This -function takes its CPU's base sched domain and checks to see if has reached -its rebalance interval. If so, then it will run load_balance on that domain. -rebalance_tick then checks the parent sched_domain (if it exists), and the -parent of the parent and so forth. +In kernel/sched.c, trigger_load_balance() is run periodically on each CPU +through scheduler_tick(). It raises a softirq after the next regularly scheduled +rebalancing event for the current runqueue has arrived. The actual load +balancing workhorse, run_rebalance_domains()->rebalance_domains(), is then run +in softirq context (SCHED_SOFTIRQ). + +The latter function takes two arguments: the current CPU and whether it was idle +at the time the scheduler_tick() happened and iterates over all sched domains +our CPU is on, starting from its base domain and going up the ->parent chain. +While doing that, it checks to see if the current domain has exhausted its +rebalance interval. If so, it runs load_balance() on that domain. It then checks +the parent sched_domain (if it exists), and the parent of the parent and so +forth. + +Initially, load_balance() finds the busiest group in the current sched domain. +If it succeeds, it looks for the busiest runqueue of all the CPUs' runqueues in +that group. If it manages to find such a runqueue, it locks both our initial +CPU's runqueue and the newly found busiest one and starts moving tasks from it +to our runqueue. The exact number of tasks amounts to an imbalance previously +computed while iterating over this sched domain's groups. *** Implementing sched domains *** The "base" domain will "span" the first level of the hierarchy. In the case diff --git a/Documentation/scheduler/sched-stats.txt b/Documentation/scheduler/sched-stats.txt index 01e69404ee5e..1cd5d51bc761 100644 --- a/Documentation/scheduler/sched-stats.txt +++ b/Documentation/scheduler/sched-stats.txt @@ -1,3 +1,7 @@ +Version 15 of schedstats dropped counters for some sched_yield: +yld_exp_empty, yld_act_empty and yld_both_empty. Otherwise, it is +identical to version 14. + Version 14 of schedstats includes support for sched_domains, which hit the mainline kernel in 2.6.20 although it is identical to the stats from version 12 which was in the kernel from 2.6.13-2.6.19 (version 13 never saw a kernel @@ -28,32 +32,25 @@ to write their own scripts, the fields are described here. CPU statistics -------------- -cpu<N> 1 2 3 4 5 6 7 8 9 10 11 12 - -NOTE: In the sched_yield() statistics, the active queue is considered empty - if it has only one process in it, since obviously the process calling - sched_yield() is that process. +cpu<N> 1 2 3 4 5 6 7 8 9 -First four fields are sched_yield() statistics: - 1) # of times both the active and the expired queue were empty - 2) # of times just the active queue was empty - 3) # of times just the expired queue was empty - 4) # of times sched_yield() was called +First field is a sched_yield() statistic: + 1) # of times sched_yield() was called Next three are schedule() statistics: - 5) # of times we switched to the expired queue and reused it - 6) # of times schedule() was called - 7) # of times schedule() left the processor idle + 2) # of times we switched to the expired queue and reused it + 3) # of times schedule() was called + 4) # of times schedule() left the processor idle Next two are try_to_wake_up() statistics: - 8) # of times try_to_wake_up() was called - 9) # of times try_to_wake_up() was called to wake up the local cpu + 5) # of times try_to_wake_up() was called + 6) # of times try_to_wake_up() was called to wake up the local cpu Next three are statistics describing scheduling latency: - 10) sum of all time spent running by tasks on this processor (in jiffies) - 11) sum of all time spent waiting to run by tasks on this processor (in + 7) sum of all time spent running by tasks on this processor (in jiffies) + 8) sum of all time spent waiting to run by tasks on this processor (in jiffies) - 12) # of timeslices run on this cpu + 9) # of timeslices run on this cpu Domain statistics diff --git a/Documentation/scsi/ChangeLog.lpfc b/Documentation/scsi/ChangeLog.lpfc index 337c924cc81f..c56ec99d7b2f 100644 --- a/Documentation/scsi/ChangeLog.lpfc +++ b/Documentation/scsi/ChangeLog.lpfc @@ -352,7 +352,7 @@ Changes from 20041229 to 20050110 lpfc_scsiport.c * In remote port changes: no longer nulling target->pnode when removing from mapped list. Pnode get nulled when the node is - freed (after nodev tmo). This bug was causing i/o recieved in + freed (after nodev tmo). This bug was causing i/o received in the small window while the device was blocked to be errored w/ did_no_connect. With the fix, it returns host_busy (per the pre-remote port changes). @@ -530,7 +530,7 @@ Changes from 20041018 to 20041123 coherent mappings. Note: There are more consistent mappings that are using pci_dma_sync calls. Probably these should be removed as well. - * Modified lpfc_free_scsi_buf to accomodate all three scsi_buf + * Modified lpfc_free_scsi_buf to accommodate all three scsi_buf free types to alleviate miscellaneous panics with cable pull testing. * Set hotplug to default 0 and lpfc_target_remove to not remove @@ -573,7 +573,7 @@ Changes from 20041018 to 20041123 * Backround nodev_timeout processing to DPC This enables us to unblock (stop dev_loss_tmo) when appopriate. * Fix array discovery with multiple luns. The max_luns was 0 at - the time the host structure was intialized. lpfc_cfg_params + the time the host structure was initialized. lpfc_cfg_params then set the max_luns to the correct value afterwards. * Remove unused define LPFC_MAX_LUN and set the default value of lpfc_max_lun parameter to 512. @@ -583,7 +583,7 @@ Changes from 20041018 to 20041123 included more than once. * Replaced "set_current_state(TASK_UNINTERRUPTIBLE); schedule_timeout(timeout)" with "msleep(timeout)". - * Fixnode was loosing starget when rediscovered. We saw messages + * Fixnode was losing starget when rediscovered. We saw messages like: lpfc 0000:04:02.0: 0:0263 Cannot block scsi target as a result. Moved starget field into struct lpfc_target which is referenced from the node. @@ -604,7 +604,7 @@ Changes from 20041018 to 20041123 * Make 3 functions static: lpfc_get_hba_sym_node_name, lpfc_intr_prep and lpfc_setup_slim_access. Move lpfc_intr_prep and lpfc_setup_slim_access so they're defined before being used. - * Remove an unecessary list_del() in lpfc_hbadisc.c. + * Remove an unnecessary list_del() in lpfc_hbadisc.c. * Set nlp_state before calling lpfc_nlp_list() since this will potentially call fc_target_unblock which may cause a race in queuecommand by releasing host_lock. @@ -753,7 +753,7 @@ Changes from 20040908 to 20040920 * Changed version number to 8.0.12 * Removed used #defines: DEFAULT_PCI_LATENCY_CLOCKS and PCI_LATENCY_VALUE from lpfc_hw.h. - * Changes to accomodate rnid. + * Changes to accommodate rnid. * Fix RSCN handling so RSCN NS queries only effect NPorts found in RSCN data. * If we rcv a plogi on a NPort queued up for discovery, clear the @@ -813,7 +813,7 @@ Changes from 20040908 to 20040920 counter instead, brd_no isn't reused anymore. Also some tiny whitespace cleanups in surrounding code. * Reorder functions in lpfc_els.c to remove need for prototypes. - * Removed unsed prototypes from lpfc_crtn.h - + * Removed unused prototypes from lpfc_crtn.h - lpfc_ip_timeout_handler, lpfc_read_pci and lpfc_revoke. * Removed some unused prototypes from lpfc_crtn.h - lpfc_scsi_hba_reset, lpfc_scsi_issue_inqsn, @@ -863,7 +863,7 @@ Changes from 20040823 to 20040908 * Minimal support for SCSI flat space addressing/volume set addressing. Use 16 bits of LUN address so that flat addressing/VSA will work. - * Changed 2 occurences of if( 1 != f(x)) to if(f(x) != 1) + * Changed 2 occurrences of if( 1 != f(x)) to if(f(x) != 1) * Drop include of lpfc_cfgparm.h. * Reduce stack usage of lpfc_fdmi_cmd in lpfc_ct.c. * Add minimum range checking property to /sys write/store @@ -1449,7 +1449,7 @@ Changes from 20040402 to 20040409 * Removed lpfc_els_chk_latt from the lpfc_config_post function. lpfc_els_chk_latt will enable the link event interrupts when flogi is pending which causes two discovery state machines - running parallely. + running parallelly. * Add pci_disable_device to unload path. * Move lpfc_sleep_event from lpfc_fcp.c to lpfc_util_ioctl.c * Call dma_map_single() & pci_map_single() directly instead of via @@ -1590,7 +1590,7 @@ Changes from 20040326 to 20040402 ELX_WRITE_HS ELX_WRITE_HA ELX_WRITE_CA ELX_READ_HC ELX_READ_HS ELX_READ_HA ELX_READ_CA ELX_READ_MB ELX_RESET ELX_READ_HBA ELX_INSTANCE ELX_LIP. Also introduced - attribute "set" to be used in conjuction with the above + attribute "set" to be used in conjunction with the above attributes. * Removed DLINK, enque and deque declarations now that clock doesn't use them anymore diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid index 5e07d320817d..d2052fdbedd2 100644 --- a/Documentation/scsi/ChangeLog.megaraid +++ b/Documentation/scsi/ChangeLog.megaraid @@ -168,7 +168,7 @@ Older Version : 2.20.4.6 (scsi module), 2.20.2.6 (cmm module) 1. Sorted out PCI IDs to remove megaraid support overlaps. Based on the patch from Daniel, sorted out PCI IDs along with - charactor node name change from 'megadev' to 'megadev_legacy' to avoid + character node name change from 'megadev' to 'megadev_legacy' to avoid conflict. --- Hopefully we'll be getting the build restriction zapped much sooner, diff --git a/Documentation/scsi/ChangeLog.megaraid_sas b/Documentation/scsi/ChangeLog.megaraid_sas index 30023568805e..4d9ce73ff730 100644 --- a/Documentation/scsi/ChangeLog.megaraid_sas +++ b/Documentation/scsi/ChangeLog.megaraid_sas @@ -1,3 +1,95 @@ +Release Date : Thu. Feb 24, 2011 17:00:00 PST 2010 - + (emaild-id:megaraidlinux@lsi.com) + Adam Radford +Current Version : 00.00.05.34-rc1 +Old Version : 00.00.05.29-rc1 + 1. Fix some failure gotos from megasas_probe_one(), etc. + 2. Add missing check_and_restore_queue_depth() call in + complete_cmd_fusion(). + 3. Enable MSI-X before calling megasas_init_fw(). + 4. Call tasklet_schedule() even if outbound_intr_status == 0 for MFI based + boards in MSI-X mode. + 5. Fix megasas_probe_one() to clear PCI_MSIX_FLAGS_ENABLE in msi control + register in kdump kernel. + 6. Fix megasas_get_cmd() to only print "Command pool empty" if + megasas_dbg_lvl is set. + 7. Fix megasas_build_dcdb_fusion() to not filter by TYPE_DISK. + 8. Fix megasas_build_dcdb_fusion() to use io_request->LUN[1] field. + 9. Add MR_EVT_CFG_CLEARED to megasas_aen_polling(). + 10. Fix tasklet_init() in megasas_init_fw() to use instancet->tasklet. + 11. Fix fault state handling in megasas_transition_to_ready(). + 12. Fix max_sectors setting for IEEE SGL's. + 13. Fix iMR OCR support to work correctly. +------------------------------------------------------------------------------- +Release Date : Tues. Dec 14, 2010 17:00:00 PST 2010 - + (emaild-id:megaraidlinux@lsi.com) + Adam Radford +Current Version : 00.00.05.29-rc1 +Old Version : 00.00.04.31-rc1 + 1. Rename megaraid_sas.c to megaraid_sas_base.c. + 2. Update GPL headers. + 3. Add MSI-X support and 'msix_disable' module parameter. + 4. Use lowest memory bar (for SR-IOV VF support). + 5. Add struct megasas_instance_temlate changes, and change all code to use + new instance entries: + + irqreturn_t (*service_isr )(int irq, void *devp); + void (*tasklet)(unsigned long); + u32 (*init_adapter)(struct megasas_instance *); + u32 (*build_and_issue_cmd) (struct megasas_instance *, + struct scsi_cmnd *); + void (*issue_dcmd) (struct megasas_instance *instance, + struct megasas_cmd *cmd); + + 6. Add code to support MegaRAID 9265/9285 controllers device id (0x5b). +------------------------------------------------------------------------------- +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/ChangeLog.ncr53c8xx b/Documentation/scsi/ChangeLog.ncr53c8xx index 8b278c10edfd..9288e3d8974a 100644 --- a/Documentation/scsi/ChangeLog.ncr53c8xx +++ b/Documentation/scsi/ChangeLog.ncr53c8xx @@ -200,7 +200,7 @@ Sun Feb 14:00 1999 Gerard Roudier (groudier@club-internet.fr) By default the driver uses both IRQF_SHARED and IRQF_DISABLED. Option 'ncr53c8xx=irqm:0x20' may be used when an IRQ is shared by a 53C8XX adapter and a network board. - - Tiny mispelling fixed (ABORT instead of ABRT). Was fortunately + - Tiny misspelling fixed (ABORT instead of ABRT). Was fortunately harmless. - Negotiate SYNC data transfers with CCS devices. diff --git a/Documentation/scsi/ChangeLog.sym53c8xx b/Documentation/scsi/ChangeLog.sym53c8xx index 02ffbc1e8a84..c1933707d0bc 100644 --- a/Documentation/scsi/ChangeLog.sym53c8xx +++ b/Documentation/scsi/ChangeLog.sym53c8xx @@ -457,7 +457,7 @@ Fri Jan 1 20:00 1999 Gerard Roudier (groudier@club-internet.fr) Sat Dec 19 21:00 1998 Gerard Roudier (groudier@club-internet.fr) * version sym53c8xx-1.0 - Define some new IO registers for the 896 (istat1, mbox0, mbox1) - - Revamp slighly the Symbios NVRAM lay-out based on the excerpt of + - Revamp slightly the Symbios NVRAM lay-out based on the excerpt of the header file I received from Symbios. - Check the PCI bus number for the boot order (Using a fast PCI controller behing a PCI-PCI bridge seems sub-optimal). diff --git a/Documentation/scsi/aha152x.txt b/Documentation/scsi/aha152x.txt index 29ce6d87e451..94848734ac66 100644 --- a/Documentation/scsi/aha152x.txt +++ b/Documentation/scsi/aha152x.txt @@ -124,7 +124,7 @@ in the partition table and therefore every operating system has to know the right geometry to be able to interpret it. Moreover there are certain limitations to the C/H/S addressing scheme, -namely the address space is limited to upto 255 heads, upto 63 sectors +namely the address space is limited to up to 255 heads, up to 63 sectors and a maximum of 1023 cylinders. The AHA-1522 BIOS calculates the geometry by fixing the number of heads diff --git a/Documentation/scsi/aic79xx.txt b/Documentation/scsi/aic79xx.txt index 16e054c9c70b..64ac7093c872 100644 --- a/Documentation/scsi/aic79xx.txt +++ b/Documentation/scsi/aic79xx.txt @@ -267,7 +267,7 @@ The following information is available in this file: Option: tag_info:{{value[,value...]}[,{value[,value...]}...]} Definition: Set the per-target tagged queue depth on a per controller basis. Both controllers and targets - may be ommitted indicating that they should retain + may be omitted indicating that they should retain the default tag depth. Examples: tag_info:{{16,32,32,64,8,8,,32,32,32,32,32,32,32,32,32} On Controller 0 @@ -291,7 +291,7 @@ The following information is available in this file: The rd_strm_bitmask is a 16 bit hex value in which each bit represents a target. Setting the target's bit to '1' enables read streaming for that - target. Controllers may be ommitted indicating that + target. Controllers may be omitted indicating that they should retain the default read streaming setting. Example: rd_strm:{0x0041} On Controller 0 @@ -313,7 +313,7 @@ The following information is available in this file: ----------------------------------------------------------------- Option: dv: {value[,value...]} Definition: Set Domain Validation Policy on a per-controller basis. - Controllers may be ommitted indicating that + Controllers may be omitted indicating that they should retain the default read streaming setting. Example: dv:{-1,0,,1,1,0} On Controller 0 leave DV at its default setting. @@ -340,7 +340,7 @@ The following information is available in this file: Option: precomp: {value[,value...]} Definition: Set IO Cell precompensation value on a per-controller basis. - Controllers may be ommitted indicating that + Controllers may be omitted indicating that they should retain the default precompensation setting. Example: precomp:{0x1} On Controller 0 set precompensation to 1. @@ -353,7 +353,7 @@ The following information is available in this file: ----------------------------------------------------------------- Option: slewrate: {value[,value...]} Definition: Set IO Cell slew rate on a per-controller basis. - Controllers may be ommitted indicating that + Controllers may be omitted indicating that they should retain the default slew rate setting. Example: slewrate:{0x1} On Controller 0 set slew rate to 1. @@ -366,7 +366,7 @@ The following information is available in this file: ----------------------------------------------------------------- Option: amplitude: {value[,value...]} Definition: Set IO Cell signal amplitude on a per-controller basis. - Controllers may be ommitted indicating that + Controllers may be omitted indicating that they should retain the default read streaming setting. Example: amplitude:{0x1} On Controller 0 set amplitude to 1. diff --git a/Documentation/scsi/hpsa.txt b/Documentation/scsi/hpsa.txt index dca658362cbf..891435a72fce 100644 --- a/Documentation/scsi/hpsa.txt +++ b/Documentation/scsi/hpsa.txt @@ -28,6 +28,12 @@ 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. +The "hpsa_simple_mode=1" boot parameter may be used to prevent the driver from +putting the controller into "performant" mode. The difference is that with simple +mode, each command completion requires an interrupt, while with "performant mode" +(the default, and ordinarily better performing) it is possible to have multiple +command completions indicated by a single interrupt. + HPSA specific entries in /sys ----------------------------- @@ -39,6 +45,8 @@ HPSA specific entries in /sys /sys/class/scsi_host/host*/rescan /sys/class/scsi_host/host*/firmware_revision + /sys/class/scsi_host/host*/resettable + /sys/class/scsi_host/host*/transport_mode 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 @@ -55,6 +63,21 @@ HPSA specific entries in /sys root@host:/sys/class/scsi_host/host4# cat firmware_revision 7.14 + The transport_mode indicates whether the controller is in "performant" + or "simple" mode. This is controlled by the "hpsa_simple_mode" module + parameter. + + The "resettable" read-only attribute indicates whether a particular + controller is able to honor the "reset_devices" kernel parameter. If the + device is resettable, this file will contain a "1", otherwise, a "0". This + parameter is used by kdump, for example, to reset the controller at driver + load time to eliminate any outstanding commands on the controller and get the + controller into a known state so that the kdump initiated i/o will work right + and not be disrupted in any way by stale commands or other stale state + remaining on the controller from the previous kernel. This attribute enables + kexec tools to warn the user if they attempt to designate a device which is + unable to honor the reset_devices kernel parameter as a dump device. + HPSA specific disk attributes: ------------------------------ diff --git a/Documentation/scsi/ibmmca.txt b/Documentation/scsi/ibmmca.txt index 45d61ad8c6f7..ac41a9fcac77 100644 --- a/Documentation/scsi/ibmmca.txt +++ b/Documentation/scsi/ibmmca.txt @@ -303,7 +303,7 @@ (scb) and calls a local function issue_cmd(), which writes a scb command into subsystem I/O ports. Once the scb command is carried out, the interrupt_handler() is invoked. If a device is determined to be - existant and it has not assigned any ldn, it gets one dynamically. + existent and it has not assigned any ldn, it gets one dynamically. For this, the whole stuff is done in ibmmca_queuecommand(). 2.6 Abort & Reset Commands @@ -741,7 +741,7 @@ some error appeared, else it is undefined. Now, this is fixed. Before any SCB command gets queued, the tsb.dev_status is set to 0, so the cmd->result won't screw up Linux higher level drivers. - 2) The reset-function has slightly improved. This is still planed for + 2) The reset-function has slightly improved. This is still planned for abort. During the abort and the reset function, no interrupts are allowed. This is however quite hard to cope with, so the INT-status register is read. When the interrupt gets queued, one can find its diff --git a/Documentation/scsi/scsi-changer.txt b/Documentation/scsi/scsi-changer.txt index 032399b16a53..ade046ea7c17 100644 --- a/Documentation/scsi/scsi-changer.txt +++ b/Documentation/scsi/scsi-changer.txt @@ -102,7 +102,7 @@ Trouble? If you insmod the driver with "insmod debug=1", it will be verbose and prints a lot of stuff to the syslog. Compiling the kernel with -CONFIG_SCSI_CONSTANTS=y improves the quality of the error messages alot +CONFIG_SCSI_CONSTANTS=y improves the quality of the error messages a lot because the kernel will translate the error codes into human-readable strings then. diff --git a/Documentation/scsi/scsi_eh.txt b/Documentation/scsi/scsi_eh.txt index 7acbebb17fa6..6ff16b620d84 100644 --- a/Documentation/scsi/scsi_eh.txt +++ b/Documentation/scsi/scsi_eh.txt @@ -290,7 +290,7 @@ scmd->allowed. SCSI transports/LLDDs automatically acquire sense data on command failures (autosense). Autosense is recommended for performance reasons and as sense information could get out of - sync inbetween occurrence of CHECK CONDITION and this action. + sync between occurrence of CHECK CONDITION and this action. Note that if autosense is not supported, scmd->sense_buffer contains invalid sense data when error-completing the scmd diff --git a/Documentation/scsi/scsi_fc_transport.txt b/Documentation/scsi/scsi_fc_transport.txt index e00192de4d1c..f79282fc48d7 100644 --- a/Documentation/scsi/scsi_fc_transport.txt +++ b/Documentation/scsi/scsi_fc_transport.txt @@ -291,7 +291,7 @@ Transport <-> LLDD Interfaces : Vport support by LLDD: The LLDD indicates support for vports by supplying a vport_create() - function in the transport template. The presense of this function will + function in the transport template. The presence of this function will cause the creation of the new attributes on the fc_host. As part of the physical port completing its initialization relative to the transport, it should set the max_npiv_vports attribute to indicate the diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index 570ef2b3d79b..5f17d29c59b5 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -1044,9 +1044,9 @@ Details: /** - * queuecommand - queue scsi command, invoke 'done' on completion + * queuecommand - queue scsi command, invoke scp->scsi_done on completion + * @shost: pointer to the scsi host object * @scp: pointer to scsi command object - * @done: function pointer to be invoked on completion * * Returns 0 on success. * @@ -1074,42 +1074,45 @@ Details: * * Other types of errors that are detected immediately may be * flagged by setting scp->result to an appropriate value, - * invoking the 'done' callback, and then returning 0 from this - * function. If the command is not performed immediately (and the - * LLD is starting (or will start) the given command) then this - * function should place 0 in scp->result and return 0. + * invoking the scp->scsi_done callback, and then returning 0 + * from this function. If the command is not performed + * immediately (and the LLD is starting (or will start) the given + * command) then this function should place 0 in scp->result and + * return 0. * * Command ownership. If the driver returns zero, it owns the - * command and must take responsibility for ensuring the 'done' - * callback is executed. Note: the driver may call done before - * returning zero, but after it has called done, it may not - * return any value other than zero. If the driver makes a - * non-zero return, it must not execute the command's done - * callback at any time. - * - * Locks: struct Scsi_Host::host_lock held on entry (with "irqsave") - * and is expected to be held on return. + * command and must take responsibility for ensuring the + * scp->scsi_done callback is executed. Note: the driver may + * call scp->scsi_done before returning zero, but after it has + * called scp->scsi_done, it may not return any value other than + * zero. If the driver makes a non-zero return, it must not + * execute the command's scsi_done callback at any time. + * + * Locks: up to and including 2.6.36, struct Scsi_Host::host_lock + * held on entry (with "irqsave") and is expected to be + * held on return. From 2.6.37 onwards, queuecommand is + * called without any locks held. * * Calling context: in interrupt (soft irq) or process context * - * Notes: This function should be relatively fast. Normally it will - * not wait for IO to complete. Hence the 'done' callback is invoked - * (often directly from an interrupt service routine) some time after - * this function has returned. In some cases (e.g. pseudo adapter - * drivers that manufacture the response to a SCSI INQUIRY) - * the 'done' callback may be invoked before this function returns. - * If the 'done' callback is not invoked within a certain period - * the SCSI mid level will commence error processing. - * If a status of CHECK CONDITION is placed in "result" when the - * 'done' callback is invoked, then the LLD driver should - * perform autosense and fill in the struct scsi_cmnd::sense_buffer + * Notes: This function should be relatively fast. Normally it + * will not wait for IO to complete. Hence the scp->scsi_done + * callback is invoked (often directly from an interrupt service + * routine) some time after this function has returned. In some + * cases (e.g. pseudo adapter drivers that manufacture the + * response to a SCSI INQUIRY) the scp->scsi_done callback may be + * invoked before this function returns. If the scp->scsi_done + * callback is not invoked within a certain period the SCSI mid + * level will commence error processing. If a status of CHECK + * CONDITION is placed in "result" when the scp->scsi_done + * callback is invoked, then the LLD driver should perform + * autosense and fill in the struct scsi_cmnd::sense_buffer * array. The scsi_cmnd::sense_buffer array is zeroed prior to * the mid level queuing a command to an LLD. * * Defined in: LLD **/ - int queuecommand(struct scsi_cmnd * scp, - void (*done)(struct scsi_cmnd *)) + int queuecommand(struct Scsi_Host *shost, struct scsi_cmnd * scp) /** @@ -1340,7 +1343,7 @@ Members of interest: underruns (overruns should be rare). If possible an LLD should set 'resid' prior to invoking 'done'. The most interesting case is data transfers from a SCSI target - device device (i.e. READs) that underrun. + device (e.g. READs) that underrun. underflow - LLD should place (DID_ERROR << 16) in 'result' if actual number of bytes transferred is less than this figure. Not many LLDs implement this check and some that @@ -1348,6 +1351,18 @@ Members of interest: report a DID_ERROR. Better for an LLD to implement 'resid'. +It is recommended that a LLD set 'resid' on data transfers from a SCSI +target device (e.g. READs). It is especially important that 'resid' is set +when such data transfers have sense keys of MEDIUM ERROR and HARDWARE ERROR +(and possibly RECOVERED ERROR). In these cases if a LLD is in doubt how much +data has been received then the safest approach is to indicate no bytes have +been received. For example: to indicate that no valid data has been received +a LLD might use these helpers: + scsi_set_resid(SCpnt, scsi_bufflen(SCpnt)); +where 'SCpnt' is a pointer to a scsi_cmnd object. To indicate only three 512 +bytes blocks has been received 'resid' could be set like this: + scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512)); + The scsi_cmnd structure is defined in include/scsi/scsi_cmnd.h diff --git a/Documentation/scsi/st.txt b/Documentation/scsi/st.txt index 40752602c050..691ca292c24d 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/scsi/sym53c8xx_2.txt b/Documentation/scsi/sym53c8xx_2.txt index 6f63b7989679..6af8f7a7770f 100644 --- a/Documentation/scsi/sym53c8xx_2.txt +++ b/Documentation/scsi/sym53c8xx_2.txt @@ -285,7 +285,7 @@ from the driver. 7. Profiling information -This driver does not provide profiling informations as did its predecessors. +This driver does not provide profiling information as did its predecessors. This feature was not this useful and added complexity to the code. As the driver code got more complex, I have decided to remove everything that didn't seem actually useful. diff --git a/Documentation/serial/00-INDEX b/Documentation/serial/00-INDEX index 07dcdb0d2a36..e09468ad3cb1 100644 --- a/Documentation/serial/00-INDEX +++ b/Documentation/serial/00-INDEX @@ -14,6 +14,8 @@ riscom8.txt - notes on using the RISCom/8 multi-port serial driver. rocket.txt - info on the Comtrol RocketPort multiport serial driver. +serial-rs485.txt + - info about RS485 structures and support in the kernel. specialix.txt - info on hardware/driver for specialix IO8+ multiport serial card. stallion.txt diff --git a/Documentation/serial/moxa-smartio b/Documentation/serial/moxa-smartio index d10443918684..5d2a33be0bd8 100644 --- a/Documentation/serial/moxa-smartio +++ b/Documentation/serial/moxa-smartio @@ -473,7 +473,7 @@ Content spd_normal Use 38.4kb when the application requests 38.4kb. spd_cust Use the custom divisor to set the speed when the application requests 38.4kb. - divisor This option set the custom divison. + divisor This option set the custom division. baud_base This option set the base baud rate. ----------------------------------------------------------------------------- diff --git a/Documentation/serial/n_gsm.txt b/Documentation/serial/n_gsm.txt new file mode 100644 index 000000000000..a5d91126a8f7 --- /dev/null +++ b/Documentation/serial/n_gsm.txt @@ -0,0 +1,89 @@ +n_gsm.c GSM 0710 tty multiplexor HOWTO +=================================================== + +This line discipline implements the GSM 07.10 multiplexing protocol +detailed in the following 3GPP document : +http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip + +This document give some hints on how to use this driver with GPRS and 3G +modems connected to a physical serial port. + +How to use it +------------- +1- initialize the modem in 0710 mux mode (usually AT+CMUX= command) through +its serial port. Depending on the modem used, you can pass more or less +parameters to this command, +2- switch the serial line to using the n_gsm line discipline by using +TIOCSETD ioctl, +3- configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl, + +Major parts of the initialization program : +(a good starting point is util-linux-ng/sys-utils/ldattach.c) +#include <linux/gsmmux.h> +#define N_GSM0710 21 /* GSM 0710 Mux */ +#define DEFAULT_SPEED B115200 +#define SERIAL_PORT /dev/ttyS0 + + int ldisc = N_GSM0710; + struct gsm_config c; + struct termios configuration; + + /* open the serial port connected to the modem */ + fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY); + + /* configure the serial port : speed, flow control ... */ + + /* send the AT commands to switch the modem to CMUX mode + and check that it's successful (should return OK) */ + write(fd, "AT+CMUX=0\r", 10); + + /* experience showed that some modems need some time before + being able to answer to the first MUX packet so a delay + may be needed here in some case */ + sleep(3); + + /* use n_gsm line discipline */ + ioctl(fd, TIOCSETD, &ldisc); + + /* get n_gsm configuration */ + ioctl(fd, GSMIOC_GETCONF, &c); + /* we are initiator and need encoding 0 (basic) */ + c.initiator = 1; + c.encapsulation = 0; + /* our modem defaults to a maximum size of 127 bytes */ + c.mru = 127; + c.mtu = 127; + /* set the new configuration */ + ioctl(fd, GSMIOC_SETCONF, &c); + + /* and wait for ever to keep the line discipline enabled */ + daemon(0,0); + pause(); + +4- create the devices corresponding to the "virtual" serial ports (take care, +each modem has its configuration and some DLC have dedicated functions, +for example GPS), starting with minor 1 (DLC0 is reserved for the management +of the mux) + +MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}` +for i in `seq 1 4`; do + mknod /dev/ttygsm$i c $MAJOR $i +done + +5- use these devices as plain serial ports. +for example, it's possible : +- and to use gnokii to send / receive SMS on ttygsm1 +- to use ppp to establish a datalink on ttygsm2 + +6- first close all virtual ports before closing the physical port. + +Additional Documentation +------------------------ +More practical details on the protocol and how it's supported by industrial +modems can be found in the following documents : +http://www.telit.com/module/infopool/download.php?id=616 +http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf +http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx +http://wm.sim.com/sim/News/photo/2010721161442.pdf + +11-03-08 - Eric Bénard - <eric@eukrea.com> diff --git a/Documentation/serial/serial-rs485.txt b/Documentation/serial/serial-rs485.txt new file mode 100644 index 000000000000..a4932387bbfb --- /dev/null +++ b/Documentation/serial/serial-rs485.txt @@ -0,0 +1,120 @@ + RS485 SERIAL COMMUNICATIONS + +1. INTRODUCTION + + EIA-485, also known as TIA/EIA-485 or RS-485, is a standard defining the + electrical characteristics of drivers and receivers for use in balanced + digital multipoint systems. + This standard is widely used for communications in industrial automation + because it can be used effectively over long distances and in electrically + noisy environments. + +2. HARDWARE-RELATED CONSIDERATIONS + + Some CPUs/UARTs (e.g., Atmel AT91 or 16C950 UART) contain a built-in + half-duplex mode capable of automatically controlling line direction by + toggling RTS or DTR signals. That can be used to control external + half-duplex hardware like an RS485 transceiver or any RS232-connected + half-duplex devices like some modems. + + For these microcontrollers, the Linux driver should be made capable of + working in both modes, and proper ioctls (see later) should be made + available at user-level to allow switching from one mode to the other, and + vice versa. + +3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL + + The Linux kernel provides the serial_rs485 structure (see [1]) to handle + RS485 communications. This data structure is used to set and configure RS485 + parameters in the platform data and in ioctls. + + Any driver for devices capable of working both as RS232 and RS485 should + provide at least the following ioctls: + + - TIOCSRS485 (typically associated with number 0x542F). This ioctl is used + to enable/disable RS485 mode from user-space + + - TIOCGRS485 (typically associated with number 0x542E). This ioctl is used + to get RS485 mode from kernel-space (i.e., driver) to user-space. + + In other words, the serial driver should contain a code similar to the next + one: + + static struct uart_ops atmel_pops = { + /* ... */ + .ioctl = handle_ioctl, + }; + + static int handle_ioctl(struct uart_port *port, + unsigned int cmd, + unsigned long arg) + { + struct serial_rs485 rs485conf; + + switch (cmd) { + case TIOCSRS485: + if (copy_from_user(&rs485conf, + (struct serial_rs485 *) arg, + sizeof(rs485conf))) + return -EFAULT; + + /* ... */ + break; + + case TIOCGRS485: + if (copy_to_user((struct serial_rs485 *) arg, + ..., + sizeof(rs485conf))) + return -EFAULT; + /* ... */ + break; + + /* ... */ + } + } + + +4. USAGE FROM USER-LEVEL + + From user-level, RS485 configuration can be get/set using the previous + ioctls. For instance, to set RS485 you can use the following code: + + #include <linux/serial.h> + + /* Driver-specific ioctls: */ + #define TIOCGRS485 0x542E + #define TIOCSRS485 0x542F + + /* Open your specific device (e.g., /dev/mydevice): */ + int fd = open ("/dev/mydevice", O_RDWR); + if (fd < 0) { + /* Error handling. See errno. */ + } + + struct serial_rs485 rs485conf; + + /* Set RS485 mode: */ + rs485conf.flags |= SER_RS485_ENABLED; + + /* Set rts delay before send, if needed: */ + rs485conf.flags |= SER_RS485_RTS_BEFORE_SEND; + rs485conf.delay_rts_before_send = ...; + + /* Set rts delay after send, if needed: */ + rs485conf.flags |= SER_RS485_RTS_AFTER_SEND; + rs485conf.delay_rts_after_send = ...; + + if (ioctl (fd, TIOCSRS485, &rs485conf) < 0) { + /* Error handling. See errno. */ + } + + /* Use read() and write() syscalls here... */ + + /* Close the device when finished: */ + if (close (fd) < 0) { + /* Error handling. See errno. */ + } + +5. REFERENCES + + [1] include/linux/serial.h diff --git a/Documentation/serial/tty.txt b/Documentation/serial/tty.txt index 7c900507279f..540db41dfd5d 100644 --- a/Documentation/serial/tty.txt +++ b/Documentation/serial/tty.txt @@ -107,7 +107,7 @@ write_wakeup() - May be called at any point between open and close. dcd_change() - Report to the tty line the current DCD pin status changes and the relative timestamp. The timestamp - can be NULL. + cannot be NULL. Driver Access diff --git a/Documentation/sh/clk.txt b/Documentation/sh/clk.txt deleted file mode 100644 index 114b595cfa97..000000000000 --- a/Documentation/sh/clk.txt +++ /dev/null @@ -1,32 +0,0 @@ -Clock framework on SuperH architecture - -The framework on SH extends existing API by the function clk_set_rate_ex, -which prototype is as follows: - - clk_set_rate_ex (struct clk *clk, unsigned long rate, int algo_id) - -The algo_id parameter is used to specify algorithm used to recalculate clocks, -adjanced to clock, specified as first argument. It is assumed that algo_id==0 -means no changes to adjanced clock - -Internally, the clk_set_rate_ex forwards request to clk->ops->set_rate method, -if it is present in ops structure. The method should set the clock rate and adjust -all needed clocks according to the passed algo_id. -Exact values for algo_id are machine-dependent. For the sh7722, the following -values are defined: - - NO_CHANGE = 0, - IUS_N1_N1, /* I:U = N:1, U:Sh = N:1 */ - IUS_322, /* I:U:Sh = 3:2:2 */ - IUS_522, /* I:U:Sh = 5:2:2 */ - IUS_N11, /* I:U:Sh = N:1:1 */ - SB_N1, /* Sh:B = N:1 */ - SB3_N1, /* Sh:B3 = N:1 */ - SB3_32, /* Sh:B3 = 3:2 */ - SB3_43, /* Sh:B3 = 4:3 */ - SB3_54, /* Sh:B3 = 5:4 */ - BP_N1, /* B:P = N:1 */ - IP_N1 /* I:P = N:1 */ - -Each of these constants means relation between clocks that can be set via the FRQCR -register diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index 7f4dcebda9c6..9822afb6313c 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 chosen 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 chosen 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 -------------- @@ -906,13 +974,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. See hdspm.txt for details. - Module snd-hifier - ----------------- - - Module for the MediaTek/TempoTec HiFier Fantasia sound card. - - This module supports autoprobe and multiple cards. - Module snd-ice1712 ------------------ @@ -1463,15 +1524,20 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module snd-oxygen ----------------- - Module for sound cards based on the C-Media CMI8788 chip: + Module for sound cards based on the C-Media CMI8786/8787/8788 chip: * Asound A-8788 + * Asus Xonar DG * AuzenTech X-Meridian + * AuzenTech X-Meridian 2G * Bgears b-Enspirer * Club3D Theatron DTS * HT-Omega Claro (plus) * HT-Omega Claro halo (XT) + * Kuroutoshikou CMI8787-HG2PCI * Razer Barracuda AC-1 * Sondigo Inferno + * TempoTec HiFier Fantasia + * TempoTec HiFier Serenade This module supports autoprobe and multiple cards. @@ -1641,20 +1707,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 ----------------- @@ -1952,9 +2004,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module snd-virtuoso ------------------- - Module for sound cards based on the Asus AV100/AV200 chips, - i.e., Xonar D1, DX, D2, D2X, DS, HDAV1.3 (Deluxe), Essence ST - (Deluxe) and Essence STX. + Module for sound cards based on the Asus AV66/AV100/AV200 chips, + i.e., Xonar D1, DX, D2, D2X, DS, Essence ST (Deluxe), Essence STX, + HDAV1.3 (Deluxe), and HDAV1.3 Slim. This module supports autoprobe and multiple cards. @@ -2177,7 +2229,7 @@ Proc interfaces (/proc/asound) /proc/asound/card#/pcm#[cp]/oss ------------------------------- - String "erase" - erase all additional informations about OSS applications + String "erase" - erase all additional information about OSS applications String "<app_name> <fragments> <fragment_size> [<options>]" <app_name> - name of application with (higher priority) or without path diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt index 37c6aad5e590..d70c93bdcadf 100644 --- a/Documentation/sound/alsa/HD-Audio-Models.txt +++ b/Documentation/sound/alsa/HD-Audio-Models.txt @@ -94,7 +94,7 @@ ALC662/663/272 3stack-dig 3-stack (2-channel) with SPDIF 3stack-6ch 3-stack (6-channel) 3stack-6ch-dig 3-stack (6-channel) with SPDIF - 6stack-dig 6-stack with SPDIF + 5stack-dig 5-stack with SPDIF lenovo-101e Lenovo laptop eeepc-p701 ASUS Eeepc P701 eeepc-ep20 ASUS Eeepc EP20 @@ -149,7 +149,6 @@ ALC882/883/885/888/889 acer-aspire-7730g Acer Aspire 7730G acer-aspire-8930g Acer Aspire 8930G medion Medion Laptops - medion-md2 Medion MD2 targa-dig Targa/MSI targa-2ch-dig Targa/MSI with 2-channel targa-8ch-dig Targa/MSI with 8-channel (MSI GX620) @@ -297,6 +296,7 @@ Conexant 5066 ============= laptop Basic Laptop config (default) hp-laptop HP laptops, e g G60 + asus Asus K52JU, Lenovo G560 dell-laptop Dell laptops dell-vostro Dell Vostro olpc-xo-1_5 OLPC XO 1.5 diff --git a/Documentation/sound/alsa/HD-Audio.txt b/Documentation/sound/alsa/HD-Audio.txt index 278cc2122ea0..c82beb007634 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 diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt index 37ba3a72cb76..bce23a4a7875 100644 --- a/Documentation/sound/alsa/soc/codec.txt +++ b/Documentation/sound/alsa/soc/codec.txt @@ -27,42 +27,38 @@ ASoC Codec driver breakdown 1 - Codec DAI and PCM configuration ----------------------------------- -Each codec driver must have a struct snd_soc_codec_dai to define its DAI and +Each codec driver must have a struct snd_soc_dai_driver to define its DAI and PCM capabilities and operations. This struct is exported so that it can be registered with the core by your machine driver. e.g. -struct snd_soc_codec_dai wm8731_dai = { - .name = "WM8731", - /* playback capabilities */ +static struct snd_soc_dai_ops wm8731_dai_ops = { + .prepare = wm8731_pcm_prepare, + .hw_params = wm8731_hw_params, + .shutdown = wm8731_shutdown, + .digital_mute = wm8731_mute, + .set_sysclk = wm8731_set_dai_sysclk, + .set_fmt = wm8731_set_dai_fmt, +}; + +struct snd_soc_dai_driver wm8731_dai = { + .name = "wm8731-hifi", .playback = { .stream_name = "Playback", .channels_min = 1, .channels_max = 2, .rates = WM8731_RATES, .formats = WM8731_FORMATS,}, - /* capture capabilities */ .capture = { .stream_name = "Capture", .channels_min = 1, .channels_max = 2, .rates = WM8731_RATES, .formats = WM8731_FORMATS,}, - /* pcm operations - see section 4 below */ - .ops = { - .prepare = wm8731_pcm_prepare, - .hw_params = wm8731_hw_params, - .shutdown = wm8731_shutdown, - }, - /* DAI operations - see DAI.txt */ - .dai_ops = { - .digital_mute = wm8731_mute, - .set_sysclk = wm8731_set_dai_sysclk, - .set_fmt = wm8731_set_dai_fmt, - } + .ops = &wm8731_dai_ops, + .symmetric_rates = 1, }; -EXPORT_SYMBOL_GPL(wm8731_dai); 2 - Codec control IO @@ -186,13 +182,14 @@ when the mute is applied or freed. i.e. -static int wm8974_mute(struct snd_soc_codec *codec, - struct snd_soc_codec_dai *dai, int mute) +static int wm8974_mute(struct snd_soc_dai *dai, int mute) { - u16 mute_reg = wm8974_read_reg_cache(codec, WM8974_DAC) & 0xffbf; - if(mute) - wm8974_write(codec, WM8974_DAC, mute_reg | 0x40); + struct snd_soc_codec *codec = dai->codec; + u16 mute_reg = snd_soc_read(codec, WM8974_DAC) & 0xffbf; + + if (mute) + snd_soc_write(codec, WM8974_DAC, mute_reg | 0x40); else - wm8974_write(codec, WM8974_DAC, mute_reg); + snd_soc_write(codec, WM8974_DAC, mute_reg); return 0; } diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt index 2524c75557df..3e2ec9cbf397 100644 --- a/Documentation/sound/alsa/soc/machine.txt +++ b/Documentation/sound/alsa/soc/machine.txt @@ -12,6 +12,8 @@ the following struct:- struct snd_soc_card { char *name; + ... + int (*probe)(struct platform_device *pdev); int (*remove)(struct platform_device *pdev); @@ -22,12 +24,13 @@ struct snd_soc_card { int (*resume_pre)(struct platform_device *pdev); int (*resume_post)(struct platform_device *pdev); - /* machine stream operations */ - struct snd_soc_ops *ops; + ... /* CPU <--> Codec DAI links */ struct snd_soc_dai_link *dai_link; int num_links; + + ... }; probe()/remove() @@ -42,11 +45,6 @@ of any machine audio tasks that have to be done before or after the codec, DAIs and DMA is suspended and resumed. Optional. -Machine operations ------------------- -The machine specific audio operations can be set here. Again this is optional. - - Machine DAI Configuration ------------------------- The machine DAI configuration glues all the codec and CPU DAIs together. It can @@ -61,8 +59,10 @@ struct snd_soc_dai_link is used to set up each DAI in your machine. e.g. static struct snd_soc_dai_link corgi_dai = { .name = "WM8731", .stream_name = "WM8731", - .cpu_dai = &pxa_i2s_dai, - .codec_dai = &wm8731_dai, + .cpu_dai_name = "pxa-is2-dai", + .codec_dai_name = "wm8731-hifi", + .platform_name = "pxa-pcm-audio", + .codec_name = "wm8713-codec.0-001a", .init = corgi_wm8731_init, .ops = &corgi_ops, }; @@ -77,26 +77,6 @@ static struct snd_soc_card snd_soc_corgi = { }; -Machine Audio Subsystem ------------------------ - -The machine soc device glues the platform, machine and codec driver together. -Private data can also be set here. e.g. - -/* corgi audio private data */ -static struct wm8731_setup_data corgi_wm8731_setup = { - .i2c_address = 0x1b, -}; - -/* corgi audio subsystem */ -static struct snd_soc_device corgi_snd_devdata = { - .machine = &snd_soc_corgi, - .platform = &pxa2xx_soc_platform, - .codec_dev = &soc_codec_dev_wm8731, - .codec_data = &corgi_wm8731_setup, -}; - - Machine Power Map ----------------- diff --git a/Documentation/sound/alsa/soc/platform.txt b/Documentation/sound/alsa/soc/platform.txt index 06d835987c6a..d57efad37e0a 100644 --- a/Documentation/sound/alsa/soc/platform.txt +++ b/Documentation/sound/alsa/soc/platform.txt @@ -20,9 +20,10 @@ struct snd_soc_ops { int (*trigger)(struct snd_pcm_substream *, int); }; -The platform driver exports its DMA functionality via struct snd_soc_platform:- +The platform driver exports its DMA functionality via struct +snd_soc_platform_driver:- -struct snd_soc_platform { +struct snd_soc_platform_driver { char *name; int (*probe)(struct platform_device *pdev); @@ -34,6 +35,13 @@ struct snd_soc_platform { int (*pcm_new)(struct snd_card *, struct snd_soc_codec_dai *, struct snd_pcm *); void (*pcm_free)(struct snd_pcm *); + /* + * For platform caused delay reporting. + * Optional. + */ + snd_pcm_sframes_t (*delay)(struct snd_pcm_substream *, + struct snd_soc_dai *); + /* platform stream ops */ struct snd_pcm_ops *pcm_ops; }; diff --git a/Documentation/sound/oss/AudioExcelDSP16 b/Documentation/sound/oss/AudioExcelDSP16 index c0f08922993b..e0dc0641b480 100644 --- a/Documentation/sound/oss/AudioExcelDSP16 +++ b/Documentation/sound/oss/AudioExcelDSP16 @@ -1,10 +1,10 @@ Driver ------ -Informations about Audio Excel DSP 16 driver can be found in the source +Information about Audio Excel DSP 16 driver can be found in the source file aedsp16.c Please, read the head of the source before using it. It contain useful -informations. +information. Configuration ------------- @@ -68,7 +68,7 @@ Sound cards supported This driver supports the SC-6000 and SC-6600 based Gallant's sound card. It don't support the Audio Excel DSP 16 III (try the SC-6600 code). I'm working on the III version of the card: if someone have useful -informations about it, please let me know. +information about it, please let me know. For all the non-supported audio cards, you have to boot MS-DOS (or WIN95) activating the audio card with the MS-DOS device driver, then you have to <ctrl>-<alt>-<del> and boot Linux. diff --git a/Documentation/sound/oss/README.OSS b/Documentation/sound/oss/README.OSS index c615debbf08d..4be259428a1c 100644 --- a/Documentation/sound/oss/README.OSS +++ b/Documentation/sound/oss/README.OSS @@ -1352,7 +1352,7 @@ OSS-mixer. The PCM20 contains a radio tuner, which is also controlled by ACI. This radio tuner is supported by the ACI driver together with the miropcm20.o module. Also the 7-band equalizer is integrated -(limited by the OSS-design). Developement has started and maybe +(limited by the OSS-design). Development has started and maybe finished for the RDS decoder on this card, too. You will be able to read RadioText, the Programme Service name, Programme TYpe and others. Even the v4l radio module benefits from it with a refined diff --git a/Documentation/sound/oss/README.ymfsb b/Documentation/sound/oss/README.ymfsb index af8a7d3a4e8e..b6b77906b58d 100644 --- a/Documentation/sound/oss/README.ymfsb +++ b/Documentation/sound/oss/README.ymfsb @@ -5,7 +5,7 @@ FIRST OF ALL ============ This code references YAMAHA's sample codes and data sheets. - I respect and thank for all people they made open the informations + I respect and thank for all people they made open the information about YMF7xx cards. And this codes heavily based on Jeff Garzik <jgarzik@pobox.com>'s diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx index 6bb916d57c95..493dada57372 100644 --- a/Documentation/spi/pxa2xx +++ b/Documentation/spi/pxa2xx @@ -19,7 +19,7 @@ Declaring PXA2xx Master Controllers ----------------------------------- Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a "platform device". The master configuration is passed to the driver via a table -found in arch/arm/mach-pxa/include/mach/pxa2xx_spi.h: +found in include/linux/spi/pxa2xx_spi.h: struct pxa2xx_spi_master { enum pxa_ssp_type ssp_type; @@ -94,7 +94,7 @@ using the "spi_board_info" structure found in "linux/spi/spi.h". See Each slave device attached to the PXA must provide slave specific configuration information via the structure "pxa2xx_spi_chip" found in -"arch/arm/mach-pxa/include/mach/pxa2xx_spi.h". The pxa2xx_spi master controller driver +"include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver will uses the configuration whenever the driver communicates with the slave device. All fields are optional. @@ -143,7 +143,7 @@ configured to use SSPFRM instead. NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the chipselect is dropped after each spi_transfer. Most devices need chip select asserted around the complete message. Use SSPFRM as a GPIO (through cs_control) -to accomodate these chips. +to accommodate these chips. NSSP SLAVE SAMPLE diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp index 34a9cfd746bd..463f6d01fa15 100644 --- a/Documentation/spi/spi-lm70llp +++ b/Documentation/spi/spi-lm70llp @@ -46,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows: Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin is connected to both pin D7 (as Master Out) and Select (as Master In) -using an arrangment that lets either the parport or the LM70 pull the +using an arrangement that lets either the parport or the LM70 pull the pin low. This can't be shared with true SPI devices, but other 3-wire devices might share the same SI/SO pin. diff --git a/Documentation/spinlocks.txt b/Documentation/spinlocks.txt index 178c831b907d..2e3c64b1a6a5 100644 --- a/Documentation/spinlocks.txt +++ b/Documentation/spinlocks.txt @@ -86,7 +86,7 @@ to change the variables it has to get an exclusive write lock. The routines look the same as above: - rwlock_t xxx_lock = RW_LOCK_UNLOCKED; + rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock); unsigned long flags; @@ -196,25 +196,3 @@ appropriate: For static initialization, use DEFINE_SPINLOCK() / DEFINE_RWLOCK() or __SPIN_LOCK_UNLOCKED() / __RW_LOCK_UNLOCKED() as appropriate. - -SPIN_LOCK_UNLOCKED and RW_LOCK_UNLOCKED are deprecated. These interfere -with lockdep state tracking. - -Most of the time, you can simply turn: - static spinlock_t xxx_lock = SPIN_LOCK_UNLOCKED; -into: - static DEFINE_SPINLOCK(xxx_lock); - -Static structure member variables go from: - - struct foo bar { - .lock = SPIN_LOCK_UNLOCKED; - }; - -to: - - struct foo bar { - .lock = __SPIN_LOCK_UNLOCKED(bar.lock); - }; - -Declaration of static rw_locks undergo a similar transformation. diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt index 847b342b7b20..db3be892afb2 100644 --- a/Documentation/stable_api_nonsense.txt +++ b/Documentation/stable_api_nonsense.txt @@ -122,7 +122,7 @@ operating system to suffer. In both of these instances, all developers agreed that these were important changes that needed to be made, and they were made, with -relatively little pain. If Linux had to ensure that it preserve a +relatively little pain. If Linux had to ensure that it will preserve a stable source interface, a new interface would have been created, and the older, broken one would have had to be maintained over time, leading to extra work for the USB developers. Since all Linux USB developers do diff --git a/Documentation/sysctl/00-INDEX b/Documentation/sysctl/00-INDEX index 1286f455992f..8cf5d493fd03 100644 --- a/Documentation/sysctl/00-INDEX +++ b/Documentation/sysctl/00-INDEX @@ -4,8 +4,6 @@ README - general information about /proc/sys/ sysctl files. abi.txt - documentation for /proc/sys/abi/*. -ctl_unnumbered.txt - - explanation of why one should not add new binary sysctl numbers. fs.txt - documentation for /proc/sys/fs/*. kernel.txt diff --git a/Documentation/sysctl/fs.txt b/Documentation/sysctl/fs.txt index 62682500878a..4af0614147ef 100644 --- a/Documentation/sysctl/fs.txt +++ b/Documentation/sysctl/fs.txt @@ -88,20 +88,19 @@ you might want to raise the limit. file-max & file-nr: -The kernel allocates file handles dynamically, but as yet it -doesn't free them again. - The value in file-max denotes the maximum number of file- handles that the Linux kernel will allocate. When you get lots of error messages about running out of file handles, you might want to increase this limit. -Historically, the three values in file-nr denoted the number of -allocated file handles, the number of allocated but unused file -handles, and the maximum number of file handles. Linux 2.6 always -reports 0 as the number of free file handles -- this is not an -error, it just means that the number of allocated file handles -exactly matches the number of used file handles. +Historically,the kernel was able to allocate file handles +dynamically, but not to free them again. The three values in +file-nr denote the number of allocated file handles, the number +of allocated but unused file handles, and the maximum number of +file handles. Linux 2.6 always reports 0 as the number of free +file handles -- this is not an error, it just means that the +number of allocated file handles exactly matches the number of +used file handles. Attempts to allocate more file descriptors than file-max are reported with printk, look for "VFS: file-max limit <number> diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 3894eaa23486..36f007514db3 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -28,11 +28,13 @@ show up in /proc/sys/kernel: - core_uses_pid - ctrl-alt-del - dentry-state +- dmesg_restrict - domainname - hostname - hotplug - java-appletviewer [ binfmt_java, obsolete ] - java-interpreter [ binfmt_java, obsolete ] +- kptr_restrict - kstack_depth_to_print [ X86 only ] - l2cr [ PPC only ] - modprobe ==> Documentation/debugging-modules.txt @@ -213,6 +215,19 @@ to decide what to do with it. ============================================================== +dmesg_restrict: + +This toggle indicates whether unprivileged users are prevented from using +dmesg(8) to view messages from the kernel's log buffer. When +dmesg_restrict is set to (0) there are no restrictions. When +dmesg_restrict is set set to (1), users must have CAP_SYSLOG to use +dmesg(8). + +The kernel config option CONFIG_SECURITY_DMESG_RESTRICT sets the default +value of dmesg_restrict. + +============================================================== + domainname & hostname: These files can be used to set the NIS/YP domainname and the @@ -247,6 +262,19 @@ This flag controls the L2 cache of G3 processor boards. If ============================================================== +kptr_restrict: + +This toggle indicates whether restrictions are placed on +exposing kernel addresses via /proc and other interfaces. When +kptr_restrict is set to (0), there are no restrictions. When +kptr_restrict is set to (1), the default, kernel pointers +printed using the %pK format specifier will be replaced with 0's +unless the user has CAP_SYSLOG. When kptr_restrict is set to +(2), kernel pointers printed using %pK will be replaced with 0's +regardless of privileges. + +============================================================== + kstack_depth_to_print: (X86 only) Controls the number of words to print when dumping the raw @@ -339,7 +367,7 @@ the different loglevels. - console_loglevel: messages with a higher priority than this will be printed to the console -- default_message_level: messages without an explicit priority +- default_message_loglevel: messages without an explicit priority will be printed with this priority - minimum_console_loglevel: minimum (highest) value to which console_loglevel can be set diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index b606c2c4dd37..96f0ee825bed 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 @@ -477,10 +481,10 @@ the DMA zone. Type(A) is called as "Node" order. Type (B) is "Zone" order. "Node order" orders the zonelists by node, then by zone within each node. -Specify "[Nn]ode" for zone order +Specify "[Nn]ode" for node order "Zone Order" orders the zonelists by zone type, then by node within each -zone. Specify "[Zz]one"for zode order. +zone. Specify "[Zz]one" for zone order. Specify "[Dd]efault" to request automatic configuration. Autoconfiguration will select "node" order in following case. diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt index 5c17196c8fe9..312e3754e8c5 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/target/tcm_mod_builder.py b/Documentation/target/tcm_mod_builder.py new file mode 100755 index 000000000000..7ef9b843d529 --- /dev/null +++ b/Documentation/target/tcm_mod_builder.py @@ -0,0 +1,1094 @@ +#!/usr/bin/python +# The TCM v4 multi-protocol fabric module generation script for drivers/target/$NEW_MOD +# +# Copyright (c) 2010 Rising Tide Systems +# Copyright (c) 2010 Linux-iSCSI.org +# +# Author: nab@kernel.org +# +import os, sys +import subprocess as sub +import string +import re +import optparse + +tcm_dir = "" + +fabric_ops = [] +fabric_mod_dir = "" +fabric_mod_port = "" +fabric_mod_init_port = "" + +def tcm_mod_err(msg): + print msg + sys.exit(1) + +def tcm_mod_create_module_subdir(fabric_mod_dir_var): + + if os.path.isdir(fabric_mod_dir_var) == True: + return 1 + + print "Creating fabric_mod_dir: " + fabric_mod_dir_var + ret = os.mkdir(fabric_mod_dir_var) + if ret: + tcm_mod_err("Unable to mkdir " + fabric_mod_dir_var) + + return + +def tcm_mod_build_FC_include(fabric_mod_dir_var, fabric_mod_name): + global fabric_mod_port + global fabric_mod_init_port + buf = "" + + f = fabric_mod_dir_var + "/" + fabric_mod_name + "_base.h" + print "Writing file: " + f + + p = open(f, 'w'); + if not p: + tcm_mod_err("Unable to open file: " + f) + + buf = "#define " + fabric_mod_name.upper() + "_VERSION \"v0.1\"\n" + buf += "#define " + fabric_mod_name.upper() + "_NAMELEN 32\n" + buf += "\n" + buf += "struct " + fabric_mod_name + "_nacl {\n" + buf += " /* Binary World Wide unique Port Name for FC Initiator Nport */\n" + buf += " u64 nport_wwpn;\n" + buf += " /* ASCII formatted WWPN for FC Initiator Nport */\n" + buf += " char nport_name[" + fabric_mod_name.upper() + "_NAMELEN];\n" + buf += " /* Returned by " + fabric_mod_name + "_make_nodeacl() */\n" + buf += " struct se_node_acl se_node_acl;\n" + buf += "};\n" + buf += "\n" + buf += "struct " + fabric_mod_name + "_tpg {\n" + buf += " /* FC lport target portal group tag for TCM */\n" + buf += " u16 lport_tpgt;\n" + buf += " /* Pointer back to " + fabric_mod_name + "_lport */\n" + buf += " struct " + fabric_mod_name + "_lport *lport;\n" + buf += " /* Returned by " + fabric_mod_name + "_make_tpg() */\n" + buf += " struct se_portal_group se_tpg;\n" + buf += "};\n" + buf += "\n" + buf += "struct " + fabric_mod_name + "_lport {\n" + buf += " /* SCSI protocol the lport is providing */\n" + buf += " u8 lport_proto_id;\n" + buf += " /* Binary World Wide unique Port Name for FC Target Lport */\n" + buf += " u64 lport_wwpn;\n" + buf += " /* ASCII formatted WWPN for FC Target Lport */\n" + buf += " char lport_name[" + fabric_mod_name.upper() + "_NAMELEN];\n" + buf += " /* Returned by " + fabric_mod_name + "_make_lport() */\n" + buf += " struct se_wwn lport_wwn;\n" + buf += "};\n" + + ret = p.write(buf) + if ret: + tcm_mod_err("Unable to write f: " + f) + + p.close() + + fabric_mod_port = "lport" + fabric_mod_init_port = "nport" + + return + +def tcm_mod_build_SAS_include(fabric_mod_dir_var, fabric_mod_name): + global fabric_mod_port + global fabric_mod_init_port + buf = "" + + f = fabric_mod_dir_var + "/" + fabric_mod_name + "_base.h" + print "Writing file: " + f + + p = open(f, 'w'); + if not p: + tcm_mod_err("Unable to open file: " + f) + + buf = "#define " + fabric_mod_name.upper() + "_VERSION \"v0.1\"\n" + buf += "#define " + fabric_mod_name.upper() + "_NAMELEN 32\n" + buf += "\n" + buf += "struct " + fabric_mod_name + "_nacl {\n" + buf += " /* Binary World Wide unique Port Name for SAS Initiator port */\n" + buf += " u64 iport_wwpn;\n" + buf += " /* ASCII formatted WWPN for Sas Initiator port */\n" + buf += " char iport_name[" + fabric_mod_name.upper() + "_NAMELEN];\n" + buf += " /* Returned by " + fabric_mod_name + "_make_nodeacl() */\n" + buf += " struct se_node_acl se_node_acl;\n" + buf += "};\n\n" + buf += "struct " + fabric_mod_name + "_tpg {\n" + buf += " /* SAS port target portal group tag for TCM */\n" + buf += " u16 tport_tpgt;\n" + buf += " /* Pointer back to " + fabric_mod_name + "_tport */\n" + buf += " struct " + fabric_mod_name + "_tport *tport;\n" + buf += " /* Returned by " + fabric_mod_name + "_make_tpg() */\n" + buf += " struct se_portal_group se_tpg;\n" + buf += "};\n\n" + buf += "struct " + fabric_mod_name + "_tport {\n" + buf += " /* SCSI protocol the tport is providing */\n" + buf += " u8 tport_proto_id;\n" + buf += " /* Binary World Wide unique Port Name for SAS Target port */\n" + buf += " u64 tport_wwpn;\n" + buf += " /* ASCII formatted WWPN for SAS Target port */\n" + buf += " char tport_name[" + fabric_mod_name.upper() + "_NAMELEN];\n" + buf += " /* Returned by " + fabric_mod_name + "_make_tport() */\n" + buf += " struct se_wwn tport_wwn;\n" + buf += "};\n" + + ret = p.write(buf) + if ret: + tcm_mod_err("Unable to write f: " + f) + + p.close() + + fabric_mod_port = "tport" + fabric_mod_init_port = "iport" + + return + +def tcm_mod_build_iSCSI_include(fabric_mod_dir_var, fabric_mod_name): + global fabric_mod_port + global fabric_mod_init_port + buf = "" + + f = fabric_mod_dir_var + "/" + fabric_mod_name + "_base.h" + print "Writing file: " + f + + p = open(f, 'w'); + if not p: + tcm_mod_err("Unable to open file: " + f) + + buf = "#define " + fabric_mod_name.upper() + "_VERSION \"v0.1\"\n" + buf += "#define " + fabric_mod_name.upper() + "_NAMELEN 32\n" + buf += "\n" + buf += "struct " + fabric_mod_name + "_nacl {\n" + buf += " /* ASCII formatted InitiatorName */\n" + buf += " char iport_name[" + fabric_mod_name.upper() + "_NAMELEN];\n" + buf += " /* Returned by " + fabric_mod_name + "_make_nodeacl() */\n" + buf += " struct se_node_acl se_node_acl;\n" + buf += "};\n\n" + buf += "struct " + fabric_mod_name + "_tpg {\n" + buf += " /* iSCSI target portal group tag for TCM */\n" + buf += " u16 tport_tpgt;\n" + buf += " /* Pointer back to " + fabric_mod_name + "_tport */\n" + buf += " struct " + fabric_mod_name + "_tport *tport;\n" + buf += " /* Returned by " + fabric_mod_name + "_make_tpg() */\n" + buf += " struct se_portal_group se_tpg;\n" + buf += "};\n\n" + buf += "struct " + fabric_mod_name + "_tport {\n" + buf += " /* SCSI protocol the tport is providing */\n" + buf += " u8 tport_proto_id;\n" + buf += " /* ASCII formatted TargetName for IQN */\n" + buf += " char tport_name[" + fabric_mod_name.upper() + "_NAMELEN];\n" + buf += " /* Returned by " + fabric_mod_name + "_make_tport() */\n" + buf += " struct se_wwn tport_wwn;\n" + buf += "};\n" + + ret = p.write(buf) + if ret: + tcm_mod_err("Unable to write f: " + f) + + p.close() + + fabric_mod_port = "tport" + fabric_mod_init_port = "iport" + + return + +def tcm_mod_build_base_includes(proto_ident, fabric_mod_dir_val, fabric_mod_name): + + if proto_ident == "FC": + tcm_mod_build_FC_include(fabric_mod_dir_val, fabric_mod_name) + elif proto_ident == "SAS": + tcm_mod_build_SAS_include(fabric_mod_dir_val, fabric_mod_name) + elif proto_ident == "iSCSI": + tcm_mod_build_iSCSI_include(fabric_mod_dir_val, fabric_mod_name) + else: + print "Unsupported proto_ident: " + proto_ident + sys.exit(1) + + return + +def tcm_mod_build_configfs(proto_ident, fabric_mod_dir_var, fabric_mod_name): + buf = "" + + f = fabric_mod_dir_var + "/" + fabric_mod_name + "_configfs.c" + print "Writing file: " + f + + p = open(f, 'w'); + if not p: + tcm_mod_err("Unable to open file: " + f) + + buf = "#include <linux/module.h>\n" + buf += "#include <linux/moduleparam.h>\n" + buf += "#include <linux/version.h>\n" + buf += "#include <generated/utsrelease.h>\n" + buf += "#include <linux/utsname.h>\n" + buf += "#include <linux/init.h>\n" + buf += "#include <linux/slab.h>\n" + buf += "#include <linux/kthread.h>\n" + buf += "#include <linux/types.h>\n" + buf += "#include <linux/string.h>\n" + buf += "#include <linux/configfs.h>\n" + buf += "#include <linux/ctype.h>\n" + buf += "#include <asm/unaligned.h>\n\n" + buf += "#include <target/target_core_base.h>\n" + buf += "#include <target/target_core_transport.h>\n" + buf += "#include <target/target_core_fabric_ops.h>\n" + buf += "#include <target/target_core_fabric_configfs.h>\n" + buf += "#include <target/target_core_fabric_lib.h>\n" + buf += "#include <target/target_core_device.h>\n" + buf += "#include <target/target_core_tpg.h>\n" + buf += "#include <target/target_core_configfs.h>\n" + buf += "#include <target/target_core_base.h>\n" + buf += "#include <target/configfs_macros.h>\n\n" + buf += "#include \"" + fabric_mod_name + "_base.h\"\n" + buf += "#include \"" + fabric_mod_name + "_fabric.h\"\n\n" + + buf += "/* Local pointer to allocated TCM configfs fabric module */\n" + buf += "struct target_fabric_configfs *" + fabric_mod_name + "_fabric_configfs;\n\n" + + buf += "static struct se_node_acl *" + fabric_mod_name + "_make_nodeacl(\n" + buf += " struct se_portal_group *se_tpg,\n" + buf += " struct config_group *group,\n" + buf += " const char *name)\n" + buf += "{\n" + buf += " struct se_node_acl *se_nacl, *se_nacl_new;\n" + buf += " struct " + fabric_mod_name + "_nacl *nacl;\n" + + if proto_ident == "FC" or proto_ident == "SAS": + buf += " u64 wwpn = 0;\n" + + buf += " u32 nexus_depth;\n\n" + buf += " /* " + fabric_mod_name + "_parse_wwn(name, &wwpn, 1) < 0)\n" + buf += " return ERR_PTR(-EINVAL); */\n" + buf += " se_nacl_new = " + fabric_mod_name + "_alloc_fabric_acl(se_tpg);\n" + buf += " if (!(se_nacl_new))\n" + buf += " return ERR_PTR(-ENOMEM);\n" + buf += "//#warning FIXME: Hardcoded nexus depth in " + fabric_mod_name + "_make_nodeacl()\n" + buf += " nexus_depth = 1;\n" + buf += " /*\n" + buf += " * se_nacl_new may be released by core_tpg_add_initiator_node_acl()\n" + buf += " * when converting a NodeACL from demo mode -> explict\n" + buf += " */\n" + buf += " se_nacl = core_tpg_add_initiator_node_acl(se_tpg, se_nacl_new,\n" + buf += " name, nexus_depth);\n" + buf += " if (IS_ERR(se_nacl)) {\n" + buf += " " + fabric_mod_name + "_release_fabric_acl(se_tpg, se_nacl_new);\n" + buf += " return se_nacl;\n" + buf += " }\n" + buf += " /*\n" + buf += " * Locate our struct " + fabric_mod_name + "_nacl and set the FC Nport WWPN\n" + buf += " */\n" + buf += " nacl = container_of(se_nacl, struct " + fabric_mod_name + "_nacl, se_node_acl);\n" + + if proto_ident == "FC" or proto_ident == "SAS": + buf += " nacl->" + fabric_mod_init_port + "_wwpn = wwpn;\n" + + buf += " /* " + fabric_mod_name + "_format_wwn(&nacl->" + fabric_mod_init_port + "_name[0], " + fabric_mod_name.upper() + "_NAMELEN, wwpn); */\n\n" + buf += " return se_nacl;\n" + buf += "}\n\n" + buf += "static void " + fabric_mod_name + "_drop_nodeacl(struct se_node_acl *se_acl)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_nacl *nacl = container_of(se_acl,\n" + buf += " struct " + fabric_mod_name + "_nacl, se_node_acl);\n" + buf += " core_tpg_del_initiator_node_acl(se_acl->se_tpg, se_acl, 1);\n" + buf += " kfree(nacl);\n" + buf += "}\n\n" + + buf += "static struct se_portal_group *" + fabric_mod_name + "_make_tpg(\n" + buf += " struct se_wwn *wwn,\n" + buf += " struct config_group *group,\n" + buf += " const char *name)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + "*" + fabric_mod_port + " = container_of(wwn,\n" + buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + ", " + fabric_mod_port + "_wwn);\n\n" + buf += " struct " + fabric_mod_name + "_tpg *tpg;\n" + buf += " unsigned long tpgt;\n" + buf += " int ret;\n\n" + buf += " if (strstr(name, \"tpgt_\") != name)\n" + buf += " return ERR_PTR(-EINVAL);\n" + buf += " if (strict_strtoul(name + 5, 10, &tpgt) || tpgt > UINT_MAX)\n" + buf += " return ERR_PTR(-EINVAL);\n\n" + buf += " tpg = kzalloc(sizeof(struct " + fabric_mod_name + "_tpg), GFP_KERNEL);\n" + buf += " if (!(tpg)) {\n" + buf += " printk(KERN_ERR \"Unable to allocate struct " + fabric_mod_name + "_tpg\");\n" + buf += " return ERR_PTR(-ENOMEM);\n" + buf += " }\n" + buf += " tpg->" + fabric_mod_port + " = " + fabric_mod_port + ";\n" + buf += " tpg->" + fabric_mod_port + "_tpgt = tpgt;\n\n" + buf += " ret = core_tpg_register(&" + fabric_mod_name + "_fabric_configfs->tf_ops, wwn,\n" + buf += " &tpg->se_tpg, (void *)tpg,\n" + buf += " TRANSPORT_TPG_TYPE_NORMAL);\n" + buf += " if (ret < 0) {\n" + buf += " kfree(tpg);\n" + buf += " return NULL;\n" + buf += " }\n" + buf += " return &tpg->se_tpg;\n" + buf += "}\n\n" + buf += "static void " + fabric_mod_name + "_drop_tpg(struct se_portal_group *se_tpg)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_tpg *tpg = container_of(se_tpg,\n" + buf += " struct " + fabric_mod_name + "_tpg, se_tpg);\n\n" + buf += " core_tpg_deregister(se_tpg);\n" + buf += " kfree(tpg);\n" + buf += "}\n\n" + + buf += "static struct se_wwn *" + fabric_mod_name + "_make_" + fabric_mod_port + "(\n" + buf += " struct target_fabric_configfs *tf,\n" + buf += " struct config_group *group,\n" + buf += " const char *name)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + " *" + fabric_mod_port + ";\n" + + if proto_ident == "FC" or proto_ident == "SAS": + buf += " u64 wwpn = 0;\n\n" + + buf += " /* if (" + fabric_mod_name + "_parse_wwn(name, &wwpn, 1) < 0)\n" + buf += " return ERR_PTR(-EINVAL); */\n\n" + buf += " " + fabric_mod_port + " = kzalloc(sizeof(struct " + fabric_mod_name + "_" + fabric_mod_port + "), GFP_KERNEL);\n" + buf += " if (!(" + fabric_mod_port + ")) {\n" + buf += " printk(KERN_ERR \"Unable to allocate struct " + fabric_mod_name + "_" + fabric_mod_port + "\");\n" + buf += " return ERR_PTR(-ENOMEM);\n" + buf += " }\n" + + if proto_ident == "FC" or proto_ident == "SAS": + buf += " " + fabric_mod_port + "->" + fabric_mod_port + "_wwpn = wwpn;\n" + + buf += " /* " + fabric_mod_name + "_format_wwn(&" + fabric_mod_port + "->" + fabric_mod_port + "_name[0], " + fabric_mod_name.upper() + "__NAMELEN, wwpn); */\n\n" + buf += " return &" + fabric_mod_port + "->" + fabric_mod_port + "_wwn;\n" + buf += "}\n\n" + buf += "static void " + fabric_mod_name + "_drop_" + fabric_mod_port + "(struct se_wwn *wwn)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + " *" + fabric_mod_port + " = container_of(wwn,\n" + buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + ", " + fabric_mod_port + "_wwn);\n" + buf += " kfree(" + fabric_mod_port + ");\n" + buf += "}\n\n" + buf += "static ssize_t " + fabric_mod_name + "_wwn_show_attr_version(\n" + buf += " struct target_fabric_configfs *tf,\n" + buf += " char *page)\n" + buf += "{\n" + buf += " return sprintf(page, \"" + fabric_mod_name.upper() + " fabric module %s on %s/%s\"\n" + buf += " \"on \"UTS_RELEASE\"\\n\", " + fabric_mod_name.upper() + "_VERSION, utsname()->sysname,\n" + buf += " utsname()->machine);\n" + buf += "}\n\n" + buf += "TF_WWN_ATTR_RO(" + fabric_mod_name + ", version);\n\n" + buf += "static struct configfs_attribute *" + fabric_mod_name + "_wwn_attrs[] = {\n" + buf += " &" + fabric_mod_name + "_wwn_version.attr,\n" + buf += " NULL,\n" + buf += "};\n\n" + + buf += "static struct target_core_fabric_ops " + fabric_mod_name + "_ops = {\n" + buf += " .get_fabric_name = " + fabric_mod_name + "_get_fabric_name,\n" + buf += " .get_fabric_proto_ident = " + fabric_mod_name + "_get_fabric_proto_ident,\n" + buf += " .tpg_get_wwn = " + fabric_mod_name + "_get_fabric_wwn,\n" + buf += " .tpg_get_tag = " + fabric_mod_name + "_get_tag,\n" + buf += " .tpg_get_default_depth = " + fabric_mod_name + "_get_default_depth,\n" + buf += " .tpg_get_pr_transport_id = " + fabric_mod_name + "_get_pr_transport_id,\n" + buf += " .tpg_get_pr_transport_id_len = " + fabric_mod_name + "_get_pr_transport_id_len,\n" + buf += " .tpg_parse_pr_out_transport_id = " + fabric_mod_name + "_parse_pr_out_transport_id,\n" + buf += " .tpg_check_demo_mode = " + fabric_mod_name + "_check_false,\n" + buf += " .tpg_check_demo_mode_cache = " + fabric_mod_name + "_check_true,\n" + buf += " .tpg_check_demo_mode_write_protect = " + fabric_mod_name + "_check_true,\n" + buf += " .tpg_check_prod_mode_write_protect = " + fabric_mod_name + "_check_false,\n" + buf += " .tpg_alloc_fabric_acl = " + fabric_mod_name + "_alloc_fabric_acl,\n" + buf += " .tpg_release_fabric_acl = " + fabric_mod_name + "_release_fabric_acl,\n" + buf += " .tpg_get_inst_index = " + fabric_mod_name + "_tpg_get_inst_index,\n" + buf += " .release_cmd_to_pool = " + fabric_mod_name + "_release_cmd,\n" + buf += " .release_cmd_direct = " + fabric_mod_name + "_release_cmd,\n" + buf += " .shutdown_session = " + fabric_mod_name + "_shutdown_session,\n" + buf += " .close_session = " + fabric_mod_name + "_close_session,\n" + buf += " .stop_session = " + fabric_mod_name + "_stop_session,\n" + buf += " .fall_back_to_erl0 = " + fabric_mod_name + "_reset_nexus,\n" + buf += " .sess_logged_in = " + fabric_mod_name + "_sess_logged_in,\n" + buf += " .sess_get_index = " + fabric_mod_name + "_sess_get_index,\n" + buf += " .sess_get_initiator_sid = NULL,\n" + buf += " .write_pending = " + fabric_mod_name + "_write_pending,\n" + buf += " .write_pending_status = " + fabric_mod_name + "_write_pending_status,\n" + buf += " .set_default_node_attributes = " + fabric_mod_name + "_set_default_node_attrs,\n" + buf += " .get_task_tag = " + fabric_mod_name + "_get_task_tag,\n" + buf += " .get_cmd_state = " + fabric_mod_name + "_get_cmd_state,\n" + buf += " .new_cmd_failure = " + fabric_mod_name + "_new_cmd_failure,\n" + buf += " .queue_data_in = " + fabric_mod_name + "_queue_data_in,\n" + buf += " .queue_status = " + fabric_mod_name + "_queue_status,\n" + buf += " .queue_tm_rsp = " + fabric_mod_name + "_queue_tm_rsp,\n" + buf += " .get_fabric_sense_len = " + fabric_mod_name + "_get_fabric_sense_len,\n" + buf += " .set_fabric_sense_len = " + fabric_mod_name + "_set_fabric_sense_len,\n" + buf += " .is_state_remove = " + fabric_mod_name + "_is_state_remove,\n" + buf += " .pack_lun = " + fabric_mod_name + "_pack_lun,\n" + buf += " /*\n" + buf += " * Setup function pointers for generic logic in target_core_fabric_configfs.c\n" + buf += " */\n" + buf += " .fabric_make_wwn = " + fabric_mod_name + "_make_" + fabric_mod_port + ",\n" + buf += " .fabric_drop_wwn = " + fabric_mod_name + "_drop_" + fabric_mod_port + ",\n" + buf += " .fabric_make_tpg = " + fabric_mod_name + "_make_tpg,\n" + buf += " .fabric_drop_tpg = " + fabric_mod_name + "_drop_tpg,\n" + buf += " .fabric_post_link = NULL,\n" + buf += " .fabric_pre_unlink = NULL,\n" + buf += " .fabric_make_np = NULL,\n" + buf += " .fabric_drop_np = NULL,\n" + buf += " .fabric_make_nodeacl = " + fabric_mod_name + "_make_nodeacl,\n" + buf += " .fabric_drop_nodeacl = " + fabric_mod_name + "_drop_nodeacl,\n" + buf += "};\n\n" + + buf += "static int " + fabric_mod_name + "_register_configfs(void)\n" + buf += "{\n" + buf += " struct target_fabric_configfs *fabric;\n" + buf += " int ret;\n\n" + buf += " printk(KERN_INFO \"" + fabric_mod_name.upper() + " fabric module %s on %s/%s\"\n" + buf += " \" on \"UTS_RELEASE\"\\n\"," + fabric_mod_name.upper() + "_VERSION, utsname()->sysname,\n" + buf += " utsname()->machine);\n" + buf += " /*\n" + buf += " * Register the top level struct config_item_type with TCM core\n" + buf += " */\n" + buf += " fabric = target_fabric_configfs_init(THIS_MODULE, \"" + fabric_mod_name[4:] + "\");\n" + buf += " if (!(fabric)) {\n" + buf += " printk(KERN_ERR \"target_fabric_configfs_init() failed\\n\");\n" + buf += " return -ENOMEM;\n" + buf += " }\n" + buf += " /*\n" + buf += " * Setup fabric->tf_ops from our local " + fabric_mod_name + "_ops\n" + buf += " */\n" + buf += " fabric->tf_ops = " + fabric_mod_name + "_ops;\n" + buf += " /*\n" + buf += " * Setup default attribute lists for various fabric->tf_cit_tmpl\n" + buf += " */\n" + buf += " TF_CIT_TMPL(fabric)->tfc_wwn_cit.ct_attrs = " + fabric_mod_name + "_wwn_attrs;\n" + buf += " TF_CIT_TMPL(fabric)->tfc_tpg_base_cit.ct_attrs = NULL;\n" + buf += " TF_CIT_TMPL(fabric)->tfc_tpg_attrib_cit.ct_attrs = NULL;\n" + buf += " TF_CIT_TMPL(fabric)->tfc_tpg_param_cit.ct_attrs = NULL;\n" + buf += " TF_CIT_TMPL(fabric)->tfc_tpg_np_base_cit.ct_attrs = NULL;\n" + buf += " TF_CIT_TMPL(fabric)->tfc_tpg_nacl_base_cit.ct_attrs = NULL;\n" + buf += " TF_CIT_TMPL(fabric)->tfc_tpg_nacl_attrib_cit.ct_attrs = NULL;\n" + buf += " TF_CIT_TMPL(fabric)->tfc_tpg_nacl_auth_cit.ct_attrs = NULL;\n" + buf += " TF_CIT_TMPL(fabric)->tfc_tpg_nacl_param_cit.ct_attrs = NULL;\n" + buf += " /*\n" + buf += " * Register the fabric for use within TCM\n" + buf += " */\n" + buf += " ret = target_fabric_configfs_register(fabric);\n" + buf += " if (ret < 0) {\n" + buf += " printk(KERN_ERR \"target_fabric_configfs_register() failed\"\n" + buf += " \" for " + fabric_mod_name.upper() + "\\n\");\n" + buf += " return ret;\n" + buf += " }\n" + buf += " /*\n" + buf += " * Setup our local pointer to *fabric\n" + buf += " */\n" + buf += " " + fabric_mod_name + "_fabric_configfs = fabric;\n" + buf += " printk(KERN_INFO \"" + fabric_mod_name.upper() + "[0] - Set fabric -> " + fabric_mod_name + "_fabric_configfs\\n\");\n" + buf += " return 0;\n" + buf += "};\n\n" + buf += "static void " + fabric_mod_name + "_deregister_configfs(void)\n" + buf += "{\n" + buf += " if (!(" + fabric_mod_name + "_fabric_configfs))\n" + buf += " return;\n\n" + buf += " target_fabric_configfs_deregister(" + fabric_mod_name + "_fabric_configfs);\n" + buf += " " + fabric_mod_name + "_fabric_configfs = NULL;\n" + buf += " printk(KERN_INFO \"" + fabric_mod_name.upper() + "[0] - Cleared " + fabric_mod_name + "_fabric_configfs\\n\");\n" + buf += "};\n\n" + + buf += "static int __init " + fabric_mod_name + "_init(void)\n" + buf += "{\n" + buf += " int ret;\n\n" + buf += " ret = " + fabric_mod_name + "_register_configfs();\n" + buf += " if (ret < 0)\n" + buf += " return ret;\n\n" + buf += " return 0;\n" + buf += "};\n\n" + buf += "static void " + fabric_mod_name + "_exit(void)\n" + buf += "{\n" + buf += " " + fabric_mod_name + "_deregister_configfs();\n" + buf += "};\n\n" + + buf += "#ifdef MODULE\n" + buf += "MODULE_DESCRIPTION(\"" + fabric_mod_name.upper() + " series fabric driver\");\n" + buf += "MODULE_LICENSE(\"GPL\");\n" + buf += "module_init(" + fabric_mod_name + "_init);\n" + buf += "module_exit(" + fabric_mod_name + "_exit);\n" + buf += "#endif\n" + + ret = p.write(buf) + if ret: + tcm_mod_err("Unable to write f: " + f) + + p.close() + + return + +def tcm_mod_scan_fabric_ops(tcm_dir): + + fabric_ops_api = tcm_dir + "include/target/target_core_fabric_ops.h" + + print "Using tcm_mod_scan_fabric_ops: " + fabric_ops_api + process_fo = 0; + + p = open(fabric_ops_api, 'r') + + line = p.readline() + while line: + if process_fo == 0 and re.search('struct target_core_fabric_ops {', line): + line = p.readline() + continue + + if process_fo == 0: + process_fo = 1; + line = p.readline() + # Search for function pointer + if not re.search('\(\*', line): + continue + + fabric_ops.append(line.rstrip()) + continue + + line = p.readline() + # Search for function pointer + if not re.search('\(\*', line): + continue + + fabric_ops.append(line.rstrip()) + + p.close() + return + +def tcm_mod_dump_fabric_ops(proto_ident, fabric_mod_dir_var, fabric_mod_name): + buf = "" + bufi = "" + + f = fabric_mod_dir_var + "/" + fabric_mod_name + "_fabric.c" + print "Writing file: " + f + + p = open(f, 'w') + if not p: + tcm_mod_err("Unable to open file: " + f) + + fi = fabric_mod_dir_var + "/" + fabric_mod_name + "_fabric.h" + print "Writing file: " + fi + + pi = open(fi, 'w') + if not pi: + tcm_mod_err("Unable to open file: " + fi) + + buf = "#include <linux/slab.h>\n" + buf += "#include <linux/kthread.h>\n" + buf += "#include <linux/types.h>\n" + buf += "#include <linux/list.h>\n" + buf += "#include <linux/types.h>\n" + buf += "#include <linux/string.h>\n" + buf += "#include <linux/ctype.h>\n" + buf += "#include <asm/unaligned.h>\n" + buf += "#include <scsi/scsi.h>\n" + buf += "#include <scsi/scsi_host.h>\n" + buf += "#include <scsi/scsi_device.h>\n" + buf += "#include <scsi/scsi_cmnd.h>\n" + buf += "#include <scsi/libfc.h>\n\n" + buf += "#include <target/target_core_base.h>\n" + buf += "#include <target/target_core_transport.h>\n" + buf += "#include <target/target_core_fabric_ops.h>\n" + buf += "#include <target/target_core_fabric_lib.h>\n" + buf += "#include <target/target_core_device.h>\n" + buf += "#include <target/target_core_tpg.h>\n" + buf += "#include <target/target_core_configfs.h>\n\n" + buf += "#include \"" + fabric_mod_name + "_base.h\"\n" + buf += "#include \"" + fabric_mod_name + "_fabric.h\"\n\n" + + buf += "int " + fabric_mod_name + "_check_true(struct se_portal_group *se_tpg)\n" + buf += "{\n" + buf += " return 1;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_check_true(struct se_portal_group *);\n" + + buf += "int " + fabric_mod_name + "_check_false(struct se_portal_group *se_tpg)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_check_false(struct se_portal_group *);\n" + + total_fabric_ops = len(fabric_ops) + i = 0 + + while i < total_fabric_ops: + fo = fabric_ops[i] + i += 1 +# print "fabric_ops: " + fo + + if re.search('get_fabric_name', fo): + buf += "char *" + fabric_mod_name + "_get_fabric_name(void)\n" + buf += "{\n" + buf += " return \"" + fabric_mod_name[4:] + "\";\n" + buf += "}\n\n" + bufi += "char *" + fabric_mod_name + "_get_fabric_name(void);\n" + continue + + if re.search('get_fabric_proto_ident', fo): + buf += "u8 " + fabric_mod_name + "_get_fabric_proto_ident(struct se_portal_group *se_tpg)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_tpg *tpg = container_of(se_tpg,\n" + buf += " struct " + fabric_mod_name + "_tpg, se_tpg);\n" + buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + " *" + fabric_mod_port + " = tpg->" + fabric_mod_port + ";\n" + buf += " u8 proto_id;\n\n" + buf += " switch (" + fabric_mod_port + "->" + fabric_mod_port + "_proto_id) {\n" + if proto_ident == "FC": + buf += " case SCSI_PROTOCOL_FCP:\n" + buf += " default:\n" + buf += " proto_id = fc_get_fabric_proto_ident(se_tpg);\n" + buf += " break;\n" + elif proto_ident == "SAS": + buf += " case SCSI_PROTOCOL_SAS:\n" + buf += " default:\n" + buf += " proto_id = sas_get_fabric_proto_ident(se_tpg);\n" + buf += " break;\n" + elif proto_ident == "iSCSI": + buf += " case SCSI_PROTOCOL_ISCSI:\n" + buf += " default:\n" + buf += " proto_id = iscsi_get_fabric_proto_ident(se_tpg);\n" + buf += " break;\n" + + buf += " }\n\n" + buf += " return proto_id;\n" + buf += "}\n\n" + bufi += "u8 " + fabric_mod_name + "_get_fabric_proto_ident(struct se_portal_group *);\n" + + if re.search('get_wwn', fo): + buf += "char *" + fabric_mod_name + "_get_fabric_wwn(struct se_portal_group *se_tpg)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_tpg *tpg = container_of(se_tpg,\n" + buf += " struct " + fabric_mod_name + "_tpg, se_tpg);\n" + buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + " *" + fabric_mod_port + " = tpg->" + fabric_mod_port + ";\n\n" + buf += " return &" + fabric_mod_port + "->" + fabric_mod_port + "_name[0];\n" + buf += "}\n\n" + bufi += "char *" + fabric_mod_name + "_get_fabric_wwn(struct se_portal_group *);\n" + + if re.search('get_tag', fo): + buf += "u16 " + fabric_mod_name + "_get_tag(struct se_portal_group *se_tpg)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_tpg *tpg = container_of(se_tpg,\n" + buf += " struct " + fabric_mod_name + "_tpg, se_tpg);\n" + buf += " return tpg->" + fabric_mod_port + "_tpgt;\n" + buf += "}\n\n" + bufi += "u16 " + fabric_mod_name + "_get_tag(struct se_portal_group *);\n" + + if re.search('get_default_depth', fo): + buf += "u32 " + fabric_mod_name + "_get_default_depth(struct se_portal_group *se_tpg)\n" + buf += "{\n" + buf += " return 1;\n" + buf += "}\n\n" + bufi += "u32 " + fabric_mod_name + "_get_default_depth(struct se_portal_group *);\n" + + if re.search('get_pr_transport_id\)\(', fo): + buf += "u32 " + fabric_mod_name + "_get_pr_transport_id(\n" + buf += " struct se_portal_group *se_tpg,\n" + buf += " struct se_node_acl *se_nacl,\n" + buf += " struct t10_pr_registration *pr_reg,\n" + buf += " int *format_code,\n" + buf += " unsigned char *buf)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_tpg *tpg = container_of(se_tpg,\n" + buf += " struct " + fabric_mod_name + "_tpg, se_tpg);\n" + buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + " *" + fabric_mod_port + " = tpg->" + fabric_mod_port + ";\n" + buf += " int ret = 0;\n\n" + buf += " switch (" + fabric_mod_port + "->" + fabric_mod_port + "_proto_id) {\n" + if proto_ident == "FC": + buf += " case SCSI_PROTOCOL_FCP:\n" + buf += " default:\n" + buf += " ret = fc_get_pr_transport_id(se_tpg, se_nacl, pr_reg,\n" + buf += " format_code, buf);\n" + buf += " break;\n" + elif proto_ident == "SAS": + buf += " case SCSI_PROTOCOL_SAS:\n" + buf += " default:\n" + buf += " ret = sas_get_pr_transport_id(se_tpg, se_nacl, pr_reg,\n" + buf += " format_code, buf);\n" + buf += " break;\n" + elif proto_ident == "iSCSI": + buf += " case SCSI_PROTOCOL_ISCSI:\n" + buf += " default:\n" + buf += " ret = iscsi_get_pr_transport_id(se_tpg, se_nacl, pr_reg,\n" + buf += " format_code, buf);\n" + buf += " break;\n" + + buf += " }\n\n" + buf += " return ret;\n" + buf += "}\n\n" + bufi += "u32 " + fabric_mod_name + "_get_pr_transport_id(struct se_portal_group *,\n" + bufi += " struct se_node_acl *, struct t10_pr_registration *,\n" + bufi += " int *, unsigned char *);\n" + + if re.search('get_pr_transport_id_len\)\(', fo): + buf += "u32 " + fabric_mod_name + "_get_pr_transport_id_len(\n" + buf += " struct se_portal_group *se_tpg,\n" + buf += " struct se_node_acl *se_nacl,\n" + buf += " struct t10_pr_registration *pr_reg,\n" + buf += " int *format_code)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_tpg *tpg = container_of(se_tpg,\n" + buf += " struct " + fabric_mod_name + "_tpg, se_tpg);\n" + buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + " *" + fabric_mod_port + " = tpg->" + fabric_mod_port + ";\n" + buf += " int ret = 0;\n\n" + buf += " switch (" + fabric_mod_port + "->" + fabric_mod_port + "_proto_id) {\n" + if proto_ident == "FC": + buf += " case SCSI_PROTOCOL_FCP:\n" + buf += " default:\n" + buf += " ret = fc_get_pr_transport_id_len(se_tpg, se_nacl, pr_reg,\n" + buf += " format_code);\n" + buf += " break;\n" + elif proto_ident == "SAS": + buf += " case SCSI_PROTOCOL_SAS:\n" + buf += " default:\n" + buf += " ret = sas_get_pr_transport_id_len(se_tpg, se_nacl, pr_reg,\n" + buf += " format_code);\n" + buf += " break;\n" + elif proto_ident == "iSCSI": + buf += " case SCSI_PROTOCOL_ISCSI:\n" + buf += " default:\n" + buf += " ret = iscsi_get_pr_transport_id_len(se_tpg, se_nacl, pr_reg,\n" + buf += " format_code);\n" + buf += " break;\n" + + + buf += " }\n\n" + buf += " return ret;\n" + buf += "}\n\n" + bufi += "u32 " + fabric_mod_name + "_get_pr_transport_id_len(struct se_portal_group *,\n" + bufi += " struct se_node_acl *, struct t10_pr_registration *,\n" + bufi += " int *);\n" + + if re.search('parse_pr_out_transport_id\)\(', fo): + buf += "char *" + fabric_mod_name + "_parse_pr_out_transport_id(\n" + buf += " struct se_portal_group *se_tpg,\n" + buf += " const char *buf,\n" + buf += " u32 *out_tid_len,\n" + buf += " char **port_nexus_ptr)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_tpg *tpg = container_of(se_tpg,\n" + buf += " struct " + fabric_mod_name + "_tpg, se_tpg);\n" + buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + " *" + fabric_mod_port + " = tpg->" + fabric_mod_port + ";\n" + buf += " char *tid = NULL;\n\n" + buf += " switch (" + fabric_mod_port + "->" + fabric_mod_port + "_proto_id) {\n" + if proto_ident == "FC": + buf += " case SCSI_PROTOCOL_FCP:\n" + buf += " default:\n" + buf += " tid = fc_parse_pr_out_transport_id(se_tpg, buf, out_tid_len,\n" + buf += " port_nexus_ptr);\n" + elif proto_ident == "SAS": + buf += " case SCSI_PROTOCOL_SAS:\n" + buf += " default:\n" + buf += " tid = sas_parse_pr_out_transport_id(se_tpg, buf, out_tid_len,\n" + buf += " port_nexus_ptr);\n" + elif proto_ident == "iSCSI": + buf += " case SCSI_PROTOCOL_ISCSI:\n" + buf += " default:\n" + buf += " tid = iscsi_parse_pr_out_transport_id(se_tpg, buf, out_tid_len,\n" + buf += " port_nexus_ptr);\n" + + buf += " }\n\n" + buf += " return tid;\n" + buf += "}\n\n" + bufi += "char *" + fabric_mod_name + "_parse_pr_out_transport_id(struct se_portal_group *,\n" + bufi += " const char *, u32 *, char **);\n" + + if re.search('alloc_fabric_acl\)\(', fo): + buf += "struct se_node_acl *" + fabric_mod_name + "_alloc_fabric_acl(struct se_portal_group *se_tpg)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_nacl *nacl;\n\n" + buf += " nacl = kzalloc(sizeof(struct " + fabric_mod_name + "_nacl), GFP_KERNEL);\n" + buf += " if (!(nacl)) {\n" + buf += " printk(KERN_ERR \"Unable to alocate struct " + fabric_mod_name + "_nacl\\n\");\n" + buf += " return NULL;\n" + buf += " }\n\n" + buf += " return &nacl->se_node_acl;\n" + buf += "}\n\n" + bufi += "struct se_node_acl *" + fabric_mod_name + "_alloc_fabric_acl(struct se_portal_group *);\n" + + if re.search('release_fabric_acl\)\(', fo): + buf += "void " + fabric_mod_name + "_release_fabric_acl(\n" + buf += " struct se_portal_group *se_tpg,\n" + buf += " struct se_node_acl *se_nacl)\n" + buf += "{\n" + buf += " struct " + fabric_mod_name + "_nacl *nacl = container_of(se_nacl,\n" + buf += " struct " + fabric_mod_name + "_nacl, se_node_acl);\n" + buf += " kfree(nacl);\n" + buf += "}\n\n" + bufi += "void " + fabric_mod_name + "_release_fabric_acl(struct se_portal_group *,\n" + bufi += " struct se_node_acl *);\n" + + if re.search('tpg_get_inst_index\)\(', fo): + buf += "u32 " + fabric_mod_name + "_tpg_get_inst_index(struct se_portal_group *se_tpg)\n" + buf += "{\n" + buf += " return 1;\n" + buf += "}\n\n" + bufi += "u32 " + fabric_mod_name + "_tpg_get_inst_index(struct se_portal_group *);\n" + + if re.search('release_cmd_to_pool', fo): + buf += "void " + fabric_mod_name + "_release_cmd(struct se_cmd *se_cmd)\n" + buf += "{\n" + buf += " return;\n" + buf += "}\n\n" + bufi += "void " + fabric_mod_name + "_release_cmd(struct se_cmd *);\n" + + if re.search('shutdown_session\)\(', fo): + buf += "int " + fabric_mod_name + "_shutdown_session(struct se_session *se_sess)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_shutdown_session(struct se_session *);\n" + + if re.search('close_session\)\(', fo): + buf += "void " + fabric_mod_name + "_close_session(struct se_session *se_sess)\n" + buf += "{\n" + buf += " return;\n" + buf += "}\n\n" + bufi += "void " + fabric_mod_name + "_close_session(struct se_session *);\n" + + if re.search('stop_session\)\(', fo): + buf += "void " + fabric_mod_name + "_stop_session(struct se_session *se_sess, int sess_sleep , int conn_sleep)\n" + buf += "{\n" + buf += " return;\n" + buf += "}\n\n" + bufi += "void " + fabric_mod_name + "_stop_session(struct se_session *, int, int);\n" + + if re.search('fall_back_to_erl0\)\(', fo): + buf += "void " + fabric_mod_name + "_reset_nexus(struct se_session *se_sess)\n" + buf += "{\n" + buf += " return;\n" + buf += "}\n\n" + bufi += "void " + fabric_mod_name + "_reset_nexus(struct se_session *);\n" + + if re.search('sess_logged_in\)\(', fo): + buf += "int " + fabric_mod_name + "_sess_logged_in(struct se_session *se_sess)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_sess_logged_in(struct se_session *);\n" + + if re.search('sess_get_index\)\(', fo): + buf += "u32 " + fabric_mod_name + "_sess_get_index(struct se_session *se_sess)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "u32 " + fabric_mod_name + "_sess_get_index(struct se_session *);\n" + + if re.search('write_pending\)\(', fo): + buf += "int " + fabric_mod_name + "_write_pending(struct se_cmd *se_cmd)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_write_pending(struct se_cmd *);\n" + + if re.search('write_pending_status\)\(', fo): + buf += "int " + fabric_mod_name + "_write_pending_status(struct se_cmd *se_cmd)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_write_pending_status(struct se_cmd *);\n" + + if re.search('set_default_node_attributes\)\(', fo): + buf += "void " + fabric_mod_name + "_set_default_node_attrs(struct se_node_acl *nacl)\n" + buf += "{\n" + buf += " return;\n" + buf += "}\n\n" + bufi += "void " + fabric_mod_name + "_set_default_node_attrs(struct se_node_acl *);\n" + + if re.search('get_task_tag\)\(', fo): + buf += "u32 " + fabric_mod_name + "_get_task_tag(struct se_cmd *se_cmd)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "u32 " + fabric_mod_name + "_get_task_tag(struct se_cmd *);\n" + + if re.search('get_cmd_state\)\(', fo): + buf += "int " + fabric_mod_name + "_get_cmd_state(struct se_cmd *se_cmd)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_get_cmd_state(struct se_cmd *);\n" + + if re.search('new_cmd_failure\)\(', fo): + buf += "void " + fabric_mod_name + "_new_cmd_failure(struct se_cmd *se_cmd)\n" + buf += "{\n" + buf += " return;\n" + buf += "}\n\n" + bufi += "void " + fabric_mod_name + "_new_cmd_failure(struct se_cmd *);\n" + + if re.search('queue_data_in\)\(', fo): + buf += "int " + fabric_mod_name + "_queue_data_in(struct se_cmd *se_cmd)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_queue_data_in(struct se_cmd *);\n" + + if re.search('queue_status\)\(', fo): + buf += "int " + fabric_mod_name + "_queue_status(struct se_cmd *se_cmd)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_queue_status(struct se_cmd *);\n" + + if re.search('queue_tm_rsp\)\(', fo): + buf += "int " + fabric_mod_name + "_queue_tm_rsp(struct se_cmd *se_cmd)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_queue_tm_rsp(struct se_cmd *);\n" + + if re.search('get_fabric_sense_len\)\(', fo): + buf += "u16 " + fabric_mod_name + "_get_fabric_sense_len(void)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "u16 " + fabric_mod_name + "_get_fabric_sense_len(void);\n" + + if re.search('set_fabric_sense_len\)\(', fo): + buf += "u16 " + fabric_mod_name + "_set_fabric_sense_len(struct se_cmd *se_cmd, u32 sense_length)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "u16 " + fabric_mod_name + "_set_fabric_sense_len(struct se_cmd *, u32);\n" + + if re.search('is_state_remove\)\(', fo): + buf += "int " + fabric_mod_name + "_is_state_remove(struct se_cmd *se_cmd)\n" + buf += "{\n" + buf += " return 0;\n" + buf += "}\n\n" + bufi += "int " + fabric_mod_name + "_is_state_remove(struct se_cmd *);\n" + + if re.search('pack_lun\)\(', fo): + buf += "u64 " + fabric_mod_name + "_pack_lun(unsigned int lun)\n" + buf += "{\n" + buf += " WARN_ON(lun >= 256);\n" + buf += " /* Caller wants this byte-swapped */\n" + buf += " return cpu_to_le64((lun & 0xff) << 8);\n" + buf += "}\n\n" + bufi += "u64 " + fabric_mod_name + "_pack_lun(unsigned int);\n" + + + ret = p.write(buf) + if ret: + tcm_mod_err("Unable to write f: " + f) + + p.close() + + ret = pi.write(bufi) + if ret: + tcm_mod_err("Unable to write fi: " + fi) + + pi.close() + return + +def tcm_mod_build_kbuild(fabric_mod_dir_var, fabric_mod_name): + + buf = "" + f = fabric_mod_dir_var + "/Makefile" + print "Writing file: " + f + + p = open(f, 'w') + if not p: + tcm_mod_err("Unable to open file: " + f) + + buf += fabric_mod_name + "-objs := " + fabric_mod_name + "_fabric.o \\\n" + buf += " " + fabric_mod_name + "_configfs.o\n" + buf += "obj-$(CONFIG_" + fabric_mod_name.upper() + ") += " + fabric_mod_name + ".o\n" + + ret = p.write(buf) + if ret: + tcm_mod_err("Unable to write f: " + f) + + p.close() + return + +def tcm_mod_build_kconfig(fabric_mod_dir_var, fabric_mod_name): + + buf = "" + f = fabric_mod_dir_var + "/Kconfig" + print "Writing file: " + f + + p = open(f, 'w') + if not p: + tcm_mod_err("Unable to open file: " + f) + + buf = "config " + fabric_mod_name.upper() + "\n" + buf += " tristate \"" + fabric_mod_name.upper() + " fabric module\"\n" + buf += " depends on TARGET_CORE && CONFIGFS_FS\n" + buf += " default n\n" + buf += " ---help---\n" + buf += " Say Y here to enable the " + fabric_mod_name.upper() + " fabric module\n" + + ret = p.write(buf) + if ret: + tcm_mod_err("Unable to write f: " + f) + + p.close() + return + +def tcm_mod_add_kbuild(tcm_dir, fabric_mod_name): + buf = "obj-$(CONFIG_" + fabric_mod_name.upper() + ") += " + fabric_mod_name.lower() + "/\n" + kbuild = tcm_dir + "/drivers/target/Makefile" + + f = open(kbuild, 'a') + f.write(buf) + f.close() + return + +def tcm_mod_add_kconfig(tcm_dir, fabric_mod_name): + buf = "source \"drivers/target/" + fabric_mod_name.lower() + "/Kconfig\"\n" + kconfig = tcm_dir + "/drivers/target/Kconfig" + + f = open(kconfig, 'a') + f.write(buf) + f.close() + return + +def main(modname, proto_ident): +# proto_ident = "FC" +# proto_ident = "SAS" +# proto_ident = "iSCSI" + + tcm_dir = os.getcwd(); + tcm_dir += "/../../" + print "tcm_dir: " + tcm_dir + fabric_mod_name = modname + fabric_mod_dir = tcm_dir + "drivers/target/" + fabric_mod_name + print "Set fabric_mod_name: " + fabric_mod_name + print "Set fabric_mod_dir: " + fabric_mod_dir + print "Using proto_ident: " + proto_ident + + if proto_ident != "FC" and proto_ident != "SAS" and proto_ident != "iSCSI": + print "Unsupported proto_ident: " + proto_ident + sys.exit(1) + + ret = tcm_mod_create_module_subdir(fabric_mod_dir) + if ret: + print "tcm_mod_create_module_subdir() failed because module already exists!" + sys.exit(1) + + tcm_mod_build_base_includes(proto_ident, fabric_mod_dir, fabric_mod_name) + tcm_mod_scan_fabric_ops(tcm_dir) + tcm_mod_dump_fabric_ops(proto_ident, fabric_mod_dir, fabric_mod_name) + tcm_mod_build_configfs(proto_ident, fabric_mod_dir, fabric_mod_name) + tcm_mod_build_kbuild(fabric_mod_dir, fabric_mod_name) + tcm_mod_build_kconfig(fabric_mod_dir, fabric_mod_name) + + input = raw_input("Would you like to add " + fabric_mod_name + "to drivers/target/Makefile..? [yes,no]: ") + if input == "yes" or input == "y": + tcm_mod_add_kbuild(tcm_dir, fabric_mod_name) + + input = raw_input("Would you like to add " + fabric_mod_name + "to drivers/target/Kconfig..? [yes,no]: ") + if input == "yes" or input == "y": + tcm_mod_add_kconfig(tcm_dir, fabric_mod_name) + + return + +parser = optparse.OptionParser() +parser.add_option('-m', '--modulename', help='Module name', dest='modname', + action='store', nargs=1, type='string') +parser.add_option('-p', '--protoident', help='Protocol Ident', dest='protoident', + action='store', nargs=1, type='string') + +(opts, args) = parser.parse_args() + +mandatories = ['modname', 'protoident'] +for m in mandatories: + if not opts.__dict__[m]: + print "mandatory option is missing\n" + parser.print_help() + exit(-1) + +if __name__ == "__main__": + + main(str(opts.modname), opts.protoident) diff --git a/Documentation/target/tcm_mod_builder.txt b/Documentation/target/tcm_mod_builder.txt new file mode 100644 index 000000000000..84533d8e747f --- /dev/null +++ b/Documentation/target/tcm_mod_builder.txt @@ -0,0 +1,145 @@ +>>>>>>>>>> The TCM v4 fabric module script generator <<<<<<<<<< + +Greetings all, + +This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py +script to generate a brand new functional TCM v4 fabric .ko module of your very own, +that once built can be immediately be loaded to start access the new TCM/ConfigFS +fabric skeleton, by simply using: + + modprobe $TCM_NEW_MOD + mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD + +This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following + + *) Generate new API callers for drivers/target/target_core_fabric_configs.c logic + ->make_nodeacl(), ->drop_nodeacl(), ->make_tpg(), ->drop_tpg() + ->make_wwn(), ->drop_wwn(). These are created into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c + *) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module + using a skeleton struct target_core_fabric_ops API template. + *) Based on user defined T10 Proto_Ident for the new fabric module being built, + the TransportID / Initiator and Target WWPN related handlers for + SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c + using drivers/target/target_core_fabric_lib.c logic. + *) NOP API calls for all other Data I/O path and fabric dependent attribute logic + in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c + +tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m +$FABRIC_MOD_name' parameters, and actually running the script looks like: + +target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000 +tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../ +Set fabric_mod_name: tcm_nab5000 +Set fabric_mod_dir: +/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000 +Using proto_ident: iSCSI +Creating fabric_mod_dir: +/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000 +Writing file: +/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h +Using tcm_mod_scan_fabric_ops: +/mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h +Writing file: +/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c +Writing file: +/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h +Writing file: +/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c +Writing file: +/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild +Writing file: +/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig +Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes +Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes + +At the end of tcm_mod_builder.py. the script will ask to add the following +line to drivers/target/Kbuild: + + obj-$(CONFIG_TCM_NAB5000) += tcm_nab5000/ + +and the same for drivers/target/Kconfig: + + source "drivers/target/tcm_nab5000/Kconfig" + +*) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item: + + <M> TCM_NAB5000 fabric module + +*) Build using 'make modules', once completed you will have: + +target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/ +total 1348 +drwxr-xr-x 2 root root 4096 2010-10-05 03:23 . +drwxr-xr-x 9 root root 4096 2010-10-05 03:22 .. +-rw-r--r-- 1 root root 282 2010-10-05 03:22 Kbuild +-rw-r--r-- 1 root root 171 2010-10-05 03:22 Kconfig +-rw-r--r-- 1 root root 49 2010-10-05 03:23 modules.order +-rw-r--r-- 1 root root 738 2010-10-05 03:22 tcm_nab5000_base.h +-rw-r--r-- 1 root root 9096 2010-10-05 03:22 tcm_nab5000_configfs.c +-rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o +-rw-r--r-- 1 root root 40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd +-rw-r--r-- 1 root root 5414 2010-10-05 03:22 tcm_nab5000_fabric.c +-rw-r--r-- 1 root root 2016 2010-10-05 03:22 tcm_nab5000_fabric.h +-rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o +-rw-r--r-- 1 root root 40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd +-rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko +-rw-r--r-- 1 root root 265 2010-10-05 03:23 .tcm_nab5000.ko.cmd +-rw-r--r-- 1 root root 459 2010-10-05 03:23 tcm_nab5000.mod.c +-rw-r--r-- 1 root root 23896 2010-10-05 03:23 tcm_nab5000.mod.o +-rw-r--r-- 1 root root 22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd +-rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o +-rw-r--r-- 1 root root 211 2010-10-05 03:23 .tcm_nab5000.o.cmd + +*) Load the new module, create a lun_0 configfs group, and add new TCM Core + IBLOCK backstore symlink to port: + +target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko +target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0 +target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/ +target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port + +target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd - +target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/ +/sys/kernel/config/target/nab5000/ +|-- discovery_auth +|-- iqn.foo +| `-- tpgt_1 +| |-- acls +| |-- attrib +| |-- lun +| | `-- lun_0 +| | |-- alua_tg_pt_gp +| | |-- alua_tg_pt_offline +| | |-- alua_tg_pt_status +| | |-- alua_tg_pt_write_md +| | `-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0 +| |-- np +| `-- param +`-- version + +target:/mnt/sdb/lio-core-2.6.git# lsmod +Module Size Used by +tcm_nab5000 3935 4 +iscsi_target_mod 193211 0 +target_core_stgt 8090 0 +target_core_pscsi 11122 1 +target_core_file 9172 2 +target_core_iblock 9280 1 +target_core_mod 228575 31 +tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock +libfc 73681 0 +scsi_debug 56265 0 +scsi_tgt 8666 1 target_core_stgt +configfs 20644 2 target_core_mod + +---------------------------------------------------------------------- + +Future TODO items: + + *) Add more T10 proto_idents + *) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer + defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops + structure members. + +October 5th, 2010 +Nicholas A. Bellinger <nab@linux-iscsi.org> diff --git a/Documentation/telephony/ixj.txt b/Documentation/telephony/ixj.txt index 4fb314d51702..db94fb6c5678 100644 --- a/Documentation/telephony/ixj.txt +++ b/Documentation/telephony/ixj.txt @@ -51,7 +51,7 @@ be removed to protect the rights of others. Specifically, very old Internet PhoneJACK cards have non-standard G.723.1 codecs (due to the early nature of the DSPs in those days). The auto-conversion code to bring those cards into compliance with -todays standards is available as a binary only module to those people +today's standards is available as a binary only module to those people needing it. If you bought your card after 1997 or so, you are OK - it's only the very old cards that are affected. diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.txt index cb3d15bc1aeb..b61e46f449aa 100644 --- a/Documentation/thermal/sysfs-api.txt +++ b/Documentation/thermal/sysfs-api.txt @@ -278,3 +278,15 @@ method, the sys I/F structure will be built like this: |---name: acpitz |---temp1_input: 37000 |---temp1_crit: 100000 + +4. Event Notification + +The framework includes a simple notification mechanism, in the form of a +netlink event. Netlink socket initialization is done during the _init_ +of the framework. Drivers which intend to use the notification mechanism +just need to call generate_netlink_event() with two arguments viz +(originator, event). Typically the originator will be an integer assigned +to a thermal_zone_device when it registers itself with the framework. The +event will be one of:{THERMAL_AUX0, THERMAL_AUX1, THERMAL_CRITICAL, +THERMAL_DEV_FAULT}. Notification can be sent when the current temperature +crosses any of the configured thresholds. diff --git a/Documentation/timers/hpet_example.c b/Documentation/timers/hpet_example.c index 4bfafb7bc4c5..9a3e7012c190 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/timer_stats.txt b/Documentation/timers/timer_stats.txt index 9bd00fc2e823..8abd40b22b7f 100644 --- a/Documentation/timers/timer_stats.txt +++ b/Documentation/timers/timer_stats.txt @@ -19,7 +19,7 @@ Linux system over a sample period: - the pid of the task(process) which initialized the timer - the name of the process which initialized the timer -- the function where the timer was intialized +- the function where the timer was initialized - the callback function which is associated to the timer - the number of events (callbacks) diff --git a/Documentation/trace/events-power.txt b/Documentation/trace/events-power.txt new file mode 100644 index 000000000000..96d87b67fe37 --- /dev/null +++ b/Documentation/trace/events-power.txt @@ -0,0 +1,90 @@ + + Subsystem Trace Points: power + +The power tracing system captures events related to power transitions +within the kernel. Broadly speaking there are three major subheadings: + + o Power state switch which reports events related to suspend (S-states), + cpuidle (C-states) and cpufreq (P-states) + o System clock related changes + o Power domains related changes and transitions + +This document describes what each of the tracepoints is and why they +might be useful. + +Cf. include/trace/events/power.h for the events definitions. + +1. Power state switch events +============================ + +1.1 New trace API +----------------- + +A 'cpu' event class gathers the CPU-related events: cpuidle and +cpufreq. + +cpu_idle "state=%lu cpu_id=%lu" +cpu_frequency "state=%lu cpu_id=%lu" + +A suspend event is used to indicate the system going in and out of the +suspend mode: + +machine_suspend "state=%lu" + + +Note: the value of '-1' or '4294967295' for state means an exit from the current state, +i.e. trace_cpu_idle(4, smp_processor_id()) means that the system +enters the idle state 4, while trace_cpu_idle(PWR_EVENT_EXIT, smp_processor_id()) +means that the system exits the previous idle state. + +The event which has 'state=4294967295' in the trace is very important to the user +space tools which are using it to detect the end of the current state, and so to +correctly draw the states diagrams and to calculate accurate statistics etc. + +1.2 DEPRECATED trace API +------------------------ + +A new Kconfig option CONFIG_EVENT_POWER_TRACING_DEPRECATED with the default value of +'y' has been created. This allows the legacy trace power API to be used conjointly +with the new trace API. +The Kconfig option, the old trace API (in include/trace/events/power.h) and the +old trace points will disappear in a future release (namely 2.6.41). + +power_start "type=%lu state=%lu cpu_id=%lu" +power_frequency "type=%lu state=%lu cpu_id=%lu" +power_end "cpu_id=%lu" + +The 'type' parameter takes one of those macros: + . POWER_NONE = 0, + . POWER_CSTATE = 1, /* C-State */ + . POWER_PSTATE = 2, /* Fequency change or DVFS */ + +The 'state' parameter is set depending on the type: + . Target C-state for type=POWER_CSTATE, + . Target frequency for type=POWER_PSTATE, + +power_end is used to indicate the exit of a state, corresponding to the latest +power_start event. + +2. Clocks events +================ +The clock events are used for clock enable/disable and for +clock rate change. + +clock_enable "%s state=%lu cpu_id=%lu" +clock_disable "%s state=%lu cpu_id=%lu" +clock_set_rate "%s state=%lu cpu_id=%lu" + +The first parameter gives the clock name (e.g. "gpio1_iclk"). +The second parameter is '1' for enable, '0' for disable, the target +clock rate for set_rate. + +3. Power domains events +======================= +The power domain events are used for power domains transitions + +power_domain_target "%s state=%lu cpu_id=%lu" + +The first parameter gives the power domain name (e.g. "mpu_pwrdm"). +The second parameter is the power domain target state. + diff --git a/Documentation/trace/events.txt b/Documentation/trace/events.txt index 09bd8e902989..b510564aac7e 100644 --- a/Documentation/trace/events.txt +++ b/Documentation/trace/events.txt @@ -125,7 +125,7 @@ is the size of the data item, in bytes. For example, here's the information displayed for the 'sched_wakeup' event: -# cat /debug/tracing/events/sched/sched_wakeup/format +# cat /sys/kernel/debug/tracing/events/sched/sched_wakeup/format name: sched_wakeup ID: 60 @@ -201,19 +201,19 @@ to the 'filter' file for the given event. For example: -# cd /debug/tracing/events/sched/sched_wakeup +# cd /sys/kernel/debug/tracing/events/sched/sched_wakeup # echo "common_preempt_count > 4" > filter A slightly more involved example: -# cd /debug/tracing/events/sched/sched_signal_send +# cd /sys/kernel/debug/tracing/events/signal/signal_generate # echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter If there is an error in the expression, you'll get an 'Invalid argument' error when setting it, and the erroneous string along with an error message can be seen by looking at the filter e.g.: -# cd /debug/tracing/events/sched/sched_signal_send +# cd /sys/kernel/debug/tracing/events/signal/signal_generate # echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter -bash: echo: write error: Invalid argument # cat filter diff --git a/Documentation/trace/ftrace-design.txt b/Documentation/trace/ftrace-design.txt index dc52bd442c92..79fcafc7fd64 100644 --- a/Documentation/trace/ftrace-design.txt +++ b/Documentation/trace/ftrace-design.txt @@ -247,6 +247,13 @@ You need very few things to get the syscalls tracing in an arch. - Support the TIF_SYSCALL_TRACEPOINT thread flags. - Put the trace_sys_enter() and trace_sys_exit() tracepoints calls from ptrace in the ptrace syscalls tracing path. +- If the system call table on this arch is more complicated than a simple array + of addresses of the system calls, implement an arch_syscall_addr to return + the address of a given system call. +- If the symbol names of the system calls do not match the function names on + this arch, define ARCH_HAS_SYSCALL_MATCH_SYM_NAME in asm/ftrace.h and + implement arch_syscall_match_sym_name with the appropriate logic to return + true if the function name corresponds with the symbol name. - Tag this arch as HAVE_SYSCALL_TRACEPOINTS. diff --git a/Documentation/trace/ftrace.txt b/Documentation/trace/ftrace.txt index 557c1edeccaf..1ebc24cf9a55 100644 --- a/Documentation/trace/ftrace.txt +++ b/Documentation/trace/ftrace.txt @@ -80,11 +80,11 @@ of ftrace. Here is a list of some of the key files: tracers listed here can be configured by echoing their name into current_tracer. - tracing_enabled: + tracing_on: - This sets or displays whether the current_tracer - is activated and tracing or not. Echo 0 into this - file to disable the tracer or 1 to enable it. + This sets or displays whether writing to the trace + ring buffer is enabled. Echo 0 into this file to disable + the tracer or 1 to enable it. trace: @@ -202,10 +202,6 @@ Here is the list of current tracers that may be configured. to draw a graph of function calls similar to C code source. - "sched_switch" - - Traces the context switches and wakeups between tasks. - "irqsoff" Traces the areas that disable interrupts and saves @@ -273,39 +269,6 @@ format, the function name that was traced "path_put" and the parent function that called this function "path_walk". The timestamp is the time at which the function was entered. -The sched_switch tracer also includes tracing of task wakeups -and context switches. - - ksoftirqd/1-7 [01] 1453.070013: 7:115:R + 2916:115:S - ksoftirqd/1-7 [01] 1453.070013: 7:115:R + 10:115:S - ksoftirqd/1-7 [01] 1453.070013: 7:115:R ==> 10:115:R - events/1-10 [01] 1453.070013: 10:115:S ==> 2916:115:R - kondemand/1-2916 [01] 1453.070013: 2916:115:S ==> 7:115:R - ksoftirqd/1-7 [01] 1453.070013: 7:115:S ==> 0:140:R - -Wake ups are represented by a "+" and the context switches are -shown as "==>". The format is: - - Context switches: - - Previous task Next Task - - <pid>:<prio>:<state> ==> <pid>:<prio>:<state> - - Wake ups: - - Current task Task waking up - - <pid>:<prio>:<state> + <pid>:<prio>:<state> - -The prio is the internal kernel priority, which is the inverse -of the priority that is usually displayed by user-space tools. -Zero represents the highest priority (99). Prio 100 starts the -"nice" priorities with 100 being equal to nice -20 and 139 being -nice 19. The prio "140" is reserved for the idle task which is -the lowest priority thread (pid 0). - - Latency trace format -------------------- @@ -491,78 +454,10 @@ x494] <- /root/a.out[+0x4a8] <- /lib/libc-2.7.so[+0x1e1a6] latencies, as described in "Latency trace format". -sched_switch ------------- - -This tracer simply records schedule switches. Here is an example -of how to use it. - - # echo sched_switch > current_tracer - # echo 1 > tracing_enabled - # sleep 1 - # echo 0 > tracing_enabled - # cat trace - -# tracer: sched_switch -# -# TASK-PID CPU# TIMESTAMP FUNCTION -# | | | | | - bash-3997 [01] 240.132281: 3997:120:R + 4055:120:R - bash-3997 [01] 240.132284: 3997:120:R ==> 4055:120:R - sleep-4055 [01] 240.132371: 4055:120:S ==> 3997:120:R - bash-3997 [01] 240.132454: 3997:120:R + 4055:120:S - bash-3997 [01] 240.132457: 3997:120:R ==> 4055:120:R - sleep-4055 [01] 240.132460: 4055:120:D ==> 3997:120:R - bash-3997 [01] 240.132463: 3997:120:R + 4055:120:D - bash-3997 [01] 240.132465: 3997:120:R ==> 4055:120:R - <idle>-0 [00] 240.132589: 0:140:R + 4:115:S - <idle>-0 [00] 240.132591: 0:140:R ==> 4:115:R - ksoftirqd/0-4 [00] 240.132595: 4:115:S ==> 0:140:R - <idle>-0 [00] 240.132598: 0:140:R + 4:115:S - <idle>-0 [00] 240.132599: 0:140:R ==> 4:115:R - ksoftirqd/0-4 [00] 240.132603: 4:115:S ==> 0:140:R - sleep-4055 [01] 240.133058: 4055:120:S ==> 3997:120:R - [...] - - -As we have discussed previously about this format, the header -shows the name of the trace and points to the options. The -"FUNCTION" is a misnomer since here it represents the wake ups -and context switches. - -The sched_switch file only lists the wake ups (represented with -'+') and context switches ('==>') with the previous task or -current task first followed by the next task or task waking up. -The format for both of these is PID:KERNEL-PRIO:TASK-STATE. -Remember that the KERNEL-PRIO is the inverse of the actual -priority with zero (0) being the highest priority and the nice -values starting at 100 (nice -20). Below is a quick chart to map -the kernel priority to user land priorities. - - Kernel Space User Space - =============================================================== - 0(high) to 98(low) user RT priority 99(high) to 1(low) - with SCHED_RR or SCHED_FIFO - --------------------------------------------------------------- - 99 sched_priority is not used in scheduling - decisions(it must be specified as 0) - --------------------------------------------------------------- - 100(high) to 139(low) user nice -20(high) to 19(low) - --------------------------------------------------------------- - 140 idle task priority - --------------------------------------------------------------- - -The task states are: - - R - running : wants to run, may not actually be running - S - sleep : process is waiting to be woken up (handles signals) - D - disk sleep (uninterruptible sleep) : process must be woken up - (ignores signals) - T - stopped : process suspended - t - traced : process is being traced (with something like gdb) - Z - zombie : process waiting to be cleaned up - X - unknown - + overwrite - This controls what happens when the trace buffer is + full. If "1" (default), the oldest events are + discarded and overwritten. If "0", then the newest + events are discarded. ftrace_enabled -------------- @@ -607,10 +502,10 @@ an example: # echo irqsoff > current_tracer # echo latency-format > trace_options # echo 0 > tracing_max_latency - # echo 1 > tracing_enabled + # echo 1 > tracing_on # ls -ltr [...] - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: irqsoff # @@ -715,10 +610,10 @@ is much like the irqsoff tracer. # echo preemptoff > current_tracer # echo latency-format > trace_options # echo 0 > tracing_max_latency - # echo 1 > tracing_enabled + # echo 1 > tracing_on # ls -ltr [...] - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: preemptoff # @@ -863,10 +758,10 @@ tracers. # echo preemptirqsoff > current_tracer # echo latency-format > trace_options # echo 0 > tracing_max_latency - # echo 1 > tracing_enabled + # echo 1 > tracing_on # ls -ltr [...] - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: preemptirqsoff # @@ -1026,9 +921,9 @@ Instead of performing an 'ls', we will run 'sleep 1' under # echo wakeup > current_tracer # echo latency-format > trace_options # echo 0 > tracing_max_latency - # echo 1 > tracing_enabled + # echo 1 > tracing_on # chrt -f 5 sleep 1 - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: wakeup # @@ -1140,9 +1035,9 @@ ftrace_enabled is set; otherwise this tracer is a nop. # sysctl kernel.ftrace_enabled=1 # echo function > current_tracer - # echo 1 > tracing_enabled + # echo 1 > tracing_on # usleep 1 - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: function # @@ -1180,7 +1075,7 @@ int trace_fd; [...] int main(int argc, char *argv[]) { [...] - trace_fd = open(tracing_file("tracing_enabled"), O_WRONLY); + trace_fd = open(tracing_file("tracing_on"), O_WRONLY); [...] if (condition_hit()) { write(trace_fd, "0", 1); @@ -1631,9 +1526,9 @@ If I am only interested in sys_nanosleep and hrtimer_interrupt: # echo sys_nanosleep hrtimer_interrupt \ > set_ftrace_filter # echo function > current_tracer - # echo 1 > tracing_enabled + # echo 1 > tracing_on # usleep 1 - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: ftrace # @@ -1879,9 +1774,9 @@ different. The trace is live. # echo function > current_tracer # cat trace_pipe > /tmp/trace.out & [1] 4153 - # echo 1 > tracing_enabled + # echo 1 > tracing_on # usleep 1 - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: function # diff --git a/Documentation/trace/kprobetrace.txt b/Documentation/trace/kprobetrace.txt index 5f77d94598dd..6d27ab8d6e9f 100644 --- a/Documentation/trace/kprobetrace.txt +++ b/Documentation/trace/kprobetrace.txt @@ -42,11 +42,25 @@ 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) and string are supported. + (u8/u16/u32/u64/s8/s16/s32/s64), "string" and bitfield + are supported. (*) only for return probe. (**) this is useful for fetching a field of data structures. +Types +----- +Several types are supported for fetch-args. Kprobe tracer will access memory +by given type. Prefix 's' and 'u' means those types are signed and unsigned +respectively. Traced arguments are shown in decimal (signed) or hex (unsigned). +String type is a special type, which fetches a "null-terminated" string from +kernel space. This means it will fail and store NULL if the string container +has been paged out. +Bitfield is another special type, which takes 3 parameters, bit-width, bit- +offset, and container-size (usually 32). The syntax is; + + b<bit-width>@<bit-offset>/<container-size> + Per-Probe Event Filtering ------------------------- diff --git a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl index 1b55146d1c8d..12cecc83cd91 100644 --- a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl +++ b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl @@ -46,7 +46,7 @@ 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_RECLAIM => 24; +use constant HIGH_NR_RECLAIMED => 24; use constant HIGH_NR_CONTIG_DIRTY => 25; my %perprocesspid; @@ -58,11 +58,13 @@ 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; @@ -104,7 +106,7 @@ 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 = 'lru=([A-Z_]*) nr_scanned=([0-9]*) nr_reclaimed=([0-9]*) priority=([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_|]*)'; @@ -203,8 +205,8 @@ $regex_lru_shrink_inactive = generate_traceevent_regex( "vmscan/mm_vmscan_lru_shrink_inactive", $regex_lru_shrink_inactive_default, "nid", "zid", - "lru", - "nr_scanned", "nr_reclaimed", "priority"); + "nr_scanned", "nr_reclaimed", "priority", + "flags"); $regex_lru_shrink_active = generate_traceevent_regex( "vmscan/mm_vmscan_lru_shrink_active", $regex_lru_shrink_active_default, @@ -371,10 +373,29 @@ EVENT_PROCESS: print " $regex_lru_isolate/o\n"; next; } + my $isolate_mode = $1; my $nr_scanned = $4; my $nr_contig_dirty = $7; - $perprocesspid{$process_pid}->{HIGH_NR_SCANNED} += $nr_scanned; + + # To closer match vmstat scanning statistics, only count isolate_both + # and isolate_inactive as scanning. isolate_active is rotation + # isolate_inactive == 0 + # isolate_active == 1 + # isolate_both == 2 + if ($isolate_mode != 1) { + $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) { @@ -464,8 +485,8 @@ sub dump_stats { # Print out process activity printf("\n"); - printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s %8s\n", "Process", "Direct", "Wokeup", "Pages", "Pages", "Pages", "Time"); - printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s %8s\n", "details", "Rclms", "Kswapd", "Scanned", "Sync-IO", "ASync-IO", "Stalled"); + 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}) { @@ -475,6 +496,7 @@ sub dump_stats { $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}; @@ -489,11 +511,12 @@ sub dump_stats { $index++; } - printf("%-" . $max_strlen . "s %8d %10d %8u %8u %8u %8.3f", + 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); @@ -529,8 +552,8 @@ sub dump_stats { # Print out kswapd activity printf("\n"); - printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s\n", "Kswapd", "Kswapd", "Order", "Pages", "Pages", "Pages"); - printf("%-" . $max_strlen . "s %8s %10s %8s %8s %8s %8s\n", "Instance", "Wakeups", "Re-wakeup", "Scanned", "Sync-IO", "ASync-IO"); + 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}) { @@ -539,16 +562,18 @@ sub dump_stats { $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 %8i %8u", + 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}); @@ -579,6 +604,7 @@ sub dump_stats { 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"; @@ -588,6 +614,7 @@ sub dump_stats { 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"; @@ -612,6 +639,7 @@ sub aggregate_perprocesspid() { $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}; diff --git a/Documentation/trace/ring-buffer-design.txt b/Documentation/trace/ring-buffer-design.txt index d299ff31df57..7d350b496585 100644 --- a/Documentation/trace/ring-buffer-design.txt +++ b/Documentation/trace/ring-buffer-design.txt @@ -237,7 +237,7 @@ with the previous write. |written | +---------+ |written | - +---------+ <--- next positon for write (current commit) + +---------+ <--- next position for write (current commit) | empty | +---------+ diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt index b29d8e56cf28..c9ffa9ced7ee 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -2,7 +2,7 @@ Alan Stern <stern@rowland.harvard.edu> - December 11, 2009 + October 28, 2010 @@ -107,9 +107,14 @@ allowed to issue dynamic suspends. The user interface for controlling dynamic PM is located in the power/ subdirectory of each USB device's sysfs directory, that is, in /sys/bus/usb/devices/.../power/ where "..." is the device's ID. The -relevant attribute files are: wakeup, control, and autosuspend. -(There may also be a file named "level"; this file was deprecated -as of the 2.6.35 kernel and replaced by the "control" file.) +relevant attribute files are: wakeup, control, and +autosuspend_delay_ms. (There may also be a file named "level"; this +file was deprecated as of the 2.6.35 kernel and replaced by the +"control" file. In 2.6.38 the "autosuspend" file will be deprecated +and replaced by the "autosuspend_delay_ms" file. The only difference +is that the newer file expresses the delay in milliseconds whereas the +older file uses seconds. Confusingly, both files are present in 2.6.37 +but only "autosuspend" works.) power/wakeup @@ -140,33 +145,36 @@ as of the 2.6.35 kernel and replaced by the "control" file.) suspended and autoresume was not allowed. This setting is no longer supported.) - power/autosuspend + power/autosuspend_delay_ms This file contains an integer value, which is the - number of seconds the device should remain idle before - the kernel will autosuspend it (the idle-delay time). - The default is 2. 0 means to autosuspend as soon as - the device becomes idle, and negative values mean - never to autosuspend. You can write a number to the - file to change the autosuspend idle-delay time. - -Writing "-1" to power/autosuspend and writing "on" to power/control do -essentially the same thing -- they both prevent the device from being -autosuspended. Yes, this is a redundancy in the API. + number of milliseconds the device should remain idle + before the kernel will autosuspend it (the idle-delay + time). The default is 2000. 0 means to autosuspend + as soon as the device becomes idle, and negative + values mean never to autosuspend. You can write a + number to the file to change the autosuspend + idle-delay time. + +Writing "-1" to power/autosuspend_delay_ms and writing "on" to +power/control do essentially the same thing -- they both prevent the +device from being autosuspended. Yes, this is a redundancy in the +API. (In 2.6.21 writing "0" to power/autosuspend would prevent the device from being autosuspended; the behavior was changed in 2.6.22. The power/autosuspend attribute did not exist prior to 2.6.21, and the power/level attribute did not exist prior to 2.6.22. power/control -was added in 2.6.34.) +was added in 2.6.34, and power/autosuspend_delay_ms was added in +2.6.37 but did not become functional until 2.6.38.) Changing the default idle-delay time ------------------------------------ -The default autosuspend idle-delay time is controlled by a module -parameter in usbcore. You can specify the value when usbcore is -loaded. For example, to set it to 5 seconds instead of 2 you would +The default autosuspend idle-delay time (in seconds) is controlled by +a module parameter in usbcore. You can specify the value when usbcore +is loaded. For example, to set it to 5 seconds instead of 2 you would do: modprobe usbcore autosuspend=5 @@ -234,25 +242,23 @@ every device. If a driver knows that its device has proper suspend/resume support, it can enable autosuspend all by itself. For example, the video -driver for a laptop's webcam might do this, since these devices are -rarely used and so should normally be autosuspended. +driver for a laptop's webcam might do this (in recent kernels they +do), since these devices are rarely used and so should normally be +autosuspended. Sometimes it turns out that even when a device does work okay with -autosuspend there are still problems. For example, there are -experimental patches adding autosuspend support to the usbhid driver, -which manages keyboards and mice, among other things. Tests with a -number of keyboards showed that typing on a suspended keyboard, while -causing the keyboard to do a remote wakeup all right, would -nonetheless frequently result in lost keystrokes. Tests with mice -showed that some of them would issue a remote-wakeup request in -response to button presses but not to motion, and some in response to -neither. +autosuspend there are still problems. For example, the usbhid driver, +which manages keyboards and mice, has autosuspend support. Tests with +a number of keyboards show that typing on a suspended keyboard, while +causing the keyboard to do a remote wakeup all right, will nonetheless +frequently result in lost keystrokes. Tests with mice show that some +of them will issue a remote-wakeup request in response to button +presses but not to motion, and some in response to neither. The kernel will not prevent you from enabling autosuspend on devices that can't handle it. It is even possible in theory to damage a -device by suspending it at the wrong time -- for example, suspending a -USB hard disk might cause it to spin down without parking the heads. -(Highly unlikely, but possible.) Take care. +device by suspending it at the wrong time. (Highly unlikely, but +possible.) Take care. The driver interface for Power Management @@ -336,10 +342,6 @@ autosuspend the interface's device. When the usage counter is = 0 then the interface is considered to be idle, and the kernel may autosuspend the device. -(There is a similar usage counter field in struct usb_device, -associated with the device itself rather than any of its interfaces. -This counter is used only by the USB core.) - Drivers need not be concerned about balancing changes to the usage counter; the USB core will undo any remaining "get"s when a driver is unbound from its interface. As a corollary, drivers must not call @@ -409,11 +411,11 @@ during autosuspend. For example, there's not much point autosuspending a keyboard if the user can't cause the keyboard to do a remote wakeup by typing on it. If the driver sets intf->needs_remote_wakeup to 1, the kernel won't autosuspend the -device if remote wakeup isn't available or has been disabled through -the power/wakeup attribute. (If the device is already autosuspended, -though, setting this flag won't cause the kernel to autoresume it. -Normally a driver would set this flag in its probe method, at which -time the device is guaranteed not to be autosuspended.) +device if remote wakeup isn't available. (If the device is already +autosuspended, though, setting this flag won't cause the kernel to +autoresume it. Normally a driver would set this flag in its probe +method, at which time the device is guaranteed not to be +autosuspended.) If a driver does its I/O asynchronously in interrupt context, it should call usb_autopm_get_interface_async() before starting output and @@ -422,20 +424,19 @@ it receives an input event, it should call usb_mark_last_busy(struct usb_device *udev); -in the event handler. This sets udev->last_busy to the current time. -udev->last_busy is the field used for idle-delay calculations; -updating it will cause any pending autosuspend to be moved back. Most -of the usb_autopm_* routines will also set the last_busy field to the -current time. +in the event handler. This tells the PM core that the device was just +busy and therefore the next autosuspend idle-delay expiration should +be pushed back. Many of the usb_autopm_* routines also make this call, +so drivers need to worry only when interrupt-driven input arrives. Asynchronous operation is always subject to races. For example, a -driver may call one of the usb_autopm_*_interface_async() routines at -a time when the core has just finished deciding the device has been -idle for long enough but not yet gotten around to calling the driver's -suspend method. The suspend method must be responsible for -synchronizing with the output request routine and the URB completion -handler; it should cause autosuspends to fail with -EBUSY if the -driver needs to use the device. +driver may call the usb_autopm_get_interface_async() routine at a time +when the core has just finished deciding the device has been idle for +long enough but not yet gotten around to calling the driver's suspend +method. The suspend method must be responsible for synchronizing with +the I/O request routine and the URB completion handler; it should +cause autosuspends to fail with -EBUSY if the driver needs to use the +device. External suspend calls should never be allowed to fail in this way, only autosuspend calls. The driver can tell them apart by checking @@ -472,7 +473,9 @@ Firstly, a device may already be autosuspended when a system suspend occurs. Since system suspends are supposed to be as transparent as possible, the device should remain suspended following the system resume. But this theory may not work out well in practice; over time -the kernel's behavior in this regard has changed. +the kernel's behavior in this regard has changed. As of 2.6.37 the +policy is to resume all devices during a system resume and let them +handle their own runtime suspends afterward. Secondly, a dynamic power-management event may occur as a system suspend is underway. The window for this is short, since system diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt index fafcd4723260..afe596d5f201 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/usbmon.txt b/Documentation/usb/usbmon.txt index 66f92d1194c1..a4efa0462f05 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -12,6 +12,10 @@ Controller Drivers (HCD). So, if HCD is buggy, the traces reported by usbmon may not correspond to bus transactions precisely. This is the same situation as with tcpdump. +Two APIs are currently implemented: "text" and "binary". The binary API +is available through a character device in /dev namespace and is an ABI. +The text API is deprecated since 2.6.35, but available for convenience. + * How to use usbmon to collect raw text traces Unlike the packet socket, usbmon has an interface which provides traces @@ -162,39 +166,11 @@ Here is the list of words, from left to right: not machine words, but really just a byte stream split into words to make it easier to read. Thus, the last word may contain from one to four bytes. The length of collected data is limited and can be less than the data length - report in Data Length word. - -Here is an example of code to read the data stream in a well known programming -language: - -class ParsedLine { - int data_len; /* Available length of data */ - byte data[]; - - void parseData(StringTokenizer st) { - int availwords = st.countTokens(); - data = new byte[availwords * 4]; - data_len = 0; - while (st.hasMoreTokens()) { - String data_str = st.nextToken(); - int len = data_str.length() / 2; - int i; - int b; // byte is signed, apparently?! XXX - for (i = 0; i < len; i++) { - // data[data_len] = Byte.parseByte( - // data_str.substring(i*2, i*2 + 2), - // 16); - b = Integer.parseInt( - data_str.substring(i*2, i*2 + 2), - 16); - if (b >= 128) - b *= -1; - data[data_len] = (byte) b; - data_len++; - } - } - } -} + reported in the Data Length word. In the case of an Isochronous input (Zi) + completion where the received data is sparse in the buffer, the length of + the collected data can be greater than the Data Length value (because Data + Length counts only the bytes that were received whereas the Data words + contain the entire transfer buffer). Examples: diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88 index f2510541373b..42517d9121de 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 5c568757c301..9aae449440dc 100644 --- a/Documentation/video4linux/CARDLIST.em28xx +++ b/Documentation/video4linux/CARDLIST.em28xx @@ -1,5 +1,5 @@ 0 -> Unknown EM2800 video grabber (em2800) [eb1a:2800] - 1 -> Unknown EM2750/28xx video grabber (em2820/em2840) [eb1a:2710,eb1a:2820,eb1a:2821,eb1a:2860,eb1a:2861,eb1a:2862,eb1a:2863,eb1a:2870,eb1a:2881,eb1a:2883,eb1a:2868] + 1 -> Unknown EM2750/28xx video grabber (em2820/em2840) [eb1a:2710,eb1a:2820,eb1a:2821,eb1a:2860,eb1a:2861,eb1a:2862,eb1a:2863,eb1a:2870,eb1a:2881,eb1a:2883,eb1a:2868,eb1a:2875] 2 -> Terratec Cinergy 250 USB (em2820/em2840) [0ccd:0036] 3 -> Pinnacle PCTV USB 2 (em2820/em2840) [2304:0208] 4 -> Hauppauge WinTV USB 2 (em2820/em2840) [2040:4200,2040:4201] @@ -9,7 +9,7 @@ 8 -> Kworld USB2800 (em2800) 9 -> Pinnacle Dazzle DVC 90/100/101/107 / Kaiser Baas Video to DVD maker (em2820/em2840) [1b80:e302,1b80:e304,2304:0207,2304:021a] 10 -> Hauppauge WinTV HVR 900 (em2880) [2040:6500] - 11 -> Terratec Hybrid XS (em2880) [0ccd:0042] + 11 -> Terratec Hybrid XS (em2880) 12 -> Kworld PVR TV 2800 RF (em2820/em2840) 13 -> Terratec Prodigy XS (em2880) [0ccd:0047] 14 -> SIIG AVTuner-PVR / Pixelview Prolink PlayTV USB 2.0 (em2820/em2840) @@ -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,15 +46,15 @@ 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] 52 -> DNT DA2 Hybrid (em2881) 53 -> Pinnacle Hybrid Pro (em2881) 54 -> Kworld VS-DVB-T 323UR (em2882) [eb1a:e323] - 55 -> Terratec Hybrid XS (em2882) (em2882) [0ccd:005e] - 56 -> Pinnacle Hybrid Pro (2) (em2882) [2304:0226] + 55 -> Terratec Cinnergy Hybrid T USB XS (em2882) (em2882) [0ccd:005e,0ccd:0042] + 56 -> Pinnacle Hybrid Pro (330e) (em2882) [2304:0226] 57 -> Kworld PlusTV HD Hybrid 330 (em2883) [eb1a:a316] 58 -> Compro VideoMate ForYou/Stereo (em2820/em2840) [185b:2041] 60 -> Hauppauge WinTV HVR 850 (em2883) [2040:651f] diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 4000c29fcfb6..6b4c72d8862d 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] @@ -180,3 +180,5 @@ 179 -> Beholder BeholdTV A7 [5ace:7090] 180 -> Avermedia PCI M733A [1461:4155,1461:4255] 181 -> TechoTrend TT-budget T-3000 [13c2:2804] +182 -> Kworld PCI SBTVD/ISDB-T Full-Seg Hybrid [17de:b136] +183 -> Compro VideoMate Vista M1F [185b:c900] diff --git a/Documentation/video4linux/Makefile b/Documentation/video4linux/Makefile deleted file mode 100644 index 1ed0e98d057d..000000000000 --- a/Documentation/video4linux/Makefile +++ /dev/null @@ -1,8 +0,0 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - -# List of programs to build -hostprogs-y := v4lgrab - -# Tell kbuild to always build the programs -always := $(hostprogs-y) diff --git a/Documentation/video4linux/README.cpia b/Documentation/video4linux/README.cpia deleted file mode 100644 index 8a747fee661f..000000000000 --- a/Documentation/video4linux/README.cpia +++ /dev/null @@ -1,191 +0,0 @@ -This is a driver for the CPiA PPC2 driven parallel connected -Camera. For example the Creative WebcamII is CPiA driven. - - ) [1]Peter Pregler, Linz 2000, published under the [2]GNU GPL - ---------------------------------------------------------------------------- - -USAGE: - -General: -======== - -1) Make sure you have created the video devices (/dev/video*): - -- if you have a recent MAKEDEV do a 'cd /dev;./MAKEDEV video' -- otherwise do a: - -cd /dev -mknod video0 c 81 0 -ln -s video0 video - -2) Compile the kernel (see below for the list of options to use), - configure your parport and reboot. - -3) If all worked well you should get messages similar - to the following (your versions may be different) on the console: - -V4L-Driver for Vision CPiA based cameras v0.7.4 -parport0: read2 timeout. -parport0: Multimedia device, VLSI Vision Ltd PPC2 -Parallel port driver for Vision CPiA based camera - CPIA Version: 1.20 (2.0) - CPIA PnP-ID: 0553:0002:0100 - VP-Version: 1.0 0100 - 1 camera(s) found - - -As modules: -=========== - -Make sure you have selected the following kernel options (you can -select all stuff as modules): - -The cpia-stuff is in the section 'Character devices -> Video For Linux'. - -CONFIG_PARPORT=m -CONFIG_PARPORT_PC=m -CONFIG_PARPORT_PC_FIFO=y -CONFIG_PARPORT_1284=y -CONFIG_VIDEO_DEV=m -CONFIG_VIDEO_CPIA=m -CONFIG_VIDEO_CPIA_PP=m - -For autoloading of all those modules you need to tell module-init-tools -some stuff. Add the following line to your module-init-tools config-file -(e.g. /etc/modprobe.conf or wherever your distribution does store that -stuff): - -options parport_pc io=0x378 irq=7 dma=3 -alias char-major-81 cpia_pp - -The first line tells the dma/irq channels to use. Those _must_ match -the settings of your BIOS. Do NOT simply use the values above. See -Documentation/parport.txt for more information about this. The second -line associates the video-device file with the driver. Of cause you -can also load the modules once upon boot (usually done in /etc/modules). - -Linked into the kernel: -======================= - -Make sure you have selected the following kernel options. Note that -you cannot compile the parport-stuff as modules and the cpia-driver -statically (the other way round is okay though). - -The cpia-stuff is in the section 'Character devices -> Video For Linux'. - -CONFIG_PARPORT=y -CONFIG_PARPORT_PC=y -CONFIG_PARPORT_PC_FIFO=y -CONFIG_PARPORT_1284=y -CONFIG_VIDEO_DEV=y -CONFIG_VIDEO_CPIA=y -CONFIG_VIDEO_CPIA_PP=y - -To use DMA/irq you will need to tell the kernel upon boot time the -hardware configuration of the parport. You can give the boot-parameter -at the LILO-prompt or specify it in lilo.conf. I use the following -append-line in lilo.conf: - - append="parport=0x378,7,3" - -See Documentation/parport.txt for more information about the -configuration of the parport and the values given above. Do not simply -use the values given above. - ---------------------------------------------------------------------------- -FEATURES: - -- mmap/read v4l-interface (but no overlay) -- image formats: CIF/QCIF, SIF/QSIF, various others used by isabel; - note: all sizes except CIF/QCIF are implemented by clipping, i.e. - pixels are not uploaded from the camera -- palettes: VIDEO_PALETTE_GRAY, VIDEO_PALETTE_RGB565, VIDEO_PALETTE_RGB555, - VIDEO_PALETTE_RGB24, VIDEO_PALETTE_RGB32, VIDEO_PALETTE_YUYV, - VIDEO_PALETTE_UYVY, VIDEO_PALETTE_YUV422 -- state information (color balance, exposure, ...) is preserved between - device opens -- complete control over camera via proc-interface (_all_ camera settings are - supported), there is also a python-gtk application available for this [3] -- works under SMP (but the driver is completely serialized and synchronous) - so you get no benefit from SMP, but at least it does not crash your box -- might work for non-Intel architecture, let us know about this - ---------------------------------------------------------------------------- -TESTED APPLICATIONS: - -- a simple test application based on Xt is available at [3] -- another test-application based on gqcam-0.4 (uses GTK) -- gqcam-0.6 should work -- xawtv-3.x (also the webcam software) -- xawtv-2.46 -- w3cam (cgi-interface and vidcat, e.g. you may try out 'vidcat |xv - -maxpect -root -quit +noresetroot -rmode 5 -') -- vic, the MBONE video conferencing tool (version 2.8ucl4-1) -- isabel 3R4beta (barely working, but AFAICT all the problems are on - their side) -- camserv-0.40 - -See [3] for pointers to v4l-applications. - ---------------------------------------------------------------------------- -KNOWN PROBLEMS: - -- some applications do not handle the image format correctly, you will - see strange horizontal stripes instead of a nice picture -> make sure - your application does use a supported image size or queries the driver - for the actually used size (reason behind this: the camera cannot - provide any image format, so if size NxM is requested the driver will - use a format to the closest fitting N1xM1, the application should now - query for this granted size, most applications do not). -- all the todo ;) -- if there is not enough light and the picture is too dark try to - adjust the SetSensorFPS setting, automatic frame rate adjustment - has its price -- do not try out isabel 3R4beta (built 135), you will be disappointed - ---------------------------------------------------------------------------- -TODO: - -- multiple camera support (struct camera or something) - This should work, - but hasn't been tested yet. -- architecture independence? -- SMP-safe asynchronous mmap interface -- nibble mode for old parport interfaces -- streaming capture, this should give a performance gain - ---------------------------------------------------------------------------- -IMPLEMENTATION NOTES: - -The camera can act in two modes, streaming or grabbing. Right now a -polling grab-scheme is used. Maybe interrupt driven streaming will be -used for a asynchronous mmap interface in the next major release of the -driver. This might give a better frame rate. - ---------------------------------------------------------------------------- -THANKS (in no particular order): - -- Scott J. Bertin <sbertin@mindspring.com> for cleanups, the proc-filesystem - and much more -- Henry Bruce <whb@vvl.co.uk> for providing developers information about - the CPiA chip, I wish all companies would treat Linux as seriously -- Karoly Erdei <Karoly.Erdei@risc.uni-linz.ac.at> and RISC-Linz for being - my boss ;) resp. my employer and for providing me the hardware and - allow me to devote some working time to this project -- Manuel J. Petit de Gabriel <mpetit@dit.upm.es> for providing help - with Isabel (http://isabel.dit.upm.es/) -- Bas Huisman <bhuism@cs.utwente.nl> for writing the initial parport code -- Jarl Totland <Jarl.Totland@bdc.no> for setting up the mailing list - and maintaining the web-server[3] -- Chris Whiteford <Chris@informinteractive.com> for fixes related to the - 1.02 firmware -- special kudos to all the tester whose machines crashed and/or - will crash. :) - ---------------------------------------------------------------------------- -REFERENCES - - 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 42b06686eb78..2579b5b709ed 100644 --- a/Documentation/video4linux/README.ivtv +++ b/Documentation/video4linux/README.ivtv @@ -36,8 +36,7 @@ Additional features for the PVR-350 (CX23415 based): * Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the video signal) * Provides a framebuffer (allowing X applications to appear on the video - device) (this framebuffer is not yet part of the kernel. In the meantime it - is available from www.ivtvdriver.org). + device) * Supports raw YUV output. IMPORTANT: In case of problems first read this page: diff --git a/Documentation/video4linux/README.pvrusb2 b/Documentation/video4linux/README.pvrusb2 index a747200fe67c..2137b589276b 100644 --- a/Documentation/video4linux/README.pvrusb2 +++ b/Documentation/video4linux/README.pvrusb2 @@ -172,7 +172,7 @@ Source file list / functional overview: to provide a streaming API usable by a read() system call style of I/O. Right now this is the only layer on top of pvrusb2-io.[ch], however the underlying architecture here was intended to allow for - other styles of I/O to be implemented with additonal modules, like + other styles of I/O to be implemented with additional modules, like mmap()'ed buffers or something even more exotic. pvrusb2-main.c - This is the top level of the driver. Module level diff --git a/Documentation/video4linux/Zoran b/Documentation/video4linux/Zoran index 00e3f9267814..c40e3bab08fa 100644 --- a/Documentation/video4linux/Zoran +++ b/Documentation/video4linux/Zoran @@ -130,7 +130,7 @@ Card number: 4 Note: No module for the mse3000 is available yet Note: No module for the vpx3224 is available yet -Note: use encoder=X or decoder=X for non-default i2c chips (see i2c-id.h) +Note: use encoder=X or decoder=X for non-default i2c chips =========================== @@ -322,76 +322,11 @@ your IRQs and make sure the card has its own interrupts. 4. Programming interface -This driver conforms to video4linux and video4linux2, both can be used to -use the driver. Since video4linux didn't provide adequate calls to fully -use the cards' features, we've introduced several programming extensions, -which are currently officially accepted in the 2.4.x branch of the kernel. -These extensions are known as the v4l/mjpeg extensions. See zoran.h for -details (structs/ioctls). - -Information - video4linux: -http://linux.bytesex.org/v4l2/API.html -Documentation/video4linux/API.html -/usr/include/linux/videodev.h - -Information - video4linux/mjpeg extensions: -./zoran.h -(also see below) - -Information - video4linux2: -http://linuxtv.org -http://v4l2spec.bytesex.org/ -/usr/include/linux/videodev2.h - -More information on the video4linux/mjpeg extensions, by Serguei -Miridonovi and Rainer Johanni: --- -The ioctls for that interface are as follows: - -BUZIOC_G_PARAMS -BUZIOC_S_PARAMS - -Get and set the parameters of the buz. The user should always do a -BUZIOC_G_PARAMS (with a struct buz_params) to obtain the default -settings, change what he likes and then make a BUZIOC_S_PARAMS call. - -BUZIOC_REQBUFS - -Before being able to capture/playback, the user has to request -the buffers he is wanting to use. Fill the structure -zoran_requestbuffers with the size (recommended: 256*1024) and -the number (recommended 32 up to 256). There are no such restrictions -as for the Video for Linux buffers, you should LEAVE SUFFICIENT -MEMORY for your system however, else strange things will happen .... -On return, the zoran_requestbuffers structure contains number and -size of the actually allocated buffers. -You should use these numbers for doing a mmap of the buffers -into the user space. -The BUZIOC_REQBUFS ioctl also makes it happen, that the next mmap -maps the MJPEG buffer instead of the V4L buffers. - -BUZIOC_QBUF_CAPT -BUZIOC_QBUF_PLAY - -Queue a buffer for capture or playback. The first call also starts -streaming capture. When streaming capture is going on, you may -only queue further buffers or issue syncs until streaming -capture is switched off again with a argument of -1 to -a BUZIOC_QBUF_CAPT/BUZIOC_QBUF_PLAY ioctl. - -BUZIOC_SYNC - -Issue this ioctl when all buffers are queued. This ioctl will -block until the first buffer becomes free for saving its -data to disk (after BUZIOC_QBUF_CAPT) or for reuse (after BUZIOC_QBUF_PLAY). - -BUZIOC_G_STATUS - -Get the status of the input lines (video source connected/norm). +This driver conforms to video4linux2. Support for V4L1 and for the custom +zoran ioctls has been removed in kernel 2.6.38. For programming example, please, look at lavrec.c and lavplay.c code in -lavtools-1.2p2 package (URL: http://www.cicese.mx/) -and the 'examples' directory in the original Buz driver distribution. +the MJPEG-tools (http://mjpeg.sf.net/). Additional notes for software developers: @@ -402,9 +337,6 @@ Additional notes for software developers: standard is "more constant" for current country than geometry settings of a variety of TV capture cards which may work in ITU or square pixel format. --- -Please note that lavplay/lavrec are also included in the MJPEG-tools -(http://mjpeg.sf.net/). =========================== diff --git a/Documentation/video4linux/bttv/Cards b/Documentation/video4linux/bttv/Cards index 12217fc49725..db833ced2cb8 100644 --- a/Documentation/video4linux/bttv/Cards +++ b/Documentation/video4linux/bttv/Cards @@ -464,10 +464,6 @@ Siemens ------- Multimedia eXtension Board (MXB) (SAA7146, SAA7111) -Stradis -------- - SDM275,SDM250,SDM026,SDM025 (SAA7146, IBMMPEG2): MPEG2 decoder only - Powercolor ---------- MTV878 diff --git a/Documentation/video4linux/bttv/Insmod-options b/Documentation/video4linux/bttv/Insmod-options index bbe3ed667d91..14c065fa23ef 100644 --- a/Documentation/video4linux/bttv/Insmod-options +++ b/Documentation/video4linux/bttv/Insmod-options @@ -1,5 +1,5 @@ -Note: "modinfo <module>" prints various informations about a kernel +Note: "modinfo <module>" prints various information about a kernel module, among them a complete and up-to-date list of insmod options. This list tends to be outdated because it is updated manually ... diff --git a/Documentation/video4linux/bttv/MAKEDEV b/Documentation/video4linux/bttv/MAKEDEV index 9d112f7fd5f7..093c0cd18042 100644 --- a/Documentation/video4linux/bttv/MAKEDEV +++ b/Documentation/video4linux/bttv/MAKEDEV @@ -19,7 +19,6 @@ function makedev () { 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/README b/Documentation/video4linux/bttv/README index 3a367cdb664e..7cbf4fb6cf31 100644 --- a/Documentation/video4linux/bttv/README +++ b/Documentation/video4linux/bttv/README @@ -70,7 +70,7 @@ If you have trouble with some specific TV card, try to ask there instead of mailing me directly. The chance that someone with the same card listens there is much higher... -For problems with sound: There are alot of different systems used +For problems with sound: There are a lot of different systems used for TV sound all over the world. And there are also different chips which decode the audio signal. Reports about sound problems ("stereo does'nt work") are pretty useless unless you include some details diff --git a/Documentation/video4linux/bttv/README.freeze b/Documentation/video4linux/bttv/README.freeze index 4259dccc8287..5eddfa076cfb 100644 --- a/Documentation/video4linux/bttv/README.freeze +++ b/Documentation/video4linux/bttv/README.freeze @@ -33,7 +33,7 @@ state is stuck. I've seen reports that bttv 0.7.x crashes whereas 0.8.x works rock solid for some people. Thus probably a small buglet left somewhere in bttv -0.7.x. I have no idea where exactly, it works stable for me and alot of +0.7.x. I have no idea where exactly, it works stable for me and a lot of other people. But in case you have problems with the 0.7.x versions you can give 0.8.x a try ... diff --git a/Documentation/video4linux/bttv/Sound-FAQ b/Documentation/video4linux/bttv/Sound-FAQ index 1e6328f91083..395f6c6fdd98 100644 --- a/Documentation/video4linux/bttv/Sound-FAQ +++ b/Documentation/video4linux/bttv/Sound-FAQ @@ -2,13 +2,13 @@ bttv and sound mini howto ========================= -There are alot of different bt848/849/878/879 based boards available. +There are a lot of different bt848/849/878/879 based boards available. Making video work often is not a big deal, because this is handled completely by the bt8xx chip, which is common on all boards. But sound is handled in slightly different ways on each board. To handle the grabber boards correctly, there is a array tvcards[] in -bttv-cards.c, which holds the informations required for each board. +bttv-cards.c, which holds the information required for each board. Sound will work only, if the correct entry is used (for video it often makes no difference). The bttv driver prints a line to the kernel log, telling which card type is used. Like this one: diff --git a/Documentation/video4linux/et61x251.txt b/Documentation/video4linux/et61x251.txt index 1247566c4de3..e0cdae491858 100644 --- a/Documentation/video4linux/et61x251.txt +++ b/Documentation/video4linux/et61x251.txt @@ -191,10 +191,10 @@ Syntax: <n> Description: Debugging information level, from 0 to 3: 0 = none (use carefully) 1 = critical errors - 2 = significant informations + 2 = significant information 3 = more verbose messages Level 3 is useful for testing only, when only one device - is used at the same time. It also shows some more informations + is used at the same time. It also shows some more information about the hardware being detected. This module parameter can be changed at runtime thanks to the /sys filesystem interface. Default: 2 diff --git a/Documentation/video4linux/gspca.txt b/Documentation/video4linux/gspca.txt index 56ba7bba7168..5c542e60f51d 100644 --- a/Documentation/video4linux/gspca.txt +++ b/Documentation/video4linux/gspca.txt @@ -103,6 +103,7 @@ spca561 046d:092d Logitech QC Elch2 spca561 046d:092e Logitech QC Elch2 spca561 046d:092f Logitech QuickCam Express Plus sunplus 046d:0960 Logitech ClickSmart 420 +nw80x 046d:d001 Logitech QuickCam Pro (dark focus ring) sunplus 0471:0322 Philips DMVC1300K zc3xx 0471:0325 Philips SPC 200 NC zc3xx 0471:0326 Philips SPC 300 NC @@ -150,10 +151,12 @@ sunplus 04fc:5330 Digitrex 2110 sunplus 04fc:5360 Sunplus Generic spca500 04fc:7333 PalmPixDC85 sunplus 04fc:ffff Pure DigitalDakota +nw80x 0502:d001 DVC V6 spca501 0506:00df 3Com HomeConnect Lite sunplus 052b:1507 Megapixel 5 Pretec DC-1007 sunplus 052b:1513 Megapix V4 sunplus 052b:1803 MegaImage VI +nw80x 052b:d001 EZCam Pro p35u tv8532 0545:808b Veo Stingray tv8532 0545:8333 Veo Stingray sunplus 0546:3155 Polaroid PDC3070 @@ -177,6 +180,7 @@ sunplus 055f:c530 Mustek Gsmart LCD 3 sunplus 055f:c540 Gsmart D30 sunplus 055f:c630 Mustek MDC4000 sunplus 055f:c650 Mustek MDC5500Z +nw80x 055f:d001 Mustek Wcam 300 mini zc3xx 055f:d003 Mustek WCam300A zc3xx 055f:d004 Mustek WCam300 AN conex 0572:0041 Creative Notebook cx11646 @@ -195,14 +199,20 @@ gl860 05e3:0503 Genesys Logic PC Camera gl860 05e3:f191 Genesys Logic PC Camera spca561 060b:a001 Maxell Compact Pc PM3 zc3xx 0698:2003 CTX M730V built in +nw80x 06a5:0000 Typhoon Webcam 100 USB +nw80x 06a5:d001 Divio based webcams +nw80x 06a5:d800 Divio Chicony TwinkleCam, Trust SpaceCam spca500 06bd:0404 Agfa CL20 spca500 06be:0800 Optimedia +nw80x 06be:d001 EZCam Pro p35u sunplus 06d6:0031 Trust 610 LCD PowerC@m Zoom spca506 06e1:a190 ADS Instant VCD +ov534 06f8:3002 Hercules Blog Webcam ov534_9 06f8:3003 Hercules Dualpix HD Weblog sonixj 06f8:3004 Hercules Classic Silver sonixj 06f8:3008 Hercules Deluxe Optical Glass pac7302 06f8:3009 Hercules Classic Link +nw80x 0728:d001 AVerMedia Camguard spca508 0733:0110 ViewQuest VQ110 spca501 0733:0401 Intel Create and Share spca501 0733:0402 ViewQuest M318B @@ -302,12 +312,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 @@ -364,6 +376,7 @@ t613 17a1:0128 TASCORP JPEG Webcam, NGS Cyclops vc032x 17ef:4802 Lenovo Vc0323+MI1310_SOC pac207 2001:f115 D-Link DSB-C120 sq905c 2770:9050 Disney pix micro (CIF) +sq905c 2770:9051 Lego Bionicle 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 diff --git a/Documentation/video4linux/meye.txt b/Documentation/video4linux/meye.txt index bf3af5fe558f..34e2842c70ae 100644 --- a/Documentation/video4linux/meye.txt +++ b/Documentation/video4linux/meye.txt @@ -45,8 +45,6 @@ module argument syntax (<param>=<value> when passing the option to the module or meye.<param>=<value> on the kernel boot line when meye is statically linked into the kernel). Those options are: - forcev4l1: force use of V4L1 API instead of V4L2 - gbuffers: number of capture buffers, default is 2 (32 max) gbufsize: size of each capture buffer, default is 614400 @@ -79,9 +77,8 @@ Usage: Private API: ------------ - The driver supports frame grabbing with the video4linux API - (either v4l1 or v4l2), so all video4linux tools (like xawtv) - should work with this driver. + The driver supports frame grabbing with the video4linux API, + so all video4linux tools (like xawtv) should work with this driver. Besides the video4linux interface, the driver has a private interface for accessing the Motion Eye extended parameters (camera sharpness, @@ -123,7 +120,4 @@ Private API: Bugs / Todo: ------------ - - the driver could be much cleaned up by removing the v4l1 support. - However, this means all v4l1-only applications will stop working. - - 'motioneye' still uses the meye private v4l1 API extensions. diff --git a/Documentation/video4linux/omap3isp.txt b/Documentation/video4linux/omap3isp.txt new file mode 100644 index 000000000000..69be2c782b98 --- /dev/null +++ b/Documentation/video4linux/omap3isp.txt @@ -0,0 +1,278 @@ +OMAP 3 Image Signal Processor (ISP) driver + +Copyright (C) 2010 Nokia Corporation +Copyright (C) 2009 Texas Instruments, Inc. + +Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com> + Sakari Ailus <sakari.ailus@iki.fi> + David Cohen <dacohen@gmail.com> + + +Introduction +============ + +This file documents the Texas Instruments OMAP 3 Image Signal Processor (ISP) +driver located under drivers/media/video/omap3isp. The original driver was +written by Texas Instruments but since that it has been rewritten (twice) at +Nokia. + +The driver has been successfully used on the following versions of OMAP 3: + + 3430 + 3530 + 3630 + +The driver implements V4L2, Media controller and v4l2_subdev interfaces. +Sensor, lens and flash drivers using the v4l2_subdev interface in the kernel +are supported. + + +Split to subdevs +================ + +The OMAP 3 ISP is split into V4L2 subdevs, each of the blocks inside the ISP +having one subdev to represent it. Each of the subdevs provide a V4L2 subdev +interface to userspace. + + OMAP3 ISP CCP2 + OMAP3 ISP CSI2a + OMAP3 ISP CCDC + OMAP3 ISP preview + OMAP3 ISP resizer + OMAP3 ISP AEWB + OMAP3 ISP AF + OMAP3 ISP histogram + +Each possible link in the ISP is modelled by a link in the Media controller +interface. For an example program see [2]. + + +Controlling the OMAP 3 ISP +========================== + +In general, the settings given to the OMAP 3 ISP take effect at the beginning +of the following frame. This is done when the module becomes idle during the +vertical blanking period on the sensor. In memory-to-memory operation the pipe +is run one frame at a time. Applying the settings is done between the frames. + +All the blocks in the ISP, excluding the CSI-2 and possibly the CCP2 receiver, +insist on receiving complete frames. Sensors must thus never send the ISP +partial frames. + +Autoidle does have issues with some ISP blocks on the 3430, at least. +Autoidle is only enabled on 3630 when the omap3isp module parameter autoidle +is non-zero. + + +Events +====== + +The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and +statistics (AEWB, AF and histogram) subdevs. + +The CCDC subdev produces V4L2_EVENT_OMAP3ISP_HS_VS type event on HS_VS +interrupt which is used to signal frame start. The event is triggered exactly +when the reception of the first line of the frame starts in the CCDC module. +The event can be subscribed on the CCDC subdev. + +(When using parallel interface one must pay account to correct configuration +of the VS signal polarity. This is automatically correct when using the serial +receivers.) + +Each of the statistics subdevs is able to produce events. An event is +generated whenever a statistics buffer can be dequeued by a user space +application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available +are: + + V4L2_EVENT_OMAP3ISP_AEWB + V4L2_EVENT_OMAP3ISP_AF + V4L2_EVENT_OMAP3ISP_HIST + +The type of the event data is struct omap3isp_stat_event_status for these +ioctls. If there is an error calculating the statistics, there will be an +event as usual, but no related statistics buffer. In this case +omap3isp_stat_event_status.buf_err is set to non-zero. + + +Private IOCTLs +============== + +The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where +possible and practical. Much of the functions provided by the ISP, however, +does not fall under the standard IOCTLs --- gamma tables and configuration of +statistics collection are examples of such. + +In general, there is a private ioctl for configuring each of the blocks +containing hardware-dependent functions. + +The following private IOCTLs are supported: + + VIDIOC_OMAP3ISP_CCDC_CFG + VIDIOC_OMAP3ISP_PRV_CFG + VIDIOC_OMAP3ISP_AEWB_CFG + VIDIOC_OMAP3ISP_HIST_CFG + VIDIOC_OMAP3ISP_AF_CFG + VIDIOC_OMAP3ISP_STAT_REQ + VIDIOC_OMAP3ISP_STAT_EN + +The parameter structures used by these ioctls are described in +include/linux/omap3isp.h. The detailed functions of the ISP itself related to +a given ISP block is described in the Technical Reference Manuals (TRMs) --- +see the end of the document for those. + +While it is possible to use the ISP driver without any use of these private +IOCTLs it is not possible to obtain optimal image quality this way. The AEWB, +AF and histogram modules cannot be used without configuring them using the +appropriate private IOCTLs. + + +CCDC and preview block IOCTLs +============================= + +The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to +configure, enable and disable functions in the CCDC and preview blocks, +respectively. Both IOCTLs control several functions in the blocks they +control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct +omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG +accepts a pointer to struct omap3isp_prev_update_config. The definition of +both structures is available in [1]. + +The update field in the structures tells whether to update the configuration +for the specific function and the flag tells whether to enable or disable the +function. + +The update and flag bit masks accept the following values. Each separate +functions in the CCDC and preview blocks is associated with a flag (either +disable or enable; part of the flag field in the structure) and a pointer to +configuration data for the function. + +Valid values for the update and flag fields are listed here for +VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one +function in the same IOCTL call. + + OMAP3ISP_CCDC_ALAW + OMAP3ISP_CCDC_LPF + OMAP3ISP_CCDC_BLCLAMP + OMAP3ISP_CCDC_BCOMP + OMAP3ISP_CCDC_FPC + OMAP3ISP_CCDC_CULL + OMAP3ISP_CCDC_CONFIG_LSC + OMAP3ISP_CCDC_TBL_LSC + +The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here: + + OMAP3ISP_PREV_LUMAENH + OMAP3ISP_PREV_INVALAW + OMAP3ISP_PREV_HRZ_MED + OMAP3ISP_PREV_CFA + OMAP3ISP_PREV_CHROMA_SUPP + OMAP3ISP_PREV_WB + OMAP3ISP_PREV_BLKADJ + OMAP3ISP_PREV_RGB2RGB + OMAP3ISP_PREV_COLOR_CONV + OMAP3ISP_PREV_YC_LIMIT + OMAP3ISP_PREV_DEFECT_COR + OMAP3ISP_PREV_GAMMABYPASS + OMAP3ISP_PREV_DRK_FRM_CAPTURE + OMAP3ISP_PREV_DRK_FRM_SUBTRACT + OMAP3ISP_PREV_LENS_SHADING + OMAP3ISP_PREV_NF + OMAP3ISP_PREV_GAMMA + +The associated configuration pointer for the function may not be NULL when +enabling the function. When disabling a function the configuration pointer is +ignored. + + +Statistic blocks IOCTLs +======================= + +The statistics subdevs do offer more dynamic configuration options than the +other subdevs. They can be enabled, disable and reconfigured when the pipeline +is in streaming state. + +The statistics blocks always get the input image data from the CCDC (as the +histogram memory read isn't implemented). The statistics are dequeueable by +the user from the statistics subdev nodes using private IOCTLs. + +The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily +reflected by the register level interface offered by the ISP hardware. There +are aspects that are purely related to the driver implementation and these are +discussed next. + +VIDIOC_OMAP3ISP_STAT_EN +----------------------- + +This private IOCTL enables/disables a statistic module. If this request is +done before streaming, it will take effect as soon as the pipeline starts to +stream. If the pipeline is already streaming, it will take effect as soon as +the CCDC becomes idle. + +VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG +----------------------------------------------------------------------------- + +Those IOCTLs are used to configure the modules. They require user applications +to have an in-depth knowledge of the hardware. Most of the fields explanation +can be found on OMAP's TRMs. The two following fields common to all the above +configure private IOCTLs require explanation for better understanding as they +are not part of the TRM. + +omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size: + +The modules handle their buffers internally. The necessary buffer size for the +module's data output depends on the requested configuration. Although the +driver supports reconfiguration while streaming, it does not support a +reconfiguration which requires bigger buffer size than what is already +internally allocated if the module is enabled. It will return -EBUSY on this +case. In order to avoid such condition, either disable/reconfigure/enable the +module or request the necessary buffer size during the first configuration +while the module is disabled. + +The internal buffer size allocation considers the requested configuration's +minimum buffer size and the value set on buf_size field. If buf_size field is +out of [minimum, maximum] buffer size range, it's clamped to fit in there. +The driver then selects the biggest value. The corrected buf_size value is +written back to user application. + +omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter: + +As the configuration doesn't take effect synchronously to the request, the +driver must provide a way to track this information to provide more accurate +data. After a configuration is requested, the config_counter returned to user +space application will be an unique value associated to that request. When +user application receives an event for buffer availability or when a new +buffer is requested, this config_counter is used to match a buffer data and a +configuration. + +VIDIOC_OMAP3ISP_STAT_REQ +------------------------ + +Send to user space the oldest data available in the internal buffer queue and +discards such buffer afterwards. The field omap3isp_stat_data.frame_number +matches with the video buffer's field_count. + + +Technical reference manuals (TRMs) and other documentation +========================================================== + +OMAP 3430 TRM: +<URL:http://focus.ti.com/pdfs/wtbu/OMAP34xx_ES3.1.x_PUBLIC_TRM_vZM.zip> +Referenced 2011-03-05. + +OMAP 35xx TRM: +<URL:http://www.ti.com/litv/pdf/spruf98o> Referenced 2011-03-05. + +OMAP 3630 TRM: +<URL:http://focus.ti.com/pdfs/wtbu/OMAP36xx_ES1.x_PUBLIC_TRM_vQ.zip> +Referenced 2011-03-05. + +DM 3730 TRM: +<URL:http://www.ti.com/litv/pdf/sprugn4h> Referenced 2011-03-06. + + +References +========== + +[1] include/linux/omap3isp.h + +[2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary diff --git a/Documentation/video4linux/pxa_camera.txt b/Documentation/video4linux/pxa_camera.txt index 4f6d0ca01956..51ed1578b0e8 100644 --- a/Documentation/video4linux/pxa_camera.txt +++ b/Documentation/video4linux/pxa_camera.txt @@ -84,12 +84,12 @@ DMA usage transfer is not started. On "End Of Frame" interrupt, the irq handler starts the DMA chain. - capture of one videobuffer - The DMA chain starts transfering data into videobuffer RAM pages. - When all pages are transfered, the DMA irq is raised on "ENDINTR" status + The DMA chain starts transferring data into videobuffer RAM pages. + When all pages are transferred, the DMA irq is raised on "ENDINTR" status - finishing one videobuffer The DMA irq handler marks the videobuffer as "done", and removes it from the active running queue - Meanwhile, the next videobuffer (if there is one), is transfered by DMA + Meanwhile, the next videobuffer (if there is one), is transferred by DMA - finishing the last videobuffer On the DMA irq of the last videobuffer, the QCI is stopped. @@ -101,7 +101,7 @@ DMA usage This structure is pointed by dma->sg_cpu. The descriptors are used as follows : - - desc-sg[i]: i-th descriptor, transfering the i-th sg + - desc-sg[i]: i-th descriptor, transferring the i-th sg element to the video buffer scatter gather - finisher: has ddadr=DADDR_STOP, dcmd=ENDIRQEN - linker: has ddadr= desc-sg[0] of next video buffer, dcmd=0 diff --git a/Documentation/video4linux/sn9c102.txt b/Documentation/video4linux/sn9c102.txt index 73de4050d637..b4f67040403a 100644 --- a/Documentation/video4linux/sn9c102.txt +++ b/Documentation/video4linux/sn9c102.txt @@ -214,10 +214,10 @@ Syntax: <n> Description: Debugging information level, from 0 to 3: 0 = none (use carefully) 1 = critical errors - 2 = significant informations + 2 = significant information 3 = more verbose messages Level 3 is useful for testing only. It also shows some more - informations about the hardware being detected. + information about the hardware being detected. This parameter can be changed at runtime thanks to the /sys filesystem interface. Default: 2 diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt index 8773778d23fc..881e7f44491b 100644 --- a/Documentation/video4linux/v4l2-controls.txt +++ b/Documentation/video4linux/v4l2-controls.txt @@ -285,6 +285,9 @@ implement g_volatile_ctrl like this: 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. +Note that if one or more controls in a control cluster are marked as volatile, +then all the controls in the cluster are seen as volatile. + To mark a control as volatile you have to set the is_volatile flag: ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...); @@ -462,6 +465,15 @@ 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. +In rare cases you might want to know which controls of a cluster actually +were set explicitly by the user. For this you can check the 'is_new' flag of +each control. For example, in the case of a volume/mute cluster the 'is_new' +flag of the mute control would be set if the user called VIDIOC_S_CTRL for +mute only. If the user would call VIDIOC_S_EXT_CTRLS for both mute and volume +controls, then the 'is_new' flag would be 1 for both controls. + +The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup(). + VIDIOC_LOG_STATUS Support ========================= diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index e831aaca66f8..cf21f7aae976 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; @@ -71,6 +71,10 @@ sub-device instances, the video_device struct stores V4L2 device node data and in the future a v4l2_fh struct will keep track of filehandle instances (this is not yet implemented). +The V4L2 framework also optionally integrates with the media framework. If a +driver sets the struct v4l2_device mdev field, sub-devices and video nodes +will automatically appear in the media framework as entities. + struct v4l2_device ------------------ @@ -83,11 +87,20 @@ You must register the device instance: v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev); -Registration will initialize the v4l2_device struct and link dev->driver_data -to v4l2_dev. If v4l2_dev->name is empty then it will be set to a value derived -from dev (driver name followed by the bus_id, to be precise). If you set it -up before calling v4l2_device_register then it will be untouched. If dev is -NULL, then you *must* setup v4l2_dev->name before calling v4l2_device_register. +Registration will initialize the v4l2_device struct. If the dev->driver_data +field is NULL, it will be linked to v4l2_dev. + +Drivers that want integration with the media device framework need to set +dev->driver_data manually to point to the driver-specific device structure +that embed the struct v4l2_device instance. This is achieved by a +dev_set_drvdata() call before registering the V4L2 device instance. They must +also set the struct v4l2_device mdev field to point to a properly initialized +and registered media_device instance. + +If v4l2_dev->name is empty then it will be set to a value derived from dev +(driver name followed by the bus_id, to be precise). If you set it up before +calling v4l2_device_register then it will be untouched. If dev is NULL, then +you *must* setup v4l2_dev->name before calling v4l2_device_register. You can use v4l2_device_set_name() to set the name based on a driver name and a driver-global atomic_t instance. This will generate names like ivtv0, ivtv1, @@ -108,6 +121,7 @@ You unregister with: v4l2_device_unregister(struct v4l2_device *v4l2_dev); +If the dev->driver_data field points to v4l2_dev, it will be reset to NULL. Unregistering will also automatically unregister all subdevs from the device. If you have a hotpluggable device (e.g. a USB device), then when a disconnect @@ -167,6 +181,21 @@ static int __devinit drv_probe(struct pci_dev *pdev, state->instance = atomic_inc_return(&drv_instance) - 1; } +If you have multiple device nodes then it can be difficult to know when it is +safe to unregister v4l2_device. For this purpose v4l2_device has refcounting +support. The refcount is increased whenever video_register_device is called and +it is decreased whenever that device node is released. When the refcount reaches +zero, then the v4l2_device release() callback is called. You can do your final +cleanup there. + +If other device nodes (e.g. ALSA) are created, then you can increase and +decrease the refcount manually as well by calling: + +void v4l2_device_get(struct v4l2_device *v4l2_dev); + +or: + +int v4l2_device_put(struct v4l2_device *v4l2_dev); struct v4l2_subdev ------------------ @@ -192,6 +221,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. @@ -249,6 +283,26 @@ A sub-device driver initializes the v4l2_subdev struct using: Afterwards you need to initialize subdev->name with a unique name and set the module owner. This is done for you if you use the i2c helper functions. +If integration with the media framework is needed, you must initialize the +media_entity struct embedded in the v4l2_subdev struct (entity field) by +calling media_entity_init(): + + struct media_pad *pads = &my_sd->pads; + int err; + + err = media_entity_init(&sd->entity, npads, pads, 0); + +The pads array must have been previously initialized. There is no need to +manually set the struct media_entity type and name fields, but the revision +field must be initialized if needed. + +A reference to the entity will be automatically acquired/released when the +subdev device node (if any) is opened/closed. + +Don't forget to cleanup the media entity before the sub-device is destroyed: + + media_entity_cleanup(&sd->entity); + A device (bridge) driver needs to register the v4l2_subdev with the v4l2_device: @@ -258,6 +312,9 @@ This can fail if the subdev module disappeared before it could be registered. After this function was called successfully the subdev->dev field points to the v4l2_device. +If the v4l2_device parent device has a non-NULL mdev field, the sub-device +entity will be automatically registered with the media device. + You can unregister a sub-device using: v4l2_device_unregister_subdev(sd); @@ -286,7 +343,7 @@ ignored. If you want to check for errors use this: err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_chip_ident, &chip); Any error except -ENOIOCTLCMD will exit the loop with that error. If no -errors (except -ENOIOCTLCMD) occured, then 0 is returned. +errors (except -ENOIOCTLCMD) occurred, then 0 is returned. The second argument to both calls is a group ID. If 0, then all subdevs are called. If non-zero, then only those whose group ID match that value will @@ -314,6 +371,61 @@ controlled through GPIO pins. This distinction is only relevant when setting up the device, but once the subdev is registered it is completely transparent. +V4L2 sub-device userspace API +----------------------------- + +Beside exposing a kernel API through the v4l2_subdev_ops structure, V4L2 +sub-devices can also be controlled directly by userspace applications. + +Device nodes named v4l-subdevX can be created in /dev to access sub-devices +directly. If a sub-device supports direct userspace configuration it must set +the V4L2_SUBDEV_FL_HAS_DEVNODE flag before being registered. + +After registering sub-devices, the v4l2_device driver can create device nodes +for all registered sub-devices marked with V4L2_SUBDEV_FL_HAS_DEVNODE by calling +v4l2_device_register_subdev_nodes(). Those device nodes will be automatically +removed when sub-devices are unregistered. + +The device node handles a subset of the V4L2 API. + +VIDIOC_QUERYCTRL +VIDIOC_QUERYMENU +VIDIOC_G_CTRL +VIDIOC_S_CTRL +VIDIOC_G_EXT_CTRLS +VIDIOC_S_EXT_CTRLS +VIDIOC_TRY_EXT_CTRLS + + The controls ioctls are identical to the ones defined in V4L2. They + behave identically, with the only exception that they deal only with + controls implemented in the sub-device. Depending on the driver, those + controls can be also be accessed through one (or several) V4L2 device + nodes. + +VIDIOC_DQEVENT +VIDIOC_SUBSCRIBE_EVENT +VIDIOC_UNSUBSCRIBE_EVENT + + The events ioctls are identical to the ones defined in V4L2. They + behave identically, with the only exception that they deal only with + events generated by the sub-device. Depending on the driver, those + events can also be reported by one (or several) V4L2 device nodes. + + Sub-device drivers that want to use events need to set the + V4L2_SUBDEV_USES_EVENTS v4l2_subdev::flags and initialize + v4l2_subdev::nevents to events queue depth before registering the + sub-device. After registration events can be queued as usual on the + v4l2_subdev::devnode device node. + + To properly support events, the poll() file operation is also + implemented. + +Private ioctls + + All ioctls not in the above list are passed directly to the sub-device + driver through the core::ioctl operation. + + I2C sub-device drivers ---------------------- @@ -448,6 +560,14 @@ 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. +- prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY. + If left to NULL, then it will use the struct v4l2_prio_state in v4l2_device. + If you want to have a separate priority state per (group of) device node(s), + then you can point it to your own struct v4l2_prio_state. - 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. @@ -457,13 +577,50 @@ You should also set these fields: (cx8802). Since the v4l2_device cannot be associated with a particular PCI device it is setup without a parent device. But when the struct video_device is setup you do know which parent PCI device to use. +- flags: optional. Set to V4L2_FL_USE_FH_PRIO if you want to let the framework + handle the VIDIOC_G/S_PRIORITY ioctls. This requires that you use struct + v4l2_fh. Eventually this flag will disappear once all drivers use the core + priority handling. But for now it has to be set explicitly. + +If you use v4l2_ioctl_ops, then you should set .unlocked_ioctl to video_ioctl2 +in your v4l2_file_operations struct. -If you use v4l2_ioctl_ops, then you should set either .unlocked_ioctl or -.ioctl to video_ioctl2 in your v4l2_file_operations struct. +Do not use .ioctl! This is deprecated and will go away in the future. 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. +If integration with the media framework is needed, you must initialize the +media_entity struct embedded in the video_device struct (entity field) by +calling media_entity_init(): + + struct media_pad *pad = &my_vdev->pad; + int err; + + err = media_entity_init(&vdev->entity, 1, pad, 0); + +The pads array must have been previously initialized. There is no need to +manually set the struct media_entity type and name fields. + +A reference to the entity will be automatically acquired/released when the +video device is opened/closed. + +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 ------------------------- @@ -477,13 +634,15 @@ for you. return err; } +If the v4l2_device parent device has a non-NULL mdev field, the video device +entity will be automatically registered with the media device. + Which device is registered depends on the type argument. The following types exist: VFL_TYPE_GRABBER: videoX for video input/output devices VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext) VFL_TYPE_RADIO: radioX for radio tuners -VFL_TYPE_VTX: vtxX for teletext devices (deprecated, don't use) The last argument gives you a certain amount of control over the device device node number used (i.e. the X in videoX). Normally you will pass -1 @@ -547,13 +706,19 @@ 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. +Don't forget to cleanup the media entity associated with the video device if +it has been initialized: + + media_entity_cleanup(&vdev->entity); + +This can be done from the release callback. + video_device helper functions ----------------------------- @@ -613,39 +778,25 @@ struct v4l2_fh -------------- struct v4l2_fh provides a way to easily keep file handle specific data -that is used by the V4L2 framework. Using v4l2_fh is optional for -drivers. +that is used by the V4L2 framework. New drivers must use struct v4l2_fh +since it is also used to implement priority handling (VIDIOC_G/S_PRIORITY) +if the video_device flag V4L2_FL_USE_FH_PRIO is also set. The users of v4l2_fh (in the V4L2 framework, not the driver) know whether a driver uses v4l2_fh as its file->private_data pointer by -testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. - -Useful functions: - -- v4l2_fh_init() - - Initialise the file handle. This *MUST* be performed in the driver's - v4l2_file_operations->open() handler. - -- v4l2_fh_add() - - Add a v4l2_fh to video_device file handle list. May be called after - initialising the file handle. - -- v4l2_fh_del() - - Unassociate the file handle from video_device(). The file handle - exit function may now be called. +testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. This bit is +set whenever v4l2_fh_init() is called. -- v4l2_fh_exit() +struct v4l2_fh is allocated as a part of the driver's own file handle +structure and file->private_data is set to it in the driver's open +function by the driver. - Uninitialise the file handle. After uninitialisation the v4l2_fh - memory can be freed. +In many cases the struct v4l2_fh will be embedded in a larger structure. +In that case you should call v4l2_fh_init+v4l2_fh_add in open() and +v4l2_fh_del+v4l2_fh_exit in release(). -struct v4l2_fh is allocated as a part of the driver's own file handle -structure and is set to file->private_data in the driver's open -function by the driver. Drivers can extract their own file handle -structure by using the container_of macro. Example: +Drivers can extract their own file handle structure by using the container_of +macro. Example: struct my_fh { int blah; @@ -662,15 +813,21 @@ int my_open(struct file *file) ... + my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); + + ... + ret = v4l2_fh_init(&my_fh->fh, vfd); - if (ret) + if (ret) { + kfree(my_fh); return ret; + } - v4l2_fh_add(&my_fh->fh); + ... file->private_data = &my_fh->fh; - - ... + v4l2_fh_add(&my_fh->fh); + return 0; } int my_release(struct file *file) @@ -679,8 +836,65 @@ int my_release(struct file *file) struct my_fh *my_fh = container_of(fh, struct my_fh, fh); ... + v4l2_fh_del(&my_fh->fh); + v4l2_fh_exit(&my_fh->fh); + kfree(my_fh); + return 0; } +Below is a short description of the v4l2_fh functions used: + +int v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev) + + Initialise the file handle. This *MUST* be performed in the driver's + v4l2_file_operations->open() handler. + +void v4l2_fh_add(struct v4l2_fh *fh) + + Add a v4l2_fh to video_device file handle list. Must be called once the + file handle is completely initialized. + +void v4l2_fh_del(struct v4l2_fh *fh) + + Unassociate the file handle from video_device(). The file handle + exit function may now be called. + +void v4l2_fh_exit(struct v4l2_fh *fh) + + Uninitialise the file handle. After uninitialisation the v4l2_fh + memory can be freed. + + +If struct v4l2_fh is not embedded, then you can use these helper functions: + +int v4l2_fh_open(struct file *filp) + + This allocates a struct v4l2_fh, initializes it and adds it to the struct + video_device associated with the file struct. + +int v4l2_fh_release(struct file *filp) + + This deletes it from the struct video_device associated with the file + struct, uninitialised the v4l2_fh and frees it. + +These two functions can be plugged into the v4l2_file_operation's open() and +release() ops. + + +Several drivers need to do something when the first file handle is opened and +when the last file handle closes. Two helper functions were added to check +whether the v4l2_fh struct is the only open filehandle of the associated +device node: + +int v4l2_fh_is_singular(struct v4l2_fh *fh) + + Returns 1 if the file handle is the only open file handle, else 0. + +int v4l2_fh_is_singular_file(struct file *filp) + + Same, but it calls v4l2_fh_is_singular with filp->private_data. + + V4L2 events ----------- diff --git a/Documentation/video4linux/v4lgrab.c b/Documentation/video4linux/v4lgrab.c deleted file mode 100644 index c8ded175796e..000000000000 --- a/Documentation/video4linux/v4lgrab.c +++ /dev/null @@ -1,201 +0,0 @@ -/* Simple Video4Linux image grabber. */ -/* - * Video4Linux Driver Test/Example Framegrabbing Program - * - * Compile with: - * gcc -s -Wall -Wstrict-prototypes v4lgrab.c -o v4lgrab - * Use as: - * v4lgrab >image.ppm - * - * Copyright (C) 1998-05-03, Phil Blundell <philb@gnu.org> - * Copied from http://www.tazenda.demon.co.uk/phil/vgrabber.c - * with minor modifications (Dave Forrest, drf5n@virginia.edu). - * - * - * For some cameras you may need to pre-load libv4l to perform - * the necessary decompression, e.g.: - * - * export LD_PRELOAD=/usr/lib/libv4l/v4l1compat.so - * ./v4lgrab >image.ppm - * - * see http://hansdegoede.livejournal.com/3636.html for details. - * - */ - -#include <unistd.h> -#include <sys/types.h> -#include <sys/stat.h> -#include <fcntl.h> -#include <stdio.h> -#include <sys/ioctl.h> -#include <stdlib.h> - -#include <linux/types.h> -#include <linux/videodev.h> - -#define VIDEO_DEV "/dev/video0" - -/* Stole this from tvset.c */ - -#define READ_VIDEO_PIXEL(buf, format, depth, r, g, b) \ -{ \ - switch (format) \ - { \ - case VIDEO_PALETTE_GREY: \ - switch (depth) \ - { \ - case 4: \ - case 6: \ - case 8: \ - (r) = (g) = (b) = (*buf++ << 8);\ - break; \ - \ - case 16: \ - (r) = (g) = (b) = \ - *((unsigned short *) buf); \ - buf += 2; \ - break; \ - } \ - break; \ - \ - \ - case VIDEO_PALETTE_RGB565: \ - { \ - unsigned short tmp = *(unsigned short *)buf; \ - (r) = tmp&0xF800; \ - (g) = (tmp<<5)&0xFC00; \ - (b) = (tmp<<11)&0xF800; \ - buf += 2; \ - } \ - break; \ - \ - case VIDEO_PALETTE_RGB555: \ - (r) = (buf[0]&0xF8)<<8; \ - (g) = ((buf[0] << 5 | buf[1] >> 3)&0xF8)<<8; \ - (b) = ((buf[1] << 2 ) & 0xF8)<<8; \ - buf += 2; \ - break; \ - \ - case VIDEO_PALETTE_RGB24: \ - (r) = buf[0] << 8; (g) = buf[1] << 8; \ - (b) = buf[2] << 8; \ - buf += 3; \ - break; \ - \ - default: \ - fprintf(stderr, \ - "Format %d not yet supported\n", \ - format); \ - } \ -} - -static int get_brightness_adj(unsigned char *image, long size, int *brightness) { - long i, tot = 0; - for (i=0;i<size*3;i++) - tot += image[i]; - *brightness = (128 - tot/(size*3))/3; - return !((tot/(size*3)) >= 126 && (tot/(size*3)) <= 130); -} - -int main(int argc, char ** argv) -{ - int fd = open(VIDEO_DEV, O_RDONLY), f; - struct video_capability cap; - struct video_window win; - struct video_picture vpic; - - unsigned char *buffer, *src; - int bpp = 24, r = 0, g = 0, b = 0; - unsigned int i, src_depth = 16; - - if (fd < 0) { - perror(VIDEO_DEV); - exit(1); - } - - if (ioctl(fd, VIDIOCGCAP, &cap) < 0) { - perror("VIDIOGCAP"); - fprintf(stderr, "(" VIDEO_DEV " not a video4linux device?)\n"); - close(fd); - exit(1); - } - - if (ioctl(fd, VIDIOCGWIN, &win) < 0) { - perror("VIDIOCGWIN"); - close(fd); - exit(1); - } - - if (ioctl(fd, VIDIOCGPICT, &vpic) < 0) { - perror("VIDIOCGPICT"); - close(fd); - exit(1); - } - - if (cap.type & VID_TYPE_MONOCHROME) { - vpic.depth=8; - vpic.palette=VIDEO_PALETTE_GREY; /* 8bit grey */ - if(ioctl(fd, VIDIOCSPICT, &vpic) < 0) { - vpic.depth=6; - if(ioctl(fd, VIDIOCSPICT, &vpic) < 0) { - vpic.depth=4; - if(ioctl(fd, VIDIOCSPICT, &vpic) < 0) { - fprintf(stderr, "Unable to find a supported capture format.\n"); - close(fd); - exit(1); - } - } - } - } else { - vpic.depth=24; - vpic.palette=VIDEO_PALETTE_RGB24; - - if(ioctl(fd, VIDIOCSPICT, &vpic) < 0) { - vpic.palette=VIDEO_PALETTE_RGB565; - vpic.depth=16; - - if(ioctl(fd, VIDIOCSPICT, &vpic)==-1) { - vpic.palette=VIDEO_PALETTE_RGB555; - vpic.depth=15; - - if(ioctl(fd, VIDIOCSPICT, &vpic)==-1) { - fprintf(stderr, "Unable to find a supported capture format.\n"); - return -1; - } - } - } - } - - buffer = malloc(win.width * win.height * bpp); - if (!buffer) { - fprintf(stderr, "Out of memory.\n"); - exit(1); - } - - do { - int newbright; - read(fd, buffer, win.width * win.height * bpp); - f = get_brightness_adj(buffer, win.width * win.height, &newbright); - if (f) { - vpic.brightness += (newbright << 8); - if(ioctl(fd, VIDIOCSPICT, &vpic)==-1) { - perror("VIDIOSPICT"); - break; - } - } - } while (f); - - fprintf(stdout, "P6\n%d %d 255\n", win.width, win.height); - - src = buffer; - - for (i = 0; i < win.width * win.height; i++) { - READ_VIDEO_PIXEL(src, vpic.palette, src_depth, r, g, b); - fputc(r>>8, stdout); - fputc(g>>8, stdout); - fputc(b>>8, stdout); - } - - close(fd); - return 0; -} diff --git a/Documentation/video4linux/videobuf b/Documentation/video4linux/videobuf index 17a1f9abf260..1d00d7f15b8f 100644 --- a/Documentation/video4linux/videobuf +++ b/Documentation/video4linux/videobuf @@ -247,8 +247,6 @@ calls. The relevant helper functions are: int nonblocking); int videobuf_streamon(struct videobuf_queue *q); int videobuf_streamoff(struct videobuf_queue *q); - int videobuf_cgmbuf(struct videobuf_queue *q, struct video_mbuf *mbuf, - int count); So, for example, a VIDIOC_REQBUFS call turns into a call to the driver's vidioc_reqbufs() callback which, in turn, usually only needs to locate the @@ -258,10 +256,7 @@ boilerplate in a lot of V4L2 drivers. The vidioc_streamon() and vidioc_streamoff() functions will be a bit more complex, of course, since they will also need to deal with starting and -stopping the capture engine. videobuf_cgmbuf(), called from the driver's -vidiocgmbuf() function, only exists if the V4L1 compatibility module has -been selected with CONFIG_VIDEO_V4L1_COMPAT, so its use must be surrounded -with #ifdef directives. +stopping the capture engine. Buffer allocation diff --git a/Documentation/video4linux/w9968cf.txt b/Documentation/video4linux/w9968cf.txt index 05138e8aea07..9649450f3b90 100644 --- a/Documentation/video4linux/w9968cf.txt +++ b/Documentation/video4linux/w9968cf.txt @@ -413,7 +413,7 @@ Syntax: <n> Description: Debugging information level, from 0 to 6: 0 = none (use carefully) 1 = critical errors - 2 = significant informations + 2 = significant information 3 = configuration or general messages 4 = warnings 5 = called functions diff --git a/Documentation/video4linux/zc0301.txt b/Documentation/video4linux/zc0301.txt index befdfdacdc5b..b41c83cf09f4 100644 --- a/Documentation/video4linux/zc0301.txt +++ b/Documentation/video4linux/zc0301.txt @@ -181,10 +181,10 @@ Syntax: <n> Description: Debugging information level, from 0 to 3: 0 = none (use carefully) 1 = critical errors - 2 = significant informations + 2 = significant information 3 = more verbose messages Level 3 is useful for testing only, when only one device - is used at the same time. It also shows some more informations + is used at the same time. It also shows some information about the hardware being detected. This module parameter can be changed at runtime thanks to the /sys filesystem interface. Default: 2 @@ -261,7 +261,7 @@ the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. 11. Credits =========== -- Informations about the chip internals needed to enable the I2C protocol have +- Information about the chip internals needed to enable the I2C protocol have been taken from the documentation of the ZC030x Video4Linux1 driver written by Andrew Birkett <andy@nobugs.org>; - The initialization values of the ZC0301 controller connected to the PAS202BCB diff --git a/Documentation/vm/Makefile b/Documentation/vm/Makefile index 9dcff328b964..3fa4d0668864 100644 --- a/Documentation/vm/Makefile +++ b/Documentation/vm/Makefile @@ -2,7 +2,7 @@ obj- := dummy.o # List of programs to build -hostprogs-y := slabinfo page-types hugepage-mmap hugepage-shm map_hugetlb +hostprogs-y := page-types hugepage-mmap hugepage-shm map_hugetlb # Tell kbuild to always build the programs always := $(hostprogs-y) diff --git a/Documentation/vm/active_mm.txt b/Documentation/vm/active_mm.txt index 4ee1f643d897..dbf45817405f 100644 --- a/Documentation/vm/active_mm.txt +++ b/Documentation/vm/active_mm.txt @@ -74,7 +74,7 @@ we have a user context", and is generally done by the page fault handler and things like that). Anyway, I put a pre-patch-2.3.13-1 on ftp.kernel.org just a moment ago, -because it slightly changes the interfaces to accomodate the alpha (who +because it slightly changes the interfaces to accommodate the alpha (who would have thought it, but the alpha actually ends up having one of the ugliest context switch codes - unlike the other architectures where the MM and register state is separate, the alpha PALcode joins the two, and you diff --git a/Documentation/vm/highmem.txt b/Documentation/vm/highmem.txt new file mode 100644 index 000000000000..4324d24ffacd --- /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/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index 457634c1e03e..f8551b3879f8 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt @@ -72,7 +72,7 @@ number of huge pages requested. This is the most reliable method of allocating huge pages as memory has not yet become fragmented. Some platforms support multiple huge page sizes. To allocate huge pages -of a specific size, one must preceed the huge pages boot command parameters +of a specific size, one must precede the huge pages boot command parameters with a huge page size selection parameter "hugepagesz=<size>". <size> must be specified in bytes with optional scale suffix [kKmMgG]. The default huge page size may be selected with the "default_hugepagesz=<size>" boot parameter. diff --git a/Documentation/vm/numa_memory_policy.txt b/Documentation/vm/numa_memory_policy.txt index 6690fc34ef6d..4e7da6543424 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/overcommit-accounting b/Documentation/vm/overcommit-accounting index 21c7b1f8f32b..706d7ed9d8d2 100644 --- a/Documentation/vm/overcommit-accounting +++ b/Documentation/vm/overcommit-accounting @@ -4,7 +4,7 @@ The Linux kernel supports the following overcommit handling modes address space are refused. Used for a typical system. It ensures a seriously wild allocation fails while allowing overcommit to reduce swap usage. root is allowed to - allocate slighly more memory in this mode. This is the + allocate slightly more memory in this mode. This is the default. 1 - Always overcommit. Appropriate for some scientific diff --git a/Documentation/vm/page-types.c b/Documentation/vm/page-types.c index ccd951fa94ee..7445caa26d05 100644 --- a/Documentation/vm/page-types.c +++ b/Documentation/vm/page-types.c @@ -32,8 +32,20 @@ #include <sys/types.h> #include <sys/errno.h> #include <sys/fcntl.h> +#include <sys/mount.h> +#include <sys/statfs.h> +#include "../../include/linux/magic.h" +#ifndef MAX_PATH +# define MAX_PATH 256 +#endif + +#ifndef STR +# define _STR(x) #x +# define STR(x) _STR(x) +#endif + /* * pagemap kernel ABI bits */ @@ -152,6 +164,12 @@ static const char *page_flag_names[] = { }; +static const char *debugfs_known_mountpoints[] = { + "/sys/kernel/debug", + "/debug", + 0, +}; + /* * data structures */ @@ -184,7 +202,7 @@ static int kpageflags_fd; static int opt_hwpoison; static int opt_unpoison; -static const char hwpoison_debug_fs[] = "/debug/hwpoison"; +static char hwpoison_debug_fs[MAX_PATH+1]; static int hwpoison_inject_fd; static int hwpoison_forget_fd; @@ -464,21 +482,100 @@ static uint64_t kpageflags_flags(uint64_t flags) return flags; } +/* verify that a mountpoint is actually a debugfs instance */ +static int debugfs_valid_mountpoint(const char *debugfs) +{ + struct statfs st_fs; + + if (statfs(debugfs, &st_fs) < 0) + return -ENOENT; + else if (st_fs.f_type != (long) DEBUGFS_MAGIC) + return -ENOENT; + + return 0; +} + +/* find the path to the mounted debugfs */ +static const char *debugfs_find_mountpoint(void) +{ + const char **ptr; + char type[100]; + FILE *fp; + + ptr = debugfs_known_mountpoints; + while (*ptr) { + if (debugfs_valid_mountpoint(*ptr) == 0) { + strcpy(hwpoison_debug_fs, *ptr); + return hwpoison_debug_fs; + } + ptr++; + } + + /* give up and parse /proc/mounts */ + fp = fopen("/proc/mounts", "r"); + if (fp == NULL) + perror("Can't open /proc/mounts for read"); + + while (fscanf(fp, "%*s %" + STR(MAX_PATH) + "s %99s %*s %*d %*d\n", + hwpoison_debug_fs, type) == 2) { + if (strcmp(type, "debugfs") == 0) + break; + } + fclose(fp); + + if (strcmp(type, "debugfs") != 0) + return NULL; + + return hwpoison_debug_fs; +} + +/* mount the debugfs somewhere if it's not mounted */ + +static void debugfs_mount(void) +{ + const char **ptr; + + /* see if it's already mounted */ + if (debugfs_find_mountpoint()) + return; + + ptr = debugfs_known_mountpoints; + while (*ptr) { + if (mount(NULL, *ptr, "debugfs", 0, NULL) == 0) { + /* save the mountpoint */ + strcpy(hwpoison_debug_fs, *ptr); + break; + } + ptr++; + } + + if (*ptr == NULL) { + perror("mount debugfs"); + exit(EXIT_FAILURE); + } +} + /* * page actions */ static void prepare_hwpoison_fd(void) { - char buf[100]; + char buf[MAX_PATH + 1]; + + debugfs_mount(); if (opt_hwpoison && !hwpoison_inject_fd) { - sprintf(buf, "%s/corrupt-pfn", hwpoison_debug_fs); + snprintf(buf, MAX_PATH, "%s/hwpoison/corrupt-pfn", + hwpoison_debug_fs); hwpoison_inject_fd = checked_open(buf, O_WRONLY); } if (opt_unpoison && !hwpoison_forget_fd) { - sprintf(buf, "%s/renew-pfn", hwpoison_debug_fs); + snprintf(buf, MAX_PATH, "%s/hwpoison/unpoison-pfn", + hwpoison_debug_fs); hwpoison_forget_fd = checked_open(buf, O_WRONLY); } } diff --git a/Documentation/vm/slabinfo.c b/Documentation/vm/slabinfo.c deleted file mode 100644 index 92e729f4b676..000000000000 --- a/Documentation/vm/slabinfo.c +++ /dev/null @@ -1,1364 +0,0 @@ -/* - * Slabinfo: Tool to get reports about slabs - * - * (C) 2007 sgi, Christoph Lameter - * - * Compile by: - * - * gcc -o slabinfo slabinfo.c - */ -#include <stdio.h> -#include <stdlib.h> -#include <sys/types.h> -#include <dirent.h> -#include <strings.h> -#include <string.h> -#include <unistd.h> -#include <stdarg.h> -#include <getopt.h> -#include <regex.h> -#include <errno.h> - -#define MAX_SLABS 500 -#define MAX_ALIASES 500 -#define MAX_NODES 1024 - -struct slabinfo { - char *name; - int alias; - int refs; - int aliases, align, cache_dma, cpu_slabs, destroy_by_rcu; - int hwcache_align, object_size, objs_per_slab; - int sanity_checks, slab_size, store_user, trace; - int order, poison, reclaim_account, red_zone; - unsigned long partial, objects, slabs, objects_partial, objects_total; - unsigned long alloc_fastpath, alloc_slowpath; - unsigned long free_fastpath, free_slowpath; - unsigned long free_frozen, free_add_partial, free_remove_partial; - unsigned long alloc_from_partial, alloc_slab, free_slab, alloc_refill; - unsigned long cpuslab_flush, deactivate_full, deactivate_empty; - unsigned long deactivate_to_head, deactivate_to_tail; - unsigned long deactivate_remote_frees, order_fallback; - int numa[MAX_NODES]; - int numa_partial[MAX_NODES]; -} slabinfo[MAX_SLABS]; - -struct aliasinfo { - char *name; - char *ref; - struct slabinfo *slab; -} aliasinfo[MAX_ALIASES]; - -int slabs = 0; -int actual_slabs = 0; -int aliases = 0; -int alias_targets = 0; -int highest_node = 0; - -char buffer[4096]; - -int show_empty = 0; -int show_report = 0; -int show_alias = 0; -int show_slab = 0; -int skip_zero = 1; -int show_numa = 0; -int show_track = 0; -int show_first_alias = 0; -int validate = 0; -int shrink = 0; -int show_inverted = 0; -int show_single_ref = 0; -int show_totals = 0; -int sort_size = 0; -int sort_active = 0; -int set_debug = 0; -int show_ops = 0; -int show_activity = 0; - -/* Debug options */ -int sanity = 0; -int redzone = 0; -int poison = 0; -int tracking = 0; -int tracing = 0; - -int page_size; - -regex_t pattern; - -static void fatal(const char *x, ...) -{ - va_list ap; - - va_start(ap, x); - vfprintf(stderr, x, ap); - va_end(ap); - exit(EXIT_FAILURE); -} - -static void usage(void) -{ - printf("slabinfo 5/7/2007. (c) 2007 sgi.\n\n" - "slabinfo [-ahnpvtsz] [-d debugopts] [slab-regexp]\n" - "-a|--aliases Show aliases\n" - "-A|--activity Most active slabs first\n" - "-d<options>|--debug=<options> Set/Clear Debug options\n" - "-D|--display-active Switch line format to activity\n" - "-e|--empty Show empty slabs\n" - "-f|--first-alias Show first alias\n" - "-h|--help Show usage information\n" - "-i|--inverted Inverted list\n" - "-l|--slabs Show slabs\n" - "-n|--numa Show NUMA information\n" - "-o|--ops Show kmem_cache_ops\n" - "-s|--shrink Shrink slabs\n" - "-r|--report Detailed report on single slabs\n" - "-S|--Size Sort by size\n" - "-t|--tracking Show alloc/free information\n" - "-T|--Totals Show summary information\n" - "-v|--validate Validate slabs\n" - "-z|--zero Include empty slabs\n" - "-1|--1ref Single reference\n" - "\nValid debug options (FZPUT may be combined)\n" - "a / A Switch on all debug options (=FZUP)\n" - "- Switch off all debug options\n" - "f / F Sanity Checks (SLAB_DEBUG_FREE)\n" - "z / Z Redzoning\n" - "p / P Poisoning\n" - "u / U Tracking\n" - "t / T Tracing\n" - ); -} - -static unsigned long read_obj(const char *name) -{ - FILE *f = fopen(name, "r"); - - if (!f) - buffer[0] = 0; - else { - if (!fgets(buffer, sizeof(buffer), f)) - buffer[0] = 0; - fclose(f); - if (buffer[strlen(buffer)] == '\n') - buffer[strlen(buffer)] = 0; - } - return strlen(buffer); -} - - -/* - * Get the contents of an attribute - */ -static unsigned long get_obj(const char *name) -{ - if (!read_obj(name)) - return 0; - - return atol(buffer); -} - -static unsigned long get_obj_and_str(const char *name, char **x) -{ - unsigned long result = 0; - char *p; - - *x = NULL; - - if (!read_obj(name)) { - x = NULL; - return 0; - } - result = strtoul(buffer, &p, 10); - while (*p == ' ') - p++; - if (*p) - *x = strdup(p); - return result; -} - -static void set_obj(struct slabinfo *s, const char *name, int n) -{ - char x[100]; - FILE *f; - - snprintf(x, 100, "%s/%s", s->name, name); - f = fopen(x, "w"); - if (!f) - fatal("Cannot write to %s\n", x); - - fprintf(f, "%d\n", n); - fclose(f); -} - -static unsigned long read_slab_obj(struct slabinfo *s, const char *name) -{ - char x[100]; - FILE *f; - size_t l; - - snprintf(x, 100, "%s/%s", s->name, name); - f = fopen(x, "r"); - if (!f) { - buffer[0] = 0; - l = 0; - } else { - l = fread(buffer, 1, sizeof(buffer), f); - buffer[l] = 0; - fclose(f); - } - return l; -} - - -/* - * Put a size string together - */ -static int store_size(char *buffer, unsigned long value) -{ - unsigned long divisor = 1; - char trailer = 0; - int n; - - if (value > 1000000000UL) { - divisor = 100000000UL; - trailer = 'G'; - } else if (value > 1000000UL) { - divisor = 100000UL; - trailer = 'M'; - } else if (value > 1000UL) { - divisor = 100; - trailer = 'K'; - } - - value /= divisor; - n = sprintf(buffer, "%ld",value); - if (trailer) { - buffer[n] = trailer; - n++; - buffer[n] = 0; - } - if (divisor != 1) { - memmove(buffer + n - 2, buffer + n - 3, 4); - buffer[n-2] = '.'; - n++; - } - return n; -} - -static void decode_numa_list(int *numa, char *t) -{ - int node; - int nr; - - memset(numa, 0, MAX_NODES * sizeof(int)); - - if (!t) - return; - - while (*t == 'N') { - t++; - node = strtoul(t, &t, 10); - if (*t == '=') { - t++; - nr = strtoul(t, &t, 10); - numa[node] = nr; - if (node > highest_node) - highest_node = node; - } - while (*t == ' ') - t++; - } -} - -static void slab_validate(struct slabinfo *s) -{ - if (strcmp(s->name, "*") == 0) - return; - - set_obj(s, "validate", 1); -} - -static void slab_shrink(struct slabinfo *s) -{ - if (strcmp(s->name, "*") == 0) - return; - - set_obj(s, "shrink", 1); -} - -int line = 0; - -static void first_line(void) -{ - if (show_activity) - printf("Name Objects Alloc Free %%Fast Fallb O\n"); - else - printf("Name Objects Objsize Space " - "Slabs/Part/Cpu O/S O %%Fr %%Ef Flg\n"); -} - -/* - * Find the shortest alias of a slab - */ -static struct aliasinfo *find_one_alias(struct slabinfo *find) -{ - struct aliasinfo *a; - struct aliasinfo *best = NULL; - - for(a = aliasinfo;a < aliasinfo + aliases; a++) { - if (a->slab == find && - (!best || strlen(best->name) < strlen(a->name))) { - best = a; - if (strncmp(a->name,"kmall", 5) == 0) - return best; - } - } - return best; -} - -static unsigned long slab_size(struct slabinfo *s) -{ - return s->slabs * (page_size << s->order); -} - -static unsigned long slab_activity(struct slabinfo *s) -{ - return s->alloc_fastpath + s->free_fastpath + - s->alloc_slowpath + s->free_slowpath; -} - -static void slab_numa(struct slabinfo *s, int mode) -{ - int node; - - if (strcmp(s->name, "*") == 0) - return; - - if (!highest_node) { - printf("\n%s: No NUMA information available.\n", s->name); - return; - } - - if (skip_zero && !s->slabs) - return; - - if (!line) { - printf("\n%-21s:", mode ? "NUMA nodes" : "Slab"); - for(node = 0; node <= highest_node; node++) - printf(" %4d", node); - printf("\n----------------------"); - for(node = 0; node <= highest_node; node++) - printf("-----"); - printf("\n"); - } - printf("%-21s ", mode ? "All slabs" : s->name); - for(node = 0; node <= highest_node; node++) { - char b[20]; - - store_size(b, s->numa[node]); - printf(" %4s", b); - } - printf("\n"); - if (mode) { - printf("%-21s ", "Partial slabs"); - for(node = 0; node <= highest_node; node++) { - char b[20]; - - store_size(b, s->numa_partial[node]); - printf(" %4s", b); - } - printf("\n"); - } - line++; -} - -static void show_tracking(struct slabinfo *s) -{ - printf("\n%s: Kernel object allocation\n", s->name); - printf("-----------------------------------------------------------------------\n"); - if (read_slab_obj(s, "alloc_calls")) - printf(buffer); - else - printf("No Data\n"); - - printf("\n%s: Kernel object freeing\n", s->name); - printf("------------------------------------------------------------------------\n"); - if (read_slab_obj(s, "free_calls")) - printf(buffer); - else - printf("No Data\n"); - -} - -static void ops(struct slabinfo *s) -{ - if (strcmp(s->name, "*") == 0) - return; - - if (read_slab_obj(s, "ops")) { - printf("\n%s: kmem_cache operations\n", s->name); - printf("--------------------------------------------\n"); - printf(buffer); - } else - printf("\n%s has no kmem_cache operations\n", s->name); -} - -static const char *onoff(int x) -{ - if (x) - return "On "; - return "Off"; -} - -static void slab_stats(struct slabinfo *s) -{ - unsigned long total_alloc; - unsigned long total_free; - unsigned long total; - - if (!s->alloc_slab) - return; - - total_alloc = s->alloc_fastpath + s->alloc_slowpath; - total_free = s->free_fastpath + s->free_slowpath; - - if (!total_alloc) - return; - - printf("\n"); - printf("Slab Perf Counter Alloc Free %%Al %%Fr\n"); - printf("--------------------------------------------------\n"); - printf("Fastpath %8lu %8lu %3lu %3lu\n", - s->alloc_fastpath, s->free_fastpath, - s->alloc_fastpath * 100 / total_alloc, - s->free_fastpath * 100 / total_free); - printf("Slowpath %8lu %8lu %3lu %3lu\n", - total_alloc - s->alloc_fastpath, s->free_slowpath, - (total_alloc - s->alloc_fastpath) * 100 / total_alloc, - s->free_slowpath * 100 / total_free); - printf("Page Alloc %8lu %8lu %3lu %3lu\n", - s->alloc_slab, s->free_slab, - s->alloc_slab * 100 / total_alloc, - s->free_slab * 100 / total_free); - printf("Add partial %8lu %8lu %3lu %3lu\n", - s->deactivate_to_head + s->deactivate_to_tail, - s->free_add_partial, - (s->deactivate_to_head + s->deactivate_to_tail) * 100 / total_alloc, - s->free_add_partial * 100 / total_free); - printf("Remove partial %8lu %8lu %3lu %3lu\n", - s->alloc_from_partial, s->free_remove_partial, - s->alloc_from_partial * 100 / total_alloc, - s->free_remove_partial * 100 / total_free); - - printf("RemoteObj/SlabFrozen %8lu %8lu %3lu %3lu\n", - s->deactivate_remote_frees, s->free_frozen, - s->deactivate_remote_frees * 100 / total_alloc, - s->free_frozen * 100 / total_free); - - printf("Total %8lu %8lu\n\n", total_alloc, total_free); - - if (s->cpuslab_flush) - printf("Flushes %8lu\n", s->cpuslab_flush); - - if (s->alloc_refill) - printf("Refill %8lu\n", s->alloc_refill); - - total = s->deactivate_full + s->deactivate_empty + - s->deactivate_to_head + s->deactivate_to_tail; - - if (total) - printf("Deactivate Full=%lu(%lu%%) Empty=%lu(%lu%%) " - "ToHead=%lu(%lu%%) ToTail=%lu(%lu%%)\n", - s->deactivate_full, (s->deactivate_full * 100) / total, - s->deactivate_empty, (s->deactivate_empty * 100) / total, - s->deactivate_to_head, (s->deactivate_to_head * 100) / total, - s->deactivate_to_tail, (s->deactivate_to_tail * 100) / total); -} - -static void report(struct slabinfo *s) -{ - if (strcmp(s->name, "*") == 0) - return; - - printf("\nSlabcache: %-20s Aliases: %2d Order : %2d Objects: %lu\n", - s->name, s->aliases, s->order, s->objects); - if (s->hwcache_align) - printf("** Hardware cacheline aligned\n"); - if (s->cache_dma) - printf("** Memory is allocated in a special DMA zone\n"); - if (s->destroy_by_rcu) - printf("** Slabs are destroyed via RCU\n"); - if (s->reclaim_account) - printf("** Reclaim accounting active\n"); - - printf("\nSizes (bytes) Slabs Debug Memory\n"); - printf("------------------------------------------------------------------------\n"); - printf("Object : %7d Total : %7ld Sanity Checks : %s Total: %7ld\n", - s->object_size, s->slabs, onoff(s->sanity_checks), - s->slabs * (page_size << s->order)); - printf("SlabObj: %7d Full : %7ld Redzoning : %s Used : %7ld\n", - s->slab_size, s->slabs - s->partial - s->cpu_slabs, - onoff(s->red_zone), s->objects * s->object_size); - printf("SlabSiz: %7d Partial: %7ld Poisoning : %s Loss : %7ld\n", - page_size << s->order, s->partial, onoff(s->poison), - s->slabs * (page_size << s->order) - s->objects * s->object_size); - printf("Loss : %7d CpuSlab: %7d Tracking : %s Lalig: %7ld\n", - s->slab_size - s->object_size, s->cpu_slabs, onoff(s->store_user), - (s->slab_size - s->object_size) * s->objects); - printf("Align : %7d Objects: %7d Tracing : %s Lpadd: %7ld\n", - s->align, s->objs_per_slab, onoff(s->trace), - ((page_size << s->order) - s->objs_per_slab * s->slab_size) * - s->slabs); - - ops(s); - show_tracking(s); - slab_numa(s, 1); - slab_stats(s); -} - -static void slabcache(struct slabinfo *s) -{ - char size_str[20]; - char dist_str[40]; - char flags[20]; - char *p = flags; - - if (strcmp(s->name, "*") == 0) - return; - - if (actual_slabs == 1) { - report(s); - return; - } - - if (skip_zero && !show_empty && !s->slabs) - return; - - if (show_empty && s->slabs) - return; - - store_size(size_str, slab_size(s)); - snprintf(dist_str, 40, "%lu/%lu/%d", s->slabs - s->cpu_slabs, - s->partial, s->cpu_slabs); - - if (!line++) - first_line(); - - if (s->aliases) - *p++ = '*'; - if (s->cache_dma) - *p++ = 'd'; - if (s->hwcache_align) - *p++ = 'A'; - if (s->poison) - *p++ = 'P'; - if (s->reclaim_account) - *p++ = 'a'; - if (s->red_zone) - *p++ = 'Z'; - if (s->sanity_checks) - *p++ = 'F'; - if (s->store_user) - *p++ = 'U'; - if (s->trace) - *p++ = 'T'; - - *p = 0; - if (show_activity) { - unsigned long total_alloc; - unsigned long total_free; - - total_alloc = s->alloc_fastpath + s->alloc_slowpath; - total_free = s->free_fastpath + s->free_slowpath; - - printf("%-21s %8ld %10ld %10ld %3ld %3ld %5ld %1d\n", - s->name, s->objects, - total_alloc, total_free, - total_alloc ? (s->alloc_fastpath * 100 / total_alloc) : 0, - total_free ? (s->free_fastpath * 100 / total_free) : 0, - s->order_fallback, s->order); - } - else - printf("%-21s %8ld %7d %8s %14s %4d %1d %3ld %3ld %s\n", - s->name, s->objects, s->object_size, size_str, dist_str, - s->objs_per_slab, s->order, - s->slabs ? (s->partial * 100) / s->slabs : 100, - s->slabs ? (s->objects * s->object_size * 100) / - (s->slabs * (page_size << s->order)) : 100, - flags); -} - -/* - * Analyze debug options. Return false if something is amiss. - */ -static int debug_opt_scan(char *opt) -{ - if (!opt || !opt[0] || strcmp(opt, "-") == 0) - return 1; - - if (strcasecmp(opt, "a") == 0) { - sanity = 1; - poison = 1; - redzone = 1; - tracking = 1; - return 1; - } - - for ( ; *opt; opt++) - switch (*opt) { - case 'F' : case 'f': - if (sanity) - return 0; - sanity = 1; - break; - case 'P' : case 'p': - if (poison) - return 0; - poison = 1; - break; - - case 'Z' : case 'z': - if (redzone) - return 0; - redzone = 1; - break; - - case 'U' : case 'u': - if (tracking) - return 0; - tracking = 1; - break; - - case 'T' : case 't': - if (tracing) - return 0; - tracing = 1; - break; - default: - return 0; - } - return 1; -} - -static int slab_empty(struct slabinfo *s) -{ - if (s->objects > 0) - return 0; - - /* - * We may still have slabs even if there are no objects. Shrinking will - * remove them. - */ - if (s->slabs != 0) - set_obj(s, "shrink", 1); - - return 1; -} - -static void slab_debug(struct slabinfo *s) -{ - if (strcmp(s->name, "*") == 0) - return; - - if (sanity && !s->sanity_checks) { - set_obj(s, "sanity", 1); - } - if (!sanity && s->sanity_checks) { - if (slab_empty(s)) - set_obj(s, "sanity", 0); - else - fprintf(stderr, "%s not empty cannot disable sanity checks\n", s->name); - } - if (redzone && !s->red_zone) { - if (slab_empty(s)) - set_obj(s, "red_zone", 1); - else - fprintf(stderr, "%s not empty cannot enable redzoning\n", s->name); - } - if (!redzone && s->red_zone) { - if (slab_empty(s)) - set_obj(s, "red_zone", 0); - else - fprintf(stderr, "%s not empty cannot disable redzoning\n", s->name); - } - if (poison && !s->poison) { - if (slab_empty(s)) - set_obj(s, "poison", 1); - else - fprintf(stderr, "%s not empty cannot enable poisoning\n", s->name); - } - if (!poison && s->poison) { - if (slab_empty(s)) - set_obj(s, "poison", 0); - else - fprintf(stderr, "%s not empty cannot disable poisoning\n", s->name); - } - if (tracking && !s->store_user) { - if (slab_empty(s)) - set_obj(s, "store_user", 1); - else - fprintf(stderr, "%s not empty cannot enable tracking\n", s->name); - } - if (!tracking && s->store_user) { - if (slab_empty(s)) - set_obj(s, "store_user", 0); - else - fprintf(stderr, "%s not empty cannot disable tracking\n", s->name); - } - if (tracing && !s->trace) { - if (slabs == 1) - set_obj(s, "trace", 1); - else - fprintf(stderr, "%s can only enable trace for one slab at a time\n", s->name); - } - if (!tracing && s->trace) - set_obj(s, "trace", 1); -} - -static void totals(void) -{ - struct slabinfo *s; - - int used_slabs = 0; - char b1[20], b2[20], b3[20], b4[20]; - unsigned long long max = 1ULL << 63; - - /* Object size */ - unsigned long long min_objsize = max, max_objsize = 0, avg_objsize; - - /* Number of partial slabs in a slabcache */ - unsigned long long min_partial = max, max_partial = 0, - avg_partial, total_partial = 0; - - /* Number of slabs in a slab cache */ - unsigned long long min_slabs = max, max_slabs = 0, - avg_slabs, total_slabs = 0; - - /* Size of the whole slab */ - unsigned long long min_size = max, max_size = 0, - avg_size, total_size = 0; - - /* Bytes used for object storage in a slab */ - unsigned long long min_used = max, max_used = 0, - avg_used, total_used = 0; - - /* Waste: Bytes used for alignment and padding */ - unsigned long long min_waste = max, max_waste = 0, - avg_waste, total_waste = 0; - /* Number of objects in a slab */ - unsigned long long min_objects = max, max_objects = 0, - avg_objects, total_objects = 0; - /* Waste per object */ - unsigned long long min_objwaste = max, - max_objwaste = 0, avg_objwaste, - total_objwaste = 0; - - /* Memory per object */ - unsigned long long min_memobj = max, - max_memobj = 0, avg_memobj, - total_objsize = 0; - - /* Percentage of partial slabs per slab */ - unsigned long min_ppart = 100, max_ppart = 0, - avg_ppart, total_ppart = 0; - - /* Number of objects in partial slabs */ - unsigned long min_partobj = max, max_partobj = 0, - avg_partobj, total_partobj = 0; - - /* Percentage of partial objects of all objects in a slab */ - unsigned long min_ppartobj = 100, max_ppartobj = 0, - avg_ppartobj, total_ppartobj = 0; - - - for (s = slabinfo; s < slabinfo + slabs; s++) { - unsigned long long size; - unsigned long used; - unsigned long long wasted; - unsigned long long objwaste; - unsigned long percentage_partial_slabs; - unsigned long percentage_partial_objs; - - if (!s->slabs || !s->objects) - continue; - - used_slabs++; - - size = slab_size(s); - used = s->objects * s->object_size; - wasted = size - used; - objwaste = s->slab_size - s->object_size; - - percentage_partial_slabs = s->partial * 100 / s->slabs; - if (percentage_partial_slabs > 100) - percentage_partial_slabs = 100; - - percentage_partial_objs = s->objects_partial * 100 - / s->objects; - - if (percentage_partial_objs > 100) - percentage_partial_objs = 100; - - if (s->object_size < min_objsize) - min_objsize = s->object_size; - if (s->partial < min_partial) - min_partial = s->partial; - if (s->slabs < min_slabs) - min_slabs = s->slabs; - if (size < min_size) - min_size = size; - if (wasted < min_waste) - min_waste = wasted; - if (objwaste < min_objwaste) - min_objwaste = objwaste; - if (s->objects < min_objects) - min_objects = s->objects; - if (used < min_used) - min_used = used; - if (s->objects_partial < min_partobj) - min_partobj = s->objects_partial; - if (percentage_partial_slabs < min_ppart) - min_ppart = percentage_partial_slabs; - if (percentage_partial_objs < min_ppartobj) - min_ppartobj = percentage_partial_objs; - if (s->slab_size < min_memobj) - min_memobj = s->slab_size; - - if (s->object_size > max_objsize) - max_objsize = s->object_size; - if (s->partial > max_partial) - max_partial = s->partial; - if (s->slabs > max_slabs) - max_slabs = s->slabs; - if (size > max_size) - max_size = size; - if (wasted > max_waste) - max_waste = wasted; - if (objwaste > max_objwaste) - max_objwaste = objwaste; - if (s->objects > max_objects) - max_objects = s->objects; - if (used > max_used) - max_used = used; - if (s->objects_partial > max_partobj) - max_partobj = s->objects_partial; - if (percentage_partial_slabs > max_ppart) - max_ppart = percentage_partial_slabs; - if (percentage_partial_objs > max_ppartobj) - max_ppartobj = percentage_partial_objs; - if (s->slab_size > max_memobj) - max_memobj = s->slab_size; - - total_partial += s->partial; - total_slabs += s->slabs; - total_size += size; - total_waste += wasted; - - total_objects += s->objects; - total_used += used; - total_partobj += s->objects_partial; - total_ppart += percentage_partial_slabs; - total_ppartobj += percentage_partial_objs; - - total_objwaste += s->objects * objwaste; - total_objsize += s->objects * s->slab_size; - } - - if (!total_objects) { - printf("No objects\n"); - return; - } - if (!used_slabs) { - printf("No slabs\n"); - return; - } - - /* Per slab averages */ - avg_partial = total_partial / used_slabs; - avg_slabs = total_slabs / used_slabs; - avg_size = total_size / used_slabs; - avg_waste = total_waste / used_slabs; - - avg_objects = total_objects / used_slabs; - avg_used = total_used / used_slabs; - avg_partobj = total_partobj / used_slabs; - avg_ppart = total_ppart / used_slabs; - avg_ppartobj = total_ppartobj / used_slabs; - - /* Per object object sizes */ - avg_objsize = total_used / total_objects; - avg_objwaste = total_objwaste / total_objects; - avg_partobj = total_partobj * 100 / total_objects; - avg_memobj = total_objsize / total_objects; - - printf("Slabcache Totals\n"); - printf("----------------\n"); - printf("Slabcaches : %3d Aliases : %3d->%-3d Active: %3d\n", - slabs, aliases, alias_targets, used_slabs); - - store_size(b1, total_size);store_size(b2, total_waste); - store_size(b3, total_waste * 100 / total_used); - printf("Memory used: %6s # Loss : %6s MRatio:%6s%%\n", b1, b2, b3); - - store_size(b1, total_objects);store_size(b2, total_partobj); - store_size(b3, total_partobj * 100 / total_objects); - printf("# Objects : %6s # PartObj: %6s ORatio:%6s%%\n", b1, b2, b3); - - printf("\n"); - printf("Per Cache Average Min Max Total\n"); - printf("---------------------------------------------------------\n"); - - store_size(b1, avg_objects);store_size(b2, min_objects); - store_size(b3, max_objects);store_size(b4, total_objects); - printf("#Objects %10s %10s %10s %10s\n", - b1, b2, b3, b4); - - store_size(b1, avg_slabs);store_size(b2, min_slabs); - store_size(b3, max_slabs);store_size(b4, total_slabs); - printf("#Slabs %10s %10s %10s %10s\n", - b1, b2, b3, b4); - - store_size(b1, avg_partial);store_size(b2, min_partial); - store_size(b3, max_partial);store_size(b4, total_partial); - printf("#PartSlab %10s %10s %10s %10s\n", - b1, b2, b3, b4); - store_size(b1, avg_ppart);store_size(b2, min_ppart); - store_size(b3, max_ppart); - store_size(b4, total_partial * 100 / total_slabs); - printf("%%PartSlab%10s%% %10s%% %10s%% %10s%%\n", - b1, b2, b3, b4); - - store_size(b1, avg_partobj);store_size(b2, min_partobj); - store_size(b3, max_partobj); - store_size(b4, total_partobj); - printf("PartObjs %10s %10s %10s %10s\n", - b1, b2, b3, b4); - - store_size(b1, avg_ppartobj);store_size(b2, min_ppartobj); - store_size(b3, max_ppartobj); - store_size(b4, total_partobj * 100 / total_objects); - printf("%% PartObj%10s%% %10s%% %10s%% %10s%%\n", - b1, b2, b3, b4); - - store_size(b1, avg_size);store_size(b2, min_size); - store_size(b3, max_size);store_size(b4, total_size); - printf("Memory %10s %10s %10s %10s\n", - b1, b2, b3, b4); - - store_size(b1, avg_used);store_size(b2, min_used); - store_size(b3, max_used);store_size(b4, total_used); - printf("Used %10s %10s %10s %10s\n", - b1, b2, b3, b4); - - store_size(b1, avg_waste);store_size(b2, min_waste); - store_size(b3, max_waste);store_size(b4, total_waste); - printf("Loss %10s %10s %10s %10s\n", - b1, b2, b3, b4); - - printf("\n"); - printf("Per Object Average Min Max\n"); - printf("---------------------------------------------\n"); - - store_size(b1, avg_memobj);store_size(b2, min_memobj); - store_size(b3, max_memobj); - printf("Memory %10s %10s %10s\n", - b1, b2, b3); - store_size(b1, avg_objsize);store_size(b2, min_objsize); - store_size(b3, max_objsize); - printf("User %10s %10s %10s\n", - b1, b2, b3); - - store_size(b1, avg_objwaste);store_size(b2, min_objwaste); - store_size(b3, max_objwaste); - printf("Loss %10s %10s %10s\n", - b1, b2, b3); -} - -static void sort_slabs(void) -{ - struct slabinfo *s1,*s2; - - for (s1 = slabinfo; s1 < slabinfo + slabs; s1++) { - for (s2 = s1 + 1; s2 < slabinfo + slabs; s2++) { - int result; - - if (sort_size) - result = slab_size(s1) < slab_size(s2); - else if (sort_active) - result = slab_activity(s1) < slab_activity(s2); - else - result = strcasecmp(s1->name, s2->name); - - if (show_inverted) - result = -result; - - if (result > 0) { - struct slabinfo t; - - memcpy(&t, s1, sizeof(struct slabinfo)); - memcpy(s1, s2, sizeof(struct slabinfo)); - memcpy(s2, &t, sizeof(struct slabinfo)); - } - } - } -} - -static void sort_aliases(void) -{ - struct aliasinfo *a1,*a2; - - for (a1 = aliasinfo; a1 < aliasinfo + aliases; a1++) { - for (a2 = a1 + 1; a2 < aliasinfo + aliases; a2++) { - char *n1, *n2; - - n1 = a1->name; - n2 = a2->name; - if (show_alias && !show_inverted) { - n1 = a1->ref; - n2 = a2->ref; - } - if (strcasecmp(n1, n2) > 0) { - struct aliasinfo t; - - memcpy(&t, a1, sizeof(struct aliasinfo)); - memcpy(a1, a2, sizeof(struct aliasinfo)); - memcpy(a2, &t, sizeof(struct aliasinfo)); - } - } - } -} - -static void link_slabs(void) -{ - struct aliasinfo *a; - struct slabinfo *s; - - for (a = aliasinfo; a < aliasinfo + aliases; a++) { - - for (s = slabinfo; s < slabinfo + slabs; s++) - if (strcmp(a->ref, s->name) == 0) { - a->slab = s; - s->refs++; - break; - } - if (s == slabinfo + slabs) - fatal("Unresolved alias %s\n", a->ref); - } -} - -static void alias(void) -{ - struct aliasinfo *a; - char *active = NULL; - - sort_aliases(); - link_slabs(); - - for(a = aliasinfo; a < aliasinfo + aliases; a++) { - - if (!show_single_ref && a->slab->refs == 1) - continue; - - if (!show_inverted) { - if (active) { - if (strcmp(a->slab->name, active) == 0) { - printf(" %s", a->name); - continue; - } - } - printf("\n%-12s <- %s", a->slab->name, a->name); - active = a->slab->name; - } - else - printf("%-20s -> %s\n", a->name, a->slab->name); - } - if (active) - printf("\n"); -} - - -static void rename_slabs(void) -{ - struct slabinfo *s; - struct aliasinfo *a; - - for (s = slabinfo; s < slabinfo + slabs; s++) { - if (*s->name != ':') - continue; - - if (s->refs > 1 && !show_first_alias) - continue; - - a = find_one_alias(s); - - if (a) - s->name = a->name; - else { - s->name = "*"; - actual_slabs--; - } - } -} - -static int slab_mismatch(char *slab) -{ - return regexec(&pattern, slab, 0, NULL, 0); -} - -static void read_slab_dir(void) -{ - DIR *dir; - struct dirent *de; - struct slabinfo *slab = slabinfo; - struct aliasinfo *alias = aliasinfo; - char *p; - char *t; - int count; - - if (chdir("/sys/kernel/slab") && chdir("/sys/slab")) - fatal("SYSFS support for SLUB not active\n"); - - dir = opendir("."); - while ((de = readdir(dir))) { - if (de->d_name[0] == '.' || - (de->d_name[0] != ':' && slab_mismatch(de->d_name))) - continue; - switch (de->d_type) { - case DT_LNK: - alias->name = strdup(de->d_name); - count = readlink(de->d_name, buffer, sizeof(buffer)); - - if (count < 0) - fatal("Cannot read symlink %s\n", de->d_name); - - buffer[count] = 0; - p = buffer + count; - while (p > buffer && p[-1] != '/') - p--; - alias->ref = strdup(p); - alias++; - break; - case DT_DIR: - if (chdir(de->d_name)) - fatal("Unable to access slab %s\n", slab->name); - slab->name = strdup(de->d_name); - slab->alias = 0; - slab->refs = 0; - slab->aliases = get_obj("aliases"); - slab->align = get_obj("align"); - slab->cache_dma = get_obj("cache_dma"); - slab->cpu_slabs = get_obj("cpu_slabs"); - slab->destroy_by_rcu = get_obj("destroy_by_rcu"); - slab->hwcache_align = get_obj("hwcache_align"); - slab->object_size = get_obj("object_size"); - slab->objects = get_obj("objects"); - slab->objects_partial = get_obj("objects_partial"); - slab->objects_total = get_obj("objects_total"); - slab->objs_per_slab = get_obj("objs_per_slab"); - slab->order = get_obj("order"); - slab->partial = get_obj("partial"); - slab->partial = get_obj_and_str("partial", &t); - decode_numa_list(slab->numa_partial, t); - free(t); - slab->poison = get_obj("poison"); - slab->reclaim_account = get_obj("reclaim_account"); - slab->red_zone = get_obj("red_zone"); - slab->sanity_checks = get_obj("sanity_checks"); - slab->slab_size = get_obj("slab_size"); - slab->slabs = get_obj_and_str("slabs", &t); - decode_numa_list(slab->numa, t); - free(t); - slab->store_user = get_obj("store_user"); - slab->trace = get_obj("trace"); - slab->alloc_fastpath = get_obj("alloc_fastpath"); - slab->alloc_slowpath = get_obj("alloc_slowpath"); - slab->free_fastpath = get_obj("free_fastpath"); - slab->free_slowpath = get_obj("free_slowpath"); - slab->free_frozen= get_obj("free_frozen"); - slab->free_add_partial = get_obj("free_add_partial"); - slab->free_remove_partial = get_obj("free_remove_partial"); - slab->alloc_from_partial = get_obj("alloc_from_partial"); - slab->alloc_slab = get_obj("alloc_slab"); - slab->alloc_refill = get_obj("alloc_refill"); - slab->free_slab = get_obj("free_slab"); - slab->cpuslab_flush = get_obj("cpuslab_flush"); - slab->deactivate_full = get_obj("deactivate_full"); - slab->deactivate_empty = get_obj("deactivate_empty"); - slab->deactivate_to_head = get_obj("deactivate_to_head"); - slab->deactivate_to_tail = get_obj("deactivate_to_tail"); - slab->deactivate_remote_frees = get_obj("deactivate_remote_frees"); - slab->order_fallback = get_obj("order_fallback"); - chdir(".."); - if (slab->name[0] == ':') - alias_targets++; - slab++; - break; - default : - fatal("Unknown file type %lx\n", de->d_type); - } - } - closedir(dir); - slabs = slab - slabinfo; - actual_slabs = slabs; - aliases = alias - aliasinfo; - if (slabs > MAX_SLABS) - fatal("Too many slabs\n"); - if (aliases > MAX_ALIASES) - fatal("Too many aliases\n"); -} - -static void output_slabs(void) -{ - struct slabinfo *slab; - - for (slab = slabinfo; slab < slabinfo + slabs; slab++) { - - if (slab->alias) - continue; - - - if (show_numa) - slab_numa(slab, 0); - else if (show_track) - show_tracking(slab); - else if (validate) - slab_validate(slab); - else if (shrink) - slab_shrink(slab); - else if (set_debug) - slab_debug(slab); - else if (show_ops) - ops(slab); - else if (show_slab) - slabcache(slab); - else if (show_report) - report(slab); - } -} - -struct option opts[] = { - { "aliases", 0, NULL, 'a' }, - { "activity", 0, NULL, 'A' }, - { "debug", 2, NULL, 'd' }, - { "display-activity", 0, NULL, 'D' }, - { "empty", 0, NULL, 'e' }, - { "first-alias", 0, NULL, 'f' }, - { "help", 0, NULL, 'h' }, - { "inverted", 0, NULL, 'i'}, - { "numa", 0, NULL, 'n' }, - { "ops", 0, NULL, 'o' }, - { "report", 0, NULL, 'r' }, - { "shrink", 0, NULL, 's' }, - { "slabs", 0, NULL, 'l' }, - { "track", 0, NULL, 't'}, - { "validate", 0, NULL, 'v' }, - { "zero", 0, NULL, 'z' }, - { "1ref", 0, NULL, '1'}, - { NULL, 0, NULL, 0 } -}; - -int main(int argc, char *argv[]) -{ - int c; - int err; - char *pattern_source; - - page_size = getpagesize(); - - while ((c = getopt_long(argc, argv, "aAd::Defhil1noprstvzTS", - opts, NULL)) != -1) - switch (c) { - case '1': - show_single_ref = 1; - break; - case 'a': - show_alias = 1; - break; - case 'A': - sort_active = 1; - break; - case 'd': - set_debug = 1; - if (!debug_opt_scan(optarg)) - fatal("Invalid debug option '%s'\n", optarg); - break; - case 'D': - show_activity = 1; - break; - case 'e': - show_empty = 1; - break; - case 'f': - show_first_alias = 1; - break; - case 'h': - usage(); - return 0; - case 'i': - show_inverted = 1; - break; - case 'n': - show_numa = 1; - break; - case 'o': - show_ops = 1; - break; - case 'r': - show_report = 1; - break; - case 's': - shrink = 1; - break; - case 'l': - show_slab = 1; - break; - case 't': - show_track = 1; - break; - case 'v': - validate = 1; - break; - case 'z': - skip_zero = 0; - break; - case 'T': - show_totals = 1; - break; - case 'S': - sort_size = 1; - break; - - default: - fatal("%s: Invalid option '%c'\n", argv[0], optopt); - - } - - if (!show_slab && !show_alias && !show_track && !show_report - && !validate && !shrink && !set_debug && !show_ops) - show_slab = 1; - - if (argc > optind) - pattern_source = argv[optind]; - else - pattern_source = ".*"; - - err = regcomp(&pattern, pattern_source, REG_ICASE|REG_NOSUB); - if (err) - fatal("%s: Invalid pattern '%s' code %d\n", - argv[0], pattern_source, err); - read_slab_dir(); - if (show_alias) - alias(); - else - if (show_totals) - totals(); - else { - link_slabs(); - rename_slabs(); - sort_slabs(); - output_slabs(); - } - return 0; -} diff --git a/Documentation/vm/transhuge.txt b/Documentation/vm/transhuge.txt new file mode 100644 index 000000000000..0924aaca3302 --- /dev/null +++ b/Documentation/vm/transhuge.txt @@ -0,0 +1,298 @@ += Transparent Hugepage Support = + +== Objective == + +Performance critical computing applications dealing with large memory +working sets are already running on top of libhugetlbfs and in turn +hugetlbfs. Transparent Hugepage Support is an alternative means of +using huge pages for the backing of virtual memory with huge pages +that supports the automatic promotion and demotion of page sizes and +without the shortcomings of hugetlbfs. + +Currently it only works for anonymous memory mappings but in the +future it can expand over the pagecache layer starting with tmpfs. + +The reason applications are running faster is because of two +factors. The first factor is almost completely irrelevant and it's not +of significant interest because it'll also have the downside of +requiring larger clear-page copy-page in page faults which is a +potentially negative effect. The first factor consists in taking a +single page fault for each 2M virtual region touched by userland (so +reducing the enter/exit kernel frequency by a 512 times factor). This +only matters the first time the memory is accessed for the lifetime of +a memory mapping. The second long lasting and much more important +factor will affect all subsequent accesses to the memory for the whole +runtime of the application. The second factor consist of two +components: 1) the TLB miss will run faster (especially with +virtualization using nested pagetables but almost always also on bare +metal without virtualization) and 2) a single TLB entry will be +mapping a much larger amount of virtual memory in turn reducing the +number of TLB misses. With virtualization and nested pagetables the +TLB can be mapped of larger size only if both KVM and the Linux guest +are using hugepages but a significant speedup already happens if only +one of the two is using hugepages just because of the fact the TLB +miss is going to run faster. + +== Design == + +- "graceful fallback": mm components which don't have transparent + hugepage knowledge fall back to breaking a transparent hugepage and + working on the regular pages and their respective regular pmd/pte + mappings + +- if a hugepage allocation fails because of memory fragmentation, + regular pages should be gracefully allocated instead and mixed in + the same vma without any failure or significant delay and without + userland noticing + +- if some task quits and more hugepages become available (either + immediately in the buddy or through the VM), guest physical memory + backed by regular pages should be relocated on hugepages + automatically (with khugepaged) + +- it doesn't require memory reservation and in turn it uses hugepages + whenever possible (the only possible reservation here is kernelcore= + to avoid unmovable pages to fragment all the memory but such a tweak + is not specific to transparent hugepage support and it's a generic + feature that applies to all dynamic high order allocations in the + kernel) + +- this initial support only offers the feature in the anonymous memory + regions but it'd be ideal to move it to tmpfs and the pagecache + later + +Transparent Hugepage Support maximizes the usefulness of free memory +if compared to the reservation approach of hugetlbfs by allowing all +unused memory to be used as cache or other movable (or even unmovable +entities). It doesn't require reservation to prevent hugepage +allocation failures to be noticeable from userland. It allows paging +and all other advanced VM features to be available on the +hugepages. It requires no modifications for applications to take +advantage of it. + +Applications however can be further optimized to take advantage of +this feature, like for example they've been optimized before to avoid +a flood of mmap system calls for every malloc(4k). Optimizing userland +is by far not mandatory and khugepaged already can take care of long +lived page allocations even for hugepage unaware applications that +deals with large amounts of memory. + +In certain cases when hugepages are enabled system wide, application +may end up allocating more memory resources. An application may mmap a +large region but only touch 1 byte of it, in that case a 2M page might +be allocated instead of a 4k page for no good. This is why it's +possible to disable hugepages system-wide and to only have them inside +MADV_HUGEPAGE madvise regions. + +Embedded systems should enable hugepages only inside madvise regions +to eliminate any risk of wasting any precious byte of memory and to +only run faster. + +Applications that gets a lot of benefit from hugepages and that don't +risk to lose memory by using hugepages, should use +madvise(MADV_HUGEPAGE) on their critical mmapped regions. + +== sysfs == + +Transparent Hugepage Support can be entirely disabled (mostly for +debugging purposes) or only enabled inside MADV_HUGEPAGE regions (to +avoid the risk of consuming more memory resources) or enabled system +wide. This can be achieved with one of: + +echo always >/sys/kernel/mm/transparent_hugepage/enabled +echo madvise >/sys/kernel/mm/transparent_hugepage/enabled +echo never >/sys/kernel/mm/transparent_hugepage/enabled + +It's also possible to limit defrag efforts in the VM to generate +hugepages in case they're not immediately free to madvise regions or +to never try to defrag memory and simply fallback to regular pages +unless hugepages are immediately available. Clearly if we spend CPU +time to defrag memory, we would expect to gain even more by the fact +we use hugepages later instead of regular pages. This isn't always +guaranteed, but it may be more likely in case the allocation is for a +MADV_HUGEPAGE region. + +echo always >/sys/kernel/mm/transparent_hugepage/defrag +echo madvise >/sys/kernel/mm/transparent_hugepage/defrag +echo never >/sys/kernel/mm/transparent_hugepage/defrag + +khugepaged will be automatically started when +transparent_hugepage/enabled is set to "always" or "madvise, and it'll +be automatically shutdown if it's set to "never". + +khugepaged runs usually at low frequency so while one may not want to +invoke defrag algorithms synchronously during the page faults, it +should be worth invoking defrag at least in khugepaged. However it's +also possible to disable defrag in khugepaged: + +echo yes >/sys/kernel/mm/transparent_hugepage/khugepaged/defrag +echo no >/sys/kernel/mm/transparent_hugepage/khugepaged/defrag + +You can also control how many pages khugepaged should scan at each +pass: + +/sys/kernel/mm/transparent_hugepage/khugepaged/pages_to_scan + +and how many milliseconds to wait in khugepaged between each pass (you +can set this to 0 to run khugepaged at 100% utilization of one core): + +/sys/kernel/mm/transparent_hugepage/khugepaged/scan_sleep_millisecs + +and how many milliseconds to wait in khugepaged if there's an hugepage +allocation failure to throttle the next allocation attempt. + +/sys/kernel/mm/transparent_hugepage/khugepaged/alloc_sleep_millisecs + +The khugepaged progress can be seen in the number of pages collapsed: + +/sys/kernel/mm/transparent_hugepage/khugepaged/pages_collapsed + +for each pass: + +/sys/kernel/mm/transparent_hugepage/khugepaged/full_scans + +== Boot parameter == + +You can change the sysfs boot time defaults of Transparent Hugepage +Support by passing the parameter "transparent_hugepage=always" or +"transparent_hugepage=madvise" or "transparent_hugepage=never" +(without "") to the kernel command line. + +== Need of application restart == + +The transparent_hugepage/enabled values only affect future +behavior. So to make them effective you need to restart any +application that could have been using hugepages. This also applies to +the regions registered in khugepaged. + +== get_user_pages and follow_page == + +get_user_pages and follow_page if run on a hugepage, will return the +head or tail pages as usual (exactly as they would do on +hugetlbfs). Most gup users will only care about the actual physical +address of the page and its temporary pinning to release after the I/O +is complete, so they won't ever notice the fact the page is huge. But +if any driver is going to mangle over the page structure of the tail +page (like for checking page->mapping or other bits that are relevant +for the head page and not the tail page), it should be updated to jump +to check head page instead (while serializing properly against +split_huge_page() to avoid the head and tail pages to disappear from +under it, see the futex code to see an example of that, hugetlbfs also +needed special handling in futex code for similar reasons). + +NOTE: these aren't new constraints to the GUP API, and they match the +same constrains that applies to hugetlbfs too, so any driver capable +of handling GUP on hugetlbfs will also work fine on transparent +hugepage backed mappings. + +In case you can't handle compound pages if they're returned by +follow_page, the FOLL_SPLIT bit can be specified as parameter to +follow_page, so that it will split the hugepages before returning +them. Migration for example passes FOLL_SPLIT as parameter to +follow_page because it's not hugepage aware and in fact it can't work +at all on hugetlbfs (but it instead works fine on transparent +hugepages thanks to FOLL_SPLIT). migration simply can't deal with +hugepages being returned (as it's not only checking the pfn of the +page and pinning it during the copy but it pretends to migrate the +memory in regular page sizes and with regular pte/pmd mappings). + +== Optimizing the applications == + +To be guaranteed that the kernel will map a 2M page immediately in any +memory region, the mmap region has to be hugepage naturally +aligned. posix_memalign() can provide that guarantee. + +== Hugetlbfs == + +You can use hugetlbfs on a kernel that has transparent hugepage +support enabled just fine as always. No difference can be noted in +hugetlbfs other than there will be less overall fragmentation. All +usual features belonging to hugetlbfs are preserved and +unaffected. libhugetlbfs will also work fine as usual. + +== Graceful fallback == + +Code walking pagetables but unware about huge pmds can simply call +split_huge_page_pmd(mm, pmd) where the pmd is the one returned by +pmd_offset. It's trivial to make the code transparent hugepage aware +by just grepping for "pmd_offset" and adding split_huge_page_pmd where +missing after pmd_offset returns the pmd. Thanks to the graceful +fallback design, with a one liner change, you can avoid to write +hundred if not thousand of lines of complex code to make your code +hugepage aware. + +If you're not walking pagetables but you run into a physical hugepage +but you can't handle it natively in your code, you can split it by +calling split_huge_page(page). This is what the Linux VM does before +it tries to swapout the hugepage for example. + +Example to make mremap.c transparent hugepage aware with a one liner +change: + +diff --git a/mm/mremap.c b/mm/mremap.c +--- a/mm/mremap.c ++++ b/mm/mremap.c +@@ -41,6 +41,7 @@ static pmd_t *get_old_pmd(struct mm_stru + return NULL; + + pmd = pmd_offset(pud, addr); ++ split_huge_page_pmd(mm, pmd); + if (pmd_none_or_clear_bad(pmd)) + return NULL; + +== Locking in hugepage aware code == + +We want as much code as possible hugepage aware, as calling +split_huge_page() or split_huge_page_pmd() has a cost. + +To make pagetable walks huge pmd aware, all you need to do is to call +pmd_trans_huge() on the pmd returned by pmd_offset. You must hold the +mmap_sem in read (or write) mode to be sure an huge pmd cannot be +created from under you by khugepaged (khugepaged collapse_huge_page +takes the mmap_sem in write mode in addition to the anon_vma lock). If +pmd_trans_huge returns false, you just fallback in the old code +paths. If instead pmd_trans_huge returns true, you have to take the +mm->page_table_lock and re-run pmd_trans_huge. Taking the +page_table_lock will prevent the huge pmd to be converted into a +regular pmd from under you (split_huge_page can run in parallel to the +pagetable walk). If the second pmd_trans_huge returns false, you +should just drop the page_table_lock and fallback to the old code as +before. Otherwise you should run pmd_trans_splitting on the pmd. In +case pmd_trans_splitting returns true, it means split_huge_page is +already in the middle of splitting the page. So if pmd_trans_splitting +returns true it's enough to drop the page_table_lock and call +wait_split_huge_page and then fallback the old code paths. You are +guaranteed by the time wait_split_huge_page returns, the pmd isn't +huge anymore. If pmd_trans_splitting returns false, you can proceed to +process the huge pmd and the hugepage natively. Once finished you can +drop the page_table_lock. + +== compound_lock, get_user_pages and put_page == + +split_huge_page internally has to distribute the refcounts in the head +page to the tail pages before clearing all PG_head/tail bits from the +page structures. It can do that easily for refcounts taken by huge pmd +mappings. But the GUI API as created by hugetlbfs (that returns head +and tail pages if running get_user_pages on an address backed by any +hugepage), requires the refcount to be accounted on the tail pages and +not only in the head pages, if we want to be able to run +split_huge_page while there are gup pins established on any tail +page. Failure to be able to run split_huge_page if there's any gup pin +on any tail page, would mean having to split all hugepages upfront in +get_user_pages which is unacceptable as too many gup users are +performance critical and they must work natively on hugepages like +they work natively on hugetlbfs already (hugetlbfs is simpler because +hugetlbfs pages cannot be splitted so there wouldn't be requirement of +accounting the pins on the tail pages for hugetlbfs). If we wouldn't +account the gup refcounts on the tail pages during gup, we won't know +anymore which tail page is pinned by gup and which is not while we run +split_huge_page. But we still have to add the gup pin to the head page +too, to know when we can free the compound page in case it's never +splitted during its lifetime. That requires changing not just +get_page, but put_page as well so that when put_page runs on a tail +page (and only on a tail page) it will find its respective head page, +and then it will decrease the head page refcount in addition to the +tail page refcount. To obtain a head page reliably and to decrease its +refcount without race conditions, put_page has to serialize against +__split_huge_page_refcount using a special per-page lock called +compound_lock. diff --git a/Documentation/vm/unevictable-lru.txt b/Documentation/vm/unevictable-lru.txt index 2d70d0d95108..97bae3c576c2 100644 --- a/Documentation/vm/unevictable-lru.txt +++ b/Documentation/vm/unevictable-lru.txt @@ -84,8 +84,7 @@ indicate that the page is being managed on the unevictable list. The PG_unevictable flag is analogous to, and mutually exclusive with, the PG_active flag in that it indicates on which LRU list a page resides when -PG_lru is set. The unevictable list is compile-time configurable based on the -UNEVICTABLE_LRU Kconfig option. +PG_lru is set. The Unevictable LRU infrastructure maintains unevictable pages on an additional LRU list for a few reasons: diff --git a/Documentation/w1/slaves/00-INDEX b/Documentation/w1/slaves/00-INDEX index f8101d6b07b7..75613c9ac4db 100644 --- a/Documentation/w1/slaves/00-INDEX +++ b/Documentation/w1/slaves/00-INDEX @@ -2,3 +2,5 @@ - This file w1_therm - The Maxim/Dallas Semiconductor ds18*20 temperature sensor. +w1_ds2423 + - The Maxim/Dallas Semiconductor ds2423 counter device. diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423 new file mode 100644 index 000000000000..3f98b505a0ee --- /dev/null +++ b/Documentation/w1/slaves/w1_ds2423 @@ -0,0 +1,47 @@ +Kernel driver w1_ds2423 +======================= + +Supported chips: + * Maxim DS2423 based counter devices. + +supported family codes: + W1_THERM_DS2423 0x1D + +Author: Mika Laitio <lamikr@pilppa.org> + +Description +----------- + +Support is provided through the sysfs w1_slave file. Each opening and +read sequence of w1_slave file initiates the read of counters and ram +available in DS2423 pages 12 - 15. + +Result of each page is provided as an ASCII output where each counter +value and associated ram buffer is outpputed to own line. + +Each lines will contain the values of 42 bytes read from the counter and +memory page along the crc=YES or NO for indicating whether the read operation +was successful and CRC matched. +If the operation was successful, there is also in the end of each line +a counter value expressed as an integer after c= + +Meaning of 42 bytes represented is following: + - 1 byte from ram page + - 4 bytes for the counter value + - 4 zero bytes + - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes + - 31 remaining bytes from the ram page + - crc=YES/NO indicating whether read was ok and crc matched + - c=<int> current counter value + +example from the successful read: +00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 +00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 +00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761 +00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5 + +example from the read with crc errors: +00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 +00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO +00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO +00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1.netlink index 804445f745ed..f59a31965d50 100644 --- a/Documentation/w1/w1.netlink +++ b/Documentation/w1/w1.netlink @@ -81,7 +81,7 @@ which will contain list of all registered master ids in the following format: cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct - w1_netlink_msg) plus number of masters multipled by 4) + w1_netlink_msg) plus number of masters multiplied by 4) w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to number of masters multiplied by 4 (u32 size)) id0 ... idN diff --git a/Documentation/watchdog/hpwdt.txt b/Documentation/watchdog/hpwdt.txt index 9c24d5ffbb06..9488078900e0 100644 --- a/Documentation/watchdog/hpwdt.txt +++ b/Documentation/watchdog/hpwdt.txt @@ -8,7 +8,7 @@ Last reviewed: 06/02/2009 The HP iLO2 NMI Watchdog driver is a kernel module that provides basic watchdog functionality and the added benefit of NMI sourcing. Both the watchdog functionality and the NMI sourcing capability need to be enabled - by the user. Remember that the two modes are not dependant on one another. + by the user. Remember that the two modes are not dependent on one another. A user can have the NMI sourcing without the watchdog timer and vice-versa. Watchdog functionality is enabled like any other common watchdog driver. That diff --git a/Documentation/workqueue.txt b/Documentation/workqueue.txt index e4498a2872c3..a0b577de918f 100644 --- a/Documentation/workqueue.txt +++ b/Documentation/workqueue.txt @@ -12,6 +12,7 @@ CONTENTS 4. Application Programming Interface (API) 5. Example Execution Scenarios 6. Guidelines +7. Debugging 1. Introduction @@ -190,17 +191,17 @@ resources, scheduled and executed. * Long running CPU intensive workloads which can be better managed by the system scheduler. - WQ_FREEZEABLE + WQ_FREEZABLE - A freezeable wq participates in the freeze phase of the system + A freezable 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_RESCUER + WQ_MEM_RECLAIM All wq which might be used in the memory reclaim paths _MUST_ - have this flag set. This reserves one worker exclusively for - the execution of this wq under memory pressure. + have this flag set. The wq is guaranteed to have at least one + execution context regardless of memory pressure. WQ_HIGHPRI @@ -356,11 +357,11 @@ If q1 has WQ_CPU_INTENSIVE set, 6. Guidelines -* Do not forget to use WQ_RESCUER if a wq may process work items which - are used during memory reclaim. Each wq with WQ_RESCUER set has one - rescuer thread 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_RESCUER. +* 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. @@ -368,13 +369,53 @@ If q1 has WQ_CPU_INTENSIVE set, 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_RESCUER), - 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. +* 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. + + +7. Debugging + +Because the work functions are executed by generic worker threads +there are a few tricks needed to shed some light on misbehaving +workqueue users. + +Worker threads show up in the process list as: + +root 5671 0.0 0.0 0 0 ? S 12:07 0:00 [kworker/0:1] +root 5672 0.0 0.0 0 0 ? S 12:07 0:00 [kworker/1:2] +root 5673 0.0 0.0 0 0 ? S 12:12 0:00 [kworker/0:0] +root 5674 0.0 0.0 0 0 ? S 12:13 0:00 [kworker/1:0] + +If kworkers are going crazy (using too much cpu), there are two types +of possible problems: + + 1. Something beeing scheduled in rapid succession + 2. A single work item that consumes lots of cpu cycles + +The first one can be tracked using tracing: + + $ echo workqueue:workqueue_queue_work > /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace_pipe > out.txt + (wait a few secs) + ^C + +If something is busy looping on work queueing, it would be dominating +the output and the offender can be determined with the work item +function. + +For the second type of problems it should be possible to just check +the stack trace of the offending worker thread. + + $ cat /proc/THE_OFFENDING_KWORKER/stack + +The work item's function should be trivially visible in the stack +trace. diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 30b43e1b2697..9b7221a86df2 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -600,6 +600,7 @@ Protocol: 2.07+ 0x00000001 lguest 0x00000002 Xen 0x00000003 Moorestown MID + 0x00000004 CE4100 TV Platform Field name: hardware_subarch_data Type: write (subarch-dependent) @@ -621,9 +622,9 @@ Protocol: 2.08+ The payload may be compressed. The format of both the compressed and uncompressed data should be determined using the standard magic numbers. The currently supported compression formats are gzip - (magic numbers 1F 8B or 1F 9E), bzip2 (magic number 42 5A) and LZMA - (magic number 5D 00). The uncompressed payload is currently always ELF - (magic number 7F 45 4C 46). + (magic numbers 1F 8B or 1F 9E), bzip2 (magic number 42 5A), LZMA + (magic number 5D 00), and XZ (magic number FD 37). The uncompressed + payload is currently always ELF (magic number 7F 45 4C 46). Field name: payload_length Type: read diff --git a/Documentation/x86/x86_64/boot-options.txt b/Documentation/x86/x86_64/boot-options.txt index 7fbbaf85f5b7..092e596a1301 100644 --- a/Documentation/x86/x86_64/boot-options.txt +++ b/Documentation/x86/x86_64/boot-options.txt @@ -189,13 +189,13 @@ ACPI PCI - pci=off Don't use PCI - pci=conf1 Use conf1 access. - pci=conf2 Use conf2 access. - pci=rom Assign ROMs. - pci=assign-busses Assign busses - pci=irqmask=MASK Set PCI interrupt mask to MASK - pci=lastbus=NUMBER Scan upto NUMBER busses, no matter what the mptable says. + pci=off Don't use PCI + pci=conf1 Use conf1 access. + pci=conf2 Use conf2 access. + pci=rom Assign ROMs. + pci=assign-busses Assign busses + pci=irqmask=MASK Set PCI interrupt mask to MASK + pci=lastbus=NUMBER Scan up to NUMBER busses, no matter what the mptable says. pci=noacpi Don't use ACPI to set up PCI interrupt routing. IOMMU (input/output memory management unit) @@ -293,11 +293,6 @@ IOMMU (input/output memory management unit) Debugging - oops=panic Always panic on oopses. Default is to just kill the process, - but there is a small probability of deadlocking the machine. - This will also cause panics on machine check exceptions. - Useful together with panic=30 to trigger a reboot. - kstack=N Print N words from the kernel stack in oops dumps. pagefaulttrace Dump all page faults. Only useful for extreme debugging diff --git a/Documentation/x86/x86_64/kernel-stacks b/Documentation/x86/x86_64/kernel-stacks index 5ad65d51fb95..a01eec5d1d0b 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/xz.txt b/Documentation/xz.txt new file mode 100644 index 000000000000..2cf3e2608de3 --- /dev/null +++ b/Documentation/xz.txt @@ -0,0 +1,121 @@ + +XZ data compression in Linux +============================ + +Introduction + + XZ is a general purpose data compression format with high compression + ratio and relatively fast decompression. The primary compression + algorithm (filter) is LZMA2. Additional filters can be used to improve + compression ratio even further. E.g. Branch/Call/Jump (BCJ) filters + improve compression ratio of executable data. + + The XZ decompressor in Linux is called XZ Embedded. It supports + the LZMA2 filter and optionally also BCJ filters. CRC32 is supported + for integrity checking. The home page of XZ Embedded is at + <http://tukaani.org/xz/embedded.html>, where you can find the + latest version and also information about using the code outside + the Linux kernel. + + For userspace, XZ Utils provide a zlib-like compression library + and a gzip-like command line tool. XZ Utils can be downloaded from + <http://tukaani.org/xz/>. + +XZ related components in the kernel + + The xz_dec module provides XZ decompressor with single-call (buffer + to buffer) and multi-call (stateful) APIs. The usage of the xz_dec + module is documented in include/linux/xz.h. + + The xz_dec_test module is for testing xz_dec. xz_dec_test is not + useful unless you are hacking the XZ decompressor. xz_dec_test + allocates a char device major dynamically to which one can write + .xz files from userspace. The decompressed output is thrown away. + Keep an eye on dmesg to see diagnostics printed by xz_dec_test. + See the xz_dec_test source code for the details. + + For decompressing the kernel image, initramfs, and initrd, there + is a wrapper function in lib/decompress_unxz.c. Its API is the + same as in other decompress_*.c files, which is defined in + include/linux/decompress/generic.h. + + scripts/xz_wrap.sh is a wrapper for the xz command line tool found + from XZ Utils. The wrapper sets compression options to values suitable + for compressing the kernel image. + + For kernel makefiles, two commands are provided for use with + $(call if_needed). The kernel image should be compressed with + $(call if_needed,xzkern) which will use a BCJ filter and a big LZMA2 + dictionary. It will also append a four-byte trailer containing the + uncompressed size of the file, which is needed by the boot code. + Other things should be compressed with $(call if_needed,xzmisc) + which will use no BCJ filter and 1 MiB LZMA2 dictionary. + +Notes on compression options + + Since the XZ Embedded supports only streams with no integrity check or + CRC32, make sure that you don't use some other integrity check type + when encoding files that are supposed to be decoded by the kernel. With + liblzma, you need to use either LZMA_CHECK_NONE or LZMA_CHECK_CRC32 + when encoding. With the xz command line tool, use --check=none or + --check=crc32. + + Using CRC32 is strongly recommended unless there is some other layer + which will verify the integrity of the uncompressed data anyway. + Double checking the integrity would probably be waste of CPU cycles. + Note that the headers will always have a CRC32 which will be validated + by the decoder; you can only change the integrity check type (or + disable it) for the actual uncompressed data. + + In userspace, LZMA2 is typically used with dictionary sizes of several + megabytes. The decoder needs to have the dictionary in RAM, thus big + dictionaries cannot be used for files that are intended to be decoded + by the kernel. 1 MiB is probably the maximum reasonable dictionary + size for in-kernel use (maybe more is OK for initramfs). The presets + in XZ Utils may not be optimal when creating files for the kernel, + so don't hesitate to use custom settings. Example: + + xz --check=crc32 --lzma2=dict=512KiB inputfile + + An exception to above dictionary size limitation is when the decoder + is used in single-call mode. Decompressing the kernel itself is an + example of this situation. In single-call mode, the memory usage + doesn't depend on the dictionary size, and it is perfectly fine to + use a big dictionary: for maximum compression, the dictionary should + be at least as big as the uncompressed data itself. + +Future plans + + Creating a limited XZ encoder may be considered if people think it is + useful. LZMA2 is slower to compress than e.g. Deflate or LZO even at + the fastest settings, so it isn't clear if LZMA2 encoder is wanted + into the kernel. + + Support for limited random-access reading is planned for the + decompression code. I don't know if it could have any use in the + kernel, but I know that it would be useful in some embedded projects + outside the Linux kernel. + +Conformance to the .xz file format specification + + There are a couple of corner cases where things have been simplified + at expense of detecting errors as early as possible. These should not + matter in practice all, since they don't cause security issues. But + it is good to know this if testing the code e.g. with the test files + from XZ Utils. + +Reporting bugs + + Before reporting a bug, please check that it's not fixed already + at upstream. See <http://tukaani.org/xz/embedded.html> to get the + latest code. + + Report bugs to <lasse.collin@tukaani.org> or visit #tukaani on + Freenode and talk to Larhzu. I don't actively read LKML or other + kernel-related mailing lists, so if there's something I should know, + you should email to me personally or use IRC. + + Don't bother Igor Pavlov with questions about the XZ implementation + in the kernel or about XZ Utils. While these two implementations + include essential code that is directly based on Igor Pavlov's code, + these implementations aren't maintained nor supported by him. diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO index 69160779e432..faf976c0c731 100644 --- a/Documentation/zh_CN/HOWTO +++ b/Documentation/zh_CN/HOWTO @@ -347,8 +347,8 @@ bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。 最新bug的通知，可以订阅bugme-new邮件列表（只有新的bug报告会被寄到这里） 或者订阅bugme-janitor邮件列表（所有bugzilla的变动都会被寄到这里）。 - http://lists.osdl.org/mailman/listinfo/bugme-new - http://lists.osdl.org/mailman/listinfo/bugme-janitors + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors 邮件列表 diff --git a/Documentation/zh_CN/SecurityBugs b/Documentation/zh_CN/SecurityBugs new file mode 100644 index 000000000000..d21eb07fe943 --- /dev/null +++ b/Documentation/zh_CN/SecurityBugs @@ -0,0 +1,50 @@ +Chinese translated version of Documentation/SecurityBugs + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: Harry Wei <harryxiyou@gmail.com> +--------------------------------------------------------------------- +Documentation/SecurityBugs 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 贾威威 Harry Wei <harryxiyou@gmail.com> +中文版翻译者： 贾威威 Harry Wei <harryxiyou@gmail.com> +中文版校译者： 贾威威 Harry Wei <harryxiyou@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +Linux内核开发者认为安全非常重要。因此，我们想要知道当一个有关于 +安全的漏洞被发现的时候，并且它可能会被尽快的修复或者公开。请把这个安全 +漏洞报告给Linux内核安全团队。 + +1) 联系 + +linux内核安全团队可以通过email<security@kernel.org>来联系。这是 +一组独立的安全工作人员，可以帮助改善漏洞报告并且公布和取消一个修复。安 +全团队有可能会从部分的维护者那里引进额外的帮助来了解并且修复安全漏洞。 +当遇到任何漏洞，所能提供的信息越多就越能诊断和修复。如果你不清楚什么 +是有帮助的信息，那就请重温一下REPORTING-BUGS文件中的概述过程。任 +何攻击性的代码都是非常有用的，未经报告者的同意不会被取消，除非它已经 +被公布于众。 + +2) 公开 + +Linux内核安全团队的宗旨就是和漏洞提交者一起处理漏洞的解决方案直 +到公开。我们喜欢尽快地完全公开漏洞。当一个漏洞或者修复还没有被完全地理 +解，解决方案没有通过测试或者供应商协调，可以合理地延迟公开。然而，我们 +期望这些延迟尽可能的短些，是可数的几天，而不是几个星期或者几个月。公开 +日期是通过安全团队和漏洞提供者以及供应商洽谈后的结果。公开时间表是从很 +短（特殊的，它已经被公众所知道）到几个星期。作为一个基本的默认政策，我 +们所期望通知公众的日期是7天的安排。 + +3) 保密协议 + +Linux内核安全团队不是一个正式的团体，因此不能加入任何的保密协议。 diff --git a/Documentation/zh_CN/SubmitChecklist b/Documentation/zh_CN/SubmitChecklist new file mode 100644 index 000000000000..951415bbab0c --- /dev/null +++ b/Documentation/zh_CN/SubmitChecklist @@ -0,0 +1,109 @@ +Chinese translated version of Documentation/SubmitChecklist + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: Harry Wei <harryxiyou@gmail.com> +--------------------------------------------------------------------- +Documentation/SubmitChecklist ķ + +ۻ±ĵݣֱϵԭĵάߡʹӢ +ѵĻҲİά²ʱ߷ +⣬ϵİάߡ + +İάߣ Harry Wei <harryxiyou@gmail.com> +İ淭ߣ Harry Wei <harryxiyou@gmail.com> +İУߣ Harry Wei <harryxiyou@gmail.com> + + +Ϊ +--------------------------------------------------------------------- +Linuxںύ嵥 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +һЩں˿ӦĻ飬뿴Լں˲ύ +ܵĸ졣 + +ЩdzDocumentation/SubmittingPatchesĵṩԼ +ύLinuxں˲˵ + +1ʹһô#include/ǸܵǸļ + Ҫ붨/Ǹܵͷļ + +2û߸CONFIGѡ =y=m=n + Ҫб뾯/ ҪӾ/ + +2bͨ allnoconfig, allmodconfig + +2cʹ 0=builddir ɹع + +3ͨʹñؽ빤һЩڶCPUϹ + +4ppc64 һܺõļ齻ĿܣΪѡunsigned long + 64λֵʹá + +5Documentation/CodingStyleļϸ㲹 + ʹòΥ(scripts/checkpatch.pl)Աύ + Ӧõ㲹еΥ档 + +6κθ»߸ĶCONFIGѡܴò˵ + +7еKconfigѡ¶Ҫ˵֡ + +8ѾܽصKconfigϡǺͨõ--½ + +9мԡ + +10ʹ'make checkstack''make namespacecheck'飬Ȼҵ⡣ + ע⣺ջ鲻ȷس⣬κεһڶջʹö512ֽ + Ҫġ + +11kernel-docȫںAPIsļҪ̬ĺǰҲν + ʹ'make htmldocs''make mandocs'kernel-docȻκ + ֵ⡣ + +12ѾͨCONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, + CONFIG_DEBUG_SLAB, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, + CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_SPINLOCK_SLEEPԣͬʱ + ʹܡ + +13Ѿʹû߲ʹ CONFIG_SMP CONFIG_PREEMPTִʱ䡣 + +14ӰIO/DiskȵȣѾͨʹû߲ʹ CONFIG_LBDAF ԡ + +15еcodepathsѾʹlockdepùܡ + +16е/proc¼¶ҪļDocumentation/Ŀ¼¡ + +17еں¶¼Documentation/kernel-parameters.txtļС + +18еģ¶MODULE_PARM_DESC()¼ + +19еûռӿڸ¶¼Documentation/ABI/鿴Documentation/ABI/README + ԻøϢıûռӿڵIJӦñʼlinux-api@vger.kernel.org + +20DzǶͨ`make headers_check' + +21Ѿͨslabpage-allocationʧܼ顣鿴Documentation/fault-injection/ + +22¼ԴѾͨ`gcc -W'ʹ"make EXTRA_CFLAGS=-W"롣ܶෳգ + ǶѰ©洦:"warning: comparison between signed and unsigned" + +23ϲ-mmٲԣȷǷͲеһԼVMVFS + ϵͳи仯 + +24еڴ{e.g., barrier(), rmb(), wmb()}ҪԴеһעǶǸʲô + Լԭ + +25κƵIJӣҲҪDocumentation/ioctl/ioctl-number.txt + +26ĸĴʹκεںAPIskconfigйϵĹܣҪ + ʹصkconfigŹرգ and/or =mѡṩ[ͬһʱ䲻õĶã + ] + + CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI, + CONFIG_BLOCK, CONFIG_PM, CONFIG_HOTPLUG, CONFIG_MAGIC_SYSRQ, + CONFIG_NET, CONFIG_INET=n (һʹ CONFIG_NET=y) diff --git a/Documentation/zh_CN/SubmittingDrivers b/Documentation/zh_CN/SubmittingDrivers index c27b0f6cdd39..5889f8df6312 100644 --- a/Documentation/zh_CN/SubmittingDrivers +++ b/Documentation/zh_CN/SubmittingDrivers @@ -61,7 +61,7 @@ Linux 2.4: Linux 2.6: 除了遵循和 2.4 版内核同样的规则外，你还需要在 linux-kernel 邮件 列表上跟踪最新的 API 变化。向 Linux 2.6 内核提交驱动的顶级联系人 - 是 Andrew Morton <akpm@osdl.org>。 + 是 Andrew Morton <akpm@linux-foundation.org>。 决定设备驱动能否被接受的条件 ---------------------------- diff --git a/Documentation/zh_CN/SubmittingPatches b/Documentation/zh_CN/SubmittingPatches index 9a1a6e1ed09e..0f4385a62a49 100644 --- a/Documentation/zh_CN/SubmittingPatches +++ b/Documentation/zh_CN/SubmittingPatches @@ -100,7 +100,7 @@ http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz 将改动拆分，逻辑类似的放到同一个补丁文件里。 -例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动才分到两个或 +例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动拆分到两个或 者更多的补丁文件中。如果你的改动包含对API的修改，并且修改了驱动程序来适 应这些新的API，那么把这些修改分成两个补丁。 @@ -230,7 +230,7 @@ pref("mailnews.display.disable_format_flowed_support", true); 些原因，修正错误，重新提交更新后的改动，是你自己的工作。 Linus不给出任何评论就“丢弃”你的补丁是常见的事情。在系统中这样的事情很 -平常。如果他没有接受你的补丁，也许是由于以下原本： +平常。如果他没有接受你的补丁，也许是由于以下原因： * 你的补丁不能在最新版本的内核上干净的打上。 * 你的补丁在 linux-kernel 邮件列表中没有得到充分的讨论。 * 风格问题（参照第2小节） diff --git a/Documentation/zh_CN/magic-number.txt b/Documentation/zh_CN/magic-number.txt new file mode 100644 index 000000000000..4c4ce853577b --- /dev/null +++ b/Documentation/zh_CN/magic-number.txt @@ -0,0 +1,167 @@ +Chinese translated version of Documentation/magic-number.txt + +If you have any comment or update to the content, please post to LKML directly. +However, if you have problem communicating in English you can also ask the +Chinese maintainer for help. Contact the Chinese maintainer, if this +translation is outdated or there is problem with translation. + +Chinese maintainer: Jia Wei Wei <harryxiyou@gmail.com> +--------------------------------------------------------------------- +Documentation/magic-number.txt的中文翻译 + +如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 +以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 + +中文版维护者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> +中文版翻译者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> +中文版校译者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> + +以下为正文 +--------------------------------------------------------------------- +这个文件是有关当前使用的魔术值注册表。当你给一个结构添加了一个魔术值，你也应该把这个魔术值添加到这个文件，因为我们最好把用于各种结构的魔术值统一起来。 + +使用魔术值来保护内核数据结构是一个非常好的主意。这就允许你在运行期检查(a)一个结构是否已经被攻击，或者(b)你已经给一个例行程序通过了一个错误的结构。后一种情况特别地有用---特别是当你通过一个空指针指向结构体的时候。tty源码，例如，经常通过特定驱动使用这种方法并且反复地排列特定方面的结构。 + +使用魔术值的方法是在结构的开始处声明的，如下： + +struct tty_ldisc { + int magic; + ... +}; + +当你以后给内核添加增强功能的时候，请遵守这条规则！这样就会节省数不清的调试时间，特别是一些古怪的情况，例如，数组超出范围并且重新写了超出部分。遵守这个规则，这些情况可以被快速地，安全地避免。 + + Theodore Ts'o + 31 Mar 94 + +给当前的Linux 2.1.55添加魔术表。 + + Michael Chastain + <mailto:mec@shout.net> + 22 Sep 1997 + +现在应该最新的Linux 2.1.112.因为在特性冻结期间，不能在2.2.x前改变任何东西。这些条目被数域所排序。 + + Krzysztof G.Baranowski + <mailto: kgb@knm.org.pl> + 29 Jul 1998 + +更新魔术表到Linux 2.5.45。刚好越过特性冻结，但是有可能还会有一些新的魔术值在2.6.x之前融入到内核中。 + + Petr Baudis + <pasky@ucw.cz> + 03 Nov 2002 + +更新魔术表到Linux 2.5.74。 + + Fabian Frederick + <ffrederick@users.sourceforge.net> + 09 Jul 2003 + +魔术名 地址 结构 所在文件 +=========================================================================== +PG_MAGIC 'P' pg_{read,write}_hdr include/linux/pg.h +CMAGIC 0x0111 user include/linux/a.out.h +MKISS_DRIVER_MAGIC 0x04bf mkiss_channel drivers/net/mkiss.h +RISCOM8_MAGIC 0x0907 riscom_port drivers/char/riscom8.h +SPECIALIX_MAGIC 0x0907 specialix_port drivers/char/specialix_io8.h +HDLC_MAGIC 0x239e n_hdlc drivers/char/n_hdlc.c +APM_BIOS_MAGIC 0x4101 apm_user arch/i386/kernel/apm.c +CYCLADES_MAGIC 0x4359 cyclades_port include/linux/cyclades.h +DB_MAGIC 0x4442 fc_info drivers/net/iph5526_novram.c +DL_MAGIC 0x444d fc_info drivers/net/iph5526_novram.c +FASYNC_MAGIC 0x4601 fasync_struct include/linux/fs.h +FF_MAGIC 0x4646 fc_info drivers/net/iph5526_novram.c +ISICOM_MAGIC 0x4d54 isi_port include/linux/isicom.h +PTY_MAGIC 0x5001 drivers/char/pty.c +PPP_MAGIC 0x5002 ppp include/linux/if_pppvar.h +SERIAL_MAGIC 0x5301 async_struct include/linux/serial.h +SSTATE_MAGIC 0x5302 serial_state include/linux/serial.h +SLIP_MAGIC 0x5302 slip drivers/net/slip.h +STRIP_MAGIC 0x5303 strip drivers/net/strip.c +X25_ASY_MAGIC 0x5303 x25_asy drivers/net/x25_asy.h +SIXPACK_MAGIC 0x5304 sixpack drivers/net/hamradio/6pack.h +AX25_MAGIC 0x5316 ax_disp drivers/net/mkiss.h +ESP_MAGIC 0x53ee esp_struct drivers/char/esp.h +TTY_MAGIC 0x5401 tty_struct include/linux/tty.h +MGSL_MAGIC 0x5401 mgsl_info drivers/char/synclink.c +TTY_DRIVER_MAGIC 0x5402 tty_driver include/linux/tty_driver.h +MGSLPC_MAGIC 0x5402 mgslpc_info drivers/char/pcmcia/synclink_cs.c +TTY_LDISC_MAGIC 0x5403 tty_ldisc include/linux/tty_ldisc.h +USB_SERIAL_MAGIC 0x6702 usb_serial drivers/usb/serial/usb-serial.h +FULL_DUPLEX_MAGIC 0x6969 drivers/net/tulip/de2104x.c +USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth drivers/usb/class/bluetty.c +RFCOMM_TTY_MAGIC 0x6d02 net/bluetooth/rfcomm/tty.c +USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port drivers/usb/serial/usb-serial.h +CG_MAGIC 0x00090255 ufs_cylinder_group include/linux/ufs_fs.h +A2232_MAGIC 0x000a2232 gs_port drivers/char/ser_a2232.h +RPORT_MAGIC 0x00525001 r_port drivers/char/rocket_int.h +LSEMAGIC 0x05091998 lse drivers/fc4/fc.c +GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str drivers/scsi/gdth_ioctl.h +RIEBL_MAGIC 0x09051990 drivers/net/atarilance.c +RIO_MAGIC 0x12345678 gs_port drivers/char/rio/rio_linux.c +SX_MAGIC 0x12345678 gs_port drivers/char/sx.h +NBD_REQUEST_MAGIC 0x12560953 nbd_request include/linux/nbd.h +RED_MAGIC2 0x170fc2a5 (any) mm/slab.c +BAYCOM_MAGIC 0x19730510 baycom_state drivers/net/baycom_epp.c +ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data + drivers/isdn/isdn_x25iface.h +ECP_MAGIC 0x21504345 cdkecpsig include/linux/cdk.h +LSOMAGIC 0x27091997 lso drivers/fc4/fc.c +LSMAGIC 0x2a3b4d2a ls drivers/fc4/fc.c +WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} include/linux/wanpipe.h +CS_CARD_MAGIC 0x43525553 cs_card sound/oss/cs46xx.c +LABELCL_MAGIC 0x4857434c labelcl_info_s include/asm/ia64/sn/labelcl.h +ISDN_ASYNC_MAGIC 0x49344C01 modem_info include/linux/isdn.h +CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info drivers/s390/net/ctctty.c +ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s drivers/isdn/i4l/isdn_net_lib.h +SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg arch/*/amiga/config.c +STLI_BOARDMAGIC 0x4bc6c825 stlibrd include/linux/istallion.h +CS_STATE_MAGIC 0x4c4f4749 cs_state sound/oss/cs46xx.c +SLAB_C_MAGIC 0x4f17a36d kmem_cache mm/slab.c +COW_MAGIC 0x4f4f4f4d cow_header_v1 arch/um/drivers/ubd_user.c +I810_CARD_MAGIC 0x5072696E i810_card sound/oss/i810_audio.c +TRIDENT_CARD_MAGIC 0x5072696E trident_card sound/oss/trident.c +ROUTER_MAGIC 0x524d4157 wan_device include/linux/wanrouter.h +SCC_MAGIC 0x52696368 gs_port drivers/char/scc.h +SAVEKMSG_MAGIC1 0x53415645 savekmsg arch/*/amiga/config.c +GDA_MAGIC 0x58464552 gda arch/mips/include/asm/sn/gda.h +RED_MAGIC1 0x5a2cf071 (any) mm/slab.c +STL_PORTMAGIC 0x5a7182c9 stlport include/linux/stallion.h +EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev drivers/atm/lanai.c +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state include/linux/hdlcdrv.h +EPCA_MAGIC 0x5c6df104 channel include/linux/epca.h +PCXX_MAGIC 0x5c6df104 channel drivers/char/pcxx.h +KV_MAGIC 0x5f4b565f kernel_vars_s arch/mips/include/asm/sn/klkernvars.h +I810_STATE_MAGIC 0x63657373 i810_state sound/oss/i810_audio.c +TRIDENT_STATE_MAGIC 0x63657373 trient_state sound/oss/trident.c +M3_CARD_MAGIC 0x646e6f50 m3_card sound/oss/maestro3.c +FW_HEADER_MAGIC 0x65726F66 fw_header drivers/atm/fore200e.h +SLOT_MAGIC 0x67267321 slot drivers/hotplug/cpqphp.h +SLOT_MAGIC 0x67267322 slot drivers/hotplug/acpiphp.h +LO_MAGIC 0x68797548 nbd_device include/linux/nbd.h +OPROFILE_MAGIC 0x6f70726f super_block drivers/oprofile/oprofilefs.h +M3_STATE_MAGIC 0x734d724d m3_state sound/oss/maestro3.c +STL_PANELMAGIC 0x7ef621a1 stlpanel include/linux/stallion.h +VMALLOC_MAGIC 0x87654320 snd_alloc_track sound/core/memory.c +KMALLOC_MAGIC 0x87654321 snd_alloc_track sound/core/memory.c +PWC_MAGIC 0x89DC10AB pwc_device drivers/usb/media/pwc.h +NBD_REPLY_MAGIC 0x96744668 nbd_reply include/linux/nbd.h +STL_BOARDMAGIC 0xa2267f52 stlbrd include/linux/stallion.h +ENI155_MAGIC 0xa54b872d midway_eprom drivers/atm/eni.h +SCI_MAGIC 0xbabeface gs_port drivers/char/sh-sci.h +CODA_MAGIC 0xC0DAC0DA coda_file_info include/linux/coda_fs_i.h +DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram drivers/scsi/gdth.h +STLI_PORTMAGIC 0xe671c7a1 stliport include/linux/istallion.h +YAM_MAGIC 0xF10A7654 yam_port drivers/net/hamradio/yam.c +CCB_MAGIC 0xf2691ad2 ccb drivers/scsi/ncr53c8xx.c +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry drivers/scsi/arm/queue.c +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry drivers/scsi/arm/queue.c +HTB_CMAGIC 0xFEFAFEF1 htb_class net/sched/sch_htb.c +NMI_MAGIC 0x48414d4d455201 nmi_s arch/mips/include/asm/sn/nmi.h + +请注意，在声音记忆管理中仍然有每一些被定义的驱动魔术值。查看include/sound/sndmagic.h来获取他们完整的列表信息。很多OSS声音驱动拥有自己从声卡PCI ID构建的魔术值-他们也没有被列在这里。 + +IrDA子系统也使用了大量的自己的魔术值，查看include/net/irda/irda.h来获取他们完整的信息。 + +HFS是另外一个比较大的使用魔术值的文件系统-你可以在fs/hfs/hfs.h中找到他们。 |
