| LPCOpen Platform v1.03 LPCOpen Platform for NXP LPC Microcontrollers

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

- Data Structures
- Data Structure Index
- Data Fields

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Fields
USBD_HID_INIT_PARAM_T Struct Reference
HID Class Function Driver

## Detailed Description

USB descriptors data structure.

This module exposes functions which interact directly with USB device stack's core layer. The application layer uses this component when it has to implement custom class function driver or standard class function driver which is not part of the current USB device stack. The functions exposed by this interface are to register class specific EP0 handlers and corresponding utility functions to manipulate EP0 state machine of the stack. This interface also exposes function to register custom endpoint interrupt handler.

Definition at line 188 of file usbd_api.h.

`#include "usbd_api.h"`

## Data Fields
uint32_t | mem_base
uint32_t | mem_size
uint8_t | max_reports
uint8_t * | intf_desc
USB_HID_REPORT_T * | report_data
ErrorCode_t(* | HID_GetReport )(USBD_HID_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuffer, uint16_t *length)
ErrorCode_t(* | HID_SetReport )(USBD_HID_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuffer, uint16_t length)
ErrorCode_t(* | HID_GetPhysDesc )(USBD_HID_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuf, uint16_t *length)
ErrorCode_t(* | HID_SetIdle )(USBD_HID_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t idleTime)
ErrorCode_t(* | HID_SetProtocol )(USBD_HID_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t protocol)
ErrorCode_t(* | HID_EpIn_Hdlr )(USBD_HANDLE_T hUsb, void *data, uint32_t event)
ErrorCode_t(* | HID_EpOut_Hdlr )(USBD_HANDLE_T hUsb, void *data, uint32_t event)
ErrorCode_t(* | HID_GetReportDesc )(USBD_HID_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuf, uint16_t *length)
ErrorCode_t(* | HID_Ep0_Hdlr )(USBD_HANDLE_T hUsb, void *data, uint32_t event)
uint8_t | pad [3]

## Field Documentation

ErrorCode_t(* HID_Ep0_Hdlr)(USBD_HANDLE_T hUsb, void *data, uint32_t event)

Optional user overridable function to replace the default HID class handler.

The application software could override the default EP0 class handler with their own by providing the handler function address as this data member of the parameter structure. Application which like the default handler should set this data member to zero before calling the USBD_HID_API::Init().

Note

Parameters

  [in] | hUsb | Handle to the USB device stack.
  [in] | data | Pointer to the data which will be passed when callback function is called by the stack.
  [in] | event | Type of endpoint event. See USBD_EVENT_T for more details.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Optional user overridable function to replace the default HID class handler.

The application software could override the default EP0 class handler with their own by providing the handler function address as this data member of the parameter structure. Application which like the default handler should set this data member to zero before calling the USBD_HID_API::Init().

Note

Parameters

  hUsb | Handle to the USB device stack.
  data | Pointer to the data which will be passed when callback function is called by the stack.
  event | Type of endpoint event. See USBD_EVENT_T for more details.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Definition at line 215 of file usbd_api.h.

ErrorCode_t(* HID_EpIn_Hdlr)(USBD_HANDLE_T hUsb, void *data, uint32_t event)

Optional Interrupt IN endpoint event handler.

The application software could provide Interrupt IN endpoint event handler. Application which send reports to host on interrupt endpoint should provide an endpoint event handler through this data member. This data memeber is ignored if the interface descriptor intf_desc doesn't have any IN interrupt endpoint descriptor associated.

Parameters

  [in] | hUsb | Handle to the USB device stack.
  [in] | data | Handle to HID function driver.
  [in] | event | Type of endpoint event. See USBD_EVENT_T for more details.

Returns
  The call back should return ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Optional Interrupt IN endpoint event handler.

The application software could provide Interrupt IN endpoint event handler. Application which send reports to host on interrupt endpoint should provide an endpoint event handler through this data member. This data memeber is ignored if the interface descriptor intf_desc doesn't have any IN interrupt endpoint descriptor associated.

Parameters

  hUsb | Handle to the USB device stack.
  data | Handle to HID function driver.
  event | Type of endpoint event. See USBD_EVENT_T for more details.

Returns
  The call back should return ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Definition at line 210 of file usbd_api.h.

ErrorCode_t(* HID_EpOut_Hdlr)(USBD_HANDLE_T hUsb, void *data, uint32_t event)

Optional Interrupt OUT endpoint event handler.

The application software could provide Interrupt OUT endpoint event handler. Application which recieves reports from host on interrupt endpoint should provide an endpoint event handler through this data member. This data memeber is ignored if the interface descriptor intf_desc doesn't have any OUT interrupt endpoint descriptor associated.

Parameters

  [in] | hUsb | Handle to the USB device stack.
  [in] | data | Handle to HID function driver.
  [in] | event | Type of endpoint event. See USBD_EVENT_T for more details.

Returns
  The call back should return ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Optional Interrupt OUT endpoint event handler.

The application software could provide Interrupt OUT endpoint event handler. Application which recieves reports from host on interrupt endpoint should provide an endpoint event handler through this data member. This data memeber is ignored if the interface descriptor intf_desc doesn't have any OUT interrupt endpoint descriptor associated.

Parameters

  hUsb | Handle to the USB device stack.
  data | Handle to HID function driver.
  event | Type of endpoint event. See USBD_EVENT_T for more details.

Returns
  The call back should return ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Definition at line 211 of file usbd_api.h.

ErrorCode_t(* HID_GetPhysDesc)(USBD_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuf, uint16_t *length)

Optional callback function to handle HID_GetPhysDesc request.

The application software could provide this callback HID_GetPhysDesc handler to handle get physical descriptor requests sent by the host. When host requests Physical Descriptor set 0, application should return a special descriptor identifying the number of descriptor sets and their sizes. A Get_Descriptor request with the Physical Index equal to 1 should return the first Physical Descriptor set. A device could possibly have alternate uses for its items. These can be enumerated by issuing subsequent Get_Descriptor requests while incrementing the Descriptor Index. A device should return the last descriptor set to requests with an index greater than the last number defined in the HID descriptor.

Note
  Applications which don't have physical descriptor should set this data member to zero before calling the USBD_HID_API::Init().

Parameters

  [in] | hHid | Handle to HID function driver.
  [in] | pSetup | Pointer to setup packet recived from host.
  [in] | pBuf | Pointer to a pointer of data buffer containing physical descriptor data. If the physical descriptor is in USB accessable memory area application could just update the pointer or else it should copy the descriptor to the address pointed by this pointer.
  [in] | length | Amount of data copied to destination buffer or descriptor length.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Optional callback function to handle HID_GetPhysDesc request.

The application software could provide this callback HID_GetPhysDesc handler to handle get physical descriptor requests sent by the host. When host requests Physical Descriptor set 0, application should return a special descriptor identifying the number of descriptor sets and their sizes. A Get_Descriptor request with the Physical Index equal to 1 should return the first Physical Descriptor set. A device could possibly have alternate uses for its items. These can be enumerated by issuing subsequent Get_Descriptor requests while incrementing the Descriptor Index. A device should return the last descriptor set to requests with an index greater than the last number defined in the HID descriptor.

Note
  Applications which don't have physical descriptor should set this data member to zero before calling the USBD_HID_API::Init().

Parameters

  hHid | Handle to HID function driver.
  pSetup | Pointer to setup packet recived from host.
  pBuf | Pointer to a pointer of data buffer containing physical descriptor data. If the physical descriptor is in USB accessable memory area application could just update the pointer or else it should copy the descriptor to the address pointed by this pointer.
  length | Amount of data copied to destination buffer or descriptor length.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Definition at line 207 of file usbd_api.h.

ErrorCode_t(* HID_GetReport)(USBD_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuffer, uint16_t *length)

HID get report callback function.

This function is provided by the application software. This function gets called when host sends a HID_REQUEST_GET_REPORT request. The setup packet data (pSetup) is passed to the callback so that application can extract the report ID, report type and other information need to generate the report.

Note
  HID reports are sent via interrupt IN endpoint also. This function is called only when report request is received on control endpoint. Application should implement HID_EpIn_Hdlr to send reports to host via interrupt IN endpoint.

Parameters

  [in] | hHid | Handle to HID function driver.
  [in] | pSetup | Pointer to setup packet recived from host.
  [in,out] | pBuffer | Pointer to a pointer of data buffer containing report data. Pointer-to-pointer is used to implement zero-copy buffers.
  [in] | length | Amount of data copied to destination buffer.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

HID get report callback function.

This function is provided by the application software. This function gets called when host sends a HID_REQUEST_GET_REPORT request. The setup packet data (pSetup) is passed to the callback so that application can extract the report ID, report type and other information need to generate the report.

Note
  HID reports are sent via interrupt IN endpoint also. This function is called only when report request is received on control endpoint. Application should implement HID_EpIn_Hdlr to send reports to host via interrupt IN endpoint.

Parameters

  hHid | Handle to HID function driver.
  pSetup | Pointer to setup packet recived from host.
  pBuffer | Pointer to a pointer of data buffer containing report data. Pointer-to-pointer is used to implement zero-copy buffers.
  length | Amount of data copied to destination buffer.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Definition at line 204 of file usbd_api.h.

ErrorCode_t(* HID_GetReportDesc)(USBD_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuf, uint16_t *length)

Optional user overridable function to replace the default HID_GetReportDesc handler.

The application software could override the default HID_GetReportDesc handler with their own by providing the handler function address as this data member of the parameter structure. Application which like the default handler should set this data member to zero before calling the USBD_HID_API::Init() and also provide report data array report_data field.

Note

Parameters

  [in] | hUsb | Handle to the USB device stack.
  [in] | data | Pointer to the data which will be passed when callback function is called by the stack.
  [in] | event | Type of endpoint event. See USBD_EVENT_T for more details.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Optional user overridable function to replace the default HID_GetReportDesc handler.

The application software could override the default HID_GetReportDesc handler with their own by providing the handler function address as this data member of the parameter structure. Application which like the default handler should set this data member to zero before calling the USBD_HID_API::Init() and also provide report data array report_data field.

Note

Parameters

  hUsb | Handle to the USB device stack.
  data | Pointer to the data which will be passed when callback function is called by the stack.
  event | Type of endpoint event. See USBD_EVENT_T for more details.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Definition at line 214 of file usbd_api.h.

ErrorCode_t(* HID_SetIdle)(USBD_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t idleTime)

Optional callback function to handle HID_REQUEST_SET_IDLE request.

The application software could provide this callback to handle HID_REQUEST_SET_IDLE requests sent by the host. This callback is provided to applications to adjust timers associated with various reports, which are sent to host over interrupt endpoint. The setup packet data (pSetup) is passed to the callback so that application can extract the report ID, report type and other information need to modify the report's idle time.

Note
  Applications which don't send reports on Interrupt endpoint or don't have idle time between reports should set this data member to zero before calling the USBD_HID_API::Init().

Parameters

  [in] | hHid | Handle to HID function driver.
  [in] | pSetup | Pointer to setup packet recived from host.
  [in] | idleTime | Idle time to be set for the specified report.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Optional callback function to handle HID_REQUEST_SET_IDLE request.

The application software could provide this callback to handle HID_REQUEST_SET_IDLE requests sent by the host. This callback is provided to applications to adjust timers associated with various reports, which are sent to host over interrupt endpoint. The setup packet data (pSetup) is passed to the callback so that application can extract the report ID, report type and other information need to modify the report's idle time.

Note
  Applications which don't send reports on Interrupt endpoint or don't have idle time between reports should set this data member to zero before calling the USBD_HID_API::Init().

Parameters

  hHid | Handle to HID function driver.
  pSetup | Pointer to setup packet recived from host.
  idleTime | Idle time to be set for the specified report.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Definition at line 208 of file usbd_api.h.

ErrorCode_t(* HID_SetProtocol)(USBD_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t protocol)

Optional callback function to handle HID_REQUEST_SET_PROTOCOL request.

The application software could provide this callback to handle HID_REQUEST_SET_PROTOCOL requests sent by the host. This callback is provided to applications to adjust modes of their code between boot mode and report mode.

Note
  Applications which don't support protocol modes should set this data member to zero before calling the USBD_HID_API::Init().

Parameters

  [in] | hHid | Handle to HID function driver.
  [in] | pSetup | Pointer to setup packet recived from host.
  [in] | protocol | Protocol mode. 0 = Boot Protocol 1 = Report Protocol

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Optional callback function to handle HID_REQUEST_SET_PROTOCOL request.

The application software could provide this callback to handle HID_REQUEST_SET_PROTOCOL requests sent by the host. This callback is provided to applications to adjust modes of their code between boot mode and report mode.

Note
  Applications which don't support protocol modes should set this data member to zero before calling the USBD_HID_API::Init().

Parameters

  hHid | Handle to HID function driver.
  pSetup | Pointer to setup packet recived from host.
  protocol | Protocol mode. 0 = Boot Protocol 1 = Report Protocol

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Definition at line 209 of file usbd_api.h.

ErrorCode_t(* HID_SetReport)(USBD_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuffer, uint16_t length)

HID set report callback function.

This function is provided by the application software. This function gets called when host sends a HID_REQUEST_SET_REPORT request. The setup packet data (pSetup) is passed to the callback so that application can extract the report ID, report type and other information need to modify the report. An application might choose to ignore input Set_Report requests as meaningless. Alternatively these reports could be used to reset the origin of a control (that is, current position should report zero).

Parameters

  [in] | hHid | Handle to HID function driver.
  [in] | pSetup | Pointer to setup packet recived from host.
  [in,out] | pBuffer | Pointer to a pointer of data buffer containing report data. Pointer-to-pointer is used to implement zero-copy buffers.
  [in] | length | Amount of data copied to destination buffer.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

HID set report callback function.

This function is provided by the application software. This function gets called when host sends a HID_REQUEST_SET_REPORT request. The setup packet data (pSetup) is passed to the callback so that application can extract the report ID, report type and other information need to modify the report. An application might choose to ignore input Set_Report requests as meaningless. Alternatively these reports could be used to reset the origin of a control (that is, current position should report zero).

Parameters

  hHid | Handle to HID function driver.
  pSetup | Pointer to setup packet recived from host.
  pBuffer | Pointer to a pointer of data buffer containing report data. Pointer-to-pointer is used to implement zero-copy buffers.
  length | Amount of data copied to destination buffer.

Returns
  The call back should returns ErrorCode_t type to indicate success or error condition.

Return values

  LPC_OK | On success.
  ERR_USBD_UNHANDLED | Event is not handled hence pass the event to next in line.
  ERR_USBD_xxx | For other error conditions.

Definition at line 205 of file usbd_api.h.

uint8_t * intf_desc

Pointer to the HID interface descriptor within the descriptor array (high_speed_desc) passed to Init() through USB_CORE_DESCS_T structure.

Pointer to the HID interface descriptor within the descriptor array (high_speed_desc) passed to Init() through USB_CORE_DESCS_T structure.

Definition at line 199 of file usbd_api.h.

uint8_t max_reports

Number of HID reports supported by this instance of HID class driver.

Definition at line 194 of file usbd_api.h.

uint32_t mem_base

Base memory location from where the stack can allocate data and buffers.

Note
  The memory address set in this field should be accessible by USB DMA controller. Also this value should be aligned on 4 byte boundary.

Base memory location from where the stack can allocate data and buffers.

Note
  The memory address set in this field should be accessible by USB DMA controller. Also this value should be aligned on 4 byte boundary.

Definition at line 191 of file usbd_api.h.

uint32_t mem_size

The size of memory buffer which stack can use.

Note
  The mem_size should be greater than the size returned by USBD_HID_API::GetMemSize() routine.

The size of memory buffer which stack can use.

Note
  The mem_size should be greater than the size returned by USBD_HID_API::GetMemSize() routine.

Definition at line 192 of file usbd_api.h.

uint8_t pad[3]

Definition at line 105 of file usbd_hiduser.h.

USB_HID_REPORT_T * report_data

Pointer to an array of HID report descriptor data structure (USB_HID_REPORT_T). The number of elements in the array should be same a max_reports value. The stack uses this array to respond to requests recieved for various HID report descriptor information.

Note
  This array should be of global scope.

Pointer to an array of HID report descriptor data structure (USB_HID_REPORT_T). The number of elements in the array should be same a max_reports value. The stack uses this array to respond to requests recieved for various HID report descriptor information.

Note
  This array should be of global scope.

Definition at line 200 of file usbd_api.h.

The documentation for this struct was generated from the following files:

- C:/nxp/v1.03/lpcopen_v1.03/lpcopen/software/lpc_core/lpc_ip/usbd_rom/usbd_api.h
- C:/nxp/v1.03/lpcopen_v1.03/lpcopen/software/lpc_core/lpc_ip/usbd_rom/usbd_hiduser.h
- C:/nxp/v1.03/lpcopen_v1.03/lpcopen/software/LPCUSBLib/Drivers/USB/Core/DCD/USBRom/usbd_hiduser.h