Skip to content

Support Push and Pop global items in report descriptor parsing - #29

Open
Nortaq-PlayNexus wants to merge 1 commit into
usb-tools:mainfrom
Nortaq-PlayNexus:fix/support-push-pop-global-items
Open

Support Push and Pop global items in report descriptor parsing#29
Nortaq-PlayNexus wants to merge 1 commit into
usb-tools:mainfrom
Nortaq-PlayNexus:fix/support-push-pop-global-items

Conversation

@Nortaq-PlayNexus

Copy link
Copy Markdown

Support Push (0b1010) and Pop (0b1011) global items

Summary

The HID specification defines two global item tags that save and restore the global item state table (HID 1.11, sections 6.2.2.7 and 6.2.2.8):

  • Push (0b1010) — saves the current values of all global items onto a state stack
  • Pop (0b1011) — restores the most recently saved state and pops it from the stack

These tags are used by real devices (for example Wacom digitizers) to temporarily change a subset of global items inside a collection and restore them afterwards.

The library already recognized these tags in print(), but _parse() raised NotImplementedError('Unsupported global tag: 0b1010'), making it impossible to parse such descriptors. This PR implements Push/Pop support in _parse().

Changes

  • hid_parser/__init__.py:
    • Track a state stack in _parse() and handle TagGlobal.PUSH / TagGlobal.POP
    • Push saves (usage_page, report_id, report_count, report_size, glob); Pop restores it
    • A Pop without a matching Push raises InvalidReportDescriptor('Pop without a matching Push')
    • Since a Pop can restore a previously saved report_id, report offsets are seeded for that id if missing
  • tests/test_parse.py:
    • Regression test: a descriptor that pushes logical min/max, changes them for two axes, then pops and reuses the original global values
    • Test that an unbalanced Pop raises InvalidReportDescriptor

Verification

  • Parses the descriptor attached to the original issue (Unsupported global tag: 0b1010 #12), which uses Push at byte 538 and Pop at byte 704 (the 17-item pen collection in report id 6), plus a second Push/Pop pair
  • 75 passed (full test suite), mypy clean

Fixes #12

The global item tags Push (0b1010) and Pop (0b1011) are part of the HID
spec (6.2.2.7 / 6.2.2.8) and save/restore the global item state table.
They were previously only recognized by the printer, while the parser
raised NotImplementedError('Unsupported global tag: 0b1010'). (fixes usb-tools#12)
@Nortaq-PlayNexus
Nortaq-PlayNexus requested a review from FFY00 as a code owner August 2, 2026 03:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Unsupported global tag: 0b1010

1 participant