scheduler: cpuacct: Enable platform hooks to track cpuusage for CPU frequencies
[linux-2.6.git] / Documentation / usb / dma.txt
index e8b50b7..84ef865 100644 (file)
@@ -6,8 +6,9 @@ in the kernel usb programming guide (kerneldoc, from the source code).
 API OVERVIEW
 
 The big picture is that USB drivers can continue to ignore most DMA issues,
-though they still must provide DMA-ready buffers (see DMA-mapping.txt).
-That's how they've worked through the 2.4 (and earlier) kernels.
+though they still must provide DMA-ready buffers (see
+Documentation/PCI/PCI-DMA-mapping.txt).  That's how they've worked through
+the 2.4 (and earlier) kernels.
 
 OR:  they can now be DMA-aware.
 
@@ -15,11 +16,11 @@ OR:  they can now be DMA-aware.
   manage dma mappings for existing dma-ready buffers (see below).
 
 - URBs have an additional "transfer_dma" field, as well as a transfer_flags
-  bit saying if it's valid.  (Control requests also have "setup_dma" and a
-  corresponding transfer_flags bit.)
+  bit saying if it's valid.  (Control requests also have "setup_dma", but
+  drivers must not use it.)
 
-- "usbcore" will map those DMA addresses, if a DMA-aware driver didn't do
-  it first and set URB_NO_TRANSFER_DMA_MAP or URB_NO_SETUP_DMA_MAP.  HCDs
+- "usbcore" will map this DMA address, if a DMA-aware driver didn't do
+  it first and set URB_NO_TRANSFER_DMA_MAP.  HCDs
   don't manage dma mappings for URBs.
 
 - There's a new "generic DMA API", parts of which are usable by USB device
@@ -42,28 +43,22 @@ and effects like cache-trashing can impose subtle penalties.
   kind of addresses to store in urb->transfer_buffer and urb->transfer_dma.
   You'd also set URB_NO_TRANSFER_DMA_MAP in urb->transfer_flags:
 
-       void *usb_buffer_alloc (struct usb_device *dev, size_t size,
+       void *usb_alloc_coherent (struct usb_device *dev, size_t size,
                int mem_flags, dma_addr_t *dma);
 
-       void usb_buffer_free (struct usb_device *dev, size_t size,
+       void usb_free_coherent (struct usb_device *dev, size_t size,
                void *addr, dma_addr_t dma);
 
   Most drivers should *NOT* be using these primitives; they don't need
   to use this type of memory ("dma-coherent"), and memory returned from
   kmalloc() will work just fine.
 
-  For control transfers you can use the buffer primitives or not for each
-  of the transfer buffer and setup buffer independently.  Set the flag bits
-  URB_NO_TRANSFER_DMA_MAP and URB_NO_SETUP_DMA_MAP to indicate which
-  buffers you have prepared.  For non-control transfers URB_NO_SETUP_DMA_MAP
-  is ignored.
-
   The memory buffer returned is "dma-coherent"; sometimes you might need to
   force a consistent memory access ordering by using memory barriers.  It's
   not using a streaming DMA mapping, so it's good for small transfers on
   systems where the I/O would otherwise thrash an IOMMU mapping.  (See
-  Documentation/DMA-mapping.txt for definitions of "coherent" and "streaming"
-  DMA mappings.)
+  Documentation/PCI/PCI-DMA-mapping.txt for definitions of "coherent" and
+  "streaming" DMA mappings.)
 
   Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
   space-efficient.
@@ -93,7 +88,7 @@ WORKING WITH EXISTING BUFFERS
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  However, most buffers passed to your
 driver can safely be used with such DMA mapping.  (See the first section
-of DMA-mapping.txt, titled "What memory is DMA-able?")
+of Documentation/PCI/PCI-DMA-mapping.txt, titled "What memory is DMA-able?")
 
 - When you're using scatterlists, you can map everything at once.  On some
   systems, this kicks in an IOMMU and turns the scatterlists into single
@@ -129,8 +124,8 @@ of DMA-mapping.txt, titled "What memory is DMA-able?")
        void usb_buffer_unmap (struct urb *urb);
 
   The calls manage urb->transfer_dma for you, and set URB_NO_TRANSFER_DMA_MAP
-  so that usbcore won't map or unmap the buffer.  The same goes for
-  urb->setup_dma and URB_NO_SETUP_DMA_MAP for control requests.
+  so that usbcore won't map or unmap the buffer.  They cannot be used for
+  setup_packet buffers in control requests.
 
 Note that several of those interfaces are currently commented out, since
 they don't have current users.  See the source code.  Other than the dmasync