USBD ROM Stack  2.0
ROM based USB device stack
Data Fields
USBD_HID_INIT_PARAM_T Struct Reference

USB descriptors data structure. More...

#include <C:/Data/nxp/GIT/lpcopen_v3/lpcopen_version3/LPC43xx_18xx/lpc43xx_18xx/LPC_USBD_Lib/mw_usbd/mw_usbd_hiduser.h>

Data Fields

uint32_t mem_base
 
uint32_t mem_size
 
uint8_t max_reports
 
uint8_t pad [3]
 
uint8_t * intf_desc
 
USB_HID_REPORT_Treport_data
 
ErrorCode_t(* HID_GetReport )(USBD_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuffer, uint16_t *length)
 
ErrorCode_t(* HID_SetReport )(USBD_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuffer, uint16_t length)
 
ErrorCode_t(* HID_GetPhysDesc )(USBD_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t **pBuf, uint16_t *length)
 
ErrorCode_t(* HID_SetIdle )(USBD_HANDLE_T hHid, USB_SETUP_PACKET *pSetup, uint8_t idleTime)
 
ErrorCode_t(* HID_SetProtocol )(USBD_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_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)
 

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.

Field Documentation

◆ mem_base

uint32_t USBD_HID_INIT_PARAM_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.

◆ mem_size

uint32_t USBD_HID_INIT_PARAM_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.

◆ max_reports

uint8_t USBD_HID_INIT_PARAM_T::max_reports

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

◆ intf_desc

uint8_t* USBD_HID_INIT_PARAM_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.

◆ report_data

USB_HID_REPORT_T* USBD_HID_INIT_PARAM_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 received for various HID report descriptor information.

Note
This array should be of global scope.

◆ HID_GetReport

ErrorCode_t(* USBD_HID_INIT_PARAM_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]hHidHandle to HID function driver.
[in]pSetupPointer to setup packet received from host.
[in,out]pBufferPointer to a pointer of data buffer containing report data. Pointer-to-pointer is used to implement zero-copy buffers. See Zero-Copy Data Transfer model for more details on zero-copy concept.
[in]lengthAmount of data copied to destination buffer.
Returns
The call back should returns ErrorCode_t type to indicate success or error condition.
Return values
LPC_OKOn success.
ERR_USBD_UNHANDLEDEvent is not handled hence pass the event to next in line.
ERR_USBD_xxxFor other error conditions.

◆ HID_SetReport

ErrorCode_t(* USBD_HID_INIT_PARAM_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]hHidHandle to HID function driver.
[in]pSetupPointer to setup packet received from host.
[in,out]pBufferPointer to a pointer of data buffer containing report data. Pointer-to-pointer is used to implement zero-copy buffers. See Zero-Copy Data Transfer model for more details on zero-copy concept.
[in]lengthAmount of data copied to destination buffer.
Returns
The call back should returns ErrorCode_t type to indicate success or error condition.
Return values
LPC_OKOn success.
ERR_USBD_UNHANDLEDEvent is not handled hence pass the event to next in line.
ERR_USBD_xxxFor other error conditions.

◆ HID_GetPhysDesc

ErrorCode_t(* USBD_HID_INIT_PARAM_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]hHidHandle to HID function driver.
[in]pSetupPointer to setup packet received from host.
[in]pBufPointer to a pointer of data buffer containing physical descriptor data. If the physical descriptor is in USB accessible memory area application could just update the pointer or else it should copy the descriptor to the address pointed by this pointer.
[in]lengthAmount 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_OKOn success.
ERR_USBD_UNHANDLEDEvent is not handled hence pass the event to next in line.
ERR_USBD_xxxFor other error conditions.

◆ HID_SetIdle

ErrorCode_t(* USBD_HID_INIT_PARAM_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]hHidHandle to HID function driver.
[in]pSetupPointer to setup packet received from host.
[in]idleTimeIdle 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_OKOn success.
ERR_USBD_UNHANDLEDEvent is not handled hence pass the event to next in line.
ERR_USBD_xxxFor other error conditions.

◆ HID_SetProtocol

ErrorCode_t(* USBD_HID_INIT_PARAM_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]hHidHandle to HID function driver.
[in]pSetupPointer to setup packet received from host.
[in]protocolProtocol 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_OKOn success.
ERR_USBD_UNHANDLEDEvent is not handled hence pass the event to next in line.
ERR_USBD_xxxFor other error conditions.

◆ HID_EpIn_Hdlr

ErrorCode_t(* USBD_HID_INIT_PARAM_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 member is ignored if the interface descriptor intf_desc doesn't have any IN interrupt endpoint descriptor associated.

Parameters
[in]hUsbHandle to the USB device stack.
[in]dataHandle to HID function driver.
[in]eventType 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_OKOn success.
ERR_USBD_UNHANDLEDEvent is not handled hence pass the event to next in line.
ERR_USBD_xxxFor other error conditions.

◆ HID_EpOut_Hdlr

ErrorCode_t(* USBD_HID_INIT_PARAM_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 receives reports from host on interrupt endpoint should provide an endpoint event handler through this data member. This data member is ignored if the interface descriptor intf_desc doesn't have any OUT interrupt endpoint descriptor associated.

Parameters
[in]hUsbHandle to the USB device stack.
[in]dataHandle to HID function driver.
[in]eventType 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_OKOn success.
ERR_USBD_UNHANDLEDEvent is not handled hence pass the event to next in line.
ERR_USBD_xxxFor other error conditions.

◆ HID_GetReportDesc

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

Optional user override-able 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]hUsbHandle to the USB device stack.
[in]pSetupPointer to setup packet received from host.
[in]pBufPointer to a pointer of data buffer containing report descriptor.
[in]lengthAmount of data copied to destination buffer.
Returns
The call back should returns ErrorCode_t type to indicate success or error condition.
Return values
LPC_OKOn success.
ERR_USBD_UNHANDLEDEvent is not handled hence pass the event to next in line.
ERR_USBD_xxxFor other error conditions.

◆ HID_Ep0_Hdlr

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

Optional user override-able 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]hUsbHandle to the USB device stack.
[in]dataPointer to the data which will be passed when callback function is called by the stack.
[in]eventType 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_OKOn success.
ERR_USBD_UNHANDLEDEvent is not handled hence pass the event to next in line.
ERR_USBD_xxxFor other error conditions.

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