diff options
Diffstat (limited to 'Documentation')
57 files changed, 5487 insertions, 733 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 25be325..428676c 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -133,6 +133,46 @@ Description: The symbolic link points to the PCI device sysfs entry of the Physical Function this device associates with. + +What: /sys/bus/pci/slots/... +Date: April 2005 (possibly older) +KernelVersion: 2.6.12 (possibly older) +Contact: linux-pci@vger.kernel.org +Description: + When the appropriate driver is loaded, it will create a + directory per claimed physical PCI slot in + /sys/bus/pci/slots/. The names of these directories are + specific to the driver, which in turn, are specific to the + platform, but in general, should match the label on the + machine's physical chassis. + + The drivers that can create slot directories include the + PCI hotplug drivers, and as of 2.6.27, the pci_slot driver. + + The slot directories contain, at a minimum, a file named + 'address' which contains the PCI bus:device:function tuple. + Other files may appear as well, but are specific to the + driver. + +What: /sys/bus/pci/slots/.../function[0-7] +Date: March 2010 +KernelVersion: 2.6.35 +Contact: linux-pci@vger.kernel.org +Description: + If PCI slot directories (as described above) are created, + and the physical slot is actually populated with a device, + symbolic links in the slot directory pointing to the + device's PCI functions are created as well. + +What: /sys/bus/pci/devices/.../slot +Date: March 2010 +KernelVersion: 2.6.35 +Contact: linux-pci@vger.kernel.org +Description: + If PCI slot directories (as described above) are created, + a symbolic link pointing to the slot directory will be + created as well. + What: /sys/bus/pci/slots/.../module Date: June 2009 Contact: linux-pci@vger.kernel.org diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power new file mode 100644 index 0000000..78c7bac --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-power @@ -0,0 +1,20 @@ +What: /sys/class/power/ds2760-battery.*/charge_now +Date: May 2010 +KernelVersion: 2.6.35 +Contact: Daniel Mack <daniel@caiaq.de> +Description: + This file is writeable and can be used to set the current + coloumb counter value inside the battery monitor chip. This + is needed for unavoidable corrections of aging batteries. + A userspace daemon can monitor the battery charging logic + and once the counter drops out of considerable bounds, take + appropriate action. + +What: /sys/class/power/ds2760-battery.*/charge_full +Date: May 2010 +KernelVersion: 2.6.35 +Contact: Daniel Mack <daniel@caiaq.de> +Description: + This file is writeable and can be used to set the assumed + battery 'full level'. As batteries age, this value has to be + amended over time. diff --git a/Documentation/ABI/testing/sysfs-devices-node b/Documentation/ABI/testing/sysfs-devices-node new file mode 100644 index 0000000..453a210 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-node @@ -0,0 +1,7 @@ +What: /sys/devices/system/node/nodeX/compact +Date: February 2010 +Contact: Mel Gorman <mel@csn.ul.ie> +Description: + When this file is written to, all memory within that node + will be compacted. When it completes, memory will be freed + into blocks which have as many contiguous pages as possible diff --git a/Documentation/ABI/testing/sysfs-driver-hid-picolcd b/Documentation/ABI/testing/sysfs-driver-hid-picolcd new file mode 100644 index 0000000..08579e7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-picolcd @@ -0,0 +1,43 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/operation_mode +Date: March 2010 +Contact: Bruno Prémont <bonbons@linux-vserver.org> +Description: Make it possible to switch the PicoLCD device between LCD + (firmware) and bootloader (flasher) operation modes. + + Reading: returns list of available modes, the active mode being + enclosed in brackets ('[' and ']') + + Writing: causes operation mode switch. Permitted values are + the non-active mode names listed when read. + + Note: when switching mode the current PicoLCD HID device gets + disconnected and reconnects after above delay (see attribute + operation_mode_delay for its value). + + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/operation_mode_delay +Date: April 2010 +Contact: Bruno Prémont <bonbons@linux-vserver.org> +Description: Delay PicoLCD waits before restarting in new mode when + operation_mode has changed. + + Reading/Writing: It is expressed in ms and permitted range is + 0..30000ms. + + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/fb_update_rate +Date: March 2010 +Contact: Bruno Prémont <bonbons@linux-vserver.org> +Description: Make it possible to adjust defio refresh rate. + + Reading: returns list of available refresh rates (expressed in Hz), + the active refresh rate being enclosed in brackets ('[' and ']') + + Writing: accepts new refresh rate expressed in integer Hz + within permitted rates. + + Note: As device can barely do 2 complete refreshes a second + it only makes sense to adjust this value if only one or two + tiles get changed and it's not appropriate to expect the application + to flush it's tiny changes explicitely at higher than default rate. + diff --git a/Documentation/ABI/testing/sysfs-driver-hid-prodikeys b/Documentation/ABI/testing/sysfs-driver-hid-prodikeys new file mode 100644 index 0000000..05d988c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-prodikeys @@ -0,0 +1,29 @@ +What: /sys/bus/hid/drivers/prodikeys/.../channel +Date: April 2010 +KernelVersion: 2.6.34 +Contact: Don Prince <dhprince.devel@yahoo.co.uk> +Description: + Allows control (via software) the midi channel to which + that the pc-midi keyboard will output.midi data. + Range: 0..15 + Type: Read/write +What: /sys/bus/hid/drivers/prodikeys/.../sustain +Date: April 2010 +KernelVersion: 2.6.34 +Contact: Don Prince <dhprince.devel@yahoo.co.uk> +Description: + Allows control (via software) the sustain duration of a + note held by the pc-midi driver. + 0 means sustain mode is disabled. + Range: 0..5000 (milliseconds) + Type: Read/write +What: /sys/bus/hid/drivers/prodikeys/.../octave +Date: April 2010 +KernelVersion: 2.6.34 +Contact: Don Prince <dhprince.devel@yahoo.co.uk> +Description: + Controls the octave shift modifier in the pc-midi driver. + The octave can be shifted via software up/down 2 octaves. + 0 means the no ocatve shift. + Range: -2..2 (minus 2 to plus 2) + Type: Read/Write diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone new file mode 100644 index 0000000..88340a2 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone @@ -0,0 +1,111 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/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 + press of a button. + When read, this file returns the raw number of the actual dpi + setting reported by the mouse. This number has to be further + processed to receive the real dpi value. + + VALUE DPI + 1 800 + 2 1200 + 3 1600 + 4 2000 + 5 2400 + 6 3200 + + This file is readonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/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. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/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 + firmware reported by the mouse. Using the integer value eases + further usage in other programs. To receive the real version + number the decimal point has to be shifted 2 positions to the + left. E.g. a returned value of 138 means 1.38 + This file is readonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/kone_driver_version +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the driver version. + The format of the string is "v<major>.<minor>.<patchlevel>". + This attribute is used by the userland tools to find the sysfs- + paths of installed kone-mice and determine the capabilites of + the driver. Versions of this driver for old kernels replace + usbhid instead of generic-usb. The way to scan for this file + has been chosen to provide a consistent way for all supported + kernel versions. + This file is readonly. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/profile[1-5] +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile holds informations like button + mappings, sensitivity, the colors of the 5 leds and light + effects. + When read, these files return the respective profile. The + returned data is 975 bytes in size. + When written, this file lets one write the respective profile + data back to the mouse. The data has to be 975 bytes long. + The mouse will reject invalid data, whereas the profile number + stored in the profile doesn't need to fit the number of the + store. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/settings +Date: March 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 36 bytes and holds information like the + startup_profile, tcu state and calibration_data. + 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. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/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. + 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. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/tcu +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse has a "Tracking Control Unit" which lets the user + calibrate the laser power to fit the mousepad surface. + When read, this file returns the current state of the TCU, + where 0 means off and 1 means on. + 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. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/weight +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can be equipped with one of four supplied weights + ranging from 5 to 20 grams which are recognized by the mouse + and its value can be read out. When read, this file returns the + raw value returned by the mouse which eases further processing + in other software. + The values map to the weights as follows: + + VALUE WEIGHT + 0 none + 1 5g + 2 10g + 3 15g + 4 20g + + This file is readonly. diff --git a/Documentation/ABI/testing/sysfs-firmware-sfi b/Documentation/ABI/testing/sysfs-firmware-sfi new file mode 100644 index 0000000..4be7d44 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-sfi @@ -0,0 +1,15 @@ +What: /sys/firmware/sfi/tables/ +Date: May 2010 +Contact: Len Brown <lenb@kernel.org> +Description: + SFI defines a number of small static memory tables + so the kernel can get platform information from firmware. + + The tables are defined in the latest SFI specification: + http://simplefirmware.org/documentation + + While the tables are used by the kernel, user-space + can observe them this way: + + # cd /sys/firmware/sfi/tables + # cat $TABLENAME > $TABLENAME.bin diff --git a/Documentation/ABI/testing/sysfs-wacom b/Documentation/ABI/testing/sysfs-wacom new file mode 100644 index 0000000..1517976 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-wacom @@ -0,0 +1,10 @@ +What: /sys/class/hidraw/hidraw*/device/speed +Date: April 2010 +Kernel Version: 2.6.35 +Contact: linux-bluetooth@vger.kernel.org +Description: + The /sys/class/hidraw/hidraw*/device/speed file controls + reporting speed of wacom bluetooth tablet. Reading from + this file returns 1 if tablet reports in high speed mode + or 0 otherwise. Writing to this file one of these values + switches reporting speed. diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index 2e435ad..98ce517 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -639,6 +639,36 @@ is planned to completely remove virt_to_bus() and bus_to_virt() as they are entirely deprecated. Some ports already do not provide these as it is impossible to correctly support them. + Handling Errors + +DMA address space is limited on some architectures and an allocation +failure can be determined by: + +- checking if dma_alloc_coherent returns NULL or dma_map_sg returns 0 + +- checking the returned dma_addr_t of dma_map_single and dma_map_page + by using dma_mapping_error(): + + dma_addr_t dma_handle; + + dma_handle = dma_map_single(dev, addr, size, direction); + if (dma_mapping_error(dev, dma_handle)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + } + +Networking drivers must call dev_kfree_skb to free the socket buffer +and return NETDEV_TX_OK if the DMA mapping fails on the transmit hook +(ndo_start_xmit). This means that the socket buffer is just dropped in +the failure case. + +SCSI drivers must return SCSI_MLQUEUE_HOST_BUSY if the DMA mapping +fails in the queuecommand hook. This means that the SCSI subsystem +passes the command to the driver again later. + Optimizing Unmap State Space Consumption On many platforms, dma_unmap_{single,page}() is simply a nop. @@ -703,42 +733,25 @@ to "Closing". 1) Struct scatterlist requirements. - Struct scatterlist must contain, at a minimum, the following - members: - - struct page *page; - unsigned int offset; - unsigned int length; - - The base address is specified by a "page+offset" pair. - - Previous versions of struct scatterlist contained a "void *address" - field that was sometimes used instead of page+offset. As of Linux - 2.5., page+offset is always used, and the "address" field has been - deleted. - -2) More to come... - - Handling Errors - -DMA address space is limited on some architectures and an allocation -failure can be determined by: - -- checking if dma_alloc_coherent returns NULL or dma_map_sg returns 0 - -- checking the returned dma_addr_t of dma_map_single and dma_map_page - by using dma_mapping_error(): - - dma_addr_t dma_handle; - - dma_handle = dma_map_single(dev, addr, size, direction); - if (dma_mapping_error(dev, dma_handle)) { - /* - * reduce current DMA mapping usage, - * delay and try again later or - * reset driver. - */ - } + Don't invent the architecture specific struct scatterlist; just use + <asm-generic/scatterlist.h>. You need to enable + CONFIG_NEED_SG_DMA_LENGTH if the architecture supports IOMMUs + (including software IOMMU). + +2) ARCH_KMALLOC_MINALIGN + + Architectures must ensure that kmalloc'ed buffer is + DMA-safe. Drivers and subsystems depend on it. If an architecture + isn't fully DMA-coherent (i.e. hardware doesn't ensure that data in + the CPU cache is identical to data in main memory), + ARCH_KMALLOC_MINALIGN must be set so that the memory allocator + makes sure that kmalloc'ed buffer doesn't share a cache line with + the others. See arch/arm/include/asm/cache.h as an example. + + Note that ARCH_KMALLOC_MINALIGN is about DMA memory alignment + constraints. You don't need to worry about the architecture data + alignment constraints (e.g. the alignment constraints about 64-bit + objects). Closing diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 325cfd1..c7e5dc7 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -14,7 +14,7 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ mac80211.xml debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ - tracepoint.xml media.xml + tracepoint.xml media.xml drm.xml ### # The build process is as follows (targets): diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl new file mode 100644 index 0000000..7583dc7 --- /dev/null +++ b/Documentation/DocBook/drm.tmpl @@ -0,0 +1,839 @@ +<?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="drmDevelopersGuide"> + <bookinfo> + <title>Linux DRM Developer's Guide</title> + + <copyright> + <year>2008-2009</year> + <holder> + Intel Corporation (Jesse Barnes <jesse.barnes@intel.com>) + </holder> + </copyright> + + <legalnotice> + <para> + The contents of this file may be used under the terms of the GNU + General Public License version 2 (the "GPL") as distributed in + the kernel source COPYING file. + </para> + </legalnotice> + </bookinfo> + +<toc></toc> + + <!-- Introduction --> + + <chapter id="drmIntroduction"> + <title>Introduction</title> + <para> + The Linux DRM layer contains code intended to support the needs + of complex graphics devices, usually containing programmable + pipelines well suited to 3D graphics acceleration. Graphics + drivers in the kernel can make use of DRM functions to make + tasks like memory management, interrupt handling and DMA easier, + and provide a uniform interface to applications. + </para> + <para> + A note on versions: this guide covers features found in the DRM + tree, including the TTM memory manager, output configuration and + mode setting, and the new vblank internals, in addition to all + the regular features found in current kernels. + </para> + <para> + [Insert diagram of typical DRM stack here] + </para> + </chapter> + + <!-- Internals --> + + <chapter id="drmInternals"> + <title>DRM Internals</title> + <para> + This chapter documents DRM internals relevant to driver authors + and developers working to add support for the latest features to + existing drivers. + </para> + <para> + First, we'll go over some typical driver initialization + requirements, like setting up command buffers, creating an + initial output configuration, and initializing core services. + Subsequent sections will cover core internals in more detail, + providing implementation notes and examples. + </para> + <para> + The DRM layer provides several services to graphics drivers, + many of them driven by the application interfaces it provides + through libdrm, the library that wraps most of the DRM ioctls. + These include vblank event handling, memory + management, output management, framebuffer management, command + submission & fencing, suspend/resume support, and DMA + services. + </para> + <para> + The core of every DRM driver is struct drm_device. Drivers + will typically statically initialize a drm_device structure, + then pass it to drm_init() at load time. + </para> + + <!-- Internals: driver init --> + + <sect1> + <title>Driver initialization</title> + <para> + Before calling the DRM initialization routines, the driver must + first create and fill out a struct drm_device structure. + </para> + <programlisting> + static struct drm_driver driver = { + /* don't use mtrr's here, the Xserver or user space app should + * deal with them for intel hardware. + */ + .driver_features = + DRIVER_USE_AGP | DRIVER_REQUIRE_AGP | + DRIVER_HAVE_IRQ | DRIVER_IRQ_SHARED | DRIVER_MODESET, + .load = i915_driver_load, + .unload = i915_driver_unload, + .firstopen = i915_driver_firstopen, + .lastclose = i915_driver_lastclose, + .preclose = i915_driver_preclose, + .save = i915_save, + .restore = i915_restore, + .device_is_agp = i915_driver_device_is_agp, + .get_vblank_counter = i915_get_vblank_counter, + .enable_vblank = i915_enable_vblank, + .disable_vblank = i915_disable_vblank, + .irq_preinstall = i915_driver_irq_preinstall, + .irq_postinstall = i915_driver_irq_postinstall, + .irq_uninstall = i915_driver_irq_uninstall, + .irq_handler = i915_driver_irq_handler, + .reclaim_buffers = drm_core_reclaim_buffers, + .get_map_ofs = drm_core_get_map_ofs, + .get_reg_ofs = drm_core_get_reg_ofs, + .fb_probe = intelfb_probe, + .fb_remove = intelfb_remove, + .fb_resize = intelfb_resize, + .master_create = i915_master_create, + .master_destroy = i915_master_destroy, +#if defined(CONFIG_DEBUG_FS) + .debugfs_init = i915_debugfs_init, + .debugfs_cleanup = i915_debugfs_cleanup, +#endif + .gem_init_object = i915_gem_init_object, + .gem_free_object = i915_gem_free_object, + .gem_vm_ops = &i915_gem_vm_ops, + .ioctls = i915_ioctls, + .fops = { + .owner = THIS_MODULE, + .open = drm_open, + .release = drm_release, + .ioctl = drm_ioctl, + .mmap = drm_mmap, + .poll = drm_poll, + .fasync = drm_fasync, +#ifdef CONFIG_COMPAT + .compat_ioctl = i915_compat_ioctl, +#endif + }, + .pci_driver = { + .name = DRIVER_NAME, + .id_table = pciidlist, + .probe = probe, + .remove = __devexit_p(drm_cleanup_pci), + }, + .name = DRIVER_NAME, + .desc = DRIVER_DESC, + .date = DRIVER_DATE, + .major = DRIVER_MAJOR, + .minor = DRIVER_MINOR, + .patchlevel = DRIVER_PATCHLEVEL, + }; + </programlisting> + <para> + In the example above, taken from the i915 DRM driver, the driver + sets several flags indicating what core features it supports. + We'll go over the individual callbacks in later sections. Since + flags indicate which features your driver supports to the DRM + core, you need to set most of them prior to calling drm_init(). Some, + like DRIVER_MODESET can be set later based on user supplied parameters, + but that's the exception rather than the rule. + </para> + <variablelist> + <title>Driver flags</title> + <varlistentry> + <term>DRIVER_USE_AGP</term> + <listitem><para> + Driver uses AGP interface + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_REQUIRE_AGP</term> + <listitem><para> + Driver needs AGP interface to function. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_USE_MTRR</term> + <listitem> + <para> + Driver uses MTRR interface for mapping memory. Deprecated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_PCI_DMA</term> + <listitem><para> + Driver is capable of PCI DMA. Deprecated. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_SG</term> + <listitem><para> + Driver can perform scatter/gather DMA. Deprecated. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_HAVE_DMA</term> + <listitem><para>Driver supports DMA. Deprecated.</para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term> + <listitem> + <para> + DRIVER_HAVE_IRQ indicates whether the driver has a IRQ + handler, DRIVER_IRQ_SHARED indicates whether the device & + handler support shared IRQs (note that this is required of + PCI drivers). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_DMA_QUEUE</term> + <listitem> + <para> + If the driver queues DMA requests and completes them + asynchronously, this flag should be set. Deprecated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_FB_DMA</term> + <listitem> + <para> + Driver supports DMA to/from the framebuffer. Deprecated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_MODESET</term> + <listitem> + <para> + Driver supports mode setting interfaces. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + In this specific case, the driver requires AGP and supports + IRQs. DMA, as we'll see, is handled by device specific ioctls + in this case. It also supports the kernel mode setting APIs, though + unlike in the actual i915 driver source, this example unconditionally + exports KMS capability. + </para> + </sect1> + + <!-- Internals: driver load --> + + <sect1> + <title>Driver load</title> + <para> + In the previous section, we saw what a typical drm_driver + structure might look like. One of the more important fields in + the structure is the hook for the load function. + </para> + <programlisting> + static struct drm_driver driver = { + ... + .load = i915_driver_load, + ... + }; + </programlisting> + <para> + The load function has many responsibilities: allocating a driver + private structure, specifying supported performance counters, + configuring the device (e.g. mapping registers & command + buffers), initializing the memory manager, and setting up the + initial output configuration. + </para> + <para> + Note that the tasks performed at driver load time must not + conflict with DRM client requirements. For instance, if user + level mode setting drivers are in use, it would be problematic + to perform output discovery & configuration at load time. + Likewise, if pre-memory management aware user level drivers are + in use, memory management and command buffer setup may need to + be omitted. These requirements are driver specific, and care + needs to be taken to keep both old and new applications and + libraries working. The i915 driver supports the "modeset" + module parameter to control whether advanced features are + enabled at load time or in legacy fashion. If compatibility is + a concern (e.g. with drivers converted over to the new interfaces + from the old ones), care must be taken to prevent incompatible + device initialization and control with the currently active + userspace drivers. + </para> + + <sect2> + <title>Driver private & performance counters</title> + <para> + The driver private hangs off the main drm_device structure and + can be used for tracking various device specific bits of + information, like register offsets, command buffer status, + register state for suspend/resume, etc. At load time, a + driver can simply allocate one and set drm_device.dev_priv + appropriately; at unload the driver can free it and set + drm_device.dev_priv to NULL. + </para> + <para> + The DRM supports several counters which can be used for rough + performance characterization. Note that the DRM stat counter + system is not often used by applications, and supporting + additional counters is completely optional. + </para> + <para> + These interfaces are deprecated and should not be used. If performance + monitoring is desired, the developer should investigate and + potentially enhance the kernel perf and tracing infrastructure to export + GPU related performance information to performance monitoring + tools and applications. + </para> + </sect2> + + <sect2> + <title>Configuring the device</title> + <para> + Obviously, device configuration will be device specific. + However, there are several common operations: finding a + device's PCI resources, mapping them, and potentially setting + up an IRQ handler. + </para> + <para> + Finding & mapping resources is fairly straightforward. The + DRM wrapper functions, drm_get_resource_start() and + drm_get_resource_len() can be used to find BARs on the given + drm_device struct. Once those values have been retrieved, the + driver load function can call drm_addmap() to create a new + mapping for the BAR in question. Note you'll probably want a + drm_local_map_t in your driver private structure to track any + mappings you create. +<!-- !Fdrivers/gpu/drm/drm_bufs.c drm_get_resource_* --> +<!-- !Finclude/drm/drmP.h drm_local_map_t --> + </para> + <para> + if compatibility with other operating systems isn't a concern + (DRM drivers can run under various BSD variants and OpenSolaris), + native Linux calls can be used for the above, e.g. pci_resource_* + and iomap*/iounmap. See the Linux device driver book for more + info. + </para> + <para> + Once you have a register map, you can use the DRM_READn() and + DRM_WRITEn() macros to access the registers on your device, or + use driver specific versions to offset into your MMIO space + relative to a driver specific base pointer (see I915_READ for + example). + </para> + <para> + If your device supports interrupt generation, you may want to + setup an interrupt handler at driver load time as well. This + is done using the drm_irq_install() function. If your device + supports vertical blank interrupts, it should call + drm_vblank_init() to initialize the core vblank handling code before + enabling interrupts on your device. This ensures the vblank related + structures are allocated and allows the core to handle vblank events. + </para> +<!--!Fdrivers/char/drm/drm_irq.c drm_irq_install--> + <para> + Once your interrupt handler is registered (it'll use your + drm_driver.irq_handler as the actual interrupt handling + function), you can safely enable interrupts on your device, + assuming any other state your interrupt handler uses is also + initialized. + </para> + <para> + Another task that may be necessary during configuration is + mapping the video BIOS. On many devices, the VBIOS describes + device configuration, LCD panel timings (if any), and contains + flags indicating device state. Mapping the BIOS can be done + using the pci_map_rom() call, a convenience function that + takes care of mapping the actual ROM, whether it has been + shadowed into memory (typically at address 0xc0000) or exists + on the PCI device in the ROM BAR. Note that once you've + mapped the ROM and extracted any necessary information, be + sure to unmap it; on many devices the ROM address decoder is + shared with other BARs, so leaving it mapped can cause + undesired behavior like hangs or memory corruption. +<!--!Fdrivers/pci/rom.c pci_map_rom--> + </para> + </sect2> + + <sect2> + <title>Memory manager initialization</title> + <para> + In order to allocate command buffers, cursor memory, scanout + buffers, etc., as well as support the latest features provided + by packages like Mesa and the X.Org X server, your driver + should support a memory manager. + </para> + <para> + If your driver supports memory management (it should!), you'll + need to set that up at load time as well. How you intialize + it depends on which memory manager you're using, TTM or GEM. + </para> + <sect3> + <title>TTM initialization</title> + <para> + TTM (for Translation Table Manager) manages video memory and + aperture space for graphics devices. TTM supports both UMA devices + and devices with dedicated video RAM (VRAM), i.e. most discrete + graphics devices. If your device has dedicated RAM, supporting + TTM is desireable. TTM also integrates tightly with your + driver specific buffer execution function. See the radeon + driver for examples. + </para> + <para> + The core TTM structure is the ttm_bo_driver struct. It contains + several fields with function pointers for initializing the TTM, + allocating and freeing memory, waiting for command completion + and fence synchronization, and memory migration. See the + radeon_ttm.c file for an example of usage. + </para> + <para> + The ttm_global_reference structure is made up of several fields: + </para> + <programlisting> + struct ttm_global_reference { + enum ttm_global_types global_type; + size_t size; + void *object; + int (*init) (struct ttm_global_reference *); + void (*release) (struct ttm_global_reference *); + }; + </programlisting> + <para> + There should be one global reference structure for your memory + manager as a whole, and there will be others for each object + created by the memory manager at runtime. Your global TTM should + have a type of TTM_GLOBAL_TTM_MEM. The size field for the global + object should be sizeof(struct ttm_mem_global), and the init and + release hooks should point at your driver specific init and + release routines, which will probably eventually call + ttm_mem_global_init and ttm_mem_global_release respectively. + </para> + <para> + Once your global TTM accounting structure is set up and initialized + (done by calling ttm_global_item_ref on the global object you + just created), you'll need to create a buffer object TTM to + provide a pool for buffer object allocation by clients and the + kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, + and its size should be sizeof(struct ttm_bo_global). Again, + driver specific init and release functions can be provided, + likely eventually calling ttm_bo_global_init and + ttm_bo_global_release, respectively. Also like the previous + object, ttm_global_item_ref is used to create an initial reference + count for the TTM, which will call your initalization function. + </para> + </sect3> + <sect3> + <title>GEM initialization</title> + <para> + GEM is an alternative to TTM, designed specifically for UMA + devices. It has simpler initialization and execution requirements + than TTM, but has no VRAM management capability. Core GEM + initialization is comprised of a basic drm_mm_init call to create + a GTT DRM MM object, which provides an address space pool for + object allocation. In a KMS configuration, the driver will + need to allocate and initialize a command ring buffer following + basic GEM initialization. Most UMA devices have a so-called + "stolen" memory region, which provides space for the initial + framebuffer and large, contiguous memory regions required by the + device. This space is not typically managed by GEM, and must + be initialized separately into its own DRM MM object. + </para> + <para> + Initialization will be driver specific, and will depend on + the architecture of the device. In the case of Intel + integrated graphics chips like 965GM, GEM initialization can + be done by calling the internal GEM init function, + i915_gem_do_init(). Since the 965GM is a UMA device + (i.e. it doesn't have dedicated VRAM), GEM will manage + making regular RAM available for GPU operations. Memory set + aside by the BIOS (called "stolen" memory by the i915 + driver) will be managed by the DRM memrange allocator; the + rest of the aperture will be managed by GEM. + <programlisting> + /* Basic memrange allocator for stolen space (aka vram) */ + drm_memrange_init(&dev_priv->vram, 0, prealloc_size); + /* Let GEM Manage from end of prealloc space to end of aperture */ + i915_gem_do_init(dev, prealloc_size, agp_size); + </programlisting> +<!--!Edrivers/char/drm/drm_memrange.c--> + </para> + <para> + Once the memory manager has been set up, we can allocate the + command buffer. In the i915 case, this is also done with a + GEM function, i915_gem_init_ringbuffer(). + </para> + </sect3> + </sect2> + + <sect2> + <title>Output configuration</title> + <para> + The final initialization task is output configuration. This involves + finding and initializing the CRTCs, encoders and connectors + for your device, creating an initial configuration and + registering a framebuffer console driver. + </para> + <sect3> + <title>Output discovery and initialization</title> + <para> + Several core functions exist to create CRTCs, encoders and + connectors, namely drm_crtc_init(), drm_connector_init() and + drm_encoder_init(), along with several "helper" functions to + perform common tasks. + </para> + <para> + Connectors should be registered with sysfs once they've been + detected and initialized, using the + drm_sysfs_connector_add() function. Likewise, when they're + removed from the system, they should be destroyed with + drm_sysfs_connector_remove(). + </para> + <programlisting> +<![CDATA[ +void intel_crt_init(struct drm_device *dev) +{ + struct drm_connector *connector; + struct intel_output *intel_output; + + intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); + if (!intel_output) + return; + + connector = &intel_output->base; + drm_connector_init(dev, &intel_output->base, + &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); + + drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, + DRM_MODE_ENCODER_DAC); + + drm_mode_connector_attach_encoder(&intel_output->base, + &intel_output->enc); + + /* Set up the DDC bus. */ + intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); + if (!intel_output->ddc_bus) { + dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " + "failed.\n"); + return; + } + + intel_output->type = INTEL_OUTPUT_ANALOG; + connector->interlace_allowed = 0; + connector->doublescan_allowed = 0; + + drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); + drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); + + drm_sysfs_connector_add(connector); +} +]]> + </programlisting> + <para> + In the example above (again, taken from the i915 driver), a + CRT connector and encoder combination is created. A device + specific i2c bus is also created, for fetching EDID data and + performing monitor detection. Once the process is complete, + the new connector is regsitered with sysfs, to make its + properties available to applications. + </para> + <sect4> + <title>Helper functions and core functions</title> + <para> + Since many PC-class graphics devices have similar display output + designs, the DRM provides a set of helper functions to make + output management easier. The core helper routines handle + encoder re-routing and disabling of unused functions following + mode set. Using the helpers is optional, but recommended for + devices with PC-style architectures (i.e. a set of display planes + for feeding pixels to encoders which are in turn routed to + connectors). Devices with more complex requirements needing + finer grained management can opt to use the core callbacks + directly. + </para> + <para> + [Insert typical diagram here.] [Insert OMAP style config here.] + </para> + </sect4> + <para> + For each encoder, CRTC and connector, several functions must + be provided, depending on the object type. Encoder objects + need should provide a DPMS (basically on/off) function, mode fixup + (for converting requested modes into native hardware timings), + and prepare, set and commit functions for use by the core DRM + helper functions. Connector helpers need to provide mode fetch and + validity functions as well as an encoder matching function for + returing an ideal encoder for a given connector. The core + connector functions include a DPMS callback, (deprecated) + save/restore routines, detection, mode probing, property handling, + and cleanup functions. + </para> +<!--!Edrivers/char/drm/drm_crtc.h--> +<!--!Edrivers/char/drm/drm_crtc.c--> +<!--!Edrivers/char/drm/drm_crtc_helper.c--> + </sect3> + </sect2> + </sect1> + + <!-- Internals: vblank handling --> + + <sect1> + <title>VBlank event handling</title> + <para> + The DRM core exposes two vertical blank related ioctls: + DRM_IOCTL_WAIT_VBLANK and DRM_IOCTL_MODESET_CTL. +<!--!Edrivers/char/drm/drm_irq.c--> + </para> + <para> + DRM_IOCTL_WAIT_VBLANK takes a struct drm_wait_vblank structure + as its argument, and is used to block or request a signal when a + specified vblank event occurs. + </para> + <para> + DRM_IOCTL_MODESET_CTL should be called by application level + drivers before and after mode setting, since on many devices the + vertical blank counter will be reset at that time. Internally, + the DRM snapshots the last vblank count when the ioctl is called + with the _DRM_PRE_MODESET command so that the counter won't go + backwards (which is dealt with when _DRM_POST_MODESET is used). + </para> + <para> + To support the functions above, the DRM core provides several + helper functions for tracking vertical blank counters, and + requires drivers to provide several callbacks: + get_vblank_counter(), enable_vblank() and disable_vblank(). The + core uses get_vblank_counter() to keep the counter accurate + across interrupt disable periods. It should return the current + vertical blank event count, which is often tracked in a device + register. The enable and disable vblank callbacks should enable + and disable vertical blank interrupts, respectively. In the + absence of DRM clients waiting on vblank events, the core DRM + code will use the disable_vblank() function to disable + interrupts, which saves power. They'll be re-enabled again when + a client calls the vblank wait ioctl above. + </para> + <para> + Devices that don't provide a count register can simply use an + internal atomic counter incremented on every vertical blank + interrupt, and can make their enable and disable vblank + functions into no-ops. + </para> + </sect1> + + <sect1> + <title>Memory management</title> + <para> + The memory manager lies at the heart of many DRM operations, and + is also required to support advanced client features like OpenGL + pbuffers. The DRM currently contains two memory managers, TTM + and GEM. + </para> + + <sect2> + <title>The Translation Table Manager (TTM)</title> + <para> + TTM was developed by Tungsten Graphics, primarily by Thomas + Hellström, and is intended to be a flexible, high performance + graphics memory manager. + </para> + <para> + Drivers wishing to support TTM must fill out a drm_bo_driver + structure. + </para> + <para> + TTM design background and information belongs here. + </para> + </sect2> + + <sect2> + <title>The Graphics Execution Manager (GEM)</title> + <para> + GEM is an Intel project, authored by Eric Anholt and Keith + Packard. It provides simpler interfaces than TTM, and is well + suited for UMA devices. + </para> + <para> + GEM-enabled drivers must provide gem_init_object() and + gem_free_object() callbacks to support the core memory + allocation routines. They should also provide several driver + specific ioctls to support command execution, pinning, buffer + read & write, mapping, and domain ownership transfers. + </para> + <para> + On a fundamental level, GEM involves several operations: memory + allocation and freeing, command execution, and aperture management + at command execution time. Buffer object allocation is relatively + straightforward and largely provided by Linux's shmem layer, which + provides memory to back each object. When mapped into the GTT + or used in a command buffer, the backing pages for an object are + flushed to memory and marked write combined so as to be coherent + with the GPU. Likewise, when the GPU finishes rendering to an object, + if the CPU accesses it, it must be made coherent with the CPU's view + of memory, usually involving GPU cache flushing of various kinds. + This core CPU<->GPU coherency management is provided by the GEM + set domain function, which evaluates an object's current domain and + performs any necessary flushing or synchronization to put the object + into the desired coherency domain (note that the object may be busy, + i.e. an active render target; in that case the set domain function + will block the client and wait for rendering to complete before + performing any necessary flushing operations). + </para> + <para> + Perhaps the most important GEM function is providing a command + execution interface to clients. Client programs construct command + buffers containing references to previously allocated memory objects + and submit them to GEM. At that point, GEM will take care to bind + all the objects into the GTT, execute the buffer, and provide + necessary synchronization between clients accessing the same buffers. + This often involves evicting some objects from the GTT and re-binding + others (a fairly expensive operation), and providing relocation + support which hides fixed GTT offsets from clients. Clients must + take care not to submit command buffers that reference more objects + than can fit in the GTT or GEM will reject them and no rendering + will occur. Similarly, if several objects in the buffer require + fence registers to be allocated for correct rendering (e.g. 2D blits + on pre-965 chips), care must be taken not to require more fence + registers than are available to the client. Such resource management + should be abstracted from the client in libdrm. + </para> + </sect2> + + </sect1> + + <!-- Output management --> + <sect1> + <title>Output management</title> + <para> + At the core of the DRM output management code is a set of + structures representing CRTCs, encoders and connectors. + </para> + <para> + A CRTC is an abstraction representing a part of the chip that + contains a pointer to a scanout buffer. Therefore, the number + of CRTCs available determines how many independent scanout + buffers can be active at any given time. The CRTC structure + contains several fields to support this: a pointer to some video + memory, a display mode, and an (x, y) offset into the video + memory to support panning or configurations where one piece of + video memory spans multiple CRTCs. + </para> + <para> + An encoder takes pixel data from a CRTC and converts it to a + format suitable for any attached connectors. On some devices, + it may be possible to have a CRTC send data to more than one + encoder. In that case, both encoders would receive data from + the same scanout buffer, resulting in a "cloned" display + configuration across the connectors attached to each encoder. + </para> + <para> + A connector is the final destination for pixel data on a device, + and usually connects directly to an external display device like + a monitor or laptop panel. A connector can only be attached to + one encoder at a time. The connector is also the structure + where information about the attached display is kept, so it + contains fields for display data, EDID data, DPMS & + connection status, and information about modes supported on the + attached displays. + </para> +<!--!Edrivers/char/drm/drm_crtc.c--> + </sect1> + + <sect1> + <title>Framebuffer management</title> + <para> + In order to set a mode on a given CRTC, encoder and connector + configuration, clients need to provide a framebuffer object which + will provide a source of pixels for the CRTC to deliver to the encoder(s) + and ultimately the connector(s) in the configuration. A framebuffer + is fundamentally a driver specific memory object, made into an opaque + handle by the DRM addfb function. Once an fb has been created this + way it can be passed to the KMS mode setting routines for use in + a configuration. + </para> + </sect1> + + <sect1> + <title>Command submission & fencing</title> + <para> + This should cover a few device specific command submission + implementations. + </para> + </sect1> + + <sect1> + <title>Suspend/resume</title> + <para> + The DRM core provides some suspend/resume code, but drivers + wanting full suspend/resume support should provide save() and + restore() functions. These will be called at suspend, + hibernate, or resume time, and should perform any state save or + restore required by your device across suspend or hibernate + states. + </para> + </sect1> + + <sect1> + <title>DMA services</title> + <para> + This should cover how DMA mapping etc. is supported by the core. + These functions are deprecated and should not be used. + </para> + </sect1> + </chapter> + + <!-- External interfaces --> + + <chapter id="drmExternals"> + <title>Userland interfaces</title> + <para> + The DRM core exports several interfaces to applications, + generally intended to be used through corresponding libdrm + wrapper functions. In addition, drivers export device specific + interfaces for use by userspace drivers & device aware + applications through ioctls and sysfs files. + </para> + <para> + External interfaces include: memory mapping, context management, + DMA operations, AGP management, vblank control, fence + management, memory management, and output management. + </para> + <para> + Cover generic ioctls and sysfs layout here. Only need high + level info, since man pages will cover the rest. + </para> + </chapter> + + <!-- API reference --> + + <appendix id="drmDriverApi"> + <title>DRM Driver API</title> + <para> + Include auto-generated API reference here (need to reference it + from paragraphs above too). + </para> + </appendix> + +</book> diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl index 5cff41a..55f12ac 100644 --- a/Documentation/DocBook/kgdb.tmpl +++ b/Documentation/DocBook/kgdb.tmpl @@ -4,7 +4,7 @@ <book id="kgdbOnLinux"> <bookinfo> - <title>Using kgdb and the kgdb Internals</title> + <title>Using kgdb, kdb and the kernel debugger internals</title> <authorgroup> <author> @@ -17,33 +17,8 @@ </affiliation> </author> </authorgroup> - - <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rini</surname> - <affiliation> - <address> - <email>trini@kernel.crashing.org</email> - </address> - </affiliation> - </author> - </authorgroup> - - <authorgroup> - <author> - <firstname>Amit S.</firstname> - <surname>Kale</surname> - <affiliation> - <address> - <email>amitkale@linsyssoft.com</email> - </address> - </affiliation> - </author> - </authorgroup> - <copyright> - <year>2008</year> + <year>2008,2010</year> <holder>Wind River Systems, Inc.</holder> </copyright> <copyright> @@ -69,41 +44,76 @@ <chapter id="Introduction"> <title>Introduction</title> <para> - kgdb is a source level debugger for linux kernel. It is used along - with gdb to debug a linux kernel. The expectation is that gdb can - be used to "break in" to the kernel to inspect memory, variables - and look through call stack information similar to what an - application developer would use gdb for. It is possible to place - breakpoints in kernel code and perform some limited execution - stepping. + The kernel has two different debugger front ends (kdb and kgdb) + which interface to the debug core. It is possible to use either + of the debugger front ends and dynamically transition between them + if you configure the kernel properly at compile and runtime. + </para> + <para> + Kdb is simplistic shell-style interface which you can use on a + system console with a keyboard or serial console. You can use it + to inspect memory, registers, process lists, dmesg, and even set + breakpoints to stop in a certain location. Kdb is not a source + level debugger, although you can set breakpoints and execute some + basic kernel run control. Kdb is mainly aimed at doing some + analysis to aid in development or diagnosing kernel problems. You + can access some symbols by name in kernel built-ins or in kernel + modules if the code was built + with <symbol>CONFIG_KALLSYMS</symbol>. + </para> + <para> + Kgdb is intended to be used as a source level debugger for the + Linux kernel. It is used along with gdb to debug a Linux kernel. + The expectation is that gdb can be used to "break in" to the + kernel to inspect memory, variables and look through call stack + information similar to the way an application developer would use + gdb to debug an application. It is possible to place breakpoints + in kernel code and perform some limited execution stepping. </para> <para> - Two machines are required for using kgdb. One of these machines is a - development machine and the other is a test machine. The kernel - to be debugged runs on the test machine. The development machine - runs an instance of gdb against the vmlinux file which contains - the symbols (not boot image such as bzImage, zImage, uImage...). - In gdb the developer specifies the connection parameters and - connects to kgdb. The type of connection a developer makes with - gdb depends on the availability of kgdb I/O modules compiled as - builtin's or kernel modules in the test machine's kernel. + Two machines are required for using kgdb. One of these machines is + a development machine and the other is the target machine. The + kernel to be debugged runs on the target machine. The development + machine runs an instance of gdb against the vmlinux file which + contains the symbols (not boot image such as bzImage, zImage, + uImage...). In gdb the developer specifies the connection + parameters and connects to kgdb. The type of connection a + developer makes with gdb depends on the availability of kgdb I/O + modules compiled as built-ins or loadable kernel modules in the test + machine's kernel. </para> </chapter> <chapter id="CompilingAKernel"> - <title>Compiling a kernel</title> + <title>Compiling a kernel</title> + <para> + <itemizedlist> + <listitem><para>In order to enable compilation of kdb, you must first enable kgdb.</para></listitem> + <listitem><para>The kgdb test compile options are described in the kgdb test suite chapter.</para></listitem> + </itemizedlist> + </para> + <sect1 id="CompileKGDB"> + <title>Kernel config options for kgdb</title> <para> To enable <symbol>CONFIG_KGDB</symbol> you should first turn on "Prompt for development and/or incomplete code/drivers" (CONFIG_EXPERIMENTAL) in "General setup", then under the - "Kernel debugging" select "KGDB: kernel debugging with remote gdb". + "Kernel debugging" select "KGDB: kernel debugger". + </para> + <para> + While it is not a hard requirement that you have symbols in your + vmlinux file, gdb tends not to be very useful without the symbolic + data, so you will want to turn + on <symbol>CONFIG_DEBUG_INFO</symbol> which is called "Compile the + kernel with debug info" in the config menu. </para> <para> It is advised, but not required that you turn on the - CONFIG_FRAME_POINTER kernel option. This option inserts code to - into the compiled executable which saves the frame information in - registers or on the stack at different points which will allow a - debugger such as gdb to more accurately construct stack back traces - while debugging the kernel. + <symbol>CONFIG_FRAME_POINTER</symbol> kernel option which is called "Compile the + kernel with frame pointers" in the config menu. This option + inserts code to into the compiled executable which saves the frame + information in registers or on the stack at different points which + allows a debugger such as gdb to more accurately construct + stack back traces while debugging the kernel. </para> <para> If the architecture that you are using supports the kernel option @@ -116,38 +126,160 @@ this option. </para> <para> - Next you should choose one of more I/O drivers to interconnect debugging - host and debugged target. Early boot debugging requires a KGDB - I/O driver that supports early debugging and the driver must be - built into the kernel directly. Kgdb I/O driver configuration - takes place via kernel or module parameters, see following - chapter. + Next you should choose one of more I/O drivers to interconnect + debugging host and debugged target. Early boot debugging requires + a KGDB I/O driver that supports early debugging and the driver + must be built into the kernel directly. Kgdb I/O driver + configuration takes place via kernel or module parameters which + you can learn more about in the in the section that describes the + parameter "kgdboc". </para> - <para> - The kgdb test compile options are described in the kgdb test suite chapter. + <para>Here is an example set of .config symbols to enable or + disable for kgdb: + <itemizedlist> + <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> + <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> + <listitem><para>CONFIG_KGDB=y</para></listitem> + <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> + </itemizedlist> </para> - + </sect1> + <sect1 id="CompileKDB"> + <title>Kernel config options for kdb</title> + <para>Kdb is quite a bit more complex than the simple gdbstub + sitting on top of the kernel's debug core. Kdb must implement a + shell, and also adds some helper functions in other parts of the + kernel, responsible for printing out interesting data such as what + you would see if you ran "lsmod", or "ps". In order to build kdb + into the kernel you follow the same steps as you would for kgdb. + </para> + <para>The main config option for kdb + is <symbol>CONFIG_KGDB_KDB</symbol> which is called "KGDB_KDB: + include kdb frontend for kgdb" in the config menu. In theory you + would have already also selected an I/O driver such as the + CONFIG_KGDB_SERIAL_CONSOLE interface if you plan on using kdb on a + serial port, when you were configuring kgdb. + </para> + <para>If you want to use a PS/2-style keyboard with kdb, you would + select CONFIG_KDB_KEYBOARD which is called "KGDB_KDB: keyboard as + input device" in the config menu. The CONFIG_KDB_KEYBOARD option + is not used for anything in the gdb interface to kgdb. The + CONFIG_KDB_KEYBOARD option only works with kdb. + </para> + <para>Here is an example set of .config symbols to enable/disable kdb: + <itemizedlist> + <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> + <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> + <listitem><para>CONFIG_KGDB=y</para></listitem> + <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> + <listitem><para>CONFIG_KGDB_KDB=y</para></listitem> + <listitem><para>CONFIG_KDB_KEYBOARD=y</para></listitem> + </itemizedlist> + </para> + </sect1> </chapter> - <chapter id="EnableKGDB"> - <title>Enable kgdb for debugging</title> - <para> - In order to use kgdb you must activate it by passing configuration - information to one of the kgdb I/O drivers. If you do not pass any - configuration information kgdb will not do anything at all. Kgdb - will only actively hook up to the kernel trap hooks if a kgdb I/O - driver is loaded and configured. If you unconfigure a kgdb I/O - driver, kgdb will unregister all the kernel hook points. + <chapter id="kgdbKernelArgs"> + <title>Kernel Debugger Boot Arguments</title> + <para>This section describes the various runtime kernel + parameters that affect the configuration of the kernel debugger. + The following chapter covers using kdb and kgdb as well as + provides some examples of the configuration parameters.</para> + <sect1 id="kgdboc"> + <title>Kernel parameter: kgdboc</title> + <para>The kgdboc driver was originally an abbreviation meant to + stand for "kgdb over console". Today it is the primary mechanism + to configure how to communicate from gdb to kgdb as well as the + devices you want to use to interact with the kdb shell. + </para> + <para>For kgdb/gdb, kgdboc is designed to work with a single serial + port. It is intended to cover the circumstance where you want to + use a serial console as your primary console as well as using it to + perform kernel debugging. It is also possible to use kgdb on a + serial port which is not designated as a system console. Kgdboc + may be configured as a kernel built-in or a kernel loadable module. + You can only make use of <constant>kgdbwait</constant> and early + debugging if you build kgdboc into the kernel as a built-in. </para> + <sect2 id="kgdbocArgs"> + <title>kgdboc arguments</title> + <para>Usage: <constant>kgdboc=[kbd][[,]serial_device][,baud]</constant></para> + <sect3 id="kgdbocArgs1"> + <title>Using loadable module or built-in</title> <para> - All drivers can be reconfigured at run time, if - <symbol>CONFIG_SYSFS</symbol> and <symbol>CONFIG_MODULES</symbol> - are enabled, by echo'ing a new config string to - <constant>/sys/module/<driver>/parameter/<option></constant>. - The driver can be unconfigured by passing an empty string. You cannot - change the configuration while the debugger is attached. Make sure - to detach the debugger with the <constant>detach</constant> command - prior to trying unconfigure a kgdb I/O driver. + <orderedlist> + <listitem><para>As a kernel built-in:</para> + <para>Use the kernel boot argument: <constant>kgdboc=<tty-device>,[baud]</constant></para></listitem> + <listitem> + <para>As a kernel loadable module:</para> + <para>Use the command: <constant>modprobe kgdboc kgdboc=<tty-device>,[baud]</constant></para> + <para>Here are two examples of how you might formate the kgdboc + string. The first is for an x86 target using the first serial port. + The second example is for the ARM Versatile AB using the second + serial port. + <orderedlist> + <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> + <listitem><para><constant>kgdboc=ttyAMA1,115200</constant></para></listitem> + </orderedlist> </para> + </listitem> + </orderedlist></para> + </sect3> + <sect3 id="kgdbocArgs2"> + <title>Configure kgdboc at runtime with sysfs</title> + <para>At run time you can enable or disable kgdboc by echoing a + parameters into the sysfs. Here are two examples:</para> + <orderedlist> + <listitem><para>Enable kgdboc on ttyS0</para> + <para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + <listitem><para>Disable kgdboc</para> + <para><constant>echo "" > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + </orderedlist> + <para>NOTE: You do not need to specify the baud if you are + configuring the console on tty which is already configured or + open.</para> + </sect3> + <sect3 id="kgdbocArgs3"> + <title>More examples</title> + <para>You can configure kgdboc to use the keyboard, and or a serial device + depending on if you are using kdb and or kgdb, in one of the + following scenarios. + <orderedlist> + <listitem><para>kdb and kgdb over only a serial port</para> + <para><constant>kgdboc=<serial_device>[,baud]</constant></para> + <para>Example: <constant>kgdboc=ttyS0,115200</constant></para> + </listitem> + <listitem><para>kdb and kgdb with keyboard and a serial port</para> + <para><constant>kgdboc=kbd,<serial_device>[,baud]</constant></para> + <para>Example: <constant>kgdboc=kbd,ttyS0,115200</constant></para> + </listitem> + <listitem><para>kdb with a keyboard</para> + <para><constant>kgdboc=kbd</constant></para> + </listitem> + </orderedlist> + </para> + </sect3> + <para>NOTE: Kgdboc does not support interrupting the target via the + gdb remote protocol. You must manually send a sysrq-g unless you + have a proxy that splits console output to a terminal program. + A console proxy has a separate TCP port for the debugger and a separate + TCP port for the "human" console. The proxy can take care of sending + the sysrq-g for you. + </para> + <para>When using kgdboc with no debugger proxy, you can end up + connecting the debugger at one of two entry points. If an + exception occurs after you have loaded kgdboc, a message should + print on the console stating it is waiting for the debugger. In + this case you disconnect your terminal program and then connect the + debugger in its place. If you want to interrupt the target system + and forcibly enter a debug session you have to issue a Sysrq + sequence and then type the letter <constant>g</constant>. Then + you disconnect the terminal session and connect gdb. Your options + if you don't like this are to hack gdb to send the sysrq-g for you + as well as on the initial connect, or to use a debugger proxy that + allows an unmodified gdb to do the debugging. + </para> + </sect2> + </sect1> <sect1 id="kgdbwait"> <title>Kernel parameter: kgdbwait</title> <para> @@ -162,103 +294,204 @@ </para> <para> The kernel will stop and wait as early as the I/O driver and - architecture will allow when you use this option. If you build the - kgdb I/O driver as a kernel module kgdbwait will not do anything. + architecture allows when you use this option. If you build the + kgdb I/O driver as a loadable kernel module kgdbwait will not do + anything. </para> </sect1> - <sect1 id="kgdboc"> - <title>Kernel parameter: kgdboc</title> - <para> - The kgdboc driver was originally an abbreviation meant to stand for - "kgdb over console". Kgdboc is designed to work with a single - serial port. It was meant to cover the circumstance - where you wanted to use a serial console as your primary console as - well as using it to perform kernel debugging. Of course you can - also use kgdboc without assigning a console to the same port. + <sect1 id="kgdbcon"> + <title>Kernel parameter: kgdbcon</title> + <para> The kgdbcon feature allows you to see printk() messages + inside gdb while gdb is connected to the kernel. Kdb does not make + use of the kgdbcon feature. + </para> + <para>Kgdb supports using the gdb serial protocol to send console + messages to the debugger when the debugger is connected and running. + There are two ways to activate this feature. + <orderedlist> + <listitem><para>Activate with the kernel command line option:</para> + <para><constant>kgdbcon</constant></para> + </listitem> + <listitem><para>Use sysfs before configuring an I/O driver</para> + <para> + <constant>echo 1 > /sys/module/kgdb/parameters/kgdb_use_con</constant> + </para> + <para> + NOTE: If you do this after you configure the kgdb I/O driver, the + setting will not take effect until the next point the I/O is + reconfigured. + </para> + </listitem> + </orderedlist> + <para>IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an + active system console. An example incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant> + </para> + <para>It is possible to use this option with kgdboc on a tty that is not a system console. + </para> </para> - <sect2 id="UsingKgdboc"> - <title>Using kgdboc</title> - <para> - You can configure kgdboc via sysfs or a module or kernel boot line - parameter depending on if you build with CONFIG_KGDBOC as a module - or built-in. - <orderedlist> - <listitem><para>From the module load or build-in</para> - <para><constant>kgdboc=<tty-device>,[baud]</constant></para> + </sect1> + </chapter> + <chapter id="usingKDB"> + <title>Using kdb</title> <para> - The example here would be if your console port was typically ttyS0, you would use something like <constant>kgdboc=ttyS0,115200</constant> or on the ARM Versatile AB you would likely use <constant>kgdboc=ttyAMA0,115200</constant> + </para> + <sect1 id="quickKDBserial"> + <title>Quick start for kdb on a serial port</title> + <para>This is a quick example of how to use kdb.</para> + <para><orderedlist> + <listitem><para>Boot kernel with arguments: + <itemizedlist> + <listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem> + </itemizedlist></para> + <para>OR</para> + <para>Configure kgdboc after the kernel booted; assuming you are using a serial port console: + <itemizedlist> + <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + </itemizedlist> </para> </listitem> - <listitem><para>From sysfs</para> - <para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para> + <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para> + <itemizedlist> + <listitem><para>When logged in as root or with a super user session you can run:</para> + <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> + <listitem><para>Example using minicom 2.2</para> + <para>Press: <constant>Control-a</constant></para> + <para>Press: <constant>f</constant></para> + <para>Press: <constant>g</constant></para> </listitem> - </orderedlist> - </para> - <para> - NOTE: Kgdboc does not support interrupting the target via the - gdb remote protocol. You must manually send a sysrq-g unless you - have a proxy that splits console output to a terminal problem and - has a separate port for the debugger to connect to that sends the - sysrq-g for you. + <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para> + <para>Press: <constant>Control-]</constant></para> + <para>Type in:<constant>send break</constant></para> + <para>Press: <constant>Enter</constant></para> + <para>Press: <constant>g</constant></para> + </listitem> + </itemizedlist> + </listitem> + <listitem><para>From the kdb prompt you can run the "help" command to see a complete list of the commands that are available.</para> + <para>Some useful commands in kdb include: + <itemizedlist> + <listitem><para>lsmod -- Shows where kernel modules are loaded</para></listitem> + <listitem><para>ps -- Displays only the active processes</para></listitem> + <listitem><para>ps A -- Shows all the processes</para></listitem> + <listitem><para>summary -- Shows kernel version info and memory usage</para></listitem> + <listitem><para>bt -- Get a backtrace of the current process using dump_stack()</para></listitem> + <listitem><para>dmesg -- View the kernel syslog buffer</para></listitem> + <listitem><para>go -- Continue the system</para></listitem> + </itemizedlist> </para> - <para>When using kgdboc with no debugger proxy, you can end up - connecting the debugger for one of two entry points. If an - exception occurs after you have loaded kgdboc a message should print - on the console stating it is waiting for the debugger. In case you - disconnect your terminal program and then connect the debugger in - its place. If you want to interrupt the target system and forcibly - enter a debug session you have to issue a Sysrq sequence and then - type the letter <constant>g</constant>. Then you disconnect the - terminal session and connect gdb. Your options if you don't like - this are to hack gdb to send the sysrq-g for you as well as on the - initial connect, or to use a debugger proxy that allows an - unmodified gdb to do the debugging. + </listitem> + <listitem> + <para>When you are done using kdb you need to consider rebooting the + system or using the "go" command to resuming normal kernel + execution. If you have paused the kernel for a lengthy period of + time, applications that rely on timely networking or anything to do + with real wall clock time could be adversely affected, so you + should take this into consideration when using the kernel + debugger.</para> + </listitem> + </orderedlist></para> + </sect1> + <sect1 id="quickKDBkeyboard"> + <title>Quick start for kdb using a keyboard connected console</title> + <para>This is a quick example of how to use kdb with a keyboard.</para> + <para><orderedlist> + <listitem><para>Boot kernel with arguments: + <itemizedlist> + <listitem><para><constant>kgdboc=kbd</constant></para></listitem> + </itemizedlist></para> + <para>OR</para> + <para>Configure kgdboc after the kernel booted: + <itemizedlist> + <listitem><para><constant>echo kbd > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + </itemizedlist> </para> - </sect2> + </listitem> + <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para> + <itemizedlist> + <listitem><para>When logged in as root or with a super user session you can run:</para> + <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> + <listitem><para>Example using a laptop keyboard</para> + <para>Press and hold down: <constant>Alt</constant></para> + <para>Press and hold down: <constant>Fn</constant></para> + <para>Press and release the key with the label: <constant>SysRq</constant></para> + <para>Release: <constant>Fn</constant></para> + <para>Press and release: <constant>g</constant></para> + <para>Release: <constant>Alt</constant></para> + </listitem> + <listitem><para>Example using a PS/2 101-key keyboard</para> + <para>Press and hold down: <constant>Alt</constant></para> + <para>Press and release the key with the label: <constant>SysRq</constant></para> + <para>Press and release: <constant>g</constant></para> + <para>Release: <constant>Alt</constant></para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>Now type in a kdb command such as "help", "dmesg", "bt" or "go" to continue kernel execution.</para> + </listitem> + </orderedlist></para> </sect1> - <sect1 id="kgdbcon"> - <title>Kernel parameter: kgdbcon</title> - <para> - Kgdb supports using the gdb serial protocol to send console messages - to the debugger when the debugger is connected and running. There - are two ways to activate this feature. + </chapter> + <chapter id="EnableKGDB"> + <title>Using kgdb / gdb</title> + <para>In order to use kgdb you must activate it by passing + configuration information to one of the kgdb I/O drivers. If you + do not pass any configuration information kgdb will not do anything + at all. Kgdb will only actively hook up to the kernel trap hooks + if a kgdb I/O driver is loaded and configured. If you unconfigure + a kgdb I/O driver, kgdb will unregister all the kernel hook points. + </para> + <para> All kgdb I/O drivers can be reconfigured at run time, if + <symbol>CONFIG_SYSFS</symbol> and <symbol>CONFIG_MODULES</symbol> + are enabled, by echo'ing a new config string to + <constant>/sys/module/<driver>/parameter/<option></constant>. + The driver can be unconfigured by passing an empty string. You cannot + change the configuration while the debugger is attached. Make sure + to detach the debugger with the <constant>detach</constant> command + prior to trying to unconfigure a kgdb I/O driver. + </para> + <sect1 id="ConnectingGDB"> + <title>Connecting with gdb to a serial port</title> <orderedlist> - <listitem><para>Activate with the kernel command line option:</para> - <para><constant>kgdbcon</constant></para> + <listitem><para>Configure kgdboc</para> + <para>Boot kernel with arguments: + <itemizedlist> + <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> + </itemizedlist></para> + <para>OR</para> + <para>Configure kgdboc after the kernel booted: + <itemizedlist> + <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + </itemizedlist></para> </listitem> - <listitem><para>Use sysfs before configuring an io driver</para> - <para> - <constant>echo 1 > /sys/module/kgdb/parameters/kgdb_use_con</constant> - </para> - <para> - NOTE: If you do this after you configure the kgdb I/O driver, the - setting will not take effect until the next point the I/O is - reconfigured. - </para> + <listitem> + <para>Stop kernel execution (break into the debugger)</para> + <para>In order to connect to gdb via kgdboc, the kernel must + first be stopped. There are several ways to stop the kernel which + include using kgdbwait as a boot argument, via a sysrq-g, or running + the kernel until it takes an exception where it waits for the + debugger to attach. + <itemizedlist> + <listitem><para>When logged in as root or with a super user session you can run:</para> + <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> + <listitem><para>Example using minicom 2.2</para> + <para>Press: <constant>Control-a</constant></para> + <para>Press: <constant>f</constant></para> + <para>Press: <constant>g</constant></para> </listitem> - </orderedlist> - </para> - <para> - IMPORTANT NOTE: Using this option with kgdb over the console - (kgdboc) is not supported. + <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para> + <para>Press: <constant>Control-]</constant></para> + <para>Type in:<constant>send break</constant></para> + <para>Press: <constant>Enter</constant></para> + <para>Press: <constant>g</constant></para> + </listitem> + </itemizedlist> </para> - </sect1> - </chapter> - <chapter id="ConnectingGDB"> - <title>Connecting gdb</title> - <para> - If you are using kgdboc, you need to have used kgdbwait as a boot - argument, issued a sysrq-g, or the system you are going to debug - has already taken an exception and is waiting for the debugger to - attach before you can connect gdb. - </para> - <para> - If you are not using different kgdb I/O driver other than kgdboc, - you should be able to connect and the target will automatically - respond. - </para> + </listitem> + <listitem> + <para>Connect from from gdb</para> <para> - Example (using a serial port): + Example (using a directly connected port): </para> <programlisting> % gdb ./vmlinux @@ -266,7 +499,7 @@ (gdb) target remote /dev/ttyS0 </programlisting> <para> - Example (kgdb to a terminal server on tcp port 2012): + Example (kgdb to a terminal server on TCP port 2012): </para> <programlisting> % gdb ./vmlinux @@ -283,6 +516,83 @@ communications. You do this prior to issuing the <constant>target remote</constant> command by typing in: <constant>set debug remote 1</constant> </para> + </listitem> + </orderedlist> + <para>Remember if you continue in gdb, and need to "break in" again, + you need to issue an other sysrq-g. It is easy to create a simple + entry point by putting a breakpoint at <constant>sys_sync</constant> + and then you can run "sync" from a shell or script to break into the + debugger.</para> + </sect1> + </chapter> + <chapter id="switchKdbKgdb"> + <title>kgdb and kdb interoperability</title> + <para>It is possible to transition between kdb and kgdb dynamically. + The debug core will remember which you used the last time and + automatically start in the same mode.</para> + <sect1> + <title>Switching between kdb and kgdb</title> + <sect2> + <title>Switching from kgdb to kdb</title> + <para> + There are two ways to switch from kgdb to kdb: you can use gdb to + issue a maintenance packet, or you can blindly type the command $3#33. + Whenever kernel debugger stops in kgdb mode it will print the + message <constant>KGDB or $3#33 for KDB</constant>. It is important + to note that you have to type the sequence correctly in one pass. + You cannot type a backspace or delete because kgdb will interpret + that as part of the debug stream. + <orderedlist> + <listitem><para>Change from kgdb to kdb by blindly typing:</para> + <para><constant>$3#33</constant></para></listitem> + <listitem><para>Change from kgdb to kdb with gdb</para> + <para><constant>maintenance packet 3</constant></para> + <para>NOTE: Now you must kill gdb. Typically you press control-z and + issue the command: kill -9 %</para></listitem> + </orderedlist> + </para> + </sect2> + <sect2> + <title>Change from kdb to kgdb</title> + <para>There are two ways you can change from kdb to kgdb. You can + manually enter kgdb mode by issuing the kgdb command from the kdb + shell prompt, or you can connect gdb while the kdb shell prompt is + active. The kdb shell looks for the typical first commands that gdb + would issue with the gdb remote protocol and if it sees one of those + commands it automatically changes into kgdb mode.</para> + <orderedlist> + <listitem><para>From kdb issue the command:</para> + <para><constant>kgdb</constant></para> + <para>Now disconnect your terminal program and connect gdb in its place</para></listitem> + <listitem><para>At the kdb prompt, disconnect the terminal program and connect gdb in its place.</para></listitem> + </orderedlist> + </sect2> + </sect1> + <sect1> + <title>Running kdb commands from gdb</title> + <para>It is possible to run a limited set of kdb commands from gdb, + using the gdb monitor command. You don't want to execute any of the + run control or breakpoint operations, because it can disrupt the + state of the kernel debugger. You should be using gdb for + breakpoints and run control operations if you have gdb connected. + The more useful commands to run are things like lsmod, dmesg, ps or + possibly some of the memory information commands. To see all the kdb + commands you can run <constant>monitor help</constant>.</para> + <para>Example: + <informalexample><programlisting> +(gdb) monitor ps +1 idle process (state I) and +27 sleeping system daemon (state M) processes suppressed, +use 'ps A' to see all. +Task Addr Pid Parent [*] cpu State Thread Command + +0xc78291d0 1 0 0 0 S 0xc7829404 init +0xc7954150 942 1 0 0 S 0xc7954384 dropbear +0xc78789c0 944 1 0 0 S 0xc7878bf4 sh +(gdb) + </programlisting></informalexample> + </para> + </sect1> </chapter> <chapter id="KGDBTestSuite"> <title>kgdb Test Suite</title> @@ -309,34 +619,36 @@ </para> </chapter> <chapter id="CommonBackEndReq"> - <title>KGDB Internals</title> + <title>Kernel Debugger Internals</title> <sect1 id="kgdbArchitecture"> <title>Architecture Specifics</title> <para> - Kgdb is organized into three basic components: + The kernel debugger is organized into a number of components: <orderedlist> - <listitem><para>kgdb core</para> + <listitem><para>The debug core</para> <para> - The kgdb core is found in kernel/kgdb.c. It contains: + The debug core is found in kernel/debugger/debug_core.c. It contains: <itemizedlist> - <listitem><para>All the logic to implement the gdb serial protocol</para></listitem> - <listitem><para>A generic OS exception handler which includes sync'ing the processors into a stopped state on an multi cpu system.</para></listitem> + <listitem><para>A generic OS exception handler which includes + sync'ing the processors into a stopped state on an multi-CPU + system.</para></listitem> <listitem><para>The API to talk to the kgdb I/O drivers</para></listitem> - <listitem><para>The API to make calls to the arch specific kgdb implementation</para></listitem> + <listitem><para>The API to make calls to the arch-specific kgdb implementation</para></listitem> <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem> <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem> + <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem> </itemizedlist> </para> </listitem> - <listitem><para>kgdb arch specific implementation</para> + <listitem><para>kgdb arch-specific implementation</para> <para> This implementation is generally found in arch/*/kernel/kgdb.c. As an example, arch/x86/kernel/kgdb.c contains the specifics to implement HW breakpoint as well as the initialization to dynamically register and unregister for the trap handlers on - this architecture. The arch specific portion implements: + this architecture. The arch-specific portion implements: <itemizedlist> - <listitem><para>contains an arch specific trap catcher which + <listitem><para>contains an arch-specific trap catcher which invokes kgdb_handle_exception() to start kgdb about doing its work</para></listitem> <listitem><para>translation to and from gdb specific packet format to pt_regs</para></listitem> @@ -347,11 +659,35 @@ </itemizedlist> </para> </listitem> + <listitem><para>gdbstub frontend (aka kgdb)</para> + <para>The gdbstub is located in kernel/debug/gdbstub.c. It contains:</para> + <itemizedlist> + <listitem><para>All the logic to implement the gdb serial protocol</para></listitem> + </itemizedlist> + </listitem> + <listitem><para>kdb frontend</para> + <para>The kdb debugger shell is broken down into a number of + components. The kdb core is located in kernel/debug/kdb. There + are a number of helper functions in some of the other kernel + components to make it possible for kdb to examine and report + information about the kernel without taking locks that could + cause a kernel deadlock. The kdb core contains implements the following functionality.</para> + <itemizedlist> + <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> + <listitem><para>The implementation for kdb_printf() which + emits messages directly to I/O drivers, bypassing the kernel + log.</para></listitem> + <listitem><para>SW / HW breakpoint management for the kdb shell</para></listitem> + </itemizedlist> + </listitem> <listitem><para>kgdb I/O driver</para> <para> - Each kgdb I/O driver has to provide an implemenation for the following: + Each kgdb I/O driver has to provide an implementation for the following: <itemizedlist> - <listitem><para>configuration via builtin or module</para></listitem> + <listitem><para>configuration via built-in or module</para></listitem> <listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem> <listitem><para>read and write character interface</para></listitem> <listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem> @@ -416,15 +752,15 @@ underlying low level to the hardware driver having "polling hooks" which the to which the tty driver is attached. In the initial implementation of kgdboc it the serial_core was changed to expose a - low level uart hook for doing polled mode reading and writing of a + low level UART hook for doing polled mode reading and writing of a single character while in an atomic context. When kgdb makes an I/O request to the debugger, kgdboc invokes a call back in the serial - core which in turn uses the call back in the uart driver. It is - certainly possible to extend kgdboc to work with non-uart based + core which in turn uses the call back in the UART driver. It is + certainly possible to extend kgdboc to work with non-UART based consoles in the future. </para> <para> - When using kgdboc with a uart, the uart driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting> + When using kgdboc with a UART, the UART driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting> #ifdef CONFIG_CONSOLE_POLL .poll_get_char = serial8250_get_poll_char, .poll_put_char = serial8250_put_poll_char, @@ -434,7 +770,7 @@ <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above. Keep in mind that polling hooks have to be implemented in such a way that they can be called from an atomic context and have to restore - the state of the uart chip on return such that the system can return + the state of the UART chip on return such that the system can return to normal when the debugger detaches. You need to be very careful with any kind of lock you consider, because failing here is most going to mean pressing the reset button. @@ -453,6 +789,10 @@ <itemizedlist> <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem> </itemizedlist> + In Jan 2010 this document was updated to include kdb. + <itemizedlist> + <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem> + </itemizedlist> </para> </chapter> </book> diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl index 133cd6c..020ac80 100644 --- a/Documentation/DocBook/mtdnand.tmpl +++ b/Documentation/DocBook/mtdnand.tmpl @@ -269,7 +269,7 @@ static void board_hwcontrol(struct mtd_info *mtd, int cmd) information about the device. </para> <programlisting> -int __init board_init (void) +static int __init board_init (void) { struct nand_chip *this; int err = 0; diff --git a/Documentation/PCI/pcieaer-howto.txt b/Documentation/PCI/pcieaer-howto.txt index be21001..26d3d94 100644 --- a/Documentation/PCI/pcieaer-howto.txt +++ b/Documentation/PCI/pcieaer-howto.txt @@ -13,7 +13,7 @@ Reporting (AER) driver and provides information on how to use it, as well as how to enable the drivers of endpoint devices to conform with PCI Express AER driver. -1.2 Copyright Intel Corporation 2006. +1.2 Copyright (C) Intel Corporation 2006. 1.3 What is the PCI Express AER Driver? @@ -71,15 +71,11 @@ console. If it's a correctable error, it is outputed as a warning. Otherwise, it is printed as an error. So users could choose different log level to filter out correctable error messages. -Below shows an example. -+------ PCI-Express Device Error -----+ -Error Severity : Uncorrected (Fatal) -PCIE Bus Error type : Transaction Layer -Unsupported Request : First -Requester ID : 0500 -VendorID=8086h, DeviceID=0329h, Bus=05h, Device=00h, Function=00h -TLB Header: -04000001 00200a03 05010000 00050100 +Below shows an example: +0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID) +0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000 +0000:50:00.0: [20] Unsupported Request (First) +0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100 In the example, 'Requester ID' means the ID of the device who sends the error message to root port. Pls. refer to pci express specs for @@ -112,7 +108,7 @@ but the PCI Express link itself is fully functional. Fatal errors, on the other hand, cause the link to be unreliable. When AER is enabled, a PCI Express device will automatically send an -error message to the PCIE root port above it when the device captures +error message to the PCIe root port above it when the device captures an error. The Root Port, upon receiving an error reporting message, internally processes and logs the error message in its PCI Express capability structure. Error information being logged includes storing @@ -198,8 +194,9 @@ to reset link, AER port service driver is required to provide the function to reset link. Firstly, kernel looks for if the upstream component has an aer driver. If it has, kernel uses the reset_link callback of the aer driver. If the upstream component has no aer driver -and the port is downstream port, we will use the aer driver of the -root port who reports the AER error. As for upstream ports, +and the port is downstream port, we will perform a hot reset as the +default by setting the Secondary Bus Reset bit of the Bridge Control +register associated with the downstream port. As for upstream ports, they should provide their own aer service drivers with reset_link function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes @@ -253,11 +250,11 @@ cleanup uncorrectable status register. Pls. refer to section 3.3. 4. Software error injection -Debugging PCIE AER error recovery code is quite difficult because it +Debugging PCIe AER error recovery code is quite difficult because it is hard to trigger real hardware errors. Software based error -injection can be used to fake various kinds of PCIE errors. +injection can be used to fake various kinds of PCIe errors. -First you should enable PCIE AER software error injection in kernel +First you should enable PCIe AER software error injection in kernel configuration, that is, following item should be in your .config. CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist index 8916ca4..da0382d 100644 --- a/Documentation/SubmitChecklist +++ b/Documentation/SubmitChecklist @@ -18,6 +18,8 @@ kernel patches. 2b: Passes allnoconfig, allmodconfig +2c: Builds successfully when using O=builddir + 3: Builds on multiple CPU architectures by using local cross-compile tools or some other build farm. @@ -95,3 +97,13 @@ kernel patches. 25: If any ioctl's are added by the patch, then also update Documentation/ioctl/ioctl-number.txt. + +26: If your modified source code depends on or uses any of the kernel + APIs or features that are related to the following kconfig symbols, + then test multiple builds with the related kconfig symbols disabled + and/or =m (if that option is available) [not all of these at the + same time, just various/random combinations of them]: + + 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 (but latter with CONFIG_NET=y) diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index 99e72a8..4947fd8 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -130,6 +130,8 @@ Linux kernel master tree: ftp.??.kernel.org:/pub/linux/kernel/... ?? == your country code, such as "us", "uk", "fr", etc. + http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git + Linux kernel mailing list: linux-kernel@vger.kernel.org [mail majordomo@vger.kernel.org to subscribe] @@ -160,3 +162,6 @@ How to NOT write kernel driver by Arjan van de Ven: Kernel Janitor: http://janitor.kernelnewbies.org/ + +GIT, Fast Version Control System: + http://git-scm.com/ diff --git a/Documentation/cgroups/blkio-controller.txt b/Documentation/cgroups/blkio-controller.txt index 630879c..48e0b21 100644 --- a/Documentation/cgroups/blkio-controller.txt +++ b/Documentation/cgroups/blkio-controller.txt @@ -17,6 +17,9 @@ HOWTO You can do a very simple testing of running two dd threads in two different cgroups. Here is what you can do. +- Enable Block IO controller + CONFIG_BLK_CGROUP=y + - Enable group scheduling in CFQ CONFIG_CFQ_GROUP_IOSCHED=y @@ -54,32 +57,52 @@ cgroups. Here is what you can do. Various user visible config options =================================== -CONFIG_CFQ_GROUP_IOSCHED - - Enables group scheduling in CFQ. Currently only 1 level of group - creation is allowed. - -CONFIG_DEBUG_CFQ_IOSCHED - - Enables some debugging messages in blktrace. Also creates extra - cgroup file blkio.dequeue. - -Config options selected automatically -===================================== -These config options are not user visible and are selected/deselected -automatically based on IO scheduler configuration. - CONFIG_BLK_CGROUP - - Block IO controller. Selected by CONFIG_CFQ_GROUP_IOSCHED. + - Block IO controller. CONFIG_DEBUG_BLK_CGROUP - - Debug help. Selected by CONFIG_DEBUG_CFQ_IOSCHED. + - Debug help. Right now some additional stats file show up in cgroup + if this option is enabled. + +CONFIG_CFQ_GROUP_IOSCHED + - Enables group scheduling in CFQ. Currently only 1 level of group + creation is allowed. Details of cgroup files ======================= - blkio.weight - - Specifies per cgroup 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. +- blkio.weight_device + - One can specify per cgroup per device rules using this interface. + These rules override the default value of group weight as specified + by blkio.weight. + + Following is the format. + + #echo dev_maj:dev_minor weight > /path/to/cgroup/blkio.weight_device + Configure weight=300 on /dev/sdb (8:16) in this cgroup + # echo 8:16 300 > blkio.weight_device + # cat blkio.weight_device + dev weight + 8:16 300 + + Configure weight=500 on /dev/sda (8:0) in this cgroup + # echo 8:0 500 > blkio.weight_device + # cat blkio.weight_device + dev weight + 8:0 500 + 8:16 300 + + Remove specific weight for /dev/sda in this cgroup + # echo 8:0 0 > blkio.weight_device + # cat blkio.weight_device + dev weight + 8:16 300 + - blkio.time - disk time allocated to cgroup per device in milliseconds. First two fields specify the major and minor number of the device and @@ -92,13 +115,105 @@ Details of cgroup files third field specifies the number of sectors transferred by the group to/from the device. +- blkio.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. + +- blkio.io_serviced + - Number of IOs completed 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 IOs. + +- blkio.io_service_time + - Total amount of time between request dispatch and request completion + for the IOs done by this cgroup. This is in nanoseconds to make it + meaningful for flash devices too. For devices with queue depth of 1, + this time represents the actual service time. When queue_depth > 1, + that is no longer true as requests may be served out of order. This + may cause the service time for a given IO to include the service time + of multiple IOs when served out of order which may result in total + io_service_time > actual time elapsed. This time is 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 + io_service_time in ns. + +- blkio.io_wait_time + - Total amount of time the IOs for this cgroup spent waiting in the + scheduler queues for service. This can be greater than the total time + elapsed since it is cumulative io_wait_time for all IOs. It is not a + measure of total time the cgroup spent waiting but rather a measure of + the wait_time for its individual IOs. For devices with queue_depth > 1 + this metric does not include the time spent waiting for service once + the IO is dispatched to the device but till it actually gets serviced + (there might be a time lag here due to re-ordering of requests by the + device). This is in nanoseconds to make it meaningful for flash + devices too. This time is 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 io_wait_time in ns. + +- blkio.io_merged + - Total number of bios/requests merged into requests belonging to this + cgroup. This is further divided by the type of operation - read or + write, sync or async. + +- blkio.io_queued + - Total number of requests queued up at any given instant for this + cgroup. This is further divided by the type of operation - read or + write, sync or async. + +- blkio.avg_queue_size + - Debugging aid only enabled if CONFIG_DEBUG_BLK_CGROUP=y. + The average queue size for this cgroup over the entire time of this + cgroup's existence. Queue size samples are taken each time one of the + queues of this cgroup gets a timeslice. + +- blkio.group_wait_time + - Debugging aid only enabled if CONFIG_DEBUG_BLK_CGROUP=y. + This is the amount of time the cgroup had to wait since it became busy + (i.e., went from 0 to 1 request queued) to get a timeslice for one of + its queues. This is different from the io_wait_time which is the + cumulative total of the amount of time spent by each IO in that cgroup + waiting in the scheduler queue. This is in nanoseconds. If this is + read when the cgroup is in a waiting (for timeslice) state, the stat + will only report the group_wait_time accumulated till the last time it + got a timeslice and will not include the current delta. + +- blkio.empty_time + - Debugging aid only enabled if CONFIG_DEBUG_BLK_CGROUP=y. + This is the amount of time a cgroup spends without any pending + requests when not being served, i.e., it does not include any time + spent idling for one of the queues of the cgroup. This is in + nanoseconds. If this is read when the cgroup is in an empty state, + the stat will only report the empty_time accumulated till the last + time it had a pending request and will not include the current delta. + +- blkio.idle_time + - Debugging aid only enabled if CONFIG_DEBUG_BLK_CGROUP=y. + This is the amount of time spent by the IO scheduler idling for a + given cgroup in anticipation of a better request than the exising ones + from other queues/cgroups. This is in nanoseconds. If this is read + when the cgroup is in an idling state, the stat will only report the + idle_time accumulated till the last idle period and will not include + the current delta. + - blkio.dequeue - - Debugging aid only enabled if CONFIG_DEBUG_CFQ_IOSCHED=y. This + - Debugging aid only enabled if CONFIG_DEBUG_BLK_CGROUP=y. This gives the statistics about how many a times a group was dequeued from service tree of the device. First two fields specify the major and minor number of the device and third field specifies the number of times a group was dequeued from a particular device. +- 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 diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroups/cgroups.txt index 57444c2..b34823f 100644 --- a/Documentation/cgroups/cgroups.txt +++ b/Documentation/cgroups/cgroups.txt @@ -339,7 +339,7 @@ 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. -To mount a cgroup hierarchy with just the cpuset and numtasks +To mount a cgroup hierarchy with just the cpuset and memory subsystems, type: # mount -t cgroup -o cpuset,memory hier1 /dev/cgroup diff --git a/Documentation/cgroups/memory.txt b/Documentation/cgroups/memory.txt index 6cab1f2..7781857 100644 --- a/Documentation/cgroups/memory.txt +++ b/Documentation/cgroups/memory.txt @@ -1,18 +1,15 @@ Memory Resource Controller NOTE: The Memory Resource Controller has been generically been referred -to as the memory controller in this document. Do not confuse memory controller -used here with the memory controller that is used in hardware. + to as the memory controller in this document. Do not confuse memory + controller used here with the memory controller that is used in hardware. -Salient features - -a. Enable control of Anonymous, Page Cache (mapped and unmapped) and - Swap Cache memory pages. -b. The infrastructure allows easy addition of other types of memory to control -c. Provides *zero overhead* for non memory controller users -d. Provides a double LRU: global memory pressure causes reclaim from the - global LRU; a cgroup on hitting a limit, reclaims from the per - cgroup LRU +(For editors) +In this document: + When we mention a cgroup (cgroupfs's directory) with memory controller, + we call it "memory cgroup". When you see git-log and source code, you'll + see patch's title and function names tend to use "memcg". + In this document, we avoid using it. Benefits and Purpose of the memory controller @@ -33,6 +30,45 @@ d. A CD/DVD burner could control the amount of memory used by the e. There are several other use cases, find one or use the controller just for fun (to learn and hack on the VM subsystem). +Current Status: linux-2.6.34-mmotm(development version of 2010/April) + +Features: + - accounting anonymous pages, file caches, swap caches usage and limiting them. + - private LRU and reclaim routine. (system's global LRU and private LRU + work independently from each other) + - optionally, memory+swap usage can be accounted and limited. + - hierarchical accounting + - soft limit + - moving(recharging) account at moving a task is selectable. + - usage threshold notifier + - oom-killer disable knob and oom-notifier + - Root cgroup has no limit controls. + + Kernel memory and Hugepages are not under control yet. We just manage + pages on LRU. To add more controls, we have to take care of performance. + +Brief summary of control files. + + tasks # attach a task(thread) and show list of threads + cgroup.procs # show list of processes + cgroup.event_control # an interface for event_fd() + memory.usage_in_bytes # show current memory(RSS+Cache) usage. + memory.memsw.usage_in_bytes # show current memory+Swap usage + memory.limit_in_bytes # set/show limit of memory usage + memory.memsw.limit_in_bytes # set/show limit of memory+Swap usage + memory.failcnt # show the number of memory usage hits limits + memory.memsw.failcnt # show the number of memory+Swap hits limits + memory.max_usage_in_bytes # show max memory usage recorded + memory.memsw.usage_in_bytes # show max memory+Swap usage recorded + memory.soft_limit_in_bytes # set/show soft limit of memory usage + memory.stat # show various statistics + memory.use_hierarchy # set/show hierarchical account enabled + memory.force_empty # trigger forced move charge to parent + memory.swappiness # set/show swappiness parameter of vmscan + (See sysctl's vm.swappiness) + memory.move_charge_at_immigrate # set/show controls of moving charges + memory.oom_control # set/show oom controls. + 1. History The memory controller has a long history. A request for comments for the memory @@ -106,14 +142,14 @@ the necessary data structures and check if the cgroup that is being charged is over its limit. If it is then reclaim is invoked on the cgroup. More details can be found in the reclaim section of this document. If everything goes well, a page meta-data-structure called page_cgroup is -allocated and associated with the page. This routine also adds the page to -the per cgroup LRU. +updated. page_cgroup has its own LRU on cgroup. +(*) page_cgroup structure is allocated at boot/memory-hotplug time. 2.2.1 Accounting details All mapped anon pages (RSS) and cache pages (Page Cache) are accounted. -(some pages which never be reclaimable and will not be on global LRU - are not accounted. we just accounts pages under usual vm management.) +Some pages which are never reclaimable and will not be on the global LRU +are not accounted. We just account pages under usual VM management. RSS pages are accounted at page_fault unless they've already been accounted for earlier. A file page will be accounted for as Page Cache when it's @@ -121,12 +157,19 @@ inserted into inode (radix-tree). While it's mapped into the page tables of processes, duplicate accounting is carefully avoided. A RSS page is unaccounted when it's fully unmapped. A PageCache page is -unaccounted when it's removed from radix-tree. +unaccounted when it's removed from radix-tree. Even if RSS pages are fully +unmapped (by kswapd), they may exist as SwapCache in the system until they +are really freed. Such SwapCaches also also accounted. +A swapped-in page is not accounted until it's mapped. + +Note: The kernel does swapin-readahead and read multiple swaps at once. +This means swapped-in pages may contain pages for other tasks than a task +causing page fault. So, we avoid accounting at swap-in I/O. At page migration, accounting information is kept. -Note: we just account pages-on-lru because our purpose is to control amount -of used pages. not-on-lru pages are tend to be out-of-control from vm view. +Note: we just account pages-on-LRU because our purpose is to control amount +of used pages; not-on-LRU pages tend to be out-of-control from VM view. 2.3 Shared Page Accounting @@ -143,6 +186,7 @@ caller of swapoff rather than the users of shmem. 2.4 Swap Extension (CONFIG_CGROUP_MEM_RES_CTLR_SWAP) + Swap Extension allows you to record charge for swap. A swapped-in page is charged back to original page allocator if possible. @@ -150,13 +194,20 @@ When swap is accounted, following files are added. - memory.memsw.usage_in_bytes. - memory.memsw.limit_in_bytes. -usage of mem+swap is limited by memsw.limit_in_bytes. +memsw means memory+swap. Usage of memory+swap is limited by +memsw.limit_in_bytes. -* why 'mem+swap' rather than swap. +Example: Assume a system with 4G of swap. A task which allocates 6G of memory +(by mistake) under 2G memory limitation will use all swap. +In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap. +By using memsw limit, you can avoid system OOM which can be caused by swap +shortage. + +* why 'memory+swap' rather than swap. The global LRU(kswapd) can swap out arbitrary pages. Swap-out means to move account from memory to swap...there is no change in usage of -mem+swap. In other words, when we want to limit the usage of swap without -affecting global LRU, mem+swap limit is better than just limiting swap from +memory+swap. In other words, when we want to limit the usage of swap without +affecting global LRU, memory+swap limit is better than just limiting swap from OS point of view. * What happens when a cgroup hits memory.memsw.limit_in_bytes @@ -168,12 +219,12 @@ it by cgroup. 2.5 Reclaim -Each cgroup maintains a per cgroup LRU that consists of an active -and inactive list. When a cgroup goes over its limit, we first try +Each cgroup maintains a per cgroup LRU which has the same structure as +global VM. When a cgroup goes over its limit, we first try to reclaim memory from the cgroup so as to make space for the new pages that the cgroup has touched. If the reclaim is unsuccessful, an OOM routine is invoked to select and kill the bulkiest task in the -cgroup. +cgroup. (See 10. OOM Control below.) The reclaim algorithm has not been modified for cgroups, except that pages that are selected for reclaiming come from the per cgroup LRU @@ -184,13 +235,22 @@ limits on the root cgroup. Note2: When panic_on_oom is set to "2", the whole system will panic. -2. Locking +When oom event notifier is registered, event will be delivered. +(See oom_control section) + +2.6 Locking -The memory controller uses the following hierarchy + lock_page_cgroup()/unlock_page_cgroup() should not be called under + mapping->tree_lock. -1. zone->lru_lock is used for selecting pages to be isolated -2. mem->per_zone->lru_lock protects the per cgroup LRU (per zone) -3. lock_page_cgroup() is used to protect page->page_cgroup + Other lock order is following: + PG_locked. + mm->page_table_lock + zone->lru_lock + lock_page_cgroup. + In many cases, just lock_page_cgroup() is called. + per-zone-per-cgroup LRU (cgroup's private LRU) is just guarded by + zone->lru_lock, it has no lock of its own. 3. User Interface @@ -199,6 +259,7 @@ The memory controller uses the following hierarchy a. Enable CONFIG_CGROUPS b. Enable CONFIG_RESOURCE_COUNTERS c. Enable CONFIG_CGROUP_MEM_RES_CTLR +d. Enable CONFIG_CGROUP_MEM_RES_CTLR_SWAP (to use swap extension) 1. Prepare the cgroups # mkdir -p /cgroups @@ -206,31 +267,28 @@ c. Enable CONFIG_CGROUP_MEM_RES_CTLR 2. Make the new group and move bash into it # mkdir /cgroups/0 -# echo $$ > /cgroups/0/tasks +# echo $$ > /cgroups/0/tasks -Since now we're in the 0 cgroup, -We can alter the memory limit: +Since now we're in the 0 cgroup, we can alter the memory limit: # echo 4M > /cgroups/0/memory.limit_in_bytes NOTE: We can use a suffix (k, K, m, M, g or G) to indicate values in kilo, -mega or gigabytes. +mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes, Gibibytes.) + NOTE: We can write "-1" to reset the *.limit_in_bytes(unlimited). NOTE: We cannot set limits on the root cgroup any more. # cat /cgroups/0/memory.limit_in_bytes 4194304 -NOTE: The interface has now changed to display the usage in bytes -instead of pages - We can check the usage: # cat /cgroups/0/memory.usage_in_bytes 1216512 A successful write to this file does not guarantee a successful set of -this limit to the value written into the file. This can be due to a +this limit to the value written into the file. This can be due to a number of factors, such as rounding up to page boundaries or the total -availability of memory on the system. The user is required to re-read +availability of memory on the system. The user is required to re-read this file after a write to guarantee the value committed by the kernel. # echo 1 > memory.limit_in_bytes @@ -245,15 +303,23 @@ caches, RSS and Active pages/Inactive pages are shown. 4. Testing -Balbir posted lmbench, AIM9, LTP and vmmstress results [10] and [11]. -Apart from that v6 has been tested with several applications and regular -daily use. The controller has also been tested on the PPC64, x86_64 and -UML platforms. +For testing features and implementation, see memcg_test.txt. + +Performance test is also important. To see pure memory controller's overhead, +testing on tmpfs will give you good numbers of small overheads. +Example: do kernel make on tmpfs. + +Page-fault scalability is also important. At measuring parallel +page fault test, multi-process test may be better than multi-thread +test because it has noise of shared objects/status. + +But the above two are testing extreme situations. +Trying usual test under memory controller is always helpful. 4.1 Troubleshooting Sometimes a user might find that the application under a cgroup is -terminated. There are several causes for this: +terminated by OOM killer. There are several causes for this: 1. The cgroup limit is too low (just too low to do anything useful) 2. The user is using anonymous memory and swap is turned off or too low @@ -261,6 +327,9 @@ terminated. There are several causes for this: A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of some of the pages cached in the cgroup (page cache pages). +To know what happens, disable OOM_Kill by 10. OOM Control(see below) and +seeing what happens will be helpful. + 4.2 Task migration When a task migrates from one cgroup to another, its charge is not @@ -268,16 +337,19 @@ carried forward by default. The pages allocated from the original cgroup still remain charged to it, the charge is dropped when the page is freed or reclaimed. -Note: You can move charges of a task along with task migration. See 8. +You can move charges of a task along with task migration. +See 8. "Move charges at task migration" 4.3 Removing a cgroup A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a cgroup might have some charge associated with it, even though all -tasks have migrated away from it. -Such charges are freed(at default) or moved to its parent. When moved, -both of RSS and CACHES are moved to parent. -If both of them are busy, rmdir() returns -EBUSY. See 5.1 Also. +tasks have migrated away from it. (because we charge against pages, not +against tasks.) + +Such charges are freed or moved to their parent. At moving, both of RSS +and CACHES are moved to parent. +rmdir() may return -EBUSY if freeing/moving fails. See 5.1 also. Charges recorded in swap information is not updated at removal of cgroup. Recorded information is discarded and a cgroup which uses swap (swapcache) @@ -293,10 +365,10 @@ will be charged as a new owner of it. # echo 0 > memory.force_empty - Almost all pages tracked by this memcg will be unmapped and freed. Some of - pages cannot be freed because it's locked or in-use. Such pages are moved - to parent and this cgroup will be empty. But this may return -EBUSY in - some too busy case. + Almost all pages tracked by this memory cgroup will be unmapped and freed. + Some pages cannot be freed because they are locked or in-use. Such pages are + moved to parent and this cgroup will be empty. This may return -EBUSY if + VM is too busy to free/move all pages immediately. Typical use case of this interface is that calling this before rmdir(). Because rmdir() moves all pages to parent, some out-of-use page caches can be @@ -306,19 +378,41 @@ will be charged as a new owner of it. memory.stat file includes following statistics +# per-memory cgroup local status cache - # of bytes of page cache memory. rss - # of bytes of anonymous and swap cache memory. +mapped_file - # of bytes of mapped file (includes tmpfs/shmem) pgpgin - # of pages paged in (equivalent to # of charging events). pgpgout - # of pages paged out (equivalent to # of uncharging events). -active_anon - # of bytes of anonymous and swap cache memory on active - lru list. +swap - # of bytes of swap usage inactive_anon - # of bytes of anonymous memory and swap cache memory on - inactive lru list. -active_file - # of bytes of file-backed memory on active lru list. -inactive_file - # of bytes of file-backed memory on inactive lru list. + LRU list. +active_anon - # of bytes of anonymous and swap cache memory on active + inactive LRU list. +inactive_file - # of bytes of file-backed memory on inactive LRU list. +active_file - # of bytes of file-backed memory on active LRU list. unevictable - # of bytes of memory that cannot be reclaimed (mlocked etc). -The following additional stats are dependent on CONFIG_DEBUG_VM. +# status considering hierarchy (see memory.use_hierarchy settings) + +hierarchical_memory_limit - # of bytes of memory limit with regard to hierarchy + under which the memory cgroup is +hierarchical_memsw_limit - # of bytes of memory+swap limit with regard to + hierarchy under which memory cgroup is. + +total_cache - sum of all children's "cache" +total_rss - sum of all children's "rss" +total_mapped_file - sum of all children's "cache" +total_pgpgin - sum of all children's "pgpgin" +total_pgpgout - sum of all children's "pgpgout" +total_swap - sum of all children's "swap" +total_inactive_anon - sum of all children's "inactive_anon" +total_active_anon - sum of all children's "active_anon" +total_inactive_file - sum of all children's "inactive_file" +total_active_file - sum of all children's "active_file" +total_unevictable - sum of all children's "unevictable" + +# The following additional stats are dependent on CONFIG_DEBUG_VM. inactive_ratio - VM internal parameter. (see mm/page_alloc.c) recent_rotated_anon - VM internal parameter. (see mm/vmscan.c) @@ -327,24 +421,37 @@ recent_scanned_anon - VM internal parameter. (see mm/vmscan.c) recent_scanned_file - VM internal parameter. (see mm/vmscan.c) Memo: - recent_rotated means recent frequency of lru rotation. - recent_scanned means recent # of scans to lru. + recent_rotated means recent frequency of LRU rotation. + recent_scanned means recent # of scans to LRU. showing for better debug please see the code for meanings. Note: Only anonymous and swap cache memory is listed as part of 'rss' stat. This should not be confused with the true 'resident set size' or the - amount of physical memory used by the cgroup. Per-cgroup rss - accounting is not done yet. + amount of physical memory used by the cgroup. + 'rss + file_mapped" will give you resident set size of cgroup. + (Note: file and shmem may be shared among other cgroups. In that case, + file_mapped is accounted only when the memory cgroup is owner of page + cache.) 5.3 swappiness - Similar to /proc/sys/vm/swappiness, but affecting a hierarchy of groups only. - Following cgroups' swappiness can't be changed. - - root cgroup (uses /proc/sys/vm/swappiness). - - a cgroup which uses hierarchy and it has child cgroup. - - a cgroup which uses hierarchy and not the root of hierarchy. +Similar to /proc/sys/vm/swappiness, but affecting a hierarchy of groups only. +Following cgroups' swappiness can't be changed. +- root cgroup (uses /proc/sys/vm/swappiness). +- a cgroup which uses hierarchy and it has other cgroup(s) below it. +- a cgroup which uses hierarchy and not the root of hierarchy. + +5.4 failcnt + +A memory cgroup provides memory.failcnt and memory.memsw.failcnt files. +This failcnt(== failure count) shows the number of times that a usage counter +hit its limit. When a memory cgroup hits a limit, failcnt increases and +memory under it will be reclaimed. + +You can reset failcnt by writing 0 to failcnt file. +# echo 0 > .../memory.failcnt 6. Hierarchy support @@ -363,13 +470,13 @@ hierarchy In the diagram above, with hierarchical accounting enabled, all memory usage of e, is accounted to its ancestors up until the root (i.e, c and root), -that has memory.use_hierarchy enabled. If one of the ancestors goes over its +that has memory.use_hierarchy enabled. If one of the ancestors goes over its limit, the reclaim algorithm reclaims from the tasks in the ancestor and the children of the ancestor. 6.1 Enabling hierarchical accounting and reclaim -The memory controller by default disables the hierarchy feature. Support +A memory cgroup by default disables the hierarchy feature. Support can be enabled by writing 1 to memory.use_hierarchy file of the root cgroup # echo 1 > memory.use_hierarchy @@ -379,10 +486,10 @@ 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. + cgroups created below it. NOTE2: When panic_on_oom is set to "2", the whole system will panic in -case of an oom event in any cgroup. + case of an OOM event in any cgroup. 7. Soft limits @@ -392,7 +499,7 @@ is to allow control groups to use as much of the memory as needed, provided a. There is no memory contention b. They do not exceed their hard limit -When the system detects memory contention or low memory control groups +When the system detects memory contention or low memory, control groups are pushed back to their soft limits. If the soft limit of each control group is very high, they are pushed back as much as possible to make sure that one control group does not starve the others of memory. @@ -406,7 +513,7 @@ it gets invoked from balance_pgdat (kswapd). 7.1 Interface Soft limits can be setup by using the following commands (in this example we -assume a soft limit of 256 megabytes) +assume a soft limit of 256 MiB) # echo 256M > memory.soft_limit_in_bytes @@ -442,7 +549,7 @@ Note: Charges are moved only when you move mm->owner, IOW, a leader of a thread Note: If we cannot find enough space for the task in the destination cgroup, we try to make space by reclaiming memory. Task migration may fail if we cannot make enough space. -Note: It can take several seconds if you move charges in giga bytes order. +Note: It can take several seconds if you move charges much. And if you want disable it again: @@ -451,21 +558,27 @@ And if you want disable it again: 8.2 Type of charges which can be move Each bits of move_charge_at_immigrate has its own meaning about what type of -charges should be moved. +charges should be moved. But in any cases, it must be noted that an account of +a page or a swap can be moved only when it is charged to the task's current(old) +memory cgroup. bit | what type of charges would be moved ? -----+------------------------------------------------------------------------ 0 | A charge of an anonymous page(or swap of it) used by the target task. | Those pages and swaps must be used only by the target task. You must | enable Swap Extension(see 2.4) to enable move of swap charges. - -Note: Those pages and swaps must be charged to the old cgroup. -Note: More type of pages(e.g. file cache, shmem,) will be supported by other - bits in future. + -----+------------------------------------------------------------------------ + 1 | A charge of file pages(normal file, tmpfs file(e.g. ipc shared memory) + | and swaps of tmpfs file) mmapped by the target task. Unlike the case of + | anonymous pages, file pages(and swaps) in the range mmapped by the task + | will be moved even if the task hasn't done page fault, i.e. they might + | not be the task's "RSS", but other task's "RSS" that maps the same file. + | And mapcount of the page is ignored(the page can be moved even if + | page_mapcount(page) > 1). You must enable Swap Extension(see 2.4) to + | enable move of swap charges. 8.3 TODO -- Add support for other types of pages(e.g. file cache, shmem, etc.). - Implement madvise(2) to let users decide the vma to be moved or not to be moved. - All of moving charge operations are done under cgroup_mutex. It's not good @@ -473,22 +586,61 @@ Note: More type of pages(e.g. file cache, shmem,) will be supported by other 9. Memory thresholds -Memory controler implements memory thresholds using cgroups notification +Memory cgroup implements memory thresholds using cgroups notification API (see cgroups.txt). It allows to register multiple memory and memsw thresholds and gets notifications when it crosses. To register a threshold application need: - - create an eventfd using eventfd(2); - - open memory.usage_in_bytes or memory.memsw.usage_in_bytes; - - write string like "<event_fd> <memory.usage_in_bytes> <threshold>" to - cgroup.event_control. +- create an eventfd using eventfd(2); +- open memory.usage_in_bytes or memory.memsw.usage_in_bytes; +- write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to + cgroup.event_control. Application will be notified through eventfd when memory usage crosses threshold in any direction. It's applicable for root and non-root cgroup. -10. TODO +10. OOM Control + +memory.oom_control file is for OOM notification and other controls. + +Memory cgroup implements OOM notifier using cgroup notification +API (See cgroups.txt). It allows to register multiple OOM notification +delivery and gets notification when OOM happens. + +To register a notifier, application need: + - create an eventfd using eventfd(2) + - open memory.oom_control file + - write string like "<event_fd> <fd of memory.oom_control>" to + cgroup.event_control + +Application will be notified through eventfd when OOM happens. +OOM notification doesn't work for root cgroup. + +You can disable OOM-killer by writing "1" to memory.oom_control file, as: + + #echo 1 > memory.oom_control + +This operation is only allowed to the top cgroup of sub-hierarchy. +If OOM-killer is disabled, tasks under cgroup will hang/sleep +in memory cgroup's OOM-waitqueue when they request accountable memory. + +For running them, you have to relax the memory cgroup's OOM status by + * enlarge limit or reduce usage. +To reduce usage, + * kill some tasks. + * move some tasks to other group with account migration. + * remove some files (on tmpfs?) + +Then, stopped tasks will work again. + +At reading, current status of OOM is shown. + oom_kill_disable 0 or 1 (if 1, oom-killer is disabled) + under_oom 0 or 1 (if 1, the memory cgroup is under OOM, tasks may + be stopped.) + +11. TODO 1. Add support for accounting huge pages (as a separate controller) 2. Make per-cgroup scanner reclaim not-shared pages first diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process index d750321..97726eb 100644 --- a/Documentation/development-process/2.Process +++ b/Documentation/development-process/2.Process @@ -151,7 +151,7 @@ The stages that a patch goes through are, generally: well. - Wider review. When the patch is getting close to ready for mainline - inclusion, it will be accepted by a relevant subsystem maintainer - + 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 @@ -159,6 +159,15 @@ The stages that a patch goes through are, generally: the discovery of any problems resulting from the integration of this patch with work being done by others. +- Please note that most maintainers also have day jobs, so merging + your patch may not be their highest priority. If your patch is + getting feedback about changes that are needed, you should either + make those changes or justify why they should not be made. If your + patch has no review complaints but is not being merged by its + appropriate subsystem or driver maintainer, you should be persistent + in updating the patch to the current kernel so that it applies cleanly + and keep sending it for review and merging. + - Merging into the mainline. Eventually, a successful patch will be merged into the mainline repository managed by Linus Torvalds. More comments and/or problems may surface at this time; it is important that @@ -258,12 +267,8 @@ an appropriate subsystem tree or be sent directly to Linus. In a typical development cycle, approximately 10% of the patches going into the mainline get there via -mm. -The current -mm patch can always be found from the front page of - - http://kernel.org/ - -Those who want to see the current state of -mm can get the "-mm of the -moment" tree, found at: +The current -mm patch is available in the "mmotm" (-mm of the moment) +directory at: http://userweb.kernel.org/~akpm/mmotm/ @@ -298,6 +303,12 @@ 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. + 2.5: TOOLS @@ -319,9 +330,9 @@ developers; even if they do not use it for their own work, they'll need git to keep up with what other developers (and the mainline) are doing. Git is now packaged by almost all Linux distributions. There is a home -page at +page at: - http://git.or.cz/ + 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 diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics index a2cf740..8371794 100644 --- a/Documentation/development-process/7.AdvancedTopics +++ b/Documentation/development-process/7.AdvancedTopics @@ -25,7 +25,7 @@ long document in its own right. Instead, the focus here will be on how git fits into the kernel development process in particular. Developers who wish to come up to speed with git will find more information at: - http://git.or.cz/ + http://git-scm.com/ http://www.kernel.org/pub/software/scm/git/docs/user-manual.html diff --git a/Documentation/devices.txt b/Documentation/devices.txt index 53d64d3..1d83d12 100644 --- a/Documentation/devices.txt +++ b/Documentation/devices.txt @@ -443,6 +443,8 @@ Your cooperation is appreciated. 231 = /dev/snapshot System memory snapshot device 232 = /dev/kvm Kernel-based virtual machine (hardware virtualization extensions) 233 = /dev/kmview View-OS A process with a view + 234 = /dev/btrfs-control Btrfs control device + 235 = /dev/autofs Autofs control device 240-254 Reserved for local use 255 Reserved for MISC_DYNAMIC_MINOR diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index a86152a..672be01 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -646,3 +646,13 @@ 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> + +---------------------------- + diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index af16080..96d4293 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -380,7 +380,7 @@ prototypes: int (*open) (struct inode *, struct file *); int (*flush) (struct file *); int (*release) (struct inode *, struct file *); - int (*fsync) (struct file *, struct dentry *, int datasync); + int (*fsync) (struct file *, int datasync); int (*aio_fsync) (struct kiocb *, int datasync); int (*fasync) (int, struct file *, int); int (*lock) (struct file *, int, struct file_lock *); @@ -429,8 +429,9 @@ check_flags: no implementations. If your fs is not using generic_file_llseek, you need to acquire and release the appropriate locks in your ->llseek(). For many filesystems, it is probably safe to acquire the inode -mutex. Note some filesystems (i.e. remote ones) provide no -protection for i_size so you will need to use the BKL. +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 diff --git a/Documentation/filesystems/ext3.txt b/Documentation/filesystems/ext3.txt index 867c5b50..272f80d 100644 --- a/Documentation/filesystems/ext3.txt +++ b/Documentation/filesystems/ext3.txt @@ -59,8 +59,19 @@ commit=nrsec (*) Ext3 can be told to sync all its data and metadata Setting it to very large values will improve performance. -barrier=1 This enables/disables barriers. barrier=0 disables - it, barrier=1 enables it. +barrier=<0(*)|1> This enables/disables the use of write barriers in +barrier the jbd code. barrier=0 disables, barrier=1 enables. +nobarrier (*) This also requires an IO stack which can support + barriers, and if jbd gets an error on a barrier + write, it will disable again with a warning. + Write barriers enforce proper on-disk ordering + of journal commits, making volatile disk write caches + safe to use, at some performance penalty. If + your disks are battery-backed in one way or another, + disabling barriers may safely improve performance. + The mount options "barrier" and "nobarrier" can + also be used to enable or disable barriers, for + consistency with other ext3 mount options. orlov (*) This enables the new Orlov block allocator. It is enabled by default. diff --git a/Documentation/filesystems/gfs2.txt b/Documentation/filesystems/gfs2.txt index 5e3ab8f..0b59c02 100644 --- a/Documentation/filesystems/gfs2.txt +++ b/Documentation/filesystems/gfs2.txt @@ -1,7 +1,7 @@ Global File System ------------------ -http://sources.redhat.com/cluster/ +http://sources.redhat.com/cluster/wiki/ GFS is a cluster file system. It allows a cluster of computers to simultaneously use a block device that is shared between them (with FC, @@ -36,11 +36,11 @@ GFS2 is not on-disk compatible with previous versions of GFS, but it is pretty close. The following man pages can be found at the URL above: - fsck.gfs2 to repair a filesystem - gfs2_grow to expand a filesystem online - gfs2_jadd to add journals to a filesystem online - gfs2_tool to manipulate, examine and tune a filesystem + fsck.gfs2 to repair a filesystem + gfs2_grow to expand a filesystem online + gfs2_jadd to add journals to a filesystem online + gfs2_tool to manipulate, examine and tune a filesystem gfs2_quota to examine and change quota values in a filesystem gfs2_convert to convert a gfs filesystem to gfs2 in-place mount.gfs2 to help mount(8) mount a filesystem - mkfs.gfs2 to make a filesystem + mkfs.gfs2 to make a filesystem diff --git a/Documentation/filesystems/nilfs2.txt b/Documentation/filesystems/nilfs2.txt index cf6d0d8..d3e7673 100644 --- a/Documentation/filesystems/nilfs2.txt +++ b/Documentation/filesystems/nilfs2.txt @@ -50,8 +50,8 @@ NILFS2 supports the following mount options: (*) == default nobarrier Disables barriers. -errors=continue(*) Keep going on a filesystem error. -errors=remount-ro Remount the filesystem read-only on an error. +errors=continue Keep going on a filesystem error. +errors=remount-ro(*) Remount the filesystem read-only on an error. errors=panic Panic and halt the machine if an error occurs. cp=n Specify the checkpoint-number of the snapshot to be mounted. Checkpoints and snapshots are listed by lscp diff --git a/Documentation/filesystems/ocfs2.txt b/Documentation/filesystems/ocfs2.txt index c58b9f5..1f7ae14 100644 --- a/Documentation/filesystems/ocfs2.txt +++ b/Documentation/filesystems/ocfs2.txt @@ -80,3 +80,10 @@ 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. + 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. diff --git a/Documentation/filesystems/squashfs.txt b/Documentation/filesystems/squashfs.txt index b324c03..203f720 100644 --- a/Documentation/filesystems/squashfs.txt +++ b/Documentation/filesystems/squashfs.txt @@ -38,7 +38,8 @@ Hard link support: yes no Real inode numbers: yes no 32-bit uids/gids: yes no File creation time: yes no -Xattr and ACL support: no no +Xattr support: yes no +ACL support: no no Squashfs compresses data, inodes and directories. In addition, inode and directory data are highly compacted, and packed on byte boundaries. Each @@ -58,7 +59,7 @@ obtained from this site also. 3. SQUASHFS FILESYSTEM DESIGN ----------------------------- -A squashfs filesystem consists of seven parts, packed together on a byte +A squashfs filesystem consists of a maximum of eight parts, packed together on a byte alignment: --------------- @@ -80,6 +81,9 @@ alignment: |---------------| | uid/gid | | lookup table | + |---------------| + | xattr | + | table | --------------- Compressed data blocks are written to the filesystem as files are read from @@ -192,6 +196,26 @@ 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 +--------------- + +The xattr table contains extended attributes for each inode. The xattrs +for each inode are stored in a list, each list entry containing a type, +name and value field. The type field encodes the xattr prefix +("user.", "trusted." etc) and it also encodes how the name/value fields +should be interpreted. Currently the type indicates whether the value +is stored inline (in which case the value field contains the xattr value), +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. + +The xattr lists are packed into compressed 8K metadata blocks. +To reduce overhead in inodes, rather than storing the on-disk +location of the xattr list inside each inode, a 32-bit xattr id +is stored. This xattr id is mapped into the location of the xattr +list using a second xattr id lookup table. 4. TODOS AND OUTSTANDING ISSUES ------------------------------- @@ -199,9 +223,7 @@ it is small) is read at mount time and cached in memory. 4.1 Todo list ------------- -Implement Xattr and ACL support. The Squashfs 4.0 filesystem layout has hooks -for these but the code has not been written. Once the code has been written -the existing layout should not require modification. +Implement ACL support. 4.2 Squashfs internal cache --------------------------- diff --git a/Documentation/filesystems/sysfs-tagging.txt b/Documentation/filesystems/sysfs-tagging.txt new file mode 100644 index 0000000..caaaf12 --- /dev/null +++ b/Documentation/filesystems/sysfs-tagging.txt @@ -0,0 +1,42 @@ +Sysfs tagging +------------- + +(Taken almost verbatim from Eric Biederman's netns tagging patch +commit msg) + +The problem. Network devices show up in sysfs and with the network +namespace active multiple devices with the same name can show up in +the same directory, ouch! + +To avoid that problem and allow existing applications in network +namespaces to see the same interface that is currently presented in +sysfs, sysfs now has tagging directory support. + +By using the network namespace pointers as tags to separate out the +the sysfs directory entries we ensure that we don't have conflicts +in the directories and applications only see a limited set of +the network devices. + +Each sysfs directory entry may be tagged with zero or one +namespaces. A sysfs_dirent is augmented with a void *s_ns. If a +directory entry is tagged, then sysfs_dirent->s_flags will have a +flag between KOBJ_NS_TYPE_NONE and KOBJ_NS_TYPES, and s_ns will +point to the namespace to which it belongs. + +Each sysfs superblock's sysfs_super_info contains an array void +*ns[KOBJ_NS_TYPES]. When a a task in a tagging namespace +kobj_nstype first mounts sysfs, a new superblock is created. It +will be differentiated from other sysfs mounts by having its +s_fs_info->ns[kobj_nstype] set to the new namespace. Note that +through bind mounting and mounts propagation, a task can easily view +the contents of other namespaces' sysfs mounts. Therefore, when a +namespace exits, it will call kobj_ns_exit() to invalidate any +sysfs_dirent->s_ns pointers pointing to it. + +Users of this interface: +- define a type in the kobj_ns_type enumeration. +- call kobj_ns_type_register() with its kobj_ns_type_operations which has + - current_ns() which returns current's namespace + - netlink_ns() which returns a socket's namespace + - initial_ns() which returns the initial namesapce +- call kobj_ns_exit() when an individual tag is no longer valid diff --git a/Documentation/filesystems/tmpfs.txt b/Documentation/filesystems/tmpfs.txt index fe09a2c..98ef551 100644 --- a/Documentation/filesystems/tmpfs.txt +++ b/Documentation/filesystems/tmpfs.txt @@ -94,11 +94,19 @@ NodeList format is a comma-separated list of decimal numbers and ranges, a range being two hyphen-separated decimal numbers, the smallest and largest node numbers in the range. For example, mpol=bind:0-3,5,7,9-15 +A memory policy with a valid NodeList will be saved, as specified, for +use at file creation time. When a task allocates a file in the file +system, the mount option memory policy will be applied with a NodeList, +if any, modified by the calling task's cpuset constraints +[See Documentation/cgroups/cpusets.txt] and any optional flags, listed +below. If the resulting NodeLists is the empty set, the effective memory +policy for the file will revert to "default" policy. + NUMA memory allocation policies have optional flags that can be used in conjunction with their modes. These optional flags can be specified when tmpfs is mounted by appending them to the mode before the NodeList. See Documentation/vm/numa_memory_policy.txt for a list of all available -memory allocation policy mode flags. +memory allocation policy mode flags and their effect on memory policy. =static is equivalent to MPOL_F_STATIC_NODES =relative is equivalent to MPOL_F_RELATIVE_NODES diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index b668585..94677e7 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -401,11 +401,16 @@ otherwise noted. started might not be in the page cache at the end of the walk). - truncate: called by the VFS to change the size of a file. The + truncate: Deprecated. This will not be called if ->setsize is defined. + Called by the VFS to change the size of a file. The i_size field of the inode is set to the desired size by the VFS before this method is called. This method is called by the truncate(2) system call and related functionality. + Note: ->truncate and vmtruncate are deprecated. Do not add new + instances/calls of these. Filesystems should be converted to do their + truncate sequence via ->setattr(). + permission: called by the VFS to check for access rights on a POSIX-like filesystem. @@ -729,7 +734,7 @@ struct file_operations { int (*open) (struct inode *, struct file *); int (*flush) (struct file *); int (*release) (struct inode *, struct file *); - int (*fsync) (struct file *, struct dentry *, int datasync); + int (*fsync) (struct file *, int datasync); int (*aio_fsync) (struct kiocb *, int datasync); int (*fasync) (int, struct file *, int); int (*lock) (struct file *, int, struct file_lock *); diff --git a/Documentation/filesystems/xfs-delayed-logging-design.txt b/Documentation/filesystems/xfs-delayed-logging-design.txt new file mode 100644 index 0000000..d8119e9 --- /dev/null +++ b/Documentation/filesystems/xfs-delayed-logging-design.txt @@ -0,0 +1,816 @@ +XFS Delayed Logging Design +-------------------------- + +Introduction to Re-logging in XFS +--------------------------------- + +XFS logging is a combination of logical and physical logging. Some objects, +such as inodes and dquots, are logged in logical format where the details +logged are made up of the changes to in-core structures rather than on-disk +structures. Other objects - typically buffers - have their physical changes +logged. The reason for these differences is to reduce the amount of log space +required for objects that are frequently logged. Some parts of inodes are more +frequently logged than others, and inodes are typically more frequently logged +than any other object (except maybe the superblock buffer) so keeping the +amount of metadata logged low is of prime importance. + +The reason that this is such a concern is that XFS allows multiple separate +modifications to a single object to be carried in the log at any given time. +This allows the log to avoid needing to flush each change to disk before +recording a new change to the object. XFS does this via a method called +"re-logging". Conceptually, this is quite simple - all it requires is that any +new change to the object is recorded with a *new copy* of all the existing +changes in the new transaction that is written to the log. + +That is, if we have a sequence of changes A through to F, and the object was +written to disk after change D, we would see in the log the following series +of transactions, their contents and the log sequence number (LSN) of the +transaction: + + Transaction Contents LSN + A A X + B A+B X+n + C A+B+C X+n+m + D A+B+C+D X+n+m+o + <object written to disk> + E E Y (> X+n+m+o) + F E+F Yٍ+p + +In other words, each time an object is relogged, the new transaction contains +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 +direct encoding of the location in the log of the transaction. + +This relogging is also used to implement long-running, multiple-commit +transactions. These transaction are known as rolling transactions, and require +a special log reservation known as a permanent transaction reservation. A +typical example of a rolling transaction is the removal of extents from an +inode which can only be done at a rate of two extents per transaction because +of reservation size limitations. Hence a rolling extent removal transaction +keeps relogging the inode and btree buffers as they get modified in each +removal operation. This keeps them moving forward in the log as the operation +progresses, ensuring that current operation never gets blocked by itself if the +log wraps around. + +Hence it can be seen that the relogging operation is fundamental to the correct +working of the XFS journalling subsystem. From the above description, most +people should be able to see why the XFS metadata operations writes so much to +the log - repeated operations to the same objects write the same changes to +the log over and over again. Worse is the fact that objects tend to get +dirtier as they get relogged, so each subsequent transaction is writing more +metadata into the log. + +Another feature of the XFS transaction subsystem is that most transactions are +asynchronous. That is, they don't commit to disk until either a log buffer is +filled (a log buffer can hold multiple transactions) or a synchronous operation +forces the log buffers holding the transactions to disk. This means that XFS is +doing aggregation of transactions in memory - batching them, if you like - to +minimise the impact of the log IO on transaction throughput. + +The limitation on asynchronous transaction throughput is the number and size of +log buffers made available by the log manager. By default there are 8 log +buffers available and the size of each is 32kB - the size can be increased up +to 256kB by use of a mount option. + +Effectively, this gives us the maximum bound of outstanding metadata changes +that can be made to the filesystem at any point in time - if all the log +buffers are full and under IO, then no more transactions can be committed until +the current batch completes. It is now common for a single current CPU core to +be to able to issue enough transactions to keep the log buffers full and under +IO permanently. Hence the XFS journalling subsystem can be considered to be IO +bound. + +Delayed Logging: Concepts +------------------------- + +The key thing to note about the asynchronous logging combined with the +relogging technique XFS uses is that we can be relogging changed objects +multiple times before they are committed to disk in the log buffers. If we +return to the previous relogging example, it is entirely possible that +transactions A through D are committed to disk in the same log buffer. + +That is, a single log buffer may contain multiple copies of the same object, +but only one of those copies needs to be there - the last one "D", as it +contains all the changes from the previous changes. In other words, we have one +necessary copy in the log buffer, and three stale copies that are simply +wasting space. When we are doing repeated operations on the same set of +objects, these "stale objects" can be over 90% of the space used in the log +buffers. It is clear that reducing the number of stale objects written to the +log would greatly reduce the amount of metadata we write to the log, and this +is the fundamental goal of delayed logging. + +From a conceptual point of view, XFS is already doing relogging in memory (where +memory == log buffer), only it is doing it extremely inefficiently. It is using +logical to physical formatting to do the relogging because there is no +infrastructure to keep track of logical changes in memory prior to physically +formatting the changes in a transaction to the log buffer. Hence we cannot avoid +accumulating stale objects in the log buffers. + +Delayed logging is the name we've given to keeping and tracking transactional +changes to objects in memory outside the log buffer infrastructure. Because of +the relogging concept fundamental to the XFS journalling subsystem, this is +actually relatively easy to do - all the changes to logged items are already +tracked in the current infrastructure. The big problem is how to accumulate +them and get them to the log in a consistent, recoverable manner. +Describing the problems and how they have been solved is the focus of this +document. + +One of the key changes that delayed logging makes to the operation of the +journalling subsystem is that it disassociates the amount of outstanding +metadata changes from the size and number of log buffers available. In other +words, instead of there only being a maximum of 2MB of transaction changes not +written to the log at any point in time, there may be a much greater amount +being accumulated in memory. Hence the potential for loss of metadata on a +crash is much greater than for the existing logging mechanism. + +It should be noted that this does not change the guarantee that log recovery +will result in a consistent filesystem. What it does mean is that as far as the +recovered filesystem is concerned, there may be many thousands of transactions +that simply did not occur as a result of the crash. This makes it even more +important that applications that care about their data use fsync() where they +need to ensure application level data integrity is maintained. + +It should be noted that delayed logging is not an innovative new concept that +warrants rigorous proofs to determine whether it is correct or not. The method +of accumulating changes in memory for some period before writing them to the +log is used effectively in many filesystems including ext3 and ext4. Hence +no time is spent in this document trying to convince the reader that the +concept is sound. Instead it is simply considered a "solved problem" and as +such implementing it in XFS is purely an exercise in software engineering. + +The fundamental requirements for delayed logging in XFS are simple: + + 1. Reduce the amount of metadata written to the log by at least + an order of magnitude. + 2. Supply sufficient statistics to validate Requirement #1. + 3. Supply sufficient new tracing infrastructure to be able to debug + problems with the new code. + 4. No on-disk format change (metadata or log format). + 5. Enable and disable with a mount option. + 6. No performance regressions for synchronous transaction workloads. + +Delayed Logging: Design +----------------------- + +Storing Changes + +The problem with accumulating changes at a logical level (i.e. just using the +existing log item dirty region tracking) is that when it comes to writing the +changes to the log buffers, we need to ensure that the object we are formatting +is not changing while we do this. This requires locking the object to prevent +concurrent modification. Hence flushing the logical changes to the log would +require us to lock every object, format them, and then unlock them again. + +This introduces lots of scope for deadlocks with transactions that are already +running. For example, a transaction has object A locked and modified, but needs +the delayed logging tracking lock to commit the transaction. However, the +flushing thread has the delayed logging tracking lock already held, and is +trying to get the lock on object A to flush it to the log buffer. This appears +to be an unsolvable deadlock condition, and it was solving this problem that +was the barrier to implementing delayed logging for so long. + +The solution is relatively simple - it just took a long time to recognise it. +Put simply, the current logging code formats the changes to each item into an +vector array that points to the changed regions in the item. The log write code +simply copies the memory these vectors point to into the log buffer during +transaction commit while the item is locked in the transaction. Instead of +using the log buffer as the destination of the formatting code, we can use an +allocated memory buffer big enough to fit the formatted vector. + +If we then copy the vector into the memory buffer and rewrite the vector to +point to the memory buffer rather than the object itself, we now have a copy of +the changes in a format that is compatible with the log buffer writing code. +that does not require us to lock the item to access. This formatting and +rewriting can all be done while the object is locked during transaction commit, +resulting in a vector that is transactionally consistent and can be accessed +without needing to lock the owning item. + +Hence we avoid the need to lock items when we need to flush outstanding +asynchronous transactions to the log. The differences between the existing +formatting method and the delayed logging formatting can be seen in the +diagram below. + +Current format log vector: + +Object +---------------------------------------------+ +Vector 1 +----+ +Vector 2 +----+ +Vector 3 +----------+ + +After formatting: + +Log Buffer +-V1-+-V2-+----V3----+ + +Delayed logging vector: + +Object +---------------------------------------------+ +Vector 1 +----+ +Vector 2 +----+ +Vector 3 +----------+ + +After formatting: + +Memory Buffer +-V1-+-V2-+----V3----+ +Vector 1 +----+ +Vector 2 +----+ +Vector 3 +----------+ + +The memory buffer and associated vector need to be passed as a single object, +but still need to be associated with the parent object so if the object is +relogged we can replace the current memory buffer with a new memory buffer that +contains the latest changes. + +The reason for keeping the vector around after we've formatted the memory +buffer is to support splitting vectors across log buffer boundaries correctly. +If we don't keep the vector around, we do not know where the region boundaries +are in the item, so we'd need a new encapsulation method for regions in the log +buffer writing (i.e. double encapsulation). This would be an on-disk format +change and as such is not desirable. It also means we'd have to write the log +region headers in the formatting stage, which is problematic as there is per +region state that needs to be placed into the headers during the log write. + +Hence we need to keep the vector, but by attaching the memory buffer to it and +rewriting the vector addresses to point at the memory buffer we end up with a +self-describing object that can be passed to the log buffer write code to be +handled in exactly the same manner as the existing log vectors are handled. +Hence we avoid needing a new on-disk format to handle items that have been +relogged in memory. + + +Tracking Changes + +Now that we can record transactional changes in memory in a form that allows +them to be used without limitations, we need to be able to track and accumulate +them so that they can be written to the log at some later point in time. The +log item is the natural place to store this vector and buffer, and also makes sense +to be the object that is used to track committed objects as it will always +exist once the object has been included in a transaction. + +The log item is already used to track the log items that have been written to +the log but not yet written to disk. Such log items are considered "active" +and as such are stored in the Active Item List (AIL) which is a LSN-ordered +double linked list. Items are inserted into this list during log buffer IO +completion, after which they are unpinned and can be written to disk. An object +that is in the AIL can be relogged, which causes the object to be pinned again +and then moved forward in the AIL when the log buffer IO completes for that +transaction. + +Essentially, this shows that an item that is in the AIL can still be modified +and relogged, so any tracking must be separate to the AIL infrastructure. As +such, we cannot reuse the AIL list pointers for tracking committed items, nor +can we store state in any field that is protected by the AIL lock. Hence the +committed item tracking needs it's own locks, lists and state fields in the log +item. + +Similar to the AIL, tracking of committed items is done through a new list +called the Committed Item List (CIL). The list tracks log items that have been +committed and have formatted memory buffers attached to them. It tracks objects +in transaction commit order, so when an object is relogged it is removed from +it's place in the list and re-inserted at the tail. This is entirely arbitrary +and done to make it easy for debugging - the last items in the list are the +ones that are most recently modified. Ordering of the CIL is not necessary for +transactional integrity (as discussed in the next section) so the ordering is +done for convenience/sanity of the developers. + + +Delayed Logging: Checkpoints + +When we have a log synchronisation event, commonly known as a "log force", +all the items in the CIL must be written into the log via the log buffers. +We need to write these items in the order that they exist in the CIL, and they +need to be written as an atomic transaction. The need for all the objects to be +written as an atomic transaction comes from the requirements of relogging and +log replay - all the changes in all the objects in a given transaction must +either be completely replayed during log recovery, or not replayed at all. If +a transaction is not replayed because it is not complete in the log, then +no later transactions should be replayed, either. + +To fulfill this requirement, we need to write the entire CIL in a single log +transaction. Fortunately, the XFS log code has no fixed limit on the size of a +transaction, nor does the log replay code. The only fundamental limit is that +the transaction cannot be larger than just under half the size of the log. The +reason for this limit is that to find the head and tail of the log, there must +be at least one complete transaction in the log at any given time. If a +transaction is larger than half the log, then there is the possibility that a +crash during the write of a such a transaction could partially overwrite the +only complete previous transaction in the log. This will result in a recovery +failure and an inconsistent filesystem and hence we must enforce the maximum +size of a checkpoint to be slightly less than a half the log. + +Apart from this size requirement, a checkpoint transaction looks no different +to any other transaction - it contains a transaction header, a series of +formatted log items and a commit record at the tail. From a recovery +perspective, the checkpoint transaction is also no different - just a lot +bigger with a lot more items in it. The worst case effect of this is that we +might need to tune the recovery transaction object hash size. + +Because the checkpoint is just another transaction and all the changes to log +items are stored as log vectors, we can use the existing log buffer writing +code to write the changes into the log. To do this efficiently, we need to +minimise the time we hold the CIL locked while writing the checkpoint +transaction. The current log write code enables us to do this easily with the +way it separates the writing of the transaction contents (the log vectors) from +the transaction commit record, but tracking this requires us to have a +per-checkpoint context that travels through the log write process through to +checkpoint completion. + +Hence a checkpoint has a context that tracks the state of the current +checkpoint from initiation to checkpoint completion. A new context is initiated +at the same time a checkpoint transaction is started. That is, when we remove +all the current items from the CIL during a checkpoint operation, we move all +those changes into the current checkpoint context. We then initialise a new +context and attach that to the CIL for aggregation of new transactions. + +This allows us to unlock the CIL immediately after transfer of all the +committed items and effectively allow new transactions to be issued while we +are formatting the checkpoint into the log. It also allows concurrent +checkpoints to be written into the log buffers in the case of log force heavy +workloads, just like the existing transaction commit code does. This, however, +requires that we strictly order the commit records in the log so that +checkpoint sequence order is maintained during log replay. + +To ensure that we can be writing an item into a checkpoint transaction at +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 +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: + + CIL Head + | + V + Log Item <-> log vector 1 -> memory buffer + | -> vector array + V + Log Item <-> log vector 2 -> memory buffer + | -> vector array + V + ...... + | + V + Log Item <-> log vector N-1 -> memory buffer + | -> vector array + V + Log Item <-> log vector N -> memory buffer + -> vector array + +And after the flush the CIL head is empty, and the checkpoint context log +vector list would look like: + + Checkpoint Context + | + V + log vector 1 -> memory buffer + | -> vector array + | -> Log Item + V + log vector 2 -> memory buffer + | -> vector array + | -> Log Item + V + ...... + | + V + log vector N-1 -> memory buffer + | -> vector array + | -> Log Item + V + log vector N -> memory buffer + -> vector array + -> Log Item + +Once this transfer is done, the CIL can be unlocked and new transactions can +start, while the checkpoint flush code works over the log vector chain to +commit the checkpoint. + +Once the checkpoint is written into the log buffers, the checkpoint context is +attached to the log buffer that the commit record was written to along with a +completion callback. Log IO completion will call that callback, which can then +run transaction committed processing for the log items (i.e. insert into AIL +and unpin) in the log vector chain and then free the log vector chain and +checkpoint context. + +Discussion Point: I am uncertain as to whether the log item is the most +efficient way to track vectors, even though it seems like the natural way to do +it. The fact that we walk the log items (in the CIL) just to chain the log +vectors and break the link between the log item and the log vector means that +we take a cache line hit for the log item list modification, then another for +the log vector chaining. If we track by the log vectors, then we only need to +break the link between the log item and the log vector, which means we should +dirty only the log item cachelines. Normally I wouldn't be concerned about one +vs two dirty cachelines except for the fact I've seen upwards of 80,000 log +vectors in one checkpoint transaction. I'd guess this is a "measure and +compare" situation that can be done after a working and reviewed implementation +is in the dev tree.... + +Delayed Logging: Checkpoint Sequencing + +One of the key aspects of the XFS transaction subsystem is that it tags +committed transactions with the log sequence number of the transaction commit. +This allows transactions to be issued asynchronously even though there may be +future operations that cannot be completed until that transaction is fully +committed to the log. In the rare case that a dependent operation occurs (e.g. +re-using a freed metadata extent for a data extent), a special, optimised log +force can be issued to force the dependent transaction to disk immediately. + +To do this, transactions need to record the LSN of the commit record of the +transaction. This LSN comes directly from the log buffer the transaction is +written into. While this works just fine for the existing transaction +mechanism, it does not work for delayed logging because transactions are not +written directly into the log buffers. Hence some other method of sequencing +transactions is required. + +As discussed in the checkpoint section, delayed logging uses per-checkpoint +contexts, and as such it is simple to assign a sequence number to each +checkpoint. Because the switching of checkpoint contexts must be done +atomically, it is simple to ensure that each new context has a monotonically +increasing sequence number assigned to it without the need for an external +atomic counter - we can just take the current context sequence number and add +one to it for the new context. + +Then, instead of assigning a log buffer LSN to the transaction commit LSN +during the commit, we can assign the current checkpoint sequence. This allows +operations that track transactions that have not yet completed know what +checkpoint sequence needs to be committed before they can continue. As a +result, the code that forces the log to a specific LSN now needs to ensure that +the log forces to a specific checkpoint. + +To ensure that we can do this, we need to track all the checkpoint contexts +that are currently committing to the log. When we flush a checkpoint, the +context gets added to a "committing" list which can be searched. When a +checkpoint commit completes, it is removed from the committing list. Because +the checkpoint context records the LSN of the commit record for the checkpoint, +we can also wait on the log buffer that contains the commit record, thereby +using the existing log force mechanisms to execute synchronous forces. + +It should be noted that the synchronous forces may need to be extended with +mitigation algorithms similar to the current log buffer code to allow +aggregation of multiple synchronous transactions if there are already +synchronous transactions being flushed. Investigation of the performance of the +current design is needed before making any decisions here. + +The main concern with log forces is to ensure that all the previous checkpoints +are also committed to disk before the one we need to wait for. Therefore we +need to check that all the prior contexts in the committing list are also +complete before waiting on the one we need to complete. We do this +synchronisation in the log force code so that we don't need to wait anywhere +else for such serialisation - it only matters when we do a log force. + +The only remaining complexity is that a log force now also has to handle the +case where the forcing sequence number is the same as the current context. That +is, we need to flush the CIL and potentially wait for it to complete. This is a +simple addition to the existing log forcing code to check the sequence numbers +and push if required. Indeed, placing the current sequence checkpoint flush in +the log force code enables the current mechanism for issuing synchronous +transactions to remain untouched (i.e. commit an asynchronous transaction, then +force the log at the LSN of that transaction) and so the higher level code +behaves the same regardless of whether delayed logging is being used or not. + +Delayed Logging: Checkpoint Log Space Accounting + +The big issue for a checkpoint transaction is the log space reservation for the +transaction. We don't know how big a checkpoint transaction is going to be +ahead of time, nor how many log buffers it will take to write out, nor the +number of split log vector regions are going to be used. We can track the +amount of log space required as we add items to the commit item list, but we +still need to reserve the space in the log for the checkpoint. + +A typical transaction reserves enough space in the log for the worst case space +usage of the transaction. The reservation accounts for log record headers, +transaction and region headers, headers for split regions, buffer tail padding, +etc. as well as the actual space for all the changed metadata in the +transaction. While some of this is fixed overhead, much of it is dependent on +the size of the transaction and the number of regions being logged (the number +of log vectors in the transaction). + +An example of the differences would be logging directory changes versus logging +inode changes. If you modify lots of inode cores (e.g. chmod -R g+w *), then +there are lots of transactions that only contain an inode core and an inode log +format structure. That is, two vectors totaling roughly 150 bytes. If we modify +10,000 inodes, we have about 1.5MB of metadata to write in 20,000 vectors. Each +vector is 12 bytes, so the total to be logged is approximately 1.75MB. In +comparison, if we are logging full directory buffers, they are typically 4KB +each, so we in 1.5MB of directory buffers we'd have roughly 400 buffers and a +buffer format structure for each buffer - roughly 800 vectors or 1.51MB total +space. From this, it should be obvious that a static log space reservation is +not particularly flexible and is difficult to select the "optimal value" for +all workloads. + +Further, if we are going to use a static reservation, which bit of the entire +reservation does it cover? We account for space used by the transaction +reservation by tracking the space currently used by the object in the CIL and +then calculating the increase or decrease in space used as the object is +relogged. This allows for a checkpoint reservation to only have to account for +log buffer metadata used such as log header records. + +However, even using a static reservation for just the log metadata is +problematic. Typically log record headers use at least 16KB of log space per +1MB of log space consumed (512 bytes per 32k) and the reservation needs to be +large enough to handle arbitrary sized checkpoint transactions. This +reservation needs to be made before the checkpoint is started, and we need to +be able to reserve the space without sleeping. For a 8MB checkpoint, we need a +reservation of around 150KB, which is a non-trivial amount of space. + +A static reservation needs to manipulate the log grant counters - we can take a +permanent reservation on the space, but we still need to make sure we refresh +the write reservation (the actual space available to the transaction) after +every checkpoint transaction completion. Unfortunately, if this space is not +available when required, then the regrant code will sleep waiting for it. + +The problem with this is that it can lead to deadlocks as we may need to commit +checkpoints to be able to free up log space (refer back to the description of +rolling transactions for an example of this). Hence we *must* always have +space available in the log if we are to use static reservations, and that is +very difficult and complex to arrange. It is possible to do, but there is a +simpler way. + +The simpler way of doing this is tracking the entire log space used by the +items in the CIL and using this to dynamically calculate the amount of log +space required by the log metadata. If this log metadata space changes as a +result of a transaction commit inserting a new memory buffer into the CIL, then +the difference in space required is removed from the transaction that causes +the change. Transactions at this level will *always* have enough space +available in their reservation for this as they have already reserved the +maximal amount of log metadata space they require, and such a delta reservation +will always be less than or equal to the maximal amount in the reservation. + +Hence we can grow the checkpoint transaction reservation dynamically as items +are added to the CIL and avoid the need for reserving and regranting log space +up front. This avoids deadlocks and removes a blocking point from the +checkpoint flush code. + +As mentioned early, transactions can't grow to more than half the size of the +log. Hence as part of the reservation growing, we need to also check the size +of the reservation against the maximum allowed transaction size. If we reach +the maximum threshold, we need to push the CIL to the log. This is effectively +a "background flush" and is done on demand. This is identical to +a CIL push triggered by a log force, only that there is no waiting for the +checkpoint commit to complete. This background push is checked and executed by +transaction commit code. + +If the transaction subsystem goes idle while we still have items in the CIL, +they will be flushed by the periodic log force issued by the xfssyncd. This log +force will push the CIL to disk, and if the transaction subsystem stays idle, +allow the idle log to be covered (effectively marked clean) in exactly the same +manner that is done for the existing logging method. A discussion point is +whether this log force needs to be done more frequently than the current rate +which is once every 30s. + + +Delayed Logging: Log Item Pinning + +Currently log items are pinned during transaction commit while the items are +still locked. This happens just after the items are formatted, though it could +be done any time before the items are unlocked. The result of this mechanism is +that items get pinned once for every transaction that is committed to the log +buffers. Hence items that are relogged in the log buffers will have a pin count +for every outstanding transaction they were dirtied in. When each of these +transactions is completed, they will unpin the item once. As a result, the item +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 +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 +log item completion. The result of this is that pinning and unpinning of the +log items becomes unbalanced if we retain the "pin on transaction commit, unpin +on transaction completion" model. + +To keep pin/unpin symmetry, the algorithm needs to change to a "pin on +insertion into the CIL, unpin on checkpoint completion". In other words, the +pinning and unpinning becomes symmetric around a checkpoint context. We have to +pin the object the first time it is inserted into the CIL - if it is already in +the CIL during a transaction commit, then we do not pin it again. Because there +can be multiple outstanding checkpoint contexts, we can still see elevated pin +counts, but as each checkpoint completes the pin count will retain the correct +value according to it's context. + +Just to make matters more slightly more complex, this checkpoint level context +for the pin count means that the pinning of an item must take place under the +CIL commit/flush lock. If we pin the object outside this lock, we cannot +guarantee which context the pin count is associated with. This is because of +the fact pinning the item is dependent on whether the item is present in the +current CIL or not. If we don't pin the CIL first before we check and pin the +object, we have a race with CIL being flushed between the check and the pin +(or not pinning, as the case may be). Hence we must hold the CIL flush/commit +lock to guarantee that we pin the items correctly. + +Delayed Logging: Concurrent Scalability + +A fundamental requirement for the CIL is that accesses through transaction +commits must scale to many concurrent commits. The current transaction commit +code does not break down even when there are transactions coming from 2048 +processors at once. The current transaction code does not go any faster than if +there was only one CPU using it, but it does not slow down either. + +As a result, the delayed logging transaction commit code needs to be designed +for concurrency from the ground up. It is obvious that there are serialisation +points in the design - the three important ones are: + + 1. Locking out new transaction commits while flushing the CIL + 2. Adding items to the CIL and updating item space accounting + 3. Checkpoint commit ordering + +Looking at the transaction commit and CIL flushing interactions, it is clear +that we have a many-to-one interaction here. That is, the only restriction on +the number of concurrent transactions that can be trying to commit at once is +the amount of space available in the log for their reservations. The practical +limit here is in the order of several hundred concurrent transactions for a +128MB log, which means that it is generally one per CPU in a machine. + +The amount of time a transaction commit needs to hold out a flush is a +relatively long period of time - the pinning of log items needs to be done +while we are holding out a CIL flush, so at the moment that means it is held +across the formatting of the objects into memory buffers (i.e. while memcpy()s +are in progress). Ultimately a two pass algorithm where the formatting is done +separately to the pinning of objects could be used to reduce the hold time of +the transaction commit side. + +Because of the number of potential transaction commit side holders, the lock +really needs to be a sleeping lock - if the CIL flush takes the lock, we do not +want every other CPU in the machine spinning on the CIL lock. Given that +flushing the CIL could involve walking a list of tens of thousands of log +items, it will get held for a significant time and so spin contention is a +significant concern. Preventing lots of CPUs spinning doing nothing is the +main reason for choosing a sleeping lock even though nothing in either the +transaction commit or CIL flush side sleeps with the lock held. + +It should also be noted that CIL flushing is also a relatively rare operation +compared to transaction commit for asynchronous transaction workloads - only +time will tell if using a read-write semaphore for exclusion will limit +transaction commit concurrency due to cache line bouncing of the lock on the +read side. + +The second serialisation point is on the transaction commit side where items +are inserted into the CIL. Because transactions can enter this code +concurrently, the CIL needs to be protected separately from the above +commit/flush exclusion. It also needs to be an exclusive lock but it is only +held for a very short time and so a spin lock is appropriate here. It is +possible that this lock will become a contention point, but given the short +hold time once per transaction I think that contention is unlikely. + +The final serialisation point is the checkpoint commit record ordering code +that is run as part of the checkpoint commit and log force sequencing. The code +path that triggers a CIL flush (i.e. whatever triggers the log force) will enter +an ordering loop after writing all the log vectors into the log buffers but +before writing the commit record. This loop walks the list of committing +checkpoints and needs to block waiting for checkpoints to complete their commit +record write. As a result it needs a lock and a wait variable. Log force +sequencing also requires the same lock, list walk, and blocking mechanism to +ensure completion of checkpoints. + +These two sequencing operations can use the mechanism even though the +events they are waiting for are different. The checkpoint commit record +sequencing needs to wait until checkpoint contexts contain a commit LSN +(obtained through completion of a commit record write) while log force +sequencing needs to wait until previous checkpoint contexts are removed from +the committing list (i.e. they've completed). A simple wait variable and +broadcast wakeups (thundering herds) has been used to implement these two +serialisation queues. They use the same lock as the CIL, too. If we see too +much contention on the CIL lock, or too many context switches as a result of +the broadcast wakeups these operations can be put under a new spinlock and +given separate wait lists to reduce lock contention and the number of processes +woken by the wrong event. + + +Lifecycle Changes + +The existing log item life cycle is as follows: + + 1. Transaction allocate + 2. Transaction reserve + 3. Lock item + 4. Join item to transaction + If not already attached, + Allocate log item + Attach log item to owner item + Attach log item to transaction + 5. Modify item + Record modifications in log item + 6. Transaction commit + Pin item in memory + Format item into log buffer + Write commit LSN into transaction + Unlock item + Attach transaction to log buffer + + <log buffer IO dispatched> + <log buffer IO completes> + + 7. Transaction completion + Mark log item committed + Insert log item into AIL + Write commit LSN into log item + Unpin log item + 8. AIL traversal + Lock item + Mark log item clean + Flush item to disk + + <item IO completion> + + 9. Log item removed from AIL + Moves log tail + Item unlocked + +Essentially, steps 1-6 operate independently from step 7, which is also +independent of steps 8-9. An item can be locked in steps 1-6 or steps 8-9 +at the same time step 7 is occurring, but only steps 1-6 or 8-9 can occur +at the same time. If the log item is in the AIL or between steps 6 and 7 +and steps 1-6 are re-entered, then the item is relogged. Only when steps 8-9 +are entered and completed is the object considered clean. + +With delayed logging, there are new steps inserted into the life cycle: + + 1. Transaction allocate + 2. Transaction reserve + 3. Lock item + 4. Join item to transaction + If not already attached, + Allocate log item + Attach log item to owner item + Attach log item to transaction + 5. Modify item + Record modifications in log item + 6. Transaction commit + Pin item in memory if not pinned in CIL + Format item into log vector + buffer + Attach log vector and buffer to log item + Insert log item into CIL + Write CIL context sequence into transaction + Unlock item + + <next log force> + + 7. CIL push + lock CIL flush + Chain log vectors and buffers together + Remove items from CIL + unlock CIL flush + write log vectors into log + sequence commit records + attach checkpoint context to log buffer + + <log buffer IO dispatched> + <log buffer IO completes> + + 8. Checkpoint completion + Mark log item committed + Insert item into AIL + Write commit LSN into log item + Unpin log item + 9. AIL traversal + Lock item + Mark log item clean + Flush item to disk + <item IO completion> + 10. Log item removed from AIL + Moves log tail + Item unlocked + +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. +Hence delayed logging should not introduce any constraints on log item +behaviour, allocation or freeing that don't already exist. + +As a result of this zero-impact "insertion" of delayed logging infrastructure +and the design of the internal structures to avoid on disk format changes, we +can basically switch between delayed logging and the existing mechanism with a +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.35 Inclusion in mainline as an experimental mount option + => approximately 2-3 months to merge window + => needs to be in xfs-dev tree in 4-6 weeks + => code is nearing readiness for review + +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/hwmon/dme1737 b/Documentation/hwmon/dme1737 index 001d2e7..fc5df76 100644 --- a/Documentation/hwmon/dme1737 +++ b/Documentation/hwmon/dme1737 @@ -9,11 +9,15 @@ Supported chips: * SMSC SCH3112, SCH3114, SCH3116 Prefix: 'sch311x' Addresses scanned: none, address read from Super-I/O config space - Datasheet: http://www.nuhorizons.com/FeaturedProducts/Volume1/SMSC/311x.pdf + Datasheet: Available on the Internet * SMSC SCH5027 Prefix: 'sch5027' Addresses scanned: I2C 0x2c, 0x2d, 0x2e Datasheet: Provided by SMSC upon request and under NDA + * SMSC SCH5127 + Prefix: 'sch5127' + Addresses scanned: none, address read from Super-I/O config space + Datasheet: Provided by SMSC upon request and under NDA Authors: Juerg Haefliger <juergh@gmail.com> @@ -36,8 +40,8 @@ Description ----------- This driver implements support for the hardware monitoring capabilities of the -SMSC DME1737 and Asus A8000 (which are the same), SMSC SCH5027, and SMSC -SCH311x Super-I/O chips. These chips feature monitoring of 3 temp sensors +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 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 @@ -48,14 +52,14 @@ Fan[3-6] and pwm[3,5-6] are optional features and their availability depends on the configuration of the chip. The driver will detect which features are present during initialization and create the sysfs attributes accordingly. -For the SCH311x, fan[1-3] and pwm[1-3] are always present and fan[4-6] and -pwm[5-6] don't exist. +For the SCH311x and SCH5127, fan[1-3] and pwm[1-3] are always present and +fan[4-6] and pwm[5-6] don't exist. The hardware monitoring features of the DME1737, A8000, and SCH5027 are only -accessible via SMBus, while the SCH311x only provides access via the ISA bus. -The driver will therefore register itself as an I2C client driver if it detects -a DME1737, A8000, or SCH5027 and as a platform driver if it detects a SCH311x -chip. +accessible via SMBus, while the SCH311x and SCH5127 only provide access via +the ISA bus. The driver will therefore register itself as an I2C client driver +if it detects a DME1737, A8000, or SCH5027 and as a platform driver if it +detects a SCH311x or SCH5127 chip. Voltage Monitoring @@ -76,7 +80,7 @@ DME1737, A8000: in6: Vbat (+3.0V) 0V - 4.38V SCH311x: - in0: +2.5V 0V - 6.64V + in0: +2.5V 0V - 3.32V in1: Vccp (processor core) 0V - 2V in2: VCC (internal +3.3V) 0V - 4.38V in3: +5V 0V - 6.64V @@ -93,6 +97,15 @@ SCH5027: in5: VTR (+3.3V standby) 0V - 4.38V in6: Vbat (+3.0V) 0V - 4.38V +SCH5127: + in0: +2.5 0V - 3.32V + in1: Vccp (processor core) 0V - 3V + in2: VCC (internal +3.3V) 0V - 4.38V + in3: V2_IN 0V - 1.5V + in4: V1_IN 0V - 1.5V + in5: VTR (+3.3V standby) 0V - 4.38V + in6: Vbat (+3.0V) 0V - 4.38V + Each voltage input has associated min and max limits which trigger an alarm when crossed. @@ -293,3 +306,21 @@ pwm[1-3]_auto_point1_pwm RW Auto PWM pwm point. Auto_point1 is the pwm[1-3]_auto_point2_pwm RO Auto PWM pwm point. Auto_point2 is the full-speed duty-cycle which is hard- wired to 255 (100% duty-cycle). + +Chip Differences +---------------- + +Feature dme1737 sch311x sch5027 sch5127 +------------------------------------------------------- +temp[1-3]_offset yes yes +vid yes +zone3 yes yes yes +zone[1-3]_hyst yes yes +pwm min/off yes yes +fan3 opt yes opt yes +pwm3 opt yes opt yes +fan4 opt opt +fan5 opt opt +pwm5 opt opt +fan6 opt opt +pwm6 opt opt diff --git a/Documentation/hwmon/lm63 b/Documentation/hwmon/lm63 index 31660bf..b9843ea 100644 --- a/Documentation/hwmon/lm63 +++ b/Documentation/hwmon/lm63 @@ -7,6 +7,11 @@ Supported chips: Addresses scanned: I2C 0x4c Datasheet: Publicly available at the National Semiconductor website http://www.national.com/pf/LM/LM63.html + * National Semiconductor LM64 + Prefix: 'lm64' + Addresses scanned: I2C 0x18 and 0x4e + Datasheet: Publicly available at the National Semiconductor website + http://www.national.com/pf/LM/LM64.html Author: Jean Delvare <khali@linux-fr.org> @@ -55,3 +60,5 @@ The lm63 driver will not update its values more frequently than every second; reading them more often will do no harm, but will return 'old' values. +The LM64 is effectively an LM63 with GPIO lines. The driver does not +support these GPIO lines at present. diff --git a/Documentation/hwmon/ltc4245 b/Documentation/hwmon/ltc4245 index 02838a4..86b5880 100644 --- a/Documentation/hwmon/ltc4245 +++ b/Documentation/hwmon/ltc4245 @@ -72,9 +72,7 @@ in6_min_alarm 5v output undervoltage alarm in7_min_alarm 3v output undervoltage alarm in8_min_alarm Vee (-12v) output undervoltage alarm -in9_input GPIO #1 voltage data -in10_input GPIO #2 voltage data -in11_input GPIO #3 voltage data +in9_input GPIO voltage data power1_input 12v power usage (mW) power2_input 5v power usage (mW) diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface index 3de6b0b..d4e2917 100644 --- a/Documentation/hwmon/sysfs-interface +++ b/Documentation/hwmon/sysfs-interface @@ -80,9 +80,9 @@ All entries (except name) are optional, and should only be created in a given driver if the chip has the feature. -******** -* Name * -******** +********************* +* Global attributes * +********************* name The chip name. This should be a short, lowercase string, not containing @@ -91,6 +91,13 @@ name The chip name. I2C devices get this attribute created automatically. RO +update_rate The rate at which the chip will update readings. + Unit: millisecond + RW + Some devices have a variable update rate. This attribute + can be used to change the update rate to the desired + frequency. + ************ * Voltages * diff --git a/Documentation/hwmon/tmp102 b/Documentation/hwmon/tmp102 new file mode 100644 index 0000000..8454a77 --- /dev/null +++ b/Documentation/hwmon/tmp102 @@ -0,0 +1,26 @@ +Kernel driver tmp102 +==================== + +Supported chips: + * Texas Instruments TMP102 + Prefix: 'tmp102' + Addresses scanned: none + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp102.html + +Author: + Steven King <sfking@fdwdc.com> + +Description +----------- + +The Texas Instruments TMP102 implements one temperature sensor. Limits can be +set through the Overtemperature Shutdown register and Hysteresis register. The +sensor is accurate to 0.5 degree over the range of -25 to +85 C, and to 1.0 +degree from -40 to +125 C. Resolution of the sensor is 0.0625 degree. The +operating temperature has a minimum of -55 C and a maximum of +150 C. + +The TMP102 has a programmable update rate that can select between 8, 4, 1, and +0.5 Hz. (Currently the driver only supports the default of 4 Hz). + +The driver provides the common sysfs-interface for temperatures (see +Documentation/hwmon/sysfs-interface under Temperatures). diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index e1bb5b2..e307914 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -27,7 +27,13 @@ Authors: Module Parameters ----------------- -None. +* disable_features (bit vector) +Disable selected features normally supported by the device. This makes it +possible to work around possible driver or hardware bugs if the feature in +question doesn't work as intended for whatever reason. Bit values: + 1 disable SMBus PEC + 2 disable the block buffer + 8 disable the I2C block read functionality Description diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index b12bacd..a5c0550 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -58,6 +58,7 @@ parameter is applicable: ISAPNP ISA PnP code is enabled. ISDN Appropriate ISDN support is enabled. JOY Appropriate joystick support is enabled. + KGDB Kernel debugger support is enabled. KVM Kernel Virtual Machine support is enabled. LIBATA Libata driver is enabled LP Printer support is enabled. @@ -289,9 +290,6 @@ and is between 256 and 4096 characters. It is defined in the file advansys= [HW,SCSI] See header of drivers/scsi/advansys.c. - advwdt= [HW,WDT] Advantech WDT - Format: <iostart>,<iostop> - aedsp16= [HW,OSS] Audio Excel DSP 16 Format: <io>,<irq>,<dma>,<mss_io>,<mpu_io>,<mpu_irq> See also header of sound/oss/aedsp16.c. @@ -712,6 +710,12 @@ and is between 256 and 4096 characters. It is defined in the file The VGA output is eventually overwritten by the real console. + ekgdboc= [X86,KGDB] Allow early kernel console debugging + ekgdboc=kbd + + This is desgined to be used in conjunction with + the boot argument: earlyprintk=vga + eata= [HW,SCSI] edd= [EDD] @@ -758,9 +762,6 @@ and is between 256 and 4096 characters. It is defined in the file This option is obsoleted by the "netdev=" option, which has equivalent usage. See its documentation for details. - eurwdt= [HW,WDT] Eurotech CPU-1220/1410 onboard watchdog. - Format: <io>[,<irq>] - failslab= fail_page_alloc= fail_make_request=[KNL] @@ -1120,10 +1121,26 @@ and is between 256 and 4096 characters. It is defined in the file use the HighMem zone if it exists, and the Normal zone if it does not. - kgdboc= [HW] kgdb over consoles. - Requires a tty driver that supports console polling. - (only serial supported for now) - Format: <serial_device>[,baud] + kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. + Format: <Controller#>[,poll interval] + The controller # is the number of the ehci usb debug + port as it is probed via PCI. The poll interval is + optional and is the number seconds in between + each poll cycle to the debug port in case you need + the functionality for interrupting the kernel with + gdb or control-c on the dbgp connection. When + not using this parameter you use sysrq-g to break into + the kernel debugger. + + kgdboc= [KGDB,HW] kgdb over consoles. + Requires a tty driver that supports console polling, + or a supported polling keyboard driver (non-usb). + Serial only format: <serial_device>[,baud] + keyboard only format: kbd + keyboard and serial format: kbd,<serial_device>[,baud] + + kgdbwait [KGDB] Stop kernel execution and enter the + kernel debugger at the earliest opportunity. kmac= [MIPS] korina ethernet MAC address. Configure the RouterBoard 532 series on-chip @@ -1235,6 +1252,8 @@ and is between 256 and 4096 characters. It is defined in the file * nohrst, nosrst, norst: suppress hard, soft and both resets. + * dump_id: dump IDENTIFY data. + If there are multiple matching configurations changing the same attribute, the last one is used. @@ -2244,9 +2263,6 @@ and is between 256 and 4096 characters. It is defined in the file sched_debug [KNL] Enables verbose scheduler debug messages. - sc1200wdt= [HW,WDT] SC1200 WDT (watchdog) driver - Format: <io>[,<timeout>[,<isapnp>]] - scsi_debug_*= [SCSI] See drivers/scsi/scsi_debug.c. @@ -2835,8 +2851,10 @@ and is between 256 and 4096 characters. It is defined in the file wd7000= [HW,SCSI] See header of drivers/scsi/wd7000.c. - wdt= [WDT] Watchdog - See Documentation/watchdog/wdt.txt. + watchdog timers [HW,WDT] For information on watchdog timers, + see Documentation/watchdog/watchdog-parameters.txt + or other driver-specific files in the + Documentation/watchdog/ directory. x2apic_phys [X86-64,APIC] Use x2apic physical mode instead of default x2apic cluster mode on platforms diff --git a/Documentation/kvm/api.txt b/Documentation/kvm/api.txt index c6416a3..a237518 100644 --- a/Documentation/kvm/api.txt +++ b/Documentation/kvm/api.txt @@ -656,6 +656,7 @@ struct kvm_clock_data { 4.29 KVM_GET_VCPU_EVENTS Capability: KVM_CAP_VCPU_EVENTS +Extended by: KVM_CAP_INTR_SHADOW Architectures: x86 Type: vm ioctl Parameters: struct kvm_vcpu_event (out) @@ -676,7 +677,7 @@ struct kvm_vcpu_events { __u8 injected; __u8 nr; __u8 soft; - __u8 pad; + __u8 shadow; } interrupt; struct { __u8 injected; @@ -688,9 +689,13 @@ struct kvm_vcpu_events { __u32 flags; }; +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 Capability: KVM_CAP_VCPU_EVENTS +Extended by: KVM_CAP_INTR_SHADOW Architectures: x86 Type: vm ioctl Parameters: struct kvm_vcpu_event (in) @@ -709,6 +714,183 @@ current in-kernel state. The bits are: KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector +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 + +Capability: KVM_CAP_DEBUGREGS +Architectures: x86 +Type: vm ioctl +Parameters: struct kvm_debugregs (out) +Returns: 0 on success, -1 on error + +Reads debug registers from the vcpu. + +struct kvm_debugregs { + __u64 db[4]; + __u64 dr6; + __u64 dr7; + __u64 flags; + __u64 reserved[9]; +}; + +4.33 KVM_SET_DEBUGREGS + +Capability: KVM_CAP_DEBUGREGS +Architectures: x86 +Type: vm ioctl +Parameters: struct kvm_debugregs (in) +Returns: 0 on success, -1 on error + +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 + +Capability: KVM_CAP_USER_MEM +Architectures: all +Type: vm ioctl +Parameters: struct kvm_userspace_memory_region (in) +Returns: 0 on success, -1 on error + +struct kvm_userspace_memory_region { + __u32 slot; + __u32 flags; + __u64 guest_phys_addr; + __u64 memory_size; /* bytes */ + __u64 userspace_addr; /* start of the userspace allocated memory */ +}; + +/* for kvm_memory_region::flags */ +#define KVM_MEM_LOG_DIRTY_PAGES 1UL + +This ioctl allows the user to create or modify a guest physical memory +slot. When changing an existing slot, it may be moved in the guest +physical memory space, or its flags may be modified. It may not be +resized. Slots may not overlap in guest physical address space. + +Memory for the region is taken starting at the address denoted by the +field userspace_addr, which must point at user addressable memory for +the entire memory slot size. Any object may back this memory, including +anonymous memory, ordinary files, and hugetlbfs. + +It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr +be identical. This allows large pages in the guest to be backed by large +pages in the host. + +The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which +instructs kvm to keep track of writes to memory within the slot. See +the KVM_GET_DIRTY_LOG ioctl. + +When the KVM_CAP_SYNC_MMU capability, changes in the backing of the memory +region are automatically reflected into the guest. For example, an mmap() +that affects the region will be made visible immediately. Another example +is madvise(MADV_DROP). + +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 + +Capability: KVM_CAP_SET_TSS_ADDR +Architectures: x86 +Type: vm ioctl +Parameters: unsigned long tss_address (in) +Returns: 0 on success, -1 on error + +This ioctl defines the physical address of a three-page region in the guest +physical address space. The region must be within the first 4GB of the +guest physical address space and must not conflict with any memory slot +or any mmio address. The guest may malfunction if it accesses this memory +region. + +This ioctl is required on Intel-based hosts. This is needed on Intel hardware +because of a quirk in the virtualization implementation (see the internals +documentation when it pops into existence). + +4.36 KVM_ENABLE_CAP + +Capability: KVM_CAP_ENABLE_CAP +Architectures: ppc +Type: vcpu ioctl +Parameters: struct kvm_enable_cap (in) +Returns: 0 on success; -1 on error + ++Not all extensions are enabled by default. Using this ioctl the application +can enable an extension, making it available to the guest. + +On systems that do not support this ioctl, it always fails. On systems that +do support it, it only works for extensions that are supported for enablement. + +To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should +be used. + +struct kvm_enable_cap { + /* in */ + __u32 cap; + +The capability that is supposed to get enabled. + + __u32 flags; + +A bitfield indicating future enhancements. Has to be 0 for now. + + __u64 args[4]; + +Arguments for enabling a feature. If a feature needs initial values to +function properly, this is the place to put them. + + __u8 pad[64]; +}; + +4.37 KVM_GET_MP_STATE + +Capability: KVM_CAP_MP_STATE +Architectures: x86, ia64 +Type: vcpu ioctl +Parameters: struct kvm_mp_state (out) +Returns: 0 on success; -1 on error + +struct kvm_mp_state { + __u32 mp_state; +}; + +Returns the vcpu's current "multiprocessing state" (though also valid on +uniprocessor guests). + +Possible values are: + + - KVM_MP_STATE_RUNNABLE: the vcpu is currently running + - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP) + which has not yet received an INIT signal + - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is + now ready for a SIPI + - 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) + +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 + +Capability: KVM_CAP_MP_STATE +Architectures: x86, ia64 +Type: vcpu ioctl +Parameters: struct kvm_mp_state (in) +Returns: 0 on success; -1 on error + +Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for +arguments. + +This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel +irqchip, the multiprocessing state must be maintained by userspace. 5. The kvm_run structure @@ -820,6 +1002,13 @@ executed a memory-mapped I/O instruction which could not be satisfied by kvm. The 'data' member contains the written data if 'is_write' is true, and should be filled by application code otherwise. +NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO and KVM_EXIT_OSI, the corresponding +operations are complete (and guest state is consistent) only after userspace +has re-entered the kernel with KVM_RUN. The kernel side will first finish +incomplete operations and then check for pending signals. Userspace +can re-enter the guest with an unmasked signal pending to complete +pending operations. + /* KVM_EXIT_HYPERCALL */ struct { __u64 nr; @@ -829,7 +1018,9 @@ true, and should be filled by application code otherwise. __u32 pad; } hypercall; -Unused. +Unused. This was once used for 'hypercall to userspace'. To implement +such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390). +Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO. /* KVM_EXIT_TPR_ACCESS */ struct { @@ -870,6 +1061,19 @@ s390 specific. powerpc specific. + /* KVM_EXIT_OSI */ + struct { + __u64 gprs[32]; + } osi; + +MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch +hypercalls and exit with this exit struct that contains all the guest gprs. + +If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall. +Userspace can now handle the hypercall and when it's done modify the gprs as +necessary. Upon guest entry all guest GPRs will then be replaced by the values +in this struct. + /* Fix the size of the union. */ char padding[256]; }; diff --git a/Documentation/kvm/cpuid.txt b/Documentation/kvm/cpuid.txt new file mode 100644 index 0000000..14a12ea --- /dev/null +++ b/Documentation/kvm/cpuid.txt @@ -0,0 +1,42 @@ +KVM CPUID bits +Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010 +===================================================== + +A guest running on a kvm host, can check some of its features using +cpuid. This is not always guaranteed to work, since userspace can +mask-out some, or even all KVM-related cpuid features before launching +a guest. + +KVM cpuid functions are: + +function: KVM_CPUID_SIGNATURE (0x40000000) +returns : eax = 0, + ebx = 0x4b4d564b, + ecx = 0x564b4d56, + edx = 0x4d. +Note that this value in ebx, ecx and edx corresponds to the string "KVMKVMKVM". +This function queries the presence of KVM cpuid leafs. + + +function: define KVM_CPUID_FEATURES (0x40000001) +returns : ebx, ecx, edx = 0 + eax = and OR'ed group of (1 << flag), where each flags is: + + +flag || value || meaning +============================================================================= +KVM_FEATURE_CLOCKSOURCE || 0 || kvmclock available at msrs + || || 0x11 and 0x12. +------------------------------------------------------------------------------ +KVM_FEATURE_NOP_IO_DELAY || 1 || not necessary to perform delays + || || on PIO operations. +------------------------------------------------------------------------------ +KVM_FEATURE_MMU_OP || 2 || deprecated. +------------------------------------------------------------------------------ +KVM_FEATURE_CLOCKSOURCE2 || 3 || kvmclock available at msrs + || || 0x4b564d00 and 0x4b564d01 +------------------------------------------------------------------------------ +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/mmu.txt b/Documentation/kvm/mmu.txt new file mode 100644 index 0000000..aaed6ab --- /dev/null +++ b/Documentation/kvm/mmu.txt @@ -0,0 +1,304 @@ +The x86 kvm shadow mmu +====================== + +The mmu (in arch/x86/kvm, files mmu.[ch] and paging_tmpl.h) is responsible +for presenting a standard x86 mmu to the guest, while translating guest +physical addresses to host physical addresses. + +The mmu code attempts to satisfy the following requirements: + +- correctness: the guest should not be able to determine that it is running + on an emulated mmu except for timing (we attempt to comply + with the specification, not emulate the characteristics of + a particular implementation such as tlb size) +- security: the guest must not be able to touch host memory not assigned + to it +- performance: minimize the performance penalty imposed by the mmu +- scaling: need to scale to large memory and large vcpu guests +- hardware: support the full range of x86 virtualization hardware +- integration: Linux memory management code must be in control of guest memory + so that swapping, page migration, page merging, transparent + hugepages, and similar features work without change +- dirty tracking: report writes to guest memory to enable live migration + 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 + +Acronyms +======== + +pfn host page frame number +hpa host physical address +hva host virtual address +gfn guest frame number +gpa guest physical address +gva guest virtual address +ngpa nested guest physical address +ngva nested guest virtual address +pte page table entry (used also to refer generically to paging structure + entries) +gpte guest pte (referring to gfns) +spte shadow pte (referring to pfns) +tdp two dimensional paging (vendor neutral term for NPT and EPT) + +Virtual and real hardware supported +=================================== + +The mmu supports first-generation mmu hardware, which allows an atomic switch +of the current paging mode and cr3 during guest entry, as well as +two-dimensional paging (AMD's NPT and Intel's EPT). The emulated hardware +it exposes is the traditional 2/3/4 level x86 mmu, with support for global +pages, pae, pse, pse36, cr0.wp, and 1GB pages. Work is in progress to support +exposing NPT capable hardware on NPT capable hosts. + +Translation +=========== + +The primary job of the mmu is to program the processor's mmu to translate +addresses for the guest. Different translations are required at different +times: + +- when guest paging is disabled, we translate guest physical addresses to + host physical addresses (gpa->hpa) +- when guest paging is enabled, we translate guest virtual addresses, to + guest physical addresses, to host physical addresses (gva->gpa->hpa) +- when the guest launches a guest of its own, we translate nested guest + virtual addresses, to nested guest physical addresses, to guest physical + addresses, to host physical addresses (ngva->ngpa->gpa->hpa) + +The primary challenge is to encode between 1 and 3 translations into hardware +that support only 1 (traditional) and 2 (tdp) translations. When the +number of required translations matches the hardware, the mmu operates in +direct mode; otherwise it operates in shadow mode (see below). + +Memory +====== + +Guest memory (gpa) is part of the user address space of the process that is +using kvm. Userspace defines the translation between guest addresses and user +addresses (gpa->hva); note that two gpas may alias to the same gva, but not +vice versa. + +These gvas may be backed using any method available to the host: anonymous +memory, file backed memory, and device memory. Memory might be paged by the +host at any time. + +Events +====== + +The mmu is driven by events, some from the guest, some from the host. + +Guest generated events: +- writes to control registers (especially cr3) +- invlpg/invlpga instruction execution +- access to missing or protected translations + +Host generated events: +- changes in the gpa->hpa translation (either through gpa->hva changes or + through hva->hpa changes) +- memory pressure (the shrinker) + +Shadow pages +============ + +The principal data structure is the shadow page, 'struct kvm_mmu_page'. A +shadow page contains 512 sptes, which can be either leaf or nonleaf sptes. A +shadow page may contain a mix of leaf and nonleaf sptes. + +A nonleaf spte allows the hardware mmu to reach the leaf pages and +is not related to a translation directly. It points to other shadow pages. + +A leaf spte corresponds to either one or two translations encoded into +one paging structure entry. These are always the lowest level of the +translation stack, with optional higher level translations left to NPT/EPT. +Leaf ptes point at guest pages. + +The following table shows translations encoded by leaf ptes, with higher-level +translations in parentheses: + + Non-nested guests: + nonpaging: gpa->hpa + paging: gva->gpa->hpa + paging, tdp: (gva->)gpa->hpa + Nested guests: + non-tdp: ngva->gpa->hpa (*) + tdp: (ngva->)ngpa->gpa->hpa + +(*) the guest hypervisor will encode the ngva->gpa translation into its page + tables if npt is not present + +Shadow pages contain the following information: + role.level: + The level in the shadow paging hierarchy that this shadow page belongs to. + 1=4k sptes, 2=2M sptes, 3=1G sptes, etc. + role.direct: + If set, leaf sptes reachable from this page are for a linear range. + Examples include real mode translation, large guest pages backed by small + host pages, and gpa->hpa translations when NPT or EPT is active. + The linear range starts at (gfn << PAGE_SHIFT) and its size is determined + by role.level (2MB for first level, 1GB for second level, 0.5TB for third + level, 256TB for fourth level) + If clear, this page corresponds to a guest page table denoted by the gfn + field. + role.quadrant: + When role.cr4_pae=0, the guest uses 32-bit gptes while the host uses 64-bit + sptes. That means a guest page table contains more ptes than the host, + so multiple shadow pages are needed to shadow one guest page. + For first-level shadow pages, role.quadrant can be 0 or 1 and denotes the + first or second 512-gpte block in the guest page table. For second-level + page tables, each 32-bit gpte is converted to two 64-bit sptes + (since each first-level guest page is shadowed by two first-level + shadow pages) so role.quadrant takes values in the range 0..3. Each + quadrant maps 1GB virtual address space. + role.access: + Inherited guest access permissions in the form uwx. Note execute + permission is positive, not negative. + role.invalid: + The page is invalid and should not be used. It is a root page that is + currently pinned (by a cpu hardware register pointing to it); once it is + unpinned it will be destroyed. + role.cr4_pae: + Contains the value of cr4.pae for which the page is valid (e.g. whether + 32-bit or 64-bit gptes are in use). + role.cr4_nxe: + Contains the value of efer.nxe for which the page is valid. + role.cr0_wp: + Contains the value of cr0.wp for which the page is valid. + gfn: + Either the guest page table containing the translations shadowed by this + page, or the base page frame for linear translations. See role.direct. + spt: + A pageful of 64-bit sptes containing the translations for this page. + Accessed by both kvm and hardware. + The page pointed to by spt will have its page->private pointing back + at the shadow page structure. + sptes in spt point either at guest pages, or at lower-level shadow pages. + Specifically, if sp1 and sp2 are shadow pages, then sp1->spt[n] may point + at __pa(sp2->spt). sp2 will point back at sp1 through parent_pte. + The spt array forms a DAG structure with the shadow page as a node, and + guest pages as leaves. + gfns: + An array of 512 guest frame numbers, one for each present pte. Used to + perform a reverse map from a pte to a gfn. + slot_bitmap: + A bitmap containing one bit per memory slot. If the page contains a pte + mapping a page from memory slot n, then bit n of slot_bitmap will be set + (if a page is aliased among several slots, then it is not guaranteed that + all slots will be marked). + Used during dirty logging to avoid scanning a shadow page if none if its + pages need tracking. + root_count: + A counter keeping track of how many hardware registers (guest cr3 or + pdptrs) are now pointing at the page. While this counter is nonzero, the + page cannot be destroyed. See role.invalid. + multimapped: + Whether there exist multiple sptes pointing at this page. + parent_pte/parent_ptes: + If multimapped is zero, parent_pte points at the single spte that points at + this page's spt. Otherwise, parent_ptes points at a data structure + with a list of parent_ptes. + unsync: + If true, then the translations in this page may not match the guest's + translation. This is equivalent to the state of the tlb when a pte is + changed but before the tlb entry is flushed. Accordingly, unsync ptes + are synchronized when the guest executes invlpg or flushes its tlb by + other means. Valid for leaf pages. + unsync_children: + How many sptes in the page point at pages that are unsync (or have + unsynchronized children). + unsync_child_bitmap: + A bitmap indicating which sptes in spt point (directly or indirectly) at + pages that may be unsynchronized. Used to quickly locate all unsychronized + pages reachable from a given page. + +Reverse map +=========== + +The mmu maintains a reverse mapping whereby all ptes mapping a page can be +reached given its gfn. This is used, for example, when swapping out a page. + +Synchronized and unsynchronized pages +===================================== + +The guest uses two events to synchronize its tlb and page tables: tlb flushes +and page invalidations (invlpg). + +A tlb flush means that we need to synchronize all sptes reachable from the +guest's cr3. This is expensive, so we keep all guest page tables write +protected, and synchronize sptes to gptes when a gpte is written. + +A special case is when a guest page table is reachable from the current +guest cr3. In this case, the guest is obliged to issue an invlpg instruction +before using the translation. We take advantage of that by removing write +protection from the guest page, and allowing the guest to modify it freely. +We synchronize modified gptes when the guest invokes invlpg. This reduces +the amount of emulation we have to do when the guest modifies multiple gptes, +or when the a guest page is no longer used as a page table and is used for +random guest data. + +As a side effect we have to resynchronize all reachable unsynchronized shadow +pages on a tlb flush. + + +Reaction to events +================== + +- guest page fault (or npt page fault, or ept violation) + +This is the most complicated event. The cause of a page fault can be: + + - a true guest fault (the guest translation won't allow the access) (*) + - access to a missing translation + - access to a protected translation + - when logging dirty pages, memory is write protected + - synchronized shadow pages are write protected (*) + - access to untranslatable memory (mmio) + + (*) not applicable in direct mode + +Handling a page fault is performed as follows: + + - if needed, walk the guest page tables to determine the guest translation + (gva->gpa or ngpa->gpa) + - if permissions are insufficient, reflect the fault back to the guest + - determine the host page + - if this is an mmio request, there is no host page; call the emulator + to emulate the instruction instead + - walk the shadow page table to find the spte for the translation, + instantiating missing intermediate page tables as necessary + - try to unsynchronize the page + - if successful, we can let the guest continue and modify the gpte + - emulate the instruction + - if failed, unshadow the page and let the guest continue + - update any translations that were modified by the instruction + +invlpg handling: + + - walk the shadow page hierarchy and drop affected translations + - try to reinstantiate the indicated translation in the hope that the + guest will use it in the near future + +Guest control register updates: + +- mov to cr3 + - look up new shadow roots + - synchronize newly reachable shadow pages + +- mov to cr0/cr4/efer + - set up mmu context for new paging mode + - look up new shadow roots + - synchronize newly reachable shadow pages + +Host translation updates: + + - mmu notifier called with updated hva + - look up affected sptes through reverse map + - drop (or update) translations + +Further reading +=============== + +- NPT presentation from KVM Forum 2008 + http://www.linux-kvm.org/wiki/images/c/c8/KvmForum2008%24kdf2008_21.pdf + diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt index 39c0a09..fc15538 100644 --- a/Documentation/laptops/thinkpad-acpi.txt +++ b/Documentation/laptops/thinkpad-acpi.txt @@ -292,13 +292,13 @@ sysfs notes: Warning: when in NVRAM mode, the volume up/down/mute keys are synthesized according to changes in the mixer, - so you have to use volume up or volume down to unmute, - as per the ThinkPad volume mixer user interface. When - in ACPI event mode, volume up/down/mute are reported as - separate events, but this behaviour may be corrected in - future releases of this driver, in which case the - ThinkPad volume mixer user interface semantics will be - enforced. + which uses a single volume up or volume down hotkey + press to unmute, as per the ThinkPad volume mixer user + interface. When in ACPI event mode, volume up/down/mute + events are reported by the firmware and can behave + differently (and that behaviour changes with firmware + version -- not just with firmware models -- as well as + OSI(Linux) state). hotkey_poll_freq: frequency in Hz for hot key polling. It must be between @@ -309,7 +309,7 @@ sysfs notes: will cause hot key presses that require NVRAM polling to never be reported. - Setting hotkey_poll_freq too low will cause repeated + Setting hotkey_poll_freq too low may cause repeated pressings of the same hot key to be misreported as a single key press, or to not even be detected at all. The recommended polling frequency is 10Hz. @@ -397,6 +397,7 @@ ACPI Scan event code Key Notes 0x1001 0x00 FN+F1 - + 0x1002 0x01 FN+F2 IBM: battery (rare) Lenovo: Screen lock @@ -404,7 +405,8 @@ event code Key Notes this hot key, even with hot keys disabled or with Fn+F3 masked off - IBM: screen lock + IBM: screen lock, often turns + off the ThinkLight as side-effect Lenovo: battery 0x1004 0x03 FN+F4 Sleep button (ACPI sleep button @@ -433,7 +435,8 @@ event code Key Notes Do you feel lucky today? 0x1008 0x07 FN+F8 IBM: toggle screen expand - Lenovo: configure UltraNav + Lenovo: configure UltraNav, + or toggle screen expand 0x1009 0x08 FN+F9 - .. .. .. @@ -444,7 +447,7 @@ event code Key Notes either through the ACPI event, or through a hotkey event. The firmware may refuse to - generate further FN+F4 key + generate further FN+F12 key press events until a S3 or S4 ACPI sleep cycle is performed, or some time passes. @@ -512,15 +515,19 @@ events for switches: SW_RFKILL_ALL T60 and later hardware rfkill rocker switch SW_TABLET_MODE Tablet ThinkPads HKEY events 0x5009 and 0x500A -Non hot-key ACPI HKEY event map: +Non hotkey ACPI HKEY event map: +------------------------------- + +Events that are not propagated by the driver, except for legacy +compatibility purposes when hotkey_report_mode is set to 1: + 0x5001 Lid closed 0x5002 Lid opened 0x5009 Tablet swivel: switched to tablet mode 0x500A Tablet swivel: switched to normal mode 0x7000 Radio Switch may have changed state -The above events are not propagated by the driver, except for legacy -compatibility purposes when hotkey_report_mode is set to 1. +Events that are never propagated by the driver: 0x2304 System is waking up from suspend to undock 0x2305 System is waking up from suspend to eject bay @@ -528,14 +535,39 @@ compatibility purposes when hotkey_report_mode is set to 1. 0x2405 System is waking up from hibernation to eject bay 0x5010 Brightness level changed/control event -The above events are never propagated by the driver. +Events that are propagated by the driver to userspace: +0x2313 ALARM: System is waking up from suspend because + the battery is nearly empty +0x2413 ALARM: System is waking up from hibernation because + the battery is nearly empty 0x3003 Bay ejection (see 0x2x05) complete, can sleep again +0x3006 Bay hotplug request (hint to power up SATA link when + the optical drive tray is ejected) 0x4003 Undocked (see 0x2x04), can sleep again 0x500B Tablet pen inserted into its storage bay 0x500C Tablet pen removed from its storage bay - -The above events are propagated by the driver. +0x6011 ALARM: battery is too hot +0x6012 ALARM: battery is extremely hot +0x6021 ALARM: a sensor is too hot +0x6022 ALARM: a sensor is extremely hot +0x6030 System thermal table changed + +Battery nearly empty alarms are a last resort attempt to get the +operating system to hibernate or shutdown cleanly (0x2313), or shutdown +cleanly (0x2413) before power is lost. They must be acted upon, as the +wake up caused by the firmware will have negated most safety nets... + +When any of the "too hot" alarms happen, according to Lenovo the user +should suspend or hibernate the laptop (and in the case of battery +alarms, unplug the AC adapter) to let it cool down. These alarms do +signal that something is wrong, they should never happen on normal +operating conditions. + +The "extremely hot" alarms are emergencies. According to Lenovo, the +operating system is to force either an immediate suspend or hibernate +cycle, or a system shutdown. Obviously, something is very wrong if this +happens. Compatibility notes: diff --git a/Documentation/oops-tracing.txt b/Documentation/oops-tracing.txt index c10c022..6fe9001 100644 --- a/Documentation/oops-tracing.txt +++ b/Documentation/oops-tracing.txt @@ -256,9 +256,13 @@ characters, each representing a particular tainted value. 9: 'A' if the ACPI table has been overridden. 10: 'W' if a warning has previously been issued by the kernel. + (Though some warnings may set more specific taint flags.) 11: 'C' if a staging driver has been loaded. + 12: 'I' if the kernel is working around a severe bug in the platform + firmware (BIOS or similar). + The primary reason for the 'Tainted: ' string is to tell kernel debuggers if this is a clean kernel or if anything unusual has occurred. Tainting is permanent: even if an offending module is diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.txt index dd8fe43..62328d7 100644 --- a/Documentation/power/pci.txt +++ b/Documentation/power/pci.txt @@ -1,299 +1,1025 @@ - PCI Power Management -~~~~~~~~~~~~~~~~~~~~ -An overview of the concepts and the related functions in the Linux kernel +Copyright (c) 2010 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. + +An overview of concepts and the Linux kernel's interfaces related to PCI power +management. Based on previous work by Patrick Mochel <mochel@transmeta.com> +(and others). -Patrick Mochel <mochel@transmeta.com> -(and others) +This document only covers the aspects of power management specific to PCI +devices. For general description of the kernel's interfaces related to device +power management refer to Documentation/power/devices.txt and +Documentation/power/runtime_pm.txt. --------------------------------------------------------------------------- -1. Overview -2. How the PCI Subsystem Does Power Management -3. PCI Utility Functions -4. PCI Device Drivers -5. Resources - -1. Overview -~~~~~~~~~~~ - -The PCI Power Management Specification was introduced between the PCI 2.1 and -PCI 2.2 Specifications. It a standard interface for controlling various -power management operations. - -Implementation of the PCI PM Spec is optional, as are several sub-components of -it. If a device supports the PCI PM Spec, the device will have an 8 byte -capability field in its PCI configuration space. This field is used to describe -and control the standard PCI power management features. - -The PCI PM spec defines 4 operating states for devices (D0 - D3) and for buses -(B0 - B3). The higher the number, the less power the device consumes. However, -the higher the number, the longer the latency is for the device to return to -an operational state (D0). - -There are actually two D3 states. When someone talks about D3, they usually -mean D3hot, which corresponds to an ACPI D2 state (power is reduced, the -device may lose some context). But they may also mean D3cold, which is an -ACPI D3 state (power is fully off, all state was discarded); or both. - -Bus power management is not covered in this version of this document. - -Note that all PCI devices support D0 and D3cold by default, regardless of -whether or not they implement any of the PCI PM spec. - -The possible state transitions that a device can undergo are: - -+---------------------------+ -| Current State | New State | -+---------------------------+ -| D0 | D1, D2, D3| -+---------------------------+ -| D1 | D2, D3 | -+---------------------------+ -| D2 | D3 | -+---------------------------+ -| D1, D2, D3 | D0 | -+---------------------------+ - -Note that when the system is entering a global suspend state, all devices will -be placed into D3 and when resuming, all devices will be placed into D0. -However, when the system is running, other state transitions are possible. - -2. How The PCI Subsystem Handles Power Management -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The PCI suspend/resume functionality is accessed indirectly via the Power -Management subsystem. At boot, the PCI driver registers a power management -callback with that layer. Upon entering a suspend state, the PM layer iterates -through all of its registered callbacks. This currently takes place only during -APM state transitions. - -Upon going to sleep, the PCI subsystem walks its device tree twice. Both times, -it does a depth first walk of the device tree. The first walk saves each of the -device's state and checks for devices that will prevent the system from entering -a global power state. The next walk then places the devices in a low power +1. Hardware and Platform Support for PCI Power Management +2. PCI Subsystem and Device Power Management +3. PCI Device Drivers and Power Management +4. Resources + + +1. Hardware and Platform Support for PCI Power Management +========================================================= + +1.1. Native and Platform-Based Power Management +----------------------------------------------- +In general, power management is a feature allowing one to save energy by putting +devices into states in which they draw less power (low-power states) at the +price of reduced functionality or performance. + +Usually, a device is put into a low-power state when it is underutilized or +completely inactive. However, when it is necessary to use the device once +again, it has to be put back into the "fully functional" state (full-power +state). This may happen when there are some data for the device to handle or +as a result of an external event requiring the device to be active, which may +be signaled by the device itself. + +PCI devices may be put into low-power states in two ways, by using the device +capabilities introduced by the PCI Bus Power Management Interface Specification, +or with the help of platform firmware, such as an ACPI BIOS. In the first +approach, that is referred to as the native PCI power management (native PCI PM) +in what follows, the device power state is changed as a result of writing a +specific value into one of its standard configuration registers. The second +approach requires the platform firmware to provide special methods that may be +used by the kernel to change the device's power state. + +Devices supporting the native PCI PM usually can generate wakeup signals called +Power Management Events (PMEs) to let the kernel know about external events +requiring the device to be active. After receiving a PME the kernel is supposed +to put the device that sent it into the full-power state. However, the PCI Bus +Power Management Interface Specification doesn't define any standard method of +delivering the PME from the device to the CPU and the operating system kernel. +It is assumed that the platform firmware will perform this task and therefore, +even though a PCI device is set up to generate PMEs, it also may be necessary to +prepare the platform firmware for notifying the CPU of the PMEs coming from the +device (e.g. by generating interrupts). + +In turn, if the methods provided by the platform firmware are used for changing +the power state of a device, usually the platform also provides a method for +preparing the device to generate wakeup signals. In that case, however, it +often also is necessary to prepare the device for generating PMEs using the +native PCI PM mechanism, because the method provided by the platform depends on +that. + +Thus in many situations both the native and the platform-based power management +mechanisms have to be used simultaneously to obtain the desired result. + +1.2. Native PCI Power Management +-------------------------------- +The PCI Bus Power Management Interface Specification (PCI PM Spec) was +introduced between the PCI 2.1 and PCI 2.2 Specifications. It defined a +standard interface for performing various operations related to power +management. + +The implementation of the PCI PM Spec is optional for conventional PCI devices, +but it is mandatory for PCI Express devices. If a device supports the PCI PM +Spec, it has an 8 byte power management capability field in its PCI +configuration space. This field is used to describe and control the standard +features related to the native PCI power management. + +The PCI PM Spec defines 4 operating states for devices (D0-D3) and for buses +(B0-B3). The higher the number, the less power is drawn by the device or bus +in that state. However, the higher the number, the longer the latency for +the device or bus to return to the full-power state (D0 or B0, respectively). + +There are two variants of the D3 state defined by the specification. The first +one is D3hot, referred to as the software accessible D3, because devices can be +programmed to go into it. The second one, D3cold, is the state that PCI devices +are in when the supply voltage (Vcc) is removed from them. It is not possible +to program a PCI device to go into D3cold, although there may be a programmable +interface for putting the bus the device is on into a state in which Vcc is +removed from all devices on the bus. + +PCI bus power management, however, is not supported by the Linux kernel at the +time of this writing and therefore it is not covered by this document. + +Note that every PCI device can be in the full-power state (D0) or in D3cold, +regardless of whether or not it implements the PCI PM Spec. In addition to +that, if the PCI PM Spec is implemented by the device, it must support D3hot +as well as D0. The support for the D1 and D2 power states is optional. + +PCI devices supporting the PCI PM Spec can be programmed to go to any of the +supported low-power states (except for D3cold). While in D1-D3hot the +standard configuration registers of the device must be accessible to software +(i.e. the device is required to respond to PCI configuration accesses), although +its I/O and memory spaces are then disabled. This allows the device to be +programmatically put into D0. Thus the kernel can switch the device back and +forth between D0 and the supported low-power states (except for D3cold) and the +possible power state transitions the device can undergo are the following: + ++----------------------------+ +| Current State | New State | ++----------------------------+ +| D0 | D1, D2, D3 | ++----------------------------+ +| D1 | D2, D3 | ++----------------------------+ +| D2 | D3 | ++----------------------------+ +| D1, D2, D3 | D0 | ++----------------------------+ + +The transition from D3cold to D0 occurs when the supply voltage is provided to +the device (i.e. power is restored). In that case the device returns to D0 with +a full power-on reset sequence and the power-on defaults are restored to the +device by hardware just as at initial power up. + +PCI devices supporting the PCI PM Spec can be programmed to generate PMEs +while in a low-power state (D1-D3), but they are not required to be capable +of generating PMEs from all supported low-power states. In particular, the +capability of generating PMEs from D3cold is optional and depends on the +presence of additional voltage (3.3Vaux) allowing the device to remain +sufficiently active to generate a wakeup signal. + +1.3. ACPI Device Power Management +--------------------------------- +The platform firmware support for the power management of PCI devices is +system-specific. However, if the system in question is compliant with the +Advanced Configuration and Power Interface (ACPI) Specification, like the +majority of x86-based systems, it is supposed to implement device power +management interfaces defined by the ACPI standard. + +For this purpose the ACPI BIOS provides special functions called "control +methods" that may be executed by the kernel to perform specific tasks, such as +putting a device into a low-power state. These control methods are encoded +using special byte-code language called the ACPI Machine Language (AML) and +stored in the machine's BIOS. The kernel loads them from the BIOS and executes +them as needed using an AML interpreter that translates the AML byte code into +computations and memory or I/O space accesses. This way, in theory, a BIOS +writer can provide the kernel with a means to perform actions depending +on the system design in a system-specific fashion. + +ACPI control methods may be divided into global control methods, that are not +associated with any particular devices, and device control methods, that have +to be defined separately for each device supposed to be handled with the help of +the platform. This means, in particular, that ACPI device control methods can +only be used to handle devices that the BIOS writer knew about in advance. The +ACPI methods used for device power management fall into that category. + +The ACPI specification assumes that devices can be in one of four power states +labeled as D0, D1, D2, and D3 that roughly correspond to the native PCI PM +D0-D3 states (although the difference between D3hot and D3cold is not taken +into account by ACPI). Moreover, for each power state of a device there is a +set of power resources that have to be enabled for the device to be put into +that state. These power resources are controlled (i.e. enabled or disabled) +with the help of their own control methods, _ON and _OFF, that have to be +defined individually for each of them. + +To put a device into the ACPI power state Dx (where x is a number between 0 and +3 inclusive) the kernel is supposed to (1) enable the power resources required +by the device in this state using their _ON control methods and (2) execute the +_PSx control method defined for the device. In addition to that, if the device +is going to be put into a low-power state (D1-D3) and is supposed to generate +wakeup signals from that state, the _DSW (or _PSW, replaced with _DSW by ACPI +3.0) control method defined for it has to be executed before _PSx. Power +resources that are not required by the device in the target power state and are +not required any more by any other device should be disabled (by executing their +_OFF control methods). If the current power state of the device is D3, it can +only be put into D0 this way. + +However, quite often the power states of devices are changed during a +system-wide transition into a sleep state or back into the working state. ACPI +defines four system sleep states, S1, S2, S3, and S4, and denotes the system +working state as S0. In general, the target system sleep (or working) state +determines the highest power (lowest number) state the device can be put +into and the kernel is supposed to obtain this information by executing the +device's _SxD control method (where x is a number between 0 and 4 inclusive). +If the device is required to wake up the system from the target sleep state, the +lowest power (highest number) state it can be put into is also determined by the +target state of the system. The kernel is then supposed to use the device's +_SxW control method to obtain the number of that state. It also is supposed to +use the device's _PRW control method to learn which power resources need to be +enabled for the device to be able to generate wakeup signals. + +1.4. Wakeup Signaling +--------------------- +Wakeup signals generated by PCI devices, either as native PCI PMEs, or as +a result of the execution of the _DSW (or _PSW) ACPI control method before +putting the device into a low-power state, have to be caught and handled as +appropriate. If they are sent while the system is in the working state +(ACPI S0), they should be translated into interrupts so that the kernel can +put the devices generating them into the full-power state and take care of the +events that triggered them. In turn, if they are sent while the system is +sleeping, they should cause the system's core logic to trigger wakeup. + +On ACPI-based systems wakeup signals sent by conventional PCI devices are +converted into ACPI General-Purpose Events (GPEs) which are hardware signals +from the system core logic generated in response to various events that need to +be acted upon. Every GPE is associated with one or more sources of potentially +interesting events. In particular, a GPE may be associated with a PCI device +capable of signaling wakeup. The information on the connections between GPEs +and event sources is recorded in the system's ACPI BIOS from where it can be +read by the kernel. + +If a PCI device known to the system's ACPI BIOS signals wakeup, the GPE +associated with it (if there is one) is triggered. The GPEs associated with PCI +bridges may also be triggered in response to a wakeup signal from one of the +devices below the bridge (this also is the case for root bridges) and, for +example, native PCI PMEs from devices unknown to the system's ACPI BIOS may be +handled this way. + +A GPE may be triggered when the system is sleeping (i.e. when it is in one of +the ACPI S1-S4 states), in which case system wakeup is started by its core logic +(the device that was the source of the signal causing the system wakeup to occur +may be identified later). The GPEs used in such situations are referred to as +wakeup GPEs. + +Usually, however, GPEs are also triggered when the system is in the working +state (ACPI S0) and in that case the system's core logic generates a System +Control Interrupt (SCI) to notify the kernel of the event. Then, the SCI +handler identifies the GPE that caused the interrupt to be generated which, +in turn, allows the kernel to identify the source of the event (that may be +a PCI device signaling wakeup). The GPEs used for notifying the kernel of +events occurring while the system is in the working state are referred to as +runtime GPEs. + +Unfortunately, there is no standard way of handling wakeup signals sent by +conventional PCI devices on systems that are not ACPI-based, but there is one +for PCI Express devices. Namely, the PCI Express Base Specification introduced +a native mechanism for converting native PCI PMEs into interrupts generated by +root ports. For conventional PCI devices native PMEs are out-of-band, so they +are routed separately and they need not pass through bridges (in principle they +may be routed directly to the system's core logic), but for PCI Express devices +they are in-band messages that have to pass through the PCI Express hierarchy, +including the root port on the path from the device to the Root Complex. Thus +it was possible to introduce a mechanism by which a root port generates an +interrupt whenever it receives a PME message from one of the devices below it. +The PCI Express Requester ID of the device that sent the PME message is then +recorded in one of the root port's configuration registers from where it may be +read by the interrupt handler allowing the device to be identified. [PME +messages sent by PCI Express endpoints integrated with the Root Complex don't +pass through root ports, but instead they cause a Root Complex Event Collector +(if there is one) to generate interrupts.] + +In principle the native PCI Express PME signaling may also be used on ACPI-based +systems along with the GPEs, but to use it the kernel has to ask the system's +ACPI BIOS to release control of root port configuration registers. The ACPI +BIOS, however, is not required to allow the kernel to control these registers +and if it doesn't do that, the kernel must not modify their contents. Of course +the native PCI Express PME signaling cannot be used by the kernel in that case. + + +2. PCI Subsystem and Device Power Management +============================================ + +2.1. Device Power Management Callbacks +-------------------------------------- +The PCI Subsystem participates in the power management of PCI devices in a +number of ways. First of all, it provides an intermediate code layer between +the device power management core (PM core) and PCI device drivers. +Specifically, the pm field of the PCI subsystem's struct bus_type object, +pci_bus_type, points to a struct dev_pm_ops object, pci_dev_pm_ops, containing +pointers to several device power management callbacks: + +const struct dev_pm_ops pci_dev_pm_ops = { + .prepare = pci_pm_prepare, + .complete = pci_pm_complete, + .suspend = pci_pm_suspend, + .resume = pci_pm_resume, + .freeze = pci_pm_freeze, + .thaw = pci_pm_thaw, + .poweroff = pci_pm_poweroff, + .restore = pci_pm_restore, + .suspend_noirq = pci_pm_suspend_noirq, + .resume_noirq = pci_pm_resume_noirq, + .freeze_noirq = pci_pm_freeze_noirq, + .thaw_noirq = pci_pm_thaw_noirq, + .poweroff_noirq = pci_pm_poweroff_noirq, + .restore_noirq = pci_pm_restore_noirq, + .runtime_suspend = pci_pm_runtime_suspend, + .runtime_resume = pci_pm_runtime_resume, + .runtime_idle = pci_pm_runtime_idle, +}; + +These callbacks are executed by the PM core in various situations related to +device power management and they, in turn, execute power management callbacks +provided by PCI device drivers. They also perform power management operations +involving some standard configuration registers of PCI devices that device +drivers need not know or care about. + +The structure representing a PCI device, struct pci_dev, contains several fields +that these callbacks operate on: + +struct pci_dev { + ... + pci_power_t current_state; /* Current operating state. */ + int pm_cap; /* PM capability offset in the + configuration space */ + unsigned int pme_support:5; /* Bitmask of states from which PME# + can be generated */ + unsigned int pme_interrupt:1;/* Is native PCIe PME signaling used? */ + unsigned int d1_support:1; /* Low power state D1 is supported */ + unsigned int d2_support:1; /* Low power state D2 is supported */ + unsigned int no_d1d2:1; /* D1 and D2 are forbidden */ + unsigned int wakeup_prepared:1; /* Device prepared for wake up */ + unsigned int d3_delay; /* D3->D0 transition time in ms */ + ... +}; + +They also indirectly use some fields of the struct device that is embedded in +struct pci_dev. + +2.2. Device Initialization +-------------------------- +The PCI subsystem's first task related to device power management is to +prepare the device for power management and initialize the fields of struct +pci_dev used for this purpose. This happens in two functions defined in +drivers/pci/pci.c, pci_pm_init() and platform_pci_wakeup_init(). + +The first of these functions checks if the device supports native PCI PM +and if that's the case the offset of its power management capability structure +in the configuration space is stored in the pm_cap field of the device's struct +pci_dev object. Next, the function checks which PCI low-power states are +supported by the device and from which low-power states the device can generate +native PCI PMEs. The power management fields of the device's struct pci_dev and +the struct device embedded in it are updated accordingly and the generation of +PMEs by the device is disabled. + +The second function checks if the device can be prepared to signal wakeup with +the help of the platform firmware, such as the ACPI BIOS. If that is the case, +the function updates the wakeup fields in struct device embedded in the +device's struct pci_dev and uses the firmware-provided method to prevent the +device from signaling wakeup. + +At this point the device is ready for power management. For driverless devices, +however, this functionality is limited to a few basic operations carried out +during system-wide transitions to a sleep state and back to the working state. + +2.3. Runtime Device Power Management +------------------------------------ +The PCI subsystem plays a vital role in the runtime power management of PCI +devices. For this purpose it uses the general runtime power management +(runtime PM) framework described in Documentation/power/runtime_pm.txt. +Namely, it provides subsystem-level callbacks: + + pci_pm_runtime_suspend() + pci_pm_runtime_resume() + pci_pm_runtime_idle() + +that are executed by the core runtime PM routines. It also implements the +entire mechanics necessary for handling runtime wakeup signals from PCI devices +in low-power states, which at the time of this writing works for both the native +PCI Express PME signaling and the ACPI GPE-based wakeup signaling described in +Section 1. + +First, a PCI device is put into a low-power state, or suspended, with the help +of pm_schedule_suspend() or pm_runtime_suspend() which for PCI devices call +pci_pm_runtime_suspend() to do the actual job. For this to work, the device's +driver has to provide a pm->runtime_suspend() callback (see below), which is +run by pci_pm_runtime_suspend() as the first action. If the driver's callback +returns successfully, the device's standard configuration registers are saved, +the device is prepared to generate wakeup signals and, finally, it is put into +the target low-power state. + +The low-power state to put the device into is the lowest-power (highest number) +state from which it can signal wakeup. The exact method of signaling wakeup is +system-dependent and is determined by the PCI subsystem on the basis of the +reported capabilities of the device and the platform firmware. To prepare the +device for signaling wakeup and put it into the selected low-power state, the +PCI subsystem can use the platform firmware as well as the device's native PCI +PM capabilities, if supported. + +It is expected that the device driver's pm->runtime_suspend() callback will +not attempt to prepare the device for signaling wakeup or to put it into a +low-power state. The driver ought to leave these tasks to the PCI subsystem +that has all of the information necessary to perform them. + +A suspended device is brought back into the "active" state, or resumed, +with the help of pm_request_resume() or pm_runtime_resume() which both call +pci_pm_runtime_resume() for PCI devices. Again, this only works if the device's +driver provides a pm->runtime_resume() callback (see below). However, before +the driver's callback is executed, pci_pm_runtime_resume() brings the device +back into the full-power state, prevents it from signaling wakeup while in that +state and restores its standard configuration registers. Thus the driver's +callback need not worry about the PCI-specific aspects of the device resume. + +Note that generally pci_pm_runtime_resume() may be called in two different +situations. First, it may be called at the request of the device's driver, for +example if there are some data for it to process. Second, it may be called +as a result of a wakeup signal from the device itself (this sometimes is +referred to as "remote wakeup"). Of course, for this purpose the wakeup signal +is handled in one of the ways described in Section 1 and finally converted into +a notification for the PCI subsystem after the source device has been +identified. + +The pci_pm_runtime_idle() function, called for PCI devices by pm_runtime_idle() +and pm_request_idle(), executes the device driver's pm->runtime_idle() +callback, if defined, and if that callback doesn't return error code (or is not +present at all), suspends the device with the help of pm_runtime_suspend(). +Sometimes pci_pm_runtime_idle() is called automatically by the PM core (for +example, it is called right after the device has just been resumed), in which +cases it is expected to suspend the device if that makes sense. Usually, +however, the PCI subsystem doesn't really know if the device really can be +suspended, so it lets the device's driver decide by running its +pm->runtime_idle() callback. + +2.4. System-Wide Power Transitions +---------------------------------- +There are a few different types of system-wide power transitions, described in +Documentation/power/devices.txt. Each of them requires devices to be handled +in a specific way and the PM core executes subsystem-level power management +callbacks for this purpose. They are executed in phases such that each phase +involves executing the same subsystem-level callback for every device belonging +to the given subsystem before the next phase begins. These phases always run +after tasks have been frozen. + +2.4.1. System Suspend + +When the system is going into a sleep state in which the contents of memory will +be preserved, such as one of the ACPI sleep states S1-S3, the phases are: + + prepare, suspend, suspend_noirq. + +The following PCI bus type's callbacks, respectively, are used in these phases: + + pci_pm_prepare() + pci_pm_suspend() + pci_pm_suspend_noirq() + +The pci_pm_prepare() routine first puts the device into the "fully functional" +state with the help of pm_runtime_resume(). Then, it executes the device +driver's pm->prepare() callback if defined (i.e. if the driver's struct +dev_pm_ops object is present and the prepare pointer in that object is valid). + +The pci_pm_suspend() routine first checks if the device's driver implements +legacy PCI suspend routines (see Section 3), in which case the driver's legacy +suspend callback is executed, if present, and its result is returned. Next, if +the device's driver doesn't provide a struct dev_pm_ops object (containing +pointers to the driver's callbacks), pci_pm_default_suspend() is called, which +simply turns off the device's bus master capability and runs +pcibios_disable_device() to disable it, unless the device is a bridge (PCI +bridges are ignored by this routine). Next, the device driver's pm->suspend() +callback is executed, if defined, and its result is returned if it fails. +Finally, pci_fixup_device() is called to apply hardware suspend quirks related +to the device if necessary. + +Note that the suspend phase is carried out asynchronously for PCI devices, so +the pci_pm_suspend() callback may be executed in parallel for any pair of PCI +devices that don't depend on each other in a known way (i.e. none of the paths +in the device tree from the root bridge to a leaf device contains both of them). + +The pci_pm_suspend_noirq() routine is executed after suspend_device_irqs() has +been called, which means that the device driver's interrupt handler won't be +invoked while this routine is running. It first checks if the device's driver +implements legacy PCI suspends routines (Section 3), in which case the legacy +late suspend routine is called and its result is returned (the standard +configuration registers of the device are saved if the driver's callback hasn't +done that). Second, if the device driver's struct dev_pm_ops object is not +present, the device's standard configuration registers are saved and the routine +returns success. Otherwise the device driver's pm->suspend_noirq() callback is +executed, if present, and its result is returned if it fails. Next, if the +device's standard configuration registers haven't been saved yet (one of the +device driver's callbacks executed before might do that), pci_pm_suspend_noirq() +saves them, prepares the device to signal wakeup (if necessary) and puts it into +a low-power state. + +The low-power state to put the device into is the lowest-power (highest number) +state from which it can signal wakeup while the system is in the target sleep +state. Just like in the runtime PM case described above, the mechanism of +signaling wakeup is system-dependent and determined by the PCI subsystem, which +is also responsible for preparing the device to signal wakeup from the system's +target sleep state as appropriate. + +PCI device drivers (that don't implement legacy power management callbacks) are +generally not expected to prepare devices for signaling wakeup or to put them +into low-power states. However, if one of the driver's suspend callbacks +(pm->suspend() or pm->suspend_noirq()) saves the device's standard configuration +registers, pci_pm_suspend_noirq() will assume that the device has been prepared +to signal wakeup and put into a low-power state by the driver (the driver is +then assumed to have used the helper functions provided by the PCI subsystem for +this purpose). PCI device drivers are not encouraged to do that, but in some +rare cases doing that in the driver may be the optimum approach. + +2.4.2. System Resume + +When the system is undergoing a transition from a sleep state in which the +contents of memory have been preserved, such as one of the ACPI sleep states +S1-S3, into the working state (ACPI S0), the phases are: + + resume_noirq, resume, complete. + +The following PCI bus type's callbacks, respectively, are executed in these +phases: + + pci_pm_resume_noirq() + pci_pm_resume() + pci_pm_complete() + +The pci_pm_resume_noirq() routine first puts the device into the full-power +state, restores its standard configuration registers and applies early resume +hardware quirks related to the device, if necessary. This is done +unconditionally, regardless of whether or not the device's driver implements +legacy PCI power management callbacks (this way all PCI devices are in the +full-power state and their standard configuration registers have been restored +when their interrupt handlers are invoked for the first time during resume, +which allows the kernel to avoid problems with the handling of shared interrupts +by drivers whose devices are still suspended). If legacy PCI power management +callbacks (see Section 3) are implemented by the device's driver, the legacy +early resume callback is executed and its result is returned. Otherwise, the +device driver's pm->resume_noirq() callback is executed, if defined, and its +result is returned. + +The pci_pm_resume() routine first checks if the device's standard configuration +registers have been restored and restores them if that's not the case (this +only is necessary in the error path during a failing suspend). Next, resume +hardware quirks related to the device are applied, if necessary, and if the +device's driver implements legacy PCI power management callbacks (see +Section 3), the driver's legacy resume callback is executed and its result is +returned. Otherwise, the device's wakeup signaling mechanisms are blocked and +its driver's pm->resume() callback is executed, if defined (the callback's +result is then returned). + +The resume phase is carried out asynchronously for PCI devices, like the +suspend phase described above, which means that if two PCI devices don't depend +on each other in a known way, the pci_pm_resume() routine may be executed for +the both of them in parallel. + +The pci_pm_complete() routine only executes the device driver's pm->complete() +callback, if defined. + +2.4.3. System Hibernation + +System hibernation is more complicated than system suspend, because it requires +a system image to be created and written into a persistent storage medium. The +image is created atomically and all devices are quiesced, or frozen, before that +happens. + +The freezing of devices is carried out after enough memory has been freed (at +the time of this writing the image creation requires at least 50% of system RAM +to be free) in the following three phases: + + prepare, freeze, freeze_noirq + +that correspond to the PCI bus type's callbacks: + + pci_pm_prepare() + pci_pm_freeze() + pci_pm_freeze_noirq() + +This means that the prepare phase is exactly the same as for system suspend. +The other two phases, however, are different. + +The pci_pm_freeze() routine is quite similar to pci_pm_suspend(), but it runs +the device driver's pm->freeze() callback, if defined, instead of pm->suspend(), +and it doesn't apply the suspend-related hardware quirks. It is executed +asynchronously for different PCI devices that don't depend on each other in a +known way. + +The pci_pm_freeze_noirq() routine, in turn, is similar to +pci_pm_suspend_noirq(), but it calls the device driver's pm->freeze_noirq() +routine instead of pm->suspend_noirq(). It also doesn't attempt to prepare the +device for signaling wakeup and put it into a low-power state. Still, it saves +the device's standard configuration registers if they haven't been saved by one +of the driver's callbacks. + +Once the image has been created, it has to be saved. However, at this point all +devices are frozen and they cannot handle I/O, while their ability to handle +I/O is obviously necessary for the image saving. Thus they have to be brought +back to the fully functional state and this is done in the following phases: + + thaw_noirq, thaw, complete + +using the following PCI bus type's callbacks: + + pci_pm_thaw_noirq() + pci_pm_thaw() + pci_pm_complete() + +respectively. + +The first of them, pci_pm_thaw_noirq(), is analogous to pci_pm_resume_noirq(), +but it doesn't put the device into the full power state and doesn't attempt to +restore its standard configuration registers. It also executes the device +driver's pm->thaw_noirq() callback, if defined, instead of pm->resume_noirq(). + +The pci_pm_thaw() routine is similar to pci_pm_resume(), but it runs the device +driver's pm->thaw() callback instead of pm->resume(). It is executed +asynchronously for different PCI devices that don't depend on each other in a +known way. + +The complete phase it the same as for system resume. + +After saving the image, devices need to be powered down before the system can +enter the target sleep state (ACPI S4 for ACPI-based systems). This is done in +three phases: + + prepare, poweroff, poweroff_noirq + +where the prepare phase is exactly the same as for system suspend. The other +two phases are analogous to the suspend and suspend_noirq phases, respectively. +The PCI subsystem-level callbacks they correspond to + + pci_pm_poweroff() + pci_pm_poweroff_noirq() + +work in analogy with pci_pm_suspend() and pci_pm_poweroff_noirq(), respectively, +although they don't attempt to save the device's standard configuration +registers. + +2.4.4. System Restore + +System restore requires a hibernation image to be loaded into memory and the +pre-hibernation memory contents to be restored before the pre-hibernation system +activity can be resumed. + +As described in Documentation/power/devices.txt, the hibernation image is loaded +into memory by a fresh instance of the kernel, called the boot kernel, which in +turn is loaded and run by a boot loader in the usual way. After the boot kernel +has loaded the image, it needs to replace its own code and data with the code +and data of the "hibernated" kernel stored within the image, called the image +kernel. For this purpose all devices are frozen just like before creating +the image during hibernation, in the + + prepare, freeze, freeze_noirq + +phases described above. However, the devices affected by these phases are only +those having drivers in the boot kernel; other devices will still be in whatever +state the boot loader left them. + +Should the restoration of the pre-hibernation memory contents fail, the boot +kernel would go through the "thawing" procedure described above, using the +thaw_noirq, thaw, and complete phases (that will only affect the devices having +drivers in the boot kernel), and then continue running normally. + +If the pre-hibernation memory contents are restored successfully, which is the +usual situation, control is passed to the image kernel, which then becomes +responsible for bringing the system back to the working state. To achieve this, +it must restore the devices' pre-hibernation functionality, which is done much +like waking up from the memory sleep state, although it involves different +phases: + + restore_noirq, restore, complete + +The first two of these are analogous to the resume_noirq and resume phases +described above, respectively, and correspond to the following PCI subsystem +callbacks: + + pci_pm_restore_noirq() + pci_pm_restore() + +These callbacks work in analogy with pci_pm_resume_noirq() and pci_pm_resume(), +respectively, but they execute the device driver's pm->restore_noirq() and +pm->restore() callbacks, if available. + +The complete phase is carried out in exactly the same way as during system +resume. + + +3. PCI Device Drivers and Power Management +========================================== + +3.1. Power Management Callbacks +------------------------------- +PCI device drivers participate in power management by providing callbacks to be +executed by the PCI subsystem's power management routines described above and by +controlling the runtime power management of their devices. + +At the time of this writing there are two ways to define power management +callbacks for a PCI device driver, the recommended one, based on using a +dev_pm_ops structure described in Documentation/power/devices.txt, and the +"legacy" one, in which the .suspend(), .suspend_late(), .resume_early(), and +.resume() callbacks from struct pci_driver are used. The legacy approach, +however, doesn't allow one to define runtime power management callbacks and is +not really suitable for any new drivers. Therefore it is not covered by this +document (refer to the source code to learn more about it). + +It is recommended that all PCI device drivers define a struct dev_pm_ops object +containing pointers to power management (PM) callbacks that will be executed by +the PCI subsystem's PM routines in various circumstances. A pointer to the +driver's struct dev_pm_ops object has to be assigned to the driver.pm field in +its struct pci_driver object. Once that has happened, the "legacy" PM callbacks +in struct pci_driver are ignored (even if they are not NULL). + +The PM callbacks in struct dev_pm_ops are not mandatory and if they are not +defined (i.e. the respective fields of struct dev_pm_ops are unset) the PCI +subsystem will handle the device in a simplified default manner. If they are +defined, though, they are expected to behave as described in the following +subsections. + +3.1.1. prepare() + +The prepare() callback is executed during system suspend, during hibernation +(when a hibernation image is about to be created), during power-off after +saving a hibernation image and during system restore, when a hibernation image +has just been loaded into memory. + +This callback is only necessary if the driver's device has children that in +general may be registered at any time. In that case the role of the prepare() +callback is to prevent new children of the device from being registered until +one of the resume_noirq(), thaw_noirq(), or restore_noirq() callbacks is run. + +In addition to that the prepare() callback may carry out some operations +preparing the device to be suspended, although it should not allocate memory +(if additional memory is required to suspend the device, it has to be +preallocated earlier, for example in a suspend/hibernate notifier as described +in Documentation/power/notifiers.txt). + +3.1.2. suspend() + +The suspend() callback is only executed during system suspend, after prepare() +callbacks have been executed for all devices in the system. + +This callback is expected to quiesce the device and prepare it to be put into a +low-power state by the PCI subsystem. It is not required (in fact it even is +not recommended) that a PCI driver's suspend() callback save the standard +configuration registers of the device, prepare it for waking up the system, or +put it into a low-power state. All of these operations can very well be taken +care of by the PCI subsystem, without the driver's participation. + +However, in some rare case it is convenient to carry out these operations in +a PCI driver. Then, pci_save_state(), pci_prepare_to_sleep(), and +pci_set_power_state() should be used to save the device's standard configuration +registers, to prepare it for system wakeup (if necessary), and to put it into a +low-power state, respectively. Moreover, if the driver calls pci_save_state(), +the PCI subsystem will not execute either pci_prepare_to_sleep(), or +pci_set_power_state() for its device, so the driver is then responsible for +handling the device as appropriate. + +While the suspend() callback is being executed, the driver's interrupt handler +can be invoked to handle an interrupt from the device, so all suspend-related +operations relying on the driver's ability to handle interrupts should be +carried out in this callback. + +3.1.3. suspend_noirq() + +The suspend_noirq() callback is only executed during system suspend, after +suspend() callbacks have been executed for all devices in the system and +after device interrupts have been disabled by the PM core. + +The difference between suspend_noirq() and suspend() is that the driver's +interrupt handler will not be invoked while suspend_noirq() is running. Thus +suspend_noirq() can carry out operations that would cause race conditions to +arise if they were performed in suspend(). + +3.1.4. freeze() + +The freeze() callback is hibernation-specific and is executed in two situations, +during hibernation, after prepare() callbacks have been executed for all devices +in preparation for the creation of a system image, and during restore, +after a system image has been loaded into memory from persistent storage and the +prepare() callbacks have been executed for all devices. + +The role of this callback is analogous to the role of the suspend() callback +described above. In fact, they only need to be different in the rare cases when +the driver takes the responsibility for putting the device into a low-power state. -The first walk allows a graceful recovery in the event of a failure, since none -of the devices have actually been powered down. - -In both walks, in particular the second, all children of a bridge are touched -before the actual bridge itself. This allows the bridge to retain power while -its children are being accessed. - -Upon resuming from sleep, just the opposite must be true: all bridges must be -powered on and restored before their children are powered on. This is easily -accomplished with a breadth-first walk of the PCI device tree. - - -3. PCI Utility Functions -~~~~~~~~~~~~~~~~~~~~~~~~ - -These are helper functions designed to be called by individual device drivers. -Assuming that a device behaves as advertised, these should be applicable in most -cases. However, results may vary. - -Note that these functions are never implicitly called for the driver. The driver -is always responsible for deciding when and if to call these. - - -pci_save_state --------------- - -Usage: - pci_save_state(struct pci_dev *dev); - -Description: - Save first 64 bytes of PCI config space, along with any additional - PCI-Express or PCI-X information. - - -pci_restore_state ------------------ - -Usage: - pci_restore_state(struct pci_dev *dev); - -Description: - Restore previously saved config space. - - -pci_set_power_state -------------------- - -Usage: - pci_set_power_state(struct pci_dev *dev, pci_power_t state); - -Description: - Transition device to low power state using PCI PM Capabilities - registers. - - Will fail under one of the following conditions: - - If state is less than current state, but not D0 (illegal transition) - - Device doesn't support PM Capabilities - - Device does not support requested state - - -pci_enable_wake ---------------- - -Usage: - pci_enable_wake(struct pci_dev *dev, pci_power_t state, int enable); - -Description: - Enable device to generate PME# during low power state using PCI PM - Capabilities. - - Checks whether if device supports generating PME# from requested state - and fail if it does not, unless enable == 0 (request is to disable wake - events, which is implicit if it doesn't even support it in the first - place). - - Note that the PMC Register in the device's PM Capabilities has a bitmask - of the states it supports generating PME# from. D3hot is bit 3 and - D3cold is bit 4. So, while a value of 4 as the state may not seem - semantically correct, it is. - - -4. PCI Device Drivers -~~~~~~~~~~~~~~~~~~~~~ - -These functions are intended for use by individual drivers, and are defined in -struct pci_driver: - - int (*suspend) (struct pci_dev *dev, pm_message_t state); - int (*resume) (struct pci_dev *dev); - - -suspend -------- - -Usage: - -if (dev->driver && dev->driver->suspend) - dev->driver->suspend(dev,state); - -A driver uses this function to actually transition the device into a low power -state. This should include disabling I/O, IRQs, and bus-mastering, as well as -physically transitioning the device to a lower power state; it may also include -calls to pci_enable_wake(). - -Bus mastering may be disabled by doing: - -pci_disable_device(dev); - -For devices that support the PCI PM Spec, this may be used to set the device's -power state to match the suspend() parameter: - -pci_set_power_state(dev,state); - -The driver is also responsible for disabling any other device-specific features -(e.g blanking screen, turning off on-card memory, etc). - -The driver should be sure to track the current state of the device, as it may -obviate the need for some operations. - -The driver should update the current_state field in its pci_dev structure in -this function, except for PM-capable devices when pci_set_power_state is used. - -resume ------- - -Usage: - -if (dev->driver && dev->driver->resume) - dev->driver->resume(dev) +In that cases the freeze() callback should not prepare the device system wakeup +or put it into a low-power state. Still, either it or freeze_noirq() should +save the device's standard configuration registers using pci_save_state(). -The resume callback may be called from any power state, and is always meant to -transition the device to the D0 state. +3.1.5. freeze_noirq() -The driver is responsible for reenabling any features of the device that had -been disabled during previous suspend calls, such as IRQs and bus mastering, -as well as calling pci_restore_state(). +The freeze_noirq() callback is hibernation-specific. It is executed during +hibernation, after prepare() and freeze() callbacks have been executed for all +devices in preparation for the creation of a system image, and during restore, +after a system image has been loaded into memory and after prepare() and +freeze() callbacks have been executed for all devices. It is always executed +after device interrupts have been disabled by the PM core. -If the device is currently in D3, it may need to be reinitialized in resume(). +The role of this callback is analogous to the role of the suspend_noirq() +callback described above and it very rarely is necessary to define +freeze_noirq(). - * Some types of devices, like bus controllers, will preserve context in D3hot - (using Vcc power). Their drivers will often want to avoid re-initializing - them after re-entering D0 (perhaps to avoid resetting downstream devices). +The difference between freeze_noirq() and freeze() is analogous to the +difference between suspend_noirq() and suspend(). - * Other kinds of devices in D3hot will discard device context as part of a - soft reset when re-entering the D0 state. - - * Devices resuming from D3cold always go through a power-on reset. Some - device context can also be preserved using Vaux power. +3.1.6. poweroff() - * Some systems hide D3cold resume paths from drivers. For example, on PCs - the resume path for suspend-to-disk often runs BIOS powerup code, which - will sometimes re-initialize the device. +The poweroff() callback is hibernation-specific. It is executed when the system +is about to be powered off after saving a hibernation image to a persistent +storage. prepare() callbacks are executed for all devices before poweroff() is +called. -To handle resets during D3 to D0 transitions, it may be convenient to share -device initialization code between probe() and resume(). Device parameters -can also be saved before the driver suspends into D3, avoiding re-probe. +The role of this callback is analogous to the role of the suspend() and freeze() +callbacks described above, although it does not need to save the contents of +the device's registers. In particular, if the driver wants to put the device +into a low-power state itself instead of allowing the PCI subsystem to do that, +the poweroff() callback should use pci_prepare_to_sleep() and +pci_set_power_state() to prepare the device for system wakeup and to put it +into a low-power state, respectively, but it need not save the device's standard +configuration registers. -If the device supports the PCI PM Spec, it can use this to physically transition -the device to D0: +3.1.7. poweroff_noirq() -pci_set_power_state(dev,0); +The poweroff_noirq() callback is hibernation-specific. It is executed after +poweroff() callbacks have been executed for all devices in the system. -Note that if the entire system is transitioning out of a global sleep state, all -devices will be placed in the D0 state, so this is not necessary. However, in -the event that the device is placed in the D3 state during normal operation, -this call is necessary. It is impossible to determine which of the two events is -taking place in the driver, so it is always a good idea to make that call. +The role of this callback is analogous to the role of the suspend_noirq() and +freeze_noirq() callbacks described above, but it does not need to save the +contents of the device's registers. -The driver should take note of the state that it is resuming from in order to -ensure correct (and speedy) operation. +The difference between poweroff_noirq() and poweroff() is analogous to the +difference between suspend_noirq() and suspend(). -The driver should update the current_state field in its pci_dev structure in -this function, except for PM-capable devices when pci_set_power_state is used. +3.1.8. resume_noirq() +The resume_noirq() callback is only executed during system resume, after the +PM core has enabled the non-boot CPUs. The driver's interrupt handler will not +be invoked while resume_noirq() is running, so this callback can carry out +operations that might race with the interrupt handler. +Since the PCI subsystem unconditionally puts all devices into the full power +state in the resume_noirq phase of system resume and restores their standard +configuration registers, resume_noirq() is usually not necessary. In general +it should only be used for performing operations that would lead to race +conditions if carried out by resume(). -A reference implementation -------------------------- -.suspend() -{ - /* driver specific operations */ +3.1.9. resume() - /* Disable IRQ */ - free_irq(); - /* If using MSI */ - pci_disable_msi(); +The resume() callback is only executed during system resume, after +resume_noirq() callbacks have been executed for all devices in the system and +device interrupts have been enabled by the PM core. - pci_save_state(); - pci_enable_wake(); - /* Disable IO/bus master/irq router */ - pci_disable_device(); - pci_set_power_state(pci_choose_state()); -} +This callback is responsible for restoring the pre-suspend configuration of the +device and bringing it back to the fully functional state. The device should be +able to process I/O in a usual way after resume() has returned. -.resume() -{ - pci_set_power_state(PCI_D0); - pci_restore_state(); - /* device's irq possibly is changed, driver should take care */ - pci_enable_device(); - pci_set_master(); +3.1.10. thaw_noirq() - /* if using MSI, device's vector possibly is changed */ - pci_enable_msi(); +The thaw_noirq() callback is hibernation-specific. It is executed after a +system image has been created and the non-boot CPUs have been enabled by the PM +core, in the thaw_noirq phase of hibernation. It also may be executed if the +loading of a hibernation image fails during system restore (it is then executed +after enabling the non-boot CPUs). The driver's interrupt handler will not be +invoked while thaw_noirq() is running. - request_irq(); - /* driver specific operations; */ -} +The role of this callback is analogous to the role of resume_noirq(). The +difference between these two callbacks is that thaw_noirq() is executed after +freeze() and freeze_noirq(), so in general it does not need to modify the +contents of the device's registers. -This is a typical implementation. Drivers can slightly change the order -of the operations in the implementation, ignore some operations or add -more driver specific operations in it, but drivers should do something like -this on the whole. +3.1.11. thaw() -5. Resources -~~~~~~~~~~~~ +The thaw() callback is hibernation-specific. It is executed after thaw_noirq() +callbacks have been executed for all devices in the system and after device +interrupts have been enabled by the PM core. -PCI Local Bus Specification -PCI Bus Power Management Interface Specification +This callback is responsible for restoring the pre-freeze configuration of +the device, so that it will work in a usual way after thaw() has returned. - http://www.pcisig.com +3.1.12. restore_noirq() +The restore_noirq() callback is hibernation-specific. It is executed in the +restore_noirq phase of hibernation, when the boot kernel has passed control to +the image kernel and the non-boot CPUs have been enabled by the image kernel's +PM core. + +This callback is analogous to resume_noirq() with the exception that it cannot +make any assumption on the previous state of the device, even if the BIOS (or +generally the platform firmware) is known to preserve that state over a +suspend-resume cycle. + +For the vast majority of PCI device drivers there is no difference between +resume_noirq() and restore_noirq(). + +3.1.13. restore() + +The restore() callback is hibernation-specific. It is executed after +restore_noirq() callbacks have been executed for all devices in the system and +after the PM core has enabled device drivers' interrupt handlers to be invoked. + +This callback is analogous to resume(), just like restore_noirq() is analogous +to resume_noirq(). Consequently, the difference between restore_noirq() and +restore() is analogous to the difference between resume_noirq() and resume(). + +For the vast majority of PCI device drivers there is no difference between +resume() and restore(). + +3.1.14. complete() + +The complete() callback is executed in the following situations: + - during system resume, after resume() callbacks have been executed for all + devices, + - during hibernation, before saving the system image, after thaw() callbacks + have been executed for all devices, + - during system restore, when the system is going back to its pre-hibernation + state, after restore() callbacks have been executed for all devices. +It also may be executed if the loading of a hibernation image into memory fails +(in that case it is run after thaw() callbacks have been executed for all +devices that have drivers in the boot kernel). + +This callback is entirely optional, although it may be necessary if the +prepare() callback performs operations that need to be reversed. + +3.1.15. runtime_suspend() + +The runtime_suspend() callback is specific to device runtime power management +(runtime PM). It is executed by the PM core's runtime PM framework when the +device is about to be suspended (i.e. quiesced and put into a low-power state) +at run time. + +This callback is responsible for freezing the device and preparing it to be +put into a low-power state, but it must allow the PCI subsystem to perform all +of the PCI-specific actions necessary for suspending the device. + +3.1.16. runtime_resume() + +The runtime_resume() callback is specific to device runtime PM. It is executed +by the PM core's runtime PM framework when the device is about to be resumed +(i.e. put into the full-power state and programmed to process I/O normally) at +run time. + +This callback is responsible for restoring the normal functionality of the +device after it has been put into the full-power state by the PCI subsystem. +The device is expected to be able to process I/O in the usual way after +runtime_resume() has returned. + +3.1.17. runtime_idle() + +The runtime_idle() callback is specific to device runtime PM. It is executed +by the PM core's runtime PM framework whenever it may be desirable to suspend +the device according to the PM core's information. In particular, it is +automatically executed right after runtime_resume() has returned in case the +resume of the device has happened as a result of a spurious event. + +This callback is optional, but if it is not implemented or if it returns 0, the +PCI subsystem will call pm_runtime_suspend() for the device, which in turn will +cause the driver's runtime_suspend() callback to be executed. + +3.1.18. Pointing Multiple Callback Pointers to One Routine + +Although in principle each of the callbacks described in the previous +subsections can be defined as a separate function, it often is convenient to +point two or more members of struct dev_pm_ops to the same routine. There are +a few convenience macros that can be used for this purpose. + +The SIMPLE_DEV_PM_OPS macro declares a struct dev_pm_ops object with one +suspend routine pointed to by the .suspend(), .freeze(), and .poweroff() +members and one resume routine pointed to by the .resume(), .thaw(), and +.restore() members. The other function pointers in this struct dev_pm_ops are +unset. + +The UNIVERSAL_DEV_PM_OPS macro is similar to SIMPLE_DEV_PM_OPS, but it +additionally sets the .runtime_resume() pointer to the same value as +.resume() (and .thaw(), and .restore()) and the .runtime_suspend() pointer to +the same value as .suspend() (and .freeze() and .poweroff()). + +The SET_SYSTEM_SLEEP_PM_OPS can be used inside of a declaration of struct +dev_pm_ops to indicate that one suspend routine is to be pointed to by the +.suspend(), .freeze(), and .poweroff() members and one resume routine is to +be pointed to by the .resume(), .thaw(), and .restore() members. + +3.2. Device Runtime Power Management +------------------------------------ +In addition to providing device power management callbacks PCI device drivers +are responsible for controlling the runtime power management (runtime PM) of +their devices. + +The PCI device runtime PM is optional, but it is recommended that PCI device +drivers implement it at least in the cases where there is a reliable way of +verifying that the device is not used (like when the network cable is detached +from an Ethernet adapter or there are no devices attached to a USB controller). + +To support the PCI runtime PM the driver first needs to implement the +runtime_suspend() and runtime_resume() callbacks. It also may need to implement +the runtime_idle() callback to prevent the device from being suspended again +every time right after the runtime_resume() callback has returned +(alternatively, the runtime_suspend() callback will have to check if the +device should really be suspended and return -EAGAIN if that is not the case). + +The runtime PM of PCI devices is disabled by default. It is also blocked by +pci_pm_init() that runs the pm_runtime_forbid() helper function. If a PCI +driver implements the runtime PM callbacks and intends to use the runtime PM +framework provided by the PM core and the PCI subsystem, it should enable this +feature by executing the pm_runtime_enable() helper function. However, the +driver should not call the pm_runtime_allow() helper function unblocking +the runtime PM of the device. Instead, it should allow user space or some +platform-specific code to do that (user space can do it via sysfs), although +once it has called pm_runtime_enable(), it must be prepared to handle the +runtime PM of the device correctly as soon as pm_runtime_allow() is called +(which may happen at any time). [It also is possible that user space causes +pm_runtime_allow() to be called via sysfs before the driver is loaded, so in +fact the driver has to be prepared to handle the runtime PM of the device as +soon as it calls pm_runtime_enable().] + +The runtime PM framework works by processing requests to suspend or resume +devices, or to check if they are idle (in which cases it is reasonable to +subsequently request that they be suspended). These requests are represented +by work items put into the power management workqueue, pm_wq. Although there +are a few situations in which power management requests are automatically +queued by the PM core (for example, after processing a request to resume a +device the PM core automatically queues a request to check if the device is +idle), device drivers are generally responsible for queuing power management +requests for their devices. For this purpose they should use the runtime PM +helper functions provided by the PM core, discussed in +Documentation/power/runtime_pm.txt. + +Devices can also be suspended and resumed synchronously, without placing a +request into pm_wq. In the majority of cases this also is done by their +drivers that use helper functions provided by the PM core for this purpose. + +For more information on the runtime PM of devices refer to +Documentation/power/runtime_pm.txt. + + +4. Resources +============ + +PCI Local Bus Specification, Rev. 3.0 +PCI Bus Power Management Interface Specification, Rev. 1.2 +Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b +PCI Express Base Specification, Rev. 2.0 +Documentation/power/devices.txt +Documentation/power/runtime_pm.txt diff --git a/Documentation/powerpc/dts-bindings/4xx/reboot.txt b/Documentation/powerpc/dts-bindings/4xx/reboot.txt new file mode 100644 index 0000000..d721726 --- /dev/null +++ b/Documentation/powerpc/dts-bindings/4xx/reboot.txt @@ -0,0 +1,18 @@ +Reboot property to control system reboot on PPC4xx systems: + +By setting "reset_type" to one of the following values, the default +software reset mechanism may be overidden. Here the possible values of +"reset_type": + + 1 - PPC4xx core reset + 2 - PPC4xx chip reset + 3 - PPC4xx system reset (default) + +Example: + + cpu@0 { + device_type = "cpu"; + model = "PowerPC,440SPe"; + ... + reset-type = <2>; /* Use chip-reset */ + }; diff --git a/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt b/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt index d015dce..b0019eb 100644 --- a/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt +++ b/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt @@ -11,7 +11,7 @@ Required properties: 83xx, "fsl,mpc8572-gpio" for 85xx and "fsl,mpc8610-gpio" for 86xx. - #gpio-cells : Should be two. The first cell is the pin number and the second cell is used to specify optional parameters (currently unused). - - interrupts : Interrupt mapping for GPIO IRQ (currently unused). + - interrupts : Interrupt mapping for GPIO IRQ. - interrupt-parent : Phandle for the interrupt controller that services interrupts for this device. - gpio-controller : Marks the port as GPIO controller. @@ -38,3 +38,23 @@ Example of gpio-controller nodes for a MPC8347 SoC: See booting-without-of.txt for details of how to specify GPIO information for devices. + +To use GPIO pins as interrupt sources for peripherals, specify the +GPIO controller as the interrupt parent and define GPIO number + +trigger mode using the interrupts property, which is defined like +this: + +interrupts = <number trigger>, where: + - number: GPIO pin (0..31) + - trigger: trigger mode: + 2 = trigger on falling edge + 3 = trigger on both edges + +Example of device using this is: + + funkyfpga@0 { + compatible = "funky-fpga"; + ... + interrupts = <4 3>; + interrupt-parent = <&gpio1>; + }; diff --git a/Documentation/spi/ep93xx_spi b/Documentation/spi/ep93xx_spi new file mode 100644 index 0000000..6325f5b --- /dev/null +++ b/Documentation/spi/ep93xx_spi @@ -0,0 +1,95 @@ +Cirrus EP93xx SPI controller driver HOWTO +========================================= + +ep93xx_spi driver brings SPI master support for EP93xx SPI controller. Chip +selects are implemented with GPIO lines. + +NOTE: If possible, don't use SFRMOUT (SFRM1) signal as a chip select. It will +not work correctly (it cannot be controlled by software). Use GPIO lines +instead. + +Sample configuration +==================== + +Typically driver configuration is done in platform board files (the files under +arch/arm/mach-ep93xx/*.c). In this example we configure MMC over SPI through +this driver on TS-7260 board. You can adapt the code to suit your needs. + +This example uses EGPIO9 as SD/MMC card chip select (this is wired in DIO1 +header on the board). + +You need to select CONFIG_MMC_SPI to use mmc_spi driver. + +arch/arm/mach-ep93xx/ts72xx.c: + +... +#include <linux/gpio.h> +#include <linux/spi/spi.h> + +#include <mach/ep93xx_spi.h> + +/* this is our GPIO line used for chip select */ +#define MMC_CHIP_SELECT_GPIO EP93XX_GPIO_LINE_EGPIO9 + +static int ts72xx_mmc_spi_setup(struct spi_device *spi) +{ + int err; + + err = gpio_request(MMC_CHIP_SELECT_GPIO, spi->modalias); + if (err) + return err; + + gpio_direction_output(MMC_CHIP_SELECT_GPIO, 1); + + return 0; +} + +static void ts72xx_mmc_spi_cleanup(struct spi_device *spi) +{ + gpio_set_value(MMC_CHIP_SELECT_GPIO, 1); + gpio_direction_input(MMC_CHIP_SELECT_GPIO); + gpio_free(MMC_CHIP_SELECT_GPIO); +} + +static void ts72xx_mmc_spi_cs_control(struct spi_device *spi, int value) +{ + gpio_set_value(MMC_CHIP_SELECT_GPIO, value); +} + +static struct ep93xx_spi_chip_ops ts72xx_mmc_spi_ops = { + .setup = ts72xx_mmc_spi_setup, + .cleanup = ts72xx_mmc_spi_cleanup, + .cs_control = ts72xx_mmc_spi_cs_control, +}; + +static struct spi_board_info ts72xx_spi_devices[] __initdata = { + { + .modalias = "mmc_spi", + .controller_data = &ts72xx_mmc_spi_ops, + /* + * We use 10 MHz even though the maximum is 7.4 MHz. The driver + * will limit it automatically to max. frequency. + */ + .max_speed_hz = 10 * 1000 * 1000, + .bus_num = 0, + .chip_select = 0, + .mode = SPI_MODE_0, + }, +}; + +static struct ep93xx_spi_info ts72xx_spi_info = { + .num_chipselect = ARRAY_SIZE(ts72xx_spi_devices), +}; + +static void __init ts72xx_init_machine(void) +{ + ... + ep93xx_register_spi(&ts72xx_spi_info, ts72xx_spi_devices, + ARRAY_SIZE(ts72xx_spi_devices)); +} + +Thanks to +========= +Martin Guy, H. Hartley Sweeten and others who helped me during development of +the driver. Simplemachines.it donated me a Sim.One board which I used testing +the driver on EP9307. diff --git a/Documentation/spi/spidev_fdx.c b/Documentation/spi/spidev_fdx.c index fc354f7..36ec077 100644 --- a/Documentation/spi/spidev_fdx.c +++ b/Documentation/spi/spidev_fdx.c @@ -58,10 +58,10 @@ static void do_msg(int fd, int len) len = sizeof buf; buf[0] = 0xaa; - xfer[0].tx_buf = (__u64) buf; + xfer[0].tx_buf = (unsigned long)buf; xfer[0].len = 1; - xfer[1].rx_buf = (__u64) buf; + xfer[1].rx_buf = (unsigned long) buf; xfer[1].len = len; status = ioctl(fd, SPI_IOC_MESSAGE(2), xfer); diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 6c7d18c..5fdbb61 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -19,6 +19,7 @@ files can be found in mm/swap.c. Currently, these files are in /proc/sys/vm: - block_dump +- compact_memory - dirty_background_bytes - dirty_background_ratio - dirty_bytes @@ -26,6 +27,7 @@ Currently, these files are in /proc/sys/vm: - dirty_ratio - dirty_writeback_centisecs - drop_caches +- extfrag_threshold - hugepages_treat_as_movable - hugetlb_shm_group - laptop_mode @@ -64,6 +66,15 @@ information on block I/O debugging is in Documentation/laptops/laptop-mode.txt. ============================================================== +compact_memory + +Available only when CONFIG_COMPACTION is set. When 1 is written to the file, +all zones are compacted such that free memory is available in contiguous +blocks where possible. This can be important for example in the allocation of +huge pages although processes will also directly compact memory as required. + +============================================================== + dirty_background_bytes Contains the amount of dirty memory at which the pdflush background writeback @@ -139,6 +150,20 @@ user should run `sync' first. ============================================================== +extfrag_threshold + +This parameter affects whether the kernel will compact memory or direct +reclaim to satisfy a high-order allocation. /proc/extfrag_index shows what +the fragmentation index for each order is in each zone in the system. Values +tending towards 0 imply allocations would fail due to lack of memory, +values towards 1000 imply failures are due to fragmentation and -1 implies +that the allocation will succeed as long as watermarks are met. + +The kernel will not compact memory in a zone if the +fragmentation index is <= extfrag_threshold. The default value is 500. + +============================================================== + hugepages_treat_as_movable This parameter is only useful when kernelcore= is specified at boot time to diff --git a/Documentation/timers/hpet_example.c b/Documentation/timers/hpet_example.c index f9ce2d9..4bfafb7 100644 --- a/Documentation/timers/hpet_example.c +++ b/Documentation/timers/hpet_example.c @@ -10,7 +10,6 @@ #include <sys/types.h> #include <sys/wait.h> #include <signal.h> -#include <fcntl.h> #include <errno.h> #include <sys/time.h> #include <linux/hpet.h> @@ -24,7 +23,6 @@ extern void hpet_read(int, const char **); #include <sys/poll.h> #include <sys/ioctl.h> -#include <signal.h> struct hpet_command { char *command; diff --git a/Documentation/vm/map_hugetlb.c b/Documentation/vm/map_hugetlb.c index 9969c7d..eda1a6d 100644 --- a/Documentation/vm/map_hugetlb.c +++ b/Documentation/vm/map_hugetlb.c @@ -19,7 +19,7 @@ #define PROTECTION (PROT_READ | PROT_WRITE) #ifndef MAP_HUGETLB -#define MAP_HUGETLB 0x40 +#define MAP_HUGETLB 0x40000 /* arch specific */ #endif /* Only ia64 requires this */ diff --git a/Documentation/vm/numa b/Documentation/vm/numa index e93ad94..a200a38 100644 --- a/Documentation/vm/numa +++ b/Documentation/vm/numa @@ -1,41 +1,149 @@ Started Nov 1999 by Kanoj Sarcar <kanoj@sgi.com> -The intent of this file is to have an uptodate, running commentary -from different people about NUMA specific code in the Linux vm. - -What is NUMA? It is an architecture where the memory access times -for different regions of memory from a given processor varies -according to the "distance" of the memory region from the processor. -Each region of memory to which access times are the same from any -cpu, is called a node. On such architectures, it is beneficial if -the kernel tries to minimize inter node communications. Schemes -for this range from kernel text and read-only data replication -across nodes, and trying to house all the data structures that -key components of the kernel need on memory on that node. - -Currently, all the numa support is to provide efficient handling -of widely discontiguous physical memory, so architectures which -are not NUMA but can have huge holes in the physical address space -can use the same code. All this code is bracketed by CONFIG_DISCONTIGMEM. - -The initial port includes NUMAizing the bootmem allocator code by -encapsulating all the pieces of information into a bootmem_data_t -structure. Node specific calls have been added to the allocator. -In theory, any platform which uses the bootmem allocator should -be able to put the bootmem and mem_map data structures anywhere -it deems best. - -Each node's page allocation data structures have also been encapsulated -into a pg_data_t. The bootmem_data_t is just one part of this. To -make the code look uniform between NUMA and regular UMA platforms, -UMA platforms have a statically allocated pg_data_t too (contig_page_data). -For the sake of uniformity, the function num_online_nodes() is also defined -for all platforms. As we run benchmarks, we might decide to NUMAize -more variables like low_on_memory, nr_free_pages etc into the pg_data_t. - -The NUMA aware page allocation code currently tries to allocate pages -from different nodes in a round robin manner. This will be changed to -do concentratic circle search, starting from current node, once the -NUMA port achieves more maturity. The call alloc_pages_node has been -added, so that drivers can make the call and not worry about whether -it is running on a NUMA or UMA platform. +What is NUMA? + +This question can be answered from a couple of perspectives: the +hardware view and the Linux software view. + +From the hardware perspective, a NUMA system is a computer platform that +comprises multiple components or assemblies each of which may contain 0 +or more CPUs, local memory, and/or IO buses. For brevity and to +disambiguate the hardware view of these physical components/assemblies +from the software abstraction thereof, we'll call the components/assemblies +'cells' in this document. + +Each of the 'cells' may be viewed as an SMP [symmetric multi-processor] subset +of the system--although some components necessary for a stand-alone SMP system +may not be populated on any given cell. The cells of the NUMA system are +connected together with some sort of system interconnect--e.g., a crossbar or +point-to-point link are common types of NUMA system interconnects. Both of +these types of interconnects can be aggregated to create NUMA platforms with +cells at multiple distances from other cells. + +For Linux, the NUMA platforms of interest are primarily what is known as Cache +Coherent NUMA or ccNUMA systems. With ccNUMA systems, all memory is visible +to and accessible from any CPU attached to any cell and cache coherency +is handled in hardware by the processor caches and/or the system interconnect. + +Memory access time and effective memory bandwidth varies depending on how far +away the cell containing the CPU or IO bus making the memory access is from the +cell containing the target memory. For example, access to memory by CPUs +attached to the same cell will experience faster access times and higher +bandwidths than accesses to memory on other, remote cells. NUMA platforms +can have cells at multiple remote distances from any given cell. + +Platform vendors don't build NUMA systems just to make software developers' +lives interesting. Rather, this architecture is a means to provide scalable +memory bandwidth. However, to achieve scalable memory bandwidth, system and +application software must arrange for a large majority of the memory references +[cache misses] to be to "local" memory--memory on the same cell, if any--or +to the closest cell with memory. + +This leads to the Linux software view of a NUMA system: + +Linux divides the system's hardware resources into multiple software +abstractions called "nodes". Linux maps the nodes onto the physical cells +of the hardware platform, abstracting away some of the details for some +architectures. As with physical cells, software nodes may contain 0 or more +CPUs, memory and/or IO buses. And, again, memory accesses to memory on +"closer" nodes--nodes that map to closer cells--will generally experience +faster access times and higher effective bandwidth than accesses to more +remote cells. + +For some architectures, such as x86, Linux will "hide" any node representing a +physical cell that has no memory attached, and reassign any CPUs attached to +that cell to a node representing a cell that does have memory. Thus, on +these architectures, one cannot assume that all CPUs that Linux associates with +a given node will see the same local memory access times and bandwidth. + +In addition, for some architectures, again x86 is an example, Linux supports +the emulation of additional nodes. For NUMA emulation, linux will carve up +the existing nodes--or the system memory for non-NUMA platforms--into multiple +nodes. Each emulated node will manage a fraction of the underlying cells' +physical memory. NUMA emluation is useful for testing NUMA kernel and +application features on non-NUMA platforms, and as a sort of memory resource +management mechanism when used together with cpusets. +[see Documentation/cgroups/cpusets.txt] + +For each node with memory, Linux constructs an independent memory management +subsystem, complete with its own free page lists, in-use page lists, usage +statistics and locks to mediate access. In addition, Linux constructs for +each memory zone [one or more of DMA, DMA32, NORMAL, HIGH_MEMORY, MOVABLE], +an ordered "zonelist". A zonelist specifies the zones/nodes to visit when a +selected zone/node cannot satisfy the allocation request. This situation, +when a zone has no available memory to satisfy a request, is called +"overflow" or "fallback". + +Because some nodes contain multiple zones containing different types of +memory, Linux must decide whether to order the zonelists such that allocations +fall back to the same zone type on a different node, or to a different zone +type on the same node. This is an important consideration because some zones, +such as DMA or DMA32, represent relatively scarce resources. Linux chooses +a default zonelist order based on the sizes of the various zone types relative +to the total memory of the node and the total memory of the system. The +default zonelist order may be overridden using the numa_zonelist_order kernel +boot parameter or sysctl. [see Documentation/kernel-parameters.txt and +Documentation/sysctl/vm.txt] + +By default, Linux will attempt to satisfy memory allocation requests from the +node to which the CPU that executes the request is assigned. Specifically, +Linux will attempt to allocate from the first node in the appropriate zonelist +for the node where the request originates. This is called "local allocation." +If the "local" node cannot satisfy the request, the kernel will examine other +nodes' zones in the selected zonelist looking for the first zone in the list +that can satisfy the request. + +Local allocation will tend to keep subsequent access to the allocated memory +"local" to the underlying physical resources and off the system interconnect-- +as long as the task on whose behalf the kernel allocated some memory does not +later migrate away from that memory. The Linux scheduler is aware of the +NUMA topology of the platform--embodied in the "scheduling domains" data +structures [see Documentation/scheduler/sched-domains.txt]--and the scheduler +attempts to minimize task migration to distant scheduling domains. However, +the scheduler does not take a task's NUMA footprint into account directly. +Thus, under sufficient imbalance, tasks can migrate between nodes, remote +from their initial node and kernel data structures. + +System administrators and application designers can restrict a task's migration +to improve NUMA locality using various CPU affinity command line interfaces, +such as taskset(1) and numactl(1), and program interfaces such as +sched_setaffinity(2). Further, one can modify the kernel's default local +allocation behavior using Linux NUMA memory policy. +[see Documentation/vm/numa_memory_policy.] + +System administrators can restrict the CPUs and nodes' memories that a non- +privileged user can specify in the scheduling or NUMA commands and functions +using control groups and CPUsets. [see Documentation/cgroups/CPUsets.txt] + +On architectures that do not hide memoryless nodes, Linux will include only +zones [nodes] with memory in the zonelists. This means that for a memoryless +node the "local memory node"--the node of the first zone in CPU's node's +zonelist--will not be the node itself. Rather, it will be the node that the +kernel selected as the nearest node with memory when it built the zonelists. +So, default, local allocations will succeed with the kernel supplying the +closest available memory. This is a consequence of the same mechanism that +allows such allocations to fallback to other nearby nodes when a node that +does contain memory overflows. + +Some kernel allocations do not want or cannot tolerate this allocation fallback +behavior. Rather they want to be sure they get memory from the specified node +or get notified that the node has no free memory. This is usually the case when +a subsystem allocates per CPU memory resources, for example. + +A typical model for making such an allocation is to obtain the node id of the +node to which the "current CPU" is attached using one of the kernel's +numa_node_id() or CPU_to_node() functions and then request memory from only +the node id returned. When such an allocation fails, the requesting subsystem +may revert to its own fallback path. The slab kernel memory allocator is an +example of this. Or, the subsystem may choose to disable or not to enable +itself on allocation failure. The kernel profiling subsystem is an example of +this. + +If the architecture supports--does not hide--memoryless nodes, then CPUs +attached to memoryless nodes would always incur the fallback path overhead +or some subsystems would fail to initialize if they attempted to allocated +memory exclusively from a node without memory. To support such +architectures transparently, kernel subsystems can use the numa_mem_id() +or cpu_to_mem() function to locate the "local memory node" for the calling or +specified CPU. Again, this is the same node from which default, local page +allocations will be attempted. diff --git a/Documentation/watchdog/00-INDEX b/Documentation/watchdog/00-INDEX index c3ea47e..ee99451 100644 --- a/Documentation/watchdog/00-INDEX +++ b/Documentation/watchdog/00-INDEX @@ -1,10 +1,15 @@ 00-INDEX - this file. +hpwdt.txt + - information on the HP iLO2 NMI watchdog pcwd-watchdog.txt - documentation for Berkshire Products PC Watchdog ISA cards. src/ - directory holding watchdog related example programs. watchdog-api.txt - description of the Linux Watchdog driver API. +watchdog-parameters.txt + - information on driver parameters (for drivers other than + the ones that have driver-specific files here) wdt.txt - description of the Watchdog Timer Interfaces for Linux. diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt new file mode 100644 index 0000000..41c95cc --- /dev/null +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -0,0 +1,390 @@ +This file provides information on the module parameters of many of +the Linux watchdog drivers. Watchdog driver parameter specs should +be listed here unless the driver has its own driver-specific information +file. + + +See Documentation/kernel-parameters.txt for information on +providing kernel parameters for builtin drivers versus loadable +modules. + + +------------------------------------------------- +acquirewdt: +wdt_stop: Acquire WDT 'stop' io port (default 0x43) +wdt_start: Acquire WDT 'start' io port (default 0x443) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +advantechwdt: +wdt_stop: Advantech WDT 'stop' io port (default 0x443) +wdt_start: Advantech WDT 'start' io port (default 0x443) +timeout: Watchdog timeout in seconds. 1<= timeout <=63, default=60. +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +alim1535_wdt: +timeout: Watchdog timeout in seconds. (0 < timeout < 18000, default=60 +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +alim7101_wdt: +timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30 +use_gpio: Use the gpio watchdog (required by old cobalt boards). + default=0/off/no +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +ar7_wdt: +margin: Watchdog margin in seconds (default=60) +nowayout: Disable watchdog shutdown on close + (default=kernel config parameter) +------------------------------------------------- +at32ap700x_wdt: +timeout: Timeout value. Limited to be 1 or 2 seconds. (default=2) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +at91rm9200_wdt: +wdt_time: Watchdog time in seconds. (default=5) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +at91sam9_wdt: +heartbeat: Watchdog heartbeats in seconds. (default = 15) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +bcm47xx_wdt: +wdt_time: Watchdog time in seconds. (default=30) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +bfin_wdt: +timeout: Watchdog timeout in seconds. (1<=timeout<=((2^32)/SCLK), default=20) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +coh901327_wdt: +margin: Watchdog margin in seconds (default 60s) +------------------------------------------------- +cpu5wdt: +port: base address of watchdog card, default is 0x91 +verbose: be verbose, default is 0 (no) +ticks: count down ticks, default is 10000 +------------------------------------------------- +cpwd: +wd0_timeout: Default watchdog0 timeout in 1/10secs +wd1_timeout: Default watchdog1 timeout in 1/10secs +wd2_timeout: Default watchdog2 timeout in 1/10secs +------------------------------------------------- +davinci_wdt: +heartbeat: Watchdog heartbeat period in seconds from 1 to 600, default 60 +------------------------------------------------- +ep93xx_wdt: +nowayout: Watchdog cannot be stopped once started +timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=TBD) +------------------------------------------------- +eurotechwdt: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +io: Eurotech WDT io port (default=0x3f0) +irq: Eurotech WDT irq (default=10) +ev: Eurotech WDT event type (default is `int') +------------------------------------------------- +gef_wdt: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +geodewdt: +timeout: Watchdog timeout in seconds. 1<= timeout <=131, default=60. +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +i6300esb: +heartbeat: Watchdog heartbeat in seconds. (1<heartbeat<2046, default=30) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +iTCO_wdt: +heartbeat: Watchdog heartbeat in seconds. + (2<heartbeat<39 (TCO v1) or 613 (TCO v2), default=30) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +iTCO_vendor_support: +vendorsupport: iTCO vendor specific support mode, default=0 (none), + 1=SuperMicro Pent3, 2=SuperMicro Pent4+, 911=Broken SMI BIOS +------------------------------------------------- +ib700wdt: +timeout: Watchdog timeout in seconds. 0<= timeout <=30, default=30. +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +ibmasr: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +indydog: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +iop_wdt: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +it8712f_wdt: +margin: Watchdog margin in seconds (default 60) +nowayout: Disable watchdog shutdown on close + (default=kernel config parameter) +------------------------------------------------- +it87_wdt: +nogameport: Forbid the activation of game port, default=0 +exclusive: Watchdog exclusive device open, default=1 +timeout: Watchdog timeout in seconds, default=60 +testmode: Watchdog test mode (1 = no reboot), default=0 +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +ixp2000_wdt: +heartbeat: Watchdog heartbeat in seconds (default 60s) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +ixp4xx_wdt: +heartbeat: Watchdog heartbeat in seconds (default 60s) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +ks8695_wdt: +wdt_time: Watchdog time in seconds. (default=5) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +machzwd: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +action: after watchdog resets, generate: + 0 = RESET(*) 1 = SMI 2 = NMI 3 = SCI +------------------------------------------------- +max63xx_wdt: +heartbeat: Watchdog heartbeat period in seconds from 1 to 60, default 60 +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +nodelay: Force selection of a timeout setting without initial delay + (max6373/74 only, default=0) +------------------------------------------------- +mixcomwd: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +mpc8xxx_wdt: +timeout: Watchdog timeout in ticks. (0<timeout<65536, default=65535) +reset: Watchdog Interrupt/Reset Mode. 0 = interrupt, 1 = reset +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +mpcore_wdt: +mpcore_margin: MPcore timer margin in seconds. + (0 < mpcore_margin < 65536, default=60) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +mpcore_noboot: MPcore watchdog action, set to 1 to ignore reboots, + 0 to reboot (default=0 +------------------------------------------------- +mv64x60_wdt: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +nuc900_wdt: +heartbeat: Watchdog heartbeats in seconds. + (default = 15) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +omap_wdt: +timer_margin: initial watchdog timeout (in seconds) +------------------------------------------------- +orion_wdt: +heartbeat: Initial watchdog heartbeat in seconds +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +pc87413_wdt: +io: pc87413 WDT I/O port (default: io). +timeout: Watchdog timeout in minutes (default=timeout). +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +pika_wdt: +heartbeat: Watchdog heartbeats in seconds. (default = 15) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +pnx4008_wdt: +heartbeat: Watchdog heartbeat period in seconds from 1 to 60, default 19 +nowayout: Set to 1 to keep watchdog running after device release +------------------------------------------------- +pnx833x_wdt: +timeout: Watchdog timeout in Mhz. (68Mhz clock), default=2040000000 (30 seconds) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +start_enabled: Watchdog is started on module insertion (default=1) +------------------------------------------------- +rc32434_wdt: +timeout: Watchdog timeout value, in seconds (default=20) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +riowd: +riowd_timeout: Watchdog timeout in minutes (default=1) +------------------------------------------------- +s3c2410_wdt: +tmr_margin: Watchdog tmr_margin in seconds. (default=15) +tmr_atboot: Watchdog is started at boot time if set to 1, default=0 +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +soft_noboot: Watchdog action, set to 1 to ignore reboots, 0 to reboot +debug: Watchdog debug, set to >1 for debug, (default 0) +------------------------------------------------- +sa1100_wdt: +margin: Watchdog margin in seconds (default 60s) +------------------------------------------------- +sb_wdog: +timeout: Watchdog timeout in microseconds (max/default 8388607 or 8.3ish secs) +------------------------------------------------- +sbc60xxwdt: +wdt_stop: SBC60xx WDT 'stop' io port (default 0x45) +wdt_start: SBC60xx WDT 'start' io port (default 0x443) +timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +sbc7240_wdt: +timeout: Watchdog timeout in seconds. (1<=timeout<=255, default=30) +nowayout: Disable watchdog when closing device file +------------------------------------------------- +sbc8360: +timeout: Index into timeout table (0-63) (default=27 (60s)) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +sbc_epx_c3: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +sbc_fitpc2_wdt: +margin: Watchdog margin in seconds (default 60s) +nowayout: Watchdog cannot be stopped once started +------------------------------------------------- +sc1200wdt: +isapnp: When set to 0 driver ISA PnP support will be disabled (default=1) +io: io port +timeout: range is 0-255 minutes, default is 1 +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +sc520_wdt: +timeout: Watchdog timeout in seconds. (1 <= timeout <= 3600, default=30) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +sch311x_wdt: +force_id: Override the detected device ID +therm_trip: Should a ThermTrip trigger the reset generator +timeout: Watchdog timeout in seconds. 1<= timeout <=15300, default=60 +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +scx200_wdt: +margin: Watchdog margin in seconds +nowayout: Disable watchdog shutdown on close +------------------------------------------------- +shwdt: +clock_division_ratio: Clock division ratio. Valid ranges are from 0x5 (1.31ms) + to 0x7 (5.25ms). (default=7) +heartbeat: Watchdog heartbeat in seconds. (1 <= heartbeat <= 3600, default=30 +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +smsc37b787_wdt: +timeout: range is 1-255 units, default is 60 +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +softdog: +soft_margin: Watchdog soft_margin in seconds. + (0 < soft_margin < 65536, default=60) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +soft_noboot: Softdog action, set to 1 to ignore reboots, 0 to reboot + (default=0) +------------------------------------------------- +stmp3xxx_wdt: +heartbeat: Watchdog heartbeat period in seconds from 1 to 4194304, default 19 +------------------------------------------------- +ts72xx_wdt: +timeout: Watchdog timeout in seconds. (1 <= timeout <= 8, default=8) +nowayout: Disable watchdog shutdown on close +------------------------------------------------- +twl4030_wdt: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +txx9wdt: +timeout: Watchdog timeout in seconds. (0<timeout<N, default=60) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +w83627hf_wdt: +wdt_io: w83627hf/thf WDT io port (default 0x2E) +timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60. +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +w83697hf_wdt: +wdt_io: w83697hf/hg WDT io port (default 0x2e, 0 = autodetect) +timeout: Watchdog timeout in seconds. 1<= timeout <=255 (default=60) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +early_disable: Watchdog gets disabled at boot time (default=1) +------------------------------------------------- +w83697ug_wdt: +wdt_io: w83697ug/uf WDT io port (default 0x2e) +timeout: Watchdog timeout in seconds. 1<= timeout <=255 (default=60) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +w83877f_wdt: +timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +w83977f_wdt: +timeout: Watchdog timeout in seconds (15..7635), default=45) +testmode: Watchdog testmode (1 = no reboot), default=0 +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +wafer5823wdt: +timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60. +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +wdt285: +soft_margin: Watchdog timeout in seconds (default=60) +------------------------------------------------- +wdt977: +timeout: Watchdog timeout in seconds (60..15300, default=60) +testmode: Watchdog testmode (1 = no reboot), default=0 +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +wm831x_wdt: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- +wm8350_wdt: +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- diff --git a/Documentation/watchdog/wdt.txt b/Documentation/watchdog/wdt.txt index 03fd756..061c2e3 100644 --- a/Documentation/watchdog/wdt.txt +++ b/Documentation/watchdog/wdt.txt @@ -14,14 +14,22 @@ reboot will depend on the state of the machines and interrupts. The hardware boards physically pull the machine down off their own onboard timers and will reboot from almost anything. -A second temperature monitoring interface is available on the WDT501P cards +A second temperature monitoring interface is available on the WDT501P cards. This provides /dev/temperature. This is the machine internal temperature in degrees Fahrenheit. Each read returns a single byte giving the temperature. The third interface logs kernel messages on additional alert events. -The wdt card cannot be safely probed for. Instead you need to pass -wdt=ioaddr,irq as a boot parameter - eg "wdt=0x240,11". +The ICS ISA-bus wdt card cannot be safely probed for. Instead you need to +pass IO address and IRQ boot parameters. E.g.: + wdt.io=0x240 wdt.irq=11 + +Other "wdt" driver parameters are: + heartbeat Watchdog heartbeat in seconds (default 60) + nowayout Watchdog cannot be stopped once started (kernel + build parameter) + tachometer WDT501-P Fan Tachometer support (0=disable, default=0) + type WDT501-P Card type (500 or 501, default=500) Features -------- @@ -40,4 +48,3 @@ Minor numbers are however allocated for it. Example Watchdog Driver: see Documentation/watchdog/src/watchdog-simple.c - |
