emUSB-Device USB Device stack User Guide & Reference Manual Document: UM09001 Software Version: 3.12 Revision: 0 Date: May 4, 2018 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 (SEGGER) 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. (c) 2010-2018 SEGGER Microcontroller GmbH, Hilden / 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 In den Weiden 11 D-40721 Hilden Germany Tel. Fax. E-mail: Internet: +49 2103-2878-0 +49 2103-2878-28 support@segger.com www.segger.com emUSB-Device User Guide & Reference Manual (c) 2010-2018 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: May 4, 2018 Software Revision 3.12 0 Date 180504 By Description RH USB Core: * Added function USBD_RemoveOnEvent(). * Removed functions USBD_SetLogFunc() and USBD_SetWarnFunc(). Audio class: * Added function USBD_AUDIO_Read_Task(). * Added function USBD_AUDIO_Write_Task(). 3.10 0 180322 RH BULK class: * Added function USBD_BULK_Add_Ex(). Update to latest software version. Added Audio chapter. 3.08 0 180212 RH USB Core: * 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. 3.06c 0 171204 RH USB Core: * Added I/O functions. 3.06b 0 171013 YR Update to latest software version. Corrected USBD_WriteEP0FromISR name (was USB__WriteEP0FromISR). 3.06 0 170915 RH Printer class: * Added function USB_PRINTER_ConfigIRQProcessing(). * Added function USB_PRINTER_TaskEx(). USB Core: * Added USBD_SetCacheConfig(). Chapter "Getting started" revised. 3.04 0 170724 YR Update to latest software version. 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. 3.02o 1 170710 YR Chapter Combining USB components: * Added information on the MSD+MTP combination feature. Added Chapter "Profiling with SystemView". 3.02o 0 170701 RH Major revision of the manual. * 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. 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. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 4 Software Revision Date By Description 3.02b 0 161028 RH Chapter SmartMSD: * Renamed functions according to the emUSB V3 conventions. 3.02a 10 161018 RH Update to latest software version. SR Chapter CDC: * Updated Overview - Added Windows 10 Support. * Updated Installing the driver. Section verification combined with Installing driver. * Updated section The .inf file * Added new section: Signing the package * Testing communication to the USB device updated. RH 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 added. * Added new function USBD_BULK_SetMSDescInfo(). * Added new function USBBULK_GetDevInfoByIdx(). * Removed description of deprecated host API functions. Chapter SmartMSD: * Added memory usage calculation. Many minor corrections. RH Update to latest software version. Chapter Target OS Interface: * New advanced OS layer interface. Chapter Mass Storage Device Class (MSD): * Added new function USBD_MSD_RequestRefresh() 3.02 3.02 3.00g 9 8 7 161007 160930 160822 3.00f 6 160720 YR Update to latest software version. Chapter SmartMSD: * Changed function prefix to SMSD. * Removed obsolete functions. 3.00e 5 160708 RH Update to latest software version. 3.00d 4 160608 YR Update to latest software version. 3.00c 3 160523 YR Update to latest software version. Chapter Bulk communication: * Added paragraph "Writing your own host driver". 3.00b 2 160427 YR Update to latest software version. 3.00a 1 160415 SR Chapter USB Core functions: * Updated prototype for USBD_SetMaxPower. Chapter HID: * 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 (c) 2010-2018 SEGGER Microcontroller GmbH 5 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, we recommend The C Programming Language by Kernighan and Richie (ISBN 0--13--1103628), which describes the standard in C programming and, in newer editions, also covers the ANSI C standard. How to use this manual This manual explains all the functions and macros that the product offers. It assumes you have a working knowledge of the C language. Knowledge of assembly programming is not required. Typographic conventions for syntax This manual uses the following typographic conventions: Style Used for Body Body text. Keyword Text that you enter at the command prompt or that appears on the display (that is system functions, file- or pathnames). Parameter Parameters in API functions. Sample Sample code in program examples. Sample comment Comments in program examples. Reference Reference to chapters, sections, tables and figures or other documents. GUIElement Buttons, dialog boxes, menu names, menu commands. Emphasis Very important sections. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 6 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 7 Table of contents 1 Introduction ..................................................................................................................19 1.1 1.2 1.3 1.4 1.5 2 Overview .....................................................................................................19 emUSB-Device features ................................................................................ 20 emUSB-Device components ........................................................................... 21 1.3.1 emUSB-Device-Bulk ...........................................................................21 1.3.2 emUSB-Device-MSD .......................................................................... 21 1.3.2.1 Purpose of emUSB-Device-MSD ................................................21 1.3.2.2 Typical applications .................................................................22 1.3.2.3 emUSB-Device-MSD features ................................................... 22 1.3.2.4 How does it work? ................................................................. 22 1.3.3 emUSB-Device IP-over-USB ................................................................23 1.3.3.1 Typical applications .................................................................23 1.3.4 emUSB-Device-SmartMSD .................................................................. 23 1.3.4.1 Typical applications .................................................................23 1.3.5 emUSB-Device-CDC ........................................................................... 23 1.3.5.1 Typical applications .................................................................23 1.3.6 emUSB-Device-HID ........................................................................... 23 1.3.6.1 Typical applications .................................................................23 1.3.7 emUSB-Device-MTP ........................................................................... 24 1.3.7.1 Typical applications .................................................................24 1.3.8 emUSB-Device-Printer ........................................................................24 1.3.8.1 Typical applications .................................................................24 1.3.9 emUSB-Device-RNDIS ........................................................................24 1.3.9.1 Typical applications .................................................................24 1.3.10 emUSB-Device-CDC-ECM .................................................................. 25 1.3.10.1 Typical applications ............................................................... 25 Requirements .............................................................................................. 26 1.4.1 Target system ...................................................................................26 1.4.2 Development environment (compiler) .................................................. 26 File structure ............................................................................................... 27 Background information .............................................................................................. 28 2.1 2.2 USB ............................................................................................................29 2.1.1 Short Overview ................................................................................. 29 2.1.2 Important USB Standard Versions ....................................................... 29 2.1.3 USB System Architecture ................................................................... 30 2.1.4 Transfer Types .................................................................................. 32 2.1.5 Setup phase / Enumeration ................................................................ 32 2.1.6 Product / Vendor IDs ......................................................................... 32 Predefined device classes .............................................................................. 33 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 8 2.3 2.4 3 Getting started ............................................................................................................ 36 3.1 3.2 3.3 4 USB hardware analyzers ............................................................................... 34 References .................................................................................................. 35 How to setup your target system ...................................................................37 3.1.1 Take a running project .......................................................................37 3.1.2 Add emUSB-Device files .....................................................................37 3.1.3 Configuring debugging output ............................................................. 37 3.1.4 Add hardware dependent configuration ................................................ 38 3.1.5 Prepare and run the application .......................................................... 38 Updating emUSB-Device ............................................................................... 40 emUSB-Device Configuration ......................................................................... 41 3.3.1 General emUSB-Device configuration ................................................... 42 3.3.1.1 USB_DEVICE_INFO .................................................................42 3.3.2 Additional required configuration functions for emUSB-MSD .................... 42 3.3.3 Descriptors ....................................................................................... 43 USB Core ....................................................................................................................44 4.1 4.2 Overview .....................................................................................................45 Target API ................................................................................................... 46 4.2.1 USB basic functions ...........................................................................48 4.2.1.1 USBD_GetState() ................................................................... 48 4.2.1.2 USBD_Init() ...........................................................................49 4.2.1.3 USBD_IsConfigured() .............................................................. 50 4.2.1.4 USBD_Start() ........................................................................ 51 4.2.1.5 USBD_Stop() ......................................................................... 52 4.2.1.6 USBD_DeInit() ....................................................................... 53 4.2.2 USB configuration functions ................................................................54 4.2.2.1 USBD_AddDriver() ..................................................................54 4.2.2.2 USBD_SetISRMgmFuncs() ....................................................... 55 4.2.2.3 USBD_SetAttachFunc() ........................................................... 56 4.2.2.4 USBD_AddEP() .......................................................................57 4.2.2.5 USBD_AddEPEx() ................................................................... 58 4.2.2.6 USBD_SetDeviceInfo() ............................................................ 59 4.2.2.7 USBD_SetClassRequestHook() ..................................................60 4.2.2.8 USBD_SetVendorRequestHook() ............................................... 61 4.2.2.9 USBD_SetIsSelfPowered() ....................................................... 62 4.2.2.10 USBD_SetMaxPower() ........................................................... 63 4.2.2.11 USBD_SetOnEvent() ............................................................. 64 4.2.2.12 USBD_RemoveOnEvent() ....................................................... 66 4.2.2.13 USBD_SetOnRxEP0() ............................................................ 67 4.2.2.14 USBD_SetOnSetupHook() ...................................................... 68 4.2.2.15 USBD_WriteEP0FromISR() ..................................................... 69 4.2.2.16 USBD_EnableIAD() ............................................................... 70 4.2.2.17 USBD_SetCacheConfig() ........................................................ 71 4.2.2.18 USBD_RegisterSCHook() ........................................................72 4.2.3 USB I/O functions ............................................................................. 73 4.2.3.1 USBD_Read() .........................................................................73 4.2.3.2 USBD_ReadOverlapped() ......................................................... 74 4.2.3.3 USBD_Receive() ..................................................................... 75 4.2.3.4 USBD_Write() ........................................................................ 76 4.2.3.5 USBD_CancelIO() ................................................................... 77 4.2.3.6 USBD_WaitForEndOfTransfer() ..................................................78 4.2.3.7 USBD_WaitForTXReady() ......................................................... 79 4.2.3.8 USBD_GetNumBytesInBuffer() ................................................. 80 4.2.3.9 USBD_GetNumBytesRemToRead() ............................................ 81 4.2.3.10 USBD_GetNumBytesRemToWrite() .......................................... 82 4.2.3.11 USBD_StallEP() .................................................................... 83 4.2.4 USB Remote wakeup functions ............................................................84 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 9 4.2.5 5 4.2.4.1 USBD_SetAllowRemoteWakeUp() .............................................. 85 Data structures ................................................................................. 86 4.2.5.1 USB_ADD_EP_INFO ................................................................ 86 4.2.5.2 SEGGER_CACHE_CONFIG ........................................................ 87 Bulk communication ....................................................................................................88 5.1 5.2 5.3 5.4 5.5 Generic bulk stack ....................................................................................... 89 Requirements for the Host (PC) ..................................................................... 90 5.2.1 Windows .......................................................................................... 90 5.2.2 Linux ............................................................................................... 90 5.2.3 macOS .............................................................................................90 Example application ......................................................................................91 5.3.1 Running the example applications ....................................................... 92 5.3.2 Compiling the PC example application ..................................................93 5.3.2.1 Windows ............................................................................... 93 5.3.2.2 Linux .................................................................................... 93 5.3.2.3 macOS ..................................................................................93 Target API ................................................................................................... 94 5.4.1 Target interface function list ............................................................... 94 5.4.2 USB-Bulk functions ............................................................................96 5.4.2.1 USBD_BULK_Add() ................................................................. 96 5.4.2.2 USBD_BULK_Add_Ex() ............................................................ 97 5.4.2.3 USBD_BULK_SetMSDescInfo() ................................................. 98 5.4.2.4 USBD_BULK_CancelRead() ...................................................... 99 5.4.2.5 USBD_BULK_CancelWrite() .................................................... 100 5.4.2.6 USBD_BULK_GetNumBytesInBuffer() ...................................... 101 5.4.2.7 USBD_BULK_GetNumBytesRemToRead() ..................................102 5.4.2.8 USBD_BULK_GetNumBytesRemToWrite() ................................. 103 5.4.2.9 USBD_BULK_Read() ..............................................................104 5.4.2.10 USBD_BULK_ReadOverlapped() ............................................ 105 5.4.2.11 USBD_BULK_Receive() ........................................................ 106 5.4.2.12 USBD_BULK_SetContinuousReadMode() .................................107 5.4.2.13 USBD_BULK_SetOnRXEvent() ............................................... 108 5.4.2.14 USBD_BULK_SetOnTXEvent() ............................................... 110 5.4.2.15 USBD_BULK_TxIsPending() .................................................. 112 5.4.2.16 USBD_BULK_WaitForRX() .....................................................113 5.4.2.17 USBD_BULK_WaitForTX() ..................................................... 114 5.4.2.18 USBD_BULK_WaitForTXReady() ............................................ 115 5.4.2.19 USBD_BULK_Write() ............................................................116 5.4.2.20 USBD_BULK_WriteEx() ........................................................ 118 5.4.3 Data structures ............................................................................... 119 5.4.3.1 USB_BULK_INIT_DATA .......................................................... 119 5.4.3.2 USB_BULK_INIT_DATA_EX ..................................................... 120 5.4.4 Multithreading ................................................................................. 121 Host API ................................................................................................... 122 5.5.1 Bulk Host API list ............................................................................ 123 5.5.2 USB-Bulk Basic functions ..................................................................125 5.5.2.1 USBBULK_Init() ....................................................................125 5.5.2.2 USBBULK_Exit() ................................................................... 126 5.5.2.3 USBBULK_AddAllowedDeviceItem() ......................................... 127 5.5.2.4 USBBULK_GetNumAvailableDevices() ...................................... 128 5.5.2.5 USBBULK_Open() ................................................................. 129 5.5.2.6 USBBULK_Close() ................................................................. 130 5.5.3 USB-Bulk direct input/output functions ...............................................131 5.5.3.1 USBBULK_Read() ..................................................................131 5.5.3.2 USBBULK_ReadTimed() ......................................................... 132 5.5.3.3 USBBULK_Write() ................................................................. 133 5.5.3.4 USBBULK_WriteTimed() ......................................................... 134 5.5.3.5 USBBULK_CancelRead() ........................................................ 135 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 10 5.5.3.6 USBBULK_FlushRx() ..............................................................136 USB-Bulk Control functions ............................................................... 137 5.5.4.1 USBBULK_SetMode() .............................................................137 5.5.4.2 USBBULK_GetMode() ............................................................ 138 5.5.4.3 USBBULK_SetReadTimeout() .................................................. 139 5.5.4.4 USBBULK_SetWriteTimeout() ..................................................140 5.5.4.5 USBBULK_ResetPipe() ........................................................... 141 5.5.4.6 USBBULK_ResetDevice() ........................................................142 5.5.5 USB-Bulk general GET functions ........................................................ 143 5.5.5.1 USBBULK_GetVersion() ......................................................... 143 5.5.5.2 USBBULK_GetDevInfo() .........................................................144 5.5.5.3 USBBULK_GetDevInfoByIdx() .................................................145 5.5.5.4 USBBULK_GetUSBId() ........................................................... 146 5.5.5.5 USBBULK_GetProductName() ................................................. 147 5.5.5.6 USBBULK_GetVendorName() .................................................. 148 5.5.5.7 USBBULK_GetSN() ................................................................149 5.5.5.8 USBBULK_GetConfigDescriptor() .............................................150 5.5.4 6 Mass Storage Device Class (MSD) .......................................................................... 151 6.1 6.2 6.3 6.4 Overview ................................................................................................... 152 MSD Configuration ......................................................................................153 6.2.1 Initial configuration ..........................................................................153 6.2.2 Final configuration ........................................................................... 153 6.2.3 MSD class specific configuration functions ...........................................153 6.2.4 Running the example application ....................................................... 153 6.2.4.1 MSD_Start_StorageRAM.c in detail ..........................................154 Target API ................................................................................................. 155 6.3.1 API functions .................................................................................. 157 6.3.1.1 USBD_MSD_Add() ................................................................ 157 6.3.1.2 USBD_MSD_AddUnit() ...........................................................158 6.3.1.3 USBD_MSD_AddCDRom() ...................................................... 159 6.3.1.4 USBD_MSD_SetPreventAllowRemovalHook() ............................ 160 6.3.1.5 USBD_MSD_SetPreventAllowRemovalHookEx() ......................... 161 6.3.1.6 USBD_MSD_SetReadWriteHook() ............................................ 162 6.3.1.7 USBD_MSD_Task() ................................................................163 6.3.1.8 USBD_MSD_SetStartStopUnitHook() ....................................... 164 6.3.2 Extended API functions .................................................................... 165 6.3.2.1 USBD_MSD_Connect() .......................................................... 165 6.3.2.2 USBD_MSD_Disconnect() .......................................................166 6.3.2.3 USBD_MSD_RequestDisconnect() ............................................167 6.3.2.4 USBD_MSD_RequestRefresh() ................................................ 168 6.3.2.5 USBD_MSD_UpdateWriteProtect() ........................................... 169 6.3.2.6 USBD_MSD_WaitForDisconnection() ........................................ 170 6.3.3 Data structures ............................................................................... 171 6.3.3.1 USB_MSD_INIT_DATA ........................................................... 171 6.3.3.2 USB_MSD_INFO ................................................................... 172 6.3.3.3 USB_MSD_INST_DATA .......................................................... 173 6.3.3.4 USB_MSD_LUN_INFO ............................................................ 174 6.3.3.5 PREVENT_ALLOW_REMOVAL_HOOK .........................................175 6.3.3.6 PREVENT_ALLOW_REMOVAL_HOOK_EX ................................... 176 6.3.3.7 READ_WRITE_HOOK ............................................................. 177 6.3.3.8 USB_MSD_INST_DATA_DRIVER .............................................. 178 6.3.3.9 USB_MSD_STORAGE_API ...................................................... 180 6.3.3.10 START_STOP_UNIT_HOOK ................................................... 181 MSD Storage Driver ....................................................................................182 6.4.1 General information ......................................................................... 182 6.4.1.1 Supported storage types ....................................................... 182 6.4.1.2 Storage drivers supplied with this release ................................ 182 6.4.2 Interface function list .......................................................................182 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 11 6.4.3 7 Smart Mass Storage Component (SmartMSD) ........................................................ 191 7.1 7.2 7.3 8 USB_MSD_STORAGE_API in detail ..................................................... 183 6.4.3.1 USB_MSD_STORAGE_INIT ..................................................... 183 6.4.3.2 USB_MSD_STORAGE_GETINFO ...............................................184 6.4.3.3 USB_MSD_STORAGE_GETREADBUFFER ................................... 185 6.4.3.4 USB_MSD_STORAGE_READ ....................................................186 6.4.3.5 USB_MSD_STORAGE_GETWRITEBUFFER ..................................187 6.4.3.6 USB_MSD_STORAGE_WRITE .................................................. 188 6.4.3.7 USB_MSD_STORAGE_MEDIUMISPRESENT ................................ 189 6.4.3.8 USB_MSD_STORAGE_DEINIT ................................................. 190 Overview ................................................................................................... 192 Configuration ............................................................................................. 193 7.2.1 Initial configuration ..........................................................................193 7.2.2 Final configuration ........................................................................... 193 7.2.3 Class specific configuration functions ................................................. 193 7.2.3.1 USB_SMSD_X_Config() ......................................................... 194 7.2.4 Running the example application ....................................................... 194 7.2.5 Calculation of RAM memory usage for SmartMSD ................................ 195 Target API ................................................................................................. 197 7.3.1 API functions .................................................................................. 198 7.3.1.1 USBD_SMSD_Add() .............................................................. 198 7.3.1.2 USB_SMSD_X_Config() ......................................................... 199 7.3.1.3 USBD_SMSD_AssignMemory() ................................................200 7.3.1.4 USBD_SMSD_SetUserAPI() .................................................... 201 7.3.1.5 USBD_SMSD_SetNumRootDirSectors() .................................... 202 7.3.1.6 USBD_SMSD_SetVolumeInfo() ............................................... 203 7.3.1.7 USBD_SMSD_AddConstFiles() ................................................ 204 7.3.1.8 USBD_SMSD_SetNumSectors() .............................................. 205 7.3.1.9 USBD_SMSD_SetSectorsPerCluster() .......................................206 7.3.2 Data structures ............................................................................... 207 7.3.2.1 USB_SMSD_CONST_FILE ....................................................... 207 7.3.2.2 USB_SMSD_USER_FUNC_API ................................................. 208 7.3.2.3 USB_SMSD_FILE_INFO ..........................................................209 7.3.2.4 USB_SMSD_DIR_ENTRY_SHORT ............................................. 210 7.3.3 Function definitions ..........................................................................212 7.3.3.1 USB_SMSD_ON_READ_FUNC ................................................. 212 7.3.3.2 USB_SMSD_ON_WRITE_FUNC ................................................ 213 7.3.3.3 USB_SMSD_MEM_ALLOC ....................................................... 214 7.3.3.4 USB_SMSD_MEM_FREE ......................................................... 215 Media Transfer Protocol Class (MTP) ...................................................................... 216 8.1 8.2 8.3 8.4 Overview ................................................................................................... 217 8.1.1 Getting access to files ......................................................................218 8.1.2 Additional information ...................................................................... 220 Configuration ............................................................................................. 221 8.2.1 Initial configuration ..........................................................................221 8.2.2 Final configuration ........................................................................... 221 8.2.3 Class specific configuration ............................................................... 221 8.2.4 Compile time configuration ............................................................... 221 Running the sample application ....................................................................223 8.3.1 USB_MTP_Start.c in detail ................................................................ 223 Target API ................................................................................................. 225 8.4.1 API functions .................................................................................. 226 8.4.1.1 USBD_MTP_Add() ................................................................. 226 8.4.1.2 USBD_MTP_AddStorage() ...................................................... 227 8.4.1.3 USBD_MTP_Task() ................................................................ 228 8.4.1.4 USBD_MTP_SendEvent() ....................................................... 229 8.4.2 Data structures ............................................................................... 231 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 12 8.5 9 8.4.2.1 USB_MTP_FILE_INFO ............................................................ 231 8.4.2.2 USB_MTP_INIT_DATA ............................................................ 232 8.4.2.3 USB_MTP_INFO .................................................................... 233 8.4.2.4 USB_MTP_INST_DATA ........................................................... 234 8.4.2.5 USB_MTP_INST_DATA_DRIVER ...............................................235 8.4.2.6 USB_MTP_STORAGE_API ....................................................... 236 8.4.2.7 USB_MTP_STORAGE_INFO ..................................................... 238 8.4.3 Enums ........................................................................................... 239 8.4.3.1 USB_MTP_EVENT ..................................................................239 MTP Storage Driver .................................................................................... 241 8.5.1 General information ......................................................................... 241 8.5.2 Interface function list .......................................................................241 8.5.3 USB_MTP_STORAGE_API in detail ......................................................242 8.5.3.1 USB_MTP_STORAGE_INIT ......................................................242 8.5.3.2 USB_MTP_STORAGE_GET_INFO ..............................................243 8.5.3.3 USB_MTP_STORAGE_FIND_FIRST_FILE ................................... 244 8.5.3.4 USB_MTP_STORAGE_FIND_NEXT_FILE .................................... 245 8.5.3.5 USB_MTP_STORAGE_OPEN_FILE ............................................ 246 8.5.3.6 USB_MTP_STORAGE_CREATE_FILE ......................................... 247 8.5.3.7 USB_MTP_STORAGE_READ_FROM_FILE ...................................248 8.5.3.8 USB_MTP_STORAGE_WRITE_TO_FILE ..................................... 249 8.5.3.9 USB_MTP_STORAGE_CLOSE_FILE ........................................... 250 8.5.3.10 USB_MTP_STORAGE_REMOVE_FILE .......................................251 8.5.3.11 USB_MTP_STORAGE_CREATE_DIR ........................................ 252 8.5.3.12 USB_MTP_STORAGE_REMOVE_DIR ....................................... 253 8.5.3.13 USB_MTP_STORAGE_FORMAT ...............................................254 8.5.3.14 USB_MTP_STORAGE_RENAME_FILE .......................................255 8.5.3.15 USB_MTP_STORAGE_DEINIT ................................................ 256 8.5.3.16 USB_MTP_STORAGE_GET_FILE_ATTRIBUTES .......................... 257 8.5.3.17 USB_MTP_STORAGE_MODIFY_FILE_ATTRIBUTES .................... 258 8.5.3.18 USB_MTP_STORAGE_GET_FILE_CREATION_TIME .................... 259 8.5.3.19 USB_MTP_STORAGE_GET_FILELAST_WRITE_TIME .................. 260 8.5.3.20 USB_MTP_STORAGE_GET_FILE_ID ........................................261 8.5.3.21 USB_MTP_STORAGE_GET_FILE_SIZE .................................... 262 Communication Device Class (CDC) ........................................................................263 9.1 9.2 9.3 9.4 Overview ................................................................................................... 264 9.1.1 Configuration .................................................................................. 264 The example application ..............................................................................265 Installing the driver .................................................................................... 266 9.3.1 The .inf file ..................................................................................... 270 9.3.2 Signing the package ........................................................................ 271 9.3.3 Testing communication to the USB device ...........................................271 Target API ................................................................................................. 274 9.4.1 Interface function list .......................................................................274 9.4.1.1 USBD_CDC_Add() .................................................................276 9.4.1.2 USBD_CDC_CancelRead() ...................................................... 277 9.4.1.3 USBD_CDC_CancelWrite() ......................................................278 9.4.1.4 USBD_CDC_Read() ............................................................... 279 9.4.1.5 USBD_CDC_ReadOverlapped() ............................................... 280 9.4.1.6 USBD_CDC_Receive() ........................................................... 281 9.4.1.7 USBD_CDC_SetOnBreak() ......................................................282 9.4.1.8 USBD_CDC_SetOnLineCoding() .............................................. 283 9.4.1.9 USBD_CDC_SetOnControlLineState() .......................................284 9.4.1.10 USBD_CDC_SetOnRXEvent() ................................................ 285 9.4.1.11 USBD_CDC_SetOnTXEvent() ................................................ 287 9.4.1.12 USBD_CDC_UpdateSerialState() ........................................... 289 9.4.1.13 USBD_CDC_Write() ............................................................. 290 9.4.1.14 USBD_CDC_WaitForRX() ...................................................... 291 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 13 9.4.1.15 USBD_CDC_WaitForTX() ...................................................... 292 9.4.1.16 USBD_CDC_WaitForTXReady() ..............................................293 9.4.1.17 USBD_CDC_WriteSerialState() .............................................. 294 9.4.1.18 USBD_CDC_GetNumBytesRemToRead() ................................. 295 9.4.1.19 USBD_CDC_GetNumBytesRemToWrite() ................................. 296 9.4.1.20 USBD_CDC_GetNumBytesInBuffer() ...................................... 297 9.4.2 Data structures ............................................................................... 298 9.4.2.1 USB_CDC_INIT_DATA ............................................................298 9.4.2.2 USB_CDC_LINE_CODING ....................................................... 299 9.4.2.3 USB_CDC_SERIAL_STATE ...................................................... 300 9.4.2.4 USB_CDC_CONTROL_LINE_STATE ...........................................301 9.4.3 Multithreading ................................................................................. 302 10 Human Interface Device Class (HID) ..................................................................... 303 10.1 10.2 10.3 10.4 10.5 10.6 Overview ................................................................................................. 304 10.1.1 Further reading ............................................................................. 304 10.1.2 Categories .................................................................................... 304 10.1.2.1 True HIDs .......................................................................... 304 10.1.2.2 Vendor specific HIDs ........................................................... 304 Background information .............................................................................306 10.2.1 HID descriptors ............................................................................. 306 10.2.1.1 HID descriptor ....................................................................306 10.2.1.2 Report descriptor ................................................................ 306 10.2.1.3 Physical descriptor .............................................................. 307 Configuration ........................................................................................... 308 10.3.1 Initial configuration ........................................................................ 308 10.3.2 Final configuration ......................................................................... 308 Example application .................................................................................. 309 10.4.1 USB_HID_Mouse.c ......................................................................... 309 10.4.1.1 Running the example .......................................................... 309 10.4.2 USB_HID_Echo1.c ..........................................................................309 10.4.2.1 Running the example .......................................................... 310 10.4.2.2 Compiling the PC example application ................................... 311 Target API ............................................................................................... 312 10.5.1 Target interface function list ............................................................313 10.5.2 HID Target API functions ................................................................ 314 10.5.2.1 USBD_HID_Add() ................................................................314 10.5.2.2 USBD_HID_GetNumBytesInBuffer() .......................................315 10.5.2.3 USBD_HID_GetNumBytesRemToRead() .................................. 316 10.5.2.4 USBD_HID_GetNumBytesRemToWrite() ................................. 317 10.5.2.5 USBD_HID_Read() .............................................................. 318 10.5.2.6 USBD_HID_ReadOverlapped() .............................................. 319 10.5.2.7 USBD_HID_WaitForRX() .......................................................320 10.5.2.8 USBD_HID_WaitForTX() ....................................................... 321 10.5.2.9 USBD_HID_Write() ..............................................................322 10.5.2.10 USBD_HID_SetOnGetReportRequest() ..................................323 10.5.2.11 USBD_HID_SetOnSetReportRequest() .................................. 324 10.5.3 Data structures ............................................................................. 325 10.5.3.1 USB_HID_INIT_DATA .......................................................... 325 10.5.4 Type definitions ............................................................................. 327 10.5.4.1 USB_HID_ON_GETREPORT_REQUEST_FUNC ........................... 327 10.5.4.2 USB_HID_ON_SETREPORT_REQUEST_FUNC ........................... 328 Host API ..................................................................................................329 10.6.1 Host API function list ..................................................................... 330 10.6.2 HID Host API functions ...................................................................331 10.6.2.1 USBHID_Close() ................................................................. 331 10.6.2.2 USBHID_Open() ................................................................. 332 10.6.2.3 USBHID_Init() .................................................................... 333 10.6.2.4 USBHID_Exit() ................................................................... 334 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 14 10.6.2.5 10.6.2.6 10.6.2.7 10.6.2.8 10.6.2.9 10.6.2.10 10.6.2.11 10.6.2.12 11 USBHID_GetNumAvailableDevices() .......................................335 USBHID_GetProductName() ................................................. 336 USBHID_GetInputReportSize() ..............................................337 USBHID_GetOutputReportSize() ............................................338 USBHID_GetProductId() .......................................................339 USBHID_GetVendorId() ......................................................340 USBHID_RefreshList() ........................................................341 USBHID_SetVendorPage() .................................................. 342 Printer Class ........................................................................................................... 343 11.1 Overview ................................................................................................. 344 11.1.1 Configuration ................................................................................ 344 11.2 The example application ............................................................................ 345 11.3 Target API ............................................................................................... 347 11.3.1 Interface function list ..................................................................... 347 11.3.2 API functions ................................................................................ 348 11.3.2.1 USB_PRINTER_Init() ........................................................... 348 11.3.2.2 USB_PRINTER_Task() .......................................................... 349 11.3.2.3 USB_PRINTER_TaskEx() .......................................................350 11.3.2.4 USB_PRINTER_ConfigIRQProcessing() ....................................351 11.3.2.5 USB_PRINTER_Read() ......................................................... 352 11.3.2.6 USB_PRINTER_ReadTimed() ................................................. 353 11.3.2.7 USB_PRINTER_Receive() ......................................................354 11.3.2.8 USB_PRINTER_ReceiveTimed() ............................................. 355 11.3.2.9 USB_PRINTER_Write() ......................................................... 356 11.3.2.10 USB_PRINTER_WriteTimed() ............................................... 357 11.3.2.11 USB_PRINTER_API ............................................................ 358 11.4 Printer API ...............................................................................................359 11.4.1 General information ....................................................................... 359 11.4.2 USB_PRINTER_API in detail ............................................................ 360 11.4.2.1 USB_PRINTER_GET_DEVICE_ID_STRING ............................... 360 11.4.2.2 USB_PRINTER_ON_DATA_RECEIVED ......................................361 11.4.2.3 USB_PRINTER_GET_HAS_NO_ERROR .................................... 362 11.4.2.4 USB_PRINTER_GET_IS_SELECTED ........................................ 363 11.4.2.5 USB_PRINTER_GET_IS_PAPER_EMPTY ................................... 364 11.4.2.6 USB_PRINTER_ON_RESET ....................................................365 12 IP-over-USB (IP) ..................................................................................................... 366 12.1 12.2 12.3 12.4 12.5 12.6 13 Overview ................................................................................................. 367 Using only RNDIS or CDC-ECM ...................................................................368 12.2.1 Working with emUSB-Device-IP ....................................................... 368 Configuration ........................................................................................... 370 12.3.1 Initial Configuration ....................................................................... 370 12.3.2 Final configuration ......................................................................... 370 12.3.3 Class specific configuration ............................................................. 370 Running the sample application .................................................................. 371 12.4.1 IP_Config_IP_over_USB.c in detail ................................................... 371 emUSB-Device-IP + embOS/IP as a "USB Webserver" ................................... 374 Target API ............................................................................................... 375 12.6.1 API functions ................................................................................ 376 12.6.1.1 USBD_IP_Add() .................................................................. 376 12.6.1.2 USBD_IP_Task() ................................................................. 377 12.6.2 Data structures ............................................................................. 378 12.6.2.1 USB_IP_INIT_DATA ............................................................. 378 Remote NDIS (RNDIS) ........................................................................................... 379 13.1 Overview ................................................................................................. 380 13.1.1 Working with RNDIS ...................................................................... 380 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 15 13.2 13.3 13.4 13.5 13.6 14 13.1.2 Additional information .................................................................... 380 Configuration ........................................................................................... 381 13.2.1 Initial Configuration ....................................................................... 381 13.2.2 Final configuration ......................................................................... 381 13.2.3 Class specific configuration ............................................................. 381 Running the sample application .................................................................. 382 13.3.1 IP_Config_RNDIS.c in detail ............................................................ 382 RNDIS + embOS/IP as a "USB Webserver" .................................................. 384 Target API ............................................................................................... 385 13.5.1 API functions ................................................................................ 386 13.5.1.1 USBD_RNDIS_Add() ............................................................386 13.5.1.2 USBD_RNDIS_Task() ........................................................... 387 13.5.1.3 USBD_RNDIS_SetDeviceInfo() ..............................................388 13.5.2 Data structures ............................................................................. 389 13.5.2.1 USB_RNDIS_INIT_DATA .......................................................389 13.5.2.2 USB_RNDIS_DEVICE_INFO .................................................. 390 13.5.3 Driver interface ............................................................................. 391 13.5.3.1 USB_IP_NI_DRIVER_API ...................................................... 391 13.5.3.2 USB_IP_NI_DRIVER_DATA ................................................... 392 RNDIS IP Driver ....................................................................................... 393 13.6.1 General information ....................................................................... 393 13.6.2 Interface function list ..................................................................... 393 13.6.3 USB_IP_NI_DRIVER_API in detail .................................................... 394 13.6.3.1 USB_IP_NI_INIT ................................................................. 394 13.6.3.2 USB_IP_NI_GET_PACKET_BUFFER .........................................395 13.6.3.3 USB_IP_NI_WRITE_PACKET ................................................. 396 13.6.3.4 USB_IP_NI_SET_PACKET_FILTER .......................................... 397 13.6.3.5 USB_IP_NI_GET_LINK_STATUS .............................................398 13.6.3.6 USB_IP_NI_GET_LINK_SPEED .............................................. 399 13.6.3.7 USB_IP_NI_GET_HWADDR ................................................... 400 13.6.3.8 USB_IP_NI_GET_STATS ....................................................... 401 13.6.3.9 USB_IP_NI_GET_MTU ..........................................................402 13.6.3.10 USB_IP_NI_RESET ............................................................ 403 13.6.3.11 USB_IP_NI_SET_WRITE_PACKET_FUNC ............................... 404 CDC-ECM ............................................................................................................... 405 14.1 14.2 14.3 14.4 14.5 Overview ................................................................................................. 406 14.1.1 Working with CDC-ECM .................................................................. 406 14.1.2 Additional information .................................................................... 407 Configuration ........................................................................................... 408 14.2.1 Initial configuration ........................................................................ 408 14.2.2 Final configuration ......................................................................... 408 Running the sample application .................................................................. 409 14.3.1 IP_Config_ECM.c in detail ............................................................... 409 Target API ............................................................................................... 411 14.4.1 API functions ................................................................................ 412 14.4.1.1 USBD_ECM_Add() ............................................................... 412 14.4.1.2 USBD_ECM_Task() .............................................................. 413 14.4.2 Data structures ............................................................................. 414 14.4.2.1 USB_ECM_INIT_DATA ..........................................................414 14.4.3 Driver interface ............................................................................. 415 14.4.3.1 USB_IP_NI_DRIVER_API ...................................................... 415 14.4.3.2 USB_IP_NI_DRIVER_DATA ................................................... 416 CDC-ECM IP Driver ................................................................................... 417 14.5.1 General information ....................................................................... 417 14.5.2 Interface function list ..................................................................... 417 14.5.3 USB_IP_NI_DRIVER_API in detail .................................................... 418 14.5.3.1 USB_IP_NI_INIT ................................................................. 418 14.5.3.2 USB_IP_NI_GET_PACKET_BUFFER .........................................419 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 16 14.5.3.3 14.5.3.4 14.5.3.5 14.5.3.6 14.5.3.7 14.5.3.8 14.5.3.9 14.5.3.10 14.5.3.11 15 USB_IP_NI_WRITE_PACKET ................................................. 420 USB_IP_NI_SET_PACKET_FILTER .......................................... 421 USB_IP_NI_GET_LINK_STATUS .............................................422 USB_IP_NI_GET_LINK_SPEED .............................................. 423 USB_IP_NI_GET_HWADDR ................................................... 424 USB_IP_NI_GET_STATS ....................................................... 425 USB_IP_NI_GET_MTU ..........................................................426 USB_IP_NI_RESET ............................................................ 427 USB_IP_NI_SET_WRITE_PACKET_FUNC ............................... 428 Audio ....................................................................................................................... 429 15.1 15.2 15.3 Overview ................................................................................................. 430 Introduction ............................................................................................. 431 Configuration ........................................................................................... 432 15.3.1 Initial configuration ........................................................................ 432 15.3.2 Final configuration ......................................................................... 432 15.3.3 Using the microphone interface ....................................................... 432 15.3.4 Using the speaker interface ............................................................ 433 15.4 Target API ............................................................................................... 434 15.4.1 API functions ................................................................................ 435 15.4.1.1 USBD_AUDIO_Add() ............................................................435 15.4.1.2 USBD_AUDIO_Read_Task() .................................................. 436 15.4.1.3 USBD_AUDIO_Write_Task() ..................................................437 15.4.1.4 USBD_AUDIO_Start_Play() ...................................................438 15.4.1.5 USBD_AUDIO_Stop_Play() ................................................... 439 15.4.1.6 USBD_AUDIO_Start_Listen() ................................................ 440 15.4.1.7 USBD_AUDIO_Stop_Listen() .................................................441 15.4.2 Data structures ............................................................................. 442 15.4.2.1 USBD_AUDIO_INIT_DATA .................................................... 442 15.4.2.2 USBD_AUDIO_MIC_CONF .....................................................444 15.4.2.3 USBD_AUDIO_SPEAKER_CONF ............................................. 445 15.4.3 Function definitions ........................................................................ 446 15.4.3.1 USBD_AUDIO_TX_FUNC ...................................................... 446 15.4.3.2 USBD_AUDIO_RX_FUNC ...................................................... 447 15.4.3.3 USBD_AUDIO_CONTROL_FUNC .............................................449 16 Combining USB components (Multi-Interface) ........................................................451 16.1 16.2 16.3 16.4 16.5 Overview ................................................................................................. 452 16.1.1 Single interface device classes ........................................................ 453 16.1.2 Multiple interface device classes ...................................................... 453 16.1.3 IAD class ...................................................................................... 454 Configuration ........................................................................................... 455 How to combine ....................................................................................... 456 emUSB-Device component specific modification ............................................ 460 16.4.1 BULK component ........................................................................... 460 16.4.1.1 Device side ........................................................................ 460 16.4.1.2 Host side ........................................................................... 460 16.4.2 MSD component ............................................................................ 460 16.4.2.1 Device side ........................................................................ 460 16.4.2.2 Host side ........................................................................... 460 16.4.3 HID component ............................................................................. 460 16.4.3.1 Device side ........................................................................ 460 16.4.3.2 Host side ........................................................................... 460 16.4.4 CDC component ............................................................................ 461 16.4.4.1 Device side ........................................................................ 461 16.4.4.2 Host side ........................................................................... 461 MSD and MTP combination feature ............................................................. 463 16.5.1 Configuration ................................................................................ 463 16.5.2 Limitations .................................................................................... 464 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 17 16.5.3 Target 16.5.3.1 16.5.3.2 16.5.3.3 17 API .................................................................................... 465 USBD_MSD_MTP_Add() ....................................................... 466 USBD_MSD_MTP_GetMode() ................................................ 467 USBD_MSD_MTP_Task() ...................................................... 468 Target OS Interface ................................................................................................ 469 17.1 General information .................................................................................. 470 17.1.1 Operating system support supplied with this release ...........................470 17.2 Interface function list ................................................................................ 471 17.2.0.1 USB_OS_DeInit() ................................................................472 17.2.0.2 USB_OS_Delay() ................................................................ 473 17.2.0.3 USB_OS_DecRI() ................................................................ 474 17.2.0.4 USB_OS_GetTickCnt() ......................................................... 475 17.2.0.5 USB_OS_IncDI() .................................................................476 17.2.0.6 USB_OS_Init() ................................................................... 477 17.2.0.7 USB_OS_Panic() ................................................................. 478 17.2.0.8 USB_OS_Signal() ................................................................479 17.2.0.9 USB_OS_Wait() .................................................................. 480 17.2.0.10 USB_OS_WaitTimed() ........................................................ 481 17.3 Example .................................................................................................. 482 18 Target USB Driver .................................................................................................. 485 18.1 General information .................................................................................. 486 18.1.1 Available USB drivers ..................................................................... 486 18.2 Adding a driver to emUSB-Device ............................................................... 487 18.2.1 USBD_X_Config() ...........................................................................487 19 Support ....................................................................................................................489 19.1 20 Contacting support ................................................................................... 490 Profiling with SystemView .......................................................................................491 20.1 20.2 Profiling overview ..................................................................................... 492 Additional files for profiling ........................................................................ 493 20.2.1 Additional files on target side ..........................................................493 20.2.2 Additional files on PC side .............................................................. 493 20.3 Enable profiling ........................................................................................ 494 20.4 Recording and analyzing profiling information ...............................................495 21 Debugging ............................................................................................................... 496 21.1 21.2 Message output ........................................................................................ 497 API functions ........................................................................................... 498 21.2.1 USBD_AddLogFilter() ......................................................................499 21.2.2 USBD_AddWarnFilter() ................................................................... 500 21.2.3 USBD_SetLogFilter() ...................................................................... 501 21.2.4 USBD_SetWarnFilter() .................................................................... 502 21.2.5 USB_PANIC ................................................................................... 503 21.2.6 USB_X_Log() ................................................................................ 504 21.2.7 USB_X_Warn() .............................................................................. 505 21.3 Message types ......................................................................................... 506 22 Certification ............................................................................................................. 508 22.1 22.2 22.3 22.4 What is the Windows Hardware Certification and why do I need it? ..................509 Certification offer ......................................................................................509 Vendor and Product ID ..............................................................................509 Certification without SEGGER Microcontroller ................................................ 510 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 18 23 Performance & resource usage .............................................................................. 511 23.1 23.2 24 Memory footprint ...................................................................................... 512 Performance .............................................................................................514 FAQ ......................................................................................................................... 515 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 1 Introduction This chapter will give a short introduction to emUSB-Device, including the supported USB classes and components. Host and target requirements are covered as well. 1.1 Overview This guide describes how to install, configure and use emUSB-Device. It also explains the internal structure of emUSB-Device. emUSB-Device has been designed to work on any embedded system with a USB client controller. It can be used with USB 1.1 or USB 2.0 devices. The highest possible transfer rate on USB 2.0 full speed (12 Mbit/s) devices is approximately 1 MB/s. This data rate can indeed be achieved on fast systems, such as Cortex-M devices running at 48 MHz and above. USB 2.0 high speed mode (480 MBit/s) is also fully supported and is automatically handled. Using USB high speed mode with an Cortex-M or faster could achieve values of approx. 40 MB/s. The USB standard defines four types of communication: Control, isochronous, interrupt, and bulk. Experience shows that for most embedded devices the bulk mode is the communication mode of choice because applications can utilize the full bandwidth of the Universal Serial Bus. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 20 CHAPTER 1 1.2 emUSB-Device features emUSB-Device features Key features of emUSB-Device are: * * * * * * * * High performance Can be used with or without an RTOS Easy to use Easy to port No custom USB host driver necessary Start / test application supplied Highly efficient, portable, and commented ANSI C source code Hardware abstraction layer allows rapid addition of support for new devices emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 21 CHAPTER 1 1.3 emUSB-Device components emUSB-Device components emUSB-Device consists of three layers: A driver for hardware access, the emUSB-Device core and at least a USB class driver or the bulk communication component. The different available hardware drivers, the USB class drivers, and the bulk communication component are additional packages, which can be combined and ordered as they fit to the requirements of your project. Normally, emUSB-Device consists of a driver that fits to the used hardware, the emUSB-Device core and at least one of the USB class drivers. Component Description USB protocol layer Bulk emUSB-Device bulk component. MSD emUSB-Device Mass Storage Device class component. IP-over-USB emUSB-Device IP-over-USB component. SmartMSD emUSB-Device SmartMSD Component CDC-ACM emUSB-Device Communication Device Class component. HID emUSB-Device Human Interface Device Class component. MTP emUSB-Device Media Transfer Protocol component. Printer emUSB-Device Printer Class component. RNDIS emUSB-Device RNDIS component. CDC-ECM emUSB-Device CDC Ethernet Control Model component. UVC emUSB-Device USB video class. Core layer emUSB-Device-Core The emUSB-Device core is the intrinsic USB stack. Hardware layer Driver 1.3.1 USB controller driver. emUSB-Device-Bulk emUSB-Device-Bulk allows you to quickly and smoothly develop software for an embedded device that communicates with a PC via USB. The communication is like a single, highspeed, reliable channel (very similar to a TCP connection). This bidirectional channel, with built-in flow control, allows the PC to send data to the embedded target, the embedded target to receive these bytes and reply with any number of bytes. The PC is the USB host, the target is the USB client. 1.3.2 1.3.2.1 emUSB-Device-MSD Purpose of emUSB-Device-MSD Access the target device like an ordinary disk drive emUSB-Device-MSD enables the use of an embedded target device as a USB mass storage device. The target device can be simply plugged-in and used like an ordinary disk drive, without the need to develop a driver for the host operating system. This is possible because the mass storage class is one of the standard device classes, defined by the USB Implementers Forum (USB IF). Virtually every major operating system on the market supports these device classes out of the box. No custom host drivers necessary Every major OS already provides host drivers for USB mass storage devices, there is no need to implement your own. The target device will be recognized as a mass storage device and can be accessed directly. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 22 CHAPTER 1 emUSB-Device components Plug and Play Assuming the target system is a digital camera using emUSB-Device-MSD, videos or photos taken by this camera can be conveniently accessed with the file system explorer of the used operating system when the camera is connected to the computer. 1.3.2.2 Typical applications Typical applications are: * * * * Digital camera USB stick MP3 Player DVD player Any target with USB interface: easy access to configuration and data files 1.3.2.3 emUSB-Device-MSD features Key features of emUSB-Device-MSD are: * * * 1.3.2.4 Can be used with RAM, parallel flash, serial flash or mechanical drives Support for full speed (12 Mbit/s) and high speed (480 Mbit/s) transfer rates OS-abstraction: Can be used with any RTOS, but no OS is required for MSD-only devices How does it work? Use file system support from host OS A device which uses emUSB-Device-MSD will be recognized as a mass storage device and can be used like an ordinary disk drive. If the device is unformatted when plugged-in, the host operating system will ask you to format the device. Any file system provided by the host can be used. Typically FAT is used, but other file systems such as NTFS are possible, too. If one of those file systems is used, the host is able to read from and write to the device using the storage functions of the emUSB-Device MSD component, which define unstructured read and write operations. Thus, there is no need to develop extra file system code if the application only accesses data on the target from the host side. This is typically the case for simple storage applications, such as USB memory sticks or ATA to USB bridges. Only provide file system code on the target if necessary Mass storage devices like USB sticks do not require their own file system implementation. File system program code is only required if the application running on the target device has to access the stored data. The development of a file system is a complex and timeconsuming task and increases the time-to market. Thus we recommend the use of a commercial file system like emFile, SEGGER's file system for embedded applications. emFile is a high performance library that is optimized for minimum memory consumption in RAM and ROM, high speed and versatility. It is written in ANSI C and runs on any CPU and on any media. Refer to www.segger.com/emfile.html for more information about emFile. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 23 CHAPTER 1 1.3.3 emUSB-Device components emUSB-Device IP-over-USB emUSB-Device IP-over-USB allows to run any IP-based protocol over USB. This component combines the advantages of RNDIS and CDC-ECM and allows plug-and-play on any major host operating system. Using the IP-over-USB technology in combination with a built in web server, the device can easily be accessed from any host (Windows, Linux, Mac) by simply typing the device name into the web browser. 1.3.3.1 Typical applications Typical applications are: * * * * 1.3.4 Headphones Printer Data logger Ethernet2USB adapter emUSB-Device-SmartMSD The emUSB-Device-SmartMSD component allows to easily stream files to and from USB devices. Once the USB device is connected to the host, files can be read or written to the application without the need for dedicated storage memory. 1.3.4.1 Typical applications Typical applications are: * * 1.3.5 Updating firmware (e.g. Handheld Terminal) Updating configuration files emUSB-Device-CDC emUSB-Device-CDC converts the target device into a serial communication device. A target device running emUSB-Device-CDC is recognized by the host as a serial interface (USB2COM, virtual COM port), without the need to install a special host driver, because the communication device class is one of the standard device classes and every major operating system already provides host drivers for those device classes. All PC software using a COM port will work without modifications with this virtual COM port. 1.3.5.1 Typical applications Typical applications are: * * * 1.3.6 Modem Telephone system Fax machine emUSB-Device-HID The Human Interface Device class (HID) is an abstract USB class protocol defined by the USB Implementers Forum. This protocol was defined for handling devices that humans use to control the operation of computer systems. An installation of a custom host USB driver is not necessary because the USB human interface device class is standardized and every major OS already provides host drivers for it. 1.3.6.1 Typical applications Typical applications are: * * * * Keyboard Mouse and similar pointing devices Gamepad Front-panel controls - for example, switches and buttons emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 24 CHAPTER 1 * * * * * 1.3.7 emUSB-Device components Bar-code reader Thermometer Voltmeter Low-speed JTAG emulator Uninterruptible power supply (UPS) emUSB-Device-MTP The Media Transfer Protocol (MTP) is a USB class protocol which can be used to transfer files to and from storage devices. MTP is an alternative to MSD as it operates on a file level rather than on a storage sector level. The advantage of MTP is the ability to access the storage medium from the host PC and from the device at the same time. Because MTP works at the file level this also eliminates the risk of damaging the file system when the communication to the host has been canceled unexpectedly (e.g. the cable was removed). MTP is supported by most operating systems without the need to install third-party drivers. 1.3.7.1 Typical applications Typical applications are: * * * * * Digital camera USB stick MP3 Player DVD player Telephone Any target with USB interface: easy access to configuration and data files. 1.3.8 emUSB-Device-Printer emUSB-Device-Printer converts the target device into a printing device. A target device running emUSB-Device-Printer is recognized by the host as a printer. Unless the device identifies itself as a printer already recognized by the host PC, you must install a driver to be able to communicate with the USB device. 1.3.8.1 Typical applications Typical applications are: * * 1.3.9 Laser/Inkjet printer CNC machine emUSB-Device-RNDIS emUSB-Device-RNDIS allows to create a virtual Ethernet adapter through which the host PC can communicate with the device using the Internet protocol suite (TCP, UDP, FTP, HTTP, Telnet). This allows the creation of USB based devices which can host a webserver or act as a telnet terminal or a FTP server. emUSB-Device-RNDIS offer a unique customer experience and allows to save development and hardware cost by e.g. using a website as a user interface instead of creating an application for every major OS and by eliminating the Ethernet hardware components from your device. 1.3.9.1 Typical applications Typical applications are: * * * USB-Webserver USB-Terminal (e.g. Telnet) USB-FTP-Server emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 25 CHAPTER 1 1.3.10 emUSB-Device components emUSB-Device-CDC-ECM emUSB-Device-CDC-ECM allows to create a virtual Ethernet adapter through which the host PC can communicate with the device using the Internet protocol suite (TCP, UDP, FTP, HTTP, Telnet). This allows the creation of USB based devices which can host a webserver or act as a telnet terminal or a FTP server. emUSB-Device-CDC-ECM offer a unique customer experience and allows to save development and hardware cost by e.g. using a website as a user interface instead of creating an application for every major OS and by eliminating the Ethernet hardware components from your device. 1.3.10.1 Typical applications Typical applications are: * * * USB-Webserver USB-Terminal (e.g. Telnet) USB-FTP-Server emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 26 CHAPTER 1 1.4 Requirements Requirements 1.4.1 Target system Hardware The target system must have a USB controller. The memory requirements can be found in the chapter Performance & resource usage on page 511. In order to have the control when the device is enumerated by the host, a switchable attach is necessary. This is a switchable pull-up connected to the D+ Line of USB. Software emUSB-Device is optimized to be used with embOS but works with any other supported RTOS or without an RTOS in a superloop. For information regarding the OS integration refer to the chapter Target OS Interface on page 469. 1.4.2 Development environment (compiler) The CPU used is of no importance; only an ANSI-compliant C compiler complying with at least one of the following international standard is required: * * * ISO/IEC/ANSI 9899:1990 (C90) with support for C++ style comments (//) ISO/IEC 9899:1999 (C99) ISO/IEC 14882:1998 (C++) If your compiler has some limitations, let us know and we will inform you if these will be a problem when compiling the software. Any compiler for 16/32/64-bit CPUs or DSPs that we know of can be used. A C++ compiler is not required, but can be used. The application program can therefore also be programmed in C++ if desired. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 27 1.5 CHAPTER 1 File structure File structure The following table shows the contents of the emUSB-Device root directory: Directory Contents Application Contains the application programs. Depending on which stack is used, several files are available for each stack. Detailed information can be found in the corresponding chapter. BSP Contains example hardware-specific configurations for different eval boards. Config Contains configuration files (USB_Conf.h, USB_ConfigIO.c). Doc Contains the emUSB-Device documentation. Inc Contains include files. Sample Contains operating systems dependent files which allows to run emUSB-Device with different RTOS's. SEGGER Contains generic routines from SEGGER (e.g. memcpy). USB Contains the emUSB-Device source code. Windows Contains Windows specific applications which can be used in conjunction with the device application samples. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 2 Background information This is a short introduction to USB. The fundamentals of USB are explained and links to additional resources are given. Information provided in this chapter is not required to use the software. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 29 CHAPTER 2 2.1 USB USB 2.1.1 Short Overview The Universal Serial Bus (USB) is a bus architecture for connecting multiple peripherals to a host computer. It is an industry standard -- maintained by the USB Implementers Forum -- and because of its many advantages it enjoys a huge industry-wide acceptance. Over the years, a number of USB-capable peripherals appeared on the market, for example printers, keyboards, mice, digital cameras etc. Among the top benefits of USB are: * * * * * * * Excellent plug-and-play capabilities allow devices to be added to the host system without reboots ("hot-plug"). Plugged-in devices are identified by the host and the appropriate drivers are loaded instantly. USB allows easy extensions of host systems without requiring host-internal extension cards. Device bandwidths may range from a few kB/s to hundreds of MB/s. A wide range of packet sizes and data transfer rates are supported. USB provides internal error handling. Together with the already mentioned hot-plug capability this greatly improves robustness. The provisions for powering connected devices dispense the need for extra power supplies for many low power devices. Several transfer modes are supported which ensures the wide applicability of USB. These benefits did not only lead to broad market acceptance, but it also added several advantages, such as low costs of USB cables and connectors or a wide range of USB stack implementations. Last but not least, the major operating systems such as Microsoft Windows, Mac OS X, or Linux provide excellent USB support. 2.1.2 Important USB Standard Versions USB 1.1 (September 1998) This standard version supports isochronous and asynchronous data transfers. It has dual speed data transfer of 1.5 Mbit/s for low speed and 12 Mbit/s for full speed devices. The maximum cable length between host and device is five meters. Up to 500 mA of electric current may be distributed to low power devices. USB 2.0 (April 2000) As all previous USB standards, USB 2.0 is fully forward and backward compatible. Existing cables and connectors may be reused. A new high speed transfer speed of 480 Mbit/s (40 times faster than USB 1.1 at full speed) was added. USB 3.0 (November 2008) As all previous USB standards, USB 3.0 is fully forward and backward compatible. Existing cables and connectors may be reused but the new speed can only be used with new USB 3.0 cables and devices. The new speed class is named USB Super-Speed, which offers a maximum rate of 5 Gbit/s. USB 3.1 (July 2013) As all previous USB standards, USB 3.1 is fully forward and backward compatible. The new specification replaces the 3.0 standard and introduces new transfer speeds of up to 10 Gbit/s. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 30 CHAPTER 2 2.1.3 USB USB System Architecture A USB system is composed of three parts - a host side, a device side and a physical bus. The physical bus is represented by the USB cable and connects the host and the device. The USB system architecture is asymmetric. Every single host can be connected to multiple devices in a tree-like fashion using special hub devices. You can connect up to 127 devices to a single host, but the count must include the hub devices as well. A USB host consists of a USB host controller hardware and a layered software stack. This host stack contains: * * * A host controller driver (HCD) which provides the functionality of the host controller hardware. The USB Driver (USBD) Layer which implements the high level functions used by USB device drivers in terms of the functionality provided by the HCD. The USB Device drivers which establish connections to USB devices. The driver classes are also located here and provide generic access to certain types of devices such as printers or mass storage devices. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 31 CHAPTER 2 USB USB Device Two types of devices exist: hubs and functions. Hubs provide for additional USB attachment points. Functions provide capabilities to the host and are able to transmit or receive data or control information over the USB bus. Every peripheral USB device represents at least one function but may implement more than one function. A USB printer for instance may provide file system like access in addition to printing. In this guide we treat the term USB device as synonymous with functions and will not consider hubs. Each USB device contains configuration information which describes its capabilities and resource requirements. A USB device must be configured by the host before its functions can be used. When a new device is connected for the first time, the host enumerates it, requests the configuration from the device, and performs the actual configuration. For example, if an embedded device uses emUSB-Device-MSD, the embedded device will appear as a USB mass storage device, and the host OS provides the driver out of the box. In general, there is no need to develop a custom driver to communicate with target devices that use one of the USB class protocols. Descriptors A device reports its attributes via descriptors. Descriptors are data structures with a standard defined format. A USB device has one device descriptor which contains information applicable to the device and all of its configurations. It also contains the number of configurations the device supports. For each configuration, a configuration descriptor contains configuration-specific information. The configuration descriptor also contains the number of interfaces provided by the configuration. An interface groups the endpoints into logical units. Each interface descriptor contains information about the number of endpoints. Each endpoint has its own endpoint descriptor which states the endpoint's address, transfer types etc. As can be seen, the descriptors form a tree. The root is the device descriptor with n configuration descriptors as children, each of which has m interface descriptors which in turn have o endpoint descriptors each. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 32 CHAPTER 2 2.1.4 USB Transfer Types The USB standard defines four transfer types: control, isochronous, interrupt, and bulk. Control transfers are used in the setup phase. The application can select one of the other three transfer types. For most embedded applications, bulk is the best choice because it allows the highest possible data rates. Control transfers Typically used for configuring a device when attached to the host. It may also be used for other device-specific purposes, including control of other pipes on the device. Isochronous transfers Typically used for applications which need guaranteed speed. Isochronous transfer is fast but with possible data loss. A typical use is for audio data which requires a constant data rate. Interrupt transfers Typically used by devices that need guaranteed quick responses (bounded latency). Bulk transfers Typically used by devices that generate or consume data in relatively large and bursty quantities. Bulk transfer has wide dynamic latitude in transmission constraints. It can use all remaining available bandwidth, but with no guarantees on bandwidth or latency. Because the USB bus is normally not very busy, there is typically 90% or more of the bandwidth available for USB transfers. 2.1.5 Setup phase / Enumeration The host first needs to get information from the target, before the target can start communicating with the host. This information is gathered in the initial setup phase. The information is contained in the descriptors, which are in the configurable section of the USB-MSD stack. The most important part of target device identification are the Product and Vendor IDs. During the setup phase, the host also assigns an address to the client. This part of the setup is called enumeration. 2.1.6 Product / Vendor IDs The Product and Vendor IDs are necessary to identify the USB device. The Product ID describes a specific device type and does not need to be unique between different devices of the same type. USB host systems like Windows use the Product ID/Vendor ID combination to identify which drivers are needed. For example: all our J-Link devices have the Vendor ID 0x1366 and Product ID 0x0105. A Vendor and Product ID is necessary only when development of the product is finished; during the development phase, the supplied Vendor and Product IDs can be used as samples. Using the sample Vendor ID (0x8765) or the SEGGER Vendor ID in a finished product is not allowed. Possible options to obtain a Vendor ID or Product ID are described in the chapter Vendor and Product ID on page 509. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 33 2.2 CHAPTER 2 Predefined device classes Predefined device classes The USB Implementers Forum has defined device classes for different purposes. In general, every device class defines a protocol for a particular type of application such as a mass storage device (MSD), human interface device (HID), etc. Device classes provide a standardized way of communication between host and device and typically work with a class driver which comes with the host operating system. Using a predefined device class where applicable minimizes the amount of work to make a device usable on different host systems. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 34 2.3 CHAPTER 2 USB hardware analyzers USB hardware analyzers A variety of USB hardware analyzers are on the market with different capabilities. If you are developing an application using emUSB-Device it should not be necessary to have a USB analyzer, but we still recommend you do. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 35 CHAPTER 2 2.4 References References For additional information see the following documents: * * * Universal Serial Bus Specification, Revision 2.0 Universal Serial Bus Mass Storage Class Specification Overview, Rev 1.2 UFI command specification: USB Mass Storage Class, UFI Command Specification, Rev 1.0 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 3 Getting started The first step in getting emUSB-Device up and running is typically to compile it for the target system and to run it in the target system. This chapter explains how to do this. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 37 CHAPTER 3 3.1 How to setup your target system How to setup your target system We assume that you are familiar with the tools you have selected for your project (compiler, project manager, linker, etc.). You should therefore be able to add files, add directories to the include search path, and so on. In this document the Embedded Studio IDE is used for all examples and screenshots, but every other ANSI C toolchain can also be used. It is also possible to use makefiles; in this case, when we say "add to the project", this translates into "add to the makefile". Procedure to follow Integration of emUSB-Device is a relatively simple process, which consists of the following steps: * * * * 3.1.1 Take a running project for your target hardware. Add emUSB-Device files to the project. Add hardware dependent configuration to the project. Prepare and run the application. Take a running project The project to start with should include the setup for basic hardware (e.g. CPU, PLL, DDR SDRAM) and initialization of the RTOS. emUSB-Device is designed to be used with embOS, SEGGER's real-time operating system. We recommend to start with an embOS sample project and include emUSB-Device into this project. 3.1.2 Add emUSB-Device files Add all source files in the USB folder to your project. It it not necessary to select files depending on your configuration. Simply add all files, the linker will drop everything not needed. Add RTOS layer Additionally add the RTOS interface layer to your project. Choose a file from the folder Sample/USB/OS that matches your RTOS. For embOS use USBH_OS_embOS.c. There is also a file USB_OS_None.c containing a layer to be used for superloop applications without an RTOS. Configuring the include path The include path is the path in which the compiler looks for include files. In cases where the included files (typically header files, .h) do not reside in the same folder as the C file to compile, an include path needs to be set. In order to build the project with all added files, you will need to add the following directories to your include path: * * * * 3.1.3 Config Inc SEGGER USB Configuring debugging output While developing and testing emUSB-Device, we recommend to use the DEBUG configuration of emUSB-Device. This is enabled by setting the preprocessor symbol DEBUG to 1 (or USB_DEBUG_LEVEL to 2). The DEBUG configuration contains many additional run-time checks and generate debug output messages which are very useful to identify problems that may occur during development. In case of a fatal problem (e.g. an invalid configuration) the program will end up in the function USB_OS_Panic() with a appropriate error message that describes the cause of the problem. Once the application is running correctly, DEBUG can be set to 0. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 38 CHAPTER 3 How to setup your target system Add the file USB_ConfigIO.c found in the folder Config to your project and configure it to match the message output method used by your debugging tools. If possible use RTT. To later compile a release configuration, which has a significant smaller code footprint, simply set the preprocessor symbol DEBUG (or USB_DEBUG_LEVEL) to 0. 3.1.4 Add hardware dependent configuration To perform target hardware dependent runtime configuration, the emUSB-Device stack calls a function named USBD_X_Config. Typical tasks that may be done inside this function are: * * * * Select an appropriate driver for the USB controller. Configure I/O pins of the MCU for USB. Configure PLL and clock divider necessary for USB operation. Install an interrupt service routine for USB. Details can be found in Target USB Driver on page 485. Sample configurations for popular evaluation boards are supplied with the driver shipment. They can be found in files called USB_Config_<TargetName>.c in the folders BSP/<BoardName>/Setup. Add the appropriate configuration file to your project. If there is no configuration file for your target hardware, take a file for a similar hardware and modify it if necessary. If the file needs modifications, we recommend to copy it into the directory Config for easy updates to later versions of emUSB-Device. Add BSP file Some targets require CPU specific functions for initialization, mainly for installing an interrupt service routine. They are contained in the file BSP_USB.c. Sample BSP_USB.c files for popular evaluation boards are supplied with the driver shipment. They can be found in the folders BSP/<BoardName>/Setup. Add the appropriate BSP_USB.c file to your project. If there is no BSP file for your target hardware, take a file for a similar hardware and modify it if necessary. If the file needs modifications, we recommend to copy it into the directory Config for easy updates to later versions of emUSB-Device. Note that a BSP_USB.c file is not always required, because for some target hardware all runtime configuration is done in USB_X_Config. 3.1.5 Prepare and run the application Choose a sample application from the folder Application and add it to your project. For example, add USB_HID_Mouse.c as your application to your project. Compile and run the application on the target hardware. After connecting the USB cable to the target device, the mouse pointer should hop from left to right. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 39 emUSB-Device User Guide & Reference Manual CHAPTER 3 How to setup your target system (c) 2010-2018 SEGGER Microcontroller GmbH 40 CHAPTER 3 3.2 Updating emUSB-Device Updating emUSB-Device If an existing project should be updated to a later emUSB-Device version, only files have to be replaced. You should have received the emUSB-Device update as a zip file. Unzip this file to the location of your choice and replace all emUSB-Device files in your project with the newer files from the emUSB-Device update shipment. In general, all files from the following directories have to be updated: * * * * * USB Inc SEGGER Doc Sample/USB/OS Some files may contain modification required for project specific customization. These files should reside in the folder Config and must not be overwritten. This includes: * * * * USB_Conf.h USB_ConfigIO.c BSP_USB.c USB_Config_<TargetName>.c emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 41 3.3 CHAPTER 3 emUSB-Device Configuration emUSB-Device Configuration An application using emUSB-Device must contain a structure containing the device identification information: typedef struct { U16 VendorId; U16 ProductId; char *sVendorName; char *sProductName; char *sSerialNumber } USB_DEVICE_INFO; Member Description VendorId Vendor ID of the target. ProductId Product ID of the target. sVendorName The manufacturer name. sProductName The product name of the target. sSerialNumber The serial number of the device. This structure and functions are included in every example application and can be used without modifications in the development phase of your application, but you may not bring a product on the market without modifying the Vendor ID and Product ID. Ids Description Default Vendor ID for all applications 0x8765 Example Vendor ID for all examples. Used Product IDs 0x1240 Example Product ID for all bulk samples. 0x1234 Example Product ID for deprecated bulk samples (using SEGGER Windows driver) 0x1000 Example Product ID for all MSD samples. 0x1200 Example Product ID for the MSD CD-ROM sample. 0x1111 Example Product ID for all CDC samples. 0x1112 Example Product ID for HID mouse sample. 0x1114 Example Product ID for the vendor specific HID sample. 0x1115 Example Product ID for HID keyboard sample. 0x2114 Example Product ID for the Printer class sample. 0x3000 Example Product ID for RNDIS sample. 0x3003 Example Product ID for ECM sample. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 42 CHAPTER 3 3.3.1 3.3.1.1 emUSB-Device Configuration General emUSB-Device configuration USB_DEVICE_INFO Description Device information that must be provided by the application via the function USBD_SetDeviceInfo() before the USB stack is started using USBD_Start() . Prototype typedef struct { U16 VendorId; U16 ProductId; char *sVendorName; char *sProductName; char *sSerialNumber } USB_DEVICE_INFO; Additional information The Product ID in combination with the Vendor ID creates a worldwide unique identifier for the product model. The Vendor ID is assigned by the USB Implementers Forum (www.usb.org). For tests, the default number above (or pretty much any other number) can be used. However, you may not bring a product to market without having been assigned your own Vendor ID. For emUSB-Device-CDC: If you change this value, do not forget to make the same change to the .inf file as described in section The .inf file on page 270. Otherwise, the Windows host will be unable to locate the driver. The manufacturer name, product name and serial number are used during the enumeration phase. They together should give a detailed information about which device is connected to the host. Note The max string length cannot be more than 126 ANSI characters. Note for MSD: In order to confirm to the USB bootability specification, the minimum string length of the serial number must be 12 characters where each character is a hexadecimal digit ('0' though '9' or 'A' through 'F'). Example static const USB_DEVICE_INFO _DeviceInfo = { 0x8765, // VendorId 0x1234, // ProductId "Vendor", // VendorName "Bulk device", // ProductName "13245678" // SerialNumber } ... USBD_SetDeviceInfo(&_DeviceInfo); ... USBD_Start(); 3.3.2 MSD Additional required configuration functions for emUSB- Refer to MSD Configuration on page 153 for more information about the required additional configuration functions for emUSB-MSD. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 43 CHAPTER 3 3.3.3 emUSB-Device Configuration Descriptors All configuration descriptors are automatically generated by emUSB-Device and do not require configuration. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 4 USB Core This chapter describes the basic functions of the USB Core. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 45 4.1 CHAPTER 4 Overview Overview This chapter describes the functions of the core layer of emUSB-Device. These functions are required for all USB class drivers and the unclassified bulk communication component. General information To communicate with the host, the example applications include a USB-specific header USB.h. This file contains API functions to communicate with the USB host through the USB Core driver. Every application using USB Core must perform the following steps: 1. Initialize the USB stack. To initialize the USB stack USBD_Init() has to be called. USBD_Init() performs the low-level initialization of the USB stack and calls USBD_X_Config() to add a driver to the USB stack. 2. Add communication endpoints. You have to add the required endpoints with the compatible transfer type for the desired interface before you can use any of the USB class drivers or the unclassified bulk communication component. For the emUSB-Device bulk component, refer to USB_BULK_INIT_DATA on page 96 for information about the initialization structure that is required when you want to add a bulk interface. For the emUSB-Device MSD component, refer to USB_MSD_INIT_DATA on page 171 and USB_MSD_INST_DATA on page 173 for information about the initialization structures that are required when you want to add an MSD interface. For the emUSB-Device CDC component, refer to USB_CDC_INIT_DATA on page 298 for information about the initialization structure that is required when you want to add a CDC interface. For the emUSB-Device HID component, refer to USB_HID_INIT_DATA on page 325 for information about the initialization structure that is required when you want to add a HID interface. 3. Provide device information using USBD_SetDeviceInfo() . 4. Start the USB stack. Call USBD_Start() to start the USB stack. Example applications for every supported USB class and the unclassified bulk component are supplied. We recommend using one of these examples as a starting point for your own application. All examples are supplied in the \Application\ directory. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 46 4.2 CHAPTER 4 Target API Target API This section describes the functions that can be used by the target application. Function Description USB basic functions USBD_Init() Initializes the USB device with its settings. USBD_Start() Starts the emUSB-Device Core. USBD_GetState() Returns the state of the USB device. USBD_IsConfigured() Checks if the USB device is initialized and ready. USBD_Stop() Stops the USB communication. USBD_DeInit() De-initialize the complete USB stack. USB configuration functions USBD_AddDriver() Adds a USB device driver to the USB stack. USBD_SetISRMgmFuncs() Register interrupt management functions. USBD_SetAttachFunc() Sets a function to perform hardware-specific actions to attach USB. USBD_AddEP() Returns an endpoint "handle" that can be used for the desired USB interface. USBD_AddEPEx() Returns an endpoint "handle" that can be used for the desired USB interface. USBD_SetDeviceInfo() Sets a all information used during device enumeration. USBD_SetClassRequestHook() Sets a callback function that is called when a setup class request is sent from the host to the specified interface index. USBD_SetVendorRequestHook() Sets a callback function that is called when a setup vendor request is sent from the host to the specified interface index. USBD_SetIsSelfPowered() Sets whether the device is self-powered or not. USBD_SetMaxPower() Sets the maximum power consumption reported to the host during enumeration. USBD_SetOnEvent() Sets a callback function for an endpoint that will be called on every RX or TX event for that endpoint. USBD_RemoveOnEvent() Removes a callback function which was added via USBD_SetOnEvent from the callback list. USBD_SetOnRxEP0() Sets a callback when data are received in the data stage of the setup request. USBD_SetOnSetupHook() Sets a callback function that is called when any setup request is sent from the host for the specified interface index. USBD_WriteEP0FromISR() Write data to EP0 (control endpoint). USBD_EnableIAD() Enables combination of multi-interface device classes with single-interface classes or other multi-interface classes. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 47 CHAPTER 4 Target API Function Description USBD_SetCacheConfig() Configures cache related functionality that might be required by the stack for cache handling in drivers. USBD_RegisterSCHook() Sets a callback function that will be called on every state change of the USB device. USB I/O functions USBD_Read() Reads data from the host. USBD_ReadOverlapped() Reads data from the host asynchronously. USBD_Receive() Reads data from host. USBD_Write() Writes data to the host. USBD_CancelIO() Cancel any read or write operation. USBD_WaitForEndOfTransfer() Wait until the current transfer on a particular EP has completed. USBD_WaitForTXReady() Waits (blocking) until the TX queue can accept another data packet. USBD_GetNumBytesInBuffer() Returns the number of bytes that are available in the internal BULK-OUT endpoint buffer. USBD_GetNumBytesRemToRead() This function is to be used in combination with USBD_ReadOverlapped(). USBD_GetNumBytesRemToWrite() This function is to be used in combination with a non-blocking call to USBD_Write(). USBD_StallEP() Stalls an endpoint. USB RemoteWakeUp functions USBD_SetAllowRemoteWakeUp() Allows the device to publish that remote wake is available. USBD_DoRemoteWakeup() Performs a remote wakeup in order to wake up the host from the standby/suspend state. Data structures SEGGER_CACHE_CONFIG emUSB-Device User Guide & Reference Manual Used to pass cache configuration and callback function pointers to the stack. (c) 2010-2018 SEGGER Microcontroller GmbH 48 CHAPTER 4 4.2.1 4.2.1.1 Target API USB basic functions USBD_GetState() Description Returns the state of the USB device. Prototype unsigned USBD_GetState(void); Return value A bitwise combination of the USB state flags: USB_STAT_ATTACHED USB_STAT_READY USB_STAT_ADDRESSED USB_STAT_CONFIGURED USB_STAT_SUSPENDED Device Device Device Device Device is is is is is attached. (Note 1) ready. addressed. configured. suspended. Additional information A USB device has several possible states. Some of these states are visible to the USB and the host, while others are internal to the USB device. Refer to Universal Serial Bus Specification, Revision 2.0, Chapter 9 for detailed information. Notes (1) Attached in a USB sense of the word does not mean that the device is physically connected to the PC via a USB cable, it only means that the pull-up resistor on the device side is connected. The status can be "attached" regardless of whether the device is connected to a host or not. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 49 CHAPTER 4 4.2.1.2 Target API USBD_Init() Description Initializes the USB device with its settings. Prototype void USBD_Init(void); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 50 CHAPTER 4 4.2.1.3 Target API USBD_IsConfigured() Description Checks if the USB device is initialized and ready. Prototype char USBD_IsConfigured(void); Return value 0 1 USB device is not configured. USB device is configured. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 51 CHAPTER 4 4.2.1.4 Target API USBD_Start() Description Starts the emUSB-Device Core. Prototype void USBD_Start(void); Additional information This function should be called after configuring USB Core. It initiates a hardware attach and updates the endpoint configuration. When the USB cable is connected to the device, the host will start enumeration of the device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 52 CHAPTER 4 4.2.1.5 Target API USBD_Stop() Description Stops the USB communication. This also makes sure that the device is detached from the HOST. Prototype void USBD_Stop(void); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 53 CHAPTER 4 4.2.1.6 Target API USBD_DeInit() Description De-initialize the complete USB stack. Prototype void USBD_DeInit(void); Additional information This function also calls USBD_Stop() internally. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 54 CHAPTER 4 4.2.2 4.2.2.1 Target API USB configuration functions USBD_AddDriver() Description Adds a USB device driver to the USB stack. This function should be called from within USBD_X_Config() which is implemented in USB_Config_*.c. Prototype void USBD_AddDriver(const USB_HW_DRIVER * pDriver); Parameters Parameter pDriver Description Pointer to the driver API structure. Additional information To add the driver, use USBD_AddDriver() with the identifier of the compatible driver. Refer to the section "Available target USB drivers" in the USB.h header file for a list of supported devices and their valid identifiers. Example /********************************************************************* * * USBD_X_Config */ void USBD_X_Config(void) { BSP_USB_Init(); USB_DRIVER_LPC17xx_ConfigAddr(0x2008C000); // USB controller of LPC1788 // is located @ 0x2008C000 USBD_AddDriver(&USB_Driver_NXPLPC17xx); USBD_SetISRMgmFuncs(_EnableISR, NULL, NULL); } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 55 CHAPTER 4 4.2.2.2 Target API USBD_SetISRMgmFuncs() Description Register interrupt management functions. Prototype void USBD_SetISRMgmFuncs(USB_ENABLE_ISR_FUNC * pfEnableISR, USB_INC_DI_FUNC * pfIncDI, USB_DEC_RI_FUNC * pfDecRI); Parameters Parameter Description pfEnableISR Pointer to the function to install the interrupt handler and enable the USB interrupt. pfIncDI Unused. pfDecRI Unused. Additional information This function must be called within USBD_X_Config() function. See Adding a driver to emUSB-Device on page 487. The functions pointer prototype is defined as follows: typedef void USB_ENABLE_ISR_FUNC (USB_ISR_HANDLER * pfISRHandler); Example See USBD_AddDriver(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 56 CHAPTER 4 4.2.2.3 Target API USBD_SetAttachFunc() Description Sets a function to perform hardware-specific actions to attach USB. Prototype void USBD_SetAttachFunc(USB_ATTACH_FUNC * pfAttach); Parameters Parameter Description Pointer to the attach function. pfAttach Additional information This function must be called within USBD_X_Config() function. See Adding a driver to emUSB-Device on page 487. The functions pointer prototypes are defined as follows: typedef void USB_ATTACH_FUNC (void); Example See USBD_X_Config() on page 487. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 57 CHAPTER 4 4.2.2.4 Target API USBD_AddEP() Description Returns an endpoint "handle" that can be used for the desired USB interface. Prototype unsigned USBD_AddEP(U8 InDir, U8 TransferType, U16 Interval, U8 * pBuffer, unsigned BufferSize); Parameters Parameter Description InDir Specifies the direction of the desired endpoint. * USB_DIR_IN * USB_DIR_OUT TransferType Specifies the transfer type of the endpoint. The following values are allowed: * USB_TRANSFER_TYPE_BULK * USB_TRANSFER_TYPE_ISO * USB_TRANSFER_TYPE_INT Interval Specifies the interval measured in units of 125us (micro frames). This value should be zero for a bulk endpoint. pBuffer Pointer to a buffer that is used for OUT-transactions. For INendpoints this parameter must be NULL. BufferSize Size of the buffer (OUT endpoints only). Must be a multiple of the maximum packet size. Return value >0 =0 A valid endpoint handle is returned. Error. Additional information The Interval parameter specifies the frequency in which the endpoint should be polled for information by the host. It must be specified in units of 125 us. Depending on the actual speed of the device during enumeration, the USB stack converts the interval to the correct value required for the endpoint descriptor according to the USB specification (into milliseconds for low/full speed, into 125 us for high speed). For endpoints of type USB_TRANSFER_TYPE_BULK the value is ignored and should be set to 0. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 58 CHAPTER 4 4.2.2.5 Target API USBD_AddEPEx() Description Returns an endpoint "handle" that can be used for the desired USB interface. Prototype unsigned USBD_AddEPEx(const USB_ADD_EP_INFO * pInfo, U8 * pBuffer, unsigned BufferSize); Parameters Parameter Description pInfo Pointer to a structure of type USB_ADD_EP_INFO. pBuffer Pointer to a buffer that is used for OUT-transactions. For INendpoints this parameter must be NULL. BufferSize Size of the buffer (OUT endpoints only). Must be a multiple of the maximum packet size. Return value >0 =0 A valid endpoint handle is returned. Error. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 59 CHAPTER 4 4.2.2.6 Target API USBD_SetDeviceInfo() Description Sets a all information used during device enumeration. Prototype void USBD_SetDeviceInfo(const USB_DEVICE_INFO * pDeviceInfo); Parameters Parameter pDeviceInfo Description Pointer to a structure containing the device information. Must point to static data that is not changed while the stack is running. Additional information See USB_DEVICE_INFO on page 42 for a description of the structure. Example See USB_DEVICE_INFO on page 42. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 60 CHAPTER 4 4.2.2.7 Target API USBD_SetClassRequestHook() Description Sets a callback function that is called when a setup class request is sent from the host to the specified interface index. Prototype void USBD_SetClassRequestHook(unsigned InterfaceNum, USB_ON_CLASS_REQUEST * pfOnClassRequest); Parameters Parameter Description InterfaceNum Interface index that for setting the class request callback. pfOnClassRequest Pointer to the callback. Additional information Note that the callback will be called within an ISR, therefore it should never block. If it is necessary to send data from the callback function through endpoint 0, use the function USBD_WriteEP0FromISR(). USB_ON_CLASS_REQUEST is defined as follows: typedef void USB_ON_CLASS_REQUEST(const emUSB-Device User Guide & Reference Manual USB_SETUP_PACKET * pSetupPacket); (c) 2010-2018 SEGGER Microcontroller GmbH 61 CHAPTER 4 4.2.2.8 Target API USBD_SetVendorRequestHook() Description Sets a callback function that is called when a setup vendor request is sent from the host to the specified interface index. Prototype void USBD_SetVendorRequestHook(unsigned InterfaceNum, USB_ON_CLASS_REQUEST * pfOnVendorRequest); Parameters Parameter Description InterfaceNum Interface index that for setting the class request callback. pfOnVendorRequest Pointer to the callback. Additional information Note that the callback will be called within an ISR, therefore it should never block. If it is necessary to send data from the callback function through endpoint 0, use the function USBD_WriteEP0FromISR(). USB_ON_CLASS_REQUEST is defined as follows: typedef void USB_ON_CLASS_REQUEST(const emUSB-Device User Guide & Reference Manual USB_SETUP_PACKET * pSetupPacket); (c) 2010-2018 SEGGER Microcontroller GmbH 62 CHAPTER 4 4.2.2.9 Target API USBD_SetIsSelfPowered() Description Sets whether the device is self-powered or not. Prototype void USBD_SetIsSelfPowered(U8 IsSelfPowered); Parameters Parameter IsSelfPowered Description * * 0 - Device is not self-powered. 1 - Device is self-powered. Additional information This function has to be called before USBD_Start(), as it will specify if the device is selfpowered or not. The default value is 0 (not self-powered). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 63 CHAPTER 4 4.2.2.10 Target API USBD_SetMaxPower() Description Sets the maximum power consumption reported to the host during enumeration. Prototype void USBD_SetMaxPower(unsigned MaxPower); Parameters Parameter MaxPower Description Current consumption of the device given in mA. MaxPower shall be in range between 0mA - 500mA. Additional information This function shall be called before USBD_Start(), as it will specify how much power the device will consume from the host. If this function is not called, a default value of 100 mA will be used. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 64 CHAPTER 4 4.2.2.11 Target API USBD_SetOnEvent() Description Sets a callback function for an endpoint that will be called on every RX or TX event for that endpoint. Prototype void USBD_SetOnEvent(unsigned EPIndex, USB_EVENT_CALLBACK * pEventCb, USB_EVENT_CALLBACK_FUNC * pfEventCb, void * pContext); Parameters Parameter Description EPIndex Endpoint index returned by USBD_AddEP(). pEventCb Pointer to a USB_EVENT_CALLBACK structure (will be initialized by this function). pfEventCb Pointer to the callback routine that will be called on every event on the USB endpoint. pContext A pointer which is used as parameter for the callback function. Additional information The USB_EVENT_CALLBACK structure is private to the USB stack. It will be initialized by USBD_SetOnEvent(). The USB stack keeps track of all event callback functions using a linked list. The USB_EVENT_CALLBACK structure will be included into this linked list and must reside in static memory. The callback function is called only, if a read or write operation was started for the endpoint using one of the USBD_Read...() or USBD_Write...() functions. Additional information The callback function has the following prototype: typedef void USB_EVENT_CALLBACK_FUNC(unsigned Events, void *pContext); Parameter Description Events A bit mask indicating which events occurred on the endpoint. pContext The pointer which was provided to the USBD_SetOnEvent() function. Note that the callback function will be called within an ISR, therefore it should never block. The first parameter to the callback function will contain a bit mask for all events that triggered the call: Event Description USB_EVENT_DATA_READ Some data was received from the host on the endpoint. USB_EVENT_DATA_SEND Some data was send to the host, so that (part of) the user write buffer may be reused by the application. USB_EVENT_DATA_ACKED Some data was acknowledged by the host. USB_EVENT_READ_COMPLETE The last read operation was completed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 65 CHAPTER 4 Event Target API Description USB_EVENT_READ_ABORT A read transfer was aborted. USB_EVENT_WRITE_ABORT A write transfer was aborted. USB_EVENT_WRITE_COMPLETE All write operations were completed. Example // The callback function. static void _OnEvent(unsigned Events, void *pContext) { if ((Events & USB_EVENT_DATA_SEND) != 0 && // Check for last write transfer to be completed. USBD_GetNumBytesToWrite(_hInst) == 0) { <.. prepare next data for writing..> // Send next packet of data. r = USBD_Write(EPIndex, &ac[0], 200, 0, -1); if (r < 0) { <.. error handling..> } } } // Main programm. // Register callback function. static USB_EVENT_CALLBACK _usb_callback; USBD_SetOnEvent(EPIndex, &_usb_callback, _OnEvent, NULL); // Send the first packet of data using an asynchronous write operation. r = USBD_Write(EPIndex, &ac[0], 200, 0, -1); if (r < 0) { <.. error handling..> } <.. do anything else here while the whole data is send..> emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 66 CHAPTER 4 4.2.2.12 Target API USBD_RemoveOnEvent() Description Removes a callback function which was added via USBD_SetOnEvent from the callback list. Prototype void USBD_RemoveOnEvent( unsigned EPIndex, const USB_EVENT_CALLBACK * pEventCb); Parameters Parameter Description EPIndex Endpoint index returned by USBD_AddEP(). pEventCb Pointer to a USB_EVENT_CALLBACK structure which was used with USBD_SetOnEvent. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 67 CHAPTER 4 4.2.2.13 Target API USBD_SetOnRxEP0() Description Sets a callback when data are received in the data stage of the setup request. Prototype void USBD_SetOnRxEP0(USB_ON_RX_FUNC * pfOnRx); Parameters Parameter pfOnRx Description Pointer to a function that should be called when receiving data other than setup packets on EP0. Additional information Please note that this function can be called multiple times from different classes in order to check the data. Note that the callback will be called within an ISR, therefore it should never block. If it is necessary to send data from the callback function through endpoint 0, use the function USBD_WriteEP0FromISR(). USB_ON_RX_FUNC is defined as follows: typedef void USB_ON_RX_FUNC(const U8 * pData, unsigned NumBytes); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 68 CHAPTER 4 4.2.2.14 Target API USBD_SetOnSetupHook() Description Sets a callback function that is called when any setup request is sent from the host for the specified interface index. Prototype void USBD_SetOnSetupHook(unsigned InterfaceNum, USB_ON_SETUP * pfOnSetup); Parameters Parameter Description InterfaceNum Interface index that for setting the setup request callback. pfOnSetup Pointer to the callback. Additional information Note that the callback will be called within an ISR, therefore it should never block. If it is necessary to send data from the callback function through endpoint 0, use the function USBD_WriteEP0FromISR(). USB_ON_SETUP is defined as follows: typedef int USB_ON_SETUP(const USB_SETUP_PACKET * pSetupPacket); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 69 CHAPTER 4 4.2.2.15 Target API USBD_WriteEP0FromISR() Description Write data to EP0 (control endpoint). This function may be called in an interrupt context. Prototype void USBD_WriteEP0FromISR(const void * pData, unsigned NumBytes, char Send0PacketIfRequired); Parameters Parameter Description pData Data that should be written. NumBytes Number of bytes to write. Send0PacketIfRequired Specifies that a zero-length packet should be sent when the last data packet to the host is a multiple of MaxPacketSize. Normally MaxPacketSize for control mode transfer is 64 byte. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 70 CHAPTER 4 4.2.2.16 Target API USBD_EnableIAD() Description Enables combination of multi-interface device classes with single-interface classes or other multi-interface classes. Prototype void USBD_EnableIAD(void); Additional information Simple device classes such as HID and MSD or BULK use only one interface descriptor to describe the class. The interface descriptor also contains the device class code. The CDC device class uses more than one interface descriptor to describe the class. The device class code will then be written into the device descriptor. It may be possible to add an interface which does not belong to the CDC class, but it may not be correctly recognized by the host, this is not standardized and depends on the host. In order to allow this, a new descriptor type was introduced: IAD (Interface Association Descriptor), this descriptor will encapsulate the multi-interface class into this IA descriptor, so that it will be seen as one single interface and will then allow to add other device classes. If you intend to use the CDC component with any other component, please call USBD_EnableIAD() before adding the CDC component through USBD_CDC_Add(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 71 CHAPTER 4 4.2.2.17 Target API USBD_SetCacheConfig() Description Configures cache related functionality that might be required by the stack for cache handling in drivers. Prototype void USBD_SetCacheConfig(const SEGGER_CACHE_CONFIG * pConfig, unsigned ConfSize); Parameters Parameter Description pConfig Pointer to an element of SEGGER_CACHE_CONFIG . ConfSize Size of the passed structure in case library and header size of the structure differs. Additional information This function has to called in USBD_X_Config(). This function replaces the legacy cache functions BSP_CACHE_CleanRange and BSP_CACHE_InvalidateRange. If you still want to use these routines please set USBD_USE_LEGACY_CACHE_ROUTINES to 1 in your USB_Conf.h file. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 72 CHAPTER 4 4.2.2.18 Target API USBD_RegisterSCHook() Description Sets a callback function that will be called on every state change of the USB device. Prototype int USBD_RegisterSCHook(USB_HOOK * pHook, USB_STATE_CALLBACK_FUNC * pfStateCb, void * pContext); Parameters Parameter Description pHook Pointer to a USB_HOOK structure (will be initialized by this function). pfStateCb Pointer to the callback routine that will be called on every state change. pContext A pointer which is used as parameter for the callback function. Return value 0 1 OK. Error, specified hook already exists. Additional information The USB_HOOK structure is private to the USB stack. It will be initialized by USBD_RegisterSCHook(). The USB stack keeps track of all state change callback functions using a linked list. The USB_HOOK structure will be included into this linked list and must reside in static memory. Note that the callback function will be called within an ISR, therefore it should never block. Example // The callback function. static void _OnStateChange(void *pContext, U8 NewState) { if ((NewState & (USB_STAT_CONFIGURED | USB_STAT_SUSPENDED)) == USB_STAT_CONFIGURED) { // Device is enumerated } else { // Device not enumerated } } // Main programm. static USB_HOOK Hook; USBD_Init(); ... USBD_RegisterSCHook(&Hook, _OnStateChange, NULL); ... USBD_Start(); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 73 CHAPTER 4 4.2.3 4.2.3.1 Target API USB I/O functions USBD_Read() Description Reads data from the host. Prototype int USBD_Read(unsigned EPOut, void * pData, unsigned NumBytesReq, unsigned Timeout); Parameters Parameter Description EPOut Handle to an OUT endpoint returned by USBD_AddEP(). pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Timeout Timeout given in milliseconds. A zero value results in an infinite timeout. Return value = NumBytes 0 && < NumBytes <0 Requested data was successfully read within the given timeout. Timeout has occurred (Number of bytes read before timeout). An error occurred. Additional information This function blocks the task until all data has been read or a timeout occurs. In case of a reset or a disconnect USB_STATUS_ERROR is returned. If the USB stack receives a data packet from the host containing more bytes than requested, the remaining bytes are stored into the internal buffer of the endpoint, that was provided via the USBD_AddEP() function. This data can be retrieved by a later call to USBD_Receive() or USBD_Read(). See also USBD_GetNumBytesInBuffer(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 74 CHAPTER 4 4.2.3.2 Target API USBD_ReadOverlapped() Description Reads data from the host asynchronously. Prototype int USBD_ReadOverlapped(unsigned EPOut, void * pData, unsigned NumBytesReq); Parameters Parameter Description EPOut Handle to an OUT endpoint returned by USBD_AddEP(). pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Return value 0 =0 <0 Number of bytes that have been read from the internal buffer (success). No data was found in the internal buffer (success). An error occurred. Additional information This function will not block the calling task. The read transfer will be initiated and the function returns immediately. In order to synchronize, USBD_WaitForEndOfTransfer() needs to be called. Another synchronization method would be to periodically call USBD_GetNumBytesRemToRead() in order to see how many bytes still need to be received (this method is preferred when a non-blocking solution is necessary). The read operation can be canceled using USBD_CancelIO(). The buffer pointed to by pData must be valid until the read operation is terminated. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 75 CHAPTER 4 4.2.3.3 Target API USBD_Receive() Description Reads data from host. The function blocks until any data have been received. In contrast to USBD_Read() this function does not wait for all of NumBytes to be received, but returns after the first packet has been received or after the timeout occurs. Prototype int USBD_Receive(unsigned EPOut, void * pData, unsigned NumBytesReq, int Timeout); Parameters Parameter Description EPOut Handle to an OUT endpoint returned by USBD_AddEP(). pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Timeout Timeout given in milliseconds. A zero value results in an infinite timeout. If Timeout is -1, the function never blocks. Return value >0 =0 <0 Number of bytes that have been read within the given timeout. A timeout occurred (if Timeout > 0), zero packet received (not every controller supports this!), no data in buffer (if Timeout < 0) or the target was disconnected during the function call and no data was read so far. An error occurred. Additional information If no error occurs, this function returns the number of bytes received. Calling USBD_Receive() will return as much data as is currently available up to the size of the buffer specified within the specified timeout. This function also returns when the target is disconnected from the host or when a USB reset occurred during the function call, it will then return the number of bytes read so far. If the target was disconnected before this function was called, it returns USB_STATUS_ERROR. If the USB stack receives a data packet from the host containing more bytes than requested, the remaining bytes are stored into the internal buffer of the endpoint, that was provided via USBD_AddEP(). This data can be retrieved by a later call to USBD_Receive() / USBD_Read(). See also USBD_GetNumBytesInBuffer(). A call of USBD_Receive(EPOut, NULL, 0, -1) can be used to trigger an asynchronous read that stores the data into the internal buffer. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 76 CHAPTER 4 4.2.3.4 Target API USBD_Write() Description Writes data to the host. Depending on the Timeout parameter, the function may block until NumBytes have been written or a timeout occurs. Prototype int USBD_Write( unsigned EPIndex, const void * pData, unsigned NumBytes, char Send0PacketIfRequired, int ms); Parameters Parameter Description EPIndex Handle to an IN endpoint returned by USBD_AddEP(). pData Pointer to data that should be sent to the host. NumBytes Number of bytes to be written. Send0PacketIfRequired Specifies that a zero-length packet should be sent when the last data packet to the host is a multiple of MaxPacketSize. Timeout Timeout in milliseconds. 0 means infinite. If Timeout is -1, the function returns immediately and the transfer is processed asynchronously. Return value =0 > 0 && < NumBytes = NumBytes <0 Successful started an asynchronous write transfer or a timeout has occurred and no data was written. Number of bytes that have been written before a timeout occurred. Write transfer successful completed. An error occurred. Additional information This function also returns when the target is disconnected from host or when a USB reset occurred. The USB stack is able to queue a small number of asynchronous write transfers (Timeout = -1). If a write transfer is still in progress when this function is called and the USB stack can not accept another write transfer request, the functions returns USB_STATUS_EP_BUSY. A synchronous write transfer (Timeout 0) will always block until the transfer (including all pending transfers) are finished. In order to synchronize, USBD_WaitForEndOfTransfer() needs to be called. Another synchronization method would be to periodically call USBD_GetNumBytesRemToWrite() in order to see how many bytes still need to be written (this method is preferred when a nonblocking solution is necessary). The write operation can be canceled using USBD_CancelIO(). If pData = NULL and NumBytes = 0, a zero-length packet is sent to the host. The content of the buffer pointed to by pData must not be changed until the transfer has been completed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 77 CHAPTER 4 4.2.3.5 Target API USBD_CancelIO() Description Cancel any read or write operation. Prototype void USBD_CancelIO(unsigned EPIndex); Parameters Parameter EPIndex Description Handle to an endpoint returned by USBD_AddEP(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 78 CHAPTER 4 4.2.3.6 Target API USBD_WaitForEndOfTransfer() Description Wait until the current transfer on a particular EP has completed. This function must be called from a task. Prototype int USBD_WaitForEndOfTransfer(unsigned EPIndex, unsigned Timeout); Parameters Parameter Description EPIndex Handle to the endpoint returned by USBD_AddEP(). Timeout Timeout in milliseconds, 0 means infinite wait. Return value 0 1 Transfer completed. Timeout occurred. Additional information In case of a timeout, a current transfer is canceled. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 79 CHAPTER 4 4.2.3.7 Target API USBD_WaitForTXReady() Description Waits (blocking) until the TX queue can accept another data packet. This function is used in combination with a non-blocking call to USBD_Write(), it waits until a new asynchronous write data transfer will be accepted by the USB stack. Prototype int USBD_WaitForTXReady(unsigned EPIndex, int Timeout); Parameters Parameter Description EPIndex Handle to an IN endpoint returned by USBD_AddEP(). Timeout Timeout in milliseconds. 0 means infinite. If Timeout is negative, the function will return immediately. Return value =0 =1 <0 A new asynchronous write data transfer will be accepted. The write queue is full, a call to USBD_Write() would return USB_STATUS_EP_BUSY. Error occurred. Additional information If Timeout is 0, the function never returns 1. If Timeout is -1, the function will not wait, but immediately return the current state. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 80 CHAPTER 4 4.2.3.8 Target API USBD_GetNumBytesInBuffer() Description Returns the number of bytes that are available in the internal BULK-OUT endpoint buffer. Prototype unsigned USBD_GetNumBytesInBuffer(unsigned EPIndex); Parameters Parameter EPIndex Description Handle to an OUT endpoint returned by USBD_AddEP(). Return value Number of bytes which have been stored in the internal buffer. Additional information The number of bytes returned by this function can be read using USBD_Read() or USBD_Receive() without blocking. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 81 CHAPTER 4 4.2.3.9 Target API USBD_GetNumBytesRemToRead() Description This function is to be used in combination with USBD_ReadOverlapped(). It returns the number of bytes which still have to be read during the transaction. Prototype unsigned USBD_GetNumBytesRemToRead(unsigned EPIndex); Parameters Parameter EPIndex Description Handle to an OUT endpoint returned by USBD_AddEP(). Return value Number of bytes which still have to be read. Additional information Note that this function does not return the number of bytes that have been read, but the number of bytes which still have to be read. This function does not block. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 82 CHAPTER 4 4.2.3.10 Target API USBD_GetNumBytesRemToWrite() Description This function is to be used in combination with a non-blocking call to USBD_Write(). It returns the number of bytes which still have to be written during the transaction. Prototype unsigned USBD_GetNumBytesRemToWrite(unsigned EPIndex); Parameters Parameter EPIndex Description Handle to an IN endpoint returned by USBD_AddEP(). Return value Number of bytes which still have to be written. Additional information Note that this function does not return the number of bytes that have been written, but the number of bytes which still have to be written. This function does not block. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 83 CHAPTER 4 4.2.3.11 Target API USBD_StallEP() Description Stalls an endpoint. Prototype void USBD_StallEP(unsigned EPIndex); Parameters Parameter EPIndex Description Handle to the endpoint handle returned by USBD_AddEP(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 84 CHAPTER 4 4.2.4 Target API USB Remote wakeup functions Remote wakeup is a feature that allows a device to wake a host system from a USB suspend state. In order to do this a special resume signal is sent over the USB data lines. Additionally the USB host controller and operating system has to be able to handle this signaling. Windows OS Currently Windows OS only supports the wakeup feature on devices based on HID mouse/ keyboard, CDC Modem and RNDIS Ethernet class. Remote wakeup for MSD, generic bulk and CDC serial is not supported by Windows. So therefore a HID mouse class even as dummy interface within your USB configuration is currently mandatory. Windows must also be told that the device shall wake the PC from the suspend state. This is done by setting the option "Allow this device to bring the computer out of standby". macOS macOS supports remote wakeup for all device classes. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 85 CHAPTER 4 4.2.4.1 Target API USBD_SetAllowRemoteWakeUp() Description Allows the device to publish that remote wake is available. Prototype void USBD_SetAllowRemoteWakeUp(U8 AllowRemoteWakeup); Parameters Parameter AllowRemoteWakeup Description * * 1 - Allows and publishes that remote wakeup is available. 0 - Publish that remote wakeup is not available. Additional information This function must be called before the function USBD_Start() is called. This ensures that the Host is informed that USB remote wake up is available. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 86 CHAPTER 4 4.2.5 4.2.5.1 Target API Data structures USB_ADD_EP_INFO Description Structure used by USBD_AddEPEx() when adding an endpoint. Type definition typedef struct { U8 Flags; U8 InDir; U8 TransferType; U16 Interval; unsigned MaxPacketSize; } USB_ADD_EP_INFO; Structure members Member Description Flags Reserved. Must be zero. InDir Specifies the direction of the desired endpoint. * USB_DIR_IN * USB_DIR_OUT TransferType Specifies the transfer type of the endpoint. The following values are allowed: * USB_TRANSFER_TYPE_BULK * USB_TRANSFER_TYPE_ISO * USB_TRANSFER_TYPE_INT Interval Specifies the interval measured in units of 125us (microframes). This value should be zero for a bulk endpoint. MaxPacketSize Maximum packet size for the endpoint. Additional information The Interval parameter specifies the frequency in which the endpoint should be polled for information by the host. It must be specified in units of 125 us. Depending on the actual speed of the device during enumeration, the USB stack converts the interval to the correct value required for the endpoint descriptor according to the USB specification (into milliseconds for low/full speed, into 125 us for high speed). For endpoints of type USB_TRANSFER_TYPE_BULK the value is ignored and should be set to 0. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 87 CHAPTER 4 4.2.5.2 Target API SEGGER_CACHE_CONFIG Description Used to pass cache configuration and callback function pointers to the stack. Prototype typedef struct { int CacheLineSize; void (*pfDMB) (void); void (*pfClean) (void *p, unsigned NumBytes); void (*pfInvalidate)(void *p, unsigned NumBytes); } SEGGER_CACHE_CONFIG; Member Description CacheLineSize Length of one cache line of the CPU. = 0: No Cache. > 0: Cache line size in bytes. Most Systems such as ARM9 use a 32 bytes cache line size. pfDMB Pointer to a callback function that executes a DMB (Data Memory Barrier) instruction to make sure all memory operations are completed. Can be NULL. pfClean Pointer to a callback function that executes a clean operation on cached memory. Can be NULL. pfInvalidate Pointer to a callback function that executes an invalidate operation on cached memory. Can be NULL. Additional information For further information about how this structure is used please refer to USBD_SetCacheConfig on page 71. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 5 Bulk communication This chapter describes how to get emUSB-Device-Bulk up and running. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 89 5.1 CHAPTER 5 Generic bulk stack Generic bulk stack The generic bulk stack is located in the directory USB. All C files in the directory should be included in the project (compiled and linked as part of your project). The files in this directory are maintained by SEGGER and should not require any modification. All files requiring modifications have been placed in other directories. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 90 CHAPTER 5 5.2 Requirements for the Host (PC) Requirements for the Host (PC) In order to communicate with a target (client) running emUSB-Device, the operating system running on the host must recognize the device connected to it. 5.2.1 Windows Microsoft's Windows operating systems (Starting with XP Service Pack 2) contains a generic driver called WinUSB.sys that is used to handle all communication to a emUSB-Device running a BULK interface. If a emUSB bulk device is connected to a Windows 8, 8.1 and 10 PC for the first time, Windows will install the WinUSB driver automatically. For Windows versions less than Windows 8. Windows provides a driver for Windows Vista and Windows 7 but this needs to be installed manually. A driver installation tool including the mentioned driver is available in the Windows\USB\Bulk\WinUSBInstall. Windows XP user can use the driver package located under Windows\USB\Bulk\WinUSB_USBBulk_XP. In order to get emUSB BULK running with the WinUSB driver the following must be considered: * * 5.2.2 The function USBD_BULK_SetMSDescInfo() must be called in the target application. The Product IDs 1234 and 1121 must not be used. Linux Linux can handle emUSB BULK devices out of the box. By default a USB device can only be accessed by a process that is running with "root" rights. In order to use the USB bulk device from normal user programs an udev rule has to be configured for the device (refer to the linux udev documentation). The emUSB-Device release contains a sample configuration file 99-emUSBD.rules, which may be modified and copied to /etc/udev/rules.d on the host machine. 5.2.3 macOS macOS can handle emUSB BULK devices out of the box. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 91 5.3 CHAPTER 5 Example application Example application Example applications for both the target (client) and the PC (host) are supplied. These can be used for testing the correct installation and proper function of the device running emUSB-Device. The host sample applications can be used for Windows, Linux and MacOSX. Precompiled executables for Windows can be found in the subfolder Windows/USB/Bulk/WindowsApplication/Exe. For example: The application USB_BULK_Echo1.c is a modified echo server; the application receives data byte by byte, increments every single byte and sends it back to the host. To use this application, make sure to use the corresponding example files both on the hostside as on the target side. The example applications on the PC host are named in the same way, just without the prefix USB_BULK_ , for example, if the host runs Echo1.exe, USB_BULK_Echo1.c has to be included into your project, compiled and downloaded into your target. There are additional examples that can be used for testing emUSB-Device. The following start application files are provided: File Description USB_BULK_Echo1.c This application was described in the upper text. USB_BULK_EchoFast.c This is the faster version of USB_BULK_Echo1.c. USB_BULK_Test.c This application can be used to test emUSB-Device-Bulk with different packet sizes received from and sent to the PC host. USB_BULK_Performance.c Measures BULK data throughput. The example applications for the target-side are supplied in source code in the Application directory. Depending on which application is running on the emUSB-Device device, use one of the following example applications: emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 92 CHAPTER 5 File Example application Description Echo1.exe If the USB_BULK_Echo1.c sample application is running on the emUSB-Device-Bulk device, use this application. EchoFast.exe If the USB_BULK_EchoFast.c sample application is running on the emUSB-Device-Bulk device, use this application. Test.exe If the USB_BULK_Test.c application is running on the emUSB-Device-Bulk device, use this application to test the emUSB-Device-Bulk stack. Performance.exe If the USB_BULK_Performace.c application is running on the emUSB-Device-Bulk device, use this application to measures BULK data throughput. For information how to compile the host examples (especially for Linux and MacOSX) refer to Compiling the PC example application on page 93. The start application will of course later on be replaced by the real application program. For the purpose of getting emUSB-Device up and running as well as doing an initial test, the start application should not be modified. 5.3.1 Running the example applications To test the emUSB-Device-Bulk component, build and download the application of choice for the target-side. To run one of the example applications, simply start the executable, for example by double clicking it. If a connection can be established, it exchanges data with the target, testing the USB connection. Example output of Echo1.exe: If the host example application can communicate with the emUSB-Device device, the example application will be in interactive mode for the Echo1 and the EchoFast application. In case of an error, a message box is displayed. Error Messages Description Unable to connect to USB BULK device The USB device is not connected to the PC or the connection is faulty. Could not write to device The PC sample application was not able to write. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 93 CHAPTER 5 Error Messages Example application Description Could not read from device (time-out) The PC sample application was not able to read. Wrong data read The result of the target sample application is not correct. 5.3.2 5.3.2.1 Compiling the PC example application Windows For compiling the example application you need Visual C++ 2010 (or later). The source code of the sample application is located in the subfolder Windows\USB\Bulk \WindowsApplication. Open the file USBBULK_Start.sln and compile the source. 5.3.2.2 Linux The subfolder Windows\USB\Bulk\WindowsApplication contains a Makefile for Linux. Change to this folder and execute "make". 5.3.2.3 macOS The subfolder Windows\USB\Bulk\WindowsApplication contains a Makefile for macOS. Change to this folder and execute "make -f Makefile_MacOSX". emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 94 CHAPTER 5 5.4 Target API Target API This chapter describes the functions that can be used with the target system. General information To communicate with the host, the sample application project includes USB-specific header and source files (USB.h, USB_Main.c, USB_Setup.c, USB_Bulk.c, USB_Bulk.h). These files contain API functions to communicate with the USB host through the emUSB-Device driver. Purpose of the USB Device API functions To have an easy start up when writing an application on the device side, these API functions have a simple interface and handle all operations that need to be done to communicate with the hosts kernel. Therefore, all operations that need to write to or read from the emUSB-Device are handled internally by the provided API functions. 5.4.1 Target interface function list Routine Explanation USB-Bulk functions USBD_BULK_Add() Adds interface for USB-Bulk communication to emUSB-Device. USBD_BULK_Add_Ex() Adds interface for USB-Bulk communication to emUSB-Device. USBD_BULK_SetMSDescInfo() Enables use of Microsoft OS Descriptors. USBD_BULK_CancelRead() Cancels any non-blocking/blocking read operation that is pending. USBD_BULK_CancelWrite() Cancels any non-blocking/blocking write operation that is pending. USBD_BULK_GetNumBytesInBuffer() Returns the number of bytes that are available in the internal BULK-OUT endpoint buffer. USBD_BULK_GetNumBytesRemToRead() Get the number of remaining bytes to read by an active read operation. USBD_BULK_GetNumBytesRemToWrite() After starting a non-blocking write operation this function can be used to periodically check how many bytes still have to be written. USBD_BULK_Read() Reads data from the host with a given timeout. USBD_BULK_ReadOverlapped() Reads data from the host asynchronously. USBD_BULK_Receive() Reads data from the host. USBD_BULK_SetContinuousReadMode() Enables continuous read mode for the RX endpoint. USBD_BULK_SetOnRXEvent() Sets a callback function for the OUT endpoint that will be called on every RX event for that endpoint. USBD_BULK_SetOnTXEvent() Sets a callback function for the IN endpoint that will be called on every TX event for that endpoint. USBD_BULK_TxIsPending() Checks whether the TX (IN endpoint) is currently pending. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 95 CHAPTER 5 Routine Target API Explanation USBD_BULK_WaitForRX() Waits (blocking) until the triggered USBD_BULK_ReadOverlapped() has received the desired data. USBD_BULK_WaitForTX() Waits (blocking) until the triggered USBD_BULK_WriteOverlapped() has sent the desired data. USBD_BULK_WaitForTXReady() Waits (blocking) until the TX queue can accept another data packet. USBD_BULK_Write() Sends data to the USB host. USBD_BULK_WriteEx() Send data to the USB host with NULL packet control. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 96 CHAPTER 5 5.4.2 5.4.2.1 Target API USB-Bulk functions USBD_BULK_Add() Description Adds interface for USB-Bulk communication to emUSB-Device. Prototype USB_BULK_HANDLE USBD_BULK_Add(const USB_BULK_INIT_DATA * pInitData); Parameters Parameter pInitData Description Pointer to USB_BULK_INIT_DATA structure. Return value Handle to a valid BULK instance. The handle of the first BULK instance is always 0. Example Example excerpt from BULK_Echo1.c: static void _AddBULK(void) { static U8 _abOutBuffer[USB_HS_BULK_MAX_PACKET_SIZE]; USB_BULK_INIT_DATA Init; Init.EPIn = USBD_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, NULL, 0); Init.EPOut = USBD_AddEP(USB_DIR_OUT, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, _abOutBuffer, USB_HS_BULK_MAX_PACKET_SIZE); USBD_BULK_Add(&Init); } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 97 CHAPTER 5 5.4.2.2 Target API USBD_BULK_Add_Ex() Description Adds interface for USB-Bulk communication to emUSB-Device. Prototype USB_BULK_HANDLE USBD_BULK_Add_Ex(const USB_BULK_INIT_DATA_EX * pInitData); Parameters Parameter pInitData Description Pointer to USB_BULK_INIT_DATA_EX structure. Return value Handle to a valid BULK instance. The handle of the first BULK instance is always 0. Example static void _AddBULK(void) { static U8 _abOutBuffer[USB_HS_BULK_MAX_PACKET_SIZE]; USB_BULK_INIT_DATA_EX Init; Init.Flags = 0; Init.EPIn = USBD_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, NULL, 0); Init.EPOut = USBD_AddEP(USB_DIR_OUT, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, _abOutBuffer, USB_HS_BULK_MAX_PACKET_SIZE); Init.pInterfaceName = "BULK Interface"; USBD_BULK_Add_Ex(&Init); } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 98 CHAPTER 5 5.4.2.3 Target API USBD_BULK_SetMSDescInfo() Description Enables use of Microsoft OS Descriptors. A USB bulk device providing these descriptors is detected by Windows to be handled by the generic WinUSB driver. For such devices no other driver needs to be installed. Prototype void USBD_BULK_SetMSDescInfo(USB_BULK_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid BULK instance, returned by USBD_BULK_Add(). Additional information This function must be called after the call to the function USBD_BULK_Add() and before USBD_Start(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 99 CHAPTER 5 5.4.2.4 Target API USBD_BULK_CancelRead() Description Cancels any non-blocking/blocking read operation that is pending. Prototype void USBD_BULK_CancelRead(USB_BULK_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid BULK instance, returned by USBD_BULK_Add(). Additional information This function shall be called when a pending asynchronous read operation should be canceled. The function can be called from any task. In case of canceling a blocking operation, this function must be called from another task. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 100 CHAPTER 5 5.4.2.5 Target API USBD_BULK_CancelWrite() Description Cancels any non-blocking/blocking write operation that is pending. Prototype void USBD_BULK_CancelWrite(USB_BULK_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid BULK instance, returned by USBD_BULK_Add(). Additional information This function shall be called when a pending asynchronous write operation should be canceled. The function can be called from any task. In case of canceling a blocking operation, this function must be called from another task. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 101 CHAPTER 5 5.4.2.6 Target API USBD_BULK_GetNumBytesInBuffer() Description Returns the number of bytes that are available in the internal BULK-OUT endpoint buffer. Prototype unsigned USBD_BULK_GetNumBytesInBuffer(USB_BULK_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid BULK instance, returned by USBD_BULK_Add(). Return value Number of bytes that are available in the internal BULK-OUT endpoint buffer. Additional information If the host is sending more data than your target application has requested, the remaining data will be stored in an internal buffer. This function shows how many bytes are available in this buffer. The number of bytes returned by this function can be read using USBD_BULK_Read() without blocking. Example Your host application sends 50 bytes. Your target application only requests to receive 1 byte. In this case the target application will get 1 byte and the remaining 49 bytes are stored in an internal buffer. When your target application now calls USBD_BULK_GetNumBytesInBuffer() it will return the number of bytes that are available in the internal buffer (49). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 102 CHAPTER 5 5.4.2.7 Target API USBD_BULK_GetNumBytesRemToRead() Description Get the number of remaining bytes to read by an active read operation. This function is to be used in combination with USBD_BULK_ReadOverlapped(). After starting the read operation this function can be used to periodically check how many bytes still have to be read. Prototype unsigned USBD_BULK_GetNumBytesRemToRead(USB_BULK_HANDLE hInst); Parameters Parameter Description Handle to a valid BULK instance, returned by USBD_BULK_Add(). hInst Return value 0 <0 Number of bytes which have not yet been read. Error occurred. Additional information Alternatively the blocking function USBD_BULK_WaitForRX() can be used. Example NumBytesReceived = USBD_BULK_ReadOverlapped(hInst, &ac[0], 50); if (NumBytesReceived < 0) { <.. error handling..> } if (NumBytesReceived > 0) { // Already had some data in the internal buffer. // The first 'NumBytesReceived' bytes may be processed here. <...> } else { // Wait until we get all 50 bytes while (USBD_BULK_GetNumBytesRemToRead(hInst) > 0) { USB_OS_Delay(50); } } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 103 CHAPTER 5 5.4.2.8 Target API USBD_BULK_GetNumBytesRemToWrite() Description After starting a non-blocking write operation this function can be used to periodically check how many bytes still have to be written. Prototype unsigned USBD_BULK_GetNumBytesRemToWrite(USB_BULK_HANDLE hInst); Parameters Parameter Description Handle to a valid BULK instance, returned by USBD_BULK_Add(). hInst Return value 0 <0 Number of bytes which have not yet been written. Error occurred. Additional information Alternatively the blocking function USBD_BULK_WaitForTX() can be used. Example r = USBD_BULK_Write(hInst, &ac[0], TRANSFER_SIZE, -1); if (r < 0) { <.. error handling..> } // NumBytesToWrite shows how many bytes still have to be written. while (USBD_BULK_GetNumBytesRemToWrite(hInst) > 0) { USB_OS_Delay(50); } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 104 CHAPTER 5 5.4.2.9 Target API USBD_BULK_Read() Description Reads data from the host with a given timeout. Prototype int USBD_BULK_Read(USB_BULK_HANDLE hInst, void * pData, unsigned NumBytes, unsigned Timeout); Parameters Parameter Description hInst Handle to a valid BULK instance, returned by USBD_BULK_Add(). pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Timeout Timeout in milliseconds, 0 means infinite. Return value = NumBytes 0 && < NumBytes <0 Requested data was successfully read within the given timeout. Timeout has occurred. Number of bytes that have been read within the given timeout. Error occurred. Additional information This function blocks a task until all data have been read or a timeout expires. This function also returns when the device is disconnected from host or when a USB reset occurs. If the USB stack receives a data packet from the host containing more bytes than requested, the remaining bytes are stored into the internal buffer of the endpoint, that was provided via USBD_AddEP(). This data can be retrieved by a later call to USBD_BULK_Receive() / USBD_BULK_Read(). See also USBD_BULK_GetNumBytesInBuffer(). If a read transfer was still pending while the function is called, it returns USB_STATUS_EP_BUSY. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 105 CHAPTER 5 5.4.2.10 Target API USBD_BULK_ReadOverlapped() Description Reads data from the host asynchronously. Prototype int USBD_BULK_ReadOverlapped(USB_BULK_HANDLE hInst, void * pData, unsigned NumBytes); Parameters Parameter Description hInst Handle to a valid BULK instance, returned by USBD_BULK_Add(). pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Return value >0 =0 <0 Number of bytes that have been read from the internal buffer (success). No data was found in the internal buffer (success). Error occurred. Additional information This function will not block the calling task. The read transfer will be initiated and the function returns immediately. In order to synchronize, USBD_BULK_WaitForRX() needs to be called. Alternatively the function USBD_BULK_GetNumBytesRemToRead() can be called periodically to check whether all bytes have been read or not. The read operation can be canceled using USBD_BULK_CancelRead(). The buffer pointed to by pData must be valid until the read operation is terminated. If a read transfer was still pending while the function is called, it returns USB_STATUS_EP_BUSY. Example See USBD_BULK_GetNumBytesRemToRead on page 102. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 106 CHAPTER 5 5.4.2.11 Target API USBD_BULK_Receive() Description Reads data from the host. The function blocks until any data has been received or a timeout occurs (if Timeout 0). In contrast to USBD_BULK_Read() this function does not wait for all of NumBytes to be received, but returns after the first packet has been received. Prototype int USBD_BULK_Receive(USB_BULK_HANDLE hInst, void * pData, unsigned NumBytes, int Timeout); Parameters Parameter Description hInst Handle to a valid BULK instance, returned by USBD_BULK_Add(). pData Pointer to a buffer where the received data will be stored. NumBytes Maximum number of bytes to read. Timeout Timeout in milliseconds. 0 means infinite. If Timeout is -1, the function never blocks. Return value >0 =0 <0 Number of bytes that have been read. A timeout occurred (if Timeout > 0), zero packet received (not every controller supports this!), no data in buffer (if Timeout < 0) or the target was disconnected during the function call and no data was read so far. Error occurred. Additional information If no error occurs, this function returns the number of bytes received. Calling USBD_BULK_Receive() will return as much data as is currently available -- up to the size of the buffer specified. This function also returns when the target is disconnected from the host or when a USB reset occurred during the function call, it will then return USB_STATUS_ERROR. If a read transfer was pending while the function is called, it returns USB_STATUS_EP_BUSY. If the USB stack receives a data packet from the host containing more bytes than requested, the remaining bytes are stored into the internal buffer of the endpoint, that was provided via USBD_AddEP(). This data can be retrieved by a later call to USBD_BULK_Receive() / USBD_BULK_Read(). See also USBD_BULK_GetNumBytesInBuffer(). A call of USBD_BULK_Receive(Inst, NULL, 0, -1) can be used to trigger an asynchronous read that stores the data into the internal buffer. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 107 CHAPTER 5 5.4.2.12 Target API USBD_BULK_SetContinuousReadMode() Description Enables continuous read mode for the RX endpoint. In this mode every finished read transfer will automatically trigger another read transfer, as long as there is enough space in the internal buffer to receive another packet. Prototype void USBD_BULK_SetContinuousReadMode(USB_BULK_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid BULK instance, returned by USBD_BULK_Add(). Additional information To check how many bytes have been read into the buffer, the function USBD_BULK_GetNumBytesInBuffer() may be called. In order to read the data the function USBD_BULK_Receive() needs to be called (non-blocking). The USB stack will use the buffer that was provided by the application with USBD_AddEP(). The transfer speed may be improved, if this buffer has a size of at least 2 * MaxPacketSize. Normally MaxPacketSize for full-speed devices is 64 bytes and for high-speed devices 512 bytes. Example USBD_BULK_SetContinuousReadMode(hInst); <...> for(;;) { // // Fetch data that was already read (non-blocking). // NumBytesReceived = USBD_BULK_Receive(hInst, &ac[0], sizeof(ac), -1); if (NumBytesReceived > 0) { // // We got some data // <.. Process data..> } else { <.. Nothing received yet, do application processing..> } } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 108 CHAPTER 5 5.4.2.13 Target API USBD_BULK_SetOnRXEvent() Description Sets a callback function for the OUT endpoint that will be called on every RX event for that endpoint. Prototype void USBD_BULK_SetOnRXEvent(USB_BULK_HANDLE hInst, USB_EVENT_CALLBACK * pEventCb, USB_EVENT_CALLBACK_FUNC * pfEventCb, void * pContext); Parameters Parameter Description hInst Handle to a valid BULK instance, returned by USBD_BULK_Add(). pEventCb Pointer to a USB_EVENT_CALLBACK structure. The structure is initialized by this function. pfEventCb Pointer to the callback routine that will be called on every event on the USB endpoint. pContext A pointer which is used as parameter for the callback function. Additional information The USB_EVENT_CALLBACK structure is private to the USB stack. It will be initialized by USBD_BULK_SetOnRXEvent(). The USB stack keeps track of all event callback functions using a linked list. The USB_EVENT_CALLBACK structure will be included into this linked list and must reside in static memory. The callback function is called only, if a read operation was started using one of the USBD_BULK_Read...() functions. The callback function has the following prototype: typedef void USB_EVENT_CALLBACK_FUNC(unsigned Events, void *pContext); Parameter Description Events A bit mask indicating which events occurred on the endpoint. pContext The pointer which was provided to the USBD_SetOnEvent() function. Note that the callback function will be called within an ISR, therefore it should never block. The first parameter to the callback function will contain a bit mask for all events that triggered the call: Event Description USB_EVENT_DATA_READ Some data was received from the host on the endpoint. USB_EVENT_READ_COMPLETE The last read operation was completed. USB_EVENT_READ_ABORT A read transfer was aborted. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 109 CHAPTER 5 Target API Example // The callback function. static void _OnEvent(unsigned Events, void *pContext) { unsigned NumBytes; if (Events & USB_EVENT_DATA_READ) { NumBytes = USBD_BULK_GetNumBytesRemToRead(hInst); if (NumBytes) { r = USBD_BULK_Receive(hInst, Buff, NumBytes, -1); if (r > 0) { <.. process data in Buff..> } } } } // Main program. // Register callback function. static USB_EVENT_CALLBACK _usb_callback; USBD_BULK_SetOnRXEvent(hInst, &_usb_callback, _OnEvent, NULL); USBD_BULK_SetContinuousReadMode(hInst); // Trigger first read USBD_BULK_Receive(Inst, NULL, 0, -1); <.. do anything else here while the data is processed in the callback ..> emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 110 CHAPTER 5 5.4.2.14 Target API USBD_BULK_SetOnTXEvent() Description Sets a callback function for the IN endpoint that will be called on every TX event for that endpoint. Prototype void USBD_BULK_SetOnTXEvent(USB_BULK_HANDLE hInst, USB_EVENT_CALLBACK * pEventCb, USB_EVENT_CALLBACK_FUNC * pfEventCb, void * pContext); Parameters Parameter Description hInst Handle to a valid BULK instance, returned by USBD_BULK_Add(). pEventCb Pointer to a USB_EVENT_CALLBACK structure. The structure is initialized by this function. pfEventCb Pointer to the callback routine that will be called on every event on the USB endpoint. pContext A pointer which is used as parameter for the callback function. Additional information The USB_EVENT_CALLBACK structure is private to the USB stack. It will be initialized by USBD_BULK_SetOnTXEvent(). The USB stack keeps track of all event callback functions using a linked list. The USB_EVENT_CALLBACK structure will be included into this linked list and must reside in static memory. The callback function is called only, if a write operation was started using one of the USBD_BULK_Write...() functions. The callback function has the following prototype: typedef void USB_EVENT_CALLBACK_FUNC(unsigned Events, void *pContext); Parameter Description Events A bit mask indicating which events occurred on the endpoint. pContext The pointer which was provided to the USBD_SetOnEvent() function. Note that the callback function will be called within an ISR, therefore it should never block. The first parameter to the callback function will contain a bit mask for all events that triggered the call: Event Description USB_EVENT_DATA_SEND Some data was send to the host, so that (part of) the user write buffer may be reused by the application. USB_EVENT_DATA_ACKED Some data was acknowledged by the host. USB_EVENT_WRITE_ABORT A write transfer was aborted. USB_EVENT_WRITE_COMPLETE All write operations were completed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 111 CHAPTER 5 Target API Example // The callback function. static void _OnEvent(unsigned Events, void *pContext) { if ((Events & USB_EVENT_DATA_SEND) != 0 && // Check for last write transfer to be completed. USBD_BULK_GetNumBytesRemToWrite(_hInst) == 0) { <.. prepare next data for writing..> // Send next packet of data. r = USBD_BULK_Write(_hInst, &ac[0], 200, -1); if (r < 0) { <.. error handling..> } } } // Main program. // Register callback function. static USB_EVENT_CALLBACK _usb_callback; USBD_BULK_SetOnTXEvent(hInst, &_usb_callback, _OnEvent, NULL); // Send the first packet of data using an asynchronous write operation. r = USBD_BULK_Write(_hInst, &ac[0], 200, -1); if (r < 0) { <.. error handling..> } <.. do anything else here while the whole data is send..> emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 112 CHAPTER 5 5.4.2.15 Target API USBD_BULK_TxIsPending() Description Checks whether the TX (IN endpoint) is currently pending. Can be called in any context. Prototype int USBD_BULK_TxIsPending(USB_BULK_HANDLE hInst); Parameters Parameter Description Handle to a valid BULK instance, returned by USBD_BULK_Add(). hInst Return value 1 0 We have queued data to be sent. Queue is empty. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 113 CHAPTER 5 5.4.2.16 Target API USBD_BULK_WaitForRX() Description Waits (blocking) until the triggered USBD_BULK_ReadOverlapped() has received the desired data. Prototype int USBD_BULK_WaitForRX(USB_BULK_HANDLE hInst, unsigned Timeout); Parameters Parameter Description hInst Handle to a valid BULK instance, returned by USBD_BULK_Add(). Timeout Timeout in milliseconds. 0 means infinite. Return value =0 =1 <0 Transfer completed. Timeout occurred. An error occurred (e.g. target disconnected) Additional information In case of a timeout, a current transfer is canceled. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 114 CHAPTER 5 5.4.2.17 Target API USBD_BULK_WaitForTX() Description Waits (blocking) until the triggered USBD_BULK_WriteOverlapped() has sent the desired data. Prototype int USBD_BULK_WaitForTX(USB_BULK_HANDLE hInst, unsigned Timeout); Parameters Parameter Description hInst Handle to a valid BULK instance, returned by USBD_BULK_Add(). Timeout Timeout in milliseconds. 0 means infinite. Return value =0 =1 <0 Transfer completed. Timeout occurred. An error occurred (e.g. target disconnected) Additional information In case of a timeout, a current transfer is canceled. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 115 CHAPTER 5 5.4.2.18 Target API USBD_BULK_WaitForTXReady() Description Waits (blocking) until the TX queue can accept another data packet. This function is used in combination with a non-blocking call to USBD_BULK_Write() , it waits until a new asynchronous write data transfer will be accepted by the USB stack. Prototype int USBD_BULK_WaitForTXReady(USB_BULK_HANDLE hInst, int Timeout); Parameters Parameter Description hInst Handle to a valid BULK instance, returned by USBD_BULK_Add(). Timeout Timeout in milliseconds. 0 means infinite. If Timeout is negative, the function will return immediately. Return value =0 =1 <0 A new asynchronous write data transfer will be accepted. The write queue is full, a call to USBD_BULK_Write() would return USB_STATUS_EP_BUSY. Error occurred. Additional information If Timeout is 0, the function never returns 1. If Timeout is -1, the function will not wait, but immediately return the current state. Example // Always keep the write queue full for maximum send speed. for (;;) { pData = GetNextData(&NumBytes); // Wait until stack can accept a new write. USBD_BULK_WaitForTxReady(hInst, 0); // Issue write transfer. if (USBD_BULK_Write(hInst, pData, NumBytes, -1) < 0) { <.. error handling..> } } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 116 CHAPTER 5 5.4.2.19 Target API USBD_BULK_Write() Description Sends data to the USB host. Depending on the Timeout parameter, the function may block until NumBytes have been written or a timeout occurs. Prototype int USBD_BULK_Write( USB_BULK_HANDLE hInst, const void * pData, unsigned NumBytes, int Timeout); Parameters Parameter Description hInst Handle to a valid BULK instance, returned by USBD_BULK_Add(). pData Data that should be written. NumBytes Number of bytes to write. Timeout Timeout in milliseconds. 0 means infinite. If Timeout is -1, the function returns immediately and the transfer is processed asynchronously. Return value =0 > 0 && < NumBytes = NumBytes <0 Successful started an asynchronous write transfer or a timeout has occurred and no data was written. Number of bytes that have been written before a timeout occurred. Write transfer successful completed. Error occurred. Additional information This function also returns when the target is disconnected from host or when a USB reset occurred. The USB stack is able to queue a small number of asynchronous write transfers (Timeout = -1). If a write transfer is still in progress when this function is called and the USB stack can not accept another write transfer request, the functions returns USB_STATUS_EP_BUSY. A synchronous write transfer (Timeout 0) will always block until the transfer (including all pending transfers) are finished or a timeout occurs. In order to synchronize, USBD_BULK_WaitForTX() needs to be called. Another synchronization method would be to periodically call USBD_BULK_GetNumBytesRemToWrite() in order to see how many bytes still need to be written (this method is preferred when a non-blocking solution is necessary). The write operation can be canceled using USBD_BULK_CancelWrite(). If pData = NULL and NumBytes = 0, a zero-length packet is sent to the host. The content of the buffer pointed to by pData must not be changed until the transfer has been completed. Example NumBytesWritten = USBD_BULK_Write(hInst, &ac[0], DataSize, 500); if (NumBytesWritten < 0) { <.. error handling..> } if (NumBytesWritten < DataSize) { emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 117 CHAPTER 5 Target API <.. timeout occurred, not all data were written within 500ms ..> } else { <.. write successful completed ..> } See also USBD_BULK_GetNumBytesRemToWrite on page 103. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 118 CHAPTER 5 5.4.2.20 Target API USBD_BULK_WriteEx() Description Send data to the USB host with NULL packet control. This function behaves exactly like USBD_BULK_Write(). Additionally sending of a zero length packet after sending the data can be suppressed by setting Send0PacketIfRequired = 0. Prototype int USBD_BULK_WriteEx( USB_BULK_HANDLE hInst, const void * pData, unsigned NumBytes, char Send0PacketIfRequired, int Timeout); Parameters Parameter Description hInst Handle to a valid BULK instance, returned by USBD_BULK_Add(). pData Pointer to a buffer that contains the written data. NumBytes Number of bytes to write. Send0PacketIfRequired Specifies that a zero-length packet shall be sent when the last data packet is a multiple of MaxPacketSize. Normally MaxPacketSize for full-speed devices is 64 bytes. For highspeed devices the normal packet size is between 64 and 512 bytes. Timeout Timeout in milliseconds. 0 means infinite. If Timeout is -1, the function returns immediately and the transfer is processed asynchronously. Return value =0 > 0 && < NumBytes = NumBytes <0 Successful started an asynchronous write transfer or a timeout has occurred and no data was written. Number of bytes that have been written before a timeout occurred. Write transfer successful completed. Error occurred. Additional information Normally USBD_BULK_Write() is called to let the stack send the data to the host and send an optional zero-length packet to tell the host that this was the last packet. This is the case when the last packet sent is MaxPacketSize bytes in size. When using this function, the zero-length packet handling can be controlled. This means the function can be called when sending data in multiple steps. Example // for high speed devices USBD_BULK_Write(hInst, _aBuffer1, 512, 0); USBD_BULK_Write(hInst, _aBuffer2, 512, 0); USBD_BULK_Write(hInst, _aBuffer3, 512, 0); // this will send 6 packets to the host with sizes: 512, 0, 512, 0, 512, 0 USBD_BULK_WriteEx(hInst, _aBuffer1, 512, 0, 0); USBD_BULK_WriteEx(hInst, _aBuffer2, 512, 0, 0); USBD_BULK_WriteEx(hInst, _aBuffer3, 512, 0, 1); // this will send 4 packets to the host with sizes: 512, 512, 512, 0 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 119 CHAPTER 5 5.4.3 Target API Data structures 5.4.3.1 USB_BULK_INIT_DATA Description Initialization structure that is needed when adding a BULK interface to emUSB-Device. Type definition typedef struct { U8 EPIn; U8 EPOut; } USB_BULK_INIT_DATA; Structure members Member Description EPIn Endpoint for sending data to the host. EPOut Endpoint for receiving data from the host. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 120 CHAPTER 5 5.4.3.2 Target API USB_BULK_INIT_DATA_EX Description Initialization structure that is needed when adding a BULK interface to emUSB-Device. Type definition typedef struct { U16 Flags; U8 EPIn; U8 EPOut; const char * pInterfaceName; } USB_BULK_INIT_DATA_EX; Structure members Member Description Flags Reserved for future use, must be 0. EPIn Endpoint for sending data to the host. EPOut Endpoint for receiving data from the host. pInterfaceName Name of the interface. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 121 CHAPTER 5 5.4.4 Target API Multithreading The emUSB BULK target API is not generally thread safe. But it is allowed to handle different endpoints in different tasks in parallel. Examples are: * * A task that performs all reads of data from the host while another task sends data to the host. Operating on different interfaces (e.g. a BULK and a CDC interface) in independent tasks. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 122 CHAPTER 5 5.5 Host API Host API This chapter describes the functions that can be used with the host system. To communicate with the target USB-Bulk stack an API is provided that can be used on Windows, Linux and macOS systems. To have an easy start-up when writing an application on the host side, these API functions have a simple interface and handle all required operations to communicate with the target USB-Bulk stack. Therefore, all operations that need to open a channel, writing to or reading from the USBBulk stack, are handled internally by the provided API functions. To use the API in an application the header file USBBULK.h must be included. Depending on the host operating system used the following components must be added to the host application: * * * Windows: USBBULK.lib and USBBULK.dll (These files are provided for 32- and 64-Bit applications). Linux: USBBULK_Linux.c. macOS: USBBULK_MacOSX.c. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 123 CHAPTER 5 5.5.1 Host API Bulk Host API list The functions below are available on the host (PC) side. Function Description USB-Bulk Basic functions USBBULK_Init() This function needs to be called first. USBBULK_Exit() This is a cleanup function, it shall be called when exiting the application. USBBULK_AddAllowedDeviceItem() Adds the Vendor and Product ID to the list of devices the USBBULK API should look for. USBBULK_GetNumAvailableDevices() Returns the number of connected USBBulk devices. USBBULK_Open() Opens an existing device. USBBULK_Close() Closes an opened device. USB-Bulk direct input/output functions USBBULK_Read() Reads data from target device running emUSB-Device-Bulk. USBBULK_ReadTimed() Reads data from target device running emUSB-Device-Bulk within a given timeout. USBBULK_Write() Writes data to the device. USBBULK_WriteTimed() Writes data to the device within a given timeout. USBBULK_CancelRead() This cancels an initiated read. USBBULK_FlushRx() Flush the any received data. USB-Bulk Control functions USBBULK_SetMode() Sets the read and write mode for a specified device running emUSB-Device-Bulk. USBBULK_GetMode() Returns the current mode of the device. USBBULK_SetReadTimeout() Sets the default read timeout for an opened device. USBBULK_SetWriteTimeout() Sets a default write timeout for an opened device. USBBULK_ResetPipe() Resets the pipes that are opened to the device. USBBULK_ResetDevice() Resets the device via a USB reset. USB-Bulk general GET functions USBBULK_GetVersion() Returns the version number of the USBBULK API. USBBULK_GetDevInfo() Retrieves information about an opened USBBULK device. USBBULK_GetDevInfoByIdx() Retrieves information about a USB device. USBBULK_GetUSBId() Returns the Product and Vendor ID of an opened device. USBBULK_GetProductName() Retrieves the device/product name if available. USBBULK_GetVendorName() Retrieves the vendor name of an opened USBBULK device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 124 CHAPTER 5 Function Host API Description USBBULK_GetSN() Retrieves the USB serial number as a string which was sent by the device during the enumeration. USBBULK_GetConfigDescriptor() Gets the received target USB configuration descriptor of a specified device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 125 CHAPTER 5 5.5.2 5.5.2.1 Host API USB-Bulk Basic functions USBBULK_Init() Description This function needs to be called first. This makes sure to have all structures and thread have been initialized. It also sets a callback in order to be notified when a device is added or removed. Prototype void USBBULK_Init(USBBULK_NOTIFICATION_FUNC * pfNotification, void * pContext); Parameters Parameter Description pfNotification Pointer to the user callback. pContext Context data that shall be called with the callback function. Example /********************************************************************* * * _OnDevNotify * * Function description: * Is called when a new device is found or an existing device is removed. * * Parameters: * pContext - Pointer to a context given when USBBULK_Init is called * Index - Device Index that has been added or removed. * Event - Type of event, currently the following are available: * USBBULK_DEVICE_EVENT_ADD * USBBULK_DEVICE_EVENT_REMOVE * */ static void _OnDevNotify(void * pContext, unsigned Index, USBBULK_DEVICE_EVENT Event) { switch(Event) { case USBBULK_DEVICE_EVENT_ADD: printf("The following DevIndex has been added: %d", Index); NumDevices = USBBULK_GetNumAvailableDevices(&DeviceMask); break; case USBBULK_DEVICE_EVENT_REMOVE: printf("The following DevIndex has been removed: %d", Index); NumDevices = USBBULK_GetNumAvailableDevices(&DeviceMask); break; } } void MainTask(void) { <...> USBBULK_Init(_OnDevNotify, NULL); <...> } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 126 CHAPTER 5 5.5.2.2 Host API USBBULK_Exit() Description This is a cleanup function, it shall be called when exiting the application. Prototype void USBBULK_Exit(void); Additional information We recommend to call this function before exiting the application in order to remove all handles and resources that have been allocated. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 127 CHAPTER 5 5.5.2.3 Host API USBBULK_AddAllowedDeviceItem() Description Adds the Vendor and Product ID to the list of devices the USBBULK API should look for. Prototype void USBBULK_AddAllowedDeviceItem(U16 VendorId, U16 ProductId); Parameters Parameter Description VendorId The desired Vendor ID mask that shall be used with the USBBULK API. ProductId The desired Product ID mask that shall be used with the USBBULK API. Additional information It is necessary to call this function first before calling USBBULK_GetNumAvailableDevices() or opening any connection to a device. The function can be called multiple times to handle more than one pairs of Vendor and Product IDs with the API. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 128 CHAPTER 5 5.5.2.4 Host API USBBULK_GetNumAvailableDevices() Description Returns the number of connected USB-Bulk devices. Prototype unsigned USBBULK_GetNumAvailableDevices(U32 * pMask); Parameters Parameter pMask Description Pointer to a U32 variable to receive the connected device mask. This parameter can be NULL. Return value Number of available devices running emUSB-Device-Bulk. Additional information For each emUSB-Device device that is connected, a bit in pMask is set. For example if device 0 and device 2 are connected to the host, the value pMask points to will be 0x00000005. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 129 CHAPTER 5 5.5.2.5 Host API USBBULK_Open() Description Opens an existing device. The ID of the device can be retrieved by the function USBBULK_GetNumAvailableDevices() via the pDeviceMask parameter. Each bit set in the DeviceMask represents an available device. Currently 32 devices can be managed at once. Prototype USB_BULK_HANDLE USBBULK_Open(unsigned Id); Parameters Parameter Description Device ID to be opened (0..31). Id Return value 0 =0 Handle to the opened device. Error occurred. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 130 CHAPTER 5 5.5.2.6 Host API USBBULK_Close() Description Closes an opened device. Prototype void USBBULK_Close(USB_BULK_HANDLE hDevice); Parameters Parameter hDevice Description Handle to the device that shall be closed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 131 CHAPTER 5 5.5.3 5.5.3.1 Host API USB-Bulk direct input/output functions USBBULK_Read() Description Reads data from target device running emUSB-Device-Bulk. Prototype int USBBULK_Read(USB_BULK_HANDLE hDevice, void * pBuffer, int NumBytes); Parameters Parameter Description hDevice Handle to the opened device. pBuffer Pointer to a buffer that shall receive the data. NumBytes Number of bytes to be read. Return value = NumBytes > 0, < NumBytes =0 <0 All bytes have been successfully read. Number of bytes that have been read. If short read transfers are not allowed (normal mode) this indicates a timeout. A timeout occurred, no data was read. Error occurred. Additional information If short read transfers are allowed (see USBBULK_SetMode()) the function returns as soon as data is available, even if just a single byte was read. Otherwise the function blocks until NumBytes were read. In both cases the function returns if a timeout occurs. The default timeout used can be set with USBBULK_SetReadTimeout(). If NumBytes exceeds the maximum read size the driver can handle (the default value is 64 Kbytes), USBBULK_Read() will read the desired NumBytes in chunks of the maximum read size. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 132 CHAPTER 5 5.5.3.2 Host API USBBULK_ReadTimed() Description Reads data from target device running emUSB-Device-Bulk within a given timeout. Prototype int USBBULK_ReadTimed(USB_BULK_HANDLE hDevice, void * pBuffer, int NumBytes, unsigned ms); Parameters Parameter Description hDevice Handle to the opened device. pBuffer Pointer to a buffer that shall receive the data. NumBytes Maximum number of bytes to be read. ms Timeout in milliseconds. Return value >0 =0 <0 Number of bytes that have been read. A timeout occurred during read. Error, cannot read from the device. Additional information The function returns as soon as data is available, even if just a single byte was read. If no data is available, the functions return after the given timeout was expired. If NumBytes exceeds the maximum read size the driver can handle (the default value is 64 Kbytes), USBBULK_ReadTimed() will read the desired NumBytes in chunks of the maximum read size. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 133 CHAPTER 5 5.5.3.3 Host API USBBULK_Write() Description Writes data to the device. Prototype int USBBULK_Write( USB_BULK_HANDLE hDevice, const void * pBuffer, int NumBytes); Parameters Parameter Description hDevice Handle to the opened device. pBuffer Pointer to a buffer that contains the data. NumBytes Number of bytes to be written. If NumBytes = 0, a zero length packet is written to the device. Return value = NumBytes > 0, < NumBytes =0 <0 All bytes have been successfully written. Number of bytes that have been written. If short read transfers are not allowed (normal mode) this indicates a timeout. A timeout occurred, no data was written. Error, cannot write to the device. Additional information If short write transfers are allowed (see USBBULK_SetMode()) the function returns after writing the minimal amount of data (either NumBytes or the maximal write transfer size). Otherwise the function blocks until NumBytes were written. In both cases the function returns if a timeout occurs. The default timeout used can be set with USBBULK_SetWriteTimeout(). If NumBytes exceeds the maximum write size the driver can handle (the default value is 64 Kbytes), USBBULK_Write() will write the desired NumBytes in chunks of the maximum write size. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 134 CHAPTER 5 5.5.3.4 Host API USBBULK_WriteTimed() Description Writes data to the device within a given timeout. Prototype int USBBULK_WriteTimed( USB_BULK_HANDLE const void * int unsigned hDevice, pBuffer, NumBytes, ms); Parameters Parameter Description hDevice Handle to the opened device. pBuffer Pointer to a buffer that contains the data. NumBytes Number of bytes to be written. If NumBytes = 0, a zero length packet is written to the device. ms Timeout in milliseconds. Return value = NumBytes > 0, < NumBytes =0 <0 All bytes have been successfully written. Number of bytes that have been written. If short read transfers are not allowed (normal mode) this indicates a timeout. A timeout occurred, no data was written. Error, cannot write to the device. Additional information If short write transfers are allowed (see USBBULK_SetMode()) the function returns after writing the minimal amount of data (either NumBytes or the maximal write transfer size). Otherwise the function blocks until NumBytes were written. In both cases the function returns if a timeout occurs. If NumBytes exceeds the maximum write size the driver can handle (the default value is 64 Kbytes), USBBULK_WriteTimed() will write the desired NumBytes in chunks of the maximum write size. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 135 CHAPTER 5 5.5.3.5 Host API USBBULK_CancelRead() Description This cancels an initiated read. Prototype void USBBULK_CancelRead(USB_BULK_HANDLE hDevice); Parameters Parameter hDevice Description Handle to the opened device. Additional information Not supported on Linux and MacOSX. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 136 CHAPTER 5 5.5.3.6 Host API USBBULK_FlushRx() Description Flush the any received data. Prototype int USBBULK_FlushRx(USB_BULK_HANDLE hDevice); Parameters Parameter hDevice Description Handle to the opened device. Return value =0 0 Error, bad handle. Success, flushing the RX buffer was successful. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 137 CHAPTER 5 5.5.4 Host API USB-Bulk Control functions 5.5.4.1 USBBULK_SetMode() Description Sets the read and write mode for a specified device running emUSB-Device-Bulk. Prototype unsigned USBBULK_SetMode(USB_BULK_HANDLE hDevice, unsigned Mode); Parameters Parameter Description hDevice Handle to the opened device. Mode Read and write mode for the USB-Bulk driver. This is a combination of the following flags, combined by binary or: * USBBULK_MODE_BIT_ALLOW_SHORT_READ * USBBULK_MODE_BIT_ALLOW_SHORT_WRITE Return value =0 0 Operation failed (invalid handle). The operation was successful. Additional information USBBULK_MODE_BIT_ALLOW_SHORT_READ allows short read transfers. Short transfers are transfers of less bytes than requested. If this bit is specified, the read function USBBULK_Read() returns as soon as data is available, even if it is just a single byte. USBBULK_MODE_BIT_ALLOW_SHORT_WRITE allows short write transfers. USBBULK_Write() and USBBULK_WriteTimed() return after writing the minimal amount of data (either NumBytes or the maximal write transfer size). Example static void _TestMode(USB_BULK_HANDLE hDevice) { unsigned Mode; char * pText; Mode = USBBULK_GetMode(hDevice); if (Mode & USBBULK_MODE_BIT_ALLOW_SHORT_READ) { pText = "USE_SHORT_MODE"; } else { pText = "USE_NORMAL_MODE"; } printf("USB-Bulk driver is in %s for device %d\n", pText, (int)hDevice); printf("Set mode to USBBULK_MODE_BIT_ALLOW_SHORT_READ\n"); USBBULK_SetMode(hDevice, USBBULK_MODE_BIT_ALLOW_SHORT_READ); Mode = USBBULK_GetMode(hDevice); if (Mode & USBBULK_MODE_BIT_ALLOW_SHORT_READ) { pText = "USE_SHORT_MODE"; } else { pText = "USE_NORMAL_MODE"; } printf("USB-Bulk driver is now in %s for device %d\n", pText,(int)hDevice); } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 138 CHAPTER 5 5.5.4.2 Host API USBBULK_GetMode() Description Returns the current mode of the device. Prototype unsigned USBBULK_GetMode(USB_BULK_HANDLE hDevice); Parameters Parameter hDevice Description Handle to the opened device. Return value A combination of the following flags, combined by binary or: * * USBBULK_MODE_BIT_ALLOW_SHORT_READ - Short read mode is enabled. USBBULK_MODE_BIT_ALLOW_SHORT_WRITE - Short write mode is enabled. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 139 CHAPTER 5 5.5.4.3 Host API USBBULK_SetReadTimeout() Description Sets the default read timeout for an opened device. Prototype void USBBULK_SetReadTimeout(USB_BULK_HANDLE hDevice, int Timeout); Parameters Parameter Description hDevice Handle to the opened device. Timeout Timeout in milliseconds. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 140 CHAPTER 5 5.5.4.4 Host API USBBULK_SetWriteTimeout() Description Sets a default write timeout for an opened device. Prototype void USBBULK_SetWriteTimeout(USB_BULK_HANDLE hDevice, int Timeout); Parameters Parameter Description hDevice Handle to the opened device. Timeout Timeout in milliseconds. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 141 CHAPTER 5 5.5.4.5 Host API USBBULK_ResetPipe() Description Resets the pipes that are opened to the device. It also flushes any data the USB bulk driver would cache. Prototype int USBBULK_ResetPipe(USB_BULK_HANDLE hDevice); Parameters Parameter hDevice Description Handle to the opened device. Return value 0 =0 The operation was successful. Operation failed. Either an invalid handle was used or the pipes cannot be flushed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 142 CHAPTER 5 5.5.4.6 Host API USBBULK_ResetDevice() Description Resets the device via a USB reset. This can be used when the device does not work properly and may be reactivated via USB reset. This will force a re-enumeration of the device. Prototype int USBBULK_ResetDevice(USB_BULK_HANDLE hDevice); Parameters Parameter hDevice Description Handle to the opened device. Return value 0 =0 The operation was successful. Operation failed. Either an invalid handle was used or the device cannot be reset. Additional information After the device has been reset it is necessary to re-open the device as the current handle will become invalid. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 143 CHAPTER 5 5.5.5 5.5.5.1 Host API USB-Bulk general GET functions USBBULK_GetVersion() Description Returns the version number of the USBBULK API. Prototype unsigned USBBULK_GetVersion(void); Return value Version number, format: < Major Version><Minor Version><Subversion> (Mmmrr, decimal). Example: 30203 is 3.02c emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 144 CHAPTER 5 5.5.5.2 Host API USBBULK_GetDevInfo() Description Retrieves information about an opened USBBULK device. Prototype void USBBULK_GetDevInfo(USB_BULK_HANDLE hDevice, USBBULK_DEV_INFO * pDevInfo); Parameters Parameter Description hDevice Handle to the opened device. pDevInfo Pointer to a device info structure. Additional information USBBULK_DEV_INFO is defined as follows: typedef struct { U16 VendorId; U16 ProductId; char acSN[256]; char acDevName[255]; U8 InterfaceNo; }; Member Description VendorId Vendor ID of the device. ProductId Product ID of the device. acSN 0-terminated string which holds the serial number of the device. acDevName 0-terminated string which holds the device name. InterfaceNo Interface number used by this device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 145 CHAPTER 5 5.5.5.3 Host API USBBULK_GetDevInfoByIdx() Description Retrieves information about a USB device. Prototype int USBBULK_GetDevInfoByIdx(unsigned Idx, USBBULK_DEV_INFO * pDevInfo); Parameters Parameter Description Idx Index of the device. pDevInfo Pointer to a device info structure. Return value = 0; 0 Error, bad device index. Success Additional information See USBBULK_GetDevInfo() for a description of the structure USBBULK_DEV_INFO. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 146 CHAPTER 5 5.5.5.4 Host API USBBULK_GetUSBId() Description Returns the Product and Vendor ID of an opened device. Prototype void USBBULK_GetUSBId(USB_BULK_HANDLE hDevice, U16 * pVendorId, U16 * pProductId); Parameters Parameter Description hDevice Handle to the opened device. pVendorId Pointer to a variable that receives the Vendor ID. pProductId Pointer to a variable that receives the Product ID. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 147 CHAPTER 5 5.5.5.5 Host API USBBULK_GetProductName() Description Retrieves the device/product name if available. Prototype int USBBULK_GetProductName(USB_BULK_HANDLE hDevice, char * sProductName, unsigned BufferSize); Parameters Parameter Description hDevice Handle to the opened device. sProductName Pointer to a buffer that should receive the string. BufferSize Size of the buffer, given in bytes. Return value =0 0 Error, product name not available or buffer to small. Success, product name stored in buffer pointed by sProductName as 0-terminated string. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 148 CHAPTER 5 5.5.5.6 Host API USBBULK_GetVendorName() Description Retrieves the vendor name of an opened USBBULK device. Prototype int USBBULK_GetVendorName(USB_BULK_HANDLE hDevice, char * sVendorName, unsigned BufferSize); Parameters Parameter Description hDevice Handle to the opened device. sVendorName Pointer to a buffer that should receive the string. BufferSize Size of the buffer, given in bytes. Return value =0 0 Error, bad handle. Success, vendor name stored in buffer pointed by sVendorName as 0-terminated string. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 149 CHAPTER 5 5.5.5.7 Host API USBBULK_GetSN() Description Retrieves the USB serial number as a string which was sent by the device during the enumeration. Prototype int USBBULK_GetSN(USB_BULK_HANDLE hDevice, U8 * pBuffer, unsigned BuffSize); Parameters Parameter Description hDevice Handle to the opened device. pBuffer Pointer to a buffer which shall receive the serial number of the device. BuffSize Size of the buffer in bytes. Return value =0 0 Operation failed. Either an invalid handle was used or the serial number is not available. The operation was successful. Additional information If the function succeeds, the buffer pointed by pBuffer contains the serial number of the device as 0-terminated string. If BuffSize is too small, the serial number is truncated. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 150 CHAPTER 5 5.5.5.8 Host API USBBULK_GetConfigDescriptor() Description Gets the received target USB configuration descriptor of a specified device. Prototype int USBBULK_GetConfigDescriptor(USB_BULK_HANDLE hDevice, void * pBuffer, int Size); Parameters Parameter Description hDevice Handle to the opened device. pBuffer Pointer to the buffer that shall store the descriptor. Size Size of the buffer, given in bytes. Return value 0 =0 Size of the returned USB configuration descriptor (Success). Operation failed. Either an invalid handle was used or the buffer that shall store the config descriptor is too small. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 6 Mass Storage Device Class (MSD) This chapter gives a general overview of the MSD class and describes how to get the MSD component running on the target. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 152 CHAPTER 6 6.1 Overview Overview The Mass Storage Device (MSD) is a USB class protocol defined by the USB Implementers Forum. The class itself is used to access one or more storage devices such as flash drives or memory sticks. As the USB mass storage device class is well standardized, every major operating system such as Microsoft Windows (after Windows 2000), Apple OS X, Linux and many more support it. So therefore an installation of a custom host USB driver is normally not necessary. emUSB-Device-MSD comes as a whole packet and contains the following: * * * * Generic USB handling MSD device class implementation, including support for direct disk and CD-ROM mode (CD-ROM access is a separate component) Several storage drivers for handling different devices Example applications emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 153 CHAPTER 6 6.2 MSD Configuration MSD Configuration 6.2.1 Initial configuration To get emUSB-Device-MSD up and running as well as doing an initial test, the configuration as it is delivered should not be modified. 6.2.2 Final configuration The configuration must only be modified, when emUSB-Device is deployed in your final product. Refer to emUSB-Device Configuration on page 41 for detailed information about the generic information functions which must be adapted. In order to comply with the Mass Storage Device Bootability specification, the serial number provided by the function USBD_SetDeviceInfo() must be a string with at least 12 characters, where each character is a hexadecimal digit ('0' through '9' or 'A' through 'F'). 6.2.3 MSD class specific configuration functions Beside the generic emUSB-Device configuration functions (emUSB-Device Configuration on page 41), the following should be adapted before the emUSB-Device MSD component is used in a final product. Example implementations are supplied in the MSD example application USB_MSD_FS_Start.c, located in the Application directory of emUSB-Device. Each logical unit (storage) which is added to the MSD component has it's own set of name and id values which is supplied when the logical unit is first added through USBD_MSD_AddUnit() Example static const USB_MSD_LUN_INFO _Lun0Info = { "Vendor", // MSD VendorName "MSD Volume", // MSD ProductName "1.00", // MSD ProductVer "134657890" // MSD SerialNo }; ... InstData.pLunInfo = &_Lun0Info; ... USB_MSD_AddUnit(&InstData); 6.2.4 Running the example application The directory Application contains example applications that can be used with emUSBDevice and the MSD component. To test the emUSB-Device-MSD component, build and download the application of choice into the target. Remove the USB connection and reconnect the target to the host. The target will enumerate and can be accessed via a file browser. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 154 CHAPTER 6 6.2.4.1 MSD Configuration MSD_Start_StorageRAM.c in detail The main part of the example application USB_MSD_Start_StorageRAM.c is implemented in a single task called MainTask(). /* MainTask() - excerpt from USB_MSD_Start_StorageRAM.c */ void MainTask(void); void MainTask(void) { USBD_Init(); _AddMSD(); USBD_Start(); while (1) { while ((USBD_GetState() & (USB_STAT_CONFIGURED | USB_STAT_SUSPENDED)) != USB_STAT_CONFIGURED) { BSP_ToggleLED(0); USB_OS_Delay(50); } BSP_SetLED(0); USBD_MSD_Task(); } } The first step is to initialize the USB core stack using USBD_Init(). The function _AddMSD() configures all required endpoints and assigns the used storage medium to the MSD component. /* _AddMSD() - excerpt from MSD_Start_StorageRAM.c */ static void _AddMSD(void) { static U8 _abOutBuffer[USB_HS_BULK_MAX_PACKET_SIZE]; USB_MSD_INIT_DATA InitData; USB_MSD_INST_DATA InstData; InitData.EPIn = USBD_AddEP(1, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, NULL, 0); InitData.EPOut = USBD_AddEP(0, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, _abOutBuffer, sizeof(_abOutBuffer)); USBD_MSD_Add(&InitData); // // Add logical unit 0: RAM drive // memset(&InstData, 0, sizeof(InstData)); InstData.pAPI = &USB_MSD_StorageRAM; InstData.DriverData.pStart = (void*)MSD_RAM_ADDR; InstData.DriverData.NumSectors = MSD_RAM_NUM_SECTORS; InstData.DriverData.SectorSize = MSD_RAM_SECTOR_SIZE; InstData.pLunInfo = &_Lun0Info; USBD_MSD_AddUnit(&InstData); } The example application uses a RAM disk as storage medium. The example RAM disk has a size of 23 kB (46 sectors with a sector size of 512 bytes). You can increase the size of the RAM disk by modifying the macros MSD_RAM_NUM_SECTORS and MSD_RAM_SECTOR_SIZE (in multiples of 512), but the size must be at least 23 kB otherwise a Windows host cannot format the disk. /* AddMSD() - excerpt from MSD_Start_StorageRAM.c */ #define MSD_RAM_NUM_SECTORS 46 #define MSD_RAM_SECTOR_SIZE 512 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 155 6.3 CHAPTER 6 Target API Target API Function Description API functions USBD_MSD_Add() Adds an MSD-class interface to the USB stack. USBD_MSD_AddUnit() Adds a mass storage device to emUSB-Device-MSD. USBD_MSD_AddCDRom() Adds a CD-ROM device to emUSB-Device-MSD. USBD_MSD_SetPreventAllowRemovalHook() Sets a callback function to prevent/allow removal of storage medium. USBD_MSD_SetPreventAllowRemovalHookEx() Sets a callback function to prevent/allow removal of storage medium. USBD_MSD_SetReadWriteHook() Sets a callback function which gives information about the read and write blockwise. USBD_MSD_Task() Task that handles the MSD-specific protocol. USBD_MSD_SetStartStopUnitHook() Sets the callback when the command StartStopUnit is called. Extended API functions USBD_MSD_Connect() Connects the storage medium to the MSD. USBD_MSD_Disconnect() Disconnects the storage medium from the MSD. USBD_MSD_RequestDisconnect() Sets the DisconnectRequest flag. USBD_MSD_RequestRefresh() Performs a disconnect (optional), a detach and optionally a re-attach, to inform host that volume contents has changed. USBD_MSD_UpdateWriteProtect() This functions updates the write protect status of the storage medium. USBD_MSD_WaitForDisconnection() Waits for disconnection while time out is not reached. Data structures USB_MSD_INIT_DATA emUSB-Device-MSD initialization structure that is required when adding an MSD interface. USB_MSD_INFO emUSB-Device-MSD storage interface. USB_MSD_INST_DATA USB-MSD initialization structure that is required when adding an MSD interface. PREVENT_ALLOW_REMOVAL_HOOK Callback function to prevent/allow removal of storage medium. PREVENT_ALLOW_REMOVAL_HOOK_EX Callback function to prevent/allow removal of storage medium. READ_WRITE_HOOK Callback function which is called with every read/write access to the storage medium. USB_MSD_INST_DATA_DRIVER USB-MSD initialization structure that is required when adding an MSD interface. USB_MSD_STORAGE_API USB-MSD initialization structure that is required when adding an MSD interface. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 156 CHAPTER 6 Function START_STOP_UNIT_HOOK emUSB-Device User Guide & Reference Manual Target API Description Callback function which is called when a START STOP UNIT SCSI command is received. (c) 2010-2018 SEGGER Microcontroller GmbH 157 CHAPTER 6 6.3.1 6.3.1.1 Target API API functions USBD_MSD_Add() Description Adds an MSD-class interface to the USB stack. Prototype void USBD_MSD_Add(const USB_MSD_INIT_DATA * pInitData); Parameters Parameter pInitData Description Pointer to a USB_MSD_INIT_DATA structure. Additional information After the initialization of general emUSB-Device, this is the first function that needs to be called when an MSD interface is used with emUSB-Device. The structure USB_MSD_INIT_DATA must be initialized before USBD_MSD_Add() is called. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 158 CHAPTER 6 6.3.1.2 Target API USBD_MSD_AddUnit() Description Adds a mass storage device to emUSB-Device-MSD. Prototype void USBD_MSD_AddUnit(const USB_MSD_INST_DATA * pInstData); Parameters Parameter pInstData Description Pointer to a USB_MSD_INST_DATA structure containing the information of the added storage device. Additional information It is necessary to call this function immediately after USBD_MSD_Add(). It will then add an R/W storage device to emUSB-Device-MSD. The structure USB_MSD_INST_DATA must be initialized before calling USBD_MSD_AddUnit(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 159 CHAPTER 6 6.3.1.3 Target API USBD_MSD_AddCDRom() Description Adds a CD-ROM device to emUSB-Device-MSD. Prototype void USBD_MSD_AddCDRom(const USB_MSD_INST_DATA * pInstData); Parameters Parameter pInstData Description Pointer to a USB_MSD_INST_DATA structure containing the information of the added storage device. Additional information Similar to USBD_MSD_AddUnit(), this function should be called after USBD_MSD_Add(). The structure USB_MSD_INST_DATA must be initialized before USBD_MSD_AddCDRom() is called. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 160 CHAPTER 6 6.3.1.4 Target API USBD_MSD_SetPreventAllowRemovalHook() Description Sets a callback function to prevent/allow removal of storage medium. Prototype void USBD_MSD_SetPreventAllowRemovalHook (U8 Lun, PREVENT_ALLOW_REMOVAL_HOOK * pfOnPreventAllowRemoval); Parameters Parameter Description Lun Logical Unit Number. Using only one storage medium, this parameter is 0. pfOnPreventAllowRemoval Callback to the callback that shall be called. Additional information The callback is called within the MSD task context. The callback must not block. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 161 CHAPTER 6 6.3.1.5 Target API USBD_MSD_SetPreventAllowRemovalHookEx() Description Sets a callback function to prevent/allow removal of storage medium. Prototype void USBD_MSD_SetPreventAllowRemovalHookEx (U8 Lun, PREVENT_ALLOW_REMOVAL_HOOK_EX * pfOnPreventAllowRemovalEx); Parameters Parameter Description Lun Zero-based index for the unit number. Using only one storage medium, this parameter is 0. pfOnPreventAllowRemovalEx Callback to the callback that shall be called. For detailed information about the function pointer, refer to PREVENT_ALLOW_REMOVAL_HOOK_EX. Additional information The callback is called within the MSD task context. The callback must not block. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 162 CHAPTER 6 6.3.1.6 Target API USBD_MSD_SetReadWriteHook() Description Sets a callback function which gives information about the read and write blockwise. operations to the storage medium. Prototype void USBD_MSD_SetReadWriteHook(U8 Lun, READ_WRITE_HOOK * pfOnReadWrite); Parameters Parameter Description Lun Zero-based index for the unit number. Using only one storage medium, this parameter is 0. pfOnReadWrite Pointer to the callback function that shall be called. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 163 CHAPTER 6 6.3.1.7 Target API USBD_MSD_Task() Description Task that handles the MSD-specific protocol. Prototype void USBD_MSD_Task(void); Additional information After the USB device has been successfully enumerated and configured, the USBD_MSD_Task() should be called. When the device is detached or is suspended, USBD_MSD_Task() will return. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 164 CHAPTER 6 6.3.1.8 Target API USBD_MSD_SetStartStopUnitHook() Description Sets the callback when the command StartStopUnit is called. Prototype void USBD_MSD_SetStartStopUnitHook(U8 Lun, START_STOP_UNIT_HOOK * pfOnStartStopUnit); Parameters Parameter Description Lun Zero-based index for the unit number. Using only one storage medium, this parameter is 0. pfOnStartStopUnit Callback to the callback that shall be called. For detailed information about the function pointer, refer to START_STOP_UNIT_HOOK. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 165 CHAPTER 6 6.3.2 6.3.2.1 Target API Extended API functions USBD_MSD_Connect() Description Connects the storage medium to the MSD. Prototype void USBD_MSD_Connect(U8 Lun); Parameters Parameter Lun Description Zero-based index for the unit number. Using only one storage medium, this parameter is 0. Additional information The storage medium is initially always connected to the MSD component. This function is normally used after the storage medium was disconnected via USBD_MSD_Disconnect() to carry out file system operations on the device application side. The stack connects the storage medium next time when the HOST requests the status of the storage medium. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 166 CHAPTER 6 6.3.2.2 Target API USBD_MSD_Disconnect() Description Disconnects the storage medium from the MSD. Prototype void USBD_MSD_Disconnect(U8 Lun); Parameters Parameter Lun Description Zero-based index for the unit number. Using only one storage medium, this parameter is 0. Additional information This function will force the storage medium to be disconnected. The host will be informed that the medium is not present. In order to reconnect the device to the host, the function USBD_MSD_Connect() shall be used. See USBD_MSD_RequestDisconnect() and USBD_MSD_WaitForDisconnection() for a graceful disconnection method. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 167 CHAPTER 6 6.3.2.3 Target API USBD_MSD_RequestDisconnect() Description Sets the DisconnectRequest flag. Prototype void USBD_MSD_RequestDisconnect(U8 Lun); Parameters Parameter Lun Description Zero-based index for the unit number. Using only one storage medium, this parameter is 0. Additional information This function sets the disconnect flag for the storage medium. As soon as the next MSD command is sent to the device, the host will be informed that the device is currently not available. To reconnect the storage medium, USBD_MSD_Connect() shall be called. Notes If the HOST tries to access the storage medium while this flag is set to 1, the status of the storage medium changes to disconnected. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 168 CHAPTER 6 6.3.2.4 Target API USBD_MSD_RequestRefresh() Description Performs a disconnect (optional), a detach and optionally a re-attach, to inform host that volume contents has changed. Prototype void USBD_MSD_RequestRefresh(U8 Lun, U32 Flags); Parameters Parameter Description Lun Zero-based index for the unit number. Using only one storage medium, this parameter is 0. Flags Request flags, a bit-ored combination of the following flags: * USB_MSD_TRY_DISCONNECT - Try a medium disconnect before doing a USB detach. * USB_MSD_RE_ATTACH - Automatically re-attach after detach has been done. Additional information If the flag USB_MSD_TRY_DISCONNECT is given, the function sets the disconnect flag for the storage medium. As soon as the next MSD command is sent to the device, the host will be informed that the device is currently not available. If the host acknowledges the disconnect, the medium is reconnected and the function USBD_MSD_Task() will return. If the flag USB_MSD_TRY_DISCONNECT is not set or the host ignores the disconnection of the medium, the USB device is detached from the host (using USBD_Stop()). If the flag USB_MSD_RE_ATTACH is set, the device is re-attached after some delay using USBD_Start(). Then the unction USBD_MSD_Task() will return. The function USBD_MSD_RequestRefresh() returns immediately while the procedure is executed in the USBD_MSD_Task(). Returning of the function USBD_MSD_Task() allows the application to reinitialize the volume (or calling USBD_Start(), if USB_MSD_RE_ATTACH was not set) before calling USBD_MSD_Task() again. Detaching the USB device not only affects the specified volume (Lun) but all volumes of the device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 169 CHAPTER 6 6.3.2.5 Target API USBD_MSD_UpdateWriteProtect() Description This functions updates the write protect status of the storage medium. Prototype void USBD_MSD_UpdateWriteProtect(U8 Lun, U8 IsWriteProtected); Parameters Parameter Description Lun Zero-based index for the unit number. Using only one storage medium, this parameter is 0. IsWriteProtected Set the write protect flag: 1 - Medium is write-protected. 0 - Medium is NOT write-protected. Additional information This functions updates the write protect status of the storage medium. Please make sure that this function is called when the LUN is disconnected from the host, otherwise the WriteProtected flag is normally not recognized. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 170 CHAPTER 6 6.3.2.6 Target API USBD_MSD_WaitForDisconnection() Description Waits for disconnection while time out is not reached. Prototype int USBD_MSD_WaitForDisconnection(U8 Lun, U32 TimeOut); Parameters Parameter Description Lun Zero-based index for the unit number. Using only one storage medium, this parameter is 0. TimeOut Timeout give in ms. How long should this function wait, until it stops waiting. Return value 0 1 Error - Time out reached. Device not disconnected. Success - Device disconnected. Additional information After triggering the disconnection via USBD_MSD_RequestDisconnect() the stack disconnects the storage medium as soon as the host requests the status of the storage medium. Win2k does not periodically check the status of a USB MSD. Therefore, the timeout is required to leave the loop. The return value can be used to decide if the disconnection should be forced. In this case, USBD_MSD_Disconnect() shall be called. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 171 CHAPTER 6 6.3.3 Target API Data structures 6.3.3.1 USB_MSD_INIT_DATA Description emUSB-Device-MSD initialization structure that is required when adding an MSD interface. Type definition typedef struct { U8 EPIn; U8 EPOut; U8 InterfaceNum; } USB_MSD_INIT_DATA; Structure members Member Description EPIn Endpoint for sending data to the host. EPOut Endpoint for receiving data from the host. InterfaceNum Interface number. This member is normally internally used, so therefore the value shall be set to 0. Additional information This structure holds the endpoints that should be used with the MSD interface. Refer to USBD_AddDriver() for more information about how to add an endpoint. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 172 CHAPTER 6 6.3.3.2 Target API USB_MSD_INFO Description emUSB-Device-MSD storage interface. Type definition typedef struct { U32 NumSectors; U16 SectorSize; } USB_MSD_INFO; Structure members Member Description NumSectors Number of available sectors. SectorSize Size of one sector. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 173 CHAPTER 6 6.3.3.3 Target API USB_MSD_INST_DATA Description USB-MSD initialization structure that is required when adding an MSD interface. Type definition typedef struct { const USB_MSD_STORAGE_API * pAPI; USB_MSD_INST_DATA_DRIVER DriverData; U8 DeviceType; U8 IsPresent; USB_MSD_HANDLE_CMD * pfHandleCmd; U8 IsWriteProtected; const USB_MSD_LUN_INFO * pLunInfo; } USB_MSD_INST_DATA; Structure members Member Description pAPI Pointer to a structure that holds the storage device driver API. DriverData Driver data that are passed to the storage driver. Refer to USB_MSD_INST_DATA_DRIVER for detailed information about how to initialize this structure. DeviceType Determines the type of the device: 0: Direct access block device 5: CD/DVD IsPresent Determines if the medium is storage is present. For non-removable devices always 1. pfHandleCmd Optional pointer to a callback function which handles SCSI commands. IsWriteProtected Specifies whether the storage medium shall be write-protected. pLunInfo Pointer to a USB_MSD_LUN_INFO structure. Filling this structure is mandatory for each LUN. Additional information All non-optional members of this structure need to be initialized correctly, except DeviceType and pfHandleCmd because it is done by the functions USBD_MSD_AddUnit() or USBD_MSD_AddCDROM(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 174 CHAPTER 6 6.3.3.4 Target API USB_MSD_LUN_INFO Description Structure that is used when adding a logical volume to emUSB-Device-MSD. Type definition typedef struct { const char * pVendorName; const char * pProductName; const char * pProductVer; const char * pSerialNo; } USB_MSD_LUN_INFO; Structure members Member Description pVendorName Vendor name of the mass storage device. The string should be no longer than 8 bytes. pProductName Product name of the mass storage device. The product name string should be no longer than 16 bytes. pProductVer Product version number of the mass storage device. The product version string should be no longer than 4 bytes. pSerialNo Product serial number of the mass storage device. The serial number string must be exactly 12 bytes, in order to satisfy the USB bootability specification requirements. Additional information The setting of these values is mandatory, if these values remain NULL at initialisation emUSB-Device will report a panic error in debug builds (USB_PANIC). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 175 CHAPTER 6 6.3.3.5 Target API PREVENT_ALLOW_REMOVAL_HOOK Description Callback function to prevent/allow removal of storage medium. See USBD_MSD_SetPreventAllowRemovalHook(). Type definition typedef void (PREVENT_ALLOW_REMOVAL_HOOK)(U8 PreventRemoval); Parameters Parameter PreventRemoval Description Show whether the device shall be locked or not. * 0 - The device shall be removable. * 1 - The device shall be locked. Additional information Most OSes call the prevent/allow removal before any write operation. This callback will be called for all LUNs that are available on the host. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 176 CHAPTER 6 6.3.3.6 Target API PREVENT_ALLOW_REMOVAL_HOOK_EX Description Callback function to prevent/allow removal of storage medium. See USBD_MSD_SetPreventAllowRemovalHookEx(). Type definition typedef void (PREVENT_ALLOW_REMOVAL_HOOK_EX)(U8 Lun, U8 PreventRemoval); Parameters Parameter Description Lun Logical Unit Number. PreventRemoval Show whether the device shall be locked or not. * 0 - The device shall be removable. * 1 - The device shall be locked. Additional information Most OSes call the prevent/allow removal before any write operation. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 177 CHAPTER 6 6.3.3.7 Target API READ_WRITE_HOOK Description Callback function which is called with every read/write access to the storage medium. Type definition typedef void (READ_WRITE_HOOK)(U8 U8 U8 U32 U32 Lun, IsRead, OnOff, StartLBA, NumBlocks); Parameters Parameter Description Lun Specifies the logical unit number which was accessed through read or write. IsRead Specifies whether a read or a write access was used: * 1 : read, * 0 : write. OnOff States whether the read or write request has been initialized (1) or whether it is complete (0). StartLBA The first Logical Block Address accessed by the transfer. NumBlocks The number of blocks accessed by the transfer, starting from the StartLBA. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 178 CHAPTER 6 6.3.3.8 Target API USB_MSD_INST_DATA_DRIVER Description USB-MSD initialization structure that is required when adding an MSD interface. Type definition typedef struct { void * pStart; U32 StartSector; U32 NumSectors; U16 SectorSize; void * pSectorBuffer; unsigned NumBytes4Buffer; U8 NumBuffers; } USB_MSD_INST_DATA_DRIVER; Structure members Member Description pStart A pointer defining the start address StartSector The start sector that is used for the driver. NumSectors The available number of sectors available for the driver. SectorSize The sector size that should be used by the driver. pSectorBuffer Pointer to an application provided buffer to be used as temporary buffer for storing the sector data. NumBytes4Buffer Size of the application provided buffer. NumBuffers Number of buffer that are available. This is only used when using the MT storage layer. Additional information This structure is passed to the storage driver. Therefore, the member of this structure can depend on the driver that is used. For the storage driver that are shipped with this software the members of USB_MSD_INST_DATA_DRIVER have the following meaning: USB_MSD_StorageRAM: Member Description pStart A pointer defining the start address of the RAM disk. StartSector This member is ignored. NumSectors The available number of sectors available for the RAM disk. SectorSize The sector size that should be used by the driver. USB_MSD_StorageByName: Member Description pStart Pointer to a string holding the name of the volumes that shall be used, for example "nand:" "mmc:1:" StartSector Specifies the start sector. NumSectors Number of sector that shall be used. SectorSize This member is ignored. pSectorBuffer Pointer to an application provided buffer to be used as temporary buffer for storing the sector data NumBytes4Buffer Size of the buffer provided by the application. Please make sure that the buffer can at least 3 sectors otherwise, pSec- emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 179 CHAPTER 6 Member Target API Description torBuffer and NumBytes4Buffer are ignored and an internal sector buffer is used. This sector-buffer is then allocated by using the FS-Storage-Layer functions. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 180 CHAPTER 6 6.3.3.9 Target API USB_MSD_STORAGE_API Description USB-MSD initialization structure that is required when adding an MSD interface. Type definition typedef struct { USB_MSD_STORAGE_INIT USB_MSD_STORAGE_GETINFO USB_MSD_STORAGE_GETREADBUFFER USB_MSD_STORAGE_READ USB_MSD_STORAGE_GETWRITEBUFFER USB_MSD_STORAGE_WRITE USB_MSD_STORAGE_MEDIUMISPRESENT USB_MSD_STORAGE_DEINIT } USB_MSD_STORAGE_API; * * * * * * * * pfInit; pfGetInfo; pfGetReadBuffer; pfRead; pfGetWriteBuffer; pfWrite; pfMediumIsPresent; pfDeInit; Structure members Member Description pfInit Initializes the storage medium. pfGetInfo Retrieves storage medium information such as sector size and number of sectors available. pfGetReadBuffer Prepares read function and returns a pointer to a buffer that is used by the storage driver. pfRead Reads one or multiple sectors from the storage medium. pfGetWriteBuffer Prepares write function and returns a pointer to a buffer that is used by the storage driver. pfWrite Writes one or more sectors to the storage medium. pfMediumIsPresent Checks if medium is present. pfDeInit De-initializes the storage medium. Additional information USB_MSD_STORAGE_API is used to retrieve information from the storage device driver or access data that needs to be read or written. Detailed information can be found in MSD Storage Driver on page 182. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 181 CHAPTER 6 6.3.3.10 Target API START_STOP_UNIT_HOOK Description Callback function which is called when a START STOP UNIT SCSI command is received. Type definition typedef void (START_STOP_UNIT_HOOK)(U8 Lun, U8 StartLoadEject); Parameters Parameter Description Lun Specifies the logical unit number. StartLoadEject Specifies which operation is executed by the host: * 0 : Stop disk * 1 : Start disk and make ready for access * 2 : Eject disk if permitted * 3 : Load, start and make disk ready. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 182 CHAPTER 6 6.4 MSD Storage Driver MSD Storage Driver 6.4.1 General information The storage interface is handled through an API-table, which contains all relevant functions necessary for read/write operations and initialization. Its implementation handles the details of how data is actually read from or written to memory. Additionally, MSD knows two different media types: * * 6.4.1.1 Direct media access, for example RAM-Disk, NAND flash, MMC/SD cards etc. CD-ROM emulation. Supported storage types The supported storage types include: * * * 6.4.1.2 RAM, directly connected to the processor via the address bus. External flash memory, e.g. SD cards. Mechanical drives, for example CD-ROM. This is essentially an ATA/SCSI to USB bridge. Storage drivers supplied with this release This release comes with the following drivers: * * * 6.4.2 USB_MSD_StorageRAM: A RAM driver which should work with almost any device. USB_MSD_StorageByIndex: A storage driver that uses the storage layer (logical block layer) of emFile to access the device. USB_MSD_StorageByName: A storage driver that uses the storage layer (logical block layer) of emFile to access the device. Interface function list As described above, access to a storage medium is realized through an API-function table (USB_MSD_STORAGE_API). The storage functions are declared in USB_MSD.h. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 183 CHAPTER 6 6.4.3 6.4.3.1 MSD Storage Driver USB_MSD_STORAGE_API in detail USB_MSD_STORAGE_INIT Description Initializes the storage medium. Type definition typedef void (USB_MSD_STORAGE_INIT)( U8 Lun, const USB_MSD_INST_DATA_DRIVER * pDriverData); Parameters Parameter Description Lun Logical unit number. Specifies for which drive the function is called. pDriverData Pointer to a USB_MSD_INST_DATA_DRIVER structure that contains all information that is necessary for the driver initialization. Refer to USB_MSD_INST_DATA_DRIVER structure for detailed information. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 184 CHAPTER 6 6.4.3.2 MSD Storage Driver USB_MSD_STORAGE_GETINFO Description Retrieves storage medium information such as sector size and number of sectors available. Type definition typedef void (USB_MSD_STORAGE_GETINFO)(U8 Lun, USB_MSD_INFO * pInfo); Parameters Parameter Description Lun Logical unit number. Specifies for which drive the function is called. pInfo Pointer to a USB_MSD_INFO structure. For detailed information about the USB_MSD_INFO structure, refer to USB_MSD_INFO. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 185 CHAPTER 6 6.4.3.3 MSD Storage Driver USB_MSD_STORAGE_GETREADBUFFER Description Prepares the read function and returns a pointer to a buffer that is used by the storage driver. Type definition typedef U32 (USB_MSD_STORAGE_GETREADBUFFER)(U8 Lun, U32 SectorIndex, void ** ppData, U32 NumSectors); Parameters Parameter Description Lun Logical unit number. Specifies for which drive the function is called. SectorIndex Specifies the start sector for the read operation. ppData Pointer to a pointer to store the read buffer address of the driver. NumSectors Number of sectors to read. Return value Maximum number of consecutive sectors that can be read at once by the driver. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 186 CHAPTER 6 6.4.3.4 MSD Storage Driver USB_MSD_STORAGE_READ Description Reads one or multiple consecutive sectors from the storage medium. Type definition typedef char (USB_MSD_STORAGE_READ)(U8 Lun, U32 SectorIndex, void * pData, U32 NumSectors); Parameters Parameter Description Lun Logical unit number. Specifies for which drive the function is called. SectorIndex Specifies the start sector from where the read operation is started. pData Pointer to buffer to store the read data. NumSectors Number of sectors to read. Return value =0 0 Success. Failed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 187 CHAPTER 6 6.4.3.5 MSD Storage Driver USB_MSD_STORAGE_GETWRITEBUFFER Description Prepares the write function and returns a pointer to a buffer that is used by the storage driver. Type definition typedef U32 (USB_MSD_STORAGE_GETWRITEBUFFER)(U8 Lun, U32 SectorIndex, void ** ppData, U32 NumSectors); Parameters Parameter Description Lun Logical unit number. Specifies for which drive the function is called. SectorIndex Specifies the start sector for the write operation. ppData Pointer to a pointer to store the write buffer address of the driver. NumSectors Number of sectors to write. Return value Maximum number of consecutive sectors that can be written into the buffer. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 188 CHAPTER 6 6.4.3.6 MSD Storage Driver USB_MSD_STORAGE_WRITE Description Writes one or more consecutive sectors to the storage medium. Type definition typedef char (USB_MSD_STORAGE_WRITE)( U8 Lun, U32 SectorIndex, const void * pData, U32 NumSectors); Parameters Parameter Description Lun Logical unit number. Specifies for which drive the function is called. SectorIndex Specifies the start sector for the write operation. pData Pointer to data to be written to the storage medium. NumSectors Number of sectors to write. Return value =0 0 Success. Failed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 189 CHAPTER 6 6.4.3.7 MSD Storage Driver USB_MSD_STORAGE_MEDIUMISPRESENT Description Checks if medium is present. Type definition typedef char (USB_MSD_STORAGE_MEDIUMISPRESENT)(U8 Lun); Parameters Parameter Description Logical unit number. Specifies for which drive the function is called. Lun Return value 1 0 Medium is present. Medium is not present. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 190 CHAPTER 6 6.4.3.8 MSD Storage Driver USB_MSD_STORAGE_DEINIT Description De-initializes the storage medium. Type definition typedef void (USB_MSD_STORAGE_DEINIT)(U8 Lun); Parameters Parameter Lun Description Logical unit number. Specifies for which drive the function is called. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 7 Smart Mass Storage Component (SmartMSD) This chapter gives a general overview of the SmartMSD component and describes how to get the SmartMSD running on the target. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 192 CHAPTER 7 7.1 Overview Overview The SmartMSD component allows to easily stream files to and from USB devices. Once the USB device is connected to the host, files can be read or written to the application without the need for dedicated storage memory. This makes the software very flexible: it can be used for various types of applications and purposes, with no additional software or drivers necessary on the host side. The SmartMSD software analyzes what operation is performed by the host and passes this to the application layer of the embedded target, which then performs the appropriate action. A simple drag and drop is all it takes to initialize this process, which is supported by a unique active file technology. Smart MSD can access all data which has been created prior to the device being attached to the host, live data cannot be provided. SmartMSD allows to use the storage device in a virtual manner, which means data does not need to be stored on a physical medium. The storage device will be shown on the host as a FAT formated volume with a configurable size and a configurable file list. With the help of that virtual function, the target device can be used for different applications by simply dragging and dropping files to and from the storage medium: * * * Firmware update application. Configuration updater. File system firewall - protect the target's filesystem from being manipulated by the host. The component itself is based on MSD class and thus can be used on virtually any OS such as any Windows, macOS or any Linux distribution (including Android) which supports MSD, without installing any third party tools. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 193 CHAPTER 7 7.2 Configuration Configuration 7.2.1 Initial configuration To get emUSB-Device-SmartMSD up and running as well as doing an initial test, the configuration as is delivered should not be modified. 7.2.2 Final configuration The configuration must only be modified if emUSB-Device is deployed in your final product. Refer to emUSB-Device Configuration on page 41 for detailed information about the generic information functions which must be adapted. 7.2.3 Class specific configuration functions For basic configuration please refer to the MSD chapter MSD class specific configuration functions on page 153. In addition to the MSD configuration functions described there the following SmartMSD functions are available. Function Description emUSB-Device-SmartMSD configuration functions USB_SMSD_X_Config() emUSB-Device User Guide & Reference Manual Configures the SmartMSD component. (c) 2010-2018 SEGGER Microcontroller GmbH 194 CHAPTER 7 7.2.3.1 Configuration USB_SMSD_X_Config() Description Main user configuration function of the SmartMSD component. This function is provided by the user. Prototype void USB_SMSD_X_Config(void); Example void USB_SMSD_X_Config(void) { // // String information used when inquiring the volume. // static const USB_MSD_LUN_INFO _LunInfo = { "Vendor", // MSD VendorName "MSD Volume", // MSD ProductName "1.00", // MSD ProductVer "134657890" // MSD SerialNo }; // // Global configuration // USBD_SMSD_AssignMemory(&_aMEMBuffer[0], sizeof(_aMEMBuffer)); // // Setup LUN0 // USBD_SMSD_SetNumSectors(0, 8000); USBD_SMSD_SetSectorsPerCluster(0, 32); // Anywhere from 1...128, needs to be 2^x USBD_SMSD_SetNumRootDirSectors(0, 2); USBD_SMSD_SetUserAPI(0, &_UserFuncAPI); USBD_SMSD_SetVolumeInfo(0, "Virt0.MSD", &_LunInfo); // Add volume ID // // Push const contents to the volume // USBD_SMSD_AddConstFiles(0, &_aConstFiles[0], COUNTOF(_aConstFiles)); } Additional information During the call of USBD_SMSD_Add() this user function is called in order to configure the SmartMSD module according to the user's preferences. In order to allow the user to configure the volume it is necessary to provide either a memory block or memory allocation/free callbacks to SmartMSD component. 7.2.4 Running the example application The directory Application contains example applications that can be used with emUSBDevice and the SmartMSD component. To test the SmartMSD component, build and download the application of choice into the target. Remove the USB connection and reconnect the target to the host. The target will enumerate and can be accessed via a file browser. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 195 CHAPTER 7 7.2.5 Configuration Calculation of RAM memory usage for SmartMSD An application has to provide RAM memory in order to use SmartMSD either via a call to the function USB_SmartMSD_AssignMemory() or by setting callback functions for memory allocation. The amount of memory used can be calculated as follows: For each volume: Purpose Bytes used Minimum Global volume information 128 128 Cluster info for predefined files added with USB_SmartMSD_AddConstFiles() 2 (for each file) 0 I/O Buffer 512 512 Directory m * 512 512 FAT n * 512 512 Total - 1664 The number of files that can be stored on the volume depends on the size of the directory which is configured using USB_SmartMSD_SetNumRootDirSectors(): Used memory for directory (bytes) Number of root directory sectors (m) max. number of files with short (8.3) file name 1 512 15 2 1024 31 3 1536 47 4 2048 63 5 2560 79 6 3072 95 Files with long file names may occupy multiple entries in the directory, depending on the actual length. The number of FAT sectors (n) depends on the virtual size of the volume (configured using USB_SmartMSD_SetNumSectors()) and the number of sectors per cluster: Number of sectors Sectors per cluster Used memory for FAT (bytes) approx. virtual volume size (MB) 10880 32 512 5.4 21792 32 1024 10.8 32704 32 1536 16.3 43616 32 2048 21.7 54528 32 2560 27.2 65440 32 3072 32.7 76352 32 3584 38.1 87264 32 4096 43.6 98176 32 4608 49.0 109088 32 5120 54.5 120000 32 5632 59.9 130720 32 6144 65.3 43520 128 512 21.3 87168 128 1024 43.5 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 196 CHAPTER 7 Number of sectors Sectors per cluster Configuration Used memory for FAT (bytes) approx. virtual volume size (MB) 130816 128 1536 65.3 174464 128 2048 87.1 218112 128 2560 108.9 261760 128 3072 130.8 305408 128 3584 152.6 349056 128 4096 174.4 392704 128 4608 196.2 436352 128 5120 218.1 480000 128 5632 239.9 522800 128 6144 261.3 There is no disadvantage of using the maximum possible number of sectors per cluster (128). In most cases the minimal configuration (FAT = 512 and directory = 512) should be sufficient. It supports a small number of files with a total size of all files up to 21 MB. If more files or bigger files are needed, the required parameters can be looked up in the tables above. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 197 7.3 CHAPTER 7 Target API Target API Function Description API functions Create SmartMSD volumes and add MSD interface to the device. USBD_SMSD_Add() User supplied functions User supplied function that configures all storages of the SMSD component. USB_SMSD_X_Config() Configuration functions USBD_SMSD_AssignMemory() Assigns memory to the SmartMSD module. USBD_SMSD_SetUserAPI() Sets the default user callbacks for the SmartMSD component. USBD_SMSD_SetNumRootDirSectors() Sets the number of sectors which should be used for root directory entries. USBD_SMSD_SetVolumeInfo() Sets the volume name for a specified LUN. USBD_SMSD_AddConstFiles() Adds constant files to SmartMSD. USBD_SMSD_SetNumSectors() Sets the number of sectors available on the volume. USBD_SMSD_SetSectorsPerCluster() Set number of sectors per cluster. Data structures USB_SMSD_CONST_FILE This structure contains information about a constant file which cannot be changed at run time and should be shown inside the SmartMSD volume (e.g. USB_SMSD_USER_FUNC_API This structure contains the function pointers for user provided functions. USB_SMSD_FILE_INFO Structure used in the read and write callbacks. USB_SMSD_DIR_ENTRY_SHORT Structure used to describe an entry with a short file name. Function definitions USB_SMSD_ON_READ_FUNC Callback function prototype that is used when calling the USBD_SMSD_SetUserAPI() function. USB_SMSD_ON_WRITE_FUNC Callback function prototype that is used when calling the USBD_SMSD_SetUserAPI() function. USB_SMSD_MEM_ALLOC Function prototype that is used when memory is being allocated by the SmartMSD module. USB_SMSD_MEM_FREE Function prototype that is used when memory is being freed by the SmartMSD module. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 198 CHAPTER 7 7.3.1 7.3.1.1 Target API API functions USBD_SMSD_Add() Description Create SmartMSD volumes and add MSD interface to the device. Prototype void USBD_SMSD_Add(void); Additional information After the initialization of emUSB-Device, this is the first function that needs to be called when the SmartMSD component is used with emUSB-Device. During the call of the said function the user function USB_SMSD_X_Config() is called in order to configure the storage itself. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 199 CHAPTER 7 7.3.1.2 Target API USB_SMSD_X_Config() Description User supplied function that configures all storages of the SMSD component. Prototype void USB_SMSD_X_Config(void); Additional information This function is called automatically by USBD_SMSD_Add() in order to allow to configure the storage volumes that SmartMSD should show after configuration. Only the following functions must be called in this context: Allowed functions with USB_X_SMSD_Config: USBD_SMSD_AssignMemory() USBD_SMSD_SetUserAPI() USBD_SMSD_SetNumRootDirSectors() USBD_SMSD_SetVolumeInfo() USBD_SMSD_AddConstFiles() USBD_SMSD_SetNumSectors() USBD_SMSD_SetSectorsPerCluster() emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 200 CHAPTER 7 7.3.1.3 Target API USBD_SMSD_AssignMemory() Description Assigns memory to the SmartMSD module. Prototype void USBD_SMSD_AssignMemory(U32 * p, U32 NumBytes); Parameters Parameter Description p Pointer to the memory which should be dedicated to SmartMSD. NumBytes Size of the memory block in bytes. Additional information See Calculation of RAM memory usage for SmartMSD on page 195. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 201 CHAPTER 7 7.3.1.4 Target API USBD_SMSD_SetUserAPI() Description Sets the default user callbacks for the SmartMSD component. Prototype void USBD_SMSD_SetUserAPI(const USB_SMSD_USER_FUNC_API * pUserFunc); Parameters Parameter pUserFunc Description Pointer to a USB_SMSD_USER_FUNC_API structure which holds the default function pointers for multiple functions. Notes (1) Must only be called from USB_SMSD_X_Config() during initialization phase emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 202 CHAPTER 7 7.3.1.5 Target API USBD_SMSD_SetNumRootDirSectors() Description Sets the number of sectors which should be used for root directory entries. Prototype void USBD_SMSD_SetNumRootDirSectors(unsigned Lun, unsigned NumRootDirSectors); Parameters Parameter Description Lun Specifies the logical unit number. NumRootDirSectors Number of sectors to be reserved for the root directory entries. Additional information The number of sectors reserved through this function is subtracted from the number of sectors configured by USBD_SMSD_SetNumSectors(). These sectors hold the root directory entries for the specified LUN. A single sector contains 512 bytes, a short file name entry (also called 8.3 filenames) needs 32 bytes, therefore a single sector has enough space for 16 root directory entries. Please note that when using LFN (long file names) the number of entries required for a single file is dynamic (depending on the length of the file name). Notes (1) Must only be called from USB_SMSD_X_Config() during initialization phase emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 203 CHAPTER 7 7.3.1.6 Target API USBD_SMSD_SetVolumeInfo() Description Sets the volume name for a specified LUN. Prototype int USBD_SMSD_SetVolumeInfo( unsigned Lun, const char * sVolumeName, const USB_MSD_LUN_INFO * pLunInfo); Parameters Parameter Description Lun Specifies the logical unit number. sVolumeName Pointer to a string containing the name of the LUN. pLunInfo Pointer to USB_MSD_LUN_INFO structure contain all relevant MSD strings. Return value 0 <0 O.K. Error Notes (1) Must only be called from USB_SMSD_X_Config() during initialization phase emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 204 CHAPTER 7 7.3.1.7 Target API USBD_SMSD_AddConstFiles() Description Adds constant files to SmartMSD. Allows to add multiple files which should be shown on a SmartMSD volume as soon as it is connected. A common example would be a "Readme.txt" or a link to the company website. Prototype int USBD_SMSD_AddConstFiles( unsigned Lun, const USB_SMSD_CONST_FILE * paConstFile, unsigned NumFiles); Parameters Parameter Description Lun Specifies the logical unit number. paConstFile Pointer to an array of USB_SMSD_CONST_FILE structures. NumFiles The number of items in the paConstFile array. Return value 0 <0 O.K. Error Additional information For additional information please see USB_SMSD_CONST_FILE. Notes (1) Must only be called from USB_SMSD_X_Config() during initialization phase Example #define COUNTOF(a) (sizeof((a))/sizeof((a)[0])) static const U8 _abFile_SeggerHTML[] = {0x3C, 0x68, 0x74, 0x6D, 0x6C, 0x3E, 0x68, 0x65, 0x61, 0x64, 0x3E, 0x3C, 0x6D, 0x65, 0x74, 0x61, 0x20, 0x68, 0x74, 0x74, 0x70, 0x2D, 0x65, 0x71, 0x75, 0x69, 0x76, 0x3D, 0x22, 0x72, 0x65, 0x66, 0x72, 0x65, 0x73, 0x68, 0x22, 0x20, 0x63, 0x6F, 0x6E, 0x74, 0x65, 0x6E, 0x74, 0x3D, 0x22, 0x30, 0x3B, 0x20, 0x75, 0x72, 0x6C, 0x3D, 0x68, 0x74, 0x74, 0x70, 0x3A, 0x2F, 0x2F, 0x77, 0x77, 0x77, 0x2E, 0x73, 0x65, 0x67, 0x67, 0x65, 0x72, 0x2E, 0x63, 0x6F, 0x6D, 0x2F, 0x69, 0x6E, 0x64, 0x65, 0x78, 0x2E, 0x68, 0x74, 0x6D, 0x6C, 0x22, 0x2F, 0x3E, 0x3C, 0x74, 0x69, 0x74, 0x6C, 0x65, 0x3E, 0x53, 0x45, 0x47, 0x47, 0x45, 0x52, 0x20, 0x53, 0x68, 0x6F, 0x72, 0x74, 0x63, 0x75, 0x74, 0x3C, 0x2F, 0x74, 0x69, 0x74, 0x6C, 0x65, 0x3E, 0x3C, 0x2F, 0x68, 0x65, 0x61, 0x64, 0x3E, 0x3C, 0x62, 0x6F, 0x64, 0x79, 0x3E, 0x3C, 0x2F, 0x62, 0x6F, 0x64, 0x79, 0x3E, 0x3C, 0x2F, 0x68, 0x74, 0x6D, 0x6C, 0x3E}; static USB_SMSD_CONST_FILE _aConstFiles[] = { // sName pData FileSize Flags { "Segger.html", _abFile_SeggerHTML, sizeof(_abFile_SeggerHTML), 0, } }; /********************************************************************* * * USB_SMSD_X_Config * * Function description * This function is called by the USB MSD Module during USB_SMSD_Init() and initializes the SmartMSD volume. */ void USB_SMSD_X_Config(void) { <...> USBD_SMSD_AddConstFiles(1, &_aConstFiles[0], COUNTOF(_aConstFiles)); <...> } emUSB-Device User Guide & Reference Manual 0x3C, (c) 2010-2018 SEGGER Microcontroller GmbH 205 CHAPTER 7 7.3.1.8 Target API USBD_SMSD_SetNumSectors() Description Sets the number of sectors available on the volume. Prototype void USBD_SMSD_SetNumSectors(unsigned Lun, unsigned NumSectors); Parameters Parameter Description Lun Specifies the logical unit number. NumSectors Specifies the number of sectors for a LUN. Notes (1) Must only be called from USB_SMSD_X_Config() during initialization phase emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 206 CHAPTER 7 7.3.1.9 Target API USBD_SMSD_SetSectorsPerCluster() Description Set number of sectors per cluster. Prototype void USBD_SMSD_SetSectorsPerCluster(unsigned Lun, unsigned SectorsPerCluster); Parameters Parameter Description Lun Specifies the logical unit number. SectorsPerCluster Number of sectors per cluster for the LUN. Additional information SectorsPerCluster can be anywhere between 1 and 128, but needs to be a power of 2. Larger clusters save memory because the management overhead is lower, but the maximum number of files is limited by the number of available clusters. Notes (1) Must only be called from USB_SMSD_X_Config() during initialization phase emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 207 CHAPTER 7 7.3.2 7.3.2.1 Target API Data structures USB_SMSD_CONST_FILE Description This structure contains information about a constant file which cannot be changed at run time and should be shown inside the SmartMSD volume (e.g. Readme.txt). This structure is a parameter for the USBD_SMSD_AddConstFiles() function. Type definition typedef struct { const char * sName; const U8 * pData; unsigned FileSize; U32 Flags; } USB_SMSD_CONST_FILE; Structure members Member Description sName Pointer to a zero-terminated string containing the filename. pData Pointer to the file data. Can be NULL. FileSize Size of the file. Normally the size of the data pointed to by pData. Flags Can be one of the following items: * USB_SMSD_FILE_WRITABLE: The file is writable * USB_SMSD_FILE_AHEAD: File is located at the start of the volume. Normally constant files are allocated at the end of the volume. Additional information If a file does not occupy complete sectors the remaining bytes of the last sector are automatically filled with 0s on read. If pData is NULL the file is not displayed in the volume. This is useful when the application has certain files which should only be displayed after certain events (e.g. the application displays a Fail.txt when the device is reconnected after an unsuccessful firmware update). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 208 CHAPTER 7 7.3.2.2 Target API USB_SMSD_USER_FUNC_API Description This structure contains the function pointers for user provided functions. This structure is a parameter for the USBD_SMSD_SetUserAPI() function. Type definition typedef struct { USB_SMSD_ON_READ_FUNC * USB_SMSD_ON_WRITE_FUNC * USB_SMSD_MEM_ALLOC * USB_SMSD_MEM_FREE * } USB_SMSD_USER_FUNC_API; pfOnReadSector; pfOnWriteSector; pfMemAlloc; pfMemFree; Structure members Member Description pfOnReadSector Pointer to a callback function of type USB_SMSD_ON_READ_FUNC which is called when a sector is read from the host. This function is mandatory and can not be NULL. pfOnWriteSector Pointer to a callback function of type USB_SMSD_ON_WRITE_FUNC which is called when a sector is written from the host. This function is mandatory and can not be NULL. pfMemAlloc Pointer to a user provided alloc function of type USB_SMSD_MEM_ALLOC. If this pointer is NULL the internal alloc function is called. If no memory block is assigned USB_PANIC is called. pfMemFree Pointer to a user provided free function of type USB_SMSD_MEM_FREE. If this pointer is NULL the internal free function is called. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 209 CHAPTER 7 7.3.2.3 Target API USB_SMSD_FILE_INFO Description Structure used in the read and write callbacks. Type definition typedef struct { const USB_SMSD_DIR_ENTRY_SHORT * pDirEntry; } USB_SMSD_FILE_INFO; Structure members Member pDirEntry Description Pointer to a USB_SMSD_DIR_ENTRY_SHORT structure. Additional information Check USB_SMSD_ON_READ_FUNC, TRY_SHORT for more information. emUSB-Device User Guide & Reference Manual USB_SMSD_ON_WRITE_FUNC and USB_SMSD_DIR_EN- (c) 2010-2018 SEGGER Microcontroller GmbH 210 CHAPTER 7 7.3.2.4 Target API USB_SMSD_DIR_ENTRY_SHORT Description Structure used to describe an entry with a short file name. This structure is a member of USB_SMSD_DIR_ENTRY. Type definition typedef struct { U8 acFilename[]; U8 acExt[]; U8 DirAttr; U8 NTRes; U8 CrtTimeTenth; U16 CrtTime; U16 CrtDate; U16 LstAccDate; U16 FstClusHI; U16 WrtTime; U16 WrtDate; U16 FstClusLO; U32 FileSize; } USB_SMSD_DIR_ENTRY_SHORT; Structure members Member Description acFilename File name, limited to 8 characters (short file name), padded with spaces (0x20). acExt File extension, limited to 3 characters (short file name), padded with spaces (0x20). DirAttr File attributes. Available attributes are listed below. NTRes Reserved for use by Windows NT. CrtTimeTenth Millisecond stamp at file creation time. This field actually contains a count of tenths of a second. CrtTime Creation time. CrtDate Date file was created. LstAccDate Last access date. Note that there is no last access time, only a date. This is the date of last read or write. FstClusHI High word of this entry?'s first cluster number. WrtTime Time of last write. WrtDate Date of last write. FstClusLO Low word of this entry'?s first cluster number. FileSize File size in bytes. Additional information The following file attributes are available for short dir entries: Attribute Explanation USB_SMSD_ATTR_READ_ONLY The file is read-only. USB_SMSD_ATTR_HIDDEN The file is hidden. USB_SMSD_ATTR_SYSTEM The file is designated as a system file. USB_SMSD_ATTR_VOLUME_ID This entry is the volume ID (volume name). USB_SMSD_ATTR_DIRECTORY The file is a directory. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 211 CHAPTER 7 Attribute Target API Explanation USB_SMSD_ATTR_ARCHIVE The file has the archive attribute. USB_SMSD_ATTR_LONG_NAME The file has a long file name. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 212 CHAPTER 7 7.3.3 7.3.3.1 Target API Function definitions USB_SMSD_ON_READ_FUNC Description Callback function prototype that is used when calling the USBD_SMSD_SetUserAPI() function. Type definition typedef int (USB_SMSD_ON_READ_FUNC)( unsigned Lun, U8 * pData, U32 Off, U32 NumBytes, const USB_SMSD_FILE_INFO * pFile); Parameters Parameter Description Lun Zero-based index for the unit number. Using only one virtual volume, this parameter is 0. pData Pointer to a buffer in which the data is stored. Off Offset in the file which is read by the host. NumBytes Amount of bytes requested by the host. pFile Pointer to a USB_SMSD_FILE_INFO structure describing the file. Return value =0 0 Success. An error occurred. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 213 CHAPTER 7 7.3.3.2 Target API USB_SMSD_ON_WRITE_FUNC Description Callback function prototype that is used when calling the USBD_SMSD_SetUserAPI() function. Type definition typedef int (USB_SMSD_ON_WRITE_FUNC)( unsigned Lun, const U8 * pData, U32 Off, U32 NumBytes, const USB_SMSD_FILE_INFO * pFile); Parameters Parameter Description Lun Zero-based index for the unit number. Using only one virtual volume, this parameter is 0. pData Pointer to the data to be written (received from the host). Off Offset in the file which the host writes. NumBytes Amount of bytes to write. pFile Pointer to a USB_SMSD_FILE_INFO structure describing the file. Return value =0 0 Success. An error occurred. Additional information Depending on the behavior of the host operating system it is possible that pFile is NULL. In this case we recommend to perform data analysis to recognize the file. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 214 CHAPTER 7 7.3.3.3 Target API USB_SMSD_MEM_ALLOC Description Function prototype that is used when memory is being allocated by the SmartMSD module. Type definition typedef void * (USB_SMSD_MEM_ALLOC)(U32 Size); Parameters Parameter Size Description Size of the required memory in bytes. Return value Pointer to the allocated memory or NULL. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 215 CHAPTER 7 7.3.3.4 Target API USB_SMSD_MEM_FREE Description Function prototype that is used when memory is being freed by the SmartMSD module. Type definition typedef void (USB_SMSD_MEM_FREE)(void * p); Parameters Parameter p Description Pointer to a memory block which was previously allocated by USB_SMSD_MEM_ALLOC. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 8 Media Transfer Protocol Class (MTP) This chapter gives a general overview of the MTP class and describes how to get the MTP component running on the target. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 217 CHAPTER 8 8.1 Overview Overview The Media Transfer Protocol (MTP) is a USB class protocol which can be used to transfer files to and from storage devices. MTP is an official extension of the Picture Transfer Protocol (PTP) designed to allow digital cameras to exchange image files with a computer. MTP extends this by adding support for audio and video files. MTP is an alternative to Mass Storage Device (MSD) and it operates at the file level, in contrast to MSD which reads and writes sector data. This type of operation gives MTP some advantages over MSD: * * * * * The cable can be safely removed during the data transfer without damaging the file system. The file system does not need to be FAT (can be the SEGGER emFile File System (EFS) or any other proprietary file system) The application has full control over which files are visible to the user. Selected files or directories can be hidden. Virtual files can be presented. Host and target can access storage simultaneously without conflicts. MTP is supported by most operating systems out of the box and the installation of additional drivers is not required. emUSB-Device-MTP supports the following capabilities: * * * * * * File read File write Format File delete Directory create Directory delete emUSB-Device-MTP comes as a complete package and contains the following: * * * * Generic USB handling MTP device class implementation Storage driver which uses emFile Sample application showing how to work with MTP emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 218 CHAPTER 8 8.1.1 Overview Getting access to files An MTP device will be displayed under the "Portable Devices" section in the "Computer" window when connected to a PC running the Microsoft Windows 7 operating system: The file and directories stored on the device are accessed in the usual way using the Windows Explorer: emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 219 CHAPTER 8 Overview On the Ubuntu Linux operating system a connected MTP device is shown in the "Computer" window: The files and directories present on the MTP device can be easily accessed via GUI: On other operating systems the data stored on MTP devices can be accessed similarly. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 220 CHAPTER 8 8.1.2 Overview Additional information For more technical details about MTP and PTP follow these links: MTP specification PTP specification emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 221 CHAPTER 8 8.2 Configuration Configuration 8.2.1 Initial configuration To get emUSB-Device-MTP up and running as well as doing an initial test, the configuration as delivered with the sample application should not be modified. 8.2.2 Final configuration The configuration must only be modified when emUSB-Device is integrated in your final product. Refer to section emUSB-Device Configuration on page 41 for detailed information about the generic information functions which have to be adapted. 8.2.3 Class specific configuration Beside the generic emUSB-Device configuration functions (emUSB-Device Configuration on page 41), the following should be adapted before the emUSB-Device MTP component is used in a final product. Example implementations are supplied in the MSD example application USB_MTP_Start.c, located in the Application directory of emUSB-Device. An MTP device is required to present an additional information set to the host. These values are added during the initial call to USBD_MTP_Add(). Example static const USB_MTP_INFO _MTPInfo = { "Vendor", // MTP Manufacturer "Storage device", // MTP Model "1.0", // MTP DeviceVersion "0123456789ABCDEF0123456789ABCDEF" // MTP SerialNumber. // It must be exactly 32 characters long. }; ... InitData.pMTPInfo = &_MTPInfo; ... USB_MTP_Add(&InitData); 8.2.4 Compile time configuration The following macros can be added to USB_Conf.h file in order to configure the behavior of the MTP component. The following types of configuration macros exist: Binary switches "B" Switches can have a value of either 0 or 1, for deactivated and activated respectively. Actually, anything other than 0 works, but 1 makes it easier to read a configuration file. These switches can enable or disable a certain functionality or behavior. Switches are the simplest form of configuration macros. Numerical values "N" Numerical values are used somewhere in the code in place of a numerical constant. Type N Macro MTP_DEBUG_LEVEL emUSB-Device User Guide & Reference Manual Default 0 Description Sets the type of diagnostic messages output at runtime. It can take one of these values: 0 - no debug messages 1 - only error messages (c) 2010-2018 SEGGER Microcontroller GmbH 222 CHAPTER 8 Type N Macro MTP_MAX_NUM_STORAGES Default Configuration Description 2 - error and log messages 4 Maximum number of storage units the storage layer can handle. 4 additional bytes are allocated for each storage unit. B MTP_SAVE_FILE_INFO 0 Specifies if the object properties (file size, write protection, creation date, modification date and file id) should be stored in RAM for quick access to them. 50 additional bytes of RAM are required for each object when the switch is set to 1. N MTP_MAX_FILE_PATH 256 Maximum number of characters in the path to a file or directory. 1 Names of the files and directories which are exchanged between the MTP component and the file system are encoded in UTF-8 format. B MTP_SUPPORT_UTF8 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 223 CHAPTER 8 8.3 Running the sample application Running the sample application The directory Application contains a sample application which can be used with emUSBDevice and the MTP component. To test the emUSB-Device-MTP component, the application should be built and then downloaded to target. Remove the USB connection and reconnect the target to the host. The target will enumerate and will be accessible via a file browser. 8.3.1 USB_MTP_Start.c in detail The main part of the example application USB_MTP_Start.c is implemented in a single task called MainTask(). // MainTask() - excerpt from USB_MTP_Start.c void MainTask(void); void MainTask(void) { USBD_Init(); _AddMTP(); USBD_Start(); while (1) { while ((USBD_GetState() & (USB_STAT_CONFIGURED | USB_STAT_SUSPENDED)) != USB_STAT_CONFIGURED) { BSP_ToggleLED(0); USB_OS_Delay(50); } BSP_SetLED(0); USBD_MTP_Task(); } } The first step is to initialize the USB core stack by calling USBD_Init(). The function _AddMTP() configures all required endpoints, adds the MTP component to emUSB-Device and assigns a storage medium to it. More than one storage medium can be added. The access to storage medium is done using a storage driver. emUSB-Device comes with a storage driver for the SEGGER emFile file system. // _AddMTP() - excerpt from USB_MTP_Start.c static void _AddMTP(void) { USB_MTP_INIT_DATA InitData; USB_MTP_INST_DATA InstData; // // Add the MTP component to USB stack. // InitData.EPIn = USBD_AddEP(1, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, NULL, 0); InitData.EPOut = USBD_AddEP(0, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, _acReceiveBuffer, sizeof(_acReceiveBuffer)); InitData.EPInt = USBD_AddEP(1, USB_TRANSFER_TYPE_INT, 10, NULL, 0); InitData.pObjectList = _aObjectList; InitData.NumBytesObjectList = sizeof(_aObjectList); InitData.pDataBuffer = _aDataBuffer; InitData.NumBytesDataBuffer = sizeof(_aDataBuffer); InitData.pMTPInfo = &_MTPInfo; USBD_MTP_Add(&InitData); // // Add a storage driver to MTP component. // InstData.pAPI = &USB_MTP_StorageFS; InstData.sDescription = "MTP volume"; InstData.sVolumeId = "0123456789"; InstData.DriverData.pRootDir = ""; USBD_MTP_AddStorage(&InstData); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 224 CHAPTER 8 Running the sample application } The size of _acReceiveBuffer and _aDataBuffer buffers must be a multiple of USB maximum packet size. The size of the buffer allocated for the object list, _aObjectList must be chosen according to the number of files on the storage medium. emUSB-Device-MTP assigns an internal object to each file or directory requested by the USB host. The USB host can request all the files and directories present at once or it can request files and directories as user browses them. An object requires a minimum of 54 bytes. The actual number of bytes allocated depends on the length of the full path to file/directory. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 225 8.4 CHAPTER 8 Target API Target API Function Description API functions USBD_MTP_Add() Adds an MTP interface to the USB stack. USBD_MTP_AddStorage() Adds a storage device to emUSB-Device-MTP. USBD_MTP_Task() Main task function of MTP component which processes the commands from host. USBD_MTP_SendEvent() Sends an event notification to the host. Data structures USB_MTP_FILE_INFO Structure which stores information about a file or directory. USB_MTP_INIT_DATA Structure which stores the parameters of the MTP interface. USB_MTP_INFO Structure that is used when initialising the MTP module. USB_MTP_INST_DATA Structure which stores the parameters of storage driver. USB_MTP_INST_DATA_DRIVER Structure which stores the parameters passed to the storage driver. USB_MTP_STORAGE_API Structure that contains callbacks to the storage driver. USB_MTP_STORAGE_INFO Structure which stores information about a storage. Enums USB_MTP_EVENT emUSB-Device User Guide & Reference Manual Enum containing the MTP event codes. (c) 2010-2018 SEGGER Microcontroller GmbH 226 CHAPTER 8 8.4.1 8.4.1.1 Target API API functions USBD_MTP_Add() Description Adds an MTP interface to the USB stack. Prototype int USBD_MTP_Add(const USB_MTP_INIT_DATA * pInitData); Parameters Parameter pInitData Description Pointer to a USB_MTP_INIT_DATA structure. Return value 0 - Successfully added. Additional information After the initialization of USB core, this is the first function that needs to be called when an MTP interface is used with emUSB-Device. The structure USB_MTP_INIT_DATA has to be initialized before USB_MTP_Add() is called. Refer to USB_MTP_INIT_DATA for more information. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 227 CHAPTER 8 8.4.1.2 Target API USBD_MTP_AddStorage() Description Adds a storage device to emUSB-Device-MTP. Prototype USB_MTP_STORAGE_HANDLE USBD_MTP_AddStorage(const USB_MTP_INST_DATA * pInstData); Parameters Parameter pInstData Description Pointer to a USB_MTP_INST_DATA structure which contains the parameters of the added storage. Return value =0 0 Invalid handle, storage could not be added A valid storage handle, this handle can be used with the USBD_MTP_SendEvent to indicate an event to the host. Additional information It is necessary to call this function immediately after USBD_MTP_Add(). This function adds a storage device such as a hard drive, MMC/SD card or NAND flash etc., to emUSB-Device-MTP, which will be used as source/destination of data exchange with the host. The structure USB_MTP_INST_DATA must be initialized before USB_MTP_AddStorage() is called. Refer to USB_MTP_INST_DATA for more information. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 228 CHAPTER 8 8.4.1.3 Target API USBD_MTP_Task() Description Main task function of MTP component which processes the commands from host. Prototype void USBD_MTP_Task(void); Additional information The USBD_MTP_Task() should be called after the USB device has been successfully enumerated and configured. The function returns when the USB device is detached or suspended. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 229 CHAPTER 8 8.4.1.4 Target API USBD_MTP_SendEvent() Description Sends an event notification to the host. Prototype void USBD_MTP_SendEvent(USB_MTP_STORAGE_HANDLE hStorage, USB_MTP_EVENT Event, void * pPara); Parameters Parameter Description hStorage Handle to a storage that was returned by USBD_MTP_AddStorage(). Event Event that occurred. The following events are currently supported: * USB_MTP_EVENT_OBJECTADDED * USB_MTP_EVENT_OBJECTREMOVED * USB_MTP_EVENT_STOREADDED * USB_MTP_EVENT_STOREREMOVED * USB_MTP_EVENT_OBJECTINFOCHANGED * USB_MTP_EVENT_STOREFULL * USB_MTP_EVENT_STORAGEINFOCHANGED pPara Pointer to additional information. This parameter depends on the event. In case of Event = * USB_MTP_EVENT_OBJECTADDED * USB_MTP_EVENT_OBJECTREMOVED * USB_MTP_EVENT_OBJECTINFOCHANGED pPara is a pointer to a filled USB_MTP_FILE_INFO structure. * USB_MTP_EVENT_STOREADDED * USB_MTP_EVENT_STOREREMOVED * USB_MTP_EVENT_STORAGEINFOCHANGED pPara is not used and can be NULL. Additional information Sending an event notification to the MTP host makes sure that the MTP host is aware of changes in the file system of the storage. This function can also be used to notify that a storage has been added or removed. Example static void _GetFileInfo(const char * sPath, USB_MTP_FILE_INFO * pFileInfo) { const char * s; U8 AttrFS; U8 AttrMTP; memset(pFileInfo, 0, sizeof(USB_MTP_FILE_INFO)); s = strrchr(sPath, '\\'); if (s) { s++; // Go to the next character after '\'. } else { s = sPath; } // // In case the file path starts with \ skip this. // if (*sPath == '\\') { sPath++; emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 230 CHAPTER 8 Target API } pFileInfo->pFileName = (char *)s; pFileInfo->pFilePath = (char *)sPath; FS_GetFileTimeEx(pFileInfo->pFilePath, &pFileInfo->CreationTime, FS_FILETIME_CREATE); FS_GetFileTimeEx(pFileInfo->pFilePath, &pFileInfo->LastWriteTime, FS_FILETIME_MODIFY); pFileInfo->IsDirectory = 0; AttrFS = FS_GetFileAttributes(pFileInfo ? pFilePath); if (AttrFS & FS_ATTR_DIRECTORY) { pFileInfo->IsDirectory = 1; } AttrMTP = 0; if (AttrFS & FS_ATTR_READ_ONLY) { AttrMTP |= MTP_FILE_ATTR_WP; } if (AttrFS & FS_ATTR_SYSTEM) { AttrMTP |= MTP_FILE_ATTR_SYSTEM; } if (AttrFS & FS_ATTR_HIDDEN) { AttrMTP |= MTP_FILE_ATTR_HIDDEN; } pFileInfo->Attributes = AttrMTP; } static int _WriteLogFile(const char * sLogFilePath) { char ac[30]; FS_FILE * pFile; int r = 0; USB_MTP_FILE_INFO FileInfo = {0}; if (FS_IsVolumeMounted("")) { // // Check whether file already exists // pFile = FS_FOpen(sLogFilePath, "r"); if (pFile) { r = USB_MTP_EVENT_OBJECTINFOCHANGED; FS_Fclose(pFile); } else { r = USB_MTP_EVENT_OBJECTADDED; } pFile = FS_FOpen(sLogFilePath, "a+"); if (pFile) { sprintf(ac, "OS_Time = %.8d\r\n", (int)OS_GetTime()); FS_Write(pFile, ac, 20); FS_Fclose(pFile); } else { r = 0; } } _GetFileInfo(sLogFilePath, &FileInfo); // // Send events to the host. // USBD_MTP_SendEvent(_ahStorage[0], (USB_MTP_EVENT)r, &FileInfo); USBD_MTP_SendEvent(_ahStorage[0], USB_MTP_EVENT_STORAGEINFOCHANGED, NULL); return r; } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 231 CHAPTER 8 8.4.2 Target API Data structures 8.4.2.1 USB_MTP_FILE_INFO Description Structure which stores information about a file or directory. Type definition typedef struct { char * pFilePath; char * pFileName; U32 FileSize; U32 CreationTime; U32 LastWriteTime; U8 IsDirectory; U8 Attributes; U8 acId[]; } USB_MTP_FILE_INFO; Structure members Member Description pFilePath Full path to file. pFileName Pointer to beginning of file/directory name in pFilePath. FileSize Size of the file in bytes. 0xFFFFFFFF when larger than 4GB. CreationTime The time and date when the file was created. LastWriteTime The time and date when the file was last modified. IsDirectory Set to 1 if the path points to a directory. Attributes Bitmask of file attributes (MTP_FILE_ATTR_...). acId Unique identifier which persists between MTP sessions. Additional information The date and time is formatted as follows: Bit range Value range Description 0-4 0-29 2-second count 5-10 0-59 Minutes 11-15 0-23 Hours 16-20 1-31 Day of month 21-24 1-12 Month of year 25-31 0-127 Number of years since 1980 The following attributes are supported: Bitmask Description MTP_FILE_ATTR_WP File/directory can not be modified. MTP_FILE_ATTR_SYSTEM File/directory is required for the correct functioning of the system. MTP_FILE_ATTR_HIDDEN File/directory should not be shown to the user. acId should be unique for each file and directory on the file system and it should be persistent between MTP sessions. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 232 CHAPTER 8 8.4.2.2 Target API USB_MTP_INIT_DATA Description Structure which stores the parameters of the MTP interface. Type definition typedef struct { U8 EPIn; U8 EPOut; U8 EPInt; void * pObjectList; U32 NumBytesObjectList; void * pDataBuffer; U32 NumBytesDataBuffer; USB_MTP_INFO * pMTPInfo; U8 InterfaceNum; U32 NumBytesAllocated; U32 NumObjects; } USB_MTP_INIT_DATA; Structure members Member Description EPIn Endpoint for receiving data from host. EPOut Endpoint for sending data to host. EPInt Endpoint for sending events to host. pObjectList Pointer to a memory region where the list of MTP objects is stored. NumBytesObjectList Number of bytes allocated for the object list. pDataBuffer Pointer to a memory region to be used as communication buffer. NumBytesDataBuffer Number of bytes allocated for the data buffer. pMTPInfo Pointer to a USB_MTP_INFO structure. Filling this structure is mandatory. InterfaceNum Internal use. NumBytesAllocated Internal use. NumObjects Internal use. Additional information This structure holds the endpoints that should be used with the MTP interface. Refer to USBD_AddEP() for more information about how to add an endpoint. The number of bytes in the pDataBuffer should be a multiple of USB maximum packet size. The number of bytes in the object list depends on the number of files/directories on the storage medium. An object is assigned to each file/directory when the USB host requests the object information for the first time. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 233 CHAPTER 8 8.4.2.3 Target API USB_MTP_INFO Description Structure that is used when initialising the MTP module. Type definition typedef struct { const char * pManufacturer; const char * pModel; const char * pDeviceVersion; const char * pSerialNumber; } USB_MTP_INFO; Structure members Member Description pManufacturer Name of the device manufacturer. pModel Model name of the MTP device. pDeviceVersion Version of the MTP device. pSerialNumber Serial number of the MTP device. The serial number should contain exactly 32 hexadecimal characters. It must be unique among devices sharing the same model name and device version strings. The MTP device returns this string in the Serial Number field of the DeviceInfo dataset. For more information, refer to MTP specification. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 234 CHAPTER 8 8.4.2.4 Target API USB_MTP_INST_DATA Description Structure which stores the parameters of storage driver. Type definition typedef struct { const USB_MTP_STORAGE_API * pAPI; const char * sDescription; const char * sVolumeId; USB_MTP_INST_DATA_DRIVER DriverData; } USB_MTP_INST_DATA; Structure members Member Description pAPI Pointer to a structure that holds the storage device driver API. sDescription Human-readable string which identifies the storage. This string is displayed in Nautilus/Windows Explorer/etc. sVolumeId Unique volume identifier DriverData Driver data that are passed to the storage driver. Refer to USB_MTP_INST_DATA_DRIVER for detailed information about how to initialize this structure. This field must be up to 256 characters long but only the first 128 are significant and these must be unique for all storages of an MTP device. Additional information The MTP device returns the sDescription string in the Storage Description parameter and the sVolumeId in the Volume Identifier of the StorageInfo dataset. For more information, refer to MTP specification. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 235 CHAPTER 8 8.4.2.5 Target API USB_MTP_INST_DATA_DRIVER Description Structure which stores the parameters passed to the storage driver. Type definition typedef struct { const char * pRootDir; U8 IsRemovable; } USB_MTP_INST_DATA_DRIVER; Structure members Member Description pRootDir Path to directory to be used as the root of the storage. IsRemovable Internal use. Additional information pRootDir can specify the root of the file system or any other subdirectory. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 236 CHAPTER 8 8.4.2.6 Target API USB_MTP_STORAGE_API Description Structure that contains callbacks to the storage driver. Type definition typedef struct { USB_MTP_STORAGE_INIT USB_MTP_STORAGE_GET_INFO USB_MTP_STORAGE_FIND_FIRST_FILE USB_MTP_STORAGE_FIND_NEXT_FILE USB_MTP_STORAGE_OPEN_FILE USB_MTP_STORAGE_CREATE_FILE USB_MTP_STORAGE_READ_FROM_FILE USB_MTP_STORAGE_WRITE_TO_FILE USB_MTP_STORAGE_CLOSE_FILE USB_MTP_STORAGE_REMOVE_FILE USB_MTP_STORAGE_CREATE_DIR USB_MTP_STORAGE_REMOVE_DIR USB_MTP_STORAGE_FORMAT USB_MTP_STORAGE_RENAME_FILE USB_MTP_STORAGE_DEINIT USB_MTP_STORAGE_GET_FILE_ATTRIBUTES USB_MTP_STORAGE_MODIFY_FILE_ATTRIBUTES USB_MTP_STORAGE_GET_FILE_CREATION_TIME USB_MTP_STORAGE_GET_FILELAST_WRITE_TIME USB_MTP_STORAGE_GET_FILE_ID USB_MTP_STORAGE_GET_FILE_SIZE } USB_MTP_STORAGE_API; * * * * * * * * * * * * * * * * * * * * * pfInit; pfGetInfo; pfFindFirstFile; pfFindNextFile; pfOpenFile; pfCreateFile; pfReadFromFile; pfWriteToFile; pfCloseFile; pfRemoveFile; pfCreateDir; pfRemoveDir; pfFormat; pfRenameFile; pfDeInit; pfGetFileAttributes; pfModifyFileAttributes; pfGetFileCreationTime; pfGetFileLastWriteTime; pfGetFileId; pfGetFileSize; Structure members Member Description pfInit Initializes the storage medium. pfGetInfo Returns information about the storage medium such as storage capacity and the available free space. pfFindFirstFile Returns information about the first file in a given directory. pfFindNextFile Moves to next file and returns information about it. pfOpenFile Opens an existing file. pfCreateFile Creates a new file. pfReadFromFile Reads data from the current file. pfWriteToFile Writes data to current file. pfCloseFile Closes the current file. pfRemoveFile Removes a file from storage medium. pfCreateDir Creates a new directory. pfRemoveDir Removes a directory from storage medium. pfFormat Formats the storage. pfRenameFile Changes the name of a file or directory. pfDeInit De-initializes the storage medium. pfGetFileAttributes Reads the attributes of a file or directory. pfModifyFileAttributes Changes the attributes of a file or directory. pfGetFileCreationTime Returns the creation time of a file or directory. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 237 CHAPTER 8 Member Target API Description pfGetFileLastWriteTime Returns the time of the last modification made to a file or directory. pfGetFileId Returns the unique ID of a file or directory. pfGetFileSize Returns the size of a file in bytes. Additional information USB_MTP_STORAGE_API is used to retrieve information from the storage device driver or access data that needs to be read or written. Detailed information can be found in MTP Storage Driver on page 241. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 238 CHAPTER 8 8.4.2.7 Target API USB_MTP_STORAGE_INFO Description Structure which stores information about a storage. Type definition typedef struct { U32 NumKBytesTotal; U32 NumKBytesFreeSpace; U16 FSType; U8 IsWriteProtected; U8 IsRemovable; char DirDelimiter; } USB_MTP_STORAGE_INFO; Structure members Member Description NumKBytesTotal Storage capacity in kBytes NumKBytesFreeSpace Available free space on storage in kBytes FSType Type of file system as specified by MTP IsWriteProtected Set to 1 if the storage medium can not be modified IsRemovable Set to 1 if the storage medium can be removed from device DirDelimiter Character which separates the directory/file names in a path emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 239 CHAPTER 8 8.4.3 8.4.3.1 Target API Enums USB_MTP_EVENT Description Enum containing the MTP event codes. Type definition typedef enum { USB_MTP_EVENT_UNDEFINED, USB_MTP_EVENT_CANCELTRANSACTION, USB_MTP_EVENT_OBJECTADDED, USB_MTP_EVENT_OBJECTREMOVED, USB_MTP_EVENT_STOREADDED, USB_MTP_EVENT_STOREREMOVED, USB_MTP_EVENT_DEVICEPROPCHANGED, USB_MTP_EVENT_OBJECTINFOCHANGED, USB_MTP_EVENT_DEVICEINFOCHANGED, USB_MTP_EVENT_REQUESTOBJECTTRANSFER, USB_MTP_EVENT_STOREFULL, USB_MTP_EVENT_DEVICERESET, USB_MTP_EVENT_STORAGEINFOCHANGED, USB_MTP_EVENT_CAPTURECOMPLETE, USB_MTP_EVENT_UNREPORTEDSTATUS, USB_MTP_EVENT_OBJECTPROPCHANGED, USB_MTP_EVENT_OBJECTPROPDESCCHANGED, USB_MTP_EVENT_OBJECTREFERENCESCHANGED } USB_MTP_EVENT; Enumeration constants Constant Description USB_MTP_EVENT_UNDEFINED This event code is undefined, and is not used USB_MTP_EVENT_CANCELTRANSACTION This event is used to initiate the cancellation of a transaction over transports which do not have their own mechanism for cancelling transactions. Currently not used. USB_MTP_EVENT_OBJECTADDED This event informs the host about a new object that has been added to the storage. USB_MTP_EVENT_OBJECTREMOVED Informs the host that an object has been removed. USB_MTP_EVENT_STOREADDED This event indicates that a storage has been added to the device. It allows to dynamically show the available storages. USB_MTP_EVENT_STOREREMOVED This event indicates that a storage has been removed to the device. It allows to dynamically hide the available storages. USB_MTP_EVENT_DEVICEPROPCHANGED A property changed on the device has occurred. Currently not used. USB_MTP_EVENT_OBJECTINFOCHANGED This event indicates that the information for a particular object has changed and that the host should acquire the information once again. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 240 CHAPTER 8 Constant Target API Description USB_MTP_EVENT_DEVICEINFOCHANGED This event indicates that the capabilities of the device have changed and that the DeviceInfo should be requested again. Currently not used. USB_MTP_EVENT_REQUESTOBJECTTRANSFER This event can be used by the device to ask the host to initiate an file object transfer to him. Currently not used. USB_MTP_EVENT_STOREFULL This event should be sent when a storage becomes full. USB_MTP_EVENT_DEVICERESET Notifies the host about an internal reset. Currently not used USB_MTP_EVENT_STORAGEINFOCHANGED This event is used when information of a storage changes. USB_MTP_EVENT_CAPTURECOMPLETE Informs the host that the previously initiated capture acquire is complete. Currently not used. USB_MTP_EVENT_UNREPORTEDSTATUS This event may be implemented for certain transports in cases where the responder unable to report events to the initiator regarding changes in its internal status. Currently not used. USB_MTP_EVENT_OBJECTPROPCHANGED Informs about a change in the object property of an specific object. Currently not used. USB_MTP_EVENT_OBJECTPROPDESCCHANGED This event informs that the property description of an object property has been changed and needs to be re-acquired. Currently not used. USB_MTP_EVENT_OBJECTREFERENCESCHANGED This event is used to indicate that the references on an object have been updated. Currently not used. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 241 CHAPTER 8 8.5 MTP Storage Driver MTP Storage Driver This section describes the emUSB-Device MTP storage interface in detail. 8.5.1 General information This release comes with USB_MTP_StorageFS driver which uses emFile to access the storage medium. If you are using emFile this chapter can be ignored. This chapter is for those who wish to write a file system interface for a third-party file system. The storage interface is handled through an API-table, which contains all relevant functions necessary for read/write operations and initialization. Its implementation handles the details of how data is actually read from or written to memory. 8.5.2 Interface function list As described above, access to a storage media is realized through an API-function table of type USB_MTP_STORAGE_API. The structure is declared in USB_MTP.h and it is described in section Data structures on page 231 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 242 CHAPTER 8 8.5.3 MTP Storage Driver USB_MTP_STORAGE_API in detail 8.5.3.1 USB_MTP_STORAGE_INIT Description Initializes the storage medium. Type definition typedef void (USB_MTP_STORAGE_INIT)( U8 Unit, const USB_MTP_INST_DATA_DRIVER * pDriverData); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pFilePath Pointer to a USB_MTP_INST_DATA_DRIVER structure that contains all information that is necessary for the driver initialization. For detailed information about the USB_MTP_INST_DATA_DRIVER structure, refer to USB_MTP_INST_DATA_DRIVER. Additional information This function is called when the storage driver is added to emUSB-Device-MTP. It is the first function of the storage driver to be called. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 243 CHAPTER 8 8.5.3.2 MTP Storage Driver USB_MTP_STORAGE_GET_INFO Description Returns information about storage medium such as capacity and available free space. Type definition typedef void (USB_MTP_STORAGE_GET_INFO)(U8 Unit, USB_MTP_STORAGE_INFO * pStorageInfo); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pStorageInfo Pointer to a USB_MTP_STORAGE_INFO structure. For detailed information about the USB_MTP_STORAGE_INFO structure, refer to USB_MTP_STORAGE_INFO. Additional information Typically, this function is called immediately after the device is connected to USB host when the USB host requests information about the available storage mediums. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 244 CHAPTER 8 8.5.3.3 MTP Storage Driver USB_MTP_STORAGE_FIND_FIRST_FILE Description Returns information about the first file in a specified directory. Type definition typedef int (USB_MTP_STORAGE_FIND_FIRST_FILE)( U8 Unit, const char * pDirPath, USB_MTP_FILE_INFO * pFileInfo); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pDirPath Full path to the directory to be searched. pFileInfo out Information about the file/directory found. Return value =0 =1 <0 File/directory found No more files/directories found An error occurred Additional information The "." and ".." directory entries which are relevant only for the file system should be skipped. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 245 CHAPTER 8 8.5.3.4 MTP Storage Driver USB_MTP_STORAGE_FIND_NEXT_FILE Description Moves to next file and returns information about it. Type definition typedef int (USB_MTP_STORAGE_FIND_NEXT_FILE)(U8 Unit, USB_MTP_FILE_INFO * pFileInfo); Parameters Parameter Description Logical unit number. Specifies for which storage medium the function is called. Unit pFileInfo out Information about the file/directory found. Return value =0 =1 <0 File/directory found No more files/directories found An error occurred Additional information The "." and ".." directory entries which are relevant only for the file system should be skipped. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 246 CHAPTER 8 8.5.3.5 MTP Storage Driver USB_MTP_STORAGE_OPEN_FILE Description Opens a file for reading. Type definition typedef int (USB_MTP_STORAGE_OPEN_FILE)( U8 Unit, const char * pFilePath); Parameters Parameter Description Logical unit number. Specifies for which storage medium the function is called. Unit pFilePath in Full path to file. Return value =0 0 File opened An error occurred Additional information This function is called at the beginning of a file read operation. It is followed by one or more calls to USB_MTP_STORAGE_READ_FROM_FILE. At the end of data transfer the MTP module closes the file by calling USB_MTP_STORAGE_CLOSE_FILE. If the file does not exists an error should be returned. The MTP module opens only one file at a time. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 247 CHAPTER 8 8.5.3.6 MTP Storage Driver USB_MTP_STORAGE_CREATE_FILE Description Opens a file for writing. Type definition typedef int (USB_MTP_STORAGE_CREATE_FILE)( U8 Unit, const char * pDirPath, USB_MTP_FILE_INFO * pFileInfo); Parameters Parameter Description Logical unit number. Specifies for which storage medium the function is called. Unit pDirPath pFileInfo in Full path to directory where the file should be created. in Information about the file to be created. pFileName points to the name of the file. out pFilePath points to full path of created file, pFileName points to the beginning of file name in pFilePath. Return value =0 0 File created and opened An error occurred Additional information This function is called at the beginning of a file write operation. The name of the file is specified in the pFileName filed of pFileInfo. If the file exists it should be truncated to zero length. When a file is created, the call to USB_MTP_STORAGE_CREATE_FILE is followed by one or more calls to USB_MTP_STORAGE_WRITE_TO_FILE. If CreationTime and LastWriteTime in pFileInfo are not zero, these should be used instead of the time stamps generated by the file system. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 248 CHAPTER 8 8.5.3.7 MTP Storage Driver USB_MTP_STORAGE_READ_FROM_FILE Description Reads data from the current file. Type definition typedef int (USB_MTP_STORAGE_READ_FROM_FILE)(U8 Unit, U32 Off, void * pData, U32 NumBytes); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. Off Byte offset where to read from. out pData NumBytes Data read from file. Number of bytes to read from file. Return value =0 0 Data read from file An error occurred Additional information The function reads data from the file opened by USB_MTP_STORAGE_OPEN_FILE. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 249 CHAPTER 8 8.5.3.8 MTP Storage Driver USB_MTP_STORAGE_WRITE_TO_FILE Description Writes data to current file. Type definition typedef int (USB_MTP_STORAGE_WRITE_TO_FILE)( U8 Unit, U32 Off, const void * pData, U32 NumBytes); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. Off Byte offset where to read from. in pData NumBytes Data to write to file. Number of bytes to write to file. Return value =0 0 Data written to file An error occurred Additional information The function writes data to file opened by USB_MTP_STORAGE_CREATE_FILE. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 250 CHAPTER 8 8.5.3.9 MTP Storage Driver USB_MTP_STORAGE_CLOSE_FILE Description Closes the current file. Type definition typedef int (USB_MTP_STORAGE_CLOSE_FILE)(U8 Unit); Parameters Parameter Description Logical unit number. Specifies for which storage medium the function is called. Unit Return value =0 0 File closed. An error occurred Additional information The function closes the file opened by USB_MTP_STORAGE_CREATE_FILE or USB_MTP_STORAGE_OPEN_FILE. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 251 CHAPTER 8 8.5.3.10 MTP Storage Driver USB_MTP_STORAGE_REMOVE_FILE Description Removes a file/directory from the storage medium. Type definition typedef int (USB_MTP_STORAGE_REMOVE_FILE)( U8 Unit, const char * pFilePath); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pFilePath Full path to file/directory to be removed Return value =0 0 File removed. An error occurred emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 252 CHAPTER 8 8.5.3.11 MTP Storage Driver USB_MTP_STORAGE_CREATE_DIR Description Creates a directory on the storage medium. Type definition typedef int (USB_MTP_STORAGE_CREATE_DIR)( U8 Unit, const char * pDirPath, USB_MTP_FILE_INFO * pFileInfo); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pDirPath Full path to directory where the directory should be created. pFileInfo in Information about the directory to be created. pFileName points to the directory name. out pFilePath points to full path of directory, pFileName points to the beginning of directory name in pFilePath in Return value =0 0 Directory created. An error occurred Additional information If CreationTime and LastWriteTime in pFileInfo are not available, zero should be used instead of the time stamps generated by the file system. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 253 CHAPTER 8 8.5.3.12 MTP Storage Driver USB_MTP_STORAGE_REMOVE_DIR Description Removes a directory and its contents from the storage medium. Type definition typedef int (USB_MTP_STORAGE_REMOVE_DIR)( U8 Unit, const char * pDirPath); Parameters Parameter Description Logical unit number. Specifies for which storage medium the function is called. Unit pDirPath in Full path to directory to be removed. Return value =0 0 Directory removed. An error occurred Additional information The function should remove the directory and the entire file tree under it. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 254 CHAPTER 8 8.5.3.13 MTP Storage Driver USB_MTP_STORAGE_FORMAT Description Initializes the storage medium. Type definition typedef int (USB_MTP_STORAGE_FORMAT)(U8 Unit); Parameters Parameter Description Logical unit number. Specifies for which storage medium the function is called. Unit Return value =0 0 Storage medium initialized. An error occurred Additional information The file system layer has to differentiate between two cases, one where the MTP root directory is the same as the root directory of the file system and one where it is only a subdirectory of the file system. If pRootDir which was configured in the call to USB_MTP_STORAGE_INIT, points to a subdirectory of the file system, the storage medium should not be formatted. Instead, all the files and directories underneath pRootDir should be removed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 255 CHAPTER 8 8.5.3.14 MTP Storage Driver USB_MTP_STORAGE_RENAME_FILE Description Changes the name of a file or directory. Type definition typedef int (USB_MTP_STORAGE_RENAME_FILE)(U8 Unit, USB_MTP_FILE_INFO * pFileInfo); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pFileInfo Pointer to a USB_MTP_FILE_INFO structure. in Information about the file/directory to be renamed. pFilePath member points to the full path and pFileName points to the new name. out pFilePath member points to full path of file/directory with the new name, pFileName points to the beginning of file/directory name in pFilePath. The other structure fields should also be filled. Return value =0 0 File/directory renamed. An error occurred Additional information Only the name of the file/directory should be changed. The path to parent directory should remain the same. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 256 CHAPTER 8 8.5.3.15 MTP Storage Driver USB_MTP_STORAGE_DEINIT Description De-initializes the storage medium. Type definition typedef void (USB_MTP_STORAGE_DEINIT)(U8 Unit); Parameters Parameter Unit Description Logical unit number. Specifies for which storage medium the function is called. Additional information Typically called when the application calls USBD_Stop() to de-initialize emUSB-Device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 257 CHAPTER 8 8.5.3.16 MTP Storage Driver USB_MTP_STORAGE_GET_FILE_ATTRIBUTES Description Returns the attributes of a file or directory. Type definition typedef int (USB_MTP_STORAGE_GET_FILE_ATTRIBUTES)( U8 Unit, const char * pFilePath, U8 * pMask); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pFilePath Full path to file or directory (0-terminated string). out pMask The bitmask of the attributes. Return value =0 0 Information returned. An error occurred Additional information This function is called only when the compile time switch MTP_SAVE_FILE_INFO is set to 0. For the list of supported attributes refer to USB_MTP_FILE_INFO. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 258 CHAPTER 8 8.5.3.17 MTP Storage Driver USB_MTP_STORAGE_MODIFY_FILE_ATTRIBUTES Description Sets and clears file attributes. Type definition typedef int (USB_MTP_STORAGE_MODIFY_FILE_ATTRIBUTES)( U8 Unit, const char * pFilePath, U8 SetMask, U8 ClrMask); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pFilePath Full path to file or directory (0-terminated string). SetMask The bitmask of the attributes which should be set. ClrMask The bitmask of the attributes which should be cleared. Return value =0 0 Attributes modified. An error occurred Additional information This function is called only when the compile time switch MTP_SAVE_FILE_INFO is set to 0. For the list of supported attributes refer to USB_MTP_FILE_INFO. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 259 CHAPTER 8 8.5.3.18 MTP Storage Driver USB_MTP_STORAGE_GET_FILE_CREATION_TIME Description Returns the creation time of file or directory. Type definition typedef int (USB_MTP_STORAGE_GET_FILE_CREATION_TIME)( U8 Unit, const char * pFilePath, U32 * pTime); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pFilePath Full path to file or directory (0-terminated string). out pTime The creation time. Return value =0 0 Creation time returned. An error occurred Additional information This function is called only when the compile time switch MTP_SAVE_FILE_INFO is set to 0. For the list of supported attributes refer to USB_MTP_FILE_INFO. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 260 CHAPTER 8 8.5.3.19 MTP Storage Driver USB_MTP_STORAGE_GET_FILELAST_WRITE_TIME Description Returns the time when the file or directory was last modified. Type definition typedef int (USB_MTP_STORAGE_GET_FILELAST_WRITE_TIME)( U8 Unit, const char * pFilePath, U32 * pTime); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pFilePath Full path to file or directory (0-terminated string). out pTime The modification time. Return value =0 0 Modification time returned. An error occurred Additional information This function is called only when the compile time switch MTP_SAVE_FILE_INFO is set to 0. For the list of supported attributes refer to USB_MTP_FILE_INFO. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 261 CHAPTER 8 8.5.3.20 MTP Storage Driver USB_MTP_STORAGE_GET_FILE_ID Description Returns an ID which uniquely identifies the file or directory. Type definition typedef int (USB_MTP_STORAGE_GET_FILE_ID)( U8 Unit, const char * pFilePath, U8 * pId); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pFilePath Full path to file or directory (0-terminated string). pId out The unique ID of file or directory. Should point to a byte array MTP_NUM_BYTES_FILE_ID large. Return value =0 0 ID returned. An error occurred Additional information This function is called only when the compile time switch MTP_SAVE_FILE_INFO is set to 0. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 262 CHAPTER 8 8.5.3.21 MTP Storage Driver USB_MTP_STORAGE_GET_FILE_SIZE Description Returns the size of a file in bytes. Type definition typedef int (USB_MTP_STORAGE_GET_FILE_SIZE)( U8 Unit, const char * pFilePath, U32 * pFileSize); Parameters Parameter Description Unit Logical unit number. Specifies for which storage medium the function is called. pFilePath Full path to file or directory (0-terminated string). pFileSize out The size of file in bytes. Return value =0 0 Size of file returned. An error occurred Additional information This function is called only when the compile time switch MTP_SAVE_FILE_INFO is set to 0. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 9 Communication Device Class (CDC) This chapter describes how to get emUSB-Device up and running as a CDC device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 264 CHAPTER 9 9.1 Overview Overview The Communication Device Class (CDC) is an abstract USB class protocol defined by the USB Implementers Forum. This protocol covers the handling of the following communication flows: * * * * VirtualCOM/Serial interface Universal modem device ISDN communication Ethernet communication This implementation of CDC currently supports the virtual COM/Serial interface, thus the USB device will behave like a serial interface. Normally, a custom USB driver is not necessary because a kernel mode driver for USBCDC serial communication is delivered by major Microsoft Windows operating systems. For installing the USB-CDC serial device, an .inf file is needed, which is also delivered. Starting in Windows 10, such a file is not necessary anymore. A generic inf is provided, handling devices/interfaces with a Device-/InterfaceClass = 0x02 or Devic-e/InterfaceClass = 0x02 and Device-/InterfaceSubClass = 0x02. Linux handles USB 2 virtual COM ports since Kernel Ver. 2.4. Further information can be found in the Linux Kernel documentation. 9.1.1 Configuration The configuration section should later be modified to match the real application. For the purpose of getting emUSB-Device up and running as well as doing an initial test, the configuration as delivered should not be modified. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 265 9.2 CHAPTER 9 The example application The example application The start application (in the Application subfolder) is a simple echo server, which can be used to test emUSB-Device. The application receives data byte by byte and sends it back to the host. Source code excerpt from USB_CDC_Start.c: /********************************************************************* * * MainTask * * USB handling task. * Modify to implement the desired protocol */ void MainTask(void); void MainTask(void) { U32 i = 0; USB_CDC_HANDLE hInst; USBD_Init(); hInst = _AddCDC(); USBD_Start(); while (1) { char ac[64]; char acOut[30]; int NumBytesReceived; int NumBytesToSend; // // Wait for configuration // while ((USBD_GetState() & (USB_STAT_CONFIGURED | USB_STAT_SUSPENDED)) ! = USB_STAT_CONFIGURED) { BSP_ToggleLED(0); USB_OS_Delay(50); } BSP_SetLED(0); // // Receive at maximum of 64 Bytes // If less data has been received, // this should be OK. // NumBytesReceived = USBD_CDC_Receive(hInst, &ac[0], sizeof(ac), 0); i++; NumBytesToSend = sprintf(acOut, "%.3lu: Received %d byte(s) \"", i, NumBytesReceived); if (NumBytesReceived > 0) { USBD_CDC_Write(hInst, &acOut[0], NumBytesToSend, 0); USBD_CDC_Write(hInst, &ac[0], NumBytesReceived, 0); USBD_CDC_Write(hInst, "\"\n\r", 3, 0); } } } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 266 9.3 CHAPTER 9 Installing the driver Installing the driver Before connecting the device to the PC, simply start the driver installer (installdriver.exe) which is located in Windows\USB\CDC\ folder. After the executable is executed Windows may show the UAC message that a specific install program is started. Confirm with Yes to start installation: The driver installer will notify that Windows will show up a warning message that the driver is not signed by Microsoft. The is normal warning for driver that have been signed with a valid code signing certificate. Confirm read of the message by clicking on the OK button. The Device Driver Installation Wizard dialog shows up. Click on Next to continue with the driver installation. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 267 CHAPTER 9 Installing the driver During the driver installation you may be ask whether the device software should be installed. Since the package is signed with a valid code signing certificate, simply answer the question with "Install", optionally you can check the box >>Always trust software from "SEGGER Microcontroller GmbH & Co. KG".<<, which would allow to always trust driver packages coming from SEGGER. Once the driver is installed the driver wizard will confirm that the driver is successfully installed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 268 CHAPTER 9 Installing the driver Now the target device can be connected with the PC. Windows will detect the new hardware. It will try to find the appropriate driver for the device. After the previous driver installation, the driver should be found quite fastly and will install it for the device. To verify that the driver installation was successful, open the device manager by open the run dialog with [Windows Key]+[r] and Type devmgmt.msc in the Open edit field: The device manager will open and will show under Ports (COM & LPT) the installed device. Normally it will be called "USB CDC serial emulation (COMx)" whereas x the assigned COM port number is. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 269 CHAPTER 9 Installing the driver Double click on the device will show the device properties. Within the Device properties window the device status will be shown as the "The device is working properly". emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 270 CHAPTER 9 9.3.1 Installing the driver The .inf file The .inf file is required for installation. It is defined as: ; ; Device installation file for ; USB 2 COM port emulation ; Copyright (c) 2006-2014 by SEGGER Microcontroller GmbH & Co. KG ; ; This file supports: ; Windows 2000 ; Windows XP ; Windows Server 2003 x86, x64 ; Windows Vista x86, x64 ; Windows 7 x86,x64 ; Windows Server 2008 x86,x64 ; Windows 8 x86,x64 ; Windows 8.1 x86,x64 ; [Version] Signature="$Windows NT$" Class=Ports ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} Provider=%MFGNAME% DriverVer=03/12/2015,6.0.2600.5 CatalogFile=usbser.cat [Manufacturer] %MFGNAME%=CDCDevice,NT,NTamd64 [DestinationDirs] DefaultDestDir = 12 [CDCDevice.NT] %DESCRIPTION%=DriverInstall,USB\VID_8765&PID_0234 [CDCDevice.NTamd64] %DESCRIPTION%=DriverInstall,USB\VID_8765&PID_0234 [DriverInstall] Include=mdmcpq.inf CopyFiles=FakeModemCopyFileSection AddReg=DriverInstall.AddReg [DriverInstall.AddReg] HKR,,DevLoader,,*ntkern HKR,,NTMPDriver,,usbser.sys HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" [DriverInstall.Services] AddService=usbser, 0x00000002, DriverServiceInst [DriverServiceInst] DisplayName=%SERVICE% ServiceType=1 StartType=3 ErrorControl=1 ServiceBinary=%12%\usbser.sys [SourceDisksNames.amd64] 1=%DiskName%,, [SourceDisksFiles.amd64] [SourceDisksNames.x86] emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 271 CHAPTER 9 Installing the driver 1=%DiskName%,, [SourceDisksFiles.x86] [FakeModemCopyFileSection] [Strings] MFGNAME = "SEGGER" DESCRIPTION = "USB CDC serial port emulation" SERVICE = "USB CDC serial port emulation" DiskName="SEGGER USB CDC Installation Disk" red - required modifications green - possible modifications You have to personalize the .inf file on the red marked positions. Changes on the green marked positions are optional and not necessary for the correct function of the device. Replace the red marked positions with your personal Vendor ID (VID) and Product ID (PID). These are the value that have been passed by the function USBD_SetDeviceInfo(). 9.3.2 Signing the package Newer Windows versions from Windows Vista on, will only install a driver when the driver package is signed. This signment must be done with a valid code signing certificate. For testing purpose the package also be signed in a testing environment, please refer to: https://msdn.microsoft.com/en-us/windows/hardware/drivers/install/testsigning-driver-packages 9.3.3 Testing communication to the USB device The start application is a simple echo server. This means each character that is entered and sent through the virtual serial port will be sent back by the USB device. A simple Windows sample application is available to test the start application. The application is located in Windows\USB\CDC\SampleApplication\Exe. Alternatively any terminal program, such as PuTTY or TerraTerm or RealTerm, can be used to check the connectivity. This section shows how to start and make the first run of the sample application. * Go to the Windows\USB\CDC\SampleApplication\Exe folder double click on the Echo application. A console window will be open and will show that one device has been found with the desired CDC Product and Vendor ID. Enter 0 to connect to that device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 272 CHAPTER 9 Installing the driver * The application will ask for the amount of bytes the application shall send to and receive from the target device. * Now enter the number of repetitions the application shall send and receive to or from device and confirm with [Enter].. * The test will run and should look like the following screenshot: emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 273 emUSB-Device User Guide & Reference Manual CHAPTER 9 Installing the driver (c) 2010-2018 SEGGER Microcontroller GmbH 274 CHAPTER 9 9.4 Target API Target API This chapter describes the functions and data structures that can be used with the target application. 9.4.1 Interface function list Name Description API functions USBD_CDC_Add() Adds a CDC ACM class to the stack. USBD_CDC_CancelRead() Cancel a pending read operation. USBD_CDC_CancelWrite() Cancel a pending write operation. USBD_CDC_Read() Reads data from the host. USBD_CDC_ReadOverlapped() Reads data from the host asynchronously. USBD_CDC_Receive() Reads data from host. USBD_CDC_SetOnBreak() Sets a callback in order to inform the application about a break condition sent by the host. USBD_CDC_SetOnLineCoding() Sets a user callback that shall be called when a SET_LINE_CODING request is sent to the device. USBD_CDC_SetOnControlLineState() Sets a user callback that shall be called when a SET_LINE_STATE request is sent to the device. USBD_CDC_SetOnRXEvent() Sets a callback function for the OUT endpoint that will be called on every RX event for that endpoint. USBD_CDC_SetOnTXEvent() Sets a callback function for the IN endpoint that will be called on every TX event for that endpoint. USBD_CDC_UpdateSerialState() Sets the new serial state. USBD_CDC_Write() Writes data to the host. USBD_CDC_WaitForRX() This function is to be used in combination with USBD_CDC_ReadOverlapped() and waits for the reading data transfer from the host to complete. USBD_CDC_WaitForTX() This function is to be used in combination with a non-blocking call to USBD_CDC_Write(). USBD_CDC_WaitForTXReady() Waits (blocking) until the TX queue can accept another data packet. USBD_CDC_WriteSerialState() Sends the current control line serial state to the host. USBD_CDC_GetNumBytesRemToRead() This function is to be used in combination with USBD_CDC_ReadOverlapped(). USBD_CDC_GetNumBytesRemToWrite() This function is to be used in combination with a non-blocking call to USBD_CDC_Write(). USBD_CDC_GetNumBytesInBuffer() Returns the number of bytes that are available in the internal BULK-OUT endpoint buffer. Data structures emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 275 CHAPTER 9 Name Target API Description USB_CDC_INIT_DATA Initialization structure that is needed when adding a CDC interface to emUSB-Device. USB_CDC_LINE_CODING Structure that contains the new line-coding information sent by the host. USB_CDC_SERIAL_STATE Structure that contains the serial state that can be send to the host. USB_CDC_CONTROL_LINE_STATE Structure that contains the new control line state sent by the host. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 276 CHAPTER 9 9.4.1.1 Target API USBD_CDC_Add() Description Adds a CDC ACM class to the stack. Prototype USB_CDC_HANDLE USBD_CDC_Add(const USB_CDC_INIT_DATA * pInitData); Parameters Parameter pInitData Description Pointer to a USB_CDC_INIT_DATA structure. Return value Handle to a valid CDC instance. The handle of the first CDC instance is always 0. Additional information After the initialization of emUSB-Device, this is the first function that needs to be called when the USB-CDC interface is used with emUSB-Device. The returned value can be used with the CDC functions in order to talk to the right CDC instance. For creating more more than one CDC-Instance please make sure the USB_EnableIAD() is called before, otherwise none but the first CDC instance will work correctly. The same is true for composite devices including CDC and another, different USB class. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 277 CHAPTER 9 9.4.1.2 Target API USBD_CDC_CancelRead() Description Cancel a pending read operation. Prototype void USBD_CDC_CancelRead(USB_CDC_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid CDC instance, returned by USBD_CDC_Add(). Additional information This function can be called when a pending asynchronous read operation (triggered by USBD_CDC_ReadOverlapped()) should be canceled. The function can be called from any task. The function can also be used to cancel a call to one of the blocking read functions (when called from a different task or interrupt function). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 278 CHAPTER 9 9.4.1.3 Target API USBD_CDC_CancelWrite() Description Cancel a pending write operation. Prototype void USBD_CDC_CancelWrite(USB_CDC_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid CDC instance, returned by USBD_CDC_Add(). Additional information This function shall be called when a pending asynchronous write operation (triggered by non-blocking call to USBD_CDC_Write()) should be canceled. It can be called from any task. The function can also be used to cancel a call to a blocking write functions (when called from a different task or interrupt function). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 279 CHAPTER 9 9.4.1.4 Target API USBD_CDC_Read() Description Reads data from the host. Prototype int USBD_CDC_Read(USB_CDC_HANDLE hInst, void * pData, unsigned NumBytes, unsigned Timeout); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Timeout Timeout given in milliseconds. A zero value results in an infinite timeout. Return value = NumBytes 0 && < NumBytes <0 Requested data was successfully read within the given timeout. Timeout has occurred (Number of bytes read before timeout). An error occurred. Additional information This function blocks the task until all data has been read or a timeout occurs. In case of a reset or a disconnect USB_STATUS_ERROR is returned. If the USB stack receives a data packet from the host containing more bytes than requested, the remaining bytes are stored into the internal buffer of the endpoint, that was provided via USBD_AddEP(). This data can be retrieved by a later call to USBD_CDC_Receive() / USBD_CDC_Read(). See also USBD_CDC_GetNumBytesInBuffer(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 280 CHAPTER 9 9.4.1.5 Target API USBD_CDC_ReadOverlapped() Description Reads data from the host asynchronously. Prototype int USBD_CDC_ReadOverlapped(USB_CDC_HANDLE hInst, void * pData, unsigned NumBytes); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Return value 0 =0 <0 Number of bytes that have been read from the internal buffer (success). No data was found in the internal buffer (success). An error occurred. Additional information This function will not block the calling task. The read transfer will be initiated and the function returns immediately. In order to synchronize, USBD_CDC_WaitForRX() needs to be called. Another synchronization method would be to periodically call USBD_CDC_GetNumBytesRemToRead() in order to see how many bytes still need to be received (this method is preferred when a non-blocking solution is necessary). The read operation can be canceled using USBD_CDC_CancelRead(). The buffer pointed to by pData must be valid until the read operation is terminated. Example See USBD_CDC_GetNumBytesRemToRead on page 295. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 281 CHAPTER 9 9.4.1.6 Target API USBD_CDC_Receive() Description Reads data from host. The function blocks until any data have been received. In contrast to USBD_CDC_Read() this function does not wait for all of NumBytes to be received, but returns after the first packet has been received or after the timeout occurs. Prototype int USBD_CDC_Receive(USB_CDC_HANDLE hInst, void * pData, unsigned NumBytes, int Timeout); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Timeout Timeout given in milliseconds. A zero value results in an infinite timeout. If Timeout is -1, the function never blocks. Return value >0 =0 <0 Number of bytes that have been read within the given timeout. A timeout occurred (if Timeout > 0), zero packet received (not every controller supports this!), no data in buffer (if Timeout < 0) or the target was disconnected during the function call and no data was read so far. An error occurred. Additional information If no error occurs, this function returns the number of bytes received. Calling USBD_CDC_Receive() will return as much data as is currently available up to the size of the buffer specified within the specified timeout. This function also returns when the target is disconnected from the host or when a USB reset occurred during the function call, it will then return the number of bytes read so far. If the target was disconnected before this function was called, it returns USB_STATUS_ERROR. If the USB stack receives a data packet from the host containing more bytes than requested, the remaining bytes are stored into the internal buffer of the endpoint, that was provided via USBD_AddEP(). This data can be retrieved by a later call to USBD_CDC_Receive() / USBD_CDC_Read(). See also USBD_CDC_GetNumBytesInBuffer(). A call of USBD_CDC_Receive(Inst, NULL, 0, -1) can be used to trigger an asynchronous read that stores the data into the internal buffer. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 282 CHAPTER 9 9.4.1.7 Target API USBD_CDC_SetOnBreak() Description Sets a callback in order to inform the application about a break condition sent by the host. Prototype void USBD_CDC_SetOnBreak(USB_CDC_HANDLE hInst, USB_CDC_ON_SET_BREAK * pfOnBreak); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). pfOnBreak Pointer to the callback function. Additional information The callback is called in an ISR context, therefore it should should execute quickly. The callback function has the following prototype: typedef void USB_CDC_ON_SET_BREAK(unsigned BreakDuration); Parameter BreakDuration emUSB-Device User Guide & Reference Manual Description Length of the break signal in milliseconds. If BreakDuration is 0xFFFF, then the host will send a break until another SendBreak request is received with BreakDuration of 0x0000. (c) 2010-2018 SEGGER Microcontroller GmbH 283 CHAPTER 9 9.4.1.8 Target API USBD_CDC_SetOnLineCoding() Description Sets a user callback that shall be called when a SET_LINE_CODING request is sent to the device. Prototype void USBD_CDC_SetOnLineCoding(USB_CDC_HANDLE hInst, USB_CDC_ON_SET_LINE_CODING * pf); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). pf Pointer to the callback function. Additional information This function is used to register a user callback which notifies the application that the host has changed the line coding. The callback is called in an ISR context, therefore it should should execute quickly. The callback function has the following prototype: typedef void USB_CDC_ON_SET_LINE_CODING(USB_CDC_LINE_CODING * pLineCoding); Parameter pLineCoding emUSB-Device User Guide & Reference Manual Description Pointer to USB_CDC_LINE_CODING structure containing the new line coding parameters sent from the host. (c) 2010-2018 SEGGER Microcontroller GmbH 284 CHAPTER 9 9.4.1.9 Target API USBD_CDC_SetOnControlLineState() Description Sets a user callback that shall be called when a SET_LINE_STATE request is sent to the device. Prototype void USBD_CDC_SetOnControlLineState(USB_CDC_HANDLE hInst, USB_CDC_ON_SET_CONTROL_LINE_STATE * pf); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). pf Pointer to the callback function. Additional information This function is used to register a user callback which notifies the application that the host has changed the control line state. The callback is called in an ISR context, therefore it should should execute quickly. The callback function has the following prototype: typedef void USB_CDC_ON_SET_CONTROL_LINE_STATE(USB_CDC_CONTROL_LINE_STATE * pLineState); Parameter pLineState emUSB-Device User Guide & Reference Manual Description Pointer to USB_CDC_CONTROL_LINE_STATE structure containing the new line state parameters send from the host. (c) 2010-2018 SEGGER Microcontroller GmbH 285 CHAPTER 9 9.4.1.10 Target API USBD_CDC_SetOnRXEvent() Description Sets a callback function for the OUT endpoint that will be called on every RX event for that endpoint. Prototype void USBD_CDC_SetOnRXEvent(USB_CDC_HANDLE hInst, USB_EVENT_CALLBACK * pEventCb, USB_EVENT_CALLBACK_FUNC * pfEventCb, void * pContext); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). pEventCb Pointer to a USB_EVENT_CALLBACK structure (will be initialized by this function). pfEventCb Pointer to the callback routine that will be called on every event on the USB endpoint. pContext A pointer which is used as parameter for the callback function. Additional information The USB_EVENT_CALLBACK structure is private to the USB stack. It will be initialized by USBD_CDC_SetOnRXEvent(). The USB stack keeps track of all event callback functions using a linked list. The USB_EVENT_CALLBACK structure will be included into this linked list and must reside in static memory. The callback function is called only, if a read operation was started using one of the USBD_CDC_Read...() functions. The callback function has the following prototype: typedef void USB_EVENT_CALLBACK_FUNC(unsigned Events, void *pContext); Parameter Description Events A bit mask indicating which events occurred on the endpoint. pContext The pointer which was provided to the USBD_SetOnEvent function. Note that the callback function will be called within an ISR, therefore it should never block. The first parameter to the callback function will contain a bit mask for all events that triggered the call: Event Description USB_EVENT_DATA_READ Some data was received from the host on the endpoint. USB_EVENT_READ_COMPLETE The last read operation was completed. USB_EVENT_READ_ABORT A read transfer was aborted. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 286 CHAPTER 9 Target API Example // The callback function. static void _OnEvent(unsigned Events, void *pContext) { unsigned NumBytes; if (Events & USB_EVENT_DATA_READ) { NumBytes = USBD_CDC_GetNumBytesRemToRead(hInst); if (NumBytes) { r = USBD_CDC_Receive(hInst, Buff, NumBytes, -1); if (r > 0) { <.. process data in Buff..> } } } } // Main program. // Register callback function. static USB_EVENT_CALLBACK _usb_callback; USBD_CDC_SetOnRXEvent(hInst, &_usb_callback, _OnEvent, NULL); // Trigger first read USBD_CDC_Receive(Inst, NULL, 0, -1); <.. do anything else here while the data is processed in the callback ..> emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 287 CHAPTER 9 9.4.1.11 Target API USBD_CDC_SetOnTXEvent() Description Sets a callback function for the IN endpoint that will be called on every TX event for that endpoint. Prototype void USBD_CDC_SetOnTXEvent(USB_CDC_HANDLE hInst, USB_EVENT_CALLBACK * pEventCb, USB_EVENT_CALLBACK_FUNC * pfEventCb, void * pContext); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). pEventCb Pointer to a USB_EVENT_CALLBACK structure (will be initialized by this function). pfEventCb Pointer to the callback routine that will be called on every event on the USB endpoint. pContext A pointer which is used as parameter for the callback function. Additional information The USB_EVENT_CALLBACK structure is private to the USB stack. It will be initialized by USBD_CDC_SetOnTXEvent(). The USB stack keeps track of all event callback functions using a linked list. The USB_EVENT_CALLBACK structure will be included into this linked list and must reside in static memory. The callback function is called only, if a write operation was started using one of the USBD_CDC_Write...() functions. The callback function has the following prototype: typedef void USB_EVENT_CALLBACK_FUNC(unsigned Events, void *pContext); Parameter Description Events A bit mask indicating which events occurred on the endpoint. pContext The pointer which was provided to the USBD_SetOnEvent function. Note that the callback function will be called within an ISR, therefore it should never block. The first parameter to the callback function will contain a bit mask for all events that triggered the call: Event Description USB_EVENT_DATA_SEND Some data was send to the host, so that (part of) the user write buffer may be reused by the application. USB_EVENT_DATA_ACKED Some data was acknowledged by the host. USB_EVENT_WRITE_ABORT A write transfer was aborted. USB_EVENT_WRITE_COMPLETE All write operations were completed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 288 CHAPTER 9 Target API Example // The callback function. static void _OnEvent(unsigned Events, void *pContext) { if ((Events & USB_EVENT_DATA_SEND) != 0 && // Check for last write transfer to be completed. USBD_CDC_GetNumBytesRemToWrite(_hInst) == 0) { <.. prepare next data for writing..> // Send next packet of data. r = USBD_CDC_Write(_hInst, &ac[0], 200, -1); if (r < 0) { <.. error handling..> } } } // Main program. // Register callback function. static USB_EVENT_CALLBACK _usb_callback; USBD_CDC_SetOnTXEvent(hInst, &_usb_callback, _OnEvent, NULL); // Send the first packet of data using an asynchronous write operation. r = USBD_CDC_Write(_hInst, &ac[0], 200, -1); if (r < 0) { <.. error handling..> } <.. do anything else here while the whole data is send..> emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 289 CHAPTER 9 9.4.1.12 Target API USBD_CDC_UpdateSerialState() Description Sets the new serial state. Prototype void USBD_CDC_UpdateSerialState( USB_CDC_HANDLE hInst, const USB_CDC_SERIAL_STATE * pSerialState); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). pSerialState Pointer to the USB_CDC_SERIAL_STATE structure. Additional information This function updates the control line state internally. In order to inform the host about the serial state change, refer to the function USBD_CDC_WriteSerialState(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 290 CHAPTER 9 9.4.1.13 Target API USBD_CDC_Write() Description Writes data to the host. Depending on the Timeout parameter, the function may block until NumBytes have been written or a timeout occurs. Prototype int USBD_CDC_Write( USB_CDC_HANDLE hInst, const void * pData, unsigned NumBytes, int Timeout); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). pData Pointer to data that should be sent to the host. NumBytes Number of bytes to be written. Timeout Timeout in milliseconds. 0 means infinite. If Timeout is -1, the function returns immediately and the transfer is processed asynchronously. Return value =0 > 0 && < NumBytes = NumBytes <0 Successful started an asynchronous write transfer or a timeout has occurred and no data was written. Number of bytes that have been written before a timeout occurred. Write transfer successful completed. An error occurred. Additional information This function also returns when the target is disconnected from host or when a USB reset occurred. The USB stack is able to queue a small number of asynchronous write transfers (Timeout = -1). If a write transfer is still in progress when this function is called and the USB stack can not accept another write transfer request, the functions returns USB_STATUS_EP_BUSY. A synchronous write transfer (Timeout 0) will always block until the transfer (including all pending transfers) are finished. In order to synchronize, USBD_CDC_WaitForTX() needs to be called. Another synchronization method would be to periodically call USBD_CDC_GetNumBytesRemToWrite() in order to see how many bytes still need to be written (this method is preferred when a non-blocking solution is necessary). The write operation can be canceled using USBD_CDC_CancelWrite(). If pData = NULL and NumBytes = 0, a zero-length packet is sent to the host. The content of the buffer pointed to by pData must not be changed until the transfer has been completed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 291 CHAPTER 9 9.4.1.14 Target API USBD_CDC_WaitForRX() Description This function is to be used in combination with USBD_CDC_ReadOverlapped() and waits for the reading data transfer from the host to complete. Prototype int USBD_CDC_WaitForRX(USB_CDC_HANDLE hInst, unsigned Timeout); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). Timeout Timeout in milliseconds. 0 means infinite. Return value 0 1 Transfer completed. Timeout occurred. Additional information This function shall be called in order to synchronize task with the read data transfer previously initiated. The function blocks until the number of bytes specified by USBD_CDC_ReadOverlapped() has been read from the host. In case of a timeout, a current transfer is canceled. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 292 CHAPTER 9 9.4.1.15 Target API USBD_CDC_WaitForTX() Description This function is to be used in combination with a non-blocking call to USBD_CDC_Write(). This function waits for the writing data transfer to the host to complete. Prototype int USBD_CDC_WaitForTX(USB_CDC_HANDLE hInst, unsigned Timeout); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). Timeout Timeout in milliseconds. 0 means infinite. Return value 0 1 Transfer completed. Timeout occurred. Additional information This function shall be called in order to synchronize task with the write data transfer previously initiated. This function blocks until the number of bytes specified by USBD_CDC_Write() has been written to the host. In case of a timeout, a current transfer is canceled. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 293 CHAPTER 9 9.4.1.16 Target API USBD_CDC_WaitForTXReady() Description Waits (blocking) until the TX queue can accept another data packet. This function is used in combination with a non-blocking call to USBD_CDC_Write(), it waits until a new asynchronous write data transfer will be accepted by the USB stack. Prototype int USBD_CDC_WaitForTXReady(USB_CDC_HANDLE hInst, int Timeout); Parameters Parameter Description hInst Handle to a valid CDC instance, returned by USBD_CDC_Add(). Timeout Timeout in milliseconds. 0 means infinite. If Timeout is negative, the function will return immediately. Return value =0 =1 <0 A new asynchronous write data transfer will be accepted. The write queue is full, a call to USBD_CDC_Write() would return USB_STATUS_EP_BUSY. Error occurred. Additional information If Timeout is 0, the function never returns 1. If Timeout is -1, the function will not wait, but immediately return the current state. Example // Always keep the write queue full for maximum send speed. for (;;) { pData = GetNextData(&NumBytes); // Wait until stack can accept a new write. USBD_CDC_WaitForTxReady(hInst, 0); // Issue write transfer. if (USBD_CDC_Write(hInst, pData, NumBytes, -1) < 0) { <.. error handling..> } } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 294 CHAPTER 9 9.4.1.17 Target API USBD_CDC_WriteSerialState() Description Sends the current control line serial state to the host. Prototype void USBD_CDC_WriteSerialState(USB_CDC_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid CDC instance, returned by USBD_CDC_Add(). Additional information This function shall be called in order to inform the host about the control serial state of the CDC instance. The current control line serial state can be set using USBD_CDC_UpdateSerialState(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 295 CHAPTER 9 9.4.1.18 Target API USBD_CDC_GetNumBytesRemToRead() Description This function is to be used in combination with USBD_CDC_ReadOverlapped(). It returns the number of bytes which still have to be read during the transaction. Prototype int USBD_CDC_GetNumBytesRemToRead(USB_CDC_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid CDC instance, returned by USBD_CDC_Add(). Return value Number of bytes which still have to be read. Additional information Note that this function does not return the number of bytes that have been read, but the number of bytes which still have to be read. This function does not block. Example NumBytesReceived = USBD_CDC_ReadOverlapped(hInst, &ac[0], 50); if (NumBytesReceived < 0) { <.. error handling..> } if (NumBytesReceived > 0) { // Already had some data in the internal buffer. // The first 'NumBytesReceived' bytes may be processed here. <...> } else { // Wait until we get all 50 bytes while (USBD_CDC_GetNumBytesRemToRead(hInst) > 0) { USB_OS_Delay(50); } } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 296 CHAPTER 9 9.4.1.19 Target API USBD_CDC_GetNumBytesRemToWrite() Description This function is to be used in combination with a non-blocking call to USBD_CDC_Write(). It returns the number of bytes which still have to be written during the transaction. Prototype int USBD_CDC_GetNumBytesRemToWrite(USB_CDC_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid CDC instance, returned by USBD_CDC_Add(). Return value Number of bytes which still have to be written. Additional information Note that this function does not return the number of bytes that have been written, but the number of bytes which still have to be written. This function does not block. Example // NumBytesWritten will contain > 0 values if we had anything in the write buffer. NumBytesWritten = USBD_CDC_Write(hInst, &ac[0], TRANSFER_SIZE, -1); if (NumBytesWritten < 0) { <.. error handling..> } // NumBytesToWrite shows how many bytes still have to be written. while (USBD_CDC_GetNumBytesRemToWrite(hInst) > 0) { USB_OS_Delay(50); } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 297 CHAPTER 9 9.4.1.20 Target API USBD_CDC_GetNumBytesInBuffer() Description Returns the number of bytes that are available in the internal BULK-OUT endpoint buffer. Prototype int USBD_CDC_GetNumBytesInBuffer(USB_CDC_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid CDC instance, returned by USBD_CDC_Add(). Return value Number of bytes which have been stored in the internal buffer. Additional information The number of bytes returned by this function can be read using USBD_CDC_Read() without blocking. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 298 CHAPTER 9 9.4.2 Target API Data structures 9.4.2.1 USB_CDC_INIT_DATA Description Initialization structure that is needed when adding a CDC interface to emUSB-Device. Type definition typedef struct { U8 EPIn; U8 EPOut; U8 EPInt; } USB_CDC_INIT_DATA; Structure members Member Description EPIn Endpoint for sending data to the host. EPOut Endpoint for receiving data from the host. EPInt Endpoint for sending status information. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 299 CHAPTER 9 9.4.2.2 Target API USB_CDC_LINE_CODING Description Structure that contains the new line-coding information sent by the host. Type definition typedef struct { U32 DTERate; U8 CharFormat; U8 ParityType; U8 DataBits; } USB_CDC_LINE_CODING; Structure members Member Description DTERate The data transfer rate for the device in bits per second. CharFormat Number of stop bits: * 0 - 1 Stop bit * 1 - 1.5 Stop bits * 2 - 2 Stop bits ParityType Specifies the parity type: * 0 - None * 1 - Odd * 2 - Even * 3 - Mark * 4 - Space DataBits Specifies the bits per byte: (5, 6, 7, 8) emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 300 CHAPTER 9 9.4.2.3 Target API USB_CDC_SERIAL_STATE Description Structure that contains the serial state that can be send to the host. Type definition typedef struct { U8 DCD; U8 DSR; U8 Break; U8 Ring; U8 FramingError; U8 ParityError; U8 OverRunError; U8 CTS; } USB_CDC_SERIAL_STATE; Structure members Member Description DCD Data Carrier Detect: Tells that the device is connected to the telephone line. DSR Data Set Read: Device is ready to receive data. Break 1 - Break condition signaled. Ring Device indicates that it has detected a ring signal on the telephone line. FramingError When set to 1, the device indicates a framing error. ParityError When set to 1, the device indicates a parity error. OverRunError When set to 1, the device indicates an over-run error. CTS Deprecated, not specified at USB.org Additional information All members of the structure may have value 0 (false) or 1 (true). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 301 CHAPTER 9 9.4.2.4 Target API USB_CDC_CONTROL_LINE_STATE Description Structure that contains the new control line state sent by the host. Type definition typedef struct { U8 DTR; U8 RTS; } USB_CDC_CONTROL_LINE_STATE; Structure members Member Description DTR Data Terminal Ready. RTS Request To Send. Additional information All members of the structure may have value 0 (false) or 1 (true). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 302 CHAPTER 9 9.4.3 Target API Multithreading The emUSB CDC target API is not generally thread safe. But it is allowed to handle different endpoint in different task in parallel. Examples are: * * A task that performs all reads of data from the host while another task sends data to the host. Operating on different interfaces (e.g. a BULK and a CDC interface) in independent tasks. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 10 Human Interface Device Class (HID) This chapter gives a general overview of the HID class and describes how to get the HID component running on the target. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 304 CHAPTER 10 10.1 Overview Overview The Human Interface Device class (HID) is an abstract USB class protocol defined by the USB Implementers Forum. This protocol was defined for the handling of devices which are used by humans to control the operation of computer systems. An installation of a custom-host USB driver is not necessary, because the USB human interface device class is standardized and every major OS already provides host drivers for it. 10.1.1 Further reading The following documents define the HID class and have been used to implement and verify the HID component: * * [HID1] Device Class Definition for Human Interface Devices (HID), Firmware Specification--6/27/01 Version 1.11 [HID2] HID Usage Tables, 1/21/2005 Version 1.12 10.1.2 Categories Devices which are in the HID class generally fall into one of two categories: True HIDs and vendor specific HIDs, explained below. One or more examples for both categories are provided. 10.1.2.1 True HIDs True HID devices are devices which communicate directly with the host operating system, this includes devices which are used by a human to enter data, but do not directly exchange data with an application program running on the host. Typical examples * * * * * Keyboard Mouse and similar pointing devices Joystick Gamepad Front-panel controls - for example, switches and buttons. 10.1.2.2 Vendor specific HIDs These are HID devices communicating with an application program. The host OS loads the same driver it loads for any "true HID" and will automatically enumerate the device, but it cannot communicate with the device. When analyzing the report descriptor, the host finds that it cannot exchange information with the device; the device uses a protocol which is meaningless to the HID driver of the host. The host will therefore not exchange information with the device. A host recognizes a vendor specific HID by its vendor-defined usage page in the report descriptor: the numerical value of the usage page lies between 0xFF00 and 0xFFFF. An application has the chance to communicate with the particular device using API functions offered by the host. This enables an application program to communicate with the device without having to load a driver. HID does not take advantage of the full USB bus bandwidth; bulk communication can be much faster, but requires a driver. Therefore it can be a good choice to select HID as a device class, especially if ease of use is important and high communication speed is not required. Typical examples * * * * Bar-code reader Thermometer Voltmeter Low-speed JTAG emulator emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 305 CHAPTER 10 * Overview UPS (Uninterruptible power supply) emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 306 CHAPTER 10 10.2 10.2.1 Background information Background information HID descriptors This section presents an overview of the HID class-specific descriptors. The HID descriptors are defined in the Device Class Definition for Human Interface Devices (HID) of the USB Implementers Forum. Refer to the USB Implementers Forum website, www.usb.org, for detailed information about the USB HID standard. 10.2.1.1 HID descriptor A HID descriptor contains the report descriptor and optionally the physical descriptors. It specifies the number, type, and size of the report descriptor and the report's physical descriptors. 10.2.1.2 Report descriptor Data between host and device is exchanged in so called "reports". The report descriptor defines the format of a report. In general, HIDs require a report descriptor as defined in the Device Class Definition for Human Interface Devices (HID). The only exception to this are very basic HIDs such as mice or keyboards. This implementation of HID always requires a report descriptor. The USB Implementers Forum provides an application which helps to build and modify HID report descriptors. The HID Descriptor Tool can be downloaded from: http://www.usb.org/developers/hidpage/ emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 307 CHAPTER 10 10.2.1.3 Background information Physical descriptor Physical descriptor sets are optional descriptors which provide information about the part or parts of the human body used to activate the controls on a device. Physical descriptors are currently not supported. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 308 CHAPTER 10 10.3 10.3.1 Configuration Configuration Initial configuration To get emUSB-Device up and running as well as doing an initial test, the configuration as it is delivered should not be modified. The configuration must only be modified if emUSB-Device should be used in your final product. Refer to the section emUSB-Device Configuration on page 41 for detailed information about the functions which must be adapted before you can release a final product version. 10.3.2 Final configuration Generating a report descriptor This step is only required if your product is a vendor-specific human interface device. The report descriptor provided in the example application can typically be used without any modification. The vendor-defined usage page should be adapted in a final product. Vendor-defined usage pages can be in the range from 0xFF00 to 0xFFFF. The low byte can be selected by the application programmer. It needs to be identical on both target and host and should be unique (as unique as an 8-bit value can be). The example(s) use the value 0x12; this value is defined at the top of the application program with the macro USB_HID_DEFAULT_VENDOR_PAGE. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 309 CHAPTER 10 10.4 Example application Example application Example applications are supplied. These can be used for testing the correct installation and proper function of the device running emUSB-Device. The following start application files are provided: File Description USB_HID_Mouse.c Simple mouse example. ("True HID" example) USB_HID_Echo1.c Modified echo server. ("vendor specific" example) 10.4.1 USB_HID_Mouse.c USB_HID_Mouse.c is a typical example for a "true HID" implementation. The host identifies the device which is programmed with this example as a mouse. After the device is enumerated, it moves the mouse cursor in an endless loop to the left and after a short delay back to the right. 10.4.1.1 Running the example 1. Add USB_HID_Mouse.c to your project and build and download the application into the target. 2. When you connect your target to the host via USB, Windows will detect the new HID device. 3. If a connection can be established, it moves the mouse cursor as long as you do not disconnect your target. 10.4.2 USB_HID_Echo1.c USB_HID_Echo1.c is a typical example for a "vendor-specific HID" implementation. The HID start application ( USB_HID_Echo1.c located in the Application subfolder) is a modified echo server; the application receives data byte by byte, increments every single byte and sends them back to the host. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 310 CHAPTER 10 Example application To use this application, include the source code file USB_HID_Echo1.c into your project and compile and download it into your target. Run HIDEcho1.exe after the target is connected to the host and the enumeration process has been completed. The PC application is supplied as executable in the Windows\USB\HID\SampleApp\Exe directory. The source code of the PC example is also supplied. Refer to section Compiling the PC example application for more information to the PC example project. 10.4.2.1 Running the example 1. Add USB_HID_Echo1.c to your project and build and download the application into the target. 2. Connect your target to the host via USB while the example application is running, Windows will detect the new HID device. 3. If a connection can be established, it exchanges data with the target, testing the USB connection. If the host example application can communicate with the emUSB-Device device, the example application outputs the product name, Vendor and Product ID and the report size which will be used to communicate with the target. The target will be in interactive mode. Example output of USB_HID_Echo1.exe: emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 311 CHAPTER 10 Example application 4. Enter the number of reports that should be transmitted when the device is connected. Every dot in the terminal window indicates a transmission. 10.4.2.2 Compiling the PC example application Under Window you can build the sample by using the provided VisualStudio 2010 project. The source code of the example application is located in the subfolder Windows\USB\HID \SampleApp. Open the file USBHID_Start.sln and compile the source choose Build | Build SampleApp.exe (Shortcut: F7). To run the executable choose Build | Execute SampleApp.exe (Shortcut: CTRL-F5). Note The Microsoft Windows Driver Development Kit (DDK) is required to compile the HID host example application. Refer to http://www.microsoft.com/whdc/devtools/ddk/default.mspx for more information. Under Linux simply generate the executable by invoking make in the Windows/USB/HID/ SampleApp folder in a shell cd Windows/USB/HID/SampleApp make emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 312 CHAPTER 10 10.5 Target API Target API This section describes the functions that can be used on the target system. General information To communicate with the host, the example application project includes USB-specific header and source files. These files contain API functions to communicate with the USB host. Purpose of the USB Device API functions To have an easy start up when writing an application on the device side, these API functions have a simple interface and handle all operations that need to be done to communicate with the host. Therefore, all operations that need to write to or read from the emUSB-Device are handled internally by the provided API functions. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 313 CHAPTER 10 10.5.1 Target API Target interface function list Function Description API functions USBD_HID_Add() Adds HID class device to the USB interface. USBD_HID_GetNumBytesInBuffer() Returns the number of bytes available in the internal read buffer. USBD_HID_GetNumBytesRemToRead() Checks how many bytes still have to be read. USBD_HID_GetNumBytesRemToWrite() Checks how many bytes still have to be written. USBD_HID_Read() Reads data from the host with a given timeout. USBD_HID_ReadOverlapped() Reads data from the host asynchronously. USBD_HID_WaitForRX() This function is to be used in combination with USBD_HID_ReadOverlapped(). USBD_HID_WaitForTX() This function is to be used in combination with a non-blocking call to USBD_HID_Write(). USBD_HID_Write() Writes data to the host. USBD_HID_SetOnGetReportRequest() Allows to set a callback for the GET_REPORT command. USBD_HID_SetOnSetReportRequest() Allows to set a callback for the SET_REPORT command. Data structures Initialization structure that is needed when adding a HID interface to emUSB-Device. USB_HID_INIT_DATA Type definitions USB_HID_ON_GETREPORT_REQUEST_FUNC Callback function description which is set via USBD_HID_SetOnGetReportRequest(). USB_HID_ON_SETREPORT_REQUEST_FUNC Callback function description which is set via USBD_HID_SetOnSetReportRequest(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 314 CHAPTER 10 10.5.2 HID Target API functions 10.5.2.1 USBD_HID_Add() Target API Description Adds HID class device to the USB interface. Prototype USB_HID_HANDLE USBD_HID_Add(const USB_HID_INIT_DATA * pInitData); Parameters Parameter pInitData Description Pointer to a USB_HID_INIT_DATA structure. For detailed information refer to USB_HID_INIT_DATA. Return value USB_HID_HANDLE: Handle to the HID instance (can be zero). Additional information After the initialization of general emUSB-Device, this is the first function that needs to be called when the USB-HID interface is used with emUSB-Device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 315 CHAPTER 10 10.5.2.2 Target API USBD_HID_GetNumBytesInBuffer() Description Returns the number of bytes available in the internal read buffer. Prototype unsigned USBD_HID_GetNumBytesInBuffer(USB_HID_HANDLE hInst); Parameters Parameter Description Handle to an HID handle which is returned by USBD_HID_Add(). hInst Return value 0 Number of bytes in the internal read buffer. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 316 CHAPTER 10 10.5.2.3 Target API USBD_HID_GetNumBytesRemToRead() Description Checks how many bytes still have to be read. Prototype unsigned USBD_HID_GetNumBytesRemToRead(USB_HID_HANDLE hInst); Parameters Parameter Description Handle to an HID instance. hInst Return value 0 Number of bytes which have not yet been read. Additional information This function is to be used in combination with USBD_HID_ReadOverlapped(). After starting the read operation this function can be used to periodically check how many bytes still have to be read. Alternatively the blocking function USBD_HID_WaitForRX() can be used. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 317 CHAPTER 10 10.5.2.4 Target API USBD_HID_GetNumBytesRemToWrite() Description Checks how many bytes still have to be written. Prototype unsigned USBD_HID_GetNumBytesRemToWrite(USB_HID_HANDLE hInst); Parameters Parameter Description Handle to an HID instance. hInst Return value 0 Number of bytes which have not yet been written. Additional information This function is to be used in combination with a non-blocking call to USBD_HID_Write(). After starting the write operation this function can be used to periodically check how many bytes still have to be written. Alternatively the blocking function USBD_HID_WaitForTX() can be used. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 318 CHAPTER 10 10.5.2.5 Target API USBD_HID_Read() Description Reads data from the host with a given timeout. Prototype int USBD_HID_Read(USB_HID_HANDLE hInst, void * pData, unsigned NumBytes, unsigned Timeout); Parameters Parameter Description hInst Handle to an HID instance. pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Timeout Timeout given in milliseconds. A zero value results in an infinite timeout. Return value = NumBytes 0, < NumBytes <0 Requested data was successfully read within the given timeout. Timeout has occurred. Number of bytes that have been read within the given timeout. Returns a USB_STATUS_ERROR. Additional information This function blocks until the timeout has been reached, it has received NumBytes or until the device is disconnected from the host. This function blocks a task until all data has been read or a timeout occurs. In case of a reset or a disconnect USB_STATUS_ERROR is returned. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 319 CHAPTER 10 10.5.2.6 Target API USBD_HID_ReadOverlapped() Description Reads data from the host asynchronously. Prototype int USBD_HID_ReadOverlapped(USB_HID_HANDLE hInst, void * pData, unsigned NumBytes); Parameters Parameter Description hInst Handle to a HID instance. pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Return value >0 =0 <0 Number of bytes that have been read from the internal buffer (success). No data was found in the internal buffer (success). Error. Additional information This function will not block the calling task. The read transfer will be initiated and the function returns immediately. In order to synchronize, USBD_HID_WaitForRX() needs to be called. Alternatively the function USBD_HID_GetNumBytesRemToRead() can be called periodically to check whether all bytes have been written or not. The buffer pointed to by pData must be valid until the read operation is terminated. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 320 CHAPTER 10 10.5.2.7 Target API USBD_HID_WaitForRX() Description This function is to be used in combination with USBD_HID_ReadOverlapped(). After the read function has been called this function can be used to synchronise. It will block until the transfer is completed. Prototype int USBD_HID_WaitForRX(USB_HID_HANDLE hInst, unsigned Timeout); Parameters Parameter Description hInst Handle to a HID instance. Timeout Timeout given in milliseconds. A zero value results in an infinite timeout. Return value 0 1 Transfer completed. Timeout occurred. Additional information In case of a timeout, a current transfer is canceled. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 321 CHAPTER 10 10.5.2.8 Target API USBD_HID_WaitForTX() Description This function is to be used in combination with a non-blocking call to USBD_HID_Write(). After the write function has been called this function can be used to synchronise. It will block until the transfer is completed. Prototype int USBD_HID_WaitForTX(USB_HID_HANDLE hInst, unsigned Timeout); Parameters Parameter Description hInst Handle to a HID instance. Timeout Timeout given in milliseconds. A zero value results in an infinite timeout. Return value 0 1 Transfer completed. Timeout occurred. Additional information In case of a timeout, a current transfer is canceled. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 322 CHAPTER 10 10.5.2.9 Target API USBD_HID_Write() Description Writes data to the host. Depending on the Timeout parameter, the function may block until NumBytes have been written or a timeout occurs. Prototype int USBD_HID_Write( USB_HID_HANDLE hInst, const void * pData, unsigned NumBytes, int Timeout); Parameters Parameter Description hInst Handle to an HID instance. pData Pointer to data that should be sent to the host. NumBytes Number of bytes to write. Timeout Timeout in milliseconds. 0 means infinite. If Timeout is -1, the function returns immediately and the transfer is processed asynchronously. Return value =0 > 0 && < NumBytes = NumBytes <0 Successful started an asynchronous write transfer or a timeout has occurred and no data was written. Number of bytes that have been written before a timeout occurred. Write transfer successful completed. Error occurred. Additional information This function also returns when the target is disconnected from host or when a USB reset occurred. The USB stack is able to queue a small number of asynchronous write transfers (Timeout = -1). If a write transfer is still in progress when this function is called and the USB stack can not accept another write transfer request, the functions returns USB_STATUS_EP_BUSY. In order to synchronize, USBD_HID_WaitForTX() needs to be called. Another synchronization method would be to periodically call USBD_HID_GetNumBytesRemToWrite() in order to see how many bytes still need to be written (this method is preferred when a non-blocking solution is necessary). The content of the buffer pointed to by pData must not be changed until the transfer has been completed. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 323 CHAPTER 10 10.5.2.10 Target API USBD_HID_SetOnGetReportRequest() Description Allows to set a callback for the GET_REPORT command. The GET_REPORT command is sent from the host to the device. Prototype void USBD_HID_SetOnGetReportRequest (USB_HID_HANDLE hInst, USB_HID_ON_GETREPORT_REQUEST_FUNC * pfOnGetReportRequest); Parameters Parameter Description hInst Handle to an HID instance. pfOnGetReportRequest Pointer to a function of type USB_HID_ON_GETREPORT_REQUEST_FUNC. Additional information See the description of USB_HID_ON_GETREPORT_REQUEST_FUNC for more details. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 324 CHAPTER 10 10.5.2.11 Target API USBD_HID_SetOnSetReportRequest() Description Allows to set a callback for the SET_REPORT command. The SET_REPORT command is sent from the host to the device. Prototype void USBD_HID_SetOnSetReportRequest (USB_HID_HANDLE hInst, USB_HID_ON_SETREPORT_REQUEST_FUNC * pfOnSetReportRequest); Parameters Parameter Description hInst Handle to an HID instance. pfOnSetReportRequest Pointer to a function of type USB_HID_ON_SETREPORT_REQUEST_FUNC . Additional information See the description of USB_HID_ON_SETREPORT_REQUEST_FUNC for more details. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 325 CHAPTER 10 10.5.3 Data structures 10.5.3.1 USB_HID_INIT_DATA Target API Description Initialization structure that is needed when adding a HID interface to emUSB-Device. Type definition typedef struct { U8 EPIn; U8 EPOut; const U8 * pReport; U16 NumBytesReport; U16 BuffSize; U8 * pBuff; } USB_HID_INIT_DATA; Structure members Member Description EPIn Endpoint for sending data to the host. EPOut Endpoint for receiving data from the host. pReport Pointer to a report descriptor. NumBytesReport Size of the HID report descriptor in bytes. BuffSize Size of the buffer pointed to by pBuff pBuff Pointer to a buffer for receiving reports from the host via endpoint 0 (Set_Report request) Additional information To be able to receive data from the host either an endpoint must be allocated (EPOut) or a buffer must be provided (BufferSize, pBuff). If EPOut = 0 and BufferSize = 0, then USBD_HID_Read() will not work and all requests from the host will be stalled by the USB stack. pReport points to a report descriptor. A report descriptor is a structure which is used to transmit HID control data to and from a human interface device. A report descriptor defines the format of a report and is composed of report items that define one or more toplevel collections. Each collection defines one or more HID reports. Refer to Universal Serial Bus Specification, 1.0 Version and the latest version of the HID Usage Tables guide for detailed information about HID input, output and feature reports. The USB Implementers Forum provide an application that helps to build and modify HID report descriptors. The HID Descriptor Tool can be downloaded from: www.usb.org/developers/hidpage/. The report descriptor used in the supplied example application HID_Echo1.c should match to the requirements of most "vendor specific HID" applications. The report size is defined to 64 bytes. As mentioned before, interrupt endpoints are limited to at most one packet of at most 64 bytes per frame (on full speed devices). Example 1 (configure to receive reports via seperate endpoint) static void _AddHID(void) { USB_HID_INIT_DATA InitData; U8 Interval = 10; static U8 acBuffer[64]; memset(&InitData, 0, sizeof(InitData)); InitData.EPIn = USB_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_INT, Interval, NULL, 0); InitData.EPOut = USB_AddEP(USB_DIR_OUT, USB_TRANSFER_TYPE_INT, Interval, &acBuffer[0], sizeof(acBuffer)); InitData.pReport = _aHIDReport; InitData.NumBytesReport = sizeof(_aHIDReport); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 326 CHAPTER 10 Target API USBD_HID_Add(&InitData); } Example 2 (configure to receive reports via endpoint 0) static void _AddHID(void) { USB_HID_INIT_DATA InitData; U8 Interval = 10; static U8 acBuffer[64]; memset(&InitData, 0, sizeof(InitData)); InitData.EPIn = USB_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_INT, Interval, NULL, 0); InitData.pBuff = &acBuffer[0]; InitData.BufferSize = sizeof(acBuffer); InitData.pReport = _aHIDReport; InitData.NumBytesReport = sizeof(_aHIDReport); USBD_HID_Add(&InitData); } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 327 CHAPTER 10 Target API 10.5.4 Type definitions 10.5.4.1 USB_HID_ON_GETREPORT_REQUEST_FUNC Description Callback function description which is set via USBD_HID_SetOnGetReportRequest(). Type definition typedef int USB_HID_ON_GETREPORT_REQUEST_FUNC( USB_HID_REPORT_TYPE unsigned const U8 * * U32 * ReportType, ReportId, pData, pNumBytes); Parameters Parameter Description ReportType HID report type, possible values are: * USB_HID_REPORT_TYPE_INPUT * USB_HID_REPORT_TYPE_OUTPUT * USB_HID_REPORT_TYPE_FEATURE ReportId The ID of the report for which the GET_REPORT request has been sent. pData in Pointer to a pointer to the data to send via GET_REPORT request. pNumBytes IN: Number of bytes requested. Out: Number of bytes that shall be sent. Return value =0 =1 <0 No data available. The stack will send a zero length packet as a response. Data is available. The stack will send data to the host. Data is handled by user application. USB_WriteEP0FromISR needs to be called from user context. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 328 CHAPTER 10 10.5.4.2 Target API USB_HID_ON_SETREPORT_REQUEST_FUNC Description Callback function description which is set via USBD_HID_SetOnSetReportRequest(). Type definition typedef void USB_HID_ON_SETREPORT_REQUEST_FUNC(USB_HID_REPORT_TYPE ReportType, unsigned ReportId, U32 NumBytes); Parameters Parameter Description ReportType HID report type, possible values are: * USB_HID_REPORT_TYPE_INPUT * USB_HID_REPORT_TYPE_OUTPUT * USB_HID_REPORT_TYPE_FEATURE ReportId The ID of the report for which the SET_REPORT request has been sent. Additional information In case no EP Out was used with the HID interface, USBD_HID_Read can be used to read the report that has been sent from the host. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 329 CHAPTER 10 10.6 Host API Host API This chapter describes the functions that can be used with the Windows host system. This functions are only required if the emUSB-Device-HID component is used to design a vendor specific HID. General information To communicate with the target USB-HID stack, the example application project includes a USB-HID specific source and header file (USBHID.c, USBHID.h). These files contain API functions to communicate with the USB-HID target through the USB-Bulk driver. Purpose of the USB Host API functions To have an easy start-up when writing an application on the host side, these API functions have simple interfaces and handle all operations that need to be done to communicate with the target USB-HID stack. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 330 CHAPTER 10 10.6.1 Host API Host API function list Function Description API functions USBHID_Close() Close the connection an open device. USBHID_Open() Opens a handle to a device. USBHID_Init() Sets the specific vendor page, initializes the USB HID User API and retrieves the information of the HID device. USBHID_Exit() Closes the connection to all open devices and de-initializes the HID module. USBHID_GetNumAvailableDevices() Returns the number of available devices. USBHID_GetProductName() Stores the name of the device into pBuffer. USBHID_GetInputReportSize() Returns the input report size of the device. USBHID_GetOutputReportSize() Returns the output report size of the device. USBHID_GetProductId() Returns the product ID of the device. USBHID_GetVendorId() Returns the vendor ID of the device. USBHID_RefreshList() Refreshes the connection info list. USBHID_SetVendorPage() Sets the vendor page so that all HID device with the specified page will be found. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 331 CHAPTER 10 10.6.2 HID Host API functions 10.6.2.1 USBHID_Close() Host API Description Close the connection an open device. Prototype void USBHID_Close(unsigned Id); Parameters Parameter Id Description Index of the HID device. This is the bit number of the mask returned by USBHID_GetNumAvailableDevices(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 332 CHAPTER 10 10.6.2.2 Host API USBHID_Open() Description Opens a handle to a device. Prototype int USBHID_Open(unsigned Id); Parameters Parameter Description Index of the HID device. This is the bit number of the mask returned by USBHID_GetNumAvailableDevices(). Id Return value 0 1 O.K. Opening was successful or already opened. Error. Handle to the device could not opened. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 333 CHAPTER 10 10.6.2.3 Host API USBHID_Init() Description Sets the specific vendor page, initializes the USB HID User API and retrieves the information of the HID device. Prototype void USBHID_Init(U8 VendorPage); Parameters Parameter VendorPage Description This parameter specifies the lower 8 bits of the vendor-specific usage page number. It must be identical on both device and host. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 334 CHAPTER 10 10.6.2.4 Host API USBHID_Exit() Description Closes the connection to all open devices and de-initializes the HID module. Prototype void USBHID_Exit(void); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 335 CHAPTER 10 10.6.2.5 Host API USBHID_GetNumAvailableDevices() Description Returns the number of available devices. Prototype unsigned USBHID_GetNumAvailableDevices(U32 * pMask); Parameters Parameter pMask Description Pointer to unsigned integer value which is used to store the bit mask of available devices. This parameter may be NULL. Return value Number of available devices. Additional information pMask will be filled by this routine. It shall be interpreted as a bit mask where a bit set means this device is available. For example, device 0 and device 2 are available, if pMask has the value 0x00000005. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 336 CHAPTER 10 10.6.2.6 Host API USBHID_GetProductName() Description Stores the name of the device into pBuffer. Prototype int USBHID_GetProductName(unsigned Id, char * pBuffer, unsigned NumBytes); Parameters Parameter Description Id Index of the HID device. This is the bit number of the mask returned by USBHID_GetNumAvailableDevices(). pBuffer Pointer to a buffer for the product name. NumBytes Size of the buffer in bytes. Return value 0 1 An error occurred. Success. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 337 CHAPTER 10 10.6.2.7 Host API USBHID_GetInputReportSize() Description Returns the input report size of the device. Prototype int USBHID_GetInputReportSize(unsigned Id); Parameters Parameter Description Index of the HID device. This is the bit number of the mask returned by USBHID_GetNumAvailableDevices(). Id Return value =0 0 An error occurred. Size of the report in bytes. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 338 CHAPTER 10 10.6.2.8 Host API USBHID_GetOutputReportSize() Description Returns the output report size of the device. Prototype int USBHID_GetOutputReportSize(unsigned Id); Parameters Parameter Description Index of the HID device. This is the bit number of the mask returned by USBHID_GetNumAvailableDevices(). Id Return value =0 0 An error occurred. Size of the report in bytes. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 339 CHAPTER 10 10.6.2.9 Host API USBHID_GetProductId() Description Returns the product ID of the device. Prototype U16 USBHID_GetProductId(unsigned Id); Parameters Parameter Description Index of the HID device. This is the bit number of the mask returned by USBHID_GetNumAvailableDevices(). Id Return value =0 0 An error occurred. Product ID. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 340 CHAPTER 10 10.6.2.10 Host API USBHID_GetVendorId() Description Returns the vendor ID of the device. Prototype U16 USBHID_GetVendorId(unsigned Id); Parameters Parameter Description Index of the HID device. This is the bit number of the mask returned by USBHID_GetNumAvailableDevices(). Id Return value =0 0 An error occurred. Vendor ID. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 341 CHAPTER 10 10.6.2.11 Host API USBHID_RefreshList() Description Refreshes the connection info list. Prototype void USBHID_RefreshList(void); Additional information Note that any open handles will be closed while refreshing the connection list. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 342 CHAPTER 10 10.6.2.12 Host API USBHID_SetVendorPage() Description Sets the vendor page so that all HID device with the specified page will be found. Prototype void USBHID_SetVendorPage(U8 Page); Parameters Parameter VendorPage Description This parameter specifies the lower 8 bits of the vendor-specific usage page number. It must be identical on both device and host. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 11 Printer Class This chapter describes how to get emUSB-Device up and running as a printer device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 344 CHAPTER 11 11.1 Overview Overview The Printer Class is an abstract USB class protocol defined by the USB Implementers Forum. This protocol delivers the existing printing command-sets to a printer over USB. 11.1.1 Configuration The configuration section will later on be modified to match the real application. For the purpose of getting emUSB-Device up and running as well as doing an initial test, the configuration as delivered should not be modified. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 345 CHAPTER 11 11.2 The example application The example application The start application (in the Application subfolder) is a simple data sink, which can be used to test emUSB-Device. The application receives data bytes from the host which it displays in the terminal I/O window of the debugger. Part of source code of USB_Printer.c: <...> /********************************************************************* * * _GetDeviceIdString * */ static const char * _GetDeviceIdString(void) { const char * s = "CLASS:PRINTER;MODEL:HP LaserJet 6MP;" "MANUFACTURER:Hewlett-Packard;" "DESCRIPTION:Hewlett-Packard LaserJet 6MP Printer;" "COMMAND SET:PJL,MLC,PCLXL,PCL,POSTSCRIPT;"; return s; } /********************************************************************* * * _GetHasNoError * */ static U8 _GetHasNoError(void) { return 1; } /********************************************************************* * * _GetIsSelected * */ static U8 _GetIsSelected(void) { return 1; } /********************************************************************* * * _GetIsPaperEmpty * */ static U8 _GetIsPaperEmpty(void) { return 0; } /********************************************************************* * * _OnDataReceived * */ static int _OnDataReceived(const U8 * pData, unsigned NumBytes) { USB_MEMCPY(_acData, pData, NumBytes); _acData[NumBytes] = 0; printf(_acData); return 0; } /********************************************************************* * * _OnReset * */ static void _OnReset(void) { } static USB_PRINTER_API _PrinterAPI = { _GetDeviceIdString, _OnDataReceived, _GetHasNoError, emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 346 CHAPTER 11 The example application _GetIsSelected, _GetIsPaperEmpty, _OnReset }; /********************************************************************* * * Public code * ********************************************************************** */ static const USB_DEVICE_INFO _DeviceInfo = { 0x8765, // VendorId 0x2114, // ProductId, should be unique for this sample "Vendor", // VendorName "Printer", // ProductName "12345678901234567890" // SerialNumber }; /********************************************************************* * * MainTask * * Function description * USB handling task. * Modify to implement the desired protocol */ void MainTask(void) { USBD_Init(); USBD_SetDeviceInfo(&_DeviceInfo); USB_PRINTER_Init(&_PrinterAPI); USBD_Start(); while (1) { // // Wait for configuration // while ((USBD_GetState() & (USB_STAT_CONFIGURED | USB_STAT_SUSPENDED)) != USB_STAT_CONFIGURED) { BSP_ToggleLED(0); USB_OS_Delay(50); } // // Receive and process data. // USB_PRINTER_Task(); } } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 347 CHAPTER 11 11.3 Target API Target API This chapter describes the functions and data structures that can be used with the target application. 11.3.1 Interface function list Function Description API functions USB_PRINTER_Init() Initializes the printer module. USB_PRINTER_Task() Processes the requests received from the USB Host. USB_PRINTER_TaskEx() Processes the requests received from the USB Host. USB_PRINTER_ConfigIRQProcessing() Configure printer class to process received data in USB interrupt. Advanced API functions USB_PRINTER_Read() Reads data from the host. USB_PRINTER_ReadTimed() Reads data from the host with a given timeout. USB_PRINTER_Receive() Reads data from host. USB_PRINTER_ReceiveTimed() Reads data from host with a given timeout. USB_PRINTER_Write() Writes data to the host. USB_PRINTER_WriteTimed() Writes data to the host within a given timeout. Data structures USB_PRINTER_API emUSB-Device User Guide & Reference Manual Initialization structure that is needed when adding a printer interface to emUSB-Device. (c) 2010-2018 SEGGER Microcontroller GmbH 348 CHAPTER 11 11.3.2 API functions 11.3.2.1 USB_PRINTER_Init() Target API Description Initializes the printer module. Prototype void USB_PRINTER_Init(USB_PRINTER_API * pAPI); Parameters Parameter pAPI Description Pointer to an API table that contains all callback functions that are necessary for handling the functionality of a printer. Additional information After the initialization of general emUSB-Device, this is the first function that needs to be called when the printer class is used with emUSB-Device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 349 CHAPTER 11 11.3.2.2 Target API USB_PRINTER_Task() Description Processes the requests received from the USB Host. Prototype void USB_PRINTER_Task(void); Additional information This function blocks as long as the USB device is connected to USB host. It handles the requests by calling the function registered in the call to USB_PRINTER_Init(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 350 CHAPTER 11 11.3.2.3 Target API USB_PRINTER_TaskEx() Description Processes the requests received from the USB Host. Uses overlapped read operation for higher performance. Prototype void USB_PRINTER_TaskEx(void); Additional information This function blocks as long as the USB device is connected to USB host. It handles the requests by calling the function registered in the call to USB_PRINTER_Init(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 351 CHAPTER 11 11.3.2.4 Target API USB_PRINTER_ConfigIRQProcessing() Description Configure printer class to process received data in USB interrupt. Must be called after USB_PRINTER_Init() and before USBD_Start(). After calling this function, USB_PRINTER_Task() should never be called. Prototype void USB_PRINTER_ConfigIRQProcessing(void); Additional information The printer API function pfOnDataReceived is called within the USB interrupt context and must not block. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 352 CHAPTER 11 11.3.2.5 Target API USB_PRINTER_Read() Description Reads data from the host. Prototype int USB_PRINTER_Read(void * pData, unsigned NumBytes); Parameters Parameter Description pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Return value = NumBytes < NumBytes Success. Error occurred. Additional information This function blocks a task until all data has been read. In case of a reset or a disconnect USB_STATUS_ERROR is returned. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 353 CHAPTER 11 11.3.2.6 Target API USB_PRINTER_ReadTimed() Description Reads data from the host with a given timeout. Prototype int USB_PRINTER_ReadTimed(void * pData, unsigned NumBytes, unsigned ms); Parameters Parameter Description pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. ms Timeout in milliseconds. A zero value results in an infinite timeout. Return value = NumBytes 0, < NumBytes <0 Success. Number of bytes that have been read within the given timeout. Error. Additional information This function blocks a task until all data has been read or a timeout occurs. In case of a reset or a disconnect USB_STATUS_ERROR is returned. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 354 CHAPTER 11 11.3.2.7 Target API USB_PRINTER_Receive() Description Reads data from host. The function blocks until any data has been received. In contrast to USB_PRINTER_Read() this function does not wait for all of NumBytes to be received, but returns after the first packet has been received. Prototype int USB_PRINTER_Receive(void * pData, unsigned NumBytes); Parameters Parameter Description pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. Return value >0 =0 <0 Number of bytes that have been read. Zero packet received (not every controller supports this!) or the target was disconnected during the function call. Error. Additional information If no error occurs, this function returns the number of bytes received. Calling USB_PRINTER_Receive() will return as much data as is currently available up to the size of the buffer specified. This function also returns when target is disconnected from host or when a USB reset occurred, it will then return the number of bytes read. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 355 CHAPTER 11 11.3.2.8 Target API USB_PRINTER_ReceiveTimed() Description Reads data from host with a given timeout. The function blocks until any data has been received. In contrast to USB_PRINTER_ReadTimed() this function does not wait for all of NumBytes tobe received, but returns after the first packet has been received or after the timeout has been reached. Prototype int USB_PRINTER_ReceiveTimed(void * pData, unsigned NumBytes, unsigned ms); Parameters Parameter Description pData Pointer to a buffer where the received data will be stored. NumBytes Number of bytes to read. ms Timeout in milliseconds. Return value >0 =0 <0 Number of bytes that have been read within the given timeout. Zero packet received (not every controller supports this!) or the target was disconnected during the function call. Returns a USB_STATUS_ERROR or USB_STATUS_TIMEOUT. Additional information If no error occurs, this function returns the number of bytes received. Calling USB_PRINTER_ReceiveTimed() will return as much data as is currently available up to the size of the buffer specified within the specified timeout. This function also returns when target is disconnected from host or when a USB reset occurred, it will then return the number of bytes read. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 356 CHAPTER 11 11.3.2.9 Target API USB_PRINTER_Write() Description Writes data to the host. Prototype int USB_PRINTER_Write(const void * pData, unsigned NumBytes); Parameters Parameter Description pData Pointer to a buffer that contains the data to be sent. NumBytes Number of bytes to write. Return value 0 <0 Number of bytes that have been written. Error. Additional information This function is blocking. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 357 CHAPTER 11 11.3.2.10 Target API USB_PRINTER_WriteTimed() Description Writes data to the host within a given timeout. Prototype int USB_PRINTER_WriteTimed(const void * pData, unsigned NumBytes, int ms); Parameters Parameter Description pData Pointer to a buffer that contains the data to be sent. NumBytes Number of bytes to write. ms Timeout in milliseconds. A zero value results in an infinite timeout. If ms is < 0, the function does not block and may return USB_STATUS_EP_BUSY. Return value >0 =0 <0 Number of bytes that have been written before timeout. Timeout occurred. Error. Additional information If ms 0, this function blocks the task until all data has been written or a timeout occurred. In case of a reset or a disconnect USB_STATUS_ERROR is returned. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 358 CHAPTER 11 11.3.2.11 Target API USB_PRINTER_API Description Initialization structure that is needed when adding a printer interface to emUSB-Device. It holds pointer to callback functions the interface invokes when it processes request from USB host. Type definition typedef struct { USB_PRINTER_GET_DEVICE_ID_STRING USB_PRINTER_ON_DATA_RECEIVED USB_PRINTER_GET_HAS_NO_ERROR USB_PRINTER_GET_IS_SELECTED USB_PRINTER_GET_IS_PAPER_EMPTY USB_PRINTER_ON_RESET } USB_PRINTER_API; * * * * * * pfGetDeviceIdString; pfOnDataReceived; pfGetHasNoError; pfGetIsSelected; pfGetIsPaperEmpty; pfOnReset; Structure members Member Description pfGetDeviceIdString The library calls this function when the USB host requests the printer's identification string. pfOnDataReceived This function is called when data arrives from USB host. pfGetHasNoError This function should return a non-zero value if the printer has no error. pfGetIsSelected This function should return a non-zero value if the printer is selected pfGetIsPaperEmpty This function should return a non-zero value if the printer is out of paper. pfOnReset The library calls this function if the USB host sends a soft reset command. Additional information Detailed information can be found in USB_PRINTER_API in detail on page 360. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 359 CHAPTER 11 11.4 Printer API Printer API This section describes the emUSB-Device Printer API in detail. 11.4.1 General information The interface includes multiple callback functions which have to be set by the user application. These functions are called by the emUSB-Device stack when the host makes the corresponding enquiries. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 360 CHAPTER 11 Printer API 11.4.2 USB_PRINTER_API in detail 11.4.2.1 USB_PRINTER_GET_DEVICE_ID_STRING Description The library calls this function when the USB host requests the printer's identification string. This string shall confirm to the IEEE 1284 Device ID Syntax. Type definition typedef const char * USB_PRINTER_GET_DEVICE_ID_STRING(void); Return value Pointer to the ID string. Additional information The return string shall confirm to the IEEE 1284 Device ID. Example "CLASS:PRINTER; MODEL:HP LaserJet 6MP; MANUFACTURER:Hewlett-Packard; DESCRIPTION:Hewlett-Packard LaserJet 6MP Printer; COMMAND SET:PJL,MLC,PCLXL,PCL,POSTSCRIPT;" emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 361 CHAPTER 11 11.4.2.2 Printer API USB_PRINTER_ON_DATA_RECEIVED Description This function is called when data arrives from USB host. Type definition typedef int USB_PRINTER_ON_DATA_RECEIVED(const U8 * pData, unsigned NumBytes); Parameters Parameter Description pData Pointer to the data. NumBytes Data length. Return value =0 0 More data can be accepted No more data can be accepted, in this case a stall will be sent back to the host. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 362 CHAPTER 11 11.4.2.3 Printer API USB_PRINTER_GET_HAS_NO_ERROR Description This function should return a non-zero value if the printer has no error. Type definition typedef U8 USB_PRINTER_GET_HAS_NO_ERROR(void); Return value =0 0 No error. Error condition present. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 363 CHAPTER 11 11.4.2.4 Printer API USB_PRINTER_GET_IS_SELECTED Description This function should return a non-zero value if the printer is selected. Type definition typedef U8 USB_PRINTER_GET_IS_SELECTED(void); Return value =0 0 Not selected. Selected. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 364 CHAPTER 11 11.4.2.5 Printer API USB_PRINTER_GET_IS_PAPER_EMPTY Description This function should return a non-zero value if the printer is out of paper. Type definition typedef U8 USB_PRINTER_GET_IS_PAPER_EMPTY(void); Return value =0 0 Out of paper. Has paper. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 365 CHAPTER 11 11.4.2.6 Printer API USB_PRINTER_ON_RESET Description The library calls this function if the USB host sends a soft reset command. Type definition typedef void USB_PRINTER_ON_RESET(void); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 12 IP-over-USB (IP) This chapter gives a general overview of the IP component and describes how to get the IP component running on the target. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 367 CHAPTER 12 12.1 Overview Overview The IP component is a very convenient package when you need to use IP-based protocols over USB with different host operating systems. It consist of two different components RNDIS and CDC-ECM Combined with the smart capabilities of emUSB-Device-IP to form a cross-platform USB to Ethernet device that works on every common Host OS that can handle USB devices. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 368 CHAPTER 12 12.2 Using only RNDIS or CDC-ECM Using only RNDIS or CDC-ECM Main problem between different Host OSes is that either one IP-over-USB class is supported which is then not supported on the other Host OS. Host OS/Protocol RNDIS CDC-ECM Windows x - Linux x x macOS - x Free/Net/OpenBSD x x Linux and all BSD distribution work with any IP-over-USB interface and therefore can be used with either RNDIS or CDC-ECM. macOS does not support RNDIS, third party tools may work but are not fully compatible and using a new version of macOS the driver or package may no longer work properly. Windows cannot handle CDC-ECM out-of-the-box. There are third-party drivers which can handle this but the driver package has to be licensed. Furthermore a new inf-file needs to be written for your device and as a consequence of that the driver package itself needs to be certified which involves further costs. Adding new CDC-ECM devices to the inf-file forces to resign that package once again. SEGGER's IP-over-USB solution eliminates these limitations. 12.2.1 Working with emUSB-Device-IP A IP-over-USB device connected to a PC running the Windows operating system is listed as a separate network interface in the "Network Connections" window as shown in this screenshot: The ping command line utility can be used to test the connection to target as shown below. If the connection is correctly established the number of the lost packets should be 0. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 369 CHAPTER 12 Using only RNDIS or CDC-ECM On macOS IP-over-USB is similarly available: And on Ubuntu: emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 370 CHAPTER 12 12.3 12.3.1 Configuration Configuration Initial Configuration To get emUSB-Device-IP up and running as well as doing an initial test, the configuration as delivered should not be modified. 12.3.2 Final configuration The configuration must only be modified when emUSB-Device-IP is used in your final product. Refer to section emUSB-Device Configuration on page 41 to get detailed information about the general emUSB-Device configuration functions which have to be adapted. 12.3.3 Class specific configuration emUSB-Device-IP specific device information must be provided by the application via the function USBD_IP_Add(). A sample how to use this function can be found in the IP_Config_IP_over_USB.c. The file is located in the Sample\IP directory of the emUSB-Device shipment. The IP_Config_IP_over_USB.c provides a ready to use layer and configuration file to be used with embOS and embOS/IP. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 371 CHAPTER 12 12.4 Running the sample application Running the sample application The sample application can be found in the Sample\IP\IP_Config_IP_over_USB.c file of the emUSB-Device shipment. In order to use the sample application the SEGGER embOS/IP middleware component is required. To test the emUSB-Device-IP component any of the embOS/IP sample applications can be used in combination with IP_Config_IP_over_USB.c . After the sample application is started the USB cable should be connected to the PC and the chosen embOS/IP sample can be tested by using the URL "usb.local". 12.4.1 IP_Config_IP_over_USB.c in detail The main part of the sample application is implemented in the function MainTask() which runs as an independent task. // IP_X_Config() - excerpt from IP_Config_IP_over_USB.c void IP_X_Config(void) { <...> IP_SetIFaceConnectHook(IFaceId, _Connect); IP_AddStateChangeHook(&_Hook, _OnHWChange) <...> } // _Connect() - excerpt from IP_Config_IP_over_USB.c static int _Connect(unsigned IFaceId) { // // Initialize the DHCP Server for this interface. // IP_DHCPS_Init(IFaceId); // // Initialize the USB stack // and prepare to use the IP-over-USB connection // USBD_Init(); USBD_SetDeviceInfo(&USB_DeviceInfo); // // Enable IAD makes sure that the device is properly enumerated on Windows 7 on USB 3 Controller // USBD_EnableIAD(); _AddIP(); USBD_Start(); return 0; // Successfully connected. } // _AddIP() - excerpt from IP_Config_IP_over_USB.c static void _AddIP(void) { USB_IP_INIT_DATA InitData; InitData.EPOut = USBD_AddEP(USB_DIR_OUT, USB_TRANSFER_TYPE_BULK, 0, _abReceiveBuffer, sizeof(_abReceiveBuffer)); InitData.EPIn = USBD_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_BULK, 0, NULL, 0); InitData.EPInt = USBD_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_INT, 5, NULL, 0); InitData.pDriverAPI = &USB_Driver_IP_NI; InitData.DriverData.pDriverData = (void *)_IFaceId; InitData.pRndisDevInfo = &_DeviceInfo; USBD_IP_Add(&InitData); } // _OnHWChange() - excerpt from IP_Config_IP_over_USB.c static void _OnHWChange(unsigned IFaceId, U8 AdminState, U8 HWState) { unsigned IsReady; IP_USE_PARA(AdminState); IsReady = HWState ? 1 : 0; emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 372 CHAPTER 12 Running the sample application _UpdateIPServiceOperation(IFaceId, IsReady); } // _UpdateIPServiceOperation() - excerpt from IP_Config_IP_over_USB.c static void _UpdateIPServiceOperation(unsigned IFaceId, unsigned LinkStatus) { U32 ServerIpAddr; U32 SubnetMask; U32 DNSServer; U8 USBAddr; if (IFaceId == _IFaceId) { if (LinkStatus) { // // As soon as we are enumerated, we know that the USB host has // assigned a USB address to us. // We will use this USB address in order to assign // the embOS/IP interface a IP address. // The IP address is selected from a so-called // IP pool for CGN (carrier grade NAT) - RFC6598 // The IP pool for this is 100.64.0.0/10. // We will use 100.127.<USBAddr>.0/29 -> gives us // 8 IP addresses, whereas 6 are assignable. // This is enough for a client/host configuration. // Therefore we will have the following scenario // embOS/IP interface: IP: 100.127.<USBAddr>.1 // Host interface: 100.127.<USBAddr>.2 - assigned // by our DHCP server. SubnetMask = 255.255.255.248 // USBAddr = USBD_GetUSBAddr(); ServerIpAddr = IP_BYTES2ADDR(100, 127, USBAddr, 1); SubnetMask = IP_BYTES2ADDR(0xff,0xff,0xff,0xf8); // // Configure the delayed exec parameters // // // IP_SetAddrMaskEx parameters // _SetAddrMaskExPara.Para0 = SEGGER_PTR2ADDR(IFaceId); _SetAddrMaskExPara.Para1 = SEGGER_PTR2ADDR(ServerIpAddr); _SetAddrMaskExPara.Para2 = SEGGER_PTR2ADDR(SubnetMask); // // IP_DHCPS_ConfigPool parameters // _DNSServer = ServerIpAddr; _DHCPS_ConfigPoolPara.Para0 = SEGGER_PTR2ADDR(IFaceId); _DHCPS_ConfigPoolPara.Para1 = SEGGER_PTR2ADDR(ServerIpAddr + 1); _DHCPS_ConfigPoolPara.Para2 = SEGGER_PTR2ADDR(SubnetMask); _DHCPS_ConfigPoolPara.Para3 = SEGGER_PTR2ADDR(4); // // IP_DHCPS_ConfigDNS parameters // _DHCPS_ConfigDNSAddPara.Para0 = SEGGER_PTR2ADDR(IFaceId); _DHCPS_ConfigDNSAddPara.Para1 = SEGGER_PTR2ADDR(&_DNSServer); _DHCPS_ConfigDNSAddPara.Para2 = SEGGER_PTR2ADDR(1); // // IP_DHCPS_Start(m)DNS parameters // IP_MEMSET(&_DNSConfig, 0, sizeof(_DNSConfig)); _DNSConfig.sHostname = SERVER_NAME; _DNSConfig.TTL = 60; _DNSConfig.apSDConfig = _aSDConfig; _DNSConfig.NumConfig = SEGGER_COUNTOF(_aSDConfig); // // Queue now the the delayed exec commands // // Assign a local address 100.127.<USBAddr>.1/8 IP_ExecDelayed(&_aIPExecDelayed[IP_SET_ADDRESS_MASK_OPERATION], IP_SetAddrMaskEx_Delayed, emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 373 CHAPTER 12 Running the sample application &_SetAddrMaskExPara, "SetAddrMaskEx", _OnDone); IP_ExecDelayed(&_aIPExecDelayed[IP_DHCPS_CONFIGPOOL_OPERATION], IP_DHCPS_ConfigPool_Delayed, &_DHCPS_ConfigPoolPara, "IP_DHCPS_ConfigPool", _OnDone); IP_ExecDelayed(&_aIPExecDelayed[IP_DHCPS_CONFIGDNSADDR_OPERATION], IP_DHCPS_ConfigDNSAddr_Delayed, &_DHCPS_ConfigDNSAddPara, "IP_DHCPS_ConfigDNSAddr", _OnDone); IP_ExecDelayed(&_aIPExecDelayed[IP_DHCPS_START_OPERATION], IP_DHCPS_Start_Delayed, SEGGER_PTR2ADDR(_IFaceId), "IP_DHCPS_Start", _OnDone); IP_ExecDelayed(&_aIPExecDelayed[IP_MDNS_SERVER_START_OPERATION], IP_MDNS_SERVER_Start_Delayed, &_DNSConfig, "IP_MDNS_SERVER_Start", _OnDone); IP_ExecDelayed(&_aIPExecDelayed[IP_DNS_SERVER_START_OPERATION], IP_DNS_SERVER_Start_Delayed, &_DNSConfig, "IP_DNS_SERVER_Start", _OnDone); } if (LinkStatus == 0) { IP_ExecDelayed(&_aIPExecDelayed[IP_DHCPS_HALT_OPERATION], IP_DHCPS_Halt_Delayed, SEGGER_PTR2ADDR(_IFaceId), "IP_DHCPS_Halt", _OnDone); IP_ExecDelayed(&_aIPExecDelayed[IP_MDNS_SERVER_STOP_OPERATION], IP_MDNS_SERVER_Stop_Delayed, NULL, "IP_MDNS_SERVER_Stop", _OnDone); IP_ExecDelayed(&_aIPExecDelayed[IP_DNS_SERVER_STOP_OPERATION], IP_DNS_SERVER_Stop_Delayed, NULL, "IP_DNS_SERVER_Stop", _OnDone); } } } The first step is to initialize the DHCP server component which assigns the IP address for the PC side. The target is configured with the IP address 100.127.<USBAddr>.1. The USB address is assigned by the host PC and is unique in the host system. This makes sure that when multiple devices using emUSB-Device-IP are connected they receive a different subnet The DHCP server is configured to distribute IP addresses starting from 100.127.<USBAddr>.2, therefore the PC will receive the IP address 100.127.<USBAddr>.2. DNS and mDNS is enabled to allow name resolution. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 374 CHAPTER 12 emUSB-Device-IP + embOS/IP as a "USB Webserver" 12.5 emUSB-Device-IP + embOS/IP as a "USB Webserver" This method of using emUSB-Device-IP provides a unique customer experience where a USB device can provide a custom web page or any other service through which a customer can interact with the device. Initially the PC recognizes an RNDIS device. In case of Windows XP and Vista a driver will be necessary (the corresponding inf-file can be found in the Windows\USB\RNDIS\WinXP_Vista folder), Windows 7 and above as well as Linux recognize RNDIS automatically. RNDIS from the viewpoint of the PC is a normal Network Interface Controller (NIC) and the PC handles it as such. The default behaviour is to request an IP address from a DHCP server. The PC retrieves an IP address from the DHCP-Server in the device. In our standard sample code the device has the local IP 100.127.<USBAddr>.1 and the PC will get 100.127.<USBAddr>.2 from the DHCP server. With this the configuration is complete and the user can access the web-interface located on the USB device via the DNS entry - "usb.local". emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 375 CHAPTER 12 12.6 Target API Target API Function Description API functions USBD_IP_Add() Adds support for the IP component to USB stack. USBD_IP_Task() Obsolete. Data structures USB_IP_INIT_DATA emUSB-Device User Guide & Reference Manual Structure which stores the parameters of the IP component. (c) 2010-2018 SEGGER Microcontroller GmbH 376 CHAPTER 12 12.6.1 API functions 12.6.1.1 USBD_IP_Add() Target API Description Adds support for the IP component to USB stack. Internally CDC-ECM and RNDIS is initialized. The IP component switches automatically between the two. Prototype void USBD_IP_Add(const USB_IP_INIT_DATA * pInitData); Parameters Parameter pInitData Description Pointer to a filled USB_IP_INIT_DATA structure data. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 377 CHAPTER 12 12.6.1.2 Target API USBD_IP_Task() Description Obsolete. Returns when USB is disconnected. Prototype void USBD_IP_Task(void); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 378 CHAPTER 12 12.6.2 Data structures 12.6.2.1 USB_IP_INIT_DATA Target API Description Structure which stores the parameters of the IP component. Type definition typedef struct { U8 EPIn; U8 EPOut; U8 EPInt; const USB_IP_NI_DRIVER_API * pDriverAPI; USB_IP_NI_DRIVER_DATA DriverData; const USB_RNDIS_DEVICE_INFO * pRndisDevInfo; } USB_IP_INIT_DATA; Structure members Member Description EPIn Endpoint to send data packets to USB host. EPOut Endpoint to receive data packets from USB host. EPInt Endpoint to send notifications to USB host. pDriverAPI Network interface driver API. DriverData Data passed at initialization to low-level driver. pRndisDevInfo Pointer to a filled USB_RNDIS_DEVICE_INFO structure. Additional information This structure holds the endpoints that should be used with the IP component. Refer to USBD_AddEP() for more information about how to add an endpoint. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 13 Remote NDIS (RNDIS) This chapter gives a general overview of the Remote Network Driver Interface Specification class and describes how to get the RNDIS component running on the target. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 380 CHAPTER 13 13.1 Overview Overview The Remote Network Driver Interface Specification (RNDIS) is a Microsoft proprietary USB class protocol which can be used to create a virtual Ethernet connection between a USB device and a host PC. A TCP/IP stack like embOS/IP is required on the USB device side to handle the actual IP communication. Any available IP protocol (UDP, TPC, FTP, HTTP, etc.) can be used to exchange data. On a typical Cortex-M CPU running at 120 MHz, a transfer speed of about 5 MB/s can be achieved when using a high-speed USB connection. USB RNDIS is supported by all Windows operating systems starting with Windows XP, as well as by Linux with kernel versions newer than 2.6.34. An .inf file is required for the installation on Microsoft Windows systems older than Windows 7. The emUSB-Device-RNDIS package includes .inf files for Windows versions older than Windows 7. OS X will require a third-party driver to work with RNDIS, which can be downloaded from here: http://joshuawise.com/horndis emUSB-Device-RNDIS contains the following components: * * * * 13.1.1 Generic USB handling RNDIS device class implementation Network interface driver which uses embOS/IP as TCP/IP stack. A sample application demonstrating how to work with RNDIS. Working with RNDIS Any USB RNDIS device connected to a PC running the Windows operating system is listed as a separate network interface in the "Network Connections" window as shown in this screenshot: The ping command line utility can be used to test the connection to target as shown below. If the connection is correctly established the number of the lost packets should be 0. 13.1.2 Additional information More technical details about RNDIS can be found here: http://msdn.microsoft.com/en-us/ library/windows/hardware/ff570660%28v=vs.85%29.aspx emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 381 CHAPTER 13 13.2 13.2.1 Configuration Configuration Initial Configuration To get emUSB-Device-RNDIS up and running as well as doing an initial test, the configuration as delivered should not be modified. 13.2.2 Final configuration The configuration must only be modified when emUSB-Device is used in your final product. Refer to section emUSB-Device Configuration on page 41 to get detailed information about the general emUSB-Device configuration functions which have to be adapted. 13.2.3 Class specific configuration RNDIS specific device information must be provided by the application via the function USBD_RNDIS_SetDeviceInfo() before the USB stack is started using USBD_Start(). A sample how to use this function can be found in the IP_Config_RNDIS.c. The file is located in the Sample\RNDIS directory of the emUSB-Device shipment. The IP_Config_RNDIS.c provides a ready to use layer and configuration file to be used with embOS and embOS/IP. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 382 CHAPTER 13 13.3 Running the sample application Running the sample application The sample application can be found in the Sample\RNDIS\IP_Config_RNDIS.c file of the emUSB-Device shipment. In order to use the sample application the SEGGER embOS/IP middleware component is required. To test the emUSB-Device-RNDIS component any of the embOS/IP sample applications can be used in combination with IP_Config_RNDIS.c . After the sample application is started the USB cable should be connected to the PC and the chosen embOS/IP sample can be tested using the appropriate methods. 13.3.1 IP_Config_RNDIS.c in detail The main part of the sample application is implemented in the function MainTask() which runs as an independent task. // _Connect() - excerpt from IP_Config_RNDIS.c static int _Connect(unsigned IFaceId) { U32 Server = IP_BYTES2ADDR(10, 0, 0, 10); IP_DHCPS_ConfigPool(IFaceId, IP_BYTES2ADDR(10, 0, 0, 11), 0xFF000000, 20); IP_DHCPS_ConfigDNSAddr(IFaceId, &Server, 1); IP_DHCPS_Init(IFaceId); IP_DHCPS_Start(IFaceId); USBD_Init(); USBD_SetDeviceInfo(&USB_DeviceInfo); USBD_RNDIS_SetDeviceInfo(&USB_RNDIS_DeviceInfo); _AddRNDIS(); USBD_Start(); return 0; // Successfully connected. } The first step is to initialize the DHCP server component which assigns the IP address for the PC side. The target is configured with the IP address 10.0.0.10. The DHCP server is configured to distribute IP addresses starting from 10.0.0.11, therefore the PC will receive the IP address 10.0.0.11. Then the USB stack is initialized and the RNDIS interface is added to it. The function _AddRNDIS() configures all required endpoints. // _AddRNDIS() - excerpt from IP_Config_RNDIS.c static U8 _abReceiveBuffer[USB_HS_BULK_MAX_PACKET_SIZE]; static void _AddRNDIS(void) { USB_RNDIS_INIT_DATA InitData; InitData.EPOut = USBD_AddEP(USB_DIR_OUT, USB_TRANSFER_TYPE_BULK, 0, _abReceiveBuffer, sizeof(_abReceiveBuffer)); InitData.EPIn = USBD_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_BULK, 0, NULL, 0); InitData.EPInt = USBD_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_INT, 5, NULL, 0); InitData.pDriverAPI = &USB_Driver_IP_NI; InitData.DriverData.pDriverData = (void *)_IFaceId; USBD_RNDIS_Add(&InitData); } The size of _acReceiveBuffer buffer must be a multiple of USB max packet size. USB_Driver_IP_NI is the network interface driver which implements the connection to the IP stack. Optionally a HW address may be configured here, which is assigned to the PC network interface. If not set (pHWAddr = NULL), the HW address is generated automatically later while setting the interface up. The IP stack is configured to use the network interface driver of emUSB-Device-RNDIS. For more information about the configuration of the IP stack refer to embOS/IP manual. // IP_X_Config() - excerpt from IP_Config.c #include "USB_Driver_IP_NI.h" void IP_X_Config(void) { emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 383 CHAPTER 13 Running the sample application <...> // // Add and configure the RNDIS driver. // The local IP address is 10.0.0.10/8. // IFaceId = IP_AddEtherInterface(&USB_IP_Driver); IP_SetIFaceConnectHook(IFaceId, _Connect); IP_SetIFaceDisconnectHook(IFaceId, _Disconnect); _IFaceId = IFaceId; <...> } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 384 CHAPTER 13 13.4 RNDIS + embOS/IP as a "USB Webserver" RNDIS + embOS/IP as a "USB Webserver" This method of using RNDIS provides a unique customer experience where a USB device can provide a custom web page or any other service through which a customer can interact with the device. Initially the PC recognizes an RNDIS device. In case of Windows XP and Vista a driver will be necessary, Windows 7 and above as well as Linux recognize RNDIS automatically. RNDIS from the viewpoint of the PC is a normal Network Interface Controller (NIC) and the PC handles it as such. The default behaviour is to request an IP address from a DHCP server. The PC retrieves an IP address from the DHCP-Server in the device. In our standard sample code the device has the local IP 10.0.0.10 and the PC will get 10.0.0.11 from the DHCP server. With this the configuration is complete and the user can access the web-interface located on the USB device via 10.0.0.10. To improve the ease-of-use NetBIOS can be used to give the device an easily readable name. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 385 CHAPTER 13 13.5 Target API Target API Function Description API functions USBD_RNDIS_Add() Adds an RNDIS-class interface to the USB stack. USBD_RNDIS_Task() Obsolete. USBD_RNDIS_SetDeviceInfo() Provides device information used during USB enumeration to the stack. Data structures USB_RNDIS_INIT_DATA Structure which stores the parameters of the RNDIS interface. USB_RNDIS_DEVICE_INFO Device information that must be provided by the application via the function USBD_RNDIS_SetDeviceInfo() before the USB stack is started using USBD_Start(). USB_IP_NI_DRIVER_API This structure contains the callback functions for the network interface driver. USB_IP_NI_DRIVER_DATA Configuration data passed to network interface driver at initialization. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 386 CHAPTER 13 13.5.1 API functions 13.5.1.1 USBD_RNDIS_Add() Target API Description Adds an RNDIS-class interface to the USB stack. Prototype void USBD_RNDIS_Add(const USB_RNDIS_INIT_DATA * pInitData); Parameters Parameter pInitData Description Pointer to initialization data. Additional information This function should be called after the initialization of the USB core to add an RNDIS interface to emUSB-Device. The initialization data is passed to the function in the structure pointed to by pInitData. Refer to USB_RNDIS_INIT_DATA for more information. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 387 CHAPTER 13 13.5.1.2 Target API USBD_RNDIS_Task() Description Obsolete. Returns when USB is disconnected. Prototype void USBD_RNDIS_Task(void); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 388 CHAPTER 13 13.5.1.3 Target API USBD_RNDIS_SetDeviceInfo() Description Provides device information used during USB enumeration to the stack. Prototype void USBD_RNDIS_SetDeviceInfo(const USB_RNDIS_DEVICE_INFO * pDeviceInfo); Parameters Parameter pDeviceInfo Description Pointer to a USB_RNDIS_DEVICE_INFO structure containing the device information. Must point to static data that is not changed while the stack is running. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 389 CHAPTER 13 13.5.2 Data structures 13.5.2.1 USB_RNDIS_INIT_DATA Target API Description Structure which stores the parameters of the RNDIS interface. Type definition typedef struct { U8 EPIn; U8 EPOut; U8 EPInt; const USB_IP_NI_DRIVER_API * pDriverAPI; USB_IP_NI_DRIVER_DATA DriverData; unsigned DataInterfaceNum; } USB_RNDIS_INIT_DATA; Structure members Member Description EPIn Endpoint for sending data to the host. EPOut Endpoint for receiving data from the host. EPInt Endpoint for sending status information. pDriverAPI Pointer to the Network interface driver API. DriverData Configuration data for the network interface driver. DataInterfaceNum Internal use Additional information This structure holds the endpoints that should be used by the RNDIS interface (EPin, EPOut and EPInt). Refer to USBD_AddEP() for more information about how to add an endpoint. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 390 CHAPTER 13 13.5.2.2 Target API USB_RNDIS_DEVICE_INFO Description Device information that must be provided by the application via the function USBD_RNDIS_SetDeviceInfo() before the USB stack is started using USBD_Start(). Type definition typedef struct { U32 VendorId; char * sDescription; U16 DriverVersion; } USB_RNDIS_DEVICE_INFO; Structure members Member Description VendorId A 24-bit Organizationally Unique Identifier (OUI) of the vendor. This is the same value as the one stored in the first 3 bytes of a HW (MAC) address. Only the least significant 24 bits of the retuned value are used. sDescription 0-terminated ASCII string describing the device. The string is then sent to the host system. DriverVersion 16-bit value representing the firmware version. The high-order byte specifies the major version and the low-order byte the minor version. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 391 CHAPTER 13 13.5.3 Driver interface 13.5.3.1 USB_IP_NI_DRIVER_API Target API Description This structure contains the callback functions for the network interface driver. Type definition typedef struct { USB_IP_NI_INIT USB_IP_NI_GET_PACKET_BUFFER USB_IP_NI_WRITE_PACKET USB_IP_NI_SET_PACKET_FILTER USB_IP_NI_GET_LINK_STATUS USB_IP_NI_GET_LINK_SPEED USB_IP_NI_GET_HWADDR USB_IP_NI_GET_STATS USB_IP_NI_GET_MTU USB_IP_NI_RESET USB_IP_NI_SET_WRITE_PACKET_FUNC } USB_IP_NI_DRIVER_API; * * * * * * * * * * * pfInit; pfGetPacketBuffer; pfWritePacket; pfSetPacketFilter; pfGetLinkStatus; pfGetLinkSpeed; pfGetHWAddr; pfGetStats; pfGetMTU; pfReset; pfSetWritePacketFunc; Structure members Member Description pfInit Initializes the driver. pfGetPacketBuffer Returns a buffer for a data packet. pfWritePacket Delivers a data packet to target IP stack. pfSetPacketFilter Configures the type of accepted data packets. pfGetLinkStatus Returns the status of the connection to target IP stack. pfGetLinkSpeed Returns the connection speed. pfGetHWAddr Returns the HW address of the PC. pfGetStats Returns statistical counters. pfGetMTU Returns the size of the largest data packet which can be transferred. pfReset Resets the driver. pfSetWritePacketFunc Allows to change the WritePacket callback which was set by pfInit. Additional information The emUSB-Device-RNDIS/emUSB-Device-CDC-ECM component calls the functions of this API to exchange data and status information with the IP stack running on the target. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 392 CHAPTER 13 13.5.3.2 Target API USB_IP_NI_DRIVER_DATA Description Configuration data passed to network interface driver at initialization. Type definition typedef struct { const U8 * pHWAddr; unsigned NumBytesHWAddr; void * pDriverData; } USB_IP_NI_DRIVER_DATA; Structure members Member Description pHWAddr Optional pointer to a HW address (or MAC address) of the host network interface. NumBytesHWAddr Number of bytes in the HW address. Typically 6 bytes. pDriverData Pointer to a user context. Additional information When pHWAddr is NULL the MAC is automatically generated. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 393 CHAPTER 13 13.6 RNDIS IP Driver RNDIS IP Driver This section describes the emUSB-Device RNDIS IP stack interface in detail. 13.6.1 General information This release comes with IP NI driver which uses embOS/IP as the IP stack. If you are using embOS/IP this chapter can be ignored. This chapter is for those who wish to write their own IP stack interface for a third-party IP stack. The IP interface is handled through an API-table, which contains all relevant functions necessary for read/write operations and initialization. 13.6.2 Interface function list As described above, access to network functions is realized through an API-function table of type USB_IP_NI_DRIVER_API. The structure is declared in USB_Driver_IP_NI.h and it is described in section Data structures on page 389 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 394 CHAPTER 13 RNDIS IP Driver 13.6.3 USB_IP_NI_DRIVER_API in detail 13.6.3.1 USB_IP_NI_INIT Description Initializes the driver. Type definition typedef unsigned (USB_IP_NI_INIT)(const USB_IP_NI_DRIVER_DATA * pDriverData, USB_IP_WRITE_PACKET * pfWritePacket); Parameters Parameter pDriverData pfWritePacket Description in Pointer to driver configuration data. Call back function called by the IP stack to transmit a packet that should be send to the USB host. Return value IP NI driver instance ID. Additional information This function is called when the RNDIS/ECM interface is added to the USB stack. Typically the function makes a local copy of the HW address passed in the pDriverData structure. For more information this structure refer to USB_IP_NI_DRIVER_DATA. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 395 CHAPTER 13 13.6.3.2 RNDIS IP Driver USB_IP_NI_GET_PACKET_BUFFER Description Returns a buffer for a data packet. Type definition typedef void * (USB_IP_NI_GET_PACKET_BUFFER)(unsigned Id, unsigned NumBytes); Parameters Parameter Description Id Instance ID returned from USB_IP_NI_INIT. NumBytes Size of the requested buffer in bytes. Return value NULL = NULL Pointer to allocated buffer No buffer available Additional information The function should allocate a buffer of the requested size. If the buffer can not be allocated a NULL pointer should be returned. The function is called when a data packet is received from PC. The packet data is stored in the returned buffer. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 396 CHAPTER 13 13.6.3.3 RNDIS IP Driver USB_IP_NI_WRITE_PACKET Description Delivers a data packet to target IP stack. Type definition typedef void (USB_IP_NI_WRITE_PACKET)( unsigned Id, const void * pData, unsigned NumBytes); Parameters Parameter Id pData NumBytes Description Instance ID returned from USB_IP_NI_INIT. in Data of the received packet. Number of bytes stored in the buffer. Additional information The function is called after a data packet has been received from USB. pData points to the buffer returned by the USB_IP_NI_GET_PACKET_BUFFER function. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 397 CHAPTER 13 13.6.3.4 RNDIS IP Driver USB_IP_NI_SET_PACKET_FILTER Description Configures the type of accepted data packets. Type definition typedef void (USB_IP_NI_SET_PACKET_FILTER)(unsigned Id, U32 Mask); Parameters Parameter Description Id Instance ID returned from USB_IP_NI_INIT. Mask Type of accepted data packets. Additional information The Mask parameter should be interpreted as a boolean value. A value different than 0 indicates that the connection to target IP stack should be established. When the function is called with the Mask parameter set to 0 the connection to target IP stack should be interrupted. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 398 CHAPTER 13 13.6.3.5 RNDIS IP Driver USB_IP_NI_GET_LINK_STATUS Description Returns the status of the connection to target IP stack. Type definition typedef int (USB_IP_NI_GET_LINK_STATUS)(unsigned Id); Parameters Parameter Id Description Instance ID returned from USB_IP_NI_INIT. Return value USB_IP_NI_LINK_STATUS_DISCONNECTED USB_IP_NI_LINK_STATUS_CONNECTED emUSB-Device User Guide & Reference Manual Connected to target IP stack. Not connected to target IP stack. (c) 2010-2018 SEGGER Microcontroller GmbH 399 CHAPTER 13 13.6.3.6 RNDIS IP Driver USB_IP_NI_GET_LINK_SPEED Description Returns the connection speed. Type definition typedef U32 (USB_IP_NI_GET_LINK_SPEED)(unsigned Id); Parameters Parameter Description Instance ID returned from USB_IP_NI_INIT. Id Return value 0 =0 The connection speed in units of 100 bits/sec. Not connected. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 400 CHAPTER 13 13.6.3.7 RNDIS IP Driver USB_IP_NI_GET_HWADDR Description Returns the HW address of the host network interface (PC). Type definition typedef void (USB_IP_NI_GET_HWADDR)(unsigned Id, U8 * pAddr, unsigned NumBytes); Parameters Parameter Id pAddr NumBytes Description Instance ID returned from USB_IP_NI_INIT. out The HW address. Maximum number of bytes to store into pAddr. Additional information The returned HW address is the one passed to the driver in the call to USB_IP_NI_INIT. Typically the HW address is 6 bytes long. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 401 CHAPTER 13 13.6.3.8 RNDIS IP Driver USB_IP_NI_GET_STATS Description Returns statistical counters. Type definition typedef U32 (USB_IP_NI_GET_STATS)(unsigned Id, int Type); Parameters Parameter Description Id Instance ID returned from USB_IP_NI_INIT. Type The type of information requested. See table below. Return value Value of the requested statistical counter. Additional information The counters should be set to 0 when the USB_IP_NI_RESET function is called. Permitted values for parameter Type USB_IP_NI_STATS_WRITE_PACKET_OK Number of packets sent without errors to target IP stack. USB_IP_NI_STATS_WRITE_PACKET_ERROR Number of packets sent with errors to target IP stack. USB_IP_NI_STATS_READ_PACKET_OK Number of packets received without errors from target IP stack. USB_IP_NI_STATS_READ_PACKET_ERROR Number of packets received with errors from target IP stack. USB_IP_NI_STATS_READ_NO_BUFFER Number of packets received from target IP stack but dropped. USB_IP_NI_STATS_READ_ALIGN_ERROR Number of packets received from target IP stack with alignment errors. USB_IP_NI_STATS_WRITE_ONE_COLLISION Number of packets which were not sent to target IP stack due to the occurrence of one collision. USB_IP_NI_STATS_WRITE_MORE_COLLISIONS Number of packets which were not sent to target IP stack due to the occurrence of one or more collisions. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 402 CHAPTER 13 13.6.3.9 RNDIS IP Driver USB_IP_NI_GET_MTU Description Returns the maximum transmission unit, the size of the largest data packet which can be transferred. Type definition typedef U32 (USB_IP_NI_GET_MTU)(unsigned Id); Parameters Parameter Id Description Instance ID returned from USB_IP_NI_INIT. Return value The MTU size in bytes. Typically 1500 bytes. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 403 CHAPTER 13 13.6.3.10 RNDIS IP Driver USB_IP_NI_RESET Description Resets the driver. Type definition typedef void (USB_IP_NI_RESET)(unsigned Id); Parameters Parameter Id Description Instance ID returned from USB_IP_NI_INIT. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 404 CHAPTER 13 13.6.3.11 RNDIS IP Driver USB_IP_NI_SET_WRITE_PACKET_FUNC Description Changes the USB_IP_WRITE_PACKET callback which was added via USB_IP_NI_INIT to a different callback function. This function is only called by the stack when USB Ethernet is used. It is not called when RNDIS or ECM is used standalone. Type definition typedef void (USB_IP_NI_SET_WRITE_PACKET_FUNC) (unsigned Id, USB_IP_WRITE_PACKET * pfWritePacket); Parameters Parameter Description Id Instance ID returned from USB_IP_NI_INIT. pfWritePacket Call back function called by the IP stack to transmit a packet that should be send to the USB host. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 14 CDC-ECM This chapter gives a general overview of the Communications Device Class / Ethernet Control Model class and describes how to get the ECM component running on the target. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 406 CHAPTER 14 14.1 Overview Overview The Communications Device Class / Ethernet Control Model is a USB class protocol of the USB Implementers Forum which can be used to create a virtual Ethernet connection between a USB device and a host PC. A TCP/IP stack like embOS/IP is required on the USB device side to handle the actual IP communication. Any available IP protocol (UDP, TPC, FTP, HTTP, etc.) can be used to exchange data. USB ECM is supported by the Linux operating system. To use it on Windows, a third party driver (not contained in emUSB-Device-ECM) has to be installed on the Windows system. emUSB-Device-ECM contains the following components: * * * * 14.1.1 Generic USB handling ECM device class implementation Network interface driver which uses embOS/IP as TCP/IP stack. A sample application demonstrating how to work with ECM. Working with CDC-ECM Any USB ECM device connected to a PC running the Windows operating system is listed as a separate network interface in the "Network Connections" window as shown in this screenshot: The ping command line utility can be used to test the connection to target as shown below. If the connection is correctly established the number of the lost packets should be 0. The following screenshot shows a manual configuration and ping on Linux. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 407 CHAPTER 14 14.1.2 Overview Additional information More technical details about CDC-ECM can be found here: http://www.usb.org/developers/docs/devclass_docs/CDC1.2_WMC1.1_052013.zip emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 408 CHAPTER 14 14.2 14.2.1 Configuration Configuration Initial configuration To get emUSB-Device-ECM up and running as well as doing an initial test, the configuration as delivered should not be modified. When using on Windows with a third party driver, the vendor id and product id must match the ids configured in the .inf file of the driver. 14.2.2 Final configuration The configuration must only be modified when emUSB-Device is used in your final product. Refer to section emUSB-Device Configuration on page 41 to get detailed information about the general emUSB-Device configuration functions which have to be adapted. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 409 CHAPTER 14 14.3 Running the sample application Running the sample application The sample application can be found in the Sample\ECM\IP_Config_ECM.c file of the emUSB-Device shipment. In order to use the sample application the SEGGER embOS/IP middleware component is required. To test the emUSB-Device-ECM component any of the embOS/IP sample applications can be used in combination with IP_Config_ECM.c. After the sample application is started the USB cable should be connected to the PC and the chosen embOS/IP sample can be tested using the appropriate methods. 14.3.1 IP_Config_ECM.c in detail The main part of the sample application is implemented in the function MainTask() which runs as an independent task. // _Connect() - excerpt from IP_Config_ECM.c static int _Connect(unsigned IFaceId) { U32 Server = IP_BYTES2ADDR(10, 0, 0, 10); IP_DHCPS_ConfigPool(IFaceId, IP_BYTES2ADDR(10, 0, 0, 11), 0xFF000000, 20); IP_DHCPS_ConfigDNSAddr(IFaceId, &Server, 1); IP_DHCPS_Init(IFaceId); IP_DHCPS_Start(IFaceId); USBD_Init(); USBD_SetDeviceInfo(&USB_DeviceInfo); _AddECM(); USBD_Start(); return 0; // Successfully connected. } The first step is to initialize the DHCP server component which assigns the IP address for the PC side. The target is configured with the IP address 10.0.0.10. The DHCP server is configured to distribute IP addresses starting from 10.0.0.11, therefore the PC will receive the IP address 10.0.0.11. Then the USB stack is initialized and the ECM interface is added to it. The function _AddECM() configures all required endpoints and configures the HW address of the PC network interface. // _AddECM() - excerpt from IP_Config_ECM.c static U8 _abReceiveBuffer[USB_HS_BULK_MAX_PACKET_SIZE]; static void _AddECM(void) { USB_ECM_INIT_DATA InitData; InitData.EPOut = USBD_AddEP(USB_DIR_OUT, USB_TRANSFER_TYPE_BULK, 0, _abReceiveBuffer, sizeof(_abReceiveBuffer)); InitData.EPIn = USBD_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_BULK, 0, NULL, 0); InitData.EPInt = USBD_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_INT, 32, NULL, 0); InitData.pDriverAPI = &USB_Driver_IP_NI; InitData.DriverData.pDriverData = (void *)_IFaceId; #if 0 InitData.DriverData.pHWAddr = "\x00\x22\xC7\xFF\xFF\xF3"; InitData.DriverData.NumBytesHWAddr = 6; #endif USBD_ECM_Add(&InitData); } The size of _acReceiveBuffer buffer must be a multiple of USB max packet size. USB_Driver_IP_NI is the network interface driver which implements the connection to the IP stack. Optionally a HW address may be configured here, which is assigned to the PC network interface. If not set (pHWAddr = NULL), the HW address is generated automatically later while setting the interface up. The IP stack is configured to use the network interface driver of emUSB-Device-ECM. For more information about the configuration of the IP stack refer to embOS/IP manual. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 410 CHAPTER 14 Running the sample application // IP_X_Config() - excerpt from IP_Config.c #include "USB_Driver_IP_NI.h" void IP_X_Config(void) { <...> // // Add and configure the ECM driver. // The local IP address is 10.0.0.10/8. // IFaceId = IP_AddEtherInterface(&USB_IP_Driver); IP_SetAddrMask(0x0A00000A, 0xFF000000); IP_SetIFaceConnectHook(IFaceId, _Connect); IP_SetIFaceDisconnectHook(IFaceId, _Disconnect); _IFaceId = IFaceId; <...> } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 411 CHAPTER 14 14.4 Target API Target API Function Description API functions USBD_ECM_Add() Adds an ECM-class interface to the USB stack. USBD_ECM_Task() Obsolete. Data structures USB_ECM_INIT_DATA Initialization data for ECM interface. USB_IP_NI_DRIVER_API This structure contains the callback functions for the network interface driver. USB_IP_NI_DRIVER_DATA Configuration data passed to network interface driver at initialization. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 412 CHAPTER 14 14.4.1 API functions 14.4.1.1 USBD_ECM_Add() Target API Description Adds an ECM-class interface to the USB stack. Prototype void USBD_ECM_Add(const USB_ECM_INIT_DATA * pInitData); Parameters Parameter pInitData Description Pointer to a USB_ECM_INIT_DATA structure. Additional information This function should be called after the initialization of the USB core to add an ECM interface to emUSB-Device. The initialization data is passed to the function in the structure pointed to by pInitData. Refer to USB_ECM_INIT_DATA for more information. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 413 CHAPTER 14 14.4.1.2 Target API USBD_ECM_Task() Description Obsolete. Returns when USB is disconnected. Prototype void USBD_ECM_Task(void); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 414 CHAPTER 14 14.4.2 Data structures 14.4.2.1 USB_ECM_INIT_DATA Target API Description Initialization data for ECM interface. Type definition typedef struct { U8 EPIn; U8 EPOut; U8 EPInt; const USB_IP_NI_DRIVER_API * pDriverAPI; USB_IP_NI_DRIVER_DATA DriverData; unsigned DataInterfaceNum; } USB_ECM_INIT_DATA; Structure members Member Description EPIn Endpoint for sending data to the host. EPOut Endpoint for receiving data from the host. The buffer associated to this endpoint must be big enough to hold a complete IP packet. EPInt Endpoint for sending status information. pDriverAPI Pointer to the Network interface driver API. See USB_IP_NI_DRIVER_API. DriverData Configuration data for the network interface driver. DataInterfaceNum Internal use. Additional information This structure holds the endpoints that should be used by the ECM interface (EPin, EPOut and EPInt). Refer to USBD_AddEP() for more information about how to add an endpoint. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 415 CHAPTER 14 14.4.3 Driver interface 14.4.3.1 USB_IP_NI_DRIVER_API Target API Description This structure contains the callback functions for the network interface driver. Type definition typedef struct { USB_IP_NI_INIT USB_IP_NI_GET_PACKET_BUFFER USB_IP_NI_WRITE_PACKET USB_IP_NI_SET_PACKET_FILTER USB_IP_NI_GET_LINK_STATUS USB_IP_NI_GET_LINK_SPEED USB_IP_NI_GET_HWADDR USB_IP_NI_GET_STATS USB_IP_NI_GET_MTU USB_IP_NI_RESET USB_IP_NI_SET_WRITE_PACKET_FUNC } USB_IP_NI_DRIVER_API; * * * * * * * * * * * pfInit; pfGetPacketBuffer; pfWritePacket; pfSetPacketFilter; pfGetLinkStatus; pfGetLinkSpeed; pfGetHWAddr; pfGetStats; pfGetMTU; pfReset; pfSetWritePacketFunc; Structure members Member Description pfInit Initializes the driver. pfGetPacketBuffer Returns a buffer for a data packet. pfWritePacket Delivers a data packet to target IP stack. pfSetPacketFilter Configures the type of accepted data packets. pfGetLinkStatus Returns the status of the connection to target IP stack. pfGetLinkSpeed Returns the connection speed. pfGetHWAddr Returns the HW address of the PC. pfGetStats Returns statistical counters. pfGetMTU Returns the size of the largest data packet which can be transferred. pfReset Resets the driver. pfSetWritePacketFunc Allows to change the WritePacket callback which was set by pfInit. Additional information The emUSB-Device-RNDIS/emUSB-Device-CDC-ECM component calls the functions of this API to exchange data and status information with the IP stack running on the target. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 416 CHAPTER 14 14.4.3.2 Target API USB_IP_NI_DRIVER_DATA Description Configuration data passed to network interface driver at initialization. Type definition typedef struct { const U8 * pHWAddr; unsigned NumBytesHWAddr; void * pDriverData; } USB_IP_NI_DRIVER_DATA; Structure members Member Description pHWAddr Optional pointer to a HW address (or MAC address) of the host network interface. NumBytesHWAddr Number of bytes in the HW address. Typically 6 bytes. pDriverData Pointer to a user context. Additional information When pHWAddr is NULL the MAC is automatically generated. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 417 CHAPTER 14 14.5 CDC-ECM IP Driver CDC-ECM IP Driver This section describes the emUSB-Device CDC-ECM IP stack interface in detail. 14.5.1 General information This release comes with IP NI driver which uses embOS/IP as the IP stack. If you are using embOS/IP this chapter can be ignored. This chapter is for those who wish to write their own IP stack interface for a third-party IP stack. The IP interface is handled through an API-table, which contains all relevant functions necessary for read/write operations and initialization. 14.5.2 Interface function list As described above, access to network functions is realized through an API-function table of type USB_IP_NI_DRIVER_API. The structure is declared in USB_Driver_IP_NI.h and it is described in section Data structures on page 414 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 418 CHAPTER 14 CDC-ECM IP Driver 14.5.3 USB_IP_NI_DRIVER_API in detail 14.5.3.1 USB_IP_NI_INIT Description Initializes the driver. Type definition typedef unsigned (USB_IP_NI_INIT)(const USB_IP_NI_DRIVER_DATA * pDriverData, USB_IP_WRITE_PACKET * pfWritePacket); Parameters Parameter pDriverData pfWritePacket Description in Pointer to driver configuration data. Call back function called by the IP stack to transmit a packet that should be send to the USB host. Return value IP NI driver instance ID. Additional information This function is called when the RNDIS/ECM interface is added to the USB stack. Typically the function makes a local copy of the HW address passed in the pDriverData structure. For more information this structure refer to USB_IP_NI_DRIVER_DATA. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 419 CHAPTER 14 14.5.3.2 CDC-ECM IP Driver USB_IP_NI_GET_PACKET_BUFFER Description Returns a buffer for a data packet. Type definition typedef void * (USB_IP_NI_GET_PACKET_BUFFER)(unsigned Id, unsigned NumBytes); Parameters Parameter Description Id Instance ID returned from USB_IP_NI_INIT. NumBytes Size of the requested buffer in bytes. Return value NULL = NULL Pointer to allocated buffer No buffer available Additional information The function should allocate a buffer of the requested size. If the buffer can not be allocated a NULL pointer should be returned. The function is called when a data packet is received from PC. The packet data is stored in the returned buffer. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 420 CHAPTER 14 14.5.3.3 CDC-ECM IP Driver USB_IP_NI_WRITE_PACKET Description Delivers a data packet to target IP stack. Type definition typedef void (USB_IP_NI_WRITE_PACKET)( unsigned Id, const void * pData, unsigned NumBytes); Parameters Parameter Id pData NumBytes Description Instance ID returned from USB_IP_NI_INIT. in Data of the received packet. Number of bytes stored in the buffer. Additional information The function is called after a data packet has been received from USB. pData points to the buffer returned by the USB_IP_NI_GET_PACKET_BUFFER function. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 421 CHAPTER 14 14.5.3.4 CDC-ECM IP Driver USB_IP_NI_SET_PACKET_FILTER Description Configures the type of accepted data packets. Type definition typedef void (USB_IP_NI_SET_PACKET_FILTER)(unsigned Id, U32 Mask); Parameters Parameter Description Id Instance ID returned from USB_IP_NI_INIT. Mask Type of accepted data packets. Additional information The Mask parameter should be interpreted as a boolean value. A value different than 0 indicates that the connection to target IP stack should be established. When the function is called with the Mask parameter set to 0 the connection to target IP stack should be interrupted. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 422 CHAPTER 14 14.5.3.5 CDC-ECM IP Driver USB_IP_NI_GET_LINK_STATUS Description Returns the status of the connection to target IP stack. Type definition typedef int (USB_IP_NI_GET_LINK_STATUS)(unsigned Id); Parameters Parameter Id Description Instance ID returned from USB_IP_NI_INIT. Return value USB_IP_NI_LINK_STATUS_DISCONNECTED USB_IP_NI_LINK_STATUS_CONNECTED emUSB-Device User Guide & Reference Manual Connected to target IP stack. Not connected to target IP stack. (c) 2010-2018 SEGGER Microcontroller GmbH 423 CHAPTER 14 14.5.3.6 CDC-ECM IP Driver USB_IP_NI_GET_LINK_SPEED Description Returns the connection speed. Type definition typedef U32 (USB_IP_NI_GET_LINK_SPEED)(unsigned Id); Parameters Parameter Description Instance ID returned from USB_IP_NI_INIT. Id Return value 0 =0 The connection speed in units of 100 bits/sec. Not connected. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 424 CHAPTER 14 14.5.3.7 CDC-ECM IP Driver USB_IP_NI_GET_HWADDR Description Returns the HW address of the host network interface (PC). Type definition typedef void (USB_IP_NI_GET_HWADDR)(unsigned Id, U8 * pAddr, unsigned NumBytes); Parameters Parameter Id pAddr NumBytes Description Instance ID returned from USB_IP_NI_INIT. out The HW address. Maximum number of bytes to store into pAddr. Additional information The returned HW address is the one passed to the driver in the call to USB_IP_NI_INIT. Typically the HW address is 6 bytes long. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 425 CHAPTER 14 14.5.3.8 CDC-ECM IP Driver USB_IP_NI_GET_STATS Description Returns statistical counters. Type definition typedef U32 (USB_IP_NI_GET_STATS)(unsigned Id, int Type); Parameters Parameter Description Id Instance ID returned from USB_IP_NI_INIT. Type The type of information requested. See table below. Return value Value of the requested statistical counter. Additional information The counters should be set to 0 when the USB_IP_NI_RESET function is called. Permitted values for parameter Type USB_IP_NI_STATS_WRITE_PACKET_OK Number of packets sent without errors to target IP stack. USB_IP_NI_STATS_WRITE_PACKET_ERROR Number of packets sent with errors to target IP stack. USB_IP_NI_STATS_READ_PACKET_OK Number of packets received without errors from target IP stack. USB_IP_NI_STATS_READ_PACKET_ERROR Number of packets received with errors from target IP stack. USB_IP_NI_STATS_READ_NO_BUFFER Number of packets received from target IP stack but dropped. USB_IP_NI_STATS_READ_ALIGN_ERROR Number of packets received from target IP stack with alignment errors. USB_IP_NI_STATS_WRITE_ONE_COLLISION Number of packets which were not sent to target IP stack due to the occurrence of one collision. USB_IP_NI_STATS_WRITE_MORE_COLLISIONS Number of packets which were not sent to target IP stack due to the occurrence of one or more collisions. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 426 CHAPTER 14 14.5.3.9 CDC-ECM IP Driver USB_IP_NI_GET_MTU Description Returns the maximum transmission unit, the size of the largest data packet which can be transferred. Type definition typedef U32 (USB_IP_NI_GET_MTU)(unsigned Id); Parameters Parameter Id Description Instance ID returned from USB_IP_NI_INIT. Return value The MTU size in bytes. Typically 1500 bytes. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 427 CHAPTER 14 14.5.3.10 CDC-ECM IP Driver USB_IP_NI_RESET Description Resets the driver. Type definition typedef void (USB_IP_NI_RESET)(unsigned Id); Parameters Parameter Id Description Instance ID returned from USB_IP_NI_INIT. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 428 CHAPTER 14 14.5.3.11 CDC-ECM IP Driver USB_IP_NI_SET_WRITE_PACKET_FUNC Description Changes the USB_IP_WRITE_PACKET callback which was added via USB_IP_NI_INIT to a different callback function. This function is only called by the stack when USB Ethernet is used. It is not called when RNDIS or ECM is used standalone. Type definition typedef void (USB_IP_NI_SET_WRITE_PACKET_FUNC) (unsigned Id, USB_IP_WRITE_PACKET * pfWritePacket); Parameters Parameter Description Id Instance ID returned from USB_IP_NI_INIT. pfWritePacket Call back function called by the IP stack to transmit a packet that should be send to the USB host. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 15 Audio This chapter gives a general overview of the Audio class and describes how to get the Audio component running on the target. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 430 CHAPTER 15 15.1 Overview Overview The USB Audio device class is a USB class protocol which can be used to transfer sound data from a device to a host and vice versa. Audio is supported by most operating systems out of the box and the installation of additional drivers is not required. emUSB-Device-Audio comes as a complete package and contains the following: * * * Generic USB handling USB Audio V1 device class implementation Sample application showing how to work with Audio emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 431 CHAPTER 15 15.2 Introduction Introduction SEGGER's implementation of the Audio class V1.0 is designed with minimal resource usage in mind, especially targeted to embedded devices. The implementation supports the usage of a "speaker" (input/output audio terminal with a feature terminal for controls) and a "microphone" (input/output audio terminal). The speaker and microphone can be used independently of each other, both can be enabled at the same time allowing audio transfer in either direction. The Audio class supports no synchronization, commands SET_CUR, GET_CUR, SET_MIN, GET_MIN, SET_MAX, GET_MAX, SET_RES, GET_RES, for the speaker interface feature unit controls are supported (volume, mute, etc.). Note emUSB-Device-Audio does not provide drivers/codecs for any audio peripherals, writing a driver to interface with the audio hardware is the responsibility of the customer. With emUSB-Device-Audio Audio data is transfered in the PCM encoding. The Audio class transfers multiple audio samples in a single packet. In the following sample the audio class is configured with 2 channels (stereo) and 16 bit data per channel: The length of a complete audio packet is equal to the bits per sample roundet up to bytes, multiplied by the number of channels and the sample rate, then divided by 1000 as a packet is sent every millisecond. For a sample rate of 48000, 16 bits per sample, 2 channels the calculation is as follows: 48000 * 16/8 * 2 / 1000 = 192 bytes For a sample rate of 44100, 16 bits per sample, 2 channels the calculation is as follows: 44100 * 16/8 * 2 / 1000 = 176.4 bytes Since we can not transfer 0.4 bytes the audio packets need to be 176 bytes (44 samples) and each 10th packet (sample size divided by the remainder: 4 / 0.4) should contain 45 samples (180 bytes) to make sure the sample rate remains at 44100. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 432 CHAPTER 15 15.3 Configuration Configuration 15.3.1 Initial configuration To get emUSB-Device-Audio up and running as well as doing an initial test, the configuration as delivered with the sample application should not be modified. 15.3.2 Final configuration The configuration must only be modified when emUSB-Device is integrated in your final product. Refer to section emUSB-Device Configuration on page 41 for detailed information about the generic information functions which have to be adapted. 15.3.3 Using the microphone interface When using the microphone sample applications with a PC it is not immediately clear whether they work as the PC only receives the audio data. To listen to the data being sent from the target running emUSB-Device-Audio to your PC it is necessary to enable a loopback mode which will transfer the audio data from the microphone interface to the physical speakers connected to your PC. Linux This guide assumes you are using pulse audio. * * * * * Make sure the device running emUSB-Device-Audio microphone sample is selected as the default sound input device. Make sure your speakers (or headphones) are selected as the default sound output device. Run pactl load-module module-loopback to enable loopback. At this point your should hear the sound being produced by the microphone sample. You can run pactl unload-module module-loopback to disable the loopback mode. Windows * * * Make sure your speakers (or headphones) are selected as the default sound output device. In the sound configuration of the device running emUSB-Device-Audio microphone sample tick the "Listen to this device" checkbox and click "Apply". At this point your should hear the sound being produced by the microphone sample. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 433 CHAPTER 15 Configuration Mac At the time of writing no built-in way of looping back audio is known. But there are a couple of third party applications out there which can enable loopback mode for macOS. 15.3.4 Using the speaker interface When using the speaker sample applications the PC merely needs to be configured to use the device running emUSB-Device-Audio as the default output sound device. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 434 CHAPTER 15 15.4 Target API Target API Function Description API functions USBD_AUDIO_Add() Adds an Audio interface to the USB stack. USBD_AUDIO_Read_Task() Task function of the Audio component which processes data received from host. USBD_AUDIO_Write_Task() Task function of the Audio component which processes data sent to the host. USBD_AUDIO_Start_Play() Starts providing audio data to the host using the microphone terminal of the audio class. USBD_AUDIO_Stop_Play() Stops providing audio data to the host. USBD_AUDIO_Start_Listen() Starts receiving audio data from the host using the speaker terminal of the audio class. USBD_AUDIO_Stop_Listen() Stops receiving audio data from the host. Data structures USBD_AUDIO_INIT_DATA Initialization data for the Audio interface. USBD_AUDIO_MIC_CONF Initialization data for the microphone interface. USBD_AUDIO_SPEAKER_CONF Initialization data for the speaker interface. Function definitions USBD_AUDIO_TX_FUNC Definition of the callback which is called when audio data is sent. USBD_AUDIO_RX_FUNC Definition of the callback which is called when audio data is received. USBD_AUDIO_CONTROL_FUNC Definition of the callback which is called when audio commands are received. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 435 CHAPTER 15 15.4.1 API functions 15.4.1.1 USBD_AUDIO_Add() Target API Description Adds an Audio interface to the USB stack. Prototype USBD_AUDIO_HANDLE USBD_AUDIO_Add(const USBD_AUDIO_INIT_DATA * pInitData); Parameters Parameter pInitData Description Pointer to a USBD_AUDIO_INIT_DATA structure containing values for the initialization. Return value USBD_AUDIO_HANDLE - Handle for the added Audio instance. Additional information After the initialization of USB core, this is the first function that needs to be called when an Audio interface is used with emUSB-Device. The structure USBD_AUDIO_INIT_DATA has to be initialized before USBD_AUDIO_Add() is called. Refer to USBD_AUDIO_INIT_DATA for more information. For the Audio component to be functional one or both of the following functions have to be created as a task: USBD_AUDIO_Read_Task(), USBD_AUDIO_Write_Task(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 436 CHAPTER 15 15.4.1.2 Target API USBD_AUDIO_Read_Task() Description Task function of the Audio component which processes data received from host. Handles operations of the speaker interface. Has to be created as a separate task. Prototype void USBD_AUDIO_Read_Task(void); Additional information Only necessary if the speaker interface is used. The function returns only when USBD_DeInit() is called. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 437 CHAPTER 15 15.4.1.3 Target API USBD_AUDIO_Write_Task() Description Task function of the Audio component which processes data sent to the host. Handles operations of the microphone interface. Has to be created as a separate task. Prototype void USBD_AUDIO_Write_Task(void); Additional information Only necessary if the microphone interface is used. The function returns only when USBD_DeInit() is called. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 438 CHAPTER 15 15.4.1.4 Target API USBD_AUDIO_Start_Play() Description Starts providing audio data to the host using the microphone terminal of the audio class. Prototype int USBD_AUDIO_Start_Play(USBD_AUDIO_HANDLE hInst); Parameters Parameter Description Handle to a valid Audio instance, returned by USBD_AUDIO_Add(). hInst Return value =0 <0 Success. An error occurred. Additional information This function starts the initial transfer after which the registered TX callback ( USBD_AUDIO_TX_FUNC ) is called. The callback is called after every successful transfer and should move the buffer pointer to the next audio packet accordingly or fill the same buffer with new data. The callback is called in an interrupt context. The execution of the callback together with the internal routines must never take longer than 1 millisecond. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 439 CHAPTER 15 15.4.1.5 Target API USBD_AUDIO_Stop_Play() Description Stops providing audio data to the host. Prototype void USBD_AUDIO_Stop_Play(USBD_AUDIO_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid Audio instance, returned by USBD_AUDIO_Add(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 440 CHAPTER 15 15.4.1.6 Target API USBD_AUDIO_Start_Listen() Description Starts receiving audio data from the host using the speaker terminal of the audio class. Prototype int USBD_AUDIO_Start_Listen(USBD_AUDIO_HANDLE hInst); Parameters Parameter Description Handle to a valid Audio instance, returned by USBD_AUDIO_Add(). hInst Return value =0 <0 Success. An error occurred. Additional information This function enables the registered callback function ( USBD_AUDIO_RX_FUNC ) which is called before the host sends data to the target. Inside the callback you may read the received data. The callback is called in an interrupt context. The execution of the callback together with the internal routines must never take longer than 1 millisecond. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 441 CHAPTER 15 15.4.1.7 Target API USBD_AUDIO_Stop_Listen() Description Stops receiving audio data from the host. Prototype void USBD_AUDIO_Stop_Listen(USBD_AUDIO_HANDLE hInst); Parameters Parameter hInst Description Handle to a valid Audio instance, returned by USBD_AUDIO_Add(). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 442 CHAPTER 15 15.4.2 Data structures 15.4.2.1 USBD_AUDIO_INIT_DATA Target API Description Initialization data for the Audio interface. Type definition typedef struct { U8 U8 U8 const U8 unsigned unsigned USBD_AUDIO_RX_FUNC USBD_AUDIO_TX_FUNC USBD_AUDIO_CONTROL_FUNC void const USBD_AUDIO_MIC_CONF const USBD_AUDIO_SPEAKER_CONF int int } USBD_AUDIO_INIT_DATA; * * * * * * * * EPIn; EPOut; pBufOut; pBufIn; InPacketSize; OutPacketSize; pfOnOut; pfOnIn; pfOnControl; pControlUserContext; pMicConf; pSpeakerConf; ReadTimeout; WriteTimeout; Structure members Member Description EPIn Isochronous endpoint for sending data to the host. If microphone functionality is not desired set this to 0. EPOut Isochronous endpoint for receiving data from the host. If speaker functionality is not desired set this to 0. pBufOut Buffer used with OUT transfers (speaker interface). pBufIn Buffer used with IN transfers (microphone interface). InPacketSize Size of a single audio IN packet. Must be calculated as follows: SampleRate * NumChannels * BitsPerSample/8 / 1000 OutPacketSize Size of a single audio OUT packet. Must be calculated as follows: SampleRate * NumChannels * BitsPerSample/8 / 1000 pfOnOut Pointer to a function of type USBD_AUDIO_RX_FUNC which handles incoming audio data. Needs to be set when the speaker interface is used. pfOnIn Pointer to a function of type USBD_AUDIO_TX_FUNC which handles outgoing audio data. Needs to be set when the microphone interface is used. pfOnControl Pointer to a function of type USBD_AUDIO_CONTROL_FUNC which handles audio commands. Always needs to be set. pControlUserContext Pointer to a user context which is passed to the pfOnControl function. Optional, can be NULL.. pMicConf Pointer to a structure of type USBD_AUDIO_MIC_CONF which contains configuration data for the microphone interface. If microphone functionality is not desired set this pointer to NULL. pSpeakerConf Pointer to a structure of type USBD_AUDIO_SPEAKER_CONF which contains configuration data for the speaker interface. If speaker functionality is not desired set this pointer to NULL. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 443 CHAPTER 15 Member Target API Description ReadTimeout Initial timeout for read requests (speaker interface). Can be changed via USBD_AUDIO_Set_Timeouts . WriteTimeout Initial timeout for write requests (microphone interface). Can be changed via USBD_AUDIO_Set_Timeouts . emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 444 CHAPTER 15 15.4.2.2 Target API USBD_AUDIO_MIC_CONF Description Initialization data for the microphone interface. Type definition typedef struct { U8 Controls; U8 NrChannels; U8 SubFrameSize; U8 BitResolution; U32 SamFreq; } USBD_AUDIO_MIC_CONF; Structure members Member Description Controls Reserved. NrChannels Number of audio channels. SubFrameSize Size of an audio frame in bytes. Must be able to hold BitResolution bits. BitResolution Number of bits inside the audio frame dedicated to audio data. (Any remaining bits are padding.) SamFreq Sample frequency. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 445 CHAPTER 15 15.4.2.3 Target API USBD_AUDIO_SPEAKER_CONF Description Initialization data for the speaker interface . Type definition typedef struct { U8 Controls; U8 NrChannels; U8 SubFrameSize; U8 BitResolution; U32 SamFreq; } USBD_AUDIO_SPEAKER_CONF; Structure members Member Description Controls A bit set to 1 indicates that the mentioned Control is supported: * b0: Mute * b1: Volume * b2: Bass * b3: Mid * b4: Treble * b5: Graphic Equalizer * b6: Automatic Gain * b7: Delay NrChannels Number of audio channels. SubFrameSize Size of an audio frame in bytes. Must be able to hold BitResolution bits. BitResolution Number of bits inside the audio frame dedicated to audio data. (Any remaining bits are padding.) SamFreq Sample frequency. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 446 CHAPTER 15 15.4.3 Function definitions 15.4.3.1 USBD_AUDIO_TX_FUNC Target API Description Definition of the callback which is called when audio data is sent. This callback is called in the context of USBD_AUDIO_Write_Task() Type definition typedef void USBD_AUDIO_TX_FUNC( void * pUserContext, const U8 * * ppNextBuffer, U32 * pNextPacketSize); Parameters Parameter Description pUserContext User context which is passed to the callback. ppNextBuffer Buffer containing audio samples which should match the configuration from USBD_AUDIO_MIC_CONF . Initially this points to the pBufIn from the USBD_AUDIO_INIT_DATA structure. The user can change this pointer to a different buffer which will be used in the next transaction or fill the same buffer with new data. pNextBufferSize Size of the next buffer. Example static void _cbOnIn(void * pUserContext, const U8 ** ppNextBuffer, U32 * pNextPacketSize) { USB_MEMCPY(_pBufMic, _pDataSource, PACKET_SIZE_IN); *ppNextBuffer = _pBufMic; *pNextPacketSize = PACKET_SIZE_IN; } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 447 CHAPTER 15 15.4.3.2 Target API USBD_AUDIO_RX_FUNC Description Definition of the callback which is called when audio data is received. This callback is called in the context of USBD_AUDIO_Read_Task(). Type definition typedef void USBD_AUDIO_RX_FUNC(void * pUserContext, int NumBytesReceived, U8 * * ppNextBuffer, U32 * pNextBufferSize); Parameters Parameter Description pUserContext User context which is passed to the callback. NumBytesReceived The number of bytes which have been read in this transaction. ppNextBuffer Buffer containing audio samples which should match the configuration from USBD_AUDIO_SPEAKER_CONF . Initially this points to the pBufOut from the USBD_AUDIO_INIT_DATA structure. The user can change this pointer to a different buffer which will be used in the next transaction or leave it as it is and copy the data from this buffer elsewhere. pNextBufferSize Size of the next buffer. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 448 CHAPTER 15 Target API Example static static static static static static U8 U8 U8 * U8 * U32 U32 _acBuf1[BUFFER_SIZE]; _acBuf2[BUFFER_SIZE]; _pBuf; _pBufComplete; _NumBytesInFullBuffer; _NumBytesInBuffer; // Receive callback function. static void _cbOnOut(void * pUserContext, int NumBytesReceived, U8 ** ppNextBuffer, U32 * pNextBufferSize) { char MBEvent; // // Check if the _next_ transfer would still fit into the buffer. // If not - switch the buffer. // if ((_NumBytesInBuffer + NumBytesReceived + PACKET_SIZE_OUT) > BUFFER_SIZE) { // // Switch buffers. // if (_CurrentBuffer == 1) { _CurrentBuffer = 2; _pBuf = _acBuf2; } else { _CurrentBuffer = 1; _pBuf = _acBuf1; } _NumBytesInFullBuffer = _NumBytesInBuffer + NumBytesReceived; _NumBytesInBuffer = 0; MBEvent = BUFFER_FULL; // // Notify the task that a buffer is full. // if (OS_PutMailCond1(&_MailBox, &MBEvent) != 0) { printf("Missed packet."); } } else { _pBuf += NumBytesReceived; _NumBytesInBuffer += NumBytesReceived; } *ppNextBuffer = _pBuf; } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 449 CHAPTER 15 15.4.3.3 Target API USBD_AUDIO_CONTROL_FUNC Description Definition of the callback which is called when audio commands are received. This callback is called in an interrupt context. Type definition typedef int USBD_AUDIO_CONTROL_FUNC(void * pUserContext, U8 Event, U8 Unit, U8 ControlSelector, U8 * pBuffer, U32 NumBytes); Parameters Parameter Description pUserContext User context which is passed to the callback. Event Audio event ID. Unit ID of the feature unit. In case of USB_AUDIO_PLAYBACK_* & USB_AUDIO_RECORD_*: 0. ControlSelector ID of the control. In case of USB_AUDIO_PLAYBACK_* & USB_AUDIO_RECORD_*: 0. pBuffer In case of GET events: pointer to a buffer into which the callback should write the reply. In case of SET events: pointer to a buffer containing the command value. In case of USB_AUDIO_PLAYBACK_* & USB_AUDIO_RECORD_*: NULL. NumBytes In case of GET events: requested size of the reply in bytes. In case of SET events: number of bytes in pBuffer. In case of USB_AUDIO_PLAYBACK_* & USB_AUDIO_RECORD_*: 0. Return value =0 0 Audio command was handled by the callback. The stack will send the reply. Audio command was not handled by the callback. The stack will STALL the request. Additional information USB_AUDIO_PLAYBACK_* & USB_AUDIO_RECORD_* events are sent upon receiving a Set Interface USB request for Alternate Setting 1 for the respective interface (microphone or speaker). By default an Audio interface is set to Alternative Setting 0 in which it can not send or receive anything. The host switches the Alternative Setting to 1 when it has to send data to the device, this can be e.g. triggered by pressing "play" in your music player. Normally the host should switch the device back to Alternative Interface 0 when it has stopped sending audio data. This works well on Linux and OS X, but does not work reliably on Windows. When using Windows as a host it seems to depend on the application whether these events are generated or not. E.g. with some applications you will receive USB_AUDIO_PLAYBACK_START when "play" is pressed, but USB_AUDIO_PLAYBACK_STOP will not be sent when "pause" or "stop" is pressed. Relying on these events to check when the host has stopped sending data is not advised, instead set timeouts via USBD_AUDIO_Set_Timeouts and check for timeouts inside your USBD_AUDIO_RX_FUNC and USBD_AUDIO_TX_FUNC . emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 450 CHAPTER 15 Target API Example // Control callback function. static int _cbOnControl(void * pUserContext, U8 Event, U8 Unit, U8 ControlSelector, U8 * pBuffer, U32 NumBytes) { int r; r = 0; switch (Event) { case USB_AUDIO_SET_CUR: switch (ControlSelector) { case USB_AUDIO_MUTE_CONTROL: if (*pBuffer == 1) { _SetMute(1); } else { _SetMute(0); } break; default: r = 1; break; } break; <...> <handle other commands> <...> } return r; } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 16 Combining USB components (Multi-Interface) In some cases, it is necessary to combine different USB components in one device. This chapter will describe how to do this and which steps are necessary. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 452 CHAPTER 16 16.1 Overview Overview The USB specification allows implementation of more than one component (function) in a single device. This is achieved by combining two or more components. These devices will be recognized by the USB host as composite device and each component will be recognized as an independent device. One device, for example a data logger, can have two components: This device can show log data files that were stored on a NAND flash through the MSD component. And the configuration of the data logger can be changed by using a BULK component, CDC component or even HID component. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 453 CHAPTER 16 16.1.1 Overview Single interface device classes Components can be combined because most USB device classes are based on one interface. This means that those components describe themselves at the interface descriptor level and thus makes it easy to combine different or even the same device classes into one device. Such devices classes are MSD, HID and generic bulk. 16.1.2 Multiple interface device classes In contrast to the single interfaces classes there are classes with multiple interfaces such as CDC and AUDIO or VIDEO class. These classes define their class identifier in the device descriptor. All interface descriptors are recognized as part of the component that is defined in the device descriptor. This prevents the combination of multiple interface device classes (for example, CDC) with any other component. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 454 CHAPTER 16 16.1.3 Overview IAD class To remove this limitation the USB organization defines a descriptor type that allows the combination of single interface device classes with multiple interface device classes. This descriptor is called an Interface Association Descriptor (IAD). It decouples the multi-interface class from other interfaces. Since IAD is an extension to the original USB specification, it is not supported by all hosts, especially older host software. If IAD is not supported, the device may not be enumerated correctly. Supported HOST At the time of writing, IAD is supported by: * * Windows XP with Service pack 2 and newer Linux Kernel 2.6.22 and higher emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 455 CHAPTER 16 16.2 Configuration Configuration In general, no configuration is required. By default, emUSB-Device supports up to four interfaces. If more interfaces are needed the following macro must be modified: Type Macro Default Description Numeric USB_MAX_NUM_IF 4 Defines the maximum number of interfaces emUSB-Device shall handle. Numeric USB_MAX_NUM_IAD 3 Defines the maximum number of Interface Association Descriptors emUSB-Device shall handle. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 456 CHAPTER 16 16.3 How to combine How to combine Combining different single interface emUSB-Device components (Bulk, HID, MSD) is an easy step, all that needs to be done is calling the appropriate USBD_xxx_Add() function. For adding the CDC component additional steps need to be taken. For detailed information refer to emUSB-Device component specific modification on page 460 and check the following sample. Requirements * * RTOS, every component requires a separate task. Sufficient endpoints for all used device classes. Make sure that your USB device controller has enough endpoints available to handle all the interfaces that shall be integrated. Sample application The following sample application uses embOS as the RTOS. This listing is taken from USB_CompositeDevice_CDC_MSD.c. /********************************************************************* * SEGGER MICROCONTROLLER GmbH & Co. KG * * Solutions for real time microcontroller applications * ********************************************************************** * * * (c) 2003-2011 SEGGER Microcontroller GmbH & Co KG * * * * Internet: www.segger.com Support: support@segger.com * * * ********************************************************************** * * * USB device stack for embedded applications * * * ********************************************************************** ---------------------------------------------------------------------File : USB_CompositeDevice_CDC_MSD.c Purpose : Sample showing a USB device with multiple interfaces (CDC+MSD). -------- END-OF-HEADER --------------------------------------------*/ #include <stdio.h> #include <stdio.h> #include "USB.h" #include "USB_CDC.h" #include "BSP.h" #include "USB_MSD.h" #include "FS.h" #include "RTOS.h" /********************************************************************* * * Static const data * ********************************************************************** */ // // Information that is used during enumeration. // static const USB_DEVICE_INFO _DeviceInfo = { 0x8765, // VendorId 0x1256, // ProductId "Vendor", // VendorName "MSD/CDC Composite device", // ProductName "1234567890ABCDEF" // SerialNumber }; // // String information used when inquiring the volume 0. // emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 457 CHAPTER 16 How to combine static const USB_MSD_LUN_INFO _Lun0Info = { "Vendor", // MSD VendorName "MSD Volume", // MSD ProductName "1.00", // MSD ProductVer "134657890" // MSD SerialNo }; /********************************************************************* * * Static data * ********************************************************************** */ // Data for MSD Task static OS_STACKPTR int _aMSDStack[512]; /* Task stacks */ static OS_TASK _MSDTCB; /* Task-control-blocks */ /********************************************************************* * * Static code * ********************************************************************** */ /********************************************************************* * * _AddMSD * * Function description * Add mass storage device to USB stack */ static void _AddMSD(void) { static U8 _abOutBuffer[USB_HS_BULK_MAX_PACKET_SIZE]; USB_MSD_INIT_DATA InitData; USB_MSD_INST_DATA InstData; InitData.EPIn = USBD_AddEP(1, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, NULL, 0); InitData.EPOut = USBD_AddEP(0, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, _abOutBuffer, sizeof(_abOutBuffer)); USB_MSD_Add(&InitData); // // Add logical unit 0: RAM drive, using SDRAM // memset(&InstData, 0, sizeof(InstData)); InstData.pAPI = &USB_MSD_StorageByName; InstData.DriverData.pStart = (void *)""; InstData.pLunInfo = &_Lun0Info; USB_MSD_AddUnit(&InstData); } /********************************************************************* * * _MSDTask * * Function description * Add mass storage device to USB stack */ static void _MSDTask(void) { while (1) { while ((USBD_GetState() & (USB_STAT_CONFIGURED | USB_STAT_SUSPENDED)) != USB_STAT_CONFIGURED) { USB_OS_Delay(50); } USB_MSD_Task(); } } /********************************************************************* * * _OnLineCoding * emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 458 CHAPTER 16 How to combine * Function description * Called whenever a "SetLineCoding" Packet has been received * * Notes * (1) Context * This function is called directly from an ISR in most cases. */ static void _OnLineCoding(USB_CDC_LINE_CODING * pLineCoding) { #if 0 printf("DTERate=%u, CharFormat=%u, ParityType=%u, DataBits=%u\n", pLineCoding->DTERate, pLineCoding->CharFormat, pLineCoding->ParityType, pLineCoding->DataBits); #else BSP_USE_PARA(pLineCoding); #endif } /********************************************************************* * * _AddCDC * * Function description * Add communication device class to USB stack */ static void _AddCDC(void) { static U8 _abOutBuffer[USB_HS_BULK_MAX_PACKET_SIZE]; USB_CDC_INIT_DATA InitData; InitData.EPIn = USBD_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_BULK, 0, NULL, 0); InitData.EPOut = USBD_AddEP(USB_DIR_OUT, USB_TRANSFER_TYPE_BULK, 0, _abOutBuffer, sizeof(_abOutBuffer)); InitData.EPInt = USBD_AddEP(USB_DIR_IN, USB_TRANSFER_TYPE_INT, 8, NULL, 0); USBD_CDC_Add(&InitData); USBD_CDC_SetOnLineCoding(_OnLineCoding); } /********************************************************************* * * Public code * ********************************************************************** */ /********************************************************************* * * MainTask * * USB handling task. * Modify to implement the desired protocol */ #ifdef __cplusplus extern "C" { /* Make sure we have C-declarations in C++ programs */ #endif void MainTask(void); #ifdef __cplusplus } #endif void MainTask(void) { USBD_Init(); USBD_EnableIAD(); _AddCDC(); _AddMSD(); USBD_SetDeviceInfo(&_DeviceInfo); USBD_Start(); BSP_SetLED(0); OS_CREATETASK(&_MSDTCB, "MSDTask", _MSDTask, 200, _aMSDStack); while (1) { char ac[64]; int NumBytesReceived; // emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 459 CHAPTER 16 How to combine // Wait for configuration // while ((USBD_GetState() & (USB_STAT_CONFIGURED | USB_STAT_SUSPENDED)) != USB_STAT_CONFIGURED) { BSP_ToggleLED(0); USB_OS_Delay(50); } BSP_SetLED(0); NumBytesReceived = USBD_CDC_Receive(&ac[0], sizeof(ac)); if (NumBytesReceived > 0) { USBD_CDC_Write(&ac[0], NumBytesReceived); } } } /**************************** end of file ***************************/ emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 460 CHAPTER 16 16.4 emUSB-Device component specific modification emUSB-Device component specific modification There are different steps for each emUSB-Device component. The next section shows what needs to be done on both sides: device and host-side. 16.4.1 BULK component 16.4.1.1 Device side No modification on device side needs to be made. 16.4.1.2 Host side No modification on host side needs to be made. 16.4.2 MSD component 16.4.2.1 Device side No modification on device side needs to be made. 16.4.2.2 Host side No modification on host side needs to be made. 16.4.3 HID component 16.4.3.1 Device side No modification on device side needs to be made. 16.4.3.2 Host side No modification on host side needs to be made. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 461 CHAPTER 16 16.4.4 CDC component 16.4.4.1 Device side emUSB-Device component specific modification In order to combine the CDC component with other components, the function USBD_EnableIAD() needs to be called, otherwise the device will not enumerate correctly. Refer to section How to combine on page 390 and check the listing of the sample application. 16.4.4.2 Host side Due to a limitation of the internal CDC serial driver of Windows, a composite device with CDC component and another device component(s) is only properly recognized by Windows XP SP3 and above. Linux kernel supports IAD with version 2.6.22. For Windows before Windows 10 the .inf file needs to be modified. The provided .inf file: ; ; Device installation file for ; USB 2 COM port emulation ; ; ; [Version] Signature="$Windows NT$" Class=Ports ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} Provider=%MFGNAME% LayoutFile=layout.inf DriverVer=03/26/2007,6.0.2600.1 CatalogFile=usbser.cat [Manufacturer] %MFGNAME%=CDCDevice,NT,NTamd64 [DestinationDirs] DefaultDestDir = 12 [CDCDevice.NT] %DESCRIPTION%=DriverInstall,USB\VID_8765&PID_1111&Mi_xx [CDCDevice.NTamd64] %DESCRIPTION%=DriverInstall,USB\VID_8765&PID_0234&Mi_xx %DESCRIPTION%=DriverInstall,USB\VID_8765&PID_1111&Mi_xx [DriverInstall.NT] Include=mdmcpq.inf CopyFiles=FakeModemCopyFileSection AddReg=DriverInstall.NT.AddReg [DriverInstall.NT.AddReg] HKR,,DevLoader,,*ntkern HKR,,NTMPDriver,,usbser.sys HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" [DriverInstall.NT.Services] AddService=usbser, 0x00000002, DriverServiceInst [DriverServiceInst] DisplayName=%SERVICE% ServiceType=1 StartType=3 ErrorControl=1 ServiceBinary=%12%\usbser.sys [Strings] MFGNAME = "Manufacturer" emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 462 CHAPTER 16 emUSB-Device component specific modification DESCRIPTION = "USB CDC serial port emulation" SERVICE = "USB CDC serial port emulation" red - required modifications Please add the red colored text to your .inf file and change xx with the interface number of the CDC component. The interface number is a zero based index and is assigned by the emUSB-Device stack when calling USBD_CDC_Add() function. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 463 CHAPTER 16 16.5 MSD and MTP combination feature MSD and MTP combination feature MTP is often preferable because of the advantages it offers over MSD. But MTP is not natively recognized by macOS. To provide a solution which works on all the major operating systems SEGGER developed a feature which presents the device as a single interface that enumerates as MTP or as MSD depending on the host PC's operating system. 16.5.1 Configuration The code of the combination feature is contained in the files USB_MSD_MTP.c and USB_MSD_MTP.h. The MSD and MTP emUSB-Device packages are obviously also necessary for this to work. The combination feature is disabled by default and can be enabled by setting the configuration define USB_SUPPORT_MSD_MTP_COMBINATION to 1 inside your USB_Conf.h file. This system works similar to MSD or MTP. The device information is added via USBD_MSD_MTP_Add, storage information is added for the MSD and MTP module (USBD_MSD_AddUnit and USBD_MTP_AddStorage). And finally the blocking function USBD_MSD_MTP_Task is called which handles all the communication as well as switching between MSD and MTP. Source code excerpt from the MSD+MTP sample USB_MSD_MTP_FS_Start.c: static void _AddMSDMTP(void) { USB_MSD_INIT_DATA MSDInitData; USB_MSD_INST_DATA MSDInstData; USB_MTP_INIT_DATA MTPInitData; USB_MTP_INST_DATA MTPInstData; // // Set the endpoints in the MSD init data to the same Endpoints as MTP. // MTPInitData.EPIn = USBD_AddEP(1, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, NULL, 0); MSDInitData.EPIn = MTPInitData.EPIn; MTPInitData.EPOut = USBD_AddEP(0, USB_TRANSFER_TYPE_BULK, USB_HS_BULK_MAX_PACKET_SIZE, _acReceiveBuffer, sizeof(_acReceiveBuffer)); MSDInitData.EPOut = MTPInitData.EPOut; MTPInitData.EPInt = USBD_AddEP(1, USB_TRANSFER_TYPE_INT, 10, NULL, 0); MTPInitData.pObjectList = _aObjectList; MTPInitData.NumBytesObjectList = sizeof(_aObjectList); MTPInitData.pDataBuffer = _aDataBuffer; MTPInitData.NumBytesDataBuffer = sizeof(_aDataBuffer); MTPInitData.pMTPInfo = &_MTPInfo; USBD_SetDeviceInfo(&_DeviceInfo); USBD_MSD_MTP_Add(&MSDInitData, &MTPInitData); // // Add logical unit 0 to MSD // memset(&MSDInstData, 0, sizeof(MSDInstData)); MSDInstData.pAPI = &USB_MSD_StorageByName; MSDInstData.DriverData.pStart = (void *)""; MSDInstData.DriverData.pSectorBuffer = _aSectorBuffer; MSDInstData.DriverData.NumBytes4Buffer = sizeof(_aSectorBuffer); MSDInstData.pLunInfo = &_Lun0Info; USBD_MSD_AddUnit(&MSDInstData); // // Add a storage driver to MTP component. // MTPInstData.pAPI = &USB_MTP_StorageFS; MTPInstData.sDescription = "MTP volume"; MTPInstData.sVolumeId = "0123456789"; MTPInstData.DriverData.pRootDir = ""; USBD_MTP_AddStorage(&MTPInstData); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 464 CHAPTER 16 MSD and MTP combination feature } 16.5.2 Limitations Because of the way libMTP recognizes MTP devices on Linux based systems a device which uses the MTP/MSD combination feature will be recognized as MSD. Unless the device is added into the libMTP device list (describing this procedure is beyond the scope of this documentation). emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 465 CHAPTER 16 16.5.3 MSD and MTP combination feature Target API Function Description API functions USBD_MSD_MTP_Add() Adds an MSD/MTP interface to the USB stack. USBD_MSD_MTP_GetMode() Returns current function mode. USBD_MSD_MTP_Task() Main task function of MSD/MTP combination which switches between MSD and MTP. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 466 CHAPTER 16 16.5.3.1 MSD and MTP combination feature USBD_MSD_MTP_Add() Description Adds an MSD/MTP interface to the USB stack. Prototype int USBD_MSD_MTP_Add(const USB_MSD_INIT_DATA * pMSDInitData, const USB_MTP_INIT_DATA * pMTPInitData); Parameters Parameter Description pMSDInitData Pointer to a USB_MSD_INIT_DATA structure. pMTPInitData Pointer to a USB_MTP_INIT_DATA structure. Return value 0 = Successfully added. Additional information After the initialization of USB core, this is the first function that needs to be called when an MSD/MTP interface is used with emUSB-Device. The structures USB_MTP_INIT_DATA and USB_MSD_INIT_DATA have to be initialized before USBD_MSD_MTP_Add() is called. The bulk endpoints configured for MTP and MSD must be the same. Refer to USB_MTP_INIT_DATA and USB_MSD_INIT_DATA for more information. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 467 CHAPTER 16 16.5.3.2 MSD and MTP combination feature USBD_MSD_MTP_GetMode() Description Returns current function mode. Prototype int USBD_MSD_MTP_GetMode(void); Return value USBD_MSD_MTP_MODE_NOT_INITED USBD_MSD_MTP_MODE_MSD USBD_MSD_MTP_MODE_MTP Not connected or not initialized yet. Running as MSD. Running as MTP. Additional information This function can be used to make sure that the application code does not access the storage medium when running as MSD. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 468 CHAPTER 16 16.5.3.3 MSD and MTP combination feature USBD_MSD_MTP_Task() Description Main task function of MSD/MTP combination which switches between MSD and MTP. Prototype void USBD_MSD_MTP_Task(void); Additional information The function returns when the USB device is detached or suspended. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 17 Target OS Interface This chapter describes the functions of the operating system abstraction layer. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 470 CHAPTER 17 17.1 General information General information emUSB-Device includes an OS abstraction layer which should make it possible to use an arbitrary operating system together with emUSB-Device. To adapt emUSB-Device to a new OS one only has to map the functions listed below in section Interface function list to the native OS functions. This chapter describes the advanced OS layer used by the USB stack if the preprocessor define USBD_OS_LAYER_EX is set to 1 in USB_Conf.h. If not set, the old, deprecated OS layer interface is used. SEGGER took great care when designing this abstraction layer, to make it easy to understand and to adapt to different operating systems. 17.1.1 Operating system support supplied with this release In the current version, abstraction layers for embOS and C/OS-II are available. A kernel abstraction layer for using emUSB-Device without any RTOS (superloop) is also supplied. Abstraction layers for other operating systems are available upon request. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 471 CHAPTER 17 17.2 Interface function list Interface function list Name Description API functions USB_OS_DeInit() Frees all resources used by the OS layer. USB_OS_Delay() Delays for a given number of ms. USB_OS_DecRI() Leave a critical region for the USB stack: Decrements interrupt disable count and enable interrupts if counter reaches 0. USB_OS_GetTickCnt() Returns the current system time in milliseconds or system ticks. USB_OS_IncDI() Enter a critical region for the USB stack: Increments interrupt disable count and disables interrupts. USB_OS_Init() This function initialize all OS objects that are necessary. USB_OS_Panic() Halts emUSB-Device. USB_OS_Signal() Wakes the task waiting for signal. USB_OS_Wait() Blocks the task until USB_OS_Signal() is called for a given transaction. USB_OS_WaitTimed() Blocks the task until USB_OS_Signal() is called for a given transaction or a timeout occurs. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 472 CHAPTER 17 17.2.0.1 Interface function list USB_OS_DeInit() Description Frees all resources used by the OS layer. Prototype void USB_OS_DeInit(void); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 473 CHAPTER 17 17.2.0.2 Interface function list USB_OS_Delay() Description Delays for a given number of ms. Prototype void USB_OS_Delay(int ms); Parameters Parameter ms Description Number of ms. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 474 CHAPTER 17 17.2.0.3 Interface function list USB_OS_DecRI() Description Leave a critical region for the USB stack: Decrements interrupt disable count and enable interrupts if counter reaches 0. Prototype void USB_OS_DecRI(void); Additional information The USB stack will perform nested calls to USB_OS_IncDI() and USB_OS_DecRI(). This function may be called from a task context or from within an interrupt. If called from an interrupt, it need not do anything. An alternate implementation would be to * * enable the USB interrupts, unlock the mutex or semaphore locked in USB_OS_IncDI() if the disable count reaches 0. This may be more efficient, because interrupts of other peripherals can be serviced while inside a critical section of the USB stack. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 475 CHAPTER 17 17.2.0.4 Interface function list USB_OS_GetTickCnt() Description Returns the current system time in milliseconds or system ticks. Prototype U32 USB_OS_GetTickCnt(void); Return value Current system time. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 476 CHAPTER 17 17.2.0.5 Interface function list USB_OS_IncDI() Description Enter a critical region for the USB stack: Increments interrupt disable count and disables interrupts. Prototype void USB_OS_IncDI(void); Additional information The USB stack will perform nested calls to USB_OS_IncDI() and USB_OS_DecRI(). This function may be called from a task context or from within an interrupt. If called from an interrupt, it need not do anything. An alternate implementation would be to * * perform a lock using a mutex or semaphore and disable the USB interrupts. This may be more efficient, because interrupts of other peripherals can be serviced while inside a critical section of the USB stack. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 477 CHAPTER 17 17.2.0.6 Interface function list USB_OS_Init() Description This function initialize all OS objects that are necessary. Prototype void USB_OS_Init(void); emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 478 CHAPTER 17 17.2.0.7 Interface function list USB_OS_Panic() Description Halts emUSB-Device. Called if a fatal error is detected. Prototype void USB_OS_Panic(const char * pErrMsg); Parameters Parameter pErrMsg Description Pointer to error message string. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 479 CHAPTER 17 17.2.0.8 Interface function list USB_OS_Signal() Description Wakes the task waiting for signal. Prototype void USB_OS_Signal(unsigned EPIndex, unsigned TransactCnt); Parameters Parameter Description EPIndex Endpoint index. Signaling must be independent for all endpoints. TransactCnt Transaction counter. Specifies which transaction has been finished. Additional information This routine is typically called from within an interrupt service routine. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 480 CHAPTER 17 17.2.0.9 Interface function list USB_OS_Wait() Description Blocks the task until USB_OS_Signal() is called for a given transaction. Prototype void USB_OS_Wait(unsigned EPIndex, unsigned TransactCnt); Parameters Parameter Description EPIndex Endpoint index. Signaling must be independent for all endpoints. TransactCnt Transaction counter. Specifies the transaction to wait for. Additional information The function must ignore signaling transactions other than given in TransactCnt. If this transaction was signaled before this function was called, it must return immediately. This routine is called from a task. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 481 CHAPTER 17 17.2.0.10 Interface function list USB_OS_WaitTimed() Description Blocks the task until USB_OS_Signal() is called for a given transaction or a timeout occurs. Prototype int USB_OS_WaitTimed(unsigned EPIndex, unsigned ms, unsigned TransactCnt); Parameters Parameter Description EPIndex Endpoint index. Signaling must be independent for all endpoints. ms Timeout time given in ms. TransactCnt Transaction counter. Specifies the transaction to wait for. Return value 0 1 Task was signaled within the given timeout. Timeout occurred. Additional information The function must ignore signaling transactions other than given in TransactCnt. If this transaction was signaled before this function was called, it must return immediately. USB_OS_WaitTimed() is called from a task. This function is used by all available timed routines. Alternatively this function may take the given timeout in units of system ticks of the underlying operating system instead of milliseconds. In this case all API functions that support a timeout parameter use also system ticks for the timeout. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 482 CHAPTER 17 17.3 Example Example A configuration to use USB with embOS might look like the sample below. This example is also supplied in the subdirectory OS\embOS\. /********************************************************************* * SEGGER MICROCONTROLLER GmbH & Co. KG * * Solutions for real time microcontroller applications * ********************************************************************** * * * (c) 2003-2017 SEGGER Microcontroller GmbH & Co KG * * * * Internet: www.segger.com Support: support@segger.com * * * ********************************************************************** * * * USB device stack for embedded applications * * * ********************************************************************** ---------------------------------------------------------------------File : USB_OS_embOS.c Purpose : Kernel abstraction for embOS Do not modify to allow easy updates ! -------- END-OF-HEADER --------------------------------------------*/ #include "USB_Private.h" #include "RTOS.h" /********************************************************************* * * Static data * ********************************************************************** */ static OS_MAILBOX _aMailBox[USB_NUM_EPS + USB_EXTRA_EVENTS]; static U32 _aMBBuffer[USB_NUM_EPS + USB_EXTRA_EVENTS]; /********************************************************************* * * Public code * ********************************************************************** */ /********************************************************************* * * USB_OS_Init * * Function description * This function initialize all OS objects that are necessary. */ void USB_OS_Init(void) { unsigned i; for (i = 0; i < COUNTOF(_aMailBox); i++) { OS_CreateMB(_aMailBox + i, sizeof(U32), 1, _aMBBuffer + i); } } /********************************************************************* * * USB_OS_DeInit * * Function description * Frees all resources used by the OS layer. */ void USB_OS_DeInit(void) { unsigned i; for (i = 0; i < COUNTOF(_aMailBox); i++) { OS_DeleteMB(&_aMailBox[i]); } } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 483 CHAPTER 17 Example /********************************************************** * * USB_OS_Signal * * Function description * Wakes the task waiting for signal. */ void USB_OS_Signal(unsigned EPIndex, unsigned TransactCnt) { U32 Tmp; do { OS_GetMail(&_aMailBox[EPIndex], &Tmp); } while (Tmp != TransactCnt); } /********************************************************** * * USB_OS_Wait * * Function description * Blocks the task until USB_OS_Signal() is called for a given transaction. */ void USB_OS_Wait(unsigned EPIndex) { U32 Tmp; do { OS_GetMail(&_aMailBox[EPIndex], &Tmp); } while (Tmp != TransactCnt); } /********************************************************** * * USB_OS_WaitTimed * * Function description * Blocks the task until USB_OS_Signal() is called for a given transaction or a timeout * occurs. */ int USB_OS_WaitTimed(unsigned EPIndex, unsigned ms) { U32 Tmp; int r; do { r = (int)OS_GetMailTimed(&_aMailBox[EPIndex], &Tmp, ms); } while (r == 0 && Tmp != TransactCnt); return r; } /********************************************************** * * USB_OS_Delay * * Function description * Delays for a given number of ms. */ void USB_OS_Delay(int ms) { OS_Delay(ms); } /********************************************************** * * USB_OS_DecRI * * Function description * Leave a critical region for the USB stack: Decrements interrupt disable count and * enable interrupts if counter reaches 0. */ void USB_OS_DecRI(void) { OS_DecRI(); } /********************************************************** * * USB_OS_IncDI emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 484 CHAPTER 17 Example * * Function description * Enter a critical reagion for the USB stack: Increments interrupt disable count and * disables interrupts. */ void USB_OS_IncDI(void) { OS_IncDI(); } /********************************************************** * * USB_OS_Panic * * Function description * Halts emUSB-Device. Called if a fatal error is detected. */ void USB_OS_Panic(const char *pErrMsg) { while (pErrMsg); } /********************************************************** * * USB_OS_GetTickCnt * * Function description * Returns the current system time in milliseconds or system ticks. */ U32 USB_OS_GetTickCnt(void) { return OS_Time; } /*************************** End of file ****************************/ emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 18 Target USB Driver This chapter describes emUSB-Device hardware interface functions in detail. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 486 CHAPTER 18 18.1 General information General information Purpose of the USB hardware interface emUSB-Device does not contain any hardware dependencies. These are encapsulated through a hardware abstraction layer, which consists of the interface functions described in this chapter. All of these functions for a particular USB controller are typically located in a single file, the USB driver. Drivers for hardware which have already been tested with emUSB-Device are available. Range of supported USB hardware The interface has been designed in such a way that it should be possible to use the most common USB device controllers. This includes USB 1.1 controllers and USB 2.0 controllers, both as external chips and as part of microcontrollers. 18.1.1 Available USB drivers An always up to date list can be found at: https://www.segger.com/emusb-drivers.html emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 487 CHAPTER 18 18.2 Adding a driver to emUSB-Device Adding a driver to emUSB-Device USBD_Init() initializes the internals of the USB stack and is always the first function which the USB application has to call. USBD_Init() will then call USBD_X_Config(). This function should be used to perform the following tasks: * * * * Perform device specific hardware initialisation if neccessary. Add a USB driver to your project. Optionally install a HWAttach function. Install interrupt management functions. You have to specify the USB device driver which should be used with emUSB-Device. For this, USBD_AddDriver() should be called in USBD_X_Config() with the identifier of the driver which is compatible to your hardware as parameter. Refer to the header file USB.h for a list of all supported devices and their valid identifiers. The _HWAttach() function should be used to perform hardware-specific actions which are not part of the USB controller logic (for example, enabling the peripheral clock for USB port). This function is called from every device driver, but may not be present if your hardware does not need to perform such actions. A _HWAttach() function may be registered to the stack by calling USBD_SetAttachFunc() within USBD_X_Config(). Additionally interrupt management functions must be installed using the function USBD_SetISRMgmFunc(). Modify USBD_X_Config(), _EnableISR() and if required, _HWAttach(). 18.2.1 USBD_X_Config() Description Configure the USB stack. Prototype void USBD_X_Config(void) Additional information This function is always called from USBD_Init(). Example /* Example excerpt from USB_Config_SAM7A3.c */ #define PID_USB (27) // USB Identifier #define _AT91C_PIOA_BASE (0xFFFFF400) #define _AT91C_PIOB_BASE (0xFFFFF600) #define _AT91C_PMC_BASE (0xFFFFFC00) #define _PIO_PER_OFFS (0x00) #define _PIO_OER_OFFS (0x10) #define _PIO_CODR_OFFS (0x34) /* Clear output data register #define _PMC (*(volatile unsigned int*) _AT91C_PMC_BASE) #define _USB_ID (_PIOB_ID) #define _USB_OER (*(volatile unsigned int*) (_AT91C_PIOB_BASE + _PIO_OER_OFFS)) #define _USB_CODR (*(volatile unsigned int*) (_AT91C_PIOB_BASE + _PIO_CODR_OFFS)) #define _USB_DP_PUP_BIT (1) static void _PMC _USB_OER _USB_CODR } _HWAttach(void) { = (1 << _USB_ID); = (1 << _USB_DP_PUP_BIT); = (1 << _USB_DP_PUP_BIT); */ /* Enable peripheral clock for USB-Port */ /* set USB_DP_PUP to output */ /* set _USB_DP_PUP_BIT to low state */ static void _EnableISR(USB_ISR_HANDLER * pfISRHandler) { emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 488 CHAPTER 18 Adding a driver to emUSB-Device *(U32*)(0xFFFFF080 + 4 * PID_USB) = (U32)pfISRHandler; // Set interrupt vector *(U32*)(0xFFFFF128) = (1 << PID_USB); // Clear pending interrupt *(U32*)(0xFFFFF120) = (1 << PID_USB); // Enable Interrupt } void USBD_X_Config(void) { USBD_AddDriver(&USB_Driver_AtmelSAM7A3); USBD_SetAttachFunc(_HWAttach); USBD_SetISRMgmFuncs(_EnableISR, NULL, NULL); } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 19 Support emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 490 CHAPTER 19 19.1 Contacting support Contacting support Before contacting support please make sure that you are using the latest version of the emUSB-Device package. Also please check the chapter Configuring debugging output on page 37 and run your application with enabled debug support. If you are a registered emUSB-Device user and you need to contact the emUSB-Device support please send the following information via email to support_emusb@segger.com: * * * * * Your emUSB-Device registration number. emUSB-Device version. A detailed description of the problem The configuration files USB_Conf*.* Any error messages. Please also take a few moments to help us to improve our service by providing a short feedback when your support case has been solved. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 20 Profiling with SystemView This chapter describes how to configure and enable profiling of emUSB-Device using SystemView. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 492 CHAPTER 20 20.1 Profiling overview Profiling overview emUSB-Device is instrumented to generate profiling information of API functions and driver-level functions. These profiling information expose the run-time behavior of emUSB-Device in an application, recording which API functions have been called, how long the execution took, and revealing which driver-level functions have been called by API functions or events like interrupts. The profiling information is recorded using SystemView. SystemView is a real-time recording and visualization tool for profiling data. It exposes the true run-time behavior of a system, going far deeper than the insight provided by debuggers. This is particularly effective when developing and working with complex systems comprising an OS with multiple threads and interrupts, and one or more middleware components. SystemView can ensure a system performs as designed, can track down inefficiencies, and show unintended interactions and resource conflicts. The recording of profiling information with SystemView is minimally intrusive to the system and can be done on virtually any system. With SEGGER's Real Time Technology (RTT) and a J-Link, SystemView can record data in real-time and analyze the data live, while the system is running. The emUSB-Device profiling instrumentation can be easily configured and set up. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 493 CHAPTER 20 20.2 Additional files for profiling Additional files for profiling Additional files are required on target and PC side for full functionality of SystemView. 20.2.1 Additional files on target side The SystemView module needs to be added to the application to enable profiling. If not already part of the project, download the sources from https://www.segger.com/systemview.html and add them to the project. Also make sure that USB_SYSVIEW.c from the /USB/ directory is included in the project. 20.2.2 Additional files on PC side For fully functional and readable outputs in the SystemView PC application, a description file for the corresponding middleware is required. This description file extends the values sent from the target to fully readable text outputs. While SystemView already comes with the most recent description files at the time the SystemView release has been built, these files might not be the latest available. The latest SystemView description files can be found in the emUSB-Device shipment in the folder /Shared/SystemView/Description/. You can copy these files over to the Description folder that comes with the SystemView package. The version at the end of the SystemView description file does not have to match the exact version of the middleware it is used with. They are valid from this version onwards until a description file for a newer version is required. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 494 CHAPTER 20 20.3 Enable profiling Enable profiling Profiling can be included or excluded at compile-time and enabled at run-time. When profiling is excluded, no additional overhead in performance or memory usage is generated. Even when profiling is enabled the overhead is minimal, due to the efficient implementation of SystemView. To include profiling, define USBD_SUPPORT_PROFILE as 1 in the emUSB-Device configuration (USB_Conf.h) or in the project preprocessor defines. Per default profiling is included when the global define SUPPORT_PROFILE is set. #if defined(SUPPORT_PROFILE) && (SUPPORT_PROFILE) #ifndef USBD_SUPPORT_PROFILE #define USBD_SUPPORT_PROFILE 1 #endif #endif To enable profiling at run-time, USBD_SYSVIEW_Init() needs to be called. Profiling can be enabled at any time, it is recommended to do this in the user-provided configuration USBD_X_Config(): /********************************************************************* * * USBD_X_Config * */ void USBD_X_Config(void) { ... #if USBD_SUPPORT_PROFILE USBD_SYSVIEW_Init(); #endif ... emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 495 CHAPTER 20 20.4 Recording and analyzing profiling information Recording and analyzing profiling information When profiling is included and enabled emUSB-Device generates profiling events. On a system which supports RTT (i.e. ARM Cortex-M and Renesas RX) the data can be read and analyzed with SystemView and a J-Link. Connect the J-Link to the target system using the default debug interface and start the SystemView host application. If the system does not support RTT, SystemView can be configured for single-shot or postmortem mode. Please refer to the SystemView User Manual for more information. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 21 Debugging emUSB-Device comes with various debugging options. These includes optional warning and log outputs, as well as other run-time options which perform checks at run time as well as options to drop incoming or outgoing packets to test stability of the implementation on the target system. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 497 CHAPTER 21 21.1 Message output Message output The debug builds of emUSB-Device include a fine grained debug system which helps to analyze the correct implementation of the stack in your application. All modules of the USB stack can output logging and warning messages via terminal I/O, if the specific message type identifier is added to the log and/or warn filter mask. This approach provides the opportunity to get and interpret only the logging and warning messages which are relevant for the part of the stack that you want to debug. By default, all of the warning messages and none of the logging messages are activated. All activated messages are forwarded to the functions USB_X_Log() and USB_X_Warn(). These functions are located in the source file USB_ConfigIO.c and may be customized or replaced if necessary. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 498 CHAPTER 21 21.2 API functions API functions Function Description Filter functions USBD_AddLogFilter() Adds one or more message types to the logging filter. USBD_AddWarnFilter() Adds one or more message types to the warning filter. USBD_SetLogFilter() Sets the message type(s) for the logging filter. USBD_SetWarnFilter() Sets the message type(s) for the warning filter. General debug functions/macros USB_PANIC Called if the stack encounters a critical situation. General helper prototypes USB_X_Log() This function is called by the stack in debug builds with log output. USB_X_Warn() This function is called by the stack in debug builds with log output. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 499 CHAPTER 21 21.2.1 API functions USBD_AddLogFilter() Description Adds one or more message types to the logging filter. Prototype void USBD_AddLogFilter(U32 FilterMask); Parameters Parameter FilterMask Description Specifies which logging messages should be added to the filter mask. Refer to Message types on page 506 for a list of valid values for parameter FilterMask. Additional information USBD_AddLogFilter() can also be used to remove a filter condition which was set before. It adds the specified filter to the filter mask via a disjunction. Example void Application (void) { USBD_AddLogFilter(USB_MTYPE_DRIVER); // Activate driver logging messages USBD_Init(); /* * Do something */ } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 500 CHAPTER 21 21.2.2 API functions USBD_AddWarnFilter() Description Adds one or more message types to the warning filter. Prototype void USBD_AddWarnFilter(U32 FilterMask); Parameters Parameter FilterMask Description Specifies which warning messages should be added to the filter mask. Refer to Message types on page 506 for a list of valid values for parameter FilterMask. Additional information USBD_AddWarnFilter() can also be used to remove a filter condition which was set before. It adds the specified filter to the filter mask via a disjunction. Example void Application (void) { USBD_AddWarnFilter(USB_MTYPE_DRIVER); // Activate driver warning messages USBD_Init(); /* * Do something */ } emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 501 CHAPTER 21 21.2.3 API functions USBD_SetLogFilter() Description Sets the message type(s) for the logging filter. Prototype void USBD_SetLogFilter(U32 FilterMask); Parameters Parameter FilterMask Description Specifies which logging messages should be set to the filter mask. Refer to Message types on page 506 for a list of valid values for parameter FilterMask. Additional information This function can be called before USBD_Init(). By default, none of filter conditions are set. The sample application contain a simple implementation which can be easily modified. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 502 CHAPTER 21 21.2.4 API functions USBD_SetWarnFilter() Description Sets the message type(s) for the warning filter. Prototype void USBD_SetWarnFilter(U32 FilterMask); Parameters Parameter FilterMask Description Specifies which warning messages should be set to the filter mask. Refer to Message types on page 506 for a list of valid values for parameter FilterMask. Additional information This function can be called before USBD_Init(). By default, none of filter conditions are set. The sample application contain a simple implementation which can be easily modified. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 503 CHAPTER 21 21.2.5 API functions USB_PANIC Description This macro is called by the stack code when it detects a situation that should not be occurring and the stack can not continue. The intention for the USB_PANIC() macro is to invoke whatever debugger may be in use by the programmer. In this way, it acts like an embedded breakpoint. Prototype USB_PANIC (const char * sError); Additional information This macro maps to a function in debug builds only. If USB_DEBUG > 0, the macro maps to the stack internal function void USB_OS_Panic ( const char * sError ). USB_OS_Panic() disables all interrupts to avoid further task switches, outputs sError via terminal I/O and loops forever. When using an emulator, you should set a breakpoint at the beginning of this routine or simply stop the program after a failure. The error message is passed to the function as parameter. In a release build, this macro is defined empty, so that no additional code will be included by the linker. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 504 CHAPTER 21 21.2.6 API functions USB_X_Log() Description This function is called by the stack in debug builds with log output. In a release build, this function is not be linked in. Prototype void USB_X_Log(const char * s); Parameters Parameter s Description Pointer to a string holding the log message. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 505 CHAPTER 21 21.2.7 API functions USB_X_Warn() Description This function is called by the stack in debug builds with log output. In a release build, this function is not be linked in. Prototype void USB_X_Warn(const char * s); Parameters Parameter s Description Pointer to a string holding the warning message. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 506 CHAPTER 21 21.3 Message types Message types Description The same message types are used for log and warning messages. Separate filters can be used for both log and warnings. For details, refer to USBD_SetLogFilter() and USBD_SetWarnFilter() as wells as USBD_AddLogFilter() and USBD_AddWarnFilter() for more information about using the message types. Definition #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define USB_MTYPE_INIT USB_MTYPE_CORE USB_MTYPE_CONFIG USB_MTYPE_DRIVER USB_MTYPE_ENUMERATION USB_MTYPE_CDC USB_MTYPE_HID USB_MTYPE_MSD USB_MTYPE_MSD_CDROM USB_MTYPE_MSD_PHY USB_MTYPE_MTP USB_MTYPE_PRINTER USB_MTYPE_RNDIS USB_MTYPE_SMART_MSD USB_MTYPE_UVC USB_MTYPE_ECM USB_MTYPE_AUDIO (1UL (1UL (1UL (1UL (1UL (1UL (1UL (1UL (1UL (1UL (1UL (1UL (1UL (1UL (1UL (1UL (1UL << << << << << << << << << << << << << << << << << 0) 1) 2) 3) 4) 7) 8) 9) 10) 11) 12) 13) 14) 16) 17) 18) 19) Symbols Definition Description USB_MTYPE_INIT Activates output of messages from the initialization of the stack that should be logged. USB_MTYPE_CORE Activates output of messages from the core of the stack that should be logged. USB_MTYPE_CONFIG Activates output of messages from the configuration of the stack. USB_MTYPE_DRIVER Activates output of messages from the driver that should be logged. USB_MTYPE_ENUMERATION Activates output of messages from enumeration that should be logged. Note: Since enumeration is handled in an ISR, use this with care as the timing will be changed greatly. USB_MTYPE_CDC Activates output of messages from CDC module that should be logged when a CDC connection is used. USB_MTYPE_HID Activates output of messages from HID module that should be logged when a HID connection is used. USB_MTYPE_MSD Activates output of messages from MSD module that should be logged when a MSD connection is used. USB_MTYPE_MSD_CDROM Activates output of messages from MSD CDROM module that should be logged. USB_MTYPE_MSD_PHY Activates output of messages from MSD Physical layer that should be logged. USB_MTYPE_MTP Activates output of messages from MTP module that should be logged when a MTP connection is used. USB_MTYPE_PRINTER Activates output of messages from Printer module that should be logged when Printer connection is used. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 507 CHAPTER 21 Definition Message types Description USB_MTYPE_RNDIS Activates output of messages from RNDIS module that should be logged when a RNIDS connection is used. USB_MTYPE_SMART_MSD Activates output of messages from Smart-MSD module that should be logged when a SmartMSD connection is used. USB_MTYPE_UVC Activates output of messages from UVC module that should be logged when a UVC connection is used. USB_MTYPE_ECM Activates output of messages from ECM module that should be logged when a ECM connection is used. USB_MTYPE_AUDIO Activates output of messages from Audio module that should be logged when an audio connection is used. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 22 Certification This chapter describes the process of USB driver certification with Microsoft Windows. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 509 CHAPTER 22 What is the Windows Hardware Certification and why do I need it? 22.1 What is the Windows Hardware Certification and why do I need it? The Windows Hardware Certification (formerly known as "Windows Logo Certification") process will sign a driver with a Microsoft certificate which signifies that the device is compatible and safe to use with Microsoft Windows operating systems. If the device is using a call which requires .inf files and if the driver is not signed the user will be confronted with messages saying that the driver is not signed and may not be safe to use with Microsoft Windows. Depending on which Windows version you are using a different message will be shown. Users of Windows Server 2008, Windows Vista x64, Windows 7 x64 an newer version of the respective distributions will be warned about the missing signature and the driver will show up as installed, but the driver will not be loaded. The user can override this security measure by hitting F8 on Windows start-up and selecting "Disable Driver Signature Enforcement" or editing the registry. Microsoft Windows Vista/7: 22.2 Certification offer Customers can complete the certification by themselves. But SEGGER also offers certification for our customers. To certify a device a customer needs a valid Vendor ID, registered at www.usb.org and a free Product ID. Using the Hardware Certification Kit a certification package is created. The package is sent to Microsoft for confirmation. After the confirmation is received from Microsoft the customer receives a .cat file which allows the drivers to be installed without problems. 22.3 Vendor and Product ID A detailed description of the Vendor and Product ID can be found in chapter Product / Vendor IDs on page 32. The customer can acquire a Vendor ID from the USB Implementers Forum, Inc. (www.usb.org). This allows to freely decide which Product ID is used for which product. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 510 CHAPTER 22 22.4 Certification without SEGGER Microcontroller Certification without SEGGER Microcontroller Certification can be completed by the customer themselves. The certification is a lengthy and complicated process. For further information, as well as the requirements see: https://msdn.microsoft.com/en-us/library/windows/hardware/jj124227.aspx emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 23 Performance & resource usage This chapter covers the performance and resource usage of emUSB-Device. It contains information about the memory requirements in typical systems which can be used to obtain sufficient estimates for most target systems. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 512 CHAPTER 23 23.1 Memory footprint Memory footprint emUSB-Device is designed to fit many kinds of embedded design requirements. Several features can be excluded from a build to get a minimal system. The code size depends on the API functions called by the application. The code was compiled for a Cortex-M4 CPU with size optimization. Note that the values are only valid for an average configuration. The following table shows the approximate RAM and ROM requirement of emUSB-Device in bytes: Component ROM RAM Note USB core 5800 900 Bulk 2000 100 CDC 1300 100 HID 1600 100 MSD 4800 300 + size of file system + configurable sector buffer of minimum 512 bytes (RAM) + size of file system + configurable file data buffer of minimum 512 bytes RAM) + configurable object buffer (typically 4 kBytes RAM) MTP 14600 1600 Printer 800 2100 RNDIS 5500 1400 + size of the IP stack ECM 2800 200 + size of the IP stack IP-Over-USB 7300 1600 + size of the IP stack SmartMSD 8300 800 + heap of minimum 1700 bytes RAM Driver Atmel SAM3U 2200 600 Driver Atmel SAM3X 2000 600 Driver Atmel SAM3S 2200 100 Driver Atmel SAM7S 2200 100 Driver Atmel SAM9X25 1900 500 Driver Atmel SAMA5D2x 1900 500 Driver Atmel SAMV7 2100 3200 Driver EM EFM32GG990 3100 700 Driver Freescale KHCI 2400 700 Driver Freescale KinetisEHCI 3100 2600 Driver Infineon XMC45xx 2900 400 Driver NXP LPC17xx 1600 100 Driver NXP LPC18xx 3200 4100 Driver NXP LPC23xx 1600 100 Driver NXP LPC43xx 3200 4100 Driver Renesas RZ 3300 7800 Driver Renesas RX 2800 700 Driver Renesas SynergyS1 2800 600 Driver Renesas SynergyFS 2800 700 Driver Renesas SynergyHS 3400 4700 emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 513 CHAPTER 23 Component ROM Memory footprint RAM Driver ST STM32x32 2000 300 Driver ST STM32F107 2900 400 Driver ST STM32F4xxFS 3000 400 Driver ST STM32F4xxHS 3300 3300 Driver ST STM32F7xxFS 3100 600 Driver ST STM32F7xxHS 3200 4900 Driver ST STM32L4xx 2900 600 Driver ST STR91x 1400 0 Driver TI AM335x 1300 7700 Driver TI OMAP L138 1300 2100 Note Additionally 64 or 512 bytes of RAM (64 for Full Speed and 512 for High Speed devices) are necessary for each OUT-endpoint as a data buffer. This buffer is assigned within the application. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 514 CHAPTER 23 23.2 Performance Performance The tests were run on a LPC4357 CPU running at 180 MHz using the USB Bulk and the USB MSD component connected to a Linux host. The following table shows the transfer speed of emUSB-Device: Description Speed USB High-Speed controller (device to host) 44.1 MB/s USB High-Speed controller (host to device) 41.8 MB/s USB Full-Speed controller 1200 kB/s emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Chapter 24 FAQ This chapter answers some frequently asked questions. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH 516 CHAPTER 24 Q: Which CPUs can I use emUSB-Device with? A: It can be used with any CPU (or MPU) for which a C compiler exists. Of course, it will work faster on 16/32-bit CPUs than on 8-bit CPUs. Q: When designing my hardware can I just permanently connect the D+ 1.5 kOhm pull-up resistor to 3.3V to save a MCU pin? A: No, the pull-up being connected tells the USB host that the device is ready to communicate. Permanently connecting the pull-up is dangerous as the host may start to communicate with the device prematurely, before it has finished with the start-up. Furthermore, when using USB high-speed the device must disconnect the pull-up from D+ according to the USB 2.0 specification. Any currently know USB high speed controller (with internal or external USB Highspeed PHY) have internal logic to enable an internal pull-up initially. So for those controller an external pull-up is not necessary. Q: When using MSD can I read/write onto the storage medium when the device is connected to a USB host? A: No, when a MSC device is connected to a USB host the host is the sole master of the storage medium. It can write or read at any point in time. Should the application try to access the storage medium at the same time as the host the results are unpredictable. To resolve this issue the device needs to detach the storage medium from the host, see USBD_MSD_RequestDisconnect(), USBD_MSD_Disconnect() and USBD_MSD_WaitForDisconnection(). Q: Can I combine different USB components together? A: Yes. See Combining USB components (Multi-Interface) on page 451. Q: Do I need a real-time operating system (RTOS) to use the emUSB-Device-MSD? A: No, if your target application is a pure storage application. You do not need an RTOS if all you want to do is running emUSB-Device-MSD as the only task on the target device. If your target application is more than just a storage device and needs to perform other tasks simultaneously, you need an RTOS which handles the multi-tasking. We recommend using our embOS Real-time OS, since all example and trial projects are based on it. Q: Do I need extra file system code to use the emUSB-Device-MSD? A: No, if you access the target data only from the host. Yes, if you want to access the target data from within the target itself. There is no extra file system code needed if you only want to access the data on the target from the host side. The host OS already provides several file systems. You have to provide file system program code on the target only if you want to access the data from within the target application itself. emUSB-Device User Guide & Reference Manual (c) 2010-2018 SEGGER Microcontroller GmbH Mouser Electronics Authorized Distributor Click to View Pricing, Inventory, Delivery & Lifecycle Information: Segger Microcontroller: 9.50.04 9.50.02