WebSVN – Kolibri OS – Diff – /drivers/usb/usbhid/report.inc


; Parser of HID structures: parse HID report descriptor,
; parse/generate input/output/feature reports.
 
; =============================================================================
; ================================= Constants =================================
; =============================================================================
; Usage codes from HID specification
; Generic Desktop usage page
USAGE_GD_POINTER     = 10001h
USAGE_GD_MOUSE       = 10002h
USAGE_GD_JOYSTICK    = 10004h
USAGE_GD_GAMEPAD     = 10005h
USAGE_GD_KEYBOARD    = 10006h
USAGE_GD_KEYPAD      = 10007h
 
USAGE_GD_X           = 10030h
USAGE_GD_Y           = 10031h
USAGE_GD_Z           = 10032h
USAGE_GD_RX          = 10033h
USAGE_GD_RY          = 10034h
USAGE_GD_RZ          = 10035h
USAGE_GD_SLIDER      = 10036h
USAGE_GD_DIAL        = 10037h
USAGE_GD_WHEEL       = 10038h
 
USAGE_GD_CONS_CTRL   = 0C0001h ; Consumer control (media keys)
 
; Keyboard/Keypad usage page
USAGE_KBD_NOEVENT    = 70000h
USAGE_KBD_ROLLOVER   = 70001h
USAGE_KBD_POSTFAIL   = 70002h
USAGE_KBD_FIRST_KEY  = 70004h ; this is 'A', actually
USAGE_KBD_LCTRL      = 700E0h
USAGE_KBD_LSHIFT     = 700E1h
USAGE_KBD_LALT       = 700E2h
USAGE_KBD_LWIN       = 700E3h
USAGE_KBD_RCTRL      = 700E4h
USAGE_KBD_RSHIFT     = 700E5h
USAGE_KBD_RALT       = 700E6h
USAGE_KBD_RWIN       = 700E7h
 
; LED usage page
USAGE_LED_NUMLOCK    = 80001h
USAGE_LED_CAPSLOCK   = 80002h
USAGE_LED_SCROLLLOCK = 80003h
 
; Button usage page
; First button is USAGE_BUTTON_PAGE+1, second - USAGE_BUTTON_PAGE+2 etc.
USAGE_BUTTON_PAGE    = 90000h
 
; Consumer control usage page
USAGE_CONSUMER       = 0C0000h
 
; Flags for input/output/feature fields
HID_FIELD_CONSTANT   = 1 ; if not, then Data field
HID_FIELD_VARIABLE   = 2 ; if not, then Array field
HID_FIELD_RELATIVE   = 4 ; if not, then Absolute field
HID_FIELD_WRAP       = 8
HID_FIELD_NONLINEAR  = 10h
HID_FIELD_NOPREFERRED= 20h ; no preferred state
HID_FIELD_HASNULL    = 40h ; has null state
HID_FIELD_VOLATILE   = 80h ; for output/feature fields
HID_FIELD_BUFBYTES   = 100h; buffered bytes
 
; Report descriptor can easily describe gigabytes of (meaningless) data.
; Keep report size reasonable to avoid excessive memory allocations and
; calculation overflows; 1 Kb is more than enough (typical size is 3-10 bytes).
MAX_REPORT_BYTES = 1024
 
; =============================================================================
; ================================ Structures =================================
; =============================================================================
; Every meaningful report field group has one or more associated usages.
; Usages can be individual or joined into continuous ranges.
; This structure describes one range or one individual usage in a large array;
; individual usage is equivalent to a range of length 1.
struct usage_range
offset          dd      ?
; Sum of range sizes over all previous array items.
; Size of range a equals
; [a + sizeof.usage_range + usage_range.offset] - [a + usage_range.offset].
; The total sum over all array items immediately follows the array,
; this field must be the first so that the formula above works for the last item.
first_usage     dd      ?
; Usage code for first item in the range.
ends
 
; This structure describes one group of report fields with identical properties.
struct report_field_group
next            dd      ?
; All field groups in one report are organized in a single-linked list.
; This is the next group in the report or 0 for the last group.
size            dd      ?
; Size in bits of one field. Cannot be zero or greater than 32.
count           dd      ?       ; field count, cannot be zero
offset          dd      ?       ; offset from report start, in bits
; Following fields are decoded from report descriptor, see HID spec for details.
flags           dd      ?
logical_minimum dd      ?
logical_maximum dd      ?
physical_minimum dd     ?
physical_maximum dd     ?
unit_exponent   dd      ?
unit            dd      ?
; Following fields are used to speedup extract_field_value.
mask            dd      ?
; Bitmask for all data bits except sign bit:
; (1 shl .size) - 1 for unsigned fields, (1 shl (.size-1)) - 1 for signed fields
sign_mask       dd      ?
; Zero for unsigned fields. Bitmask with sign bit set for signed fields.
common_sizeof   rd      0
; Variable and Array field groups differ significantly.
; Variable field groups are simple. There are .count fields, each field has
; predefined Usage, the content of a field is its value. Each field is
; always present in the report. For Variable field groups, we just keep
; additional .count dwords with usages for individual fields.
; Array field groups are complicated. There are .count uniform fields.
; The content of a field determines Usage; Usages which are currently presented
; in the report have value = 1, other Usages have value = 0. The number of
; possible Usages is limited only by field .size; 32-bit field could encode any
; Usage, so it is unreasonable to keep all Usages in the plain array, as with
; Variable fields. However, many unrelated Usages in one group are meaningless,
; so usually possible values are grouped in sequential ranges; number of ranges
; is limited by report descriptor size (max 0xFFFF bytes should contain all
; information, including usage ranges and field descriptions).
; Also, for Array variables we pass changes in state to drivers, not the state
; itself, because sending information about all possible Usages is inpractical;
; so we should remember the previous state in addition to the current state.
; Thus, for Array variables keep the following information, in this order:
; * some members listed below; note that they do NOT exist for Variable groups;
; * array of usage ranges in form of usage_range structures, including
;   an additional dword after array described in usage_range structure;
; * allocated memory for current values of the report;
; * values of the previous report.
num_values_prev dd      ?       ; number of values in the previous report
num_usage_ranges dd     ?       ; number of usage_range, always nonzero
usages          rd      0
ends
 
; This structure describes one report.
; All reports of one type are organized into a single-linked list.
struct report
next            dd      ?       ; pointer to next report of the same type, if any
size            dd      ?       ; total size in bits
first_field     dd      ?       ; pointer to first report_field_group for this report
last_field      dd      ?
; pointer to last report_field_group for this report, if any;
; address of .first_field, if .first_field is 0
id              dd      ?
; Report ID, if assigned. Zero otherwise.
top_level_collection dd ?       ; top-level collection for this report
ends
 
; This structure describes a set of reports of the same type;
; there are 3 sets (possibly empty), input, output and feature.
struct report_set
data            dd      ?
; If .numbered is zero, this is zero for the empty set and
; a pointer to the (only) report structure otherwise.
; If .numbered is nonzero, this is a pointer to 256-dword array of pointers
; to reports organized by report ID.
first_report    dd      ?
; Pointer to the first report or 0 for the empty set.
numbered        db      ?
; If zero, report IDs are not used, there can be at most one report in the set.
; If nonzero, first byte of the report is report ID.
                rb      3       ; padding
ends
 
; This structure describes a range of reports of one type that belong to
; some collection.
struct collection_report_set
first_report    dd      ?
first_field     dd      ?
last_report     dd      ?
last_field      dd      ?
ends
 
; This structure defines driver callbacks which are used while
; device is active; i.e. all callbacks except add_device.
struct hid_driver_active_callbacks
disconnect      dd      ?
; Called when an existing HID device is disconnected.
;
; Four following functions are called when a new input packet arrives
; in the following order: .begin_packet, then .input_field several times
; for each input field, interleaved with .array_overflow? for array groups,
; then .end_packet.
begin_packet    dd      ?
; edi -> driver data
array_overflow? dd      ?
; edi -> driver data
; out: CF cleared <=> ignore this array
input_field     dd      ?
; edi -> driver data, ecx = usage, edx = value
end_packet      dd      ?
; edi -> driver data
ends
 
; This structure describes one collection.
struct collection
next            dd      ?       ; pointer to the next collection in the same level
                                ; must be the first field
parent          dd      ?       ; pointer to nesting collection
first_child     dd      ?       ; pointer to the first nested collection
last_child      dd      ?       ; pointer to the last nested collection
                                ; or to .first_child, if .first_child is zero
type            dd      ?       ; Application, Physical etc
usage           dd      ?       ; associated Usage code
; Next fields are filled only for top-level collections.
callbacks       hid_driver_active_callbacks
driver_data     dd      ?       ; value to be passed as is to driver callbacks
input           collection_report_set
output          collection_report_set
feature         collection_report_set
ends
 
; This structure keeps all data used by the HID layer for one device.
struct hid_data
input           report_set
output          report_set
feature         report_set
first_collection        dd      ?
ends
 
; This structure defines callbacks required from the driver.
struct hid_driver_callbacks
add_device      dd      ?
; Called when a new HID device is connected.
active          hid_driver_active_callbacks
ends
 
; Two following structures describe temporary data;
; the corresponding objects cease to exist when HID parser completes
; state of Global items
struct global_items
next                    dd      ?
usage_page              dd      ?
logical_minimum         dd      ?
logical_maximum         dd      ?
physical_minimum        dd      ?
physical_maximum        dd      ?
unit_exponent           dd      ?
unit                    dd      ?
report_size             dd      ?
report_id               dd      ?
report_count            dd      ?
ends
 
; one range of Usages
struct usage_list_item
next                    dd      ?
first_usage             dd      ?
num_usages              dd      ?
ends
 
; =============================================================================
; =================================== Code ====================================
; =============================================================================
 
macro workers_globals
{
        workers_globals
; Jump tables for switch'ing in the code.
align 4
; jump table for two lower bits which encode size of item data
parse_descr_label.fetch_jumps:
        dd      parse_descr_label.fetch_none    ; x0, x4, x8, xC
        dd      parse_descr_label.fetch_byte    ; x1, x5, x9, xD
        dd      parse_descr_label.fetch_word    ; x2, x6, xA, xE
        dd      parse_descr_label.fetch_dword   ; x3, x7, xB, xF
; jump table for two next bits which encode item type
parse_descr_label.type_jumps:
        dd      parse_descr_label.parse_main
        dd      parse_descr_label.parse_global
        dd      parse_descr_label.parse_local
        dd      parse_descr_label.parse_reserved
; jump table for 4 upper bits in the case of Main item
parse_descr_label.main_jumps:
        dd      parse_descr_label.input ; 80...83
        dd      parse_descr_label.output        ; 90...93
        dd      parse_descr_label.collection    ; A0...A3
        dd      parse_descr_label.feature       ; B0...B3
        dd      parse_descr_label.end_collection ; C0...C3
parse_descr_label.num_main_items = ($ - parse_descr_label.main_jumps) / 4
; jump table for 4 upper bits in the case of Global item
parse_descr_label.global_jumps:
        dd      parse_descr_label.usage_page    ; 04...07
        dd      parse_descr_label.logical_minimum ; 14...17
        dd      parse_descr_label.logical_maximum ; 24...27
        dd      parse_descr_label.physical_minimum ; 34...37
        dd      parse_descr_label.physical_maximum ; 44...47
        dd      parse_descr_label.unit_exponent ; 54...57
        dd      parse_descr_label.unit          ; 64...67
        dd      parse_descr_label.report_size   ; 74...77
        dd      parse_descr_label.report_id     ; 84...87
        dd      parse_descr_label.report_count  ; 94...97
        dd      parse_descr_label.push          ; A4...A7
        dd      parse_descr_label.pop           ; B4...B7
parse_descr_label.num_global_items = ($ - parse_descr_label.global_jumps) / 4
; jump table for 4 upper bits in the case of Local item
parse_descr_label.local_jumps:
        dd      parse_descr_label.usage ; 08...0B
        dd      parse_descr_label.usage_minimum ; 18...1B
        dd      parse_descr_label.usage_maximum ; 28...2B
        dd      parse_descr_label.item_parsed   ; 38...3B = designator item; ignore
        dd      parse_descr_label.item_parsed   ; 48...4B = designator minimum; ignore
        dd      parse_descr_label.item_parsed   ; 58...5B = designator maximum; ignore
        dd      parse_descr_label.item_parsed   ; 68...6B not assigned
        dd      parse_descr_label.item_parsed   ; 78...7B = string index; ignore
        dd      parse_descr_label.item_parsed   ; 88...8B = string minimum; ignore
        dd      parse_descr_label.item_parsed   ; 98...9B = string maximum; ignore
        dd      parse_descr_label.delimiter     ; A8...AB
parse_descr_label.num_local_items = ($ - parse_descr_label.local_jumps) / 4
}
 
; Local variables for parse_descr.
macro parse_descr_locals
{
cur_item_size   dd      ?       ; encoded size of data for current item
report_ok       db      ?       ; 0 on error, 1 if everything is ok
field_type      db      ?       ; 0/1/2 for input/output/feature fields
                rb      2       ; alignment
field_data      dd      ?       ; data for current item when it describes a field group
last_reports    rd      3       ; pointers to last input/output/feature records
usage_minimum   dd      ?       ; current value of Usage Minimum
usage_list      dd      ?       ; list head of usage_list_item
usage_tail      dd      ?       ; list tail of usage_list_item
num_usage_ranges dd     ?       ; number of usage ranges, size of usage_list
delimiter_depth dd      ?       ; normally 0; 1 inside of Delimiter();
                                ; nested Delimiter()s are not allowed
usage_variant   dd      ?       ; 0 outside of Delimiter()s and for first Usage inside Delimiter(),
                                ; incremented with each new Usage inside Delimiter()
cur_collection  dd      ?       ; current collection
last_collection dd      ?       ; last top-level collection
}
 
; Parse report descriptor. The caller should provide local variables
; [buffer] = pointer to report descriptor, [length] = length of report descriptor,
; [calldata] = pointer to hid_data (possibly wrapped in a large structure).
macro parse_descr
{
parse_descr_label:
; 1. Initialize.
; 1a. Set some variables to initial values.
        xor     edi, edi
        mov     dword [report_ok], edi
        mov     [usage_list], edi
        mov     [cur_collection], edi
        mov     eax, [calldata]
        add     eax, hid_data.input.first_report
        mov     [last_reports+0*4], eax
        add     eax, hid_data.output.first_report - hid_data.input.first_report
        mov     [last_reports+1*4], eax
        add     eax, hid_data.feature.first_report - hid_data.output.first_report
        mov     [last_reports+2*4], eax
        add     eax, hid_data.first_collection - hid_data.feature.first_report
        mov     [last_collection], eax
; 1b. Allocate state of global items.
        movi    eax, sizeof.global_items
        invoke  Kmalloc
        test    eax, eax
        jz      .memory_error
; 1c. Zero-initialize it and move pointer to edi.
        push    eax
        xchg    eax, edi
        movi    ecx, sizeof.global_items / 4
        rep stosd
        pop     edi
; 1d. Load pointer to data into esi and make [length] point to end of data.
        mov     esi, [buffer]
        add     [length], esi
; 2. Clear all local items.
; This is needed in the beginning and after processing any Main item.
.zero_local_items:
        mov     eax, [usage_list]
@@:
        test    eax, eax
        jz      @f
        push    [eax+usage_list_item.next]
        invoke  Kfree
        pop     eax
        jmp     @b
@@:
        lea     ecx, [usage_list]
        mov     [usage_tail], ecx
        mov     [ecx], eax
        mov     [delimiter_depth], eax
        mov     [usage_variant], eax
        mov     [usage_minimum], eax
        mov     [num_usage_ranges], eax
; 3. Parse items until end of data found.
        cmp     esi, [length]
        jae     .parse_end
.fetch_next_item:
; --------------------------------- Parse item --------------------------------
; 4. Parse one item.
; 4a. Get item data. eax = first item byte = code+type+size (4+2+2 bits),
; ebx = item data interpreted as unsigned,
; ecx = item data interpreted as signed.
        movzx   eax, byte [esi]
        mov     ecx, eax
        and     ecx, 3
        mov     [cur_item_size], ecx
        jmp     dword [.fetch_jumps+ecx*4]
.invalid_report:
        mov     esi, invalid_report_msg
        jmp     .end_str
.fetch_none:
        xor     ebx, ebx
        xor     ecx, ecx
        inc     esi
        jmp     .fetched
.fetch_byte:
        add     esi, 2
        cmp     esi, [length]
        ja      .invalid_report
        movzx   ebx, byte [esi-1]
        movsx   ecx, bl
        jmp     .fetched
.fetch_word:
        add     esi, 3
        cmp     esi, [length]
        ja      .invalid_report
        movzx   ebx, word [esi-2]
        movsx   ecx, bx
        jmp     .fetched
.fetch_dword:
        add     esi, 5
        cmp     esi, [length]
        ja      .invalid_report
        mov     ebx, dword [esi-4]
        mov     ecx, ebx
.fetched:
; 4b. Select the branch according to item type.
; For every type, select the concrete handler and go there.
        mov     edx, eax
        shr     edx, 2
        and     edx, 3
        shr     eax, 4
        jmp     dword [.type_jumps+edx*4]
; -------------------------------- Main items ---------------------------------
.parse_main:
        sub     eax, 8
        cmp     eax, .num_main_items
        jae     .item_parsed
        jmp     dword [.main_jumps+eax*4]
; There are 5 Main items.
; Input/Output/Feature items create new field groups in the corresponding report;
; Collection item opens a new collection (possibly nested),
; End Collection item closes the most nested collection.
.output:
        mov     [field_type], 1
        jmp     .new_field
.feature:
        mov     [field_type], 2
        jmp     .new_field
.input:
        mov     [field_type], 0
.new_field:
; Create a new field group.
        mov     [field_data], ebx
        movzx   ebx, [field_type]
if sizeof.report_set = 12
        lea     ebx, [ebx*3]
        shl     ebx, 2
else
err Change the code
end if
        add     ebx, [calldata]
; 5. Sanity checks: field size and fields count must be nonzero,
; field size cannot be more than 32 bits,
; if field count is more than MAX_REPORT_SIZE * 8, the report would be more than
; MAX_REPORT_SIZE bytes, so it is invalid too.
; More precise check for size occurs later; this check only guarantees that
; there will be no overflows during subsequent calculations.
        cmp     [edi+global_items.report_size], 0
        jz      .invalid_report
        cmp     [edi+global_items.report_size], 32
        ja      .invalid_report
; There are devices with Report Count(0) + Input(Constant Variable),
; zero-length padding. Thus, do not consider descriptors with Report Count(0)
; as invalid; instead, just ignore fields with Report Count(0).
        cmp     [edi+global_items.report_count], 0
        jz      .zero_local_items
        cmp     [edi+global_items.report_count], MAX_REPORT_BYTES * 8
        ja      .invalid_report
; 6. Get the pointer to the place for the corresponding report in ebx.
; 6a. If report ID is not assigned, ebx already points to report_set.data,
; so go to 7.
        cmp     [edi+global_items.report_id], 0
        jz      .report_ptr_found
; 6b. If table for reports was already allocated,
; go to 6d skipping the next substep.
        cmp     [ebx+report_set.numbered], 0
        jnz     .report_set_allocated
; 6c. This is the first report with ID;
; allocate and zero-initialize table for reports.
; Note: it is incorrect but theoretically possible that some fields were
; already allocated in report without ID; if so, abort processing with error.
        cmp     [ebx+report_set.data], 0
        jnz     .invalid_report
        mov     eax, 256*4
        invoke  Kmalloc
        test    eax, eax
        jz      .memory_error
        mov     [ebx+report_set.data], eax
        inc     [ebx+report_set.numbered]
        push    edi
        mov     edi, eax
        mov     ecx, 256
        xor     eax, eax
        rep stosd
        pop     edi
; 6d. Report ID is assigned, report table is allocated,
; get the pointer to the corresponding item in the report table.
.report_set_allocated:
        mov     ebx, [ebx+report_set.data]
        mov     ecx, [edi+global_items.report_id]
        lea     ebx, [ebx+ecx*4]
; 7. If the field group is the first one in the report,
; allocate and initialize report without fields.
.report_ptr_found:
; 7a. Check whether the report has been allocated.
        cmp     dword [ebx], 0
        jnz     .report_allocated
; 7b. Allocate.
        movi    eax, sizeof.report
        invoke  Kmalloc
        test    eax, eax
        jz      .memory_error
; 7c. Initialize.
        xor     edx, edx
        lea     ecx, [eax+report.first_field]
        mov     [ebx], eax
        mov     [eax+report.next], edx
        mov     [eax+report.size], edx
        mov     [ecx], edx
        mov     [eax+report.last_field], ecx
        mov     [eax+report.top_level_collection], edx
        mov     ecx, [edi+global_items.report_id]
        mov     [eax+report.id], ecx
; 7d. Append to the overall list of reports.
        movzx   edx, [field_type]
        lea     edx, [last_reports+edx*4]
        mov     ecx, [edx]
        mov     [edx], eax
        mov     [ecx], eax
.report_allocated:
        mov     ebx, [ebx]
; ebx points to an already existing report; add new field.
; 8. Calculate total size of the group and
; check that the new group would not overflow the report.
        mov     eax, [edi+global_items.report_size]
        mul     [edi+global_items.report_count]
        mov     ecx, [ebx+report.size]
        add     ecx, eax
        cmp     ecx, MAX_REPORT_BYTES * 8
        ja      .invalid_report
; 9. If there are no usages for this group, this is padding;
; add it's size to total report size and stop processing.
        cmp     [num_usage_ranges], 0
        jz      .padding
; 10. Allocate memory for the group: this includes field group structure
; and additional fields depending on field type.
; See comments in report_field_group structure.
        push    eax
        mov     edx, [edi+global_items.report_count]
        lea     eax, [report_field_group.common_sizeof+edx*4]
        test    byte [field_data], HID_FIELD_VARIABLE
        jnz     @f
        lea     eax, [eax+edx*4]
        mov     edx, [num_usage_ranges]
        lea     eax, [eax+edx*sizeof.usage_range+4]
@@:
        invoke  Kmalloc
        pop     edx
        test    eax, eax
        jz      .memory_error
; 11. Update report data.
; Field offset is the current report size;
; get the current report size and update report size.
; Also store the pointer to new field in the previous last field
; and update the last field.
        mov     ecx, [ebx+report.last_field]
        xadd    [ebx+report.size], edx
        mov     [ebx+report.last_field], eax
        mov     [ecx], eax
; 12. Initialize field data: offset was calculated in the previous step,
; copy other characteristics from global_items data,
; calculate .mask and .sign_mask.
        mov     [eax+report_field_group.offset], edx
        xor     edx, edx
        mov     [eax+report_field_group.next], edx
        mov     [eax+report_field_group.sign_mask], edx
        inc     edx
        mov     ecx, [edi+global_items.report_size]
        mov     [eax+report_field_group.size], ecx
        shl     edx, cl
        cmp     [edi+global_items.logical_minimum], 0
        jge     .unsigned
        shr     edx, 1
        mov     [eax+report_field_group.sign_mask], edx
.unsigned:
        dec     edx
        mov     [eax+report_field_group.mask], edx
        mov     ecx, [edi+global_items.report_count]
        mov     [eax+report_field_group.count], ecx
        mov     ecx, [field_data]
        mov     [eax+report_field_group.flags], ecx
irps field, logical_minimum logical_maximum physical_minimum physical_maximum unit_exponent unit
\{
        mov     ecx, [edi+global_items.\#field]
        mov     [eax+report_field_group.\#field], ecx
\}
; 13. Update the current collection; nesting collections will be updated by
; end-of-collection handler.
        movzx   edx, [field_type]
if sizeof.collection_report_set = 16
        shl     edx, 4
else
err Change the code
end if
        mov     ecx, [cur_collection]
        test    ecx, ecx
        jz      .no_collection
        lea     ecx, [ecx+collection.input+edx]
        mov     [ecx+collection_report_set.last_report], ebx
        mov     [ecx+collection_report_set.last_field], eax
        cmp     [ecx+collection_report_set.first_field], 0
        jnz     .no_collection
        mov     [ecx+collection_report_set.first_report], ebx
        mov     [ecx+collection_report_set.first_field], eax
.no_collection:
; 14. Transform usage ranges. The target format depends on field type.
        test    byte [eax+report_field_group.flags], HID_FIELD_VARIABLE
        jz      .transform_usages_for_array
; For Variable field groups, expand all ranges to array with .count Usages.
; If total number of Usages in all ranges is too large, ignore excessive.
; If total number of Usages in all ranges is too small, duplicate the last
; Usage up to .count Usages (e.g. group of several indicators can have one usage
; "Generic Indicator" assigned to all fields).
        mov     ecx, [eax+report_field_group.count]
        mov     ebx, [usage_list]
.next_usage_range_for_variable:
        mov     edx, [ebx+usage_list_item.first_usage]
        push    [ebx+usage_list_item.num_usages]
.next_usage_for_variable:
        mov     [eax+report_field_group.common_sizeof], edx
        dec     ecx
        jz      @f
        add     eax, 4
        inc     edx
        dec     dword [esp]
        jnz     .next_usage_for_variable
        dec     edx
        inc     dword [esp]
        cmp     [ebx+usage_list_item.next], 0
        jz      .next_usage_for_variable
        pop     edx
        mov     ebx, [ebx+usage_list_item.next]
        jmp     .next_usage_range_for_variable
@@:
        pop     ebx
        jmp     .zero_local_items
.transform_usages_for_array:
; For Array field groups, leave ranges unexpanded, but recode in the form
; more convenient to value lookup, see comments in report_field_group structure.
        mov     ecx, [num_usage_ranges]
        mov     [eax+report_field_group.num_usage_ranges], ecx
        and     [eax+report_field_group.num_values_prev], 0
        mov     ecx, [usage_list]
        xor     ebx, ebx
@@:
        mov     edx, [ecx+usage_list_item.first_usage]
        mov     [eax+report_field_group.usages+usage_range.offset], ebx
        add     ebx, [ecx+usage_list_item.num_usages]
        jc      .invalid_report
        mov     [eax+report_field_group.usages+usage_range.first_usage], edx
        add     eax, sizeof.usage_range
        mov     ecx, [ecx+usage_list_item.next]
        test    ecx, ecx
        jnz     @b
        mov     [eax+report_field_group.usages], ebx
; New field is initialized.
        jmp     .zero_local_items
.padding:
        mov     [ebx+report.size], ecx
        jmp     .zero_local_items
; Create a new collection, nested in the current one.
.collection:
; Actions are quite straightforward:
; allocate, zero-initialize, update parent, if there is one,
; make it current.
        movi    eax, sizeof.collection
        invoke  Kmalloc
        test    eax, eax
        jz      .memory_error
        push    eax edi
        movi    ecx, sizeof.collection / 4
        xchg    edi, eax
        xor     eax, eax
        rep stosd
        pop     edi eax
        mov     edx, [cur_collection]
        mov     [eax+collection.parent], edx
        lea     ecx, [last_collection]
        test    edx, edx
        jz      .no_parent
        lea     ecx, [edx+collection.last_child]
.no_parent:
        mov     edx, [ecx]
        mov     [ecx], eax
        mov     [edx], eax
        lea     ecx, [eax+collection.first_child]
; In theory, there must be at least one usage.
; In practice, some nested collections don't have any. Use zero in this case.
        mov     edx, [usage_list]
        test    edx, edx
        jz      @f
        mov     edx, [edx+usage_list_item.first_usage]
@@:
        mov     [eax+collection.last_child], ecx
        mov     [eax+collection.type], ebx
        mov     [eax+collection.usage], edx
        mov     [cur_collection], eax
        jmp     .zero_local_items
; Close the current collection.
.end_collection:
; There must be an opened collection.
        mov     eax, [cur_collection]
        test    eax, eax
        jz      .invalid_report
; Make parent collection the current one.
        mov     edx, [eax+collection.parent]
        mov     [cur_collection], edx
; Add field range of the closing collection to field range for nesting collection,
; if there is one.
        test    edx, edx
        jz      .zero_local_items
        push    3       ; for each type: input, output, feature
.update_ranges:
        mov     ecx, [eax+collection.input.last_report]
        test    ecx, ecx
        jz      .no_fields
        mov     [edx+collection.input.last_report], ecx
        mov     ecx, [eax+collection.input.last_field]
        mov     [edx+collection.input.last_field], ecx
        cmp     [edx+collection.input.first_report], 0
        jnz     .no_fields
        mov     ecx, [eax+collection.input.first_report]
        mov     [edx+collection.input.first_report], ecx
        mov     ecx, [eax+collection.input.first_field]
        mov     [edx+collection.input.first_field], ecx
.no_fields:
        add     eax, sizeof.collection_report_set
        add     edx, sizeof.collection_report_set
        dec     dword [esp]
        jnz     .update_ranges
        pop     eax
        jmp     .zero_local_items
; ------------------------------- Global items --------------------------------
.parse_global:
        cmp     eax, .num_global_items
        jae     .item_parsed
        jmp     dword [.global_jumps+eax*4]
; For most global items, just store the value in the current global_items structure.
; Note 1: Usage Page will be used for upper word of Usage[| Minimum|Maximum], so
; shift it in advance.
; Note 2: the HID specification allows both signed and unsigned values for
; logical and physical minimum/maximum, but does not give a method to distinguish.
; Thus, hope that minimum comes first, parse the minimum as signed value always,
; if it is less than zero, assume signed values, otherwise assume unsigned values.
; This covers both common cases Minimum(0)/Maximum(FF) and Minimum(-7F)/Maximum(7F).
; Note 3: zero value for Report ID is forbidden by the HID specification.
; It is quite convenient, we use report_id == 0 for reports without ID.
.usage_page:
        shl     ebx, 16
        mov     [edi+global_items.usage_page], ebx
        jmp     .item_parsed
.logical_minimum:
        mov     [edi+global_items.logical_minimum], ecx
        jmp     .item_parsed
.logical_maximum:
        cmp     [edi+global_items.logical_minimum], 0
        jge     @f
        mov     ebx, ecx
@@:
        mov     [edi+global_items.logical_maximum], ebx
        jmp     .item_parsed
.physical_minimum:
        mov     [edi+global_items.physical_minimum], ecx
        jmp     .item_parsed
.physical_maximum:
        cmp     [edi+global_items.physical_maximum], 0
        jge     @f
        mov     ebx, ecx
@@:
        mov     [edi+global_items.physical_maximum], ebx
        jmp     .item_parsed
.unit_exponent:
        mov     [edi+global_items.unit_exponent], ecx
        jmp     .item_parsed
.unit:
        mov     [edi+global_items.unit], ebx
        jmp     .item_parsed
.report_size:
        mov     [edi+global_items.report_size], ebx
        jmp     .item_parsed
.report_id:
        test    ebx, ebx
        jz      .invalid_report
        cmp     ebx, 0x100
        jae     .invalid_report
        mov     [edi+global_items.report_id], ebx
        jmp     .item_parsed
.report_count:
        mov     [edi+global_items.report_count], ebx
        jmp     .item_parsed
; Two special global items: Push/Pop.
.push:
; For Push, allocate new global_items structure,
; initialize from the current one and make it current.
        movi    eax, sizeof.global_items
        invoke  Kmalloc
        test    eax, eax
        jz      .memory_error
        push    esi eax
        movi    ecx, sizeof.global_items / 4
        mov     esi, edi
        xchg    eax, edi
        rep movsd
        pop     edi esi
        mov     [edi+global_items.next], eax
        jmp     .item_parsed
.pop:
; For Pop, restore the last global_items structure and free the current one.
        mov     eax, [edi+global_items.next]
        test    eax, eax
        jz      .invalid_report
        push    eax
        xchg    eax, edi
        invoke  Kfree
        pop     edi
        jmp     .item_parsed
; -------------------------------- Local items --------------------------------
.parse_local:
        cmp     eax, .num_local_items
        jae     .item_parsed
        jmp     dword [.local_jumps+eax*4]
.usage:
; Usage tag.
; If length is 0, 1, 2 bytes, append the global item Usage Page.
        cmp     [cur_item_size], 2
        ja      @f
        or      ebx, [edi+global_items.usage_page]
@@:
; If inside Delimiter(), ignore everything except the first tag.
        cmp     [delimiter_depth], 0
        jz      .usage.write
        inc     [usage_variant]
        cmp     [usage_variant], 1
        jnz     .item_parsed
.usage.write:
; Add new range with start = item data and length = 1.
        mov     [usage_minimum], ebx
        push    1
.new_usage:
        movi    eax, sizeof.usage_list_item
        invoke  Kmalloc
        pop     edx
        test    eax, eax
        jz      .memory_error
        inc     [num_usage_ranges]
        mov     ecx, [usage_minimum]
        and     [eax+usage_list_item.next], 0
        mov     [eax+usage_list_item.first_usage], ecx
        mov     [eax+usage_list_item.num_usages], edx
        mov     ecx, [usage_tail]
        mov     [usage_tail], eax
        mov     [ecx], eax
        jmp     .item_parsed
.usage_minimum:
; Usage Minimum tag. Just store in the local var.
; If length is 0, 1, 2 bytes, append the global item Usage Page.
        cmp     [cur_item_size], 2
        ja      @f
        or      ebx, [edi+global_items.usage_page]
@@:
        mov     [usage_minimum], ebx
        jmp     .item_parsed
.usage_maximum:
; Usage Maximum tag.
; If length is 0, 1, 2 bytes, append the global item Usage Page.
        cmp     [cur_item_size], 2
        ja      @f
        or      ebx, [edi+global_items.usage_page]
@@:
; Meaningless inside Delimiter().
        cmp     [delimiter_depth], 0
        jnz     .invalid_report
; Add new range with start = saved Usage Minimum and
; length = Usage Maximum - Usage Minimum + 1.
        sub     ebx, [usage_minimum]
        inc     ebx
        push    ebx
        jmp     .new_usage
.delimiter:
; Delimiter tag.
        test    ebx, ebx
        jz      .delimiter.close
; Delimiter(Opened).
; Store that we are inside Delimiter(),
; say a warning that only preferred Usage will be used.
        cmp     [delimiter_depth], 0
        jnz     .invalid_report
        inc     [delimiter_depth]
        push    esi
        mov     esi, delimiter_note
        invoke  SysMsgBoardStr
        pop     esi
        jmp     .item_parsed
.delimiter.close:
; Delimiter(Closed).
; Store that we are not inside Delimiter() anymore.
        dec     [delimiter_depth]
        js      .invalid_report
        and     [usage_variant], 0
        jmp     .item_parsed
.parse_reserved:
; Ignore reserved items, except that tag 0xFE means long item
; with first data byte = length of additional data,
; second data byte = long item tag. No long items are defined yet,
; so just skip them.
        cmp     eax, 0xF
        jnz     .item_parsed
        cmp     [cur_item_size], 2
        jnz     .item_parsed
        movzx   ecx, bl
        add     esi, ecx
        cmp     esi, [length]
        ja      .invalid_report
.item_parsed:
        cmp     esi, [length]
        jb      .fetch_next_item
.parse_end:
;-------------------------------- End of parsing ------------------------------
; If there are opened collections, it is invalid report.
        cmp     [cur_collection], 0
        jnz     .invalid_report
; There must be at least one input field.
        mov     eax, [calldata]
        add     eax, hid_data.input.first_report
        cmp     [last_reports+0*4], eax
        jz      .invalid_report
; Everything is ok.
        inc     [report_ok]
        jmp     .end
.memory_error:
        mov     esi, nomemory_msg
.end_str:
        invoke  SysMsgBoardStr
.end:
; Free all global_items structures.
        test    edi, edi
        jz      @f
        push    [edi+global_items.next]
        xchg    eax, edi
        invoke  Kfree
        pop     edi
        jmp     .end
@@:
; Free the last Usage list, if any.
        mov     eax, [usage_list]
@@:
        test    eax, eax
        jz      @f
        push    [eax+usage_list_item.next]
        invoke  Kfree
        pop     eax
        jmp     @b
@@:
}
 
; Assign drivers to top-level HID collections.
; The caller should provide ebx = pointer to hid_data and a local variable
; [has_driver], it will be initialized with 0 if no driver is present.
macro postprocess_descr
{
postprocess_report_label:
; Assign drivers to top-level collections.
; Use mouse driver for Usage(GenericDesktop:Mouse),
; use keyboard driver for Usage(GenericDesktop:Keyboard)
; and Usage(GenericDesktop:Keypad)
; 1. Prepare for the loop: get the pointer to the first collection,
; store that no drivers were assigned yet.
        mov     edi, [ebx+hid_data.first_collection]
if ~HID_DUMP_UNCLAIMED
        mov     [has_driver], 0
end if
.next_collection:
; 2. Test whether there is a collection to test; if no, break from the loop.
        test    edi, edi
        jz      .postprocess_done
; 3. Get pointer to driver callbacks depending on [collection.usage].
; If [collection.usage] is unknown, use default driver if HID_DUMP_UNCLAIMED
; and do not assign a driver otherwise.
        mov     esi, mouse_driver
        cmp     [edi+collection.usage], USAGE_GD_POINTER
        jz      .has_driver
        cmp     [edi+collection.usage], USAGE_GD_MOUSE
        jz      .has_driver
        mov     esi, keyboard_driver
        cmp     [edi+collection.usage], USAGE_GD_KEYBOARD
        jz      .has_driver
        cmp     [edi+collection.usage], USAGE_GD_KEYPAD
        jz      .has_driver
        mov     esi, multimedia_driver
        cmp     [edi+collection.usage], USAGE_GD_CONS_CTRL
        jz      .has_driver
if HID_DUMP_UNCLAIMED
        mov     esi, default_driver
else
        xor     esi, esi
end if
; 4. If no driver is assigned (possible only if not HID_DUMP_UNCLAIMED),
; go to 7 with driver data = 0;
; other code uses this as a sign that driver callbacks should not be called.
.has_driver:
        xor     eax, eax
if ~HID_DUMP_UNCLAIMED
        test    esi, esi
        jz      .set_driver
end if
; 5. Notify the driver about new device.
        call    [esi+hid_driver_callbacks.add_device]
; 6. If the driver has returned non-zero driver data,
; store that is an assigned driver.
; Otherwise, if HID_DUMP_UNCLAIMED, try to assign the default driver.
if HID_DUMP_UNCLAIMED
        test    eax, eax
        jnz     .set_driver
        mov     esi, default_driver
        call    [esi+hid_driver_callbacks.add_device]
else
        test    eax, eax
        jz      @f
        mov     [has_driver], 1
        jmp     .set_driver
@@:
        xor     esi, esi
end if
.set_driver:
; 7. Store driver data. If a driver is assigned, copy driver callbacks.
        mov     [edi+collection.driver_data], eax
        test    esi, esi
        jz      @f
        push    edi
        lodsd   ; skip hid_driver_callbacks.add_device
        add     edi, collection.callbacks
repeat sizeof.hid_driver_active_callbacks / 4
        movsd
end repeat
        pop     edi
@@:
; 8. Store pointer to the collection in all input reports belonging to it.
; Note that the HID spec requires that reports should not cross top-level collections.
        mov     eax, [edi+collection.input.first_report]
        test    eax, eax
        jz      .reports_processed
.next_report:
        mov     [eax+report.top_level_collection], edi
        cmp     eax, [edi+collection.input.last_report]
        mov     eax, [eax+report.next]
        jnz     .next_report
.reports_processed:
        mov     edi, [edi+collection.next]
        jmp     .next_collection
.postprocess_done:
}
 
; Cleanup all resources allocated during parse_descr and postprocess_descr.
; Called when the corresponding device is disconnected
; with ebx = pointer to hid_data.
macro hid_cleanup
{
; 1. Notify all assigned drivers about disconnect.
; Loop over all top-level collections and call callbacks.disconnect,
; if a driver is assigned.
        mov     esi, [ebx+hid_data.first_collection]
.notify_drivers:
        test    esi, esi
        jz      .notify_drivers_done
        mov     edi, [esi+collection.driver_data]
        test    edi, edi
        jz      @f
        call    [esi+collection.callbacks.disconnect]
@@:
        mov     esi, [esi+collection.next]
        jmp     .notify_drivers
.notify_drivers_done:
; 2. Free all collections.
        mov     esi, [ebx+hid_data.first_collection]
.free_collections:
        test    esi, esi
        jz      .collections_done
; If a collection has childen, make it forget about them,
; kill all children; after last child is killed, return to
; the collection as a parent; this time, it will appear
; as childless, so it will be killed after children.
        mov     eax, [esi+collection.first_child]
        test    eax, eax
        jz      .no_children
        and     [esi+collection.first_child], 0
        xchg    esi, eax
        jmp     .free_collections
.no_children:
; If a collection has no children (maybe there were no children at all,
; maybe all children were already killed), kill it and proceed either to
; next sibling (if any) or to the parent.
        mov     eax, [esi+collection.next]
        test    eax, eax
        jnz     @f
        mov     eax, [esi+collection.parent]
@@:
        xchg    eax, esi
        invoke  Kfree
        jmp     .free_collections
.collections_done:
; 3. Free all three report sets.
        push    3
        lea     esi, [ebx+hid_data.input]
; For every report set, loop over all reports,
; for every report free all field groups, then free report itself.
; When all reports in one set have been freed, free also report list table,
; if there is one (reports are numbered).
.report_set_loop:
        mov     edi, [esi+report_set.first_report]
.report_loop:
        test    edi, edi
        jz      .report_done
        mov     eax, [edi+report.first_field]
.field_loop:
        test    eax, eax
        jz      .field_done
        push    [eax+report_field_group.next]
        invoke  Kfree
        pop     eax
        jmp     .field_loop
.field_done:
        mov     eax, [edi+report.next]
        xchg    eax, edi
        invoke  Kfree
        jmp     .report_loop
.report_done:
        cmp     [esi+report_set.numbered], 0
        jz      @f
        mov     eax, [esi+report_set.data]
        invoke  Kfree
@@:
        add     esi, sizeof.report_set
        dec     dword [esp]
        jnz     .report_set_loop
        pop     eax
}
 
; Helper for parse_input. Extracts value of one field.
; in: esi -> report_field_group
; in: eax = offset in bits from report start
; in: report -> report data
; out: edx = value
; Note: it can read one dword past report data.
macro extract_field_value report
{
        mov     ecx, eax
        shr     eax, 5
        shl     eax, 2
        add     eax, report
        and     ecx, 31
        mov     edx, [eax]
        mov     eax, [eax+4]
        shrd    edx, eax, cl
        mov     ecx, [esi+report_field_group.sign_mask]
        and     ecx, edx
        and     edx, [esi+report_field_group.mask]
        sub     edx, ecx
}
 
; Local variables for parse_input.
macro parse_input_locals
{
count_inside_group      dd      ?
; Number of fields left in the current field.
field_offset            dd      ?
; Offset of the current field from report start, in bits.
field_range_size                dd      ?
; Size of range with valid values, Logical Maximum - Logical Minimum + 1.
cur_usage               dd      ?
; Pointer to current usage for Variable field groups.
num_values              dd      ?
; Number of values in the current instantiation of Array field group.
values_base             dd      ?
; Pointer to memory allocated for array with current values.
values_prev             dd      ?
; Pointer to memory allocated for array with previous values.
values_cur_ptr          dd      ?
; Pointer to the next value in [values_base] array.
values_end              dd      ?
; End of data in array with current values.
values_prev_ptr         dd      ?
; Pointer to the next value in [values_prev_ptr] array.
values_prev_end         dd      ?
; End of data in array with previous values.
}
 
; Parse input report. The caller should provide esi = pointer to report,
; local variables parse_input_locals and [buffer] = report data.
macro parse_input
{
; 1. Ignore the report if there is no driver for it.
        mov     ebx, [esi+report.top_level_collection]
        mov     edi, [ebx+collection.driver_data]
        test    edi, edi
        jz      .done
; 2. Notify the driver that a new packet arrived.
        call    [ebx+collection.callbacks.begin_packet]
; Loop over all field groups.
; Report without fields is meaningless, but theoretically possible:
; parse_descr does not create reports of zero size, but
; a report can consist of "padding" fields without usages and have
; no real fields.
        mov     esi, [esi+report.first_field]
        test    esi, esi
        jz      .packet_processed
.field_loop:
; 3. Prepare for group handling: initialize field offset, fields count
; and size of range for valid values.
        mov     eax, [esi+report_field_group.offset]
        mov     [field_offset], eax
        mov     ecx, [esi+report_field_group.count]
        mov     [count_inside_group], ecx
        mov     eax, [esi+report_field_group.logical_maximum]
        inc     eax
        sub     eax, [esi+report_field_group.logical_minimum]
        mov     [field_range_size], eax
; 4. Select handler. Variable and Array groups are handled entirely differently;
; for Variable groups, advance to 5, for Array groups, go to 6.
        test    byte [esi+report_field_group.flags], HID_FIELD_VARIABLE
        jz      .array_field
; 5. Variable groups. They are simple. Loop over all .count fields,
; for every field extract the value and get the next usage,
; if the value is within valid range, call the driver.
        lea     eax, [esi+report_field_group.common_sizeof]
        mov     [cur_usage], eax
.variable_data_loop:
        mov     eax, [field_offset]
        extract_field_value [buffer]    ; -> edx
        mov     ecx, [cur_usage]
        mov     ecx, [ecx]
        call    [ebx+collection.callbacks.input_field]
        add     [cur_usage], 4
        mov     eax, [esi+report_field_group.size]
        add     [field_offset], eax
        dec     [count_inside_group]
        jnz     .variable_data_loop
; Variable group is processed; go to 12.
        jmp     .field_done
.array_field:
; Array groups. They are complicated.
; 6. Array group: extract all values in one array.
; memory was allocated during group creation, use it
; 6a. Prepare: get data pointer, initialize num_values with zero.
        mov     eax, [esi+report_field_group.num_usage_ranges]
        lea     edx, [esi+report_field_group.usages+eax*sizeof.usage_range+4]
        mov     eax, [esi+report_field_group.count]
        mov     [values_cur_ptr], edx
        mov     [values_base], edx
        lea     edx, [edx+ecx*4]
        mov     [values_prev], edx
        mov     [values_prev_ptr], edx
        mov     [num_values], 0
; 6b. Start loop for every field. Note that there must be at least one field,
; parse_descr does not allow .count == 0.
.array_getval_loop:
; 6c. Extract the value of the current field.
        mov     eax, [field_offset]
        extract_field_value [buffer]    ; -> edx
; 6d. Transform the value to the usage with binary search in array of
; usage_ranges. started at [esi+report_field_group.usages]
; having [esi+report_field_group.num_usage_ranges] items.
; Ignore items outside of valid range.
        sub     edx, [esi+report_field_group.logical_minimum]
        cmp     edx, [field_range_size]
        jae     .array_skip_item
; If there are too few usages, use last of them.
        mov     ecx, [esi+report_field_group.num_usage_ranges]  ; upper bound
        xor     eax, eax        ; lower bound
        cmp     edx, [esi+report_field_group.usages+ecx*sizeof.usage_range+usage_range.offset]
        jae     .array_last_usage
; loop invariant: usages[eax].offset <= edx < usages[ecx].offset
.array_find_usage:
        lea     edi, [eax+ecx]
        shr     edi, 1
        cmp     edi, eax
        jz      .array_found_usage_range
        cmp     edx, [esi+report_field_group.usages+edi*sizeof.usage_range+usage_range.offset]
        jae     .update_low
        mov     ecx, edi
        jmp     .array_find_usage
.update_low:
        mov     eax, edi
        jmp     .array_find_usage
.array_last_usage:
        lea     eax, [ecx-1]
        mov     edx, [esi+report_field_group.usages+ecx*sizeof.usage_range+usage_range.offset]
        dec     edx
.array_found_usage_range:
        sub     edx, [esi+report_field_group.usages+eax*sizeof.usage_range+usage_range.offset]
        add     edx, [esi+report_field_group.usages+eax*sizeof.usage_range+usage_range.first_usage]
; 6e. Store the usage, advance data pointer, continue loop started at 6b.
        mov     eax, [values_cur_ptr]
        mov     [eax], edx
        add     [values_cur_ptr], 4
        inc     [num_values]
.array_skip_item:
        mov     eax, [esi+report_field_group.size]
        add     [field_offset], eax
        dec     [count_inside_group]
        jnz     .array_getval_loop
; 7. Array group: ask driver about array overflow.
; If driver says that the array is invalid, stop processing this group
; (in particular, do not update previous values).
        mov     ecx, [num_values]
        test    ecx, ecx
        jz      .duplicates_removed
        mov     edx, [values_base]
        mov     edi, [ebx+collection.driver_data]
        call    [ebx+collection.callbacks.array_overflow?]
        jnc     .field_done
; 8. Array group: sort the array with current values.
        push    esi
        mov     ecx, [num_values]
        mov     edx, [values_base]
        call    sort
        pop     esi
; 9. Array group: remove duplicates.
        cmp     [num_values], 1
        jbe     .duplicates_removed
        mov     eax, [values_base]
        mov     edx, [eax]
        add     eax, 4
        mov     ecx, eax
.duplicates_loop:
        cmp     edx, [eax]
        jz      @f
        mov     edx, [eax]
        mov     [ecx], edx
        add     ecx, 4
@@:
        add     eax, 4
        cmp     eax, [values_cur_ptr]
        jb      .duplicates_loop
        mov     [values_cur_ptr], ecx
        sub     ecx, [values_base]
        shr     ecx, 2
        mov     [num_values], ecx
.duplicates_removed:
; 10. Array group: compare current and previous values,
; call driver for differences.
        mov     edi, [ebx+collection.driver_data]
        mov     eax, [values_cur_ptr]
        mov     [values_end], eax
        mov     eax, [values_base]
        mov     [values_cur_ptr], eax
        mov     eax, [esi+report_field_group.num_values_prev]
        shl     eax, 2
        add     eax, [values_prev]
        mov     [values_prev_end], eax
.find_common:
        mov     eax, [values_cur_ptr]
        cmp     eax, [values_end]
        jae     .cur_done
        mov     ecx, [eax]
        mov     eax, [values_prev_ptr]
        cmp     eax, [values_prev_end]
        jae     .prev_done
        mov     edx, [eax]
        cmp     ecx, edx
        jb      .advance_cur
        ja      .advance_prev
; common item in both arrays; ignore
        add     [values_cur_ptr], 4
        add     [values_prev_ptr], 4
        jmp     .find_common
.advance_cur:
; item is present in current array but not in previous;
; call the driver with value = 1
        add     [values_cur_ptr], 4
        mov     edx, 1
        call    [ebx+collection.callbacks.input_field]
        jmp     .find_common
.advance_prev:
; item is present in previous array but not in current;
; call the driver with value = 0
        add     [values_prev_ptr], 4
        mov     ecx, edx
        xor     edx, edx
        call    [ebx+collection.callbacks.input_field]
        jmp     .find_common
.prev_done:
; for all items which are left in current array
; call the driver with value = 1
        mov     eax, [values_cur_ptr]
@@:
        add     [values_cur_ptr], 4
        mov     ecx, [eax]
        mov     edx, 1
        call    [ebx+collection.callbacks.input_field]
        mov     eax, [values_cur_ptr]
        cmp     eax, [values_end]
        jb      @b
        jmp     .copy_array
.cur_done:
; for all items which are left in previous array
; call the driver with value = 0
        mov     eax, [values_prev_ptr]
        add     [values_prev_ptr], 4
        cmp     eax, [values_prev_end]
        jae     @f
        mov     ecx, [eax]
        xor     edx, edx
        call    [ebx+collection.callbacks.input_field]
        jmp     .cur_done
@@:
.copy_array:
; 11. Array group: copy current values to previous values.
        push    esi edi
        mov     ecx, [num_values]
        mov     [esi+report_field_group.num_values_prev], ecx
        mov     esi, [values_base]
        mov     edi, [values_prev]
        rep movsd
        pop     edi esi
; 12. Field group is processed. Repeat with the next group, if any.
.field_done:
        mov     esi, [esi+report_field_group.next]
        test    esi, esi
        jnz     .field_loop
.packet_processed:
; 13. Packet is processed, notify the driver.
        call    [ebx+collection.callbacks.end_packet]
}

Rev 5051	Rev 5148
1	; Parser of HID structures: parse HID report descriptor,	1	; Parser of HID structures: parse HID report descriptor,
2	; parse/generate input/output/feature reports.	2	; parse/generate input/output/feature reports.
3		3
4	; =============================================================================	4	; =============================================================================
5	; ================================= Constants =================================	5	; ================================= Constants =================================
6	; =============================================================================	6	; =============================================================================
7	; Usage codes from HID specification	7	; Usage codes from HID specification
8	; Generic Desktop usage page	8	; Generic Desktop usage page
9	USAGE_GD_POINTER = 10001h	9	USAGE_GD_POINTER = 10001h
10	USAGE_GD_MOUSE = 10002h	10	USAGE_GD_MOUSE = 10002h
11	USAGE_GD_JOYSTICK = 10004h	11	USAGE_GD_JOYSTICK = 10004h
12	USAGE_GD_GAMEPAD = 10005h	12	USAGE_GD_GAMEPAD = 10005h
13	USAGE_GD_KEYBOARD = 10006h	13	USAGE_GD_KEYBOARD = 10006h
14	USAGE_GD_KEYPAD = 10007h	14	USAGE_GD_KEYPAD = 10007h
15		15
16	USAGE_GD_X = 10030h	16	USAGE_GD_X = 10030h
17	USAGE_GD_Y = 10031h	17	USAGE_GD_Y = 10031h
18	USAGE_GD_Z = 10032h	18	USAGE_GD_Z = 10032h
19	USAGE_GD_RX = 10033h	19	USAGE_GD_RX = 10033h
20	USAGE_GD_RY = 10034h	20	USAGE_GD_RY = 10034h
21	USAGE_GD_RZ = 10035h	21	USAGE_GD_RZ = 10035h
22	USAGE_GD_SLIDER = 10036h	22	USAGE_GD_SLIDER = 10036h
23	USAGE_GD_DIAL = 10037h	23	USAGE_GD_DIAL = 10037h
24	USAGE_GD_WHEEL = 10038h	24	USAGE_GD_WHEEL = 10038h
-		25
-		26	USAGE_GD_CONS_CTRL = 0C0001h ; Consumer control (media keys)
25		27
26	; Keyboard/Keypad usage page	28	; Keyboard/Keypad usage page
27	USAGE_KBD_NOEVENT = 70000h	29	USAGE_KBD_NOEVENT = 70000h
28	USAGE_KBD_ROLLOVER = 70001h	30	USAGE_KBD_ROLLOVER = 70001h
29	USAGE_KBD_POSTFAIL = 70002h	31	USAGE_KBD_POSTFAIL = 70002h
30	USAGE_KBD_FIRST_KEY = 70004h ; this is 'A', actually	32	USAGE_KBD_FIRST_KEY = 70004h ; this is 'A', actually
31	USAGE_KBD_LCTRL = 700E0h	33	USAGE_KBD_LCTRL = 700E0h
32	USAGE_KBD_LSHIFT = 700E1h	34	USAGE_KBD_LSHIFT = 700E1h
33	USAGE_KBD_LALT = 700E2h	35	USAGE_KBD_LALT = 700E2h
34	USAGE_KBD_LWIN = 700E3h	36	USAGE_KBD_LWIN = 700E3h
35	USAGE_KBD_RCTRL = 700E4h	37	USAGE_KBD_RCTRL = 700E4h
36	USAGE_KBD_RSHIFT = 700E5h	38	USAGE_KBD_RSHIFT = 700E5h
37	USAGE_KBD_RALT = 700E6h	39	USAGE_KBD_RALT = 700E6h
38	USAGE_KBD_RWIN = 700E7h	40	USAGE_KBD_RWIN = 700E7h
39		41
40	; LED usage page	42	; LED usage page
41	USAGE_LED_NUMLOCK = 80001h	43	USAGE_LED_NUMLOCK = 80001h
42	USAGE_LED_CAPSLOCK = 80002h	44	USAGE_LED_CAPSLOCK = 80002h
43	USAGE_LED_SCROLLLOCK = 80003h	45	USAGE_LED_SCROLLLOCK = 80003h
44		46
45	; Button usage page	47	; Button usage page
46	; First button is USAGE_BUTTON_PAGE+1, second - USAGE_BUTTON_PAGE+2 etc.	48	; First button is USAGE_BUTTON_PAGE+1, second - USAGE_BUTTON_PAGE+2 etc.
47	USAGE_BUTTON_PAGE = 90000h	49	USAGE_BUTTON_PAGE = 90000h
-		50
-		51	; Consumer control usage page
-		52	USAGE_CONSUMER = 0C0000h
48		53
49	; Flags for input/output/feature fields	54	; Flags for input/output/feature fields
50	HID_FIELD_CONSTANT = 1 ; if not, then Data field	55	HID_FIELD_CONSTANT = 1 ; if not, then Data field
51	HID_FIELD_VARIABLE = 2 ; if not, then Array field	56	HID_FIELD_VARIABLE = 2 ; if not, then Array field
52	HID_FIELD_RELATIVE = 4 ; if not, then Absolute field	57	HID_FIELD_RELATIVE = 4 ; if not, then Absolute field
53	HID_FIELD_WRAP = 8	58	HID_FIELD_WRAP = 8
54	HID_FIELD_NONLINEAR = 10h	59	HID_FIELD_NONLINEAR = 10h
55	HID_FIELD_NOPREFERRED= 20h ; no preferred state	60	HID_FIELD_NOPREFERRED= 20h ; no preferred state
56	HID_FIELD_HASNULL = 40h ; has null state	61	HID_FIELD_HASNULL = 40h ; has null state
57	HID_FIELD_VOLATILE = 80h ; for output/feature fields	62	HID_FIELD_VOLATILE = 80h ; for output/feature fields
58	HID_FIELD_BUFBYTES = 100h; buffered bytes	63	HID_FIELD_BUFBYTES = 100h; buffered bytes
59		64
60	; Report descriptor can easily describe gigabytes of (meaningless) data.	65	; Report descriptor can easily describe gigabytes of (meaningless) data.
61	; Keep report size reasonable to avoid excessive memory allocations and	66	; Keep report size reasonable to avoid excessive memory allocations and
62	; calculation overflows; 1 Kb is more than enough (typical size is 3-10 bytes).	67	; calculation overflows; 1 Kb is more than enough (typical size is 3-10 bytes).
63	MAX_REPORT_BYTES = 1024	68	MAX_REPORT_BYTES = 1024
64		69
65	; =============================================================================	70	; =============================================================================
66	; ================================ Structures =================================	71	; ================================ Structures =================================
67	; =============================================================================	72	; =============================================================================
68	; Every meaningful report field group has one or more associated usages.	73	; Every meaningful report field group has one or more associated usages.
69	; Usages can be individual or joined into continuous ranges.	74	; Usages can be individual or joined into continuous ranges.
70	; This structure describes one range or one individual usage in a large array;	75	; This structure describes one range or one individual usage in a large array;
71	; individual usage is equivalent to a range of length 1.	76	; individual usage is equivalent to a range of length 1.
72	struct usage_range	77	struct usage_range
73	offset dd ?	78	offset dd ?
74	; Sum of range sizes over all previous array items.	79	; Sum of range sizes over all previous array items.
75	; Size of range a equals	80	; Size of range a equals
76	; [a + sizeof.usage_range + usage_range.offset] - [a + usage_range.offset].	81	; [a + sizeof.usage_range + usage_range.offset] - [a + usage_range.offset].
77	; The total sum over all array items immediately follows the array,	82	; The total sum over all array items immediately follows the array,
78	; this field must be the first so that the formula above works for the last item.	83	; this field must be the first so that the formula above works for the last item.
79	first_usage dd ?	84	first_usage dd ?
80	; Usage code for first item in the range.	85	; Usage code for first item in the range.
81	ends	86	ends
82		87
83	; This structure describes one group of report fields with identical properties.	88	; This structure describes one group of report fields with identical properties.
84	struct report_field_group	89	struct report_field_group
85	next dd ?	90	next dd ?
86	; All field groups in one report are organized in a single-linked list.	91	; All field groups in one report are organized in a single-linked list.
87	; This is the next group in the report or 0 for the last group.	92	; This is the next group in the report or 0 for the last group.
88	size dd ?	93	size dd ?
89	; Size in bits of one field. Cannot be zero or greater than 32.	94	; Size in bits of one field. Cannot be zero or greater than 32.
90	count dd ? ; field count, cannot be zero	95	count dd ? ; field count, cannot be zero
91	offset dd ? ; offset from report start, in bits	96	offset dd ? ; offset from report start, in bits
92	; Following fields are decoded from report descriptor, see HID spec for details.	97	; Following fields are decoded from report descriptor, see HID spec for details.
93	flags dd ?	98	flags dd ?
94	logical_minimum dd ?	99	logical_minimum dd ?
95	logical_maximum dd ?	100	logical_maximum dd ?
96	physical_minimum dd ?	101	physical_minimum dd ?
97	physical_maximum dd ?	102	physical_maximum dd ?
98	unit_exponent dd ?	103	unit_exponent dd ?
99	unit dd ?	104	unit dd ?
100	; Following fields are used to speedup extract_field_value.	105	; Following fields are used to speedup extract_field_value.
101	mask dd ?	106	mask dd ?
102	; Bitmask for all data bits except sign bit:	107	; Bitmask for all data bits except sign bit:
103	; (1 shl .size) - 1 for unsigned fields, (1 shl (.size-1)) - 1 for signed fields	108	; (1 shl .size) - 1 for unsigned fields, (1 shl (.size-1)) - 1 for signed fields
104	sign_mask dd ?	109	sign_mask dd ?
105	; Zero for unsigned fields. Bitmask with sign bit set for signed fields.	110	; Zero for unsigned fields. Bitmask with sign bit set for signed fields.
106	common_sizeof rd 0	111	common_sizeof rd 0
107	; Variable and Array field groups differ significantly.	112	; Variable and Array field groups differ significantly.
108	; Variable field groups are simple. There are .count fields, each field has	113	; Variable field groups are simple. There are .count fields, each field has
109	; predefined Usage, the content of a field is its value. Each field is	114	; predefined Usage, the content of a field is its value. Each field is
110	; always present in the report. For Variable field groups, we just keep	115	; always present in the report. For Variable field groups, we just keep
111	; additional .count dwords with usages for individual fields.	116	; additional .count dwords with usages for individual fields.
112	; Array field groups are complicated. There are .count uniform fields.	117	; Array field groups are complicated. There are .count uniform fields.
113	; The content of a field determines Usage; Usages which are currently presented	118	; The content of a field determines Usage; Usages which are currently presented
114	; in the report have value = 1, other Usages have value = 0. The number of	119	; in the report have value = 1, other Usages have value = 0. The number of
115	; possible Usages is limited only by field .size; 32-bit field could encode any	120	; possible Usages is limited only by field .size; 32-bit field could encode any
116	; Usage, so it is unreasonable to keep all Usages in the plain array, as with	121	; Usage, so it is unreasonable to keep all Usages in the plain array, as with
117	; Variable fields. However, many unrelated Usages in one group are meaningless,	122	; Variable fields. However, many unrelated Usages in one group are meaningless,
118	; so usually possible values are grouped in sequential ranges; number of ranges	123	; so usually possible values are grouped in sequential ranges; number of ranges
119	; is limited by report descriptor size (max 0xFFFF bytes should contain all	124	; is limited by report descriptor size (max 0xFFFF bytes should contain all
120	; information, including usage ranges and field descriptions).	125	; information, including usage ranges and field descriptions).
121	; Also, for Array variables we pass changes in state to drivers, not the state	126	; Also, for Array variables we pass changes in state to drivers, not the state
122	; itself, because sending information about all possible Usages is inpractical;	127	; itself, because sending information about all possible Usages is inpractical;
123	; so we should remember the previous state in addition to the current state.	128	; so we should remember the previous state in addition to the current state.
124	; Thus, for Array variables keep the following information, in this order:	129	; Thus, for Array variables keep the following information, in this order:
125	; * some members listed below; note that they do NOT exist for Variable groups;	130	; * some members listed below; note that they do NOT exist for Variable groups;
126	; * array of usage ranges in form of usage_range structures, including	131	; * array of usage ranges in form of usage_range structures, including
127	; an additional dword after array described in usage_range structure;	132	; an additional dword after array described in usage_range structure;
128	; * allocated memory for current values of the report;	133	; * allocated memory for current values of the report;
129	; * values of the previous report.	134	; * values of the previous report.
130	num_values_prev dd ? ; number of values in the previous report	135	num_values_prev dd ? ; number of values in the previous report
131	num_usage_ranges dd ? ; number of usage_range, always nonzero	136	num_usage_ranges dd ? ; number of usage_range, always nonzero
132	usages rd 0	137	usages rd 0
133	ends	138	ends
134		139
135	; This structure describes one report.	140	; This structure describes one report.
136	; All reports of one type are organized into a single-linked list.	141	; All reports of one type are organized into a single-linked list.
137	struct report	142	struct report
138	next dd ? ; pointer to next report of the same type, if any	143	next dd ? ; pointer to next report of the same type, if any
139	size dd ? ; total size in bits	144	size dd ? ; total size in bits
140	first_field dd ? ; pointer to first report_field_group for this report	145	first_field dd ? ; pointer to first report_field_group for this report
141	last_field dd ?	146	last_field dd ?
142	; pointer to last report_field_group for this report, if any;	147	; pointer to last report_field_group for this report, if any;
143	; address of .first_field, if .first_field is 0	148	; address of .first_field, if .first_field is 0
144	id dd ?	149	id dd ?
145	; Report ID, if assigned. Zero otherwise.	150	; Report ID, if assigned. Zero otherwise.
146	top_level_collection dd ? ; top-level collection for this report	151	top_level_collection dd ? ; top-level collection for this report
147	ends	152	ends
148		153
149	; This structure describes a set of reports of the same type;	154	; This structure describes a set of reports of the same type;
150	; there are 3 sets (possibly empty), input, output and feature.	155	; there are 3 sets (possibly empty), input, output and feature.
151	struct report_set	156	struct report_set
152	data dd ?	157	data dd ?
153	; If .numbered is zero, this is zero for the empty set and	158	; If .numbered is zero, this is zero for the empty set and
154	; a pointer to the (only) report structure otherwise.	159	; a pointer to the (only) report structure otherwise.
155	; If .numbered is nonzero, this is a pointer to 256-dword array of pointers	160	; If .numbered is nonzero, this is a pointer to 256-dword array of pointers
156	; to reports organized by report ID.	161	; to reports organized by report ID.
157	first_report dd ?	162	first_report dd ?
158	; Pointer to the first report or 0 for the empty set.	163	; Pointer to the first report or 0 for the empty set.
159	numbered db ?	164	numbered db ?
160	; If zero, report IDs are not used, there can be at most one report in the set.	165	; If zero, report IDs are not used, there can be at most one report in the set.
161	; If nonzero, first byte of the report is report ID.	166	; If nonzero, first byte of the report is report ID.
162	rb 3 ; padding	167	rb 3 ; padding
163	ends	168	ends
164		169
165	; This structure describes a range of reports of one type that belong to	170	; This structure describes a range of reports of one type that belong to
166	; some collection.	171	; some collection.
167	struct collection_report_set	172	struct collection_report_set
168	first_report dd ?	173	first_report dd ?
169	first_field dd ?	174	first_field dd ?
170	last_report dd ?	175	last_report dd ?
171	last_field dd ?	176	last_field dd ?
172	ends	177	ends
173		178
174	; This structure defines driver callbacks which are used while	179	; This structure defines driver callbacks which are used while
175	; device is active; i.e. all callbacks except add_device.	180	; device is active; i.e. all callbacks except add_device.
176	struct hid_driver_active_callbacks	181	struct hid_driver_active_callbacks
177	disconnect dd ?	182	disconnect dd ?
178	; Called when an existing HID device is disconnected.	183	; Called when an existing HID device is disconnected.
179	;	184	;
180	; Four following functions are called when a new input packet arrives	185	; Four following functions are called when a new input packet arrives
181	; in the following order: .begin_packet, then .input_field several times	186	; in the following order: .begin_packet, then .input_field several times
182	; for each input field, interleaved with .array_overflow? for array groups,	187	; for each input field, interleaved with .array_overflow? for array groups,
183	; then .end_packet.	188	; then .end_packet.
184	begin_packet dd ?	189	begin_packet dd ?
185	; edi -> driver data	190	; edi -> driver data
186	array_overflow? dd ?	191	array_overflow? dd ?
187	; edi -> driver data	192	; edi -> driver data
188	; out: CF cleared <=> ignore this array	193	; out: CF cleared <=> ignore this array
189	input_field dd ?	194	input_field dd ?
190	; edi -> driver data, ecx = usage, edx = value	195	; edi -> driver data, ecx = usage, edx = value
191	end_packet dd ?	196	end_packet dd ?
192	; edi -> driver data	197	; edi -> driver data
193	ends	198	ends
194		199
195	; This structure describes one collection.	200	; This structure describes one collection.
196	struct collection	201	struct collection
197	next dd ? ; pointer to the next collection in the same level	202	next dd ? ; pointer to the next collection in the same level
198	; must be the first field	203	; must be the first field
199	parent dd ? ; pointer to nesting collection	204	parent dd ? ; pointer to nesting collection
200	first_child dd ? ; pointer to the first nested collection	205	first_child dd ? ; pointer to the first nested collection
201	last_child dd ? ; pointer to the last nested collection	206	last_child dd ? ; pointer to the last nested collection
202	; or to .first_child, if .first_child is zero	207	; or to .first_child, if .first_child is zero
203	type dd ? ; Application, Physical etc	208	type dd ? ; Application, Physical etc
204	usage dd ? ; associated Usage code	209	usage dd ? ; associated Usage code
205	; Next fields are filled only for top-level collections.	210	; Next fields are filled only for top-level collections.
206	callbacks hid_driver_active_callbacks	211	callbacks hid_driver_active_callbacks
207	driver_data dd ? ; value to be passed as is to driver callbacks	212	driver_data dd ? ; value to be passed as is to driver callbacks
208	input collection_report_set	213	input collection_report_set
209	output collection_report_set	214	output collection_report_set
210	feature collection_report_set	215	feature collection_report_set
211	ends	216	ends
212		217
213	; This structure keeps all data used by the HID layer for one device.	218	; This structure keeps all data used by the HID layer for one device.
214	struct hid_data	219	struct hid_data
215	input report_set	220	input report_set
216	output report_set	221	output report_set
217	feature report_set	222	feature report_set
218	first_collection dd ?	223	first_collection dd ?
219	ends	224	ends
220		225
221	; This structure defines callbacks required from the driver.	226	; This structure defines callbacks required from the driver.
222	struct hid_driver_callbacks	227	struct hid_driver_callbacks
223	add_device dd ?	228	add_device dd ?
224	; Called when a new HID device is connected.	229	; Called when a new HID device is connected.
225	active hid_driver_active_callbacks	230	active hid_driver_active_callbacks
226	ends	231	ends
227		232
228	; Two following structures describe temporary data;	233	; Two following structures describe temporary data;
229	; the corresponding objects cease to exist when HID parser completes	234	; the corresponding objects cease to exist when HID parser completes
230	; state of Global items	235	; state of Global items
231	struct global_items	236	struct global_items
232	next dd ?	237	next dd ?
233	usage_page dd ?	238	usage_page dd ?
234	logical_minimum dd ?	239	logical_minimum dd ?
235	logical_maximum dd ?	240	logical_maximum dd ?
236	physical_minimum dd ?	241	physical_minimum dd ?
237	physical_maximum dd ?	242	physical_maximum dd ?
238	unit_exponent dd ?	243	unit_exponent dd ?
239	unit dd ?	244	unit dd ?
240	report_size dd ?	245	report_size dd ?
241	report_id dd ?	246	report_id dd ?
242	report_count dd ?	247	report_count dd ?
243	ends	248	ends
244		249
245	; one range of Usages	250	; one range of Usages
246	struct usage_list_item	251	struct usage_list_item
247	next dd ?	252	next dd ?
248	first_usage dd ?	253	first_usage dd ?
249	num_usages dd ?	254	num_usages dd ?
250	ends	255	ends
251		256
252	; =============================================================================	257	; =============================================================================
253	; =================================== Code ====================================	258	; =================================== Code ====================================
254	; =============================================================================	259	; =============================================================================
255		260
256	macro workers_globals	261	macro workers_globals
257	{	262	{
258	workers_globals	263	workers_globals
259	; Jump tables for switch'ing in the code.	264	; Jump tables for switch'ing in the code.
260	align 4	265	align 4
261	; jump table for two lower bits which encode size of item data	266	; jump table for two lower bits which encode size of item data
262	parse_descr_label.fetch_jumps:	267	parse_descr_label.fetch_jumps:
263	dd parse_descr_label.fetch_none ; x0, x4, x8, xC	268	dd parse_descr_label.fetch_none ; x0, x4, x8, xC
264	dd parse_descr_label.fetch_byte ; x1, x5, x9, xD	269	dd parse_descr_label.fetch_byte ; x1, x5, x9, xD
265	dd parse_descr_label.fetch_word ; x2, x6, xA, xE	270	dd parse_descr_label.fetch_word ; x2, x6, xA, xE
266	dd parse_descr_label.fetch_dword ; x3, x7, xB, xF	271	dd parse_descr_label.fetch_dword ; x3, x7, xB, xF
267	; jump table for two next bits which encode item type	272	; jump table for two next bits which encode item type
268	parse_descr_label.type_jumps:	273	parse_descr_label.type_jumps:
269	dd parse_descr_label.parse_main	274	dd parse_descr_label.parse_main
270	dd parse_descr_label.parse_global	275	dd parse_descr_label.parse_global
271	dd parse_descr_label.parse_local	276	dd parse_descr_label.parse_local
272	dd parse_descr_label.parse_reserved	277	dd parse_descr_label.parse_reserved
273	; jump table for 4 upper bits in the case of Main item	278	; jump table for 4 upper bits in the case of Main item
274	parse_descr_label.main_jumps:	279	parse_descr_label.main_jumps:
275	dd parse_descr_label.input ; 80...83	280	dd parse_descr_label.input ; 80...83
276	dd parse_descr_label.output ; 90...93	281	dd parse_descr_label.output ; 90...93
277	dd parse_descr_label.collection ; A0...A3	282	dd parse_descr_label.collection ; A0...A3
278	dd parse_descr_label.feature ; B0...B3	283	dd parse_descr_label.feature ; B0...B3
279	dd parse_descr_label.end_collection ; C0...C3	284	dd parse_descr_label.end_collection ; C0...C3
280	parse_descr_label.num_main_items = ($ - parse_descr_label.main_jumps) / 4	285	parse_descr_label.num_main_items = ($ - parse_descr_label.main_jumps) / 4
281	; jump table for 4 upper bits in the case of Global item	286	; jump table for 4 upper bits in the case of Global item
282	parse_descr_label.global_jumps:	287	parse_descr_label.global_jumps:
283	dd parse_descr_label.usage_page ; 04...07	288	dd parse_descr_label.usage_page ; 04...07
284	dd parse_descr_label.logical_minimum ; 14...17	289	dd parse_descr_label.logical_minimum ; 14...17
285	dd parse_descr_label.logical_maximum ; 24...27	290	dd parse_descr_label.logical_maximum ; 24...27
286	dd parse_descr_label.physical_minimum ; 34...37	291	dd parse_descr_label.physical_minimum ; 34...37
287	dd parse_descr_label.physical_maximum ; 44...47	292	dd parse_descr_label.physical_maximum ; 44...47
288	dd parse_descr_label.unit_exponent ; 54...57	293	dd parse_descr_label.unit_exponent ; 54...57
289	dd parse_descr_label.unit ; 64...67	294	dd parse_descr_label.unit ; 64...67
290	dd parse_descr_label.report_size ; 74...77	295	dd parse_descr_label.report_size ; 74...77
291	dd parse_descr_label.report_id ; 84...87	296	dd parse_descr_label.report_id ; 84...87
292	dd parse_descr_label.report_count ; 94...97	297	dd parse_descr_label.report_count ; 94...97
293	dd parse_descr_label.push ; A4...A7	298	dd parse_descr_label.push ; A4...A7
294	dd parse_descr_label.pop ; B4...B7	299	dd parse_descr_label.pop ; B4...B7
295	parse_descr_label.num_global_items = ($ - parse_descr_label.global_jumps) / 4	300	parse_descr_label.num_global_items = ($ - parse_descr_label.global_jumps) / 4
296	; jump table for 4 upper bits in the case of Local item	301	; jump table for 4 upper bits in the case of Local item
297	parse_descr_label.local_jumps:	302	parse_descr_label.local_jumps:
298	dd parse_descr_label.usage ; 08...0B	303	dd parse_descr_label.usage ; 08...0B
299	dd parse_descr_label.usage_minimum ; 18...1B	304	dd parse_descr_label.usage_minimum ; 18...1B
300	dd parse_descr_label.usage_maximum ; 28...2B	305	dd parse_descr_label.usage_maximum ; 28...2B
301	dd parse_descr_label.item_parsed ; 38...3B = designator item; ignore	306	dd parse_descr_label.item_parsed ; 38...3B = designator item; ignore
302	dd parse_descr_label.item_parsed ; 48...4B = designator minimum; ignore	307	dd parse_descr_label.item_parsed ; 48...4B = designator minimum; ignore
303	dd parse_descr_label.item_parsed ; 58...5B = designator maximum; ignore	308	dd parse_descr_label.item_parsed ; 58...5B = designator maximum; ignore
304	dd parse_descr_label.item_parsed ; 68...6B not assigned	309	dd parse_descr_label.item_parsed ; 68...6B not assigned
305	dd parse_descr_label.item_parsed ; 78...7B = string index; ignore	310	dd parse_descr_label.item_parsed ; 78...7B = string index; ignore
306	dd parse_descr_label.item_parsed ; 88...8B = string minimum; ignore	311	dd parse_descr_label.item_parsed ; 88...8B = string minimum; ignore
307	dd parse_descr_label.item_parsed ; 98...9B = string maximum; ignore	312	dd parse_descr_label.item_parsed ; 98...9B = string maximum; ignore
308	dd parse_descr_label.delimiter ; A8...AB	313	dd parse_descr_label.delimiter ; A8...AB
309	parse_descr_label.num_local_items = ($ - parse_descr_label.local_jumps) / 4	314	parse_descr_label.num_local_items = ($ - parse_descr_label.local_jumps) / 4
310	}	315	}
311		316
312	; Local variables for parse_descr.	317	; Local variables for parse_descr.
313	macro parse_descr_locals	318	macro parse_descr_locals
314	{	319	{
315	cur_item_size dd ? ; encoded size of data for current item	320	cur_item_size dd ? ; encoded size of data for current item
316	report_ok db ? ; 0 on error, 1 if everything is ok	321	report_ok db ? ; 0 on error, 1 if everything is ok
317	field_type db ? ; 0/1/2 for input/output/feature fields	322	field_type db ? ; 0/1/2 for input/output/feature fields
318	rb 2 ; alignment	323	rb 2 ; alignment
319	field_data dd ? ; data for current item when it describes a field group	324	field_data dd ? ; data for current item when it describes a field group
320	last_reports rd 3 ; pointers to last input/output/feature records	325	last_reports rd 3 ; pointers to last input/output/feature records
321	usage_minimum dd ? ; current value of Usage Minimum	326	usage_minimum dd ? ; current value of Usage Minimum
322	usage_list dd ? ; list head of usage_list_item	327	usage_list dd ? ; list head of usage_list_item
323	usage_tail dd ? ; list tail of usage_list_item	328	usage_tail dd ? ; list tail of usage_list_item
324	num_usage_ranges dd ? ; number of usage ranges, size of usage_list	329	num_usage_ranges dd ? ; number of usage ranges, size of usage_list
325	delimiter_depth dd ? ; normally 0; 1 inside of Delimiter();	330	delimiter_depth dd ? ; normally 0; 1 inside of Delimiter();
326	; nested Delimiter()s are not allowed	331	; nested Delimiter()s are not allowed
327	usage_variant dd ? ; 0 outside of Delimiter()s and for first Usage inside Delimiter(),	332	usage_variant dd ? ; 0 outside of Delimiter()s and for first Usage inside Delimiter(),
328	; incremented with each new Usage inside Delimiter()	333	; incremented with each new Usage inside Delimiter()
329	cur_collection dd ? ; current collection	334	cur_collection dd ? ; current collection
330	last_collection dd ? ; last top-level collection	335	last_collection dd ? ; last top-level collection
331	}	336	}
332		337
333	; Parse report descriptor. The caller should provide local variables	338	; Parse report descriptor. The caller should provide local variables
334	; [buffer] = pointer to report descriptor, [length] = length of report descriptor,	339	; [buffer] = pointer to report descriptor, [length] = length of report descriptor,
335	; [calldata] = pointer to hid_data (possibly wrapped in a large structure).	340	; [calldata] = pointer to hid_data (possibly wrapped in a large structure).
336	macro parse_descr	341	macro parse_descr
337	{	342	{
338	parse_descr_label:	343	parse_descr_label:
339	; 1. Initialize.	344	; 1. Initialize.
340	; 1a. Set some variables to initial values.	345	; 1a. Set some variables to initial values.
341	xor edi, edi	346	xor edi, edi
342	mov dword [report_ok], edi	347	mov dword [report_ok], edi
343	mov [usage_list], edi	348	mov [usage_list], edi
344	mov [cur_collection], edi	349	mov [cur_collection], edi
345	mov eax, [calldata]	350	mov eax, [calldata]
346	add eax, hid_data.input.first_report	351	add eax, hid_data.input.first_report
347	mov [last_reports+0*4], eax	352	mov [last_reports+0*4], eax
348	add eax, hid_data.output.first_report - hid_data.input.first_report	353	add eax, hid_data.output.first_report - hid_data.input.first_report
349	mov [last_reports+1*4], eax	354	mov [last_reports+1*4], eax
350	add eax, hid_data.feature.first_report - hid_data.output.first_report	355	add eax, hid_data.feature.first_report - hid_data.output.first_report
351	mov [last_reports+2*4], eax	356	mov [last_reports+2*4], eax
352	add eax, hid_data.first_collection - hid_data.feature.first_report	357	add eax, hid_data.first_collection - hid_data.feature.first_report
353	mov [last_collection], eax	358	mov [last_collection], eax
354	; 1b. Allocate state of global items.	359	; 1b. Allocate state of global items.
355	movi eax, sizeof.global_items	360	movi eax, sizeof.global_items
356	invoke Kmalloc	361	invoke Kmalloc
357	test eax, eax	362	test eax, eax
358	jz .memory_error	363	jz .memory_error
359	; 1c. Zero-initialize it and move pointer to edi.	364	; 1c. Zero-initialize it and move pointer to edi.
360	push eax	365	push eax
361	xchg eax, edi	366	xchg eax, edi
362	movi ecx, sizeof.global_items / 4	367	movi ecx, sizeof.global_items / 4
363	rep stosd	368	rep stosd
364	pop edi	369	pop edi
365	; 1d. Load pointer to data into esi and make [length] point to end of data.	370	; 1d. Load pointer to data into esi and make [length] point to end of data.
366	mov esi, [buffer]	371	mov esi, [buffer]
367	add [length], esi	372	add [length], esi
368	; 2. Clear all local items.	373	; 2. Clear all local items.
369	; This is needed in the beginning and after processing any Main item.	374	; This is needed in the beginning and after processing any Main item.
370	.zero_local_items:	375	.zero_local_items:
371	mov eax, [usage_list]	376	mov eax, [usage_list]
372	@@:	377	@@:
373	test eax, eax	378	test eax, eax
374	jz @f	379	jz @f
375	push [eax+usage_list_item.next]	380	push [eax+usage_list_item.next]
376	invoke Kfree	381	invoke Kfree
377	pop eax	382	pop eax
378	jmp @b	383	jmp @b
379	@@:	384	@@:
380	lea ecx, [usage_list]	385	lea ecx, [usage_list]
381	mov [usage_tail], ecx	386	mov [usage_tail], ecx
382	mov [ecx], eax	387	mov [ecx], eax
383	mov [delimiter_depth], eax	388	mov [delimiter_depth], eax
384	mov [usage_variant], eax	389	mov [usage_variant], eax
385	mov [usage_minimum], eax	390	mov [usage_minimum], eax
386	mov [num_usage_ranges], eax	391	mov [num_usage_ranges], eax
387	; 3. Parse items until end of data found.	392	; 3. Parse items until end of data found.
388	cmp esi, [length]	393	cmp esi, [length]
389	jae .parse_end	394	jae .parse_end
390	.fetch_next_item:	395	.fetch_next_item:
391	; --------------------------------- Parse item --------------------------------	396	; --------------------------------- Parse item --------------------------------
392	; 4. Parse one item.	397	; 4. Parse one item.
393	; 4a. Get item data. eax = first item byte = code+type+size (4+2+2 bits),	398	; 4a. Get item data. eax = first item byte = code+type+size (4+2+2 bits),
394	; ebx = item data interpreted as unsigned,	399	; ebx = item data interpreted as unsigned,
395	; ecx = item data interpreted as signed.	400	; ecx = item data interpreted as signed.
396	movzx eax, byte [esi]	401	movzx eax, byte [esi]
397	mov ecx, eax	402	mov ecx, eax
398	and ecx, 3	403	and ecx, 3
399	mov [cur_item_size], ecx	404	mov [cur_item_size], ecx
400	jmp dword [.fetch_jumps+ecx*4]	405	jmp dword [.fetch_jumps+ecx*4]
401	.invalid_report:	406	.invalid_report:
402	mov esi, invalid_report_msg	407	mov esi, invalid_report_msg
403	jmp .end_str	408	jmp .end_str
404	.fetch_none:	409	.fetch_none:
405	xor ebx, ebx	410	xor ebx, ebx
406	xor ecx, ecx	411	xor ecx, ecx
407	inc esi	412	inc esi
408	jmp .fetched	413	jmp .fetched
409	.fetch_byte:	414	.fetch_byte:
410	add esi, 2	415	add esi, 2
411	cmp esi, [length]	416	cmp esi, [length]
412	ja .invalid_report	417	ja .invalid_report
413	movzx ebx, byte [esi-1]	418	movzx ebx, byte [esi-1]
414	movsx ecx, bl	419	movsx ecx, bl
415	jmp .fetched	420	jmp .fetched
416	.fetch_word:	421	.fetch_word:
417	add esi, 3	422	add esi, 3
418	cmp esi, [length]	423	cmp esi, [length]
419	ja .invalid_report	424	ja .invalid_report
420	movzx ebx, word [esi-2]	425	movzx ebx, word [esi-2]
421	movsx ecx, bx	426	movsx ecx, bx
422	jmp .fetched	427	jmp .fetched
423	.fetch_dword:	428	.fetch_dword:
424	add esi, 5	429	add esi, 5
425	cmp esi, [length]	430	cmp esi, [length]
426	ja .invalid_report	431	ja .invalid_report
427	mov ebx, dword [esi-4]	432	mov ebx, dword [esi-4]
428	mov ecx, ebx	433	mov ecx, ebx
429	.fetched:	434	.fetched:
430	; 4b. Select the branch according to item type.	435	; 4b. Select the branch according to item type.
431	; For every type, select the concrete handler and go there.	436	; For every type, select the concrete handler and go there.
432	mov edx, eax	437	mov edx, eax
433	shr edx, 2	438	shr edx, 2
434	and edx, 3	439	and edx, 3
435	shr eax, 4	440	shr eax, 4
436	jmp dword [.type_jumps+edx*4]	441	jmp dword [.type_jumps+edx*4]
437	; -------------------------------- Main items ---------------------------------	442	; -------------------------------- Main items ---------------------------------
438	.parse_main:	443	.parse_main:
439	sub eax, 8	444	sub eax, 8
440	cmp eax, .num_main_items	445	cmp eax, .num_main_items
441	jae .item_parsed	446	jae .item_parsed
442	jmp dword [.main_jumps+eax*4]	447	jmp dword [.main_jumps+eax*4]
443	; There are 5 Main items.	448	; There are 5 Main items.
444	; Input/Output/Feature items create new field groups in the corresponding report;	449	; Input/Output/Feature items create new field groups in the corresponding report;
445	; Collection item opens a new collection (possibly nested),	450	; Collection item opens a new collection (possibly nested),
446	; End Collection item closes the most nested collection.	451	; End Collection item closes the most nested collection.
447	.output:	452	.output:
448	mov [field_type], 1	453	mov [field_type], 1
449	jmp .new_field	454	jmp .new_field
450	.feature:	455	.feature:
451	mov [field_type], 2	456	mov [field_type], 2
452	jmp .new_field	457	jmp .new_field
453	.input:	458	.input:
454	mov [field_type], 0	459	mov [field_type], 0
455	.new_field:	460	.new_field:
456	; Create a new field group.	461	; Create a new field group.
457	mov [field_data], ebx	462	mov [field_data], ebx
458	movzx ebx, [field_type]	463	movzx ebx, [field_type]
459	if sizeof.report_set = 12	464	if sizeof.report_set = 12
460	lea ebx, [ebx*3]	465	lea ebx, [ebx*3]
461	shl ebx, 2	466	shl ebx, 2
462	else	467	else
463	err Change the code	468	err Change the code
464	end if	469	end if
465	add ebx, [calldata]	470	add ebx, [calldata]
466	; 5. Sanity checks: field size and fields count must be nonzero,	471	; 5. Sanity checks: field size and fields count must be nonzero,
467	; field size cannot be more than 32 bits,	472	; field size cannot be more than 32 bits,
468	; if field count is more than MAX_REPORT_SIZE * 8, the report would be more than	473	; if field count is more than MAX_REPORT_SIZE * 8, the report would be more than
469	; MAX_REPORT_SIZE bytes, so it is invalid too.	474	; MAX_REPORT_SIZE bytes, so it is invalid too.
470	; More precise check for size occurs later; this check only guarantees that	475	; More precise check for size occurs later; this check only guarantees that
471	; there will be no overflows during subsequent calculations.	476	; there will be no overflows during subsequent calculations.
472	cmp [edi+global_items.report_size], 0	477	cmp [edi+global_items.report_size], 0
473	jz .invalid_report	478	jz .invalid_report
474	cmp [edi+global_items.report_size], 32	479	cmp [edi+global_items.report_size], 32
475	ja .invalid_report	480	ja .invalid_report
476	; There are devices with Report Count(0) + Input(Constant Variable),	481	; There are devices with Report Count(0) + Input(Constant Variable),
477	; zero-length padding. Thus, do not consider descriptors with Report Count(0)	482	; zero-length padding. Thus, do not consider descriptors with Report Count(0)
478	; as invalid; instead, just ignore fields with Report Count(0).	483	; as invalid; instead, just ignore fields with Report Count(0).
479	cmp [edi+global_items.report_count], 0	484	cmp [edi+global_items.report_count], 0
480	jz .zero_local_items	485	jz .zero_local_items
481	cmp [edi+global_items.report_count], MAX_REPORT_BYTES * 8	486	cmp [edi+global_items.report_count], MAX_REPORT_BYTES * 8
482	ja .invalid_report	487	ja .invalid_report
483	; 6. Get the pointer to the place for the corresponding report in ebx.	488	; 6. Get the pointer to the place for the corresponding report in ebx.
484	; 6a. If report ID is not assigned, ebx already points to report_set.data,	489	; 6a. If report ID is not assigned, ebx already points to report_set.data,
485	; so go to 7.	490	; so go to 7.
486	cmp [edi+global_items.report_id], 0	491	cmp [edi+global_items.report_id], 0
487	jz .report_ptr_found	492	jz .report_ptr_found
488	; 6b. If table for reports was already allocated,	493	; 6b. If table for reports was already allocated,
489	; go to 6d skipping the next substep.	494	; go to 6d skipping the next substep.
490	cmp [ebx+report_set.numbered], 0	495	cmp [ebx+report_set.numbered], 0
491	jnz .report_set_allocated	496	jnz .report_set_allocated
492	; 6c. This is the first report with ID;	497	; 6c. This is the first report with ID;
493	; allocate and zero-initialize table for reports.	498	; allocate and zero-initialize table for reports.
494	; Note: it is incorrect but theoretically possible that some fields were	499	; Note: it is incorrect but theoretically possible that some fields were
495	; already allocated in report without ID; if so, abort processing with error.	500	; already allocated in report without ID; if so, abort processing with error.

Subversion Repositories Kolibri OS

(root)/drivers/usb/usbhid/report.inc – Rev 5051 → 5148