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
Quoted 9 lines · Németh Márton
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
Quoted 6 lines
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
Quoted 10 lines · Greg KH
Quoted 9 lines · Németh Márton
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
Quoted 8 lines
Quoted 6 lines
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.
Quoted 4 lines
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
Quoted 4 lines · Németh Márton
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
Quoted 11 lines · N??meth M??rton
Quoted 10 lines · Greg KH
Quoted 9 lines · N??meth M??rton
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
Quoted 8 lines
Quoted 8 lines
Quoted 6 lines
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!
Quoted 20 lines
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.hand 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);
Quoted 1 line
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.
Quoted 9 lines
Quoted 4 lines
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:
Quoted 6 lines
* 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
Quoted 13 lines · matt mooney
Quoted 2 lines · Németh Márton
Quoted 1 line · Greg KH
I think the code is the "real" documentation.
I concur!
Quoted 7 lines
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.hand 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_'
Quoted 13 lines
Quoted 13 lines
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);
Quoted 5 lines
Quoted 1 line
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?
Quoted 5 lines · Németh Márton
Quoted 4 lines
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?
Quoted 4 lines · Greg KH
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 :)
Quoted 5 lines · matt mooney
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
Quoted 27 lines · Németh Márton
Quoted 12 lines · matt mooney
Quoted 2 lines · Németh Márton
Quoted 1 line · Greg KH
I think the code is the "real" documentation.
I concur!
Quoted 7 lines
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.hand 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_'
Quoted 13 lines
Quoted 13 lines
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);
Quoted 8 lines
Quoted 4 lines
Quoted 1 line
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.
Quoted 51 lines
Quoted 5 lines · Németh Márton
Quoted 4 lines
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?
Quoted 4 lines · Greg KH
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 :)
Quoted 5 lines · matt mooney
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
RFC PATCH 1/1 USBIP protocol documentation
From: Márton Németh <[email protected]>
USBIP v1.0.0 protocol documentation.
---
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
---
drivers/staging/usbip/usbip_protocol.txt +352 -0
@@ -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.
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]>:
Quoted 356 lines
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_SUBMITandUSBIP_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 withUSB_CMD_SUBMITand then unlinked withUSB_CMD_UNLINKthe completition handler is called only once. In the protocol, however, we have two different type of packets:USB_RET_SUBMITandUSBIP_RET_UNLINK. The status field of these messages may contain anything in this case depending on the timing.Regards,
Márton Németh
---
diff -uprNstaging-2.6.orig/drivers/staging/usbip/usbip_protocol.txtstaging-2.6/drivers/staging/usbip/usbip_protocol.txtdrivers/staging/usbip/usbip_protocol.txt 2011-06-28 08:30:04.000000000 +0200 renamed from drivers/staging/usbip/usbip_protocol.txt 1970-01-01 01:00:00.000000000 +0100 +323
-0@@ -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?
drivers/staging/usbip/usbip_protocol.txt 2011-06-28 08:30:04.000000000 +0200 line 333
Quoted 10 lines
drivers/staging/usbip/usbip_protocol.txt 2011-06-28 08:30:04.000000000 +0200 renamed from drivers/staging/usbip/usbip_protocol.txt 1970-01-01 01:00:00.000000000 +0100 +10
-0+-----------+--------+------------+--------------------------------------------------- + 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.
Quoted 9 lines
drivers/staging/usbip/usbip_protocol.txt 2011-06-28 08:30:04.000000000 +0200 renamed from drivers/staging/usbip/usbip_protocol.txt 1970-01-01 01:00:00.000000000 +0100 +9
-0+ +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 +-----------+--------+------------+---------------------------------------------------
drivers/staging/usbip/usbip_protocol.txt 2011-06-28 08:30:04.000000000 +0200 line 352
Quoted 10 lines
drivers/staging/usbip/usbip_protocol.txt 2011-06-28 08:30:04.000000000 +0200 renamed from drivers/staging/usbip/usbip_protocol.txt 1970-01-01 01:00:00.000000000 +0100 +10
-0+ 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
Quoted 6 lines
_______________________________________________
devel mailing list
[email protected]
http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
Re: [PATCH, RFC] USBIP protocol documentation
Hi Németh,
2011/6/29 David Chang <[email protected]>:
Quoted 21 lines
Hi,
Thanks for your great effort.
Just a little comment on UNLINK pdu size.2011/6/28 Németh Márton <[email protected]>:
Quoted 15 lines
From: Márton Németh <[email protected]>
USBIP v1.0.0 protocol documentation.
Signed-off-by Márton Németh <[email protected]>---
drivers/staging/usbip/usbip_protocol.txt +9
-0+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
Quoted 8 lines
Quoted 8 lines
+-----------+--------+------------+--------------------------------------------------- + 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.
Quoted 11 lines
Quoted 11 lines
drivers/staging/usbip/usbip_protocol.txt +11
-0+ +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 +-----------+--------+------------+---------------------------------------------------
Quoted 8 lines
Quoted 8 lines
+
0xC| 4 | | direction: 0:USBIP_DIR_IN
+ | | | 1:USBIP_DIR_OUT+-----------+--------+------------+--------------------------------------------------- + 0x10 | 4 | | ep: endpoint number +-----------+--------+------------+--------------------------------------------------- + 0x14 | 4 | | status: This is the value contained in the + | | | urb->status in the URB completition handler. + | | | FIXME: a better explanation needed.
-----------+--------+------------+---------------------------------------------------0x30 | n | | URB data bytes. For ISO transfers the padding
| | | between each ISO
packets is not transmitted.
Would you add this field into your path or should I send another patch to add it?
Thanks.
Regards,
David Chang
Quoted 11 lines
Regards,
David ChangQuoted 6 lines
_______________________________________________
devel mailing list
[email protected]
http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
Re: [PATCH, RFC] USBIP protocol documentation
Hi David, Matt Chen and Matt Mooney,
it looks like we four are actively dealing with the USBIP protocol documentation.
David, are you working at the same place like Matt Chen? Then you can easily see what you two has been done and not working parallel on the same thing.
I'm currently not actively modifying the USBIP protocol description.
Matt Mooney wanted to restructure the USBIP protocol documentation. Matt, do you have anything already done? If yes, maybe it would be good if you could send it so David can do the changes on your version. If you haven't worked on it then please tell and David can add the necessary modifications he suggested.
Regards,
Márton Németh
Quoted 7 lines · David Chang
Hi Németh,
2011/6/29 David Chang <[email protected]>:
Quoted 4 lines
Hi,
Thanks for your great effort.
Just a little comment on UNLINK pdu size.
[...]
Quoted 2 lines
Would you add this field into your path or should I send another patch to add it?
Re: [PATCH, RFC] USBIP protocol documentation
Hi Németh,
2011/7/4 Németh Márton <[email protected]>:
Quoted 6 lines
Hi David, Matt Chen and Matt Mooney,
it looks like we four are actively dealing with the USBIP protocol documentation.
David, are you working at the same place like Matt Chen? Then you can easily see what you two has been done and not working parallel on the same thing.
Actually, David and me (Matt Chen) are working on 2 different part.
1. Matt Chen : Server side
2. David Chang : Client side.
Just didn't figure you submitted the protocol document earlier than we do. We also write a wiki for our code reviewing, protocol, but since all we are working personally, something we don't sync, that's why I tried to ask if which part you are not working on or finished, we can work on it.
Since you submitted the document, it turned out we follow the format you've done and do some fix for it.
Quoted 6 lines
I'm currently not actively modifying the USBIP protocol description.
Matt Mooney wanted to restructure the USBIP protocol documentation. Matt, do you have anything already done? If yes, maybe it would be good if you could send it so David can do the changes on your version. If you haven't worked on it then please tell and David can add the necessary modifications he suggested.
I supposed it is Matt Mooney. ~ :)
Quoted 5 lines
Regards,
Márton Németh
David Chang wrote:
Quoted 12 lines
Quoted 7 lines
Hi Németh,
2011/6/29 David Chang <[email protected]>:
Quoted 4 lines
Hi,
Thanks for your great effort.
Just a little comment on UNLINK pdu size.[...]
Quoted 2 lines
Would you add this field into your path or should I send another patch to add it?
--
Thanks ~
Matt Chen
Re: [PATCH, RFC] USBIP protocol documentation
Quoted 9 lines · Matt Chen
Hi N?meth,
2011/7/4 N?meth M?rton <[email protected]>:
Quoted 6 lines
Hi David, Matt Chen and Matt Mooney,
it looks like we four are actively dealing with the USBIP protocol documentation.
David, are you working at the same place like Matt Chen? Then you can easily see what you two has been done and not working parallel on the same thing.
Quoted 8 lines
Actually, David and me (Matt Chen) are working on 2 different part.
1. Matt Chen : Server side
2. David Chang : Client side.
Just didn't figure you submitted the protocol document earlier than we do. We also write a wiki for our code reviewing, protocol, but since all we are working personally, something we don't sync, that's why I tried to ask if which part you are not working on or finished, we can work on it.
Hey guys,
It seems like you guys all have a handle on this, so I will defer. When the documentation is at a point where it can be submitted, I will send in grammar patches along with possible reorganization suggestions.
Is this a public wiki Matt so that you can post a link to it?
Thanks,
mfm
Quoted 33 lines
Since you submitted the document, it turned out we follow the format you've done and do some fix for it.
Quoted 6 lines
I'm currently not actively modifying the USBIP protocol description.
Matt Mooney wanted to restructure the USBIP protocol documentation. Matt, do you have anything already done? If yes, maybe it would be good if you could send it so David can do the changes on your version. If you haven't worked on it then please tell and David can add the necessary modifications he suggested.
I supposed it is Matt Mooney. ~ :)
Quoted 5 lines
Regards,
? ? ? ?M?rton N?meth
David Chang wrote:
Quoted 12 lines
Quoted 7 lines
Hi N?meth,
2011/6/29 David Chang <[email protected]>:
Quoted 4 lines
Hi,
Thanks for your great effort.
Just a little comment on UNLINK pdu size.[...]
Quoted 2 lines
Would you add this field into your path or should I send another patch to add it?
--
Thanks ~
Matt Chen
Re: [PATCH, RFC] USBIP protocol documentation
Hi Matt mooney (just in case of confusing that I am Matt as well),
2011/7/7 matt mooney <[email protected]>:
Quoted 19 lines · Matt Chen
Quoted 9 lines
Hi N?meth,
2011/7/4 N?meth M?rton <[email protected]>:
Quoted 6 lines
Hi David, Matt Chen and Matt Mooney,
it looks like we four are actively dealing with the USBIP protocol documentation.
David, are you working at the same place like Matt Chen? Then you can easily see what you two has been done and not working parallel on the same thing.
Quoted 8 lines
Actually, David and me (Matt Chen) are working on 2 different part.
1. Matt Chen : Server side
2. David Chang : Client side.
Just didn't figure you submitted the protocol document earlier than we do. We also write a wiki for our code reviewing, protocol, but since all we are working personally, something we don't sync, that's why I tried to ask if which part you are not working on or finished, we can work on it.
Quoted 7 lines
Hey guys,
It seems like you guys all have a handle on this, so I will defer. When the documentation is at a point where it can be submitted, I will send in grammar patches along with possible reorganization suggestions.
Is this a public wiki Matt so that you can post a link to it?
Recently we are writing in our internal wiki system. We are intended to change to a external wiki pages, such as open SuSE wiki pages. We are working on it right now.
But it would take time before it's done. ;-)
Thanks in advanced.
Quoted 37 lines
Thanks,
mfmQuoted 33 lines
Since you submitted the document, it turned out we follow the format you've done and do some fix for it.
Quoted 6 lines
I'm currently not actively modifying the USBIP protocol description.
Matt Mooney wanted to restructure the USBIP protocol documentation. Matt, do you have anything already done? If yes, maybe it would be good if you could send it so David can do the changes on your version. If you haven't worked on it then please tell and David can add the necessary modifications he suggested.
I supposed it is Matt Mooney. ~ :)
Quoted 5 lines
Regards,
? ? ? ?M?rton N?meth
David Chang wrote:
Quoted 12 lines
Quoted 7 lines
Hi N?meth,
2011/6/29 David Chang <[email protected]>:
Quoted 4 lines
Hi,
Thanks for your great effort.
Just a little comment on UNLINK pdu size.[...]
Quoted 2 lines
Would you add this field into your path or should I send another patch to add it?
--
Thanks ~
Matt Chen
--
Thanks ~
Matt Chen
Re: [PATCH, RFC] USBIP protocol documentation
Hi all,
The USBIP protocol we maintained is in
you guys may have a look or try to modify them as you like.
2011/7/7 Matt Chen <[email protected]>:
Quoted 75 lines
Hi Matt mooney (just in case of confusing that I am Matt as well),
2011/7/7 matt mooney <[email protected]>:
Quoted 19 lines · Matt Chen
Quoted 9 lines
Hi N?meth,
2011/7/4 N?meth M?rton <[email protected]>:
Quoted 6 lines
Hi David, Matt Chen and Matt Mooney,
it looks like we four are actively dealing with the USBIP protocol documentation.
David, are you working at the same place like Matt Chen? Then you can easily see what you two has been done and not working parallel on the same thing.
Quoted 8 lines
Actually, David and me (Matt Chen) are working on 2 different part.
1. Matt Chen : Server side
2. David Chang : Client side.
Just didn't figure you submitted the protocol document earlier than we do. We also write a wiki for our code reviewing, protocol, but since all we are working personally, something we don't sync, that's why I tried to ask if which part you are not working on or finished, we can work on it.Quoted 7 lines
Hey guys,
It seems like you guys all have a handle on this, so I will defer. When the documentation is at a point where it can be submitted, I will send in grammar patches along with possible reorganization suggestions.
Is this a public wiki Matt so that you can post a link to it?
Recently we are writing in our internal wiki system. We are intended to change to a external wiki pages, such as open SuSE wiki pages. We are working on it right now.
But it would take time before it's done. ;-)Thanks in advanced.
Quoted 37 lines
Thanks,
mfmQuoted 33 lines
Since you submitted the document, it turned out we follow the format you've done and do some fix for it.
Quoted 6 lines
I'm currently not actively modifying the USBIP protocol description.
Matt Mooney wanted to restructure the USBIP protocol documentation. Matt, do you have anything already done? If yes, maybe it would be good if you could send it so David can do the changes on your version. If you haven't worked on it then please tell and David can add the necessary modifications he suggested.
I supposed it is Matt Mooney. ~ :)
Quoted 5 lines
Regards,
? ? ? ?M?rton N?meth
David Chang wrote:
Quoted 12 lines
Quoted 7 lines
Hi N?meth,
2011/6/29 David Chang <[email protected]>:
Quoted 4 lines
Hi,
Thanks for your great effort.
Just a little comment on UNLINK pdu size.[...]
Quoted 2 lines
Would you add this field into your path or should I send another patch to add it?
--
Thanks ~
Matt Chen
Quoted 4 lines
--
Thanks ~
Matt Chen
--
Thanks ~
Matt Chen
Re: [PATCH, RFC] USBIP protocol documentation
In reply to Németh MártonQuoted 10 lines · N??meth M??rton
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
Quoted 375 lines
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_SUBMITandUSBIP_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 withUSB_CMD_SUBMITand then unlinked withUSB_CMD_UNLINKthe completition handler is called only once. In the protocol, however, we have two different type of packets:USB_RET_SUBMITandUSBIP_RET_UNLINK. The status field of these messages may contain anything in this case depending on the timing.Regards,
M??rton N??meth---
diff -uprNstaging-2.6.orig/drivers/staging/usbip/usbip_protocol.txtstaging-2.6/drivers/staging/usbip/usbip_protocol.txtdrivers/staging/usbip/usbip_protocol.txt +352
-0@@ -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.
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH, RFC] USBIP protocol documentation
Quoted 20 lines · Matt Chen
Hi Matt,
2011/6/30 matt mooney <[email protected] <mailto:[email protected]>>:
Quoted 6 lines · N??meth M??rton
Quoted 5 lines
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]>>
Quoted 5 lines
Quoted 5 lines
---
Hi,
I tried to document the USBIP protocol as implemented in the Linux
kernel 3.0-rc2.
Quoted 3 lines
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
Quoted 7 lines
I have a
Quoted 3 lines
few suggestions.
For one, the grammar needs to be cleaned up, but instead of me
pointing out all
Quoted 1 line
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
.
Quoted 43 lines
Quoted 1 line
the finished document. I like that you did a time sequence diagram,
which is
Quoted 1 line
something I had neglected to include myself; however, I am not a big
fan of how
Quoted 1 line
you laid out the messages. I was planning on using packet diagrams.
IMHO, it
Quoted 1 line
makes understanding the message composition much easier allowing more
insight to
Quoted 16 lines
be gathered from a cursory glance.
Message Format
--------------
0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | Opcode |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Status |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. Data .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Quoted 7 lines
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_DEVLISTMessage Format0 1 2
3 4+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0000 0000 1000 0000 | 1000 0000 0000 0101 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- | 0000 0000 0000 0000 0000 0000 0000 0000 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
Quoted 3 lines
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Quoted 595 lines
Quoted 1 line
As you may or may not see, I was going to take a more generic approach
and then
Quoted 1 line
describe the fields on a per-op basis. Of course, the main point here
is that
Quoted 1 line
the protocol is documented, so I am not opposed to a different style
being used.
Quoted 2 lines
But if you insist on the current layout, do not put a value for the
version
Quoted 1 line
because it is not constant (and in fact no longer at 1.0.0). And the
"Meaning"
Quoted 3 lines
header should be "Description" or something better.
Hmm, taking another look the layout just seems to busy... I really do
think we
Quoted 6 lines
should find a different way to format the information.
Thanks,
mattQuoted 1 line
The description is a preliminary draft only, it may contain mistakes.
I tried
Quoted 1 line
Quoted 1 line
to document what I have understand from the source code and from the
actual
Quoted 1 line
Quoted 1 line
captured network traffic when the USBIP is in action. Please review
it, correct it,
Quoted 3 lines
Quoted 3 lines
point out the missing parts.
During I have documented the protocol a question came into my mind:
why do we
Quoted 1 line
Quoted 1 line
have two different type of package when the URB completition handler
is called,
Quoted 1 line
Quoted 1 line
namely
USB_RET_SUBMITandUSBIP_RET_UNLINK? As far as I can see thiscauses race
Quoted 1 line
Quoted 1 line
condition because for one URB the completition handler is only called
once. If
Quoted 1 line
Quoted 1 line
the one URB is sent in with
USB_CMD_SUBMITand then unlinked with
USB_CMD_UNLINKQuoted 1 line
Quoted 1 line
the completition handler is called only once. In the protocol,
however, we have
Quoted 1 line
Quoted 1 line
two different type of packets:
USB_RET_SUBMITandUSBIP_RET_UNLINK.The status
Quoted 1 line
Quoted 1 line
field of these messages may contain anything in this case depending
on the timing.
Quoted 6 lines
Quoted 6 lines
Regards,
M??rton N??meth---
diff -uprNstaging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt
staging-2.6/drivers/staging/usbip/usbip_protocol.txtQuoted 1 line
Quoted 1 line
---
staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt1970-01-01 01:00:00.000000000 +0100Quoted 1 line
Quoted 1 line
+++
staging-2.6/drivers/staging/usbip/usbip_protocol.txt2011-06-28 08:30:04.000000000 +0200Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 4
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0@@ -0,0 +1,352 @@ +PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! +28 Jun 2011 + +The USB/IP protocol follows a server/client architecture. The serverexports the
Quoted 1 line
Review line 5
Quoted 1 line
(quoted diff) +1
-0+USB devices and the clients imports them. The device driver for theexported
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt +3
-0+USB device runs on the client machine. + +The client may ask for the list of the exported USB devices. To getthe list the
Quoted 1 line
Review line 9
Quoted 1 line
(quoted diff) +1
-0+client opens a TCP/IP connection towards the server, and sends an
OP_REQ_DEVLISTQuoted 1 line
Review line 10
Quoted 1 line
(quoted diff) +1
-0+packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLISTmay be sent
Quoted 1 line
Review line 11
Quoted 1 line
(quoted diff) +1
-0+in one or more pieces at the low level transport layer). The serversends back
Quoted 1 line
Review line 12
Quoted 1 line
(quoted diff) +1
-0+the OP_REP_DEVLIST packet which lists the exported USB devices.Finally the
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+TCP/IP connection is closed. + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USBdevices)
Quoted 9 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 9 lines
drivers/staging/usbip/usbip_protocol.txt +9
-0+ | | + | OP_REQ_DEVLIST | + | ----------------------------------------------> | + | | + | OP_REP_DEVLIST | + | <---------------------------------------------- | + | | + +Once the client knows the list of exported USB devices it may decideto use one
Quoted 1 line
Review line 27
Quoted 1 line
(quoted diff) +1
-0+of them. First the client opens a TCP/IP connection towards theserver and
Quoted 1 line
Review line 28
Quoted 1 line
(quoted diff) +1
-0+sends an OP_REQ_IMPORT packet. The server replies with
OP_REP_IMPORT. If theQuoted 1 line
Review line 29
Quoted 1 line
(quoted diff) +1
-0+import was successful the TCP/IP connection remains open and will beused
Quoted 1 line
Review line 30
Quoted 1 line
(quoted diff) +1
-0+to trasfer the URB traffic between the client and the server. Theclient may
Quoted 2 lines
Review line 32
Quoted 2 lines
(quoted diff) +2
-0+send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answersof the
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USBdevices)
Quoted 42 lines
Quoted 42 lines
drivers/staging/usbip/usbip_protocol.txt +42
-0+ | | + | 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) | + | <---------------------------------------------- | + | . | + | : | + | |Quoted 8 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 8 lines
drivers/staging/usbip/usbip_protocol.txt +8
-0+ | USBIP_CMD_UNLINK | + | ----------------------------------------------> | + | | + | USBIP_RET_UNLINK | + | <---------------------------------------------- | + | | + +The fields are in network (big endian) byte order meaning that themost significant
Quoted 7 lines
drivers/staging/usbip/usbip_protocol.txt line 93
Quoted 7 lines
drivers/staging/usbip/usbip_protocol.txt +6
-0+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 USBIPversion number: v1.0.0
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 2 | 2 | 0x8005 | Command code: Retrieve the listof exported USB
Quoted 2 lines
Quoted 2 lines
+ | | | devices.
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 104
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +OP_REP_DEVLIST: Reply with the list of exported USB devices. + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 2 | 0x0100 | Binary-coded decimal USBIPversion number: v1.0.0.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 2 | 2 | 0x0005 | Reply code: The list of exportedUSB devices.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | 0x00000000 | Status: 0 for OKQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | n | Number of exported devices: 0means no exported
Quoted 2 lines
Quoted 2 lines
+ | | | devices.
+-----------+--------+------------+--------------------------------------------------- >> + 0x0C | | | From now on the exported ndevices are described,
Quoted 1 line
Quoted 1 line
+ | | | if any. If no devices are
exported the message
Quoted 1 line
Quoted 1 line
+ | | | ends with the previous "number
of exported
Quoted 2 lines
Quoted 2 lines
+ | | | devices" field.
+-----------+--------+------------+--------------------------------------------------- >> + | 256 | | path: Path of the device on thehost exporting the
Quoted 1 line
Quoted 1 line
+ | | | USB device, string closed with
zero byte, e.g.
Quoted 1 line
Quoted 1 line
+ | | |
"/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
Quoted 1 line
Quoted 1 line
+ | | | The unused bytes shall be
filled with zero
Quoted 2 lines
Quoted 2 lines
+ | | | bytes.
+-----------+--------+------------+--------------------------------------------------- >> + 0x10C | 32 | | busid: Bus ID of the exporteddevice, string
Quoted 1 line
Quoted 1 line
+ | | | closed with zero byte, e.g.
"3-2". The unused
Quoted 1 line
Quoted 1 line
+ | | | bytes shall be filled with zero
bytes.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x12C | 4 | | busnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x130 | 4 | | devnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x134 | 4 | | speedQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x138 | 2 | | idVendorQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13A | 2 | | idProductQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13C | 2 | | bcdDeviceQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13E | 1 | | bDeviceClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13F | 1 | | bDeviceSubClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x140 | 1 | | bDeviceProtocolQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x141 | 1 | | bConfigurationValueQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x142 | 1 | | bNumConfigurationsQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x143 | 1 | | bNumInterfacesQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x144 | | m_0 | From now on each interface isdescribed, all
Quoted 1 line
Quoted 1 line
+ | | | together bNumInterfaces times,
with the
Quoted 2 lines
Quoted 2 lines
+ | | | the following 4 fields:
+-----------+--------+------------+--------------------------------------------------- >> + | 1 | | bInterfaceClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x145 | 1 | | bInterfaceSubClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x146 | 1 | | bInterfaceProtocolQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x147 | 1 | | padding byte for alignment, shallbe set to zero
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC + | | | The second exported USB devicestarts at i=1
Quoted 7 lines
drivers/staging/usbip/usbip_protocol.txt line 172
Quoted 7 lines
+ i*0x138 + | | | with the busid field. + m_(i-1)*4 | | |drivers/staging/usbip/usbip_protocol.txt +4
-0+ +OP_REQ_IMPORT: Request to import (attach) a remote USB device. + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 2 | 0x0100 | Binary-coded decimal USBIPversion number: v1.0.0
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 2 | 2 | 0x8003 | Command code: import a remote USBdevice.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 32 | | busid: the busid of the exporteddevice on the
Quoted 1 line
Quoted 1 line
+ | | | remote host. The possible
values are taken
Quoted 1 line
Quoted 1 line
+ | | | from the message field
OP_REP_DEVLIST.busid.
Quoted 1 line
Quoted 1 line
+ | | | A string closed with zero, the
unused bytes
Quoted 2 lines
Quoted 2 lines
+ | | | shall be filled with zeros.
+-----------+--------+------------+---------------------------------------------------
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 189
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +OP_REP_IMPORT: Reply to import (attach) a remote USB device. + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 2 | 0x0100 | Binary-coded decimal USBIPversion number: v1.0.0
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 2 | 2 | 0x0003 | Reply code: Reply to import.Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | 0x00000000 | Status: 0 for OK >> + | | | 1 for errorQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | | | From now on comes the details ofthe imported
Quoted 1 line
Quoted 1 line
+ | | | device, if the previous status
field was OK (0),
Quoted 1 line
Quoted 1 line
+ | | | otherwise the reply ends with
the status field.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + | 256 | | path: Path of the device on thehost exporting the
Quoted 1 line
Quoted 1 line
+ | | | USB device, string closed with
zero byte, e.g.
Quoted 1 line
Quoted 1 line
+ | | |
"/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
Quoted 1 line
Quoted 1 line
+ | | | The unused bytes shall be
filled with zero
Quoted 2 lines
Quoted 2 lines
+ | | | bytes.
+-----------+--------+------------+--------------------------------------------------- >> + 0x108 | 32 | | busid: Bus ID of the exporteddevice, string
Quoted 1 line
Quoted 1 line
+ | | | closed with zero byte, e.g.
"3-2". The unused
Quoted 1 line
Quoted 1 line
+ | | | bytes shall be filled with zero
bytes.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x128 | 4 | | busnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x12C | 4 | | devnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x130 | 4 | | speedQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x134 | 2 | | idVendorQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x136 | 2 | | idProductQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x138 | 2 | | bcdDeviceQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x139 | 1 | | bDeviceClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13A | 1 | | bDeviceSubClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13B | 1 | | bDeviceProtocolQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13C | 1 | | bConfigurationValueQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13D | 1 | | bNumConfigurationsQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13E | 1 | | bNumInterfacesQuoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 238
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +USBIP_CMD_SUBMIT: Submit an URB + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 4 | 0x00000001 | command: Submit an URBQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: the sequence number ofthe URB to submit
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint number, possiblevalues are: 0...15
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | transfer_flags: possible valuesdepend on the
Quoted 2 lines
Quoted 2 lines
+ | | | URB transfer type, see below
+-----------+--------+------------+--------------------------------------------------- >> + 0x18 | 4 | | transfer_buffer_lengthQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x1C | 4 | | start_frame: specify the selectedframe to
Quoted 1 line
Quoted 1 line
+ | | | transmit an ISO frame, ignored
if
URB_ISO_ASAPQuoted 2 lines
Quoted 2 lines
+ | | | is specified at
transfer_flags+-----------+--------+------------+--------------------------------------------------- >> + 0x20 | 4 | | number_of_packets: number of ISOpackets
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x24 | 4 | | interval: maximum time for therequest on the
Quoted 2 lines
Quoted 2 lines
+ | | | server-side host controller
+-----------+--------+------------+--------------------------------------------------- >> + 0x28 | 8 | | setup: data bytes for USB setup,filled with
Quoted 2 lines
Quoted 2 lines
+ | | | zeros if not used
+-----------+--------+------------+--------------------------------------------------- >> + 0x30 | | | URB data. For ISO transfers thepadding between
Quoted 1 line
Quoted 1 line
+ | | | each ISO packets is not
transmitted.
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt +3
-0+ + + Allowed transfer_flags | value | control | interrupt | bulk| isochronous
Quoted 1 line
Quoted 1 line
+
-------------------------+------------+---------+-----------+----------+-------------
Quoted 1 line
Quoted 1 line
+
URB_SHORT_NOT_OK|0x00000001| only in | only in | onlyin | no
Quoted 1 line
Quoted 1 line
+
URB_ISO_ASAP|0x00000002| no | no | no| yes
Quoted 1 line
Quoted 1 line
+
URB_NO_TRANSFER_DMA_MAP|0x00000004| yes | yes | yes| yes
Quoted 1 line
Quoted 1 line
+
URB_NO_FSBR|0x00000020| yes | no | no| no
Quoted 1 line
Quoted 1 line
+
URB_ZERO_PACKET|0x00000040| no | no | onlyout | no
Quoted 1 line
Quoted 1 line
+
URB_NO_INTERRUPT|0x00000080| yes | yes | yes| yes
Quoted 1 line
Quoted 1 line
+
URB_FREE_BUFFER|0x00000100| yes | yes | yes| yes
Quoted 1 line
Quoted 1 line
+
URB_DIR_MASK|0x00000200| yes | yes | yes| yes
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt line 286
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+ + +USBIP_RET_SUBMIT: Reply for submitting an URB + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 4 | 0x00000002 | commandQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: URB sequence numberQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint numberQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | status: zero for successful URBtransaction,
Quoted 1 line
Quoted 1 line
+ | | | otherwise some kind of error
happened.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x18 | 4 | n | actual_length: number of URB databytes
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x1C | 4 | | start_frame: for an ISO frame theactually
Quoted 2 lines
Quoted 2 lines
+ | | | selected frame for transmit.
+-----------+--------+------------+--------------------------------------------------- >> + 0x20 | 4 | | number_of_packetsQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x24 | 4 | | error_countQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x28 | 8 | | setup: data bytes for USB setup,filled with
Quoted 2 lines
Quoted 2 lines
+ | | | zeros if not used
+-----------+--------+------------+--------------------------------------------------- >> + 0x30 | n | | URB data bytes. For ISO transfersthe padding
Quoted 1 line
Quoted 1 line
+ | | | between each ISO packets is not
transmitted.
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 319
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +USBIP_CMD_UNLINK: Unlink an URB + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 4 | 0x00000003 | command: URB unlink commandQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: URB sequence number tounlink: FIXME: is this so?
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint number: zeroQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | seqnum: the URB sequence numbergiven previously
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt line 337
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+ | | | 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 unlinkcommand
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: the unlinked URB sequencenumber
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint numberQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | status: This is the valuecontained in the
Quoted 1 line
Quoted 1 line
+ | | |
urb->statusin the URBcompletition handler.
Quoted 7 lines
Quoted 2 lines
+ | | | FIXME: a better explanation needed.
_______________________________________________
devel mailing list
[email protected] <mailto:[email protected]>
http://driverdev.linuxdriverproject.org/mailman/listinfo/develSignature · 2 lines
Thanks ~ Matt Chen
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]>
Quoted 105 lines
Quoted 20 lines · Matt Chen
Hi Matt,
2011/6/30 matt mooney <[email protected] <mailto:[email protected]>>:
Quoted 6 lines · N??meth M??rton
Quoted 5 lines
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]>>
Quoted 5 lines
Quoted 5 lines
---
Hi,
I tried to document the USBIP protocol as implemented in the Linux
kernel 3.0-rc2.
Quoted 3 lines
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
Quoted 7 lines
I have a
Quoted 3 lines
few suggestions.
For one, the grammar needs to be cleaned up, but instead of me
pointing out all
Quoted 1 line
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
.Quoted 43 lines
Quoted 1 line
the finished document. I like that you did a time sequence diagram,
which is
Quoted 1 line
something I had neglected to include myself; however, I am not a big
fan of how
Quoted 1 line
you laid out the messages. I was planning on using packet diagrams.
IMHO, it
Quoted 1 line
makes understanding the message composition much easier allowing more
insight to
Quoted 16 lines
be gathered from a cursory glance.
Message Format
--------------
0 1 2 3+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Version | Opcode | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Status | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+. . . Data . . .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Quoted 7 lines
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_DEVLISTMessage Format0 1 2
3 4+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0000 0000 1000 0000 | 1000 0000 0000 0101 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- | 0000 0000 0000 0000 0000 0000 0000 0000 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-Quoted 3 lines
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
Quoted 603 lines
0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x0100 | 0x8005 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x00000000 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Quoted 595 lines
Quoted 1 line
As you may or may not see, I was going to take a more generic approach
and then
Quoted 1 line
describe the fields on a per-op basis. Of course, the main point here
is that
Quoted 1 line
the protocol is documented, so I am not opposed to a different style
being used.
Quoted 2 lines
But if you insist on the current layout, do not put a value for the
version
Quoted 1 line
because it is not constant (and in fact no longer at 1.0.0). And the
"Meaning"
Quoted 3 lines
header should be "Description" or something better.
Hmm, taking another look the layout just seems to busy... I really do
think we
Quoted 6 lines
should find a different way to format the information.
Thanks,
mattQuoted 1 line
The description is a preliminary draft only, it may contain mistakes.
I tried
Quoted 1 line
Quoted 1 line
to document what I have understand from the source code and from the
actual
Quoted 1 line
Quoted 1 line
captured network traffic when the USBIP is in action. Please review
it, correct it,
Quoted 3 lines
Quoted 3 lines
point out the missing parts.
During I have documented the protocol a question came into my mind:
why do we
Quoted 1 line
Quoted 1 line
have two different type of package when the URB completition handler
is called,
Quoted 1 line
Quoted 1 line
namely
USB_RET_SUBMITandUSBIP_RET_UNLINK? As far as I can see thiscauses race
Quoted 1 line
Quoted 1 line
condition because for one URB the completition handler is only called
once. If
Quoted 1 line
Quoted 1 line
the one URB is sent in with
USB_CMD_SUBMITand then unlinked with
USB_CMD_UNLINKQuoted 1 line
Quoted 1 line
the completition handler is called only once. In the protocol,
however, we have
Quoted 1 line
Quoted 1 line
two different type of packets:
USB_RET_SUBMITandUSBIP_RET_UNLINK.The status
Quoted 1 line
Quoted 1 line
field of these messages may contain anything in this case depending
on the timing.
Quoted 6 lines
Quoted 6 lines
Regards,
M??rton N??meth
---
diff -uprNstaging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt
staging-2.6/drivers/staging/usbip/usbip_protocol.txtQuoted 1 line
Quoted 1 line
---
staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt1970-01-01 01:00:00.000000000 +0100Quoted 1 line
Quoted 1 line
+++
staging-2.6/drivers/staging/usbip/usbip_protocol.txt2011-06-28 08:30:04.000000000 +0200Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 4
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0@@ -0,0 +1,352 @@ +PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! +28 Jun 2011 + +The USB/IP protocol follows a server/client architecture. The serverexports the
Quoted 1 line
Review line 5
Quoted 1 line
(quoted diff) +1
-0+USB devices and the clients imports them. The device driver for theexported
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt +3
-0+USB device runs on the client machine. + +The client may ask for the list of the exported USB devices. To getthe list the
Quoted 1 line
Review line 9
Quoted 1 line
(quoted diff) +1
-0+client opens a TCP/IP connection towards the server, and sends an
OP_REQ_DEVLISTQuoted 1 line
Review line 10
Quoted 1 line
(quoted diff) +1
-0+packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLISTmay be sent
Quoted 1 line
Review line 11
Quoted 1 line
(quoted diff) +1
-0+in one or more pieces at the low level transport layer). The serversends back
Quoted 1 line
Review line 12
Quoted 1 line
(quoted diff) +1
-0+the OP_REP_DEVLIST packet which lists the exported USB devices.Finally the
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+TCP/IP connection is closed. + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USBdevices)
Quoted 9 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 9 lines
drivers/staging/usbip/usbip_protocol.txt +9
-0+ | | + | OP_REQ_DEVLIST | + | ----------------------------------------------> | + | | + | OP_REP_DEVLIST | + | <---------------------------------------------- | + | | + +Once the client knows the list of exported USB devices it may decideto use one
Quoted 1 line
Review line 27
Quoted 1 line
(quoted diff) +1
-0+of them. First the client opens a TCP/IP connection towards theserver and
Quoted 1 line
Review line 28
Quoted 1 line
(quoted diff) +1
-0+sends an OP_REQ_IMPORT packet. The server replies with
OP_REP_IMPORT. If theQuoted 1 line
Review line 29
Quoted 1 line
(quoted diff) +1
-0+import was successful the TCP/IP connection remains open and will beused
Quoted 1 line
Review line 30
Quoted 1 line
(quoted diff) +1
-0+to trasfer the URB traffic between the client and the server. Theclient may
Quoted 2 lines
Review line 32
Quoted 2 lines
(quoted diff) +2
-0+send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answersof the
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USBdevices)
Quoted 42 lines
Quoted 42 lines
drivers/staging/usbip/usbip_protocol.txt +42
-0+ | | + | 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) | + | <---------------------------------------------- | + | . | + | : | + | |Quoted 8 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 8 lines
drivers/staging/usbip/usbip_protocol.txt +8
-0+ | USBIP_CMD_UNLINK | + | ----------------------------------------------> | + | | + | USBIP_RET_UNLINK | + | <---------------------------------------------- | + | | + +The fields are in network (big endian) byte order meaning that themost significant
Quoted 7 lines
drivers/staging/usbip/usbip_protocol.txt line 93
Quoted 7 lines
drivers/staging/usbip/usbip_protocol.txt +6
-0+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 USBIPversion number: v1.0.0
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 2 | 2 | 0x8005 | Command code: Retrieve the listof exported USB
Quoted 2 lines
Quoted 2 lines
+ | | | devices.
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 104
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +OP_REP_DEVLIST: Reply with the list of exported USB devices. + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 2 | 0x0100 | Binary-coded decimal USBIPversion number: v1.0.0.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 2 | 2 | 0x0005 | Reply code: The list of exportedUSB devices.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | 0x00000000 | Status: 0 for OKQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | n | Number of exported devices: 0means no exported
Quoted 2 lines
Quoted 2 lines
+ | | | devices.
+-----------+--------+------------+--------------------------------------------------- >> + 0x0C | | | From now on the exported ndevices are described,
Quoted 1 line
Quoted 1 line
+ | | | if any. If no devices are
exported the message
Quoted 1 line
Quoted 1 line
+ | | | ends with the previous "number
of exported
Quoted 2 lines
Quoted 2 lines
+ | | | devices" field.
+-----------+--------+------------+--------------------------------------------------- >> + | 256 | | path: Path of the device on thehost exporting the
Quoted 1 line
Quoted 1 line
+ | | | USB device, string closed with
zero byte, e.g.
Quoted 1 line
Quoted 1 line
+ | | |
"/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
Quoted 1 line
Quoted 1 line
+ | | | The unused bytes shall be
filled with zero
Quoted 2 lines
Quoted 2 lines
+ | | | bytes.
+-----------+--------+------------+--------------------------------------------------- >> + 0x10C | 32 | | busid: Bus ID of the exporteddevice, string
Quoted 1 line
Quoted 1 line
+ | | | closed with zero byte, e.g.
"3-2". The unused
Quoted 1 line
Quoted 1 line
+ | | | bytes shall be filled with zero
bytes.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x12C | 4 | | busnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x130 | 4 | | devnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x134 | 4 | | speedQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x138 | 2 | | idVendorQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13A | 2 | | idProductQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13C | 2 | | bcdDeviceQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13E | 1 | | bDeviceClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13F | 1 | | bDeviceSubClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x140 | 1 | | bDeviceProtocolQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x141 | 1 | | bConfigurationValueQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x142 | 1 | | bNumConfigurationsQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x143 | 1 | | bNumInterfacesQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x144 | | m_0 | From now on each interface isdescribed, all
Quoted 1 line
Quoted 1 line
+ | | | together bNumInterfaces times,
with the
Quoted 2 lines
Quoted 2 lines
+ | | | the following 4 fields:
+-----------+--------+------------+--------------------------------------------------- >> + | 1 | | bInterfaceClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x145 | 1 | | bInterfaceSubClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x146 | 1 | | bInterfaceProtocolQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x147 | 1 | | padding byte for alignment, shallbe set to zero
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC + | | | The second exported USB devicestarts at i=1
Quoted 7 lines
drivers/staging/usbip/usbip_protocol.txt line 172
Quoted 7 lines
+ i*0x138 + | | | with the busid field. + m_(i-1)*4 | | |drivers/staging/usbip/usbip_protocol.txt +4
-0+ +OP_REQ_IMPORT: Request to import (attach) a remote USB device. + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 2 | 0x0100 | Binary-coded decimal USBIPversion number: v1.0.0
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 2 | 2 | 0x8003 | Command code: import a remote USBdevice.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 32 | | busid: the busid of the exporteddevice on the
Quoted 1 line
Quoted 1 line
+ | | | remote host. The possible
values are taken
Quoted 1 line
Quoted 1 line
+ | | | from the message field
OP_REP_DEVLIST.busid.
Quoted 1 line
Quoted 1 line
+ | | | A string closed with zero, the
unused bytes
Quoted 2 lines
Quoted 2 lines
+ | | | shall be filled with zeros.
+-----------+--------+------------+---------------------------------------------------
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 189
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +OP_REP_IMPORT: Reply to import (attach) a remote USB device. + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 2 | 0x0100 | Binary-coded decimal USBIPversion number: v1.0.0
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 2 | 2 | 0x0003 | Reply code: Reply to import.Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | 0x00000000 | Status: 0 for OK >> + | | | 1 for errorQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | | | From now on comes the details ofthe imported
Quoted 1 line
Quoted 1 line
+ | | | device, if the previous status
field was OK (0),
Quoted 1 line
Quoted 1 line
+ | | | otherwise the reply ends with
the status field.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + | 256 | | path: Path of the device on thehost exporting the
Quoted 1 line
Quoted 1 line
+ | | | USB device, string closed with
zero byte, e.g.
Quoted 1 line
Quoted 1 line
+ | | |
"/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
Quoted 1 line
Quoted 1 line
+ | | | The unused bytes shall be
filled with zero
Quoted 2 lines
Quoted 2 lines
+ | | | bytes.
+-----------+--------+------------+--------------------------------------------------- >> + 0x108 | 32 | | busid: Bus ID of the exporteddevice, string
Quoted 1 line
Quoted 1 line
+ | | | closed with zero byte, e.g.
"3-2". The unused
Quoted 1 line
Quoted 1 line
+ | | | bytes shall be filled with zero
bytes.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x128 | 4 | | busnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x12C | 4 | | devnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x130 | 4 | | speedQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x134 | 2 | | idVendorQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x136 | 2 | | idProductQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x138 | 2 | | bcdDeviceQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x139 | 1 | | bDeviceClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13A | 1 | | bDeviceSubClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13B | 1 | | bDeviceProtocolQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13C | 1 | | bConfigurationValueQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13D | 1 | | bNumConfigurationsQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13E | 1 | | bNumInterfacesQuoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 238
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +USBIP_CMD_SUBMIT: Submit an URB + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 4 | 0x00000001 | command: Submit an URBQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: the sequence number ofthe URB to submit
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint number, possiblevalues are: 0...15
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | transfer_flags: possible valuesdepend on the
Quoted 2 lines
Quoted 2 lines
+ | | | URB transfer type, see below
+-----------+--------+------------+--------------------------------------------------- >> + 0x18 | 4 | | transfer_buffer_lengthQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x1C | 4 | | start_frame: specify the selectedframe to
Quoted 1 line
Quoted 1 line
+ | | | transmit an ISO frame, ignored
if
URB_ISO_ASAPQuoted 2 lines
Quoted 2 lines
+ | | | is specified at
transfer_flags+-----------+--------+------------+--------------------------------------------------- >> + 0x20 | 4 | | number_of_packets: number of ISOpackets
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x24 | 4 | | interval: maximum time for therequest on the
Quoted 2 lines
Quoted 2 lines
+ | | | server-side host controller
+-----------+--------+------------+--------------------------------------------------- >> + 0x28 | 8 | | setup: data bytes for USB setup,filled with
Quoted 2 lines
Quoted 2 lines
+ | | | zeros if not used
+-----------+--------+------------+--------------------------------------------------- >> + 0x30 | | | URB data. For ISO transfers thepadding between
Quoted 1 line
Quoted 1 line
+ | | | each ISO packets is not
transmitted.
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt +3
-0+ + + Allowed transfer_flags | value | control | interrupt | bulk| isochronous
Quoted 1 line
Quoted 1 line
+
-------------------------+------------+---------+-----------+----------+-------------
Quoted 1 line
Quoted 1 line
+ URB_SHORT_NOT_OK |
0x00000001| only in | only in | onlyin | no
Quoted 1 line
Quoted 1 line
+ URB_ISO_ASAP |
0x00000002| no | no | no| yes
Quoted 1 line
Quoted 1 line
+ URB_NO_TRANSFER_DMA_MAP |
0x00000004| yes | yes | yes| yes
Quoted 1 line
Quoted 1 line
+ URB_NO_FSBR |
0x00000020| yes | no | no| no
Quoted 1 line
Quoted 1 line
+ URB_ZERO_PACKET |
0x00000040| no | no | onlyout | no
Quoted 1 line
Quoted 1 line
+ URB_NO_INTERRUPT |
0x00000080| yes | yes | yes| yes
Quoted 1 line
Quoted 1 line
+ URB_FREE_BUFFER |
0x00000100| yes | yes | yes| yes
Quoted 1 line
Quoted 1 line
+ URB_DIR_MASK |
0x00000200| yes | yes | yes| yes
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt line 286
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+ + +USBIP_RET_SUBMIT: Reply for submitting an URB + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 4 | 0x00000002 | commandQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: URB sequence numberQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint numberQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | status: zero for successful URBtransaction,
Quoted 1 line
Quoted 1 line
+ | | | otherwise some kind of error
happened.
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x18 | 4 | n | actual_length: number of URB databytes
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x1C | 4 | | start_frame: for an ISO frame theactually
Quoted 2 lines
Quoted 2 lines
+ | | | selected frame for transmit.
+-----------+--------+------------+--------------------------------------------------- >> + 0x20 | 4 | | number_of_packetsQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x24 | 4 | | error_countQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x28 | 8 | | setup: data bytes for USB setup,filled with
Quoted 2 lines
Quoted 2 lines
+ | | | zeros if not used
+-----------+--------+------------+--------------------------------------------------- >> + 0x30 | n | | URB data bytes. For ISO transfersthe padding
Quoted 1 line
Quoted 1 line
+ | | | between each ISO packets is not
transmitted.
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 319
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +USBIP_CMD_UNLINK: Unlink an URB + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 4 | 0x00000003 | command: URB unlink commandQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: URB sequence number tounlink: FIXME: is this so?
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint number: zeroQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | seqnum: the URB sequence numbergiven previously
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt line 337
Quoted 6 lines
+ | | | at USBIP_CMD_SUBMIT.seqnum field
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +USBIP_RET_UNLINK: Reply for URB unlink + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 4 | 0x00000004 | command: reply for the URB unlinkcommand
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: the unlinked URB sequencenumber
Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint numberQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | status: This is the valuecontained in the
Quoted 1 line
Quoted 1 line
+ | | |
urb->statusin the URBcompletition handler.
Quoted 7 lines
Quoted 2 lines
+ | | | 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
Re: [PATCH, RFC] USBIP protocol documentation
Quoted 4 lines · Matt Chen
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.
Quoted 695 lines
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]>
Quoted 101 lines
Quoted 19 lines · Matt Chen
Hi Matt,
2011/6/30 matt mooney <[email protected] <mailto:[email protected]>>:
Quoted 6 lines · N??meth M??rton
Quoted 5 lines
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]>>
Quoted 5 lines
Quoted 5 lines
---
Hi,
I tried to document the USBIP protocol as implemented in the Linux
kernel 3.0-rc2.
Quoted 2 lines
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
Quoted 7 lines
I have a
Quoted 3 lines
few suggestions.
For one, the grammar needs to be cleaned up, but instead of me
pointing out all
Quoted 1 line
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
.Quoted 43 lines
Quoted 1 line
the finished document. I like that you did a time sequence diagram,
which is
Quoted 1 line
something I had neglected to include myself; however, I am not a big
fan of how
Quoted 1 line
you laid out the messages. I was planning on using packet diagrams.
IMHO, it
Quoted 1 line
makes understanding the message composition much easier allowing more
insight to
Quoted 16 lines
be gathered from a cursory glance.
Message Format
--------------
0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | Opcode |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Status |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. Data .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Quoted 7 lines
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_DEVLISTMessage Format0 1 2
3 4+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0000 0000 1000 0000 | 1000 0000 0000 0101 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- | 0000 0000 0000 0000 0000 0000 0000 0000 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-Quoted 3 lines
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_DEVLISTMessage FormatQuoted 581 lines
0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x0100 | 0x8005 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x00000000 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Quoted 574 lines
Quoted 1 line
As you may or may not see, I was going to take a more generic approach
and then
Quoted 1 line
describe the fields on a per-op basis. Of course, the main point here
is that
Quoted 1 line
the protocol is documented, so I am not opposed to a different style
being used.
Quoted 1 line
But if you insist on the current layout, do not put a value for the
version
Quoted 1 line
because it is not constant (and in fact no longer at 1.0.0). And the
"Meaning"
Quoted 3 lines
header should be "Description" or something better.
Hmm, taking another look the layout just seems to busy... I really do
think we
Quoted 6 lines
should find a different way to format the information.
Thanks,
mattQuoted 1 line
The description is a preliminary draft only, it may contain mistakes.
I tried
Quoted 1 line
Quoted 1 line
to document what I have understand from the source code and from the
actual
Quoted 1 line
Quoted 1 line
captured network traffic when the USBIP is in action. Please review
it, correct it,
Quoted 3 lines
Quoted 3 lines
point out the missing parts.
During I have documented the protocol a question came into my mind:
why do we
Quoted 1 line
Quoted 1 line
have two different type of package when the URB completition handler
is called,
Quoted 1 line
Quoted 1 line
namely
USB_RET_SUBMITandUSBIP_RET_UNLINK? As far as I can see thiscauses race
Quoted 1 line
Quoted 1 line
condition because for one URB the completition handler is only called
once. If
Quoted 1 line
Quoted 1 line
the one URB is sent in with
USB_CMD_SUBMITand then unlinked with
USB_CMD_UNLINKQuoted 1 line
Quoted 1 line
the completition handler is called only once. In the protocol,
however, we have
Quoted 1 line
Quoted 1 line
two different type of packets:
USB_RET_SUBMITandUSBIP_RET_UNLINK.The status
Quoted 1 line
Quoted 1 line
field of these messages may contain anything in this case depending
on the timing.
Quoted 5 lines
Quoted 5 lines
Regards,
M??rton N??meth---
diff -uprNstaging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt
staging-2.6/drivers/staging/usbip/usbip_protocol.txtQuoted 1 line
Quoted 1 line
---
staging-2.6.orig/drivers/staging/usbip/usbip_protocol.txt1970-01-01 01:00:00.000000000 +0100Quoted 1 line
Quoted 1 line
+++
staging-2.6/drivers/staging/usbip/usbip_protocol.txt2011-06-28 08:30:04.000000000 +0200Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 4
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0@@ -0,0 +1,352 @@ +PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! +28 Jun 2011 + +The USB/IP protocol follows a server/client architecture. The serverexports the
Quoted 1 line
Review line 5
Quoted 1 line
(quoted diff) +1
-0+USB devices and the clients imports them. The device driver for theexported
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt +3
-0+USB device runs on the client machine. + +The client may ask for the list of the exported USB devices. To getthe list the
Quoted 1 line
Review line 9
Quoted 1 line
(quoted diff) +1
-0+client opens a TCP/IP connection towards the server, and sends an
OP_REQ_DEVLISTQuoted 1 line
Review line 10
Quoted 1 line
(quoted diff) +1
-0+packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLISTmay be sent
Quoted 1 line
Review line 11
Quoted 1 line
(quoted diff) +1
-0+in one or more pieces at the low level transport layer). The serversends back
Quoted 1 line
Review line 12
Quoted 1 line
(quoted diff) +1
-0+the OP_REP_DEVLIST packet which lists the exported USB devices.Finally the
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+TCP/IP connection is closed. + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USBdevices)
Quoted 9 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 9 lines
drivers/staging/usbip/usbip_protocol.txt +9
-0+ | | + | OP_REQ_DEVLIST | + | ----------------------------------------------> | + | | + | OP_REP_DEVLIST | + | <---------------------------------------------- | + | | + +Once the client knows the list of exported USB devices it may decideto use one
Quoted 1 line
Review line 27
Quoted 1 line
(quoted diff) +1
-0+of them. First the client opens a TCP/IP connection towards theserver and
Quoted 1 line
Review line 28
Quoted 1 line
(quoted diff) +1
-0+sends an OP_REQ_IMPORT packet. The server replies with
OP_REP_IMPORT. If theQuoted 1 line
Review line 29
Quoted 1 line
(quoted diff) +1
-0+import was successful the TCP/IP connection remains open and will beused
Quoted 1 line
Review line 30
Quoted 1 line
(quoted diff) +1
-0+to trasfer the URB traffic between the client and the server. Theclient may
Quoted 2 lines
Review line 32
Quoted 2 lines
(quoted diff) +2
-0+send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answersof the
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USBdevices)
Quoted 42 lines
Quoted 42 lines
drivers/staging/usbip/usbip_protocol.txt +42
-0+ | | + | 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) | + | <---------------------------------------------- | + | . | + | : | + | |Quoted 8 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 8 lines
drivers/staging/usbip/usbip_protocol.txt +8
-0+ | USBIP_CMD_UNLINK | + | ----------------------------------------------> | + | | + | USBIP_RET_UNLINK | + | <---------------------------------------------- | + | | + +The fields are in network (big endian) byte order meaning that themost significant
Quoted 7 lines
drivers/staging/usbip/usbip_protocol.txt line 93
Quoted 7 lines
drivers/staging/usbip/usbip_protocol.txt +6
-0+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 listof exported USB
Quoted 2 lines
Review line 94
Quoted 2 lines
(quoted diff) +1
-0+ | | | devices.+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 104
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-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 OKQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | n | Number of exported devices: 0means no exported
Quoted 2 lines
Quoted 2 lines
+ | | | devices.
+-----------+--------+------------+--------------------------------------------------- >> + 0x0C | | | From now on the exported ndevices are described,
Quoted 1 line
Quoted 1 line
+ | | | if any. If no devices are
exported the message
Quoted 1 line
Quoted 1 line
+ | | | ends with the previous "number
of exported
Quoted 2 lines
Quoted 2 lines
+ | | | devices" field.
+-----------+--------+------------+--------------------------------------------------- >> + | 256 | | path: Path of the device on thehost exporting the
Quoted 1 line
Quoted 1 line
+ | | | USB device, string closed with
zero byte, e.g.
Quoted 1 line
Quoted 1 line
+ | | |
"/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
Quoted 1 line
Quoted 1 line
+ | | | The unused bytes shall be
filled with zero
Quoted 2 lines
Quoted 2 lines
+ | | | bytes.
+-----------+--------+------------+--------------------------------------------------- >> + 0x10C | 32 | | busid: Bus ID of the exporteddevice, string
Quoted 1 line
Quoted 1 line
+ | | | closed with zero byte, e.g.
"3-2". The unused
Quoted 1 line
Quoted 1 line
+ | | | bytes shall be filled with zero
bytes.
+-----------+--------+------------+--------------------------------------------------- >> + 0x12C | 4 | | busnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x130 | 4 | | devnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x134 | 4 | | speedQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x138 | 2 | | idVendorQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13A | 2 | | idProductQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13C | 2 | | bcdDeviceQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13E | 1 | | bDeviceClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13F | 1 | | bDeviceSubClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x140 | 1 | | bDeviceProtocolQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x141 | 1 | | bConfigurationValueQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x142 | 1 | | bNumConfigurationsQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x143 | 1 | | bNumInterfacesQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x144 | | m_0 | From now on each interface isdescribed, all
Quoted 1 line
Quoted 1 line
+ | | | together bNumInterfaces times,
with the
Quoted 2 lines
Quoted 2 lines
+ | | | the following 4 fields:
+-----------+--------+------------+--------------------------------------------------- >> + | 1 | | bInterfaceClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x145 | 1 | | bInterfaceSubClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x146 | 1 | | bInterfaceProtocolQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x147 | 1 | | padding byte for alignment, shall be set to zero +-----------+--------+------------+--------------------------------------------------- >> + 0xC + | | | The second exported USB devicestarts at i=1
Quoted 7 lines
drivers/staging/usbip/usbip_protocol.txt line 172
Quoted 7 lines
+ i*0x138 + | | | with the busid field. + m_(i-1)*4 | | |drivers/staging/usbip/usbip_protocol.txt +4
-0+ +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 0Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 32 | | busid: the busid of the exporteddevice on the
Quoted 1 line
Quoted 1 line
+ | | | remote host. The possible
values are taken
Quoted 1 line
Quoted 1 line
+ | | | from the message field
OP_REP_DEVLIST.busid.
Quoted 1 line
Quoted 1 line
+ | | | A string closed with zero, the
unused bytes
Quoted 2 lines
Quoted 2 lines
+ | | | shall be filled with zeros.
+-----------+--------+------------+---------------------------------------------------
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 189
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +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.Quoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | 0x00000000 | Status: 0 for OK >> + | | | 1 for errorQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | | | From now on comes the details ofthe imported
Quoted 1 line
Quoted 1 line
+ | | | device, if the previous status
field was OK (0),
Quoted 1 line
Quoted 1 line
+ | | | otherwise the reply ends with
the status field.
+-----------+--------+------------+--------------------------------------------------- >> + | 256 | | path: Path of the device on thehost exporting the
Quoted 1 line
Quoted 1 line
+ | | | USB device, string closed with
zero byte, e.g.
Quoted 1 line
Quoted 1 line
+ | | |
"/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
Quoted 1 line
Quoted 1 line
+ | | | The unused bytes shall be
filled with zero
Quoted 2 lines
Quoted 2 lines
+ | | | bytes.
+-----------+--------+------------+--------------------------------------------------- >> + 0x108 | 32 | | busid: Bus ID of the exporteddevice, string
Quoted 1 line
Quoted 1 line
+ | | | closed with zero byte, e.g.
"3-2". The unused
Quoted 1 line
Quoted 1 line
+ | | | bytes shall be filled with zero
bytes.
+-----------+--------+------------+--------------------------------------------------- >> + 0x128 | 4 | | busnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x12C | 4 | | devnumQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x130 | 4 | | speedQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x134 | 2 | | idVendorQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x136 | 2 | | idProductQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x138 | 2 | | bcdDeviceQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x139 | 1 | | bDeviceClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13A | 1 | | bDeviceSubClassQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13B | 1 | | bDeviceProtocolQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13C | 1 | | bConfigurationValueQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13D | 1 | | bNumConfigurationsQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x13E | 1 | | bNumInterfacesQuoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 238
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +USBIP_CMD_SUBMIT: Submit an URB + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 4 | 0x00000001 | command: Submit an URBQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: the sequence number of the URB to submit +-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint number, possible values are: 0...15 +-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | transfer_flags: possible valuesdepend on the
Quoted 2 lines
Quoted 2 lines
+ | | | URB transfer type, see below
+-----------+--------+------------+--------------------------------------------------- >> + 0x18 | 4 | | transfer_buffer_lengthQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x1C | 4 | | start_frame: specify the selectedframe to
Quoted 1 line
Quoted 1 line
+ | | | transmit an ISO frame, ignored
if
URB_ISO_ASAPQuoted 2 lines
Quoted 2 lines
+ | | | is specified at
transfer_flags+-----------+--------+------------+--------------------------------------------------- >> + 0x20 | 4 | | number_of_packets: number of ISO packets +-----------+--------+------------+--------------------------------------------------- >> + 0x24 | 4 | | interval: maximum time for therequest on the
Quoted 2 lines
Quoted 2 lines
+ | | | server-side host controller
+-----------+--------+------------+--------------------------------------------------- >> + 0x28 | 8 | | setup: data bytes for USB setup,filled with
Quoted 2 lines
Quoted 2 lines
+ | | | zeros if not used
+-----------+--------+------------+--------------------------------------------------- >> + 0x30 | | | URB data. For ISO transfers thepadding between
Quoted 1 line
Quoted 1 line
+ | | | each ISO packets is not
transmitted.
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt
Quoted 3 lines
drivers/staging/usbip/usbip_protocol.txt +3
-0+ + + Allowed transfer_flags | value | control | interrupt | bulk| isochronous
Quoted 1 line
Quoted 1 line
+
-------------------------+------------+---------+-----------+----------+-------------
Quoted 1 line
Quoted 1 line
+
URB_SHORT_NOT_OK|0x00000001| only in | only in | onlyin | no
Quoted 1 line
Quoted 1 line
+
URB_ISO_ASAP|0x00000002| no | no | no| yes
Quoted 1 line
Quoted 1 line
+
URB_NO_TRANSFER_DMA_MAP|0x00000004| yes | yes | yes| yes
Quoted 1 line
Quoted 1 line
+
URB_NO_FSBR|0x00000020| yes | no | no| no
Quoted 1 line
Quoted 1 line
+
URB_ZERO_PACKET|0x00000040| no | no | onlyout | no
Quoted 1 line
Quoted 1 line
+
URB_NO_INTERRUPT|0x00000080| yes | yes | yes| yes
Quoted 1 line
Quoted 1 line
+
URB_FREE_BUFFER|0x00000100| yes | yes | yes| yes
Quoted 1 line
Quoted 1 line
+
URB_DIR_MASK|0x00000200| yes | yes | yes| yes
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt line 286
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+ + +USBIP_RET_SUBMIT: Reply for submitting an URB + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 4 | 0x00000002 | commandQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: URB sequence numberQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint numberQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | status: zero for successful URBtransaction,
Quoted 1 line
Quoted 1 line
+ | | | otherwise some kind of error
happened.
+-----------+--------+------------+--------------------------------------------------- >> + 0x18 | 4 | n | actual_length: number of URB data bytes +-----------+--------+------------+--------------------------------------------------- >> + 0x1C | 4 | | start_frame: for an ISO frame theactually
Quoted 2 lines
Quoted 2 lines
+ | | | selected frame for transmit.
+-----------+--------+------------+--------------------------------------------------- >> + 0x20 | 4 | | number_of_packetsQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x24 | 4 | | error_countQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x28 | 8 | | setup: data bytes for USB setup,filled with
Quoted 2 lines
Quoted 2 lines
+ | | | zeros if not used
+-----------+--------+------------+--------------------------------------------------- >> + 0x30 | n | | URB data bytes. For ISO transfersthe padding
Quoted 1 line
Quoted 1 line
+ | | | between each ISO packets is not
transmitted.
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt line 319
Quoted 5 lines
drivers/staging/usbip/usbip_protocol.txt +4
-0+ +USBIP_CMD_UNLINK: Unlink an URB + + Offset | Length | Value | Meaning+-----------+--------+------------+--------------------------------------------------- >> + 0 | 4 | 0x00000003 | command: URB unlink commandQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 4 | 4 | | seqnum: URB sequence number to unlink: FIXME: is this so? +-----------+--------+------------+--------------------------------------------------- >> + 8 | 4 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint number: zeroQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | seqnum: the URB sequence numbergiven previously
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt line 337
Quoted 6 lines
drivers/staging/usbip/usbip_protocol.txt +5
-0+ | | | 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 | | devidQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0xC | 4 | | direction: 0: USBIP_DIR_IN >> + | | | 1: USBIP_DIR_OUTQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x10 | 4 | | ep: endpoint numberQuoted 1 line
Quoted 1 line
+-----------+--------+------------+--------------------------------------------------- >> + 0x14 | 4 | | status: This is the valuecontained in the
Quoted 1 line
Quoted 1 line
+ | | |
urb->statusin the URBcompletition handler.
Quoted 7 lines
Quoted 2 lines
+ | | | 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
Re: [PATCH, RFC] USBIP protocol documentation
In reply to Németh MártonHi Greg,
2011/6/28 Németh Márton <[email protected]>:
Quoted 25 lines
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_SUBMITandUSBIP_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 withUSB_CMD_SUBMITand then unlinked withUSB_CMD_UNLINKthe completition handler is called only once. In the protocol, however, we have two different type of packets:USB_RET_SUBMITandUSBIP_RET_UNLINK. The status field of these messages may contain anything in this case depending on the timing.
Quoted 3 lines
Regards,
Márton Németh
Sorry, just one question about the usbip protocol document. I would like to know why didn't you apply this patch. Thanks in advance!
Best Regards,
David
Quoted 6 lines
_______________________________________________
devel mailing list
[email protected]
http://driverdev.linuxdriverproject.org/mailman/listinfo/devel
Re: [PATCH, RFC] USBIP protocol documentation
Quoted 28 lines · David Chang
Hi Greg,
2011/6/28 Németh Márton <[email protected]>:
Quoted 25 lines
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_SUBMITandUSBIP_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 withUSB_CMD_SUBMITand then unlinked withUSB_CMD_UNLINKthe completition handler is called only once. In the protocol, however, we have two different type of packets:USB_RET_SUBMITandUSBIP_RET_UNLINK. The status field of these messages may contain anything in this case depending on the timing.
Quoted 6 lines
Quoted 3 lines
Regards,
Márton Németh
Sorry, just one question about the usbip protocol document. I would like to know why didn't you apply this patch.
Because it was sent as a "RFC" (i.e. request for comments) and based on the discussion afterward, there were lots of comments :)
If someone wants to resend it to me, without that marking, I'll be glad to apply it.
thanks,
greg k-h
Re: [PATCH, RFC] USBIP protocol documentation
Hi Németh,
2011/8/9 Greg KH <[email protected]>:
Quoted 12 lines · David Chang
Quoted 4 lines
Hi Greg,
Sorry, just one question about the usbip protocol document. I would like to know why didn't you apply this patch.
Because it was sent as a "RFC" (i.e. request for comments) and based on the discussion afterward, there were lots of comments :)
If someone wants to resend it to me, without that marking, I'll be glad to apply it.
Could you resend the protocol document patch again without the RFC marking? And then we can get an initial version of the USBIP document. Thanks!
Best Regards,
David