2011-05-24 18:28:29

by Németh Márton

[permalink] [raw]
Subject: USBIP protocol documentation?

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


2011-05-24 18:34:53

by Greg KH

[permalink] [raw]
Subject: Re: USBIP protocol documentation?

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

2011-05-24 20:25:36

by Németh Márton

[permalink] [raw]
Subject: Re: USBIP protocol documentation?

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

2011-05-24 21:30:10

by Greg KH

[permalink] [raw]
Subject: Re: USBIP protocol documentation?

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

2011-05-25 03:13:34

by matt mooney

[permalink] [raw]
Subject: Re: USBIP protocol documentation?

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

2011-05-25 05:30:15

by Németh Márton

[permalink] [raw]
Subject: Re: USBIP protocol documentation?


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 <[email protected]>

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

2011-05-26 07:13:50

by Németh Márton

[permalink] [raw]
Subject: Re: USBIP protocol documentation?

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 <[email protected]>
>
> 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
>

2011-06-28 06:55:20

by Németh Márton

[permalink] [raw]
Subject: [PATCH, RFC] USBIP protocol documentation

From: Márton Németh <[email protected]>

USBIP v1.0.0 protocol documentation.

Signed-off-by: Márton Németh <[email protected]>
---

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.

2011-06-29 08:05:08

by David Chang

[permalink] [raw]
Subject: Re: [PATCH, RFC] USBIP protocol documentation

Hi,

Thanks for your great effort.
Just a little comment on UNLINK pdu size.

2011/6/28 N?meth M?rton <[email protected]>:
> From: M?rton N?meth <[email protected]>
>
> USBIP v1.0.0 protocol documentation.
>
> Signed-off-by: M?rton N?meth <[email protected]>
> ---
>
> 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
> [email protected]
> http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
>

2011-06-29 23:35:41

by matt mooney

[permalink] [raw]
Subject: Re: [PATCH, RFC] USBIP protocol documentation

On 08:52 Tue 28 Jun , N??meth M??rton wrote:
> From: M??rton N??meth <[email protected]>
>
> USBIP v1.0.0 protocol documentation.
>
> Signed-off-by: M??rton N??meth <[email protected]>
> ---
>
> 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.
>

2011-06-30 05:57:46

by Németh Márton

[permalink] [raw]
Subject: Re: [PATCH, RFC] USBIP protocol documentation

Matt Chen wrote:
> Hi Matt,
>
>
> 2011/6/30 matt mooney <[email protected] <mailto:[email protected]>>:
>> On 08:52 Tue 28 Jun , N??meth M??rton wrote:
>>> From: M??rton N??meth <[email protected] <mailto:[email protected]>>
>>>
>>> USBIP v1.0.0 protocol documentation.
>>>
>>> Signed-off-by: M??rton N??meth <[email protected]
> <mailto:[email protected]>>
>>> ---
>>>
>>> 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
>> [email protected] <mailto:[email protected]>
>> http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
>>
>
>
>
> --
> Thanks ~
> Matt Chen
>
>
>

2011-06-30 06:54:57

by Matt Chen

[permalink] [raw]
Subject: Re: [PATCH, RFC] USBIP protocol documentation

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 <[email protected]>
>
> Matt Chen wrote:
> > Hi Matt,
> >
> >
> > 2011/6/30 matt mooney <[email protected] <mailto:[email protected]>>:
> >> On 08:52 Tue 28 Jun ? ? , N??meth M??rton wrote:
> >>> From: M??rton N??meth <[email protected] <mailto:[email protected]>>
> >>>
> >>> USBIP v1.0.0 protocol documentation.
> >>>
> >>> Signed-off-by: M??rton N??meth <[email protected]
> > <mailto:[email protected]>>
> >>> ---
> >>>
> >>> 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
> >> [email protected] <mailto:[email protected]>
> >> http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
> >>
> >
> >
> >
> > --
> > Thanks ~
> > Matt Chen
> >
> >
> >
>



--
Thanks ~
Matt Chen

2011-06-30 19:39:39

by Németh Márton

[permalink] [raw]
Subject: Re: [PATCH, RFC] USBIP protocol documentation

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 <[email protected]>
>> Matt Chen wrote:
>>> Hi Matt,
>>>
>>>
>>> 2011/6/30 matt mooney <[email protected] <mailto:[email protected]>>:
>>>> On 08:52 Tue 28 Jun , N??meth M??rton wrote:
>>>>> From: M??rton N??meth <[email protected] <mailto:[email protected]>>
>>>>>
>>>>> USBIP v1.0.0 protocol documentation.
>>>>>
>>>>> Signed-off-by: M??rton N??meth <[email protected]
>>> <mailto:[email protected]>>
>>>>> ---
>>>>>
>>>>> 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
>>>> [email protected] <mailto:[email protected]>
>>>> http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
>>>>
>>>
>>>
>>> --
>>> Thanks ~
>>> Matt Chen
>>>
>>>
>>>
>
>
>
> --
> Thanks ~
> Matt Chen
>
>