Rewrite rules

A rule matches traffic and rewrites, answers, refuses, or drops it. Rules use the (class, id, direction) address catch reads, in the write direction. A masked compare on the packet's head narrows the match.

Rules are session state, like a lock. The library re-asserts them on each keepalive, on reconnect and by session recovery. The box clears them on control-PC silence, reset, the real device detaching, an inter-chip link loss, a re-clone, or the opt-in going off (native lifecycle).

  real device            the box  (host chip  |  device chip = the clone)         game PC

  HID report  ---IN--->  [ HID_IN ]--> renderer --> [ EMIT ]---interrupt-IN---->  reads report
                          ^ as it arrived            ^ the wire
  relayed     <--OUT---  [ HID_OUT ]<-- relay <--------------- interrupt-OUT <--  writes report
                          ^ VEND_INTR / VEND_BULK
  control     <-- EP0 -> [ CONTROL ]<-- proxy ------------------- EP0 <-------->  class, vendor requests
                          ^ id = endpoint number

              a rule acts at the [ bracketed ] stage its class names; ANY acts at each
              on EP0 only the requests relayed to the real device reach [ CONTROL ]

A packet reaches the clip's packet triggers before the rule table. A packet a trigger consumes reaches no rule. Catch marks a packet a rule acted on (rule_acted).

The host chip weighs the bound mouse's relative axes from the report as it arrived. Whenever a scale, injection or rendering changes them, the host chip's values replace a HidIn rewrite of those bytes. Rewrite motion at Emit.

The advanced control layer needs allow_imperfect_clones. With it off, set_rewrite returns Error::ImperfectRequired.

set_rewrite, remove_rewrite, and clear_rewrite are fire-and-forget. query_rewrite reads back what the box holds.

set_rewriteInstall or overwrite one rule

fn set_rewrite(&self, rule: &RewriteRule) -> Result<()>

Fire-and-forget

Parameter	Type	Description
`rule`	`RewriteRule`	Its address, `action`, and any masked match or payload.

Rules are keyed by (class, id, direction, match, mask). Setting an existing key overwrites the rule, resets its hits and moves it to the end of the table. The crate checks the box's limits before sending.

REFUSALS

Limit	Past it
2048 payload bytes across every held rule (`REWRITE_PAYLOAD_POOL`), checked first. An overwrite frees the bytes of the rule it replaces.	`Error::RewritePoolFull`
32 rules (`REWRITE_MAX_ENTRIES`), for a new key	`Error::RewriteTableFull`

EXAMPLE

use medius::{Device, Direction, RewriteRule, RewriteClass, RewriteAction};

let device = Device::find()?;
device.allow_imperfect_clones(true)?;

// Drop every report the clone emits on interrupt-IN endpoint 1.
device.set_rewrite(&RewriteRule::new(RewriteClass::Emit, 1, Direction::IN, RewriteAction::Drop))?;

// Overwrite byte 2 of each report the clone emits on endpoint 1, when byte 0 is the report id 0x01.
device.set_rewrite(
    &RewriteRule::new(RewriteClass::Emit, 1, Direction::IN, RewriteAction::Patch)
        .matching([0x01], [0xFF])
        .at_offset(2)
        .with_payload([0x00]),
)?;

remove_rewriteDrop one rule

fn remove_rewrite(&self, rule: &RewriteRule) -> Result<()>

Fire-and-forget

Drops the rule with this rule's (class, id, direction, match, mask) key, ignoring its action and payload. A no-op if no such rule is held.

EXAMPLE

let rule = RewriteRule::new(RewriteClass::Emit, 1, Direction::IN, RewriteAction::Drop);
device.set_rewrite(&rule)?;
device.remove_rewrite(&rule)?; // the same key, dropped

clear_rewriteDrop every rule

fn clear_rewrite(&self) -> Result<()>

Fire-and-forget

Drops the whole table. Whatever the opt-in, it also drops the crate's held rules, so a reconnect never re-asserts a cleared rule.

EXAMPLE

device.clear_rewrite()?;

query_rewriteTable summary

fn query_rewrite(&self) -> Result<RewriteTable>

Blocks

Returns a RewriteTable: a full flag, a generation counter, and a row per rule without its match, mask, or payload bytes. The full flag means the box refused the last new rule or overwrite for lack of room. The next table change or a clear resets it.

EXAMPLE

let table = device.query_rewrite()?;
println!("{} rules, gen {}", table.entries.len(), table.generation);
for e in &table.entries {
    println!("  {:?} id {:#04x} -> {:?}, {} hits", e.class, e.id, e.action, e.hits);
}

query_rewrite_entryOne rule in full

fn query_rewrite_entry(&self, index: u8) -> Result<RewriteRule>

Blocks

Parameter	Type	Description
`index`	`u8`	The row in the `query_rewrite` summary.

Returns one RewriteRule in full, in the shape set_rewrite takes.

EXAMPLE

let table = device.query_rewrite()?;
for i in 0..table.entries.len() as u8 {
    let rule = device.query_rewrite_entry(i)?; // replayable as a set
    let _ = rule;
}

On AsyncDeviceset_rewrite and the queries await; remove and clear fire

AsyncDevice makes set_rewrite a future that awaits the opt-in check before sending. query_rewrite and query_rewrite_entry are futures too. remove_rewrite and clear_rewrite carry no opt-in check and stay synchronous.

EXAMPLE

use futures::executor::block_on;
use medius::{AsyncDevice, Direction, RewriteRule, RewriteClass, RewriteAction};

let device = AsyncDevice::open("/dev/ttyACM0")?;
device.allow_imperfect_clones(true)?;
let rule = RewriteRule::new(RewriteClass::Emit, 1, Direction::IN, RewriteAction::Drop);
block_on(device.set_rewrite(&rule))?;            // awaits the opt-in gate
device.remove_rewrite(&rule)?;                   // sync: no gate
let table = block_on(device.query_rewrite())?;   // query awaits