* USBIP protocol documentation?
@ 2011-05-24 18:28 Németh Márton
2011-05-24 18:34 ` Greg KH
0 siblings, 1 reply; 22+ messages in thread
From: Németh Márton @ 2011-05-24 18:28 UTC (permalink / raw)
To: Greg Kroah-Hartman, Matthew Wilcox; +Cc: linux-usb, LKML
Hi,
I'm looking for the USBIP protocol documentation. I found that
there was already a discussion about the USBIP protocol and
there is some draft about it:
* http://marc.info/?l=linux-kernel&m=122001863119269&w=2
* http://www.kernel.org/pub/linux/kernel/people/willy/usbip/usbip-protocol-draft-1
Unfortunately I couldn't found any detailed protocol documentation
on the project homepage:
* http://usbip.sourceforge.net/#documentation
Do you know any follow-up on the USBIP protocol documentation?
Regards,
Márton Németh
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: USBIP protocol documentation?
2011-05-24 18:28 USBIP protocol documentation? Németh Márton
@ 2011-05-24 18:34 ` Greg KH
2011-05-24 20:25 ` Németh Márton
0 siblings, 1 reply; 22+ messages in thread
From: Greg KH @ 2011-05-24 18:34 UTC (permalink / raw)
To: Németh Márton; +Cc: Matthew Wilcox, linux-usb, LKML
On Tue, May 24, 2011 at 08:28:13PM +0200, Németh Márton wrote:
> Hi,
>
> I'm looking for the USBIP protocol documentation. I found that
> there was already a discussion about the USBIP protocol and
> there is some draft about it:
>
> * http://marc.info/?l=linux-kernel&m=122001863119269&w=2
> * http://www.kernel.org/pub/linux/kernel/people/willy/usbip/usbip-protocol-draft-1
>
> Unfortunately I couldn't found any detailed protocol documentation
> on the project homepage:
>
> * http://usbip.sourceforge.net/#documentation
>
> Do you know any follow-up on the USBIP protocol documentation?
I think the code is the "real" documentation.
Note a number of developers are actively working on changing the protocol
and fixing it up based on Matthew's previous comments. Look at the
thread on the usbip project's mailing list for a few details. More will
be in the patches produced by the developers.
good luck,
greg k-h
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: USBIP protocol documentation?
2011-05-24 18:34 ` Greg KH
@ 2011-05-24 20:25 ` Németh Márton
2011-05-24 21:25 ` Greg KH
2011-05-25 3:12 ` matt mooney
0 siblings, 2 replies; 22+ messages in thread
From: Németh Márton @ 2011-05-24 20:25 UTC (permalink / raw)
To: Greg KH; +Cc: Matthew Wilcox, Matt Mooney, linux-usb, LKML, usbip-devel
Greg KH wrote:
> On Tue, May 24, 2011 at 08:28:13PM +0200, Németh Márton wrote:
>> Hi,
>>
>> I'm looking for the USBIP protocol documentation. I found that
>> there was already a discussion about the USBIP protocol and
>> there is some draft about it:
>>
>> * http://marc.info/?l=linux-kernel&m=122001863119269&w=2
>> * http://www.kernel.org/pub/linux/kernel/people/willy/usbip/usbip-protocol-draft-1
>>
>> Unfortunately I couldn't found any detailed protocol documentation
>> on the project homepage:
>>
>> * http://usbip.sourceforge.net/#documentation
>>
>> Do you know any follow-up on the USBIP protocol documentation?
>
> I think the code is the "real" documentation.
If it is, then I need to read it in the right way, through it is not an easy task.
I tried to find the points in the USBIP kernel code where opening, sending,
receiving and closing of the TCP connection takes place. I took all function names
from linux/net.h and I found the following places so far:
$ grep -n -E
'sock_wake_async|sock_register|sock_unregister|sock_create|sock_create_kern|sock_create_lite|sock_release|sock_sendmsg|sock_recvmsg|sock_map_fd|sockfd_lookup|sockfd_put|net_ratelimit|kernel_sendmsg|kernel_recvmsg|kernel_bind|kernel_listen|kernel_accept|kernel_connect|kernel_getsockname|kernel_getpeername|kernel_getsockopt|kernel_setsockopt|kernel_sendpage|kernel_sock_ioctl|kernel_sock_shutdown|SHUT_'
linux-2.6/drivers/staging/usbip/*
linux-2.6/drivers/staging/usbip/stub_dev.c:201: kernel_sock_shutdown(ud->tcp_socket, SHUT_RDWR);
linux-2.6/drivers/staging/usbip/stub_dev.c:216: sock_release(ud->tcp_socket);
linux-2.6/drivers/staging/usbip/stub_tx.c:263: ret = kernel_sendmsg(sdev->ud.tcp_socket, &msg,
linux-2.6/drivers/staging/usbip/stub_tx.c:338: ret = kernel_sendmsg(sdev->ud.tcp_socket, &msg, iov,
linux-2.6/drivers/staging/usbip/usbip_common.c:382: result = kernel_sendmsg(sock, &msg, &iov, 1, size);
linux-2.6/drivers/staging/usbip/usbip_common.c:384: result = kernel_recvmsg(sock, &msg, &iov, 1, size,
linux-2.6/drivers/staging/usbip/vhci_hcd.c:845: kernel_sock_shutdown(ud->tcp_socket, SHUT_RDWR);
linux-2.6/drivers/staging/usbip/vhci_hcd.c:858: sock_release(vdev->ud.tcp_socket);
linux-2.6/drivers/staging/usbip/vhci_tx.c:119: ret = kernel_sendmsg(vdev->ud.tcp_socket, &msg, iov, 3, txsize);
linux-2.6/drivers/staging/usbip/vhci_tx.c:189: ret = kernel_sendmsg(vdev->ud.tcp_socket, &msg, iov, 1, txsize);
I guess this is not all, there is also a protocol defined to the user-space world.
> Note a number of developers are actively working on changing the protocol
> and fixing it up based on Matthew's previous comments. Look at the
> thread on the usbip project's mailing list for a few details. More will
> be in the patches produced by the developers.
I had a look at the usbip-devel mailing list archive at
http://sourceforge.net/mailarchive/forum.php?forum_name=usbip-devel and found
a thread where I could find some protocol description also:
* http://sourceforge.net/mailarchive/message.php?msg_id=27240940
The current protocol implementation is based on top of TCP. In the message
at http://marc.info/?l=linux-kernel&m=122001883519653&w=2 the SCTP is mentioned.
Have anybody worked on finding out what benefits the SCTP could give to USBIP
and what would be the drawbacks?
Regards,
Márton Németh
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: USBIP protocol documentation?
2011-05-24 20:25 ` Németh Márton
@ 2011-05-24 21:25 ` Greg KH
2011-05-25 3:12 ` matt mooney
1 sibling, 0 replies; 22+ messages in thread
From: Greg KH @ 2011-05-24 21:25 UTC (permalink / raw)
To: Németh Márton
Cc: Matthew Wilcox, Matt Mooney, linux-usb, LKML, usbip-devel
On Tue, May 24, 2011 at 10:25:18PM +0200, Németh Márton wrote:
> The current protocol implementation is based on top of TCP. In the message
> at http://marc.info/?l=linux-kernel&m=122001883519653&w=2 the SCTP is mentioned.
> Have anybody worked on finding out what benefits the SCTP could give to USBIP
> and what would be the drawbacks?
It might not work well on Windows, which the current code does today.
I think that the TCP vs. SCTP is the least of the protocol issues at the
moment, there are lots of other things to work on :)
greg k-h
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: USBIP protocol documentation?
2011-05-24 20:25 ` Németh Márton
2011-05-24 21:25 ` Greg KH
@ 2011-05-25 3:12 ` matt mooney
2011-05-25 5:29 ` Németh Márton
1 sibling, 1 reply; 22+ messages in thread
From: matt mooney @ 2011-05-25 3:12 UTC (permalink / raw)
To: N??meth M??rton; +Cc: Greg KH, Matthew Wilcox, linux-usb, LKML, usbip-devel
On 22:25 Tue 24 May , N??meth M??rton wrote:
> Greg KH wrote:
> > On Tue, May 24, 2011 at 08:28:13PM +0200, N??meth M??rton wrote:
> >> Hi,
> >>
> >> I'm looking for the USBIP protocol documentation. I found that
> >> there was already a discussion about the USBIP protocol and
> >> there is some draft about it:
> >>
> >> * http://marc.info/?l=linux-kernel&m=122001863119269&w=2
> >> * http://www.kernel.org/pub/linux/kernel/people/willy/usbip/usbip-protocol-draft-1
> >>
> >> Unfortunately I couldn't found any detailed protocol documentation
> >> on the project homepage:
> >>
> >> * http://usbip.sourceforge.net/#documentation
> >>
> >> Do you know any follow-up on the USBIP protocol documentation?
> >
> > I think the code is the "real" documentation.
I concur!
> If it is, then I need to read it in the right way, through it is not an easy task.
> I tried to find the points in the USBIP kernel code where opening, sending,
> receiving and closing of the TCP connection takes place. I took all function names
> from linux/net.h and I found the following places so far:
>
> $ grep -n -E
> 'sock_wake_async|sock_register|sock_unregister|sock_create|sock_create_kern|sock_create_lite|sock_release|sock_sendmsg|sock_recvmsg|sock_map_fd|sockfd_lookup|sockfd_put|net_ratelimit|kernel_sendmsg|kernel_recvmsg|kernel_bind|kernel_listen|kernel_accept|kernel_connect|kernel_getsockname|kernel_getpeername|kernel_getsockopt|kernel_setsockopt|kernel_sendpage|kernel_sock_ioctl|kernel_sock_shutdown|SHUT_'
> linux-2.6/drivers/staging/usbip/*
>
> linux-2.6/drivers/staging/usbip/stub_dev.c:201: kernel_sock_shutdown(ud->tcp_socket, SHUT_RDWR);
> linux-2.6/drivers/staging/usbip/stub_dev.c:216: sock_release(ud->tcp_socket);
> linux-2.6/drivers/staging/usbip/stub_tx.c:263: ret = kernel_sendmsg(sdev->ud.tcp_socket, &msg,
> linux-2.6/drivers/staging/usbip/stub_tx.c:338: ret = kernel_sendmsg(sdev->ud.tcp_socket, &msg, iov,
> linux-2.6/drivers/staging/usbip/usbip_common.c:382: result = kernel_sendmsg(sock, &msg, &iov, 1, size);
> linux-2.6/drivers/staging/usbip/usbip_common.c:384: result = kernel_recvmsg(sock, &msg, &iov, 1, size,
> linux-2.6/drivers/staging/usbip/vhci_hcd.c:845: kernel_sock_shutdown(ud->tcp_socket, SHUT_RDWR);
> linux-2.6/drivers/staging/usbip/vhci_hcd.c:858: sock_release(vdev->ud.tcp_socket);
> linux-2.6/drivers/staging/usbip/vhci_tx.c:119: ret = kernel_sendmsg(vdev->ud.tcp_socket, &msg, iov, 3, txsize);
> linux-2.6/drivers/staging/usbip/vhci_tx.c:189: ret = kernel_sendmsg(vdev->ud.tcp_socket, &msg, iov, 1, txsize);
>
> I guess this is not all, there is also a protocol defined to the user-space world.
Very true, and part of what is taking place is a unification of the userspace
and kernel protocols. Then there will be some degree of documentation. Mainly in
the form of packet diagrams to show on-wire communication.
> > Note a number of developers are actively working on changing the protocol
> > and fixing it up based on Matthew's previous comments. Look at the
> > thread on the usbip project's mailing list for a few details. More will
> > be in the patches produced by the developers.
>
> I had a look at the usbip-devel mailing list archive at
> http://sourceforge.net/mailarchive/forum.php?forum_name=usbip-devel and found
> a thread where I could find some protocol description also:
>
> * http://sourceforge.net/mailarchive/message.php?msg_id=27240940
>
> The current protocol implementation is based on top of TCP. In the message
> at http://marc.info/?l=linux-kernel&m=122001883519653&w=2 the SCTP is mentioned.
> Have anybody worked on finding out what benefits the SCTP could give to USBIP
> and what would be the drawbacks?
I think sctp would be interesting, but as greg said, and I tend to agree, this
is the least of usbip's problems.
(Maybe eliminating the need to interact w/ windows would be a good project ;)
jk!
-matt
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: USBIP protocol documentation?
2011-05-25 3:12 ` matt mooney
@ 2011-05-25 5:29 ` Németh Márton
2011-05-26 7:13 ` Németh Márton
0 siblings, 1 reply; 22+ messages in thread
From: Németh Márton @ 2011-05-25 5:29 UTC (permalink / raw)
To: Greg KH, Matthew Wilcox, linux-usb, LKML, usbip-devel
matt mooney wrote:
> On 22:25 Tue 24 May , Németh Márton wrote:
>> Greg KH wrote:
>>> I think the code is the "real" documentation.
>
> I concur!
>
>> If it is, then I need to read it in the right way, through it is not an easy task.
>> I tried to find the points in the USBIP kernel code where opening, sending,
>> receiving and closing of the TCP connection takes place. I took all function names
>> from linux/net.h and I found the following places so far:
>>
>> $ grep -n -E
>>
'sock_wake_async|sock_register|sock_unregister|sock_create|sock_create_kern|sock_create_lite|sock_release|sock_sendmsg|sock_recvmsg|sock_map_fd|sockfd_lookup|sockfd_put|net_ratelimit|kernel_sendmsg|kernel_recvmsg|kernel_bind|kernel_listen|kernel_accept|kernel_connect|kernel_getsockname|kernel_getpeername|kernel_getsockopt|kernel_setsockopt|kernel_sendpage|kernel_sock_ioctl|kernel_sock_shutdown|SHUT_'
>> linux-2.6/drivers/staging/usbip/*
>>
>> linux-2.6/drivers/staging/usbip/stub_dev.c:201: kernel_sock_shutdown(ud->tcp_socket, SHUT_RDWR);
>> linux-2.6/drivers/staging/usbip/stub_dev.c:216: sock_release(ud->tcp_socket);
>> linux-2.6/drivers/staging/usbip/stub_tx.c:263: ret = kernel_sendmsg(sdev->ud.tcp_socket, &msg,
>> linux-2.6/drivers/staging/usbip/stub_tx.c:338: ret = kernel_sendmsg(sdev->ud.tcp_socket, &msg, iov,
>> linux-2.6/drivers/staging/usbip/usbip_common.c:382: result = kernel_sendmsg(sock, &msg, &iov, 1, size);
>> linux-2.6/drivers/staging/usbip/usbip_common.c:384: result = kernel_recvmsg(sock, &msg, &iov, 1, size,
>> linux-2.6/drivers/staging/usbip/vhci_hcd.c:845: kernel_sock_shutdown(ud->tcp_socket, SHUT_RDWR);
>> linux-2.6/drivers/staging/usbip/vhci_hcd.c:858: sock_release(vdev->ud.tcp_socket);
>> linux-2.6/drivers/staging/usbip/vhci_tx.c:119: ret = kernel_sendmsg(vdev->ud.tcp_socket, &msg, iov, 3, txsize);
>> linux-2.6/drivers/staging/usbip/vhci_tx.c:189: ret = kernel_sendmsg(vdev->ud.tcp_socket, &msg, iov, 1, txsize);
>>
>> I guess this is not all, there is also a protocol defined to the user-space world.
>
> Very true, and part of what is taking place is a unification of the userspace
> and kernel protocols. Then there will be some degree of documentation. Mainly in
> the form of packet diagrams to show on-wire communication.
Could you please give some hints witch function names to look for and
where to start "reading" the source code to see how the userspace protocol
looks like?
> On Tue, May 24, 2011 at 10:25:18PM +0200, Németh Márton wrote:
>> The current protocol implementation is based on top of TCP. In the message
>> at http://marc.info/?l=linux-kernel&m=122001883519653&w=2 the SCTP is mentioned.
>> Have anybody worked on finding out what benefits the SCTP could give to USBIP
>> and what would be the drawbacks?
Greg KH wrote:
> It might not work well on Windows, which the current code does today.
>
> I think that the TCP vs. SCTP is the least of the protocol issues at the
> moment, there are lots of other things to work on :)
matt mooney wrote:
> I think sctp would be interesting, but as greg said, and I tend to agree, this
> is the least of usbip's problems.
>
> (Maybe eliminating the need to interact w/ windows would be a good project ;)
> jk!
OK, I see your point. I tried to check the "source code" for a TODO list,
but I think I failed at that point because I just found:
| $ cat linux-2.6/drivers/staging/usbip/README
| TODO:
| - more discussion about the protocol
| - testing
| - review of the userspace interface
|
| Please send patches for this code to Greg Kroah-Hartman <greg@kroah.com>
These are quite hard tasks to solve. More discussion about the protocol? I
think the first problem is that it is difficult (at least for me) to see clearly
the protocol because of lack of documentation.
Testing: when you test something you compare the running code against something.
If you compare the running code against the source code then you will not test
the USBIP implementation/protocol, but the compiler itself, whether the compiler
generated the same code which is available in source format.
Review of the userspace interface: first I will need to understand how it looks
like befor I can do anything on this point.
Do you have a bit detailed TODO list somewhere written down or in your heads
so beginners can also help? E.g. running "scripts/checkpatch.pl -f" and
solving the errors/warnings helps at this point? Or compiling with "make W=1 C=1 ..."
and solving those warnings helps?
Regards,
Márton Németh
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: USBIP protocol documentation?
2011-05-25 5:29 ` Németh Márton
@ 2011-05-26 7:13 ` Németh Márton
2011-06-28 6:52 ` [PATCH, RFC] USBIP protocol documentation Németh Márton
0 siblings, 1 reply; 22+ messages in thread
From: Németh Márton @ 2011-05-26 7:13 UTC (permalink / raw)
To: Greg KH, Matthew Wilcox, linux-usb, LKML, usbip-devel
Németh Márton wrote:
> matt mooney wrote:
>> On 22:25 Tue 24 May , Németh Márton wrote:
>>> Greg KH wrote:
>>>> I think the code is the "real" documentation.
>> I concur!
>>
>>> If it is, then I need to read it in the right way, through it is not an easy task.
>>> I tried to find the points in the USBIP kernel code where opening, sending,
>>> receiving and closing of the TCP connection takes place. I took all function names
>>> from linux/net.h and I found the following places so far:
>>>
>>> $ grep -n -E
>>>
> 'sock_wake_async|sock_register|sock_unregister|sock_create|sock_create_kern|sock_create_lite|sock_release|sock_sendmsg|sock_recvmsg|sock_map_fd|sockfd_lookup|sockfd_put|net_ratelimit|kernel_sendmsg|kernel_recvmsg|kernel_bind|kernel_listen|kernel_accept|kernel_connect|kernel_getsockname|kernel_getpeername|kernel_getsockopt|kernel_setsockopt|kernel_sendpage|kernel_sock_ioctl|kernel_sock_shutdown|SHUT_'
>>> linux-2.6/drivers/staging/usbip/*
>>>
>>> linux-2.6/drivers/staging/usbip/stub_dev.c:201: kernel_sock_shutdown(ud->tcp_socket, SHUT_RDWR);
>>> linux-2.6/drivers/staging/usbip/stub_dev.c:216: sock_release(ud->tcp_socket);
>>> linux-2.6/drivers/staging/usbip/stub_tx.c:263: ret = kernel_sendmsg(sdev->ud.tcp_socket, &msg,
>>> linux-2.6/drivers/staging/usbip/stub_tx.c:338: ret = kernel_sendmsg(sdev->ud.tcp_socket, &msg, iov,
>>> linux-2.6/drivers/staging/usbip/usbip_common.c:382: result = kernel_sendmsg(sock, &msg, &iov, 1, size);
>>> linux-2.6/drivers/staging/usbip/usbip_common.c:384: result = kernel_recvmsg(sock, &msg, &iov, 1, size,
>>> linux-2.6/drivers/staging/usbip/vhci_hcd.c:845: kernel_sock_shutdown(ud->tcp_socket, SHUT_RDWR);
>>> linux-2.6/drivers/staging/usbip/vhci_hcd.c:858: sock_release(vdev->ud.tcp_socket);
>>> linux-2.6/drivers/staging/usbip/vhci_tx.c:119: ret = kernel_sendmsg(vdev->ud.tcp_socket, &msg, iov, 3, txsize);
>>> linux-2.6/drivers/staging/usbip/vhci_tx.c:189: ret = kernel_sendmsg(vdev->ud.tcp_socket, &msg, iov, 1, txsize);
>>>
>>> I guess this is not all, there is also a protocol defined to the user-space world.
>> Very true, and part of what is taking place is a unification of the userspace
>> and kernel protocols. Then there will be some degree of documentation. Mainly in
>> the form of packet diagrams to show on-wire communication.
>
> Could you please give some hints witch function names to look for and
> where to start "reading" the source code to see how the userspace protocol
> looks like?
I think I found a good way to "read out" from the source code where the userspace
communication takes palce:
$ grep -n DEVICE_ATTR linux-2.6/drivers/staging/usbip/*
linux-2.6/drivers/staging/usbip/stub_dev.c:85:static DEVICE_ATTR(usbip_status, S_IRUGO, show_status, NULL);
linux-2.6/drivers/staging/usbip/stub_dev.c:153:static DEVICE_ATTR(usbip_sockfd, S_IWUSR, NULL, store_sockfd);
linux-2.6/drivers/staging/usbip/usbip_common.c:55:DEVICE_ATTR(usbip_debug, (S_IRUGO | S_IWUSR), show_flag, store_flag);
linux-2.6/drivers/staging/usbip/vhci_sysfs.c:76:static DEVICE_ATTR(status, S_IRUGO, show_status, NULL);
linux-2.6/drivers/staging/usbip/vhci_sysfs.c:132:static DEVICE_ATTR(detach, S_IWUSR, NULL, store_detach);
linux-2.6/drivers/staging/usbip/vhci_sysfs.c:232:static DEVICE_ATTR(attach, S_IWUSR, NULL, store_attach);
The DEVICE_ATTR macro is defined in linux/device.h . Its first parameter is used as
a postfix and this postfix will be added to the dev_attr_ to create variable names.
In this case the variable names will be dev_attr_usbip_status, dev_attr_usbip_sockfd,
dev_attr_usbip_debug, dev_attr_status, dev_attr_detach and dev_attr_attach.
The type of the variables will be struct device_attribute. The struct device_attribute
is also defined in linux/device.h . It contains a struct attribute, and two fuction
pointers: one for show and one for store. The struct attribute is defined in
linux/sysfs.h . Here we see that we have a name and a mode parameter.
The fist parameter of DEVICE_ATTR macro is also used for the second time. The
parameter is first stringified (i.e. usbip_status -> "usbip_status") and used to
initialize the name in the struct attribute.
The second parameter of DEVICE_ATTR will be used to initialize the mode attrubute.
The third and fourth parameter is used to initialize the show and store function
pointers, respectively.
What is not clear for me is the return value of the store functions. Usually
the sscanf() function is used to parse the buffer from the userspace. The sscanf()
function is declared in linux/kernel.h and has int return value. In USBIP code
the return value is ignored and the count value is used instead. I don't think
it is a good idea, but I might overseen something (for example trailing whitespaces?).
I hope writing down of how I understand reading the code will help others
also so they can understand USBIP easier than me.
>> On Tue, May 24, 2011 at 10:25:18PM +0200, Németh Márton wrote:
>>> The current protocol implementation is based on top of TCP. In the message
>>> at http://marc.info/?l=linux-kernel&m=122001883519653&w=2 the SCTP is mentioned.
>>> Have anybody worked on finding out what benefits the SCTP could give to USBIP
>>> and what would be the drawbacks?
>
> Greg KH wrote:
>> It might not work well on Windows, which the current code does today.
>>
>> I think that the TCP vs. SCTP is the least of the protocol issues at the
>> moment, there are lots of other things to work on :)
>
> matt mooney wrote:
>> I think sctp would be interesting, but as greg said, and I tend to agree, this
>> is the least of usbip's problems.
>>
>> (Maybe eliminating the need to interact w/ windows would be a good project ;)
>> jk!
>
> OK, I see your point. I tried to check the "source code" for a TODO list,
> but I think I failed at that point because I just found:
>
> | $ cat linux-2.6/drivers/staging/usbip/README
> | TODO:
> | - more discussion about the protocol
> | - testing
> | - review of the userspace interface
> |
> | Please send patches for this code to Greg Kroah-Hartman <greg@kroah.com>
>
> These are quite hard tasks to solve. More discussion about the protocol? I
> think the first problem is that it is difficult (at least for me) to see clearly
> the protocol because of lack of documentation.
>
> Testing: when you test something you compare the running code against something.
> If you compare the running code against the source code then you will not test
> the USBIP implementation/protocol, but the compiler itself, whether the compiler
> generated the same code which is available in source format.
>
> Review of the userspace interface: first I will need to understand how it looks
> like befor I can do anything on this point.
>
> Do you have a bit detailed TODO list somewhere written down or in your heads
> so beginners can also help? E.g. running "scripts/checkpatch.pl -f" and
> solving the errors/warnings helps at this point? Or compiling with "make W=1 C=1 ..."
> and solving those warnings helps?
>
> Regards,
>
> Márton Németh
>
^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCH, RFC] USBIP protocol documentation
2011-05-26 7:13 ` Németh Márton
@ 2011-06-28 6:52 ` Németh Márton
2011-06-29 8:04 ` David Chang
` (2 more replies)
0 siblings, 3 replies; 22+ messages in thread
From: Németh Márton @ 2011-06-28 6:52 UTC (permalink / raw)
To: Greg KH, Matthew Wilcox, Max Vozeler, Matt Mooney, Joe Perches,
David Chang, linux-usb, usbip-devel, devel
Cc: LKML
From: Márton Németh <nm127@freemail.hu>
USBIP v1.0.0 protocol documentation.
Signed-off-by: Márton Németh <nm127@freemail.hu>
---
Hi,
I tried to document the USBIP protocol as implemented in the Linux kernel 3.0-rc2.
The description is a preliminary draft only, it may contain mistakes. I tried
to document what I have understand from the source code and from the actual
captured network traffic when the USBIP is in action. Please review it, correct it,
point out the missing parts.
During I have documented the protocol a question came into my mind: why do we
have two different type of package when the URB completition handler is called,
namely USB_RET_SUBMIT and USBIP_RET_UNLINK? As far as I can see this causes race
condition because for one URB the completition handler is only called once. If
the one URB is sent in with USB_CMD_SUBMIT and then unlinked with USB_CMD_UNLINK
the completition handler is called only once. In the protocol, however, we have
two different type of packets: USB_RET_SUBMIT and USBIP_RET_UNLINK. The status
field of these messages may contain anything in this case depending on the timing.
Regards,
Márton Németh
---
diff -uprN staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt staging-2.6/drivers/staging/usbip/usbip_protocol.txt
--- staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt 1970-01-01 01:00:00.000000000 +0100
+++ staging-2.6/drivers/staging/usbip/usbip_protocol.txt 2011-06-28 08:30:04.000000000 +0200
@@ -0,0 +1,352 @@
+PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
+28 Jun 2011
+
+The USB/IP protocol follows a server/client architecture. The server exports the
+USB devices and the clients imports them. The device driver for the exported
+USB device runs on the client machine.
+
+The client may ask for the list of the exported USB devices. To get the list the
+client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST
+packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent
+in one or more pieces at the low level transport layer). The server sends back
+the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the
+TCP/IP connection is closed.
+
+ virtual host controller usb host
+ "client" "server"
+ (imports USB devices) (exports USB devices)
+ | |
+ | OP_REQ_DEVLIST |
+ | ----------------------------------------------> |
+ | |
+ | OP_REP_DEVLIST |
+ | <---------------------------------------------- |
+ | |
+
+Once the client knows the list of exported USB devices it may decide to use one
+of them. First the client opens a TCP/IP connection towards the server and
+sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the
+import was successful the TCP/IP connection remains open and will be used
+to trasfer the URB traffic between the client and the server. The client may
+send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
+USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the
+server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
+
+ virtual host controller usb host
+ "client" "server"
+ (imports USB devices) (exports USB devices)
+ | |
+ | OP_REQ_IMPORT |
+ | ----------------------------------------------> |
+ | |
+ | OP_REP_IMPORT |
+ | <---------------------------------------------- |
+ | |
+ | |
+ | USBIP_CMD_SUBMIT(seqnum = n) |
+ | ----------------------------------------------> |
+ | |
+ | USBIP_RET_SUBMIT(seqnum = n) |
+ | <---------------------------------------------- |
+ | . |
+ | : |
+ | |
+ | USBIP_CMD_SUBMIT(seqnum = m) |
+ | ----------------------------------------------> |
+ | |
+ | USBIP_CMD_SUBMIT(seqnum = m+1) |
+ | ----------------------------------------------> |
+ | |
+ | USBIP_CMD_SUBMIT(seqnum = m+2) |
+ | ----------------------------------------------> |
+ | |
+ | USBIP_RET_SUBMIT(seqnum = m) |
+ | <---------------------------------------------- |
+ | |
+ | USBIP_CMD_SUBMIT(seqnum = m+3) |
+ | ----------------------------------------------> |
+ | |
+ | USBIP_RET_SUBMIT(seqnum = m+1) |
+ | <---------------------------------------------- |
+ | |
+ | USBIP_CMD_SUBMIT(seqnum = m+4) |
+ | ----------------------------------------------> |
+ | |
+ | USBIP_RET_SUBMIT(seqnum = m+2) |
+ | <---------------------------------------------- |
+ | . |
+ | : |
+ | |
+ | USBIP_CMD_UNLINK |
+ | ----------------------------------------------> |
+ | |
+ | USBIP_RET_UNLINK |
+ | <---------------------------------------------- |
+ | |
+
+The fields are in network (big endian) byte order meaning that the most significant
+byte (MSB) is stored at the lowest address.
+
+
+OP_REQ_DEVLIST: Retrieve the list of exported USB devices.
+
+ Offset | Length | Value | Meaning
+-----------+--------+------------+---------------------------------------------------
+ 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
+-----------+--------+------------+---------------------------------------------------
+ 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB
+ | | | devices.
+-----------+--------+------------+---------------------------------------------------
+ 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
+
+OP_REP_DEVLIST: Reply with the list of exported USB devices.
+
+ Offset | Length | Value | Meaning
+-----------+--------+------------+---------------------------------------------------
+ 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0.
+-----------+--------+------------+---------------------------------------------------
+ 2 | 2 | 0x0005 | Reply code: The list of exported USB devices.
+-----------+--------+------------+---------------------------------------------------
+ 4 | 4 | 0x00000000 | Status: 0 for OK
+-----------+--------+------------+---------------------------------------------------
+ 8 | 4 | n | Number of exported devices: 0 means no exported
+ | | | devices.
+-----------+--------+------------+---------------------------------------------------
+ 0x0C | | | From now on the exported n devices are described,
+ | | | if any. If no devices are exported the message
+ | | | ends with the previous "number of exported
+ | | | devices" field.
+-----------+--------+------------+---------------------------------------------------
+ | 256 | | path: Path of the device on the host exporting the
+ | | | USB device, string closed with zero byte, e.g.
+ | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
+ | | | The unused bytes shall be filled with zero
+ | | | bytes.
+-----------+--------+------------+---------------------------------------------------
+ 0x10C | 32 | | busid: Bus ID of the exported device, string
+ | | | closed with zero byte, e.g. "3-2". The unused
+ | | | bytes shall be filled with zero bytes.
+-----------+--------+------------+---------------------------------------------------
+ 0x12C | 4 | | busnum
+-----------+--------+------------+---------------------------------------------------
+ 0x130 | 4 | | devnum
+-----------+--------+------------+---------------------------------------------------
+ 0x134 | 4 | | speed
+-----------+--------+------------+---------------------------------------------------
+ 0x138 | 2 | | idVendor
+-----------+--------+------------+---------------------------------------------------
+ 0x13A | 2 | | idProduct
+-----------+--------+------------+---------------------------------------------------
+ 0x13C | 2 | | bcdDevice
+-----------+--------+------------+---------------------------------------------------
+ 0x13E | 1 | | bDeviceClass
+-----------+--------+------------+---------------------------------------------------
+ 0x13F | 1 | | bDeviceSubClass
+-----------+--------+------------+---------------------------------------------------
+ 0x140 | 1 | | bDeviceProtocol
+-----------+--------+------------+---------------------------------------------------
+ 0x141 | 1 | | bConfigurationValue
+-----------+--------+------------+---------------------------------------------------
+ 0x142 | 1 | | bNumConfigurations
+-----------+--------+------------+---------------------------------------------------
+ 0x143 | 1 | | bNumInterfaces
+-----------+--------+------------+---------------------------------------------------
+ 0x144 | | m_0 | From now on each interface is described, all
+ | | | together bNumInterfaces times, with the
+ | | | the following 4 fields:
+-----------+--------+------------+---------------------------------------------------
+ | 1 | | bInterfaceClass
+-----------+--------+------------+---------------------------------------------------
+ 0x145 | 1 | | bInterfaceSubClass
+-----------+--------+------------+---------------------------------------------------
+ 0x146 | 1 | | bInterfaceProtocol
+-----------+--------+------------+---------------------------------------------------
+ 0x147 | 1 | | padding byte for alignment, shall be set to zero
+-----------+--------+------------+---------------------------------------------------
+ 0xC + | | | The second exported USB device starts at i=1
+ i*0x138 + | | | with the busid field.
+ m_(i-1)*4 | | |
+
+OP_REQ_IMPORT: Request to import (attach) a remote USB device.
+
+ Offset | Length | Value | Meaning
+-----------+--------+------------+---------------------------------------------------
+ 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
+-----------+--------+------------+---------------------------------------------------
+ 2 | 2 | 0x8003 | Command code: import a remote USB device.
+-----------+--------+------------+---------------------------------------------------
+ 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
+-----------+--------+------------+---------------------------------------------------
+ 8 | 32 | | busid: the busid of the exported device on the
+ | | | remote host. The possible values are taken
+ | | | from the message field OP_REP_DEVLIST.busid.
+ | | | A string closed with zero, the unused bytes
+ | | | shall be filled with zeros.
+-----------+--------+------------+---------------------------------------------------
+
+OP_REP_IMPORT: Reply to import (attach) a remote USB device.
+
+ Offset | Length | Value | Meaning
+-----------+--------+------------+---------------------------------------------------
+ 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
+-----------+--------+------------+---------------------------------------------------
+ 2 | 2 | 0x0003 | Reply code: Reply to import.
+-----------+--------+------------+---------------------------------------------------
+ 4 | 4 | 0x00000000 | Status: 0 for OK
+ | | | 1 for error
+-----------+--------+------------+---------------------------------------------------
+ 8 | | | From now on comes the details of the imported
+ | | | device, if the previous status field was OK (0),
+ | | | otherwise the reply ends with the status field.
+-----------+--------+------------+---------------------------------------------------
+ | 256 | | path: Path of the device on the host exporting the
+ | | | USB device, string closed with zero byte, e.g.
+ | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
+ | | | The unused bytes shall be filled with zero
+ | | | bytes.
+-----------+--------+------------+---------------------------------------------------
+ 0x108 | 32 | | busid: Bus ID of the exported device, string
+ | | | closed with zero byte, e.g. "3-2". The unused
+ | | | bytes shall be filled with zero bytes.
+-----------+--------+------------+---------------------------------------------------
+ 0x128 | 4 | | busnum
+-----------+--------+------------+---------------------------------------------------
+ 0x12C | 4 | | devnum
+-----------+--------+------------+---------------------------------------------------
+ 0x130 | 4 | | speed
+-----------+--------+------------+---------------------------------------------------
+ 0x134 | 2 | | idVendor
+-----------+--------+------------+---------------------------------------------------
+ 0x136 | 2 | | idProduct
+-----------+--------+------------+---------------------------------------------------
+ 0x138 | 2 | | bcdDevice
+-----------+--------+------------+---------------------------------------------------
+ 0x139 | 1 | | bDeviceClass
+-----------+--------+------------+---------------------------------------------------
+ 0x13A | 1 | | bDeviceSubClass
+-----------+--------+------------+---------------------------------------------------
+ 0x13B | 1 | | bDeviceProtocol
+-----------+--------+------------+---------------------------------------------------
+ 0x13C | 1 | | bConfigurationValue
+-----------+--------+------------+---------------------------------------------------
+ 0x13D | 1 | | bNumConfigurations
+-----------+--------+------------+---------------------------------------------------
+ 0x13E | 1 | | bNumInterfaces
+
+USBIP_CMD_SUBMIT: Submit an URB
+
+ Offset | Length | Value | Meaning
+-----------+--------+------------+---------------------------------------------------
+ 0 | 4 | 0x00000001 | command: Submit an URB
+-----------+--------+------------+---------------------------------------------------
+ 4 | 4 | | seqnum: the sequence number of the URB to submit
+-----------+--------+------------+---------------------------------------------------
+ 8 | 4 | | devid
+-----------+--------+------------+---------------------------------------------------
+ 0xC | 4 | | direction: 0: USBIP_DIR_IN
+ | | | 1: USBIP_DIR_OUT
+-----------+--------+------------+---------------------------------------------------
+ 0x10 | 4 | | ep: endpoint number, possible values are: 0...15
+-----------+--------+------------+---------------------------------------------------
+ 0x14 | 4 | | transfer_flags: possible values depend on the
+ | | | URB transfer type, see below
+-----------+--------+------------+---------------------------------------------------
+ 0x18 | 4 | | transfer_buffer_length
+-----------+--------+------------+---------------------------------------------------
+ 0x1C | 4 | | start_frame: specify the selected frame to
+ | | | transmit an ISO frame, ignored if URB_ISO_ASAP
+ | | | is specified at transfer_flags
+-----------+--------+------------+---------------------------------------------------
+ 0x20 | 4 | | number_of_packets: number of ISO packets
+-----------+--------+------------+---------------------------------------------------
+ 0x24 | 4 | | interval: maximum time for the request on the
+ | | | server-side host controller
+-----------+--------+------------+---------------------------------------------------
+ 0x28 | 8 | | setup: data bytes for USB setup, filled with
+ | | | zeros if not used
+-----------+--------+------------+---------------------------------------------------
+ 0x30 | | | URB data. For ISO transfers the padding between
+ | | | each ISO packets is not transmitted.
+
+
+ Allowed transfer_flags | value | control | interrupt | bulk | isochronous
+ -------------------------+------------+---------+-----------+----------+-------------
+ URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no
+ URB_ISO_ASAP | 0x00000002 | no | no | no | yes
+ URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes
+ URB_NO_FSBR | 0x00000020 | yes | no | no | no
+ URB_ZERO_PACKET | 0x00000040 | no | no | only out | no
+ URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes
+ URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes
+ URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes
+
+
+USBIP_RET_SUBMIT: Reply for submitting an URB
+
+ Offset | Length | Value | Meaning
+-----------+--------+------------+---------------------------------------------------
+ 0 | 4 | 0x00000002 | command
+-----------+--------+------------+---------------------------------------------------
+ 4 | 4 | | seqnum: URB sequence number
+-----------+--------+------------+---------------------------------------------------
+ 8 | 4 | | devid
+-----------+--------+------------+---------------------------------------------------
+ 0xC | 4 | | direction: 0: USBIP_DIR_IN
+ | | | 1: USBIP_DIR_OUT
+-----------+--------+------------+---------------------------------------------------
+ 0x10 | 4 | | ep: endpoint number
+-----------+--------+------------+---------------------------------------------------
+ 0x14 | 4 | | status: zero for successful URB transaction,
+ | | | otherwise some kind of error happened.
+-----------+--------+------------+---------------------------------------------------
+ 0x18 | 4 | n | actual_length: number of URB data bytes
+-----------+--------+------------+---------------------------------------------------
+ 0x1C | 4 | | start_frame: for an ISO frame the actually
+ | | | selected frame for transmit.
+-----------+--------+------------+---------------------------------------------------
+ 0x20 | 4 | | number_of_packets
+-----------+--------+------------+---------------------------------------------------
+ 0x24 | 4 | | error_count
+-----------+--------+------------+---------------------------------------------------
+ 0x28 | 8 | | setup: data bytes for USB setup, filled with
+ | | | zeros if not used
+-----------+--------+------------+---------------------------------------------------
+ 0x30 | n | | URB data bytes. For ISO transfers the padding
+ | | | between each ISO packets is not transmitted.
+
+USBIP_CMD_UNLINK: Unlink an URB
+
+ Offset | Length | Value | Meaning
+-----------+--------+------------+---------------------------------------------------
+ 0 | 4 | 0x00000003 | command: URB unlink command
+-----------+--------+------------+---------------------------------------------------
+ 4 | 4 | | seqnum: URB sequence number to unlink: FIXME: is this so?
+-----------+--------+------------+---------------------------------------------------
+ 8 | 4 | | devid
+-----------+--------+------------+---------------------------------------------------
+ 0xC | 4 | | direction: 0: USBIP_DIR_IN
+ | | | 1: USBIP_DIR_OUT
+-----------+--------+------------+---------------------------------------------------
+ 0x10 | 4 | | ep: endpoint number: zero
+-----------+--------+------------+---------------------------------------------------
+ 0x14 | 4 | | seqnum: the URB sequence number given previously
+ | | | at USBIP_CMD_SUBMIT.seqnum field
+
+USBIP_RET_UNLINK: Reply for URB unlink
+
+ Offset | Length | Value | Meaning
+-----------+--------+------------+---------------------------------------------------
+ 0 | 4 | 0x00000004 | command: reply for the URB unlink command
+-----------+--------+------------+---------------------------------------------------
+ 4 | 4 | | seqnum: the unlinked URB sequence number
+-----------+--------+------------+---------------------------------------------------
+ 8 | 4 | | devid
+-----------+--------+------------+---------------------------------------------------
+ 0xC | 4 | | direction: 0: USBIP_DIR_IN
+ | | | 1: USBIP_DIR_OUT
+-----------+--------+------------+---------------------------------------------------
+ 0x10 | 4 | | ep: endpoint number
+-----------+--------+------------+---------------------------------------------------
+ 0x14 | 4 | | status: This is the value contained in the
+ | | | urb->status in the URB completition handler.
+ | | | FIXME: a better explanation needed.
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-06-28 6:52 ` [PATCH, RFC] USBIP protocol documentation Németh Márton
@ 2011-06-29 8:04 ` David Chang
2011-07-04 3:11 ` David Chang
2011-06-29 23:34 ` matt mooney
2011-08-09 9:23 ` David Chang
2 siblings, 1 reply; 22+ messages in thread
From: David Chang @ 2011-06-29 8:04 UTC (permalink / raw)
To: Németh Márton
Cc: Greg KH, Matthew Wilcox, Max Vozeler, Matt Mooney, Joe Perches,
linux-usb, usbip-devel, devel, LKML
Hi,
Thanks for your great effort.
Just a little comment on UNLINK pdu size.
2011/6/28 Németh Márton <nm127@freemail.hu>:
> From: Márton Németh <nm127@freemail.hu>
>
> USBIP v1.0.0 protocol documentation.
>
> Signed-off-by: Márton Németh <nm127@freemail.hu>
> ---
>
> Hi,
>
> I tried to document the USBIP protocol as implemented in the Linux kernel 3.0-rc2.
>
> The description is a preliminary draft only, it may contain mistakes. I tried
> to document what I have understand from the source code and from the actual
> captured network traffic when the USBIP is in action. Please review it, correct it,
> point out the missing parts.
>
> During I have documented the protocol a question came into my mind: why do we
> have two different type of package when the URB completition handler is called,
> namely USB_RET_SUBMIT and USBIP_RET_UNLINK? As far as I can see this causes race
> condition because for one URB the completition handler is only called once. If
> the one URB is sent in with USB_CMD_SUBMIT and then unlinked with USB_CMD_UNLINK
> the completition handler is called only once. In the protocol, however, we have
> two different type of packets: USB_RET_SUBMIT and USBIP_RET_UNLINK. The status
> field of these messages may contain anything in this case depending on the timing.
>
> Regards,
>
> Márton Németh
> ---
> diff -uprN staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt staging-2.6/drivers/staging/usbip/usbip_protocol.txt
> --- staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt 1970-01-01 01:00:00.000000000 +0100
> +++ staging-2.6/drivers/staging/usbip/usbip_protocol.txt 2011-06-28 08:30:04.000000000 +0200
> @@ -0,0 +1,352 @@
> +PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
> +28 Jun 2011
> +
> +The USB/IP protocol follows a server/client architecture. The server exports the
> +USB devices and the clients imports them. The device driver for the exported
> +USB device runs on the client machine.
> +
> +The client may ask for the list of the exported USB devices. To get the list the
> +client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST
> +packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent
> +in one or more pieces at the low level transport layer). The server sends back
> +the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the
> +TCP/IP connection is closed.
> +
> + virtual host controller usb host
> + "client" "server"
> + (imports USB devices) (exports USB devices)
> + | |
> + | OP_REQ_DEVLIST |
> + | ----------------------------------------------> |
> + | |
> + | OP_REP_DEVLIST |
> + | <---------------------------------------------- |
> + | |
> +
> +Once the client knows the list of exported USB devices it may decide to use one
> +of them. First the client opens a TCP/IP connection towards the server and
> +sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the
> +import was successful the TCP/IP connection remains open and will be used
> +to trasfer the URB traffic between the client and the server. The client may
> +send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
> +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the
> +server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
> +
> + virtual host controller usb host
> + "client" "server"
> + (imports USB devices) (exports USB devices)
> + | |
> + | OP_REQ_IMPORT |
> + | ----------------------------------------------> |
> + | |
> + | OP_REP_IMPORT |
> + | <---------------------------------------------- |
> + | |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = n) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_RET_SUBMIT(seqnum = n) |
> + | <---------------------------------------------- |
> + | . |
> + | : |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = m) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = m+1) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = m+2) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_RET_SUBMIT(seqnum = m) |
> + | <---------------------------------------------- |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = m+3) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_RET_SUBMIT(seqnum = m+1) |
> + | <---------------------------------------------- |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = m+4) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_RET_SUBMIT(seqnum = m+2) |
> + | <---------------------------------------------- |
> + | . |
> + | : |
> + | |
> + | USBIP_CMD_UNLINK |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_RET_UNLINK |
> + | <---------------------------------------------- |
> + | |
> +
> +The fields are in network (big endian) byte order meaning that the most significant
> +byte (MSB) is stored at the lowest address.
> +
> +
> +OP_REQ_DEVLIST: Retrieve the list of exported USB devices.
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
> +-----------+--------+------------+---------------------------------------------------
> + 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB
> + | | | devices.
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
> +
> +OP_REP_DEVLIST: Reply with the list of exported USB devices.
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0.
> +-----------+--------+------------+---------------------------------------------------
> + 2 | 2 | 0x0005 | Reply code: The list of exported USB devices.
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | 0x00000000 | Status: 0 for OK
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 4 | n | Number of exported devices: 0 means no exported
> + | | | devices.
> +-----------+--------+------------+---------------------------------------------------
> + 0x0C | | | From now on the exported n devices are described,
> + | | | if any. If no devices are exported the message
> + | | | ends with the previous "number of exported
> + | | | devices" field.
> +-----------+--------+------------+---------------------------------------------------
> + | 256 | | path: Path of the device on the host exporting the
> + | | | USB device, string closed with zero byte, e.g.
> + | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
> + | | | The unused bytes shall be filled with zero
> + | | | bytes.
> +-----------+--------+------------+---------------------------------------------------
> + 0x10C | 32 | | busid: Bus ID of the exported device, string
> + | | | closed with zero byte, e.g. "3-2". The unused
> + | | | bytes shall be filled with zero bytes.
> +-----------+--------+------------+---------------------------------------------------
> + 0x12C | 4 | | busnum
> +-----------+--------+------------+---------------------------------------------------
> + 0x130 | 4 | | devnum
> +-----------+--------+------------+---------------------------------------------------
> + 0x134 | 4 | | speed
> +-----------+--------+------------+---------------------------------------------------
> + 0x138 | 2 | | idVendor
> +-----------+--------+------------+---------------------------------------------------
> + 0x13A | 2 | | idProduct
> +-----------+--------+------------+---------------------------------------------------
> + 0x13C | 2 | | bcdDevice
> +-----------+--------+------------+---------------------------------------------------
> + 0x13E | 1 | | bDeviceClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x13F | 1 | | bDeviceSubClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x140 | 1 | | bDeviceProtocol
> +-----------+--------+------------+---------------------------------------------------
> + 0x141 | 1 | | bConfigurationValue
> +-----------+--------+------------+---------------------------------------------------
> + 0x142 | 1 | | bNumConfigurations
> +-----------+--------+------------+---------------------------------------------------
> + 0x143 | 1 | | bNumInterfaces
> +-----------+--------+------------+---------------------------------------------------
> + 0x144 | | m_0 | From now on each interface is described, all
> + | | | together bNumInterfaces times, with the
> + | | | the following 4 fields:
> +-----------+--------+------------+---------------------------------------------------
> + | 1 | | bInterfaceClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x145 | 1 | | bInterfaceSubClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x146 | 1 | | bInterfaceProtocol
> +-----------+--------+------------+---------------------------------------------------
> + 0x147 | 1 | | padding byte for alignment, shall be set to zero
> +-----------+--------+------------+---------------------------------------------------
> + 0xC + | | | The second exported USB device starts at i=1
> + i*0x138 + | | | with the busid field.
> + m_(i-1)*4 | | |
> +
> +OP_REQ_IMPORT: Request to import (attach) a remote USB device.
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
> +-----------+--------+------------+---------------------------------------------------
> + 2 | 2 | 0x8003 | Command code: import a remote USB device.
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 32 | | busid: the busid of the exported device on the
> + | | | remote host. The possible values are taken
> + | | | from the message field OP_REP_DEVLIST.busid.
> + | | | A string closed with zero, the unused bytes
> + | | | shall be filled with zeros.
> +-----------+--------+------------+---------------------------------------------------
> +
> +OP_REP_IMPORT: Reply to import (attach) a remote USB device.
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
> +-----------+--------+------------+---------------------------------------------------
> + 2 | 2 | 0x0003 | Reply code: Reply to import.
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | 0x00000000 | Status: 0 for OK
> + | | | 1 for error
> +-----------+--------+------------+---------------------------------------------------
> + 8 | | | From now on comes the details of the imported
> + | | | device, if the previous status field was OK (0),
> + | | | otherwise the reply ends with the status field.
> +-----------+--------+------------+---------------------------------------------------
> + | 256 | | path: Path of the device on the host exporting the
> + | | | USB device, string closed with zero byte, e.g.
> + | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
> + | | | The unused bytes shall be filled with zero
> + | | | bytes.
> +-----------+--------+------------+---------------------------------------------------
> + 0x108 | 32 | | busid: Bus ID of the exported device, string
> + | | | closed with zero byte, e.g. "3-2". The unused
> + | | | bytes shall be filled with zero bytes.
> +-----------+--------+------------+---------------------------------------------------
> + 0x128 | 4 | | busnum
> +-----------+--------+------------+---------------------------------------------------
> + 0x12C | 4 | | devnum
> +-----------+--------+------------+---------------------------------------------------
> + 0x130 | 4 | | speed
> +-----------+--------+------------+---------------------------------------------------
> + 0x134 | 2 | | idVendor
> +-----------+--------+------------+---------------------------------------------------
> + 0x136 | 2 | | idProduct
> +-----------+--------+------------+---------------------------------------------------
> + 0x138 | 2 | | bcdDevice
> +-----------+--------+------------+---------------------------------------------------
> + 0x139 | 1 | | bDeviceClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x13A | 1 | | bDeviceSubClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x13B | 1 | | bDeviceProtocol
> +-----------+--------+------------+---------------------------------------------------
> + 0x13C | 1 | | bConfigurationValue
> +-----------+--------+------------+---------------------------------------------------
> + 0x13D | 1 | | bNumConfigurations
> +-----------+--------+------------+---------------------------------------------------
> + 0x13E | 1 | | bNumInterfaces
> +
> +USBIP_CMD_SUBMIT: Submit an URB
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 4 | 0x00000001 | command: Submit an URB
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | | seqnum: the sequence number of the URB to submit
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 4 | | devid
> +-----------+--------+------------+---------------------------------------------------
> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> + | | | 1: USBIP_DIR_OUT
> +-----------+--------+------------+---------------------------------------------------
> + 0x10 | 4 | | ep: endpoint number, possible values are: 0...15
> +-----------+--------+------------+---------------------------------------------------
> + 0x14 | 4 | | transfer_flags: possible values depend on the
> + | | | URB transfer type, see below
> +-----------+--------+------------+---------------------------------------------------
> + 0x18 | 4 | | transfer_buffer_length
> +-----------+--------+------------+---------------------------------------------------
> + 0x1C | 4 | | start_frame: specify the selected frame to
> + | | | transmit an ISO frame, ignored if URB_ISO_ASAP
> + | | | is specified at transfer_flags
> +-----------+--------+------------+---------------------------------------------------
> + 0x20 | 4 | | number_of_packets: number of ISO packets
> +-----------+--------+------------+---------------------------------------------------
> + 0x24 | 4 | | interval: maximum time for the request on the
> + | | | server-side host controller
> +-----------+--------+------------+---------------------------------------------------
> + 0x28 | 8 | | setup: data bytes for USB setup, filled with
> + | | | zeros if not used
> +-----------+--------+------------+---------------------------------------------------
> + 0x30 | | | URB data. For ISO transfers the padding between
> + | | | each ISO packets is not transmitted.
> +
> +
> + Allowed transfer_flags | value | control | interrupt | bulk | isochronous
> + -------------------------+------------+---------+-----------+----------+-------------
> + URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no
> + URB_ISO_ASAP | 0x00000002 | no | no | no | yes
> + URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes
> + URB_NO_FSBR | 0x00000020 | yes | no | no | no
> + URB_ZERO_PACKET | 0x00000040 | no | no | only out | no
> + URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes
> + URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes
> + URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes
> +
> +
> +USBIP_RET_SUBMIT: Reply for submitting an URB
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 4 | 0x00000002 | command
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | | seqnum: URB sequence number
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 4 | | devid
> +-----------+--------+------------+---------------------------------------------------
> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> + | | | 1: USBIP_DIR_OUT
> +-----------+--------+------------+---------------------------------------------------
> + 0x10 | 4 | | ep: endpoint number
> +-----------+--------+------------+---------------------------------------------------
> + 0x14 | 4 | | status: zero for successful URB transaction,
> + | | | otherwise some kind of error happened.
> +-----------+--------+------------+---------------------------------------------------
> + 0x18 | 4 | n | actual_length: number of URB data bytes
> +-----------+--------+------------+---------------------------------------------------
> + 0x1C | 4 | | start_frame: for an ISO frame the actually
> + | | | selected frame for transmit.
> +-----------+--------+------------+---------------------------------------------------
> + 0x20 | 4 | | number_of_packets
> +-----------+--------+------------+---------------------------------------------------
> + 0x24 | 4 | | error_count
> +-----------+--------+------------+---------------------------------------------------
> + 0x28 | 8 | | setup: data bytes for USB setup, filled with
> + | | | zeros if not used
> +-----------+--------+------------+---------------------------------------------------
> + 0x30 | n | | URB data bytes. For ISO transfers the padding
> + | | | between each ISO packets is not transmitted.
> +
> +USBIP_CMD_UNLINK: Unlink an URB
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 4 | 0x00000003 | command: URB unlink command
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | | seqnum: URB sequence number to unlink: FIXME: is this so?
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 4 | | devid
> +-----------+--------+------------+---------------------------------------------------
> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> + | | | 1: USBIP_DIR_OUT
> +-----------+--------+------------+---------------------------------------------------
> + 0x10 | 4 | | ep: endpoint number: zero
> +-----------+--------+------------+---------------------------------------------------
> + 0x14 | 4 | | seqnum: the URB sequence number given previously
> + | | | at USBIP_CMD_SUBMIT.seqnum field
-----------+--------+------------+---------------------------------------------------
0x30 | n | | URB data bytes. For ISO
transfers the padding
| | | between each ISO
packets is not transmitted.
> +
> +USBIP_RET_UNLINK: Reply for URB unlink
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 4 | 0x00000004 | command: reply for the URB unlink command
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | | seqnum: the unlinked URB sequence number
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 4 | | devid
> +-----------+--------+------------+---------------------------------------------------
> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> + | | | 1: USBIP_DIR_OUT
> +-----------+--------+------------+---------------------------------------------------
> + 0x10 | 4 | | ep: endpoint number
> +-----------+--------+------------+---------------------------------------------------
> + 0x14 | 4 | | status: This is the value contained in the
> + | | | urb->status in the URB completition handler.
> + | | | FIXME: a better explanation needed.
-----------+--------+------------+---------------------------------------------------
0x30 | n | | URB data bytes. For ISO
transfers the padding
| | | between each ISO
packets is not transmitted.
Regards,
David Chang
>
> _______________________________________________
> devel mailing list
> devel@linuxdriverproject.org
> http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
>
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-06-28 6:52 ` [PATCH, RFC] USBIP protocol documentation Németh Márton
2011-06-29 8:04 ` David Chang
@ 2011-06-29 23:34 ` matt mooney
[not found] ` <BANLkTi=qXgnapyrsSANJ0XZuE=kz7QgsvA@mail.gmail.com>
2011-08-09 9:23 ` David Chang
2 siblings, 1 reply; 22+ messages in thread
From: matt mooney @ 2011-06-29 23:34 UTC (permalink / raw)
To: N??meth M??rton
Cc: Greg KH, Matthew Wilcox, Max Vozeler, Joe Perches, David Chang,
linux-usb, usbip-devel, devel, LKML
On 08:52 Tue 28 Jun , N??meth M??rton wrote:
> From: M??rton N??meth <nm127@freemail.hu>
>
> USBIP v1.0.0 protocol documentation.
>
> Signed-off-by: M??rton N??meth <nm127@freemail.hu>
> ---
>
> Hi,
>
> I tried to document the USBIP protocol as implemented in the Linux kernel 3.0-rc2.
Yeah, thanks for doing this. I am also documenting the protocol but am not
finished yet. We can use yours as the base if you would like although I have a
few suggestions.
For one, the grammar needs to be cleaned up, but instead of me pointing out all
of the needed corrections, I will send in a grammar corrections patch on top of
the finished document. I like that you did a time sequence diagram, which is
something I had neglected to include myself; however, I am not a big fan of how
you laid out the messages. I was planning on using packet diagrams. IMHO, it
makes understanding the message composition much easier allowing more insight to
be gathered from a cursory glance.
Message Format
--------------
0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | Opcode |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Status |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. Data .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Version: 16 bit
Binary-coded decimal version number of the usbip-utils package from
which the program was built.
Opcode: 16 bits
...
As you may or may not see, I was going to take a more generic approach and then
describe the fields on a per-op basis. Of course, the main point here is that
the protocol is documented, so I am not opposed to a different style being used.
But if you insist on the current layout, do not put a value for the version
because it is not constant (and in fact no longer at 1.0.0). And the "Meaning"
header should be "Description" or something better.
Hmm, taking another look the layout just seems to busy... I really do think we
should find a different way to format the information.
Thanks,
matt
> The description is a preliminary draft only, it may contain mistakes. I tried
> to document what I have understand from the source code and from the actual
> captured network traffic when the USBIP is in action. Please review it, correct it,
> point out the missing parts.
>
> During I have documented the protocol a question came into my mind: why do we
> have two different type of package when the URB completition handler is called,
> namely USB_RET_SUBMIT and USBIP_RET_UNLINK? As far as I can see this causes race
> condition because for one URB the completition handler is only called once. If
> the one URB is sent in with USB_CMD_SUBMIT and then unlinked with USB_CMD_UNLINK
> the completition handler is called only once. In the protocol, however, we have
> two different type of packets: USB_RET_SUBMIT and USBIP_RET_UNLINK. The status
> field of these messages may contain anything in this case depending on the timing.
>
> Regards,
>
> M??rton N??meth
> ---
> diff -uprN staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt staging-2.6/drivers/staging/usbip/usbip_protocol.txt
> --- staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt 1970-01-01 01:00:00.000000000 +0100
> +++ staging-2.6/drivers/staging/usbip/usbip_protocol.txt 2011-06-28 08:30:04.000000000 +0200
> @@ -0,0 +1,352 @@
> +PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
> +28 Jun 2011
> +
> +The USB/IP protocol follows a server/client architecture. The server exports the
> +USB devices and the clients imports them. The device driver for the exported
> +USB device runs on the client machine.
> +
> +The client may ask for the list of the exported USB devices. To get the list the
> +client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST
> +packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent
> +in one or more pieces at the low level transport layer). The server sends back
> +the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the
> +TCP/IP connection is closed.
> +
> + virtual host controller usb host
> + "client" "server"
> + (imports USB devices) (exports USB devices)
> + | |
> + | OP_REQ_DEVLIST |
> + | ----------------------------------------------> |
> + | |
> + | OP_REP_DEVLIST |
> + | <---------------------------------------------- |
> + | |
> +
> +Once the client knows the list of exported USB devices it may decide to use one
> +of them. First the client opens a TCP/IP connection towards the server and
> +sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the
> +import was successful the TCP/IP connection remains open and will be used
> +to trasfer the URB traffic between the client and the server. The client may
> +send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
> +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the
> +server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
> +
> + virtual host controller usb host
> + "client" "server"
> + (imports USB devices) (exports USB devices)
> + | |
> + | OP_REQ_IMPORT |
> + | ----------------------------------------------> |
> + | |
> + | OP_REP_IMPORT |
> + | <---------------------------------------------- |
> + | |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = n) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_RET_SUBMIT(seqnum = n) |
> + | <---------------------------------------------- |
> + | . |
> + | : |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = m) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = m+1) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = m+2) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_RET_SUBMIT(seqnum = m) |
> + | <---------------------------------------------- |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = m+3) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_RET_SUBMIT(seqnum = m+1) |
> + | <---------------------------------------------- |
> + | |
> + | USBIP_CMD_SUBMIT(seqnum = m+4) |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_RET_SUBMIT(seqnum = m+2) |
> + | <---------------------------------------------- |
> + | . |
> + | : |
> + | |
> + | USBIP_CMD_UNLINK |
> + | ----------------------------------------------> |
> + | |
> + | USBIP_RET_UNLINK |
> + | <---------------------------------------------- |
> + | |
> +
> +The fields are in network (big endian) byte order meaning that the most significant
> +byte (MSB) is stored at the lowest address.
> +
> +
> +OP_REQ_DEVLIST: Retrieve the list of exported USB devices.
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
> +-----------+--------+------------+---------------------------------------------------
> + 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB
> + | | | devices.
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
> +
> +OP_REP_DEVLIST: Reply with the list of exported USB devices.
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0.
> +-----------+--------+------------+---------------------------------------------------
> + 2 | 2 | 0x0005 | Reply code: The list of exported USB devices.
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | 0x00000000 | Status: 0 for OK
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 4 | n | Number of exported devices: 0 means no exported
> + | | | devices.
> +-----------+--------+------------+---------------------------------------------------
> + 0x0C | | | From now on the exported n devices are described,
> + | | | if any. If no devices are exported the message
> + | | | ends with the previous "number of exported
> + | | | devices" field.
> +-----------+--------+------------+---------------------------------------------------
> + | 256 | | path: Path of the device on the host exporting the
> + | | | USB device, string closed with zero byte, e.g.
> + | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
> + | | | The unused bytes shall be filled with zero
> + | | | bytes.
> +-----------+--------+------------+---------------------------------------------------
> + 0x10C | 32 | | busid: Bus ID of the exported device, string
> + | | | closed with zero byte, e.g. "3-2". The unused
> + | | | bytes shall be filled with zero bytes.
> +-----------+--------+------------+---------------------------------------------------
> + 0x12C | 4 | | busnum
> +-----------+--------+------------+---------------------------------------------------
> + 0x130 | 4 | | devnum
> +-----------+--------+------------+---------------------------------------------------
> + 0x134 | 4 | | speed
> +-----------+--------+------------+---------------------------------------------------
> + 0x138 | 2 | | idVendor
> +-----------+--------+------------+---------------------------------------------------
> + 0x13A | 2 | | idProduct
> +-----------+--------+------------+---------------------------------------------------
> + 0x13C | 2 | | bcdDevice
> +-----------+--------+------------+---------------------------------------------------
> + 0x13E | 1 | | bDeviceClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x13F | 1 | | bDeviceSubClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x140 | 1 | | bDeviceProtocol
> +-----------+--------+------------+---------------------------------------------------
> + 0x141 | 1 | | bConfigurationValue
> +-----------+--------+------------+---------------------------------------------------
> + 0x142 | 1 | | bNumConfigurations
> +-----------+--------+------------+---------------------------------------------------
> + 0x143 | 1 | | bNumInterfaces
> +-----------+--------+------------+---------------------------------------------------
> + 0x144 | | m_0 | From now on each interface is described, all
> + | | | together bNumInterfaces times, with the
> + | | | the following 4 fields:
> +-----------+--------+------------+---------------------------------------------------
> + | 1 | | bInterfaceClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x145 | 1 | | bInterfaceSubClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x146 | 1 | | bInterfaceProtocol
> +-----------+--------+------------+---------------------------------------------------
> + 0x147 | 1 | | padding byte for alignment, shall be set to zero
> +-----------+--------+------------+---------------------------------------------------
> + 0xC + | | | The second exported USB device starts at i=1
> + i*0x138 + | | | with the busid field.
> + m_(i-1)*4 | | |
> +
> +OP_REQ_IMPORT: Request to import (attach) a remote USB device.
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
> +-----------+--------+------------+---------------------------------------------------
> + 2 | 2 | 0x8003 | Command code: import a remote USB device.
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 32 | | busid: the busid of the exported device on the
> + | | | remote host. The possible values are taken
> + | | | from the message field OP_REP_DEVLIST.busid.
> + | | | A string closed with zero, the unused bytes
> + | | | shall be filled with zeros.
> +-----------+--------+------------+---------------------------------------------------
> +
> +OP_REP_IMPORT: Reply to import (attach) a remote USB device.
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0
> +-----------+--------+------------+---------------------------------------------------
> + 2 | 2 | 0x0003 | Reply code: Reply to import.
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | 0x00000000 | Status: 0 for OK
> + | | | 1 for error
> +-----------+--------+------------+---------------------------------------------------
> + 8 | | | From now on comes the details of the imported
> + | | | device, if the previous status field was OK (0),
> + | | | otherwise the reply ends with the status field.
> +-----------+--------+------------+---------------------------------------------------
> + | 256 | | path: Path of the device on the host exporting the
> + | | | USB device, string closed with zero byte, e.g.
> + | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
> + | | | The unused bytes shall be filled with zero
> + | | | bytes.
> +-----------+--------+------------+---------------------------------------------------
> + 0x108 | 32 | | busid: Bus ID of the exported device, string
> + | | | closed with zero byte, e.g. "3-2". The unused
> + | | | bytes shall be filled with zero bytes.
> +-----------+--------+------------+---------------------------------------------------
> + 0x128 | 4 | | busnum
> +-----------+--------+------------+---------------------------------------------------
> + 0x12C | 4 | | devnum
> +-----------+--------+------------+---------------------------------------------------
> + 0x130 | 4 | | speed
> +-----------+--------+------------+---------------------------------------------------
> + 0x134 | 2 | | idVendor
> +-----------+--------+------------+---------------------------------------------------
> + 0x136 | 2 | | idProduct
> +-----------+--------+------------+---------------------------------------------------
> + 0x138 | 2 | | bcdDevice
> +-----------+--------+------------+---------------------------------------------------
> + 0x139 | 1 | | bDeviceClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x13A | 1 | | bDeviceSubClass
> +-----------+--------+------------+---------------------------------------------------
> + 0x13B | 1 | | bDeviceProtocol
> +-----------+--------+------------+---------------------------------------------------
> + 0x13C | 1 | | bConfigurationValue
> +-----------+--------+------------+---------------------------------------------------
> + 0x13D | 1 | | bNumConfigurations
> +-----------+--------+------------+---------------------------------------------------
> + 0x13E | 1 | | bNumInterfaces
> +
> +USBIP_CMD_SUBMIT: Submit an URB
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 4 | 0x00000001 | command: Submit an URB
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | | seqnum: the sequence number of the URB to submit
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 4 | | devid
> +-----------+--------+------------+---------------------------------------------------
> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> + | | | 1: USBIP_DIR_OUT
> +-----------+--------+------------+---------------------------------------------------
> + 0x10 | 4 | | ep: endpoint number, possible values are: 0...15
> +-----------+--------+------------+---------------------------------------------------
> + 0x14 | 4 | | transfer_flags: possible values depend on the
> + | | | URB transfer type, see below
> +-----------+--------+------------+---------------------------------------------------
> + 0x18 | 4 | | transfer_buffer_length
> +-----------+--------+------------+---------------------------------------------------
> + 0x1C | 4 | | start_frame: specify the selected frame to
> + | | | transmit an ISO frame, ignored if URB_ISO_ASAP
> + | | | is specified at transfer_flags
> +-----------+--------+------------+---------------------------------------------------
> + 0x20 | 4 | | number_of_packets: number of ISO packets
> +-----------+--------+------------+---------------------------------------------------
> + 0x24 | 4 | | interval: maximum time for the request on the
> + | | | server-side host controller
> +-----------+--------+------------+---------------------------------------------------
> + 0x28 | 8 | | setup: data bytes for USB setup, filled with
> + | | | zeros if not used
> +-----------+--------+------------+---------------------------------------------------
> + 0x30 | | | URB data. For ISO transfers the padding between
> + | | | each ISO packets is not transmitted.
> +
> +
> + Allowed transfer_flags | value | control | interrupt | bulk | isochronous
> + -------------------------+------------+---------+-----------+----------+-------------
> + URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no
> + URB_ISO_ASAP | 0x00000002 | no | no | no | yes
> + URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes
> + URB_NO_FSBR | 0x00000020 | yes | no | no | no
> + URB_ZERO_PACKET | 0x00000040 | no | no | only out | no
> + URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes
> + URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes
> + URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes
> +
> +
> +USBIP_RET_SUBMIT: Reply for submitting an URB
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 4 | 0x00000002 | command
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | | seqnum: URB sequence number
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 4 | | devid
> +-----------+--------+------------+---------------------------------------------------
> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> + | | | 1: USBIP_DIR_OUT
> +-----------+--------+------------+---------------------------------------------------
> + 0x10 | 4 | | ep: endpoint number
> +-----------+--------+------------+---------------------------------------------------
> + 0x14 | 4 | | status: zero for successful URB transaction,
> + | | | otherwise some kind of error happened.
> +-----------+--------+------------+---------------------------------------------------
> + 0x18 | 4 | n | actual_length: number of URB data bytes
> +-----------+--------+------------+---------------------------------------------------
> + 0x1C | 4 | | start_frame: for an ISO frame the actually
> + | | | selected frame for transmit.
> +-----------+--------+------------+---------------------------------------------------
> + 0x20 | 4 | | number_of_packets
> +-----------+--------+------------+---------------------------------------------------
> + 0x24 | 4 | | error_count
> +-----------+--------+------------+---------------------------------------------------
> + 0x28 | 8 | | setup: data bytes for USB setup, filled with
> + | | | zeros if not used
> +-----------+--------+------------+---------------------------------------------------
> + 0x30 | n | | URB data bytes. For ISO transfers the padding
> + | | | between each ISO packets is not transmitted.
> +
> +USBIP_CMD_UNLINK: Unlink an URB
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 4 | 0x00000003 | command: URB unlink command
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | | seqnum: URB sequence number to unlink: FIXME: is this so?
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 4 | | devid
> +-----------+--------+------------+---------------------------------------------------
> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> + | | | 1: USBIP_DIR_OUT
> +-----------+--------+------------+---------------------------------------------------
> + 0x10 | 4 | | ep: endpoint number: zero
> +-----------+--------+------------+---------------------------------------------------
> + 0x14 | 4 | | seqnum: the URB sequence number given previously
> + | | | at USBIP_CMD_SUBMIT.seqnum field
> +
> +USBIP_RET_UNLINK: Reply for URB unlink
> +
> + Offset | Length | Value | Meaning
> +-----------+--------+------------+---------------------------------------------------
> + 0 | 4 | 0x00000004 | command: reply for the URB unlink command
> +-----------+--------+------------+---------------------------------------------------
> + 4 | 4 | | seqnum: the unlinked URB sequence number
> +-----------+--------+------------+---------------------------------------------------
> + 8 | 4 | | devid
> +-----------+--------+------------+---------------------------------------------------
> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> + | | | 1: USBIP_DIR_OUT
> +-----------+--------+------------+---------------------------------------------------
> + 0x10 | 4 | | ep: endpoint number
> +-----------+--------+------------+---------------------------------------------------
> + 0x14 | 4 | | status: This is the value contained in the
> + | | | urb->status in the URB completition handler.
> + | | | FIXME: a better explanation needed.
>
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
[not found] ` <BANLkTi=qXgnapyrsSANJ0XZuE=kz7QgsvA@mail.gmail.com>
@ 2011-06-30 5:56 ` Németh Márton
2011-06-30 6:54 ` Matt Chen
0 siblings, 1 reply; 22+ messages in thread
From: Németh Márton @ 2011-06-30 5:56 UTC (permalink / raw)
To: Matt Chen
Cc: Greg KH, Matthew Wilcox, Max Vozeler, Joe Perches, David Chang,
linux-usb, usbip-devel, devel, LKML
Matt Chen wrote:
> Hi Matt,
>
>
> 2011/6/30 matt mooney <mfm@muteddisk.com <mailto:mfm@muteddisk.com>>:
>> On 08:52 Tue 28 Jun , N??meth M??rton wrote:
>>> From: M??rton N??meth <nm127@freemail.hu <mailto:nm127@freemail.hu>>
>>>
>>> USBIP v1.0.0 protocol documentation.
>>>
>>> Signed-off-by: M??rton N??meth <nm127@freemail.hu
> <mailto:nm127@freemail.hu>>
>>> ---
>>>
>>> Hi,
>>>
>>> I tried to document the USBIP protocol as implemented in the Linux
> kernel 3.0-rc2.
>>
>> Yeah, thanks for doing this. I am also documenting the protocol but am not
>> finished yet. We can use yours as the base if you would like although
> I have a
>> few suggestions.
>>
>> For one, the grammar needs to be cleaned up, but instead of me
> pointing out all
>> of the needed corrections, I will send in a grammar corrections patch
> on top of
Please go on with the corrections. I really started documenting the
current USBIP protocol because I think digging in the source code is
not the right way to describe a protocol. I'm happy that the review
of the USBIP protocol description started. Once we have documented the current
USBIP protocol I think we'll see more clearly its weaknesses.
What I think important to include in the protocol description is to
identify the unused fields and specify an exact value (usually zero) to
use for these fields. This makes possible future extension of the protocol
easy.
One more random thing which came to my mind is that I tend to think that
the current implementation is buggy when ISO packets are transmitted.
I have a hama AC-150 webcam which is not working well with USBIP. This
webcam usually sends smaller ISO packets so there is a gap between
the ISO packets in one single URB. The problem came up already in case
of usbmon, see https://bugzilla.kernel.org/show_bug.cgi?id=22182 and
http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=b17ea167c5fb50dcd5dce5b874a467f04eec886d
.
>> the finished document. I like that you did a time sequence diagram,
> which is
>> something I had neglected to include myself; however, I am not a big
> fan of how
>> you laid out the messages. I was planning on using packet diagrams.
> IMHO, it
>> makes understanding the message composition much easier allowing more
> insight to
>> be gathered from a cursory glance.
>>
>>
>> Message Format
>> --------------
>> 0 1 2 3
>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>> | Version | Opcode |
>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>> | Status |
>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>> . .
>> . Data .
>> . .
>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>>
>> Version: 16 bit
>> Binary-coded decimal version number of the usbip-utils package from
>> which the program was built.
>>
>> Opcode: 16 bits
>> ...
>>
> So as you mentioned, the message format is looked like below:
>
> OP_REQ_DEVLIST Message Format
>
> 0 1 2
> 3 4
> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> | 0000 0000 1000 0000 | 1000 0000 0000 0101 |
> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
> | 0000 0000 0000 0000 0000 0000 0000 0000 |
> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
>
> Is this correct ?
>
> Personally, I like this way to describe the protocol. ;-)
This layout format what is used in other RFCs, too, is really a better
way to show the messages. I think, however, that we don't need to put
the values in binary format, we could just put one hexadecimal number
in the gaps, like this:
OP_REQ_DEVLIST Message Format
0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x0100 | 0x8005 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x00000000 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>> As you may or may not see, I was going to take a more generic approach
> and then
>> describe the fields on a per-op basis. Of course, the main point here
> is that
>> the protocol is documented, so I am not opposed to a different style
> being used.
>>
>> But if you insist on the current layout, do not put a value for the
> version
>> because it is not constant (and in fact no longer at 1.0.0). And the
> "Meaning"
>> header should be "Description" or something better.
>>
>> Hmm, taking another look the layout just seems to busy... I really do
> think we
>> should find a different way to format the information.
>>
>> Thanks,
>> matt
>>
>>> The description is a preliminary draft only, it may contain mistakes.
> I tried
>>> to document what I have understand from the source code and from the
> actual
>>> captured network traffic when the USBIP is in action. Please review
> it, correct it,
>>> point out the missing parts.
>>>
>>> During I have documented the protocol a question came into my mind:
> why do we
>>> have two different type of package when the URB completition handler
> is called,
>>> namely USB_RET_SUBMIT and USBIP_RET_UNLINK? As far as I can see this
> causes race
>>> condition because for one URB the completition handler is only called
> once. If
>>> the one URB is sent in with USB_CMD_SUBMIT and then unlinked with
> USB_CMD_UNLINK
>>> the completition handler is called only once. In the protocol,
> however, we have
>>> two different type of packets: USB_RET_SUBMIT and USBIP_RET_UNLINK.
> The status
>>> field of these messages may contain anything in this case depending
> on the timing.
>>>
>>> Regards,
>>>
>>> M??rton N??meth
>>> ---
>>> diff -uprN staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt
> staging-2.6/drivers/staging/usbip/usbip_protocol.txt
>>> --- staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt
> 1970-01-01 01:00:00.000000000 +0100
>>> +++ staging-2.6/drivers/staging/usbip/usbip_protocol.txt
> 2011-06-28 08:30:04.000000000 +0200
>>> @@ -0,0 +1,352 @@
>>> +PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
>>> +28 Jun 2011
>>> +
>>> +The USB/IP protocol follows a server/client architecture. The server
> exports the
>>> +USB devices and the clients imports them. The device driver for the
> exported
>>> +USB device runs on the client machine.
>>> +
>>> +The client may ask for the list of the exported USB devices. To get
> the list the
>>> +client opens a TCP/IP connection towards the server, and sends an
> OP_REQ_DEVLIST
>>> +packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST
> may be sent
>>> +in one or more pieces at the low level transport layer). The server
> sends back
>>> +the OP_REP_DEVLIST packet which lists the exported USB devices.
> Finally the
>>> +TCP/IP connection is closed.
>>> +
>>> + virtual host controller usb host
>>> + "client" "server"
>>> + (imports USB devices) (exports USB
> devices)
>>> + | |
>>> + | OP_REQ_DEVLIST |
>>> + | ----------------------------------------------> |
>>> + | |
>>> + | OP_REP_DEVLIST |
>>> + | <---------------------------------------------- |
>>> + | |
>>> +
>>> +Once the client knows the list of exported USB devices it may decide
> to use one
>>> +of them. First the client opens a TCP/IP connection towards the
> server and
>>> +sends an OP_REQ_IMPORT packet. The server replies with
> OP_REP_IMPORT. If the
>>> +import was successful the TCP/IP connection remains open and will be
> used
>>> +to trasfer the URB traffic between the client and the server. The
> client may
>>> +send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
>>> +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers
> of the
>>> +server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
>>> +
>>> + virtual host controller usb host
>>> + "client" "server"
>>> + (imports USB devices) (exports USB
> devices)
>>> + | |
>>> + | OP_REQ_IMPORT |
>>> + | ----------------------------------------------> |
>>> + | |
>>> + | OP_REP_IMPORT |
>>> + | <---------------------------------------------- |
>>> + | |
>>> + | |
>>> + | USBIP_CMD_SUBMIT(seqnum = n) |
>>> + | ----------------------------------------------> |
>>> + | |
>>> + | USBIP_RET_SUBMIT(seqnum = n) |
>>> + | <---------------------------------------------- |
>>> + | . |
>>> + | : |
>>> + | |
>>> + | USBIP_CMD_SUBMIT(seqnum = m) |
>>> + | ----------------------------------------------> |
>>> + | |
>>> + | USBIP_CMD_SUBMIT(seqnum = m+1) |
>>> + | ----------------------------------------------> |
>>> + | |
>>> + | USBIP_CMD_SUBMIT(seqnum = m+2) |
>>> + | ----------------------------------------------> |
>>> + | |
>>> + | USBIP_RET_SUBMIT(seqnum = m) |
>>> + | <---------------------------------------------- |
>>> + | |
>>> + | USBIP_CMD_SUBMIT(seqnum = m+3) |
>>> + | ----------------------------------------------> |
>>> + | |
>>> + | USBIP_RET_SUBMIT(seqnum = m+1) |
>>> + | <---------------------------------------------- |
>>> + | |
>>> + | USBIP_CMD_SUBMIT(seqnum = m+4) |
>>> + | ----------------------------------------------> |
>>> + | |
>>> + | USBIP_RET_SUBMIT(seqnum = m+2) |
>>> + | <---------------------------------------------- |
>>> + | . |
>>> + | : |
>>> + | |
>>> + | USBIP_CMD_UNLINK |
>>> + | ----------------------------------------------> |
>>> + | |
>>> + | USBIP_RET_UNLINK |
>>> + | <---------------------------------------------- |
>>> + | |
>>> +
>>> +The fields are in network (big endian) byte order meaning that the
> most significant
>>> +byte (MSB) is stored at the lowest address.
>>> +
>>> +
>>> +OP_REQ_DEVLIST: Retrieve the list of exported USB devices.
>>> +
>>> + Offset | Length | Value | Meaning
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
> version number: v1.0.0
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 2 | 2 | 0x8005 | Command code: Retrieve the list
> of exported USB
>>> + | | | devices.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
>>> +
>>> +OP_REP_DEVLIST: Reply with the list of exported USB devices.
>>> +
>>> + Offset | Length | Value | Meaning
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
> version number: v1.0.0.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 2 | 2 | 0x0005 | Reply code: The list of exported
> USB devices.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 4 | 4 | 0x00000000 | Status: 0 for OK
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 8 | 4 | n | Number of exported devices: 0
> means no exported
>>> + | | | devices.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x0C | | | From now on the exported n
> devices are described,
>>> + | | | if any. If no devices are
> exported the message
>>> + | | | ends with the previous "number
> of exported
>>> + | | | devices" field.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + | 256 | | path: Path of the device on the
> host exporting the
>>> + | | | USB device, string closed with
> zero byte, e.g.
>>> + | | |
> "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
>>> + | | | The unused bytes shall be
> filled with zero
>>> + | | | bytes.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x10C | 32 | | busid: Bus ID of the exported
> device, string
>>> + | | | closed with zero byte, e.g.
> "3-2". The unused
>>> + | | | bytes shall be filled with zero
> bytes.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x12C | 4 | | busnum
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x130 | 4 | | devnum
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x134 | 4 | | speed
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x138 | 2 | | idVendor
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x13A | 2 | | idProduct
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x13C | 2 | | bcdDevice
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x13E | 1 | | bDeviceClass
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x13F | 1 | | bDeviceSubClass
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x140 | 1 | | bDeviceProtocol
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x141 | 1 | | bConfigurationValue
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x142 | 1 | | bNumConfigurations
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x143 | 1 | | bNumInterfaces
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x144 | | m_0 | From now on each interface is
> described, all
>>> + | | | together bNumInterfaces times,
> with the
>>> + | | | the following 4 fields:
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + | 1 | | bInterfaceClass
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x145 | 1 | | bInterfaceSubClass
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x146 | 1 | | bInterfaceProtocol
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x147 | 1 | | padding byte for alignment, shall
> be set to zero
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0xC + | | | The second exported USB device
> starts at i=1
>>> + i*0x138 + | | | with the busid field.
>>> + m_(i-1)*4 | | |
>>> +
>>> +OP_REQ_IMPORT: Request to import (attach) a remote USB device.
>>> +
>>> + Offset | Length | Value | Meaning
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
> version number: v1.0.0
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 2 | 2 | 0x8003 | Command code: import a remote USB
> device.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 8 | 32 | | busid: the busid of the exported
> device on the
>>> + | | | remote host. The possible
> values are taken
>>> + | | | from the message field
> OP_REP_DEVLIST.busid.
>>> + | | | A string closed with zero, the
> unused bytes
>>> + | | | shall be filled with zeros.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> +
>>> +OP_REP_IMPORT: Reply to import (attach) a remote USB device.
>>> +
>>> + Offset | Length | Value | Meaning
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
> version number: v1.0.0
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 2 | 2 | 0x0003 | Reply code: Reply to import.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 4 | 4 | 0x00000000 | Status: 0 for OK
>>> + | | | 1 for error
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 8 | | | From now on comes the details of
> the imported
>>> + | | | device, if the previous status
> field was OK (0),
>>> + | | | otherwise the reply ends with
> the status field.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + | 256 | | path: Path of the device on the
> host exporting the
>>> + | | | USB device, string closed with
> zero byte, e.g.
>>> + | | |
> "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
>>> + | | | The unused bytes shall be
> filled with zero
>>> + | | | bytes.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x108 | 32 | | busid: Bus ID of the exported
> device, string
>>> + | | | closed with zero byte, e.g.
> "3-2". The unused
>>> + | | | bytes shall be filled with zero
> bytes.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x128 | 4 | | busnum
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x12C | 4 | | devnum
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x130 | 4 | | speed
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x134 | 2 | | idVendor
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x136 | 2 | | idProduct
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x138 | 2 | | bcdDevice
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x139 | 1 | | bDeviceClass
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x13A | 1 | | bDeviceSubClass
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x13B | 1 | | bDeviceProtocol
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x13C | 1 | | bConfigurationValue
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x13D | 1 | | bNumConfigurations
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x13E | 1 | | bNumInterfaces
>>> +
>>> +USBIP_CMD_SUBMIT: Submit an URB
>>> +
>>> + Offset | Length | Value | Meaning
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0 | 4 | 0x00000001 | command: Submit an URB
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 4 | 4 | | seqnum: the sequence number of
> the URB to submit
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 8 | 4 | | devid
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
>>> + | | | 1: USBIP_DIR_OUT
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x10 | 4 | | ep: endpoint number, possible
> values are: 0...15
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x14 | 4 | | transfer_flags: possible values
> depend on the
>>> + | | | URB transfer type, see below
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x18 | 4 | | transfer_buffer_length
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x1C | 4 | | start_frame: specify the selected
> frame to
>>> + | | | transmit an ISO frame, ignored
> if URB_ISO_ASAP
>>> + | | | is specified at transfer_flags
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x20 | 4 | | number_of_packets: number of ISO
> packets
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x24 | 4 | | interval: maximum time for the
> request on the
>>> + | | | server-side host controller
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x28 | 8 | | setup: data bytes for USB setup,
> filled with
>>> + | | | zeros if not used
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x30 | | | URB data. For ISO transfers the
> padding between
>>> + | | | each ISO packets is not
> transmitted.
>>> +
>>> +
>>> + Allowed transfer_flags | value | control | interrupt | bulk
> | isochronous
>>> +
> -------------------------+------------+---------+-----------+----------+-------------
>>> + URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only
> in | no
>>> + URB_ISO_ASAP | 0x00000002 | no | no | no
> | yes
>>> + URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes
> | yes
>>> + URB_NO_FSBR | 0x00000020 | yes | no | no
> | no
>>> + URB_ZERO_PACKET | 0x00000040 | no | no | only
> out | no
>>> + URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes
> | yes
>>> + URB_FREE_BUFFER | 0x00000100 | yes | yes | yes
> | yes
>>> + URB_DIR_MASK | 0x00000200 | yes | yes | yes
> | yes
>>> +
>>> +
>>> +USBIP_RET_SUBMIT: Reply for submitting an URB
>>> +
>>> + Offset | Length | Value | Meaning
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0 | 4 | 0x00000002 | command
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 4 | 4 | | seqnum: URB sequence number
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 8 | 4 | | devid
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
>>> + | | | 1: USBIP_DIR_OUT
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x10 | 4 | | ep: endpoint number
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x14 | 4 | | status: zero for successful URB
> transaction,
>>> + | | | otherwise some kind of error
> happened.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x18 | 4 | n | actual_length: number of URB data
> bytes
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x1C | 4 | | start_frame: for an ISO frame the
> actually
>>> + | | | selected frame for transmit.
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x20 | 4 | | number_of_packets
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x24 | 4 | | error_count
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x28 | 8 | | setup: data bytes for USB setup,
> filled with
>>> + | | | zeros if not used
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x30 | n | | URB data bytes. For ISO transfers
> the padding
>>> + | | | between each ISO packets is not
> transmitted.
>>> +
>>> +USBIP_CMD_UNLINK: Unlink an URB
>>> +
>>> + Offset | Length | Value | Meaning
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0 | 4 | 0x00000003 | command: URB unlink command
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 4 | 4 | | seqnum: URB sequence number to
> unlink: FIXME: is this so?
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 8 | 4 | | devid
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
>>> + | | | 1: USBIP_DIR_OUT
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x10 | 4 | | ep: endpoint number: zero
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x14 | 4 | | seqnum: the URB sequence number
> given previously
>>> + | | | at USBIP_CMD_SUBMIT.seqnum field
>>> +
>>> +USBIP_RET_UNLINK: Reply for URB unlink
>>> +
>>> + Offset | Length | Value | Meaning
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0 | 4 | 0x00000004 | command: reply for the URB unlink
> command
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 4 | 4 | | seqnum: the unlinked URB sequence
> number
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 8 | 4 | | devid
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
>>> + | | | 1: USBIP_DIR_OUT
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x10 | 4 | | ep: endpoint number
>>>
> +-----------+--------+------------+---------------------------------------------------
>>> + 0x14 | 4 | | status: This is the value
> contained in the
>>> + | | | urb->status in the URB
> completition handler.
>>> + | | | FIXME: a better explanation needed.
>>>
>> _______________________________________________
>> devel mailing list
>> devel@linuxdriverproject.org <mailto:devel@linuxdriverproject.org>
>> http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
>>
>
>
>
> --
> Thanks ~
> Matt Chen
>
>
>
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-06-30 5:56 ` Németh Márton
@ 2011-06-30 6:54 ` Matt Chen
2011-06-30 19:38 ` Németh Márton
0 siblings, 1 reply; 22+ messages in thread
From: Matt Chen @ 2011-06-30 6:54 UTC (permalink / raw)
To: Németh Márton
Cc: Greg KH, Matthew Wilcox, Max Vozeler, Joe Perches, David Chang,
linux-usb, usbip-devel, devel, LKML
Hi Németh and Matt,
We are also working on reviewing protocol here. We were wondering if
you are available for letting us know which part you've already done.
Then we can save the time for doing the same parts.
And also we would like to follow your suggesting format to work on it.
Then it would make it work much faster.
Any suggestion ?
2011/6/30 Németh Márton <nm127@freemail.hu>
>
> Matt Chen wrote:
> > Hi Matt,
> >
> >
> > 2011/6/30 matt mooney <mfm@muteddisk.com <mailto:mfm@muteddisk.com>>:
> >> On 08:52 Tue 28 Jun , N??meth M??rton wrote:
> >>> From: M??rton N??meth <nm127@freemail.hu <mailto:nm127@freemail.hu>>
> >>>
> >>> USBIP v1.0.0 protocol documentation.
> >>>
> >>> Signed-off-by: M??rton N??meth <nm127@freemail.hu
> > <mailto:nm127@freemail.hu>>
> >>> ---
> >>>
> >>> Hi,
> >>>
> >>> I tried to document the USBIP protocol as implemented in the Linux
> > kernel 3.0-rc2.
> >>
> >> Yeah, thanks for doing this. I am also documenting the protocol but am not
> >> finished yet. We can use yours as the base if you would like although
> > I have a
> >> few suggestions.
> >>
> >> For one, the grammar needs to be cleaned up, but instead of me
> > pointing out all
> >> of the needed corrections, I will send in a grammar corrections patch
> > on top of
>
> Please go on with the corrections. I really started documenting the
> current USBIP protocol because I think digging in the source code is
> not the right way to describe a protocol. I'm happy that the review
> of the USBIP protocol description started. Once we have documented the current
> USBIP protocol I think we'll see more clearly its weaknesses.
>
> What I think important to include in the protocol description is to
> identify the unused fields and specify an exact value (usually zero) to
> use for these fields. This makes possible future extension of the protocol
> easy.
>
> One more random thing which came to my mind is that I tend to think that
> the current implementation is buggy when ISO packets are transmitted.
> I have a hama AC-150 webcam which is not working well with USBIP. This
> webcam usually sends smaller ISO packets so there is a gap between
> the ISO packets in one single URB. The problem came up already in case
> of usbmon, see https://bugzilla.kernel.org/show_bug.cgi?id=22182 and
> http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=b17ea167c5fb50dcd5dce5b874a467f04eec886d
> .
>
> >> the finished document. I like that you did a time sequence diagram,
> > which is
> >> something I had neglected to include myself; however, I am not a big
> > fan of how
> >> you laid out the messages. I was planning on using packet diagrams.
> > IMHO, it
> >> makes understanding the message composition much easier allowing more
> > insight to
> >> be gathered from a cursory glance.
> >>
> >>
> >> Message Format
> >> --------------
> >> 0 1 2 3
> >> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> >> | Version | Opcode |
> >> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> >> | Status |
> >> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> >> . .
> >> . Data .
> >> . .
> >> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> >>
> >> Version: 16 bit
> >> Binary-coded decimal version number of the usbip-utils package from
> >> which the program was built.
> >>
> >> Opcode: 16 bits
> >> ...
> >>
> > So as you mentioned, the message format is looked like below:
> >
> > OP_REQ_DEVLIST Message Format
> >
> > 0 1 2
> > 3 4
> > +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> > | 0000 0000 1000 0000 | 1000 0000 0000 0101 |
> > +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
> > | 0000 0000 0000 0000 0000 0000 0000 0000 |
> > +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
> >
> > Is this correct ?
> >
> > Personally, I like this way to describe the protocol. ;-)
>
> This layout format what is used in other RFCs, too, is really a better
> way to show the messages. I think, however, that we don't need to put
> the values in binary format, we could just put one hexadecimal number
> in the gaps, like this:
>
> OP_REQ_DEVLIST Message Format
>
>
> 0 1 2 3
> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> | 0x0100 | 0x8005 |
> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
> | 0x00000000 |
> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>
> >> As you may or may not see, I was going to take a more generic approach
> > and then
> >> describe the fields on a per-op basis. Of course, the main point here
> > is that
> >> the protocol is documented, so I am not opposed to a different style
> > being used.
> >>
> >> But if you insist on the current layout, do not put a value for the
> > version
> >> because it is not constant (and in fact no longer at 1.0.0). And the
> > "Meaning"
> >> header should be "Description" or something better.
> >>
> >> Hmm, taking another look the layout just seems to busy... I really do
> > think we
> >> should find a different way to format the information.
> >>
> >> Thanks,
> >> matt
> >>
> >>> The description is a preliminary draft only, it may contain mistakes.
> > I tried
> >>> to document what I have understand from the source code and from the
> > actual
> >>> captured network traffic when the USBIP is in action. Please review
> > it, correct it,
> >>> point out the missing parts.
> >>>
> >>> During I have documented the protocol a question came into my mind:
> > why do we
> >>> have two different type of package when the URB completition handler
> > is called,
> >>> namely USB_RET_SUBMIT and USBIP_RET_UNLINK? As far as I can see this
> > causes race
> >>> condition because for one URB the completition handler is only called
> > once. If
> >>> the one URB is sent in with USB_CMD_SUBMIT and then unlinked with
> > USB_CMD_UNLINK
> >>> the completition handler is called only once. In the protocol,
> > however, we have
> >>> two different type of packets: USB_RET_SUBMIT and USBIP_RET_UNLINK.
> > The status
> >>> field of these messages may contain anything in this case depending
> > on the timing.
> >>>
> >>> Regards,
> >>>
> >>> M??rton N??meth
> >>> ---
> >>> diff -uprN staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt
> > staging-2.6/drivers/staging/usbip/usbip_protocol.txt
> >>> --- staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt
> > 1970-01-01 01:00:00.000000000 +0100
> >>> +++ staging-2.6/drivers/staging/usbip/usbip_protocol.txt
> > 2011-06-28 08:30:04.000000000 +0200
> >>> @@ -0,0 +1,352 @@
> >>> +PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
> >>> +28 Jun 2011
> >>> +
> >>> +The USB/IP protocol follows a server/client architecture. The server
> > exports the
> >>> +USB devices and the clients imports them. The device driver for the
> > exported
> >>> +USB device runs on the client machine.
> >>> +
> >>> +The client may ask for the list of the exported USB devices. To get
> > the list the
> >>> +client opens a TCP/IP connection towards the server, and sends an
> > OP_REQ_DEVLIST
> >>> +packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST
> > may be sent
> >>> +in one or more pieces at the low level transport layer). The server
> > sends back
> >>> +the OP_REP_DEVLIST packet which lists the exported USB devices.
> > Finally the
> >>> +TCP/IP connection is closed.
> >>> +
> >>> + virtual host controller usb host
> >>> + "client" "server"
> >>> + (imports USB devices) (exports USB
> > devices)
> >>> + | |
> >>> + | OP_REQ_DEVLIST |
> >>> + | ----------------------------------------------> |
> >>> + | |
> >>> + | OP_REP_DEVLIST |
> >>> + | <---------------------------------------------- |
> >>> + | |
> >>> +
> >>> +Once the client knows the list of exported USB devices it may decide
> > to use one
> >>> +of them. First the client opens a TCP/IP connection towards the
> > server and
> >>> +sends an OP_REQ_IMPORT packet. The server replies with
> > OP_REP_IMPORT. If the
> >>> +import was successful the TCP/IP connection remains open and will be
> > used
> >>> +to trasfer the URB traffic between the client and the server. The
> > client may
> >>> +send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
> >>> +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers
> > of the
> >>> +server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
> >>> +
> >>> + virtual host controller usb host
> >>> + "client" "server"
> >>> + (imports USB devices) (exports USB
> > devices)
> >>> + | |
> >>> + | OP_REQ_IMPORT |
> >>> + | ----------------------------------------------> |
> >>> + | |
> >>> + | OP_REP_IMPORT |
> >>> + | <---------------------------------------------- |
> >>> + | |
> >>> + | |
> >>> + | USBIP_CMD_SUBMIT(seqnum = n) |
> >>> + | ----------------------------------------------> |
> >>> + | |
> >>> + | USBIP_RET_SUBMIT(seqnum = n) |
> >>> + | <---------------------------------------------- |
> >>> + | . |
> >>> + | : |
> >>> + | |
> >>> + | USBIP_CMD_SUBMIT(seqnum = m) |
> >>> + | ----------------------------------------------> |
> >>> + | |
> >>> + | USBIP_CMD_SUBMIT(seqnum = m+1) |
> >>> + | ----------------------------------------------> |
> >>> + | |
> >>> + | USBIP_CMD_SUBMIT(seqnum = m+2) |
> >>> + | ----------------------------------------------> |
> >>> + | |
> >>> + | USBIP_RET_SUBMIT(seqnum = m) |
> >>> + | <---------------------------------------------- |
> >>> + | |
> >>> + | USBIP_CMD_SUBMIT(seqnum = m+3) |
> >>> + | ----------------------------------------------> |
> >>> + | |
> >>> + | USBIP_RET_SUBMIT(seqnum = m+1) |
> >>> + | <---------------------------------------------- |
> >>> + | |
> >>> + | USBIP_CMD_SUBMIT(seqnum = m+4) |
> >>> + | ----------------------------------------------> |
> >>> + | |
> >>> + | USBIP_RET_SUBMIT(seqnum = m+2) |
> >>> + | <---------------------------------------------- |
> >>> + | . |
> >>> + | : |
> >>> + | |
> >>> + | USBIP_CMD_UNLINK |
> >>> + | ----------------------------------------------> |
> >>> + | |
> >>> + | USBIP_RET_UNLINK |
> >>> + | <---------------------------------------------- |
> >>> + | |
> >>> +
> >>> +The fields are in network (big endian) byte order meaning that the
> > most significant
> >>> +byte (MSB) is stored at the lowest address.
> >>> +
> >>> +
> >>> +OP_REQ_DEVLIST: Retrieve the list of exported USB devices.
> >>> +
> >>> + Offset | Length | Value | Meaning
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
> > version number: v1.0.0
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 2 | 2 | 0x8005 | Command code: Retrieve the list
> > of exported USB
> >>> + | | | devices.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
> >>> +
> >>> +OP_REP_DEVLIST: Reply with the list of exported USB devices.
> >>> +
> >>> + Offset | Length | Value | Meaning
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
> > version number: v1.0.0.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 2 | 2 | 0x0005 | Reply code: The list of exported
> > USB devices.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 4 | 4 | 0x00000000 | Status: 0 for OK
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 8 | 4 | n | Number of exported devices: 0
> > means no exported
> >>> + | | | devices.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x0C | | | From now on the exported n
> > devices are described,
> >>> + | | | if any. If no devices are
> > exported the message
> >>> + | | | ends with the previous "number
> > of exported
> >>> + | | | devices" field.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + | 256 | | path: Path of the device on the
> > host exporting the
> >>> + | | | USB device, string closed with
> > zero byte, e.g.
> >>> + | | |
> > "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
> >>> + | | | The unused bytes shall be
> > filled with zero
> >>> + | | | bytes.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x10C | 32 | | busid: Bus ID of the exported
> > device, string
> >>> + | | | closed with zero byte, e.g.
> > "3-2". The unused
> >>> + | | | bytes shall be filled with zero
> > bytes.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x12C | 4 | | busnum
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x130 | 4 | | devnum
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x134 | 4 | | speed
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x138 | 2 | | idVendor
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x13A | 2 | | idProduct
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x13C | 2 | | bcdDevice
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x13E | 1 | | bDeviceClass
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x13F | 1 | | bDeviceSubClass
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x140 | 1 | | bDeviceProtocol
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x141 | 1 | | bConfigurationValue
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x142 | 1 | | bNumConfigurations
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x143 | 1 | | bNumInterfaces
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x144 | | m_0 | From now on each interface is
> > described, all
> >>> + | | | together bNumInterfaces times,
> > with the
> >>> + | | | the following 4 fields:
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + | 1 | | bInterfaceClass
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x145 | 1 | | bInterfaceSubClass
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x146 | 1 | | bInterfaceProtocol
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x147 | 1 | | padding byte for alignment, shall
> > be set to zero
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0xC + | | | The second exported USB device
> > starts at i=1
> >>> + i*0x138 + | | | with the busid field.
> >>> + m_(i-1)*4 | | |
> >>> +
> >>> +OP_REQ_IMPORT: Request to import (attach) a remote USB device.
> >>> +
> >>> + Offset | Length | Value | Meaning
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
> > version number: v1.0.0
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 2 | 2 | 0x8003 | Command code: import a remote USB
> > device.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 8 | 32 | | busid: the busid of the exported
> > device on the
> >>> + | | | remote host. The possible
> > values are taken
> >>> + | | | from the message field
> > OP_REP_DEVLIST.busid.
> >>> + | | | A string closed with zero, the
> > unused bytes
> >>> + | | | shall be filled with zeros.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> +
> >>> +OP_REP_IMPORT: Reply to import (attach) a remote USB device.
> >>> +
> >>> + Offset | Length | Value | Meaning
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
> > version number: v1.0.0
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 2 | 2 | 0x0003 | Reply code: Reply to import.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 4 | 4 | 0x00000000 | Status: 0 for OK
> >>> + | | | 1 for error
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 8 | | | From now on comes the details of
> > the imported
> >>> + | | | device, if the previous status
> > field was OK (0),
> >>> + | | | otherwise the reply ends with
> > the status field.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + | 256 | | path: Path of the device on the
> > host exporting the
> >>> + | | | USB device, string closed with
> > zero byte, e.g.
> >>> + | | |
> > "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
> >>> + | | | The unused bytes shall be
> > filled with zero
> >>> + | | | bytes.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x108 | 32 | | busid: Bus ID of the exported
> > device, string
> >>> + | | | closed with zero byte, e.g.
> > "3-2". The unused
> >>> + | | | bytes shall be filled with zero
> > bytes.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x128 | 4 | | busnum
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x12C | 4 | | devnum
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x130 | 4 | | speed
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x134 | 2 | | idVendor
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x136 | 2 | | idProduct
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x138 | 2 | | bcdDevice
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x139 | 1 | | bDeviceClass
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x13A | 1 | | bDeviceSubClass
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x13B | 1 | | bDeviceProtocol
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x13C | 1 | | bConfigurationValue
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x13D | 1 | | bNumConfigurations
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x13E | 1 | | bNumInterfaces
> >>> +
> >>> +USBIP_CMD_SUBMIT: Submit an URB
> >>> +
> >>> + Offset | Length | Value | Meaning
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0 | 4 | 0x00000001 | command: Submit an URB
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 4 | 4 | | seqnum: the sequence number of
> > the URB to submit
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 8 | 4 | | devid
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> >>> + | | | 1: USBIP_DIR_OUT
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x10 | 4 | | ep: endpoint number, possible
> > values are: 0...15
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x14 | 4 | | transfer_flags: possible values
> > depend on the
> >>> + | | | URB transfer type, see below
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x18 | 4 | | transfer_buffer_length
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x1C | 4 | | start_frame: specify the selected
> > frame to
> >>> + | | | transmit an ISO frame, ignored
> > if URB_ISO_ASAP
> >>> + | | | is specified at transfer_flags
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x20 | 4 | | number_of_packets: number of ISO
> > packets
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x24 | 4 | | interval: maximum time for the
> > request on the
> >>> + | | | server-side host controller
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x28 | 8 | | setup: data bytes for USB setup,
> > filled with
> >>> + | | | zeros if not used
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x30 | | | URB data. For ISO transfers the
> > padding between
> >>> + | | | each ISO packets is not
> > transmitted.
> >>> +
> >>> +
> >>> + Allowed transfer_flags | value | control | interrupt | bulk
> > | isochronous
> >>> +
> > -------------------------+------------+---------+-----------+----------+-------------
> >>> + URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only
> > in | no
> >>> + URB_ISO_ASAP | 0x00000002 | no | no | no
> > | yes
> >>> + URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes
> > | yes
> >>> + URB_NO_FSBR | 0x00000020 | yes | no | no
> > | no
> >>> + URB_ZERO_PACKET | 0x00000040 | no | no | only
> > out | no
> >>> + URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes
> > | yes
> >>> + URB_FREE_BUFFER | 0x00000100 | yes | yes | yes
> > | yes
> >>> + URB_DIR_MASK | 0x00000200 | yes | yes | yes
> > | yes
> >>> +
> >>> +
> >>> +USBIP_RET_SUBMIT: Reply for submitting an URB
> >>> +
> >>> + Offset | Length | Value | Meaning
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0 | 4 | 0x00000002 | command
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 4 | 4 | | seqnum: URB sequence number
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 8 | 4 | | devid
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> >>> + | | | 1: USBIP_DIR_OUT
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x10 | 4 | | ep: endpoint number
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x14 | 4 | | status: zero for successful URB
> > transaction,
> >>> + | | | otherwise some kind of error
> > happened.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x18 | 4 | n | actual_length: number of URB data
> > bytes
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x1C | 4 | | start_frame: for an ISO frame the
> > actually
> >>> + | | | selected frame for transmit.
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x20 | 4 | | number_of_packets
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x24 | 4 | | error_count
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x28 | 8 | | setup: data bytes for USB setup,
> > filled with
> >>> + | | | zeros if not used
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x30 | n | | URB data bytes. For ISO transfers
> > the padding
> >>> + | | | between each ISO packets is not
> > transmitted.
> >>> +
> >>> +USBIP_CMD_UNLINK: Unlink an URB
> >>> +
> >>> + Offset | Length | Value | Meaning
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0 | 4 | 0x00000003 | command: URB unlink command
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 4 | 4 | | seqnum: URB sequence number to
> > unlink: FIXME: is this so?
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 8 | 4 | | devid
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> >>> + | | | 1: USBIP_DIR_OUT
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x10 | 4 | | ep: endpoint number: zero
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x14 | 4 | | seqnum: the URB sequence number
> > given previously
> >>> + | | | at USBIP_CMD_SUBMIT.seqnum field
> >>> +
> >>> +USBIP_RET_UNLINK: Reply for URB unlink
> >>> +
> >>> + Offset | Length | Value | Meaning
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0 | 4 | 0x00000004 | command: reply for the URB unlink
> > command
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 4 | 4 | | seqnum: the unlinked URB sequence
> > number
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 8 | 4 | | devid
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
> >>> + | | | 1: USBIP_DIR_OUT
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x10 | 4 | | ep: endpoint number
> >>>
> > +-----------+--------+------------+---------------------------------------------------
> >>> + 0x14 | 4 | | status: This is the value
> > contained in the
> >>> + | | | urb->status in the URB
> > completition handler.
> >>> + | | | FIXME: a better explanation needed.
> >>>
> >> _______________________________________________
> >> devel mailing list
> >> devel@linuxdriverproject.org <mailto:devel@linuxdriverproject.org>
> >> http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
> >>
> >
> >
> >
> > --
> > Thanks ~
> > Matt Chen
> >
> >
> >
>
--
Thanks ~
Matt Chen
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-06-30 6:54 ` Matt Chen
@ 2011-06-30 19:38 ` Németh Márton
0 siblings, 0 replies; 22+ messages in thread
From: Németh Márton @ 2011-06-30 19:38 UTC (permalink / raw)
To: Matt Chen
Cc: Greg KH, Matthew Wilcox, Max Vozeler, Joe Perches, David Chang,
linux-usb, usbip-devel, devel, LKML
Matt Chen wrote:
> Hi Németh and Matt,
> We are also working on reviewing protocol here. We were wondering if
> you are available for letting us know which part you've already done.
> Then we can save the time for doing the same parts.
I've already sent everything I have. Nothing remained unsent from my side.
> And also we would like to follow your suggesting format to work on it.
> Then it would make it work much faster.
> Any suggestion ?
>
> 2011/6/30 Németh Márton <nm127@freemail.hu>
>> Matt Chen wrote:
>>> Hi Matt,
>>>
>>>
>>> 2011/6/30 matt mooney <mfm@muteddisk.com <mailto:mfm@muteddisk.com>>:
>>>> On 08:52 Tue 28 Jun , N??meth M??rton wrote:
>>>>> From: M??rton N??meth <nm127@freemail.hu <mailto:nm127@freemail.hu>>
>>>>>
>>>>> USBIP v1.0.0 protocol documentation.
>>>>>
>>>>> Signed-off-by: M??rton N??meth <nm127@freemail.hu
>>> <mailto:nm127@freemail.hu>>
>>>>> ---
>>>>>
>>>>> Hi,
>>>>>
>>>>> I tried to document the USBIP protocol as implemented in the Linux
>>> kernel 3.0-rc2.
>>>> Yeah, thanks for doing this. I am also documenting the protocol but am not
>>>> finished yet. We can use yours as the base if you would like although
>>> I have a
>>>> few suggestions.
>>>>
>>>> For one, the grammar needs to be cleaned up, but instead of me
>>> pointing out all
>>>> of the needed corrections, I will send in a grammar corrections patch
>>> on top of
>> Please go on with the corrections. I really started documenting the
>> current USBIP protocol because I think digging in the source code is
>> not the right way to describe a protocol. I'm happy that the review
>> of the USBIP protocol description started. Once we have documented the current
>> USBIP protocol I think we'll see more clearly its weaknesses.
>>
>> What I think important to include in the protocol description is to
>> identify the unused fields and specify an exact value (usually zero) to
>> use for these fields. This makes possible future extension of the protocol
>> easy.
>>
>> One more random thing which came to my mind is that I tend to think that
>> the current implementation is buggy when ISO packets are transmitted.
>> I have a hama AC-150 webcam which is not working well with USBIP. This
>> webcam usually sends smaller ISO packets so there is a gap between
>> the ISO packets in one single URB. The problem came up already in case
>> of usbmon, see https://bugzilla.kernel.org/show_bug.cgi?id=22182 and
>> http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=b17ea167c5fb50dcd5dce5b874a467f04eec886d
>> .
>>
>>>> the finished document. I like that you did a time sequence diagram,
>>> which is
>>>> something I had neglected to include myself; however, I am not a big
>>> fan of how
>>>> you laid out the messages. I was planning on using packet diagrams.
>>> IMHO, it
>>>> makes understanding the message composition much easier allowing more
>>> insight to
>>>> be gathered from a cursory glance.
>>>>
>>>>
>>>> Message Format
>>>> --------------
>>>> 0 1 2 3
>>>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>>>> | Version | Opcode |
>>>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>>>> | Status |
>>>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>>>> . .
>>>> . Data .
>>>> . .
>>>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>>>>
>>>> Version: 16 bit
>>>> Binary-coded decimal version number of the usbip-utils package from
>>>> which the program was built.
>>>>
>>>> Opcode: 16 bits
>>>> ...
>>>>
>>> So as you mentioned, the message format is looked like below:
>>>
>>> OP_REQ_DEVLIST Message Format
>>>
>>> 0 1 2
>>> 3 4
>>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>>> | 0000 0000 1000 0000 | 1000 0000 0000 0101 |
>>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
>>> | 0000 0000 0000 0000 0000 0000 0000 0000 |
>>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
>>>
>>> Is this correct ?
>>>
>>> Personally, I like this way to describe the protocol. ;-)
>> This layout format what is used in other RFCs, too, is really a better
>> way to show the messages. I think, however, that we don't need to put
>> the values in binary format, we could just put one hexadecimal number
>> in the gaps, like this:
>>
>> OP_REQ_DEVLIST Message Format
>>
>>
>> 0 1 2 3
>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>> | 0x0100 | 0x8005 |
>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>> | 0x00000000 |
>> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>>
>>>> As you may or may not see, I was going to take a more generic approach
>>> and then
>>>> describe the fields on a per-op basis. Of course, the main point here
>>> is that
>>>> the protocol is documented, so I am not opposed to a different style
>>> being used.
>>>> But if you insist on the current layout, do not put a value for the
>>> version
>>>> because it is not constant (and in fact no longer at 1.0.0). And the
>>> "Meaning"
>>>> header should be "Description" or something better.
>>>>
>>>> Hmm, taking another look the layout just seems to busy... I really do
>>> think we
>>>> should find a different way to format the information.
>>>>
>>>> Thanks,
>>>> matt
>>>>
>>>>> The description is a preliminary draft only, it may contain mistakes.
>>> I tried
>>>>> to document what I have understand from the source code and from the
>>> actual
>>>>> captured network traffic when the USBIP is in action. Please review
>>> it, correct it,
>>>>> point out the missing parts.
>>>>>
>>>>> During I have documented the protocol a question came into my mind:
>>> why do we
>>>>> have two different type of package when the URB completition handler
>>> is called,
>>>>> namely USB_RET_SUBMIT and USBIP_RET_UNLINK? As far as I can see this
>>> causes race
>>>>> condition because for one URB the completition handler is only called
>>> once. If
>>>>> the one URB is sent in with USB_CMD_SUBMIT and then unlinked with
>>> USB_CMD_UNLINK
>>>>> the completition handler is called only once. In the protocol,
>>> however, we have
>>>>> two different type of packets: USB_RET_SUBMIT and USBIP_RET_UNLINK.
>>> The status
>>>>> field of these messages may contain anything in this case depending
>>> on the timing.
>>>>> Regards,
>>>>>
>>>>> M??rton N??meth
>>>>> ---
>>>>> diff -uprN staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt
>>> staging-2.6/drivers/staging/usbip/usbip_protocol.txt
>>>>> --- staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt
>>> 1970-01-01 01:00:00.000000000 +0100
>>>>> +++ staging-2.6/drivers/staging/usbip/usbip_protocol.txt
>>> 2011-06-28 08:30:04.000000000 +0200
>>>>> @@ -0,0 +1,352 @@
>>>>> +PRELIMINARY DRAFT, MAY CONTAIN MISTAKES!
>>>>> +28 Jun 2011
>>>>> +
>>>>> +The USB/IP protocol follows a server/client architecture. The server
>>> exports the
>>>>> +USB devices and the clients imports them. The device driver for the
>>> exported
>>>>> +USB device runs on the client machine.
>>>>> +
>>>>> +The client may ask for the list of the exported USB devices. To get
>>> the list the
>>>>> +client opens a TCP/IP connection towards the server, and sends an
>>> OP_REQ_DEVLIST
>>>>> +packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST
>>> may be sent
>>>>> +in one or more pieces at the low level transport layer). The server
>>> sends back
>>>>> +the OP_REP_DEVLIST packet which lists the exported USB devices.
>>> Finally the
>>>>> +TCP/IP connection is closed.
>>>>> +
>>>>> + virtual host controller usb host
>>>>> + "client" "server"
>>>>> + (imports USB devices) (exports USB
>>> devices)
>>>>> + | |
>>>>> + | OP_REQ_DEVLIST |
>>>>> + | ----------------------------------------------> |
>>>>> + | |
>>>>> + | OP_REP_DEVLIST |
>>>>> + | <---------------------------------------------- |
>>>>> + | |
>>>>> +
>>>>> +Once the client knows the list of exported USB devices it may decide
>>> to use one
>>>>> +of them. First the client opens a TCP/IP connection towards the
>>> server and
>>>>> +sends an OP_REQ_IMPORT packet. The server replies with
>>> OP_REP_IMPORT. If the
>>>>> +import was successful the TCP/IP connection remains open and will be
>>> used
>>>>> +to trasfer the URB traffic between the client and the server. The
>>> client may
>>>>> +send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and
>>>>> +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers
>>> of the
>>>>> +server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
>>>>> +
>>>>> + virtual host controller usb host
>>>>> + "client" "server"
>>>>> + (imports USB devices) (exports USB
>>> devices)
>>>>> + | |
>>>>> + | OP_REQ_IMPORT |
>>>>> + | ----------------------------------------------> |
>>>>> + | |
>>>>> + | OP_REP_IMPORT |
>>>>> + | <---------------------------------------------- |
>>>>> + | |
>>>>> + | |
>>>>> + | USBIP_CMD_SUBMIT(seqnum = n) |
>>>>> + | ----------------------------------------------> |
>>>>> + | |
>>>>> + | USBIP_RET_SUBMIT(seqnum = n) |
>>>>> + | <---------------------------------------------- |
>>>>> + | . |
>>>>> + | : |
>>>>> + | |
>>>>> + | USBIP_CMD_SUBMIT(seqnum = m) |
>>>>> + | ----------------------------------------------> |
>>>>> + | |
>>>>> + | USBIP_CMD_SUBMIT(seqnum = m+1) |
>>>>> + | ----------------------------------------------> |
>>>>> + | |
>>>>> + | USBIP_CMD_SUBMIT(seqnum = m+2) |
>>>>> + | ----------------------------------------------> |
>>>>> + | |
>>>>> + | USBIP_RET_SUBMIT(seqnum = m) |
>>>>> + | <---------------------------------------------- |
>>>>> + | |
>>>>> + | USBIP_CMD_SUBMIT(seqnum = m+3) |
>>>>> + | ----------------------------------------------> |
>>>>> + | |
>>>>> + | USBIP_RET_SUBMIT(seqnum = m+1) |
>>>>> + | <---------------------------------------------- |
>>>>> + | |
>>>>> + | USBIP_CMD_SUBMIT(seqnum = m+4) |
>>>>> + | ----------------------------------------------> |
>>>>> + | |
>>>>> + | USBIP_RET_SUBMIT(seqnum = m+2) |
>>>>> + | <---------------------------------------------- |
>>>>> + | . |
>>>>> + | : |
>>>>> + | |
>>>>> + | USBIP_CMD_UNLINK |
>>>>> + | ----------------------------------------------> |
>>>>> + | |
>>>>> + | USBIP_RET_UNLINK |
>>>>> + | <---------------------------------------------- |
>>>>> + | |
>>>>> +
>>>>> +The fields are in network (big endian) byte order meaning that the
>>> most significant
>>>>> +byte (MSB) is stored at the lowest address.
>>>>> +
>>>>> +
>>>>> +OP_REQ_DEVLIST: Retrieve the list of exported USB devices.
>>>>> +
>>>>> + Offset | Length | Value | Meaning
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
>>> version number: v1.0.0
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 2 | 2 | 0x8005 | Command code: Retrieve the list
>>> of exported USB
>>>>> + | | | devices.
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
>>>>> +
>>>>> +OP_REP_DEVLIST: Reply with the list of exported USB devices.
>>>>> +
>>>>> + Offset | Length | Value | Meaning
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
>>> version number: v1.0.0.
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 2 | 2 | 0x0005 | Reply code: The list of exported
>>> USB devices.
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 4 | 4 | 0x00000000 | Status: 0 for OK
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 8 | 4 | n | Number of exported devices: 0
>>> means no exported
>>>>> + | | | devices.
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x0C | | | From now on the exported n
>>> devices are described,
>>>>> + | | | if any. If no devices are
>>> exported the message
>>>>> + | | | ends with the previous "number
>>> of exported
>>>>> + | | | devices" field.
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + | 256 | | path: Path of the device on the
>>> host exporting the
>>>>> + | | | USB device, string closed with
>>> zero byte, e.g.
>>>>> + | | |
>>> "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
>>>>> + | | | The unused bytes shall be
>>> filled with zero
>>>>> + | | | bytes.
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x10C | 32 | | busid: Bus ID of the exported
>>> device, string
>>>>> + | | | closed with zero byte, e.g.
>>> "3-2". The unused
>>>>> + | | | bytes shall be filled with zero
>>> bytes.
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x12C | 4 | | busnum
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x130 | 4 | | devnum
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x134 | 4 | | speed
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x138 | 2 | | idVendor
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x13A | 2 | | idProduct
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x13C | 2 | | bcdDevice
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x13E | 1 | | bDeviceClass
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x13F | 1 | | bDeviceSubClass
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x140 | 1 | | bDeviceProtocol
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x141 | 1 | | bConfigurationValue
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x142 | 1 | | bNumConfigurations
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x143 | 1 | | bNumInterfaces
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x144 | | m_0 | From now on each interface is
>>> described, all
>>>>> + | | | together bNumInterfaces times,
>>> with the
>>>>> + | | | the following 4 fields:
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + | 1 | | bInterfaceClass
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x145 | 1 | | bInterfaceSubClass
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x146 | 1 | | bInterfaceProtocol
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x147 | 1 | | padding byte for alignment, shall
>>> be set to zero
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0xC + | | | The second exported USB device
>>> starts at i=1
>>>>> + i*0x138 + | | | with the busid field.
>>>>> + m_(i-1)*4 | | |
>>>>> +
>>>>> +OP_REQ_IMPORT: Request to import (attach) a remote USB device.
>>>>> +
>>>>> + Offset | Length | Value | Meaning
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
>>> version number: v1.0.0
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 2 | 2 | 0x8003 | Command code: import a remote USB
>>> device.
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 8 | 32 | | busid: the busid of the exported
>>> device on the
>>>>> + | | | remote host. The possible
>>> values are taken
>>>>> + | | | from the message field
>>> OP_REP_DEVLIST.busid.
>>>>> + | | | A string closed with zero, the
>>> unused bytes
>>>>> + | | | shall be filled with zeros.
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> +
>>>>> +OP_REP_IMPORT: Reply to import (attach) a remote USB device.
>>>>> +
>>>>> + Offset | Length | Value | Meaning
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0 | 2 | 0x0100 | Binary-coded decimal USBIP
>>> version number: v1.0.0
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 2 | 2 | 0x0003 | Reply code: Reply to import.
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 4 | 4 | 0x00000000 | Status: 0 for OK
>>>>> + | | | 1 for error
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 8 | | | From now on comes the details of
>>> the imported
>>>>> + | | | device, if the previous status
>>> field was OK (0),
>>>>> + | | | otherwise the reply ends with
>>> the status field.
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + | 256 | | path: Path of the device on the
>>> host exporting the
>>>>> + | | | USB device, string closed with
>>> zero byte, e.g.
>>>>> + | | |
>>> "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
>>>>> + | | | The unused bytes shall be
>>> filled with zero
>>>>> + | | | bytes.
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x108 | 32 | | busid: Bus ID of the exported
>>> device, string
>>>>> + | | | closed with zero byte, e.g.
>>> "3-2". The unused
>>>>> + | | | bytes shall be filled with zero
>>> bytes.
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x128 | 4 | | busnum
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x12C | 4 | | devnum
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x130 | 4 | | speed
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x134 | 2 | | idVendor
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x136 | 2 | | idProduct
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x138 | 2 | | bcdDevice
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x139 | 1 | | bDeviceClass
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x13A | 1 | | bDeviceSubClass
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x13B | 1 | | bDeviceProtocol
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x13C | 1 | | bConfigurationValue
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x13D | 1 | | bNumConfigurations
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x13E | 1 | | bNumInterfaces
>>>>> +
>>>>> +USBIP_CMD_SUBMIT: Submit an URB
>>>>> +
>>>>> + Offset | Length | Value | Meaning
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0 | 4 | 0x00000001 | command: Submit an URB
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 4 | 4 | | seqnum: the sequence number of
>>> the URB to submit
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 8 | 4 | | devid
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
>>>>> + | | | 1: USBIP_DIR_OUT
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x10 | 4 | | ep: endpoint number, possible
>>> values are: 0...15
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x14 | 4 | | transfer_flags: possible values
>>> depend on the
>>>>> + | | | URB transfer type, see below
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x18 | 4 | | transfer_buffer_length
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x1C | 4 | | start_frame: specify the selected
>>> frame to
>>>>> + | | | transmit an ISO frame, ignored
>>> if URB_ISO_ASAP
>>>>> + | | | is specified at transfer_flags
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x20 | 4 | | number_of_packets: number of ISO
>>> packets
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x24 | 4 | | interval: maximum time for the
>>> request on the
>>>>> + | | | server-side host controller
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x28 | 8 | | setup: data bytes for USB setup,
>>> filled with
>>>>> + | | | zeros if not used
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x30 | | | URB data. For ISO transfers the
>>> padding between
>>>>> + | | | each ISO packets is not
>>> transmitted.
>>>>> +
>>>>> +
>>>>> + Allowed transfer_flags | value | control | interrupt | bulk
>>> | isochronous
>>>>> +
>>> -------------------------+------------+---------+-----------+----------+-------------
>>>>> + URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only
>>> in | no
>>>>> + URB_ISO_ASAP | 0x00000002 | no | no | no
>>> | yes
>>>>> + URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes
>>> | yes
>>>>> + URB_NO_FSBR | 0x00000020 | yes | no | no
>>> | no
>>>>> + URB_ZERO_PACKET | 0x00000040 | no | no | only
>>> out | no
>>>>> + URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes
>>> | yes
>>>>> + URB_FREE_BUFFER | 0x00000100 | yes | yes | yes
>>> | yes
>>>>> + URB_DIR_MASK | 0x00000200 | yes | yes | yes
>>> | yes
>>>>> +
>>>>> +
>>>>> +USBIP_RET_SUBMIT: Reply for submitting an URB
>>>>> +
>>>>> + Offset | Length | Value | Meaning
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0 | 4 | 0x00000002 | command
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 4 | 4 | | seqnum: URB sequence number
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 8 | 4 | | devid
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
>>>>> + | | | 1: USBIP_DIR_OUT
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x10 | 4 | | ep: endpoint number
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x14 | 4 | | status: zero for successful URB
>>> transaction,
>>>>> + | | | otherwise some kind of error
>>> happened.
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x18 | 4 | n | actual_length: number of URB data
>>> bytes
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x1C | 4 | | start_frame: for an ISO frame the
>>> actually
>>>>> + | | | selected frame for transmit.
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x20 | 4 | | number_of_packets
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x24 | 4 | | error_count
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x28 | 8 | | setup: data bytes for USB setup,
>>> filled with
>>>>> + | | | zeros if not used
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x30 | n | | URB data bytes. For ISO transfers
>>> the padding
>>>>> + | | | between each ISO packets is not
>>> transmitted.
>>>>> +
>>>>> +USBIP_CMD_UNLINK: Unlink an URB
>>>>> +
>>>>> + Offset | Length | Value | Meaning
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0 | 4 | 0x00000003 | command: URB unlink command
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 4 | 4 | | seqnum: URB sequence number to
>>> unlink: FIXME: is this so?
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 8 | 4 | | devid
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
>>>>> + | | | 1: USBIP_DIR_OUT
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x10 | 4 | | ep: endpoint number: zero
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x14 | 4 | | seqnum: the URB sequence number
>>> given previously
>>>>> + | | | at USBIP_CMD_SUBMIT.seqnum field
>>>>> +
>>>>> +USBIP_RET_UNLINK: Reply for URB unlink
>>>>> +
>>>>> + Offset | Length | Value | Meaning
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0 | 4 | 0x00000004 | command: reply for the URB unlink
>>> command
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 4 | 4 | | seqnum: the unlinked URB sequence
>>> number
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 8 | 4 | | devid
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
>>>>> + | | | 1: USBIP_DIR_OUT
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x10 | 4 | | ep: endpoint number
>>>>>
>>> +-----------+--------+------------+---------------------------------------------------
>>>>> + 0x14 | 4 | | status: This is the value
>>> contained in the
>>>>> + | | | urb->status in the URB
>>> completition handler.
>>>>> + | | | FIXME: a better explanation needed.
>>>>>
>>>> _______________________________________________
>>>> devel mailing list
>>>> devel@linuxdriverproject.org <mailto:devel@linuxdriverproject.org>
>>>> http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
>>>>
>>>
>>>
>>> --
>>> Thanks ~
>>> Matt Chen
>>>
>>>
>>>
>
>
>
> --
> Thanks ~
> Matt Chen
>
>
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-06-29 8:04 ` David Chang
@ 2011-07-04 3:11 ` David Chang
2011-07-04 5:38 ` Németh Márton
0 siblings, 1 reply; 22+ messages in thread
From: David Chang @ 2011-07-04 3:11 UTC (permalink / raw)
To: Németh Márton
Cc: Greg KH, Matthew Wilcox, Max Vozeler, Matt Mooney, Joe Perches,
linux-usb, usbip-devel, devel, LKML
Hi Németh,
2011/6/29 David Chang <dchang@novell.com>:
> Hi,
>
> Thanks for your great effort.
> Just a little comment on UNLINK pdu size.
>
> 2011/6/28 Németh Márton <nm127@freemail.hu>:
>> From: Márton Németh <nm127@freemail.hu>
>>
>> USBIP v1.0.0 protocol documentation.
>>
>> Signed-off-by: Márton Németh <nm127@freemail.hu>
>> ---
>> +USBIP_CMD_UNLINK: Unlink an URB
>> +
>> + Offset | Length | Value | Meaning
>> +-----------+--------+------------+---------------------------------------------------
>> + 0 | 4 | 0x00000003 | command: URB unlink command
>> +-----------+--------+------------+---------------------------------------------------
>> + 4 | 4 | | seqnum: URB sequence number to unlink: FIXME: is this so?
>> +-----------+--------+------------+---------------------------------------------------
>> + 8 | 4 | | devid
>> +-----------+--------+------------+---------------------------------------------------
>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
>> + | | | 1: USBIP_DIR_OUT
>> +-----------+--------+------------+---------------------------------------------------
>> + 0x10 | 4 | | ep: endpoint number: zero
>> +-----------+--------+------------+---------------------------------------------------
>> + 0x14 | 4 | | seqnum: the URB sequence number given previously
>> + | | | at USBIP_CMD_SUBMIT.seqnum field
-----------+--------+------------+---------------------------------------------------
0x30 | n | | URB data bytes. For ISO
transfers the padding
| | | between each ISO
packets is not transmitted.
>> +
>> +USBIP_RET_UNLINK: Reply for URB unlink
>> +
>> + Offset | Length | Value | Meaning
>> +-----------+--------+------------+---------------------------------------------------
>> + 0 | 4 | 0x00000004 | command: reply for the URB unlink command
>> +-----------+--------+------------+---------------------------------------------------
>> + 4 | 4 | | seqnum: the unlinked URB sequence number
>> +-----------+--------+------------+---------------------------------------------------
>> + 8 | 4 | | devid
>> +-----------+--------+------------+---------------------------------------------------
>> + 0xC | 4 | | direction: 0: USBIP_DIR_IN
>> + | | | 1: USBIP_DIR_OUT
>> +-----------+--------+------------+---------------------------------------------------
>> + 0x10 | 4 | | ep: endpoint number
>> +-----------+--------+------------+---------------------------------------------------
>> + 0x14 | 4 | | status: This is the value contained in the
>> + | | | urb->status in the URB completition handler.
>> + | | | FIXME: a better explanation needed.
-----------+--------+------------+---------------------------------------------------
0x30 | n | | URB data bytes. For ISO
transfers the padding
| | | between each ISO
packets is not transmitted.
Would you add this field into your path or should I send another patch
to add it?
Thanks.
Regards,
David Chang
>
> Regards,
> David Chang
>
>>
>> _______________________________________________
>> devel mailing list
>> devel@linuxdriverproject.org
>> http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
>>
>
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-07-04 3:11 ` David Chang
@ 2011-07-04 5:38 ` Németh Márton
2011-07-04 8:24 ` Matt Chen
0 siblings, 1 reply; 22+ messages in thread
From: Németh Márton @ 2011-07-04 5:38 UTC (permalink / raw)
To: David Chang, Matt Mooney, Matt Chen
Cc: Greg KH, Matthew Wilcox, Max Vozeler, Joe Perches, linux-usb,
usbip-devel, devel, LKML
Hi David, Matt Chen and Matt Mooney,
it looks like we four are actively dealing with the USBIP protocol documentation.
David, are you working at the same place like Matt Chen? Then you can easily
see what you two has been done and not working parallel on the same thing.
I'm currently not actively modifying the USBIP protocol description.
Matt Mooney wanted to restructure the USBIP protocol documentation. Matt, do
you have anything already done? If yes, maybe it would be good if you could
send it so David can do the changes on your version. If you haven't worked on
it then please tell and David can add the necessary modifications he suggested.
Regards,
Márton Németh
David Chang wrote:
> Hi Németh,
>
> 2011/6/29 David Chang <dchang@novell.com>:
>> Hi,
>>
>> Thanks for your great effort.
>> Just a little comment on UNLINK pdu size.
[...]
> Would you add this field into your path or should I send another patch
> to add it?
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-07-04 5:38 ` Németh Márton
@ 2011-07-04 8:24 ` Matt Chen
2011-07-07 4:14 ` matt mooney
0 siblings, 1 reply; 22+ messages in thread
From: Matt Chen @ 2011-07-04 8:24 UTC (permalink / raw)
To: Németh Márton
Cc: David Chang, Matt Mooney, Greg KH, Matthew Wilcox, Max Vozeler,
Joe Perches, linux-usb, usbip-devel, devel, LKML
Hi Németh,
2011/7/4 Németh Márton <nm127@freemail.hu>:
> Hi David, Matt Chen and Matt Mooney,
>
> it looks like we four are actively dealing with the USBIP protocol documentation.
>
> David, are you working at the same place like Matt Chen? Then you can easily
> see what you two has been done and not working parallel on the same thing.
Actually, David and me (Matt Chen) are working on 2 different part.
1. Matt Chen : Server side
2. David Chang : Client side.
Just didn't figure you submitted the protocol document earlier than we do.
We also write a wiki for our code reviewing, protocol, but since all
we are working personally, something we don't sync, that's why I tried
to ask if which part you are not working on or finished, we can work
on it.
Since you submitted the document, it turned out we follow the format
you've done and do some fix for it.
> I'm currently not actively modifying the USBIP protocol description.
>
> Matt Mooney wanted to restructure the USBIP protocol documentation. Matt, do
> you have anything already done? If yes, maybe it would be good if you could
> send it so David can do the changes on your version. If you haven't worked on
> it then please tell and David can add the necessary modifications he suggested.
I supposed it is Matt Mooney. ~ :)
> Regards,
>
> Márton Németh
>
> David Chang wrote:
>> Hi Németh,
>>
>> 2011/6/29 David Chang <dchang@novell.com>:
>>> Hi,
>>>
>>> Thanks for your great effort.
>>> Just a little comment on UNLINK pdu size.
> [...]
>> Would you add this field into your path or should I send another patch
>> to add it?
>
>
--
Thanks ~
Matt Chen
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-07-04 8:24 ` Matt Chen
@ 2011-07-07 4:14 ` matt mooney
2011-07-07 6:20 ` Matt Chen
0 siblings, 1 reply; 22+ messages in thread
From: matt mooney @ 2011-07-07 4:14 UTC (permalink / raw)
To: Matt Chen
Cc: N?meth M?rton, David Chang, Greg KH, Matthew Wilcox, Max Vozeler,
Joe Perches, linux-usb, usbip-devel, devel, LKML
On 16:24 Mon 04 Jul , Matt Chen wrote:
> Hi N?meth,
>
> 2011/7/4 N?meth M?rton <nm127@freemail.hu>:
> > Hi David, Matt Chen and Matt Mooney,
> >
> > it looks like we four are actively dealing with the USBIP protocol documentation.
> >
> > David, are you working at the same place like Matt Chen? Then you can easily
> > see what you two has been done and not working parallel on the same thing.
> Actually, David and me (Matt Chen) are working on 2 different part.
> 1. Matt Chen : Server side
> 2. David Chang : Client side.
> Just didn't figure you submitted the protocol document earlier than we do.
> We also write a wiki for our code reviewing, protocol, but since all
> we are working personally, something we don't sync, that's why I tried
> to ask if which part you are not working on or finished, we can work
> on it.
Hey guys,
It seems like you guys all have a handle on this, so I will defer. When the
documentation is at a point where it can be submitted, I will send in grammar
patches along with possible reorganization suggestions.
Is this a public wiki Matt so that you can post a link to it?
Thanks,
mfm
> Since you submitted the document, it turned out we follow the format
> you've done and do some fix for it.
> > I'm currently not actively modifying the USBIP protocol description.
> >
> > Matt Mooney wanted to restructure the USBIP protocol documentation. Matt, do
> > you have anything already done? If yes, maybe it would be good if you could
> > send it so David can do the changes on your version. If you haven't worked on
> > it then please tell and David can add the necessary modifications he suggested.
> I supposed it is Matt Mooney. ~ :)
> > Regards,
> >
> > ? ? ? ?M?rton N?meth
> >
> > David Chang wrote:
> >> Hi N?meth,
> >>
> >> 2011/6/29 David Chang <dchang@novell.com>:
> >>> Hi,
> >>>
> >>> Thanks for your great effort.
> >>> Just a little comment on UNLINK pdu size.
> > [...]
> >> Would you add this field into your path or should I send another patch
> >> to add it?
> >
> >
>
>
>
> --
> Thanks ~
> Matt Chen
>
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-07-07 4:14 ` matt mooney
@ 2011-07-07 6:20 ` Matt Chen
2011-07-25 4:30 ` Matt Chen
0 siblings, 1 reply; 22+ messages in thread
From: Matt Chen @ 2011-07-07 6:20 UTC (permalink / raw)
To: Matt Chen, N?meth M?rton, David Chang, Greg KH, Matthew Wilcox,
Max Vozeler, Joe Perches, linux-usb, usbip-devel, devel, LKML
Hi Matt mooney (just in case of confusing that I am Matt as well),
2011/7/7 matt mooney <mfm@muteddisk.com>:
> On 16:24 Mon 04 Jul , Matt Chen wrote:
>> Hi N?meth,
>>
>> 2011/7/4 N?meth M?rton <nm127@freemail.hu>:
>> > Hi David, Matt Chen and Matt Mooney,
>> >
>> > it looks like we four are actively dealing with the USBIP protocol documentation.
>> >
>> > David, are you working at the same place like Matt Chen? Then you can easily
>> > see what you two has been done and not working parallel on the same thing.
>> Actually, David and me (Matt Chen) are working on 2 different part.
>> 1. Matt Chen : Server side
>> 2. David Chang : Client side.
>> Just didn't figure you submitted the protocol document earlier than we do.
>> We also write a wiki for our code reviewing, protocol, but since all
>> we are working personally, something we don't sync, that's why I tried
>> to ask if which part you are not working on or finished, we can work
>> on it.
>
> Hey guys,
>
> It seems like you guys all have a handle on this, so I will defer. When the
> documentation is at a point where it can be submitted, I will send in grammar
> patches along with possible reorganization suggestions.
>
> Is this a public wiki Matt so that you can post a link to it?
Recently we are writing in our internal wiki system. We are intended
to change to a external wiki pages, such as open SuSE wiki pages. We
are working on it right now.
But it would take time before it's done. ;-)
Thanks in advanced.
> Thanks,
> mfm
>
>> Since you submitted the document, it turned out we follow the format
>> you've done and do some fix for it.
>> > I'm currently not actively modifying the USBIP protocol description.
>> >
>> > Matt Mooney wanted to restructure the USBIP protocol documentation. Matt, do
>> > you have anything already done? If yes, maybe it would be good if you could
>> > send it so David can do the changes on your version. If you haven't worked on
>> > it then please tell and David can add the necessary modifications he suggested.
>> I supposed it is Matt Mooney. ~ :)
>> > Regards,
>> >
>> > ? ? ? ?M?rton N?meth
>> >
>> > David Chang wrote:
>> >> Hi N?meth,
>> >>
>> >> 2011/6/29 David Chang <dchang@novell.com>:
>> >>> Hi,
>> >>>
>> >>> Thanks for your great effort.
>> >>> Just a little comment on UNLINK pdu size.
>> > [...]
>> >> Would you add this field into your path or should I send another patch
>> >> to add it?
>> >
>> >
>>
>>
>>
>> --
>> Thanks ~
>> Matt Chen
>>
>
--
Thanks ~
Matt Chen
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-07-07 6:20 ` Matt Chen
@ 2011-07-25 4:30 ` Matt Chen
0 siblings, 0 replies; 22+ messages in thread
From: Matt Chen @ 2011-07-25 4:30 UTC (permalink / raw)
To: Matt Chen, N?meth M?rton, David Chang, Greg KH, Matthew Wilcox,
Max Vozeler, Joe Perches, linux-usb, usbip-devel, devel, LKML
Hi all,
The USBIP protocol we maintained is in
http://en.opensuse.org/USBIP
you guys may have a look or try to modify them as you like.
2011/7/7 Matt Chen <machen@novell.com>:
> Hi Matt mooney (just in case of confusing that I am Matt as well),
>
> 2011/7/7 matt mooney <mfm@muteddisk.com>:
>> On 16:24 Mon 04 Jul , Matt Chen wrote:
>>> Hi N?meth,
>>>
>>> 2011/7/4 N?meth M?rton <nm127@freemail.hu>:
>>> > Hi David, Matt Chen and Matt Mooney,
>>> >
>>> > it looks like we four are actively dealing with the USBIP protocol documentation.
>>> >
>>> > David, are you working at the same place like Matt Chen? Then you can easily
>>> > see what you two has been done and not working parallel on the same thing.
>>> Actually, David and me (Matt Chen) are working on 2 different part.
>>> 1. Matt Chen : Server side
>>> 2. David Chang : Client side.
>>> Just didn't figure you submitted the protocol document earlier than we do.
>>> We also write a wiki for our code reviewing, protocol, but since all
>>> we are working personally, something we don't sync, that's why I tried
>>> to ask if which part you are not working on or finished, we can work
>>> on it.
>>
>> Hey guys,
>>
>> It seems like you guys all have a handle on this, so I will defer. When the
>> documentation is at a point where it can be submitted, I will send in grammar
>> patches along with possible reorganization suggestions.
>>
>> Is this a public wiki Matt so that you can post a link to it?
> Recently we are writing in our internal wiki system. We are intended
> to change to a external wiki pages, such as open SuSE wiki pages. We
> are working on it right now.
> But it would take time before it's done. ;-)
>
> Thanks in advanced.
>> Thanks,
>> mfm
>>
>>> Since you submitted the document, it turned out we follow the format
>>> you've done and do some fix for it.
>>> > I'm currently not actively modifying the USBIP protocol description.
>>> >
>>> > Matt Mooney wanted to restructure the USBIP protocol documentation. Matt, do
>>> > you have anything already done? If yes, maybe it would be good if you could
>>> > send it so David can do the changes on your version. If you haven't worked on
>>> > it then please tell and David can add the necessary modifications he suggested.
>>> I supposed it is Matt Mooney. ~ :)
>>> > Regards,
>>> >
>>> > ? ? ? ?M?rton N?meth
>>> >
>>> > David Chang wrote:
>>> >> Hi N?meth,
>>> >>
>>> >> 2011/6/29 David Chang <dchang@novell.com>:
>>> >>> Hi,
>>> >>>
>>> >>> Thanks for your great effort.
>>> >>> Just a little comment on UNLINK pdu size.
>>> > [...]
>>> >> Would you add this field into your path or should I send another patch
>>> >> to add it?
>>> >
>>> >
>>>
>>>
>>>
>>> --
>>> Thanks ~
>>> Matt Chen
>>>
>>
>
>
>
> --
> Thanks ~
> Matt Chen
>
--
Thanks ~
Matt Chen
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-06-28 6:52 ` [PATCH, RFC] USBIP protocol documentation Németh Márton
2011-06-29 8:04 ` David Chang
2011-06-29 23:34 ` matt mooney
@ 2011-08-09 9:23 ` David Chang
2011-08-09 14:22 ` Greg KH
2 siblings, 1 reply; 22+ messages in thread
From: David Chang @ 2011-08-09 9:23 UTC (permalink / raw)
To: Greg KH
Cc: Németh Márton, Matthew Wilcox, Max Vozeler,
Matt Mooney, Joe Perches, linux-usb, usbip-devel, devel, LKML
Hi Greg,
2011/6/28 Németh Márton <nm127@freemail.hu>:
> From: Márton Németh <nm127@freemail.hu>
>
> USBIP v1.0.0 protocol documentation.
>
> Signed-off-by: Márton Németh <nm127@freemail.hu>
> ---
>
> Hi,
>
> I tried to document the USBIP protocol as implemented in the Linux kernel 3.0-rc2.
>
> The description is a preliminary draft only, it may contain mistakes. I tried
> to document what I have understand from the source code and from the actual
> captured network traffic when the USBIP is in action. Please review it, correct it,
> point out the missing parts.
>
> During I have documented the protocol a question came into my mind: why do we
> have two different type of package when the URB completition handler is called,
> namely USB_RET_SUBMIT and USBIP_RET_UNLINK? As far as I can see this causes race
> condition because for one URB the completition handler is only called once. If
> the one URB is sent in with USB_CMD_SUBMIT and then unlinked with USB_CMD_UNLINK
> the completition handler is called only once. In the protocol, however, we have
> two different type of packets: USB_RET_SUBMIT and USBIP_RET_UNLINK. The status
> field of these messages may contain anything in this case depending on the timing.
>
> Regards,
>
> Márton Németh
Sorry, just one question about the usbip protocol document.
I would like to know why didn't you apply this patch.
Thanks in advance!
Best Regards,
David
>
> _______________________________________________
> devel mailing list
> devel@linuxdriverproject.org
> http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
>
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-08-09 9:23 ` David Chang
@ 2011-08-09 14:22 ` Greg KH
2011-08-10 6:41 ` David Chang
0 siblings, 1 reply; 22+ messages in thread
From: Greg KH @ 2011-08-09 14:22 UTC (permalink / raw)
To: David Chang
Cc: Németh Márton, Matthew Wilcox, Max Vozeler,
Matt Mooney, Joe Perches, linux-usb, usbip-devel, devel, LKML
On Tue, Aug 09, 2011 at 05:23:14PM +0800, David Chang wrote:
> Hi Greg,
>
> 2011/6/28 Németh Márton <nm127@freemail.hu>:
> > From: Márton Németh <nm127@freemail.hu>
> >
> > USBIP v1.0.0 protocol documentation.
> >
> > Signed-off-by: Márton Németh <nm127@freemail.hu>
> > ---
> >
> > Hi,
> >
> > I tried to document the USBIP protocol as implemented in the Linux kernel 3.0-rc2.
> >
> > The description is a preliminary draft only, it may contain mistakes. I tried
> > to document what I have understand from the source code and from the actual
> > captured network traffic when the USBIP is in action. Please review it, correct it,
> > point out the missing parts.
> >
> > During I have documented the protocol a question came into my mind: why do we
> > have two different type of package when the URB completition handler is called,
> > namely USB_RET_SUBMIT and USBIP_RET_UNLINK? As far as I can see this causes race
> > condition because for one URB the completition handler is only called once. If
> > the one URB is sent in with USB_CMD_SUBMIT and then unlinked with USB_CMD_UNLINK
> > the completition handler is called only once. In the protocol, however, we have
> > two different type of packets: USB_RET_SUBMIT and USBIP_RET_UNLINK. The status
> > field of these messages may contain anything in this case depending on the timing.
> >
> > Regards,
> >
> > Márton Németh
>
> Sorry, just one question about the usbip protocol document.
> I would like to know why didn't you apply this patch.
Because it was sent as a "RFC" (i.e. request for comments) and based on
the discussion afterward, there were lots of comments :)
If someone wants to resend it to me, without that marking, I'll be glad
to apply it.
thanks,
greg k-h
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH, RFC] USBIP protocol documentation
2011-08-09 14:22 ` Greg KH
@ 2011-08-10 6:41 ` David Chang
0 siblings, 0 replies; 22+ messages in thread
From: David Chang @ 2011-08-10 6:41 UTC (permalink / raw)
To: Németh Márton
Cc: Matthew Wilcox, Max Vozeler, Joe Perches, linux-usb, usbip-devel,
devel, LKML, Greg KH, Matt Mooney
Hi Németh,
2011/8/9 Greg KH <greg@kroah.com>:
> On Tue, Aug 09, 2011 at 05:23:14PM +0800, David Chang wrote:
>> Hi Greg,
>>
>> Sorry, just one question about the usbip protocol document.
>> I would like to know why didn't you apply this patch.
>
> Because it was sent as a "RFC" (i.e. request for comments) and based on
> the discussion afterward, there were lots of comments :)
>
> If someone wants to resend it to me, without that marking, I'll be glad
> to apply it.
>
Could you resend the protocol document patch again without the RFC marking?
And then we can get an initial version of the USBIP document.
Thanks!
Best Regards,
David
^ permalink raw reply [flat|nested] 22+ messages in thread
end of thread, other threads:[~2011-08-10 6:41 UTC | newest]
Thread overview: 22+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-05-24 18:28 USBIP protocol documentation? Németh Márton
2011-05-24 18:34 ` Greg KH
2011-05-24 20:25 ` Németh Márton
2011-05-24 21:25 ` Greg KH
2011-05-25 3:12 ` matt mooney
2011-05-25 5:29 ` Németh Márton
2011-05-26 7:13 ` Németh Márton
2011-06-28 6:52 ` [PATCH, RFC] USBIP protocol documentation Németh Márton
2011-06-29 8:04 ` David Chang
2011-07-04 3:11 ` David Chang
2011-07-04 5:38 ` Németh Márton
2011-07-04 8:24 ` Matt Chen
2011-07-07 4:14 ` matt mooney
2011-07-07 6:20 ` Matt Chen
2011-07-25 4:30 ` Matt Chen
2011-06-29 23:34 ` matt mooney
[not found] ` <BANLkTi=qXgnapyrsSANJ0XZuE=kz7QgsvA@mail.gmail.com>
2011-06-30 5:56 ` Németh Márton
2011-06-30 6:54 ` Matt Chen
2011-06-30 19:38 ` Németh Márton
2011-08-09 9:23 ` David Chang
2011-08-09 14:22 ` Greg KH
2011-08-10 6:41 ` David Chang
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.