Usblib_host_device

Macros
#define	USBHKEYB_REPORT_SIZE   8
#define	USBHKEYB_DEVICE_PRESENT   0x00000001
#define	USBHMS_REPORT_SIZE   4
#define	USBHMS_DEVICE_PRESENT   0x00000001

Typedefs
typedef struct tUSBHKeyboard	tUSBHKeyboard
typedef void(*	tUSBHIDKeyboardCallback) (tUSBHKeyboard *psKbInstance, uint32_t ui32Event, uint32_t ui32MsgParam, void *pvMsgData)
typedef struct tUSBHMouse	tUSBHMouse
typedef void(*	tUSBHIDMouseCallback) (tUSBHMouse *psMsInstance, uint32_t ui32Event, uint32_t ui32MsgParam, void *pvMsgData)

Functions
tUSBHKeyboard *	USBHKeyboardOpen (tUSBHIDKeyboardCallback pfnCallback, uint8_t *pui8Buffer, uint32_t ui32Size)
uint32_t	USBHKeyboardClose (tUSBHKeyboard *psKbInstance)
uint32_t	USBHKeyboardUsageToChar (tUSBHKeyboard *psKbInstance, const tHIDKeyboardUsageTable *psTable, uint8_t ui8UsageID)
uint32_t	USBHKeyboardModifierSet (tUSBHKeyboard *psKbInstance, uint32_t ui32Modifiers)
uint32_t	USBHKeyboardInit (tUSBHKeyboard *psKbInstance)
uint32_t	USBHKeyboardPollRateSet (tUSBHKeyboard *psKbInstance, uint32_t ui32PollRate)
uint32_t	USBHKeyboardLPMSleep (tUSBHKeyboard *psKbInstance)
uint32_t	USBHKeyboardLPMStatus (tUSBHKeyboard *psKbInstance)
tUSBHMouse *	USBHMouseOpen (tUSBHIDMouseCallback pfnCallback, uint8_t *pui8Buffer, uint32_t ui32Size)
uint32_t	USBHMouseClose (tUSBHMouse *psMsInstance)
uint32_t	USBHMouseInit (tUSBHMouse *psMsInstance)
uint32_t	USBHMouseLPMSleep (tUSBHMouse *psMsInstance)
uint32_t	USBHMouseLPMStatus (tUSBHMouse *psMsInstance)

Detailed Description

Macro Definition Documentation

USBHKEYB_REPORT_SIZE

#define USBHKEYB_REPORT_SIZE   8

Referenced by USBHKeyboardInit().

USBHKEYB_DEVICE_PRESENT

#define USBHKEYB_DEVICE_PRESENT   0x00000001

USBHMS_REPORT_SIZE

#define USBHMS_REPORT_SIZE   4

USBHMS_DEVICE_PRESENT

#define USBHMS_DEVICE_PRESENT   0x00000001

Typedef Documentation

tUSBHKeyboard

typedef struct tUSBHKeyboard tUSBHKeyboard

tUSBHIDKeyboardCallback

typedef void(* tUSBHIDKeyboardCallback) (tUSBHKeyboard *psKbInstance, uint32_t ui32Event, uint32_t ui32MsgParam, void *pvMsgData)

tUSBHMouse

typedef struct tUSBHMouse tUSBHMouse

tUSBHIDMouseCallback

typedef void(* tUSBHIDMouseCallback) (tUSBHMouse *psMsInstance, uint32_t ui32Event, uint32_t ui32MsgParam, void *pvMsgData)

Function Documentation

USBHKeyboardOpen()

tUSBHKeyboard * USBHKeyboardOpen	(	tUSBHIDKeyboardCallback	pfnCallback,
		uint8_t *	pui8Buffer,
		uint32_t	ui32Size
	)

This function is used open an instance of a keyboard.

Parameters

pfnCallback	is the callback function to call when new events occur with the keyboard returned.
pui8Buffer	is the memory used by the keyboard to interact with the USB keyboard.
ui32Size	is the size of the buffer provided by pui8Buffer.

This function is used to open an instance of the keyboard. The value returned from this function should be used as the instance identifier for all other USBHKeyboard calls. The pui8Buffer memory buffer is used to access the keyboard. The buffer size required is at least enough to hold a normal report descriptor for the device. If there is not enough space only a partial report descriptor will be read out.

Returns

Returns the instance identifier for the keyboard that is attached. If there is no keyboard present this will return 0.

References eUSBHHIDClassKeyboard, and USBHHIDOpen().

USBHKeyboardClose()

uint32_t USBHKeyboardClose

(

tUSBHKeyboard *

psKbInstance

)

This function is used close an instance of a keyboard.

Parameters

psKbInstance

is the instance value for this keyboard.

This function is used to close an instance of the keyboard that was opened with a call to USBHKeyboardOpen(). The psKbInstance value is the value that was returned when the application called USBHKeyboardOpen().

Returns

This function returns 0 to indicate success any non-zero value indicates an error condition.

References USBHHIDClose().

USBHKeyboardUsageToChar()

uint32_t USBHKeyboardUsageToChar	(	tUSBHKeyboard *	psKbInstance,
		const tHIDKeyboardUsageTable *	psTable,
		uint8_t	ui8UsageID
	)

This function is used to map a USB usage ID to a printable character.

Parameters

psKbInstance	is the instance value for this keyboard.
psTable	is the table to use to map the usage ID to characters.
ui8UsageID	is the USB usage ID to map to a character.

This function is used to map a USB usage ID to a character. The provided psTable is used to perform the mapping and is described by the tHIDKeyboardUsageTable type defined structure. See the documentation on the tHIDKeyboardUsageTable structure for more details on the internals of this structure. This function uses the current state of the shift keys and the Caps Lock key to modify the data returned by this function. The psTable structure has values indicating which keys are modified by Caps and alternate values for shifted cases. The number of bytes returned from Lock this function depends on the psTable structure passed in as it holds the number of bytes per character in the table.

Returns

Returns the character value for the given usage id.

References HID_KEYB_CAPS_LOCK, tHIDKeyboardUsageTable::pui32CapsLock, tHIDKeyboardUsageTable::pvCharMapping, and tHIDKeyboardUsageTable::ui8BytesPerChar.

USBHKeyboardModifierSet()

uint32_t USBHKeyboardModifierSet	(	tUSBHKeyboard *	psKbInstance,
		uint32_t	ui32Modifiers
	)

This function is used to set one of the fixed modifier keys on a keyboard.

Parameters

psKbInstance	is the instance value for this keyboard.
ui32Modifiers	is a bit mask of the modifiers to set on the keyboard.

This function is used to set the modifier key states on a keyboard. The ui32Modifiers value is a bitmask of the following set of values:

• HID_KEYB_NUM_LOCK
• HID_KEYB_CAPS_LOCK
• HID_KEYB_SCROLL_LOCK
• HID_KEYB_COMPOSE
• HID_KEYB_KANA

Not all of these will be supported on all keyboards however setting values on a keyboard that does not have them should have no effect. The psKbInstance value is the value that was returned when the application called USBHKeyboardOpen(). If the value HID_KEYB_CAPS_LOCK is used it will modify the values returned from the USBHKeyboardUsageToChar() function.

Returns

This function returns 0 to indicate success any non-zero value indicates an error condition.

References USBHHIDSetReport().

USBHKeyboardInit()

uint32_t USBHKeyboardInit

(

tUSBHKeyboard *

psKbInstance

)

This function is used to initialize a keyboard interface after a keyboard has been detected.

Parameters

psKbInstance

is the instance value for this keyboard.

This function should be called after receiving a USB_EVENT_CONNECTED event in the callback function provided by USBHKeyboardOpen(), however this function should only be called outside the callback function. This will initialize the keyboard interface and determine the keyboard's layout and how it reports keys to the USB host controller. The psKbInstance value is the value that was returned when the application called USBHKeyboardOpen(). This function only needs to be called once per connection event but it should be called every time a USB_EVENT_CONNECTED event occurs.

Returns

This function returns 0 to indicate success any non-zero value indicates an error condition.

References USBHHIDGetReportDescriptor(), USBHHIDSetIdle(), USBHHIDSetProtocol(), USBHHIDSetReport(), and USBHKEYB_REPORT_SIZE.

USBHKeyboardPollRateSet()

uint32_t USBHKeyboardPollRateSet	(	tUSBHKeyboard *	psKbInstance,
		uint32_t	ui32PollRate
	)

This function is used to set the automatic poll rate of the keyboard.

Parameters

psKbInstance	is the instance value for this keyboard.
ui32PollRate	is the rate in ms to cause the keyboard to update the host regardless of no change in key state.

This function will allow an application to tell the keyboard how often it should send updates to the USB host controller regardless of any changes in keyboard state. The psKbInstance value is the value that was returned when the application called USBHKeyboardOpen(). The ui32PollRate is the new value in ms for the update rate on the keyboard. This value is initially set to 0 which indicates that the keyboard should only to update when the keyboard state changes. Any value other than 0 can be used to force the keyboard to generate auto-repeat sequences for the application.

Returns

This function returns 0 to indicate success any non-zero value indicates an error condition.

References USBHHIDSetIdle().

USBHKeyboardLPMSleep()

uint32_t USBHKeyboardLPMSleep

(

tUSBHKeyboard *

psKbInstance

)

This function forwards an LPM request for a device to enter L1 sleep state.

Parameters

psKbInstance

is the HID keyboard instance that was returned from the call to USBHKeyboardOpen().

This function forwards a request from an application to the HID device class to request that a device enter the LPM L1 sleep state. The caller must check the return value to see if the request can be attempted at this time. If another LPM transaction is busy on this or another device, then this function returns USBHCD_LPM_PENDING. If the LPM request was scheduled to be sent the function returns USBHCD_LPM_AVAIL. The caller should check the USBHCDLPMStatus() function to determine if the request completed successfully or if there was an error.

Returns

This function returns the following values:

• USBHCD_LPM_AVAIL - The transition to L1 state is scheduled to be sent.
• USBHCD_LPM_PENDING - There is already an LPM request pending.

References USBHHIDLPMSleep().

USBHKeyboardLPMStatus()

uint32_t USBHKeyboardLPMStatus

(

tUSBHKeyboard *

psKbInstance

)

This function returns the current status of an LPM request.

Parameters

psKbInstance

is the HID keyboard instance that was returned from the call to USBHKeyboardOpen().

This function returns the current status of LPM requests for a given device. This is called to determine if a previous request completed successfully or if there was an error.

Returns

This function returns the following values:

• USBHCD_LPM_AVAIL - There are no pending LPM requests on this specific device or the last request completed successfully.
• USBHCD_LPM_ERROR - The last LPM request for this device did not complete successfully.
• USBHCD_LPM_PENDING - The last LPM request has not completed.

References USBHHIDLPMStatus().

USBHMouseOpen()

tUSBHMouse * USBHMouseOpen	(	tUSBHIDMouseCallback	pfnCallback,
		uint8_t *	pui8Buffer,
		uint32_t	ui32Size
	)

This function is used open an instance of a mouse.

Parameters

pfnCallback	is the callback function to call when new events occur with the mouse returned.
pui8Buffer	is the memory used by the driver to interact with the USB mouse.
ui32Size	is the size of the buffer provided by pui8Buffer.

This function is used to open an instance of the mouse. The value returned from this function should be used as the instance identifier for all other USBHMouse calls. The pui8Buffer memory buffer is used to access the mouse. The buffer size required is at least enough to hold a normal report descriptor for the device.

Returns

Returns the instance identifier for the mouse that is attached. If there is no mouse present this will return 0.

References eUSBHHIDClassMouse, and USBHHIDOpen().

USBHMouseClose()

uint32_t USBHMouseClose

(

tUSBHMouse *

psMsInstance

)

This function is used close an instance of a mouse.

Parameters

psMsInstance

is the instance value for this mouse.

This function is used to close an instance of the mouse that was opened with a call to USBHMouseOpen(). The psMsInstance value is the value that was returned when the application called USBHMouseOpen().

Returns

Returns 0.

References USBHHIDClose().

USBHMouseInit()

uint32_t USBHMouseInit

(

tUSBHMouse *

psMsInstance

)

This function is used to initialize a mouse interface after a mouse has been detected.

Parameters

psMsInstance

is the instance value for this mouse.

This function should be called after receiving a USB_EVENT_CONNECTED event in the callback function provided by USBHMouseOpen(), however it should only be called outside of the callback function. This will initialize the mouse interface and determine how it reports events to the USB host controller. The psMsInstance value is the value that was returned when the application called USBHMouseOpen(). This function only needs to be called once per connection event but it should be called every time a USB_EVENT_CONNECTED event occurs.

Returns

Non-zero values should be assumed to indicate an error condition.

References USBHHIDGetReportDescriptor(), USBHHIDSetIdle(), and USBHHIDSetProtocol().

USBHMouseLPMSleep()

uint32_t USBHMouseLPMSleep

(

tUSBHMouse *

psMsInstance

)

This function forwards an LPM request for a device to enter L1 sleep state.

Parameters

psMsInstance

is the HID keyboard instance that was returned from the call to USBHMouseOpen().

This function forwards a request from an application to the HID device class to request that a device enter the LPM L1 sleep state. The caller must check the return value to see if the request can be attempted at this time. If another LPM transaction is busy on this or another device, then this function returns USBHCD_LPM_PENDING. If the LPM request was scheduled to be sent the function returns USBHCD_LPM_AVAIL. The caller should check the USBHCDLPMStatus() function to determine if the request completed successfully or if there was an error.

Returns

This function returns the following values:

• USBHCD_LPM_AVAIL - The transition to L1 state is scheduled to be sent.
• USBHCD_LPM_PENDING - There is already an LPM request pending.

References USBHHIDLPMSleep().

USBHMouseLPMStatus()

uint32_t USBHMouseLPMStatus

(

tUSBHMouse *

psMsInstance

)

This function returns the current status of an LPM request.

Parameters

psMsInstance

is the HID keyboard instance that was returned from the call to USBHMouseOpen().

This function returns the current status of LPM requests for a given device. This is called to determine if a previous request completed successfully or if there was an error.

Returns

This function returns the following values:

• USBHCD_LPM_AVAIL - There are no pending LPM requests on this specific device or the last request completed successfully.
• USBHCD_LPM_ERROR - The last LPM request for this device did not complete successfully.
• USBHCD_LPM_PENDING - The last LPM request has not completed.

References USBHHIDLPMStatus().