Raw
RAW places one packet or bulk transfer, byte for byte, on an endpoint named by number and direction: IN to the game PC, OUT to the real device. It enters the path after every stage that reads or rewrites a packet.
IN native report --> rewrite --> lock, render, inject --> rewrite ---+
HID_IN EMIT |
v
RAW(ep, 1) ------> [ IN queue ] --> game PC
OUT game PC --------> rewrite ----------------------------------------+
HID_OUT, VEND_INTR, VEND_BULK |
v
RAW(ep, 2) ------> [ OUT relay ] --> real device
rewrite = the rewrite rules and the clip packet triggers on that surfaceStandard inputs belong in INJECT and MOVE, which the box renders into a faithful report. RAW is for bytes no semantic field describes.
RAW runs only under OPTION(IMPERFECT). Otherwise the box discards the frame with no reply. It also discards a clip raw item, counted in gated.
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
| Offset | Field | Type | Notes |
|---|---|---|---|
| 0 | ep_num | u8 | endpoint number; low four bits used |
| 1 | dir | u8 | 1 IN, 2 OUT (the LOCK direction byte) |
| 2 | bytes | u8[] | packet, verbatim; delimited by the frame LEN, so ≤510 bytes |
| Value | Name | Effect |
|---|---|---|
1 | IN | queued on the clone's IN endpoint ep_num (HID interrupt, vendor interrupt or bulk) for the game PC to read |
2 | OUT | relayed through the host chip to OUT endpoint ep_num (HID interrupt, vendor interrupt or bulk) on the real device |
| Refused when | Why |
|---|---|
| payload <2 bytes | no endpoint address |
| clone not yet configured by the game PC | clone endpoints are unarmed until the PC's SET_CONFIGURATION |
dir is not 1 or 2 | only 1 (IN) and 2 (OUT) name an address |
IN: no cloned HID or vendor IN endpoint ep_num | the box writes only IN endpoints it cloned |
OUT: no real-device OUT endpoint ep_num | the host chip drops it, with no endpoint to submit to |
| an interrupt packet past its limit | an interrupt transfer is one packet, so a split would be emitted as two reports |
The bytes reach the endpoint as given. RAW has no reply. An EMIT subscription shows an IN packet as the game PC reads it.
Left button down on HID interrupt IN endpoint 1: ep_num = 1, dir = 1, a 4-byte report:
The release, button bit clear:
A keyboard LED report, Caps Lock on, to interrupt OUT endpoint 2: ep_num = 2, dir = 2, one byte:
Packet size Per 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.
| Aspect | dir = 1, IN | dir = 2, OUT |
|---|---|---|
| Interrupt | one 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 is | one packet, at most the endpoint's wMaxPacketSize |
| Bulk | split at wMaxPacketSize | |
| Bulk end | a short packet, or a zero-length packet (ZLP) when the payload is an exact multiple of wMaxPacketSize. An empty bytes sends one ZLP | |
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
| Name | Behaviour |
|---|---|
| HID IN, 8 reports | when 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 packets | drops the oldest packet when full, counted in relay_drops |
| vendor bulk IN, 8 packets | drops 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 endpoints | each 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 ->|A RAW packet goes straight to the endpoint, past every rewrite rule, clip packet trigger, LOCK, TRANSFORM, rendering and injection.
| Mechanism | Effect |
|---|---|
| report merging | sums motion between other queued reports and keeps each RAW report whole, byte for byte |
| change suppression | if 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 taps Traffic 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.
| When | Raises |
|---|---|
the game PC reads a RAW report off a HID IN endpoint | EMIT (9), dir = 1 |
a RAW packet enters a vendor IN queue | VEND_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 flag | EMIT (9), dir = 1 |