Merge kroah.com:/home/linux/linux/BK/bleeding-2.5

into kroah.com:/home/linux/linux/BK/gregkh-2.5

2 files changed, 127 insertions, 13 deletions

diff --git a/Documentation/usb/dma.txt b/Documentation/usb/dma.txt
new file mode 100644
index 000000000000..fae537186570
--- /dev/null
+++ b/Documentation/usb/dma.txt
@@ -0,0 +1,104 @@
+In Linux 2.5 kernels (and later), USB device drivers have additional control
+over how DMA may be used to perform I/O operations.  The APIs are detailed
+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.
+
+OR:  they can now be DMA-aware.
+
+- New calls enable DMA-aware drivers, letting them allocate dma buffers and
+  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 needed "setup_dma".) 
+
+- "usbcore" will map those DMA addresses, if a DMA-aware driver didn't do it
+  first and set URB_NO_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
+  drivers.  Never use dma_set_mask() on any USB interface or device; that
+  would potentially break all devices sharing that bus.
+
+
+ELIMINATING COPIES
+
+It's good to avoid making CPUs copy data needlessly.  The costs can add up,
+and effects like cache-trashing can impose subtle penalties.
+
+- When you're allocating a buffer for DMA purposes anyway, use the buffer
+  primitives.  Think of them as kmalloc and kfree that give you the right
+  kind of addresses to store in urb->transfer_buffer and urb->transfer_dma,
+  while guaranteeing that hidden copies through DMA "bounce" buffers won't
+  slow things down.  You'd also set URB_NO_DMA_MAP in urb->transfer_flags:
+
+	void *usb_buffer_alloc (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 *addr, dma_addr_t dma);
+
+  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 tie up an IOMMU mapping.
+
+  Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
+  space-efficient.
+
+- Devices on some EHCI controllers could handle DMA to/from high memory.
+  Driver probe() routines can notice this using a generic DMA call, then
+  tell higher level code (network, scsi, etc) about it like this:
+
+	if (dma_supported (&intf->dev, 0xffffffffffffffffULL))
+		net->features |= NETIF_F_HIGHDMA;
+
+  That can eliminate dma bounce buffering of requests that originate (or
+  terminate) in high memory, in cases where the buffers aren't allocated
+  with usb_buffer_alloc() but instead are dma-mapped.
+
+
+WORKING WITH EXISTING BUFFERS
+
+Existing buffers aren't usable for DMA without first being mapped into the
+DMA address space of the device.
+
+- 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
+  DMA transactions:
+
+	int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe,
+		struct scatterlist *sg, int nents);
+
+	void usb_buffer_dmasync_sg (struct usb_device *dev, unsigned pipe,
+		struct scatterlist *sg, int n_hw_ents);
+
+	void usb_buffer_unmap_sg (struct usb_device *dev, unsigned pipe,
+		struct scatterlist *sg, int n_hw_ents);
+
+  It's probably easier to use the new usb_sg_*() calls, which do the DMA
+  mapping and apply other tweaks to make scatterlist i/o be fast.
+
+- Some drivers may prefer to work with the model that they're mapping large
+  buffers, synchronizing their safe re-use.  (If there's no re-use, then let
+  usbcore do the map/unmap.)  Large periodic transfers make good examples
+  here, since it's cheaper to just synchronize the buffer than to unmap it
+  each time an urb completes and then re-map it on during resubmission.
+
+  These calls all work with initialized urbs:  urb->dev, urb->pipe,
+  urb->transfer_buffer, and urb->transfer_buffer_length must all be
+  valid when these calls are used:
+
+	struct urb *usb_buffer_map (struct urb *urb);
+
+	void usb_buffer_dmasync (struct urb *urb);
+
+	void usb_buffer_unmap (struct urb *urb);
+
+  The calls manage urb->transfer_dma for you, and set URB_NO_DMA_MAP so that
+  usbcore won't map or unmap the buffer.
+
diff --git a/Documentation/usb/usb-serial.txt b/Documentation/usb/usb-serial.txt
index 7e6150c50088..82d73ba58392 100644
--- a/Documentation/usb/usb-serial.txt
+++ b/Documentation/usb/usb-serial.txt
@@ -91,27 +91,27 @@ HandSpring Visor, Palm USB, and Clié USB driver
   Kroah-Hartman at greg@kroah.com
 
 
-Compaq iPAQ, HP Jornada and Casio EM500 driver
+PocketPC PDA Driver
 
-  This driver can be used to connect to Compaq iPAQ, HP Jornada and Casio EM500
-  PDAs running Windows CE 3.0 or PocketPC 2002 using a USB cable/cradle.
-  It's very likely that every device supported by ActiveSync USB works with this
-  driver. The driver supports the Compaq iPAQ, Jornada 548/568 and the Casio
-  EM500 out of the box. For others, please use module parameters to specify
-  the product and vendor id. e.g. modprobe ipaq vendor=0x3f0 product=0x1125
+  This driver can be used to connect to Compaq iPAQ, HP Jornada, Casio EM500
+  and other PDAs running Windows CE 3.0 or PocketPC 2002 using a USB
+  cable/cradle.
+  Most devices supported by ActiveSync are supported out of the box.
+  For others, please use module parameters to specify the product and vendor
+  id. e.g. modprobe ipaq vendor=0x3f0 product=0x1125
 
   The driver presents a serial interface (usually on /dev/ttyUSB0) over
-  which one may run ppp and establish a TCP/IP link to the iPAQ. Once this
+  which one may run ppp and establish a TCP/IP link to the PDA. Once this
   is done, you can transfer files, backup, download email etc. The most
-  significant advantage of using USB is speed - you can get 73 to 113
-  kbytes/sec for download/upload to the iPAQ.
+  significant advantage of using USB is speed - I can get 73 to 113
+  kbytes/sec for download/upload to my iPAQ.
 
   This driver is only one of a set of components required to utilize
   the USB connection. Please visit http://synce.sourceforge.net which
   contains the necessary packages and a simple step-by-step howto.
 
   Once connected, you can use Win CE programs like ftpView, Pocket Outlook
-  from the iPAQ and xcerdisp, synce utilities from the Linux side.
+  from the PDA and xcerdisp, synce utilities from the Linux side.
 
   To use Pocket IE, follow the instructions given at
   http://www.tekguru.co.uk/EM500/usbtonet.htm to achieve the same thing
@@ -126,8 +126,18 @@ Compaq iPAQ, HP Jornada and Casio EM500 driver
 
   If it doesn't work for some reason, load both the usbserial and ipaq module
   with the module parameter "debug" set to 1 and examine the system log.
-  You can also try soft-resetting your iPAQ before attempting a connection.
-
+  You can also try soft-resetting your PDA before attempting a connection.
+
+  Other functionality may be possible depending on your PDA. According to
+  Wes Cilldhaire <billybobjoehenrybob@hotmail.com>, with the Toshiba E570,
+  ...if you boot into the bootloader (hold down the power when hitting the
+  reset button, continuing to hold onto the power until the bootloader screen
+  is displayed), then put it in the cradle with the ipaq driver loaded, open
+  a terminal on /dev/ttyUSB0, it gives you a "USB Reflash" terminal, which can
+  be used to flash the ROM, as well as the microP code..  so much for needing
+  Toshiba's $350 serial cable for flashing!! :D
+  NOTE: This has NOT been tested. Use at your own risk.
+ 
   For any questions or problems with the driver, please contact Ganesh
   Varadarajan <ganesh@veritas.com>