Re: [PATCH 13/82] media: usbtv: core: make use of new usb_endpoint_maxp_mult()

[Mauro Carvalho Chehab]

Em Mon, 31 Oct 2016 12:48:05 +0200
Felipe Balbi  escreveu:

> We have introduced a helper to calculate multiplier
> value from wMaxPacketSize. Start using it.

Good idea! Btw, we have something similar at em28xx, stk1160-core.c and
tm6000 drivers. On them, we have this:
/* high bandwidth multiplier, as encoded in highspeed endpoint 
descriptors */
#define hb_mult(wMaxPacketSize) (1 + (((wMaxPacketSize) >> 11) & 0x03))

PLease add the same changes for the above files on this patch.

Btw, are you planning to send this patch via USB tree or via the
media one? If you want to send via USB, after this change,
feel free to add my ack:

    Acked-by: Mauro Carvalho Chehab 


> 
> Cc: Mauro Carvalho Chehab 
> Cc: 
> Signed-off-by: Felipe Balbi 
> ---
>  drivers/media/usb/usbtv/usbtv-core.c | 7 +--
>  1 file changed, 5 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/media/usb/usbtv/usbtv-core.c 
> b/drivers/media/usb/usbtv/usbtv-core.c
> index dc76fd41e00f..ceb953be0770 100644
> --- a/drivers/media/usb/usbtv/usbtv-core.c
> +++ b/drivers/media/usb/usbtv/usbtv-core.c
> @@ -71,6 +71,7 @@ static int usbtv_probe(struct usb_interface *intf,
>   int size;
>   struct device *dev = &intf->dev;
>   struct usbtv *usbtv;
> + struct usb_host_endpoint *ep;
>  
>   /* Checks that the device is what we think it is. */
>   if (intf->num_altsetting != 2)
> @@ -78,10 +79,12 @@ static int usbtv_probe(struct usb_interface *intf,
>   if (intf->altsetting[1].desc.bNumEndpoints != 4)
>   return -ENODEV;
>  
> + ep = &intf->altsetting[1].endpoint[0];
> +
>   /* Packet size is split into 11 bits of base size and count of
>* extra multiplies of it.*/
> - size = usb_endpoint_maxp(&intf->altsetting[1].endpoint[0].desc);
> - size = (size & 0x07ff) * (((size & 0x1800) >> 11) + 1);
> + size = usb_endpoint_maxp(&ep->desc);
> + size = (size & 0x07ff) * usb_endpoint_maxp_mult(&ep->desc);
>  
>   /* Device structure */
>   usbtv = kzalloc(sizeof(struct usbtv), GFP_KERNEL);


Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] USB: change bInterval default to 10 ms

[Mauro Carvalho Chehab]

Em Fri, 16 Sep 2016 10:24:26 -0400 (EDT)
Alan Stern  escreveu:

> Some full-speed mceusb infrared transceivers contain invalid endpoint
> descriptors for their interrupt endpoints, with bInterval set to 0.
> In the past they have worked out okay with the mceusb driver, because
> the driver sets the bInterval field in the descriptor to 1,
> overwriting whatever value may have been there before.  However, this
> approach was never sanctioned by the USB core, and in fact it does not
> work with xHCI controllers, because they use the bInterval value that
> was present when the configuration was installed.
> 
> Currently usbcore uses 32 ms as the default interval if the value in
> the endpoint descriptor is invalid.  It turns out that these IR
> transceivers don't work properly unless the interval is set to 10 ms
> or below.  To work around this mceusb problem, this patch changes the
> endpoint-descriptor parsing routine, making the default interval value
> be 10 ms rather than 32 ms.
> 
> Signed-off-by: Alan Stern 
> Tested-by: Wade Berrier 
> CC: 

Acked-by: Mauro Carvalho Chehab 

> 
> ---
> 
> 
> [as1812]
> 
> 
>  drivers/usb/core/config.c |   28 +---
>  1 file changed, 17 insertions(+), 11 deletions(-)
> 
> Index: usb-4.x/drivers/usb/core/config.c
> ===
> --- usb-4.x.orig/drivers/usb/core/config.c
> +++ usb-4.x/drivers/usb/core/config.c
> @@ -240,8 +240,10 @@ static int usb_parse_endpoint(struct dev
>   memcpy(&endpoint->desc, d, n);
>   INIT_LIST_HEAD(&endpoint->urb_list);
>  
> - /* Fix up bInterval values outside the legal range. Use 32 ms if no
> -  * proper value can be guessed. */
> + /*
> +  * Fix up bInterval values outside the legal range.
> +  * Use 10 or 8 ms if no proper value can be guessed.
> +  */
>   i = 0;  /* i = min, j = max, n = default */
>   j = 255;
>   if (usb_endpoint_xfer_int(d)) {
> @@ -250,13 +252,15 @@ static int usb_parse_endpoint(struct dev
>   case USB_SPEED_SUPER_PLUS:
>   case USB_SPEED_SUPER:
>   case USB_SPEED_HIGH:
> - /* Many device manufacturers are using full-speed
> + /*
> +  * Many device manufacturers are using full-speed
>* bInterval values in high-speed interrupt endpoint
> -  * descriptors. Try to fix those and fall back to a
> -  * 32 ms default value otherwise. */
> +  * descriptors. Try to fix those and fall back to an
> +  * 8-ms default value otherwise.
> +  */
>   n = fls(d->bInterval*8);
>   if (n == 0)
> - n = 9;  /* 32 ms = 2^(9-1) uframes */
> + n = 7;  /* 8 ms = 2^(7-1) uframes */
>   j = 16;
>  
>   /*
> @@ -271,10 +275,12 @@ static int usb_parse_endpoint(struct dev
>   }
>   break;
>   default:/* USB_SPEED_FULL or _LOW */
> - /* For low-speed, 10 ms is the official minimum.
> + /*
> +  * For low-speed, 10 ms is the official minimum.
>* But some "overclocked" devices might want faster
> -  * polling so we'll allow it. */
> - n = 32;
> +  * polling so we'll allow it.
> +  */
> + n = 10;
>   break;
>   }
>   } else if (usb_endpoint_xfer_isoc(d)) {
> @@ -282,10 +288,10 @@ static int usb_parse_endpoint(struct dev
>   j = 16;
>   switch (to_usb_device(ddev)->speed) {
>   case USB_SPEED_HIGH:
> - n = 9;  /* 32 ms = 2^(9-1) uframes */
> + n = 7;  /* 8 ms = 2^(7-1) uframes */
>   break;
>   default:/* USB_SPEED_FULL */
> - n = 6;  /* 32 ms = 2^(6-1) frames */
> + n = 4;  /* 8 ms = 2^(4-1) frames */
>   break;
>   }
>   }
> 



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: mceusb xhci issue?

[Mauro Carvalho Chehab]

Em Fri, 16 Sep 2016 10:25:31 -0400 (EDT)
Alan Stern  escreveu:

> On Thu, 15 Sep 2016, Wade Berrier wrote:
> 
> > On Thu Sep 15 15:13, Alan Stern wrote:  
> > > On Sat, 10 Sep 2016, Wade Berrier wrote:
> > >   
> > > > On Thu Aug 11 16:18, Alan Stern wrote:  
> > > > > I never received any replies to this message.  Should the patch I 
> > > > > suggested be merged?
> > > > >  
> > > > 
> > > > Hello,
> > > > 
> > > > I applied this updated patch to the fedora23 4.7.2 kernel and the mceusb
> > > > transceiver works as expected.  
> > > 
> > > Thank you for testing.  Can you provide the "lsusb -v" output for the
> > > troublesome IR transceiver?
> > >   
> > 
> > Here's the output:
> > 
> > Bus 001 Device 006: ID 1784:0006 TopSeed Technology Corp. eHome Infrared 
> > Transceiver
> > Device Descriptor:
> >   bLength18
> >   bDescriptorType 1
> >   bcdUSB   2.00
> >   bDeviceClass0 
> >   bDeviceSubClass 0 
> >   bDeviceProtocol 0 
> >   bMaxPacketSize0 8
> >   idVendor   0x1784 TopSeed Technology Corp.
> >   idProduct  0x0006 eHome Infrared Transceiver
> >   bcdDevice1.02
> >   iManufacturer   1 TopSeed Technology Corp.
> >   iProduct2 eHome Infrared Transceiver
> >   iSerial 3 TS004RrP
> >   bNumConfigurations  1
> >   Configuration Descriptor:
> > bLength 9
> > bDescriptorType 2
> > wTotalLength   32
> > bNumInterfaces  1
> > bConfigurationValue 1
> > iConfiguration  0 
> > bmAttributes 0xa0
> >   (Bus Powered)
> >   Remote Wakeup
> > MaxPower  100mA
> > Interface Descriptor:
> >   bLength 9
> >   bDescriptorType 4
> >   bInterfaceNumber0
> >   bAlternateSetting   0
> >   bNumEndpoints   2
> >   bInterfaceClass   255 Vendor Specific Class
> >   bInterfaceSubClass255 Vendor Specific Subclass
> >   bInterfaceProtocol255 Vendor Specific Protocol
> >   iInterface  0 
> >   Endpoint Descriptor:
> > bLength 7
> > bDescriptorType 5
> > bEndpointAddress 0x01  EP 1 OUT
> > bmAttributes3
> >   Transfer TypeInterrupt
> >   Synch Type   None
> >   Usage Type   Data
> > wMaxPacketSize 0x0020  1x 32 bytes
> > bInterval   0  
> 
> And there's the problem.  0 is an invalid bInterval value for an 
> Interrupt endpoint.

Unfortunately, it is a know issue that some mceusb drivers have the
bInterval set to zero.

> > Device Status: 0x0001
> >   Self Powered
> > 
> > Wade  
> 
> Thank you.  The patch has been submitted.

Thanks!

Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 50/57] [media] zr364xx: don't break long lines

[Mauro Carvalho Chehab]

Due to the 80-cols checkpatch warnings, several strings
were broken into multiple lines. This is not considered
a good practice anymore, as it makes harder to grep for
strings at the source code. So, join those continuation
lines.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/usb/zr364xx/zr364xx.c | 6 ++
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/drivers/media/usb/zr364xx/zr364xx.c 
b/drivers/media/usb/zr364xx/zr364xx.c
index cc128db85723..3950708cbb32 100644
--- a/drivers/media/usb/zr364xx/zr364xx.c
+++ b/drivers/media/usb/zr364xx/zr364xx.c
@@ -633,8 +633,7 @@ static int zr364xx_read_video_callback(struct 
zr364xx_camera *cam,
} else {
if (frm->cur_size + purb->actual_length > MAX_FRAME_SIZE) {
dev_info(&cam->udev->dev,
-"%s: buffer (%d bytes) too small to hold "
-"frame data. Discarding frame data.\n",
+"%s: buffer (%d bytes) too small to hold frame 
data. Discarding frame data.\n",
 __func__, MAX_FRAME_SIZE);
} else {
pdest += frm->cur_size;
@@ -1373,8 +1372,7 @@ static int zr364xx_board_init(struct zr364xx_camera *cam)
&cam->buffer.frame[i], i,
cam->buffer.frame[i].lpvbits);
if (cam->buffer.frame[i].lpvbits == NULL) {
-   printk(KERN_INFO KBUILD_MODNAME ": out of memory. "
-  "Using less frames\n");
+   printk(KERN_INFO KBUILD_MODNAME ": out of memory. Using 
less frames\n");
break;
}
}
-- 
2.7.4


--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 49/58] zr364xx: don't break long lines

[Mauro Carvalho Chehab]

Due to the 80-cols restrictions, and latter due to checkpatch
warnings, several strings were broken into multiple lines. This
is not considered a good practice anymore, as it makes harder
to grep for strings at the source code.

As we're right now fixing other drivers due to KERN_CONT, we need
to be able to identify what printk strings don't end with a "\n".
It is a way easier to detect those if we don't break long lines.

So, join those continuation lines.

The patch was generated via the script below, and manually
adjusted if needed.


use Text::Tabs;
while (<>) {
if ($next ne "") {
$c=$_;
if ($c =~ /^\s+\"(.*)/) {
$c2=$1;
$next =~ s/\"\n$//;
$n = expand($next);
$funpos = index($n, '(');
$pos = index($c2, '",');
if ($funpos && $pos > 0) {
$s1 = substr $c2, 0, $pos + 2;
$s2 = ' ' x ($funpos + 1) . substr $c2, $pos + 
2;
$s2 =~ s/^\s+//;

$s2 = ' ' x ($funpos + 1) . $s2 if ($s2 ne "");

print unexpand("$next$s1\n");
print unexpand("$s2\n") if ($s2 ne "");
} else {
print "$next$c2\n";
}
$next="";
next;
} else {
print $next;
}
$next="";
} else {
if (m/\"$/) {
if (!m/\\n\"$/) {
    $next=$_;
next;
}
}
}
print $_;
}


Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/media/usb/zr364xx/zr364xx.c | 6 ++
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/drivers/media/usb/zr364xx/zr364xx.c 
b/drivers/media/usb/zr364xx/zr364xx.c
index cc128db85723..3950708cbb32 100644
--- a/drivers/media/usb/zr364xx/zr364xx.c
+++ b/drivers/media/usb/zr364xx/zr364xx.c
@@ -633,8 +633,7 @@ static int zr364xx_read_video_callback(struct 
zr364xx_camera *cam,
} else {
if (frm->cur_size + purb->actual_length > MAX_FRAME_SIZE) {
dev_info(&cam->udev->dev,
-"%s: buffer (%d bytes) too small to hold "
-"frame data. Discarding frame data.\n",
+"%s: buffer (%d bytes) too small to hold frame 
data. Discarding frame data.\n",
 __func__, MAX_FRAME_SIZE);
} else {
pdest += frm->cur_size;
@@ -1373,8 +1372,7 @@ static int zr364xx_board_init(struct zr364xx_camera *cam)
&cam->buffer.frame[i], i,
cam->buffer.frame[i].lpvbits);
if (cam->buffer.frame[i].lpvbits == NULL) {
-   printk(KERN_INFO KBUILD_MODNAME ": out of memory. "
-  "Using less frames\n");
+   printk(KERN_INFO KBUILD_MODNAME ": out of memory. Using 
less frames\n");
break;
}
}
-- 
2.7.4


--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: mceusb xhci issue?

[Mauro Carvalho Chehab]

C/C linux-usb Mailing list:


Em Wed, 18 May 2016 08:52:28 -0600
Wade Berrier  escreveu:

> On May 14 20:29, Wade Berrier wrote:
> > On Wed Apr 27 21:07, Sean Young wrote:  
> > > On Mon, Apr 25, 2016 at 09:16:51PM -0600, Wade Berrier wrote:  
> > > > On Apr 25 18:15, Sean Young wrote:  
> > > > > On Sun, Apr 24, 2016 at 10:06:33PM -0600, Wade Berrier wrote:  
> > > > > > Hello,
> > > > > > 
> > > > > > I have a mceusb compatible transceiver that only seems to work with
> > > > > > certain computers.  I'm testing this on centos7 (3.10.0) and 
> > > > > > fedora23
> > > > > > (4.4.7).
> > > > > > 
> > > > > > The only difference I can see is that the working computer shows
> > > > > > "using uhci_hcd" and the non working shows "using xhci_hcd".
> > > > > > 
> > > > > > Here's the dmesg output of the non-working version:
> > > > > > 
> > > > > > -
> > > > > > 
> > > > > > [  217.951079] usb 1-5: new full-speed USB device number 10 using 
> > > > > > xhci_hcd
> > > > > > [  218.104087] usb 1-5: device descriptor read/64, error -71
> > > > > > [  218.371010] usb 1-5: config 1 interface 0 altsetting 0 endpoint 
> > > > > > 0x1 has an invalid bInterval 0, changing to 32
> > > > > > [  218.371019] usb 1-5: config 1 interface 0 altsetting 0 endpoint 
> > > > > > 0x81 has an invalid bInterval 0, changing to 32  
> > > > > 
> > > > > That's odd. Can you post a "lsusb -vvv" of the device please?
> > > > >   
> > > > 
> > > > Sure.
> > > > 
> > > > ---
> > > > 
> > > > Bus 002 Device 009: ID 1784:0006 TopSeed Technology Corp. eHome 
> > > > Infrared Transceiver
> > > > Device Descriptor:
> > > >   bLength18
> > > >   bDescriptorType 1
> > > >   bcdUSB   2.00
> > > >   bDeviceClass0 
> > > >   bDeviceSubClass 0 
> > > >   bDeviceProtocol 0 
> > > >   bMaxPacketSize0 8
> > > >   idVendor   0x1784 TopSeed Technology Corp.
> > > >   idProduct  0x0006 eHome Infrared Transceiver
> > > >   bcdDevice1.02
> > > >   iManufacturer   1 TopSeed Technology Corp.
> > > >   iProduct2 eHome Infrared Transceiver
> > > >   iSerial 3 TS004RrP
> > > >   bNumConfigurations  1
> > > >   Configuration Descriptor:
> > > > bLength 9
> > > > bDescriptorType 2
> > > > wTotalLength   32
> > > > bNumInterfaces  1
> > > > bConfigurationValue 1
> > > > iConfiguration  0 
> > > > bmAttributes 0xa0
> > > >   (Bus Powered)
> > > >   Remote Wakeup
> > > > MaxPower  100mA
> > > > Interface Descriptor:
> > > >   bLength 9
> > > >   bDescriptorType 4
> > > >   bInterfaceNumber0
> > > >   bAlternateSetting   0
> > > >   bNumEndpoints   2
> > > >   bInterfaceClass   255 Vendor Specific Class
> > > >   bInterfaceSubClass255 Vendor Specific Subclass
> > > >   bInterfaceProtocol255 Vendor Specific Protocol
> > > >   iInterface  0 
> > > >   Endpoint Descriptor:
> > > > bLength 7
> > > > bDescriptorType 5
> > > > bEndpointAddress 0x01  EP 1 OUT
> > > > bmAttributes3
> > > >   Transfer TypeInterrupt
> > > >   Synch Type   None
> > > >   Usage Type   Data
> > > > wMaxPacketSize 0x0020  1x 32 bytes
> > > > bInterval   0  
> > > 
> > > That's wrong indeed. It might be interesting to see if there is anything
> > > in the xhci debug messages with (in Fedora 23):
> > > 
> > > echo "file xhci*.c +p" > /sys/kernel/debug/dynamic_debug/control
> > > echo "file mceusb.c +p" > /sys/kernel/debug/dynamic_debug/control
> > > 
> > > And then plug in the receiver, and try to send IR to it with a remote.
> > > You should have quite a few kernel messages in the journal.  
> > 
> > Here's the output after enabling the debug options, plugging in the
> > receiver, running lircd, and pressing some remote buttons:
> >  
> 
> [snip]
> 
> > 
> > I'm not sure what to look for... ?
> >   
> > >   
> > > >   Endpoint Descriptor:
> > > > bLength 7
> > > > bDescriptorType 5
> > > > bEndpointAddress 0x81  EP 1 IN
> > > > bmAttributes3
> > > >   Transfer TypeInterrupt
> > > >   Synch Type   None
> > > >   Usage Type   Data
> > > > wMaxPacketSize 0x0020  1x 32 bytes
> > > > bInterval   0
> > > > Device Status: 0x0001
> > > >   Self Powered
> > > > 
> > > > ---
> > > > 
> > > > Also, here's a link to a response on the lirc list:
> > > > 
> > > > https://sourceforge.net/p/lirc/mailman/message/35039126/  
> > > 
> > > That seems suggest that mode2 works but 

[PATCH RFC] dwc2: Don't assume URB transfer_buffer are dword-aligned

[Mauro Carvalho Chehab]

The dwc2 hardware doesn't like to do DMA transfers without
aligning data in DWORD. The driver also assumes that, even
when there's no DMA, at dwc2_read_packet().

That cause buffer overflows, preventing some drivers to work.

In the specific case of uvc_driver, it uses an array where
it caches the content of video controls, passing it to the
USB stack via usb_control_msg(). Typical controls use 1 or 2
bytes. The net result is that other values of the buffer
gets overriden when this function is called.

Fix it by changing the logic at dwc2_alloc_dma_aligned_buffer()
to ensure that the buffer used for DMA will be DWORD-aligned.

Detected with uvc driver.

Signed-off-by: Mauro Carvalho Chehab 
---

On Raspberry Pi 3, I was unable to test  dwc2_read_packet(), as this was
never called there. However, the change at the second hunk, e. g. at
dwc2_alloc_dma_aligned_buffer() made UVC to answer the same way
as on x86, while reading the values for the device controls.

 drivers/usb/dwc2/hcd.c | 29 ++---
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/drivers/usb/dwc2/hcd.c b/drivers/usb/dwc2/hcd.c
index a73722e27d07..c53d3c24d5b5 100644
--- a/drivers/usb/dwc2/hcd.c
+++ b/drivers/usb/dwc2/hcd.c
@@ -572,20 +572,26 @@ u32 dwc2_calc_frame_interval(struct dwc2_hsotg *hsotg)
 void dwc2_read_packet(struct dwc2_hsotg *hsotg, u8 *dest, u16 bytes)
 {
u32 __iomem *fifo = hsotg->regs + HCFIFO(0);
-   u32 *data_buf = (u32 *)dest;
-   int word_count = (bytes + 3) / 4;
-   int i;
-
-   /*
-* Todo: Account for the case where dest is not dword aligned. This
-* requires reading data from the FIFO into a u32 temp buffer, then
-* moving it into the data buffer.
-*/
+   u32 *data_buf = (u32 *)dest, tmp;
+   int word_count = bytes >> 2;
+   int i, j;
 
dev_vdbg(hsotg->dev, "%s(%p,%p,%d)\n", __func__, hsotg, dest, bytes);
 
for (i = 0; i < word_count; i++, data_buf++)
*data_buf = dwc2_readl(fifo);
+
+   /* Handle the case where the buffer is not dword-aligned */
+   if (bytes & 0x3) {
+   u8 *buf = (u8 *)data_buf;
+
+   tmp = dwc2_readl(fifo);
+
+   i <<= 2;
+   for (j = 0; i < bytes; j++, i++, dest++)
+   *buf = tmp >> (8 * j);
+   }
+
 }
 
 /**
@@ -2594,8 +2600,9 @@ static int dwc2_alloc_dma_aligned_buffer(struct urb *urb, 
gfp_t mem_flags)
size_t kmalloc_size;
 
if (urb->num_sgs || urb->sg ||
-   urb->transfer_buffer_length == 0 ||
-   !((uintptr_t)urb->transfer_buffer & (DWC2_USB_DMA_ALIGN - 1)))
+   urb->transfer_buffer_length == 0 || (
+   !((uintptr_t)urb->transfer_buffer & (DWC2_USB_DMA_ALIGN - 1)) &&
+   !((uintptr_t)(urb->transfer_buffer + urb->transfer_buffer_length) & 
(DWC2_USB_DMA_ALIGN - 1
return 0;
 
/* Allocate a buffer with enough padding for alignment */
-- 
2.9.3


--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH RFC] dwc2: Don't assume URB transfer_buffer are dword-aligned

[Mauro Carvalho Chehab]

Hi Greg,

(c/c media ML)

Em Fri, 17 Mar 2017 10:24:15 +0900
Greg Kroah-Hartman  escreveu:

> On Thu, Mar 16, 2017 at 09:08:40PM -0300, Mauro Carvalho Chehab wrote:
> > The dwc2 hardware doesn't like to do DMA transfers without
> > aligning data in DWORD. The driver also assumes that, even
> > when there's no DMA, at dwc2_read_packet().
> > 
> > That cause buffer overflows, preventing some drivers to work.  
> 
> Why aren't the drivers being fixed?  This is a well-known (hopefully)
> restriction on USB data buffers, can't the uvc_driver be fixed?

I never knew that adding padding data is required on the
transfer buffer. Yet, almost all drivers at media just do
something like:

data = kmalloc(size, GFP_KERNEL);
...
usb_control_msg(dev->udev, pipe, req, reqtype, val, idx,
data, size, timeout);

So, if kmalloc add pad bytes to the data, it should work, even
if size is not dword-aligned.

The UVC driver does something different, though. For video controls,
it gets value from 7 different USB registers and store on a cache,
with this code:

#define UVC_CTRL_DATA_CURRENT   0
#define UVC_CTRL_DATA_BACKUP1
#define UVC_CTRL_DATA_MIN   2
#define UVC_CTRL_DATA_MAX   3
#define UVC_CTRL_DATA_RES   4
#define UVC_CTRL_DATA_DEF   5
#define UVC_CTRL_DATA_LAST  6

The size of each control is stored on a struct, at
ctrl->info.size, and vary from control to control. On the webcam I'm
currently working, there are controls with 1 byte, 2 bytes, 8 bytes
and 26 bytes.

Instead of allocating 7 buffers, to store each value, it uses
just one kmalloc for the entire cache:

ctrl->uvc_data = kzalloc(ctrl->info.size * UVC_CTRL_DATA_LAST + 1,
 GFP_KERNEL);

And it uses a function that returns a position inside the 
register cache buffer:

static inline __u8 *uvc_ctrl_data(struct uvc_control *ctrl, int id)
{
return ctrl->uvc_data + id * ctrl->info.size;
}

This is not packed nor dword-aligned.

It shouldn't be hard to change its logic to ensure that the
cached data will be aligned with the architecture's default
alignment, by changing the code to:

for (i = 0; i < UVC_CTRL_DATA_LAST; i++)
ctrl->uvc_data[i] = kzalloc(ctrl->info.size, GFP_KERNEL);

...

static inline __u8 *uvc_ctrl_data(struct uvc_control *ctrl, int id)
{
return ctrl->uvc_data[id];
}

With should solve this issue and avoid double-buffering. I think
we should do it anyway.


Yet, there are already *a lot* of URB traffic done using non-aligned
transfer buffers on RPi3. I was able to add dump_stack() only after
adding a rate-limit logic there. I applied the enclosed patch without
having any external USB devices connected to RPi3 and without this 
RFC patch applied. I'm using network via RPi3 Ethernet port.

That's what I got:

[   43.083288] dwc2_alloc_dma_aligned_buffer: creating a DMA-aligned buffer 
with size 145:
[   43.083301] CPU: 1 PID: 791 Comm: sshd Tainted: G C  4.11.0-rc1+ 
#52
[   43.083305] Hardware name: Generic DT based system
[   43.083329] [] (unwind_backtrace) from [] 
(show_stack+0x10/0x14)
[   43.083345] [] (show_stack) from [] 
(dump_stack+0x88/0x9c)
[   43.083362] [] (dump_stack) from [] 
(dwc2_map_urb_for_dma+0x14c/0x154)
[   43.083378] [] (dwc2_map_urb_for_dma) from [] 
(usb_hcd_submit_urb+0x94/0xa08)
[   43.083396] [] (usb_hcd_submit_urb) from [] 
(usbnet_start_xmit+0x228/0x6e0)
[   43.083416] [] (usbnet_start_xmit) from [] 
(dev_hard_start_xmit+0x88/0x110)
[   43.083434] [] (dev_hard_start_xmit) from [] 
(sch_direct_xmit+0xe0/0x1b4)
[   43.083450] [] (sch_direct_xmit) from [] 
(__dev_queue_xmit+0x1ec/0x568)
[   43.083466] [] (__dev_queue_xmit) from [] 
(ip6_finish_output2+0x1e0/0x5a0)
[   43.083480] [] (ip6_finish_output2) from [] 
(ip6_xmit+0x2a8/0x5dc)
[   43.083494] [] (ip6_xmit) from [] 
(inet6_csk_xmit+0x78/0xac)
[   43.083513] [] (inet6_csk_xmit) from [] 
(tcp_transmit_skb+0x44c/0x8fc)
[   43.083529] [] (tcp_transmit_skb) from [] 
(tcp_write_xmit+0x16c/0xffc)
[   43.083545] [] (tcp_write_xmit) from [] 
(__tcp_push_pending_frames+0x34/0xe8)
[   43.083560] [] (__tcp_push_pending_frames) from [] 
(tcp_sendmsg+0x890/0xbd4)
[   43.083577] [] (tcp_sendmsg) from [] 
(sock_sendmsg+0x14/0x24)
[   43.083592] [] (sock_sendmsg) from [] 
(sock_write_iter+0x80/0xb0)
[   43.083608] [] (sock_write_iter) from [] 
(__vfs_write+0xbc/0x114)
[   43.083624] [] (__vfs_write) from [] 
(vfs_write+0xa4/0x168)
[   43.083639] [] (vfs_write) from [] (SyS_write+0x3c/0x90)
[   43.083655] [] (SyS_write) from [] 
(ret_fast_syscall+0x0/0x3c)
[   43.084178] dwc2_alloc_dma_aligned_buffer: creating a DMA-aligned buffer 
with size 18955:
[   43.084193] CPU: 0 PID: 0 Comm: swapper/0 Tainted: G C  
4.11.0-rc1+ #52
[   43.084198] Hard

Re: [PATCH RFC] dwc2: Don't assume URB transfer_buffer are dword-aligned

[Mauro Carvalho Chehab]

Em Fri, 17 Mar 2017 10:24:15 +0900
Greg Kroah-Hartman  escreveu:

> On Thu, Mar 16, 2017 at 09:08:40PM -0300, Mauro Carvalho Chehab wrote:
> > The dwc2 hardware doesn't like to do DMA transfers without
> > aligning data in DWORD. The driver also assumes that, even
> > when there's no DMA, at dwc2_read_packet().
> > 
> > That cause buffer overflows, preventing some drivers to work.  
> 
> Why aren't the drivers being fixed?  This is a well-known (hopefully)
> restriction on USB data buffers, can't the uvc_driver be fixed?

I talked to Laurent about on IRC. He told that he is willing to consider
that option, if the USB API explicitly states that all buffers must be
dword-aligned (and/or buffer sizes).

IMHO, he has a point: if this is a restriction of for usb transfer
buffers, it should be documented somewhere.

Yet, a quick check with:
$ git grep -i dword Documentation/usb/
$ git grep -i align Documentation/usb/

Didn't hit anything related to it. 

> > In the specific case of uvc_driver, it uses an array where
> > it caches the content of video controls, passing it to the
> > USB stack via usb_control_msg(). Typical controls use 1 or 2
> > bytes. The net result is that other values of the buffer
> > gets overriden when this function is called.  
> 
> Not good, it should be fixed, otherwise you are going to have to try to
> fix up all host controllers :(
> 
> thanks,
> 
> greg k-h



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH RFC] dwc2: Don't assume URB transfer_buffer are dword-aligned

[Mauro Carvalho Chehab]

Em Wed, 29 Mar 2017 11:57:22 +0200
Greg Kroah-Hartman  escreveu:

> On Tue, Mar 28, 2017 at 06:48:02AM -0300, Mauro Carvalho Chehab wrote:
> > Em Fri, 17 Mar 2017 10:24:15 +0900
> > Greg Kroah-Hartman  escreveu:
> >   
> > > On Thu, Mar 16, 2017 at 09:08:40PM -0300, Mauro Carvalho Chehab wrote:  
> > > > The dwc2 hardware doesn't like to do DMA transfers without
> > > > aligning data in DWORD. The driver also assumes that, even
> > > > when there's no DMA, at dwc2_read_packet().
> > > > 
> > > > That cause buffer overflows, preventing some drivers to work.
> > > 
> > > Why aren't the drivers being fixed?  This is a well-known (hopefully)
> > > restriction on USB data buffers, can't the uvc_driver be fixed?  
> > 
> > I talked to Laurent about on IRC. He told that he is willing to consider
> > that option, if the USB API explicitly states that all buffers must be
> > dword-aligned (and/or buffer sizes).
> > 
> > IMHO, he has a point: if this is a restriction of for usb transfer
> > buffers, it should be documented somewhere.
> > 
> > Yet, a quick check with:
> > $ git grep -i dword Documentation/usb/
> > $ git grep -i align Documentation/usb/
> > 
> > Didn't hit anything related to it.   
> 
> Hm, most of the USB documentation is in the kerneldoc in the USB code
> itself, and is built that way.  I'm pretty sure this is documented
> somewhere, but I can't seem to find it at the moment either :(
> 
> Care to write a patch for that?  :)

Sure. Btw, I noticed that not all USB documents were converted
yet to ReST, so I took the time to convert the core documents to ReST
too.

I kept the driver-specific documentation at Documentation/usb.
The final result is at:
http://www.infradead.org/~mchehab/kernel_docs/driver-api/usb/index.html

I'll be sending the documentation patches in a few.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 14/22] usb/persist.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/index.rst |  1 +
 .../persist.txt => driver-api/usb/persist.rst} | 22 +-
 2 files changed, 14 insertions(+), 9 deletions(-)
 rename Documentation/{usb/persist.txt => driver-api/usb/persist.rst} (94%)

diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 43f0a8b72b11..3f08cb5d5feb 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -12,6 +12,7 @@ Linux USB API
dma
power-management
hotplug
+   persist
error-codes
writing_usb_driver
writing_musb_glue_layer
diff --git a/Documentation/usb/persist.txt 
b/Documentation/driver-api/usb/persist.rst
similarity index 94%
rename from Documentation/usb/persist.txt
rename to Documentation/driver-api/usb/persist.rst
index 35d70eda9ad6..af02baf61f57 100644
--- a/Documentation/usb/persist.txt
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,11 +1,12 @@
-   USB device persistence during system suspend
+USB device persistence during system suspend
+
 
-  Alan Stern 
+Alan Stern 
+September 2, 2006 (Updated February 25, 2008)
 
-   September 2, 2006 (Updated February 25, 2008)
 
-
-   What is the problem?
+What is the problem?
+
 
 According to the USB specification, when a USB bus is suspended the
 bus must continue to supply suspend current (around 1-5 mA).  This
@@ -63,7 +64,8 @@ suspended -- but it will crash as soon as it wakes up, which 
isn't
 much better.)
 
 
-   What is the solution?
+What is the solution?
+=
 
 The kernel includes a feature called USB-persist.  It tries to work
 around these issues by allowing the core USB device data structures to
@@ -99,7 +101,7 @@ now a good and happy place.
 
 Note that the "USB-persist" feature will be applied only to those
 devices for which it is enabled.  You can enable the feature by doing
-(as root):
+(as root)::
 
echo 1 >/sys/bus/usb/devices/.../power/persist
 
@@ -110,7 +112,8 @@ doesn't even exist, so you only have to worry about setting 
it for
 devices where it really matters.
 
 
-   Is this the best solution?
+Is this the best solution?
+==
 
 Perhaps not.  Arguably, keeping track of mounted filesystems and
 memory mappings across device disconnects should be handled by a
@@ -130,7 +133,8 @@ just mass-storage devices.  It might turn out to be equally 
useful for
 other device types, such as network interfaces.
 
 
-   WARNING: USB-persist can be dangerous!!
+WARNING: USB-persist can be dangerous!!
+===
 
 When recovering an interrupted power session the kernel does its best
 to make sure the USB device hasn't been changed; that is, the same
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 07/22] usb/anchors.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../anchors.txt => driver-api/usb/anchors.rst} | 36 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 21 insertions(+), 16 deletions(-)
 rename Documentation/{usb/anchors.txt => driver-api/usb/anchors.rst} (75%)

diff --git a/Documentation/usb/anchors.txt 
b/Documentation/driver-api/usb/anchors.rst
similarity index 75%
rename from Documentation/usb/anchors.txt
rename to Documentation/driver-api/usb/anchors.rst
index fe6a99a32bbd..4b248e691bd6 100644
--- a/Documentation/usb/anchors.txt
+++ b/Documentation/driver-api/usb/anchors.rst
@@ -1,3 +1,6 @@
+USB Anchors
+~~~
+
 What is anchor?
 ===
 
@@ -13,7 +16,7 @@ Allocation and Initialisation
 =
 
 There's no API to allocate an anchor. It is simply declared
-as struct usb_anchor. init_usb_anchor() must be called to
+as struct usb_anchor. :c:func:`init_usb_anchor` must be called to
 initialise the data structure.
 
 Deallocation
@@ -26,52 +29,53 @@ Association and disassociation of URBs with anchors
 ===
 
 An association of URBs to an anchor is made by an explicit
-call to usb_anchor_urb(). The association is maintained until
+call to :c:func:`usb_anchor_urb`. The association is maintained until
 an URB is finished by (successful) completion. Thus disassociation
 is automatic. A function is provided to forcibly finish (kill)
 all URBs associated with an anchor.
-Furthermore, disassociation can be made with usb_unanchor_urb()
+Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb`
 
 Operations on multitudes of URBs
 
 
-usb_kill_anchored_urbs()
-
+:c:func:`usb_kill_anchored_urbs`
+
 
 This function kills all URBs associated with an anchor. The URBs
 are called in the reverse temporal order they were submitted.
 This way no data can be reordered.
 
-usb_unlink_anchored_urbs()
---
+:c:func:`usb_unlink_anchored_urbs`
+--
+
 
 This function unlinks all URBs associated with an anchor. The URBs
 are processed in the reverse temporal order they were submitted.
-This is similar to usb_kill_anchored_urbs(), but it will not sleep.
+This is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep.
 Therefore no guarantee is made that the URBs have been unlinked when
 the call returns. They may be unlinked later but will be unlinked in
 finite time.
 
-usb_scuttle_anchored_urbs()

+:c:func:`usb_scuttle_anchored_urbs`
+---
 
 All URBs of an anchor are unanchored en masse.
 
-usb_wait_anchor_empty_timeout()

+:c:func:`usb_wait_anchor_empty_timeout`
+---
 
 This function waits for all URBs associated with an anchor to finish
 or a timeout, whichever comes first. Its return value will tell you
 whether the timeout was reached.
 
-usb_anchor_empty()
---
+:c:func:`usb_anchor_empty`
+--
 
 Returns true if no URBs are associated with an anchor. Locking
 is the caller's responsibility.
 
-usb_get_from_anchor()
--
+:c:func:`usb_get_from_anchor`
+-
 
 Returns the oldest anchored URB of an anchor. The URB is unanchored
 and returned with a reference. As you may mix URBs to several
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index cf2fa2e8d236..5dfb04b2d730 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -6,6 +6,7 @@ Linux USB API
 
usb
gadget
+   anchors
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 01/22] driver-api/basics.rst: add device table header

[Mauro Carvalho Chehab]

The structs there at device table are used by other documentation
at the Kernel. So, add it to the driver API.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/basics.rst | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/driver-api/basics.rst 
b/Documentation/driver-api/basics.rst
index 935b9b8d456c..472e7a664d13 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -7,6 +7,12 @@ Driver Entry and Exit points
 .. kernel-doc:: include/linux/init.h
:internal:
 
+Driver device table
+---
+
+.. kernel-doc:: include/linux/mod_devicetable.h
+   :internal:
+
 Atomic and pointer manipulation
 ---
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Several host controllers, commonly found on ARM, like dwc2,
require buffers that are CPU-word aligned for they to work.

Failing to do that will cause random troubles at the caller
drivers, causing them to fail.

Document it.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/URB.rst | 18 ++
 drivers/usb/core/message.c   | 15 +++
 include/linux/usb.h  | 18 ++
 3 files changed, 51 insertions(+)

diff --git a/Documentation/driver-api/usb/URB.rst 
b/Documentation/driver-api/usb/URB.rst
index d9ea6a3996e7..b83b557e9891 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -274,6 +274,24 @@ If you specify your own start frame, make sure it's 
several frames in advance
 of the current frame.  You might want this model if you're synchronizing
 ISO data with some other event stream.
 
+.. note::
+
+   Several host drivers require that the ``transfer_buffer`` to be aligned
+   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
+   It is up to USB drivers should ensure that they'll only pass buffers
+   with such alignments.
+
+   Please also notice that, due to such restriction, the host driver
+   may also override PAD bytes at the end of the ``transfer_buffer``, up to the
+   size of the CPU word.
+
+   Please notice that ancillary routines that transfer URBs, like
+   usb_control_msg() also have such restriction.
+
+   Such word alignment condition is normally ensured if the buffer is
+   allocated with kmalloc(), but this may not be the case if the driver
+   allocates a bigger buffer and point to a random place inside it.
+
 
 How to start interrupt (INT) transfers?
 ===
diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 4c38ea41ae96..1662a4446475 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct usb_device 
*usb_dev,
  * make sure your disconnect() method can wait for it to complete. Since you
  * don't have a handle on the URB used, you can't cancel the request.
  *
+ * .. note::
+ *
+ *   Several host drivers require that the @data buffer to be aligned
+ *   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
+ *   It is up to USB drivers should ensure that they'll only pass buffers
+ *   with such alignments.
+ *
+ *   Please also notice that, due to such restriction, the host driver
+ *   may also override PAD bytes at the end of the @data buffer, up to the
+ *   size of the CPU word.
+ *
+ *   Such word alignment condition is normally ensured if the buffer is
+ *   allocated with kmalloc(), but this may not be the case if the driver
+ *   allocates a bigger buffer and point to a random place inside it.
+ *
  * Return: If successful, the number of bytes transferred. Otherwise, a 
negative
  * error number.
  */
diff --git a/include/linux/usb.h b/include/linux/usb.h
index 7e68259360de..8b5ad6624708 100644
--- a/include/linux/usb.h
+++ b/include/linux/usb.h
@@ -1373,6 +1373,24 @@ typedef void (*usb_complete_t)(struct urb *);
  * capable, assign NULL to it, so that usbmon knows not to use the value.
  * The setup_packet must always be set, so it cannot be located in highmem.
  *
+ * .. note::
+ *
+ *   Several host drivers require that the @transfer_buffer to be aligned
+ *   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
+ *   It is up to USB drivers should ensure that they'll only pass buffers
+ *   with such alignments.
+ *
+ *   Please also notice that, due to such restriction, the host driver
+ *   may also override PAD bytes at the end of the @transfer_buffer, up to the
+ *   size of the CPU word.
+ *
+ *   Please notice that ancillary routines that start URB transfers, like
+ *   usb_control_msg() also have such restriction.
+ *
+ *   Such word alignment condition is normally ensured if the buffer is
+ *   allocated with kmalloc(), but this may not be the case if the driver
+ *   allocates a bigger buffer and point to a random place inside it.
+ *
  * Initialization:
  *
  * All URBs submitted must initialize the dev, pipe, transfer_flags (may be
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 20/22] usb: gadget.h: be consistent at kernel doc macros

[Mauro Carvalho Chehab]

There's one value that use spaces instead of tabs to ident.
That causes the following warning:

./include/linux/usb/gadget.h:193: ERROR: Unexpected indentation.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/usb/gadget.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/usb/gadget.h b/include/linux/usb/gadget.h
index e4516e9ded0f..fbc22a39e7bc 100644
--- a/include/linux/usb/gadget.h
+++ b/include/linux/usb/gadget.h
@@ -188,7 +188,7 @@ struct usb_ep_caps {
  * @caps:The structure describing types and directions supported by endoint.
  * @maxpacket:The maximum packet size used on this endpoint.  The initial
  * value can sometimes be reduced (hardware allowing), according to
- *  the endpoint descriptor used to configure the endpoint.
+ * the endpoint descriptor used to configure the endpoint.
  * @maxpacket_limit:The maximum packet size value which can be handled by this
  * endpoint. It's set once by UDC driver when endpoint is initialized, and
  * should not be changed. Should not be confused with maxpacket.
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 12/22] error-codes.rst: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/error-codes.rst | 205 +++
 Documentation/driver-api/usb/index.rst   |   1 +
 Documentation/usb/error-codes.txt| 175 ---
 3 files changed, 206 insertions(+), 175 deletions(-)
 create mode 100644 Documentation/driver-api/usb/error-codes.rst
 delete mode 100644 Documentation/usb/error-codes.txt

diff --git a/Documentation/driver-api/usb/error-codes.rst 
b/Documentation/driver-api/usb/error-codes.rst
new file mode 100644
index ..715cc35b29b0
--- /dev/null
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -0,0 +1,205 @@
+USB Error codes
+~~~
+
+Revised: 2004-Oct-21
+
+This is the documentation of (hopefully) all possible error codes (and
+their interpretation) that can be returned from usbcore.
+
+Some of them are returned by the Host Controller Drivers (HCDs), which
+device drivers only see through usbcore.  As a rule, all the HCDs should
+behave the same except for transfer speed dependent behaviors and the
+way certain faults are reported.
+
+
+Error codes returned by :c:func:`usb_submit_urb`
+
+
+Non-USB-specific:
+
+
+=== ===
+0  URB submission went fine
+
+``-ENOMEM``no memory for allocation of internal structures
+=== ===
+
+USB-specific:
+
+===
===
+``-EBUSY`` The URB is already active.
+
+``-ENODEV``specified USB-device or bus doesn't exist
+
+``-ENOENT``specified interface or endpoint does not exist or
+   is not enabled
+
+``-ENXIO`` host controller driver does not support queuing of
+   this type of urb.  (treat as a host controller bug.)
+
+``-EINVAL``a) Invalid transfer type specified (or not supported)
+   b) Invalid or unsupported periodic transfer interval
+   c) ISO: attempted to change transfer interval
+   d) ISO: ``number_of_packets`` is < 0
+   e) various other cases
+
+``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the
+   frames the URB would be scheduled in have already
+   expired.
+
+``-EFBIG`` Host controller driver can't schedule that many ISO
+   frames.
+
+``-EPIPE`` The pipe type specified in the URB doesn't match the
+   endpoint's actual type.
+
+``-EMSGSIZE``  (a) endpoint maxpacket size is zero; it is not usable
+   in the current interface altsetting.
+   (b) ISO packet is larger than the endpoint maxpacket.
+   (c) requested data transfer length is invalid: negative
+   or too large for the host controller.
+
+``-ENOSPC``This request would overcommit the usb bandwidth reserved
+   for periodic transfers (interrupt, isochronous).
+
+``-ESHUTDOWN`` The device or host controller has been disabled due to
+   some problem that could not be worked around.
+
+``-EPERM`` Submission failed because ``urb->reject`` was set.
+
+``-EHOSTUNREACH``  URB was rejected because the device is suspended.
+
+``-ENOEXEC``   A control URB doesn't contain a Setup packet.
+===
===
+
+Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` 
(for ISO)
+===
+
+USB device drivers may only test urb status values in completion handlers.
+This is because otherwise there would be a race between HCDs updating
+these values on one CPU, and device drivers testing them on another CPU.
+
+A transfer's actual_length may be positive even when an error has been
+reported.  That's because transfers often involve several packets, so that
+one or more packets could finish before an error stops further endpoint I/O.
+
+For isochronous URBs, the urb status value is non-zero only if the URB is
+unlinked, the device is removed, the host controller is disabled, or the total
+transferred length is less than the requested length and the
+``URB_SHORT_NOT_OK`` flag is set.  Completion handlers for isochronous URBs
+should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,
+``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame de

[PATCH 06/22] writing_musb_glue_layer.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

This file is actually quite complex, and required several
manual handwork:

- add a title for the document;
- use the right tags for monospaced fonts;
- use c references where needed;
- adjust cross-reference to writing_usb_driver.rst
- hightlight cross-referenced lines.

With regards to C code snippet line highlights, the better would be
to use :linenos: for the C code snippets that are referenced by
the line number. However, at least with Sphinx 1.4.9, enabling
it cause the line number to be misaligned with the code,
making it even more confusing. So, instead, let's use
:emphasize-lines: tag to mark the lines that are referenced
at the text.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../driver-api/usb/writing_musb_glue_layer.rst | 251 ++---
 1 file changed, 120 insertions(+), 131 deletions(-)

diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst 
b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
index 2546a102394f..89333a69d4ba 100644
--- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst
+++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
@@ -1,3 +1,6 @@
+Writing MUSB Glue Layer
+~~~
+
 Introduction
 
 
@@ -15,10 +18,12 @@ design.
 As a self-taught exercise I have written an MUSB glue layer for the
 Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the
 kernel source tree. This layer can be found at
-drivers/usb/musb/jz4740.c. In this documentation I will walk through the
-basics of the jz4740.c glue layer, explaining the different pieces and
+``drivers/usb/musb/jz4740.c``. In this documentation I will walk through the
+basics of the ``jz4740.c`` glue layer, explaining the different pieces and
 what needs to be done in order to write your own device glue layer.
 
+.. _musb-basics:
+
 Linux MUSB Basics
 =
 
@@ -33,9 +38,7 @@ USB Device Drivers documentation (again, see Resources).
 
 Linux USB stack is a layered architecture in which the MUSB controller
 hardware sits at the lowest. The MUSB controller driver abstract the
-MUSB controller hardware to the Linux USB stack.
-
-::
+MUSB controller hardware to the Linux USB stack::
 
  
  |  | <--- drivers/usb/gadget
@@ -59,7 +62,6 @@ MUSB controller hardware to the Linux USB stack.
   |   MUSB Controller Hardware|
   -
 
-
 As outlined above, the glue layer is actually the platform specific code
 sitting in between the controller driver and the controller hardware.
 
@@ -72,9 +74,7 @@ about an embedded controller chip here, so no insertion or 
removal at
 run-time.
 
 All of this information is passed to the MUSB controller driver through
-a platform\_driver structure defined in the glue layer as:
-
-::
+a :c:type:`platform_driver` structure defined in the glue layer as::
 
 static struct platform_driver jz4740_driver = {
.probe  = jz4740_probe,
@@ -84,20 +84,17 @@ a platform\_driver structure defined in the glue layer as:
},
 };
 
-
 The probe and remove function pointers are called when a matching device
 is detected and, respectively, released. The name string describes the
 device supported by this glue layer. In the current case it matches a
-platform\_device structure declared in arch/mips/jz4740/platform.c. Note
+platform_device structure declared in ``arch/mips/jz4740/platform.c``. Note
 that we are not using device tree bindings here.
 
 In order to register itself to the controller driver, the glue layer
 goes through a few steps, basically allocating the controller hardware
 resources and initialising a couple of circuits. To do so, it needs to
 keep track of the information used throughout these steps. This is done
-by defining a private jz4740\_glue structure:
-
-::
+by defining a private ``jz4740_glue`` structure::
 
 struct jz4740_glue {
struct device   *dev;
@@ -115,10 +112,13 @@ information related to the device clock operation.
 Let's go through the steps of the probe function that leads the glue
 layer to register itself to the controller driver.
 
-N.B.: For the sake of readability each function will be split in logical
-parts, each part being shown as if it was independent from the others.
+.. note::
 
-::
+   For the sake of readability each function will be split in logical
+   parts, each part being shown as if it was independent from the others:
+
+   .. code-block:: c
+:emphasize-lines: 8,12,18
 
 static int jz4740_probe(struct platform_device *pdev)
 {
@@ -163,21 +163,23 @@ parts, each part being shown as if it was independent 
from the others.
return ret;
 }
 
+   The first few lines of the probe function allocate and assign the glue,
+   musb and clk variables. The ``GFP_KERNEL`` flag (line 8) allows the
+   allocation process to sleep and wait for memory, thus being usable in a
+   locking s

[PATCH 03/22] usb.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

- use the proper warning and note markups;
- add references for parts of the document that will be
  cross-referenced on other USB docs;
- some minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/usb.rst | 48 +---
 1 file changed, 17 insertions(+), 31 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index b856abb3200e..7e820768ee4f 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -102,6 +102,8 @@ disconnect testing (while the device is active) with each 
different host
 controller driver, to make sure drivers don't have bugs of their own as
 well as to make sure they aren't relying on some HCD-specific behavior.
 
+.. _usb_chapter9:
+
 USB-Standard Types
 ==
 
@@ -112,6 +114,8 @@ USB, and in APIs including this host side API, gadget APIs, 
and usbfs.
 .. kernel-doc:: include/linux/usb/ch9.h
:internal:
 
+.. _usb_header:
+
 Host-Side Data Types and Macros
 ===
 
@@ -209,7 +213,7 @@ library that wraps it. Such libraries include
 `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
 `jUSB <http://jUSB.sourceforge.net>`__ for Java.
 
-**Note**
+.. note::
 
 This particular documentation is incomplete, especially with respect
 to the asynchronous mode. As of kernel 2.5.66 the code and this
@@ -319,9 +323,7 @@ files. For information about the current format of this 
file, see the
 sources.
 
 This file, in combination with the poll() system call, can also be used
-to detect when devices are added or removed:
-
-::
+to detect when devices are added or removed::
 
 int fd;
 struct pollfd pfd;
@@ -407,9 +409,7 @@ The ioctl() Requests
 
 
 To use these ioctls, you need to include the following headers in your
-userspace program:
-
-::
+userspace program::
 
 #include 
 #include 
@@ -458,9 +458,7 @@ USBDEVFS_CLAIMINTERFACE
 
 USBDEVFS_CONNECTINFO
 Says whether the device is lowspeed. The ioctl parameter points to a
-structure like this:
-
-::
+structure like this::
 
struct usbdevfs_connectinfo {
unsigned int   devnum;
@@ -477,9 +475,7 @@ USBDEVFS_CONNECTINFO
 USBDEVFS_GETDRIVER
 Returns the name of the kernel driver bound to a given interface (a
 string). Parameter is a pointer to this structure, which is
-modified:
-
-::
+modified::
 
struct usbdevfs_getdriver {
unsigned int  interface;
@@ -490,9 +486,7 @@ USBDEVFS_GETDRIVER
 
 USBDEVFS_IOCTL
 Passes a request from userspace through to a kernel driver that has
-an ioctl entry in the *struct usb_driver* it registered.
-
-::
+an ioctl entry in the *struct usb_driver* it registered::
 
struct usbdevfs_ioctl {
int ifno;
@@ -534,7 +528,7 @@ USBDEVFS_RELEASEINTERFACE
 the number of the interface (bInterfaceNumber from descriptor); File
 modification time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*No security check is made to ensure that the task which made
the claim is the one which is releasing it. This means that user
@@ -574,9 +568,7 @@ a time.
 
 USBDEVFS_BULK
 Issues a bulk read or write request to the device. The ioctl
-parameter is a pointer to this structure:
-
-::
+parameter is a pointer to this structure::
 
struct usbdevfs_bulktransfer {
unsigned int  ep;
@@ -606,9 +598,7 @@ USBDEVFS_CLEAR_HALT
 
 USBDEVFS_CONTROL
 Issues a control request to the device. The ioctl parameter points
-to a structure like this:
-
-::
+to a structure like this::
 
struct usbdevfs_ctrltransfer {
__u8   bRequestType;
@@ -638,7 +628,7 @@ USBDEVFS_RESET
 the reset, this rebinds all device interfaces. File modification
 time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -646,9 +636,7 @@ USBDEVFS_RESET
 
 USBDEVFS_SETINTERFACE
 Sets the alternate setting for an interface. The ioctl parameter is
-a pointer to a structure like this:
-
-::
+a pointer to a structure like this::
 
struct usbdevfs_setinterface {
unsigned int  interface;
@@ -669,7 +657,7 @@ USBDEVFS_SETCONFIGURATION
 configuration (bConfigurationValue from descriptor). File
 modification time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -702,9 +690,7 @@ When usbfs returns these urbs, the status value is updated, 
and the
 buffer 

[PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- use the proper warning and note markups;
- use kernel-doc to include Kernel header and c files;
- remove legacy notes with regards to DocBook;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/gadget.rst | 69 +
 1 file changed, 45 insertions(+), 24 deletions(-)

diff --git a/Documentation/driver-api/usb/gadget.rst 
b/Documentation/driver-api/usb/gadget.rst
index 4fd9862f3f21..c4c76ebb51d3 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -1,3 +1,7 @@
+Linux-USB "Gadget" kernel mode API
+~~
+
+
 Introduction
 
 
@@ -175,16 +179,12 @@ the gadget, and submitting one or more *struct 
usb\_request* buffers to
 transfer data. Understand those four data types, and their operations,
 and you will understand how this API works.
 
-**Note**
+.. Note::
 
-This documentation was prepared using the standard Linux kernel
-``docproc`` tool, which turns text and in-code comments into SGML
-DocBook and then into usable formats such as HTML or PDF. Other than
-the "Chapter 9" data types, most of the significant data types and
-functions are described here.
+Other than the "Chapter 9" data types, most of the significant data
+types and functions are described here.
 
-However, docproc does not understand all the C constructs that are
-used, so some relevant information is likely omitted from what you
+However, some relevant information is likely omitted from what you
 are reading. One example of such information is endpoint
 autoconfiguration. You'll have to read the header file, and use
 example source code (such as that for "Gadget Zero"), to fully
@@ -192,10 +192,10 @@ and you will understand how this API works.
 
 The part of the API implementing some basic driver capabilities is
 specific to the version of the Linux kernel that's in use. The 2.6
-kernel includes a *driver model* framework that has no analogue on
-earlier kernels; so those parts of the gadget API are not fully
-portable. (They are implemented on 2.4 kernels, but in a different
-way.) The driver model state is another part of this API that is
+and upper kernel versions include a *driver model* framework that has
+no analogue on earlier kernels; so those parts of the gadget API are
+not fully portable. (They are implemented on 2.4 kernels, but in a
+different way.) The driver model state is another part of this API that is
 ignored by the kerneldoc tools.
 
 The core API does not expose every possible hardware feature, only the
@@ -301,18 +301,19 @@ USB 2.0 Chapter 9 Types and Constants
 -
 
 Gadget drivers rely on common USB structures and constants defined in
-the  header file, which is standard in Linux 2.6
-kernels. These are the same types and constants used by host side
+the :ref:`linux/usb/ch9.h ` header file, which is standard in
+Linux 2.6+ kernels. These are the same types and constants used by host side
 drivers (and usbcore).
 
-!Iinclude/linux/usb/ch9.h
 Core Objects and Methods
 
 
 These are declared in , and are used by gadget
 drivers to interact with USB peripheral controller drivers.
 
-!Iinclude/linux/usb/gadget.h
+.. kernel-doc:: include/linux/usb/gadget.h
+   :internal:
+
 Optional Utilities
 --
 
@@ -320,7 +321,12 @@ The core API is sufficient for writing a USB Gadget 
Driver, but some
 optional utilities are provided to simplify common tasks. These
 utilities include endpoint autoconfiguration.
 
-!Edrivers/usb/gadget/usbstring.c !Edrivers/usb/gadget/config.c
+.. kernel-doc:: drivers/usb/gadget/usbstring.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/config.c
+   :export:
+
 Composite Device Framework
 --
 
@@ -337,7 +343,12 @@ usb\_function*, which packages a user visible role such as 
"network
 link" or "mass storage device". Management functions may also exist,
 such as "Device Firmware Upgrade".
 
-!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c
+.. kernel-doc:: include/linux/usb/composite.h
+   :internal:
+
+.. kernel-doc:: drivers/usb/gadget/composite.c
+   :export:
+
 Composite Device Functions
 --
 
@@ -345,11 +356,21 @@ At this writing, a few of the current gadget drivers have 
been converted
 to this framework. Near-term plans include converting all of them,
 except for "gadgetfs".
 
-!Edrivers/usb/gadget/function/f\_acm.c
-!Edrivers/usb/gadget/function/f\_ecm.c
-!Edrivers/usb/gadget/function/f\_subset.c
-!Edrivers/usb/gadget/function/f\_obex.c
-!Edr

[PATCH 18/22] usb: get rid of some ReST doc build errors

[Mauro Carvalho Chehab]

We need an space before a numbered list to avoid those warnings:

./drivers/usb/core/message.c:478: ERROR: Unexpected indentation.
./drivers/usb/core/message.c:479: WARNING: Block quote ends without a blank 
line; unexpected unindent.
./include/linux/usb/composite.h:455: ERROR: Unexpected indentation.
./include/linux/usb/composite.h:456: WARNING: Block quote ends without a blank 
line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/usb/core/message.c| 1 +
 include/linux/usb/composite.h | 1 +
 2 files changed, 2 insertions(+)

diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 2184ef40a82a..4c38ea41ae96 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -474,6 +474,7 @@ EXPORT_SYMBOL_GPL(usb_sg_init);
  * significantly improve USB throughput.
  *
  * There are three kinds of completion for this function.
+ *
  * (1) success, where io->status is zero.  The number of io->bytes
  * transferred is as requested.
  * (2) error, where io->status is a negative errno value.  The number
diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 4616a49a1c2e..30a063e98c19 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -451,6 +451,7 @@ static inline struct usb_composite_driver *to_cdriver(
  * sure doing that won't hurt too much.
  *
  * One notion for how to handle Wireless USB devices involves:
+ *
  * (a) a second gadget here, discovery mechanism TBD, but likely
  * needing separate "register/unregister WUSB gadget" calls;
  * (b) updates to usb_gadget to include flags "is it wireless",
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 15/22] usb/URB.txt: convert to ReST and update it

[Mauro Carvalho Chehab]

The URB doc describes the Kernel mechanism that do USB transfers.
While the functions are already described at urb.h, there are a
number of concepts and theory that are important for USB driver
developers.

Convert it to ReST and use C ref links to point to the places
at usb.h where each function and struct is located.

A few of those descriptions were incomplete. While here, update
to reflect the current API status.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../{usb/URB.txt => driver-api/usb/URB.rst}| 204 -
 Documentation/driver-api/usb/index.rst |   1 +
 Documentation/driver-api/usb/usb.rst   |   2 +
 3 files changed, 120 insertions(+), 87 deletions(-)
 rename Documentation/{usb/URB.txt => driver-api/usb/URB.rst} (52%)

diff --git a/Documentation/usb/URB.txt b/Documentation/driver-api/usb/URB.rst
similarity index 52%
rename from Documentation/usb/URB.txt
rename to Documentation/driver-api/usb/URB.rst
index 50da0d455444..c5d2b68b4dae 100644
--- a/Documentation/usb/URB.txt
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,16 +1,25 @@
-Revised: 2000-Dec-05.
+USB Request Block (URB)
+~~~
+
+Revised: 2000-Dec-05
+
 Again:   2002-Jul-06
+
 Again:   2005-Sep-19
 
-NOTE:
+Again:   2017-Mar-29
 
-The USB subsystem now has a substantial section in "The Linux Kernel API"
-guide (in Documentation/DocBook), generated from the current source
-code.  This particular documentation file isn't particularly current or
-complete; don't rely on it except for a quick overview.
 
+.. note::
 
-1.1. Basic concept or 'What is an URB?'
+The USB subsystem now has a substantial section at :ref:`usb-hostside-api`
+section, generated from the current source code.
+This particular documentation file isn't complete and may not be
+updated to the last version; don't rely on it except for a quick
+overview.
+
+Basic concept or 'What is an URB?'
+==
 
 The basic idea of the new driver is message passing, the message itself is 
 called USB Request Block, or URB for short. 
@@ -19,10 +28,11 @@ called USB Request Block, or URB for short.
   and deliver the data and status back. 
 
 - Execution of an URB is inherently an asynchronous operation, i.e. the 
-  usb_submit_urb(urb) call returns immediately after it has successfully
+  :c:func:`usb_submit_urb` call returns immediately after it has successfully
   queued the requested action.
 
-- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. 
+- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb`
+  at any time.
 
 - Each URB has a completion handler, which is called after the action
   has been successfully completed or canceled. The URB also contains a
@@ -35,53 +45,55 @@ called USB Request Block, or URB for short.
   of data to (or from) devices when using periodic transfer modes.
 
 
-1.2. The URB structure
+The URB structure
+=
 
-Some of the fields in an URB are:
+Some of the fields in struct :c:type:`urb` are::
 
-struct urb
-{
-// (IN) device and pipe specify the endpoint queue
+  struct urb
+  {
+  // (IN) device and pipe specify the endpoint queue
struct usb_device *dev; // pointer to associated USB device
unsigned int pipe;  // endpoint information
 
-   unsigned int transfer_flags;// ISO_ASAP, SHORT_NOT_OK, etc.
+   unsigned int transfer_flags;// URB_ISO_ASAP, URB_SHORT_NOT_OK, etc.
 
-// (IN) all urbs need completion routines
+  // (IN) all urbs need completion routines
void *context;  // context for completion routine
-   void (*complete)(struct urb *); // pointer to completion routine
+   usb_complete_t complete;// pointer to completion routine
 
-// (OUT) status after each completion
+  // (OUT) status after each completion
int status; // returned status
 
-// (IN) buffer used for data transfers
+  // (IN) buffer used for data transfers
void *transfer_buffer;  // associated data buffer
-   int transfer_buffer_length; // data buffer length
+   u32 transfer_buffer_length; // data buffer length
int number_of_packets;  // size of iso_frame_desc
 
-// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
-   int actual_length;  // actual data buffer length
+  // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
+   u32 actual_length;  // actual data buffer length
 
-// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
-   unsigned char* setup_packet;// setup packet (control only)
+  // (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
+   unsigned char *setup_packet;// setup packet (control only)
 
-// Only for PERIODIC transfers (ISO, INTERRUPT)
-// (IN/OUT) sta

[PATCH 19/22] usb: composite.h: fix two warnings when building docs

[Mauro Carvalho Chehab]

By definition, we use /* private: */ tag when we won't be documenting
a parameter. However, those two parameters are documented:

./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef 
member 'setup_pending' description in 'usb_composite_dev'
./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef 
member 'os_desc_pending' description in 'usb_composite_dev'

So, we need to use /* public: */ to avoid a warning.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/usb/composite.h | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 30a063e98c19..f665d2ceac20 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -504,8 +504,9 @@ struct usb_composite_dev {
/* protects deactivations and delayed_status counts*/
spinlock_t  lock;
 
-   unsignedsetup_pending:1;
-   unsignedos_desc_pending:1;
+   /* public: */
+   unsigned intsetup_pending:1;
+   unsigned intos_desc_pending:1;
 };
 
 extern int usb_string_id(struct usb_composite_dev *c);
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 11/22] usb/dma.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../{usb/dma.txt => driver-api/usb/dma.rst}| 51 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 28 insertions(+), 24 deletions(-)
 rename Documentation/{usb/dma.txt => driver-api/usb/dma.rst} (79%)

diff --git a/Documentation/usb/dma.txt b/Documentation/driver-api/usb/dma.rst
similarity index 79%
rename from Documentation/usb/dma.txt
rename to Documentation/driver-api/usb/dma.rst
index 444651e70d95..59d5aee89e37 100644
--- a/Documentation/usb/dma.txt
+++ b/Documentation/driver-api/usb/dma.rst
@@ -1,16 +1,19 @@
+USB DMA
+~~~
+
 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
+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
-Documentation/DMA-API-HOWTO.txt).  That's how they've worked through
-the 2.4 (and earlier) kernels.
+``Documentation/DMA-API-HOWTO.txt``).  That's how they've worked through
+the 2.4 (and earlier) kernels, or they can now be DMA-aware.
 
-OR:  they can now be DMA-aware.
+DMA-aware usb drivers:
 
 - New calls enable DMA-aware drivers, letting them allocate dma buffers and
   manage dma mappings for existing dma-ready buffers (see below).
@@ -20,15 +23,15 @@ OR:  they can now be DMA-aware.
   drivers must not use it.)
 
 - "usbcore" will map this DMA address, if a DMA-aware driver didn't do
-  it first and set URB_NO_TRANSFER_DMA_MAP.  HCDs
+  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
   drivers.  Never use dma_set_mask() on any USB interface or device; that
   would potentially break all devices sharing that bus.
 
-
-ELIMINATING COPIES
+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.
@@ -41,7 +44,7 @@ and effects like cache-trashing can impose subtle penalties.
   For those specific cases, USB has primitives to allocate less expensive
   memory.  They work like kmalloc and kfree versions that give you the right
   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:
+  You'd also set ``URB_NO_TRANSFER_DMA_MAP`` in urb->transfer_flags::
 
void *usb_alloc_coherent (struct usb_device *dev, size_t size,
int mem_flags, dma_addr_t *dma);
@@ -49,15 +52,15 @@ and effects like cache-trashing can impose subtle penalties.
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
+  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.
+  :c:func:`kmalloc` will work just fine.
 
   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-API-HOWTO.txt for definitions of "coherent" and
+  ``Documentation/DMA-API-HOWTO.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
@@ -75,15 +78,15 @@ and effects like cache-trashing can impose subtle penalties.
   way to expose these capabilities ... and in any case, HIGHMEM is mostly a
   design wart specific to x86_32.  So your best bet is to ensure you never
   pass a highmem buffer into a USB driver.  That's easy; it's the default
-  behavior.  Just don't override it; e.g. with NETIF_F_HIGHDMA.
+  behavior.  Just don't override it; e.g. with ``NETIF_F_HIGHDMA``.
 
   This may force your callers to do some bounce buffering, copying from
   high memory to "normal" DMA memory.  If you can come up with a good way
   to fix this issue (for x86_32 machines with over 1 GByte of memory),
   feel free to submit patches.
 
-
-WORKING WITH EXISTING BUFFERS
+Working with existing buffers
+=
 
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  H

[PATCH 05/22] writing_usb_driver.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- adjust function and struct references;
- use monospaced fonts for C code names;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../driver-api/usb/writing_usb_driver.rst  | 97 +-
 1 file changed, 41 insertions(+), 56 deletions(-)

diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst 
b/Documentation/driver-api/usb/writing_usb_driver.rst
index 48f2fdb4745b..180859f664db 100644
--- a/Documentation/driver-api/usb/writing_usb_driver.rst
+++ b/Documentation/driver-api/usb/writing_usb_driver.rst
@@ -1,3 +1,8 @@
+.. _writing-usb-driver:
+
+Writing USB drivers
+~~~
+
 Introduction
 
 
@@ -42,10 +47,8 @@ The first thing a Linux USB driver needs to do is register 
itself with
 the Linux USB subsystem, giving it some information about which devices
 the driver supports and which functions to call when a device supported
 by the driver is inserted or removed from the system. All of this
-information is passed to the USB subsystem in the usb\_driver structure.
-The skeleton driver declares a usb\_driver as:
-
-::
+information is passed to the USB subsystem in the :c:type:`usb_driver`
+structure. The skeleton driver declares a :c:type:`usb_driver` as::
 
 static struct usb_driver skel_driver = {
.name= "skeleton",
@@ -60,7 +63,7 @@ The skeleton driver declares a usb\_driver as:
 The variable name is a string that describes the driver. It is used in
 informational messages printed to the system log. The probe and
 disconnect function pointers are called when a device that matches the
-information provided in the id\_table variable is either seen or
+information provided in the ``id_table`` variable is either seen or
 removed.
 
 The fops and minor variables are optional. Most USB drivers hook into
@@ -70,15 +73,13 @@ subsystem, and any user-space interactions are provided 
through that
 interface. But for drivers that do not have a matching kernel subsystem,
 such as MP3 players or scanners, a method of interacting with user space
 is needed. The USB subsystem provides a way to register a minor device
-number and a set of file\_operations function pointers that enable this
-user-space interaction. The skeleton driver needs this kind of
+number and a set of :c:type:`file_operations` function pointers that enable
+this user-space interaction. The skeleton driver needs this kind of
 interface, so it provides a minor starting number and a pointer to its
-file\_operations functions.
+:c:type:`file_operations` functions.
 
-The USB driver is then registered with a call to usb\_register, usually
-in the driver's init function, as shown here:
-
-::
+The USB driver is then registered with a call to :c:func:`usb_register`,
+usually in the driver's init function, as shown here::
 
 static int __init usb_skel_init(void)
 {
@@ -98,10 +99,8 @@ in the driver's init function, as shown here:
 
 
 When the driver is unloaded from the system, it needs to deregister
-itself with the USB subsystem. This is done with the usb\_deregister
-function:
-
-::
+itself with the USB subsystem. This is done with the :c:func:`usb_deregister`
+function::
 
 static void __exit usb_skel_exit(void)
 {
@@ -112,11 +111,9 @@ function:
 
 
 To enable the linux-hotplug system to load the driver automatically when
-the device is plugged in, you need to create a MODULE\_DEVICE\_TABLE.
+the device is plugged in, you need to create a ``MODULE_DEVICE_TABLE``.
 The following code tells the hotplug scripts that this module supports a
-single device with a specific vendor and product ID:
-
-::
+single device with a specific vendor and product ID::
 
 /* table of devices that work with this driver */
 static struct usb_device_id skel_table [] = {
@@ -126,19 +123,17 @@ single device with a specific vendor and product ID:
 MODULE_DEVICE_TABLE (usb, skel_table);
 
 
-There are other macros that can be used in describing a usb\_device\_id
-for drivers that support a whole class of USB drivers. See usb.h for
-more information on this.
+There are other macros that can be used in describing a struct
+:c:type:`usb_device_id` for drivers that support a whole class of USB
+drivers. See :ref:`usb.h ` for more information on this.
 
 Device operation
 
 
 When a device is plugged into the USB bus that matches the device ID
 pattern that your driver registered with the USB core, the probe
-function is called. The usb\_device structure, interface number and the
-interface ID are passed to the function:
-
-::
+function is called. The :c:type:`usb_device` structure, interface number and
+the interface ID are passed to the function::
 
 static int skel_probe(struct usb_interface *interface,
const struct usb_device_id *id)
@@ -160,16 +155,14

[PATCH 17/22] usb.rst: get rid of some Sphinx errors

[Mauro Carvalho Chehab]

Get rid of those warnings:

Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_type".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_dir".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_recip".
Documentation/driver-api/usb/usb.rst:679: ERROR: Unknown target name: 
"usbdevfs_urb_type".

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/usb.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index d15ab8ae5239..5ebaf669704c 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -615,8 +615,8 @@ USBDEVFS_CONTROL
 The first eight bytes of this structure are the contents of the
 SETUP packet to be sent to the device; see the USB 2.0 specification
 for details. The bRequestType value is composed by combining a
-USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\*
-value (from **). If wLength is nonzero, it describes
+``USB_TYPE_*`` value, a ``USB_DIR_*`` value, and a ``USB_RECIP_*``
+value (from ``linux/usb.h``). If wLength is nonzero, it describes
 the length of the data buffer, which is either written to the device
 (USB_DIR_OUT) or read from the device (USB_DIR_IN).
 
@@ -678,7 +678,7 @@ the blocking is separate.
 
 These requests are packaged into a structure that resembles the URB used
 by kernel device drivers. (No POSIX Async I/O support here, sorry.) It
-identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint
+identifies the endpoint type (``USBDEVFS_URB_TYPE_*``), endpoint
 (number, masked with USB_DIR_IN as appropriate), buffer and length,
 and a user "context" value serving to uniquely identify each request.
 (It's usually a pointer to per-request data.) Flags can modify requests
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 16/22] usb/gadget.rst: remove unused kernel-doc tags

[Mauro Carvalho Chehab]

The DocBook file used to have "!E" include tags for usb gadget functions.
However, there's nothing there to be documented:

./drivers/usb/gadget/function/f_acm.c:1: warning: no structured 
comments found
./drivers/usb/gadget/function/f_ecm.c:1: warning: no structured 
comments found
./drivers/usb/gadget/function/f_subset.c:1: warning: no structured 
comments found
./drivers/usb/gadget/function/f_obex.c:1: warning: no structured 
comments found
./drivers/usb/gadget/function/f_serial.c:1: warning: no structured 
comments found

So, let's remove it. If someone wants do document the function
there, they may just revert this patch in the future.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/gadget.rst | 15 ---
 1 file changed, 15 deletions(-)

diff --git a/Documentation/driver-api/usb/gadget.rst 
b/Documentation/driver-api/usb/gadget.rst
index c4c76ebb51d3..0488b89de21c 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -356,21 +356,6 @@ At this writing, a few of the current gadget drivers have 
been converted
 to this framework. Near-term plans include converting all of them,
 except for "gadgetfs".
 
-.. kernel-doc:: drivers/usb/gadget/function/f_acm.c
-   :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_ecm.c
-   :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_subset.c
-   :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_obex.c
-   :export:
-
-.. kernel-doc:: drivers/usb/gadget/function/f_serial.c
-   :export:
-
 Peripheral Controller Drivers
 =
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 10/22] usb/power-management.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/index.rst |   1 +
 .../usb/power-management.rst}  | 403 +++--
 2 files changed, 214 insertions(+), 190 deletions(-)
 rename Documentation/{usb/power-management.txt => 
driver-api/usb/power-management.rst} (69%)

diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 441c5dacdf27..23c76c17fc19 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -9,6 +9,7 @@ Linux USB API
anchors
bulk-streams
callbacks
+   power-management
writing_usb_driver
writing_musb_glue_layer
 
diff --git a/Documentation/usb/power-management.txt 
b/Documentation/driver-api/usb/power-management.rst
similarity index 69%
rename from Documentation/usb/power-management.txt
rename to Documentation/driver-api/usb/power-management.rst
index 00e706997130..7c547d6b8372 100644
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -1,10 +1,13 @@
-   Power Management for USB
+.. _usb-power-management:
 
-Alan Stern 
+Power Management for USB
+
 
-  Last-updated: February 2014
+Alan Stern 
 
+Last-updated: February 2014
 
+..
Contents:
-
* What is Power Management?
@@ -25,14 +28,14 @@
* Suggested Userspace Port Power Policy
 
 
-   What is Power Management?
-   -
+What is Power Management?
+-
 
 Power Management (PM) is the practice of saving energy by suspending
 parts of a computer system when they aren't being used.  While a
-component is "suspended" it is in a nonfunctional low-power state; it
+component is ``suspended`` it is in a nonfunctional low-power state; it
 might even be turned off completely.  A suspended component can be
-"resumed" (returned to a functional full-power state) when the kernel
+``resumed`` (returned to a functional full-power state) when the kernel
 needs to use it.  (There also are forms of PM in which components are
 placed in a less functional but still usable state instead of being
 suspended; an example would be reducing the CPU's clock rate.  This
@@ -44,22 +47,25 @@ device is turned off while the system as a whole remains 
running, we
 call it a "dynamic suspend" (also known as a "runtime suspend" or
 "selective suspend").  This document concentrates mostly on how
 dynamic PM is implemented in the USB subsystem, although system PM is
-covered to some extent (see Documentation/power/*.txt for more
+covered to some extent (see ``Documentation/power/*.txt`` for more
 information about system PM).
 
-System PM support is present only if the kernel was built with CONFIG_SUSPEND
-or CONFIG_HIBERNATION enabled.  Dynamic PM support for USB is present whenever
-the kernel was built with CONFIG_PM enabled.
+System PM support is present only if the kernel was built with
+``CONFIG_SUSPEND`` or ``CONFIG_HIBERNATION`` enabled.  Dynamic PM support
+
+for USB is present whenever
+the kernel was built with ``CONFIG_PM`` enabled.
 
 [Historically, dynamic PM support for USB was present only if the
-kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on
-CONFIG_PM_RUNTIME).  Starting with the 3.10 kernel release, dynamic PM support
-for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME
-enabled.  The CONFIG_USB_SUSPEND option had been eliminated.]
+kernel had been built with ``CONFIG_USB_SUSPEND`` enabled (which depended on
+``CONFIG_PM_RUNTIME``).  Starting with the 3.10 kernel release, dynamic PM
+support for USB was present whenever the kernel was built with
+``CONFIG_PM_RUNTIME`` enabled.  The ``CONFIG_USB_SUSPEND`` option had been
+eliminated.]
 
 
-   What is Remote Wakeup?
-   --
+What is Remote Wakeup?
+--
 
 When a device has been suspended, it generally doesn't resume until
 the computer tells it to.  Likewise, if the entire computer has been
@@ -76,8 +82,8 @@ event.  Examples include a suspended keyboard resuming when a 
key is
 pressed, or a suspended USB hub resuming when a device is plugged in.
 
 
-   When is a USB device idle?
-   --
+When is a USB device idle?
+--
 
 A device is idle whenever the kernel thinks it's not busy doing
 anything important and thus is a candidate for being suspended.  The
@@ -92,11 +98,11 @@ If a USB device has no driver, its usbfs file isn't open, 
and it isn't
 being accessed through sysfs, then it definitely is idle.
 
 
-   Forms of dynamic PM
-   ---
+Forms of dynamic PM
+---
 
 Dynamic

[PATCH 13/22] usb/hotplug.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../hotplug.txt => driver-api/usb/hotplug.rst} | 66 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 37 insertions(+), 30 deletions(-)
 rename Documentation/{usb/hotplug.txt => driver-api/usb/hotplug.rst} (76%)

diff --git a/Documentation/usb/hotplug.txt 
b/Documentation/driver-api/usb/hotplug.rst
similarity index 76%
rename from Documentation/usb/hotplug.txt
rename to Documentation/driver-api/usb/hotplug.rst
index 5b243f315b2c..79663e653ca1 100644
--- a/Documentation/usb/hotplug.txt
+++ b/Documentation/driver-api/usb/hotplug.rst
@@ -1,4 +1,9 @@
-LINUX HOTPLUGGING
+USB hotplugging
+~~~
+
+Linux Hotplugging
+=
+
 
 In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
 into the bus with power on.  In most cases, users expect the devices to become
@@ -30,11 +35,11 @@ Because some of those actions rely on information about 
drivers (metadata)
 that is currently available only when the drivers are dynamically linked,
 you get the best hotplugging when you configure a highly modular system.
 
+Kernel Hotplug Helper (``/sbin/hotplug``)
+=
 
-KERNEL HOTPLUG HELPER (/sbin/hotplug)
-
-There is a kernel parameter: /proc/sys/kernel/hotplug, which normally
-holds the pathname "/sbin/hotplug".  That parameter names a program
+There is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally
+holds the pathname ``/sbin/hotplug``.  That parameter names a program
 which the kernel may invoke at various times.
 
 The /sbin/hotplug program can be invoked by any subsystem as part of its
@@ -51,26 +56,26 @@ Hotplug software and other resources is available at:
 Mailing list information is also available at that site.
 
 
---
+USB Policy Agent
+
 
-
-USB POLICY AGENT
-
-The USB subsystem currently invokes /sbin/hotplug when USB devices
+The USB subsystem currently invokes ``/sbin/hotplug`` when USB devices
 are added or removed from system.  The invocation is done by the kernel
 hub workqueue [hub_wq], or else as part of root hub initialization
 (done by init, modprobe, kapmd, etc).  Its single command line parameter
 is the string "usb", and it passes these environment variables:
 
-ACTION ... "add", "remove"
-PRODUCT ... USB vendor, product, and version codes (hex)
-TYPE ... device class codes (decimal)
-INTERFACE ... interface 0 class codes (decimal)
+== 
+ACTION ``add``, ``remove``
+PRODUCTUSB vendor, product, and version codes (hex)
+TYPE   device class codes (decimal)
+INTERFACE  interface 0 class codes (decimal)
+== 
 
 If "usbdevfs" is configured, DEVICE and DEVFS are also passed.  DEVICE is
 the pathname of the device, and is useful for devices with multiple and/or
 alternate interfaces that complicate driver selection.  By design, USB
-hotplugging is independent of "usbdevfs":  you can do most essential parts
+hotplugging is independent of ``usbdevfs``:  you can do most essential parts
 of USB device setup without using that filesystem, and without running a
 user mode daemon to detect changes in system configuration.
 
@@ -79,19 +84,20 @@ modules, and can invoke driver-specific setup scripts.  The 
newest ones
 leverage USB module-init-tools support.  Later agents might unload drivers.
 
 
-USB MODUTILS SUPPORT
+USB Modutils Support
+
 
-Current versions of module-init-tools will create a "modules.usbmap" file
-which contains the entries from each driver's MODULE_DEVICE_TABLE.  Such
+Current versions of module-init-tools will create a ``modules.usbmap`` file
+which contains the entries from each driver's ``MODULE_DEVICE_TABLE``.  Such
 files can be used by various user mode policy agents to make sure all the
 right driver modules get loaded, either at boot time or later.
 
-See  for full information about such table entries; or look
+See ``linux/usb.h`` for full information about such table entries; or look
 at existing drivers.  Each table entry describes one or more criteria to
 be used when matching a driver to a device or class of devices.  The
 specific criteria are identified by bits set in "match_flags", paired
 with field values.  You can construct the criteria directly, or with
-macros such as these, and use driver_info to store more information.
+macros such as these, and use driver_info to store more information::
 
 USB_DEVICE (vendorId, productId)
... matching devices with specified vendor and product ids
@@ -103,7 +109,7 @@ macros such as these, and use driver_info to store more 
information.

[PATCH 08/22] usb/bulk-streams.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../bulk-streams.txt => driver-api/usb/bulk-streams.rst}| 13 +
 Documentation/driver-api/usb/index.rst  |  1 +
 2 files changed, 10 insertions(+), 4 deletions(-)
 rename Documentation/{usb/bulk-streams.txt => driver-api/usb/bulk-streams.rst} 
(94%)

diff --git a/Documentation/usb/bulk-streams.txt 
b/Documentation/driver-api/usb/bulk-streams.rst
similarity index 94%
rename from Documentation/usb/bulk-streams.txt
rename to Documentation/driver-api/usb/bulk-streams.rst
index ffc02021863e..99b515babdeb 100644
--- a/Documentation/usb/bulk-streams.txt
+++ b/Documentation/driver-api/usb/bulk-streams.rst
@@ -1,3 +1,6 @@
+USB bulk streams
+
+
 Background
 ==
 
@@ -25,7 +28,9 @@ time.
 Driver implications
 ===
 
-int usb_alloc_streams(struct usb_interface *interface,
+::
+
+  int usb_alloc_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
unsigned int num_streams, gfp_t mem_flags);
 
@@ -53,7 +58,7 @@ controller driver, and may change in the future.
 
 
 Picking new Stream IDs to use
-
+=
 
 Stream ID 0 is reserved, and should not be used to communicate with devices.  
If
 usb_alloc_streams() returns with a value of N, you may use streams 1 though N.
@@ -68,9 +73,9 @@ Clean up
 
 
 If a driver wishes to stop using streams to communicate with the device, it
-should call
+should call::
 
-void usb_free_streams(struct usb_interface *interface,
+  void usb_free_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
gfp_t mem_flags);
 
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 5dfb04b2d730..6fe7611f7332 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -7,6 +7,7 @@ Linux USB API
usb
gadget
anchors
+   bulk-streams
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 21/22] docs-rst: fix usb cross-references

[Mauro Carvalho Chehab]

As some USB documentation files got moved, adjust their
cross-references to their new place.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ABI/stable/sysfs-bus-usb| 2 +-
 Documentation/driver-api/usb/URB.rst  | 2 ++
 Documentation/driver-api/usb/callbacks.rst| 4 ++--
 Documentation/driver-api/usb/error-codes.rst  | 2 ++
 Documentation/driver-api/usb/persist.rst  | 2 ++
 Documentation/driver-api/usb/power-management.rst | 2 +-
 Documentation/driver-api/usb/usb.rst  | 4 ++--
 Documentation/power/swsusp.txt| 2 +-
 drivers/staging/most/hdm-usb/hdm_usb.c| 2 +-
 drivers/usb/core/Kconfig  | 2 +-
 10 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-bus-usb 
b/Documentation/ABI/stable/sysfs-bus-usb
index 831f15d9672f..b832eeff 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -9,7 +9,7 @@ Description:
hubs this facility is always enabled and their device
directories will not contain this file.
 
-   For more information, see Documentation/usb/persist.txt.
+   For more information, see 
Documentation/driver-api/usb/persist.rst.
 
 What:  /sys/bus/usb/devices/.../power/autosuspend
 Date:  March 2007
diff --git a/Documentation/driver-api/usb/URB.rst 
b/Documentation/driver-api/usb/URB.rst
index c5d2b68b4dae..d9ea6a3996e7 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,3 +1,5 @@
+.. _usb-urb:
+
 USB Request Block (URB)
 ~~~
 
diff --git a/Documentation/driver-api/usb/callbacks.rst 
b/Documentation/driver-api/usb/callbacks.rst
index 93a8d53e27e7..2b80cf54bcc3 100644
--- a/Documentation/driver-api/usb/callbacks.rst
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -8,7 +8,7 @@ Usbcore will call into a driver through callbacks defined in 
the driver
 structure and through the completion handler of URBs a driver submits.
 Only the former are in the scope of this document. These two kinds of
 callbacks are completely independent of each other. Information on the
-completion callback can be found in Documentation/usb/URB.txt.
+completion callback can be found in :ref:`usb-urb`.
 
 The callbacks defined in the driver structure are:
 
@@ -53,7 +53,7 @@ The callbacks defined in the driver structure are:
 
 The ioctl interface (2) should be used only if you have a very good
 reason. Sysfs is preferred these days. The PM callbacks are covered
-separately in Documentation/usb/power-management.txt.
+separately in :ref:`usb-power-management`.
 
 Calling conventions
 ===
diff --git a/Documentation/driver-api/usb/error-codes.rst 
b/Documentation/driver-api/usb/error-codes.rst
index 715cc35b29b0..5bc5eda58520 100644
--- a/Documentation/driver-api/usb/error-codes.rst
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -1,3 +1,5 @@
+.. _usb-error-codes:
+
 USB Error codes
 ~~~
 
diff --git a/Documentation/driver-api/usb/persist.rst 
b/Documentation/driver-api/usb/persist.rst
index af02baf61f57..8ee2a62d889b 100644
--- a/Documentation/driver-api/usb/persist.rst
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,3 +1,5 @@
+.. _usb-persist:
+
 USB device persistence during system suspend
 
 
diff --git a/Documentation/driver-api/usb/power-management.rst 
b/Documentation/driver-api/usb/power-management.rst
index 7c547d6b8372..3e4ebbf47b76 100644
--- a/Documentation/driver-api/usb/power-management.rst
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -329,7 +329,7 @@ possible to work around the hibernation-forces-disconnect 
problem by
 using the USB Persist facility.)
 
 The ``reset_resume`` method is used by the USB Persist facility (see
-``Documentation/usb/persist.txt``) and it can also be used under certain
+:ref:`usb-persist`) and it can also be used under certain
 circumstances when ``CONFIG_USB_PERSIST`` is not enabled.  Currently, if a
 device is reset during a resume and the driver does not have a
 ``reset_resume`` method, the driver won't receive any notification about
diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index 5ebaf669704c..6824089ef4c8 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -424,8 +424,8 @@ header.
 Unless noted otherwise, the ioctl requests described here will update
 the modification time on the usbfs file to which they are applied
 (unless they fail). A return of zero indicates success; otherwise, a
-standard USB error code is returned. (These are documented in
-``Documentation/usb/error-codes.txt`` in your kernel sources.)
+standard USB error code is returned (These are documented in
+:ref:`usb-error-codes`).
 
 Each of these files multiplexes access to several I/O st

[PATCH 09/22] usb/callbacks.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../callbacks.txt => driver-api/usb/callbacks.rst} | 61 +++---
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 43 insertions(+), 19 deletions(-)
 rename Documentation/{usb/callbacks.txt => driver-api/usb/callbacks.rst} (78%)

diff --git a/Documentation/usb/callbacks.txt 
b/Documentation/driver-api/usb/callbacks.rst
similarity index 78%
rename from Documentation/usb/callbacks.txt
rename to Documentation/driver-api/usb/callbacks.rst
index 9e85846bdb98..93a8d53e27e7 100644
--- a/Documentation/usb/callbacks.txt
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -1,3 +1,6 @@
+USB core callbacks
+~~
+
 What callbacks will usbcore do?
 ===
 
@@ -11,30 +14,42 @@ The callbacks defined in the driver structure are:
 
 1. Hotplugging callbacks:
 
- * @probe: Called to see if the driver is willing to manage a particular
- * interface on a device.
- * @disconnect: Called when the interface is no longer accessible, usually
- * because its device has been (or is being) disconnected or the
- * driver module is being unloaded.
+ - @probe:
+   Called to see if the driver is willing to manage a particular
+   interface on a device.
+
+ - @disconnect:
+   Called when the interface is no longer accessible, usually
+   because its device has been (or is being) disconnected or the
+   driver module is being unloaded.
 
 2. Odd backdoor through usbfs:
 
- * @ioctl: Used for drivers that want to talk to userspace through
- * the "usbfs" filesystem.  This lets devices provide ways to
- * expose information to user space regardless of where they
- * do (or don't) show up otherwise in the filesystem.
+ - @ioctl:
+   Used for drivers that want to talk to userspace through
+   the "usbfs" filesystem.  This lets devices provide ways to
+   expose information to user space regardless of where they
+   do (or don't) show up otherwise in the filesystem.
 
 3. Power management (PM) callbacks:
 
- * @suspend: Called when the device is going to be suspended.
- * @resume: Called when the device is being resumed.
- * @reset_resume: Called when the suspended device has been reset instead
- * of being resumed.
+ - @suspend:
+   Called when the device is going to be suspended.
+
+ - @resume:
+   Called when the device is being resumed.
+
+ - @reset_resume:
+   Called when the suspended device has been reset instead
+   of being resumed.
 
 4. Device level operations:
 
- * @pre_reset: Called when the device is about to be reset.
- * @post_reset: Called after the device has been reset
+ - @pre_reset:
+   Called when the device is about to be reset.
+
+ - @post_reset:
+   Called after the device has been reset
 
 The ioctl interface (2) should be used only if you have a very good
 reason. Sysfs is preferred these days. The PM callbacks are covered
@@ -58,7 +73,9 @@ an interface. A driver's bond to an interface is exclusive.
 The probe() callback
 
 
-int (*probe) (struct usb_interface *intf,
+::
+
+  int (*probe) (struct usb_interface *intf,
const struct usb_device_id *id);
 
 Accept or decline an interface. If you accept the device return 0,
@@ -75,7 +92,9 @@ initialisation that doesn't take too long is a good idea here.
 The disconnect() callback
 -
 
-void (*disconnect) (struct usb_interface *intf);
+::
+
+  void (*disconnect) (struct usb_interface *intf);
 
 This callback is a signal to break any connection with an interface.
 You are not allowed any IO to a device after returning from this
@@ -93,7 +112,9 @@ Device level callbacks
 pre_reset
 -
 
-int (*pre_reset)(struct usb_interface *intf);
+::
+
+  int (*pre_reset)(struct usb_interface *intf);
 
 A driver or user space is triggering a reset on the device which
 contains the interface passed as an argument. Cease IO, wait for all
@@ -107,7 +128,9 @@ are in atomic context.
 post_reset
 --
 
-int (*post_reset)(struct usb_interface *intf);
+::
+
+  int (*post_reset)(struct usb_interface *intf);
 
 The reset has completed.  Restore any saved device state and begin
 using the device again.
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 6fe7611f7332..441c5dacdf27 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -8,6 +8,7 @@ Linux USB API
gadget
anchors
bulk-streams
+   callbacks
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 01:15:27 +0300
Laurent Pinchart  escreveu:

> Hi Mauro,
> 
> Thank you for the patch.
> 
> On Wednesday 29 Mar 2017 15:54:21 Mauro Carvalho Chehab wrote:
> > Several host controllers, commonly found on ARM, like dwc2,
> > require buffers that are CPU-word aligned for they to work.
> > 
> > Failing to do that will cause random troubles at the caller
> > drivers, causing them to fail.
> > 
> > Document it.
> > 
> > Signed-off-by: Mauro Carvalho Chehab 
> > ---
> >  Documentation/driver-api/usb/URB.rst | 18 ++
> >  drivers/usb/core/message.c   | 15 +++
> >  include/linux/usb.h  | 18 ++
> >  3 files changed, 51 insertions(+)
> > 
> > diff --git a/Documentation/driver-api/usb/URB.rst
> > b/Documentation/driver-api/usb/URB.rst index d9ea6a3996e7..b83b557e9891
> > 100644
> > --- a/Documentation/driver-api/usb/URB.rst
> > +++ b/Documentation/driver-api/usb/URB.rst
> > @@ -274,6 +274,24 @@ If you specify your own start frame, make sure it's
> > several frames in advance of the current frame.  You might want this model
> > if you're synchronizing ISO data with some other event stream.
> > 
> > +.. note::
> > +
> > +   Several host drivers require that the ``transfer_buffer`` to be aligned
> > +   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).  
> 
> Is it the CPU word size or the DMA transfer size ? I assume the latter, and I 
> wouldn't be surprised if the alignment requirement was 32-bit on at least 
> some 
> of the 64-bit platforms.

Yeah, it is actually the DMA transfer size. Yet, worse case scenario is that
the DMA transfer size to be 64 bits on 64 bits CPU.

> 
> > +   It is up to USB drivers should ensure that they'll only pass buffers
> > +   with such alignments.
> > +
> > +   Please also notice that, due to such restriction, the host driver  
> 
> s/notice/note/ (and below as well) ?

OK.

> > +   may also override PAD bytes at the end of the ``transfer_buffer``, up to
> > the
> > +   size of the CPU word.  
> 
> "May" is quite weak here. If some host controller drivers require buffers to 
> be aligned, then it's an API requirement, and all buffers must be aligned. 
> I'm 
> not even sure I would mention that some host drivers require it, I think we 
> should just state that the API requires buffers to be aligned.

What I'm trying to say here is that, on a 32-bits system, if the driver do
a USB_DIR_IN transfer using some code similar to:

size = 4;
buffer = kmalloc(size, GFP_KERNEL);

usb_control_msg(udev, pipe, req, type, val, idx, buffer + 2, 2, 
timeout);
usb_control_msg(udev, pipe, req, type, val, idx, buffer, size, timeout);

Drivers like dwc2 will mess with the buffer.

The first transfer will actually work, due to a workaround inside the
driver that will create a temporary DWORD-aligned buffer, avoiding it
to go past the buffer.

However, the second transfer will destroy the data received from the
first usb_control_msg(), as it will write 4 bytes at the buffer.

Not all drivers would do that, though.

Please notice that, as kmalloc will always return a CPU-aligned buffer,
if the client do something like:

size = 2;
buffer = kmalloc(size, GFP_KERNEL);

usb_control_msg(udev, pipe, req, type, val, idx, buffer, 2, timeout);

What happens there is that the DMA engine will still write 4 bytes at
the buffer, but the 2 bytes that go past the end of buffer will be
written on a memory that will never be used.

> 
> > +   Please notice that ancillary routines that transfer URBs, like
> > +   usb_control_msg() also have such restriction.
> > +
> > +   Such word alignment condition is normally ensured if the buffer is
> > +   allocated with kmalloc(), but this may not be the case if the driver
> > +   allocates a bigger buffer and point to a random place inside it.
> > +
> > 
> >  How to start interrupt (INT) transfers?
> >  ===
> > diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
> > index 4c38ea41ae96..1662a4446475 100644
> > --- a/drivers/usb/core/message.c
> > +++ b/drivers/usb/core/message.c
> > @@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct usb_device
> > *usb_dev, * make sure your disconnect() method can wait for it to complete.
> > Since you * don't have a handle on the URB used, you can't cancel the
> > request. *
> > + * .. note::
> > + *
> > + *   Several host drivers require that the @data buffer to be aligned
> > 

Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 10:01:29 +0300
Jani Nikula  escreveu:

> On Wed, 29 Mar 2017, Mauro Carvalho Chehab  wrote:
> > The pandoc conversion is not perfect. Do handwork in order to:
> >
> > - add a title to this chapter;
> > - use the proper warning and note markups;
> > - use kernel-doc to include Kernel header and c files;  
> 
> Please look at Documentation/sphinx/tmplcvt which takes care of all of
> that.

Ah, didn't know about such script!

Trying it here:

$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl 
sed: couldn't open file convert_template.sed: No such file or directory

It would be good to change the script for it to seek for convert_template.sed
at the right place.

So, please consider the following patch.

Regards,
Mauro


[PATCH] tmplcvt: make the tool more robust

Currently, the script just assumes to be called at
Documentation/sphinx/. Change it to work on any directory,
and make it abort if something gets wrong.

Also, be sure that both parameters are specified.

That should avoid troubles like this:

$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
sed: couldn't open file convert_template.sed: No such file or directory

Signed-off-by: Mauro Carvalho Chehab 

diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
index 909a73065e0a..31df8eb7feca 100755
--- a/Documentation/sphinx/tmplcvt
+++ b/Documentation/sphinx/tmplcvt
@@ -7,13 +7,22 @@
 # fix \_
 # title line?
 #
+set -eu
+
+if [ "$2" == "" ]; then
+   echo "$0  "
+   exit
+fi
+
+DIR=$(dirname $0)
 
 in=$1
 rst=$2
 tmp=$rst.tmp
 
 cp $in $tmp
-sed --in-place -f convert_template.sed $tmp
+sed --in-place -f $DIR/convert_template.sed $tmp
 pandoc -s -S -f docbook -t rst -o $rst $tmp
-sed --in-place -f post_convert.sed $rst
+sed --in-place -f $DIR/post_convert.sed $rst
 rm $tmp
+echo "book writen to $rst"
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 10:04:32 +0300
Jani Nikula  escreveu:

> On Thu, 30 Mar 2017, Jani Nikula  wrote:
> > On Wed, 29 Mar 2017, Mauro Carvalho Chehab  
> > wrote:  
> >> The pandoc conversion is not perfect. Do handwork in order to:
> >>
> >> - add a title to this chapter;
> >> - use the proper warning and note markups;
> >> - use kernel-doc to include Kernel header and c files;  
> >
> > Please look at Documentation/sphinx/tmplcvt which takes care of all of
> > that.  
> 
> That said, since you've already manually done the work, you might want
> to do another conversion using the script, and diff the results to see
> if there's something you've perhaps missed. I'm pretty sure nobody's
> going to read patch 2 line-by-line...

Done. The only thing left was the original docbook title and author
information.

The diff also showed that I was a little lazy manually adjust the
gadget.rst document ;) The enclosed patch should fix those issues.

I'll likely fold it with other patches when sending a version 2.

Regards,
Mauro

[PATCH] docs-rst: improve docbook-converted documents

The output of Documentation/sphinx/tmplcvt showed that a few
adjustments could be done in order to improve the output of
the two files that were converted from docbook:

- Use the original title from docbook;
- Add author info;
- Add C references for source code xrefs;
- Use monospaced fonts to be consistent with other docs.

Signed-off-by: Mauro Carvalho Chehab 

diff --git a/Documentation/driver-api/usb/gadget.rst 
b/Documentation/driver-api/usb/gadget.rst
index 0488b89de21c..4b02c61a389d 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -1,6 +1,9 @@
-Linux-USB "Gadget" kernel mode API
-~~
+
+USB Gadget API for Linux
+
 
+:Author: David Brownell
+:Date:   20 August 2004
 
 Introduction
 
@@ -35,7 +38,7 @@ address a number of important problems, including:
resources.
 
 Most Linux developers will not be able to use this API, since they have
-USB "host" hardware in a PC, workstation, or server. Linux users with
+USB ``host`` hardware in a PC, workstation, or server. Linux users with
 embedded systems are more likely to have USB peripheral hardware. To
 distinguish drivers running inside such hardware from the more familiar
 Linux "USB device drivers", which are host side proxies for the real USB
@@ -61,7 +64,7 @@ Structure of Gadget Drivers
 
 A system running inside a USB peripheral normally has at least three
 layers inside the kernel to handle USB protocol processing, and may have
-additional layers in user space code. The "gadget" API is used by the
+additional layers in user space code. The ``gadget`` API is used by the
 middle layer to interact with the lowest level (which directly handles
 hardware).
 
@@ -140,13 +143,13 @@ In Linux, from the bottom up, these layers are:
 *Additional Layers*
 Other layers may exist. These could include kernel layers, such as
 network protocol stacks, as well as user mode applications building
-on standard POSIX system call APIs such as *open()*, *close()*,
-*read()* and *write()*. On newer systems, POSIX Async I/O calls may
+on standard POSIX system call APIs such as ``open()``, ``close()``,
+``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may
 be an option. Such user mode code will not necessarily be subject to
 the GNU General Public License (GPL).
 
 OTG-capable systems will also need to include a standard Linux-USB host
-side stack, with *usbcore*, one or more *Host Controller Drivers*
+side stack, with ``usbcore``, one or more *Host Controller Drivers*
 (HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
 List", and so forth. There will also be an *OTG Controller Driver*,
 which is visible to gadget and device driver developers only indirectly.
@@ -171,11 +174,11 @@ combined, to implement composite devices.
 Kernel Mode Gadget API
 ==
 
-Gadget drivers declare themselves through a *struct
-usb\_gadget\_driver*, which is responsible for most parts of enumeration
-for a *struct usb\_gadget*. The response to a set\_configuration usually
-involves enabling one or more of the *struct usb\_ep* objects exposed by
-the gadget, and submitting one or more *struct usb\_request* buffers to
+Gadget drivers declare themselves through a struct
+:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
+for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
+involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
+the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
 transfer data. Understand those four data typ

Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 11:20:14 +0200
Markus Heiser  escreveu:

> Am 30.03.2017 um 10:21 schrieb Jani Nikula :
> 
> > On Thu, 30 Mar 2017, Markus Heiser  wrote:  
> >> Hi Mauro,
> >> 
> >> Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab 
> >> :
> >>   
> >>> As we're moving out of DocBook, let's convert the remaining
> >>> USB docbooks to ReST.
> >>> 
> >>> The transformation itself on this patch is a no-brainer
> >>> conversion using pandoc.  
> >> 
> >> right, its a no-brainer ;-) I'am not very happy with this
> >> conversions, some examples see below.
> >> 
> >> I recommend to use a more elaborate conversion as starting point,
> >> e.g. from my sphkerneldoc project:
> >> 
> >> * 
> >> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
> >> * 
> >> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
> >> * 
> >> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver
> >> 
> >> Since these DocBooks hasn't been changed in the last month, the linked reST
> >> should be up to date.  
> > 
> > Markus, I know you've done a lot of work on your conversions, and you
> > like to advocate them, but AFAICT you have never posted the conversions
> > as patches to the list. Your project isn't a clone of the kernel
> > tree. It's a pile of .rst files that nobody knows how to produce from
> > current upstream DocBook .tmpl files. I'm sorry, but this just doesn't
> > work that way.  
> 
> The conversion is done with the dbxml2rst tool:
> 
>   https://github.com/return42/dbxml2rst
> 
> But you are right, the links I send are decoupled from kernel. It is
> a 5 month old snapshot of a DocBook to reST conversion (now updated,
> with no affect to the linked files, since they have not been patched
> in the meantime) ...
> 
> > At this point I'd just go with what Mauro has. It's here now, as
> > patches. We've seen from the GPU documentation that polishing the
> > one-time initial conversion is, after a point, wasted effort. Having the
> > documentation in rst attracts more attention and contributions, and any
> > remaining issues will get ironed out in rst.  
> 
> I totally agree with you (I have never said something different)
> 
> > This is also one reason I'm in favor of just bulk converting the rest of
> > the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
> > and be done with it, and have the crowds focus on rst.  
> 
> I also agree with that. The tmplcvt script is good enough for this task,
> the dbxml2rst tool is more elaborate.

I like the idea of a bulk conversion. My personal preference here is to
use the tmplcvt for such task, at least for simple books like the ones
I converted from USB.

The advantage is that it places everything on a single rst file, with,
IMHO, works best for books that aren't too complex.

Of course, it doesn't hurt to compare the end result with dbxml2rst
and see if something could be improved.

> 
> If Jonathan also likes to have a bulk conversion of the rest DocBooks,
> we can use tmplcvt or even dbxml2rst for this task. Everything under
> 
>   
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated
> 
> is just a "make dbxm2rst", I can update every time and if a bulk conversion
> is the way ... I can send such patches or you send a tmplcvt conversion.
> 
> @Jon: what do you think about a bulk conversion?
> 
>  -- Markus --
>   


Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 12:34:32 +0300
Laurent Pinchart  escreveu:

> Hi Oliver,
> 
> On Thursday 30 Mar 2017 10:11:31 Oliver Neukum wrote:
> > Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:  
> > > > +   may also override PAD bytes at the end of the ``transfer_buffer``,
> > > > up to the
> > > > +   size of the CPU word.  
> > > 
> > > "May" is quite weak here. If some host controller drivers require buffers
> > > to be aligned, then it's an API requirement, and all buffers must be
> > > aligned. I'm not even sure I would mention that some host drivers require
> > > it, I think we should just state that the API requires buffers to be
> > > aligned.  
> > 
> > That effectively changes the API. Many network drivers are written with
> > the assumption that any contiguous buffer is valid. In fact you could
> > argue that those drivers are buggy and must use bounce buffers in those
> > cases.

Blaming the dwc2 driver was my first approach, but such patch got nacked ;)

Btw, the dwc2 driver has a routine that creates a temporary buffer if the
buffer pointer is not DWORD aligned. My first approach were to add
a logic there to also use the temporary buffer if the buffer size is
not DWORD aligned:
https://patchwork.linuxtv.org/patch/40093/

While debugging this issue, I saw *a lot* of network-generated URB
traffic from RPi3 Ethernet port drivers that were using non-aligned 
buffers and were subject to the temporary buffer conversion.

My understanding here is that having a temporary bounce buffer sucks,
as the performance and latency are affected. So, I see the value of
adding this constraint to the API, pushing the task of getting 
aligned buffers to the USB drivers, but you're right: that means a lot
of work, as all USB drivers should be reviewed.

Btw, I'm a lot more concerned about USB storage drivers. When I was
discussing about this issue at the #raspberrypi-devel IRC channel,
someone complained that, after switching from the RPi downstream Kernel
to upstream, his USB data storage got corrupted. Well, if the USB
storage drivers also assume that the buffer can be continuous,
that can corrupt data.

That's why I think that being verbose here is a good idea.

I'll rework on this patch to put more emphasis about this issue.

> > 
> > So we need to include the full story here.  
> 
> I personally don't care much about whose side is responsible for handling the 
> alignment constraints, but I want it to be documented before "fixing" any USB 
> driver.
> 



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 09/22] usb/bulk-streams.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../bulk-streams.txt => driver-api/usb/bulk-streams.rst}| 13 +
 Documentation/driver-api/usb/index.rst  |  1 +
 2 files changed, 10 insertions(+), 4 deletions(-)
 rename Documentation/{usb/bulk-streams.txt => driver-api/usb/bulk-streams.rst} 
(94%)

diff --git a/Documentation/usb/bulk-streams.txt 
b/Documentation/driver-api/usb/bulk-streams.rst
similarity index 94%
rename from Documentation/usb/bulk-streams.txt
rename to Documentation/driver-api/usb/bulk-streams.rst
index ffc02021863e..99b515babdeb 100644
--- a/Documentation/usb/bulk-streams.txt
+++ b/Documentation/driver-api/usb/bulk-streams.rst
@@ -1,3 +1,6 @@
+USB bulk streams
+
+
 Background
 ==
 
@@ -25,7 +28,9 @@ time.
 Driver implications
 ===
 
-int usb_alloc_streams(struct usb_interface *interface,
+::
+
+  int usb_alloc_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
unsigned int num_streams, gfp_t mem_flags);
 
@@ -53,7 +58,7 @@ controller driver, and may change in the future.
 
 
 Picking new Stream IDs to use
-
+=
 
 Stream ID 0 is reserved, and should not be used to communicate with devices.  
If
 usb_alloc_streams() returns with a value of N, you may use streams 1 though N.
@@ -68,9 +73,9 @@ Clean up
 
 
 If a driver wishes to stop using streams to communicate with the device, it
-should call
+should call::
 
-void usb_free_streams(struct usb_interface *interface,
+  void usb_free_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
gfp_t mem_flags);
 
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 5dfb04b2d730..6fe7611f7332 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -7,6 +7,7 @@ Linux USB API
usb
gadget
anchors
+   bulk-streams
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 02/22] driver-api/basics.rst: add device table header

[Mauro Carvalho Chehab]

The structs there at device table are used by other documentation
at the Kernel. So, add it to the driver API.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/basics.rst | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/driver-api/basics.rst 
b/Documentation/driver-api/basics.rst
index 935b9b8d456c..472e7a664d13 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -7,6 +7,12 @@ Driver Entry and Exit points
 .. kernel-doc:: include/linux/init.h
:internal:
 
+Driver device table
+---
+
+.. kernel-doc:: include/linux/mod_devicetable.h
+   :internal:
+
 Atomic and pointer manipulation
 ---
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 16/22] usb/URB.txt: convert to ReST and update it

[Mauro Carvalho Chehab]

The URB doc describes the Kernel mechanism that do USB transfers.
While the functions are already described at urb.h, there are a
number of concepts and theory that are important for USB driver
developers.

Convert it to ReST and use C ref links to point to the places
at usb.h where each function and struct is located.

A few of those descriptions were incomplete. While here, update
to reflect the current API status.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../{usb/URB.txt => driver-api/usb/URB.rst}| 205 -
 Documentation/driver-api/usb/index.rst |   1 +
 Documentation/driver-api/usb/usb.rst   |   2 +
 3 files changed, 119 insertions(+), 89 deletions(-)
 rename Documentation/{usb/URB.txt => driver-api/usb/URB.rst} (52%)

diff --git a/Documentation/usb/URB.txt b/Documentation/driver-api/usb/URB.rst
similarity index 52%
rename from Documentation/usb/URB.txt
rename to Documentation/driver-api/usb/URB.rst
index 50da0d455444..2bcd06c2c5aa 100644
--- a/Documentation/usb/URB.txt
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,16 +1,22 @@
-Revised: 2000-Dec-05.
-Again:   2002-Jul-06
-Again:   2005-Sep-19
+USB Request Block (URB)
+~~~
 
-NOTE:
+:Revised: 2000-Dec-05
+:Again:   2002-Jul-06
+:Again:   2005-Sep-19
+:Again:   2017-Mar-29
 
-The USB subsystem now has a substantial section in "The Linux Kernel API"
-guide (in Documentation/DocBook), generated from the current source
-code.  This particular documentation file isn't particularly current or
-complete; don't rely on it except for a quick overview.
 
+.. note::
 
-1.1. Basic concept or 'What is an URB?'
+The USB subsystem now has a substantial section at :ref:`usb-hostside-api`
+section, generated from the current source code.
+This particular documentation file isn't complete and may not be
+updated to the last version; don't rely on it except for a quick
+overview.
+
+Basic concept or 'What is an URB?'
+==
 
 The basic idea of the new driver is message passing, the message itself is 
 called USB Request Block, or URB for short. 
@@ -19,10 +25,11 @@ called USB Request Block, or URB for short.
   and deliver the data and status back. 
 
 - Execution of an URB is inherently an asynchronous operation, i.e. the 
-  usb_submit_urb(urb) call returns immediately after it has successfully
+  :c:func:`usb_submit_urb` call returns immediately after it has successfully
   queued the requested action.
 
-- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. 
+- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb`
+  at any time.
 
 - Each URB has a completion handler, which is called after the action
   has been successfully completed or canceled. The URB also contains a
@@ -35,53 +42,55 @@ called USB Request Block, or URB for short.
   of data to (or from) devices when using periodic transfer modes.
 
 
-1.2. The URB structure
+The URB structure
+=
 
-Some of the fields in an URB are:
+Some of the fields in struct :c:type:`urb` are::
 
-struct urb
-{
-// (IN) device and pipe specify the endpoint queue
+  struct urb
+  {
+  // (IN) device and pipe specify the endpoint queue
struct usb_device *dev; // pointer to associated USB device
unsigned int pipe;  // endpoint information
 
-   unsigned int transfer_flags;// ISO_ASAP, SHORT_NOT_OK, etc.
+   unsigned int transfer_flags;// URB_ISO_ASAP, URB_SHORT_NOT_OK, etc.
 
-// (IN) all urbs need completion routines
+  // (IN) all urbs need completion routines
void *context;  // context for completion routine
-   void (*complete)(struct urb *); // pointer to completion routine
+   usb_complete_t complete;// pointer to completion routine
 
-// (OUT) status after each completion
+  // (OUT) status after each completion
int status; // returned status
 
-// (IN) buffer used for data transfers
+  // (IN) buffer used for data transfers
void *transfer_buffer;  // associated data buffer
-   int transfer_buffer_length; // data buffer length
+   u32 transfer_buffer_length; // data buffer length
int number_of_packets;  // size of iso_frame_desc
 
-// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
-   int actual_length;  // actual data buffer length
+  // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
+   u32 actual_length;  // actual data buffer length
 
-// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
-   unsigned char* setup_packet;// setup packet (control only)
+  // (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
+   unsigned char *setup_packet;// setup packet (control only)
 
-// Only for PERIODIC transf

[PATCH v2 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Several host controllers, commonly found on ARM, like dwc2,
require buffers that are CPU-word aligned for they to work.

Failing to do that will cause random troubles at the caller
drivers, causing them to fail.

Document it.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/URB.rst | 12 
 drivers/usb/core/message.c   | 15 +++
 include/linux/usb.h  | 12 
 3 files changed, 39 insertions(+)

diff --git a/Documentation/driver-api/usb/URB.rst 
b/Documentation/driver-api/usb/URB.rst
index 810ceb0e71bb..2f3db660e613 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -271,6 +271,18 @@ If you specify your own start frame, make sure it's 
several frames in advance
 of the current frame.  You might want this model if you're synchronizing
 ISO data with some other event stream.
 
+ .. warning::
+
+   Several host drivers have a 32-bits or 64-bits DMA transfer word size,
+   with usually matches the CPU word. Due to such restriction, you should
+   warrant that the @transfer_buffer is DWORD aligned, on 32 bits system, or
+   QDWORD aligned, on 64 bits system. You should also ensure that the
+   buffer has enough space for PAD bits.
+
+   This condition is satisfied if you pass a buffer directly allocated by
+   kmalloc(), but this may not be the case if the driver allocates a bigger
+   buffer and point to a random place inside it.
+
 
 How to start interrupt (INT) transfers?
 ===
diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 4c38ea41ae96..1662a4446475 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct usb_device 
*usb_dev,
  * make sure your disconnect() method can wait for it to complete. Since you
  * don't have a handle on the URB used, you can't cancel the request.
  *
+ * .. note::
+ *
+ *   Several host drivers require that the @data buffer to be aligned
+ *   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
+ *   It is up to USB drivers should ensure that they'll only pass buffers
+ *   with such alignments.
+ *
+ *   Please also notice that, due to such restriction, the host driver
+ *   may also override PAD bytes at the end of the @data buffer, up to the
+ *   size of the CPU word.
+ *
+ *   Such word alignment condition is normally ensured if the buffer is
+ *   allocated with kmalloc(), but this may not be the case if the driver
+ *   allocates a bigger buffer and point to a random place inside it.
+ *
  * Return: If successful, the number of bytes transferred. Otherwise, a 
negative
  * error number.
  */
diff --git a/include/linux/usb.h b/include/linux/usb.h
index 7e68259360de..5739d4422343 100644
--- a/include/linux/usb.h
+++ b/include/linux/usb.h
@@ -1373,6 +1373,18 @@ typedef void (*usb_complete_t)(struct urb *);
  * capable, assign NULL to it, so that usbmon knows not to use the value.
  * The setup_packet must always be set, so it cannot be located in highmem.
  *
+ * .. warning::
+ *
+ *   Several host drivers have a 32-bits or 64-bits DMA transfer word size,
+ *   with usually matches the CPU word. Due to such restriction, you should
+ *   warrant that the @transfer_buffer is DWORD aligned, on 32 bits system, or
+ *   QDWORD aligned, on 64 bits system. You should also ensure that the
+ *   buffer has enough space for PAD bits.
+ *
+ *   This condition is satisfied if you pass a buffer directly allocated by
+ *   kmalloc(), but this may not be the case if the driver allocates a bigger
+ *   buffer and point to a random place inside it.
+ *
  * Initialization:
  *
  * All URBs submitted must initialize the dev, pipe, transfer_flags (may be
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 17/22] usb.rst: get rid of some Sphinx errors

[Mauro Carvalho Chehab]

Get rid of those warnings:

Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_type".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_dir".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_recip".
Documentation/driver-api/usb/usb.rst:679: ERROR: Unknown target name: 
"usbdevfs_urb_type".

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/usb.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index d15ab8ae5239..5ebaf669704c 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -615,8 +615,8 @@ USBDEVFS_CONTROL
 The first eight bytes of this structure are the contents of the
 SETUP packet to be sent to the device; see the USB 2.0 specification
 for details. The bRequestType value is composed by combining a
-USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\*
-value (from **). If wLength is nonzero, it describes
+``USB_TYPE_*`` value, a ``USB_DIR_*`` value, and a ``USB_RECIP_*``
+value (from ``linux/usb.h``). If wLength is nonzero, it describes
 the length of the data buffer, which is either written to the device
 (USB_DIR_OUT) or read from the device (USB_DIR_IN).
 
@@ -678,7 +678,7 @@ the blocking is separate.
 
 These requests are packaged into a structure that resembles the URB used
 by kernel device drivers. (No POSIX Async I/O support here, sorry.) It
-identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint
+identifies the endpoint type (``USBDEVFS_URB_TYPE_*``), endpoint
 (number, masked with USB_DIR_IN as appropriate), buffer and length,
 and a user "context" value serving to uniquely identify each request.
 (It's usually a pointer to per-request data.) Flags can modify requests
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 12/22] usb/dma.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../{usb/dma.txt => driver-api/usb/dma.rst}| 51 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 28 insertions(+), 24 deletions(-)
 rename Documentation/{usb/dma.txt => driver-api/usb/dma.rst} (79%)

diff --git a/Documentation/usb/dma.txt b/Documentation/driver-api/usb/dma.rst
similarity index 79%
rename from Documentation/usb/dma.txt
rename to Documentation/driver-api/usb/dma.rst
index 444651e70d95..59d5aee89e37 100644
--- a/Documentation/usb/dma.txt
+++ b/Documentation/driver-api/usb/dma.rst
@@ -1,16 +1,19 @@
+USB DMA
+~~~
+
 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
+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
-Documentation/DMA-API-HOWTO.txt).  That's how they've worked through
-the 2.4 (and earlier) kernels.
+``Documentation/DMA-API-HOWTO.txt``).  That's how they've worked through
+the 2.4 (and earlier) kernels, or they can now be DMA-aware.
 
-OR:  they can now be DMA-aware.
+DMA-aware usb drivers:
 
 - New calls enable DMA-aware drivers, letting them allocate dma buffers and
   manage dma mappings for existing dma-ready buffers (see below).
@@ -20,15 +23,15 @@ OR:  they can now be DMA-aware.
   drivers must not use it.)
 
 - "usbcore" will map this DMA address, if a DMA-aware driver didn't do
-  it first and set URB_NO_TRANSFER_DMA_MAP.  HCDs
+  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
   drivers.  Never use dma_set_mask() on any USB interface or device; that
   would potentially break all devices sharing that bus.
 
-
-ELIMINATING COPIES
+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.
@@ -41,7 +44,7 @@ and effects like cache-trashing can impose subtle penalties.
   For those specific cases, USB has primitives to allocate less expensive
   memory.  They work like kmalloc and kfree versions that give you the right
   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:
+  You'd also set ``URB_NO_TRANSFER_DMA_MAP`` in urb->transfer_flags::
 
void *usb_alloc_coherent (struct usb_device *dev, size_t size,
int mem_flags, dma_addr_t *dma);
@@ -49,15 +52,15 @@ and effects like cache-trashing can impose subtle penalties.
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
+  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.
+  :c:func:`kmalloc` will work just fine.
 
   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-API-HOWTO.txt for definitions of "coherent" and
+  ``Documentation/DMA-API-HOWTO.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
@@ -75,15 +78,15 @@ and effects like cache-trashing can impose subtle penalties.
   way to expose these capabilities ... and in any case, HIGHMEM is mostly a
   design wart specific to x86_32.  So your best bet is to ensure you never
   pass a highmem buffer into a USB driver.  That's easy; it's the default
-  behavior.  Just don't override it; e.g. with NETIF_F_HIGHDMA.
+  behavior.  Just don't override it; e.g. with ``NETIF_F_HIGHDMA``.
 
   This may force your callers to do some bounce buffering, copying from
   high memory to "normal" DMA memory.  If you can come up with a good way
   to fix this issue (for x86_32 machines with over 1 GByte of memory),
   feel free to submit patches.
 
-
-WORKING WITH EXISTING BUFFERS
+Working with existing buffers
+=
 
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  H

[PATCH v2 18/22] usb: get rid of some ReST doc build errors

[Mauro Carvalho Chehab]

We need an space before a numbered list to avoid those warnings:

./drivers/usb/core/message.c:478: ERROR: Unexpected indentation.
./drivers/usb/core/message.c:479: WARNING: Block quote ends without a blank 
line; unexpected unindent.
./include/linux/usb/composite.h:455: ERROR: Unexpected indentation.
./include/linux/usb/composite.h:456: WARNING: Block quote ends without a blank 
line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/usb/core/message.c| 1 +
 include/linux/usb/composite.h | 1 +
 2 files changed, 2 insertions(+)

diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 2184ef40a82a..4c38ea41ae96 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -474,6 +474,7 @@ EXPORT_SYMBOL_GPL(usb_sg_init);
  * significantly improve USB throughput.
  *
  * There are three kinds of completion for this function.
+ *
  * (1) success, where io->status is zero.  The number of io->bytes
  * transferred is as requested.
  * (2) error, where io->status is a negative errno value.  The number
diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 4616a49a1c2e..30a063e98c19 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -451,6 +451,7 @@ static inline struct usb_composite_driver *to_cdriver(
  * sure doing that won't hurt too much.
  *
  * One notion for how to handle Wireless USB devices involves:
+ *
  * (a) a second gadget here, discovery mechanism TBD, but likely
  * needing separate "register/unregister WUSB gadget" calls;
  * (b) updates to usb_gadget to include flags "is it wireless",
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 19/22] usb: composite.h: fix two warnings when building docs

[Mauro Carvalho Chehab]

By definition, we use /* private: */ tag when we won't be documenting
a parameter. However, those two parameters are documented:

./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef 
member 'setup_pending' description in 'usb_composite_dev'
./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef 
member 'os_desc_pending' description in 'usb_composite_dev'

So, we need to use /* public: */ to avoid a warning.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/usb/composite.h | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 30a063e98c19..f665d2ceac20 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -504,8 +504,9 @@ struct usb_composite_dev {
/* protects deactivations and delayed_status counts*/
spinlock_t  lock;
 
-   unsignedsetup_pending:1;
-   unsignedos_desc_pending:1;
+   /* public: */
+   unsigned intsetup_pending:1;
+   unsigned intos_desc_pending:1;
 };
 
 extern int usb_string_id(struct usb_composite_dev *c);
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 20/22] usb: gadget.h: be consistent at kernel doc macros

[Mauro Carvalho Chehab]

There's one value that use spaces instead of tabs to ident.
That causes the following warning:

./include/linux/usb/gadget.h:193: ERROR: Unexpected indentation.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/usb/gadget.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/usb/gadget.h b/include/linux/usb/gadget.h
index e4516e9ded0f..fbc22a39e7bc 100644
--- a/include/linux/usb/gadget.h
+++ b/include/linux/usb/gadget.h
@@ -188,7 +188,7 @@ struct usb_ep_caps {
  * @caps:The structure describing types and directions supported by endoint.
  * @maxpacket:The maximum packet size used on this endpoint.  The initial
  * value can sometimes be reduced (hardware allowing), according to
- *  the endpoint descriptor used to configure the endpoint.
+ * the endpoint descriptor used to configure the endpoint.
  * @maxpacket_limit:The maximum packet size value which can be handled by this
  * endpoint. It's set once by UDC driver when endpoint is initialized, and
  * should not be changed. Should not be confused with maxpacket.
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 07/22] writing_musb_glue_layer.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

This file is actually quite complex, and required several
manual handwork:

- add a title for the document;
- use the right tags for monospaced fonts;
- use c references where needed;
- adjust cross-reference to writing_usb_driver.rst
- hightlight cross-referenced lines.

With regards to C code snippet line highlights, the better would be
to use :linenos: for the C code snippets that are referenced by
the line number. However, at least with Sphinx 1.4.9, enabling
it cause the line number to be misaligned with the code,
making it even more confusing. So, instead, let's use
:emphasize-lines: tag to mark the lines that are referenced
at the text.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../driver-api/usb/writing_musb_glue_layer.rst | 598 ++---
 1 file changed, 292 insertions(+), 306 deletions(-)

diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst 
b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
index 52700c7031f9..e90e8fa95600 100644
--- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst
+++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
@@ -1,6 +1,6 @@
-==
-Writing an MUSB Glue Layer
-==
+=
+Writing a MUSB Glue Layer
+=
 
 :Author: Apelete Seketeli
 
@@ -21,10 +21,12 @@ design.
 As a self-taught exercise I have written an MUSB glue layer for the
 Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the
 kernel source tree. This layer can be found at
-drivers/usb/musb/jz4740.c. In this documentation I will walk through the
-basics of the jz4740.c glue layer, explaining the different pieces and
+``drivers/usb/musb/jz4740.c``. In this documentation I will walk through the
+basics of the ``jz4740.c`` glue layer, explaining the different pieces and
 what needs to be done in order to write your own device glue layer.
 
+.. _musb-basics:
+
 Linux MUSB Basics
 =
 
@@ -39,33 +41,30 @@ USB Device Drivers documentation (again, see Resources).
 
 Linux USB stack is a layered architecture in which the MUSB controller
 hardware sits at the lowest. The MUSB controller driver abstract the
-MUSB controller hardware to the Linux USB stack.
+MUSB controller hardware to the Linux USB stack::
 
-::
-
-  
-  |  | <--- drivers/usb/gadget
-  | Linux USB Core Stack | <--- drivers/usb/host
-  |  | <--- drivers/usb/core
-  
- ⬍
- --
- || <-- drivers/usb/musb/musb_gadget.c
- | MUSB Controller driver | <-- drivers/usb/musb/musb_host.c
- || <-- drivers/usb/musb/musb_core.c
- --
- ⬍
+ 
+ |  | <--- drivers/usb/gadget
+ | Linux USB Core Stack | <--- drivers/usb/host
+ |  | <--- drivers/usb/core
+ 
+⬍
+--
+|| <-- drivers/usb/musb/musb_gadget.c
+| MUSB Controller driver | <-- drivers/usb/musb/musb_host.c
+|| <-- drivers/usb/musb/musb_core.c
+--
+⬍
   -
   | MUSB Platform Specific Driver |
   |   | <-- drivers/usb/musb/jz4740.c
   |   aka "Glue Layer"|
   -
- ⬍
+⬍
   -
   |   MUSB Controller Hardware|
   -
 
-
 As outlined above, the glue layer is actually the platform specific code
 sitting in between the controller driver and the controller hardware.
 
@@ -78,37 +77,32 @@ about an embedded controller chip here, so no insertion or 
removal at
 run-time.
 
 All of this information is passed to the MUSB controller driver through
-a platform_driver structure defined in the glue layer as:
-
-::
+a :c:type:`platform_driver` structure defined in the glue layer as::
 
 static struct platform_driver jz4740_driver = {
-.probe  = jz4740_probe,
-.remove = jz4740_remove,
-.driver = {
-.name   = "musb-jz4740",
-},
+   .probe  = jz4740_probe,
+   .remove = jz4740_remove,
+   .driver = {
+   .name   = "musb-jz4740",
+   },
 };
 
-
 The probe and remove function pointers are called when a matching device
 is detected and, respectively, released. The name string describes the
 device supported by this glue laye

[PATCH v2 21/22] docs-rst: fix usb cross-references

[Mauro Carvalho Chehab]

As some USB documentation files got moved, adjust their
cross-references to their new place.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ABI/stable/sysfs-bus-usb| 2 +-
 Documentation/driver-api/usb/URB.rst  | 2 ++
 Documentation/driver-api/usb/callbacks.rst| 4 ++--
 Documentation/driver-api/usb/error-codes.rst  | 2 ++
 Documentation/driver-api/usb/persist.rst  | 2 ++
 Documentation/driver-api/usb/power-management.rst | 2 +-
 Documentation/driver-api/usb/usb.rst  | 4 ++--
 Documentation/power/swsusp.txt| 2 +-
 drivers/staging/most/hdm-usb/hdm_usb.c| 2 +-
 drivers/usb/core/Kconfig  | 2 +-
 10 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-bus-usb 
b/Documentation/ABI/stable/sysfs-bus-usb
index 831f15d9672f..b832eeff 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -9,7 +9,7 @@ Description:
hubs this facility is always enabled and their device
directories will not contain this file.
 
-   For more information, see Documentation/usb/persist.txt.
+   For more information, see 
Documentation/driver-api/usb/persist.rst.
 
 What:  /sys/bus/usb/devices/.../power/autosuspend
 Date:  March 2007
diff --git a/Documentation/driver-api/usb/URB.rst 
b/Documentation/driver-api/usb/URB.rst
index 2bcd06c2c5aa..810ceb0e71bb 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,3 +1,5 @@
+.. _usb-urb:
+
 USB Request Block (URB)
 ~~~
 
diff --git a/Documentation/driver-api/usb/callbacks.rst 
b/Documentation/driver-api/usb/callbacks.rst
index 93a8d53e27e7..2b80cf54bcc3 100644
--- a/Documentation/driver-api/usb/callbacks.rst
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -8,7 +8,7 @@ Usbcore will call into a driver through callbacks defined in 
the driver
 structure and through the completion handler of URBs a driver submits.
 Only the former are in the scope of this document. These two kinds of
 callbacks are completely independent of each other. Information on the
-completion callback can be found in Documentation/usb/URB.txt.
+completion callback can be found in :ref:`usb-urb`.
 
 The callbacks defined in the driver structure are:
 
@@ -53,7 +53,7 @@ The callbacks defined in the driver structure are:
 
 The ioctl interface (2) should be used only if you have a very good
 reason. Sysfs is preferred these days. The PM callbacks are covered
-separately in Documentation/usb/power-management.txt.
+separately in :ref:`usb-power-management`.
 
 Calling conventions
 ===
diff --git a/Documentation/driver-api/usb/error-codes.rst 
b/Documentation/driver-api/usb/error-codes.rst
index 9c11a0fd16cb..a3e84bfac776 100644
--- a/Documentation/driver-api/usb/error-codes.rst
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -1,3 +1,5 @@
+.. _usb-error-codes:
+
 USB Error codes
 ~~~
 
diff --git a/Documentation/driver-api/usb/persist.rst 
b/Documentation/driver-api/usb/persist.rst
index ea1b43f0559e..08cafc6292c1 100644
--- a/Documentation/driver-api/usb/persist.rst
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,3 +1,5 @@
+.. _usb-persist:
+
 USB device persistence during system suspend
 
 
diff --git a/Documentation/driver-api/usb/power-management.rst 
b/Documentation/driver-api/usb/power-management.rst
index c068257f6d27..79beb807996b 100644
--- a/Documentation/driver-api/usb/power-management.rst
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -328,7 +328,7 @@ possible to work around the hibernation-forces-disconnect 
problem by
 using the USB Persist facility.)
 
 The ``reset_resume`` method is used by the USB Persist facility (see
-``Documentation/usb/persist.txt``) and it can also be used under certain
+:ref:`usb-persist`) and it can also be used under certain
 circumstances when ``CONFIG_USB_PERSIST`` is not enabled.  Currently, if a
 device is reset during a resume and the driver does not have a
 ``reset_resume`` method, the driver won't receive any notification about
diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index 5ebaf669704c..6824089ef4c8 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -424,8 +424,8 @@ header.
 Unless noted otherwise, the ioctl requests described here will update
 the modification time on the usbfs file to which they are applied
 (unless they fail). A return of zero indicates success; otherwise, a
-standard USB error code is returned. (These are documented in
-``Documentation/usb/error-codes.txt`` in your kernel sources.)
+standard USB error code is returned (These are documented in
+:ref:`usb-error-codes`).
 
 Each of these files multiplexes access to several I/O st

[PATCH v2 05/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- use the proper warning and note markups;
- use kernel-doc to include Kernel header and c files;
- remove legacy notes with regards to DocBook;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/gadget.rst | 127 +---
 1 file changed, 52 insertions(+), 75 deletions(-)

diff --git a/Documentation/driver-api/usb/gadget.rst 
b/Documentation/driver-api/usb/gadget.rst
index 52b299b1ca6d..3e8a3809c0b8 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -38,7 +38,7 @@ address a number of important problems, including:
resources.
 
 Most Linux developers will not be able to use this API, since they have
-USB "host" hardware in a PC, workstation, or server. Linux users with
+USB ``host`` hardware in a PC, workstation, or server. Linux users with
 embedded systems are more likely to have USB peripheral hardware. To
 distinguish drivers running inside such hardware from the more familiar
 Linux "USB device drivers", which are host side proxies for the real USB
@@ -64,7 +64,7 @@ Structure of Gadget Drivers
 
 A system running inside a USB peripheral normally has at least three
 layers inside the kernel to handle USB protocol processing, and may have
-additional layers in user space code. The "gadget" API is used by the
+additional layers in user space code. The ``gadget`` API is used by the
 middle layer to interact with the lowest level (which directly handles
 hardware).
 
@@ -143,13 +143,13 @@ In Linux, from the bottom up, these layers are:
 *Additional Layers*
 Other layers may exist. These could include kernel layers, such as
 network protocol stacks, as well as user mode applications building
-on standard POSIX system call APIs such as *open()*, *close()*,
-*read()* and *write()*. On newer systems, POSIX Async I/O calls may
+on standard POSIX system call APIs such as ``open()``, ``close()``,
+``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may
 be an option. Such user mode code will not necessarily be subject to
 the GNU General Public License (GPL).
 
 OTG-capable systems will also need to include a standard Linux-USB host
-side stack, with *usbcore*, one or more *Host Controller Drivers*
+side stack, with ``usbcore``, one or more *Host Controller Drivers*
 (HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
 List", and so forth. There will also be an *OTG Controller Driver*,
 which is visible to gadget and device driver developers only indirectly.
@@ -174,24 +174,20 @@ combined, to implement composite devices.
 Kernel Mode Gadget API
 ==
 
-Gadget drivers declare themselves through a *struct
-usb_gadget_driver*, which is responsible for most parts of enumeration
-for a *struct usb_gadget*. The response to a set_configuration usually
-involves enabling one or more of the *struct usb_ep* objects exposed by
-the gadget, and submitting one or more *struct usb_request* buffers to
+Gadget drivers declare themselves through a struct
+:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
+for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
+involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
+the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
 transfer data. Understand those four data types, and their operations,
 and you will understand how this API works.
 
-**Note**
+.. Note::
 
-This documentation was prepared using the standard Linux kernel
-``docproc`` tool, which turns text and in-code comments into SGML
-DocBook and then into usable formats such as HTML or PDF. Other than
-the "Chapter 9" data types, most of the significant data types and
-functions are described here.
+Other than the "Chapter 9" data types, most of the significant data
+types and functions are described here.
 
-However, docproc does not understand all the C constructs that are
-used, so some relevant information is likely omitted from what you
+However, some relevant information is likely omitted from what you
 are reading. One example of such information is endpoint
 autoconfiguration. You'll have to read the header file, and use
 example source code (such as that for "Gadget Zero"), to fully
@@ -199,10 +195,10 @@ and you will understand how this API works.
 
 The part of the API implementing some basic driver capabilities is
 specific to the version of the Linux kernel that's in use. The 2.6
-kernel includes a *driver model* framework that has no analogue on
-earlier kernels; so those parts of the gadget API are n

[PATCH v2 10/22] usb/callbacks.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../callbacks.txt => driver-api/usb/callbacks.rst} | 61 +++---
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 43 insertions(+), 19 deletions(-)
 rename Documentation/{usb/callbacks.txt => driver-api/usb/callbacks.rst} (78%)

diff --git a/Documentation/usb/callbacks.txt 
b/Documentation/driver-api/usb/callbacks.rst
similarity index 78%
rename from Documentation/usb/callbacks.txt
rename to Documentation/driver-api/usb/callbacks.rst
index 9e85846bdb98..93a8d53e27e7 100644
--- a/Documentation/usb/callbacks.txt
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -1,3 +1,6 @@
+USB core callbacks
+~~
+
 What callbacks will usbcore do?
 ===
 
@@ -11,30 +14,42 @@ The callbacks defined in the driver structure are:
 
 1. Hotplugging callbacks:
 
- * @probe: Called to see if the driver is willing to manage a particular
- * interface on a device.
- * @disconnect: Called when the interface is no longer accessible, usually
- * because its device has been (or is being) disconnected or the
- * driver module is being unloaded.
+ - @probe:
+   Called to see if the driver is willing to manage a particular
+   interface on a device.
+
+ - @disconnect:
+   Called when the interface is no longer accessible, usually
+   because its device has been (or is being) disconnected or the
+   driver module is being unloaded.
 
 2. Odd backdoor through usbfs:
 
- * @ioctl: Used for drivers that want to talk to userspace through
- * the "usbfs" filesystem.  This lets devices provide ways to
- * expose information to user space regardless of where they
- * do (or don't) show up otherwise in the filesystem.
+ - @ioctl:
+   Used for drivers that want to talk to userspace through
+   the "usbfs" filesystem.  This lets devices provide ways to
+   expose information to user space regardless of where they
+   do (or don't) show up otherwise in the filesystem.
 
 3. Power management (PM) callbacks:
 
- * @suspend: Called when the device is going to be suspended.
- * @resume: Called when the device is being resumed.
- * @reset_resume: Called when the suspended device has been reset instead
- * of being resumed.
+ - @suspend:
+   Called when the device is going to be suspended.
+
+ - @resume:
+   Called when the device is being resumed.
+
+ - @reset_resume:
+   Called when the suspended device has been reset instead
+   of being resumed.
 
 4. Device level operations:
 
- * @pre_reset: Called when the device is about to be reset.
- * @post_reset: Called after the device has been reset
+ - @pre_reset:
+   Called when the device is about to be reset.
+
+ - @post_reset:
+   Called after the device has been reset
 
 The ioctl interface (2) should be used only if you have a very good
 reason. Sysfs is preferred these days. The PM callbacks are covered
@@ -58,7 +73,9 @@ an interface. A driver's bond to an interface is exclusive.
 The probe() callback
 
 
-int (*probe) (struct usb_interface *intf,
+::
+
+  int (*probe) (struct usb_interface *intf,
const struct usb_device_id *id);
 
 Accept or decline an interface. If you accept the device return 0,
@@ -75,7 +92,9 @@ initialisation that doesn't take too long is a good idea here.
 The disconnect() callback
 -
 
-void (*disconnect) (struct usb_interface *intf);
+::
+
+  void (*disconnect) (struct usb_interface *intf);
 
 This callback is a signal to break any connection with an interface.
 You are not allowed any IO to a device after returning from this
@@ -93,7 +112,9 @@ Device level callbacks
 pre_reset
 -
 
-int (*pre_reset)(struct usb_interface *intf);
+::
+
+  int (*pre_reset)(struct usb_interface *intf);
 
 A driver or user space is triggering a reset on the device which
 contains the interface passed as an argument. Cease IO, wait for all
@@ -107,7 +128,9 @@ are in atomic context.
 post_reset
 --
 
-int (*post_reset)(struct usb_interface *intf);
+::
+
+  int (*post_reset)(struct usb_interface *intf);
 
 The reset has completed.  Restore any saved device state and begin
 using the device again.
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 6fe7611f7332..441c5dacdf27 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -8,6 +8,7 @@ Linux USB API
gadget
anchors
bulk-streams
+   callbacks
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 01/22] tmplcvt: make the tool more robust

[Mauro Carvalho Chehab]

Currently, the script just assumes to be called at
Documentation/sphinx/. Change it to work on any directory,
and make it abort if something gets wrong.

Also, be sure that both parameters are specified.

That should avoid troubles like this:

$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
sed: couldn't open file convert_template.sed: No such file or directory

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/sphinx/tmplcvt | 13 +++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
index 909a73065e0a..31df8eb7feca 100755
--- a/Documentation/sphinx/tmplcvt
+++ b/Documentation/sphinx/tmplcvt
@@ -7,13 +7,22 @@
 # fix \_
 # title line?
 #
+set -eu
+
+if [ "$2" == "" ]; then
+   echo "$0  "
+   exit
+fi
+
+DIR=$(dirname $0)
 
 in=$1
 rst=$2
 tmp=$rst.tmp
 
 cp $in $tmp
-sed --in-place -f convert_template.sed $tmp
+sed --in-place -f $DIR/convert_template.sed $tmp
 pandoc -s -S -f docbook -t rst -o $rst $tmp
-sed --in-place -f post_convert.sed $rst
+sed --in-place -f $DIR/post_convert.sed $rst
 rm $tmp
+echo "book writen to $rst"
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 11/22] usb/power-management.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/index.rst |   1 +
 .../usb/power-management.rst}  | 404 +++--
 2 files changed, 214 insertions(+), 191 deletions(-)
 rename Documentation/{usb/power-management.txt => 
driver-api/usb/power-management.rst} (69%)

diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 441c5dacdf27..23c76c17fc19 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -9,6 +9,7 @@ Linux USB API
anchors
bulk-streams
callbacks
+   power-management
writing_usb_driver
writing_musb_glue_layer
 
diff --git a/Documentation/usb/power-management.txt 
b/Documentation/driver-api/usb/power-management.rst
similarity index 69%
rename from Documentation/usb/power-management.txt
rename to Documentation/driver-api/usb/power-management.rst
index 00e706997130..c068257f6d27 100644
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -1,10 +1,12 @@
-   Power Management for USB
+.. _usb-power-management:
 
-Alan Stern 
-
-  Last-updated: February 2014
+Power Management for USB
+
 
+:Author: Alan Stern 
+:Date: Last-updated: February 2014
 
+..
Contents:
-
* What is Power Management?
@@ -25,14 +27,14 @@
* Suggested Userspace Port Power Policy
 
 
-   What is Power Management?
-   -
+What is Power Management?
+-
 
 Power Management (PM) is the practice of saving energy by suspending
 parts of a computer system when they aren't being used.  While a
-component is "suspended" it is in a nonfunctional low-power state; it
+component is ``suspended`` it is in a nonfunctional low-power state; it
 might even be turned off completely.  A suspended component can be
-"resumed" (returned to a functional full-power state) when the kernel
+``resumed`` (returned to a functional full-power state) when the kernel
 needs to use it.  (There also are forms of PM in which components are
 placed in a less functional but still usable state instead of being
 suspended; an example would be reducing the CPU's clock rate.  This
@@ -44,22 +46,25 @@ device is turned off while the system as a whole remains 
running, we
 call it a "dynamic suspend" (also known as a "runtime suspend" or
 "selective suspend").  This document concentrates mostly on how
 dynamic PM is implemented in the USB subsystem, although system PM is
-covered to some extent (see Documentation/power/*.txt for more
+covered to some extent (see ``Documentation/power/*.txt`` for more
 information about system PM).
 
-System PM support is present only if the kernel was built with CONFIG_SUSPEND
-or CONFIG_HIBERNATION enabled.  Dynamic PM support for USB is present whenever
-the kernel was built with CONFIG_PM enabled.
+System PM support is present only if the kernel was built with
+``CONFIG_SUSPEND`` or ``CONFIG_HIBERNATION`` enabled.  Dynamic PM support
+
+for USB is present whenever
+the kernel was built with ``CONFIG_PM`` enabled.
 
 [Historically, dynamic PM support for USB was present only if the
-kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on
-CONFIG_PM_RUNTIME).  Starting with the 3.10 kernel release, dynamic PM support
-for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME
-enabled.  The CONFIG_USB_SUSPEND option had been eliminated.]
+kernel had been built with ``CONFIG_USB_SUSPEND`` enabled (which depended on
+``CONFIG_PM_RUNTIME``).  Starting with the 3.10 kernel release, dynamic PM
+support for USB was present whenever the kernel was built with
+``CONFIG_PM_RUNTIME`` enabled.  The ``CONFIG_USB_SUSPEND`` option had been
+eliminated.]
 
 
-   What is Remote Wakeup?
-   --
+What is Remote Wakeup?
+--
 
 When a device has been suspended, it generally doesn't resume until
 the computer tells it to.  Likewise, if the entire computer has been
@@ -76,8 +81,8 @@ event.  Examples include a suspended keyboard resuming when a 
key is
 pressed, or a suspended USB hub resuming when a device is plugged in.
 
 
-   When is a USB device idle?
-   --
+When is a USB device idle?
+--
 
 A device is idle whenever the kernel thinks it's not busy doing
 anything important and thus is a candidate for being suspended.  The
@@ -92,11 +97,11 @@ If a USB device has no driver, its usbfs file isn't open, 
and it isn't
 being accessed through sysfs, then it definitely is idle.
 
 
-   Forms of dynamic PM
-   ---
+Forms of dynamic PM
+---
 
 

[PATCH v2 06/22] writing_usb_driver.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- adjust function and struct references;
- use monospaced fonts for C code names;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../driver-api/usb/writing_usb_driver.rst  | 182 ++---
 1 file changed, 82 insertions(+), 100 deletions(-)

diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst 
b/Documentation/driver-api/usb/writing_usb_driver.rst
index c18dbd74152b..69f077dcdb78 100644
--- a/Documentation/driver-api/usb/writing_usb_driver.rst
+++ b/Documentation/driver-api/usb/writing_usb_driver.rst
@@ -1,3 +1,5 @@
+.. _writing-usb-driver:
+
 ==
 Writing USB Device Drivers
 ==
@@ -48,25 +50,23 @@ The first thing a Linux USB driver needs to do is register 
itself with
 the Linux USB subsystem, giving it some information about which devices
 the driver supports and which functions to call when a device supported
 by the driver is inserted or removed from the system. All of this
-information is passed to the USB subsystem in the usb_driver structure.
-The skeleton driver declares a usb_driver as:
-
-::
+information is passed to the USB subsystem in the :c:type:`usb_driver`
+structure. The skeleton driver declares a :c:type:`usb_driver` as::
 
 static struct usb_driver skel_driver = {
-.name= "skeleton",
-.probe   = skel_probe,
-.disconnect  = skel_disconnect,
-.fops= &skel_fops,
-.minor   = USB_SKEL_MINOR_BASE,
-.id_table= skel_table,
+   .name= "skeleton",
+   .probe   = skel_probe,
+   .disconnect  = skel_disconnect,
+   .fops= &skel_fops,
+   .minor   = USB_SKEL_MINOR_BASE,
+   .id_table= skel_table,
 };
 
 
 The variable name is a string that describes the driver. It is used in
 informational messages printed to the system log. The probe and
 disconnect function pointers are called when a device that matches the
-information provided in the id_table variable is either seen or
+information provided in the ``id_table`` variable is either seen or
 removed.
 
 The fops and minor variables are optional. Most USB drivers hook into
@@ -76,78 +76,70 @@ subsystem, and any user-space interactions are provided 
through that
 interface. But for drivers that do not have a matching kernel subsystem,
 such as MP3 players or scanners, a method of interacting with user space
 is needed. The USB subsystem provides a way to register a minor device
-number and a set of file_operations function pointers that enable this
-user-space interaction. The skeleton driver needs this kind of
+number and a set of :c:type:`file_operations` function pointers that enable
+this user-space interaction. The skeleton driver needs this kind of
 interface, so it provides a minor starting number and a pointer to its
-file_operations functions.
+:c:type:`file_operations` functions.
 
-The USB driver is then registered with a call to usb_register, usually
-in the driver's init function, as shown here:
-
-::
+The USB driver is then registered with a call to :c:func:`usb_register`,
+usually in the driver's init function, as shown here::
 
 static int __init usb_skel_init(void)
 {
-int result;
+   int result;
 
-/* register this driver with the USB subsystem */
-result = usb_register(&skel_driver);
-if (result < 0) {
-err("usb_register failed for the "__FILE__ "driver."
-"Error number %d", result);
-return -1;
-}
+   /* register this driver with the USB subsystem */
+   result = usb_register(&skel_driver);
+   if (result < 0) {
+   err("usb_register failed for the "__FILE__ "driver."
+   "Error number %d", result);
+   return -1;
+   }
 
-return 0;
+   return 0;
 }
 module_init(usb_skel_init);
 
 
 When the driver is unloaded from the system, it needs to deregister
-itself with the USB subsystem. This is done with the usb_deregister
-function:
-
-::
+itself with the USB subsystem. This is done with the :c:func:`usb_deregister`
+function::
 
 static void __exit usb_skel_exit(void)
 {
-/* deregister this driver with the USB subsystem */
-usb_deregister(&skel_driver);
+   /* deregister this driver with the USB subsystem */
+   usb_deregister(&skel_driver);
 }
 module_exit(usb_skel_exit);
 
 
 To enable the linux-hotplug system to load the driver automatically when
-the device is plugged in, you need 

[PATCH v2 15/22] usb/persist.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/index.rst |  1 +
 .../persist.txt => driver-api/usb/persist.rst} | 22 +-
 2 files changed, 14 insertions(+), 9 deletions(-)
 rename Documentation/{usb/persist.txt => driver-api/usb/persist.rst} (94%)

diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 43f0a8b72b11..3f08cb5d5feb 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -12,6 +12,7 @@ Linux USB API
dma
power-management
hotplug
+   persist
error-codes
writing_usb_driver
writing_musb_glue_layer
diff --git a/Documentation/usb/persist.txt 
b/Documentation/driver-api/usb/persist.rst
similarity index 94%
rename from Documentation/usb/persist.txt
rename to Documentation/driver-api/usb/persist.rst
index 35d70eda9ad6..ea1b43f0559e 100644
--- a/Documentation/usb/persist.txt
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,11 +1,12 @@
-   USB device persistence during system suspend
+USB device persistence during system suspend
+
 
-  Alan Stern 
+:Author: Alan Stern 
+:Date: September 2, 2006 (Updated February 25, 2008)
 
-   September 2, 2006 (Updated February 25, 2008)
 
-
-   What is the problem?
+What is the problem?
+
 
 According to the USB specification, when a USB bus is suspended the
 bus must continue to supply suspend current (around 1-5 mA).  This
@@ -63,7 +64,8 @@ suspended -- but it will crash as soon as it wakes up, which 
isn't
 much better.)
 
 
-   What is the solution?
+What is the solution?
+=
 
 The kernel includes a feature called USB-persist.  It tries to work
 around these issues by allowing the core USB device data structures to
@@ -99,7 +101,7 @@ now a good and happy place.
 
 Note that the "USB-persist" feature will be applied only to those
 devices for which it is enabled.  You can enable the feature by doing
-(as root):
+(as root)::
 
echo 1 >/sys/bus/usb/devices/.../power/persist
 
@@ -110,7 +112,8 @@ doesn't even exist, so you only have to worry about setting 
it for
 devices where it really matters.
 
 
-   Is this the best solution?
+Is this the best solution?
+==
 
 Perhaps not.  Arguably, keeping track of mounted filesystems and
 memory mappings across device disconnects should be handled by a
@@ -130,7 +133,8 @@ just mass-storage devices.  It might turn out to be equally 
useful for
 other device types, such as network interfaces.
 
 
-   WARNING: USB-persist can be dangerous!!
+WARNING: USB-persist can be dangerous!!
+===
 
 When recovering an interrupted power session the kernel does its best
 to make sure the USB device hasn't been changed; that is, the same
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 04/22] usb.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

- use the proper warning and note markups;
- add references for parts of the document that will be
  cross-referenced on other USB docs;
- some minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/usb.rst | 48 +---
 1 file changed, 17 insertions(+), 31 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index b856abb3200e..7e820768ee4f 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -102,6 +102,8 @@ disconnect testing (while the device is active) with each 
different host
 controller driver, to make sure drivers don't have bugs of their own as
 well as to make sure they aren't relying on some HCD-specific behavior.
 
+.. _usb_chapter9:
+
 USB-Standard Types
 ==
 
@@ -112,6 +114,8 @@ USB, and in APIs including this host side API, gadget APIs, 
and usbfs.
 .. kernel-doc:: include/linux/usb/ch9.h
:internal:
 
+.. _usb_header:
+
 Host-Side Data Types and Macros
 ===
 
@@ -209,7 +213,7 @@ library that wraps it. Such libraries include
 `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
 `jUSB <http://jUSB.sourceforge.net>`__ for Java.
 
-**Note**
+.. note::
 
 This particular documentation is incomplete, especially with respect
 to the asynchronous mode. As of kernel 2.5.66 the code and this
@@ -319,9 +323,7 @@ files. For information about the current format of this 
file, see the
 sources.
 
 This file, in combination with the poll() system call, can also be used
-to detect when devices are added or removed:
-
-::
+to detect when devices are added or removed::
 
 int fd;
 struct pollfd pfd;
@@ -407,9 +409,7 @@ The ioctl() Requests
 
 
 To use these ioctls, you need to include the following headers in your
-userspace program:
-
-::
+userspace program::
 
 #include 
 #include 
@@ -458,9 +458,7 @@ USBDEVFS_CLAIMINTERFACE
 
 USBDEVFS_CONNECTINFO
 Says whether the device is lowspeed. The ioctl parameter points to a
-structure like this:
-
-::
+structure like this::
 
struct usbdevfs_connectinfo {
unsigned int   devnum;
@@ -477,9 +475,7 @@ USBDEVFS_CONNECTINFO
 USBDEVFS_GETDRIVER
 Returns the name of the kernel driver bound to a given interface (a
 string). Parameter is a pointer to this structure, which is
-modified:
-
-::
+modified::
 
struct usbdevfs_getdriver {
unsigned int  interface;
@@ -490,9 +486,7 @@ USBDEVFS_GETDRIVER
 
 USBDEVFS_IOCTL
 Passes a request from userspace through to a kernel driver that has
-an ioctl entry in the *struct usb_driver* it registered.
-
-::
+an ioctl entry in the *struct usb_driver* it registered::
 
struct usbdevfs_ioctl {
int ifno;
@@ -534,7 +528,7 @@ USBDEVFS_RELEASEINTERFACE
 the number of the interface (bInterfaceNumber from descriptor); File
 modification time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*No security check is made to ensure that the task which made
the claim is the one which is releasing it. This means that user
@@ -574,9 +568,7 @@ a time.
 
 USBDEVFS_BULK
 Issues a bulk read or write request to the device. The ioctl
-parameter is a pointer to this structure:
-
-::
+parameter is a pointer to this structure::
 
struct usbdevfs_bulktransfer {
unsigned int  ep;
@@ -606,9 +598,7 @@ USBDEVFS_CLEAR_HALT
 
 USBDEVFS_CONTROL
 Issues a control request to the device. The ioctl parameter points
-to a structure like this:
-
-::
+to a structure like this::
 
struct usbdevfs_ctrltransfer {
__u8   bRequestType;
@@ -638,7 +628,7 @@ USBDEVFS_RESET
 the reset, this rebinds all device interfaces. File modification
 time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -646,9 +636,7 @@ USBDEVFS_RESET
 
 USBDEVFS_SETINTERFACE
 Sets the alternate setting for an interface. The ioctl parameter is
-a pointer to a structure like this:
-
-::
+a pointer to a structure like this::
 
struct usbdevfs_setinterface {
unsigned int  interface;
@@ -669,7 +657,7 @@ USBDEVFS_SETCONFIGURATION
 configuration (bConfigurationValue from descriptor). File
 modification time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -702,9 +690,7 @@ When usbfs returns these urbs, the status value is updated, 
and the
 buffer 

[PATCH v2 13/22] error-codes.rst: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/error-codes.rst | 205 +++
 Documentation/driver-api/usb/index.rst   |   1 +
 Documentation/usb/error-codes.txt| 175 ---
 3 files changed, 206 insertions(+), 175 deletions(-)
 create mode 100644 Documentation/driver-api/usb/error-codes.rst
 delete mode 100644 Documentation/usb/error-codes.txt

diff --git a/Documentation/driver-api/usb/error-codes.rst 
b/Documentation/driver-api/usb/error-codes.rst
new file mode 100644
index ..9c11a0fd16cb
--- /dev/null
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -0,0 +1,205 @@
+USB Error codes
+~~~
+
+:Revised: 2004-Oct-21
+
+This is the documentation of (hopefully) all possible error codes (and
+their interpretation) that can be returned from usbcore.
+
+Some of them are returned by the Host Controller Drivers (HCDs), which
+device drivers only see through usbcore.  As a rule, all the HCDs should
+behave the same except for transfer speed dependent behaviors and the
+way certain faults are reported.
+
+
+Error codes returned by :c:func:`usb_submit_urb`
+
+
+Non-USB-specific:
+
+
+=== ===
+0  URB submission went fine
+
+``-ENOMEM``no memory for allocation of internal structures
+=== ===
+
+USB-specific:
+
+===
===
+``-EBUSY`` The URB is already active.
+
+``-ENODEV``specified USB-device or bus doesn't exist
+
+``-ENOENT``specified interface or endpoint does not exist or
+   is not enabled
+
+``-ENXIO`` host controller driver does not support queuing of
+   this type of urb.  (treat as a host controller bug.)
+
+``-EINVAL``a) Invalid transfer type specified (or not supported)
+   b) Invalid or unsupported periodic transfer interval
+   c) ISO: attempted to change transfer interval
+   d) ISO: ``number_of_packets`` is < 0
+   e) various other cases
+
+``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the
+   frames the URB would be scheduled in have already
+   expired.
+
+``-EFBIG`` Host controller driver can't schedule that many ISO
+   frames.
+
+``-EPIPE`` The pipe type specified in the URB doesn't match the
+   endpoint's actual type.
+
+``-EMSGSIZE``  (a) endpoint maxpacket size is zero; it is not usable
+   in the current interface altsetting.
+   (b) ISO packet is larger than the endpoint maxpacket.
+   (c) requested data transfer length is invalid: negative
+   or too large for the host controller.
+
+``-ENOSPC``This request would overcommit the usb bandwidth reserved
+   for periodic transfers (interrupt, isochronous).
+
+``-ESHUTDOWN`` The device or host controller has been disabled due to
+   some problem that could not be worked around.
+
+``-EPERM`` Submission failed because ``urb->reject`` was set.
+
+``-EHOSTUNREACH``  URB was rejected because the device is suspended.
+
+``-ENOEXEC``   A control URB doesn't contain a Setup packet.
+===
===
+
+Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` 
(for ISO)
+===
+
+USB device drivers may only test urb status values in completion handlers.
+This is because otherwise there would be a race between HCDs updating
+these values on one CPU, and device drivers testing them on another CPU.
+
+A transfer's actual_length may be positive even when an error has been
+reported.  That's because transfers often involve several packets, so that
+one or more packets could finish before an error stops further endpoint I/O.
+
+For isochronous URBs, the urb status value is non-zero only if the URB is
+unlinked, the device is removed, the host controller is disabled, or the total
+transferred length is less than the requested length and the
+``URB_SHORT_NOT_OK`` flag is set.  Completion handlers for isochronous URBs
+should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,
+``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame de

[PATCH v2 08/22] usb/anchors.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../anchors.txt => driver-api/usb/anchors.rst} | 36 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 21 insertions(+), 16 deletions(-)
 rename Documentation/{usb/anchors.txt => driver-api/usb/anchors.rst} (75%)

diff --git a/Documentation/usb/anchors.txt 
b/Documentation/driver-api/usb/anchors.rst
similarity index 75%
rename from Documentation/usb/anchors.txt
rename to Documentation/driver-api/usb/anchors.rst
index fe6a99a32bbd..4b248e691bd6 100644
--- a/Documentation/usb/anchors.txt
+++ b/Documentation/driver-api/usb/anchors.rst
@@ -1,3 +1,6 @@
+USB Anchors
+~~~
+
 What is anchor?
 ===
 
@@ -13,7 +16,7 @@ Allocation and Initialisation
 =
 
 There's no API to allocate an anchor. It is simply declared
-as struct usb_anchor. init_usb_anchor() must be called to
+as struct usb_anchor. :c:func:`init_usb_anchor` must be called to
 initialise the data structure.
 
 Deallocation
@@ -26,52 +29,53 @@ Association and disassociation of URBs with anchors
 ===
 
 An association of URBs to an anchor is made by an explicit
-call to usb_anchor_urb(). The association is maintained until
+call to :c:func:`usb_anchor_urb`. The association is maintained until
 an URB is finished by (successful) completion. Thus disassociation
 is automatic. A function is provided to forcibly finish (kill)
 all URBs associated with an anchor.
-Furthermore, disassociation can be made with usb_unanchor_urb()
+Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb`
 
 Operations on multitudes of URBs
 
 
-usb_kill_anchored_urbs()
-
+:c:func:`usb_kill_anchored_urbs`
+
 
 This function kills all URBs associated with an anchor. The URBs
 are called in the reverse temporal order they were submitted.
 This way no data can be reordered.
 
-usb_unlink_anchored_urbs()
---
+:c:func:`usb_unlink_anchored_urbs`
+--
+
 
 This function unlinks all URBs associated with an anchor. The URBs
 are processed in the reverse temporal order they were submitted.
-This is similar to usb_kill_anchored_urbs(), but it will not sleep.
+This is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep.
 Therefore no guarantee is made that the URBs have been unlinked when
 the call returns. They may be unlinked later but will be unlinked in
 finite time.
 
-usb_scuttle_anchored_urbs()

+:c:func:`usb_scuttle_anchored_urbs`
+---
 
 All URBs of an anchor are unanchored en masse.
 
-usb_wait_anchor_empty_timeout()

+:c:func:`usb_wait_anchor_empty_timeout`
+---
 
 This function waits for all URBs associated with an anchor to finish
 or a timeout, whichever comes first. Its return value will tell you
 whether the timeout was reached.
 
-usb_anchor_empty()
---
+:c:func:`usb_anchor_empty`
+--
 
 Returns true if no URBs are associated with an anchor. Locking
 is the caller's responsibility.
 
-usb_get_from_anchor()
--
+:c:func:`usb_get_from_anchor`
+-
 
 Returns the oldest anchored URB of an anchor. The URB is unanchored
 and returned with a reference. As you may mix URBs to several
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index cf2fa2e8d236..5dfb04b2d730 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -6,6 +6,7 @@ Linux USB API
 
usb
gadget
+   anchors
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 14/22] usb/hotplug.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../hotplug.txt => driver-api/usb/hotplug.rst} | 66 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 37 insertions(+), 30 deletions(-)
 rename Documentation/{usb/hotplug.txt => driver-api/usb/hotplug.rst} (76%)

diff --git a/Documentation/usb/hotplug.txt 
b/Documentation/driver-api/usb/hotplug.rst
similarity index 76%
rename from Documentation/usb/hotplug.txt
rename to Documentation/driver-api/usb/hotplug.rst
index 5b243f315b2c..79663e653ca1 100644
--- a/Documentation/usb/hotplug.txt
+++ b/Documentation/driver-api/usb/hotplug.rst
@@ -1,4 +1,9 @@
-LINUX HOTPLUGGING
+USB hotplugging
+~~~
+
+Linux Hotplugging
+=
+
 
 In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
 into the bus with power on.  In most cases, users expect the devices to become
@@ -30,11 +35,11 @@ Because some of those actions rely on information about 
drivers (metadata)
 that is currently available only when the drivers are dynamically linked,
 you get the best hotplugging when you configure a highly modular system.
 
+Kernel Hotplug Helper (``/sbin/hotplug``)
+=
 
-KERNEL HOTPLUG HELPER (/sbin/hotplug)
-
-There is a kernel parameter: /proc/sys/kernel/hotplug, which normally
-holds the pathname "/sbin/hotplug".  That parameter names a program
+There is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally
+holds the pathname ``/sbin/hotplug``.  That parameter names a program
 which the kernel may invoke at various times.
 
 The /sbin/hotplug program can be invoked by any subsystem as part of its
@@ -51,26 +56,26 @@ Hotplug software and other resources is available at:
 Mailing list information is also available at that site.
 
 
---
+USB Policy Agent
+
 
-
-USB POLICY AGENT
-
-The USB subsystem currently invokes /sbin/hotplug when USB devices
+The USB subsystem currently invokes ``/sbin/hotplug`` when USB devices
 are added or removed from system.  The invocation is done by the kernel
 hub workqueue [hub_wq], or else as part of root hub initialization
 (done by init, modprobe, kapmd, etc).  Its single command line parameter
 is the string "usb", and it passes these environment variables:
 
-ACTION ... "add", "remove"
-PRODUCT ... USB vendor, product, and version codes (hex)
-TYPE ... device class codes (decimal)
-INTERFACE ... interface 0 class codes (decimal)
+== 
+ACTION ``add``, ``remove``
+PRODUCTUSB vendor, product, and version codes (hex)
+TYPE   device class codes (decimal)
+INTERFACE  interface 0 class codes (decimal)
+== 
 
 If "usbdevfs" is configured, DEVICE and DEVFS are also passed.  DEVICE is
 the pathname of the device, and is useful for devices with multiple and/or
 alternate interfaces that complicate driver selection.  By design, USB
-hotplugging is independent of "usbdevfs":  you can do most essential parts
+hotplugging is independent of ``usbdevfs``:  you can do most essential parts
 of USB device setup without using that filesystem, and without running a
 user mode daemon to detect changes in system configuration.
 
@@ -79,19 +84,20 @@ modules, and can invoke driver-specific setup scripts.  The 
newest ones
 leverage USB module-init-tools support.  Later agents might unload drivers.
 
 
-USB MODUTILS SUPPORT
+USB Modutils Support
+
 
-Current versions of module-init-tools will create a "modules.usbmap" file
-which contains the entries from each driver's MODULE_DEVICE_TABLE.  Such
+Current versions of module-init-tools will create a ``modules.usbmap`` file
+which contains the entries from each driver's ``MODULE_DEVICE_TABLE``.  Such
 files can be used by various user mode policy agents to make sure all the
 right driver modules get loaded, either at boot time or later.
 
-See  for full information about such table entries; or look
+See ``linux/usb.h`` for full information about such table entries; or look
 at existing drivers.  Each table entry describes one or more criteria to
 be used when matching a driver to a device or class of devices.  The
 specific criteria are identified by bits set in "match_flags", paired
 with field values.  You can construct the criteria directly, or with
-macros such as these, and use driver_info to store more information.
+macros such as these, and use driver_info to store more information::
 
 USB_DEVICE (vendorId, productId)
... matching devices with specified vendor and product ids
@@ -103,7 +109,7 @@ macros such as these, and use driver_info to store more 
information.

Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 12:38:42 +0300
Laurent Pinchart  escreveu:

> Hi Mauro,
> 
> On Wednesday 29 Mar 2017 22:06:33 Mauro Carvalho Chehab wrote:
> > Em Thu, 30 Mar 2017 01:15:27 +0300 Laurent Pinchart escreveu:  
> > > On Wednesday 29 Mar 2017 15:54:21 Mauro Carvalho Chehab wrote:  
> > > > Several host controllers, commonly found on ARM, like dwc2,
> > > > require buffers that are CPU-word aligned for they to work.
> > > > 
> > > > Failing to do that will cause random troubles at the caller
> > > > drivers, causing them to fail.
> > > > 
> > > > Document it.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab 
> > > > ---
> > > > 
> > > >  Documentation/driver-api/usb/URB.rst | 18 ++
> > > >  drivers/usb/core/message.c   | 15 +++
> > > >  include/linux/usb.h  | 18 ++
> > > >  3 files changed, 51 insertions(+)
> > > > 
> > > > diff --git a/Documentation/driver-api/usb/URB.rst
> > > > b/Documentation/driver-api/usb/URB.rst index d9ea6a3996e7..b83b557e9891
> > > > 100644
> > > > --- a/Documentation/driver-api/usb/URB.rst
> > > > +++ b/Documentation/driver-api/usb/URB.rst
> > > > @@ -274,6 +274,24 @@ If you specify your own start frame, make sure it's
> > > > several frames in advance of the current frame.  You might want this
> > > > model
> > > > if you're synchronizing ISO data with some other event stream.
> > > > 
> > > > +.. note::
> > > > +
> > > > +   Several host drivers require that the ``transfer_buffer`` to be
> > > > aligned
> > > > +   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64
> > > > bits).  
> > > 
> > > Is it the CPU word size or the DMA transfer size ? I assume the latter,
> > > and I wouldn't be surprised if the alignment requirement was 32-bit on at
> > > least some of the 64-bit platforms.  
> > 
> > Yeah, it is actually the DMA transfer size. Yet, worse case scenario is that
> > the DMA transfer size to be 64 bits on 64 bits CPU.
> >   
> > > > +   It is up to USB drivers should ensure that they'll only pass buffers
> > > > +   with such alignments.
> > > > +
> > > > +   Please also notice that, due to such restriction, the host driver  
> > > 
> > > s/notice/note/ (and below as well) ?  
> > 
> > OK.
> >   
> > > > +   may also override PAD bytes at the end of the ``transfer_buffer``,
> > > > up to the
> > > > +   size of the CPU word.  
> > > 
> > > "May" is quite weak here. If some host controller drivers require buffers
> > > to be aligned, then it's an API requirement, and all buffers must be
> > > aligned. I'm not even sure I would mention that some host drivers require
> > > it, I think we should just state that the API requires buffers to be
> > > aligned.  
> > 
> > What I'm trying to say here is that, on a 32-bits system, if the driver do
> > a USB_DIR_IN transfer using some code similar to:
> > 
> > size = 4;
> > buffer = kmalloc(size, GFP_KERNEL);
> > 
> > usb_control_msg(udev, pipe, req, type, val, idx, buffer + 2, 2,   
> timeout);
> > usb_control_msg(udev, pipe, req, type, val, idx, buffer, size,   
> timeout);
> > 
> > Drivers like dwc2 will mess with the buffer.
> > 
> > The first transfer will actually work, due to a workaround inside the
> > driver that will create a temporary DWORD-aligned buffer, avoiding it
> > to go past the buffer.
> > 
> > However, the second transfer will destroy the data received from the
> > first usb_control_msg(), as it will write 4 bytes at the buffer.
> > 
> > Not all drivers would do that, though.
> > 
> > Please notice that, as kmalloc will always return a CPU-aligned buffer,
> > if the client do something like:
> > 
> > size = 2;
> > buffer = kmalloc(size, GFP_KERNEL);
> > 
> > usb_control_msg(udev, pipe, req, type, val, idx, buffer, 2, timeout);
> > 
> > What happens there is that the DMA engine will still write 4 bytes at
> > the buffer, but the 2 bytes that go past the end of buffer will be
> > written on a memory that will never be used.  
> 
> I understand that, but stating that host controller drivers "may" do this 
> won&

Re: [PATCH v2 01/22] tmplcvt: make the tool more robust

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 07:45:35 -0300
Mauro Carvalho Chehab  escreveu:

> Currently, the script just assumes to be called at
> Documentation/sphinx/. Change it to work on any directory,
> and make it abort if something gets wrong.
> 
> Also, be sure that both parameters are specified.
> 
> That should avoid troubles like this:
> 
> $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
> sed: couldn't open file convert_template.sed: No such file or directory
> 
> Signed-off-by: Mauro Carvalho Chehab 

Forgot to mention. The entire USB book, after this patch series,
generated with Sphinx 1.4.9, can be seen, in HTML, at:

http://www.infradead.org/~mchehab/kernel_docs/driver-api/usb/index.html

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 13:17:16 +0200
Markus Heiser  escreveu:

> Am 30.03.2017 um 12:12 schrieb Mauro Carvalho Chehab 
> :
> >>> At this point I'd just go with what Mauro has. It's here now, as
> >>> patches. We've seen from the GPU documentation that polishing the
> >>> one-time initial conversion is, after a point, wasted effort. Having the
> >>> documentation in rst attracts more attention and contributions, and any
> >>> remaining issues will get ironed out in rst.
> >> 
> >> I totally agree with you (I have never said something different)
> >>   
> >>> This is also one reason I'm in favor of just bulk converting the rest of
> >>> the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
> >>> and be done with it, and have the crowds focus on rst.
> >> 
> >> I also agree with that. The tmplcvt script is good enough for this task,
> >> the dbxml2rst tool is more elaborate.  
> > 
> > I like the idea of a bulk conversion. My personal preference here is to
> > use the tmplcvt for such task, at least for simple books like the ones
> > I converted from USB.
> > 
> > The advantage is that it places everything on a single rst file, with,
> > IMHO, works best for books that aren't too complex.
> > Of course, it doesn't hurt to compare the end result with dbxml2rst
> > and see if something could be improved.  
> 
> If it helps ... dbxml2rst also supports single file conversion  ... I updated:
> 
>   
> https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated

Ok, I double-checked the results from dbxml2rst with pandoc (via
the script). Those are the differences after running the following commands:

$ wget 
https://raw.githubusercontent.com/return42/sphkerneldoc/master/Documentation/books_migrated/writing_usb_driver/index.rst
$ Documentation/sphinx/tmplcvt 
Documentation/DocBook/writing_usb_driver.tmpl writing_usb_driver.rst
$ diff -uprBw writing_usb_driver.rst index.rst 

1) Author data:

-:Author: Greg Kroah-Hartman
+:author:Kroah-Hartman Greg
+:address:   g...@kroah.com

dbxml2rst inverted the author's name.  It also added author's e-mail.

IMHO, it is better to not have email address there, as it could be
outdated, but this is just my personal preference.

2) dbxml2rst added a copyright information:

+**Copyright** 2001-2002 : Greg Kroah-Hartman

This is a good thing.

3) dbxml2rst added a GPL information.

IMHO, we should add just one GPL information, per hole book
(and not per converted file).

4) dbxml2rst created some references that won't be unique:

+.. _intro:

That's a bad thing, as I bet most converted documents will have "intro"
sections.

5) dbxml2rst use ".. code-block:: c" instead of "::"

I prefer using "::"

6) dbxml2rst appends a commentary at the end:

+.. 
--
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/dbxml2rst). The origin XML comes
+.. from the linux kernel:
+..
+..   http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git
+.. 
--

7) dbxml2rst did a worse job with URB conversions:

-USB Home Page: http://www.usb.org
+USB Home Page: `http://www.usb.org <http://www.usb.org>`__

So, in summary, at least for this document, the only thing good with
dbxml2rst was that it filled the copyright info.

Maybe for more complex documents, it would do a better job.

Yet, in order to standardize it everywhere, I guess the best would be to
produce copyright data like:

.. include:: 

:Copyright: |copy| 2001-2002 : Greg Kroah-Hartman

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 15:05:30 +0300
Laurent Pinchart  escreveu:

> Hi Mauro,
> 
> On Thursday 30 Mar 2017 07:28:00 Mauro Carvalho Chehab wrote:
> > Em Thu, 30 Mar 2017 12:34:32 +0300 Laurent Pinchart escreveu:  
> > > On Thursday 30 Mar 2017 10:11:31 Oliver Neukum wrote:  
> > >> Am Donnerstag, den 30.03.2017, 01:15 +0300 schrieb Laurent Pinchart:  
> > >>>> +   may also override PAD bytes at the end of the
> > >>>> ``transfer_buffer``, up to the
> > >>>> +   size of the CPU word.  
> > >>> 
> > >>> "May" is quite weak here. If some host controller drivers require
> > >>> buffers to be aligned, then it's an API requirement, and all buffers
> > >>> must be aligned. I'm not even sure I would mention that some host
> > >>> drivers require it, I think we should just state that the API requires
> > >>> buffers to be aligned.  
> > >> 
> > >> That effectively changes the API. Many network drivers are written with
> > >> the assumption that any contiguous buffer is valid. In fact you could
> > >> argue that those drivers are buggy and must use bounce buffers in those
> > >> cases.  
> > 
> > Blaming the dwc2 driver was my first approach, but such patch got nacked ;)
> > 
> > Btw, the dwc2 driver has a routine that creates a temporary buffer if the
> > buffer pointer is not DWORD aligned. My first approach were to add
> > a logic there to also use the temporary buffer if the buffer size is
> > not DWORD aligned:
> > https://patchwork.linuxtv.org/patch/40093/
> > 
> > While debugging this issue, I saw *a lot* of network-generated URB
> > traffic from RPi3 Ethernet port drivers that were using non-aligned
> > buffers and were subject to the temporary buffer conversion.
> > 
> > My understanding here is that having a temporary bounce buffer sucks,
> > as the performance and latency are affected. So, I see the value of
> > adding this constraint to the API, pushing the task of getting
> > aligned buffers to the USB drivers,  
> 
> This could however degrade performances when the HCD can handle unaligned 
> buffers.

No, it won't degrade performance out there, except if the driver
would need to do double buffering due to such constraint. 

It will just waste memory.

> 
> > but you're right: that means a lot of work, as all USB drivers should be
> > reviewed.  
> 
> If we decide in the end to push the constraint on the USB device driver side, 
> then the dwc2 HCD driver should return an error when the buffer isn't 
> correctly aligned.

Yeah, with such constraint, either the HCD drivers or the USB core
should complain.

There is another option: to add a field, filled by te USB driver,
telling the core that the buffer is aligned, e. g. drivers would
be doing something like:

urb->transfer_buffer_align = 4;

Something similar could be filled by the HCD driver:

hc_driver->transfer_buffer_align = 4;

The core will then check if the alignment required by the HCD driver
is compatible with the buffer alignment ensured by the USB driver.
If it doesn't, then the core would create a temporary buffer for the
transfers.

No idea about how easy/hard would be to implement something like
that.

In such case, it could make sense to generate a warning that
the driver should be fixed, or that the performance would
decrease due to double-buffering.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 22/22] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Em Thu, 30 Mar 2017 10:26:32 -0400 (EDT)
Alan Stern  escreveu:

> On Thu, 30 Mar 2017, Oliver Neukum wrote:
> 
> > > Btw, I'm a lot more concerned about USB storage drivers. When I was
> > > discussing about this issue at the #raspberrypi-devel IRC channel,
> > > someone complained that, after switching from the RPi downstream Kernel
> > > to upstream, his USB data storage got corrupted. Well, if the USB
> > > storage drivers also assume that the buffer can be continuous,
> > > that can corrupt data.  
> 
> > 
> > They do assume that.  
> 
> Wait a minute.  Where does that assumption occur?
> 
> And exactly what is the assumption?  Mauro wrote "the buffer can be 
> continuous", but that is certainly not what he meant.

What I meant to say is that drivers like the uvcdriver (and maybe network and
usb-storage drivers) may allocate a big buffer and get data there on some
random order, e. g.: 

int get_from_buf_pos(char *buf, int pos, int size)
{
/* or an equivalent call to usb_submit_urb() */
usb_control_msg(..., buf + pos, size, ...);
}

some_function ()
{
...

chr *buf = kzalloc(4, GFP_KERNEL);

/* 
 * Access the bytes at the array on a random order, with random size,
 * Like:
 */
get_from_buf_pos(buf, 2, 2);/* should read 0x56, 0x78 */
get_from_buf_pos(buf, 0, 2);/* should read 0x12, 0x34 */

/*
 * the expected value for the buffer would be:
 *  { 0x12, 0x34, 0x56, 0x78 }
 */

E. g. they assume that the transfer URB can work with any arbitrary
pointer and size, without needing of pre-align them.

This doesn't work with HCD drivers like dwc2, as each USB_IN operation will
actually write 4 bytes to the buffer.

So, what happens, instead, is that each data transfer will get four
bytes. Due to a hack inside dwc2, with checks if the transfer_buffer
is DWORD aligned. So, the first transfer will do what's expected: it will
read 4 bytes to a temporary buffer, allocated inside the driver,
copying just two bytes to buf. So, after the first read, the
buffer content will be:

buf = { 0x00, x00, 0x56, 0x78 }

But, on the second read, it won't be using any temporary
buffer. So, instead of reading a 16-bits word (0x5678),
it will actually read 32 bits, with 16-bits with some random value,
causing a buffer overflow. E. g. buffer content will now be:

buf = { 0x12, x34, 0xde, 0xad }

In other words, the second transfer corrupted the data from the
first transfer.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 01/22] tmplcvt: make the tool more robust

[Mauro Carvalho Chehab]

Em Sun, 2 Apr 2017 15:32:31 -0600
Jonathan Corbet  escreveu:

> On Thu, 30 Mar 2017 07:45:35 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > Currently, the script just assumes to be called at
> > Documentation/sphinx/. Change it to work on any directory,
> > and make it abort if something gets wrong.
> > 
> > Also, be sure that both parameters are specified.
> > 
> > That should avoid troubles like this:
> > 
> > $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
> > sed: couldn't open file convert_template.sed: No such file or directory  
> 
> What's the status of this patch set?  I saw that Jani had one comment
> that, I think, hasn't been addressed?

I'm resending it today, rebased on the top of docs-next.

I'll send the last patch in separate, as it is unrelated to the
doc conversion.

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 06/21] writing_usb_driver.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- adjust function and struct references;
- use monospaced fonts for C code names;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../driver-api/usb/writing_usb_driver.rst  | 182 ++---
 1 file changed, 82 insertions(+), 100 deletions(-)

diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst 
b/Documentation/driver-api/usb/writing_usb_driver.rst
index c18dbd74152b..69f077dcdb78 100644
--- a/Documentation/driver-api/usb/writing_usb_driver.rst
+++ b/Documentation/driver-api/usb/writing_usb_driver.rst
@@ -1,3 +1,5 @@
+.. _writing-usb-driver:
+
 ==
 Writing USB Device Drivers
 ==
@@ -48,25 +50,23 @@ The first thing a Linux USB driver needs to do is register 
itself with
 the Linux USB subsystem, giving it some information about which devices
 the driver supports and which functions to call when a device supported
 by the driver is inserted or removed from the system. All of this
-information is passed to the USB subsystem in the usb_driver structure.
-The skeleton driver declares a usb_driver as:
-
-::
+information is passed to the USB subsystem in the :c:type:`usb_driver`
+structure. The skeleton driver declares a :c:type:`usb_driver` as::
 
 static struct usb_driver skel_driver = {
-.name= "skeleton",
-.probe   = skel_probe,
-.disconnect  = skel_disconnect,
-.fops= &skel_fops,
-.minor   = USB_SKEL_MINOR_BASE,
-.id_table= skel_table,
+   .name= "skeleton",
+   .probe   = skel_probe,
+   .disconnect  = skel_disconnect,
+   .fops= &skel_fops,
+   .minor   = USB_SKEL_MINOR_BASE,
+   .id_table= skel_table,
 };
 
 
 The variable name is a string that describes the driver. It is used in
 informational messages printed to the system log. The probe and
 disconnect function pointers are called when a device that matches the
-information provided in the id_table variable is either seen or
+information provided in the ``id_table`` variable is either seen or
 removed.
 
 The fops and minor variables are optional. Most USB drivers hook into
@@ -76,78 +76,70 @@ subsystem, and any user-space interactions are provided 
through that
 interface. But for drivers that do not have a matching kernel subsystem,
 such as MP3 players or scanners, a method of interacting with user space
 is needed. The USB subsystem provides a way to register a minor device
-number and a set of file_operations function pointers that enable this
-user-space interaction. The skeleton driver needs this kind of
+number and a set of :c:type:`file_operations` function pointers that enable
+this user-space interaction. The skeleton driver needs this kind of
 interface, so it provides a minor starting number and a pointer to its
-file_operations functions.
+:c:type:`file_operations` functions.
 
-The USB driver is then registered with a call to usb_register, usually
-in the driver's init function, as shown here:
-
-::
+The USB driver is then registered with a call to :c:func:`usb_register`,
+usually in the driver's init function, as shown here::
 
 static int __init usb_skel_init(void)
 {
-int result;
+   int result;
 
-/* register this driver with the USB subsystem */
-result = usb_register(&skel_driver);
-if (result < 0) {
-err("usb_register failed for the "__FILE__ "driver."
-"Error number %d", result);
-return -1;
-}
+   /* register this driver with the USB subsystem */
+   result = usb_register(&skel_driver);
+   if (result < 0) {
+   err("usb_register failed for the "__FILE__ "driver."
+   "Error number %d", result);
+   return -1;
+   }
 
-return 0;
+   return 0;
 }
 module_init(usb_skel_init);
 
 
 When the driver is unloaded from the system, it needs to deregister
-itself with the USB subsystem. This is done with the usb_deregister
-function:
-
-::
+itself with the USB subsystem. This is done with the :c:func:`usb_deregister`
+function::
 
 static void __exit usb_skel_exit(void)
 {
-/* deregister this driver with the USB subsystem */
-usb_deregister(&skel_driver);
+   /* deregister this driver with the USB subsystem */
+   usb_deregister(&skel_driver);
 }
 module_exit(usb_skel_exit);
 
 
 To enable the linux-hotplug system to load the driver automatically when
-the device is plugged in, you need 

[PATCH v2 05/21] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- use the proper warning and note markups;
- use kernel-doc to include Kernel header and c files;
- remove legacy notes with regards to DocBook;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/gadget.rst | 127 +---
 1 file changed, 52 insertions(+), 75 deletions(-)

diff --git a/Documentation/driver-api/usb/gadget.rst 
b/Documentation/driver-api/usb/gadget.rst
index 52b299b1ca6d..3e8a3809c0b8 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -38,7 +38,7 @@ address a number of important problems, including:
resources.
 
 Most Linux developers will not be able to use this API, since they have
-USB "host" hardware in a PC, workstation, or server. Linux users with
+USB ``host`` hardware in a PC, workstation, or server. Linux users with
 embedded systems are more likely to have USB peripheral hardware. To
 distinguish drivers running inside such hardware from the more familiar
 Linux "USB device drivers", which are host side proxies for the real USB
@@ -64,7 +64,7 @@ Structure of Gadget Drivers
 
 A system running inside a USB peripheral normally has at least three
 layers inside the kernel to handle USB protocol processing, and may have
-additional layers in user space code. The "gadget" API is used by the
+additional layers in user space code. The ``gadget`` API is used by the
 middle layer to interact with the lowest level (which directly handles
 hardware).
 
@@ -143,13 +143,13 @@ In Linux, from the bottom up, these layers are:
 *Additional Layers*
 Other layers may exist. These could include kernel layers, such as
 network protocol stacks, as well as user mode applications building
-on standard POSIX system call APIs such as *open()*, *close()*,
-*read()* and *write()*. On newer systems, POSIX Async I/O calls may
+on standard POSIX system call APIs such as ``open()``, ``close()``,
+``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may
 be an option. Such user mode code will not necessarily be subject to
 the GNU General Public License (GPL).
 
 OTG-capable systems will also need to include a standard Linux-USB host
-side stack, with *usbcore*, one or more *Host Controller Drivers*
+side stack, with ``usbcore``, one or more *Host Controller Drivers*
 (HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
 List", and so forth. There will also be an *OTG Controller Driver*,
 which is visible to gadget and device driver developers only indirectly.
@@ -174,24 +174,20 @@ combined, to implement composite devices.
 Kernel Mode Gadget API
 ==
 
-Gadget drivers declare themselves through a *struct
-usb_gadget_driver*, which is responsible for most parts of enumeration
-for a *struct usb_gadget*. The response to a set_configuration usually
-involves enabling one or more of the *struct usb_ep* objects exposed by
-the gadget, and submitting one or more *struct usb_request* buffers to
+Gadget drivers declare themselves through a struct
+:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
+for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
+involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
+the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
 transfer data. Understand those four data types, and their operations,
 and you will understand how this API works.
 
-**Note**
+.. Note::
 
-This documentation was prepared using the standard Linux kernel
-``docproc`` tool, which turns text and in-code comments into SGML
-DocBook and then into usable formats such as HTML or PDF. Other than
-the "Chapter 9" data types, most of the significant data types and
-functions are described here.
+Other than the "Chapter 9" data types, most of the significant data
+types and functions are described here.
 
-However, docproc does not understand all the C constructs that are
-used, so some relevant information is likely omitted from what you
+However, some relevant information is likely omitted from what you
 are reading. One example of such information is endpoint
 autoconfiguration. You'll have to read the header file, and use
 example source code (such as that for "Gadget Zero"), to fully
@@ -199,10 +195,10 @@ and you will understand how this API works.
 
 The part of the API implementing some basic driver capabilities is
 specific to the version of the Linux kernel that's in use. The 2.6
-kernel includes a *driver model* framework that has no analogue on
-earlier kernels; so those parts of the gadget API are n

[PATCH v2 11/21] usb/power-management.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/index.rst |   1 +
 .../usb/power-management.rst}  | 404 +++--
 2 files changed, 214 insertions(+), 191 deletions(-)
 rename Documentation/{usb/power-management.txt => 
driver-api/usb/power-management.rst} (69%)

diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 441c5dacdf27..23c76c17fc19 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -9,6 +9,7 @@ Linux USB API
anchors
bulk-streams
callbacks
+   power-management
writing_usb_driver
writing_musb_glue_layer
 
diff --git a/Documentation/usb/power-management.txt 
b/Documentation/driver-api/usb/power-management.rst
similarity index 69%
rename from Documentation/usb/power-management.txt
rename to Documentation/driver-api/usb/power-management.rst
index 00e706997130..c068257f6d27 100644
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -1,10 +1,12 @@
-   Power Management for USB
+.. _usb-power-management:
 
-Alan Stern 
-
-  Last-updated: February 2014
+Power Management for USB
+
 
+:Author: Alan Stern 
+:Date: Last-updated: February 2014
 
+..
Contents:
-
* What is Power Management?
@@ -25,14 +27,14 @@
* Suggested Userspace Port Power Policy
 
 
-   What is Power Management?
-   -
+What is Power Management?
+-
 
 Power Management (PM) is the practice of saving energy by suspending
 parts of a computer system when they aren't being used.  While a
-component is "suspended" it is in a nonfunctional low-power state; it
+component is ``suspended`` it is in a nonfunctional low-power state; it
 might even be turned off completely.  A suspended component can be
-"resumed" (returned to a functional full-power state) when the kernel
+``resumed`` (returned to a functional full-power state) when the kernel
 needs to use it.  (There also are forms of PM in which components are
 placed in a less functional but still usable state instead of being
 suspended; an example would be reducing the CPU's clock rate.  This
@@ -44,22 +46,25 @@ device is turned off while the system as a whole remains 
running, we
 call it a "dynamic suspend" (also known as a "runtime suspend" or
 "selective suspend").  This document concentrates mostly on how
 dynamic PM is implemented in the USB subsystem, although system PM is
-covered to some extent (see Documentation/power/*.txt for more
+covered to some extent (see ``Documentation/power/*.txt`` for more
 information about system PM).
 
-System PM support is present only if the kernel was built with CONFIG_SUSPEND
-or CONFIG_HIBERNATION enabled.  Dynamic PM support for USB is present whenever
-the kernel was built with CONFIG_PM enabled.
+System PM support is present only if the kernel was built with
+``CONFIG_SUSPEND`` or ``CONFIG_HIBERNATION`` enabled.  Dynamic PM support
+
+for USB is present whenever
+the kernel was built with ``CONFIG_PM`` enabled.
 
 [Historically, dynamic PM support for USB was present only if the
-kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on
-CONFIG_PM_RUNTIME).  Starting with the 3.10 kernel release, dynamic PM support
-for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME
-enabled.  The CONFIG_USB_SUSPEND option had been eliminated.]
+kernel had been built with ``CONFIG_USB_SUSPEND`` enabled (which depended on
+``CONFIG_PM_RUNTIME``).  Starting with the 3.10 kernel release, dynamic PM
+support for USB was present whenever the kernel was built with
+``CONFIG_PM_RUNTIME`` enabled.  The ``CONFIG_USB_SUSPEND`` option had been
+eliminated.]
 
 
-   What is Remote Wakeup?
-   --
+What is Remote Wakeup?
+--
 
 When a device has been suspended, it generally doesn't resume until
 the computer tells it to.  Likewise, if the entire computer has been
@@ -76,8 +81,8 @@ event.  Examples include a suspended keyboard resuming when a 
key is
 pressed, or a suspended USB hub resuming when a device is plugged in.
 
 
-   When is a USB device idle?
-   --
+When is a USB device idle?
+--
 
 A device is idle whenever the kernel thinks it's not busy doing
 anything important and thus is a candidate for being suspended.  The
@@ -92,11 +97,11 @@ If a USB device has no driver, its usbfs file isn't open, 
and it isn't
 being accessed through sysfs, then it definitely is idle.
 
 
-   Forms of dynamic PM
-   ---
+Forms of dynamic PM
+---
 
 

[PATCH v2 07/21] writing_musb_glue_layer.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

This file is actually quite complex, and required several
manual handwork:

- add a title for the document;
- use the right tags for monospaced fonts;
- use c references where needed;
- adjust cross-reference to writing_usb_driver.rst
- hightlight cross-referenced lines.

With regards to C code snippet line highlights, the better would be
to use :linenos: for the C code snippets that are referenced by
the line number. However, at least with Sphinx 1.4.9, enabling
it cause the line number to be misaligned with the code,
making it even more confusing. So, instead, let's use
:emphasize-lines: tag to mark the lines that are referenced
at the text.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../driver-api/usb/writing_musb_glue_layer.rst | 598 ++---
 1 file changed, 292 insertions(+), 306 deletions(-)

diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst 
b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
index 52700c7031f9..e90e8fa95600 100644
--- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst
+++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
@@ -1,6 +1,6 @@
-==
-Writing an MUSB Glue Layer
-==
+=
+Writing a MUSB Glue Layer
+=
 
 :Author: Apelete Seketeli
 
@@ -21,10 +21,12 @@ design.
 As a self-taught exercise I have written an MUSB glue layer for the
 Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the
 kernel source tree. This layer can be found at
-drivers/usb/musb/jz4740.c. In this documentation I will walk through the
-basics of the jz4740.c glue layer, explaining the different pieces and
+``drivers/usb/musb/jz4740.c``. In this documentation I will walk through the
+basics of the ``jz4740.c`` glue layer, explaining the different pieces and
 what needs to be done in order to write your own device glue layer.
 
+.. _musb-basics:
+
 Linux MUSB Basics
 =
 
@@ -39,33 +41,30 @@ USB Device Drivers documentation (again, see Resources).
 
 Linux USB stack is a layered architecture in which the MUSB controller
 hardware sits at the lowest. The MUSB controller driver abstract the
-MUSB controller hardware to the Linux USB stack.
+MUSB controller hardware to the Linux USB stack::
 
-::
-
-  
-  |  | <--- drivers/usb/gadget
-  | Linux USB Core Stack | <--- drivers/usb/host
-  |  | <--- drivers/usb/core
-  
- ⬍
- --
- || <-- drivers/usb/musb/musb_gadget.c
- | MUSB Controller driver | <-- drivers/usb/musb/musb_host.c
- || <-- drivers/usb/musb/musb_core.c
- --
- ⬍
+ 
+ |  | <--- drivers/usb/gadget
+ | Linux USB Core Stack | <--- drivers/usb/host
+ |  | <--- drivers/usb/core
+ 
+⬍
+--
+|| <-- drivers/usb/musb/musb_gadget.c
+| MUSB Controller driver | <-- drivers/usb/musb/musb_host.c
+|| <-- drivers/usb/musb/musb_core.c
+--
+⬍
   -
   | MUSB Platform Specific Driver |
   |   | <-- drivers/usb/musb/jz4740.c
   |   aka "Glue Layer"|
   -
- ⬍
+⬍
   -
   |   MUSB Controller Hardware|
   -
 
-
 As outlined above, the glue layer is actually the platform specific code
 sitting in between the controller driver and the controller hardware.
 
@@ -78,37 +77,32 @@ about an embedded controller chip here, so no insertion or 
removal at
 run-time.
 
 All of this information is passed to the MUSB controller driver through
-a platform_driver structure defined in the glue layer as:
-
-::
+a :c:type:`platform_driver` structure defined in the glue layer as::
 
 static struct platform_driver jz4740_driver = {
-.probe  = jz4740_probe,
-.remove = jz4740_remove,
-.driver = {
-.name   = "musb-jz4740",
-},
+   .probe  = jz4740_probe,
+   .remove = jz4740_remove,
+   .driver = {
+   .name   = "musb-jz4740",
+   },
 };
 
-
 The probe and remove function pointers are called when a matching device
 is detected and, respectively, released. The name string describes the
 device supported by this glue laye

[PATCH v2 16/21] usb/URB.txt: convert to ReST and update it

[Mauro Carvalho Chehab]

The URB doc describes the Kernel mechanism that do USB transfers.
While the functions are already described at urb.h, there are a
number of concepts and theory that are important for USB driver
developers.

Convert it to ReST and use C ref links to point to the places
at usb.h where each function and struct is located.

A few of those descriptions were incomplete. While here, update
to reflect the current API status.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../{usb/URB.txt => driver-api/usb/URB.rst}| 221 -
 Documentation/driver-api/usb/index.rst |   1 +
 Documentation/driver-api/usb/usb.rst   |   2 +
 3 files changed, 127 insertions(+), 97 deletions(-)
 rename Documentation/{usb/URB.txt => driver-api/usb/URB.rst} (50%)

diff --git a/Documentation/usb/URB.txt b/Documentation/driver-api/usb/URB.rst
similarity index 50%
rename from Documentation/usb/URB.txt
rename to Documentation/driver-api/usb/URB.rst
index 50da0d455444..c4a141f29477 100644
--- a/Documentation/usb/URB.txt
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,28 +1,35 @@
-Revised: 2000-Dec-05.
-Again:   2002-Jul-06
-Again:   2005-Sep-19
+USB Request Block (URB)
+~~~
 
-NOTE:
+:Revised: 2000-Dec-05
+:Again:   2002-Jul-06
+:Again:   2005-Sep-19
+:Again:   2017-Mar-29
 
-The USB subsystem now has a substantial section in "The Linux Kernel API"
-guide (in Documentation/DocBook), generated from the current source
-code.  This particular documentation file isn't particularly current or
-complete; don't rely on it except for a quick overview.
 
+.. note::
 
-1.1. Basic concept or 'What is an URB?'
+The USB subsystem now has a substantial section at :ref:`usb-hostside-api`
+section, generated from the current source code.
+This particular documentation file isn't complete and may not be
+updated to the last version; don't rely on it except for a quick
+overview.
 
-The basic idea of the new driver is message passing, the message itself is 
-called USB Request Block, or URB for short. 
+Basic concept or 'What is an URB?'
+==
 
-- An URB consists of all relevant information to execute any USB transaction 
-  and deliver the data and status back. 
+The basic idea of the new driver is message passing, the message itself is
+called USB Request Block, or URB for short.
 
-- Execution of an URB is inherently an asynchronous operation, i.e. the 
-  usb_submit_urb(urb) call returns immediately after it has successfully
+- An URB consists of all relevant information to execute any USB transaction
+  and deliver the data and status back.
+
+- Execution of an URB is inherently an asynchronous operation, i.e. the
+  :c:func:`usb_submit_urb` call returns immediately after it has successfully
   queued the requested action.
 
-- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. 
+- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb`
+  at any time.
 
 - Each URB has a completion handler, which is called after the action
   has been successfully completed or canceled. The URB also contains a
@@ -35,53 +42,55 @@ called USB Request Block, or URB for short.
   of data to (or from) devices when using periodic transfer modes.
 
 
-1.2. The URB structure
+The URB structure
+=
 
-Some of the fields in an URB are:
+Some of the fields in struct :c:type:`urb` are::
 
-struct urb
-{
-// (IN) device and pipe specify the endpoint queue
+  struct urb
+  {
+  // (IN) device and pipe specify the endpoint queue
struct usb_device *dev; // pointer to associated USB device
unsigned int pipe;  // endpoint information
 
-   unsigned int transfer_flags;// ISO_ASAP, SHORT_NOT_OK, etc.
+   unsigned int transfer_flags;// URB_ISO_ASAP, URB_SHORT_NOT_OK, etc.
 
-// (IN) all urbs need completion routines
+  // (IN) all urbs need completion routines
void *context;  // context for completion routine
-   void (*complete)(struct urb *); // pointer to completion routine
+   usb_complete_t complete;// pointer to completion routine
 
-// (OUT) status after each completion
+  // (OUT) status after each completion
int status; // returned status
 
-// (IN) buffer used for data transfers
+  // (IN) buffer used for data transfers
void *transfer_buffer;  // associated data buffer
-   int transfer_buffer_length; // data buffer length
+   u32 transfer_buffer_length; // data buffer length
int number_of_packets;  // size of iso_frame_desc
 
-// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
-   int actual_length;  // actual data buffer length
+  // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
+   u32 actual_length; 

[PATCH v2 00/21] Convert USB documentation to ReST format

[Mauro Carvalho Chehab]

Currently, there are several USB core documents that are at either
written in plain text or in DocBook format. Convert them to ReST
and add to the driver-api book.

Mauro Carvalho Chehab (21):
  tmplcvt: make the tool more robust
  driver-api/basics.rst: add device table header
  docs-rst: convert usb docbooks to ReST
  usb.rst: Enrich its ReST representation
  gadget.rst: Enrich its ReST representation and add kernel-doc tag
  writing_usb_driver.rst: Enrich its ReST representation
  writing_musb_glue_layer.rst: Enrich its ReST representation
  usb/anchors.txt: convert to ReST and add to driver-api book
  usb/bulk-streams.txt: convert to ReST and add to driver-api book
  usb/callbacks.txt: convert to ReST and add to driver-api book
  usb/power-management.txt: convert to ReST and add to driver-api book
  usb/dma.txt: convert to ReST and add to driver-api book
  error-codes.rst: convert to ReST and add to driver-api book
  usb/hotplug.txt: convert to ReST and add to driver-api book
  usb/persist.txt: convert to ReST and add to driver-api book
  usb/URB.txt: convert to ReST and update it
  usb.rst: get rid of some Sphinx errors
  usb: get rid of some ReST doc build errors
  usb: composite.h: fix two warnings when building docs
  usb: gadget.h: be consistent at kernel doc macros
  docs-rst: fix usb cross-references

 Documentation/ABI/stable/sysfs-bus-usb |   2 +-
 Documentation/DocBook/Makefile |   7 +-
 Documentation/DocBook/gadget.tmpl  | 793 ---
 Documentation/DocBook/writing_musb_glue_layer.tmpl | 873 -
 Documentation/DocBook/writing_usb_driver.tmpl  | 412 --
 Documentation/driver-api/basics.rst|   6 +
 Documentation/driver-api/index.rst |   2 +-
 .../{usb/URB.txt => driver-api/usb/URB.rst}| 223 +++---
 .../anchors.txt => driver-api/usb/anchors.rst} |  36 +-
 .../usb/bulk-streams.rst}  |  13 +-
 .../callbacks.txt => driver-api/usb/callbacks.rst} |  65 +-
 .../{usb/dma.txt => driver-api/usb/dma.rst}|  51 +-
 Documentation/driver-api/usb/error-codes.rst   | 207 +
 Documentation/driver-api/usb/gadget.rst| 510 
 .../hotplug.txt => driver-api/usb/hotplug.rst} |  66 +-
 Documentation/driver-api/usb/index.rst |  26 +
 .../persist.txt => driver-api/usb/persist.rst} |  22 +-
 .../usb/power-management.rst}  | 404 +-
 Documentation/driver-api/{ => usb}/usb.rst | 222 +++---
 .../driver-api/usb/writing_musb_glue_layer.rst | 723 +
 .../driver-api/usb/writing_usb_driver.rst  | 326 
 Documentation/power/swsusp.txt |   2 +-
 Documentation/sphinx/tmplcvt   |  13 +-
 Documentation/usb/error-codes.txt  | 175 -
 drivers/staging/most/hdm-usb/hdm_usb.c |   2 +-
 drivers/usb/core/Kconfig   |   2 +-
 drivers/usb/core/message.c |   1 +
 include/linux/usb/composite.h  |   6 +-
 include/linux/usb/gadget.h |   2 +-
 29 files changed, 2417 insertions(+), 2775 deletions(-)
 delete mode 100644 Documentation/DocBook/gadget.tmpl
 delete mode 100644 Documentation/DocBook/writing_musb_glue_layer.tmpl
 delete mode 100644 Documentation/DocBook/writing_usb_driver.tmpl
 rename Documentation/{usb/URB.txt => driver-api/usb/URB.rst} (50%)
 rename Documentation/{usb/anchors.txt => driver-api/usb/anchors.rst} (75%)
 rename Documentation/{usb/bulk-streams.txt => driver-api/usb/bulk-streams.rst} 
(94%)
 rename Documentation/{usb/callbacks.txt => driver-api/usb/callbacks.rst} (76%)
 rename Documentation/{usb/dma.txt => driver-api/usb/dma.rst} (79%)
 create mode 100644 Documentation/driver-api/usb/error-codes.rst
 create mode 100644 Documentation/driver-api/usb/gadget.rst
 rename Documentation/{usb/hotplug.txt => driver-api/usb/hotplug.rst} (76%)
 create mode 100644 Documentation/driver-api/usb/index.rst
 rename Documentation/{usb/persist.txt => driver-api/usb/persist.rst} (94%)
 rename Documentation/{usb/power-management.txt => 
driver-api/usb/power-management.rst} (69%)
 rename Documentation/driver-api/{ => usb}/usb.rst (85%)
 create mode 100644 Documentation/driver-api/usb/writing_musb_glue_layer.rst
 create mode 100644 Documentation/driver-api/usb/writing_usb_driver.rst
 delete mode 100644 Documentation/usb/error-codes.txt

-- 
2.9.3


--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 20/21] usb: gadget.h: be consistent at kernel doc macros

[Mauro Carvalho Chehab]

There's one value that use spaces instead of tabs to ident.
That causes the following warning:

./include/linux/usb/gadget.h:193: ERROR: Unexpected indentation.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/usb/gadget.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/usb/gadget.h b/include/linux/usb/gadget.h
index e4516e9ded0f..fbc22a39e7bc 100644
--- a/include/linux/usb/gadget.h
+++ b/include/linux/usb/gadget.h
@@ -188,7 +188,7 @@ struct usb_ep_caps {
  * @caps:The structure describing types and directions supported by endoint.
  * @maxpacket:The maximum packet size used on this endpoint.  The initial
  * value can sometimes be reduced (hardware allowing), according to
- *  the endpoint descriptor used to configure the endpoint.
+ * the endpoint descriptor used to configure the endpoint.
  * @maxpacket_limit:The maximum packet size value which can be handled by this
  * endpoint. It's set once by UDC driver when endpoint is initialized, and
  * should not be changed. Should not be confused with maxpacket.
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 15/21] usb/persist.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/index.rst |  1 +
 .../persist.txt => driver-api/usb/persist.rst} | 22 +-
 2 files changed, 14 insertions(+), 9 deletions(-)
 rename Documentation/{usb/persist.txt => driver-api/usb/persist.rst} (94%)

diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 43f0a8b72b11..3f08cb5d5feb 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -12,6 +12,7 @@ Linux USB API
dma
power-management
hotplug
+   persist
error-codes
writing_usb_driver
writing_musb_glue_layer
diff --git a/Documentation/usb/persist.txt 
b/Documentation/driver-api/usb/persist.rst
similarity index 94%
rename from Documentation/usb/persist.txt
rename to Documentation/driver-api/usb/persist.rst
index 35d70eda9ad6..ea1b43f0559e 100644
--- a/Documentation/usb/persist.txt
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,11 +1,12 @@
-   USB device persistence during system suspend
+USB device persistence during system suspend
+
 
-  Alan Stern 
+:Author: Alan Stern 
+:Date: September 2, 2006 (Updated February 25, 2008)
 
-   September 2, 2006 (Updated February 25, 2008)
 
-
-   What is the problem?
+What is the problem?
+
 
 According to the USB specification, when a USB bus is suspended the
 bus must continue to supply suspend current (around 1-5 mA).  This
@@ -63,7 +64,8 @@ suspended -- but it will crash as soon as it wakes up, which 
isn't
 much better.)
 
 
-   What is the solution?
+What is the solution?
+=
 
 The kernel includes a feature called USB-persist.  It tries to work
 around these issues by allowing the core USB device data structures to
@@ -99,7 +101,7 @@ now a good and happy place.
 
 Note that the "USB-persist" feature will be applied only to those
 devices for which it is enabled.  You can enable the feature by doing
-(as root):
+(as root)::
 
echo 1 >/sys/bus/usb/devices/.../power/persist
 
@@ -110,7 +112,8 @@ doesn't even exist, so you only have to worry about setting 
it for
 devices where it really matters.
 
 
-   Is this the best solution?
+Is this the best solution?
+==
 
 Perhaps not.  Arguably, keeping track of mounted filesystems and
 memory mappings across device disconnects should be handled by a
@@ -130,7 +133,8 @@ just mass-storage devices.  It might turn out to be equally 
useful for
 other device types, such as network interfaces.
 
 
-   WARNING: USB-persist can be dangerous!!
+WARNING: USB-persist can be dangerous!!
+===
 
 When recovering an interrupted power session the kernel does its best
 to make sure the USB device hasn't been changed; that is, the same
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 10/21] usb/callbacks.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../callbacks.txt => driver-api/usb/callbacks.rst} | 61 +++---
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 43 insertions(+), 19 deletions(-)
 rename Documentation/{usb/callbacks.txt => driver-api/usb/callbacks.rst} (78%)

diff --git a/Documentation/usb/callbacks.txt 
b/Documentation/driver-api/usb/callbacks.rst
similarity index 78%
rename from Documentation/usb/callbacks.txt
rename to Documentation/driver-api/usb/callbacks.rst
index 9e85846bdb98..93a8d53e27e7 100644
--- a/Documentation/usb/callbacks.txt
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -1,3 +1,6 @@
+USB core callbacks
+~~
+
 What callbacks will usbcore do?
 ===
 
@@ -11,30 +14,42 @@ The callbacks defined in the driver structure are:
 
 1. Hotplugging callbacks:
 
- * @probe: Called to see if the driver is willing to manage a particular
- * interface on a device.
- * @disconnect: Called when the interface is no longer accessible, usually
- * because its device has been (or is being) disconnected or the
- * driver module is being unloaded.
+ - @probe:
+   Called to see if the driver is willing to manage a particular
+   interface on a device.
+
+ - @disconnect:
+   Called when the interface is no longer accessible, usually
+   because its device has been (or is being) disconnected or the
+   driver module is being unloaded.
 
 2. Odd backdoor through usbfs:
 
- * @ioctl: Used for drivers that want to talk to userspace through
- * the "usbfs" filesystem.  This lets devices provide ways to
- * expose information to user space regardless of where they
- * do (or don't) show up otherwise in the filesystem.
+ - @ioctl:
+   Used for drivers that want to talk to userspace through
+   the "usbfs" filesystem.  This lets devices provide ways to
+   expose information to user space regardless of where they
+   do (or don't) show up otherwise in the filesystem.
 
 3. Power management (PM) callbacks:
 
- * @suspend: Called when the device is going to be suspended.
- * @resume: Called when the device is being resumed.
- * @reset_resume: Called when the suspended device has been reset instead
- * of being resumed.
+ - @suspend:
+   Called when the device is going to be suspended.
+
+ - @resume:
+   Called when the device is being resumed.
+
+ - @reset_resume:
+   Called when the suspended device has been reset instead
+   of being resumed.
 
 4. Device level operations:
 
- * @pre_reset: Called when the device is about to be reset.
- * @post_reset: Called after the device has been reset
+ - @pre_reset:
+   Called when the device is about to be reset.
+
+ - @post_reset:
+   Called after the device has been reset
 
 The ioctl interface (2) should be used only if you have a very good
 reason. Sysfs is preferred these days. The PM callbacks are covered
@@ -58,7 +73,9 @@ an interface. A driver's bond to an interface is exclusive.
 The probe() callback
 
 
-int (*probe) (struct usb_interface *intf,
+::
+
+  int (*probe) (struct usb_interface *intf,
const struct usb_device_id *id);
 
 Accept or decline an interface. If you accept the device return 0,
@@ -75,7 +92,9 @@ initialisation that doesn't take too long is a good idea here.
 The disconnect() callback
 -
 
-void (*disconnect) (struct usb_interface *intf);
+::
+
+  void (*disconnect) (struct usb_interface *intf);
 
 This callback is a signal to break any connection with an interface.
 You are not allowed any IO to a device after returning from this
@@ -93,7 +112,9 @@ Device level callbacks
 pre_reset
 -
 
-int (*pre_reset)(struct usb_interface *intf);
+::
+
+  int (*pre_reset)(struct usb_interface *intf);
 
 A driver or user space is triggering a reset on the device which
 contains the interface passed as an argument. Cease IO, wait for all
@@ -107,7 +128,9 @@ are in atomic context.
 post_reset
 --
 
-int (*post_reset)(struct usb_interface *intf);
+::
+
+  int (*post_reset)(struct usb_interface *intf);
 
 The reset has completed.  Restore any saved device state and begin
 using the device again.
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 6fe7611f7332..441c5dacdf27 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -8,6 +8,7 @@ Linux USB API
gadget
anchors
bulk-streams
+   callbacks
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 14/21] usb/hotplug.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../hotplug.txt => driver-api/usb/hotplug.rst} | 66 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 37 insertions(+), 30 deletions(-)
 rename Documentation/{usb/hotplug.txt => driver-api/usb/hotplug.rst} (76%)

diff --git a/Documentation/usb/hotplug.txt 
b/Documentation/driver-api/usb/hotplug.rst
similarity index 76%
rename from Documentation/usb/hotplug.txt
rename to Documentation/driver-api/usb/hotplug.rst
index 5b243f315b2c..79663e653ca1 100644
--- a/Documentation/usb/hotplug.txt
+++ b/Documentation/driver-api/usb/hotplug.rst
@@ -1,4 +1,9 @@
-LINUX HOTPLUGGING
+USB hotplugging
+~~~
+
+Linux Hotplugging
+=
+
 
 In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
 into the bus with power on.  In most cases, users expect the devices to become
@@ -30,11 +35,11 @@ Because some of those actions rely on information about 
drivers (metadata)
 that is currently available only when the drivers are dynamically linked,
 you get the best hotplugging when you configure a highly modular system.
 
+Kernel Hotplug Helper (``/sbin/hotplug``)
+=
 
-KERNEL HOTPLUG HELPER (/sbin/hotplug)
-
-There is a kernel parameter: /proc/sys/kernel/hotplug, which normally
-holds the pathname "/sbin/hotplug".  That parameter names a program
+There is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally
+holds the pathname ``/sbin/hotplug``.  That parameter names a program
 which the kernel may invoke at various times.
 
 The /sbin/hotplug program can be invoked by any subsystem as part of its
@@ -51,26 +56,26 @@ Hotplug software and other resources is available at:
 Mailing list information is also available at that site.
 
 
---
+USB Policy Agent
+
 
-
-USB POLICY AGENT
-
-The USB subsystem currently invokes /sbin/hotplug when USB devices
+The USB subsystem currently invokes ``/sbin/hotplug`` when USB devices
 are added or removed from system.  The invocation is done by the kernel
 hub workqueue [hub_wq], or else as part of root hub initialization
 (done by init, modprobe, kapmd, etc).  Its single command line parameter
 is the string "usb", and it passes these environment variables:
 
-ACTION ... "add", "remove"
-PRODUCT ... USB vendor, product, and version codes (hex)
-TYPE ... device class codes (decimal)
-INTERFACE ... interface 0 class codes (decimal)
+== 
+ACTION ``add``, ``remove``
+PRODUCTUSB vendor, product, and version codes (hex)
+TYPE   device class codes (decimal)
+INTERFACE  interface 0 class codes (decimal)
+== 
 
 If "usbdevfs" is configured, DEVICE and DEVFS are also passed.  DEVICE is
 the pathname of the device, and is useful for devices with multiple and/or
 alternate interfaces that complicate driver selection.  By design, USB
-hotplugging is independent of "usbdevfs":  you can do most essential parts
+hotplugging is independent of ``usbdevfs``:  you can do most essential parts
 of USB device setup without using that filesystem, and without running a
 user mode daemon to detect changes in system configuration.
 
@@ -79,19 +84,20 @@ modules, and can invoke driver-specific setup scripts.  The 
newest ones
 leverage USB module-init-tools support.  Later agents might unload drivers.
 
 
-USB MODUTILS SUPPORT
+USB Modutils Support
+
 
-Current versions of module-init-tools will create a "modules.usbmap" file
-which contains the entries from each driver's MODULE_DEVICE_TABLE.  Such
+Current versions of module-init-tools will create a ``modules.usbmap`` file
+which contains the entries from each driver's ``MODULE_DEVICE_TABLE``.  Such
 files can be used by various user mode policy agents to make sure all the
 right driver modules get loaded, either at boot time or later.
 
-See  for full information about such table entries; or look
+See ``linux/usb.h`` for full information about such table entries; or look
 at existing drivers.  Each table entry describes one or more criteria to
 be used when matching a driver to a device or class of devices.  The
 specific criteria are identified by bits set in "match_flags", paired
 with field values.  You can construct the criteria directly, or with
-macros such as these, and use driver_info to store more information.
+macros such as these, and use driver_info to store more information::
 
 USB_DEVICE (vendorId, productId)
... matching devices with specified vendor and product ids
@@ -103,7 +109,7 @@ macros such as these, and use driver_info to store more 
information.

[PATCH v2 01/21] tmplcvt: make the tool more robust

[Mauro Carvalho Chehab]

Currently, the script just assumes to be called at
Documentation/sphinx/. Change it to work on any directory,
and make it abort if something gets wrong.

Also, be sure that both parameters are specified.

That should avoid troubles like this:

$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
sed: couldn't open file convert_template.sed: No such file or directory

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/sphinx/tmplcvt | 13 +++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
index 909a73065e0a..6848f0a26fa5 100755
--- a/Documentation/sphinx/tmplcvt
+++ b/Documentation/sphinx/tmplcvt
@@ -7,13 +7,22 @@
 # fix \_
 # title line?
 #
+set -eu
+
+if [ "$#" != "2" ]; then
+   echo "$0  "
+   exit
+fi
+
+DIR=$(dirname $0)
 
 in=$1
 rst=$2
 tmp=$rst.tmp
 
 cp $in $tmp
-sed --in-place -f convert_template.sed $tmp
+sed --in-place -f $DIR/convert_template.sed $tmp
 pandoc -s -S -f docbook -t rst -o $rst $tmp
-sed --in-place -f post_convert.sed $rst
+sed --in-place -f $DIR/post_convert.sed $rst
 rm $tmp
+echo "book writen to $rst"
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 18/21] usb: get rid of some ReST doc build errors

[Mauro Carvalho Chehab]

We need an space before a numbered list to avoid those warnings:

./drivers/usb/core/message.c:478: ERROR: Unexpected indentation.
./drivers/usb/core/message.c:479: WARNING: Block quote ends without a blank 
line; unexpected unindent.
./include/linux/usb/composite.h:455: ERROR: Unexpected indentation.
./include/linux/usb/composite.h:456: WARNING: Block quote ends without a blank 
line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab 
---
 drivers/usb/core/message.c| 1 +
 include/linux/usb/composite.h | 1 +
 2 files changed, 2 insertions(+)

diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 2184ef40a82a..4c38ea41ae96 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -474,6 +474,7 @@ EXPORT_SYMBOL_GPL(usb_sg_init);
  * significantly improve USB throughput.
  *
  * There are three kinds of completion for this function.
+ *
  * (1) success, where io->status is zero.  The number of io->bytes
  * transferred is as requested.
  * (2) error, where io->status is a negative errno value.  The number
diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 4616a49a1c2e..30a063e98c19 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -451,6 +451,7 @@ static inline struct usb_composite_driver *to_cdriver(
  * sure doing that won't hurt too much.
  *
  * One notion for how to handle Wireless USB devices involves:
+ *
  * (a) a second gadget here, discovery mechanism TBD, but likely
  * needing separate "register/unregister WUSB gadget" calls;
  * (b) updates to usb_gadget to include flags "is it wireless",
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 19/21] usb: composite.h: fix two warnings when building docs

[Mauro Carvalho Chehab]

By definition, we use /* private: */ tag when we won't be documenting
a parameter. However, those two parameters are documented:

./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef 
member 'setup_pending' description in 'usb_composite_dev'
./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef 
member 'os_desc_pending' description in 'usb_composite_dev'

So, we need to use /* public: */ to avoid a warning.

Signed-off-by: Mauro Carvalho Chehab 
---
 include/linux/usb/composite.h | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 30a063e98c19..f665d2ceac20 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -504,8 +504,9 @@ struct usb_composite_dev {
/* protects deactivations and delayed_status counts*/
spinlock_t  lock;
 
-   unsignedsetup_pending:1;
-   unsignedos_desc_pending:1;
+   /* public: */
+   unsigned intsetup_pending:1;
+   unsigned intos_desc_pending:1;
 };
 
 extern int usb_string_id(struct usb_composite_dev *c);
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 17/21] usb.rst: get rid of some Sphinx errors

[Mauro Carvalho Chehab]

Get rid of those warnings:

Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_type".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_dir".
Documentation/driver-api/usb/usb.rst:615: ERROR: Unknown target name: 
"usb_recip".
Documentation/driver-api/usb/usb.rst:679: ERROR: Unknown target name: 
"usbdevfs_urb_type".

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/usb.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index d15ab8ae5239..5ebaf669704c 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -615,8 +615,8 @@ USBDEVFS_CONTROL
 The first eight bytes of this structure are the contents of the
 SETUP packet to be sent to the device; see the USB 2.0 specification
 for details. The bRequestType value is composed by combining a
-USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\*
-value (from **). If wLength is nonzero, it describes
+``USB_TYPE_*`` value, a ``USB_DIR_*`` value, and a ``USB_RECIP_*``
+value (from ``linux/usb.h``). If wLength is nonzero, it describes
 the length of the data buffer, which is either written to the device
 (USB_DIR_OUT) or read from the device (USB_DIR_IN).
 
@@ -678,7 +678,7 @@ the blocking is separate.
 
 These requests are packaged into a structure that resembles the URB used
 by kernel device drivers. (No POSIX Async I/O support here, sorry.) It
-identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint
+identifies the endpoint type (``USBDEVFS_URB_TYPE_*``), endpoint
 (number, masked with USB_DIR_IN as appropriate), buffer and length,
 and a user "context" value serving to uniquely identify each request.
 (It's usually a pointer to per-request data.) Flags can modify requests
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 12/21] usb/dma.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../{usb/dma.txt => driver-api/usb/dma.rst}| 51 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 28 insertions(+), 24 deletions(-)
 rename Documentation/{usb/dma.txt => driver-api/usb/dma.rst} (79%)

diff --git a/Documentation/usb/dma.txt b/Documentation/driver-api/usb/dma.rst
similarity index 79%
rename from Documentation/usb/dma.txt
rename to Documentation/driver-api/usb/dma.rst
index 444651e70d95..59d5aee89e37 100644
--- a/Documentation/usb/dma.txt
+++ b/Documentation/driver-api/usb/dma.rst
@@ -1,16 +1,19 @@
+USB DMA
+~~~
+
 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
+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
-Documentation/DMA-API-HOWTO.txt).  That's how they've worked through
-the 2.4 (and earlier) kernels.
+``Documentation/DMA-API-HOWTO.txt``).  That's how they've worked through
+the 2.4 (and earlier) kernels, or they can now be DMA-aware.
 
-OR:  they can now be DMA-aware.
+DMA-aware usb drivers:
 
 - New calls enable DMA-aware drivers, letting them allocate dma buffers and
   manage dma mappings for existing dma-ready buffers (see below).
@@ -20,15 +23,15 @@ OR:  they can now be DMA-aware.
   drivers must not use it.)
 
 - "usbcore" will map this DMA address, if a DMA-aware driver didn't do
-  it first and set URB_NO_TRANSFER_DMA_MAP.  HCDs
+  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
   drivers.  Never use dma_set_mask() on any USB interface or device; that
   would potentially break all devices sharing that bus.
 
-
-ELIMINATING COPIES
+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.
@@ -41,7 +44,7 @@ and effects like cache-trashing can impose subtle penalties.
   For those specific cases, USB has primitives to allocate less expensive
   memory.  They work like kmalloc and kfree versions that give you the right
   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:
+  You'd also set ``URB_NO_TRANSFER_DMA_MAP`` in urb->transfer_flags::
 
void *usb_alloc_coherent (struct usb_device *dev, size_t size,
int mem_flags, dma_addr_t *dma);
@@ -49,15 +52,15 @@ and effects like cache-trashing can impose subtle penalties.
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
+  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.
+  :c:func:`kmalloc` will work just fine.
 
   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-API-HOWTO.txt for definitions of "coherent" and
+  ``Documentation/DMA-API-HOWTO.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
@@ -75,15 +78,15 @@ and effects like cache-trashing can impose subtle penalties.
   way to expose these capabilities ... and in any case, HIGHMEM is mostly a
   design wart specific to x86_32.  So your best bet is to ensure you never
   pass a highmem buffer into a USB driver.  That's easy; it's the default
-  behavior.  Just don't override it; e.g. with NETIF_F_HIGHDMA.
+  behavior.  Just don't override it; e.g. with ``NETIF_F_HIGHDMA``.
 
   This may force your callers to do some bounce buffering, copying from
   high memory to "normal" DMA memory.  If you can come up with a good way
   to fix this issue (for x86_32 machines with over 1 GByte of memory),
   feel free to submit patches.
 
-
-WORKING WITH EXISTING BUFFERS
+Working with existing buffers
+=
 
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  H

[PATCH v2 04/21] usb.rst: Enrich its ReST representation

[Mauro Carvalho Chehab]

- use the proper warning and note markups;
- add references for parts of the document that will be
  cross-referenced on other USB docs;
- some minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/usb.rst | 48 +---
 1 file changed, 17 insertions(+), 31 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index b856abb3200e..7e820768ee4f 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -102,6 +102,8 @@ disconnect testing (while the device is active) with each 
different host
 controller driver, to make sure drivers don't have bugs of their own as
 well as to make sure they aren't relying on some HCD-specific behavior.
 
+.. _usb_chapter9:
+
 USB-Standard Types
 ==
 
@@ -112,6 +114,8 @@ USB, and in APIs including this host side API, gadget APIs, 
and usbfs.
 .. kernel-doc:: include/linux/usb/ch9.h
:internal:
 
+.. _usb_header:
+
 Host-Side Data Types and Macros
 ===
 
@@ -209,7 +213,7 @@ library that wraps it. Such libraries include
 `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
 `jUSB <http://jUSB.sourceforge.net>`__ for Java.
 
-**Note**
+.. note::
 
 This particular documentation is incomplete, especially with respect
 to the asynchronous mode. As of kernel 2.5.66 the code and this
@@ -319,9 +323,7 @@ files. For information about the current format of this 
file, see the
 sources.
 
 This file, in combination with the poll() system call, can also be used
-to detect when devices are added or removed:
-
-::
+to detect when devices are added or removed::
 
 int fd;
 struct pollfd pfd;
@@ -407,9 +409,7 @@ The ioctl() Requests
 
 
 To use these ioctls, you need to include the following headers in your
-userspace program:
-
-::
+userspace program::
 
 #include 
 #include 
@@ -458,9 +458,7 @@ USBDEVFS_CLAIMINTERFACE
 
 USBDEVFS_CONNECTINFO
 Says whether the device is lowspeed. The ioctl parameter points to a
-structure like this:
-
-::
+structure like this::
 
struct usbdevfs_connectinfo {
unsigned int   devnum;
@@ -477,9 +475,7 @@ USBDEVFS_CONNECTINFO
 USBDEVFS_GETDRIVER
 Returns the name of the kernel driver bound to a given interface (a
 string). Parameter is a pointer to this structure, which is
-modified:
-
-::
+modified::
 
struct usbdevfs_getdriver {
unsigned int  interface;
@@ -490,9 +486,7 @@ USBDEVFS_GETDRIVER
 
 USBDEVFS_IOCTL
 Passes a request from userspace through to a kernel driver that has
-an ioctl entry in the *struct usb_driver* it registered.
-
-::
+an ioctl entry in the *struct usb_driver* it registered::
 
struct usbdevfs_ioctl {
int ifno;
@@ -534,7 +528,7 @@ USBDEVFS_RELEASEINTERFACE
 the number of the interface (bInterfaceNumber from descriptor); File
 modification time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*No security check is made to ensure that the task which made
the claim is the one which is releasing it. This means that user
@@ -574,9 +568,7 @@ a time.
 
 USBDEVFS_BULK
 Issues a bulk read or write request to the device. The ioctl
-parameter is a pointer to this structure:
-
-::
+parameter is a pointer to this structure::
 
struct usbdevfs_bulktransfer {
unsigned int  ep;
@@ -606,9 +598,7 @@ USBDEVFS_CLEAR_HALT
 
 USBDEVFS_CONTROL
 Issues a control request to the device. The ioctl parameter points
-to a structure like this:
-
-::
+to a structure like this::
 
struct usbdevfs_ctrltransfer {
__u8   bRequestType;
@@ -638,7 +628,7 @@ USBDEVFS_RESET
 the reset, this rebinds all device interfaces. File modification
 time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -646,9 +636,7 @@ USBDEVFS_RESET
 
 USBDEVFS_SETINTERFACE
 Sets the alternate setting for an interface. The ioctl parameter is
-a pointer to a structure like this:
-
-::
+a pointer to a structure like this::
 
struct usbdevfs_setinterface {
unsigned int  interface;
@@ -669,7 +657,7 @@ USBDEVFS_SETCONFIGURATION
 configuration (bConfigurationValue from descriptor). File
 modification time is not updated by this request.
 
-   **Warning**
+.. warning::
 
*Avoid using this call* until some usbcore bugs get fixed, since
it does not fully synchronize device, interface, and driver (not
@@ -702,9 +690,7 @@ When usbfs returns these urbs, the status value is updated, 
and the
 buffer 

[PATCH v2 02/21] driver-api/basics.rst: add device table header

[Mauro Carvalho Chehab]

The structs there at device table are used by other documentation
at the Kernel. So, add it to the driver API.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/basics.rst | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/driver-api/basics.rst 
b/Documentation/driver-api/basics.rst
index 935b9b8d456c..472e7a664d13 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -7,6 +7,12 @@ Driver Entry and Exit points
 .. kernel-doc:: include/linux/init.h
:internal:
 
+Driver device table
+---
+
+.. kernel-doc:: include/linux/mod_devicetable.h
+   :internal:
+
 Atomic and pointer manipulation
 ---
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 09/21] usb/bulk-streams.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../bulk-streams.txt => driver-api/usb/bulk-streams.rst}| 13 +
 Documentation/driver-api/usb/index.rst  |  1 +
 2 files changed, 10 insertions(+), 4 deletions(-)
 rename Documentation/{usb/bulk-streams.txt => driver-api/usb/bulk-streams.rst} 
(94%)

diff --git a/Documentation/usb/bulk-streams.txt 
b/Documentation/driver-api/usb/bulk-streams.rst
similarity index 94%
rename from Documentation/usb/bulk-streams.txt
rename to Documentation/driver-api/usb/bulk-streams.rst
index ffc02021863e..99b515babdeb 100644
--- a/Documentation/usb/bulk-streams.txt
+++ b/Documentation/driver-api/usb/bulk-streams.rst
@@ -1,3 +1,6 @@
+USB bulk streams
+
+
 Background
 ==
 
@@ -25,7 +28,9 @@ time.
 Driver implications
 ===
 
-int usb_alloc_streams(struct usb_interface *interface,
+::
+
+  int usb_alloc_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
unsigned int num_streams, gfp_t mem_flags);
 
@@ -53,7 +58,7 @@ controller driver, and may change in the future.
 
 
 Picking new Stream IDs to use
-
+=
 
 Stream ID 0 is reserved, and should not be used to communicate with devices.  
If
 usb_alloc_streams() returns with a value of N, you may use streams 1 though N.
@@ -68,9 +73,9 @@ Clean up
 
 
 If a driver wishes to stop using streams to communicate with the device, it
-should call
+should call::
 
-void usb_free_streams(struct usb_interface *interface,
+  void usb_free_streams(struct usb_interface *interface,
struct usb_host_endpoint **eps, unsigned int num_eps,
gfp_t mem_flags);
 
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index 5dfb04b2d730..6fe7611f7332 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -7,6 +7,7 @@ Linux USB API
usb
gadget
anchors
+   bulk-streams
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 08/21] usb/anchors.txt: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core functions. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 .../anchors.txt => driver-api/usb/anchors.rst} | 36 --
 Documentation/driver-api/usb/index.rst |  1 +
 2 files changed, 21 insertions(+), 16 deletions(-)
 rename Documentation/{usb/anchors.txt => driver-api/usb/anchors.rst} (75%)

diff --git a/Documentation/usb/anchors.txt 
b/Documentation/driver-api/usb/anchors.rst
similarity index 75%
rename from Documentation/usb/anchors.txt
rename to Documentation/driver-api/usb/anchors.rst
index fe6a99a32bbd..4b248e691bd6 100644
--- a/Documentation/usb/anchors.txt
+++ b/Documentation/driver-api/usb/anchors.rst
@@ -1,3 +1,6 @@
+USB Anchors
+~~~
+
 What is anchor?
 ===
 
@@ -13,7 +16,7 @@ Allocation and Initialisation
 =
 
 There's no API to allocate an anchor. It is simply declared
-as struct usb_anchor. init_usb_anchor() must be called to
+as struct usb_anchor. :c:func:`init_usb_anchor` must be called to
 initialise the data structure.
 
 Deallocation
@@ -26,52 +29,53 @@ Association and disassociation of URBs with anchors
 ===
 
 An association of URBs to an anchor is made by an explicit
-call to usb_anchor_urb(). The association is maintained until
+call to :c:func:`usb_anchor_urb`. The association is maintained until
 an URB is finished by (successful) completion. Thus disassociation
 is automatic. A function is provided to forcibly finish (kill)
 all URBs associated with an anchor.
-Furthermore, disassociation can be made with usb_unanchor_urb()
+Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb`
 
 Operations on multitudes of URBs
 
 
-usb_kill_anchored_urbs()
-
+:c:func:`usb_kill_anchored_urbs`
+
 
 This function kills all URBs associated with an anchor. The URBs
 are called in the reverse temporal order they were submitted.
 This way no data can be reordered.
 
-usb_unlink_anchored_urbs()
---
+:c:func:`usb_unlink_anchored_urbs`
+--
+
 
 This function unlinks all URBs associated with an anchor. The URBs
 are processed in the reverse temporal order they were submitted.
-This is similar to usb_kill_anchored_urbs(), but it will not sleep.
+This is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep.
 Therefore no guarantee is made that the URBs have been unlinked when
 the call returns. They may be unlinked later but will be unlinked in
 finite time.
 
-usb_scuttle_anchored_urbs()

+:c:func:`usb_scuttle_anchored_urbs`
+---
 
 All URBs of an anchor are unanchored en masse.
 
-usb_wait_anchor_empty_timeout()

+:c:func:`usb_wait_anchor_empty_timeout`
+---
 
 This function waits for all URBs associated with an anchor to finish
 or a timeout, whichever comes first. Its return value will tell you
 whether the timeout was reached.
 
-usb_anchor_empty()
---
+:c:func:`usb_anchor_empty`
+--
 
 Returns true if no URBs are associated with an anchor. Locking
 is the caller's responsibility.
 
-usb_get_from_anchor()
--
+:c:func:`usb_get_from_anchor`
+-
 
 Returns the oldest anchored URB of an anchor. The URB is unanchored
 and returned with a reference. As you may mix URBs to several
diff --git a/Documentation/driver-api/usb/index.rst 
b/Documentation/driver-api/usb/index.rst
index cf2fa2e8d236..5dfb04b2d730 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -6,6 +6,7 @@ Linux USB API
 
usb
gadget
+   anchors
writing_usb_driver
writing_musb_glue_layer
 
-- 
2.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2 21/21] docs-rst: fix usb cross-references

[Mauro Carvalho Chehab]

As some USB documentation files got moved, adjust their
cross-references to their new place.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ABI/stable/sysfs-bus-usb| 2 +-
 Documentation/driver-api/usb/URB.rst  | 2 ++
 Documentation/driver-api/usb/callbacks.rst| 4 ++--
 Documentation/driver-api/usb/error-codes.rst  | 2 ++
 Documentation/driver-api/usb/persist.rst  | 2 ++
 Documentation/driver-api/usb/power-management.rst | 2 +-
 Documentation/driver-api/usb/usb.rst  | 4 ++--
 Documentation/power/swsusp.txt| 2 +-
 drivers/staging/most/hdm-usb/hdm_usb.c| 2 +-
 drivers/usb/core/Kconfig  | 2 +-
 10 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-bus-usb 
b/Documentation/ABI/stable/sysfs-bus-usb
index 831f15d9672f..b832eeff 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -9,7 +9,7 @@ Description:
hubs this facility is always enabled and their device
directories will not contain this file.
 
-   For more information, see Documentation/usb/persist.txt.
+   For more information, see 
Documentation/driver-api/usb/persist.rst.
 
 What:  /sys/bus/usb/devices/.../power/autosuspend
 Date:  March 2007
diff --git a/Documentation/driver-api/usb/URB.rst 
b/Documentation/driver-api/usb/URB.rst
index c4a141f29477..61a54da9fce9 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -1,3 +1,5 @@
+.. _usb-urb:
+
 USB Request Block (URB)
 ~~~
 
diff --git a/Documentation/driver-api/usb/callbacks.rst 
b/Documentation/driver-api/usb/callbacks.rst
index 93a8d53e27e7..2b80cf54bcc3 100644
--- a/Documentation/driver-api/usb/callbacks.rst
+++ b/Documentation/driver-api/usb/callbacks.rst
@@ -8,7 +8,7 @@ Usbcore will call into a driver through callbacks defined in 
the driver
 structure and through the completion handler of URBs a driver submits.
 Only the former are in the scope of this document. These two kinds of
 callbacks are completely independent of each other. Information on the
-completion callback can be found in Documentation/usb/URB.txt.
+completion callback can be found in :ref:`usb-urb`.
 
 The callbacks defined in the driver structure are:
 
@@ -53,7 +53,7 @@ The callbacks defined in the driver structure are:
 
 The ioctl interface (2) should be used only if you have a very good
 reason. Sysfs is preferred these days. The PM callbacks are covered
-separately in Documentation/usb/power-management.txt.
+separately in :ref:`usb-power-management`.
 
 Calling conventions
 ===
diff --git a/Documentation/driver-api/usb/error-codes.rst 
b/Documentation/driver-api/usb/error-codes.rst
index 9c11a0fd16cb..a3e84bfac776 100644
--- a/Documentation/driver-api/usb/error-codes.rst
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -1,3 +1,5 @@
+.. _usb-error-codes:
+
 USB Error codes
 ~~~
 
diff --git a/Documentation/driver-api/usb/persist.rst 
b/Documentation/driver-api/usb/persist.rst
index ea1b43f0559e..08cafc6292c1 100644
--- a/Documentation/driver-api/usb/persist.rst
+++ b/Documentation/driver-api/usb/persist.rst
@@ -1,3 +1,5 @@
+.. _usb-persist:
+
 USB device persistence during system suspend
 
 
diff --git a/Documentation/driver-api/usb/power-management.rst 
b/Documentation/driver-api/usb/power-management.rst
index c068257f6d27..79beb807996b 100644
--- a/Documentation/driver-api/usb/power-management.rst
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -328,7 +328,7 @@ possible to work around the hibernation-forces-disconnect 
problem by
 using the USB Persist facility.)
 
 The ``reset_resume`` method is used by the USB Persist facility (see
-``Documentation/usb/persist.txt``) and it can also be used under certain
+:ref:`usb-persist`) and it can also be used under certain
 circumstances when ``CONFIG_USB_PERSIST`` is not enabled.  Currently, if a
 device is reset during a resume and the driver does not have a
 ``reset_resume`` method, the driver won't receive any notification about
diff --git a/Documentation/driver-api/usb/usb.rst 
b/Documentation/driver-api/usb/usb.rst
index 5ebaf669704c..6824089ef4c8 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -424,8 +424,8 @@ header.
 Unless noted otherwise, the ioctl requests described here will update
 the modification time on the usbfs file to which they are applied
 (unless they fail). A return of zero indicates success; otherwise, a
-standard USB error code is returned. (These are documented in
-``Documentation/usb/error-codes.txt`` in your kernel sources.)
+standard USB error code is returned (These are documented in
+:ref:`usb-error-codes`).
 
 Each of these files multiplexes access to several I/O st

[PATCH v2 13/21] error-codes.rst: convert to ReST and add to driver-api book

[Mauro Carvalho Chehab]

This document describe some USB core features. Add it to the
driver-api book.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/usb/error-codes.rst | 205 +++
 Documentation/driver-api/usb/index.rst   |   1 +
 Documentation/usb/error-codes.txt| 175 ---
 3 files changed, 206 insertions(+), 175 deletions(-)
 create mode 100644 Documentation/driver-api/usb/error-codes.rst
 delete mode 100644 Documentation/usb/error-codes.txt

diff --git a/Documentation/driver-api/usb/error-codes.rst 
b/Documentation/driver-api/usb/error-codes.rst
new file mode 100644
index ..9c11a0fd16cb
--- /dev/null
+++ b/Documentation/driver-api/usb/error-codes.rst
@@ -0,0 +1,205 @@
+USB Error codes
+~~~
+
+:Revised: 2004-Oct-21
+
+This is the documentation of (hopefully) all possible error codes (and
+their interpretation) that can be returned from usbcore.
+
+Some of them are returned by the Host Controller Drivers (HCDs), which
+device drivers only see through usbcore.  As a rule, all the HCDs should
+behave the same except for transfer speed dependent behaviors and the
+way certain faults are reported.
+
+
+Error codes returned by :c:func:`usb_submit_urb`
+
+
+Non-USB-specific:
+
+
+=== ===
+0  URB submission went fine
+
+``-ENOMEM``no memory for allocation of internal structures
+=== ===
+
+USB-specific:
+
+===
===
+``-EBUSY`` The URB is already active.
+
+``-ENODEV``specified USB-device or bus doesn't exist
+
+``-ENOENT``specified interface or endpoint does not exist or
+   is not enabled
+
+``-ENXIO`` host controller driver does not support queuing of
+   this type of urb.  (treat as a host controller bug.)
+
+``-EINVAL``a) Invalid transfer type specified (or not supported)
+   b) Invalid or unsupported periodic transfer interval
+   c) ISO: attempted to change transfer interval
+   d) ISO: ``number_of_packets`` is < 0
+   e) various other cases
+
+``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the
+   frames the URB would be scheduled in have already
+   expired.
+
+``-EFBIG`` Host controller driver can't schedule that many ISO
+   frames.
+
+``-EPIPE`` The pipe type specified in the URB doesn't match the
+   endpoint's actual type.
+
+``-EMSGSIZE``  (a) endpoint maxpacket size is zero; it is not usable
+   in the current interface altsetting.
+   (b) ISO packet is larger than the endpoint maxpacket.
+   (c) requested data transfer length is invalid: negative
+   or too large for the host controller.
+
+``-ENOSPC``This request would overcommit the usb bandwidth reserved
+   for periodic transfers (interrupt, isochronous).
+
+``-ESHUTDOWN`` The device or host controller has been disabled due to
+   some problem that could not be worked around.
+
+``-EPERM`` Submission failed because ``urb->reject`` was set.
+
+``-EHOSTUNREACH``  URB was rejected because the device is suspended.
+
+``-ENOEXEC``   A control URB doesn't contain a Setup packet.
+===
===
+
+Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` 
(for ISO)
+===
+
+USB device drivers may only test urb status values in completion handlers.
+This is because otherwise there would be a race between HCDs updating
+these values on one CPU, and device drivers testing them on another CPU.
+
+A transfer's actual_length may be positive even when an error has been
+reported.  That's because transfers often involve several packets, so that
+one or more packets could finish before an error stops further endpoint I/O.
+
+For isochronous URBs, the urb status value is non-zero only if the URB is
+unlinked, the device is removed, the host controller is disabled, or the total
+transferred length is less than the requested length and the
+``URB_SHORT_NOT_OK`` flag is set.  Completion handlers for isochronous URBs
+should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``,
+``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame de

[PATCH v3] usb: document that URB transfer_buffer should be aligned

[Mauro Carvalho Chehab]

Several host controllers, commonly found on ARM, like dwc2,
require buffers that are CPU-word aligned for they to work.

Failing to do that will cause buffer overflows at the caller
drivers, with could cause data corruption.

Such data corruption was found, in practice, with the uvcdriver.

Document it.

Signed-off-by: Mauro Carvalho Chehab 
---

Note: this patch is based on my previous patch series with
converts URB.txt to ReST:

Subject: [PATCH v2 00/21] Convert USB documentation to ReST format
Date: Wed,  5 Apr 2017 10:22:54 -0300
https://marc.info/?l=linux-doc&m=149139868231095&w=2

This patch, together with the ones above can be found on this tree:
 
   https://git.linuxtv.org/mchehab/experimental.git/log/?h=usb-docs-v2

 Documentation/driver-api/usb/URB.rst | 12 
 drivers/usb/core/message.c   | 15 +++
 include/linux/usb.h  | 12 
 3 files changed, 39 insertions(+)

diff --git a/Documentation/driver-api/usb/URB.rst 
b/Documentation/driver-api/usb/URB.rst
index 61a54da9fce9..8d3f362fbe82 100644
--- a/Documentation/driver-api/usb/URB.rst
+++ b/Documentation/driver-api/usb/URB.rst
@@ -271,6 +271,18 @@ If you specify your own start frame, make sure it's 
several frames in advance
 of the current frame.  You might want this model if you're synchronizing
 ISO data with some other event stream.
 
+ .. warning::
+
+   Several host drivers have a 32-bits or 64-bits DMA transfer word size,
+   with usually matches the CPU word. Due to such restriction, you should
+   warrant that the @transfer_buffer is DWORD aligned, on 32 bits system, or
+   QDWORD aligned, on 64 bits system. You should also ensure that the
+   buffer has enough space for PAD bits.
+
+   This condition is satisfied if you pass a buffer directly allocated by
+   kmalloc(), but this may not be the case if the driver allocates a bigger
+   buffer and point to a random place inside it.
+
 
 How to start interrupt (INT) transfers?
 ===
diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 4c38ea41ae96..1662a4446475 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -128,6 +128,21 @@ static int usb_internal_control_msg(struct usb_device 
*usb_dev,
  * make sure your disconnect() method can wait for it to complete. Since you
  * don't have a handle on the URB used, you can't cancel the request.
  *
+ * .. note::
+ *
+ *   Several host drivers require that the @data buffer to be aligned
+ *   with the CPU word size (e. g. DWORD for 32 bits, QDWORD for 64 bits).
+ *   It is up to USB drivers should ensure that they'll only pass buffers
+ *   with such alignments.
+ *
+ *   Please also notice that, due to such restriction, the host driver
+ *   may also override PAD bytes at the end of the @data buffer, up to the
+ *   size of the CPU word.
+ *
+ *   Such word alignment condition is normally ensured if the buffer is
+ *   allocated with kmalloc(), but this may not be the case if the driver
+ *   allocates a bigger buffer and point to a random place inside it.
+ *
  * Return: If successful, the number of bytes transferred. Otherwise, a 
negative
  * error number.
  */
diff --git a/include/linux/usb.h b/include/linux/usb.h
index 7e68259360de..5739d4422343 100644
--- a/include/linux/usb.h
+++ b/include/linux/usb.h
@@ -1373,6 +1373,18 @@ typedef void (*usb_complete_t)(struct urb *);
  * capable, assign NULL to it, so that usbmon knows not to use the value.
  * The setup_packet must always be set, so it cannot be located in highmem.
  *
+ * .. warning::
+ *
+ *   Several host drivers have a 32-bits or 64-bits DMA transfer word size,
+ *   with usually matches the CPU word. Due to such restriction, you should
+ *   warrant that the @transfer_buffer is DWORD aligned, on 32 bits system, or
+ *   QDWORD aligned, on 64 bits system. You should also ensure that the
+ *   buffer has enough space for PAD bits.
+ *
+ *   This condition is satisfied if you pass a buffer directly allocated by
+ *   kmalloc(), but this may not be the case if the driver allocates a bigger
+ *   buffer and point to a random place inside it.
+ *
  * Initialization:
  *
  * All URBs submitted must initialize the dev, pipe, transfer_flags (may be
-- 
2.9.3


--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/3] include: Convert ethernet mac address declarations to use ETH_ALEN

[Mauro Carvalho Chehab]

Em Sun, 28 Jul 2013 22:29:04 -0700
Joe Perches  escreveu:

> It's convenient to have ethernet mac addresses use
> ETH_ALEN to be able to grep for them a bit easier and
> also to ensure that the addresses are __aligned(2).
> 
> Add #include  as necessary.
> 
> Signed-off-by: Joe Perches 
> ---
>  include/acpi/actbl2.h   |  4 ++-
>  include/linux/dm9000.h  |  4 ++-
>  include/linux/fs_enet_pd.h  |  3 ++-
>  include/linux/ieee80211.h   | 59 
> +
>  include/linux/mlx4/device.h | 11 
>  include/linux/mlx4/qp.h |  5 ++--
>  include/linux/mv643xx_eth.h |  3 ++-
>  include/linux/sh_eth.h  |  3 ++-
>  include/linux/smsc911x.h|  3 ++-
>  include/linux/uwb/spec.h|  5 ++--
>  include/media/tveeprom.h|  4 ++-

I'm ok with the change at media/tveeprom.h.

Please add my ack on the next version after handling Rafael's request
on acpi.

Acked-by: Mauro Carvalho Chehab 

>  include/net/irda/irlan_common.h |  3 ++-
>  12 files changed, 61 insertions(+), 46 deletions(-)
> 
> diff --git a/include/acpi/actbl2.h b/include/acpi/actbl2.h
> index ffaac0e..3f0f11c 100644
> --- a/include/acpi/actbl2.h
> +++ b/include/acpi/actbl2.h
> @@ -44,6 +44,8 @@
>  #ifndef __ACTBL2_H__
>  #define __ACTBL2_H__
>  
> +#include 
> +
>  
> /***
>   *
>   * Additional ACPI Tables (2)
> @@ -605,7 +607,7 @@ struct acpi_ibft_nic {
>   u8 secondary_dns[16];
>   u8 dhcp[16];
>   u16 vlan;
> - u8 mac_address[6];
> + u8 mac_address[ETH_ALEN];
>   u16 pci_address;
>   u16 name_length;
>   u16 name_offset;
> diff --git a/include/linux/dm9000.h b/include/linux/dm9000.h
> index 96e8769..841925f 100644
> --- a/include/linux/dm9000.h
> +++ b/include/linux/dm9000.h
> @@ -14,6 +14,8 @@
>  #ifndef __DM9000_PLATFORM_DATA
>  #define __DM9000_PLATFORM_DATA __FILE__
>  
> +#include 
> +
>  /* IO control flags */
>  
>  #define DM9000_PLATF_8BITONLY(0x0001)
> @@ -27,7 +29,7 @@
>  
>  struct dm9000_plat_data {
>   unsigned intflags;
> - unsigned char   dev_addr[6];
> + unsigned char   dev_addr[ETH_ALEN];
>  
>   /* allow replacement IO routines */
>  
> diff --git a/include/linux/fs_enet_pd.h b/include/linux/fs_enet_pd.h
> index 51b7934..343d82a 100644
> --- a/include/linux/fs_enet_pd.h
> +++ b/include/linux/fs_enet_pd.h
> @@ -18,6 +18,7 @@
>  
>  #include 
>  #include 
> +#include 
>  #include 
>  
>  #define FS_ENET_NAME "fs_enet"
> @@ -135,7 +136,7 @@ struct fs_platform_info {
>   const struct fs_mii_bus_info *bus_info;
>  
>   int rx_ring, tx_ring;   /* number of buffers on rx */
> - __u8 macaddr[6];/* mac address */
> + __u8 macaddr[ETH_ALEN]; /* mac address */
>   int rx_copybreak;   /* limit we copy small frames  */
>   int use_napi;   /* use NAPI*/
>   int napi_weight;/* NAPI weight */
> diff --git a/include/linux/ieee80211.h b/include/linux/ieee80211.h
> index b0dc87a..4e101af 100644
> --- a/include/linux/ieee80211.h
> +++ b/include/linux/ieee80211.h
> @@ -16,6 +16,7 @@
>  #define LINUX_IEEE80211_H
>  
>  #include 
> +#include 
>  #include 
>  
>  /*
> @@ -209,28 +210,28 @@ static inline u16 ieee80211_sn_sub(u16 sn1, u16 sn2)
>  struct ieee80211_hdr {
>   __le16 frame_control;
>   __le16 duration_id;
> - u8 addr1[6];
> - u8 addr2[6];
> - u8 addr3[6];
> + u8 addr1[ETH_ALEN];
> + u8 addr2[ETH_ALEN];
> + u8 addr3[ETH_ALEN];
>   __le16 seq_ctrl;
> - u8 addr4[6];
> + u8 addr4[ETH_ALEN];
>  } __packed __aligned(2);
>  
>  struct ieee80211_hdr_3addr {
>   __le16 frame_control;
>   __le16 duration_id;
> - u8 addr1[6];
> - u8 addr2[6];
> - u8 addr3[6];
> + u8 addr1[ETH_ALEN];
> + u8 addr2[ETH_ALEN];
> + u8 addr3[ETH_ALEN];
>   __le16 seq_ctrl;
>  } __packed __aligned(2);
>  
>  struct ieee80211_qos_hdr {
>   __le16 frame_control;
>   __le16 duration_id;
> - u8 addr1[6];
> - u8 addr2[6];
> - u8 addr3[6];
> + u8 addr1[ETH_ALEN];
> + u8 addr2[ETH_ALEN];
> + u8 addr3[ETH_ALEN];
>   __le16 seq_ctrl;
>   __le16 qos_ctrl;
>  } __packed __aligned(2);
> @@ -608,8 +609,8 @@ struct ieee80211s_hdr {
>   u8 flags;
>   u8 ttl;
>   __le32 seqnum;
> - u8 eaddr1[6];
> - u8 eaddr2[6];
> + u8 eaddr1[ETH_ALEN];

Re: New USB core API to change interval and max packet size

[Mauro Carvalho Chehab]

Hi Sarah,

Em Tue, 1 Oct 2013 13:45:54 -0700
Sarah Sharp  escreveu:

> On Tue, Oct 01, 2013 at 10:01:08PM +0300, Xenia Ragiadakou wrote:
> > Hi Sarah,
> > 
> > I read the mail on 'possible conflict between xhci_hcd and a patched
> > usbhid'.
> 
> For reference to others:
> http://marc.info/?l=linux-usb&m=138064948726038&w=2
> http://marc.info/?l=linux-usb&m=138065201426880&w=2
> 
> > I looked in xhci and the problem arises in xhci_queue_intr_tx() when
> > if (xhci_interval != ep_interval) {
> > ...
> > urb->interval = xhci_interval;
> > }
> > 
> > right?
> 
> Yes.  The underlying problem is that the xHCI host sets up the endpoint
> contexts during the Configure Endpoint command, using the interval from
> the device's endpoint descriptors.  It also uses the endpoint descriptor
> wMaxPacketSize, which can be wrong as well.  If the device driver wants
> to use a different urb->interval than is in the endpoint descriptor, the
> xHCI driver will simply ignore it.
> 
> (I'm Ccing the linux-media list, as I've discussed some of these devices
> with broken descriptors before.)
> 
> > When you say a new API, what do you mean? New functions in usbcore
> > to be used by usb device drivers?
> 
> Yes.  You would export the function in the USB core, and put a prototype
> in a USB include file (probably in include/linux/usb.h).  Let's say that
> function is called usb_change_ep_bandwidth.
> 
> Drivers could call into that function when they needed to change either
> the bInterval or wMaxPacketSize of a particular endpoint.  This could be
> during the driver's probe function, or before switching alternate
> interface settings, or even after the alt setting is in place, but
> userspace dictates the driver use a different bandwidth.
> 
> Drivers should pass usb_change_ep_bandwidth a pointer to the endpoint
> they need to change, along with the bInterval and wMaxPacketSize values
> they would like the endpoint to have.  Those values could be stored as
> new values in struct usb_host_endpoint.

Let me see if I understand the changes at the media drivers. So, please
correct me if I got it wrong.

I'm yet to get any USB 3.0 media device, although it is common to connect
an USB 1.1 or USB 2.0 device on a USB 3.0 host port.

So, for example, on this device:

Bus 003 Device 002: ID 2040:6600 Hauppauge 
Device Descriptor:
  bLength18
  bDescriptorType 1
  bcdUSB   2.00
  bDeviceClass0 (Defined at Interface level)
  bDeviceSubClass 0 
  bDeviceProtocol 0 
  bMaxPacketSize064
  idVendor   0x2040 Hauppauge
  idProduct  0x6600 
  bcdDevice0.69
  iManufacturer  16 
  iProduct   32 HVR900H
  iSerial64 4031932745
...
  Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x83  EP 3 IN
bmAttributes3
  Transfer TypeInterrupt
  Synch Type   None
  Usage Type   Data
wMaxPacketSize 0x0004  1x 4 bytes
bInterval   1
...

connected via this BUS device:

Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Device Descriptor:
  bLength18
  bDescriptorType 1
  bcdUSB   2.00
  bDeviceClass9 Hub
  bDeviceSubClass 0 Unused
  bDeviceProtocol 1 Single TT
  bMaxPacketSize064
  idVendor   0x1d6b Linux Foundation
  idProduct  0x0002 2.0 root hub
  bcdDevice3.11
  iManufacturer   3 Linux 3.11.2-201.fc19.x86_64 xhci_hcd
  iProduct2 xHCI Host Controller
  iSerial 1 :00:14.0

In such situation, and assuming that the USB tables are correct, there's
nothing that needs to be done there, as bInterval/wMaxPacketSize are
correct for USB 2.0.

So, there's no need to call usb_change_ep_bandwidth().

If so, then usb_change_ep_bandwidth() as a quirk, if bInterval
or wMaxPacketSize were improperly filled.

Right?
-- 

Cheers,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New USB core API to change interval and max packet size

[Mauro Carvalho Chehab]

Em Wed, 02 Oct 2013 11:00:13 -0400 (EDT)
Alan Stern  escreveu:

> On Wed, 2 Oct 2013, Mauro Carvalho Chehab wrote:
> 
> > Let me see if I understand the changes at the media drivers. So, please
> > correct me if I got it wrong.
> > 
> > I'm yet to get any USB 3.0 media device, although it is common to connect
> > an USB 1.1 or USB 2.0 device on a USB 3.0 host port.
> > 
> > So, for example, on this device:
> 
> > ...
> >   Endpoint Descriptor:
> > bLength 7
> > bDescriptorType 5
> > bEndpointAddress 0x83  EP 3 IN
> > bmAttributes3
> >   Transfer TypeInterrupt
> >   Synch Type   None
> >   Usage Type   Data
> > wMaxPacketSize 0x0004  1x 4 bytes
> > bInterval   1
> > ...
> > 
> > connected via this BUS device:
> 
> ...
> 
> > In such situation, and assuming that the USB tables are correct, there's
> > nothing that needs to be done there, as bInterval/wMaxPacketSize are
> > correct for USB 2.0.
> > 
> > So, there's no need to call usb_change_ep_bandwidth().
> 
> That's right.
> 
> > If so, then usb_change_ep_bandwidth() as a quirk, if bInterval
> > or wMaxPacketSize were improperly filled.
> > 
> > Right?
> 
> Or if the values are correct, but the driver wants to use something 
> different for its own reasons (for example, to get lower latency or 
> because it knows that it will never use packets as large as the 
> descriptor allows).  Right.

Ok, so, in this case, usb_change_ep_bandwidth() could be called
just before usb_alloc_urb(), in order to make it to use the packet
size that would be expected for that kind of ISOC traffic that
userspace indirectly selected, by adjusting the streaming
video resolution selected, right?

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New USB core API to change interval and max packet size

[Mauro Carvalho Chehab]

Em Wed, 02 Oct 2013 12:38:14 -0400 (EDT)
Alan Stern  escreveu:

> On Wed, 2 Oct 2013, Mauro Carvalho Chehab wrote:
> 
> > > > So, there's no need to call usb_change_ep_bandwidth().
> > > 
> > > That's right.
> > > 
> > > > If so, then usb_change_ep_bandwidth() as a quirk, if bInterval
> > > > or wMaxPacketSize were improperly filled.
> > > > 
> > > > Right?
> > > 
> > > Or if the values are correct, but the driver wants to use something 
> > > different for its own reasons (for example, to get lower latency or 
> > > because it knows that it will never use packets as large as the 
> > > descriptor allows).  Right.
> > 
> > Ok, so, in this case, usb_change_ep_bandwidth() could be called
> > just before usb_alloc_urb(), in order to make it to use the packet
> > size that would be expected for that kind of ISOC traffic that
> > userspace indirectly selected, by adjusting the streaming
> > video resolution selected, right?
> 
> We haven't decided on the final API yet.  However, note that
> usb_alloc_urb() doesn't depend on the packet size.  It requires you to
> specify only the number of packets, not their sizes.  Therefore it
> doesn't matter whether you call usb_change_ep_bandwidth() before or
> after usb_alloc_urb().

Sure, but, at least on almost all V4L2 drivers, the number of packets
and their sizes should be calculated to be able to receive all URBs
needed to store a complete image frame (that generally arrives on 
every 1/60 Hz or 1/50 Hz - depending on the frames per second rate).

On those drivers, the transfer_buffer is allocated at the same loop 
where usb_alloc_urb() is called.

So, it makes sense for them to specify the bandwidth parameters at
the function that calls usb_alloc_coherent() and usb_alloc_urb().

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 19/51] DMA-API: media: dt3155v4l: replace dma_set_mask()+dma_set_coherent_mask() with new helper

[Mauro Carvalho Chehab]

Hi Russell,

Em Mon, 30 Sep 2013 13:57:47 +0200
Hans Verkuil  escreveu:

> On 09/19/2013 11:44 PM, Russell King wrote:
> > Replace the following sequence:
> > 
> > dma_set_mask(dev, mask);
> > dma_set_coherent_mask(dev, mask);
> > 
> > with a call to the new helper dma_set_mask_and_coherent().
> > 
> > Signed-off-by: Russell King 
> 
> Acked-by: Hans Verkuil 

Somehow, I lost your original post (I got unsubscribed on a few days 
from all vger mailing lists at the end of september).

I suspect that you want to sent this via your tree, right?
If so:

Acked-by: Mauro Carvalho Chehab 

> 
> Regards,
> 
>   Hans
> 
> > ---
> >  drivers/staging/media/dt3155v4l/dt3155v4l.c |5 +
> >  1 files changed, 1 insertions(+), 4 deletions(-)
> > 
> > diff --git a/drivers/staging/media/dt3155v4l/dt3155v4l.c 
> > b/drivers/staging/media/dt3155v4l/dt3155v4l.c
> > index 90d6ac4..081407b 100644
> > --- a/drivers/staging/media/dt3155v4l/dt3155v4l.c
> > +++ b/drivers/staging/media/dt3155v4l/dt3155v4l.c
> > @@ -901,10 +901,7 @@ dt3155_probe(struct pci_dev *pdev, const struct 
> > pci_device_id *id)
> > int err;
> > struct dt3155_priv *pd;
> >  
> > -   err = dma_set_mask(&pdev->dev, DMA_BIT_MASK(32));
> > -   if (err)
> > -   return -ENODEV;
> > -   err = dma_set_coherent_mask(&pdev->dev, DMA_BIT_MASK(32));
> > +   err = dma_set_mask_and_coherent(&pdev->dev, DMA_BIT_MASK(32));
> > if (err)
> > return -ENODEV;
> > pd = kzalloc(sizeof(*pd), GFP_KERNEL);
> > 
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majord...@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html


-- 

Cheers,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] MIPS: OCTEON: Rename Kconfig CAVIUM_OCTEON_REFERENCE_BOARD to CAVIUM_OCTEON_SOC

[Mauro Carvalho Chehab]

Em Mon, 20 May 2013 15:19:38 -0700
David Daney  escreveu:

> From: David Daney 
> 
> CAVIUM_OCTEON_SOC most place we used to use CPU_CAVIUM_OCTEON.  This
> allows us to CPU_CAVIUM_OCTEON in places where we have no OCTEON SOC.
> 
> Remove CAVIUM_OCTEON_SIMULATOR as it doesn't really do anything, we can
> get the same configuration with CAVIUM_OCTEON_SOC.
> 
> Signed-off-by: David Daney 
> Cc: linux-...@vger.kernel.org
> Cc: linux-e...@vger.kernel.org

Acked-by: Mauro Carvalho Chehab 

> Cc: linux-...@vger.kernel.org
> Cc: net...@vger.kernel.org
> Cc: spi-devel-gene...@lists.sourceforge.net
> Cc: de...@driverdev.osuosl.org
> Cc: linux-usb@vger.kernel.org

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Isochronous transfer error on USB3

[Mauro Carvalho Chehab]

Em Mon, 18 Mar 2013 09:51:24 -0700
Sarah Sharp  escreveu:

> On Tue, Mar 12, 2013 at 10:57:22AM +0100, jean-philippe francois wrote:
> > 2013/3/12 jean-philippe francois :
> > > 2013/3/12 Sarah Sharp :
> > >> On Mon, Mar 11, 2013 at 01:21:48PM +0100, jean-philippe francois wrote:
> > >>> Hi,
> > >>>
> > >>> The company I work for is doing USB cameras, for which I wrote the
> > >>> drivers (out of tree).
> > >>
> > >> Kernel driver or userspace driver?
> > >>
> > > Kernel driver.
> 
> Ok, I don't know what license your driver is under, so I can't legally
> look at the C snippet you sent me.

Sarah,

I'm experiencing a similar error with the in-kernel em28xx driver, plus
some fixes that I'm writing for Kernel 3.14. The tree with the driver is
at:

http://git.linuxtv.org/mchehab/experimental.git/shortlog/refs/heads/em28xx-v4l2

The code with troubles is at:


http://git.linuxtv.org/mchehab/experimental.git/blob/refs/heads/em28xx-v4l2:/drivers/media/usb/em28xx/em28xx-audio.c

Basically, the device works fine on an USB 2.0 port, but if I connect
it on any of the 3 existing USB 3.0 ports on my notebook, the audio
endpoint doesn't work.

On this device, there are two isoc transfers: one for video (on frame
on every 1/60 seconds) and another one for audio. Each on a different
endpoint.

The video transfers happen fine. The audio transfer doesn't.

Due to the way the userspace works, every time the channel changes,
the audio stream is stopped and restarted. 

The code that starts streaming is at line 164:

164 static int em28xx_init_audio_isoc(struct em28xx *dev)
165 {
166 int   i, errCode;
167
168 dprintk("Starting isoc transfers\n");
169
170 /* Start streaming */
171 for (i = 0; i < EM28XX_AUDIO_BUFS; i++) {
172 memset(dev->adev.transfer_buffer[i], 0x80,
173dev->adev.urb[i]->transfer_buffer_length);
174
175 errCode = usb_submit_urb(dev->adev.urb[i], GFP_ATOMIC);
176 if (errCode) {
177 em28xx_errdev("submit of audio urb failed\n");
178 em28xx_deinit_isoc_audio(dev);
179 atomic_set(&dev->stream_started, 0);
180 return errCode;
181 }
182
183 }
184
185 return 0;
186 }

And the code that stops it is:

61 static int em28xx_deinit_isoc_audio(struct em28xx *dev)
62 {
63 int i;
64
65 dprintk("Stopping isoc\n");
66 for (i = 0; i < EM28XX_AUDIO_BUFS; i++) {
67 struct urb *urb = dev->adev.urb[i];
68
69 if (!irqs_disabled())
70 usb_kill_urb(urb);
71 else
72 usb_unlink_urb(urb);
73 }
74
75 return 0;
76 }

It seems that usb_unlink_urb() is causing troubles with xHCI: the
endpoint stops streaming, but, after that, it doesn't start again,
and lots of debug messages are produced. I emailed you the full log
after start streaming in priv (too big for vger), but basically, 
it produces:

[ 1635.754546] xhci_hcd :00:14.0: Endpoint 0x81 not halted, refusing to 
reset.
[ 1635.754562] xhci_hcd :00:14.0: Endpoint 0x82 not halted, refusing to 
reset.
[ 1635.754577] xhci_hcd :00:14.0: Endpoint 0x83 not halted, refusing to 
reset.
[ 1635.754594] xhci_hcd :00:14.0: Endpoint 0x84 not halted, refusing to 
reset.

(Not sure why it is trying to stop all endpoints - as just one endpoint was
requested to restart).

FYI, my tests are with xHCI 1.0:

[3.640583] xhci_hcd :00:14.0: // @c900040c = 0x180 
(CAPLENGTH AND HCIVERSION)

Any ideas?
-- 

Cheers,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Isochronous transfer error on USB3

[Mauro Carvalho Chehab]

Em Thu, 02 Jan 2014 14:07:22 -0800
Sarah Sharp  escreveu:

> On Sun, Dec 29, 2013 at 02:54:40AM -0200, Mauro Carvalho Chehab wrote:
> > It seems that usb_unlink_urb() is causing troubles with xHCI: the
> > endpoint stops streaming, but, after that, it doesn't start again,
> > and lots of debug messages are produced. I emailed you the full log
> > after start streaming in priv (too big for vger), but basically, 
> > it produces:
> > 
> > [ 1635.754546] xhci_hcd :00:14.0: Endpoint 0x81 not halted, refusing to 
> > reset.
> > [ 1635.754562] xhci_hcd :00:14.0: Endpoint 0x82 not halted, refusing to 
> > reset.
> > [ 1635.754577] xhci_hcd :00:14.0: Endpoint 0x83 not halted, refusing to 
> > reset.
> > [ 1635.754594] xhci_hcd :00:14.0: Endpoint 0x84 not halted, refusing to 
> > reset.
> 
> I think that's due to the driver (or userspace) attempting to reset the
> endpoint when it didn't actually receive a stall (-EPIPE) status from an
> URB.  When that happens, the xHCI host controller endpoint "toggle" bits
> get out of sync with the device toggle bits, and the result is that all
> transfers will fail to the endpoint from then on until you switch
> alternate interface settings or unplug/replug the device.
> 
> Try this patch:
> 
> http://marc.info/?l=linux-usb&m=138116117104619&w=2
> 
> It's still under RFC, and I know it has race conditions, but it will let
> you quickly test whether this fixes your issue.

Didn't work fine, or at least it didn't solve all the problems. Also, it
started to cause OOPSes due to the race conditions.

> 
> This has been a long-standing xHCI driver bug.  I asked my OPW intern to
> work on the patch to fix it, but she may be a bit busy with her new job
> to finish up the RFC.  I'll probably have to take over finishing the
> patch, if this turns out to be your issue.
> 
> > (Not sure why it is trying to stop all endpoints - as just one endpoint was
> > requested to restart).
> 
> Something is calling into usb_clear_halt() with all the endpoints.
> Userspace, perhaps? 

No, userspace is not doing it. The userspace doesn't even know that this
device is USB (and were written at the time that all media drivers were
PCI only - so it doesn't have any USB specific call on it).

> You could add WARN() calls to usb_clear_halt() to
> see what code is resetting the endpoints.  In any case, it's not part of
> the USB core code to change configuration or alt settings, since I don't
> see any xHCI driver output from the endpoint bandwidth code in this
> chunk of the dmesg you sent:

The em28xx-audio.c driver may need to call usb_set_interface() while
the video is still streaming, in order to unmute the audio. That happens
when the audio device is opened.

With EHCI, this works properly.

> [ 1649.640783] xhci_hcd :00:14.0: Removing canceled TD starting at 
> 0xb41e8580 (dma).
> [ 1649.640784] xhci_hcd :00:14.0: TRB to noop at offset 0xb41e8580
> [ 1649.643159] xhci_hcd :00:14.0: Endpoint 0x81 not halted, refusing to 
> reset.
> [ 1649.643188] xhci_hcd :00:14.0: Endpoint 0x82 not halted, refusing to 
> reset.
> [ 1649.643215] xhci_hcd :00:14.0: Endpoint 0x83 not halted, refusing to 
> reset.
> [ 1649.643239] xhci_hcd :00:14.0: Endpoint 0x84 not halted, refusing to 
> reset.
> [ 1649.735539] xhci_hcd :00:14.0: ERROR no room on ep ring, try ring 
> expansion
> 
> Sarah Sharp

Btw, sometimes, I get such logs:

[  646.192273] xhci_hcd :00:14.0: Miss service interval error, set skip flag
[  646.192292] xhci_hcd :00:14.0: Miss service interval error, set skip flag
[  646.192311] xhci_hcd :00:14.0: Miss service interval error, set skip flag
[  646.192329] xhci_hcd :00:14.0: Miss service interval error, set skip flag
[  646.192351] xhci_hcd :00:14.0: Miss service interval error, set skip flag
[  646.192376] xhci_hcd :00:14.0: Miss service interval error, set skip flag

After adding some debug at em28xx-audio, triggering alsa trigger start
events, I'm getting those:

[ 3078.971224] snd_em28xx_capture_trigger: start capture
[ 3078.971284] xhci_hcd :00:14.0: ERROR no room on ep ring, try ring 
expansion
[ 3078.971311] xhci_hcd :00:14.0: ring expansion succeed, now has 4 segments
[ 3078.971350] xhci_hcd :00:14.0: ERROR no room on ep ring, try ring 
expansion
[ 3078.971387] xhci_hcd :00:14.0: ring expansion succeed, now has 8 segments
[ 3079.034626] em28xx_audio_isocirq, 64 packets (first one with size 12)

Here, some audio data arrives.

[ 3079.034665] snd_em28xx_capture_trigger: stop capture

It seems, however, that this didn't arrive in time, and causes an alsa
buffer underrun. So, it cancels the existing URBs.

PS.: Ev

Re: Isochronous transfer error on USB3

[Mauro Carvalho Chehab]

Em Wed, 08 Jan 2014 14:31:28 -0200
Mauro Carvalho Chehab  escreveu:

> Em Thu, 02 Jan 2014 14:07:22 -0800
> Sarah Sharp  escreveu:
> 
> > On Sun, Dec 29, 2013 at 02:54:40AM -0200, Mauro Carvalho Chehab wrote:
> > > It seems that usb_unlink_urb() is causing troubles with xHCI: the
> > > endpoint stops streaming, but, after that, it doesn't start again,
> > > and lots of debug messages are produced. I emailed you the full log
> > > after start streaming in priv (too big for vger), but basically, 
> > > it produces:
> > > 
> > > [ 1635.754546] xhci_hcd :00:14.0: Endpoint 0x81 not halted, refusing 
> > > to reset.
> > > [ 1635.754562] xhci_hcd :00:14.0: Endpoint 0x82 not halted, refusing 
> > > to reset.
> > > [ 1635.754577] xhci_hcd :00:14.0: Endpoint 0x83 not halted, refusing 
> > > to reset.
> > > [ 1635.754594] xhci_hcd :00:14.0: Endpoint 0x84 not halted, refusing 
> > > to reset.
> > 
> > I think that's due to the driver (or userspace) attempting to reset the
> > endpoint when it didn't actually receive a stall (-EPIPE) status from an
> > URB.  When that happens, the xHCI host controller endpoint "toggle" bits
> > get out of sync with the device toggle bits, and the result is that all
> > transfers will fail to the endpoint from then on until you switch
> > alternate interface settings or unplug/replug the device.
> > 
> > Try this patch:
> > 
> > http://marc.info/?l=linux-usb&m=138116117104619&w=2
> > 
> > It's still under RFC, and I know it has race conditions, but it will let
> > you quickly test whether this fixes your issue.
> 
> Didn't work fine, or at least it didn't solve all the problems. Also, it
> started to cause OOPSes due to the race conditions.
> 
> > 
> > This has been a long-standing xHCI driver bug.  I asked my OPW intern to
> > work on the patch to fix it, but she may be a bit busy with her new job
> > to finish up the RFC.  I'll probably have to take over finishing the
> > patch, if this turns out to be your issue.
> > 
> > > (Not sure why it is trying to stop all endpoints - as just one endpoint 
> > > was
> > > requested to restart).
> > 
> > Something is calling into usb_clear_halt() with all the endpoints.
> > Userspace, perhaps? 
> 
> No, userspace is not doing it. The userspace doesn't even know that this
> device is USB (and were written at the time that all media drivers were
> PCI only - so it doesn't have any USB specific call on it).
> 
> > You could add WARN() calls to usb_clear_halt() to
> > see what code is resetting the endpoints.  In any case, it's not part of
> > the USB core code to change configuration or alt settings, since I don't
> > see any xHCI driver output from the endpoint bandwidth code in this
> > chunk of the dmesg you sent:
> 
> The em28xx-audio.c driver may need to call usb_set_interface() while
> the video is still streaming, in order to unmute the audio. That happens
> when the audio device is opened.
> 
> With EHCI, this works properly.
> 
> > [ 1649.640783] xhci_hcd :00:14.0: Removing canceled TD starting at 
> > 0xb41e8580 (dma).
> > [ 1649.640784] xhci_hcd :00:14.0: TRB to noop at offset 0xb41e8580
> > [ 1649.643159] xhci_hcd :00:14.0: Endpoint 0x81 not halted, refusing to 
> > reset.
> > [ 1649.643188] xhci_hcd :00:14.0: Endpoint 0x82 not halted, refusing to 
> > reset.
> > [ 1649.643215] xhci_hcd :00:14.0: Endpoint 0x83 not halted, refusing to 
> > reset.
> > [ 1649.643239] xhci_hcd :00:14.0: Endpoint 0x84 not halted, refusing to 
> > reset.
> > [ 1649.735539] xhci_hcd :00:14.0: ERROR no room on ep ring, try ring 
> > expansion
> > 
> > Sarah Sharp
> 
> Btw, sometimes, I get such logs:
> 
> [  646.192273] xhci_hcd :00:14.0: Miss service interval error, set skip 
> flag
> [  646.192292] xhci_hcd :00:14.0: Miss service interval error, set skip 
> flag
> [  646.192311] xhci_hcd :00:14.0: Miss service interval error, set skip 
> flag
> [  646.192329] xhci_hcd :00:14.0: Miss service interval error, set skip 
> flag
> [  646.192351] xhci_hcd :00:14.0: Miss service interval error, set skip 
> flag
> [  646.192376] xhci_hcd :00:14.0: Miss service interval error, set skip 
> flag
> 
> After adding some debug at em28xx-audio, triggering alsa trigger start
> events, I'm getting those:
> 
> [ 3078.971224] snd_em28xx_capture_trigger: start capture
> [ 3078.971284] xhci_hcd :00:14.0: E

Re: Isochronous transfer error on USB3

[Mauro Carvalho Chehab]

Em Wed, 08 Jan 2014 15:05:12 -0200
Mauro Carvalho Chehab  escreveu:

> Em Wed, 08 Jan 2014 14:31:28 -0200
> Mauro Carvalho Chehab  escreveu:
> 
> > Em Thu, 02 Jan 2014 14:07:22 -0800
> > Sarah Sharp  escreveu:
> > 
> > > On Sun, Dec 29, 2013 at 02:54:40AM -0200, Mauro Carvalho Chehab wrote:
> > > > It seems that usb_unlink_urb() is causing troubles with xHCI: the
> > > > endpoint stops streaming, but, after that, it doesn't start again,
> > > > and lots of debug messages are produced. I emailed you the full log
> > > > after start streaming in priv (too big for vger), but basically, 
> > > > it produces:
> > > > 
> > > > [ 1635.754546] xhci_hcd :00:14.0: Endpoint 0x81 not halted, 
> > > > refusing to reset.
> > > > [ 1635.754562] xhci_hcd :00:14.0: Endpoint 0x82 not halted, 
> > > > refusing to reset.
> > > > [ 1635.754577] xhci_hcd :00:14.0: Endpoint 0x83 not halted, 
> > > > refusing to reset.
> > > > [ 1635.754594] xhci_hcd :00:14.0: Endpoint 0x84 not halted, 
> > > > refusing to reset.
> > > 
> > > I think that's due to the driver (or userspace) attempting to reset the
> > > endpoint when it didn't actually receive a stall (-EPIPE) status from an
> > > URB.  When that happens, the xHCI host controller endpoint "toggle" bits
> > > get out of sync with the device toggle bits, and the result is that all
> > > transfers will fail to the endpoint from then on until you switch
> > > alternate interface settings or unplug/replug the device.
> > > 
> > > Try this patch:
> > > 
> > > http://marc.info/?l=linux-usb&m=138116117104619&w=2
> > > 
> > > It's still under RFC, and I know it has race conditions, but it will let
> > > you quickly test whether this fixes your issue.
> > 
> > Didn't work fine, or at least it didn't solve all the problems. Also, it
> > started to cause OOPSes due to the race conditions.
> > 
> > > 
> > > This has been a long-standing xHCI driver bug.  I asked my OPW intern to
> > > work on the patch to fix it, but she may be a bit busy with her new job
> > > to finish up the RFC.  I'll probably have to take over finishing the
> > > patch, if this turns out to be your issue.
> > > 
> > > > (Not sure why it is trying to stop all endpoints - as just one endpoint 
> > > > was
> > > > requested to restart).
> > > 
> > > Something is calling into usb_clear_halt() with all the endpoints.
> > > Userspace, perhaps? 
> > 
> > No, userspace is not doing it. The userspace doesn't even know that this
> > device is USB (and were written at the time that all media drivers were
> > PCI only - so it doesn't have any USB specific call on it).
> > 
> > > You could add WARN() calls to usb_clear_halt() to
> > > see what code is resetting the endpoints.  In any case, it's not part of
> > > the USB core code to change configuration or alt settings, since I don't
> > > see any xHCI driver output from the endpoint bandwidth code in this
> > > chunk of the dmesg you sent:
> > 
> > The em28xx-audio.c driver may need to call usb_set_interface() while
> > the video is still streaming, in order to unmute the audio. That happens
> > when the audio device is opened.
> > 
> > With EHCI, this works properly.
> > 
> > > [ 1649.640783] xhci_hcd :00:14.0: Removing canceled TD starting at 
> > > 0xb41e8580 (dma).
> > > [ 1649.640784] xhci_hcd :00:14.0: TRB to noop at offset 0xb41e8580
> > > [ 1649.643159] xhci_hcd :00:14.0: Endpoint 0x81 not halted, refusing 
> > > to reset.
> > > [ 1649.643188] xhci_hcd :00:14.0: Endpoint 0x82 not halted, refusing 
> > > to reset.
> > > [ 1649.643215] xhci_hcd :00:14.0: Endpoint 0x83 not halted, refusing 
> > > to reset.
> > > [ 1649.643239] xhci_hcd :00:14.0: Endpoint 0x84 not halted, refusing 
> > > to reset.
> > > [ 1649.735539] xhci_hcd :00:14.0: ERROR no room on ep ring, try ring 
> > > expansion
> > > 
> > > Sarah Sharp
> > 
> > Btw, sometimes, I get such logs:
> > 
> > [  646.192273] xhci_hcd :00:14.0: Miss service interval error, set skip 
> > flag
> > [  646.192292] xhci_hcd :00:14.0: Miss service interval error, set skip 
> > flag
> > [  646.192311] xhci_hcd :00:14.0: Miss service interval error, set

Fw: Isochronous transfer error on USB3

[Mauro Carvalho Chehab]

Hi Hans/Takashi,

I'm getting an weird behavior with em28xx, especially when the device
is connected into an audio port.

I'm using, on my tests, an em28xx HVR-950 device, using this tree:

http://git.linuxtv.org/mchehab/experimental.git/shortlog/refs/heads/em28xx-v4l2-v6
Where the alsa driver is at:

http://git.linuxtv.org/mchehab/experimental.git/blob/refs/heads/em28xx-v4l2-v6:/drivers/media/usb/em28xx/em28xx-audio.c

I'm testing it with xawtv3 (http://git.linuxtv.org/xawtv3.git). The
ALSA userspace code there is at:
http://git.linuxtv.org/xawtv3.git/blob/HEAD:/common/alsa_stream.c

What happens is that, when I require xawtv3 to use any latency lower 
than 65 ms, the audio doesn't work, as it gets lots of underruns per
second. 

FYI, em28xx works at a 48000 KHz sampling rate, and its PM capture Hw
is described as:

static struct snd_pcm_hardware snd_em28xx_hw_capture = {
.info = SNDRV_PCM_INFO_BLOCK_TRANSFER |
SNDRV_PCM_INFO_MMAP   |
SNDRV_PCM_INFO_INTERLEAVED|
SNDRV_PCM_INFO_BATCH  |
SNDRV_PCM_INFO_MMAP_VALID,

.formats = SNDRV_PCM_FMTBIT_S16_LE,

.rates = SNDRV_PCM_RATE_CONTINUOUS | SNDRV_PCM_RATE_KNOT,

.rate_min = 48000,
.rate_max = 48000,
.channels_min = 2,
.channels_max = 2,
.buffer_bytes_max = 62720 * 8,  /* just about the value in usbaudio.c */
.period_bytes_min = 64, /* 12544/2, */
.period_bytes_max = 12544,
.periods_min = 2,
.periods_max = 98,  /* 12544, */
};

On my tests, I experimentally discovered that the minimal latency to
avoid ALSA library underruns is:
- 65ms when using xHCI;
- 25ms when using EHCI.

Any latency lower than that causes lots of overruns. Very high
latency also causes overruns (but on a lower rate, as the period
is bigger).

I'm wandering if is there anything that could be done either at Kernel
side or at userspace side to automatically get some configuration that
works as-is, without requiring the user to play with the latency parameter
by hand.

The alsa-info data is enclosed.

Thank you!
Mauro

PS.: I'm still trying to understand why the minimal allowed latency is
different when using xHCI, but I suspect that it is because it uses a
different urb->interval than EHCI.

Forwarded message:

Date: Wed, 08 Jan 2014 16:03:51 -0200
From: Mauro Carvalho Chehab 
To: Sarah Sharp 
Cc: jean-philippe francois , linux-usb@vger.kernel.org, 
LMML , Shuah Khan 
Subject: Re: Isochronous transfer error on USB3


Em Wed, 08 Jan 2014 15:05:12 -0200
Mauro Carvalho Chehab  escreveu:

> Em Wed, 08 Jan 2014 14:31:28 -0200
> Mauro Carvalho Chehab  escreveu:
> 
> > Em Thu, 02 Jan 2014 14:07:22 -0800
> > Sarah Sharp  escreveu:
> > 
> > > On Sun, Dec 29, 2013 at 02:54:40AM -0200, Mauro Carvalho Chehab wrote:
> > > > It seems that usb_unlink_urb() is causing troubles with xHCI: the
> > > > endpoint stops streaming, but, after that, it doesn't start again,
> > > > and lots of debug messages are produced. I emailed you the full log
> > > > after start streaming in priv (too big for vger), but basically, 
> > > > it produces:
> > > > 
> > > > [ 1635.754546] xhci_hcd :00:14.0: Endpoint 0x81 not halted, 
> > > > refusing to reset.
> > > > [ 1635.754562] xhci_hcd :00:14.0: Endpoint 0x82 not halted, 
> > > > refusing to reset.
> > > > [ 1635.754577] xhci_hcd :00:14.0: Endpoint 0x83 not halted, 
> > > > refusing to reset.
> > > > [ 1635.754594] xhci_hcd :00:14.0: Endpoint 0x84 not halted, 
> > > > refusing to reset.
> > > 
> > > I think that's due to the driver (or userspace) attempting to reset the
> > > endpoint when it didn't actually receive a stall (-EPIPE) status from an
> > > URB.  When that happens, the xHCI host controller endpoint "toggle" bits
> > > get out of sync with the device toggle bits, and the result is that all
> > > transfers will fail to the endpoint from then on until you switch
> > > alternate interface settings or unplug/replug the device.
> > > 
> > > Try this patch:
> > > 
> > > http://marc.info/?l=linux-usb&m=138116117104619&w=2
> > > 
> > > It's still under RFC, and I know it has race conditions, but it will let
> > > you quickly test whether this fixes your issue.
> > 
> > Didn't work fine, or at least it didn't solve all the problems. Also, it
> > started to cause OOPSes due to the race conditions.
> > 
> > > 
> > > This has been a long-standing xHCI driver bug.  I asked m

Re: [alsa-devel] Fw: Isochronous transfer error on USB3

[Mauro Carvalho Chehab]

Em Thu, 09 Jan 2014 09:17:13 +0100
Clemens Ladisch  escreveu:

> Mauro Carvalho Chehab wrote:
> > I'm getting an weird behavior with em28xx, especially when the device
> > is connected into an audio port.
> >
> > 
> > http://git.linuxtv.org/mchehab/experimental.git/blob/refs/heads/em28xx-v4l2-v6:/drivers/media/usb/em28xx/em28xx-audio.c
> >
> > What happens is that, when I require xawtv3 to use any latency lower
> > than 65 ms, the audio doesn't work, as it gets lots of underruns per
> > second.
> 
> The driver uses five URBs with 64 frames each, so of course it
> will not be able to properly handle periods smaller than that.
> 
> > FYI, em28xx works at a 48000 KHz sampling rate, and its PM capture Hw
> > is described as:
> >
> > static struct snd_pcm_hardware snd_em28xx_hw_capture = {
> > .info = SNDRV_PCM_INFO_BLOCK_TRANSFER |
> > SNDRV_PCM_INFO_MMAP   |
> > SNDRV_PCM_INFO_INTERLEAVED|
> > SNDRV_PCM_INFO_BATCH  |
> > SNDRV_PCM_INFO_MMAP_VALID,
> >
> > .formats = SNDRV_PCM_FMTBIT_S16_LE,
> >
> > .rates = SNDRV_PCM_RATE_CONTINUOUS | SNDRV_PCM_RATE_KNOT,
> 
> This should be just SNDRV_PCM_RATE_48000.

Ok.

> 
> > .period_bytes_min = 64, /* 12544/2, */
> 
> This is wrong (if the driver doesn't install other constraints on the
> period length, like the USB audio class driver does).

Ok, how should it be estimated? Those values here were simply glued from
the USB audio class driver a long time ago without a further analysis.

I changed it to 188 (the minimum URB size I experimentally noticed with
the current settings) and it is now working fine with both xHCI and EHCI.

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [alsa-devel] Fw: Isochronous transfer error on USB3

[Mauro Carvalho Chehab]

Em Thu, 9 Jan 2014 09:29:57 -0200
Mauro Carvalho Chehab  escreveu:

> Em Thu, 09 Jan 2014 09:17:13 +0100
> Clemens Ladisch  escreveu:
> 
> > Mauro Carvalho Chehab wrote:
> > > I'm getting an weird behavior with em28xx, especially when the device
> > > is connected into an audio port.
> > >
> > >   
> > > http://git.linuxtv.org/mchehab/experimental.git/blob/refs/heads/em28xx-v4l2-v6:/drivers/media/usb/em28xx/em28xx-audio.c
> > >
> > > What happens is that, when I require xawtv3 to use any latency lower
> > > than 65 ms, the audio doesn't work, as it gets lots of underruns per
> > > second.
> > 
> > The driver uses five URBs with 64 frames each, so of course it
> > will not be able to properly handle periods smaller than that.
> > 
> > > FYI, em28xx works at a 48000 KHz sampling rate, and its PM capture Hw
> > > is described as:
> > >
> > > static struct snd_pcm_hardware snd_em28xx_hw_capture = {
> > >   .info = SNDRV_PCM_INFO_BLOCK_TRANSFER |
> > >   SNDRV_PCM_INFO_MMAP   |
> > >   SNDRV_PCM_INFO_INTERLEAVED|
> > >   SNDRV_PCM_INFO_BATCH  |
> > >   SNDRV_PCM_INFO_MMAP_VALID,
> > >
> > >   .formats = SNDRV_PCM_FMTBIT_S16_LE,
> > >
> > >   .rates = SNDRV_PCM_RATE_CONTINUOUS | SNDRV_PCM_RATE_KNOT,
> > 
> > This should be just SNDRV_PCM_RATE_48000.
> 
> Ok.
> 
> > 
> > >   .period_bytes_min = 64, /* 12544/2, */
> > 
> > This is wrong (if the driver doesn't install other constraints on the
> > period length, like the USB audio class driver does).
> 
> Ok, how should it be estimated? Those values here were simply glued from
> the USB audio class driver a long time ago without a further analysis.
> 
> I changed it to 188 (the minimum URB size I experimentally noticed with
> the current settings) and it is now working fine with both xHCI and EHCI.

PS.: using 188 there, the URBs now have a total actual size of 24 bytes.

Regards,
-- 

Cheers,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: More than one isoc transfers with usb 2.0 hardware

[Mauro Carvalho Chehab]

On Fri, 8 Feb 2008 10:48:54 -0500 (EST)
Alan Stern <[EMAIL PROTECTED]> wrote:

> On Fri, 8 Feb 2008, Mauro Carvalho Chehab wrote:
> 
> > Hi Guys,
> > 
> > There's currently an issue with isoc transfers made by em28xx driver[1] and
> > ehcd_hci. If I try to start isoc transfers on more than one hardware, the
> > second hardware fails at usb_submit_urb() with -ENOSPC.
> 
> ENOSPC means that you are attempting to use more bandwidth than the bus
> allows.  A high-speed isochronous transfer of length 3072 requires 41%
> of the total bandwidth (according to Table 5-5 in the USB 2.0 spec),
> and periodic transfers (isochronous and interrupt) on a high-speed bus
> are limited to no more than 80% of the total bandwidth.
> 
> Performing transfers to two devices would require 82% of the bandwidth;
> hence it isn't allowed.

Thanks! I'll try to decrease the transfer length, using an alternative setting.

> > urb->transfer_flags = URB_ISO_ASAP;
> 
> Since you have set urb->transfer_dma, you also need to set 
> URB_NO_TRANSFER_DMA_MAP in urb->flags.

Added, thanks.
> 
> > urb->interval = 1;
> > urb->transfer_buffer = dev->transfer_buffer[i];
> > urb->complete = em28xx_isocIrq;
> > urb->number_of_packets = 40;
> > urb->transfer_buffer_length = size;
> > for (j = 0; j < 40; j++)
> > urb->iso_frame_desc[j].offset = j * max_pkt_size;
> 
> Where do you set urb->iso_frame_desc[i].length?

I've accidentally removed the code when cleaning the e-mail. The real code is
doing:
urb->iso_frame_desc[j].offset =  max_pkt_size;

> You may need to put your two devices on separate USB buses.

Thanks. The tests I'm doing are on a notebook. Unfortunately, all 4 usb ports
shares the same USB host. I'll repeat the tests on a device with separate usb
hosts.

Cheers,
Mauro
-
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

More than one isoc transfers with usb 2.0 hardware

[Mauro Carvalho Chehab]

Hi Guys,

There's currently an issue with isoc transfers made by em28xx driver[1] and
ehcd_hci. If I try to start isoc transfers on more than one hardware, the
second hardware fails at usb_submit_urb() with -ENOSPC.

The current code that initializes isoc transfers looks like this (I've removed
error handling and replaced some constants to make it cleaner to read):

max_pkt_size = 3072;
size = 40 * max_pkt_size;
for (i = 0; i < 5; i++) {
urb = usb_alloc_urb(40, GFP_KERNEL);
dev->transfer_buffer[i] = usb_buffer_alloc(usb_dev, size, 
GFP_KERNEL, &urb->transfer_dma);

memset(dev->transfer_buffer[i], 0, size);
urb->dev = usb_udev;
urb->context = v4l_dev;
urb->pipe = usb_rcvisocpipe(usb_dev, 0x82);
urb->transfer_flags = URB_ISO_ASAP;
urb->interval = 1;
urb->transfer_buffer = dev->transfer_buffer[i];
urb->complete = em28xx_isocIrq;
urb->number_of_packets = 40;
urb->transfer_buffer_length = size;
for (j = 0; j < 40; j++)
urb->iso_frame_desc[j].offset = j * max_pkt_size;
dev->urb[i] = urb;
}

for (i = 0; i < 5; i++)
usb_submit_urb(dev->urb[i], GFP_KERNEL);

Any ideas on how this could work?

[1] The complete code is at:
http://linuxtv.org/hg/v4l-dvb/file/3be355e3e327/linux/drivers/media/video/em28xx/em28xx-core.c

Cheers,
Mauro
-
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at  http://vger.kernel.org/majordomo-info.html