Something went wrong. Try again.
A Zig library for talking to USB and Bluetooth HID devices on Linux, FreeBSD, Windows and macOS, without linking the C hidapi
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380// SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! Reading a HID report descriptor.//!//! A descriptor is a byte string describing what a device's reports contain://! how many, how long, which bits mean what, and what range each field//! carries. Without it a report is eight opaque bytes. With it, byte 3 is the//! wheel and it counts from -127 to 127.//!//! There are three levels here, and a caller can stop at whichever answers//! the question://!//! * `firstUsage` says what the device is -- a keyboard, a mouse, something//! vendor defined -- and is what enumeration uses to fill in//! `DeviceInfo.usage_page` and `usage`.//! * `Iterator` walks the raw items, for code that wants the descriptor//! exactly as written.//! * `Parser` runs the item state machine and yields a `Field` per main item,//! with its bit position, its size, its usages and its ranges all resolved.//! `Field.extract` then reads one out of a report and `Field.insert` writes//! one into it.//!//! Nothing here allocates. `Parser` is a value the caller owns, about two//! kilobytes, and the slices a `Field` hands back point into it and stay valid//! until the next call to `next` -- the same rule `Enumerator` follows.//!//! The item encoding is the USB HID Class Definition 1.11, section 6.2.2.
const std = @import("std");
/// The usage page and usage of a device's first top-level collection.pub const Usage = struct { page: u16, id: u16,};
/// The prefix of a long item, which carries its own size byte. Long items are/// defined by the specification and used by nothing, but a descriptor/// containing one still has to be walked past rather than misread.const long_item_prefix = 0b1111_1110;
/// Find the usage page and usage of the first top-level collection in/// `bytes`, or `null` if the descriptor declares none.////// Never fails: a truncated or malformed descriptor stops the walk and yields/// whatever was found before it, on the grounds that a device answering/// nonsense is a device to report rather than one to refuse to list. The/// caller sees `null`, the same as for a descriptor that genuinely has no/// collection.////// This is the cheap question -- what *is* this device -- and needs none of/// `Parser`'s state. Enumeration asks it for every device it finds.pub fn firstUsage(bytes: []const u8) ?Usage { var page: u16 = 0; var usage: ?u16 = null; // A usage item may carry the page in its own top 16 bits, in which case // it wins over the global page for that one usage. var usage_page_from_item: ?u16 = null;
var it: Iterator = .init(bytes); while (it.next()) |raw| { switch (raw.type) { .global => if (raw.tag == global_tag.usage_page) { page = @truncate(raw.unsigned()); }, .local => if (raw.tag == local_tag.usage) { const v = raw.unsigned(); if (raw.data.len == 4) { usage_page_from_item = @truncate(v >> 16); usage = @truncate(v); } else { usage_page_from_item = null; usage = @truncate(v); } }, .main => if (raw.tag == main_tag.collection) { return .{ .page = usage_page_from_item orelse page, .id = usage orelse return null, }; }, .reserved => {}, } } return null;}
test "a mouse descriptor reports the generic desktop mouse usage" { // Usage Page (Generic Desktop), Usage (Mouse), Collection (Application) const bytes = [_]u8{ 0x05, 0x01, 0x09, 0x02, 0xA1, 0x01 }; const u = firstUsage(&bytes).?; try std.testing.expectEqual(@as(u16, 0x01), u.page); try std.testing.expectEqual(@as(u16, 0x02), u.id);}
test "a vendor-defined page above 0xff is kept whole" { // Usage Page (0xFF00), Usage (0x01), Collection (Application). The page // needs both data bytes; truncating to one would report 0x00. const bytes = [_]u8{ 0x06, 0x00, 0xFF, 0x09, 0x01, 0xA1, 0x01 }; const u = firstUsage(&bytes).?; try std.testing.expectEqual(@as(u16, 0xFF00), u.page); try std.testing.expectEqual(@as(u16, 0x01), u.id);}
test "an extended usage carries its own page" { // Usage Page (Generic Desktop) then a four byte Usage naming page 0xFF01 // and usage 0x0002, which wins over the global page. const bytes = [_]u8{ 0x05, 0x01, 0x0B, 0x02, 0x00, 0x01, 0xFF, 0xA1, 0x01 }; const u = firstUsage(&bytes).?; try std.testing.expectEqual(@as(u16, 0xFF01), u.page); try std.testing.expectEqual(@as(u16, 0x0002), u.id);}
test "bSize of 3 means four bytes" { // If the four byte usage above were read as three, the collection item // would be found one byte early and the walk would go wrong. Prove the // width table directly. const bytes = [_]u8{ 0x05, 0x01, 0x09, 0x06, 0xA1, 0x01 }; const u = firstUsage(&bytes).?; try std.testing.expectEqual(@as(u16, 0x06), u.id); // Keyboard}
test "a long item is stepped over rather than misread" { // A long item with two data bytes, then a perfectly ordinary keyboard // descriptor. Getting the skip wrong finds no collection at all. const bytes = [_]u8{ 0xFE, 0x02, 0x00, 0xAA, 0xBB, 0x05, 0x01, 0x09, 0x06, 0xA1, 0x01, }; const u = firstUsage(&bytes).?; try std.testing.expectEqual(@as(u16, 0x01), u.page); try std.testing.expectEqual(@as(u16, 0x06), u.id);}
test "a truncated descriptor yields null rather than reading past the end" { // A Usage Page item that promises two bytes and supplies one. try std.testing.expectEqual(@as(?Usage, null), firstUsage(&[_]u8{ 0x06, 0x00 })); // A collection with no usage before it. try std.testing.expectEqual(@as(?Usage, null), firstUsage(&[_]u8{ 0xA1, 0x01 })); // Nothing at all. try std.testing.expectEqual(@as(?Usage, null), firstUsage(&.{}));}
test { std.testing.refAllDecls(@This());}
// ---------------------------------------------------------------------------// Raw items// ---------------------------------------------------------------------------
/// One item as the descriptor wrote it.pub const RawItem = struct { type: Type, /// The item's tag, in the top four bits of the prefix. tag: u4, /// The data bytes, 0, 1, 2 or 4 of them, little endian. Empty for a long /// item, whose payload is in `long_data`. data: []const u8, /// A long item's payload. Long items are defined by the specification and /// used by nothing, but one has to be walked past rather than misread. long_data: []const u8 = &.{},
pub const Type = enum(u2) { main = 0, global = 1, local = 2, reserved = 3 };
/// The data as an unsigned value. pub fn unsigned(self: RawItem) u32 { var v: u32 = 0; for (self.data, 0..) |b, i| v |= @as(u32, b) << @intCast(i * 8); return v; }
/// The data as a signed value, sign-extended from its width. /// /// Which items are signed is not a property of the encoding -- the same /// two bytes are a logical minimum of -1 or a report count of 65535 /// depending only on which item they belong to -- so this is applied by /// the caller and never inferred here. pub fn signed(self: RawItem) i32 { const raw = self.unsigned(); return switch (self.data.len) { 0 => 0, 1 => @as(i8, @bitCast(@as(u8, @truncate(raw)))), 2 => @as(i16, @bitCast(@as(u16, @truncate(raw)))), else => @bitCast(raw), }; }};
/// Walks the items of a descriptor.////// Stops at the first malformed item rather than guessing, because a/// descriptor that is wrong about its own lengths says nothing reliable about/// what follows.pub const Iterator = struct { bytes: []const u8, index: usize = 0,
pub fn init(bytes: []const u8) Iterator { return .{ .bytes = bytes }; }
pub fn next(self: *Iterator) ?RawItem { if (self.index >= self.bytes.len) return null; const prefix = self.bytes[self.index];
if (prefix == long_item_prefix) { if (self.index + 2 >= self.bytes.len) return null; const size = self.bytes[self.index + 1]; const tag: u4 = @truncate(self.bytes[self.index + 2]); const start = self.index + 3; if (start + size > self.bytes.len) return null; self.index = start + size; return .{ .type = .reserved, .tag = tag, .data = &.{}, .long_data = self.bytes[start..][0..size], }; }
// A `bSize` of 3 means four bytes, not three. Reading it as three is // the classic way to get a descriptor parser subtly wrong. const size: usize = switch (@as(u2, @truncate(prefix))) { 0 => 0, 1 => 1, 2 => 2, 3 => 4, }; const start = self.index + 1; if (start + size > self.bytes.len) return null; self.index = start + size; return .{ .type = @fromBackingInt(@as(u2, @truncate(prefix >> 2))), .tag = @truncate(prefix >> 4), .data = self.bytes[start..][0..size], }; }};
// ---------------------------------------------------------------------------// Parsed fields// ---------------------------------------------------------------------------
/// Which report a field belongs to.pub const Kind = enum(u2) { input = 0, output = 1, feature = 2,
pub fn format(self: Kind, w: *std.Io.Writer) std.Io.Writer.Error!void { try w.writeAll(@tagName(self)); }};
/// What kind of collection a `Collection` is, from the main item's data.pub const CollectionType = enum(u8) { physical = 0x00, application = 0x01, logical = 0x02, report = 0x03, named_array = 0x04, usage_switch = 0x05, usage_modifier = 0x06, _,};
/// One level of the collection a field sits inside.pub const Collection = struct { type: CollectionType, usage_page: u16, usage: u16,};
/// The data bits of a main item, as the specification names them.////// `constant` and `variable` are the two that change how a field is read at/// all: a constant field is padding, and an array field holds indices into/// its usage range where a variable one holds a value per usage.pub const Flags = packed struct(u32) { constant: bool = false, variable: bool = false, relative: bool = false, wrap: bool = false, non_linear: bool = false, no_preferred_state: bool = false, null_state: bool = false, @"volatile": bool = false, buffered_bytes: bool = false, _reserved: u23 = 0,
pub fn format(self: Flags, w: *std.Io.Writer) std.Io.Writer.Error!void { try w.writeAll(if (self.constant) "Cnst" else "Data"); try w.writeAll(if (self.variable) ",Var" else ",Ary"); try w.writeAll(if (self.relative) ",Rel" else ",Abs"); if (self.wrap) try w.writeAll(",Wrap"); if (self.non_linear) try w.writeAll(",NonLin"); if (self.no_preferred_state) try w.writeAll(",NoPref"); if (self.null_state) try w.writeAll(",Null"); if (self.@"volatile") try w.writeAll(",Vol"); if (self.buffered_bytes) try w.writeAll(",Buff"); }};
/// How a main item names its usages.pub const Usages = union(enum) { /// None were declared, which is legal and usual for padding. none, /// `Usage Minimum` through `Usage Maximum`. range: struct { min: u32, max: u32 }, /// Individually listed, as extended usages -- page in the high sixteen /// bits. Points into the parser and is valid until its next `next`. list: []const u32,};
/// One main item: a run of `count` fields of `bit_size` bits each.////// A main item is kept whole rather than expanded into one `Field` per/// element, because that is how the descriptor says it and because for an/// array the elements are not separate things at all -- they are slots, and/// the usages describe the values that may appear in them rather than what/// each slot means. `usageAt` resolves the per-element usage where that is a/// meaningful question.pub const Field = struct { report_id: u8, kind: Kind, /// Where element zero starts, in bits from the beginning of the report /// **body** -- that is, after the report ID byte if the device uses them. bit_offset: u32, bit_size: u16, count: u16,
/// The usage page in force, which the usages in `usages` fall under /// unless one carries its own page in its high bits. usage_page: u16, usages: Usages,
logical_min: i32, logical_max: i32, physical_min: i32, physical_max: i32, unit: u32, unit_exponent: i32,
flags: Flags,
/// The collections enclosing this field, outermost first. Points into the /// parser and is valid until its next `next`. collections: []const Collection,
/// How many bits the whole item occupies. pub fn totalBits(self: Field) u32 { return @as(u32, self.bit_size) * self.count; }
/// The usage of element `index`, or `null` when the question does not /// apply. /// /// It does not apply to an array, where a slot holds an index rather than /// meaning something on its own, nor to an item that declared no usages. /// For a variable item the specification says usage *i* belongs to /// element *i*, and that the last usage repeats for any elements beyond /// the list -- which is how one `Usage` and a count of eight describes /// eight identical things. pub fn usageAt(self: Field, index: u16) ?u32 { if (!self.flags.variable) return null; if (index >= self.count) return null; return switch (self.usages) { .none => null, .range => |r| blk: { const v = r.min + index; break :blk if (v > r.max) r.max else v; }, .list => |list| blk: { if (list.len == 0) break :blk null; break :blk if (index < list.len) list[index] else list[list.len - 1]; }, }; }
/// Whether element `index` fits inside a report body of `len` bytes. pub fn fits(self: Field, len: usize, index: u16) bool { if (index >= self.count) return false; if (self.bit_size == 0 or self.bit_size > 32) return false; const start = self.bit_offset + @as(u32, self.bit_size) * index; return start + self.bit_size <= len * 8; }
/// Whether this field's values are signed. /// /// A negative logical minimum is the only thing that says so. The bits /// cannot: the same eight bits are 200 or -56 depending only on what the /// descriptor said about them. pub fn isSigned(self: Field) bool { return self.logical_min < 0; }
pub const InsertError = error{ /// The field does not fit in the body given, which is what a report /// buffer too short for the device looks like. DoesNotFit, /// The value will not fit the field's width, or falls outside the /// logical range the descriptor declared. OutOfRange, };
/// Write `value` into element `index` of a report body. /// /// The counterpart of `extract`, and takes the body the same way: without /// any leading report ID byte. Only the field's own bits are touched, so /// several fields can be written into one report in any order, and the /// bits between them are left as the caller left them. /// /// Refuses a value that will not fit rather than truncating it, and a /// value outside the declared logical range rather than clamping it. /// Silently writing something other than what was asked for is how a /// device ends up doing something other than what was meant, and the /// caller is better placed to decide what to do about it. pub fn insert(self: Field, body: []u8, index: u16, value: i64) InsertError!void { if (!self.fits(body.len, index)) return error.DoesNotFit;
// A range of zero to zero is an undeclared range rather than a field // that may only hold zero -- padding has one, and so do plenty of // vendor descriptors -- so it is not enforced. if (self.logical_min != self.logical_max) { if (value < self.logical_min or value > self.logical_max) return error.OutOfRange; }
// And whatever the descriptor claims, the value has to fit the bits // there are. if (self.isSigned()) { const limit = @as(i64, 1) << @intCast(self.bit_size - 1); if (value < -limit or value > limit - 1) return error.OutOfRange; } else { if (value < 0) return error.OutOfRange; if (self.bit_size < 63 and value >= @as(i64, 1) << @intCast(self.bit_size)) { return error.OutOfRange; } }
const start = self.bit_offset + @as(u32, self.bit_size) * index; const raw: u64 = @bitCast(value); var written: u16 = 0; while (written < self.bit_size) : (written += 1) { const bit = start + written; const mask = @as(u8, 1) << @intCast(bit % 8); const set = (raw >> @intCast(written)) & 1 != 0; if (set) { body[bit / 8] |= mask; } else { body[bit / 8] &= ~mask; } } }
/// Read element `index` out of a report body. /// /// `body` is the report **without** any leading report ID byte: on a /// device that uses report IDs, pass `report[1..]`. Returns `null` when /// the field does not fit in what was given, which is what a short report /// looks like. /// /// The value is sign-extended when the field's logical minimum is /// negative, because that is the only thing that says a field is signed -- /// the bits themselves cannot say. pub fn extract(self: Field, body: []const u8, index: u16) ?i64 { if (index >= self.count) return null; const start = self.bit_offset + @as(u32, self.bit_size) * index; if (self.bit_size == 0 or self.bit_size > 32) return null; if (start + self.bit_size > body.len * 8) return null;
var raw: u64 = 0; var taken: u16 = 0; while (taken < self.bit_size) { const bit = start + taken; const byte = body[bit / 8]; const value: u64 = (byte >> @intCast(bit % 8)) & 1; raw |= value << @intCast(taken); taken += 1; }
if (self.logical_min < 0 and self.bit_size < 64) { const sign_bit = @as(u64, 1) << @intCast(self.bit_size - 1); if (raw & sign_bit != 0) { const extended = raw | ~((@as(u64, 1) << @intCast(self.bit_size)) - 1); return @bitCast(extended); } } return @intCast(raw); }};
// ---------------------------------------------------------------------------// The parser// ---------------------------------------------------------------------------
/// Item tags, by type. Section 6.2.2.4 through 6.2.2.8.const main_tag = struct { const input = 0x8; const output = 0x9; const collection = 0xA; const feature = 0xB; const end_collection = 0xC;};
const global_tag = struct { const usage_page = 0x0; const logical_minimum = 0x1; const logical_maximum = 0x2; const physical_minimum = 0x3; const physical_maximum = 0x4; const unit_exponent = 0x5; const unit = 0x6; const report_size = 0x7; const report_id = 0x8; const report_count = 0x9; const push = 0xA; const pop = 0xB;};
const local_tag = struct { const usage = 0x0; const usage_minimum = 0x1; const usage_maximum = 0x2; const delimiter = 0xA;};
/// The global item state, which `Push` and `Pop` save and restore.const Globals = struct { usage_page: u16 = 0, logical_min: i32 = 0, logical_max: i32 = 0, physical_min: i32 = 0, physical_max: i32 = 0, unit: u32 = 0, unit_exponent: i32 = 0, report_size: u16 = 0, report_count: u16 = 0, report_id: u8 = 0,};
/// How many report IDs one descriptor may use before the parser gives up.////// A device with more than this many distinct reports is not something that/// has been seen; the limit exists so that the bit-offset bookkeeping can be/// a flat array rather than a map.pub const max_report_ids = 32;
/// How deep `Push` may nest.pub const max_global_depth = 8;
/// How deep collections may nest.pub const max_collection_depth = 16;
/// How many usages one main item may list individually.pub const max_usages = 128;
pub const Error = error{ /// The descriptor ended in the middle of an item, or an item's length ran /// past the end. Malformed, /// An `End Collection` with no open collection, or a descriptor that ends /// with one still open. UnbalancedCollection, /// More nesting, report IDs or listed usages than this parser holds. The /// limits are `max_*` above. TooComplex,};
/// Walks a descriptor and yields one `Field` per main item.////// ```/// var parser: hidapi.descriptor.Parser = .init(bytes);/// while (try parser.next()) |field| {/// if (field.kind != .input or field.flags.constant) continue;/// for (0..field.count) |i| {/// const value = field.extract(report, @intCast(i)) orelse continue;/// std.debug.print("{x:0>8} = {d}\n", .{ field.usageAt(@intCast(i)) orelse 0, value });/// }/// }/// ```pub const Parser = struct { it: Iterator,
globals: Globals = .{}, global_stack: [max_global_depth]Globals = undefined, global_depth: u8 = 0,
/// Local item state, cleared after every main item, as 6.2.2.8 requires. usage_buf: [max_usages]u32 = undefined, usage_len: u8 = 0, usage_min: ?u32 = null, usage_max: ?u32 = null, /// Depth of an open `Delimiter` set. Inside one, only the first usage is /// kept: the specification says the first is the preferred one and the /// rest are aliases for systems that do not understand it. delimiter_depth: u8 = 0,
collections: [max_collection_depth]Collection = undefined, collection_depth: u8 = 0,
/// Bit offsets reached so far, per report ID and per report type. The /// three types are laid out independently, which is why this is not one /// counter. report_ids: [max_report_ids]u8 = undefined, offsets: [max_report_ids][3]u32 = undefined, report_id_count: u8 = 0,
pub fn init(bytes: []const u8) Parser { return .{ .it = .init(bytes) }; }
/// The next field, or `null` at the end of the descriptor. pub fn next(self: *Parser) Error!?Field { while (self.it.next()) |raw| { switch (raw.type) { .main => if (try self.main(raw)) |field| return field, .global => try self.global(raw), .local => try self.local(raw), // A long item, or a reserved short one. Both are skipped, // and neither clears the local state -- only a main item // does that. .reserved => {}, } } else { if (self.it.index < self.it.bytes.len) return error.Malformed; if (self.collection_depth != 0) return error.UnbalancedCollection; return null; } }
fn main(self: *Parser, raw: RawItem) Error!?Field { defer self.clearLocals();
switch (raw.tag) { main_tag.collection => { if (self.collection_depth >= max_collection_depth) return error.TooComplex; // A collection's usage is the first one declared for it. const usage = self.firstLocalUsage(); self.collections[self.collection_depth] = .{ .type = @fromBackingInt(@as(u8, @truncate(raw.unsigned()))), .usage_page = @truncate(usage >> 16), .usage = @truncate(usage), }; self.collection_depth += 1; return null; }, main_tag.end_collection => { if (self.collection_depth == 0) return error.UnbalancedCollection; self.collection_depth -= 1; return null; }, main_tag.input, main_tag.output, main_tag.feature => {}, // A main item this parser does not know. Its local state is still // consumed, which is what `defer` above does. else => return null, }
const kind: Kind = switch (raw.tag) { main_tag.input => .input, main_tag.output => .output, else => .feature, };
const slot = try self.reportSlot(self.globals.report_id); const bit_offset = self.offsets[slot][@backingInt(kind)]; const total = @as(u32, self.globals.report_size) * self.globals.report_count; self.offsets[slot][@backingInt(kind)] = bit_offset + total;
return .{ .report_id = self.globals.report_id, .kind = kind, .bit_offset = bit_offset, .bit_size = self.globals.report_size, .count = self.globals.report_count, .usage_page = self.globals.usage_page, .usages = self.resolveUsages(), .logical_min = self.globals.logical_min, .logical_max = self.globals.logical_max, .physical_min = self.globals.physical_min, .physical_max = self.globals.physical_max, .unit = self.globals.unit, .unit_exponent = self.globals.unit_exponent, .flags = @bitCast(raw.unsigned()), .collections = self.collections[0..self.collection_depth], }; }
fn global(self: *Parser, raw: RawItem) Error!void { switch (raw.tag) { global_tag.usage_page => self.globals.usage_page = @truncate(raw.unsigned()), global_tag.logical_minimum => self.globals.logical_min = raw.signed(), global_tag.logical_maximum => { // A logical maximum is signed by the specification, and a // device declaring a byte field writes 255 in one byte, which // read as signed is -1. Taking the unsigned reading when the // minimum is not negative is what every other parser does, // and without it half the fields on a real device come back // with an inverted range. self.globals.logical_max = if (self.globals.logical_min >= 0) @bitCast(raw.unsigned()) else raw.signed(); }, global_tag.physical_minimum => self.globals.physical_min = raw.signed(), global_tag.physical_maximum => { self.globals.physical_max = if (self.globals.physical_min >= 0) @bitCast(raw.unsigned()) else raw.signed(); }, global_tag.unit_exponent => { // A four bit two's complement value, so 0xF is -1. const nibble: u4 = @truncate(raw.unsigned()); self.globals.unit_exponent = @as(i4, @bitCast(nibble)); }, global_tag.unit => self.globals.unit = raw.unsigned(), global_tag.report_size => self.globals.report_size = @truncate(raw.unsigned()), global_tag.report_id => self.globals.report_id = @truncate(raw.unsigned()), global_tag.report_count => self.globals.report_count = @truncate(raw.unsigned()), global_tag.push => { if (self.global_depth >= max_global_depth) return error.TooComplex; self.global_stack[self.global_depth] = self.globals; self.global_depth += 1; }, global_tag.pop => { if (self.global_depth == 0) return error.Malformed; self.global_depth -= 1; self.globals = self.global_stack[self.global_depth]; }, else => {}, } }
fn local(self: *Parser, raw: RawItem) Error!void { switch (raw.tag) { local_tag.usage => { // Inside a delimited set only the first usage counts; the // rest are aliases of it. if (self.delimiter_depth > 0 and self.usage_len > 0) return; if (self.usage_len >= max_usages) return error.TooComplex; self.usage_buf[self.usage_len] = self.extendedUsage(raw); self.usage_len += 1; }, local_tag.usage_minimum => self.usage_min = self.extendedUsage(raw), local_tag.usage_maximum => self.usage_max = self.extendedUsage(raw), local_tag.delimiter => { if (raw.unsigned() != 0) { self.delimiter_depth +|= 1; } else if (self.delimiter_depth > 0) { self.delimiter_depth -= 1; } }, // Designator and string items carry indices into descriptors this // library does not read, so they are consumed and dropped. else => {}, } }
/// A usage item of four bytes carries its own page in the high half; a /// shorter one falls under the global usage page. fn extendedUsage(self: *const Parser, raw: RawItem) u32 { const value = raw.unsigned(); if (raw.data.len == 4) return value; return (@as(u32, self.globals.usage_page) << 16) | value; }
fn firstLocalUsage(self: *const Parser) u32 { if (self.usage_len > 0) return self.usage_buf[0]; if (self.usage_min) |min| return min; return @as(u32, self.globals.usage_page) << 16; }
fn resolveUsages(self: *const Parser) Usages { if (self.usage_min) |min| { // A range wins over a list: a descriptor that declares both is // describing a range whose members it also happens to name. return .{ .range = .{ .min = min, .max = self.usage_max orelse min } }; } if (self.usage_len > 0) return .{ .list = self.usage_buf[0..self.usage_len] }; return .none; }
fn clearLocals(self: *Parser) void { self.usage_len = 0; self.usage_min = null; self.usage_max = null; self.delimiter_depth = 0; }
/// The bookkeeping slot for one report ID, creating it on first sight. fn reportSlot(self: *Parser, id: u8) Error!u8 { for (self.report_ids[0..self.report_id_count], 0..) |seen, i| { if (seen == id) return @intCast(i); } if (self.report_id_count >= max_report_ids) return error.TooComplex; const slot = self.report_id_count; self.report_ids[slot] = id; self.offsets[slot] = @splat(0); self.report_id_count += 1; return slot; }};
/// The length in bytes of one report, counting the report ID byte when the/// descriptor uses them.////// Walks the whole descriptor, so a caller wanting several lengths should/// collect them from one `Parser` pass instead.pub fn reportLength(bytes: []const u8, kind: Kind, report_id: u8) Error!usize { var parser: Parser = .init(bytes); var bits: u32 = 0; var numbered = false; while (try parser.next()) |field| { if (field.report_id != 0) numbered = true; if (field.kind != kind or field.report_id != report_id) continue; bits = @max(bits, field.bit_offset + field.totalBits()); } if (bits == 0) return 0; return (bits + 7) / 8 + @intFromBool(numbered);}
// ---------------------------------------------------------------------------// Parser tests//// The two descriptors below were taken verbatim off devices on my desk, and// every assertion about them was worked out by hand from the bytes. They are// the useful kind of fixture: a real mouse exercises a usage range, a usage// list, three different usage pages and a signed sixteen bit field, and a real// keyboard exercises input, output and feature reports laid out independently,// an array item and constant padding.// ---------------------------------------------------------------------------
/// A Logitech G703 mouse. No report IDs, one eight byte input report.const mouse_descriptor = [_]u8{ 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x02, // Usage (Mouse) 0xA1, 0x01, // Collection (Application) 0x09, 0x01, // Usage (Pointer) 0xA1, 0x00, // Collection (Physical) 0x95, 0x10, // Report Count (16) 0x75, 0x01, // Report Size (1) 0x15, 0x00, // Logical Minimum (0) 0x25, 0x01, // Logical Maximum (1) 0x05, 0x09, // Usage Page (Button) 0x19, 0x01, // Usage Minimum (1) 0x29, 0x10, // Usage Maximum (16) 0x81, 0x02, // Input (Data, Var, Abs) 0x95, 0x02, // Report Count (2) 0x75, 0x10, // Report Size (16) 0x16, 0x01, 0x80, // Logical Minimum (-32767) 0x26, 0xFF, 0x7F, // Logical Maximum (32767) 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x30, // Usage (X) 0x09, 0x31, // Usage (Y) 0x81, 0x06, // Input (Data, Var, Rel) 0x95, 0x01, // Report Count (1) 0x75, 0x08, // Report Size (8) 0x15, 0x81, // Logical Minimum (-127) 0x25, 0x7F, // Logical Maximum (127) 0x09, 0x38, // Usage (Wheel) 0x81, 0x06, // Input (Data, Var, Rel) 0x95, 0x01, // Report Count (1) 0x05, 0x0C, // Usage Page (Consumer) 0x0A, 0x38, 0x02, // Usage (AC Pan) 0x81, 0x06, // Input (Data, Var, Rel) 0xC0, // End Collection 0xC0, // End Collection};
/// A YubiKey's keyboard interface. Input, output and feature reports.const keyboard_descriptor = [_]u8{ 0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x06, // Usage (Keyboard) 0xA1, 0x01, // Collection (Application) 0x05, 0x07, // Usage Page (Keyboard/Keypad) 0x19, 0xE0, // Usage Minimum (Left Control) 0x29, 0xE7, // Usage Maximum (Right GUI) 0x15, 0x00, // Logical Minimum (0) 0x25, 0x01, // Logical Maximum (1) 0x75, 0x01, // Report Size (1) 0x95, 0x08, // Report Count (8) 0x81, 0x02, // Input (Data, Var, Abs) -- the eight modifier keys 0x95, 0x01, // Report Count (1) 0x75, 0x08, // Report Size (8) 0x81, 0x01, // Input (Cnst, Ary, Abs) -- one reserved byte 0x95, 0x05, // Report Count (5) 0x75, 0x01, // Report Size (1) 0x05, 0x08, // Usage Page (LED) 0x19, 0x01, // Usage Minimum (Num Lock) 0x29, 0x05, // Usage Maximum (Kana) 0x91, 0x02, // Output (Data, Var, Abs) -- five LEDs 0x95, 0x01, // Report Count (1) 0x75, 0x03, // Report Size (3) 0x91, 0x01, // Output (Cnst, Ary, Abs) -- three bits of padding 0x95, 0x06, // Report Count (6) 0x75, 0x08, // Report Size (8) 0x15, 0x00, // Logical Minimum (0) 0x25, 0x65, // Logical Maximum (101) 0x05, 0x07, // Usage Page (Keyboard/Keypad) 0x19, 0x00, // Usage Minimum (0) 0x29, 0x65, // Usage Maximum (101) 0x81, 0x00, // Input (Data, Ary, Abs) -- six key slots 0x09, 0x03, // Usage (0x03) 0x75, 0x08, // Report Size (8) 0x95, 0x08, // Report Count (8) 0xB1, 0x02, // Feature (Data, Var, Abs) 0xC0, // End Collection};
fn collect(bytes: []const u8, out: *std.ArrayList(Field), gpa: std.mem.Allocator) !void { var parser: Parser = .init(bytes); while (try parser.next()) |field| { // The collections and usage list alias the parser, so anything kept // past the next call has to be copied. The tests only keep the scalar // parts, which is the usual thing to want. var copy = field; copy.collections = &.{}; if (copy.usages == .list) copy.usages = .none; try out.append(gpa, copy); }}
test "a real mouse descriptor parses field by field" { const gpa = std.testing.allocator; var fields: std.ArrayList(Field) = .empty; defer fields.deinit(gpa); try collect(&mouse_descriptor, &fields, gpa);
// Four Input items: buttons, X and Y together, the wheel, and AC Pan. try std.testing.expectEqual(@as(usize, 4), fields.items.len);
// Sixteen buttons, one bit each, first in the report. const buttons = fields.items[0]; try std.testing.expectEqual(Kind.input, buttons.kind); try std.testing.expectEqual(@as(u32, 0), buttons.bit_offset); try std.testing.expectEqual(@as(u16, 1), buttons.bit_size); try std.testing.expectEqual(@as(u16, 16), buttons.count); try std.testing.expectEqual(@as(u16, 0x09), buttons.usage_page); try std.testing.expectEqual(@as(i32, 0), buttons.logical_min); try std.testing.expectEqual(@as(i32, 1), buttons.logical_max); try std.testing.expect(buttons.flags.variable); try std.testing.expect(!buttons.flags.relative); // A usage range, so element three is button four. try std.testing.expectEqual(@as(?u32, 0x0009_0004), buttons.usageAt(3));
// X and Y: one main item, count two, with two usages listed. const xy = fields.items[1]; try std.testing.expectEqual(@as(u32, 16), xy.bit_offset); try std.testing.expectEqual(@as(u16, 16), xy.bit_size); try std.testing.expectEqual(@as(u16, 2), xy.count); try std.testing.expectEqual(@as(i32, -32767), xy.logical_min); try std.testing.expectEqual(@as(i32, 32767), xy.logical_max); try std.testing.expect(xy.flags.relative);
const wheel = fields.items[2]; try std.testing.expectEqual(@as(u32, 48), wheel.bit_offset); try std.testing.expectEqual(@as(i32, -127), wheel.logical_min); try std.testing.expectEqual(@as(i32, 127), wheel.logical_max);
// The consumer page's AC Pan. Its usage is a listed one, which `collect` // drops because the list aliases the parser -- see the streaming test // below for the usage itself. const pan = fields.items[3]; try std.testing.expectEqual(@as(u32, 56), pan.bit_offset); try std.testing.expectEqual(@as(u16, 0x0C), pan.usage_page);
// Eight bytes in total, and no report ID byte. try std.testing.expectEqual(@as(usize, 8), try reportLength(&mouse_descriptor, .input, 0));}
test "usages resolve per element for a list and for a range" { var parser: Parser = .init(&mouse_descriptor);
_ = try parser.next(); // buttons const xy = (try parser.next()).?; // Listed individually, so element zero is X and element one is Y. try std.testing.expectEqual(@as(?u32, 0x0001_0030), xy.usageAt(0)); try std.testing.expectEqual(@as(?u32, 0x0001_0031), xy.usageAt(1)); try std.testing.expectEqual(@as(?u32, null), xy.usageAt(2));
_ = try parser.next(); // wheel const pan = (try parser.next()).?; // A four byte usage item, carrying its own page in the high half, which // has to win over the global usage page rather than being truncated into // it. try std.testing.expectEqual(@as(?u32, 0x000C_0238), pan.usageAt(0));}
test "a collection path is reported outermost first" { var parser: Parser = .init(&mouse_descriptor); const buttons = (try parser.next()).?;
try std.testing.expectEqual(@as(usize, 2), buttons.collections.len); try std.testing.expectEqual(CollectionType.application, buttons.collections[0].type); try std.testing.expectEqual(@as(u16, 0x01), buttons.collections[0].usage_page); try std.testing.expectEqual(@as(u16, 0x02), buttons.collections[0].usage); // Mouse try std.testing.expectEqual(CollectionType.physical, buttons.collections[1].type); try std.testing.expectEqual(@as(u16, 0x01), buttons.collections[1].usage); // Pointer}
test "a real report decodes into the values it carries" { var parser: Parser = .init(&mouse_descriptor); const buttons = (try parser.next()).?; const xy = (try parser.next()).?; const wheel = (try parser.next()).?;
// Button 1 down, X = -2, Y = +1, wheel = -1. const report = [_]u8{ 0x01, 0x00, // buttons 1..16 0xFE, 0xFF, // X = -2 0x01, 0x00, // Y = 1 0xFF, // wheel = -1 0x00, // AC Pan = 0 };
try std.testing.expectEqual(@as(?i64, 1), buttons.extract(&report, 0)); try std.testing.expectEqual(@as(?i64, 0), buttons.extract(&report, 1)); // Signed, because the logical minimum is negative. try std.testing.expectEqual(@as(?i64, -2), xy.extract(&report, 0)); try std.testing.expectEqual(@as(?i64, 1), xy.extract(&report, 1)); try std.testing.expectEqual(@as(?i64, -1), wheel.extract(&report, 0));
// A report too short for the field is not guessed at. try std.testing.expectEqual(@as(?i64, null), wheel.extract(report[0..4], 0));}
test "the three report types are laid out independently" { const gpa = std.testing.allocator; var fields: std.ArrayList(Field) = .empty; defer fields.deinit(gpa); try collect(&keyboard_descriptor, &fields, gpa);
try std.testing.expectEqual(@as(usize, 6), fields.items.len);
// Input: modifiers at bit 0, a reserved byte at 8, six key slots at 16. try std.testing.expectEqual(Kind.input, fields.items[0].kind); try std.testing.expectEqual(@as(u32, 0), fields.items[0].bit_offset); try std.testing.expectEqual(@as(u32, 8), fields.items[1].bit_offset); try std.testing.expect(fields.items[1].flags.constant); try std.testing.expectEqual(@as(u32, 16), fields.items[4].bit_offset);
// Output starts again at bit 0 rather than continuing from the input. try std.testing.expectEqual(Kind.output, fields.items[2].kind); try std.testing.expectEqual(@as(u32, 0), fields.items[2].bit_offset); try std.testing.expectEqual(@as(u32, 5), fields.items[3].bit_offset);
// And so does the feature report. try std.testing.expectEqual(Kind.feature, fields.items[5].kind); try std.testing.expectEqual(@as(u32, 0), fields.items[5].bit_offset);
try std.testing.expectEqual(@as(usize, 8), try reportLength(&keyboard_descriptor, .input, 0)); try std.testing.expectEqual(@as(usize, 1), try reportLength(&keyboard_descriptor, .output, 0)); try std.testing.expectEqual(@as(usize, 8), try reportLength(&keyboard_descriptor, .feature, 0));}
test "an array item has no per-element usage" { const gpa = std.testing.allocator; var fields: std.ArrayList(Field) = .empty; defer fields.deinit(gpa); try collect(&keyboard_descriptor, &fields, gpa);
const keys = fields.items[4]; try std.testing.expect(!keys.flags.variable); try std.testing.expectEqual(@as(u16, 6), keys.count); // A slot holds a key code rather than meaning something on its own, so // asking what element two *is* has no answer -- the usage range describes // the values that may appear, not the slots. try std.testing.expectEqual(@as(?u32, null), keys.usageAt(2));}
test "a logical maximum of 255 is not minus one" { // The specification calls the item signed, and a device writes 255 in one // byte. Read signed that is -1, which inverts the range of a great many // real fields. const bytes = [_]u8{ 0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, 0x15, 0x00, // Logical Minimum (0) 0x26, 0xFF, 0x00, // Logical Maximum (255), two bytes 0x25, 0xFF, // Logical Maximum (255), one byte 0x75, 0x08, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02, 0xC0, }; var parser: Parser = .init(&bytes); const field = (try parser.next()).?; try std.testing.expectEqual(@as(i32, 0), field.logical_min); try std.testing.expectEqual(@as(i32, 255), field.logical_max);}
test "push and pop save and restore the global state" { const bytes = [_]u8{ 0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, 0x75, 0x08, 0x95, 0x01, 0x15, 0x00, 0x25, 0x7F, 0xA4, // Push 0x75, 0x10, // Report Size (16) 0x09, 0x30, 0x81, 0x02, // a 16 bit field 0xB4, // Pop 0x09, 0x31, 0x81, 0x02, // back to 8 bits 0xC0, }; var parser: Parser = .init(&bytes); const wide = (try parser.next()).?; try std.testing.expectEqual(@as(u16, 16), wide.bit_size); const narrow = (try parser.next()).?; try std.testing.expectEqual(@as(u16, 8), narrow.bit_size); try std.testing.expectEqual(@as(u32, 16), narrow.bit_offset);}
test "local state is cleared by every main item" { // The usage declared before the first Input must not leak onto the // second, which would otherwise report the same usage twice. const bytes = [_]u8{ 0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, 0x75, 0x08, 0x95, 0x01, 0x15, 0x00, 0x25, 0x7F, 0x09, 0x30, 0x81, 0x02, 0x81, 0x02, // no usage of its own 0xC0, }; var parser: Parser = .init(&bytes); const first = (try parser.next()).?; try std.testing.expectEqual(@as(?u32, 0x0001_0030), first.usageAt(0)); const second = (try parser.next()).?; try std.testing.expectEqual(@as(?u32, null), second.usageAt(0));}
test "report ids give each report its own bit offsets" { const bytes = [_]u8{ 0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, 0x75, 0x08, 0x95, 0x01, 0x15, 0x00, 0x25, 0x7F, 0x85, 0x01, // Report ID (1) 0x09, 0x30, 0x81, 0x02, 0x85, 0x02, // Report ID (2) 0x09, 0x31, 0x81, 0x02, 0x85, 0x01, // back to Report ID 1 0x09, 0x32, 0x81, 0x02, 0xC0, }; var parser: Parser = .init(&bytes); const a = (try parser.next()).?; const b = (try parser.next()).?; const c = (try parser.next()).?;
try std.testing.expectEqual(@as(u8, 1), a.report_id); try std.testing.expectEqual(@as(u32, 0), a.bit_offset); // Report 2 starts over. try std.testing.expectEqual(@as(u8, 2), b.report_id); try std.testing.expectEqual(@as(u32, 0), b.bit_offset); // And report 1 carries on where it left off. try std.testing.expectEqual(@as(u8, 1), c.report_id); try std.testing.expectEqual(@as(u32, 8), c.bit_offset);
// The length counts the report ID byte, because this device sends one. try std.testing.expectEqual(@as(usize, 3), try reportLength(&bytes, .input, 1));}
test "an unbalanced collection is an error rather than a guess" { // Ends with a collection still open. try std.testing.expectError(error.UnbalancedCollection, drain(&.{ 0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, })); // Closes one that was never opened. try std.testing.expectError(error.UnbalancedCollection, drain(&.{ 0x05, 0x01, 0xC0, }));}
test "a truncated item is an error rather than a partial read" { // A usage page item that promises two bytes and supplies one. try std.testing.expectError(error.Malformed, drain(&.{ 0x06, 0x00 }));}
fn drain(bytes: []const u8) Error!void { var parser: Parser = .init(bytes); while (try parser.next()) |_| {}}
test "a long item is stepped over" { const bytes = [_]u8{ 0xFE, 0x02, 0x00, 0xAA, 0xBB, // long item, two data bytes 0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, 0x75, 0x08, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02, 0xC0, }; var parser: Parser = .init(&bytes); const field = (try parser.next()).?; try std.testing.expectEqual(@as(u16, 8), field.bit_size); try std.testing.expect(try parser.next() == null);}
test "a value written is the value read back" { // The property that matters: for every width, signed and unsigned, at an // offset that is not byte aligned, insert and extract have to agree. var body: [16]u8 = undefined;
for ([_]bool{ false, true }) |signed| { var size: u16 = 1; while (size <= 32) : (size += 1) { // Skip the one-bit signed case, which can only hold 0 and -1 and // is not a thing a descriptor declares. if (signed and size == 1) continue;
const limit: i64 = @as(i64, 1) << @intCast(size - 1); const field: Field = .{ .report_id = 0, .kind = .output, // Deliberately not byte aligned. .bit_offset = 3, .bit_size = size, .count = 2, .usage_page = 0, .usages = .none, // Signed fields declare their range; unsigned ones here // leave it undeclared, so the only bound is the width. A // descriptor cannot state the maximum of a 32 bit unsigned // field anyway -- logical values are signed 32 bit. .logical_min = if (signed) @intCast(-limit) else 0, .logical_max = if (signed) @intCast(limit - 1) else 0, .physical_min = 0, .physical_max = 0, .unit = 0, .unit_exponent = 0, .flags = .{ .variable = true }, .collections = &.{}, };
const unsigned_max: i64 = (@as(i64, 1) << @intCast(size)) - 1; const values = [_]i64{ 0, 1, if (signed) -1 else 1, if (signed) -limit else 0, if (signed) limit - 1 else unsigned_max, }; for (values) |value| { @memset(&body, 0xA5); try field.insert(&body, 0, value); try std.testing.expectEqual(@as(?i64, value), field.extract(&body, 0));
// And the second element, so that the index arithmetic is // checked rather than assumed. try field.insert(&body, 1, value); try std.testing.expectEqual(@as(?i64, value), field.extract(&body, 1)); // Writing the second must not have disturbed the first. try std.testing.expectEqual(@as(?i64, value), field.extract(&body, 0)); } } }}
test "writing a field leaves every other bit alone" { // Four bits at offset 2, written into a body that is otherwise all ones. const field: Field = .{ .report_id = 0, .kind = .output, .bit_offset = 2, .bit_size = 4, .count = 1, .usage_page = 0, .usages = .none, .logical_min = 0, .logical_max = 15, .physical_min = 0, .physical_max = 0, .unit = 0, .unit_exponent = 0, .flags = .{ .variable = true }, .collections = &.{}, };
var body = [_]u8{ 0xFF, 0xFF }; try field.insert(&body, 0, 0b0101); // Bits 2..5 become 0101; bits 0, 1, 6 and 7 stay set. try std.testing.expectEqual(@as(u8, 0b1101_0111), body[0]); try std.testing.expectEqual(@as(u8, 0xFF), body[1]);
// Zeroes have to be written as well as ones, or a field can only ever // gain bits. try field.insert(&body, 0, 0); try std.testing.expectEqual(@as(u8, 0b1100_0011), body[0]);}
test "a value that will not fit is refused rather than truncated" { const field: Field = .{ .report_id = 0, .kind = .output, .bit_offset = 0, .bit_size = 8, .count = 1, .usage_page = 0, .usages = .none, .logical_min = 0, .logical_max = 100, .physical_min = 0, .physical_max = 0, .unit = 0, .unit_exponent = 0, .flags = .{ .variable = true }, .collections = &.{}, };
var body = [_]u8{0}; // Outside the declared logical range, though it would fit the bits. try std.testing.expectError(error.OutOfRange, field.insert(&body, 0, 200)); try std.testing.expectError(error.OutOfRange, field.insert(&body, 0, -1)); // Past the end of the item. try std.testing.expectError(error.DoesNotFit, field.insert(&body, 1, 0)); // A body too short for the field. try std.testing.expectError(error.DoesNotFit, field.insert(body[0..0], 0, 0)); // Nothing was written by any of those. try std.testing.expectEqual(@as(u8, 0), body[0]);
try field.insert(&body, 0, 100); try std.testing.expectEqual(@as(u8, 100), body[0]);}
test "a field wider than its declared range is still bounded by its bits" { // An undeclared logical range -- zero to zero -- is not enforced, but the // width always is, or the write would run into the next field. const field: Field = .{ .report_id = 0, .kind = .output, .bit_offset = 0, .bit_size = 4, .count = 1, .usage_page = 0, .usages = .none, .logical_min = 0, .logical_max = 0, .physical_min = 0, .physical_max = 0, .unit = 0, .unit_exponent = 0, .flags = .{ .variable = true }, .collections = &.{}, };
var body = [_]u8{0}; try field.insert(&body, 0, 15); try std.testing.expectEqual(@as(u8, 15), body[0]); try std.testing.expectError(error.OutOfRange, field.insert(&body, 0, 16));}
test "a whole output report is assembled from its fields" { // The keyboard's LED report: five one-bit LEDs and three bits of padding, // which is exactly the shape of thing this is for. var parser: Parser = .init(&keyboard_descriptor); var leds: ?Field = null; while (try parser.next()) |field| { if (field.kind == .output and !field.flags.constant) { leds = field; break; } } const field = leds.?; try std.testing.expectEqual(@as(u16, 5), field.count); try std.testing.expectEqual(@as(u16, 1), field.bit_size);
const len = try reportLength(&keyboard_descriptor, .output, 0); try std.testing.expectEqual(@as(usize, 1), len);
var report: [1]u8 = @splat(0); // Num Lock is usage 1, so element zero; Caps Lock is usage 2, element one. try field.insert(&report, 0, 1); try field.insert(&report, 2, 1); try std.testing.expectEqual(@as(u8, 0b0000_0101), report[0]);
try std.testing.expectEqual(@as(?u32, 0x0008_0001), field.usageAt(0)); try std.testing.expectEqual(@as(?u32, 0x0008_0003), field.usageAt(2));}