Transfer
TRANSFER runs one USB control transfer on the real device from the control PC. TRANSFER_RESP returns the outcome and the native reply, ≤448 bytes a frame.
control PC DEVICE chip HOST chip real device
| | | |
|-- TRANSFER, SEQ n ----->| | |
| |-- link request ---->| |
| | |-- SETUP, OUT data ->|
| | |<- IN data, status --|
| |<- reply, in chunks -| |
|<- TRANSFER_RESP, n -----| | |
|<- TRANSFER_RESP, n -----| | |
|<- TRANSFER_RESP, LAST --| | |The game PC's requests on the same endpoint come first.
TRANSFER runs only under OPTION(IMPERFECT). Otherwise a request with a full setup packet gets 0xFC REFUSED and never reaches the real device.
TRANSFEROne control transfer on the real device
TRANSFER carries an endpoint, a timeout, an eight-byte setup packet, and any OUT data stage. Opcode 0x1A.
TRANSFER 0x1A · payload 11..512 bytes
Reply
| Offset | Field | Type | Notes |
|---|---|---|---|
| 0 | ep | u8 | endpoint number: 0 = EP0, else a control endpoint the real device declares |
| 1 | timeout_ms | u16 | the box's wait on the real device, 1-65535 ms, little-endian |
| 3 | bmRequestType | u8 | bit 7 is direction: 1 IN, 0 OUT |
| 4 | bRequest | u8 | request code |
| 5 | wValue | u16 | little-endian |
| 7 | wIndex | u16 | little-endian |
| 9 | wLength | u16 | data stage length, little-endian |
| 11.. | data | u8[] | OUT only: the wLength bytes of the data stage, ≤501 |
Offsets 3-10 are the setup packet as the real device receives it.
| Value | Effect |
|---|---|
0 | refused with 0xFC; nothing reaches the real device |
1-65535 | the box waits that many ms on the real device, including time the game PC holds the pipe; then 0xFE NO_ANSWER, or 0xF9 BUSY if the game PC held the pipe throughout |
| Value | Effect |
|---|---|
| bit 7 = 1, IN | bytes after offset 10 ignored; the data stage comes back in the reply |
| bit 7 = 0, OUT | the first wLength bytes sent, the rest ignored; fewer is refused |
An OUT stage is ≤501 bytes, what a 512-byte payload leaves after ep, timeout_ms and the setup packet. An IN stage can be any length: the reply comes in chunks.
A SET_CONFIGURATION or SET_INTERFACE sent here changes only the real device. The clone, and the endpoints the host chip polls, stay as the game PC set them.
| When | Sends |
|---|---|
| payload <11 bytes | nothing; frame discarded |
| opt-in off | 0xFC |
timeout_ms = 0 | 0xFC |
OUT request with fewer than wLength data bytes | 0xFC |
ep naming no control endpoint the real device declares | 0xFC |
another TRANSFER outstanding | 0xFC |
GET_DESCRIPTOR(device) on EP0, 18 bytes, waiting 1000 ms (E8 03): setup 80 06 00 01 00 00 12 00.
An OUT request: SET_REPORT(Output) on interface 0 with one data byte, 02, a boot keyboard's Caps Lock LED, waiting 500 ms (F4 01).
Library bindings: transfer, transfer_timeout, and the AsyncDevice forms.
TRANSFER_RESP Reply, a chunk a frame
One or more frames per TRANSFER with a full setup packet, each echoing the command's SEQ. Opcode 0x1B.
TRANSFER_RESP 0x1B · payload 6..454 bytes
Reply
| Offset | Field | Type | Notes |
|---|---|---|---|
| 0 | ep | u8 | echoes the command's ep byte |
| 1 | status | u8 | how the transfer ended, as below; read it on the LAST chunk only |
| 2 | stage | u8 | where it ended: 0 SETUP, 1 data, 2 status; read it on the LAST chunk only |
| 3 | flags | u8 | bit 0 LAST: the reply's last chunk |
| 4 | offset | u16 | where data sits in the reply, little-endian |
| 6.. | data | u8[] | ≤448 bytes of the reply; length from the frame LEN |
Put the chunks together by offset, and resolve the TRANSFER on the LAST one, as the library's transfer does.
| Request | Reply data |
|---|---|
| IN, with a data stage | the data stage as the box received it, including bytes before a STALL, and bytes past wLength the real device sent in the packets a host asks for |
OUT, or wLength = 0 | what the real device sent where the status stage was due, ≤1 packet; usually none |
A status other than OK can still carry data, such as the bytes before a STALL. A PC sees data past wLength, and data in a status stage, as the transfer failing.
| Value | Name | Means |
|---|---|---|
0x00 | OK | the transfer completed |
0xF9 | BUSY | the game PC's transfer held the pipe until the timeout, and nothing was sent (stage 0); or the game PC's next request on that endpoint, or a bus event it caused, took the pipe in stage |
0xFA | SUSPENDED | the game PC has suspended the clone, and the real device with it; nothing was sent |
0xFB | ERROR | the real device's packets were corrupt past three tries, or ran past the buffer the host asked for; or the host chip had no channel free to send it on |
0xFC | REFUSED | never sent, per the refusals |
0xFD | STALL | the real device STALLed, in stage |
0xFE | NO_ANSWER | the real device NAKed until the timeout, in stage; or the host chip's reply was lost between the chips; or the reply's next chunk waited 1 s to be passed on to the control port (stage 1) |
0xFF | NO_DEVICE | no device attached |
The same codes flag a CLIP_XFER event, the transfer a clip runs.
The device descriptor for SEQ 07, one chunk (18 data bytes, so LEN = 24):
SEQ 09 reads 1000 bytes of a configuration descriptor, three frames:
frame flags offset data reply bytes 1 0x00 0 448 bytes 0-447 2 0x00 448 448 bytes 448-895 3 0x01 LAST 896 104 bytes 896-999 status 0x00 OK, stage 2
The real device STALLs SEQ 0A's 192-byte read after 64 bytes:
One at a time Other commands run while one waits
One TRANSFER is outstanding at a time, until its LAST chunk. If the box ends one because a chunk waited 1 s, it stays outstanding until the real device finishes it.
TRANSFER A --> [ waits on the real device ] --> TRANSFER_RESP A ... LAST TRANSFER B --> TRANSFER_RESP B, 0xFC REFUSED, while A waits MOVE, ... --> applied as each arrives, while A waits
| Quantity | Value |
|---|---|
| Wait on the real device | timeout_ms. Time a long reply's next chunk waits for the control port isn't counted, up to 1 s a chunk. |
LAST chunk | Within timeout_ms + 0.5 s of the box taking the TRANSFER, plus any time its chunks waited for the control port. If the reply is lost between the chips, the LAST chunk still comes, with 0xFE NO_ANSWER. If a chunk waits 1 s for the control port, the reply ends there: NO_ANSWER in stage 1, with the data passed on so far. |
| Client's wait | At least timeout_ms + 0.5 s, plus the client's serial latency. The library waits timeout_ms + 2 s. |
A TRANSFER doesn't hold off the 1 s silence clear (safety). While one waits, a client holding injection state keeps sending keepalives.
Shared endpoints Game PC requests come first
Each control endpoint of the real device is one pipe.
game PC ----- EP0 ---> clone ------+
|
control PC -- TRANSFER, ep 0 ------+--> EP0 pipe --------> real device EP0
| game PC first
clip -------- transfer item, ep 0 -+
game PC ----- endpoint 2 -> clone -+
+--> endpoint 2 pipe -> real device endpoint 2
control PC -- TRANSFER, ep 2 ------+| Game PC | TRANSFER |
|---|---|
| has a request waiting on that endpoint | waits behind it, inside timeout_ms |
| abandoned a request there and sent no SETUP after it | waits behind it until the box ends it, 250-300 ms after the game PC's last poll; 0xF9 BUSY in stage 0 if timeout_ms runs out first |
holds the pipe until timeout_ms runs out | 0xF9 BUSY in stage 0: nothing sent |
| sends its next request on that endpoint, or causes a bus event, mid-transfer | 0xF9 BUSY in the stage it reached |
| uses another endpoint | runs on, unaffected |
| has the clone suspended | 0xFA SUSPENDED: nothing sent |
A TRANSFER runs outside every tap, rule and trigger: CATCH CONTROL, REWRITE on CONTROL, and clip packet triggers cover the game PC's traffic only.