UM1021 User manual. STM32F105/107xx USB Host library. Introduction

Please download to get full document.

View again

of 31
All materials on our website are shared by users. If you have any questions about copyright issues, please report us to resolve them. We are always happy to assist you.
Information Report
Category:

How To, Education & Training

Published:

Views: 215 | Pages: 31

Extension: PDF | Download: 3

Share
Related documents
Description
User manual STM32F105/107xx USB Host library Introduction The STM32F105/7 USB host library is intended to provide a framework for USB host applications development. The library stands on top of the STM32F105/7
Transcript
User manual STM32F105/107xx USB Host library Introduction The STM32F105/7 USB host library is intended to provide a framework for USB host applications development. The library stands on top of the STM32F105/7 USB OTG peripheral low-level driver. It implements the necessary software blocks that aim to facilitate the developement of USB host applications. The STM32F105/7 USB host stack library supports the following two USB standard class applications: Mass Storage Class (MSC) for accessing USB flash pendrives Human Interface Device (HID) class for keyboard and mouse devices November 2010 Doc ID Rev 1 1/31 Contents UM1021 Contents 1 Folder organization of the USB host package USB host library architecture Library block diagram organization Description of the library core Core state machine Device enumeration Control transfer state machine USB I/O requests module Host channels control module Class drivers USB Mass Storage Class (MSC) driver USB Human Interface Device (HID) class driver for mouse and keyboard devices Library user API and callback functions Library user API User callback functions Class callback functions Class-independent callback functions Demo firmware Mass storage class demo Software initializations Mass storage device enumeration Accessing mass storage device content Flash pendrive tests HID mouse and keyboard demos Initializations Mouse or keyboard device enumeration Mouse demo Keyboard demo Demo footprints /31 Doc ID Rev 1 Contents 5 Known limitations Revision history Doc ID Rev 1 3/31 List of tables UM1021 List of tables Table 1. Core files Table 2. Class files Table 3. Device enumeration requests Table 4. USB I/O requests module Table 5. Host channels control module Table 6. Mass Storage Class modules Table 7. MSC core module Table 8. MSC BOT module Table 9. MSC SCSI commands Table 10. MSC filesystem interface functions Table 11. EFSL main API Table 12. HID class modules Table 13. MSC core module functions Table 14. Mouse and keyboard intialization & HID report decoding functions Table 15. Tested flash pendrives Table 16. Demo footprints Table 17. Document revision history /31 Doc ID Rev 1 List of figures List of figures Figure 1. Folder organization Figure 2. USB host library block diagram organization Figure 3. Core state machine Figure 4. Device enumeration Figure 5. Block diagram organization of the MSC driver Figure 6. MS device enumeration Figure 7. MS device content access Figure 8. Mouse demo Figure 9. Keyboard demo Doc ID Rev 1 5/31 Folder organization of the USB host package UM Folder organization of the USB host package The STM32 USB host library package has the following folder organization: Figure 1. Folder organization STM32_USB_HOST_LIB_PACKAGE Librairies CMSIS The package folders are organized as follows: STM32_USB_HOST_Library Class HID MSC Core STM32_USB_HOST_Driver STM32F10x_StdPeriph_Driver Project USB_HOST_Examples HID_KBrd_Mouse MSC Utilities STM32_EVAL STM3210C_EVAL Third_Party efsl Libraries: CMSIS: Cortex Microcontroller Software Interface Standard files STM32_USB_HOST_Library: USB Host library files STM32_USB_HOST_Driver: STM32 USB 2.0 OTG peripheral low-level driver STM32F10x_StdPeriph_Driver: STM32 standard peripheral drivers Project: USB_HOST_EXAMPLES/HID_KBrd_Mouse : HID mouse and keyboard demo files USB_HOST_EXAMPLES/MSC: Mass Storage Class demo files Utilities: STM32_EVAL/STM3210C_EVAL : STM3210C_EVAL evalboard functions (configuration of GPIOs, LCD, clocks,..) Third_Party/efsl: EFSL FAT filesystem, used for the mass storage demo 6/31 Doc ID Rev 1 Folder organization of the USB host package File organization of the USB host library The USB host library folder STM32_USB_HOST_Library is composed of two main subfolders: Core: this folder contains the USB host library core files. Those files implement the necessary functions, state machines and data structures required for: device detection and enumeration, USB Control transfer management, low-level functions for issuing control, bulk or interrupt USB transactions, configuration of the USB host channels. Class: this folder contains the necessary files for USB class management. The USB host library supports two USB classes: MSC: Mass Storage Class HID: Human Interface Device class for boot mouse and keyboard devices The following tables detail the Core and Class files: Table 1. Core files File Description usbh_core.c /.h Implements the core, the device enumeration and the control transfer state machines usbh_stdreq.c /.h USB standard requests needed during device enumeration (USB chapter 9) usbh_ioreq.c /.h usbh_hcs.c /.h usbh_def.h USB I/O requests: USB transaction requests for control, bulk and interrupt pipes USB host channel control (channel configuration, allocation, freeing...) Definitions used throughout the USB host library Table 2. Class files Class File Description HID MSC usbh_hid_core.c /.h usbh_hid_mouse.c./h usbh_hid_keyboard.c /.h usbh_msc_core.c /.h usbh_msc_bot.c./.h usbh_msc_scsi.c /.h usbh_msc_fs_interface.c./h HID class management HID mouse specific routines HID keyboard specific routines Mass Storage Class management BOT Bulk Only Transport protocol implementation SCSI standard command implementation Interface with a filesystem for file access operations Doc ID Rev 1 7/31 USB host library architecture UM USB host library architecture 2.1 Library block diagram organization The USB host library has the following block diagram organization: Figure 2. USB host library block diagram organization Library user APIs & callback functions User application File system USB host library HID MSC Class drivers Core Core state machine Device enumeration Control transfer state machine USB I/O requests USB host channels control STM32 USB OTG peripheral low-level driver As shown in the above figure, the USB host library is composed of two main parts: the core and the class drivers. The library core is composed of five main blocks: core state machine device enumeration control transfer state machine USB I/O requests USB host channels control For all class-related operations, the core state machine hands over operation to a specific class driver. In the current release version of the USB host libray, two class drivers - HID and MSC - are implemented. These class drivers use core layer services for communicating with the low-level driver. Both the core and the class drivers communicate with the user application mainly through defined callback functions. The various host library blocks are described below. 8/31 Doc ID Rev 1 USB host library architecture 2.2 Description of the library core Core state machine The following figure describes the library state machine: Figure 3. Device connection Event Core state machine HOST_ISSUE_ CORE_RESET Host Initializations USB Reset Issued HOST_IDLE Device disconnection Event Device connected & USB Reset Issued HOST_DEV_ATTACHED USB Full/Low speed device attached HOST_ENUMERATION HOST_CTRL_XFER Device enumerated User selects to enter in class operation HOST_USR_INPUT HOST_ERROR_STATE HOST_CLASS_REQUEST End of class requests calls Control transfer Unrecovered error HOST_CLASS The core state machine shows 8 states: HOST_IDLE: after host initialization, the core starts in this state, where it polls for a USB device connection. This state is also entered when a device disconnection event is detected, and also when an unrecovered error occurs. HOST_ISSUE_CORE_RESET: this state is entered when a device is connected in order to issue a USB bus RESET. HOST_DEV_ATTACHED: the core enters in this state when a device is attached. When a full-speed or low-speed device is detected, the state machine moves to the HOST_ENUMERATION state. HOST_ENUMERATION: in this state, the core proceeds with a basic enumeration of the USB device. At the end of enumeration process, the default device configuration (configuration 0) is selected. Doc ID Rev 1 9/31 USB host library architecture UM1021 HOST_USR_INPUT: this is an intermediary state which follows the enumeration and which includes a wait for user input in order to enter in USB class operation. HOST_CLASS_REQUEST: starting from this state, the class driver takes over, and a class request state machine is called in order to handle all the initial class control requests (ex: Get_Report_Descriptor for HID). After finishing the needed class requests, the core moves to the HOST_CLASS state. HOST_CLASS: in this state, the class state machine is called for class-related operation (non-control and control operation). HOST_CTRL_XFER: this state is entered whenever there is a need for a control transfer. HOST_ERROR_STATE: this state is entered whenever there is an unrecovered error from any library state machine; in such case, a user-callback function is called (for example for displaying an unrecovered error message). Then the host library is reinitialized. The core state machine process is implemented by function USBH_Process. This function should be called periodically from the application main loop. The initalization of the USB host library is implemented by function USBH_init. This function should be called from the user application during initialization. More details regarding this function are provided in Section Device enumeration After detecting a full- or low-speed device, the host library proceeds with a basic enumeration of the device. The following diagram shows the different steps involved in the device enumeration. Figure 4. Device enumeration Get first 8 bytes of device descriptor USB reset Get full device descriptor Set device address Get configuration descriptor Get string descriptors (MFC, product and serial number) Set device configuration 10/31 Doc ID Rev 1 USB host library architecture The enumeration state machine is implemented in library function USBH_HandleEnum, which is called from the core state machine process. USBH_HandleEnum function makes calls to the following library routines (implemented in file usbh_stdreq.c): Table 3. Function Device enumeration requests Description USBH_Get_CfgDesc USBH_Get_DevDesc USBH_Get_StringDesc USBH_GetDescriptor USBH_SetCfg 1) USBH_SetAddress 2) USBH_ClrFeature Get configuration descriptor request Get device descriptor request Get string descriptor request Generic get descriptor request Set configuration request Set address request Clear feature request Note: 1 USBH_SetCfg calls select the default configuration (configuration 0) 2 USBH_SetAddress calls set the device address to 0x1. A user callback will be called at the end of enumeration phase in order to enable the user to process the descriptor information (such as displaying descriptor data, for example). For more details, please refer to Section Control transfer state machine The control transfer state machine is entered from core or class driver whenever a control transfer is required. This state machine implements the standard stages for a control transfer, i.e. the setup stage, the optional data stage and, finally, the status stage. The control transfer state machine is implemented in function USBH_HandleControl. It is called from the core state machine process USB I/O requests module The USB I/O requests module is located in the low layer of the core. It interfaces with the USB low-level driver for issuing control, bulk or interrupt USB transactions. Doc ID Rev 1 11/31 USB host library architecture UM1021 Table 4 shows the main functions in the I/O request module. These functions are implemented in file usbh_ioreq.c. Table 4. USB I/O requests module Function Description USBH_CtlSendSetup USBH_CtlSendData USBH_CtlReceiveData USBH_CtlReq USBH_BulkSendData USBH_BulkReceiveData USBH_InterruptSendData USBH_InterruptReceiveData Issue a setup transaction Issue a control data OUT stage transaction Issue a control data IN stage transaction high level function for issuing a control transfer (setup, data, status stages) Issue a bulk OUT transaction Issue a bulk IN transaction Issue an interrupt OUT transaction Issue an interrupt IN transaction Host channels control module The host channels control module is located in the lower layer of the core, it allows the configuration of a host channel for a particular operation (control, bulk or interrupt transfer type) also the allocation of a selected host channel to a device endpoint for creating a USB pipe. The main functions for USB channel control module are defined in Table 6. These functions are implemented in file usbh_hcs.c. Table 5. Host channels control module Function Description USBH_Open_Channel USBH_Modify_Channel USBH_Alloc_Channel USBH_Free_Channel Open and configure a new host channel Modify an existing host channel Allocate a host channel to a device endpoint (creation of a USB pipe) Free a host channel 12/31 Doc ID Rev 1 USB host library architecture 2.3 Class drivers At the end of the enumeration, the core calls a specific class driver function to manage all class-related operations. Please note that the proper class driver selection is not based on the result of device enumeration, but it is pre-defined when initializing the host library with function call USBH_Init. A class driver is implemented using a structure of type USBH_Class_cb_TypeDef: typedef struct _Device_cb { USBH_Status (*Init) (USB_OTG_CORE_HANDLE *pdev, USBH_DeviceProp_TypeDef *hdev); void (*DeInit) (USB_OTG_CORE_HANDLE *pdev, USBH_DeviceProp_TypeDef *hdev); USBH_Status (*Requests)(USB_OTG_CORE_HANDLE *pdev, USBH_DeviceProp_TypeDef\ *hdev); USBH_Status (*Machine) (USB_OTG_CORE_HANDLE *pdev, USBH_DeviceProp_TypeDef\ *hdev); } USBH_Class_cb_TypeDef; The structure members are described below: Init: this function is called at the start-up of class operation for assuring all needed initializations. This includes: parsing interface and endpoint descriptors (please note that the current USB host library supports only one interface), opening and allocating host channels for non-control endpoints, call to a user callback (see Section 3), in case the device is not supported by the class. Denit: this function is called for freeing allocated host channels when reinitializing the host. It is called when a device is unplugged or in case of unrecovered error. Request: this function implements the class request state machine. It is called duringthe HOST_CLASS_REQUEST state; its purpose is to process initial class requests. Machine: implements the class core state machine. It is called during the HOST_CLASS core state USB Mass Storage Class (MSC) driver The Mass Storage Class driver is intended to support common USB flash pendrives, using the BOT Bulk-Only Transport protocol. The following modules, located in the class\msc folder, are used to implement the MSC driver: Table 6. Mass Storage Class modules Module usbh_msc_core.c /.h usbh_msc_bot.c./.h usbh_msc_scsi.c /.h usbh_msc_fs_interface.c./h Description MSC core state machine implementation BOT Bulk-Only Transport protocol implementation SCSI command implementation Functions for interfacing with a filesystem for file access operations Doc ID Rev 1 13/31 USB host library architecture UM1021 The block diagram in Figure 5 shows the interactions between those modules. Figure 5. Block diagram organization of the MSC driver User MSC application callback File access (OPEN,READ,WRITE) Filesystem (EFSL) Filesystem interface User callbacks call MSC Class Page READ/WRITE Filesystem init MSC core state machine SCSI commands -READ(10) / WRITE(10) -TEST_UNIT_READY -MODE_SENSE(6) -READ_CAPACITY(10) -REQUEST_SENSE BOT state machine BULK IN / OUT Control Class requests: -GET_MAX_LUN -BOT_RESET USB I/O requests Operation flow description: The MSC core state machine starts with the required device initializations, which are: Issuing GET_MAX_LUN class request for detecting the number of device logical units present on the device. Please note that only devices with one logical unit are supported. Issuing BOT_RESET class requests for resetting the device BOT state machine. Issuing SCSI commands: MODE_SENSE for detecting if the device is write-protected and READ_CAPACITY for detecting the size of the flash pendrive. After the above device initializations, the MSC core state machine calls the application user callback. The user callback can do any type of file access into the used filesystem. This operation is translated into a logical page read or write operation. The filesystem interface provides the connection between the used filesystem and the MSC driver. At the SCSI level, the logical page read or write operations are converted into SCSI commands: READ(10) or WRITE(10). Those commands are transfered to the flash pendrive device using the Bulk-Only Tranport protocol. The BOT layer state machine issues the required Bulk IN and Bulk OUT transactions using the core USB I/O request module. Each MSC module is described below. 14/31 Doc ID Rev 1 USB host library architecture MSC core module: The MSC core module usb_msc_core.c implements the MSC driver, which is defined in the structure MSC_cb of type USBH_Class_cb_TypeDef (see section 2.3). USBH_Class_cb_TypeDef MSC_cb = { USBH_MSC_InterfaceInit, USBH_MSC_InterfaceDeInit, USBH_MSC_ClassRequest, USBH_MSC_Handle, }; Table 7. MSC core module Function Description USBH_MSC_InterfaceInit USBH_MSC_InterfaceDeInit USBH_MSC_ClassRequest USBH_MSC_Handle USBH_MSC_Issue_BOTReset USBH_MSC_Issue_GETMaxLUN USBH_MSC_ErrorHandle Parses interface and endpoints descriptors and configures host channels (bulk IN and bulk OUT pipes) De-initialization routine (freeing host channels) In case of MSC, this function only moves the library core state machine to the HOST_CLASS state Implements the MSC handler core state machine Issues a BOT reset class request Issues a GET_MAX_LUN class request MSC error handling MSC BOT module: The MSC Bulk-Only Transport (BOT) module implements the transport protocol for sending the SCSI commands (such as READ (10) or WRITE(10)). This module is implemented in file usbh_msc_bot.c. For details about the BOT protocol, please refer to the usb.org mass storage class document. The BOT module has the following functions: Table 8. MSC BOT module Function Description USBH_MSC_Init USBH_MSC_HandleBOTXfer Initialize BOT state machine BOT transfer state machine MSC SCSI module: The SCSI Small Computer System Interface module usb_msc_scsi.c stands on top of the BOT. It implements the set of SCSI commands required to access the flash pendrives. Doc ID Rev 1 15/31 USB host library architecture UM1021 The implemented commands are: Table 9. MSC SCSI commands Function Description USBH_MSC_Read10 USBH_MSC_Write10 USBH_MSC_TestUnitReady USBH_MSC_ReadCapacity10 USBH_MSC_ModeSense6 USBH_MSC_RequestSense Command for logical block read Command for logical block write Command for checking device status Command for requesting the device capacity Command for checking the Write-protect status of the mass storage device Command for getting error information MSC filesystem interface module The MSC filesystem interface module usbh_msc_fs_interface.c allows interfacing of filesystems with the MSC driver. This module should be ported to the selected filesystem. The current USB host library package comes with the open source, EFSL FAT filesystem support (see next section for an overview about the EFSL API). The implemented functions in the filesystem interface are: Table 10. MSC filesystem interface functions Function Description if_initinterface if_readbuf if_writebuf if_testunitready if_requestsense Allows initalization of the filesystem (for example, reading capacity of flash pendrive) Interface function for a logical page read Interface function for a logical page write Interface function for testing if unit is ready Interface function for requesting error information using SCSI command Request Sense Note: For the EFSL filesystem, the page size is fixed to 512 bytes. Flash pendrives with higher page granularity are not supported. EFSL filesystem overview The EFSL Embedded Filesystem Li
We Need Your Support
Thank you for visiting our website and your interest in our free products and services. We are nonprofit website to share and download documents. To the running of this website, we need your help to support us.

Thanks to everyone for your continued support.

No, Thanks