Skip to content

Optionally associate reports with usages #88

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tuxedo-aer wants to merge 1 commit into
base: main
Choose a base branch
from
+5 −1
Open

Optionally associate reports with usages #88

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,8 @@ pub enum ReportField {
pub struct Report {
/// The (optional) report id associated with the report.
pub report_id: Option<ReportId>,
/// The (optional) usage id associated with the report.
pub usage: Option<Usage>,
/// The size in bits of the report.
pub size_in_bits: usize,
/// The list of fields in the report.
Expand Down
4 changes: 3 additions & 1 deletion src/report_descriptor_parser.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -455,7 +455,9 @@ impl ReportDescriptorParser {
}
}

reports.push(Report { report_id: *id, size_in_bits: bit_position as usize, fields });
let usage = report_data.first().and_then(|d| d.member_of.get(1)).map(|c| c.usage);

@joschock joschock Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this solves for the general case. If you have lots of nested collections like:

Collection (app)
   ReportId (1)
    Collection (logical)
        Collection (logical)
            Collection (logical)
                Usage(bar)
                Collection (logical)
                    Usage(foo)
                    ReportSize(1)
                    ReportCount(1)
                End
            End
        End
        Usage(baz)
        ReportSize(1)
        ReportCount(1)
    End
End

If I follow the code correctly (it's been a while since my head was in this space - so to be 100% confident I'd have to build the descriptor and test it), then the usage associated with the whole report here would be one of the inner collections wrapping the first report field, even though other fields in the same report are not associated with that collection.

I think what you want is something like "usage of the most deeply nested collection that all report fields are members of"? I think that's a bit trickier to compute; but I think something like this would work:

let usage = fields
   .iter()
   .filter(|f|!matches!(f, ReportField::Padding(_)))
   .min_by_key(|f| match f {
       ReportField::Variable(v) => v.member_of.len(),
       ReportField::Array(a) => a.member_of.len(),
       ReportField::Padding(_) => unreachable!(),
   })
   .and_then(|f| match f {
       ReportField::Variable(v) => v.member_of.get(1),
       ReportField::Array(a) => a.member_of.get(1),
       ReportField::Padding(_) => unreachable!(), 
   })   
   .map(|c|c.usage);

Also, I recommend giving a more specific name to the Report.usage field to better describe what it is capturing.

@tuxedo-aer tuxedo-aer Jun 12, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think what you want is something like "usage of the most deeply nested collection that all report fields are members of"? I think that's a bit trickier to compute; but I think something like this would work:

I think that is a correct description of what I want. To give an example, this is an example LampArray report from the HID spec:

0x05, 0x59, // USAGE_PAGE (LightingAndIllumination)
0x09, 0x01, // USAGE (LampArray)
0xa1, 0x01, // COLLECTION (Application)
0x85, 0x01,   // REPORT_ID (1)
0x09, 0x02,   // USAGE (LampArrayAttributesReport)
0xa1, 0x02,   // COLLECTION (Logical)
0x09, 0x03,     // USAGE (LampCount)
0x15, 0x00,     // LOGICAL_MINIMUM (0)
0x27, 0xff, 0xff, 0x00, 0x00, // LOGICAL_MAXIMUM (65535)
0x75, 0x10,     // REPORT_SIZE (16)
0x95, 0x01,     // REPORT_COUNT (1)
0xb1, 0x03,     // FEATURE (Cnst,Var,Abs)
0x09, 0x04,     // USAGE (BoundingBoxWidthInMicrometers)
0x09, 0x05,     // USAGE (BoundingBoxHeightInMicrometers)
0x09, 0x06,     // USAGE (BoundingBoxDepthInMicrometers)
0x09, 0x07,     // USAGE (LampArrayKind)
0x09, 0x08,     // USAGE (MinUpdateIntervalInMicroseconds)
0x15, 0x00,     // LOGICAL_MINIMUM (0)
0x27, 0xff, 0xff, 0xff, 0x7f, // LOGICAL_MAXIMUM (2147483647)
0x75, 0x20,     // REPORT_SIZE (32)
0x95, 0x05,     // REPORT_COUNT (5)
0xb1, 0x03,     // FEATURE (Cnst,Var,Abs)
0xc0,         // END_COLLECTION
...

As you can see, the REPORT_ID is directly followed by a USAGE before a nested collection is opened. If I'm not mistaken, it might even be the case that multiple such usages per report are possible.

In any case, parsing the descriptor without associating reports with the following usages it not very useful because the usage indicates which report is used for what.

I will have a closer look at the code you suggested and will check with my use-case over the next couple of days.

@joschock joschock Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Each field within the report has the full collection chain (i.e. the member_of vec that this code is using should also be available on each report field to the consumer) in addition to the usage for the field itself. On the consumer side, if you are looking at a particular report field within a report, you can evaluate the entire collection chain for that field and see if it has the usage you care about. For example, when processing a report field, you can write logic like "is this report field within a Collection that has LampArray Usage" just by inspecting the data associated with the report field as it is now. But that is per-field, rather than per-report.

I agree that it may be useful to have some notion of what an entire report's "usage" is, but the definition of what a report's "usage" remains a bit unclear (to me, anyway) because of the complicated way that collections can nest and span within and across reports.

The above "usage of the most deeply nested collection that all report fields [of a given report id] are a member of" is my attempt to reduce that to a concrete definition, but I'm open to other well-defined alternatives, if they are more useful.

For example, you could alternatively define a report's "usage" as the set of all usages associated with the report (either as field usages or on collections including or nested within the report), which would allow for membership tests (i.e. "is this Report associated with a "LampArray" usage?" becomes a test on of whether that usage is in the Report usages set).

In any case, I am open to adding usage info at the Report level, if we can settle on a good definition of what that is that works in the general case.


reports.push(Report { report_id: *id, usage, size_in_bits: bit_position as usize, fields });
}

(reports, bad_reports)
Expand Down
Loading