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

PAYLOAD
OffsetFieldTypeNotes
0epu8endpoint number: 0 = EP0, else a control endpoint the real device declares
1timeout_msu16the box's wait on the real device, 1-65535 ms, little-endian
3bmRequestTypeu8bit 7 is direction: 1 IN, 0 OUT
4bRequestu8request code
5wValueu16little-endian
7wIndexu16little-endian
9wLengthu16data stage length, little-endian
11..datau8[]OUT only: the wLength bytes of the data stage, ≤501

Offsets 3-10 are the setup packet as the real device receives it.

TIMEOUT
ValueEffect
0refused with 0xFC; nothing reaches the real device
1-65535the 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
DATA STAGE
ValueEffect
bit 7 = 1, INbytes after offset 10 ignored; the data stage comes back in the reply
bit 7 = 0, OUTthe 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.

REFUSALS
WhenSends
payload <11 bytesnothing; frame discarded
opt-in off0xFC
timeout_ms = 00xFC
OUT request with fewer than wLength data bytes0xFC
ep naming no control endpoint the real device declares0xFC
another TRANSFER outstanding0xFC
EXAMPLE

GET_DESCRIPTOR(device) on EP0, 18 bytes, waiting 1000 ms (E8 03): setup 80 06 00 01 00 00 12 00.

A5SOF
1ATYPE
07SEQ
0B 00LEN
00ep
E8 03timeout_ms
80bmRequestType
06bRequest
00 01wValue
00 00wIndex
12 00wLength
lo hiCRC16

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).

A5SOF
1ATYPE
08SEQ
0C 00LEN
00ep
F4 01timeout_ms
21bmRequestType
09bRequest
00 02wValue
00 00wIndex
01 00wLength
02data
lo hiCRC16

Library bindings: transfer, transfer_timeout, and the AsyncDevice forms.

TRANSFER_RESPReply, 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

PAYLOAD
OffsetFieldTypeNotes
0epu8echoes the command's ep byte
1statusu8how the transfer ended, as below; read it on the LAST chunk only
2stageu8where it ended: 0 SETUP, 1 data, 2 status; read it on the LAST chunk only
3flagsu8bit 0 LAST: the reply's last chunk
4offsetu16where data sits in the reply, little-endian
6..datau8[]≤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.

DATA
RequestReply data
IN, with a data stagethe 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 = 0what 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.

STATUS
ValueNameMeans
0x00OKthe transfer completed
0xF9BUSYthe 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
0xFASUSPENDEDthe game PC has suspended the clone, and the real device with it; nothing was sent
0xFBERRORthe 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
0xFCREFUSEDnever sent, per the refusals
0xFDSTALLthe real device STALLed, in stage
0xFENO_ANSWERthe 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)
0xFFNO_DEVICEno device attached

The same codes flag a CLIP_XFER event, the transfer a clip runs.

EXAMPLE

The device descriptor for SEQ 07, one chunk (18 data bytes, so LEN = 24):

A5SOF
1BTYPE
07SEQ
18 00LEN
00ep
00status
02stage
01flags
00 00offset
12 01 00 02 00 00 00 40 ... (18 bytes)data: the device descriptor
lo hiCRC16

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:

A5SOF
1BTYPE
0ASEQ
46 00LEN
00ep
FDstatus
01stage
01flags
00 00offset
... (64 bytes)data: before the STALL
lo hiCRC16

One at a timeOther 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
TIMING
QuantityValue
Wait on the real devicetimeout_ms. Time a long reply's next chunk waits for the control port isn't counted, up to 1 s a chunk.
LAST chunkWithin 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 waitAt 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 endpointsGame 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 PCTRANSFER
has a request waiting on that endpointwaits behind it, inside timeout_ms
abandoned a request there and sent no SETUP after itwaits 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 out0xF9 BUSY in stage 0: nothing sent
sends its next request on that endpoint, or causes a bus event, mid-transfer0xF9 BUSY in the stage it reached
uses another endpointruns on, unaffected
has the clone suspended0xFA SUSPENDED: nothing sent
TAPS

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.