diff options
Diffstat (limited to 'Documentation')
31 files changed, 1223 insertions, 103 deletions
diff --git a/Documentation/ABI/testing/sysfs-class-bdi b/Documentation/ABI/testing/sysfs-class-bdi new file mode 100644 index 00000000000..5ac1e01bbd4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-bdi @@ -0,0 +1,46 @@ +What: /sys/class/bdi/<bdi>/ +Date: January 2008 +Contact: Peter Zijlstra <a.p.zijlstra@chello.nl> +Description: + +Provide a place in sysfs for the backing_dev_info object. This allows +setting and retrieving various BDI specific variables. + +The <bdi> identifier can be either of the following: + +MAJOR:MINOR + + Device number for block devices, or value of st_dev on + non-block filesystems which provide their own BDI, such as NFS + and FUSE. + +default + + The default backing dev, used for non-block device backed + filesystems which do not provide their own BDI. + +Files under /sys/class/bdi/<bdi>/ +--------------------------------- + +read_ahead_kb (read-write) + + Size of the read-ahead window in kilobytes + +min_ratio (read-write) + + Under normal circumstances each device is given a part of the + total write-back cache that relates to its current average + writeout speed in relation to the other devices. + + The 'min_ratio' parameter allows assigning a minimum + percentage of the write-back cache to a particular device. + For example, this is useful for providing a minimum QoS. + +max_ratio (read-write) + + Allows limiting a particular device to use not more than the + given percentage of the write-back cache. This is useful in + situations where we want to avoid one device taking all or + most of the write-back cache. For example in case of an NFS + mount that is prone to get stuck, or a FUSE mount which cannot + be trusted to play fair. diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt index b939ebb6287..80d150458c8 100644 --- a/Documentation/DMA-API.txt +++ b/Documentation/DMA-API.txt @@ -145,7 +145,7 @@ Part Ic - DMA addressing limitations int dma_supported(struct device *dev, u64 mask) int -pci_dma_supported(struct device *dev, u64 mask) +pci_dma_supported(struct pci_dev *hwdev, u64 mask) Checks to see if the device can support DMA to the memory described by mask. @@ -189,7 +189,7 @@ dma_addr_t dma_map_single(struct device *dev, void *cpu_addr, size_t size, enum dma_data_direction direction) dma_addr_t -pci_map_single(struct device *dev, void *cpu_addr, size_t size, +pci_map_single(struct pci_dev *hwdev, void *cpu_addr, size_t size, int direction) Maps a piece of processor virtual memory so it can be accessed by the @@ -395,6 +395,71 @@ Notes: You must do this: See also dma_map_single(). +dma_addr_t +dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size, + enum dma_data_direction dir, + struct dma_attrs *attrs) + +void +dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr, + size_t size, enum dma_data_direction dir, + struct dma_attrs *attrs) + +int +dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl, + int nents, enum dma_data_direction dir, + struct dma_attrs *attrs) + +void +dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl, + int nents, enum dma_data_direction dir, + struct dma_attrs *attrs) + +The four functions above are just like the counterpart functions +without the _attrs suffixes, except that they pass an optional +struct dma_attrs*. + +struct dma_attrs encapsulates a set of "dma attributes". For the +definition of struct dma_attrs see linux/dma-attrs.h. + +The interpretation of dma attributes is architecture-specific, and +each attribute should be documented in Documentation/DMA-attributes.txt. + +If struct dma_attrs* is NULL, the semantics of each of these +functions is identical to those of the corresponding function +without the _attrs suffix. As a result dma_map_single_attrs() +can generally replace dma_map_single(), etc. + +As an example of the use of the *_attrs functions, here's how +you could pass an attribute DMA_ATTR_FOO when mapping memory +for DMA: + +#include <linux/dma-attrs.h> +/* DMA_ATTR_FOO should be defined in linux/dma-attrs.h and + * documented in Documentation/DMA-attributes.txt */ +... + + DEFINE_DMA_ATTRS(attrs); + dma_set_attr(DMA_ATTR_FOO, &attrs); + .... + n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, &attr); + .... + +Architectures that care about DMA_ATTR_FOO would check for its +presence in their implementations of the mapping and unmapping +routines, e.g.: + +void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr, + size_t size, enum dma_data_direction dir, + struct dma_attrs *attrs) +{ + .... + int foo = dma_get_attr(DMA_ATTR_FOO, attrs); + .... + if (foo) + /* twizzle the frobnozzle */ + .... + Part II - Advanced dma_ usage ----------------------------- diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.txt new file mode 100644 index 00000000000..6d772f84b47 --- /dev/null +++ b/Documentation/DMA-attributes.txt @@ -0,0 +1,24 @@ + DMA attributes + ============== + +This document describes the semantics of the DMA attributes that are +defined in linux/dma-attrs.h. + +DMA_ATTR_WRITE_BARRIER +---------------------- + +DMA_ATTR_WRITE_BARRIER is a (write) barrier attribute for DMA. DMA +to a memory region with the DMA_ATTR_WRITE_BARRIER attribute forces +all pending DMA writes to complete, and thus provides a mechanism to +strictly order DMA from a device across all intervening busses and +bridges. This barrier is not specific to a particular type of +interconnect, it applies to the system as a whole, and so its +implementation must account for the idiosyncracies of the system all +the way from the DMA device to memory. + +As an example of a situation where DMA_ATTR_WRITE_BARRIER would be +useful, suppose that a device does a DMA write to indicate that data is +ready and available in memory. The DMA of the "completion indication" +could race with data DMA. Mapping the memory used for completion +indications with DMA_ATTR_WRITE_BARRIER would prevent the race. + diff --git a/Documentation/DMA-mapping.txt b/Documentation/DMA-mapping.txt index d84f89dbf92..b463ecd0c7c 100644 --- a/Documentation/DMA-mapping.txt +++ b/Documentation/DMA-mapping.txt @@ -315,11 +315,11 @@ you should do: dma_addr_t dma_handle; - cpu_addr = pci_alloc_consistent(dev, size, &dma_handle); + cpu_addr = pci_alloc_consistent(pdev, size, &dma_handle); -where dev is a struct pci_dev *. You should pass NULL for PCI like buses -where devices don't have struct pci_dev (like ISA, EISA). This may be -called in interrupt context. +where pdev is a struct pci_dev *. This may be called in interrupt context. +You should use dma_alloc_coherent (see DMA-API.txt) for buses +where devices don't have struct pci_dev (like ISA, EISA). This argument is needed because the DMA translations may be bus specific (and often is private to the bus which the device is attached @@ -332,7 +332,7 @@ __get_free_pages (but takes size instead of a page order). If your driver needs regions sized smaller than a page, you may prefer using the pci_pool interface, described below. -The consistent DMA mapping interfaces, for non-NULL dev, will by +The consistent DMA mapping interfaces, for non-NULL pdev, will by default return a DMA address which is SAC (Single Address Cycle) addressable. Even if the device indicates (via PCI dma mask) that it may address the upper 32-bits and thus perform DAC cycles, consistent @@ -354,9 +354,9 @@ buffer you receive will not cross a 64K boundary. To unmap and free such a DMA region, you call: - pci_free_consistent(dev, size, cpu_addr, dma_handle); + pci_free_consistent(pdev, size, cpu_addr, dma_handle); -where dev, size are the same as in the above call and cpu_addr and +where pdev, size are the same as in the above call and cpu_addr and dma_handle are the values pci_alloc_consistent returned to you. This function may not be called in interrupt context. @@ -371,9 +371,9 @@ Create a pci_pool like this: struct pci_pool *pool; - pool = pci_pool_create(name, dev, size, align, alloc); + pool = pci_pool_create(name, pdev, size, align, alloc); -The "name" is for diagnostics (like a kmem_cache name); dev and size +The "name" is for diagnostics (like a kmem_cache name); pdev and size are as above. The device's hardware alignment requirement for this type of data is "align" (which is expressed in bytes, and must be a power of two). If your device has no boundary crossing restrictions, @@ -472,11 +472,11 @@ To map a single region, you do: void *addr = buffer->ptr; size_t size = buffer->len; - dma_handle = pci_map_single(dev, addr, size, direction); + dma_handle = pci_map_single(pdev, addr, size, direction); and to unmap it: - pci_unmap_single(dev, dma_handle, size, direction); + pci_unmap_single(pdev, dma_handle, size, direction); You should call pci_unmap_single when the DMA activity is finished, e.g. from the interrupt which told you that the DMA transfer is done. @@ -493,17 +493,17 @@ Specifically: unsigned long offset = buffer->offset; size_t size = buffer->len; - dma_handle = pci_map_page(dev, page, offset, size, direction); + dma_handle = pci_map_page(pdev, page, offset, size, direction); ... - pci_unmap_page(dev, dma_handle, size, direction); + pci_unmap_page(pdev, dma_handle, size, direction); Here, "offset" means byte offset within the given page. With scatterlists, you map a region gathered from several regions by: - int i, count = pci_map_sg(dev, sglist, nents, direction); + int i, count = pci_map_sg(pdev, sglist, nents, direction); struct scatterlist *sg; for_each_sg(sglist, sg, count, i) { @@ -527,7 +527,7 @@ accessed sg->address and sg->length as shown above. To unmap a scatterlist, just call: - pci_unmap_sg(dev, sglist, nents, direction); + pci_unmap_sg(pdev, sglist, nents, direction); Again, make sure DMA activity has already finished. @@ -550,11 +550,11 @@ correct copy of the DMA buffer. So, firstly, just map it with pci_map_{single,sg}, and after each DMA transfer call either: - pci_dma_sync_single_for_cpu(dev, dma_handle, size, direction); + pci_dma_sync_single_for_cpu(pdev, dma_handle, size, direction); or: - pci_dma_sync_sg_for_cpu(dev, sglist, nents, direction); + pci_dma_sync_sg_for_cpu(pdev, sglist, nents, direction); as appropriate. @@ -562,7 +562,7 @@ Then, if you wish to let the device get at the DMA area again, finish accessing the data with the cpu, and then before actually giving the buffer to the hardware call either: - pci_dma_sync_single_for_device(dev, dma_handle, size, direction); + pci_dma_sync_single_for_device(pdev, dma_handle, size, direction); or: @@ -739,7 +739,7 @@ failure can be determined by: dma_addr_t dma_handle; - dma_handle = pci_map_single(dev, addr, size, direction); + dma_handle = pci_map_single(pdev, addr, size, direction); if (pci_dma_mapping_error(dma_handle)) { /* * reduce current DMA mapping usage, diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 83966e94cc3..0eb0d027eb3 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -12,7 +12,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ - mac80211.xml + mac80211.xml debugobjects.xml ### # The build process is as follows (targets): diff --git a/Documentation/DocBook/debugobjects.tmpl b/Documentation/DocBook/debugobjects.tmpl new file mode 100644 index 00000000000..7f5f218015f --- /dev/null +++ b/Documentation/DocBook/debugobjects.tmpl @@ -0,0 +1,391 @@ +<?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="debug-objects-guide"> + <bookinfo> + <title>Debug objects life time</title> + + <authorgroup> + <author> + <firstname>Thomas</firstname> + <surname>Gleixner</surname> + <affiliation> + <address> + <email>tglx@linutronix.de</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2008</year> + <holder>Thomas Gleixner</holder> + </copyright> + + <legalnotice> + <para> + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + </para> + + <para> + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + </para> + + <para> + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + </para> + + <para> + For more details see the file COPYING in the source + distribution of Linux. + </para> + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + debugobjects is a generic infrastructure to track the life time + of kernel objects and validate the operations on those. + </para> + <para> + debugobjects is useful to check for the following error patterns: + <itemizedlist> + <listitem><para>Activation of uninitialized objects</para></listitem> + <listitem><para>Initialization of active objects</para></listitem> + <listitem><para>Usage of freed/destroyed objects</para></listitem> + </itemizedlist> + </para> + <para> + debugobjects is not changing the data structure of the real + object so it can be compiled in with a minimal runtime impact + and enabled on demand with a kernel command line option. + </para> + </chapter> + + <chapter id="howto"> + <title>Howto use debugobjects</title> + <para> + A kernel subsystem needs to provide a data structure which + describes the object type and add calls into the debug code at + appropriate places. The data structure to describe the object + type needs at minimum the name of the object type. Optional + functions can and should be provided to fixup detected problems + so the kernel can continue to work and the debug information can + be retrieved from a live system instead of hard core debugging + with serial consoles and stack trace transcripts from the + monitor. + </para> + <para> + The debug calls provided by debugobjects are: + <itemizedlist> + <listitem><para>debug_object_init</para></listitem> + <listitem><para>debug_object_init_on_stack</para></listitem> + <listitem><para>debug_object_activate</para></listitem> + <listitem><para>debug_object_deactivate</para></listitem> + <listitem><para>debug_object_destroy</para></listitem> + <listitem><para>debug_object_free</para></listitem> + </itemizedlist> + Each of these functions takes the address of the real object and + a pointer to the object type specific debug description + structure. + </para> + <para> + Each detected error is reported in the statistics and a limited + number of errors are printk'ed including a full stack trace. + </para> + <para> + The statistics are available via debugfs/debug_objects/stats. + They provide information about the number of warnings and the + number of successful fixups along with information about the + usage of the internal tracking objects and the state of the + internal tracking objects pool. + </para> + </chapter> + <chapter id="debugfunctions"> + <title>Debug functions</title> + <sect1 id="prototypes"> + <title>Debug object function reference</title> +!Elib/debugobjects.c + </sect1> + <sect1 id="debug_object_init"> + <title>debug_object_init</title> + <para> + This function is called whenever the initialization function + of a real object is called. + </para> + <para> + When the real object is already tracked by debugobjects it is + checked, whether the object can be initialized. Initializing + is not allowed for active and destroyed objects. When + debugobjects detects an error, then it calls the fixup_init + function of the object type description structure if provided + by the caller. The fixup function can correct the problem + before the real initialization of the object happens. E.g. it + can deactivate an active object in order to prevent damage to + the subsystem. + </para> + <para> + When the real object is not yet tracked by debugobjects, + debugobjects allocates a tracker object for the real object + and sets the tracker object state to ODEBUG_STATE_INIT. It + verifies that the object is not on the callers stack. If it is + on the callers stack then a limited number of warnings + including a full stack trace is printk'ed. The calling code + must use debug_object_init_on_stack() and remove the object + before leaving the function which allocated it. See next + section. + </para> + </sect1> + + <sect1 id="debug_object_init_on_stack"> + <title>debug_object_init_on_stack</title> + <para> + This function is called whenever the initialization function + of a real object which resides on the stack is called. + </para> + <para> + When the real object is already tracked by debugobjects it is + checked, whether the object can be initialized. Initializing + is not allowed for active and destroyed objects. When + debugobjects detects an error, then it calls the fixup_init + function of the object type description structure if provided + by the caller. The fixup function can correct the problem + before the real initialization of the object happens. E.g. it + can deactivate an active object in order to prevent damage to + the subsystem. + </para> + <para> + When the real object is not yet tracked by debugobjects + debugobjects allocates a tracker object for the real object + and sets the tracker object state to ODEBUG_STATE_INIT. It + verifies that the object is on the callers stack. + </para> + <para> + An object which is on the stack must be removed from the + tracker by calling debug_object_free() before the function + which allocates the object returns. Otherwise we keep track of + stale objects. + </para> + </sect1> + + <sect1 id="debug_object_activate"> + <title>debug_object_activate</title> + <para> + This function is called whenever the activation function of a + real object is called. + </para> + <para> + When the real object is already tracked by debugobjects it is + checked, whether the object can be activated. Activating is + not allowed for active and destroyed objects. When + debugobjects detects an error, then it calls the + fixup_activate function of the object type description + structure if provided by the caller. The fixup function can + correct the problem before the real activation of the object + happens. E.g. it can deactivate an active object in order to + prevent damage to the subsystem. + </para> + <para> + When the real object is not yet tracked by debugobjects then + the fixup_activate function is called if available. This is + necessary to allow the legitimate activation of statically + allocated and initialized objects. The fixup function checks + whether the object is valid and calls the debug_objects_init() + function to initialize the tracking of this object. + </para> + <para> + When the activation is legitimate, then the state of the + associated tracker object is set to ODEBUG_STATE_ACTIVE. + </para> + </sect1> + + <sect1 id="debug_object_deactivate"> + <title>debug_object_deactivate</title> + <para> + This function is called whenever the deactivation function of + a real object is called. + </para> + <para> + When the real object is tracked by debugobjects it is checked, + whether the object can be deactivated. Deactivating is not + allowed for untracked or destroyed objects. + </para> + <para> + When the deactivation is legitimate, then the state of the + associated tracker object is set to ODEBUG_STATE_INACTIVE. + </para> + </sect1> + + <sect1 id="debug_object_destroy"> + <title>debug_object_destroy</title> + <para> + This function is called to mark an object destroyed. This is + useful to prevent the usage of invalid objects, which are + still available in memory: either statically allocated objects + or objects which are freed later. + </para> + <para> + When the real object is tracked by debugobjects it is checked, + whether the object can be destroyed. Destruction is not + allowed for active and destroyed objects. When debugobjects + detects an error, then it calls the fixup_destroy function of + the object type description structure if provided by the + caller. The fixup function can correct the problem before the + real destruction of the object happens. E.g. it can deactivate + an active object in order to prevent damage to the subsystem. + </para> + <para> + When the destruction is legitimate, then the state of the + associated tracker object is set to ODEBUG_STATE_DESTROYED. + </para> + </sect1> + + <sect1 id="debug_object_free"> + <title>debug_object_free</title> + <para> + This function is called before an object is freed. + </para> + <para> + When the real object is tracked by debugobjects it is checked, + whether the object can be freed. Free is not allowed for + active objects. When debugobjects detects an error, then it + calls the fixup_free function of the object type description + structure if provided by the caller. The fixup function can + correct the problem before the real free of the object + happens. E.g. it can deactivate an active object in order to + prevent damage to the subsystem. + </para> + <para> + Note that debug_object_free removes the object from the + tracker. Later usage of the object is detected by the other + debug checks. + </para> + </sect1> + </chapter> + <chapter id="fixupfunctions"> + <title>Fixup functions</title> + <sect1 id="debug_obj_descr"> + <title>Debug object type description structure</title> +!Iinclude/linux/debugobjects.h + </sect1> + <sect1 id="fixup_init"> + <title>fixup_init</title> + <para> + This function is called from the debug code whenever a problem + in debug_object_init is detected. The function takes the + address of the object and the state which is currently + recorded in the tracker. + </para> + <para> + Called from debug_object_init when the object state is: + <itemizedlist> + <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> + </itemizedlist> + </para> + <para> + The function returns 1 when the fixup was successful, + otherwise 0. The return value is used to update the + statistics. + </para> + <para> + Note, that the function needs to call the debug_object_init() + function again, after the damage has been repaired in order to + keep the state consistent. + </para> + </sect1> + + <sect1 id="fixup_activate"> + <title>fixup_activate</title> + <para> + This function is called from the debug code whenever a problem + in debug_object_activate is detected. + </para> + <para> + Called from debug_object_activate when the object state is: + <itemizedlist> + <listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem> + <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> + </itemizedlist> + </para> + <para> + The function returns 1 when the fixup was successful, + otherwise 0. The return value is used to update the + statistics. + </para> + <para> + Note that the function needs to call the debug_object_activate() + function again after the damage has been repaired in order to + keep the state consistent. + </para> + <para> + The activation of statically initialized objects is a special + case. When debug_object_activate() has no tracked object for + this object address then fixup_activate() is called with + object state ODEBUG_STATE_NOTAVAILABLE. The fixup function + needs to check whether this is a legitimate case of a + statically initialized object or not. In case it is it calls + debug_object_init() and debug_object_activate() to make the + object known to the tracker and marked active. In this case + the function should return 0 because this is not a real fixup. + </para> + </sect1> + + <sect1 id="fixup_destroy"> + <title>fixup_destroy</title> + <para> + This function is called from the debug code whenever a problem + in debug_object_destroy is detected. + </para> + <para> + Called from debug_object_destroy when the object state is: + <itemizedlist> + <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> + </itemizedlist> + </para> + <para> + The function returns 1 when the fixup was successful, + otherwise 0. The return value is used to update the + statistics. + </para> + </sect1> + <sect1 id="fixup_free"> + <title>fixup_free</title> + <para> + This function is called from the debug code whenever a problem + in debug_object_free is detected. Further it can be called + from the debug checks in kfree/vfree, when an active object is + detected from the debug_check_no_obj_freed() sanity checks. + </para> + <para> + Called from debug_object_free() or debug_check_no_obj_freed() + when the object state is: + <itemizedlist> + <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> + </itemizedlist> + </para> + <para> + The function returns 1 when the fixup was successful, + otherwise 0. The return value is used to update the + statistics. + </para> + </sect1> + </chapter> + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + None (knock on wood). + </para> + </chapter> +</book> diff --git a/Documentation/DocBook/rapidio.tmpl b/Documentation/DocBook/rapidio.tmpl index b9e143e28c6..54eb26b5737 100644 --- a/Documentation/DocBook/rapidio.tmpl +++ b/Documentation/DocBook/rapidio.tmpl @@ -133,7 +133,6 @@ !Idrivers/rapidio/rio-sysfs.c </sect1> <sect1 id="PPC32_support"><title>PPC32 support</title> -!Iarch/powerpc/kernel/rio.c !Earch/powerpc/sysdev/fsl_rio.c !Iarch/powerpc/sysdev/fsl_rio.c </sect1> diff --git a/Documentation/braille-console.txt b/Documenta |