Hid_gamepad_device_class_api

Collaboration diagram for Hid_gamepad_device_class_api:

Data Structures
struct	tUSBDGamepadInstance
struct	tUSBDHIDGamepadDevice
struct	PACKED
	USB_CDC_GET/SET_LINE_CODING request-specific data. More...

Macros
#define	NUM_HID_SECTIONS
#define	USBDGAMEPAD_SUCCESS   0
	The USBDHIDGamepadSendReport() call successfully scheduled the report. More...
#define	USBDGAMEPAD_TX_ERROR   1
#define	USBDGAMEPAD_NOT_CONFIGURED   2
	The device is not currently configured and cannot perform any operations. More...

Enumerations
enum	tGamepadState { eHIDGamepadStateNotConnected, eHIDGamepadStateIdle, eHIDGamepadStateSending }

Functions
tUSBDHIDGamepadDevice *	USBDHIDGamepadInit (uint32_t ui32Index, tUSBDHIDGamepadDevice *psGamepad)
tUSBDHIDGamepadDevice *	USBDHIDGamepadCompositeInit (uint32_t ui32Index, tUSBDHIDGamepadDevice *psGamepad, tCompositeEntry *psCompEntry)
uint32_t	USBDHIDGamepadSendReport (tUSBDHIDGamepadDevice *psHIDGamepad, void *pvReport, uint32_t ui32Size)
void	USBDHIDGamepadTerm (tUSBDHIDGamepadDevice *psGamepad)

Detailed Description

Macro Definition Documentation

NUM_HID_SECTIONS

#define NUM_HID_SECTIONS

Value:

((sizeof(g_psHIDSections) /                   \
                                  sizeof(tConfigSection *)))

USBDGAMEPAD_SUCCESS

#define USBDGAMEPAD_SUCCESS   0

The USBDHIDGamepadSendReport() call successfully scheduled the report.

Referenced by USBDHIDGamepadSendReport().

USBDGAMEPAD_TX_ERROR

#define USBDGAMEPAD_TX_ERROR   1

The USBDHIDGamepadSendReport() function could not send the report at this time.

Referenced by USBDHIDGamepadSendReport().

USBDGAMEPAD_NOT_CONFIGURED

#define USBDGAMEPAD_NOT_CONFIGURED   2

The device is not currently configured and cannot perform any operations.

Referenced by USBDHIDGamepadSendReport().

Enumeration Type Documentation

tGamepadState

enum tGamepadState

Enumerator
eHIDGamepadStateNotConnected
eHIDGamepadStateIdle
eHIDGamepadStateSending

Function Documentation

USBDHIDGamepadInit()

tUSBDHIDGamepadDevice * USBDHIDGamepadInit	(	uint32_t	ui32Index,
		tUSBDHIDGamepadDevice *	psGamepad
	)

Initializes HID gamepad device operation for a given USB controller.

Parameters

ui32Index	is the index of the USB controller that is to be initialized for HID gamepad device operation.
psGamepad	points to a structure containing parameters customizing the operation of the HID gamepad device.

An application that enables a USB HID gamepad interface to a USB host must call this function to initialize the USB controller and attach the gamepad device to the USB bus. This function performs all required USB initialization, and the device is ready for operation on the function return.

On successful completion, this function returns the modified psGamepad pointer passed to it or returns a NULL pointer if there was a problem. This pointer must be passed on all future calls to the HID gamepad device driver.

When a host connects and configures the device, the application callback receives USB_EVENT_CONNECTED, after which calls can be made to USBDHIDGamepadSendReport() to report changes to the gamepad interface to the USB host when it requests them.

Note

The application must not make any calls to the lower level USB device interfaces if interacting with USB via the USB HID gamepad device class API.

Returns

Returns NULL on failure or the psGamepad pointer on success.

References tUSBDHIDGamepadDevice::pfnCallback, tUSBDHIDGamepadDevice::ppui8StringDescriptors, tUSBDGamepadInstance::sHIDDevice, tUSBDHIDGamepadDevice::sPrivateData, and USBDHIDGamepadCompositeInit().

USBDHIDGamepadCompositeInit()

tUSBDHIDGamepadDevice * USBDHIDGamepadCompositeInit	(	uint32_t	ui32Index,
		tUSBDHIDGamepadDevice *	psGamepad,
		tCompositeEntry *	psCompEntry
	)

Initializes HID gamepad device operation for a given USB controller.

Parameters

ui32Index	is the index of the USB controller that is to be initialized for HID gamepad device operation.
psGamepad	points to a structure containing parameters customizing the operation of the HID gamepad device.
psCompEntry	is the composite device entry to initialize when creating a composite device.

This call is very similar to USBDHIDGamepadInit() except that it is used for initializing an instance of the HID gamepad device for use in a composite device. If this HID gamepad is part of a composite device, then the psCompEntry should point to the composite device entry to initialize. This entry is part of the array that is passed to the USBDCompositeInit() function to start up and complete configuration of a composite USB device.

Returns

Returns NULL on failure or the psGamepad value that should be used with the remaining USB HID gamepad APIs.

References eHIDGamepadStateNotConnected, tUSBDGamepadInstance::iState, tUSBDHIDGamepadDevice::pfnCallback, tUSBDHIDDevice::pfnTxCallback, tUSBDHIDGamepadDevice::ppui8StringDescriptors, tUSBDHIDDevice::psReportIdle, tUSBDGamepadInstance::sHIDDevice, tUSBDHIDGamepadDevice::sPrivateData, tUSBDGamepadInstance::sReportIdle, tUSBDHIDGamepadDevice::ui16MaxPowermA, tUSBDHIDDevice::ui16MaxPowermA, tUSBDHIDGamepadDevice::ui16PID, tUSBDHIDDevice::ui16PID, tHIDReportIdle::ui16TimeTillNextmS, tUSBDHIDGamepadDevice::ui16VID, tUSBDHIDDevice::ui16VID, tHIDReportIdle::ui32TimeSinceReportmS, tHIDReportIdle::ui8Duration4mS, tUSBDHIDDevice::ui8NumInputReports, tUSBDHIDDevice::ui8Protocol, tUSBDHIDGamepadDevice::ui8PwrAttributes, tUSBDHIDDevice::ui8PwrAttributes, tHIDReportIdle::ui8ReportID, and tUSBDHIDDevice::ui8Subclass.

Referenced by USBDHIDGamepadInit().

USBDHIDGamepadSendReport()

uint32_t USBDHIDGamepadSendReport	(	tUSBDHIDGamepadDevice *	psHIDGamepad,
		void *	pvReport,
		uint32_t	ui32Size
	)

Schedules a report to be sent once the host requests more data.

Parameters

psHIDGamepad	is the structure pointer that is returned from the USBDHIDGamepadCompositeInit() or USBDHIDGamepadInit() functions.
pvReport	is the data to send to the host.
ui32Size	is the number of bytes in the pvReport buffer.

This call is made by an application to schedule data to be sent to the host when the host requests an update from the device. The application must then wait for a USB_EVENT_TX_COMPLETE event in the function provided in the pfnCallback pointer in the tUSBDHIDGamepadDevice structure before being able to send more data with this function. The pointer passed in the pvReport can be updated once this call returns as the data has been copied from the buffer. The function returns USBDGAMEPAD_SUCCESS if the transmission was successfully scheduled or USBDGAMEPAD_TX_ERROR if the report could not be sent at this time. If the call is made before the device is connected or ready to communicate with the host, then the function can return USBDGAMEPAD_NOT_CONFIGURED.

Returns

The function returns one of the USBDGAMEPAD_* values.

References eHIDGamepadStateNotConnected, eHIDGamepadStateSending, tUSBDGamepadInstance::iState, tUSBDGamepadInstance::sHIDDevice, tUSBDHIDGamepadDevice::sPrivateData, USBDGAMEPAD_NOT_CONFIGURED, USBDGAMEPAD_SUCCESS, USBDGAMEPAD_TX_ERROR, USBDHIDReportWrite(), and USBDHIDTxPacketAvailable().

USBDHIDGamepadTerm()

void USBDHIDGamepadTerm

(

tUSBDHIDGamepadDevice *

psGamepad

)

Shuts down the HID gamepad device.

Parameters

psGamepad

is the pointer to the device instance structure as returned by USBDHIDGamepadInit() or USBDHIDGamepadCompositeInit().

This function terminates HID gamepad operation for the instance supplied and removes the device from the USB bus. Following this call, the psGamepad instance may not me used in any other call to the HID gamepad device other than to reinitialize by calling USBDHIDGamepadInit() or USBDHIDGamepadCompositeInit().

Returns

None.

References eHIDGamepadStateNotConnected, tUSBDGamepadInstance::iState, tUSBDGamepadInstance::sHIDDevice, tUSBDHIDGamepadDevice::sPrivateData, and USBDHIDTerm().