host_hid.h File Reference


Detailed Description

Management of the generic host HID features.

This file manages the generic host HID features.

Author:
Atmel Corporation: http://www.atmel.com
Support and FAQ: http://support.atmel.no/

Definition in file host_hid.h.

#include "compiler.h"
#include "hid.h"

Go to the source code of this file.

Data Structures

struct  host_hid_item_t
 HID report descriptor item. More...

Functions

Standard Requests Applied to HID
Status_t host_hid_get_descriptor (U8 descriptor_type, U8 descriptor_index, U8 s_interface)
 Gets a HID class descriptor.
Status_t host_hid_set_descriptor (U8 descriptor_type, U8 descriptor_index, U8 s_interface, U16 length)
 Sets a HID class descriptor.
HID-Specific Requests
U8 host_hid_get_idle (U8 report_id, U8 s_interface)
 Reads the current idle rate for a particular Input report.
U8 host_hid_get_protocol (U8 s_interface)
 Reads which protocol is currently active (either the boot protocol or the report protocol).
Status_t host_hid_get_report (U8 report_type, U8 report_id, U8 s_interface)
 Gets a HID report.
Status_t host_hid_set_idle (U8 duration_4_ms, U8 report_id, U8 s_interface)
 Silences a particular report on the Interrupt In pipe until a new event occurs or the specified amount of time passes.
Status_t host_hid_set_protocol (U8 protocol, U8 s_interface)
 Switches between the boot protocol and the report protocol (or vice versa).
Status_t host_hid_set_report (U8 report_type, U8 report_id, U8 s_interface, U16 length)
 Sets a HID report.
HID Report Descriptor Parsing Functions
Status_bool_t host_hid_get_item (host_hid_item_t *item)
 Gets the next HID report descriptor item.


Function Documentation

Status_t host_hid_get_descriptor ( U8  descriptor_type,
U8  descriptor_index,
U8  s_interface 
)

Gets a HID class descriptor.

Parameters:
descriptor_type Type of the descriptor to get.
descriptor_index Index of the descriptor to get.
s_interface The supported interface number of which to get the descriptor.
Returns:
Status.

Definition at line 84 of file host_hid.c.

References hid_descriptor_t::bNumDescriptors, hid_descriptor_t::bType, hid_descriptor_t::Descriptor, HID_DESCRIPTOR, HID_REPORT_DESCRIPTOR, host_hid_report_descriptor_parser, SIZEOF_DATA_STAGE, and hid_descriptor_t::wLength.

00085 {
00086   Status_t status;
00087   const hid_descriptor_t *hid_descriptor = (hid_descriptor_t *)&data_stage;
00088   U8 i;
00089 
00090   usb_request.bmRequestType   = 0x81;
00091   usb_request.bRequest        = GET_DESCRIPTOR;
00092   usb_request.wValue          = descriptor_type << 8 | descriptor_index;
00093   usb_request.wIndex          = Get_interface_number(s_interface);
00094   usb_request.wLength         = SIZEOF_DATA_STAGE;
00095   usb_request.incomplete_read = FALSE;
00096 
00097   status = host_transfer_control(data_stage);
00098 
00099   switch (descriptor_type)
00100   {
00101   case HID_DESCRIPTOR:
00102     for (i = 0; i < hid_descriptor->bNumDescriptors; i++)
00103     {
00104       if (hid_descriptor->Descriptor[i].bType == HID_REPORT_DESCRIPTOR)
00105       {
00106         host_hid_report_descriptor_parser.length =
00107           usb_format_usb_to_mcu_data(16, hid_descriptor->Descriptor[i].wLength);
00108         break;
00109       }
00110     }
00111     break;
00112 
00113   case HID_REPORT_DESCRIPTOR:
00114     host_hid_report_descriptor_parser.item = (hid_item_t *)&data_stage;
00115     break;
00116   }
00117 
00118   return status;
00119 }

U8 host_hid_get_idle ( U8  report_id,
U8  s_interface 
)

Reads the current idle rate for a particular Input report.

Parameters:
report_id ID of the report of which to get the idle rate.
s_interface The supported interface number of which to get the idle rate.
Returns:
Idle duration with a 4-ms resolution, or HID_IDLE_DURATION_INDEFINITE.

Definition at line 169 of file host_hid.c.

References HID_GET_IDLE.

00170 {
00171   usb_request.bmRequestType   = 0xA1;
00172   usb_request.bRequest        = HID_GET_IDLE;
00173   usb_request.wValue          = 0x00 << 8 | report_id;
00174   usb_request.wIndex          = Get_interface_number(s_interface);
00175   usb_request.wLength         = 0x0001;
00176   usb_request.incomplete_read = FALSE;
00177 
00178   host_transfer_control(data_stage);
00179 
00180   return data_stage[0x00];
00181 }

Status_bool_t host_hid_get_item ( host_hid_item_t item  ) 

Gets the next HID report descriptor item.

Parameters:
item Pointer to the item structure to fill.
Returns:
Status.
Note:
host_hid_get_descriptor must have been called before this function for HID_DESCRIPTOR and HID_REPORT_DESCRIPTOR.

Definition at line 233 of file host_hid.c.

References hid_item_t::bDataSize, hid_item_t::bLongItemTag, hid_item_t::bSize, hid_item_t::bTag, hid_item_t::bType, hid_item_t::data, hid_item_t::header, HID_ITEM_TAG_LONG_ITEM, host_hid_report_descriptor_parser, host_hid_item_t::long_data, host_hid_item_t::long_format, hid_item_t::long_format, host_hid_item_t::short_data, hid_item_t::short_format, host_hid_item_t::tag, host_hid_item_t::type, and hid_short_item_data_t::value.

00234 {
00235   const hid_item_t *hid_item = host_hid_report_descriptor_parser.item;
00236   U8 size;
00237 
00238   if (host_hid_report_descriptor_parser.length <
00239       (U8 *)&hid_item->header - (U8 *)hid_item +
00240       sizeof(hid_item->header))
00241     return FALSE;
00242 
00243   item->type = hid_item->header.bType;
00244 
00245   if (hid_item->header.bTag == HID_ITEM_TAG_LONG_ITEM)
00246   {
00247     if (host_hid_report_descriptor_parser.length <
00248         (U8 *)&hid_item->long_format.bDataSize - (U8 *)hid_item +
00249         sizeof(hid_item->long_format.bDataSize))
00250       return FALSE;
00251 
00252     size = hid_item->long_format.bDataSize;
00253 
00254     if (host_hid_report_descriptor_parser.length <
00255         (U8 *)&hid_item->long_format.data - (U8 *)hid_item +
00256         size)
00257       return FALSE;
00258 
00259     item->tag = hid_item->long_format.bLongItemTag;
00260 
00261     item->long_format = TRUE;
00262 
00263     item->long_data.size = size;
00264     item->long_data.data = &hid_item->long_format.data;
00265 
00266     host_hid_report_descriptor_parser.length -=
00267       (U8 *)&hid_item->long_format.data - (U8 *)hid_item +
00268       size;
00269 
00270     host_hid_report_descriptor_parser.item =
00271       (hid_item_t *)&hid_item->long_format.data[size];
00272   }
00273   else
00274   {
00275     U8 i;
00276 
00277     size = (hid_item->short_format.bSize) ?
00278              1 << (hid_item->short_format.bSize - 1) :
00279              0;
00280 
00281     if (host_hid_report_descriptor_parser.length <
00282         (U8 *)&hid_item->short_format.data - (U8 *)hid_item +
00283         size)
00284       return FALSE;
00285 
00286     item->tag = hid_item->short_format.bTag;
00287 
00288     item->long_format = FALSE;
00289 
00290     item->short_data.value = 0x00000000;
00291     for (i = 0; i < size; i++)
00292     {
00293       item->short_data.value = item->short_data.value << 8 |
00294                                hid_item->short_format.data[i];
00295     }
00296     item->short_data.value =
00297       usb_format_usb_to_mcu_data(32, item->short_data.value <<
00298                                      ((sizeof(U32) - size) << 3));
00299 
00300     host_hid_report_descriptor_parser.length -=
00301       (U8 *)&hid_item->short_format.data - (U8 *)hid_item +
00302       size;
00303 
00304     host_hid_report_descriptor_parser.item =
00305       (hid_item_t *)&hid_item->short_format.data[size];
00306   }
00307 
00308   return TRUE;
00309 }

U8 host_hid_get_protocol ( U8  s_interface  ) 

Reads which protocol is currently active (either the boot protocol or the report protocol).

Parameters:
s_interface The supported interface number of which to get the protocol.
Returns:
Protocol: HID_BOOT_PROTOCOL or HID_REPORT_PROTOCOL.
Note:
This request is supported by devices in the Boot subclass.

Definition at line 197 of file host_hid.c.

References HID_GET_PROTOCOL.

00198 {
00199   usb_request.bmRequestType   = 0xA1;
00200   usb_request.bRequest        = HID_GET_PROTOCOL;
00201   usb_request.wValue          = 0x0000;
00202   usb_request.wIndex          = Get_interface_number(s_interface);
00203   usb_request.wLength         = 0x0001;
00204   usb_request.incomplete_read = FALSE;
00205 
00206   host_transfer_control(data_stage);
00207 
00208   return data_stage[0x00];
00209 }

Status_t host_hid_get_report ( U8  report_type,
U8  report_id,
U8  s_interface 
)

Gets a HID report.

Parameters:
report_type Type of the report to get.
report_id ID of the report to get.
s_interface The supported interface number of which to get the report.
Returns:
Status.

Definition at line 143 of file host_hid.c.

References HID_GET_REPORT, and SIZEOF_DATA_STAGE.

Referenced by host_mouse_hid_task().

00144 {
00145   usb_request.bmRequestType   = 0xA1;
00146   usb_request.bRequest        = HID_GET_REPORT;
00147   usb_request.wValue          = report_type << 8 | report_id;
00148   usb_request.wIndex          = Get_interface_number(s_interface);
00149   usb_request.wLength         = SIZEOF_DATA_STAGE;
00150   usb_request.incomplete_read = FALSE;
00151 
00152   return host_transfer_control(data_stage);
00153 }

Status_t host_hid_set_descriptor ( U8  descriptor_type,
U8  descriptor_index,
U8  s_interface,
U16  length 
)

Sets a HID class descriptor.

Parameters:
descriptor_type Type of the descriptor to set.
descriptor_index Index of the descriptor to set.
s_interface The supported interface number of which to set the descriptor.
length Length of the descriptor to set.
Returns:
Status.

Definition at line 122 of file host_hid.c.

00123 {
00124   usb_request.bmRequestType   = 0x01;
00125   usb_request.bRequest        = SET_DESCRIPTOR;
00126   usb_request.wValue          = descriptor_type << 8 | descriptor_index;
00127   usb_request.wIndex          = Get_interface_number(s_interface);
00128   usb_request.wLength         = length;
00129   usb_request.incomplete_read = FALSE;
00130 
00131   return host_transfer_control(data_stage);
00132 }

Status_t host_hid_set_idle ( U8  duration_4_ms,
U8  report_id,
U8  s_interface 
)

Silences a particular report on the Interrupt In pipe until a new event occurs or the specified amount of time passes.

Parameters:
duration_4_ms Idle duration with a 4-ms resolution, or HID_IDLE_DURATION_INDEFINITE.
report_id ID of the report of which to set the idle rate (can be HID_REPORT_ID_ALL).
s_interface The supported interface number of which to set the idle rate.
Returns:
Status.

Definition at line 184 of file host_hid.c.

References HID_SET_IDLE.

Referenced by host_mouse_hid_task().

00185 {
00186   usb_request.bmRequestType   = 0x21;
00187   usb_request.bRequest        = HID_SET_IDLE;
00188   usb_request.wValue          = duration_4_ms << 8 | report_id;
00189   usb_request.wIndex          = Get_interface_number(s_interface);
00190   usb_request.wLength         = 0x0000;
00191   usb_request.incomplete_read = FALSE;
00192 
00193   return host_transfer_control(data_stage);
00194 }

Status_t host_hid_set_protocol ( U8  protocol,
U8  s_interface 
)

Switches between the boot protocol and the report protocol (or vice versa).

Parameters:
protocol Protocol: HID_BOOT_PROTOCOL or HID_REPORT_PROTOCOL.
s_interface The supported interface number of which to set the protocol.
Returns:
Status.
Note:
This request is supported by devices in the Boot subclass.

When initialized, all devices default to the report protocol. However, the host should not make any assumptions about the device's state and should set the desired protocol whenever initializing a device.

Definition at line 212 of file host_hid.c.

References HID_SET_PROTOCOL.

00213 {
00214   usb_request.bmRequestType   = 0x21;
00215   usb_request.bRequest        = HID_SET_PROTOCOL;
00216   usb_request.wValue          = protocol;
00217   usb_request.wIndex          = Get_interface_number(s_interface);
00218   usb_request.wLength         = 0x0000;
00219   usb_request.incomplete_read = FALSE;
00220 
00221   return host_transfer_control(data_stage);
00222 }

Status_t host_hid_set_report ( U8  report_type,
U8  report_id,
U8  s_interface,
U16  length 
)

Sets a HID report.

Parameters:
report_type Type of the report to set.
report_id ID of the report to set.
s_interface The supported interface number of which to set the report.
length Length of the report to set.
Returns:
Status.

Definition at line 156 of file host_hid.c.

References HID_SET_REPORT.

00157 {
00158   usb_request.bmRequestType   = 0x21;
00159   usb_request.bRequest        = HID_SET_REPORT;
00160   usb_request.wValue          = report_type << 8 | report_id;
00161   usb_request.wIndex          = Get_interface_number(s_interface);
00162   usb_request.wLength         = length;
00163   usb_request.incomplete_read = FALSE;
00164 
00165   return host_transfer_control(data_stage);
00166 }


Generated on Fri Feb 19 02:33:15 2010 for AVR32 - USB HID Stand-alone Example by  doxygen 1.5.5