| usb Vitis Drivers API Documentation

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

Functions
xusb_storage.c File Reference

## Overview

This file contains Mass storage device application related functions.

Note
  The example is tested on MicroBlaze, PPC405 and 440 systems with caches included in the H/W design and also with systems not having caches.

    MODIFICATION HISTORY:

    Ver   Who  Date     Changes

    1.00a hvm  2/22/07 First release
    1.01a hvm  5/30/07 Added code to handle endpoint zero class specific
                  commands. Added support for PPC.
    1.01a hvm  10/2/08 The complete SCSI READ command processing implementation
                    is modified. The send processing is shifted into the
                    endpoint one interrupt handler.Updated the code to
                    enable caches.
    2.00a hvm  12/08/08 Updated the example with cache APIs
    2.00a hvm  03/12/09 Updated the example with DMA Done check for every
                    transaction initiated.
    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.
    3.02a hvm  08/16/10 Updated with the little endian support changes.
    4.00a hvm  06/01/11 Signature parameter of Command Status word is
                    initialized with 'U''S''B''S' in ProcessRxCmd function.
                    CR611761 fix.
    4.00a hvm  24/06/11 The cache flush call with 512 size in EP1 handler is
                    moved inside the HIGHSPEED condition. CR614791
    4.02a bss  11/01/11 Modified UsbIfIntrHandler function to unconditionally
                    reset when USB reset is asserted (CR 627574).
    5.2     MNK    03/30/2016 Modified the example to support ZYNQMP.
    5.6   pm   07/05/23 Removed powerpc support.
    5.6   pm   07/05/23 Added support for system device-tree flow.

## Functions
int | main ()
| This main function starts the USB application. More...
void | InitUsbInterface (XUsb *InstancePtr)
| This is the USB initialization function. More...
void | UsbIfIntrHandler (void *CallBackRef, u32 IntrStatus)
| This function is the interrupt handler for the USB mass storage device application. 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...
void | Ep2IntrHandler (void *CallBackRef, u8 EpNum, u32 IntrStatus)
| This function is the interrupt handler for the USB End point two events. More...
void | ProcessRxCmd (XUsb *InstancePtr)
| This function processes mass storage specific commands and sends the required response. More...
void | Read10 (XUsb *InstancePtr, PUSBCBW pCmdBlock, PUSBCSW pStatusBlock)
| This function implements the transmission of data from the device to the READ request from the USB Host. More...
void | Write10 (XUsb *InstancePtr, PUSBCBW pCmdBlock, PUSBCSW pStatusBlock)
| This function implements the reception of data in the USB device for the write request from the USB Host. More...
void | MassStorageReset (XUsb *InstancePtr)
| This routine is called when a RESET class command is received. More...
void | GetMaxLUN (XUsb *InstancePtr)
| This routine is called when a GETMAXLUN class command is received. 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(), GetMaxLUN(), MassStorageReset(), 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_Config::BaseAddress, XUsb_EpConfig::Buffer0Ready, XUsb_EpConfig::Buffer1Ready, XUsb::Config, XUsb_DeviceConfig::CurrentSpeed, XUsb::DeviceConfig, XUsb_Config::DmaEnabled, XUsb_DeviceConfig::Ep, XUSB_BUFFREADY_EP1_BUFF1_MASK, XUSB_BUFFREADY_EP1_BUFF2_MASK, XUSB_DMA_DMASR_BUSY, XUSB_DMA_STATUS_OFFSET, XUSB_EP_HIGH_SPEED, XUsb_EpDataSend(), and XUsb_ReadReg.

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

This function is the interrupt handler for the USB End point two 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 two. 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_EP2_BUFF1_MASK, and XUSB_BUFFREADY_EP2_BUFF2_MASK.

void GetMaxLUN | ( | XUsb * | InstancePtr | ) |

This routine is called when a GETMAXLUN class command is received.

Parameters

  InstancePtr | is a pointer to the XUsb instance of the controller.

Returns
  None.

Note
  None.

References XUsb_Config::BaseAddress, XUsb_EpConfig::Buffer0Ready, XUsb::Config, XUsb::DeviceConfig, XUsb::EndPointOffset, XUsb_DeviceConfig::Ep, XUsb_EpConfig::RamBase, XUSB_BUFFREADY_OFFSET, XUSB_EP_BUF0COUNT_OFFSET, and XUsb_WriteReg.

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

This is the USB initialization function.

This example initializes the device for Mass Storage Application. The following configuration is done.

- EP0 : CONTROL end point, Bidirectional, Packet size 64 bytes.
- EP1 : NON_ISOCHRONOUS, BULK_IN, packet size 512 bytes.
- EP2 : NON_ISOCHRONOUS, BULK_OUT, packet size 512 bytes

Parameters

  InstancePtr | is a pointer to the XUsb instance.

Returns
  None.

Note
  None.

References XUsb_Config::BaseAddress, XUsb_EpConfig::Buffer0Ready, XUsb_EpConfig::Buffer1Ready, XUsb::Config, XUsb::DeviceConfig, XUsb_DeviceConfig::Ep, XUsb_EpConfig::EpType, XUsb_DeviceConfig::NumEndpoints, XUsb_EpConfig::OutIn, XUsb_EpConfig::RamBase, XUsb_EpConfig::Size, XUsb_DeviceConfig::Status, XUSB_BUFFREADY_OFFSET, XUsb_ConfigureDevice(), XUSB_EP_DIRECTION_IN, XUSB_EP_DIRECTION_OUT, XUsb_EpEnable(), XUSB_RESET, XUSB_STATUS_EP_BUFF2_SHIFT, and XUsb_WriteReg.

int main | ( | void |  | ) |

This main function starts the USB application.

Parameters

  None. |

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

Note
  None.

References XUsb_Config::BaseAddress, XUsb::Config, XUsb_DeviceConfig::CurrentConfiguration, XUsb::DeviceConfig, XUsb_Config::DmaEnabled, Ep0IntrHandler(), Ep1IntrHandler(), Ep2IntrHandler(), InitUsbInterface(), ProcessRxCmd(), UsbIfIntrHandler(), XUsb_CfgInitialize(), XUSB_DMA_DMASR_BUSY, XUSB_DMA_STATUS_OFFSET, XUsb_EpDataRecv(), XUsb_EpSetHandler(), XUsb_IntrEnable(), XUsb_IntrHandler(), XUsb_IntrSetHandler(), XUsb_LookupConfig(), XUsb_ReadReg, 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_EP2_BUFF1_COMP_MASK, XUSB_STATUS_EP2_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.

void MassStorageReset | ( | XUsb * | InstancePtr | ) |

This routine is called when a RESET class command is received.

Parameters

  InstancePtr | is a pointer to the XUsb instance of the controller.

Returns
  None.

Note
  None.

References SetupControlWriteStatusStage().

void ProcessRxCmd | ( | XUsb * | InstancePtr | ) |

This function processes mass storage specific commands and sends the required response.

Parameters

  InstancePtr | is a pointer to the XUsb instance.

Returns
  None.

Note
  None.

References XUsb_Config::BaseAddress, XUsb::Config, XUsb::DeviceConfig, XUsb_Config::DmaEnabled, Read10(), XUsb_DeviceConfig::Status, Write10(), XUSB_DISCONNECTED, XUSB_DMA_DMASR_BUSY, XUSB_DMA_STATUS_OFFSET, XUsb_EpDataSend(), and XUsb_ReadReg.

void Read10 | ( | XUsb * | InstancePtr,
|  | PUSBCBW | pCmdBlock,
|  | PUSBCSW | pStatusBlock
| ) |  |

This function implements the transmission of data from the device to the READ request from the USB Host.

Parameters

  InstancePtr | is a pointer to the XUsb instance.
  pCmdBlock | is a pointer to the Mass Storage Command Block wrapper.
  pStatusBlock | is a pointer to the Mass Storage Status wrapper.

Returns
  None.

Note
  None.

References XUsb_Config::BaseAddress, XUsb::Config, XUsb_DeviceConfig::CurrentSpeed, XUsb::DeviceConfig, XUsb_Config::DmaEnabled, XUsb_DeviceConfig::Status, XUSB_DISCONNECTED, XUSB_DMA_DMASR_BUSY, XUSB_DMA_STATUS_OFFSET, XUSB_EP_HIGH_SPEED, XUsb_EpDataSend(), and XUsb_ReadReg.

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

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
  None.

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.

void Write10 | ( | XUsb * | InstancePtr,
|  | PUSBCBW | pCmdBlock,
|  | PUSBCSW | pStatusBlock
| ) |  |

This function implements the reception of data in the USB device for the write request from the USB Host.

Parameters

  InstancePtr | is a pointer to the XUsb instance.
  pCmdBlock | is a pointer to the Mass Storage Command Block wrapper.
  pStatusBlock | is a pointer to the Mass Storage Status wrapper.

Returns
  None.

Note
  None.

References XUsb_Config::BaseAddress, XUsb::Config, XUsb_DeviceConfig::CurrentSpeed, XUsb::DeviceConfig, XUsb_Config::DmaEnabled, XUsb_DeviceConfig::Status, XUSB_DISCONNECTED, XUSB_DMA_DMASR_BUSY, XUSB_DMA_STATUS_OFFSET, XUSB_EP_HIGH_SPEED, XUsb_EpDataRecv(), and XUsb_ReadReg.