| usb Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

Functions
xusb_keyboard.c File Reference

## Overview

This file contains an example for USB keyboard.

Note
  - The example is tested on ML403 and ML507 evaluation boards. The push buttons SW3,SW4,SW5 and SW7 on the ML403 evaluation board are used in the example for the key action of the USB keyboard.The push buttons SW10, SW11, SW12, SW13 and SW14 are used on the ML507 board. The example sends a character from a fixed sequence of characters from the device as and when any of the SW3 or SW4 or SW5 and SW7 push button is pressed. The fixed sequence of characters is XILINX USB KEYBOARD DEMO. The SW6 push button switch is used to complete the test. SW14 is used on ML507 board to complete the test.
  - The GPIO device has to be added to the hardware design so that the push buttons on the evaluation board could be used. If we enable the debug statements in the xusb_cp9.c file, we must add the UARTLite core to the hardware design. Debug messages can be enabled by defining the constant XUSB_DEBUG,
  - To run this example, the evaluation board is to be connected to a windows Host PC over the USB port.
  - The example configures the USB device for endpoint 0 and endpoint 1. Endpoint 0 is the control endpoint and is configured for a maximum packet length of 64 bytes. End point 1 is configured for INTERRUPT IN transactions and the maximum packet size is configured as 16 bytes.
  - The USB keyboard example code has to be compiled along with the xusb_cp9.c file. The xusb_cp9.c file contains all the USB enumeration related functions. To compile the code for USB keyboard example, the constant definitions HID_DEVICES and USB_KEYBOARD are to be defined and the definitions the constants USB_MOUSE and MASS_STORAGE_DEVICE are to be undefined. These definitions can be found in the xusb_types.h file.

    MODIFICATION HISTORY:

    Ver   Who  Date     Changes

    1.00a hvm  5/31/07 First release
    3.00a hvm  11/18/09 Updated to use HAL processor APIs.
                   XUsb_mReadReg is renamed to XUsb_ReadReg and
                   XUsb_mWriteReg is renamed to XUsb_WriteReg.
    4.00a hvm  08/11/11 Updated the code in gpio isr to increment the index by 4 as
                    a dummy byte is added in the Message variable in keyboard.h
                    file to handle the address alignment issue.
    4.02a bss  11/01/11 Modified UsbIfIntrHandler function to unconditionally
                    reset when USB reset is asserted (CR 627574).
    5.6   pm   07/05/23 Added support for system device-tree flow.

## Functions
int | UsbKbdExample (u16 UsbId, u16 GpioId)
| This function implements the USB Keyboard example. More...
void | GpioIsr (void *InstancePtr)
| This function is the Interrupt Service Routine for the GPIO device. More...
int | main (void)
| This function is the main function of the USB Keyboard example. More...
void | InitUsbInterface (XUsb *InstancePtr)
| This function initializes the USB device for Keyboard example. More...
void | UsbIfIntrHandler (void *CallBackRef, u32 IntrStatus)
| This function is the interrupt handler for the USB keyboard example. More...
void | Ep0IntrHandler (void *CallBackRef, u8 EpNum, u32 IntrStatus)
| This function is the interrupt handler for the USB End point Zero events. More...
void | Ep1IntrHandler (void *CallBackRef, u8 EpNum, u32 IntrStatus)
| This function is the interrupt handler for the USB End point one events. More...

## Function Documentation

void Ep0IntrHandler | ( | void * | CallBackRef,
|  | u8 | EpNum,
|  | u32 | IntrStatus
| ) |  |

This function is the interrupt handler for the USB End point Zero events.

Parameters

  CallBackRef | is the callback reference passed from the interrupt. handler, which in our case is a pointer to the driver instance.
  EpNum | is the end point number.
  IntrStatus | is a bit mask indicating pending interrupts.

Returns
  None.

Note
  EpNum is not used in this function as the handler is attached specific to end point zero. This parameter is useful when a single handler is used for processing all end point interrupts.

References Chapter9(), EP0ProcessInToken(), EP0ProcessOutToken(), XUSB_BUFFREADY_EP0_BUFF_MASK, XUsb_EpStall(), XUsb_IntrEnable(), XUSB_STATUS_DISCONNECT_MASK, XUSB_STATUS_FIFO_BUFF_FREE_MASK, XUSB_STATUS_FIFO_BUFF_RDY_MASK, XUSB_STATUS_RESET_MASK, XUSB_STATUS_SETUP_PACKET_MASK, and XUSB_STATUS_SUSPEND_MASK.

void Ep1IntrHandler | ( | void * | CallBackRef,
|  | u8 | EpNum,
|  | u32 | IntrStatus
| ) |  |

This function is the interrupt handler for the USB End point one events.

Parameters

  CallBackRef | is the callback reference passed from the interrupt handler, which in our case is a pointer to the driver instance.
  EpNum | is the end point number.
  IntrStatus | is a bit mask indicating pending interrupts.

Returns
  None.

Note
  EpNum is not used in this function as the handler is attached specific to end point one. This parameter is useful when a single handler is used for processing all end point interrupts.

References XUsb_EpConfig::Buffer0Ready, XUsb_EpConfig::Buffer1Ready, XUsb::DeviceConfig, XUsb_DeviceConfig::Ep, XUSB_BUFFREADY_EP1_BUFF1_MASK, and XUSB_BUFFREADY_EP1_BUFF2_MASK.

void GpioIsr | ( | void * | InstancePtr | ) |

This function is the Interrupt Service Routine for the GPIO device.

This function will detect the push button on the board has changed state and then prepare data to be sent to the host.

Parameters

  InstancePtr | is the GPIO component to operate on. It is a void pointer and in this case will be a pointer to the GPIO instance.

Returns
  None.

Note
  None.

This function will detect the push button on the board has changed state and then prepare data to be sent to the host upon receiving the Get

Parameters

  InstancePtr | is the GPIO component to operate on. It is a void pointer to meet the interface of an interrupt processing function.

Returns
  None.

Note
  None.

References XUsb_EpDataSend().

Referenced by UsbKbdExample(), and UsbMouseExample().

void InitUsbInterface | ( | XUsb * | InstancePtr | ) |

This function initializes the USB device for Keyboard example.

This is the USB initialization function.

The following is the configuration.

- EP0 : CONTROL end point, Bidirectional, Packet size 64 bytes.
- EP1 : NON_ISOCHRONOUS, INTERRUPT_IN, packet size of 16 bytes.

Parameters

  InstancePtr | is a pointer to the XUsb instance.

Returns
  None.

Note
  None.

References XUsb::DeviceConfig, XUsb_DeviceConfig::Ep, XUsb_EpConfig::EpType, XUsb_DeviceConfig::NumEndpoints, XUsb_EpConfig::OutIn, XUsb_EpConfig::RamBase, XUsb_EpConfig::Size, XUsb_ConfigureDevice(), XUSB_EP_DIRECTION_IN, XUSB_EP_DIRECTION_OUT, and XUsb_EpEnable().

int main | ( | void |  | ) |

This function is the main function of the USB Keyboard example.

Parameters

  None. |

Returns
  - XST_SUCCESS if successful,
  - XST_FAILURE if unsuccessful.

Note
  None.

References UsbKbdExample().

void UsbIfIntrHandler | ( | void * | CallBackRef,
|  | u32 | IntrStatus
| ) |  |

This function is the interrupt handler for the USB keyboard example.

This function is the interrupt handler for the USB mass storage device application.

Parameters

  CallBackRef | is the callback reference passed from the interrupt handler, which in our case is a pointer to the driver instance.
  IntrStatus | is a bit mask indicating pending interrupts.

Returns
  None.

Note
  Each interrupt source is disabled upon reception. This is to avoid the repetitive occurrence of the same event. This is done because these event conditions exist for few milliseconds.

References XUsb_Config::BaseAddress, XUsb::Config, XUsb_DeviceConfig::CurrentConfiguration, XUsb::DeviceConfig, InitUsbInterface(), XUsb_DeviceConfig::Status, XUsb_IntrDisable(), XUsb_IntrEnable(), XUSB_RESET, XUsb_SetDeviceAddress(), XUsb_Start(), XUSB_STATUS_DISCONNECT_MASK, XUSB_STATUS_RESET_MASK, XUSB_STATUS_SUSPEND_MASK, XUsb_Stop(), and XUsb_WriteReg.

int UsbKbdExample | ( | u16 | UsbId,
|  | u16 | GpioId
| ) |  |

This function implements the USB Keyboard example.

The Key board action can be seen on the PC as and when any of the push buttons SW3 or SW4 or SW5 or SW7 on the ML403 evaluation board is pressed.

Parameters

  UsbId | is the USB device id.
  GpioId | is the GPIO device id.

Returns
  - XST_SUCCESS if successful.
  - XST_FAILURE if test fails.

Note
  None.

References XUsb_Config::BaseAddress, XUsb_DeviceConfig::CurrentConfiguration, XUsb::DeviceConfig, Ep0IntrHandler(), Ep1IntrHandler(), GpioIsr(), InitUsbInterface(), UsbIfIntrHandler(), XUsb_CfgInitialize(), XUsb_EpSetHandler(), XUsb_IntrEnable(), XUsb_IntrHandler(), XUsb_IntrSetHandler(), XUsb_LookupConfig(), XUsb_SetDeviceAddress(), XUsb_Start(), XUSB_STATUS_DISCONNECT_MASK, XUSB_STATUS_EP0_BUFF1_COMP_MASK, XUSB_STATUS_EP1_BUFF1_COMP_MASK, XUSB_STATUS_EP1_BUFF2_COMP_MASK, XUSB_STATUS_FIFO_BUFF_FREE_MASK, XUSB_STATUS_FIFO_BUFF_RDY_MASK, XUSB_STATUS_GLOBAL_INTR_MASK, XUSB_STATUS_RESET_MASK, and XUSB_STATUS_SUSPEND_MASK.

Referenced by main().