RAWOne packet or bulk transfer on one endpoint

RAW carries an endpoint address and the bytes to put there. Opcode 0x19.

RAW 0x19 · payload 2 + n bytes

Fire-and-forget

PAYLOAD
OffsetFieldTypeNotes
0ep_numu8endpoint number; low four bits used
1diru81 IN, 2 OUT (the LOCK direction byte)
2bytesu8[]packet, verbatim; delimited by the frame LEN, so ≤510 bytes
DIRECTION
ValueNameEffect
1INqueued on the clone's IN endpoint ep_num (HID interrupt, vendor interrupt or bulk) for the game PC to read
2OUTrelayed through the host chip to OUT endpoint ep_num (HID interrupt, vendor interrupt or bulk) on the real device
REFUSALS
Refused whenWhy
payload <2 bytesno endpoint address
clone not yet configured by the game PCclone endpoints are unarmed until the PC's SET_CONFIGURATION
dir is not 1 or 2only 1 (IN) and 2 (OUT) name an address
IN: no cloned HID or vendor IN endpoint ep_numthe box writes only IN endpoints it cloned
OUT: no real-device OUT endpoint ep_numthe host chip drops it, with no endpoint to submit to
an interrupt packet past its limitan interrupt transfer is one packet, so a split would be emitted as two reports
EFFECT

The bytes reach the endpoint as given. RAW has no reply. An EMIT subscription shows an IN packet as the game PC reads it.

EXAMPLE

Left button down on HID interrupt IN endpoint 1: ep_num = 1, dir = 1, a 4-byte report:

A5SOF
19TYPE
00SEQ
06 00LEN
01ep_num
01dir
01 00 00 00bytes
lo hiCRC16

The release, button bit clear:

A5SOF
19TYPE
01SEQ
06 00LEN
01ep_num
01dir
00 00 00 00bytes
lo hiCRC16

A keyboard LED report, Caps Lock on, to interrupt OUT endpoint 2: ep_num = 2, dir = 2, one byte:

A5SOF
19TYPE
02SEQ
03 00LEN
02ep_num
02dir
02bytes
lo hiCRC16

Library bindings: raw, and raw on AsyncDevice.

Packet sizePer transfer type

On the wire, OUT packets follow the endpoint's wMaxPacketSize, as IN packets do. The inter-chip relay carries a bulk payload in pieces of ≤64 bytes.

Aspectdir = 1, INdir = 2, OUT
Interruptone packet, at most the endpoint's wMaxPacketSize and 64 bytes. On a HID endpoint, a packet of exactly wMaxPacketSize is ended by a ZLP when the endpoint's largest Input report is longer, as a native report of that length isone packet, at most the endpoint's wMaxPacketSize
Bulksplit at wMaxPacketSize
Bulk enda short packet, or a zero-length packet (ZLP) when the payload is an exact multiple of wMaxPacketSize. An empty bytes sends one ZLP
SPLIT
  bulk, wMaxPacketSize = 64

  bytes = 130   -->   [ 64 ] [ 64 ] [ 2 ]      the 2-byte packet ends the transfer
  bytes = 128   -->   [ 64 ] [ 64 ] [ ZLP ]    an exact multiple ends on a ZLP
  bytes = 0     -->   [ ZLP ]

  HID interrupt IN, wMaxPacketSize = 8, largest Input report 20 bytes

  bytes = 7     -->   [ 7 ]                    a short packet ends the transfer
  bytes = 8     -->   [ 8 ] [ ZLP ]            a whole packet short of 20: the PC's read ends at the ZLP
QUEUES
NameBehaviour
HID IN, 8 reportswhen full, drops the oldest native zero-length packet, counted in relay_drops. Failing that, the oldest native report, then the oldest RAW one, counted in tx_drops
vendor interrupt IN, 8 packetsdrops the oldest packet when full, counted in relay_drops
vendor bulk IN, 8 packetsdrops the new packet when full, counted in relay_drops. The box polls the real device's bulk IN only while the PC reads the clone's and <8 packets are queued or armed (RAW ones included), so only a RAW packet finds the queue full
OUT relay, 16 packets across all endpointseach waits its turn behind the real device's two-packet hold, as the PC's writes do. The PC's writes to that endpoint wait behind it, except one the clone had already taken a read for, which goes first. A packet past 16 is dropped, counted in relay_drops

Native reports take ≤1 place in an interrupt IN queue. The box polls the real device's endpoint only while the PC polls the clone's, and only as the PC takes what the last poll brought. The rest of the queue is room for RAW reports. A native bulk stream takes as many places as the PC leaves unread, up to all 8.

An interrupt endpoint's native reports take two places in two cases: while the next report is fetched before the PC has the last one whole, and for 100 ms after a report reaches the clone too late for its poll (up to 3 s while late reports keep coming).

A native STALL on an interrupt or bulk IN reaches the game PC after the reports sent before it. The endpoint stays halted until the PC's CLEAR_FEATURE(HALT), which is relayed to the real device. The box never clears it.

A bulk IN transfer longer than the queue's free slots reaches the game PC truncated. At wMaxPacketSize = 64, 510 bytes is 8 packets, the whole queue.

LifetimeHeld until the next native report

A RAW IN report is the last state the game PC read on that endpoint until the next native report replaces it.

A RAW report takes a separate poll. No native report carries it. On an endpoint the real device reports on every poll, the RAW report is emitted after ≤2 native reports.

  native report   [ btn 0 ]                            [ btn 0 ]
  RAW, dir = 1                  [ btn 1 ]
  emitted         [ btn 0 ]     [ btn 1 ]              [ btn 0 ]
                                |<- last report read ->|
PIPELINE

A RAW packet goes straight to the endpoint, past every rewrite rule, clip packet trigger, LOCK, TRANSFORM, rendering and injection.

MechanismEffect
report mergingsums motion between other queued reports and keeps each RAW report whole, byte for byte
change suppressionif a RAW report is shaped like the mouse, keyboard or media report the box injects into, it becomes the last report emitted, the baseline for injected frames

A clip raw item is the same packet on a clip tick, with a different release rule.

Catch tapsTraffic classes a RAW packet raises

A RAW IN packet raises TRAFFIC_EVENTs on the taps it passes. The HID_IN and OUT taps sit upstream of RAW's entry point.

WhenRaises
the game PC reads a RAW report off a HID IN endpointEMIT (9), dir = 1
a RAW packet enters a vendor IN queueVEND_INTR (6) or VEND_BULK (7), dir = 1, stamped clk = 1 by the device chip. An empty packet carries the ZLP flag, and on bulk the end-of-transfer flag too
the game PC reads a RAW packet off a vendor IN endpoint, an empty one with the ZLP flagEMIT (9), dir = 1