/*
* Copyright (c) 2011 Matej Klonfar
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* - The name of the author may not be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/** @addtogroup libusb
* @{
*/
/** @file
* @brief USB HID Report descriptor item tags.
*/
#ifndef LIBUSB_HID_REPORT_ITEMS_H_
#define LIBUSB_HID_REPORT_ITEMS_H_
#include <stdint.h>
/*
* Item prefix
*/
/** Returns size of item data in bytes */
#define USB_HID_ITEM_SIZE(data) ((uint8_t)(data & 0x3))
/** Returns item tag */
#define USB_HID_ITEM_TAG(data) ((uint8_t)((data & 0xF0) >> 4))
/** Returns class of item tag */
#define USB_HID_ITEM_TAG_CLASS(data) ((uint8_t)((data & 0xC) >> 2))
/** Returns if the item is the short item or long item. Long items are not
* supported.
*/
#define USB_HID_ITEM_IS_LONG(data) (data == 0xFE)
/*
* Extended usage macros
*/
/** Recognizes if the given usage is extended (contains also usage page). */
#define USB_HID_IS_EXTENDED_USAGE(usage) ((usage & 0xFFFF0000) != 0)
/** Cuts usage page of the extended usage. */
#define USB_HID_EXTENDED_USAGE_PAGE(usage) ((usage & 0xFFFF0000) >> 16)
/** Cuts usage of the extended usage */
#define USB_HID_EXTENDED_USAGE(usage) (usage & 0xFFFF)
/*
* Input/Output/Feature Item flags
*/
/**
* Indicates whether the item is data (0) or a constant (1) value. Data
* indicates the item is defining report fields that contain modifiable device
* data. Constant indicates the item is a static read-only field in a report
* and cannot be modified (written) by the host.
*/
#define USB_HID_ITEM_FLAG_CONSTANT(flags) ((flags & 0x1) == 0x1)
/**
* Indicates whether the item creates variable (1) or array (0) data fields in
* reports.
*/
#define USB_HID_ITEM_FLAG_VARIABLE(flags) ((flags & 0x2) == 0x2)
/**
* Indicates whether the data is absolute (0) (based on a fixed origin) or
* relative (1) (indicating the change in value from the last report). Mouse
* devices usually provide relative data, while tablets usually provide
* absolute data.
*/
#define USB_HID_ITEM_FLAG_RELATIVE(flags) ((flags & 0x4) == 0x4)
/** Indicates whether the data “rolls over” when reaching either the extreme
* high or low value. For example, a dial that can spin freely 360 degrees
* might output values from 0 to 10. If Wrap is indicated, the next value
* reported after passing the 10 position in the increasing direction would be
* 0.
*/
#define USB_HID_ITEM_FLAG_WRAP(flags) ((flags & 0x8) == 0x8)
/**
* Indicates whether the raw data from the device has been processed in some
* way, and no longer represents a linear relationship between what is
* measured and the data that is reported.
*/
#define USB_HID_ITEM_FLAG_LINEAR(flags) ((flags & 0x10) == 0x10)
/**
* Indicates whether the control has a preferred state to which it will return
* when the user is not physically interacting with the control. Push buttons
* (as opposed to toggle buttons) and self- centering joysticks are examples.
*/
#define USB_HID_ITEM_FLAG_PREFERRED(flags) ((flags & 0x20) == 0x20)
/**
* Indicates whether the control has a state in which it is not sending
* meaningful data. One possible use of the null state is for controls that
* require the user to physically interact with the control in order for it to
* report useful data.
*/
#define USB_HID_ITEM_FLAG_POSITION(flags) ((flags & 0x40) == 0x40)
/**
* Indicates whether the Feature or Output control's value should be changed
* by the host or not. Volatile output can change with or without host
* interaction. To avoid synchronization problems, volatile controls should be
* relative whenever possible.
*/
#define USB_HID_ITEM_FLAG_VOLATILE(flags) ((flags & 0x80) == 0x80)
/**
* Indicates that the control emits a fixed-size stream of bytes. The contents
* of the data field are determined by the application. The contents of the
* buffer are not interpreted as a single numeric quantity. Report data
* defined by a Buffered Bytes item must be aligned on an 8-bit boundary.
*/
#define USB_HID_ITEM_FLAG_BUFFERED(flags) ((flags & 0x100) == 0x100)
/* MAIN ITEMS */
/**
* Main items are used to either define or group certain types of data fields
* within a Report descriptor.
*/
#define USB_HID_TAG_CLASS_MAIN 0x0
/**
* An Input item describes information about the data provided by one or more
* physical controls. An application can use this information to interpret the
* data provided by the device. All data fields defined in a single item share
* an identical data format.
*/
#define USB_HID_REPORT_TAG_INPUT 0x8
/**
* The Output item is used to define an output data field in a report. This
* item is similar to an Input item except it describes data sent to the
* device—for example, LED states.
*/
#define USB_HID_REPORT_TAG_OUTPUT 0x9
/**
* Feature items describe device configuration information that can be sent to
* the device.
*/
#define USB_HID_REPORT_TAG_FEATURE 0xB
/**
* A Collection item identifies a relationship between two or more data
* (Input, Output, or Feature.)
*/
#define USB_HID_REPORT_TAG_COLLECTION 0xA
/**
* While the Collection item opens a collection of data, the End Collection
* item closes a collection.
*/
#define USB_HID_REPORT_TAG_END_COLLECTION 0xC
/* GLOBAL ITEMS */
/**
* Global items describe rather than define data from a control.
*/
#define USB_HID_TAG_CLASS_GLOBAL 0x1
/**
* Unsigned integer specifying the current Usage Page. Since a usage are 32
* bit values, Usage Page items can be used to conserve space in a report
* descriptor by setting the high order 16 bits of a subsequent usages. Any
* usage that follows which is defines 16 bits or less is interpreted as a
* Usage ID and concatenated with the Usage Page to form a 32 bit Usage.
*/
#define USB_HID_REPORT_TAG_USAGE_PAGE 0x0
/**
* Extent value in logical units. This is the minimum value that a variable
* or array item will report. For example, a mouse reporting x position values
* from 0 to 128 would have a Logical Minimum of 0 and a Logical Maximum of
* 128.
*/
#define USB_HID_REPORT_TAG_LOGICAL_MINIMUM 0x1
/**
* Extent value in logical units. This is the maximum value that a variable
* or array item will report.
*/
#define USB_HID_REPORT_TAG_LOGICAL_MAXIMUM 0x2
/**
* Minimum value for the physical extent of a variable item. This represents
* the Logical Minimum with units applied to it.
*/
#define USB_HID_REPORT_TAG_PHYSICAL_MINIMUM 0x3
/**
* Maximum value for the physical extent of a variable item.
*/
#define USB_HID_REPORT_TAG_PHYSICAL_MAXIMUM 0x4
/**
* Value of the unit exponent in base 10. See the table later in this section
* for more information.
*/
#define USB_HID_REPORT_TAG_UNIT_EXPONENT 0x5
/**
* Unit values.
*/
#define USB_HID_REPORT_TAG_UNIT 0x6
/**
* Unsigned integer specifying the size of the report fields in bits. This
* allows the parser to build an item map for the report handler to use.
*/
#define USB_HID_REPORT_TAG_REPORT_SIZE 0x7
/**
* Unsigned value that specifies the Report ID. If a Report ID tag is used
* anywhere in Report descriptor, all data reports for the device are preceded
* by a single byte ID field. All items succeeding the first Report ID tag but
* preceding a second Report ID tag are included in a report prefixed by a
* 1-byte ID. All items succeeding the second but preceding a third Report ID
* tag are included in a second report prefixed by a second ID, and so on.
*/
#define USB_HID_REPORT_TAG_REPORT_ID 0x8
/**
* Unsigned integer specifying the number of data fields for the item;
* determines how many fields are included in the report for this particular
* item (and consequently how many bits are added to the report).
*/
#define USB_HID_REPORT_TAG_REPORT_COUNT 0x9
/**
* Places a copy of the global item state table on the stack.
*/
#define USB_HID_REPORT_TAG_PUSH 0xA
/**
* Replaces the item state table with the top structure from the stack.
*/
#define USB_HID_REPORT_TAG_POP 0xB
/* LOCAL ITEMS */
/**
* Local item tags define characteristics of controls. These items do not
* carry over to the next Main item. If a Main item defines more than one
* control, it may be preceded by several similar Local item tags. For
* example, an Input item may have several Usage tags associated with it, one
* for each control.
*/
#define USB_HID_TAG_CLASS_LOCAL 0x2
/**
* Usage index for an item usage; represents a suggested usage for the item or
* collection. In the case where an item represents multiple controls, a Usage
* tag may suggest a usage for every variable or element in an array.
*/
#define USB_HID_REPORT_TAG_USAGE 0x0
/**
* Defines the starting usage associated with an array or bitmap.
*/
#define USB_HID_REPORT_TAG_USAGE_MINIMUM 0x1
/**
* Defines the ending usage associated with an array or bitmap.
*/
#define USB_HID_REPORT_TAG_USAGE_MAXIMUM 0x2
/**
* Determines the body part used for a control. Index points to a designator
* in the Physical descriptor.
*/
#define USB_HID_REPORT_TAG_DESIGNATOR_INDEX 0x3
/**
* Defines the index of the starting designator associated with an array or
* bitmap.
*/
#define USB_HID_REPORT_TAG_DESIGNATOR_MINIMUM 0x4
/**
* Defines the index of the ending designator associated with an array or
* bitmap.
*/
#define USB_HID_REPORT_TAG_DESIGNATOR_MAXIMUM 0x5
/**
* String index for a String descriptor; allows a string to be associated with
* a particular item or control.
*/
#define USB_HID_REPORT_TAG_STRING_INDEX 0x7
/**
* Specifies the first string index when assigning a group of sequential
* strings to controls in an array or bitmap.
*/
#define USB_HID_REPORT_TAG_STRING_MINIMUM 0x8
/**
* Specifies the last string index when assigning a group of sequential
* strings to controls in an array or bitmap.
*/
#define USB_HID_REPORT_TAG_STRING_MAXIMUM 0x9
/**
* Defines the beginning or end of a set of local items (1 = open set, 0 =
* close set).
*
* Usages other than the first (most preferred) usage defined are not
* accessible by system software.
*/
#define USB_HID_REPORT_TAG_DELIMITER 0xA
#endif
/**
* @}
*/