Emusb-Device User Guide & Reference Manual
Total Page:16
File Type:pdf, Size:1020Kb
emUSB-Device USB Device stack User Guide & Reference Manual Document: UM09001 Software Version: 3.40.0 Revision: 0 Date: March 31, 2021 A product of SEGGER Microcontroller GmbH www.segger.com 2 Disclaimer Specifications written in this document are believed to be accurate, but are not guaranteed to be entirely free of error. The information in this manual is subject to change for functional or performance improvements without notice. Please make sure your manual is the latest edition. While the information herein is assumed to be accurate, SEGGER Microcontroller GmbH (SEG- GER) assumes no responsibility for any errors or omissions. SEGGER makes and you receive no warranties or conditions, express, implied, statutory or in any communication with you. SEGGER specifically disclaims any implied warranty of merchantability or fitness for a particular purpose. Copyright notice You may not extract portions of this manual or modify the PDF file in any way without the prior written permission of SEGGER. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license. © 2010-2021 SEGGER Microcontroller GmbH, Monheim am Rhein / Germany Trademarks Names mentioned in this manual may be trademarks of their respective companies. Brand and product names are trademarks or registered trademarks of their respective holders. Contact address SEGGER Microcontroller GmbH Ecolab-Allee 5 D-40789 Monheim am Rhein Germany Tel. +49 2173-99312-0 Fax. +49 2173-99312-28 E-mail: [email protected]* Internet: www.segger.com *By sending us an email your (personal) data will automatically be processed. For further information please refer to our privacy policy which is available at https://www.segger.com/legal/privacy-policy/. emUSB-Device User Guide & Reference Manual © 2010-2021 SEGGER Microcontroller GmbH 3 Manual versions This manual describes the current software version. If you find an error in the manual or a problem in the software, please inform us and we will try to assist you as soon as possible. Contact us for further information on topics or functions that are not yet documented. As of version 3.00 the history has been reset. Older history entries can be found in older versions of this document. Print date: March 31, 2021 Software Revision Date By Description 3.40.0 0 210331 RH Add new chapter Vendor Specific Class (VSC). DFU class: • Added function USBD_DFU_AddAlternateInterface(). 3.38.0 0 210129 RH Printer class: • Added function USB_PRINTER_SetClass(). 3.36.3 0 201218 YR Update to latest software version. BULK class: • Added function USBD_BULK_PollForTX(). CDC class: 3.36.2 0 201215 RH • Added functions USBD_CDC_PollForRX(), USBD_CDC_PollForTX() and USBD_CDC_ReceivePoll(). Added new section Timeout handling Update to latest software version. 3.36.1 0 201030 YR Update to latest software version. Audio class: 3.36.0 0 201012 YR • Updated API with new function and structure names. Update to latest software version. 3.34.3 0 200825 YR Update to latest software version. 3.34.2 0 200723 YR Update to latest software version. 3.34.1 0 200610 RH Added section Synopsys DWC2 driver (DMA mode) BULK class: 3.34.0 0 200320 RH • Added function USBD_BULK_AddAlternateInterface(). 3.32.0 0 200226 RH Added CCID chapter. 3.30.0 0 200127 YR Added MIDI chapter. Update to latest software version. 3.28.1 0 191213 YR HID class: Added USBHID_Read() and USBHID_Write() functions. Printer class: 3.28.0 0 191129 YR • Added function USB_PRINTER_SetOnVendorRequest(). USB Core: • Added function USBD_GetVersion(). 3.26 0 190830 RH • Added function USBD_SetCheckAddress(). UVC class: • Added function USBD_UVC_WriteEx(). 3.24 0 190701 RH Added chapter USB Device Firmware Upgrade (DFU) BULK class: • Added function USBD_BULK_PollForRX(). • Added function USBD_BULK_ReceivePoll(). USB Core: • Added function USBD_WaitForEndOfTransferEx(). • Added function USBD_ReceivePoll(). 3.22 0 190617 RH • Added function USBD_EnableSuperSpeed(). • Added function USBD_SetWebUSBInfo(). MSD class: • Added function USBD_MSD_Poll(). Add section XHCI driver Add chapter USB Video device Class (UVC) Update to latest software version. SmartMSD was renamed to VirtualMSD. Function prefixes changed from 3.20 0 190515 YR “SMSD” to “VMSD”. HID class: Added USBD_HID_ReadReport() function. emUSB-Device User Guide & Reference Manual © 2010-2021 SEGGER Microcontroller GmbH 4 Software Revision Date By Description 3.18b 0 190304 YR Update to latest software version. Update to latest software version. Bulk Host API: • Removed USBBULK_ResetPipe() 3.18a 0 190228 YR • Added USBBULK_ResetINPipe() • Added USBBULK_ResetOUTPipe() • USBBULK_DEV_INFO received an additional member - “Speed” 3.18 0 181126 RH Update to latest software version. Update to latest software version. 3.16 0 181005 YR MTP class: • USBD_MTP_SendEvent() description updated. Added section Device driver specifics on page 663 BULK class: • Added functions USBD_BULK_ReadAsync() and USBD_BULK_WriteA- 3.14 0 180719 RH sync(). CDC class: • Added functions USBD_CDC_ReadAsync() and USBD_CDC_WriteA- sync(). USB Core: • Added function USBD_RemoveOnEvent(). • Removed functions USBD_SetLogFunc() and USBD_SetWarnFunc(). 3.12 0 180504 RH Audio class: • Added function USBD_AUDIO_Read_Task(). • Added function USBD_AUDIO_Write_Task(). BULK class: • Added function USBD_BULK_Add_Ex(). 3.10 0 180322 RH Update to latest software version. Added Audio chapter. USB Core: 3.08 0 180212 RH • Added function USBD_RegisterSCHook(). • Added function USBD_AddEPEx(). 3.06e 0 180112 RH Update to latest software version. 3.06d 0 171219 YR Update to latest software version. USB Core: 3.06c 0 171204 RH • Added I/O functions. Update to latest software version. 3.06b 0 171013 YR Corrected USBD_WriteEP0FromISR name (was USB__WriteEP0FromISR). Printer class: • Added function USB_PRINTER_ConfigIRQProcessing(). • Added function USB_PRINTER_TaskEx(). 3.06 0 170915 RH USB Core: • Added USBD_SetCacheConfig(). Chapter “Getting started” revised. Update to latest software version. 3.04 0 170724 YR Added chapter “emUSB-Device-IP” 3.02q 0 170717 YR Update to latest software version. 3.02p 0 170714 RH Update to latest software version. Chapter Combining USB components: 3.02o 1 170710 YR • Added information on the MSD+MTP combination feature. Added Chapter “Profiling with SystemView”. Major revision of the manual. 3.02o 0 170701 RH • Manual converted to text processor emDoc. 3.02n 0 170612 SR Update to latest software version. 3.02m 0 170608 RH Update to latest software version. 3.02l 0 170602 SR Update to latest software version. 3.02k 0 170410 RH Function USBD_AddEP(): Parameter ’Interval’ changed. 3.02j 0 170301 RH Update to latest software version. 3.02i 0 170126 SR Update to latest software version. emUSB-Device User Guide & Reference Manual © 2010-2021 SEGGER Microcontroller GmbH 5 Software Revision Date By Description 3.02h 0 170126 SR Update to latest software version. 3.02g 0 170123 SR Update to latest software version. 3.02f 0 170104 RH Update to latest software version. 3.02e 0 161215 RH Update to latest software version. 3.02d 0 161118 RH Update to latest software version. 3.02c 0 161103 RH Update to latest software version. Chapter VirtualMSD: 3.02b 0 161028 RH • Renamed functions according to the emUSB V3 conventions. 3.02a 10 161018 RH Update to latest software version. Chapter CDC: • Updated Overview - Added Windows 10 Support. • Updated Installing the driver. Section verification combined with In- 3.02 9 161007 SR stalling driver. • Updated section The .inf file • Added new section: Signing the package • Testing communication to the USB device updated. Chapter CDC Data structures: • Removed CTS from USB_CDC_SERIAL_STATE. Chapter BULK communication: • Removed description of the Segger USB driver(not necessary any more) • BULK host API and sample applications support for Linux and MacOSX 3.02 8 160930 RH added. • Added new function USBD_BULK_SetMSDescInfo(). • Added new function USBBULK_GetDevInfoByIdx(). • Removed description of deprecated host API functions. Chapter VirtualMSD: • Added memory usage calculation. Many minor corrections. Update to latest software version. Chapter Target OS Interface: 3.00g 7 160822 RH • New advanced OS layer interface. Chapter Mass Storage Device Class (MSD): • Added new function USBD_MSD_RequestRefresh() Update to latest software version. Chapter VirtualMSD: 3.00f 6 160720 YR • Changed function prefix to VMSD. • Removed obsolete functions. 3.00e 5 160708 RH Update to latest software version. 3.00d 4 160608 YR Update to latest software version. Update to latest software version. 3.00c 3 160523 YR Chapter Bulk communication: • Added paragraph “Writing your own host driver”. 3.00b 2 160427 YR Update to latest software version. Chapter USB Core functions: • Updated prototype for USBD_SetMaxPower. Chapter HID: 3.00a 1 160415 SR • Added new function for Setting a callback for SET_REPORT. Chapter Debugging: • Changed all prototypes from USB_* to USBD_*. 3.00 0 160212 YR Initial Version emUSB-Device User Guide & Reference Manual © 2010-2021 SEGGER Microcontroller GmbH 6 emUSB-Device User Guide & Reference Manual © 2010-2021 SEGGER Microcontroller GmbH 7 About this document Assumptions This document assumes that you already have a solid knowledge of the following: • The software tools used for building your application (assembler, linker, C compiler). • The C programming language. • The target processor. • DOS command line. If you feel that your knowledge of C is not sufficient,