pub struct CommandTable {
pub base: usize,
pub stride: usize,
pub opcode_off: usize,
pub flags_off: usize,
pub handler_off: usize,
pub term_flag: u8,
pub max_records: usize,
}Expand description
An opcode-dispatch table: an array of fixed-size records that firmware scans
by key until it finds a handler pointer to call. The shape recurs across
unrelated devices (SCSI/ATA command tables, vendor-command tables, ioctl and
AT-command jump tables), so this type stores only the geometry — where the
records start, how wide they are, and which byte of a record holds the
opcode, the flags and the handler pointer. The caller supplies those
numbers; CommandTable::find, CommandTable::walk and
CommandTable::replace are generic over them.
One worked example, given because it makes the fields concrete rather
than because the crate assumes it: an MT1959 optical-drive scanner does
ldrb [rec + opcode_off] to match, then ldr [rec + handler_off]; blx to
dispatch, over records laid out [opcode(1) | flags(1) | resv(2) | handler(4 LE)]. That table is described by stride: 8, opcode_off: 0,
flags_off: 1, handler_off: 4, and term_flag: 0x03 for the record that
ends the scan. A different firmware with, say, 12-byte records and the
handler first is the same type with different numbers.
Fields§
§base: usizeFile offset of the first record.
stride: usizeBytes per record.
opcode_off: usizeByte offset of the opcode within a record.
flags_off: usizeByte offset of the flags byte within a record.
handler_off: usizeByte offset of the 4-byte LE handler pointer within a record.
term_flag: u8Flags value that marks the terminator record (scan stops here).
max_records: usizeMax records to scan before giving up (guards a corrupt/missing terminator).
Implementations§
Source§impl CommandTable
impl CommandTable
Sourcepub fn find(&self, image: &[u8], opcode: u8) -> Option<CommandRecord>
pub fn find(&self, image: &[u8], opcode: u8) -> Option<CommandRecord>
find(opcode) — the record dispatching opcode, or None if absent
(scan stops at the terminator, exactly like the drive’s scanner).
Sourcepub fn replace(
&self,
image: &mut [u8],
rec: &CommandRecord,
handler: u32,
flags: Option<u8>,
)
pub fn replace( &self, image: &mut [u8], rec: &CommandRecord, handler: u32, flags: Option<u8>, )
replace(record, newHandler) — overwrite a record’s handler pointer (and,
if flags is Some, its flags byte). This is the hijack: point an
existing opcode’s dispatch at injected code. Prefer a record whose
current handler is null (nothing runs today); repointing a live handler
is allowed but the caller should warn.
§Panics
Panics if either field lies outside image. Both are checked before
either is written, so a record too close to the end of a truncated image
leaves the table untouched rather than half-repointed: the flags byte and
the handler pointer are one logical edit, and a table whose flags say
“live handler” while the pointer still says “null” is worse than one that
was never touched. This mirrors the atomicity detour guarantees.
Source§impl CommandTable
impl CommandTable
Sourcepub fn walk(&self, image: &[u8], chain_flag: u8) -> Vec<CommandRecord>
pub fn walk(&self, image: &[u8], chain_flag: u8) -> Vec<CommandRecord>
Walk the table exactly as the firmware’s own scanner does — following
chain records (flags == chain_flag) to successor segments and stopping
at the first terminator (flags == term_flag) — collecting every
dispatch record. A chain record is one whose flags equal chain_flag
and whose handler field is not a handler at all but the file offset of
the next segment; that is how a table too big for one contiguous run is
spelled (the MT1959 example above uses chain_flag == 4). Pass a
chain_flag that no real record uses if the table has no segments.
A BTreeSet of visited bases guards against a chain that loops back on
itself, so a corrupt image costs a wasted scan rather than a hang.
Returns the records in scan order. This is the grounded basis for
CommandTable::find-style lookups when a table spans chained segments.