Embedded USB Host Stack - Thesycon Systemsoftware ...

Embedded USB Host Stack
for Embedded Devices
Reference Manual
Version: 2.10.0
Date: 09 December 2011
Authors: Steffen Weiss
Guenter Hildebrandt
Thesycon Systemsoftware & Consulting GmbH
Werner-von-Siemens-Str. 2
D-98693 Ilmenau
Germany
Tel: +49 3677 8462 0
Fax: +49 3677 8462 18
http://www.thesycon.de
® Thesycon Systemsoftware&ConsultingGmbH

Copyright (c) 2011 by Thesycon Systemsoftware & Consulting GmbH
All Rights Reserved
Disclaimer
The information in this document is subject to change without notice. No part of this manual
may be reproduced, stored in a retrieval system, or transmitted in any form or by any means
electronic or mechanical, including photocopying and recording for any purpose other than the
purchaser’s personal use, without prior written permission from Thesycon Systemsoftware & Consulting
GmbH. The software described in this document is furnished under the software license
agreement distributed with the product. The software may be used or copied only in accordance
with the terms of the license.
Trademarks
The following trade names are referenced within this manual:
Microsoft, Windows, Win32, Windows NT, Windows XP, and Visual C++ are either trademarks
or registered trademarks of Microsoft Corporation.
Other brand and product names are trademarks or registered trademarks of their respective holders.
USB Bus Driver Reference Manual 3

Contents
Contents
Table of contents 14
1 Introduction 17
2 Overview 18
2.1 Features of the Embedded USB Host Stack . . . . . . . . . . . . . . . . . . . . 18
2.2 Features of the USB Bus Driver . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3 Supported Host Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.4 Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3 Architecture 20
3.1 Register Abstraction Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.2 Thesycon Abstraction Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.3 USB Bus Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.3.1 USB Bus Driver Core . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.3.2 USB Host Controller Driver . . . . . . . . . . . . . . . . . . . . . . . . 24
3.4 USB Class Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4 Configuration 25
4.1 Compile Time Configuration - USB Bus Driver . . . . . . . . . . . . . . . . . . 25
5 Usage 26
5.1 Initial Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.2 Debug Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.2.1 Trace Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.2.2 Assert Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.2.3 Configuration of Traces . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.3 Memory Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.4 Enumeration of USB devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.5 USB Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.6 Additional Device Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.7 Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.8 Closing the Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.9 External Hub Support1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.10 Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
USB Bus Driver Reference Manual 5

Contents
5.11 Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6 Management Reference 33
6.1 USB Bus Driver Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
USBH_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
USBH_Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
USBH_ServiceISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
USBH_ProcessInterrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
USBH_RemoveHostController . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
USBH_EnumerateDevices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7 Host Controller Creation Reference 39
7.1 Open Host Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
USBH_CreateOhcController . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
USBH_CreateEhcController . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
8 USB Bus Driver Reference 41
8.1 Application programming interface . . . . . . . . . . . . . . . . . . . . . . . . . 41
USBH_CreateInterfaceList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
USBH_DestroyInterfaceList . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
USBH_GetInterfaceID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
USBH_GetInterfaceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
USBH_WaitForIdleStack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
USBH_PnpNotification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
USBH_RegisterPnPNotification . . . . . . . . . . . . . . . . . . . . . . . . . . 47
USBH_UnregisterPnPNotification . . . . . . . . . . . . . . . . . . . . . . . . . 48
USBH_EnumErrorNotification . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
USBH_RegisterEnumErrorNotification . . . . . . . . . . . . . . . . . . . . . . 50
USBH_UnregisterEnumErrorNotification . . . . . . . . . . . . . . . . . . . . . 51
USBH_RestartEnumError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
USBH_OpenInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
USBH_CloseInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
USBH_GetDeviceDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
USBH_GetCurrentConfigurationDescriptor . . . . . . . . . . . . . . . . . . . . 56
USBH_GetInterfaceDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
USBH_GetClassDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
6 USB Bus Driver Reference Manual

Contents
USBH_GetEndpointDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
USBH_GetSerialNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
USBH_GetSpeed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
USBH_GetFrameNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
USBH_GetInterfaceIDByHandle . . . . . . . . . . . . . . . . . . . . . . . . . . 68
USBH_GetHubPortHandlebyInterface . . . . . . . . . . . . . . . . . . . . . . . 69
USBH_GetHubPortHandlebyTopology . . . . . . . . . . . . . . . . . . . . . . . 70
USBH_SetPortPowerState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
USBH_GetPortPowerState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
URB_COMPLETION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
USBH_SubmitUrb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
USBH_GetStatusStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
USBH_AbortEndpointAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . 76
USBH_SubmitUrbAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
USBH_ResetEndpointAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
USBH_ResetDeviceAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
USBH_SetConfigurationAndWait . . . . . . . . . . . . . . . . . . . . . . . . . 84
USBH_SetInterfaceAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
USBH_SetupRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
8.2 Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
USBH_INTERFACE_MASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
USBH_INTERFACE_INFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
USBH_ENUM_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
USBH_EP_MASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
URB_CONTROL_REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
URB_BULK_INT_REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
URB_ISO_FRAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
URB_ISO_REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
URB_ENDPOINT_REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
URB_SET_CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . . 105
URB_SET_INTERFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
URB_SET_SUSPEND_STATE . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
URB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
USBH_PNP_NOTIFICATION . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
URB_HEADER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
USB Bus Driver Reference Manual 7

Contents
USBH_SPEED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
USBH_PNP_EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
USBH_POWER_STATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
URB_FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
USBH_SUSPEND_STATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
8.3 Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
8.4 Status Codes Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
USBH_STATUS_SUCCESS (0x0000L) . . . . . . . . . . . . . . . . . . . . 121
USBH_STATUS_CRC (0x0001L) . . . . . . . . . . . . . . . . . . . . . . . 121
USBH_STATUS_BITSTUFFING (0x0002L) . . . . . . . . . . . . . . . . . 121
USBH_STATUS_DATATOGGLE (0x0003L) . . . . . . . . . . . . . . . . . 121
USBH_STATUS_STALL (0x0004L) . . . . . . . . . . . . . . . . . . . . . . 121
USBH_STATUS_NOTRESPONDING (0x0005L) . . . . . . . . . . . . . . . 121
USBH_STATUS_PID_CHECK (0x0006L) . . . . . . . . . . . . . . . . . . . 121
USBH_STATUS_UNEXPECTED_PID (0x0007L) . . . . . . . . . . . . . . 121
USBH_STATUS_DATA_OVERRUN (0x0008L) . . . . . . . . . . . . . . . . 121
USBH_STATUS_DATA_UNDERRUN (0x0009L) . . . . . . . . . . . . . . . 122
USBH_STATUS_BUFFER_OVERRUN (0x000CL) . . . . . . . . . . . . . . 122
USBH_STATUS_BUFFER_UNDERRUN (0x000DL) . . . . . . . . . . . . . 122
USBH_STATUS_NOT_ACCESSED (0x000FL) . . . . . . . . . . . . . . . . 122
USBH_STATUS_ERROR (0x0101L) . . . . . . . . . . . . . . . . . . . . . . 122
USBH_STATUS_BUFFER_OVERFLOW (0x0102L) . . . . . . . . . . . . . 122
USBH_STATUS_INVALID_PARAM (0x0103L) . . . . . . . . . . . . . . . 122
USBH_STATUS_PENDING (0x0104L) . . . . . . . . . . . . . . . . . . . . 122
USBH_STATUS_DEVICE_REMOVED (0x0105L) . . . . . . . . . . . . . . 123
USBH_STATUS_CANCELED (0x0106L) . . . . . . . . . . . . . . . . . . . 123
USBH_STATUS_BUSY (0x0109L) . . . . . . . . . . . . . . . . . . . . . . 123
USBH_STATUS_INVALID_DESCRIPTOR (0x0110L) . . . . . . . . . . . . 123
USBH_STATUS_ENDPOINT_HALTED (0x0111L) . . . . . . . . . . . . . 123
USBH_STATUS_TIMEOUT (0x0112L) . . . . . . . . . . . . . . . . . . . . 123
USBH_STATUS_PORT (0x0113L) . . . . . . . . . . . . . . . . . . . . . . . 123
USBH_POWER_SWITCHING_NOT_SUPPORTED (0x0114L) . . . . . . . 123
USBH_STATUS_INVALID_ALIGNMENT (0x0115L) . . . . . . . . . . . . 124
USBH_STATUS_NO_MEMORY (0x0116L) . . . . . . . . . . . . . . . . . 124
USBH_STATUS_NO_RESOURCES (0x0117L) . . . . . . . . . . . . . . . . 124
8 USB Bus Driver Reference Manual

Contents
USBH_STATUS_USER (0x8000L) . . . . . . . . . . . . . . . . . . . . . . . 124
9 Register Access Abstraction Layer 125
9.1 Open Host Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
HcohcWriteReg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
HcohcReadReg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
10 Abstraction Layer Reference 127
10.1 API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.3 Initialization and Deinitialization . . . . . . . . . . . . . . . . . . . . . . . . . . 128
TAL_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
TAL_Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
10.4 Dynamically Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . 130
TAL_Malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
TAL_Free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
10.5 Descriptor Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
TAL_AllocateDmaDescMemory . . . . . . . . . . . . . . . . . . . . . . . . . . 132
TAL_FreeDmaDescMemory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
10.6 DMA Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
TAL_GetCacheLineSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
TAL_AllocateDmaMemory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
TAL_FreeDmaMemory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
TAL_InvalidateCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
TAL_FlushCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
TAL_WriteSync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
TAL_BuildDmaMd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
10.7 Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
TAL_TimerCallbackRoutine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
TAL_AllocTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
TAL_FreeTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
TAL_StartTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
TAL_CancelTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
TAL_GetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
TAL_Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
10.8 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
USB Bus Driver Reference Manual 9

Contents
TAL_AllocEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
TAL_FreeEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
TAL_SetEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
TAL_ResetEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
TAL_WaitEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
10.9 Mutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
TAL_AllocMutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
TAL_FreeMutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
TAL_EnterMutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
TAL_LeaveMutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
10.10Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
TAL_CreateTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
TAL_DeleteTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
TAL_WaitTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
10.11Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
TAL_MD_HEADER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
TAL_MD_PAGE_ENTRY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
TAL_MD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
TAL_TIMER_HANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
11 CDC/ACM Class Driver Reference 164
11.1 Application programming interface . . . . . . . . . . . . . . . . . . . . . . . . . 164
HCLS_ACM_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
HCLS_ACM_Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
HCLS_ACM_DeviceConnected . . . . . . . . . . . . . . . . . . . . . . . . . . 166
HCLS_ACM_RegisterConnectHandler . . . . . . . . . . . . . . . . . . . . . . . 167
HCLS_ACM_CreateInterfaceList . . . . . . . . . . . . . . . . . . . . . . . . . 168
HCLS_ACM_DestroyInterfaceList . . . . . . . . . . . . . . . . . . . . . . . . . 169
HCLS_ACM_GetInterfaceID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
HCLS_ACM_GetInterfaceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
HCLS_ACM_DeviceRemoved . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
HCLS_ACM_Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
HCLS_ACM_Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
HCLS_ACM_IsDevicePresent . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
HCLS_ACM_GetDeviceStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
10 USB Bus Driver Reference Manual

Contents
HCLS_ACM_DeviceStatusChanged . . . . . . . . . . . . . . . . . . . . . . . . 179
HCLS_ACM_RegisterStatusChangeHandler . . . . . . . . . . . . . . . . . . . . 180
HCLS_ACM_SetLineCoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
HCLS_ACM_SetControlLineState . . . . . . . . . . . . . . . . . . . . . . . . . 182
HCLS_ACM_SendBreak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
HCLS_ACM_GetWriteFifoSize . . . . . . . . . . . . . . . . . . . . . . . . . . 184
HCLS_ACM_Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
HCLS_ACM_AbortWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
HCLS_ACM_ResetWritePipe . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
HCLS_ACM_GetReadFifoSize . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
HCLS_ACM_Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
HCLS_ACM_AbortRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
HCLS_ACM_ResetReadPipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
11.2 Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
HCLS_ACM_LineCoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
12 HID Class Driver Reference 196
12.1 Application programming interface . . . . . . . . . . . . . . . . . . . . . . . . . 196
HCLS_HID_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
HCLS_HID_Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
HCLS_HID_DeviceConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
HCLS_HID_RegisterConnectHandler . . . . . . . . . . . . . . . . . . . . . . . 199
HCLS_HID_CreateInterfaceList . . . . . . . . . . . . . . . . . . . . . . . . . . 200
HCLS_HID_DestroyInterfaceList . . . . . . . . . . . . . . . . . . . . . . . . . 201
HCLS_HID_GetInterfaceID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
HCLS_HID_GetInterfaceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
HCLS_HID_DeviceRemoved . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
HCLS_HID_Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
HCLS_HID_Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
HCLS_HID_IsDevicePresent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
HCLS_HID_GetHidDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
HCLS_HID_GetNumDescriptors . . . . . . . . . . . . . . . . . . . . . . . . . . 210
HCLS_HID_GetReportDescriptorSize . . . . . . . . . . . . . . . . . . . . . . . 211
HCLS_HID_GetReportDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . 212
HCLS_HID_GetReportRequest . . . . . . . . . . . . . . . . . . . . . . . . . . 214
USB Bus Driver Reference Manual 11

Contents
HCLS_HID_SetReportRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
HCLS_HID_GetProtocolRequest . . . . . . . . . . . . . . . . . . . . . . . . . . 218
HCLS_HID_SetProtocolRequest . . . . . . . . . . . . . . . . . . . . . . . . . . 219
HCLS_HID_GetIdleRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
HCLS_HID_SetIdleRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
HCLS_HID_GetWriteFifoSize . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
HCLS_HID_GetReadFifoSize . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
HCLS_HID_WriteReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
HCLS_HID_AbortWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
HCLS_HID_ResetWritePipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
HCLS_HID_ReadReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
HCLS_HID_AbortRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
HCLS_HID_ResetReadPipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
13 Printer Class Driver Reference 232
13.1 Application programming interface . . . . . . . . . . . . . . . . . . . . . . . . . 232
HCLS_PRN_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
HCLS_PRN_Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
HCLS_PRN_PrinterConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
HCLS_PRN_RegisterConnectHandler . . . . . . . . . . . . . . . . . . . . . . . 235
HCLS_PRN_CreateInterfaceList . . . . . . . . . . . . . . . . . . . . . . . . . . 236
HCLS_PRN_DestroyInterfaceList . . . . . . . . . . . . . . . . . . . . . . . . . 237
HCLS_PRN_GetInterfaceID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
HCLS_PRN_GetInterfaceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
HCLS_PRN_PrinterRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
HCLS_PRN_Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
HCLS_PRN_Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
HCLS_PRN_IsPrinterPresent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
HCLS_PRN_GetAvailableInterfaces . . . . . . . . . . . . . . . . . . . . . . . . 245
HCLS_PRN_GetCurrentInterface . . . . . . . . . . . . . . . . . . . . . . . . . 246
HCLS_PRN_SetInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
HCLS_PRN_GetDeviceId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
HCLS_PRN_GetPortStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
HCLS_PRN_SoftReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
HCLS_PRN_Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
12 USB Bus Driver Reference Manual

Contents
HCLS_PRN_WriteSync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
HCLS_PRN_AbortWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
HCLS_PRN_ResetWritePipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
HCLS_PRN_Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
HCLS_PRN_ReadSync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
HCLS_PRN_AbortRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
HCLS_PRN_ResetReadPipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
14 Mass Storage Class Driver Reference 263
14.1 Application programming interface . . . . . . . . . . . . . . . . . . . . . . . . . 263
HCLS_MS_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
HCLS_MS_Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
HCLS_MS_DeviceConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
HCLS_MS_RegisterConnectHandler . . . . . . . . . . . . . . . . . . . . . . . . 266
HCLS_MS_CreateInterfaceList . . . . . . . . . . . . . . . . . . . . . . . . . . 267
HCLS_MS_DestroyInterfaceList . . . . . . . . . . . . . . . . . . . . . . . . . . 268
HCLS_MS_GetInterfaceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
HCLS_MS_GetInterfaceID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
HCLS_MS_DeviceRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
HCLS_MS_Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
HCLS_MS_Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
HCLS_MS_GetLuns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
HCLS_MS_OpenLun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
HCLS_MS_CloseLun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
HCLS_MS_InitLun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
HCLS_MS_ReadCapacity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
HCLS_MS_ModeSenseAllPages . . . . . . . . . . . . . . . . . . . . . . . . . . 280
HCLS_MS_ReadModeSenseRawPage . . . . . . . . . . . . . . . . . . . . . . . 282
HCLS_MS_IsMediumReady . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
HCLS_MS_ReadSectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
HCLS_MS_WriteSectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
14.2 Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
T_UNIT_INFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
14.3 Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
14.4 Status Codes Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
USB Bus Driver Reference Manual 13

Contents
HCLS_MS_STATUS_LENGTH (0x1000L) . . . . . . . . . . . . . . . . . . 291
HCLS_MS_STATUS_COMMAND_FAILED (0x1002L) . . . . . . . . . . . 291
HCLS_MS_STATUS_INTERFACE_PROTOCOL (0x1003L) . . . . . . . . . 291
HCLS_MS_STATUS_INTERFACE_SUB_CLASS (0x1004L) . . . . . . . . 291
HCLS_MS_STATUS_SENSE_REPEAT (0x1006L) . . . . . . . . . . . . . . 291
HCLS_MS_STATUS_WRITE_PROTECT (0x1007L) . . . . . . . . . . . . . 291
HCLS_MS_STATUS_NOT_READY (0x1008L) . . . . . . . . . . . . . . . . 291
Index 293
14 USB Bus Driver Reference Manual

References
[1] Universal Serial Bus Specification, Revision 2.0,
http://www.usb.org
[2] USB device class specifications (Audio, HID, Printer, etc.),
http://www.usb.org
References
USB Bus Driver Reference Manual 15

1 Introduction
1 Introduction
This document describes the USB Host Stack for embedded devices. The reader should be familiar
with the concepts of embedded operating systems, the programming language C and the USB
specification.
The document describes the architecture, the installation and the API of the Embedded USB Host
Stack. The document should be read by developers that integrates the driver stack into a project or
that implements an application that uses the API of the Embedded USB Host Stack.
The complete Embedded USB Host Stack consists of the USB Bus Driver, Host Controller Drivers
and Class Drivers. A Host Controller (HC) Driver implements the access to a specific hardware
controller and a Class Driver implements the USB protocol for a specific class. The Class Driver
has a separate section in this document that describes the usage, the integration and the configuration
of the module.
USB Bus Driver Reference Manual 17

2 Overview
2 Overview
2.1 Features of the Embedded USB Host Stack
The Embedded USB Host Stack is designed to cover a USB host controller in an embedded environment.
It consists of different modules which can be adjusted and combined to satisfy your
requirements. This modular concept can easily be enhanced by your own implementations or by
prepackaged components provided by Thesycon R○ Systemsoftware & Consulting GmbH.
The Embedded USB Host Stack provides the following features:
• Implemented in ANSI C
• Works in either endian mode
• Simple register abstraction layer
• Simple abstraction layer of the operating system (TAL)
• Can be used stand-alone or with an operating system, but it is recommended to use an
operating system, classes require an operating system
• Supporting of class drivers
• Asynchronously implemented driver stack core
• Asynchronous data transfer operations
2.2 Features of the USB Bus Driver
The USB Bus Driver consists of the USB Bus Driver Core and contains one or more USB Host
Controller Driver. The user interface to the USB Bus Driver is the USB Bus Driver API.
The USB Bus Driver provides the following features:
• Control, bulk and interrupt transfers
• Hot plug and hot removal detection
• Generation of plug and removal events
• Presentation of devices at USB interface level
• Enumeration of USB devices, at the end of the enumeration the device is configured
• USB operation speed detection
• Support of the root hub
• Support for external USB hub devices
• Support for devices with alternate settings
• Support for multi-interface devices
18 USB Bus Driver Reference Manual

• Support for multi-configuration devices
• Implementing of an extended error recovery during device enumeration
• Dynamical attachment/removal of a USB Host Controller Driver
2.3 Supported Host Controllers
2 Overview
Thesycon’s Embedded USB Host Stack currently supports the Enhanced Host Controller (EHC)
and the Open Host Controller (OHC). Both controllers are PCI bus DMA controllers. The stack
can be used on each embedded sytsem that has such a host controller integrated.
2.4 Supported Platforms
The following platforms are supported:
• EmBos from Segger GmbH
• Windows PC environment based on PCIdacc
The PC environment uses a special kernel driver that enables the access to the standard USB
controllers UHC, OHC and EHC. This platform is for testing of the stack and may be used to
develop class driver or applications as long as the hardware is not yet available. A new platform
can be added by implementing the TAL abstraction layer.
USB Bus Driver Reference Manual 19

3 Architecture
3 Architecture
Operating System or
Embedded Environment
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
T
A
L
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
L
a
y
e
r
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢
¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢
¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢
¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢
¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢
¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢
¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢
¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢¡¢
USB Class
Drivers
Embedded Applications
Vendor Specific
Device Driver
USB Bus Driver
USB Bus Driver Core
USB Host
Controller Driver
Hardware-specifc
Register Abstraction Layer
Hub Driver
Hardware-independent
USB Host
Controller Driver
Hardware-specifc
¡ ¡ ¡ ¡ £¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£
£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡ £¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£
£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£¡£
¡ ¡ ¡ ¡
USB Host
Controller
Hardware
Figure 1: Components of the Embedded USB Host Stack
The Embedded USB Host Stack consists of the following components:
USB Host
Controller
Hardware
• USB Host Controller Driver - This component is part of the USB Bus Driver and encapsulates
the host controller specific USB implementation. Refer to section 3.3 for more
information.
• USB Bus Driver Core - This component is part of the USB Bus Driver and provides the
generic USB Host functionality. This module also includes a USB hub driver for external
USB hub support. Refer to section 3.3 for more information.
• USB Class Drivers - This component is optional to the USB Bus Driver. It could be the
implementation of a defined USB class driver or represent a vendor specific device driver.
Refer to section 3.4 for more information about USB class drivers.
20 USB Bus Driver Reference Manual

3 Architecture
The following software layers are required for the integration of the Embedded USB Host Stack:
• Thesycon Abstraction Layer (TAL) - This component provides the abstraction to the operating
system or embedded environment. Refer to section 3.2 for more information.
• Register Abstraction Layer - This component provides the abstraction of the register access.
Refer to section 3.1 for more information.
Figure 2 shows the interfaces between the modules and the appropriate header files containing the
definition of the interfaces.
T
A
L
L
a
y
e
r
tal_api.h
Tal_xxx()
Application
USB Host Controller Driver
USB Host Controller
Application
hcls_printer_api.h
HCLS_PRN_xxx()
Printer
Device Driver
USB Bus Driver
USB Bus Driver Core
¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡
¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡
¡ ¡
¡ ¡ ¡ ¡ ¡ ¡ ¡
¡ ¡ ¡
¡ ¡ ¡ ¡ ¡ ¡
¡ ¡ ¡ ¡
¡ ¡ ¡ ¡ ¡
¡
¡
¡
¡
¡
¡
¡ ¡ ¡
¡
¡ ¡ ¡
¡
¡ ¡ ¡
¡ ¡ ¡
¡
¡
¡
¡
¡
¡ ¡ ¡
¡
¡
¡
¡
¡
¡ ¡ ¡
¡
¡
¡
¡
¡
¡ ¡ ¡
¡
¡
¡
¡
¡
¡ ¡ ¡
¡
¡
¡
¡
¡
¡ ¡
¡
¡
¡
¡
¡
¡
¡ ¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡ ¡ ¡ ¡
¡
¡
¡
¡ ¡ ¡ ¡
¡
¡
¡
¡ ¡ ¡ ¡
¡
¡
¡
¡ ¡ ¡ ¡
¡
¡
¡
¡ ¡ ¡ ¡
¡
¡
¡
¡ ¡ ¡ ¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡ ¡ ¡
¡
¡ ¡ ¡ ¡ ¡
¡
¡ ¡ ¡ ¡ ¡
¡
¡ ¡ ¡
Register Abstraction ¡ Layer
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡
3.1 Register Abstraction Layer
Application
hcls_ms_api.h
HCLS_MS_xxx()
Mass Storage
Device Driver
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
usb_hc.h
USBH_xxx()
USB Host Controller Driver
¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡ ¡
¡
¡ ¡
¡
¡ ¡
USB Host Controller
Figure 2: Architecture of the Embedded USB Host Stack
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
¡
usbh_api.h
usbh_status.h
UBBH_xxx()
usbh_manage.h
hcohc_reg_api.h
hcehc_reg_api.h
HcohcReadReg()
The Register Abstraction Layer provides the abstraction of the access to the registers of the HC. It
encapsulates the access to the registers of the host controller with the appropriate functions defined
USB Bus Driver Reference Manual 21

3 Architecture
in the register API. These functions are host controller specific and have to be implemented by the
application designer according to the used host controller and its environment.
The Register Abstraction Layer interface is defined in header files:
hcohc_reg_api.h
hcehc_reg_api.h
3.2 Thesycon Abstraction Layer
The Thesycon Abstraction Layer (TAL) provides the abstraction of the application environment.
Because the Embedded USB Host Stack has no dependencies from the C-runtime or from other
operating system specific functions in the Thesycon Abstraction Layer are required.
The TAL provides common functions for memory, timer and synchronization handling which are
defined in the file tal_api.h. These functions have to be implemented by the application designer
according to the used operating system or embedded environment. Furthermore the abstraction
layer provides definitions of basic data types in the file tbase_types.h. It is possible that
the application designer has to change these defines according to the deployed micro processor.
Refer to section 10 on page 127 for the API reference of the abstraction layer.
22 USB Bus Driver Reference Manual

3.3 USB Bus Driver
3 Architecture
The USB Bus Driver is the central part of the Embedded USB Host Stack. It consists of the USB
Bus Driver Core and at least one USB Host Controller Driver. There is exactly one instance of the
USB Bus Driver module. The USB Bus Driver can handle any number of USB Host Controller
Drivers. It is not important whether the USB Host Controller Drivers control hardware of the
same type or of different types nor if the host controllers support high or full speed. The USB
Host Controller Drivers can be dynamically attached and removed from the USB Bus Driver at
runtime.
The interface of the bus driver is declared in the files and . The
functions of the USB bus driver can be grouped in three parts:
• Connect and removal detection
• Device information
• Device communication
3.3.1 USB Bus Driver Core
The USB Bus Driver Core module contains the generic USB host functionality which is common
to all USB host controllers. It is responsible for the enumeration of connected devices and handles
all kinds of standard requests. The USB Bus Driver Core is independent from the USB Host
Controller Driver implementation and has no access to any host controller hardware.
Additionally there is a USB hub driver for the USB Bus Driver Core module available. This is
optional and only required if external USB hubs should be supported by the Embedded USB Host
Stack.
The USB Bus Driver Core detects the connection and removal of the device. It enumerates the
devices, assigns USB device address and maintain the USB devices and the related USB interfaces
in lists. It collects information about the device by requesting the related USB descriptors. It
enables the access to the descriptor information. It provides PnP event notifications for class
drivers and applications. The devices can be found by an application with the help of enumeration
functions or with PnP notifications. The enumeration function generates a list of available USB
interfaces that fulfill the requirements of a filter mask. The application can enumerate in this list
with an index. The relation between the index and the USB interfaces in a list are constant. It can
happen that a device that is still in the list is not longer connected to the bus. In this case the open
function will fail.
The bus driver assigns each device and each interface a unique ID when the device is enumerated.
If the device is removed and reconnected the device gets a new ID. This ID is the unique identification
of a connected USB device or a USB interface. The USB Interface can be opened with the
help of the ID. With the help of the device ID the application can detect which interfaces belong
to the same USB device.
A lot of information about the device can be requested synchronously. This includes the standard
descriptors and some additional values. The communication with the device is based on the data
structure URB (USB Request Block). All communication requests with an URB are handled
asynchronously. The submit function returns immediately and independent from the state of the
USB Bus Driver Reference Manual 23

3 Architecture
operation. It signals USBH_STATUS_PENDING to indicate the operation is in progress and the
callback function will inform the caller when the operation has been finished. In this case the
owner ship of the URB is passed to the USB bus driver and the structure must not modified or
freed by the application until the completion routine is called. In the case of a submission error
the completion routine is not called. The caller has to take care on the returned status value of the
submit function.
3.3.2 USB Host Controller Driver
The USB Host Controller Driver implements the access to a specific USB host controller. It
is responsible for initializations, register based access and interrupt handling of the chosen host
controller hardware. The USB Host Controller Driver has an interface to attach or remove it from
the USB Bus Driver Core. The USB Bus Driver Core can handle host controller of different types.
A host controller implementation may have restrictions. See the source code for details.
3.4 USB Class Drivers
USB Class Drivers can be attached on top of the USB Bus Driver API. They can represent generic
USB class drivers like printer, mass storage or HID. It is also possible to implement an own vendor
specific device driver on top of the USB Bus Driver API. The current implementation supports the
following classes:
• HUB class
• Human Interface Device Class (HID)
• Mass Storage Device Class
• Communication Device Class/Abstract Control Model (UART emulation)
• Printer Device Class
The class drivers use a synchronous API. This makes the application programming easier. But the
TAL layer must support wait functions. A more detailed description of each implemented class
can be found in the reference part of this documentation.
24 USB Bus Driver Reference Manual

4 Configuration
4 Configuration
The application designer has to customize some settings in order to use the USB Host Stack in an
own application. Every software module in the USB Host Stack contains a header file with default
configuration settings. It is typically named as _config.h. Please have a look to
these header files to get an overview of possible configuration options. Every configuration file
includes . can be used to overwrite the default settings.
The host controller drivers use some pre-allocated memory pools to avoid memory allocation in
the data transfer path. The dimension of these buffers has a strong influence to the memory usage
and the option to use a number of USB devices at the same time. E.g. for the USB OHC controller
these pools are configured with the following parameters:
#define HCOHC_DEVICE_MAX_USB_DEVICES 1
#define HCOHC_MAX_INTERRUPT_ENDPOINTS 0
#define HCOHC_MAX_BULK_ENDPOINTS 2
This is a minimal configuration that allows the usage of one memory stick. Please note that USB
hubs are also devices that need resources.
4.1 Compile Time Configuration - USB Bus Driver
The compile time configuration has to be customized to meet the requirements of the application
and to adjust the USB Bus Driver to the appropriate environment. The USB Bus Driver default
settings are in . Only in rare case these settings must be changed. If the
external hub support is not licensed the files and are not part
of the delivery.
USB Bus Driver Reference Manual 25

5 Usage
5 Usage
5.1 Initial Steps
The following initial steps have to be done before using the USB Bus Driver API. Some hints
are given for the usage of a USB class driver. To ensure proper behavior the return status of the
functions has to be checked. The included demo applications provide a good starting point for
implementing you own application.
1. Configure the USB Bus Driver to meet your requirements. You have to adjust the appropriate
settings for the USB Bus Driver in the file usbh_config.h. Each parameter from the
default configuration file can be copied to the usbh_config.h file and modified.
2. Basic data types are defined in the tbase_types.h. Depending on the compiler and
CPU type it may be required to change the settings. It is important that the size in the name
of the variable is correct. E.g. T_UINT32 variable must have a size of 32 bit.
3. The OS abstraction layer defined in tal_api.h must be implemented. This implementation
can be tested with the module usbh_tal_test.c and the function UsbhTalTest().
When this function does not return with T_BOOL the implementation of the TAL layer
should be checked.
4. Initialize the abstraction Layer TAL with a call to TAL_Init. Call the TAL test function
UsbhTalTest in the debug version and check the return value.
5. Initialize the USB Bus Driver Core by a call to USBH_Init.
6. Prepare the interrupt handling for the host controller.
7. Create a Host controller with USBH_CreateOhcController or
USBH_CreateEhcController and enable the interrupts for it.
8. Start the enumeration of the devices with USBH_EnumerateDevices.
9. Start further applications or class drivers if required. Register PnP notification handler or
poll the available devices periodically.
5.2 Debug Support
The library can be compiled as a release or a debug version. The debug version is compiled
when the define TB_DEBUG is set to 1, e.g. -DTB_DEBUG=1. The debug version has the same
properties as the release version with the following enhancements:
• The code can generate text messages (traces) on a terminal.
• The code performs additional checks and parameter validation.
• The code activates asserts that check assumptions about parameters.
The debug version has a larger memory foot print and runs slightly slower than the release version.
But it is strongly recommended to use the debug version during the integration phase. The traces
of the stack are the base for qualified support from Thesycon.
26 USB Bus Driver Reference Manual

5.2.1 Trace Support
5 Usage
The possibilities to communicate text messages to a terminal may be different on each system.
For that reason the trace module must be implemented in the platform. The trace system uses the
following functions and macros:
void TbTrace(const char* format, ...);
void TbDumpBytesEx(const void* ptr, size_t byteCount, size_t bytesPerLine);
TbAssertionFailed(condition)
The high level functions TbDumpBytesEx and the macro TbAssertionFailed uses the
TbTrace function. Each of these functions has a default implementation in the files
tbase_func_TbAssertionFailed.inc
tbase_func_TbDumpBytesEx.inc
tbase_func_TbTrace.inc
When these include files are added to the project the default implementation is active.
When the runtime environment of the system provides a vprintf() function, it is easy to implement
the TbTrace similar to the implementation in tbase_func_TbTrace.inc. In this
case it must be checked that the system provided vprintf() function can handle all formatter
as described in tbase_trace.h.
If this function is not available the vprintf function from tbase_func_TbTraceVPrintf.inc
can be used. This module uses the TbTraceOutputChar function to send a single character to
a terminal port. This function can be used to put the character to a COM port or any other trace
interface.
5.2.2 Assert Support
The interface of the USB driver API is designed as trusted interface. That means that the host
driver drust the calling application. It expects that handles are valid and parameters are in the
correct range. This is a design decision to make the software effective.
In the debug version of the driver stack the handles and some other parameters are checked with
the TB_ASSERT macro. It is recommended to use the implemented assert structure during the
integration to detect possible problems in the usage of the USB host API. Our default implementation
runs into an endless loop. This enables an easy debugging because the call stack and all
local variables can be investigated in a debugger. In the release version the TB_ASSERT macros
are defined void.
5.2.3 Configuration of Traces
The traces of the driver stack are groupped into categories. Each category uses a special macro
that is either implemented or void. The macros can be configured by defines.
The file trace_config.h contains the defines that enables or disables all trace groups. By
default the trace macros
TB_TRACE_ERR,
USB Bus Driver Reference Manual 27

5 Usage
TB_TRACE_WRN and
TB_TRACE_INF
are enabled. To investigate special problems more macros can be enabled.
28 USB Bus Driver Reference Manual

5.3 Memory Abstraction
5 Usage
The CPU that executes the driver stack may support different features for the memory access. This
can be
• A MMU with virtual to physical address translation
• Memory cache for performance optimization
• Memory regions that can be accessed by the host controller
• Cache lines with a given size that are updated in one step
While the CPU accesses the virtual addresses with all the caching mechanism the host controller
uses a direct access to the memory with physical addresses.
The TAL layer provides with the functions TAL_AllocateDmaMemory and
TAL_AllocateDmaDescMemory an abstraction for the memory access.
The function TAL_AllocateDmaDescMemory allocates memory with the following properties:
• The CPU does not use any cache for this memory. Each read and write access is immediately
executed on the physical memory. The sequence of the memory write accesses is not
changed by the compiler or CPU.
• The memory is in a memory range that can be accessed efficient by the host controller. This
memory is frequently accessed by the host controller.
• The CPU can use address translation for this memory.
This kind of memory is used to allocate DMA descriptor memory for the host controller.
The function TAL_AllocateDmaMemory allocates memory with the following properties:
• The CPU can use cache to access the memory.
• The stack uses the functions TAL_InvalidateCache and TAL_FlushCache to update
the CPU memory cache.
• The memory is aligned to a cache line size and it has always a size that can be divided by the
cache line size without rest. This means the buffer may be up to one cache line size minus
one larger than the requested size during the allocation. This prevents the overwriting of
memory that follows immediately at the end of the buffer when the cache line is updated.
• The memory is in a memory range that can be accessed by the host controller.
• The CPU can use address translation for this memory.
This kind of memory is used for all data transfers with the host controller. For data transfers on
the control endpoint the driver stack allocates internal buffers with these properties. The caller can
use any memory to start a data transfer on the control endpoint. The data transfer buffer for all
other transfer types must have the properties described above. The caller can either use the TAL
function TAL_AllocateDmaMemory to get the required memory or it can make sure that the
memory that is used has the right properties.
USB Bus Driver Reference Manual 29

5 Usage
5.4 Enumeration of USB devices
The Embedded USB Host Stack supports hot plug and hot removal of USB devices. Each detected
device is enumerated by the bus driver according to the following steps:
• Sending a USB reset
• Assigning a USB address
• Requesting the device and the configuration descriptors
• Activating the configuration with the descriptor index 0
• Creating internal USB interface objects for each USB interface
• Inform the registered software modules about the connect events
5.5 USB Interfaces
To communicate with a connected USB device a interface object created in the USB Bus Driver
must be opened. The input parameter for the USBH_OpenInterface function is the interface ID.
This ID can be obtained by two different ways.
The first method enumerates all USB interfaces of all USB devices and opens the interfaces of interest.
A interface list is created with USBH_CreateInterfaceList. This internal interface list contains
all USB interfaces matching the criteria defined with the mask USBH_INTERFACE_MASK
at the point of time where the function is called. This mask includes the VID, PID, Class, Subclass
and some other values. The interfaces in a list can be enumerated with a zero based index
the functions USBH_GetInterfaceInfo and USBH_GetInterfaceID.
While USBH_GetInterfaceInfo returns some information about the found USB interface
the function USBH_GetInterfaceID returns the required interface ID.
The second method uses the function USBH_RegisterPnPNotification to install a PnP handler.
This handler is called each time a USB interface that meets the criteria defined with the
USBH_INTERFACE_MASK is connected or removed to the host controller. The notification function
gets the interface ID as a parameter. When the notification function is registered while USB
interfaces that meet the mask criteria are already connected to the stack the bus driver calls the notification
function for each interface. When the programmer decides to use the PnP notifications it
is not required to enumerate the available devices first.
This handle that is returned by USBH_OpenInterface is required for all other interface related
functions.
Typically one software module on top of the USB Bus Driver API controls one or more interfaces,
but one interface is only controlled by one software module. To prevent usage of the same interface
by different software module the interface should be opened exclusively.
5.6 Additional Device Information
The USB Bus Driver has captured some descriptors from the device during the enumeration
process. The descriptor information can be requested with the USBH_GetXXX functions, like
30 USB Bus Driver Reference Manual

5 Usage
USBH_GetDeviceDescriptor or USBH_GetInterfaceDescriptor. These functions do not perform
data transfers on the USB bus and therefore return immediately.
5.7 Data Transfer
To communicate with the device or perform data transfer the function USBH_SubmitUrb is used,
where the information is transferred within the data structure URB. The URB determines which
device operation is used. For a detailed description of the API see section 8 on page 41.
5.8 Closing the Handles
Each handle that is returned by the API has an associated resource inside the bus driver. The
internal resource is kept valid until the handle is closed. For that reason it is important that every
handle that is obtained from the bus driver API is closed exactly one time. After a handle is closed
it must not be used again. A violation of this rule will break the operation of the code.
5.9 External Hub Support1
The driver stack supports external USB hubs. The support for external hubs is an option and must
be licensed separately. The external hubs are transparent to the bus API. The interface of the hubs
do not appear in the list of available USB interfaces and cannot be controlled from the bus driver
API. The bus driver takes care on the power management and the bandwidth in the bus topology.
The hub driver does not support dynamically switching of the hubs power supply, this means if
the hub is switched to self power or bus power mode during hub operation the hub driver does not
recognize this. This software version supports USB 1.1 and USB 2.0 compliant hubs.
The implementation if the external hub module is in the files usbh_exthub.h and
usbh_exthub.c. If the external hub support is not license these files are not part of the delivery.
The files must be removed from the build environment.
5.10 Synchronization
The USB Host Driver Core and the Host Controller Driver are implemented asynchronously.
That means these software parts work event driver and does not use wait functions in the normal
data processing. The software modules can be protected with an internally implemented
TAL_MutexObject object. Whether the mutex object should be used or not can be configured
with the configuration parameter USBH_SYNCHRONIZE. If this define is set to 1 the Core and the
Host Controller Driver are protected with a mutex. It must be used when the class implementation
are used.
The driver stack releases the mutex before the callback functions are called. This enables the
application and the class driver to call non blocking function directly in the context of callback
functions.
Some API function of the Driver Core can wait. These are function like
USBH_WaitForIdleStack()
USBH_Exit()
USB Bus Driver Reference Manual 31

5 Usage
USBH_RemoveHostController()
The interrupt handling is divided in a USBH_ServiceISR and in a USBH_ProcessInterrupt
function. The function USBH_ServiceISR disables only the interrupt of the host controller. For
that reason this function can be called at each point of time without any synchronization. It can
be called directly in the context of the system ISR. No callback is performed in the context of this
function. The function USBH_ServiceISR returns T_TRUE if the interrupt was generated by
the host controller.
The function USBH_ProcessInterrupt service the interrupt and re-enables the interrupt on
the host controller. This function enters the mutex and can call notification functions. This function
is typically called in a task of the operating system that belongs to the USB host stack.
The class driver protects its data structures with its own mutex objects.
5.11 Callbacks
The callback functions are called in a arbitrary context. This means either in a timer context or
in the context of the function USBH_ProcessInterrupt. The code in a callback function
must not wait and must not call API functions that are marked as blocking. When the code in the
callback function needs a mutex object to protect variables the other code that is executed under
the same mutex must not call non blocking function or wait for something. When this rule is
violated the stack can deadlock. The stack does not detect the deadlock situation by asserts or
different methods. The stack becomes not functional.
For complex tasks, like the handling of a device remove event, the code in the callback routine
should wakeup a different task by setting an event.
When the application re-submits data buffers in the context of the callback function it should check
the return status. On error the code should start an error recovery and should not submit the buffer
in the context of the callback function. The error recovery must be either implemented as a state
machine with asynchronous functions or should wake the application task to do this job.
A special problem occurs, when a callback function is unregistered at the stack. Because of
the design rule that the callback functions are called without mutex there is the risk that a callback
function is called a short time after it was unregistered. This can cause problems when
the resources that are used in the callback function are freed. To avoid the problem the function
USBH_WaitForIdleStack must be called each time a callback function is unregistered from
the stack .
Note: The function USBH_WaitForIdleStack does not ensure that a timer callback function
is not called after the timer has been cancelled with TAL_CancelTimer.
32 USB Bus Driver Reference Manual

6 Management Reference
6.1 USB Bus Driver Core
USBH_Init
This function is called for the basic initialization of the USB Bus Driver.
Definition
USBH_STATUS
USBH_Init();
Return Value
6 Management Reference
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function has to be called one time during startup before any other function is called. The
USB Bus Driver initializes or allocates global resources within this function. The host
controller must be created and added to the bus driver at a later time.
This function is non blocking.
See Also
USBH_Exit (page 34)
USB Bus Driver Reference Manual 33

6 Management Reference
USBH_Exit
This function is called on exit of the USB Bus Driver.
Definition
void
USBH_Exit();
Comments
This function has to be called on exit of the USB Bus Driver. The USB Bus Driver may free
global resources within this function. This includes also the removing and deleting of added
host controllers. After this function was called, no other function of the USB Bus Driver
should be called.
This function is blocking.
See Also
USBH_Init (page 33)
34 USB Bus Driver Reference Manual

USBH_ServiceISR
This function must be called in the interrupt service routine of the OHCI controller.
Definition
T_BOOL
USBH_ServiceISR(
USBH_HC_HANDLE HcHandle
);
Parameter
HcHandle
This parameter is a handle to the host controller driver.
Return Value
6 Management Reference
The function returns T_TRUE if the interrupt was caused by the controller that is identified by
the handle otherwise T_FALSE.
Comments
This function must be called if an interrupt occurs. It should be called in the context of the
interrupt routine. This function disables the interrupt in the controller if the interrupt was
caused by the controller.
This function is non blocking.
See Also
USBH_ProcessInterrupt (page 36)
USB Bus Driver Reference Manual 35

6 Management Reference
USBH_ProcessInterrupt
Process an interrupt.
Definition
void
USBH_ProcessInterrupt(
USBH_HC_HANDLE HcHandle
);
Parameter
HcHandle
This handle is the context of the host controller driver.
Comments
This routine processes an interrupt from a controller. Callback functions may be called in the
the context of this function. The function enables the interrupts of the controller. It enters a
mutex to protect the code.
This function is non blocking. But in the context of this function other callback functions may
be called. Therefor no blocking functions must be called in this context. An invalid
implementation in a callback function that block this function and cause a deadlock.
See Also
USBH_ServiceISR (page 35)
36 USB Bus Driver Reference Manual

USBH_RemoveHostController
6 Management Reference
This function must be called by the application to remove the host controller from the USB Bus
Driver.
Definition
USBH_STATUS
USBH_RemoveHostController(
USBH_HC_HANDLE HcHandle
);
Parameter
HcHandle
Valid Handle to the host controller.
Comments
This removes a host controller from the library.
This function is blocking.
USB Bus Driver Reference Manual 37

6 Management Reference
USBH_EnumerateDevices
This function adds default endpoints for enumeration, sets the host controller into running state
and starts the enumeration of the complete bus.
Definition
void
USBH_EnumerateDevices(
USBH_HC_HANDLE HcHandle
);
Parameter
HcHandle
A valid handle to a host controller.
Comments
After this function returns the host controller is up and running and can detect USB devices.
The enumeration of USB devices can still be in progress when this function returns.
This function is non blocking.
See Also
USBH_Init (page 33)
38 USB Bus Driver Reference Manual

7 Host Controller Creation Reference
7.1 Open Host Controller
USBH_CreateOhcController
7 Host Controller Creation Reference
This function allocates all resources that are required for the host controller object of the USB
Host Controller Driver. Furthermore it initializes the host controller and attach it to the USB bus
driver core.
Definition
USBH_HC_HANDLE
USBH_CreateOhcController(
void* BaseAddress
);
Parameter
BaseAddress
This is the virtual base address of the OHC or any other hardware resource information.
Return Value
The function returns a handle to the created host controller object on success. If creation of the
host controller fails the function returns NULL which is an invalid handle value.
Comments
This function is non blocking.
USB Bus Driver Reference Manual 39

7 Host Controller Creation Reference
USBH_CreateEhcController
This function allocates all resources that are required for the host controller object of the USB
Host Controller Driver. Furthermore it initializes the host controller and attach it to the USB bus
driver core.
Definition
USBH_HC_HANDLE
USBH_CreateEhcController(
void* BaseAddress
);
Parameter
BaseAddress
This is the virtual base address of the EHC capabilities registers.
Return Value
The function returns a handle to the created host controller object on success. If creation of the
host controller fails the function returns NULL which is an invalid handle value.
Comments
This function is non blocking.
40 USB Bus Driver Reference Manual

8 USB Bus Driver Reference
8.1 Application programming interface
USBH_CreateInterfaceList
This function generates a list of available interfaces.
Definition
USBH_INTERFACE_LIST_HANDLE
USBH_CreateInterfaceList(
const USBH_INTERFACE_MASK* InterfaceMask,
T_UINT32* InterfaceCount
);
Parameters
8 USB Bus Driver Reference
InterfaceMask
This is an input parameter of type USBH_INTERFACE_MASK and specifies a mask for the
interfaces which should be listed.
InterfaceCount
This parameter returns the number of available interfaces.
Return Value
This function returns a handle to an interface list on success or NULL which is an invalid
handle value.
Comments
The generated interface list is stored in the bus driver and must be deleted by a call to
USBH_DestroyInterfaceList. The list contains a snapshot of interfaces available at
the point of time where the function is called. This enables the application to have a fixed
relation between the index and a USB interface in a list. The list is not updated if a device is
removed or connected. A new list must be created to capture the current available interfaces.
This function is non blocking.
See Also
USBH_DestroyInterfaceList (page 42)
USBH_GetInterfaceID (page 43)
USBH_GetInterfaceInfo (page 44)
USBH_INTERFACE_MASK (page 90)
USB Bus Driver Reference Manual 41

8 USB Bus Driver Reference
USBH_DestroyInterfaceList
This function deletes a previously generated interface list.
Definition
void
USBH_DestroyInterfaceList(
USBH_INTERFACE_LIST_HANDLE InterfaceListHandle
);
Parameter
InterfaceListHandle
This parameter contains the handle for the interface list and must not be NULL.
Comments
This function deletes an interface list generated by a previous call to
USBH_CreateInterfaceList. If an interface list is not deleted the USB Bus Driver
Core has a memory leak.
This function is non blocking.
See Also
USBH_CreateInterfaceList (page 41)
42 USB Bus Driver Reference Manual

USBH_GetInterfaceID
This function returns the interface ID for a specified interface.
Definition
USBH_INTERFACE_ID
USBH_GetInterfaceID(
USBH_INTERFACE_LIST_HANDLE InterfaceListHandle,
T_UINT32 Index
);
Parameters
InterfaceListHandle
This parameter contains the handle for an interface list generated by a call to
USBH_CreateInterfaceList.
8 USB Bus Driver Reference
Index
This parameter specifies the zero based index for a specific interface in the list.
Return Value
On success the interface ID for the interface specified by Index is returned. If the interface
index does not exist the function returns 0.
Comments
The interface ID identifies a USB interface as long as the device is connected to the host. If
the device is removed and re-connected a new interface ID is assigned. The interface ID is
even valid if the interface list is deleted. The function can return an interface ID even if the
device is removed between the call to the function USBH_CreateInterfaceList and the
call to this function. In this case a call to the function USBH_OpenInterface using this
interface ID will fail.
This function is non blocking.
See Also
USBH_CreateInterfaceList (page 41)
USBH_OpenInterface (page 53)
USB Bus Driver Reference Manual 43

8 USB Bus Driver Reference
USBH_GetInterfaceInfo
This function obtains information about a specified interface.
Definition
USBH_STATUS
USBH_GetInterfaceInfo(
USBH_INTERFACE_ID InterfaceID,
USBH_INTERFACE_INFO* InterfaceInfo
);
Parameters
InterfaceID
This parameter specifies the interface by its interface ID.
InterfaceInfo
This parameter points to a caller provided data structure USBH_INTERFACE_INFO and
retrieves the information about the interface.
Return Value
The function returns USBH_STATUS_SUCCESS on success or
USBH_STATUS_DEVICE_REMOVED if the specified interface is removed.
Comments
This function can be used to identify a USB interface without open it. More detailed
information can be requests after the USB interface is opened.
This function is non blocking.
See Also
USBH_INTERFACE_INFO (page 92)
USBH_GetInterfaceID (page 43)
USBH_OpenInterface (page 53)
44 USB Bus Driver Reference Manual

USBH_WaitForIdleStack
Call this function to make sure de-installed callback functions are not called.
Definition
int
USBH_WaitForIdleStack(
T_UINT32 TimeoutMS
);
Parameter
8 USB Bus Driver Reference
TimeoutMS
This parameter can be either a timeout in milliseconds or the constant TAL_WAIT_INFINITE.
Return Value
The function returns the following status codes:
TAL_WAIT_TIMEOUT - The timeout interval elapsed, the stack is busy. Call the function
later again.
TAL_WAIT_SIGNALED - The stack was idle. The memory that is used by the callback
function can be freed.
Comments
The callback functions are not called under the Mutex of the host stack. This allows the user
to call non blocking functions directly from the callback functions. On the other hand the
un-registering of a callback function is not an atomic operation. The callback function may be
called from the host stack after it was unregistered by the application. This situation is difficult
to handle when the application wants to free the resources that are used in the callback
function. When a callback function is un-registered this function should be called afterwards.
When this function returns with TAL_WAIT_SIGNALED the unregistered callback function
is no more called by the host stack. It is safe to free the related resources.
When this function blocks for a longer time, maybe a deadlock has been occurred. To detect
such a situation the timeout option can be used.
This function is blocking.
See Also
USBH_UnregisterPnPNotification (page 48)
USB Bus Driver Reference Manual 45

8 USB Bus Driver Reference
USBH_PnpNotification
Prototype for a callback that is called by the USB Bus Driver Core if a PnP event occurs and if a
PnP notification was registered.
Definition
typedef
void
USBH_PnpNotification(
void* Context,
USBH_PNP_EVENT Event,
USBH_INTERFACE_ID InterfaceID
);
Parameters
Context
This parameter is the user defined pointer that was passed to
USBH_RegisterPnPNotification. The USB Bus Driver Core does not modify this
parameter.
Event
This parameter is of type USBH_PNP_EVENT and specifies the PnP event.
InterfaceID
This member contains the interface ID of the removed or added interface.
Comments
This function is called in the context of a TAL timer. In the context of this function all other
non-blocking API functions of the bus driver can be called. The removed or added interface
can be identified by the interface ID. The client can use this information to find the related
USB Interface to close all handles if it was in use, to open it or to collect information about the
interface.
In the context of this function blocking functions must not be called.
See Also
USBH_PNP_EVENT (page 114)
USBH_RegisterPnPNotification (page 47)
USBH_GetInterfaceInfo (page 44)
USBH_OpenInterface (page 53)
46 USB Bus Driver Reference Manual

USBH_RegisterPnPNotification
This function registers a notification function for PnP events.
Definition
USBH_NOTIFICATION_HANDLE
USBH_RegisterPnPNotification(
USBH_PNP_NOTIFICATION* PnPNotification
);
Parameter
PnPNotification
This parameter contains a pointer to a caller provided structure
USBH_PNP_NOTIFICATION. This structure must be filled in by the caller.
Return Value
8 USB Bus Driver Reference
On success a valid handle is returned. If the function fails it returns NULL which is an invalid
handle value.
Comments
If a valid handle is returned, the function USBH_UnregisterPnPNotification must
be called to release the notification. An application can register any number of notifications.
The user notification routine is called in the context of a notify timer that is global for all USB
bus PnP notifications.
If this function is called while the bus driver has already enumerated devices that match the
USBH_INTERFACE_MASK the function USBH_PnpNotification is called for each
matching interface.
The mask can be set to 0. In this case all devices causes a PnP notification.
This function is non blocking.
See Also
USBH_PNP_NOTIFICATION (page 110)
USBH_INTERFACE_MASK (page 90)
USBH_UnregisterPnPNotification (page 48)
USBH_PnpNotification (page 46)
USB Bus Driver Reference Manual 47

8 USB Bus Driver Reference
USBH_UnregisterPnPNotification
This function unregister a previously registered notification for PnP events.
Definition
void
USBH_UnregisterPnPNotification(
USBH_NOTIFICATION_HANDLE Handle
);
Parameter
Handle
This parameter contains the valid handle for a PnP notification previously registered by a call
to USBH_RegisterPnPNotification.
Comments
This function has to be called for each PnP notification that was successfully registered by a
call to USBH_RegisterPnPNotification.
A callback can be scheduled when this function returns. To make sure that the unregistered
callback function is not called, call the function USBH_WaitForIdleStack.
The function is non blocking.
See Also
USBH_RegisterPnPNotification (page 47)
USBH_WaitForIdleStack (page 45)
48 USB Bus Driver Reference Manual

USBH_EnumErrorNotification
8 USB Bus Driver Reference
Prototype for a callback that is called by the USB Bus Driver Core if an error occurs during port
or device initialization.
Definition
typedef
void
USBH_EnumErrorNotification(
void* Context,
const USBH_ENUM_ERROR* EnumError
);
Parameters
Context
This parameter is a user defined pointer that was passed to
USBH_RegisterEnumErrorNotification.
EnumError
This parameter is of type USBH_ENUM_ERROR and specifies the enumeration error. This
pointer is temporary and must not be accessed after the function returns.
Comments
This function is called in the context of a TAL timer or ProcessInterrupt function of a host
controller. Before this function is called it must be registered with
USBH_RegisterEnumErrorNotification. If a device is not successfully enumerated
the function USBH_RestartEnumError can be called to restart a new enumeration in the
context of this function.
This callback mechanism is part of the enhanced error recovery. In an embedded system with
internal components connected with USB a central application may turn off the power supply
for some device to force a reboot or to create an alert.
In the context of this function no blocking function must be called.
See Also
USBH_ENUM_ERROR (page 94)
USBH_RegisterEnumErrorNotification (page 50)
USBH_UnregisterEnumErrorNotification (page 51)
USBH_RestartEnumError (page 52)
USB Bus Driver Reference Manual 49

8 USB Bus Driver Reference
USBH_RegisterEnumErrorNotification
This function registers a port error enumeration notification.
Definition
USBH_ENUM_ERROR_HANDLE
USBH_RegisterEnumErrorNotification(
void* Context,
USBH_EnumErrorNotification* EnumErrorCallback
);
Parameters
Context
This parameter is a user defined pointer that is passed unchanged to the notification callback
function USBH_EnumErrorNotification.
EnumErrorCallback
This parameter contains the notification function that is called from the USB Bus Driver Core
if a port enumeration error occurs.
Return Value
On success a valid handle is returned. If the function fails this function returns NULL which is
an invalid handle value.
Comments
If a valid handle is returned, the function USBH_RegisterEnumErrorNotification
must be called to release the notification. The EnumErrorCallback callback routine is
called in the context of the process where the interrupt status of a host controller is processed
(e.g. USBH_ProcessInterrupt). It is forbidden to wait in that context.
This function is non blocking.
See Also
USBH_RegisterEnumErrorNotification (page 50)
50 USB Bus Driver Reference Manual

USBH_UnregisterEnumErrorNotification
8 USB Bus Driver Reference
This function unregister a previously registered port error enumeration notification.
Definition
void
USBH_UnregisterEnumErrorNotification(
USBH_ENUM_ERROR_HANDLE Handle
);
Parameter
Handle
This parameter contains the valid handle for the notification returned by a previous call to
USBH_RegisterEnumErrorNotification.
Comments
This function has to be called for each port enumeration error notification that was
successfully registered by a call to USBH_RegisterEnumErrorNotification.
A callback can be scheduled when this function returns. To make sure that the unregistered
callback function is not called, call the function USBH_WaitForIdleStack.
This function is non blocking.
See Also
USBH_RegisterEnumErrorNotification (page 50)
USBH_WaitForIdleStack (page 45)
USB Bus Driver Reference Manual 51

8 USB Bus Driver Reference
USBH_RestartEnumError
Restart the enumeration for all devices that have failed in the enumeration process.
Definition
void
USBH_RestartEnumError();
Comments
The bus driver retries each enumeration again until the default retry count is reached.
This function is non blocking.
See Also
USBH_EnumErrorNotification (page 49)
52 USB Bus Driver Reference Manual

USBH_OpenInterface
This function opens the specified interface.
Definition
USBH_STATUS
USBH_OpenInterface(
USBH_INTERFACE_ID InterfaceID,
T_BOOL Exclusive,
USBH_INTERFACE_HANDLE* InterfaceHandle
);
Parameters
8 USB Bus Driver Reference
InterfaceID
This parameter specifies the interface to open by its interface ID. The interface ID can be
obtained by a call to USBH_PnpNotification or USBH_GetInterfaceID.
Exclusive
This parameter specifies if the interface should be opened exclusive or not. If the value is
T_TRUE the interface is opened exclusive.
InterfaceHandle
This parameter returns the handle for the opened interface on success.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. The function can fail if the device was removed or the device is opened
exclusive by another application. The function returns with an error if the exclusive flag is set
or another application has an open handle to the interface.
Comments
The handle returned by this function is used by all other functions that perform data transfer.
The returned handle must be closed with USBH_CloseInterface if it is no longer
required.
This function is non blocking.
See Also
USBH_CloseInterface (page 54)
USBH_PnpNotification (page 46)
USBH_GetInterfaceID (page 43)
USB Bus Driver Reference Manual 53

8 USB Bus Driver Reference
USBH_CloseInterface
This function closes a previously opened interface.
Definition
void
USBH_CloseInterface(
USBH_INTERFACE_HANDLE Handle
);
Parameter
Handle
This parameter contains the handle for an interface opened by a previous call to
USBH_OpenInterface. The handle must not be NULL.
Comments
Each handle must be closed exactly one time. The USB Bus Driver Core accesses invalid
memory if this function is called with an invalid handle.
This function is non blocking.
See Also
USBH_OpenInterface (page 53)
54 USB Bus Driver Reference Manual

USBH_GetDeviceDescriptor
This function retrieves the device descriptor.
Definition
USBH_STATUS
USBH_GetDeviceDescriptor(
USBH_INTERFACE_HANDLE Handle,
T_UINT8* Descriptor,
T_UINT32 Size,
T_UINT32* Count
);
Parameters
Handle
This parameter specifies the interface by its interface handle.
8 USB Bus Driver Reference
Descriptor
This parameter points to a caller provided buffer that retrieves the device descriptor on success.
Size
This parameter specifies the size of the caller provided buffer.
Count
This parameter returns the length of the returned descriptor.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or
USBH_STATUS_DEVICE_REMOVED if the device is removed.
Comments
This function returns a copy of the device descriptor and does not access the device. If the user
provided buffer is smaller than the device descriptor the function returns the first part of it.
This function is non blocking.
See Also
USBH_OpenInterface (page 53)
USBH_GetCurrentConfigurationDescriptor (page 56)
USB Bus Driver Reference Manual 55

8 USB Bus Driver Reference
USBH_GetCurrentConfigurationDescriptor
This function retrieves the current configuration descriptor.
Definition
USBH_STATUS
USBH_GetCurrentConfigurationDescriptor(
USBH_INTERFACE_HANDLE Handle,
T_UINT8* Descriptor,
T_UINT32 Size,
T_UINT32* Count
);
Parameters
Handle
This parameter specifies the interface by its interface handle.
Descriptor
This parameter points to a caller provided buffer that retrieves the current configuration
descriptor on success.
Size
This parameter specifies the size of the caller provided buffer.
Count
This parameter returns the number of valid bytes.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or
USBH_STATUS_DEVICE_REMOVED if the device is removed.
Comments
This function returns a copy of the current configuration descriptor. The descriptor is a copy
that was stored during the device enumeration. The function returns the first part of the
descriptor if the user provided buffer is smaller than the descriptor. This descriptor contains all
interface, endpoint, and possible class descriptors. The size is variable. The current
configuration descriptor is the descriptor return to the request with the index 0 if the device
was enumerated the first time. It changes if the configuration is switch with
URB_SET_CONFIGURATION. Other configuration descriptors of a multi-configuration
device can be requested with URB_FUNCTION_CONTROL_REQUEST.
This function is non blocking.
56 USB Bus Driver Reference Manual

See Also
USBH_OpenInterface (page 53)
USBH_GetDeviceDescriptor (page 55)
URB_SET_CONFIGURATION (page 105)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 57

8 USB Bus Driver Reference
USBH_GetInterfaceDescriptor
This function retrieves the interface descriptor.
Definition
USBH_STATUS
USBH_GetInterfaceDescriptor(
USBH_INTERFACE_HANDLE Handle,
T_UINT8 AlternateSetting,
T_UINT8* Descriptor,
T_UINT32 Size,
T_UINT32* Count
);
Parameters
Handle
This parameter specifies the interface by its interface handle.
AlternateSetting
This parameter specifies the alternate setting for this interface.
Descriptor
This parameter points to a caller provided buffer that retrieves the interface descriptor on
success.
Size
This parameter specifies the size of the caller provided buffer.
Count
This parameter returns the number of valid bytes in the descriptor.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or
USBH_STATUS_DEVICE_REMOVED if the device is removed. The status
USBH_STATUS_INVALID_PARAM is returned when the parameter AlternateSetting
specifies an alternate setting that does not exists.
Comments
This function returns a copy of an interface descriptor. The interface descriptor belongs to the
interface that is identified by the USBH_INTERFACE_HANDLE. If the interface has different
alternate settings the interface descriptors of each alternate setting can be requested. The
function returns a copy of this descriptor that was requested during the enumeration process.
The interface descriptor is part of the configuration descriptor.
This function is non blocking.
58 USB Bus Driver Reference Manual

See Also
USBH_OpenInterface (page 53)
USBH_GetCurrentConfigurationDescriptor (page 56)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 59

8 USB Bus Driver Reference
USBH_GetClassDescriptor
This function searches a class descriptor for the related interface and returns a copy if it is
successful.
Definition
USBH_STATUS
USBH_GetClassDescriptor(
USBH_INTERFACE_HANDLE Handle,
T_UINT8 AlternateSetting,
T_INT16 Type,
T_INT16 SubType,
T_UINT8* Descriptor,
T_UINT32 Size,
T_UINT32* Count
);
Parameters
Handle
The interface handle.
AlternateSetting
The alternate setting where the class descriptor is searched.
Type
The type of the descriptor or -1 for don’t care.
SubType
The sub-type of the descriptor or -1 for don’t care.
Descriptor
A caller provided memory that receives the copy of the descriptor.
Size
The size of the descriptor memory in bytes.
Count
Returns the byte count of the returned descriptor.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function is useful to find class information. When the descriptor is larger than the
descriptor size the first part is returned. Some descriptors my not have a sub-type. In this case
60 USB Bus Driver Reference Manual

set the sub-type parameter to -1.
This function is non blocking.
See Also
USBH_OpenInterface (page 53)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 61

8 USB Bus Driver Reference
USBH_GetEndpointDescriptor
This function retrieves an endpoint descriptor.
Definition
USBH_STATUS
USBH_GetEndpointDescriptor(
USBH_INTERFACE_HANDLE Handle,
T_UINT8 AlternateSetting,
const USBH_EP_MASK* Mask,
T_UINT8* Descriptor,
T_UINT32 Size,
T_UINT32* Count
);
Parameters
Handle
This parameter specifies the interface by its interface handle.
AlternateSetting
This parameter specifies the alternate setting for the interface. The function returns the
endpoint descriptors that are inside the specified alternate setting.
Mask
This parameter is of type USBH_EP_MASK and specifies a mask to select the endpoint.
Descriptor
This parameter specifies a pointer to the caller provided buffer that contains the endpoint
descriptor on success.
Size
This parameter specifies the size of the caller provided buffer.
Count
This parameter returns the valid number of bytes written to the buffer.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. The function fails if the endpoint can not be found or if the device is removed.
Comments
This function returns a copy of the endpoint descriptor that was captured during the
enumeration process. The endpoint descriptor is part of the configuration descriptor.
This function is non blocking.
62 USB Bus Driver Reference Manual

See Also
USBH_EP_MASK (page 96)
USBH_OpenInterface (page 53)
USBH_GetCurrentConfigurationDescriptor (page 56)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 63

8 USB Bus Driver Reference
USBH_GetSerialNumber
This function retrieves the serial number.
Definition
USBH_STATUS
USBH_GetSerialNumber(
USBH_INTERFACE_HANDLE Handle,
T_UINT8* Descriptor,
T_UINT32 Size,
T_UINT32* Count
);
Parameters
Handle
This parameter specifies the interface by its interface handle.
Descriptor
This parameter is a pointer to a caller provided buffer. It returns the serial number on success.
Size
This parameter specifies the size of the caller provided buffer in bytes.
Count
This parameter returns the number of bytes written to the buffer.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or
USBH_STATUS_DEVICE_REMOVED if the device is removed.
Comments
It returns the serial number as a UNICODE string in USB little endian format. Count returns
the number of valid bytes. The string is not zero terminated. The returned data does not
contain a USB descriptor header. The descriptor is requested with the first language ID. This
string is a copy of the serial number string that was requested during the enumeration process.
To request other string descriptors use USBH_SubmitUrb.
If the device does not support a USB serial number string the function returns success and
Count is set to 0.
This function is non blocking.
64 USB Bus Driver Reference Manual

See Also
USBH_OpenInterface (page 53)
USBH_SubmitUrb (page 74)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 65

8 USB Bus Driver Reference
USBH_GetSpeed
This function retrieves the operation speed of the device.
Definition
USBH_STATUS
USBH_GetSpeed(
USBH_INTERFACE_HANDLE Handle,
USBH_SPEED* Speed
);
Parameters
Handle
This parameter specifies the interface by its interface handle.
Speed
This parameter returns the device operating speed of type USBH_SPEED.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or
USBH_STATUS_DEVICE_REMOVED if the device is removed.
Comments
A high speed device can operate in full or high speed mode.
This function is non blocking.
See Also
USBH_OpenInterface (page 53)
USBH_SPEED (page 113)
66 USB Bus Driver Reference Manual

USBH_GetFrameNumber
This function retrieves the current frame number.
Definition
USBH_STATUS
USBH_GetFrameNumber(
USBH_INTERFACE_HANDLE Handle,
T_UINT32* FrameNumber
);
Parameters
Handle
This parameter specifies the interface by its interface handle.
FrameNumber
This parameter contains the current frame number on success.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or
USBH_STATUS_DEVICE_REMOVED if the device is removed.
Comments
8 USB Bus Driver Reference
The frame number is transferred on the bus with 11 bits. This frame number is returned as a
16 or 32 bit number related to the implementation of the host controller. The last 11 bits are
equal to the current frame. The frame number is increased each ms. This is the case for high
speed, too. The returned frame number is related to the bus where the device is connected.
The frame numbers can differ between different host controllers.
This function is non blocking.
See Also
USBH_OpenInterface (page 53)
USB Bus Driver Reference Manual 67

8 USB Bus Driver Reference
USBH_GetInterfaceIDByHandle
This function retrieves the interface ID for a given interface.
Definition
USBH_STATUS
USBH_GetInterfaceIDByHandle(
USBH_INTERFACE_HANDLE Handle,
USBH_INTERFACE_ID* InterfaceID
);
Parameters
Handle
This parameter specifies the interface by its interface handle.
InterfaceID
This parameter contains the interface ID on success.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or
USBH_STATUS_DEVICE_REMOVED if the device is removed.
Comments
This function returns the interface ID if the handle to the interface is available. This may be
useful if a Plug and Play notification is received and the application checks if it is related to a
given handle. The application can avoid calls to this function if the interface ID is stored in the
device context of the application.
This function is non blocking.
See Also
USBH_OpenInterface (page 53)
USBH_GetInterfaceID (page 43)
68 USB Bus Driver Reference Manual

USBH_GetHubPortHandlebyInterface
This function retrieves the hub port handle for a given interface.
Definition
USBH_HUB_PORT_HANDLE
USBH_GetHubPortHandlebyInterface(
USBH_INTERFACE_HANDLE interfaceHandle
);
Parameter
interfaceHandle
This parameter specifies the interface by its interface handle.
Return Value
8 USB Bus Driver Reference
This function returns a handle to a hub port or NULL which is an invalid handle value.
Comments
This function returns a hub port handle if the parent port of the device interface is a hub port.
This function is non blocking.
See Also
USBH_GetHubPortHandlebyTopology (page 70)
USBH_SetPortPowerState (page 71)
USB Bus Driver Reference Manual 69

8 USB Bus Driver Reference
USBH_GetHubPortHandlebyTopology
This function retrieves the hub port handle for a given port number array.
Definition
USBH_HUB_PORT_HANDLE
USBH_GetHubPortHandlebyTopology(
USBH_HC_HANDLE hcHandle,
T_UINT32 portNumberItems,
const T_UINT8* portNumber
);
Parameters
hcHandle
This handle was returned by the function USBH_CreateXXXController.
portNumberItems
Number of valid port numbers in the portNumber array.
portNumber
This pointer points to an array of port numbers. Each valid number is one based.
Return Value
This function returns a handle to a hub port or NULL which is an invalid handle value.
Comments
All values in the port Number array must be in the range from 1 to 127. The first element in
the array is the root hub port number. All other port numbers are external hub ports.
To address the second port of a external hub that is connected with the first root hub port the
first port number in the portNumbers array is 1 and the second one is 2.
This function is non blocking.
See Also
USBH_GetHubPortHandlebyInterface (page 69)
USBH_SetPortPowerState (page 71)
70 USB Bus Driver Reference Manual

USBH_SetPortPowerState
This function set the port power.
Definition
USBH_STATUS
USBH_SetPortPowerState(
USBH_HUB_PORT_HANDLE hubPortHandle,
USBH_POWER_STATE powerState
);
Parameters
hubPortHandle
Hub port handle.
8 USB Bus Driver Reference
powerState
This parameter is of type USBH_POWER_STATE and specifies the power state.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. Now details of important errors:
USBH_STATUS_INVALID_PARAM
Invalid port handle or invalid power state.
USBH_STATUS_BUSY
Previous external hub URB power request not completed. Try it later.
USBH_STATUS_RESOURCES
No memory resources.
Comments
If the hub port is set to power state USBH_POWER_OFF a connected USB device is not
recognized until the port power is switched on. If port power is changed the application should
wait for a minimum time of about 100ms. Normally the user waits for adding of a device on
this port and switch the port power off if the device is not needed. In that case it must wait a
minimum time before the port power is switched on.
This function is non blocking.
See Also
USBH_GetHubPortHandlebyInterface (page 69)
USBH_GetHubPortHandlebyTopology (page 70)
USB Bus Driver Reference Manual 71

8 USB Bus Driver Reference
USBH_GetPortPowerState
This function set the port power.
Definition
USBH_STATUS
USBH_GetPortPowerState(
USBH_HUB_PORT_HANDLE hubPortHandle,
USBH_POWER_STATE* powerState
);
Parameters
hubPortHandle
Hub port handle.
powerState
This parameter is of type USBH_POWER_STATE and specifies the power state.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. A reason for failure is that the port handle is invalid (removing of the hub
device).
Comments
After the port power is switched off with USBH_SetPortPowerState the function returns
USBH_POWER_OFF independent of the real port power status. If the port power is switched
the function checks the real port power state until return.
This function is non blocking.
See Also
USBH_GetHubPortHandlebyInterface (page 69)
USBH_GetHubPortHandlebyTopology (page 70)
72 USB Bus Driver Reference Manual

URB_COMPLETION
Prototype for a callback function that is called if an URB is completed.
Definition
typedef
void
URB_COMPLETION(
URB* Urb
);
Parameter
Urb
A pointer to the completed URB.
Comments
8 USB Bus Driver Reference
The application can define a completion function for each URB. The pointer to this
completion function is passed to the USB Bus Driver Core with the URB.
The completion function is called in the context of a ProcessInterrupt function of the host
controller or in a TAL timer function. The completion function can call API functions to
submit URB’s (USBH_SubmitUrb) or get information from the device. The function must
not close the interface handle with a call to USBH_CloseInterface. The function should
not perform lengthy operations, because this may influence the performance of other USB
devices. A better solution is to set an event and perform these operations in a separate task.
Do not call blocking function in the context of this callback function.
See Also
URB (page 108)
URB_FUNCTION (page 116)
URB_HEADER (page 111)
USBH_CloseInterface (page 54)
USB Bus Driver Reference Manual 73

8 USB Bus Driver Reference
USBH_SubmitUrb
This function is used to submit an URB.
Definition
USBH_STATUS
USBH_SubmitUrb(
USBH_INTERFACE_HANDLE Handle,
URB* Urb
);
Parameters
Handle
This parameter specifies the interface by its interface handle.
Urb
This is an input and output parameter. On input it contains the URB which should be
submitted. On output it contains the submitted URB with the appropriate status and the
received data if any. The storage for the URB must be permanent as long as the request is
pending. There can be special requirements for the data transfer buffers. For control transfers
any memory can be used. For all other transfers the data transfer buffer must be DMA
memory. For more information about this memory please see section 5.3 at page 29.
Return Value
If the function returns USBH_STATUS_PENDING the completion function will be called
later. In all other cases the completion routine is never called. If the function returns success,
the request was processed immediately. On error the request fail and can not be processed.
Comments
All URBs that are submitted with this function are handled asynchronously. If the status
USBH_STATUS_PENDING is returned the ownership of the URB is passed to the bus driver.
The storage of the URB must neither be freed nor modified as long as the ownership remains
at the bus driver. The bus driver passes the URB back to the application by calling the
completion routine. An URB that transfers data can remain pending for a long time.
This function is non blocking.
See Also
URB_HEADER (page 111)
URB_FUNCTION (page 116)
URB (page 108)
74 USB Bus Driver Reference Manual

USBH_GetStatusStr
This function returns the status as a string constants.
Definition
const char*
USBH_GetStatusStr(
USBH_STATUS x
);
Parameter
x
This parameter specifies the status.
Return Value
An error string is returned.
Comments
8 USB Bus Driver Reference
This function returns only an error string if the debug version of the USB Bus Driver Core is
used (TB_DEBUG=1).
This function is non blocking.
USB Bus Driver Reference Manual 75

8 USB Bus Driver Reference
USBH_AbortEndpointAndWait
This function issue an abort request to abort all pending requests on an endpoint and waits until
the URB with the abort request is completed.
Definition
USBH_STATUS
USBH_AbortEndpointAndWait(
USBH_INTERFACE_HANDLE interfaceHandle,
unsigned char endpoint,
TAL_EventObject waitEvent
);
Parameters
interfaceHandle
This parameter specifies the interface by its interface handle.
endpoint
The endpoint number including the direction bit. Use 0 for the default endpoint.
waitEvent
An event object used to wait for the completion of the request. This parameter is optional and
can be NULL. If the parameter is NULL the function allocates an event object on its own and
frees it before the function returns. With this parameter the caller can optimize the number of
event allocations.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
When this function returns the URB with the abort request is completed. But the data URB’s
can be completed delayed. The caller may wait until all pending URB’s are completed. It can
be used for all endpoint types including endpoint 0.
After aborting all pending requests the data toggle bit of the endpoint can get the wrong value.
Therefor the function USBH_ResetEndpointAndWait must be called before a new data
transfer is started on the endpoint.
This is a blocking function.
See Also
USBH_OpenInterface (page 53)
76 USB Bus Driver Reference Manual

USBH_SubmitUrb (page 74)
USBH_ResetEndpointAndWait (page 80)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 77

8 USB Bus Driver Reference
USBH_SubmitUrbAndWait
This function submits an initialized URB and waits until the operation is finished or a timeout
error has been occurred.
Definition
USBH_STATUS
USBH_SubmitUrbAndWait(
USBH_INTERFACE_HANDLE interfaceHandle,
URB* urb,
unsigned long timeout,
TAL_EventObject waitEvent
);
Parameters
interfaceHandle
This parameter specifies the interface by its interface handle.
urb
The caller provided initialized URB.
timeout
The timeout for the request in milliseconds.
waitEvent
An event object used to wait for the completion of the submitted URB. This parameter is
optional and can be NULL. If the parameter is NULL the function allocates an event object on
its own and frees it before the function returns. With this parameter the caller can optimize the
number of event allocations.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. When the timeout expires before the request is completed the request is
aborted and the function returns USBH_STATUS_TIMEOUT.
Comments
In case of a timeout the caller cannot determine whether the request has been executed
partially. An incomplete data transfer may cause a data lost. Do not use this function to poll an
endpoint for data.
This is a blocking function.
78 USB Bus Driver Reference Manual

See Also
USBH_OpenInterface (page 53)
USBH_SubmitUrb (page 74)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 79

8 USB Bus Driver Reference
USBH_ResetEndpointAndWait
This function issue a request to reset the specified endpoint and waits until the URB with the
reset request is completed or a timeout error has been occurred.
Definition
USBH_STATUS
USBH_ResetEndpointAndWait(
USBH_INTERFACE_HANDLE interfaceHandle,
unsigned char endpoint,
unsigned long timeout,
TAL_EventObject waitEvent
);
Parameters
interfaceHandle
This parameter specifies the interface by its interface handle.
endpoint
The endpoint number including the direction bit. Use 0 for the default endpoint.
timeout
The timeout for the request in milliseconds.
waitEvent
An event object used to wait for the completion of the request. This parameter is optional and
can be NULL. If the parameter is NULL the function allocates an event object on its own and
frees it before the function returns. With this parameter the caller can optimize the number of
event allocations.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. When the timeout expires before the request is completed the request is
aborted and the function returns USBH_STATUS_TIMEOUT.
Comments
To reset the endpoint a Clear Feature Endpoint stall is sent to the device. Also the data toggle
bit of the endpoint is reseted by the bus driver. Therefor the next data transfer on the endpoint
will start with a DATA0 packet.
The caller of this function must make sure that no pending request is on the endpoint. Call
USBH_AbortEndpointAndWait to abort all pending requests on the endpoint.
This is a blocking function.
80 USB Bus Driver Reference Manual

See Also
USBH_AbortEndpointAndWait (page 76)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 81

8 USB Bus Driver Reference
USBH_ResetDeviceAndWait
This function issue a request to reset the device that corresponds to the specified interface and
waits until URB with the reset request is completed or a timeout error has been occurred.
Definition
USBH_STATUS
USBH_ResetDeviceAndWait(
USBH_INTERFACE_HANDLE interfaceHandle,
unsigned long timeout,
TAL_EventObject waitEvent
);
Parameters
interfaceHandle
This parameter specifies the interface by its interface handle.
timeout
The timeout for the request in milliseconds.
waitEvent
An event object used to wait for the completion of the request. This parameter is optional and
can be NULL. If the parameter is NULL the function allocates an event object on its own and
frees it before the function returns. With this parameter the caller can optimize the number of
event allocations.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. When the timeout expires before the request is completed the request is
aborted and the function returns USBH_STATUS_TIMEOUT.
Comments
When a device is reseted the device is freshly enumerated. This causes a remove event for all
interfaces of the device. All handles to an interface of the device and their corresponding
interface IDs will become invalid. The caller should abort all pending requests and close all
handles to the interfaces of the reseted device.
After enumeration all interfaces of the reseted device get new interface IDs. If the caller has
registered for PnP notification for the interfaces of the device he will get an arrival event for
each interface. To register for PnP notification use the function
USBH_RegisterPnPNotification.
This is a blocking function.
82 USB Bus Driver Reference Manual

See Also
USBH_AbortEndpointAndWait (page 76)
USBH_CloseInterface (page 54)
USBH_RegisterPnPNotification (page 47)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 83

8 USB Bus Driver Reference
USBH_SetConfigurationAndWait
This function issue a request to set the configuration with given configuration index and waits
until the URB with the set configuration request is completed or a timeout error has been
occurred.
Definition
USBH_STATUS
USBH_SetConfigurationAndWait(
USBH_INTERFACE_HANDLE interfaceHandle,
unsigned char configurationIndex,
unsigned long timeout,
TAL_EventObject waitEvent
);
Parameters
interfaceHandle
This parameter specifies the interface by its interface handle.
configurationIndex
The index of the configuration to set.
timeout
The timeout for the request in milliseconds.
waitEvent
An event object used to wait for the completion of the request. This parameter is optional and
can be NULL. If the parameter is NULL the function allocates an event object on its own and
frees it before the function returns. With this parameter the caller can optimize the number of
event allocations.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. When the timeout expires before the request is completed the request is
aborted and the function returns USBH_STATUS_TIMEOUT.
Comments
On default the bus driver selects the configuration defined by the configuration descriptor with
the index 0 during the enumeration. As long as the application uses this configuration there is
no need to call this function.
When a new configuration is set the bus driver performs a complete new enumeration with the
device. This causes a remove event for all interfaces of the device. All handles to an interface
84 USB Bus Driver Reference Manual

8 USB Bus Driver Reference
of the device and their corresponding interface IDs will become invalid. The caller should
abort all pending requests and close all handles to the interfaces of the device.
After enumeration with the new configuration all interfaces of the device get new interface
IDs. If the caller has registered for PnP notification for the interfaces of the device he will get
an arrival event for each interface. To register for PnP notification use the function
USBH_RegisterPnPNotification.
This is a blocking function.
See Also
USBH_AbortEndpointAndWait (page 76)
USBH_CloseInterface (page 54)
USBH_RegisterPnPNotification (page 47)
USB Bus Driver Reference Manual 85

8 USB Bus Driver Reference
USBH_SetInterfaceAndWait
This function issue a set interface request to set the given alternate setting and waits until the
URB with the set interface request is completed or a timeout error has been occurred.
Definition
USBH_STATUS
USBH_SetInterfaceAndWait(
USBH_INTERFACE_HANDLE interfaceHandle,
unsigned char alternateSetting,
unsigned long timeout,
TAL_EventObject waitEvent
);
Parameters
interfaceHandle
This parameter specifies the interface by its interface handle.
alternateSetting
The alternate setting to set.
timeout
The timeout for the request in milliseconds.
waitEvent
An event object used to wait for the completion of the request. This parameter is optional and
can be NULL. If the parameter is NULL the function allocates an event object on its own and
frees it before the function returns. With this parameter the caller can optimize the number of
event allocations.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. When the timeout expires before the request is completed the request is
aborted and the function returns USBH_STATUS_TIMEOUT.
Comments
To set a new alternate setting for the specified interface there must be no pending requests on
any endpoint of this interface. Call USBH_AbortEndpointAndWait to abort all pending
requests on an endpoint.
The interface handle does not becomes invalid during this operation. The number of endpoints
may be changed.
86 USB Bus Driver Reference Manual

See Also
USBH_AbortEndpointAndWait (page 76)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 87

8 USB Bus Driver Reference
USBH_SetupRequestAndWait
This function sends a setup request to the device and waits until the URB with the setup request
is completed or a timeout error has been occurred.
Definition
USBH_STATUS
USBH_SetupRequestAndWait(
USBH_INTERFACE_HANDLE interfaceHandle,
T_UsbSetupPacket* setup,
void* buffer,
T_UINT16* length,
unsigned long timeout,
TAL_EventObject waitEvent
);
Parameters
interfaceHandle
This parameter specifies the interface by its interface handle.
setup
The setup packet for the request. The setup packet need not be allocated as DMA capable
memory. The driver takes care to use DMA capable memory if necessary.
buffer
Pointer to a caller provided buffer that is used in the data phase to transfer data. This
parameter is optional and can be NULL. The direction of the data transfer depends on the
bmRequestType fiel in the setup packet. See the USB specification for detailed
information. The memory of the buffer need not be allocated as DMA capable memory. The
driver takes care to use DMA capable memory if necessary.
length
Pointer to a caller provided variable. This is an input and output parameter. On input it
contains the size of the buffer. On output the number of bytes transferred during the data phase
are returned. The parameter can be NULL if buffer is NULL.
timeout
The timeout for the request in milliseconds.
waitEvent
An event object used to wait for the completion of the request. This parameter is optional and
can be NULL. If the parameter is NULL the function allocates an event object on its own and
frees it before the function returns. With this parameter the caller can optimize the number of
event allocations.
88 USB Bus Driver Reference Manual

Return Value
8 USB Bus Driver Reference
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. When the timeout expires before the request is completed the request is
aborted and the function returns USBH_STATUS_TIMEOUT.
Comments
A setup request consists of a setup phase, an optional data phase and a handshake phase. The
data phase is limited to a length of 4096 bytes. The Setup structure must be filled in
properly. The wLength field in the Setup must contain the size of the buffer.
This function can be used to send any standard, class or vendor specific request to the device.
Even standard requests like SetAddress can be send but would destroy the multiplexing of the
bus driver. It is not allowed to send the following standard requests:
SetAddress
This is assigned by the bus driver during enumeration or USB reset.
Clear Feature Endpoint Halt
Use USBH_ResetEndpointAndWait instead.
SetConfiguration
Use USBH_SetConfigurationAndWait instead. The bus driver has to take care on
the interfaces and endpoints of a configuration. The function
USBH_SetConfigurationAndWait updates the internal structures of the driver.
See Also
USBH_ResetEndpointAndWait (page 80)
USBH_SetConfigurationAndWait (page 84)
USB Bus Driver Reference Manual 89

8 USB Bus Driver Reference
8.2 Structures
USBH_INTERFACE_MASK
This data structure is used to describe a device.
Definition
typedef struct tag_USBH_INTERFACE_MASK{
unsigned short Mask;
unsigned short VID;
unsigned short PID;
unsigned short bcdDevice;
T_UINT8 Interface;
T_UINT8 AlternateSetting;
T_UINT8 Class;
T_UINT8 SubClass;
T_UINT8 Protocol;
USBH_DEVICE_ID DeviceID;
} USBH_INTERFACE_MASK;
Members
Mask
This member contains an or’ ed selection of the following flags. If the flag is set the related
member of this structure is compared to the properties of the USB interface.
USBH_INFO_MASK_VID
Compare the vendor ID (VID) of the device.
USBH_INFO_MASK_PID
Compare the product ID (PID) of the device.
USBH_INFO_MASK_DEVICE
Compare the bcdDevice value of the device.
USBH_INFO_MASK_INTERFACE
Compare the interface number.
USBH_INFO_MASK_ALTERNATE
Compare the alternate setting.
USBH_INFO_MASK_CLASS
Compare the class of the interface.
USBH_INFO_MASK_SUBCLASS
Compare the sub class of the interface.
USBH_INFO_MASK_PROTOCOL
Compare the protocol of the interface.
USBH_INFO_MASK_DEVICE_ID
Compare the device ID.
USBH_INFO_MASK_DEFAULT
The notification handler is called when a new device is plugged in and no other registered
info mask do match.
90 USB Bus Driver Reference Manual

VID
This member contains the vendor ID to be compared.
PID
This member contains the product ID to be compared.
bcdDevice
This member contains the BCD coded device version to be compared.
Interface
This member contains the interface number to be compared.
AlternateSetting
This member contains the alternate setting to be compared.
Class
This member describes the class code stored in the interface.
SubClass
This member describes the sub class code stored in the interface.
Protocol
This member describes the protocol stored in the interface.
DeviceID
The member contains the device ID to be compared.
Comments
8 USB Bus Driver Reference
This data structure is an input parameter to create an interface list or to register a PnP
notification. The comparison with the mask is true if each member that is marked as valid by a
flag in the Mask member is equal to the value stored in the corresponding value in the device
(the device match the description defined with this structure).
When creating an interface list only devices that match the description defined with this
structure will be in the list. Similarly when used for registering of a PnP notification only
devices that match the description defined with the structure will get a notification.
See Also
USBH_CreateInterfaceList (page 41)
USBH_RegisterPnPNotification (page 47)
USB Bus Driver Reference Manual 91

8 USB Bus Driver Reference
USBH_INTERFACE_INFO
This structure contains information about a USB interface and the related device.
Definition
typedef struct tag_USBH_INTERFACE_INFO{
USBH_INTERFACE_ID InterfaceID;
USB_DEVICE_ID DeviceID;
T_UINT16 VID;
T_UINT16 PID;
T_UINT16 bcdDevice;
T_UINT8 Interface;
T_UINT8 Class;
T_UINT8 SubClass;
T_UINT8 Protocol;
T_UINT32 OpenCount;
T_UINT8 ExclusiveUsed;
USB_SPEED Speed;
T_UINT8 SerialNumber[256];
T_UINT8 SerialNumberSize;
} USBH_INTERFACE_INFO;
Members
InterfaceID
This member contains the unique interface ID. This ID is assigned if the USB device has been
successfully enumerated. It is valid until the device is removed from the host. If the device is
reconnected a different interface ID is assigned to each interface.
DeviceID
This member contains the unique device ID. This ID is assigned if the USB device has been
successfully enumerated. It is valid until the device is removed from the host. If the device is
reconnected a different device ID is assigned. The relation between the device ID and the
interface ID can be used by an application to detect which USB interfaces belong to a device.
VID
This member contains the vendor ID.
PID
This member contains the product ID.
bcdDevice
This member contains the BCD coded device version.
Interface
This member contains the USB interface number.
Class
This member specifies the interface class.
92 USB Bus Driver Reference Manual

SubClass
This member specifies the interface sub class.
Protocol
This member specifies the interface protocol.
OpenCount
This member specifies the number of open handles for this interface.
ExclusiveUsed
This member determines if this interface is used exclusive.
8 USB Bus Driver Reference
Speed
This member is of type USBH_SPEED and specifies the operation speed of this interface.
SerialNumber[256]
This member contains the serial number as a counted UNICODE string.
SerialNumberSize
This member contains the length of the serial number in bytes.
Comments
This structure is used to get information about a device with the function
USBH_GetInterfaceInfo.
See Also
USBH_SPEED (page 113)
USBH_GetInterfaceInfo (page 44)
USB Bus Driver Reference Manual 93

8 USB Bus Driver Reference
USBH_ENUM_ERROR
This structure contains information about an enumeration error.
Definition
typedef struct tag_USBH_ENUM_ERROR{
int Flags;
int PortNumber;
USBH_STATUS Status;
int ExtendedErrorInformation;
} USBH_ENUM_ERROR;
Members
Flags
Additional flags to determine the location and the type of the error.
UDB_ENUM_ERROR_EXTHUBPORT_FLAG
means the device is connected to an external hub.
USBH_ENUM_ERROR_RETRY_FLAG
the bus driver retries the enumeration of this device automatically.
USBH_ENUM_ERROR_STOP_ENUM_FLAG
the bus driver does not restart the enumeration for this device because all retries have
failed. The application can force the bus driver to restart the enumeration by calling the
function USBH_RestartEnumError.
USBH_ENUM_ERROR_DISCONNECT_FLAG
means the device has been disconnected during the enumeration. If the hub port reports a
disconnect state the device cannot be re-enumerated by the bus driver automatically. Also
the function USBH_RestartEnumError cannot re-enumerate the device.
USBH_ENUM_ERROR_ROOT_PORT_RESET
means an error during the USB reset of a root hub port occurs.
USBH_ENUM_ERROR_HUB_PORT_RESET
means an error during a reset of an external hub port occurs.
UDB_ENUM_ERROR_INIT_DEVICE
means an error during the device initialization (e.g. no answer to a descriptor request or
failed standard request).
UDB_ENUM_ERROR_INIT_HUB
means the enumeration of an external hub fails.
PortNumber
This is the port number of the parent port where the USB device is connected. A flag in the
Flags field determine if this is an external hub port.
Status
The status of the failed operation.
ExtendedErrorInformation
This is an internal information used for debugging.
94 USB Bus Driver Reference Manual

Comments
8 USB Bus Driver Reference
This data structure is used as a notification parameter for the
USBH_EnumErrorNotification function. This data structure does not contain detailed
information about the device that fails the enumeration because this information is not
available in all phases of the enumeration.
See Also
USBH_EnumErrorNotification (page 49)
USBH_RestartEnumError (page 52)
USB Bus Driver Reference Manual 95

8 USB Bus Driver Reference
USBH_EP_MASK
This structure is used to describe an endpoint.
Definition
typedef struct tag_USBH_EP_MASK{
T_UINT32 Mask;
T_UINT8 Index;
T_UINT8 Address;
T_UINT8 Type;
T_UINT8 Direction;
} USBH_EP_MASK;
Members
Mask
This member contains the information which fields are valid. It is an or’ ed combination of the
following flags:
USBH_EP_MASK_INDEX
The Index is used for comparison.
USBH_EP_MASK_ADDRESS
The Address field is used for comparison.
USBH_EP_MASK_TYPE
The Type field is used for comparison.
USBH_EP_MASK_DIRECTION
The Direction field is used for comparison.
Index
If valid, this member contains the zero based index of the endpoint in the interface.
Address
If valid, this member contains an endpoint address with direction bit.
Type
If valid, this member contains a type.
Direction
If valid, this member specifies a direction. It is one of the following values:
USB_IN_DIRECTION
USB_OUT_DIRECTION
Comments
This data structure is used as an input parameter to get an endpoint descriptor due a call to
USBH_GetEndpointDescriptor. The comparison with the mask is true if each member
96 USB Bus Driver Reference Manual

8 USB Bus Driver Reference
that is marked as valid by a flag in the Mask member is equal to the value stored in the
endpoint. E.g. if the Mask is 0 the first endpoint is returned. If the Mask is set to
USBH_EP_MASK_INDEX the zero based index can be used to address all endpoints.
See Also
USBH_GetEndpointDescriptor (page 62)
USB Bus Driver Reference Manual 97

8 USB Bus Driver Reference
URB_CONTROL_REQUEST
This structure is used to submit a control request.
Definition
typedef struct tag_URB_FUNCTION_CONTROL_REQUEST{
T_UsbSetupPacket Setup;
T_UINT8 Endpoint;
void* Buffer;
T_UINT32 Length;
T_UINT32 Timeout;
void* DMASetupBuffer;
void* DMATransferBuffer;
} URB_CONTROL_REQUEST;
Members
Setup
This member specifies the setup packet. The setup packet need not be allocated as DMA
capable memory. The driver takes care to use DMA capable memory if necessary.
Endpoint
This member specifies the endpoint address with direction bit. Use 0 for default endpoint.
Buffer
Pointer to a caller provided buffer that is used in the data phase to transfer data. This
parameter is optional and can be NULL. The direction of the data transfer depends on the
bmRequestType fiel in the setup packet. See the USB specification for detailed
information. The memory of the buffer need not be allocated as DMA capable memory. The
driver takes care to use DMA capable memory if necessary.
Length
This is an input and output parameter. On input it contains the size of the buffer. On output the
number of bytes transferred during the data phase are returned.
Timeout
This member contains a timeout value in milliseconds. The stack aborts the operation if the
timeout expires. A value of 0 means the timeout is inactive.
DMASetupBuffer
Do not use this member. It is used for internal purposes.
DMATransferBuffer
Do not use this member. It is used for internal purposes.
Comments
A setup request consists of a setup phase, an optional data phase and a handshake phase. The
data phase is limited to a length of 4096 bytes. The Setup structure must be filled in
98 USB Bus Driver Reference Manual

8 USB Bus Driver Reference
properly. The wLength field in the Setup must contain the size of the buffer.
With this request each setup packet can be submitted. Even standard requests like SetAddress
can be send but would destroy the multiplexing of the bus driver. It is not allowed to set the
following standard requests:
SetAddress
This is assigned by the bus driver during enumeration or USB reset.
Clear Feature Endpoint Halt
Use URB_FUNCTION_RESET_ENDPOINT instead. The function
URB_FUNCTION_RESET_ENDPOINT resets the data toggle bit in the host controller
structures.
SetConfiguration
Use URB_SET_CONFIGURATION instead. The bus driver has to take care on the
interfaces and endpoints of a configuration. The function URB_SET_CONFIGURATION
updates the internal structures of the driver.
This request can be used to send any class or vendor specific request.
See Also
URB (page 108)
URB_FUNCTION (page 116)
USB Bus Driver Reference Manual 99

8 USB Bus Driver Reference
URB_BULK_INT_REQUEST
This data structure is used to transfer data from or to a bulk or interrupt endpoint.
Definition
typedef struct tag_URB_BULK_INT_REQUEST{
T_UINT8 Endpoint;
void* Buffer;
T_UINT32 Length;
} URB_BULK_INT_REQUEST;
Members
Endpoint
This member specifies the endpoint address with direction bit.
Buffer
This member is a pointer to a caller provided buffer. The buffer must be DMA memory. For
more information about this memory please see section 5.3 at page 29.
Length
This member contains the size of the buffer and returns the number of bytes transferred. The
size can be set to 0 for write operations to send a zero length packet.
Comments
The buffer size can be larger than the FIFO size but a host controller implementation can
define a maximum size for a buffer that can be handled with one URB. To get a good
performance the application should use two or more buffers.
See Also
URB (page 108)
URB_FUNCTION (page 116)
TAL_AllocateDmaMemory (page 135)
100 USB Bus Driver Reference Manual

URB_ISO_FRAME
This structure is used to define ISO transfer buffers.
Definition
typedef struct tag_URB_ISO_FRAME{
T_UINT32 Offset;
T_UINT32 Length;
USBH_STATUS Status;
} URB_ISO_FRAME;
Members
8 USB Bus Driver Reference
Offset
This member specifies the offset in bytes relative to the beginning of the transfer buffer.
Length
This member contains the length that should be transferred in one frame.
Status
This member contains the status of the operation in this frame. For an OUT endpoint this
status is always success. For an IN endpoint a CRC or Data Toggle error can be reported.
Comments
This data structure is part of URB_ISO_REQUEST. It describes the amount of data that is
transferred in one frame.
See Also
URB_ISO_REQUEST (page 102)
USB Bus Driver Reference Manual 101

8 USB Bus Driver Reference
URB_ISO_REQUEST
This data structure is used to transfer data to an ISO endpoint.
Definition
typedef struct tag_URB_ISO_REQUEST{
T_UINT8 Endpoint;
void* Buffer;
T_UINT32 Length;
T_UINT32 Flags;
T_UINT32 StartFrame;
T_UINT32 Frames;
} URB_ISO_REQUEST;
Members
Endpoint
This member specifies the endpoint address with direction bit.
Buffer
This member is a pointer to a caller provided buffer. The buffer must be DMA memory. For
more information about this memory please see section 5.3 at page 29.
Length
On input this member specifies the size of the user provided buffer. On output it contains the
number of bytes transferred.
Flags
This parameter contains 0 or the following flag:
USBH_ISO_ASAP
If this flag is set the transfer starts as soon as possible and the parameter StartFrame is
ignored.
StartFrame
If the flag USBH_ISO_ASAP is not set this parameter defines the start frame of the transfer.
The StartFrame must be in the future. Use USBH_GetFrameNumber to get the current
frame number and add some time to the current frame number.
Frames
This parameter contains the number of frames that are described with this structure.
Comments
The data structure is defined incompletely. That means the data structure consists of this data
structure of type URB_ISO_REQUEST and an array of data structures of type
URB_ISO_FRAME. The size of the array is defined by the parameter Frames. Use the macro
URB_GET_ISO_URB_SIZE to get the size for an ISO URB.
102 USB Bus Driver Reference Manual

Note that ISO transfer is optional and must be supported by the host controller
implementation.
See Also
URB (page 108)
URB_FUNCTION (page 116)
URB_ISO_FRAME (page 101)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 103

8 USB Bus Driver Reference
URB_ENDPOINT_REQUEST
This structure is used with the requests URB_FUNCTION_RESET_ENDPOINT and
URB_FUNCTION_ABORT_ENDPOINT to specify the endpoint that should be reseted or aborted.
Definition
typedef struct tag_URB_ENDPOINT_REQUEST{
T_UINT8 Endpoint;
} URB_ENDPOINT_REQUEST;
Member
Endpoint
This member specifies the endpoint address.
See Also
URB (page 108)
URB_FUNCTION (page 116)
104 USB Bus Driver Reference Manual

URB_SET_CONFIGURATION
8 USB Bus Driver Reference
This structure is used with the request URB_FUNCTION_SET_CONFIGURATION to specify the
index of the configuration to set.
Definition
typedef struct tag_URB_SET_CONFIGURATION{
T_UINT8 ConfigurationDescriptorIndex;
} URB_SET_CONFIGURATION;
Member
ConfigurationDescriptorIndex
This member specifies the index in the configuration descriptor.
See Also
URB (page 108)
URB_FUNCTION (page 116)
USB Bus Driver Reference Manual 105

8 USB Bus Driver Reference
URB_SET_INTERFACE
This structure is used with the request URB_FUNCTION_SET_INTERFACE to specify the
alternate setting to set.
Definition
typedef struct tag_URB_SET_INTERFACE{
T_UINT8 AlternateSetting;
} URB_SET_INTERFACE;
Member
AlternateSetting
This member specifies the alternate setting.
See Also
URB (page 108)
URB_FUNCTION (page 116)
106 USB Bus Driver Reference Manual

URB_SET_SUSPEND_STATE
This data structure is used to set a power state.
Definition
typedef struct tag_URB_SET_POWER_STATE{
USBH_SUSPEND_STATE PowerState;
} URB_SET_SUSPEND_STATE;
Member
8 USB Bus Driver Reference
PowerState
This member is of type USBH_SUSPEND_STATE and specifies the power state.
Comments
If the device is switched to suspend, there must be no pending requests on the device.
See Also
URB (page 108)
USBH_SUSPEND_STATE (page 119)
URB_FUNCTION (page 116)
USB Bus Driver Reference Manual 107

8 USB Bus Driver Reference
URB
The URB is the basic structure for all asynchronous operations on the bus driver.
Definition
typedef struct tag_URB{
URB_HEADER Header;
union Request;
} URB;
Members
Header
This member contains the URB header of type URB_HEADER. The most important
parameters are the function code stored in the member Function and the callback function
stored in the member Completion.
Request
This member is an union and contains information depending on the specific request type of
the URB_HEADER. The request type of the URB_HEADER is specified with the Function
member in the URB_HEADER. See comments section for further details to this member.
Comments
The following table lists the possible request types, their corresponding URB Function Types
and associated structures that should be used for the Request member of this structure:
Request Type URB Function Type Associated Structure
ControlRequest URB_FUNCTION_CONTROL_REQUEST URB_CONTROL_REQUEST
BulkRequest URB_FUNCTION_BULK_REQUEST URB_BULK_INT_REQUEST
InterruptRequest URB_FUNCTION_INT_REQUEST URB_BULK_INT_REQUEST
IsoRequest URB_FUNCTION_ISO_REQUEST URB_ISO_REQUEST
EndpointRequest URB_FUNCTION_RESET_ENDPOINT URB_ENDPOINT_REQUEST
SetConfiguration URB_FUNCTION_SET_CONFIGURATION URB_SET_CONFIGURATION
SetInterface URB_FUNCTION_SET_INTERFACE URB_SET_INTERFACE
SetSuspendState URB_FUNCTION_SET_POWER_STATE URB_SET_SUSPEND_STATE
All requests that exchange data with the device are using the URB data structure. The caller
has to provide the memory for this structure. There are no special requirements for the
memory of an URB structure. Anyhow there are maybe special requiremts for the memory of
a data transfer buffer within one of the structures used for the Request member. See the
documentation of the structures that can be used for the Request member. The memory of
the URB must be permanent until the completion function is called. This data structure is used
to submit an URB.
See Also
URB_HEADER (page 111)
URB_FUNCTION (page 116)
108 USB Bus Driver Reference Manual

URB_CONTROL_REQUEST (page 98)
URB_BULK_INT_REQUEST (page 100)
URB_ISO_REQUEST (page 102)
URB_ENDPOINT_REQUEST (page 104)
URB_SET_CONFIGURATION (page 105)
URB_SET_INTERFACE (page 106)
URB_SET_SUSPEND_STATE (page 107)
8 USB Bus Driver Reference
USB Bus Driver Reference Manual 109

8 USB Bus Driver Reference
USBH_PNP_NOTIFICATION
This structure defines a PnP notification.
Definition
typedef struct tag_USBH_PNP_NOTIFICATION{
USBH_PnpNotification* PnpNotification;
void* Context;
USBH_INTERFACE_MASK InterfaceMask;
} USBH_PNP_NOTIFICATION;
Members
PnpNotification
This member contains the notification function that is called from the USB Bus Driver Core if
a PnP event occurs.
Context
This member contains the notification context that is passed unchanged to the notification
function.
InterfaceMask
This member is of type USBH_INTERFACE_MASK and contains a mask describing the
interfaces for which the PnP notification should be called.
Comments
This data structure is used as an input parameter for the
USBH_RegisterPnPNotification function.
See Also
USBH_INTERFACE_MASK (page 90)
USBH_RegisterPnPNotification (page 47)
110 USB Bus Driver Reference Manual

URB_HEADER
This data structure defines a URB header.
Definition
typedef struct tag_URB_HEADER{
URB_FUNCTION Function;
USBH_STATUS Status;
URB_COMPLETION* Completion;
void* Context;
DLIST ListEntry;
} URB_HEADER;
Members
8 USB Bus Driver Reference
Function
This member is of type URB_FUNCTION and describes the type of the request.
Status
After completion of the corresponding URB this member contains the status for the request.
Completion
This is a pointer to the caller provided completion function which will be called if the function
USBH_SubmitUrb returns USBH_STATUS_PENDING. If a different status code is returned
the completion function is never called.
Context
This member can be used by the caller to store a context for the completion routine. This
context is passed unchanged to the completion routine.
ListEntry
This member is a list entry and can be used to keep the URB in a list. The owner of the URB
can use this list entry. If the URB is passed to the USB Bus Driver Core the USB Bus Driver
Core takes ownership of the URB and this member is changed and in use until the URB is
completed. Therefor this member must not be in use when the URB is passed to the USB Bus
Driver Core (e.g. the URB must not be linked in a list). You may get corrupted data structures
if this member is in use when passing the URB to the USB Bus Driver Core.
Comments
There are additional members which are for internal use only and therefore not described here.
A caller is not allowed to use these members. A caller must only provide the members
Function, Completion, and if required Context.
See Also
URB_COMPLETION (page 73)
USB Bus Driver Reference Manual 111

8 USB Bus Driver Reference
URB_FUNCTION (page 116)
URB (page 108)
USBH_SubmitUrb (page 74)
USBH_STATUS_PENDING (page 123)
112 USB Bus Driver Reference Manual

USBH_SPEED
8 USB Bus Driver Reference
This enumeration defines some constants that represents the speed at which a device is operating.
Definition
typedef enum tag_USBH_SPEED{
USBH_SPEED_UNKNOWN,
USBH_LOW_SPEED,
USBH_FULL_SPEED,
USBH_HIGH_SPEED
} USBH_SPEED;
Entries
USBH_SPEED_UNKNOWN
The speed is unknown.
USBH_LOW_SPEED
The device operates at low speed.
USBH_FULL_SPEED
The device operates at full speed.
USBH_HIGH_SPEED
The device operates at high speed.
Comments
This structure is used as a member in the USBH_INTERFACE_INFO data structure and as a
parameter for the USBH_GetSpeed function.
See Also
USBH_INTERFACE_INFO (page 92)
USBH_GetSpeed (page 66)
USB Bus Driver Reference Manual 113

8 USB Bus Driver Reference
USBH_PNP_EVENT
This enumeration defines the events that are used with PnP notifications.
Definition
typedef enum tag_USBH_PNP_EVENT{
USBH_AddDevice,
USBH_RemoveDevice
} USBH_PNP_EVENT;
Entries
USBH_AddDevice
This event indicates that a device was connected to the host and a new interface is available.
USBH_RemoveDevice
This events indicates that a device has been removed.
Comments
This enumeration type is used as a parameter for the PnP notification.
See Also
USBH_PnpNotification (page 46)
114 USB Bus Driver Reference Manual

USBH_POWER_STATE
This enumeration type specifies some hub port power states.
Definition
typedef enum tag_USBH_POWER_STATE{
USBH_POWER_OFF,
USBH_POWER_ON
} USBH_POWER_STATE;
Entries
USBH_POWER_OFF
The hub port power is switched off.
USBH_POWER_ON
The hub port power is switched on.
Comments
8 USB Bus Driver Reference
This enumeration type is used as a parameter in the USBH_SetPortPowerState function.
See Also
USBH_SetPortPowerState (page 71)
USB Bus Driver Reference Manual 115

8 USB Bus Driver Reference
URB_FUNCTION
This enumeration defines the possible request types for an URB.
Definition
typedef enum tag_URB_FUNCTION{
URB_FUNCTION_CONTROL_REQUEST,
URB_FUNCTION_BULK_REQUEST,
URB_FUNCTION_INT_REQUEST,
URB_FUNCTION_ISO_REQUEST,
URB_FUNCTION_RESET_DEVICE,
URB_FUNCTION_RESET_ENDPOINT,
URB_FUNCTION_ABORT_ENDPOINT,
URB_FUNCTION_SET_CONFIGURATION,
URB_FUNCTION_SET_INTERFACE,
URB_FUNCTION_SET_POWER_STATE
} URB_FUNCTION;
Entries
URB_FUNCTION_CONTROL_REQUEST
This request is used to send a URB with a control request. It uses the data structure
URB_CONTROL_REQUEST. A control request includes standard, class and vendor defined
requests. The standard requests SetConfiguration, SetAddress and SetInterface can not be
submitted by this request. These requests require a special handling in the driver. See
URB_FUNCTION_SET_CONFIGURATION and URB_FUNCTION_SET_INTERFACE for
details.
URB_FUNCTION_BULK_REQUEST
This request is used to transfer data to or from a bulk endpoint. It uses the data structure
URB_BULK_INT_REQUEST.
URB_FUNCTION_INT_REQUEST
This request is used to transfer data to or from an interrupt endpoint. It uses the data structure
URB_BULK_INT_REQUEST. The interval is defined by the endpoint descriptor.
URB_FUNCTION_ISO_REQUEST
This request is used to transfer data to or from an ISO endpoint. It uses the data structure
URB_ISO_FRAME. ISO transfer may not be supported by all host controllers.
URB_FUNCTION_RESET_DEVICE
This request sends a USB reset to the device. This causes a remove event for all interfaces of
the device. After the device is successfully enumerated an arrival event is indicated. All
interfaces get new interface ID’s. This request uses only the URB header, i.e. no special data
structure is required for the request type.
If the driver indicates a device arrival event the device is in a defined state because it is reset
and enumerated by the bus driver. This request can be part of an error recovery or part of
special class protocols like DFU.
116 USB Bus Driver Reference Manual

8 USB Bus Driver Reference
The application should abort all pending requests and close all handles to this device. All
handles become invalid.
URB_FUNCTION_RESET_ENDPOINT
This request clears an error condition on a special endpoint. If a data transfer error occurs that
can not be handled in hardware the bus driver stops the endpoint and does not allow further
data transfers before the endpoint is reset with this function. On a bulk or interrupt endpoint
the host driver sends a Clear Feature Endpoint Halt request. This informs the device about the
hardware error. The driver resets the data toggle bit for this endpoint. This request expects that
no pending URB’s are scheduled on this endpoint. Pending URB’s must be aborted with the
URB based function URB_FUNCTION_ABORT_ENDPOINT. This function uses the data
structure URB_ENDPOINT_REQUEST.
URB_FUNCTION_ABORT_ENDPOINT
This request aborts all pending requests on an endpoint. The host controller calls the
completion function with a status code USBH_STATUS_CANCELED. The completion of the
URB’s may be delayed. The application should wait until all pending requests has been
returned by the driver before the handle is closed or URB_FUNCTION_RESET_ENDPOINT
is called. When this function is called the data toggle bit of the endpoint can get the wrong
value. For that reason the function URB_FUNCTION_RESET_ENDPOINT must be called
before a new data transfer can be started on this endpoint.
This request uses the the data structure URB_ENDPOINT_REQUEST.
URB_FUNCTION_SET_CONFIGURATION
The driver selects the configuration defined by the configuration descriptor with the index 0
during the enumeration. If the application uses this configuration there is no need to call this
function. If the application wants to activate a different configuration this function has to be
called.
The driver performs a complete new enumeration with the device. That means a removal event
is indicated, the enumeration is performed with the new configuration, all interface handles
becomes invalid, all interfaces get a new interface ID and the device is enumerated with the
new configuration. The application should close all interface handles and wait for a new
arrival event.
This request uses the data structure URB_SET_CONFIGURATION.
URB_FUNCTION_SET_INTERFACE
This request selects a new alternate setting for the interface. There must be no pending
requests on any endpoint of this interface. The interface handle does not becomes invalid
during this operation. The number of endpoints may be changed. This request uses the data
structure URB_SET_INTERFACE.
URB_FUNCTION_SET_POWER_STATE
This function is used to set the power state for a device. There must be no pending requests for
this device if the device is set to the suspended state. The request uses the data structure
URB_SET_SUSPEND_STATE. After the enumeration the device is in normal power state.
USB Bus Driver Reference Manual 117

8 USB Bus Driver Reference
Comments
This enumeration type is used with the Function member within the URB_HEADER data
structure.
See Also
URB_HEADER (page 111)
URB_CONTROL_REQUEST (page 98)
URB_BULK_INT_REQUEST (page 100)
URB_ENDPOINT_REQUEST (page 104)
URB_SET_CONFIGURATION (page 105)
URB_SET_INTERFACE (page 106)
URB_SET_SUSPEND_STATE (page 107)
USBH_SubmitUrb (page 74)
118 USB Bus Driver Reference Manual

USBH_SUSPEND_STATE
This enumeration type specifies some power states.
Definition
typedef enum tag_USBH_POWER_STATE{
USBH_NORMAL_POWER,
USBH_SUSPEND
} USBH_SUSPEND_STATE;
Entries
USBH_NORMAL_POWER
The device is switched to normal operation.
USBH_SUSPEND
The device is switched to USB Suspend mode.
Comments
8 USB Bus Driver Reference
This enumeration type is used as a member in the URB_SET_SUSPEND_STATE data
structure.
See Also
URB_SET_SUSPEND_STATE (page 107)
USB Bus Driver Reference Manual 119

8 USB Bus Driver Reference
8.3 Status Codes
Table 1 lists the error codes returned by the USB Bus Driver. A detailed description can be found
in section 8.4 at page 121.
Table 1: Error codes
Error Code Numerical Value
USBH_STATUS_SUCCESS 0x0000
USBH_STATUS_CRC 0x0001
USBH_STATUS_BITSTUFFING 0x0002
USBH_STATUS_DATATOGGLE 0x0003
USBH_STATUS_STALL 0x0004
USBH_STATUS_NOTRESPONDING 0x0005
USBH_STATUS_PID_CHECK 0x0006
USBH_STATUS_UNEXPECTED_PID 0x0007
USBH_STATUS_DATA_OVERRUN 0x0008
USBH_STATUS_DATA_UNDERRUN 0x0009
USBH_STATUS_BUFFER_OVERRUN 0x000C
USBH_STATUS_BUFFER_UNDERRUN 0x000D
USBH_STATUS_NOT_ACCESSED 0x000F
USBH_STATUS_ERROR 0x0101
USBH_STATUS_BUFFER_OVERFLOW 0x0102
USBH_STATUS_INVALID_PARAM 0x0103
USBH_STATUS_PENDING 0x0104
USBH_STATUS_DEVICE_REMOVED 0x0105
USBH_STATUS_CANCELED 0x0106
USBH_STATUS_BUSY 0x0109
USBH_STATUS_INVALID_DESCRIPTOR 0x0110
USBH_STATUS_ENDPOINT_HALTED 0x0111
USBH_STATUS_TIMEOUT 0x0112
USBH_STATUS_PORT 0x0113
USBH_POWER_SWITCHING_NOT_SUPPORTED 0x0114
USBH_STATUS_INVALID_ALIGNMENT 0x0115
USBH_STATUS_NO_MEMORY 0x0116
USBH_STATUS_NO_RESOURCES 0x0117
USBH_STATUS_USER 0x8000
120 USB Bus Driver Reference Manual

8.4 Status Codes Description
USBH_STATUS_SUCCESS (0x0000L)
The operation has been successfully completed.
USBH_STATUS_CRC (0x0001L)
Returned by the hardware. A CRC error occurred.
USBH_STATUS_BITSTUFFING (0x0002L)
Returned by the hardware. A bit stuffing error is occurred.
USBH_STATUS_DATATOGGLE (0x0003L)
Returned by the hardware. A data toggle error is occurred.
USBH_STATUS_STALL (0x0004L)
The device has answered a request with the STALL PID.
USBH_STATUS_NOTRESPONDING (0x0005L)
8 USB Bus Driver Reference
The device has not answered to a request for 3 times. This can happen if the device has disabled
the endpoint (e.g. a watch dog timer has restarted the device) or if there are transmission errors
between the device and the host.
USBH_STATUS_PID_CHECK (0x0006L)
Returned by the hardware. An invalid PID has been received.
USBH_STATUS_UNEXPECTED_PID (0x0007L)
Returned by the hardware. An unexpected PID has been received.
USBH_STATUS_DATA_OVERRUN (0x0008L)
The device has send more data than expected. Possible reasons are:
A device sends more data than defined in the endpoint descriptor.
USB Bus Driver Reference Manual 121

8 USB Bus Driver Reference
The application uses a data buffer with a size that is not a multiple of the FIFO size.
Electrical noise destroys the End Of Packet (EOP) signal and the host does not detect the end
of the data transmission.
USBH_STATUS_DATA_UNDERRUN (0x0009L)
Is used internally, not returned to an application.
USBH_STATUS_BUFFER_OVERRUN (0x000CL)
The device has send more data than expected. Possible reasons are:
A device sends more data than defined in the endpoint descriptor.
The application uses a data buffer with a size that is not a multiple of the FIFO size.
Electrical noise destroys the End Of Packet (EOP) signal and the host does not detect the end
of the data transmission.
USBH_STATUS_BUFFER_UNDERRUN (0x000DL)
Is used internally, not returned to the application.
USBH_STATUS_NOT_ACCESSED (0x000FL)
The USB was not accessed by the host controller.
USBH_STATUS_ERROR (0x0101L)
A generic error code returned by the USB host driver.
USBH_STATUS_BUFFER_OVERFLOW (0x0102L)
The amount of data was larger than the buffer size or the buffer size was not a multiple of the FIFO
size.
USBH_STATUS_INVALID_PARAM (0x0103L)
A parameter passed to the function was invalid.
122 USB Bus Driver Reference Manual

USBH_STATUS_PENDING (0x0104L)
8 USB Bus Driver Reference
The request has been accept by the driver and is now pending. If the operation completes the
completion routine is called and the final status of the operation is returned to the completion
routine.
USBH_STATUS_DEVICE_REMOVED (0x0105L)
The device was removed. All handles to this device are invalid even if the device is connected
again.
USBH_STATUS_CANCELED (0x0106L)
The operation was canceled by the API. This can happen if a handle is closed, the device is
removed or if a request is aborted.
USBH_STATUS_BUSY (0x0109L)
If there are pending requests some operations like SetInterface, returns this error.
USBH_STATUS_INVALID_DESCRIPTOR (0x0110L)
This error can be returned if the device reports descriptors that are not compliant to the USB
specification.
USBH_STATUS_ENDPOINT_HALTED (0x0111L)
An endpoint with bulk or interrupt transfer is halted if a hardware error occurs. Each request that
is send to this endpoint is returned with this status. To enable the endpoint again a reset endpoint
request must be sent.
USBH_STATUS_TIMEOUT (0x0112L)
The operation has been timed out. This is an internal state for enumeration of USB devices.
USBH_STATUS_PORT (0x0113L)
An error on a root hub or hub port. This error occurs if an enabled and connected port changes to
a disabled port status during operation or if an overcurrent on a port occurs.
USB Bus Driver Reference Manual 123

8 USB Bus Driver Reference
USBH_POWER_SWITCHING_NOT_SUPPORTED (0x0114L)
Individually port power switching is not supported from the root hub or hub port.
USBH_STATUS_INVALID_ALIGNMENT (0x0115L)
This is an internal error.
USBH_STATUS_NO_MEMORY (0x0116L)
The operation could not be performed because no memory was available.
USBH_STATUS_NO_RESOURCES (0x0117L)
Not enough resources are available. Examples for resources are events, timers and tasks.
If not enough memory resources are available USBH_STATUS_NO_MEMORY is returned.
USBH_STATUS_USER (0x8000L)
This status code can be used to define user defined status codes. The status codes should be defined
in the form USBH_STATUS_USER + X, where X is an unsigned integer value.
124 USB Bus Driver Reference Manual

9 Register Access Abstraction Layer
9.1 Open Host Controller
HcohcWriteReg
This function write a 32-bit value to a specified register.
Definition
void
HcohcWriteReg(
T_UINT8* base,
T_UINT32 Offset,
T_UINT32 Value
);
Parameters
base
This field specifies the base address of the register space.
Offset
This field specifies the offset of the register.
Value
This field specifies the value that is written.
Comments
This is an abstraction for the OHC register access.
See Also
HcohcReadReg (page 126)
9 Register Access Abstraction Layer
USB Bus Driver Reference Manual 125

9 Register Access Abstraction Layer
HcohcReadReg
This function reads a 32-bit value from a specified register.
Definition
T_UINT32
HcohcReadReg(
T_UINT8* base,
T_UINT32 Offset
);
Parameters
base
This field specifies the base address of the register space.
Offset
This field specifies the offset of the register.
Return Value
This function returns the 32-bit value read from the specified register.
Comments
This is an abstraction for the OHC register access.
See Also
HcohcWriteReg (page 125)
126 USB Bus Driver Reference Manual

10 Abstraction Layer Reference
10.1 API Functions
10 Abstraction Layer Reference
The following functions define the interface of the abstraction layer. They are defined in the file
tal_api.h and must be implemented for your application. The TAL interface is based on ANSI-
C functions. The TAL functions that must be implemented are defined in the file . Each
function can be implemented as a macro in the file or in a C module like .
The TAL interface contains functions in different categories. Each category is described in one of
the following subsections.
10.2 General
Depending from the platform not all functions must be implemented. E.g. TAL_InvalidateCache
must only implemented if a host controller is used that has direct access to the memory (most
host controller) and that memory is cached within the CPU. If not needed a empty macro can be
defined.
USB Bus Driver Reference Manual 127

10 Abstraction Layer Reference
10.3 Initialization and Deinitialization
TAL_Init
This function is used to initialize the TAL layer.
Definition
T_BOOL
TAL_Init();
Return Value
The function returns T_TRUE on success or T_FALSE on error.
Comments
This function must be called one time before any other function of the TAL API is called.
This function is non blocking.
See Also
TAL_Exit (page 129)
128 USB Bus Driver Reference Manual

TAL_Exit
This function is used to free the resources of the TAL layer.
Definition
void
TAL_Exit();
Comments
10 Abstraction Layer Reference
This function frees resources of the TAL layer. All allocated TAL objects like timers, events,
tasks, etc. must be stopped and freed before this function is called.
The function is non blocking.
See Also
TAL_Init (page 128)
USB Bus Driver Reference Manual 129

10 Abstraction Layer Reference
10.4 Dynamically Memory Allocation
TAL_Malloc
This functions allocates the specified size of memory.
Definition
void*
TAL_Malloc(
unsigned long Size
);
Parameter
Size
Number of bytes to allocate. This parameter must be greater than 0.
Return Value
The function returns a void pointer to the allocated memory or NULL if there is not enough
memory available.
Comments
The malloc function allocates a memory block of at least size bytes. The returned pointer is
aligned to the size of a unsigned int variable. The memory is accessible in all context’s the
Embedded USB Host Stack is called. If the memory is no longer used it should be freed with
the function TAL_Free.
This function is non blocking.
See Also
TAL_Free (page 131)
TAL_BuildDmaMd (page 140)
130 USB Bus Driver Reference Manual

TAL_Free
This function frees a memory block.
Definition
void
TAL_Free(
void* MemBlock
);
Parameter
10 Abstraction Layer Reference
MemBlock
Pointer to a previously allocated memory block return by the function TAL_Malloc. The
pointer must not be NULL.
Comments
A memory block must be freed exactly one time.
This function is non blocking.
See Also
TAL_Malloc (page 130)
USB Bus Driver Reference Manual 131

10 Abstraction Layer Reference
10.5 Descriptor Memory Allocation
TAL_AllocateDmaDescMemory
Allocating of physical contiguous non-paged memory.
Definition
void*
TAL_AllocateDmaDescMemory(
unsigned long Size,
unsigned long Alignment,
unsigned long* PhysicalAddress
);
Parameters
Size
Bytes to allocate.
Alignment
Specifies the alignment of the returned memory pointer in bytes.
PhysicalAddress
Returns the physical address of the memory.
Return Value
The function returns a void pointer to the allocated virtual address space or NULL if there is
no memory with the requested properties available.
Comments
This function is used to allocate memory that is used for DMA descriptors. The memory is
physically contiguous and non-cached. The requested memory must be freed with the function
TAL_FreeDmaDescMemory if it is not longer used.
This function is non blocking.
See Also
TAL_FreeDmaDescMemory (page 133)
132 USB Bus Driver Reference Manual

TAL_FreeDmaDescMemory
This function frees a memory block.
Definition
void
TAL_FreeDmaDescMemory(
void* VirtualAddress
);
Parameter
10 Abstraction Layer Reference
VirtualAddress
Points to a virtual address previously allocated by a call to TAL_AllocateDmaDescMemory.
Comments
This function is non blocking.
See Also
TAL_AllocateDmaDescMemory (page 132)
USB Bus Driver Reference Manual 133

10 Abstraction Layer Reference
10.6 DMA Memory Allocation
TAL_GetCacheLineSize
The TAL_GetCacheLineSize routine returns the cache line size.
Definition
unsigned long
TAL_GetCacheLineSize();
Return Value
Is the cache line size or 1 if a cache is not used.
Comments
The cache line size is used to allocate memory that starts at a cache line and has a size of
multiple cache lines.
This function is non blocking.
See Also
TAL_AllocateDmaMemory (page 135)
TAL_Malloc (page 130)
134 USB Bus Driver Reference Manual

TAL_AllocateDmaMemory
10 Abstraction Layer Reference
This function allocates memory that can be used for data transfers with DMA capable controllers.
Definition
void*
TAL_AllocateDmaMemory(
unsigned long Size
);
Parameter
Size
Number of bytes to allocate.
Return Value
The function returns a void pointer to the allocated virtual address space or NULL if there is
no memory available.
Comments
The returned memory block is cache line size aligned and the size is a multiple of the cache
line sizes. The memory can be cached and must not be physically contiguously. For more
information about this memory please see section 5.3 at page 29.
The functions TAL_InvalidateCache and TAL_FlushCache can be applied to this
memory. The function TAL_BuildDmaMd can be used to get a memory description list.
This function is non blocking.
See Also
TAL_FreeDmaMemory (page 136)
TAL_InvalidateCache (page 137)
TAL_FlushCache (page 138)
TAL_BuildDmaMd (page 140)
USB Bus Driver Reference Manual 135

10 Abstraction Layer Reference
TAL_FreeDmaMemory
This function frees a memory block that was allocated with TAL_AllocateDmaMemory.
Definition
void
TAL_FreeDmaMemory(
void* VirtualAddress
);
Parameter
VirtualAddress
Points to a virtual address previously allocated by a call to TAL_AllocateDmaMemory.
Comments
This function is non blocking.
See Also
TAL_AllocateDmaMemory (page 135)
136 USB Bus Driver Reference Manual

TAL_InvalidateCache
10 Abstraction Layer Reference
This function invalidates cached memory. The next access to the invalidated memory address
forces the CPU to read the physical memory into the cache.
Definition
void
TAL_InvalidateCache(
void* Address,
unsigned long Length
);
Parameters
Address
Virtual address of the memory that should be invalidated.
Length
Specifies the length in bytes.
Comments
This function is called by the Embedded USB Host Stack before memory is accessed that was
modified by a DMA capable hardware.
If the architecture does not use cached memory this function can be implemented as a void
macro. The cache is typically organized in cache lines. This function must invalidate all cache
lines that are overlapping with the given memory area. The Embedded USB Host Stack takes
care that no other variables are destroyed by invalidating the cache line. The cache line size is
returned by the function TAL_GetCacheLineSize.
This function is non blocking.
See Also
TAL_FlushCache (page 138)
TAL_GetCacheLineSize (page 134)
TAL_AllocateDmaMemory (page 135)
USB Bus Driver Reference Manual 137

10 Abstraction Layer Reference
TAL_FlushCache
This function forces the MMU to write cached memory to the physical memory.
Definition
void
TAL_FlushCache(
void* Address,
unsigned long Length
);
Parameters
Address
Virtual address of the cached memory.
Length
Specifies the length in bytes.
Comments
This function is called before data are transferred with DMA. This makes sure that the DMA
engine find the correct data in the physical memory. If the architecture does not use cached
memory this function can be implemented as a void macro.
This function is non blocking.
See Also
TAL_InvalidateCache (page 137)
TAL_AllocateDmaMemory (page 135)
138 USB Bus Driver Reference Manual

TAL_WriteSync
This function forces the CPU to write the write cache to the memory.
Definition
void
TAL_WriteSync(
void* Address,
unsigned long Length
);
Parameters
Address
Virtual address of the cached memory.
Length
Specifies the length in bytes.
Comments
10 Abstraction Layer Reference
The implementation of this function is required, when the CPU has a write cache. When the
CPU does not use this feature make an empty define for this function. The stack call this
function when ever it is required.
This function is non blocking.
See Also
TAL_InvalidateCache (page 137)
USB Bus Driver Reference Manual 139

10 Abstraction Layer Reference
TAL_BuildDmaMd
The TAL_BuildDmaMd routine builds a memory descriptor list from a given memory buffer.
This list describes the underlying physical pages in the buffer.
Definition
void
TAL_BuildDmaMd(
TAL_MD* MemoryDescriptor
);
Parameter
MemoryDescriptor
Pointer memory descriptor that is used as an input and output parameter. On input the
parameters TAL_MD.Header.VirtAddr and TAL_MD.Header.Length describe the virtual
memory. On output all other parameters are valid.
Comments
The maximum number of physical page entries is equal TAL_TRANSFER_PAGES. The size
of one physical page is TAL_PHYMEM_PAGE_SIZE. The function can be used with
memory that was allocated with TAL_Malloc or TAL_AllocateDmaDescMemory. On error
the returned number of memory pages is zero.
The function is non blocking.
See Also
TAL_MD (page 162)
TAL_Malloc (page 130)
TAL_AllocateDmaDescMemory (page 132)
140 USB Bus Driver Reference Manual

10.7 Timer
Timers are required for the most host controller drivers.
TAL_TimerCallbackRoutine
10 Abstraction Layer Reference
This function is the prototype for a timer callback function which is called if a timeout on a TAL
timer function occurs.
Definition
typedef
void
TAL_TimerCallbackRoutine(
void* Context
);
Parameter
Context
This parameter is the context of the callback routine.
Comments
In the context of this callback function blocking functions must not be called.
See Also
TAL_AllocTimer (page 142)
TAL_StartTimer (page 144)
USB Bus Driver Reference Manual 141

10 Abstraction Layer Reference
TAL_AllocTimer
This routine allocates a timer and returns a handle to this timer.
Definition
TAL_TIMER_HANDLE
TAL_AllocTimer(
TAL_TimerCallbackRoutine* TimerCallbackRoutine,
void* Context
);
Parameters
TimerCallbackRoutine
Pointer to the notification function that is called from the timer.
Context
Context pointer for user information. This pointer is passed unchanged to the notification
function.
Comments
This is needed to synchronize accesses in the Embedded USB Host Stack. Other timers may
be blocked until the notification function returns. For that reason the notification function
should not be blocked for a long time. It is not allowed to call TAL_FreeTimer from the
context of the notification function.
This function is non blocking.
See Also
TAL_FreeTimer (page 143)
TAL_StartTimer (page 144)
TAL_WaitEvent (page 152)
142 USB Bus Driver Reference Manual

TAL_FreeTimer
This routine frees all resources of a timer.
Definition
void
TAL_FreeTimer(
TAL_TIMER_HANDLE TimerHandle
);
Parameter
TimerHandle
Handle to a timer previously allocated by a call to TAL_AllocTimer.
Comments
When this function is called the timer is implicitly canceled.
10 Abstraction Layer Reference
After the timer is canceled the function waits until a pending timer callback associated with
this timer is finished. So after this function returns there is a guarantee that the timer callback
for this timer will not run.
This function is blocking.
Be careful about potential deadlocks. Do not call TAL_FreeTimer while holding a mutex
that is acquired by your timer callback as well.
See Also
TAL_AllocTimer (page 142)
TAL_CancelTimer (page 145)
USB Bus Driver Reference Manual 143

10 Abstraction Layer Reference
TAL_StartTimer
This routine starts a timer.
Definition
void
TAL_StartTimer(
TAL_TIMER_HANDLE TimerHandle,
unsigned long Time
);
Parameters
TimerHandle
Valid TAL timer handle.
Time
Timeout in milliseconds.
Return Value
The function returns T_TRUE if a new timer is started. The function returns T_FALSE when
the timer was running and is restarted.
Comments
The timer is a single shot timer, i.e. the notification function of the timer is called one time
after the Time period has been elapsed. The timer can be started again in the context of the
timer notification function. The TAL_StartTimer function can be called regardless if the
current timer is still active or not. The parameter Time is set as the current timeout value.
The function is non blocking.
See Also
TAL_CancelTimer (page 145)
144 USB Bus Driver Reference Manual

TAL_CancelTimer
This routine stops a timer. It can be called regardless if the timer is active or not.
Definition
void
TAL_CancelTimer(
TAL_TIMER_HANDLE TimerHandle
);
Parameter
TimerHandle
Valid TAL timer handle.
Return Value
10 Abstraction Layer Reference
The function returns T_TRUE if the timer was removed from the timer list. In this case the
timer callback function is not called. The function returns T_FALSE when the timer was not
in the timer list. In this case the timer callback function may be called.
Comments
At the end of the timeout period there is a racing condition between the canceling process and
the notification function. This means the notification function can be started when this
function is called. Since the timer callbacks are not called from the USB Bus Driver Core you
can not use the function USBH_WaitForIdleStack to wait until no timer callbacks will
be called.
The function is non blocking.
See Also
TAL_StartTimer (page 144)
USB Bus Driver Reference Manual 145

10 Abstraction Layer Reference
TAL_GetTime
This function returns a relative time stamp in units of one microsecond.
Definition
unsigned long
TAL_GetTime();
Return Value
The returned time stamp in microseconds.
Comments
A hardware timer should be used to measure the time. The time runs over from 0xffffffff to 0
after 1.1 hours. The timestamp should be used to determine time differences.
The function is non blocking.
146 USB Bus Driver Reference Manual

TAL_Sleep
10 Abstraction Layer Reference
This function suspends the execution of the current thread for a specified interval.
Definition
void
TAL_Sleep(
unsigned int Milliseconds
);
Parameter
Milliseconds
Specifies the time, in milliseconds, for which to suspend execution.
Comments
This function should perform a task switch if possible or call a idle loop function to see if
other work can be done. It must not return until the requested time has been elapsed. But it
can return later.
This function is blocking.
USB Bus Driver Reference Manual 147

10 Abstraction Layer Reference
10.8 Events
The following events are required if a USB class driver is used that implements a synchronous
data transfer. The following class drivers provided by Thesycon implement a synchronous data
transfer and therefor need event objects:
• CDC/ACM Class Driver
• HID Class Driver
• Printer Class Driver
• Mass Storage Class Driver
TAL_AllocEvent
This function creates an event object.
Definition
TAL_EventObject
TAL_AllocEvent();
Return Value
The function returns either a pointer to the event object on success or a NULL pointer if the
creation of the event object failed.
Comments
The initial state of the event object is not signaled. The event object can be a manual or an
auto reset event. The user should not make assumptions about the behavior. This tolerant
definition of the event makes it easier to implement the TAL Layer on different platforms.
The user defined data structure TAL_EventObject can contain any information that is required
to handle the event.
This function is non blocking.
See Also
TAL_FreeEvent (page 149)
TAL_SetEvent (page 150)
148 USB Bus Driver Reference Manual

TAL_FreeEvent
This function releases an event object and frees all associated resources.
Definition
void
TAL_FreeEvent(
TAL_EventObject Event
);
Parameter
Event
Specifies an event previously allocated by a call to TAL_AllocEvent.
Comments
The function must not be called if the event is in use.
This function is non blocking.
See Also
TAL_AllocEvent (page 148)
10 Abstraction Layer Reference
USB Bus Driver Reference Manual 149

10 Abstraction Layer Reference
TAL_SetEvent
This function sets the state of the specified event object to signaled.
Definition
void
TAL_SetEvent(
TAL_EventObject Event
);
Parameter
Event
Pointer to the event object.
Comments
When a event is signaled a task that waits on the event can continue the execution.
This function is non blocking.
See Also
TAL_ResetEvent (page 151)
150 USB Bus Driver Reference Manual

TAL_ResetEvent
This function sets the state of the specified event object to not signaled.
Definition
void
TAL_ResetEvent(
TAL_EventObject Event
);
Parameter
Event
Pointer to the event object.
Comments
The event must be reseted manually.
This function is non blocking.
See Also
TAL_SetEvent (page 150)
10 Abstraction Layer Reference
USB Bus Driver Reference Manual 151

10 Abstraction Layer Reference
TAL_WaitEvent
This function returns when the specified object is in the signaled state or when the timeout
interval has been elapsed.
Definition
unsigned int
TAL_WaitEvent(
TAL_EventObject Event,
unsigned long milliSeconds
);
Parameters
Event
Pointer to the event object.
milliSeconds
Specifies the timeout interval, in milliseconds. If this parameter is TAL_WAIT_INFINITE the
function’s timeout interval never elapses. If TAL_WAIT_INFINITE is set this function returns
only if the event is set to the signaled state.
Return Value
The function returns the following status codes:
TAL_WAIT_TIMEOUT - The timeout interval elapsed and the state of the event object is not
signaled.
TAL_WAIT_SIGNALED - The state of the specified event object is signaled.
Comments
The TAL_WaitEvent function suspends the current task until the event is signaled or the
timeout elapses. If the timeout is 0 the state of the event is immediately returned.
TAL_WaitEvent for one event object instance will never be called by more than one thread
at any given point in time. The caller should not make assumptions about the state of the event
after the TAL_WaitEvent function has been returned. When the function returns with
TAL_WAIT_TIMEOUT the event is not signaled and the caller can wait again on the event.
This function is blocking.
See Also
TAL_SetEvent (page 150)
TAL_ResetEvent (page 151)
152 USB Bus Driver Reference Manual

10.9 Mutex
TAL_AllocMutex
This function creates a mutex object.
Definition
TAL_MutexObject
TAL_AllocMutex();
Return Value
10 Abstraction Layer Reference
The function returns either a pointer to the mutex object on success or a NULL pointer if the
creation of the mutex object failed.
Comments
The initial state of the mutex object is not entered. The mutex object can be entered one time
by a task.
This function is non blocking.
See Also
TAL_FreeMutex (page 154)
TAL_EnterMutex (page 155)
TAL_LeaveMutex (page 156)
USB Bus Driver Reference Manual 153

10 Abstraction Layer Reference
TAL_FreeMutex
This function frees the memory of a valid mutex object.
Definition
void
TAL_FreeMutex(
TAL_MutexObject Mutex
);
Parameter
Mutex
Pointer to the mutex object.
Comments
The function must called with a valid mutex object. The object must not be accessed after it is
freed.
This function is non blocking.
See Also
TAL_AllocMutex (page 153)
TAL_EnterMutex (page 155)
TAL_LeaveMutex (page 156)
154 USB Bus Driver Reference Manual

TAL_EnterMutex
This function enters a mutex to access code that is protected by this object.
Definition
void
TAL_EnterMutex(
TAL_MutexObject Mutex
);
Parameter
Mutex
Pointer to the mutex object.
Comments
10 Abstraction Layer Reference
The function may suspend the calling task when the mutex is used by a different task.
When the mutex is held in any execution path while a blocking function is called this function
must be considered as blocking. It can be considered as non blocking when no blocking
function is called under this mutex.
This function is blocking or non blocking depending on the usage.
See Also
TAL_AllocMutex (page 153)
TAL_FreeMutex (page 154)
TAL_LeaveMutex (page 156)
USB Bus Driver Reference Manual 155

10 Abstraction Layer Reference
TAL_LeaveMutex
This function leaves a code section that is protected by this mutex and allows other tasks to
access this code area.
Definition
void
TAL_LeaveMutex(
TAL_MutexObject Mutex
);
Parameter
Mutex
Pointer to the mutex object.
Comments
The calling task must enter the mutex before it calls this function to leave it. It is not allowed
to call this function without a call to the function TAL_EnterMutex before.
This function is non blocking.
See Also
TAL_AllocMutex (page 153)
TAL_FreeMutex (page 154)
TAL_EnterMutex (page 155)
156 USB Bus Driver Reference Manual

10.10 Task
TAL_CreateTask
This function creates a task.
Definition
TAL_TaskObject
TAL_CreateTask(
TAL_TASK_FUNCTION* taskFunction,
void* context,
unsigned int stackSize,
const char* taskName
);
Parameters
taskFunction
Pointer to the task function.
context
Pointer to the context that is passed to the task function.
stackSize
Stack size in bytes. The value must be larger than zero.
taskName
Pointer to the task name string. Set to NULL if no name is provided.
Return Value
10 Abstraction Layer Reference
The function returns either a pointer to the task object on success or a NULL pointer if
creation of the task failed.
Comments
The task is terminated when the task routine returns. There is no way to kill the task.
This function is non blocking.
See Also
TAL_DeleteTask (page 158)
TAL_WaitTask (page 159)
USB Bus Driver Reference Manual 157

10 Abstraction Layer Reference
TAL_DeleteTask
This function waits until the task function has returned and deletes the task object.
Definition
void
TAL_DeleteTask(
TAL_TaskObject taskObject
);
Parameter
taskObject
Pointer to the task object that was returned by TAL_CreateTask.
Comments
When this function is called by the task it self a dead lock occurs. The function waits infinite
until the task function has returned and than it deletes the task object. See also
TAL_WaitTask.
This function is blocking.
See Also
TAL_CreateTask (page 157)
TAL_WaitTask (page 159)
158 USB Bus Driver Reference Manual

TAL_WaitTask
10 Abstraction Layer Reference
This function waits until the task function has returned, i.e. the task is terminated.
Definition
unsigned int
TAL_WaitTask(
TAL_TaskObject task,
unsigned long timeoutMs
);
Parameters
task
Pointer to the task object that was returned by TAL_CreateTask.
timeoutMs
Timeout value in milliseconds. The function returns after this timeout, when the task function
is not yet returned.
Return Value
The function returns either a TAL_WAIT_SIGNALED or TAL_WAIT_TIMEOUT.
TAL_WAIT_SIGNALED indicates that the task function has returned.
Comments
This function can be used to wait on the completion of a task with timeout. After this function
has returned with TAL_WAIT_SIGNALED the function TAL_DeleteTask must be called
to delete the task object.
This function is blocking.
See Also
TAL_CreateTask (page 157)
TAL_DeleteTask (page 158)
USB Bus Driver Reference Manual 159

10 Abstraction Layer Reference
10.11 Data Structures
TAL_MD_HEADER
The structure represents the memory descriptor header.
Definition
typedef struct T_TAL_MD_HEADER{
void* VirtAddr;
unsigned long Length;
unsigned long NumberOfPages;
} TAL_MD_HEADER;
Members
VirtAddr
Pointer to the base virtual address of the buffer the MDL describes.
Length
Specifies the length in bytes of the buffer the MDL describes.
NumberOfPages
Specifies the number of valid page entries in the memory descriptor TAL_MD.
See Also
TAL_MD_PAGE_ENTRY (page 161)
TAL_MD (page 162)
160 USB Bus Driver Reference Manual

TAL_MD_PAGE_ENTRY
The structure describes one entry of a memory page.
Definition
typedef struct T_TAL_MD_PAGE_ENTRY{
void* VirtAddr;
unsigned long PhyAddr;
unsigned long Length;
} TAL_MD_PAGE_ENTRY;
Members
VirtAddr
Pointer to the virtual address of the page entry.
PhyAddr
Pointer to the physical address of the page entry.
Length
Length in bytes of the page.
See Also
TAL_MD_HEADER (page 160)
TAL_MD (page 162)
10 Abstraction Layer Reference
USB Bus Driver Reference Manual 161

10 Abstraction Layer Reference
TAL_MD
The structure describes a memory descriptor with a fixed memory location list.
Definition
typedef struct T_TAL_MD{
TAL_MD_HEADER Header;
TAL_MD_PAGE_ENTRY Entries[TAL_TRANSFER_PAGES];
} TAL_MD;
Members
Header
This field contains the header of the memory descriptor.
Entries[TAL_TRANSFER_PAGES]
This field contains the memory description list with a maximum number of entries.
Comments
The maximum size of the memory descriptor list limits the size of transfer descriptors that can
be used. The default value defined in usbh_default_config.h should be used.
See Also
TAL_BuildDmaMd (page 140)
162 USB Bus Driver Reference Manual

TAL_TIMER_HANDLE
The type TAL_TIMER_HANDLE is a pointer to the TAL timer object.
Definition
typedef void*{ } TAL_TIMER_HANDLE;
Member
See Also
TAL_AllocTimer (page 142)
TAL_FreeTimer (page 143)
TAL_StartTimer (page 144)
TAL_CancelTimer (page 145)
10 Abstraction Layer Reference
USB Bus Driver Reference Manual 163

11 CDC/ACM Class Driver Reference
11 CDC/ACM Class Driver Reference
11.1 Application programming interface
HCLS_ACM_Init
The function initializes this class.
Definition
T_BOOL
HCLS_ACM_Init();
Return Value
It returns T_TRUE on success or T_FALSE if some resources are not available.
Comments
The function must be called one time before any other API functions of this class driver can be
called. When the class driver is no longer required HCLS_ACM_Exit must be called. If
HCLS_ACM_Exit is not called the class driver has a memory leak.
This function is non blocking.
See Also
HCLS_ACM_Exit (page 165)
164 USB Bus Driver Reference Manual

HCLS_ACM_Exit
The exit function de-registers PnP handler and frees the allocated resources.
Definition
void
HCLS_ACM_Exit();
Comments
11 CDC/ACM Class Driver Reference
This function should be called one time when the class is not longer required. After the
function was called no callbacks are called from this class driver.
This function is blocking.
See Also
HCLS_ACM_Init (page 164)
USB Bus Driver Reference Manual 165

11 CDC/ACM Class Driver Reference
HCLS_ACM_DeviceConnected
Prototype for a callback function that can be called when a device with a CDC ACM interface is
connected to the USB host.
Definition
typedef
void
HCLS_ACM_DeviceConnected(
void* context,
USBH_INTERFACE_ID interfaceID
);
Parameters
context
This is the unchanged context pointer that was passed to the function call
HCLS_ACM_RegisterConnectHandler. It can be used by the application.
interfaceID
The interface ID is an unique identifier for the interface. This identifier can be used to get
more information about the interface. When the device with this interface is disconnected and
reconnected the host stack assigned a different interface ID.
Comments
Do not call any blocking functions in this context. See also the comments in
HCLS_ACM_RegisterConnectHandler.
See Also
HCLS_ACM_RegisterConnectHandler (page 167)
166 USB Bus Driver Reference Manual

HCLS_ACM_RegisterConnectHandler
This function registers a callback function for device connect events.
Definition
USBH_STATUS
HCLS_ACM_RegisterConnectHandler(
HCLS_ACM_DeviceConnected* connectNotification,
void* context
);
Parameters
connectNotification
The address of the callback function that should be called.
11 CDC/ACM Class Driver Reference
context
The context that is passed to the callback function. This can be any user defined pointer or
NULL.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function allows event based notifications for connected class interfaces. When this
function is called the stack calls the callback function immediately for all currently connected
class compliant interfaces. An alternative method to be informed about new devices is the
polling of the available devices with HCLS_ACM_CreateInterfaceList.
To unregister the callback call this function with connectNotification set to NULL.
This function is non blocking.
See Also
HCLS_ACM_CreateInterfaceList (page 168)
HCLS_ACM_DeviceConnected (page 166)
USB Bus Driver Reference Manual 167

11 CDC/ACM Class Driver Reference
HCLS_ACM_CreateInterfaceList
Creates an internal list with interfaces that expose a CDC ACM compliant interface.
Definition
USBH_INTERFACE_LIST_HANDLE
HCLS_ACM_CreateInterfaceList(
unsigned int* InterfaceCount
);
Parameter
InterfaceCount
This parameter returns the number of available interface.
Return Value
It returns a valid list handle on success or NULL if no resources are available.
Comments
The internal list contains a snap shot of the CDC ACM interfaces that were available at the
calling time. The returned handle must be freed with
HCLS_ACM_DestroyInterfaceList. The devices in the list can be enumerated with
HCLS_ACM_GetInterfaceID. The relation of the index and the interface ID in a list is
constant.
This function is non blocking.
See Also
HCLS_ACM_DestroyInterfaceList (page 169)
HCLS_ACM_GetInterfaceID (page 170)
168 USB Bus Driver Reference Manual

HCLS_ACM_DestroyInterfaceList
The function frees the resources that are used for the internal interface list.
Definition
void
HCLS_ACM_DestroyInterfaceList(
USBH_INTERFACE_LIST_HANDLE InterfaceListHandle
);
Parameter
InterfaceListHandle
A list handle that was returned by a successful call to the function
HCLS_ACM_CreateInterfaceList.
Comments
This function should be called when the list is not longer needed.
This function is non blocking.
See Also
HCLS_ACM_CreateInterfaceList (page 168)
11 CDC/ACM Class Driver Reference
USB Bus Driver Reference Manual 169

11 CDC/ACM Class Driver Reference
HCLS_ACM_GetInterfaceID
This function can be used to get the unique interface ID in an interface list.
Definition
USBH_INTERFACE_ID
HCLS_ACM_GetInterfaceID(
USBH_INTERFACE_LIST_HANDLE InterfaceListHandle,
unsigned int Index
);
Parameters
InterfaceListHandle
A list handle that was returned by a successful call to the function
HCLS_ACM_CreateInterfaceList.
Index
Is a number between 0 and InterfaceCount-1. The InterfaceCount is returned by
the function HCLS_ACM_CreateInterfaceList.
Return Value
The function returns the unique interface ID that is stored at the position of index in the list.
Comments
The interface list has a constant relation between the index and interface IDs and it is a snap
shoot of the available interface at the point of time when the list was created. When a device is
disconnected and reconnected it gets new interface IDs. A list can contain interface IDs that
are not longer available on the bus.
This function is non blocking.
See Also
HCLS_ACM_CreateInterfaceList (page 168)
170 USB Bus Driver Reference Manual

HCLS_ACM_GetInterfaceInfo
The function returns additional information to a known interface ID.
Definition
USBH_STATUS
HCLS_ACM_GetInterfaceInfo(
USBH_INTERFACE_ID InterfaceID,
USBH_INTERFACE_INFO* InterfaceInfo
);
Parameters
11 CDC/ACM Class Driver Reference
InterfaceID
The unique interface ID specifies the interface for which additional information should be
returned. The interface ID is returned either by HCLS_ACM_GetInterfaceID or
HCLS_ACM_DeviceConnected.
InterfaceInfo
The caller provides the storage for this structure and retrieves information about the specified
interface.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The additional information can be used to identify the device more exactly e.g. with the PID
or the serial number.
This function is non blocking.
See Also
HCLS_ACM_GetInterfaceID (page 170)
HCLS_ACM_DeviceConnected (page 166)
USBH_INTERFACE_INFO (page 92)
USB Bus Driver Reference Manual 171

11 CDC/ACM Class Driver Reference
HCLS_ACM_DeviceRemoved
Prototype for a callback that is called when a the device with the CDC ACM interface is removed.
Definition
typedef
void
HCLS_ACM_DeviceRemoved(
void* context
);
Parameter
context
The context for the function that was passed to the function call HCLS_ACM_Open.
Comments
A callback of this function can be registered with HCLS_ACM_Open to see when the
corresponding opened interface is removed.
Do not call other blocking functions in this context.
See Also
HCLS_ACM_Open (page 173)
172 USB Bus Driver Reference Manual

HCLS_ACM_Open
11 CDC/ACM Class Driver Reference
This function opens an interface exclusively and optionally registers a remove notification
function.
Definition
USBH_STATUS
HCLS_ACM_Open(
USBH_INTERFACE_ID InterfaceID,
HCLS_ACM_DeviceRemoved* removeNotification,
void* context,
HCLS_ACM_Handle* handle
);
Parameters
InterfaceID
The unique interface ID specifies the interface which should be opened. The interface ID is
returned either by HCLS_ACM_GetInterfaceID or HCLS_ACM_DeviceConnected.
The device with this interface ID may be removed in the meantime. For that reason the open
function can fail with USBH_STATUS_DEVICE_REMOVED.
removeNotification
This parameter is optional. The caller provides the address of a function prototype
HCLS_ACM_DeviceRemoved or NULL. When the caller provides this function pointer and
the open function returns with success, the remove notification function is called when the
device is removed. The function is de-registered and not longer called when the interface is
closed.
context
A user provided context for the remove notification function HCLS_ACM_DeviceRemoved
or NULL.
handle
On success the function returns a handle to the interface that is used for the operational access.
If opening of the specified interface fails the handle will be NULL which is an invalid handle
value.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
When the remove notification function is not used the application can poll the presence of the
device with HCLS_ACM_IsDevicePresent. The returned handle must be closed with
USB Bus Driver Reference Manual 173

11 CDC/ACM Class Driver Reference
HCLS_ACM_Close when it is not longer required. This class does not implement an internal
buffer circulation for the data endpoints. To create IN tokens on the bulk IN endpoint the
application has to pass a buffer with the function HCLS_ACM_Read to the class. After this
function returns with success the class driver service the notification pipe and creates IN
tokens on it.
This function is blocking.
See Also
HCLS_ACM_GetInterfaceID (page 170)
HCLS_ACM_DeviceConnected (page 166)
HCLS_ACM_DeviceRemoved (page 172)
HCLS_ACM_IsDevicePresent (page 176)
HCLS_ACM_Close (page 175)
HCLS_ACM_Read (page 190)
174 USB Bus Driver Reference Manual

HCLS_ACM_Close
The function closes an interface and releases the exclusive use.
Definition
void
HCLS_ACM_Close(
HCLS_ACM_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Comments
11 CDC/ACM Class Driver Reference
The caller has to make sure that all URB buffers that has been passed with HCLS_ACM_Read
and HCLS_ACM_Write has been returned before this function is called. The caller can use
HCLS_ACM_AbortRead and HCLS_ACM_AbortWrite to archive this.
This function is blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_Read (page 190)
HCLS_ACM_Write (page 185)
HCLS_ACM_AbortRead (page 192)
HCLS_ACM_AbortWrite (page 187)
USB Bus Driver Reference Manual 175

11 CDC/ACM Class Driver Reference
HCLS_ACM_IsDevicePresent
The function indicates if the device is present or not.
Definition
T_BOOL
HCLS_ACM_IsDevicePresent(
HCLS_ACM_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Return Value
The function returns T_TRUE when the device is present or T_FALSE when the device is
removed.
Comments
This function is non blocking.
See Also
HCLS_ACM_Open (page 173)
176 USB Bus Driver Reference Manual

HCLS_ACM_GetDeviceStatus
This function returns the device status.
Definition
T_UINT16
HCLS_ACM_GetDeviceStatus(
HCLS_ACM_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Return Value
The function returns a or’ed combination of the following flags:
11 CDC/ACM Class Driver Reference
TUSB_CLS_CDC_NOTIFY_SERIAL_STATE_DCD
The line Data Carrier Detected is signaled.
TUSB_CLS_CDC_NOTIFY_SERIAL_STATE_DSR
The line Data Send Ready is signaled.
TUSB_CLS_CDC_NOTIFY_SERIAL_STATE_BREAK
The device signals a Break.
TUSB_CLS_CDC_NOTIFY_SERIAL_STATE_RING_SIGNAL
The line Ring is signaled.
TUSB_CLS_CDC_NOTIFY_SERIAL_STATE_FRAMING
A framing error in the device has been occurred.
TUSB_CLS_CDC_NOTIFY_SERIAL_STATE_PARITY
A parity error in the device has been occurred.
TUSB_CLS_CDC_NOTIFY_SERIAL_STATE_OVERRUN
A overrun error in the device has been occurred.
HCLS_ACM_SERIAL_STATE_CONNECTED
The device signals TUSB_CLS_CDC_NOTIFY_NETWORK_CONNECTION.
Comments
The information that is returned by this function is stored inside the class driver. The
information is updated internally with the notification endpoint of the class. To get an event
when the status information is changed use the function
HCLS_ACM_RegisterStatusChangeHandler.
This function is non blocking.
USB Bus Driver Reference Manual 177

11 CDC/ACM Class Driver Reference
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_RegisterStatusChangeHandler (page 180)
178 USB Bus Driver Reference Manual

HCLS_ACM_DeviceStatusChanged
11 CDC/ACM Class Driver Reference
Prototype of a callback that is called by the class driver when the device status has been changed.
Definition
typedef
void
HCLS_ACM_DeviceStatusChanged(
void* context,
T_UINT16 state
);
Parameters
context
The context that was passed to HCLS_ACM_RegisterStatusChangeHandler.
state
This parameter contains the or’ed combination of the device status. See
HCLS_ACM_GetDeviceStatus for a definition of the bits.
Comments
This function prototype can be registered with
HCLS_ACM_RegisterStatusChangeHandler to receive notifications when the device
status changes. It is not allowed to call blocking functions of the stack in the context of this
call back function.
See Also
HCLS_ACM_RegisterStatusChangeHandler (page 180)
HCLS_ACM_GetDeviceStatus (page 177)
USB Bus Driver Reference Manual 179

11 CDC/ACM Class Driver Reference
HCLS_ACM_RegisterStatusChangeHandler
This function registers or unregisters a status change notification handler.
Definition
void
HCLS_ACM_RegisterStatusChangeHandler(
HCLS_ACM_Handle handle,
HCLS_ACM_DeviceStatusChanged* statusNotification,
void* context
);
Parameters
handle
The handle returned by HCLS_ACM_Open.
statusNotification
A pointer to a function with the prototype of HCLS_ACM_DeviceStatusChanged to
register a notification call back function or NULL to unregister it.
context
A user defined context that is passed to the notification call back function or NULL if not used.
Comments
When a notification function was registered it must be unregistered before that interface is
closed. The application can register one notification function per interface.
This function is non blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_DeviceStatusChanged (page 179)
180 USB Bus Driver Reference Manual

HCLS_ACM_SetLineCoding
This function sets the line coding in the device.
Definition
USBH_STATUS
HCLS_ACM_SetLineCoding(
HCLS_ACM_Handle handle,
HCLS_ACM_LineCoding* lineCoding
);
Parameters
handle
The handle returned by HCLS_ACM_Open.
11 CDC/ACM Class Driver Reference
lineCoding
A pointer to a caller provided and initialized data structure that contains the line coding to be
set.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function sends the class request TUSB_CLS_CDC_REQ_SET_LINE_CODING to the
device. When the device fails the operation the function returns an error. The application may
decide to ignore the error and avoid the sending of this request.
This function is blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_LineCoding (page 194)
HCLS_ACM_SetControlLineState (page 182)
USB Bus Driver Reference Manual 181

11 CDC/ACM Class Driver Reference
HCLS_ACM_SetControlLineState
This function sets the control lines of the host.
Definition
USBH_STATUS
HCLS_ACM_SetControlLineState(
HCLS_ACM_Handle handle,
T_UINT16 lineState
);
Parameters
handle
The handle returned by HCLS_ACM_Open.
lineState
This parameter contains a or’ed combination of the following flags:
TUSB_CLS_CDC_SET_CONTROL_LINE_STATE_DTR
Set this to signal Data Terminal Ready.
TUSB_CLS_CDC_SET_CONTROL_LINE_STATE_RTS
Set this to signal Request To Send.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function sends the class request
TUSB_CLS_CDC_REQ_SET_CONTROL_LINE_STATE to the device. When the device
fails the operation the function returns an error. The application may decide to ignore the error
and avoid the sending of this request.
This function is blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_SendBreak (page 183)
HCLS_ACM_SetLineCoding (page 181)
182 USB Bus Driver Reference Manual

HCLS_ACM_SendBreak
This function sends a Break signal to the device.
Definition
USBH_STATUS
HCLS_ACM_SendBreak(
HCLS_ACM_Handle handle,
T_UINT16 breakSignal
);
Parameters
handle
The handle returned by HCLS_ACM_Open.
11 CDC/ACM Class Driver Reference
breakSignal
A parameter between 1 and 0xfffe describes the duration of the break signal in milliseconds.
A value of 0xffff turns the break signal on. A value of 0 turns the break signal off.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function sends the class request TUSB_CLS_CDC_REQ_SEND_BREAK to the device.
When the device fails the operation the function returns an error. The application may decide
to ignore the error and avoid the sending of this request.
This function is blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_SetControlLineState (page 182)
HCLS_ACM_SetLineCoding (page 181)
USB Bus Driver Reference Manual 183

11 CDC/ACM Class Driver Reference
HCLS_ACM_GetWriteFifoSize
This function returns the FIFO size in bytes of the write endpoint.
Definition
T_UINT16
HCLS_ACM_GetWriteFifoSize(
HCLS_ACM_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Return Value
The write FIFO size of the bulk OUT endpoint.
Comments
The returned value can be used to calculate whether a zero length packet must be sent.
The function is non blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_Read (page 190)
184 USB Bus Driver Reference Manual

HCLS_ACM_Write
This function submits an URB with a transfer buffer to the stack.
Definition
USBH_STATUS
HCLS_ACM_Write(
HCLS_ACM_Handle handle,
URB* urb
);
Parameters
handle
The handle returned by HCLS_ACM_Open.
11 CDC/ACM Class Driver Reference
urb
A pointer to a caller provided and initialized URB structure. The caller provides the header
and the URB_BULK_INT_REQUEST information. The class driver adds the endpoint to the
request.
Return Value
The function returns USBH_STATUS_PENDING on success or an appropriate error code
otherwise.
Comments
The submitted URB and the related data transfer buffer is passed to the driver stack with this
function call. When the function returns the status USBH_STATUS_PENDING the URB is
queued for processing in the stack. The caller must neither free the buffer or the URB nor
access it as long as the ownership is at the stack. It has to wait until the callback function
provided in the URB header is called. The write operation can be delayed for an infinite time
by the device. The application can abort the operation with HCLS_ACM_AbortWrite.
After this function is called the application has to wait until the completion routine is called.
The buffer memory that is passed in URB.Request.BulkIntRequest.Buffer must be
DMA memory. For more information about this memory please see section 5.3 at page 29.
If the device expects a short packet termination of data chunks, the caller must take care on
this. When the size of the data chunk can be divided by the FIFO size without rest the caller
has to send a zero length packet.
The function is non blocking. It can be called in the context of the completion routine of the
URB. But the caller should check the status value of the returned request. When the request
fails the caller should not re-submit the URB to the stack to avoid endless loops.
USB Bus Driver Reference Manual 185

11 CDC/ACM Class Driver Reference
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_GetWriteFifoSize (page 184)
URB (page 108)
HCLS_ACM_AbortWrite (page 187)
TAL_AllocateDmaMemory (page 135)
186 USB Bus Driver Reference Manual

HCLS_ACM_AbortWrite
The function aborts all write requests on the specified interface.
Definition
USBH_STATUS
HCLS_ACM_AbortWrite(
HCLS_ACM_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Return Value
11 CDC/ACM Class Driver Reference
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function starts the abort process for all pending write requests. Typically the abort process
is delayed. The caller has to wait until the completion routine for all pending URBs is called.
The stack sets the status in the canceled URBs to USBH_STATUS_CANCELED.
After a write operation has been canceled it cannot be determined how many data has been
transferred to the device. Furthermore the data toggle mechanism to the device may be out of
order. For that reason the caller should used the function HCLS_ACM_ResetWritePipe to
clear all error conditions before the next write operation is started.
This function is blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_Write (page 185)
HCLS_ACM_ResetWritePipe (page 188)
USB Bus Driver Reference Manual 187

11 CDC/ACM Class Driver Reference
HCLS_ACM_ResetWritePipe
The functions resets the write pipe.
Definition
USBH_STATUS
HCLS_ACM_ResetWritePipe(
HCLS_ACM_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function resets the write endpoint. It sends a Clear Feature Endpoint Halt request for the
write endpoint to the device. It resets the data toggle bits and clears any other error state in the
driver stack and in possibly connected external hubs.
When the function is called no pending requests on this endpoint are allowed.
The function is blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_Write (page 185)
HCLS_ACM_AbortWrite (page 187)
188 USB Bus Driver Reference Manual

HCLS_ACM_GetReadFifoSize
This function returns the FIFO size in bytes of the read endpoint.
Definition
T_UINT16
HCLS_ACM_GetReadFifoSize(
HCLS_ACM_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Return Value
The read FIFO size of the bulk IN endpoint.
Comments
11 CDC/ACM Class Driver Reference
The returned value can be used to calculate a valid buffer size for the read operation.
The function is non blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_Read (page 190)
USB Bus Driver Reference Manual 189

11 CDC/ACM Class Driver Reference
HCLS_ACM_Read
This function submits an URB with a transfer buffer to the stack.
Definition
USBH_STATUS
HCLS_ACM_Read(
HCLS_ACM_Handle handle,
URB* urb
);
Parameters
handle
The handle returned by HCLS_ACM_Open.
urb
A pointer to a caller provided and initialized URB structure. The caller provides the header
and the URB_BULK_INT_REQUEST information. The class driver adds the endpoint to the
request.
Return Value
The function returns USBH_STATUS_PENDING on success or an appropriate error code
otherwise.
Comments
The submitted URB and the related data transfer buffer is passed to the driver stack with this
function call. When the function returns the status USBH_STATUS_PENDING the URB is
queued for processing in the stack. The caller must neither free the buffer or the URB nor
access it as long as the ownership is at the stack. It has to wait until the callback function
provided in the URB header is called.
When the first read buffer is submitted to the stack the driver starts to send IN tokens to the
bulk IN endpoint of the CDC/ACM interface. When no buffer for this endpoint is pending the
driver does not send IN tokens to it. The buffer size should be a multiple of the FIFO size.
This avoids buffer overrun errors. The device should terminate each data chunk with a short
packet. When the device is not able to terminate each data chunk with a short packet the
application should use buffers with the FIFO size of the bulk IN endpoint. But note: We
recommend to use larger buffer to archive a good performance.
The application can call HCLS_ACM_AbortRead to abort all pending buffers. After this
function is called the application has to wait until the completion routine of the aborted buffers
is called.
The buffer memory that is passed in URB.Request.BulkIntRequest.Buffer must be
DMA memory. For more information about this memory please see section 5.3 at page 29.
190 USB Bus Driver Reference Manual

11 CDC/ACM Class Driver Reference
The function is non blocking. It can be called in the context of the completion routine of the
URB. But the caller should check the status value of the returned request. When the request
fails the caller should not re-submit the URB to the stack to avoid endless loops.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_GetReadFifoSize (page 189)
URB (page 108)
HCLS_ACM_AbortRead (page 192)
TAL_AllocateDmaMemory (page 135)
USB Bus Driver Reference Manual 191

11 CDC/ACM Class Driver Reference
HCLS_ACM_AbortRead
The function aborts all read requests on the specified interface.
Definition
USBH_STATUS
HCLS_ACM_AbortRead(
HCLS_ACM_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function starts the abort process for all pending read requests. Typically the abort process
is delayed. The caller has to wait until the completion routine for all pending URBs is called.
The stack sets the status in the canceled URBs to USBH_STATUS_CANCELED.
After a read operation has been canceled it cannot be determined how many data has been
transferred from the device. Furthermore the data toggle mechanism to the device may be out
of order. For that reason the caller should used the function HCLS_ACM_ResetReadPipe
to clear all error conditions before the next read operation is started.
This function is blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_Read (page 190)
HCLS_ACM_ResetReadPipe (page 193)
192 USB Bus Driver Reference Manual

HCLS_ACM_ResetReadPipe
The functions resets the read pipe.
Definition
USBH_STATUS
HCLS_ACM_ResetReadPipe(
HCLS_ACM_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Return Value
11 CDC/ACM Class Driver Reference
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function resets the read endpoint. It sends a Clear Feature Endpoint Halt request for the
read endpoint to the device. It resets the data toggle bits and clears any other error state in the
driver stack and in possibly connected external hubs.
When the function is called no pending requests on this endpoint are allowed.
The function is blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_ACM_Read (page 190)
HCLS_ACM_AbortRead (page 192)
USB Bus Driver Reference Manual 193

11 CDC/ACM Class Driver Reference
11.2 Structures
HCLS_ACM_LineCoding
This structure describes the line coding of the serial port.
Definition
typedef struct tagHCLS_ACM_LineCoding{
T_UINT32 dwDTERate;
T_UINT8 bCharFormat;
T_UINT8 bParityType;
T_UINT8 bDataBits;
} HCLS_ACM_LineCoding;
Members
dwDTERate
Data terminal rate in bits per second.
bCharFormat
The format of the characters. It means the number of stop bits.
TUSB_CLS_CDC_SET_LINE_CODING_STOP_1
One stop bit.
TUSB_CLS_CDC_SET_LINE_CODING_STOP_1_5
One and a half stop bit.
TUSB_CLS_CDC_SET_LINE_CODING_STOP_2
Two stop bits.
bParityType
The parity of the transfer.
TUSB_CLS_CDC_SET_LINE_CODING_PARITY_NONE
Use no parity.
TUSB_CLS_CDC_SET_LINE_CODING_PARITY_ODD
Use odd parity.
TUSB_CLS_CDC_SET_LINE_CODING_PARITY_EVEN
Use even parity.
TUSB_CLS_CDC_SET_LINE_CODING_PARITY_MARK
Use mark parity.
TUSB_CLS_CDC_SET_LINE_CODING_PARITY_SPACE
Use space parity.
bDataBits
This parameter describes the number of data bits on the physical interface and can be 5,6,7,8,
or 16.
194 USB Bus Driver Reference Manual

Comments
11 CDC/ACM Class Driver Reference
The data structure is used to set the line coding on the physical serial interface. The function
HCLS_ACM_SetLineCoding is used to set the parameter.
See Also
HCLS_ACM_SetLineCoding (page 181)
USB Bus Driver Reference Manual 195

12 HID Class Driver Reference
12 HID Class Driver Reference
12.1 Application programming interface
HCLS_HID_Init
The function initializes this class.
Definition
T_BOOL
HCLS_HID_Init();
Return Value
It returns T_TRUE on success or T_FALSE if some resources are not available.
Comments
The function must be called one time before any other API functions of this class driver can be
called. When the class driver is no longer required HCLS_HID_Exit must be called. If
HCLS_HID_Exit is not called the class driver has a memory leak.
This function is non blocking.
See Also
HCLS_HID_Exit (page 197)
196 USB Bus Driver Reference Manual

HCLS_HID_Exit
The exit function de-registers PnP handler and frees the allocated resources.
Definition
void
HCLS_HID_Exit();
Comments
12 HID Class Driver Reference
This function should be called one time when the class is not longer required. After the
function was called no callbacks are called from this class driver.
This function is blocking.
See Also
HCLS_HID_Init (page 196)
USB Bus Driver Reference Manual 197

12 HID Class Driver Reference
HCLS_HID_DeviceConnected
Prototype for a callback function that can be called when a device with a HID interface is
connected to the USB host.
Definition
typedef
void
HCLS_HID_DeviceConnected(
void* context,
USBH_INTERFACE_ID interfaceID
);
Parameters
context
This is the unchanged context pointer that was passed to the function call
HCLS_HID_RegisterConnectHandler. It can be used by the application.
interfaceID
The interface ID is an unique identifier for the interface. This identifier can be used to get
more information about the interface. When the device with this interface is disconnected and
reconnected the host stack assigned a different interface ID.
Comments
Do not call any blocking functions in this context. See also the comments in
HCLS_HID_RegisterConnectHandler.
See Also
HCLS_HID_RegisterConnectHandler (page 199)
198 USB Bus Driver Reference Manual

HCLS_HID_RegisterConnectHandler
This function registers a callback function for device connect events.
Definition
USBH_STATUS
HCLS_HID_RegisterConnectHandler(
HCLS_HID_DeviceConnected* connectNotification,
void* context
);
Parameters
connectNotification
The address of the callback function that should be called.
12 HID Class Driver Reference
context
The context that is passed to the callback function. This can be any user defined pointer or
NULL.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function allows event based notifications for connected class interfaces. When this
function is called the stack calls the callback function immediately for all currently connected
class compliant interfaces. An alternative method to be informed about new devices is the
polling of the available devices with HCLS_HID_CreateInterfaceList.
To unregister the callback call this function with connectNotification set to NULL.
This function is non blocking.
See Also
HCLS_HID_CreateInterfaceList (page 200)
HCLS_HID_DeviceConnected (page 198)
USB Bus Driver Reference Manual 199

12 HID Class Driver Reference
HCLS_HID_CreateInterfaceList
Creates an internal list with interfaces that expose a HID compliant interface.
Definition
USBH_INTERFACE_LIST_HANDLE
HCLS_HID_CreateInterfaceList(
unsigned int* InterfaceCount
);
Parameter
InterfaceCount
This parameter returns the number of available interfaces.
Return Value
It returns a valid list handle on success or NULL if no resources are available.
Comments
The internal list contains a snap shot of the HID interfaces that were available at the calling
time. The returned handle must be freed with HCLS_HID_DestroyInterfaceList.
The devices in the list can be enumerated with HCLS_HID_GetInterfaceID. The
relation of the index and the interface ID in a list is constant.
This function is non blocking.
See Also
HCLS_HID_DestroyInterfaceList (page 201)
HCLS_HID_GetInterfaceID (page 202)
200 USB Bus Driver Reference Manual

HCLS_HID_DestroyInterfaceList
The function frees the resources that are used for the internal interface list.
Definition
void
HCLS_HID_DestroyInterfaceList(
USBH_INTERFACE_LIST_HANDLE InterfaceListHandle
);
Parameter
InterfaceListHandle
A list handle that was returned by a successful call to the function
HCLS_HID_CreateInterfaceList.
Comments
This function should be called when the list is not longer needed.
This function is non blocking.
See Also
HCLS_HID_CreateInterfaceList (page 200)
12 HID Class Driver Reference
USB Bus Driver Reference Manual 201

12 HID Class Driver Reference
HCLS_HID_GetInterfaceID
This function can be used to get the unique interface ID in an interface list.
Definition
USBH_INTERFACE_ID
HCLS_HID_GetInterfaceID(
USBH_INTERFACE_LIST_HANDLE InterfaceListHandle,
unsigned int Index
);
Parameters
InterfaceListHandle
A list handle that was returned by a successful call to the function
HCLS_HID_CreateInterfaceList.
Index
Is a number between 0 and InterfaceCount-1. The InterfaceCount is returned by
the function HCLS_HID_CreateInterfaceList.
Return Value
The function returns the unique interface ID that is stored at the position of index in the list.
Comments
The interface list has a constant relation between the index and interface IDs and it is a snap
shoot of the available interface at the point of time when the list was created. When a device is
disconnected and reconnected it gets new interface IDs. A list can contain interface IDs that
are not longer available on the bus.
This function is non blocking.
See Also
HCLS_HID_CreateInterfaceList (page 200)
202 USB Bus Driver Reference Manual

HCLS_HID_GetInterfaceInfo
The function returns additional information to a known interface ID.
Definition
USBH_STATUS
HCLS_HID_GetInterfaceInfo(
USBH_INTERFACE_ID InterfaceID,
USBH_INTERFACE_INFO* InterfaceInfo
);
Parameters
12 HID Class Driver Reference
InterfaceID
The unique interface ID specifies the interface for which additional information should be
returned. The interface ID is returned either by HCLS_HID_GetInterfaceID or
HCLS_HID_DeviceConnected.
InterfaceInfo
The caller provides the storage for this structure and retrieves information about the specified
interface.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The additional information can be used to identify the device more exactly e.g. with the PID
or the serial number.
This function is non blocking.
See Also
HCLS_HID_GetInterfaceID (page 202)
HCLS_HID_DeviceConnected (page 198)
USBH_INTERFACE_INFO (page 92)
USB Bus Driver Reference Manual 203

12 HID Class Driver Reference
HCLS_HID_DeviceRemoved
Prototype for a callback that is called when a the device with the HID interface is removed.
Definition
typedef
void
HCLS_HID_DeviceRemoved(
void* context
);
Parameter
context
The context for the function that was passed to the function call HCLS_HID_Open.
Comments
A callback of this function can be registered with HCLS_HID_Open to see when the
corresponding opened interface is removed.
Do not call other blocking functions in this context.
See Also
HCLS_HID_Open (page 205)
204 USB Bus Driver Reference Manual

HCLS_HID_Open
12 HID Class Driver Reference
This function opens an interface exclusively and optionally registers a remove notification
function.
Definition
USBH_STATUS
HCLS_HID_Open(
USBH_INTERFACE_ID InterfaceID,
HCLS_HID_DeviceRemoved* removeNotification,
void* context,
HCLS_HID_Handle* handle
);
Parameters
InterfaceID
The unique interface ID specifies the interface which should be opened. The interface ID is
returned either by HCLS_HID_GetInterfaceID or HCLS_HID_DeviceConnected.
The device with this interface ID may be removed in the meantime. For that reason the open
function can fail with USBH_STATUS_DEVICE_REMOVED.
removeNotification
This parameter is optional. The caller provides the address of a function prototype
HCLS_HID_DeviceRemoved or NULL. When the caller provides this function pointer and
the open function returns with success, the remove notification function is called when the
device is removed. The function is de-registered and not longer called when the interface is
closed.
context
A user provided context for the remove notification function HCLS_HID_DeviceRemoved
or NULL.
handle
On success the function returns a handle to the interface that is used for the operational access.
If opening of the specified interface fails the handle will be NULL which is an invalid handle
value.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
When the remove notification function is not used the application can poll the presence of the
device with HCLS_HID_IsDevicePresent. The returned handle must be closed with
USB Bus Driver Reference Manual 205

12 HID Class Driver Reference
HCLS_HID_Close when it is not longer required.
This class does not implement an internal buffer circulation for the interrupt endpoint. To
create IN tokens on the endpoint the application has to pass a buffer with the function
HCLS_HID_ReadReport to the class.
This function is blocking.
See Also
HCLS_HID_GetInterfaceID (page 202)
HCLS_HID_DeviceConnected (page 198)
HCLS_HID_DeviceRemoved (page 204)
HCLS_HID_IsDevicePresent (page 208)
HCLS_HID_Close (page 207)
HCLS_HID_ReadReport (page 228)
206 USB Bus Driver Reference Manual

HCLS_HID_Close
The function closes an interface and releases the exclusive use.
Definition
void
HCLS_HID_Close(
HCLS_HID_Handle handle
);
Parameter
handle
The handle returned by HCLS_HID_Open.
Comments
12 HID Class Driver Reference
The caller has to make sure that all URB buffers that has been passed with
HCLS_HID_ReadReport and HCLS_HID_WriteReport has been returned before this
function is called. The caller can use HCLS_HID_AbortRead and
HCLS_HID_AbortWrite to archive this.
This function is blocking.
See Also
HCLS_HID_Open (page 205)
HCLS_HID_ReadReport (page 228)
HCLS_HID_WriteReport (page 224)
HCLS_HID_AbortRead (page 230)
HCLS_HID_AbortWrite (page 226)
USB Bus Driver Reference Manual 207

12 HID Class Driver Reference
HCLS_HID_IsDevicePresent
The function indicates if the device is present or not.
Definition
T_BOOL
HCLS_HID_IsDevicePresent(
HCLS_HID_Handle handle
);
Parameter
handle
The handle returned by HCLS_HID_Open.
Return Value
The function returns T_TRUE when the device is present or T_FALSE when the device is
removed.
Comments
This function is non blocking.
See Also
HCLS_HID_Open (page 205)
208 USB Bus Driver Reference Manual

HCLS_HID_GetHidDescriptor
Retrieves the variable sized HID descriptor of the specified interface.
Definition
USBH_STATUS
HCLS_HID_GetHidDescriptor(
HCLS_HID_Handle handle,
void* buffer,
T_UINT8 size,
T_UINT8* bytesReturned
);
Parameters
handle
The handle returned by HCLS_HID_Open.
12 HID Class Driver Reference
buffer
Pointer to a caller provided buffer that receives the HID descriptor. The caller provides the
storage of the buffer. The argument must not be NULL.
size
The size in bytes of the buffer given with buffer.
bytesReturned
Caller provided variable that receives the number of bytes that were written to the buffer.
The caller provides the storage of the variable. The argument must not be NULL.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function is non blocking.
See Also
HCLS_HID_Open (page 205)
USB Bus Driver Reference Manual 209

12 HID Class Driver Reference
HCLS_HID_GetNumDescriptors
Returns the number of report and physical descriptors for the specified interface.
Definition
T_UINT8
HCLS_HID_GetNumDescriptors(
HCLS_HID_Handle handle
);
Parameter
handle
The handle returned by HCLS_HID_Open.
Return Value
The number of report and physical descriptors of the interface.
Comments
Since a HID device must have at least 1 report descriptor the returned number is equal or
greater to 1. The returned value is extracted from the HID descriptor.
The function is non blocking.
See Also
HCLS_HID_Open (page 205)
210 USB Bus Driver Reference Manual

HCLS_HID_GetReportDescriptorSize
Returns the size in bytes of the report descriptor identified with the given index.
Definition
T_UINT16
HCLS_HID_GetReportDescriptorSize(
HCLS_HID_Handle handle,
T_UINT8 index
);
Parameters
handle
The handle returned by HCLS_HID_Open.
12 HID Class Driver Reference
index
A zero based index that identifies the report descriptor. The index ranges from 0 to
number of the descriptors-1. Call HCLS_HID_GetNumDescriptors to get
the number of the descriptors.
Return Value
The size in bytes of the report descriptor identified by index.
Comments
The function is non blocking.
See Also
HCLS_HID_Open (page 205)
HCLS_HID_GetNumDescriptors (page 210)
USB Bus Driver Reference Manual 211

12 HID Class Driver Reference
HCLS_HID_GetReportDescriptor
The function issues a request to retrieve the specified report descriptor and waits until the request
is completed.
Definition
USBH_STATUS
HCLS_HID_GetReportDescriptor(
HCLS_HID_Handle handle,
T_UINT8 index,
void* buffer,
T_UINT16 size,
T_UINT16* bytesReturned
);
Parameters
handle
The handle returned by HCLS_HID_Open.
index
A zero based index that identifies the report descriptor. The index ranges from 0 to
number of the descriptors-1. Call HCLS_HID_GetNumDescriptors to get
the number of the descriptors.
buffer
Pointer to a caller provided buffer that receives the report descriptor. The caller provides the
storage of the buffer. The argument must not be NULL.
size
The size in bytes of the buffer given with buffer.
bytesReturned
Caller provided variable that receives the number of bytes that were written to the buffer.
The caller provides the storage of the variable. The argument must not be NULL.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function is blocking.
212 USB Bus Driver Reference Manual

See Also
HCLS_HID_Open (page 205)
HCLS_HID_GetNumDescriptors (page 210)
12 HID Class Driver Reference
USB Bus Driver Reference Manual 213

12 HID Class Driver Reference
HCLS_HID_GetReportRequest
This function sends a Get_Report request to the specified interface and waits until the request is
completed.
Definition
USBH_STATUS
HCLS_HID_GetReportRequest(
HCLS_HID_Handle handle,
T_UINT8 type,
T_UINT8 reportID,
void* buffer,
T_UINT16 size,
T_UINT16* bytesReturned
);
Parameters
handle
The handle returned by HCLS_HID_Open.
type
The type of the report to get. This must be one of the following:
TUSB_CLS_HID_REPORT_TYPE_INPUT
Get an Input report.
TUSB_CLS_HID_REPORT_TYPE_OUTPUT
Get an Output report.
TUSB_CLS_HID_REPORT_TYPE_FEATURE
Get a Feature report.
reportID
The ID of the report to get.
buffer
Pointer to a caller provided buffer that receives the requested report. The caller provides the
storage of the buffer. The argument must not be NULL.
size
The size in bytes of the buffer given with buffer.
bytesReturned
Caller provided variable that receives the number of bytes that were written to the buffer.
The caller provides the storage of the variable. The argument must not be NULL.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
214 USB Bus Driver Reference Manual

Comments
12 HID Class Driver Reference
This function can be used to request Input and Feature reports over the control pipe (endpoint
0). It should not be used to poll for Input reports. Use HCLS_HID_ReadReport to poll for
Input reports.
When the device returns a report ID in the data of the report it is part of the returned data.
The function is blocking.
See Also
HCLS_HID_Open (page 205)
HCLS_HID_ReadReport (page 228)
USB Bus Driver Reference Manual 215

12 HID Class Driver Reference
HCLS_HID_SetReportRequest
This function sends a Set_Report request to the specified interface and waits until the request is
completed.
Definition
USBH_STATUS
HCLS_HID_SetReportRequest(
HCLS_HID_Handle handle,
T_UINT8 type,
T_UINT8 reportID,
void* buffer,
T_UINT16 size
);
Parameters
handle
The handle returned by HCLS_HID_Open.
type
The type of the report to set. This must be one of the following:
TUSB_CLS_HID_REPORT_TYPE_INPUT
Set an Input report.
TUSB_CLS_HID_REPORT_TYPE_OUTPUT
Set an Output report.
TUSB_CLS_HID_REPORT_TYPE_FEATURE
Set a Feature report.
reportID
The ID of the report to set.
buffer
Caller provided buffer that contains the report to set. The caller provides the storage and the
content of the buffer. The argument must not be NULL.
size
The size in bytes of the buffer given with buffer.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
216 USB Bus Driver Reference Manual

Comments
12 HID Class Driver Reference
This function can be used tzo send Feature or Output reports over the control pipe (endpoint
0). To send Output reports with low lateny over an interrupt OUT pipe use
HCLS_HID_WriteReport.
You have to add the report ID to the buffer if this is required.
The function is blocking.
See Also
HCLS_HID_Open (page 205)
USB Bus Driver Reference Manual 217

12 HID Class Driver Reference
HCLS_HID_GetProtocolRequest
This function sends a Get_Protocol request that receives the currently active protocol of the
specified HID interface. The function waits until the request is completed.
Definition
USBH_STATUS
HCLS_HID_GetProtocolRequest(
HCLS_HID_Handle handle,
T_UINT8* protocol
);
Parameters
handle
The handle returned by HCLS_HID_Open.
protocol
Caller provided variable that receives the currently active protocol. This can be one of the
following:
TUSB_CLS_HID_BOOT_PROTOCOL
The boot protocol is active.
TUSB_CLS_HID_REPORT_PROTOCOL
The report protocol is active.
The caller provides the storage of the variable. The argument must not be NULL.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function is blocking.
See Also
HCLS_HID_Open (page 205)
218 USB Bus Driver Reference Manual

HCLS_HID_SetProtocolRequest
12 HID Class Driver Reference
This function sends a Set_Protocol request that sets the active protocol for the specified HID
interface. The function waits until the request is completed.
Definition
USBH_STATUS
HCLS_HID_SetProtocolRequest(
HCLS_HID_Handle handle,
T_UINT8 protocol
);
Parameters
handle
The handle returned by HCLS_HID_Open.
protocol
A value that indicates the protocol that should be activated. This can be one of the following:
TUSB_CLS_HID_BOOT_PROTOCOL
Activate the boot protocol.
TUSB_CLS_HID_REPORT_PROTOCOL
Activate the report protocol.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function is blocking.
See Also
HCLS_HID_Open (page 205)
USB Bus Driver Reference Manual 219

12 HID Class Driver Reference
HCLS_HID_GetIdleRequest
This functions sends a Get_Idle request to the specified interface and waits until the request is
completed.
Definition
USBH_STATUS
HCLS_HID_GetIdleRequest(
HCLS_HID_Handle handle,
T_UINT8 reportID,
T_UINT8* idleTime
);
Parameters
handle
The handle returned by HCLS_HID_Open.
reportID
The ID of the report for which to get the idle rate.
idleTime
Caller provided variable that receives the idle time for the specified report. The idle rate is
provided with a 4 milliseconds resolution, i.e. a value of 1 means an idle rate 0 4 milliseconds.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function can be used to read the current idle rate for a particular Input report.
The function is blocking.
See Also
HCLS_HID_Open (page 205)
220 USB Bus Driver Reference Manual

HCLS_HID_SetIdleRequest
12 HID Class Driver Reference
This functions sends a Set_Idle request to the specified interface and waits until the request is
completed.
Definition
USBH_STATUS
HCLS_HID_SetIdleRequest(
HCLS_HID_Handle handle,
T_UINT8 reportID,
T_UINT8 idleTime
);
Parameters
handle
The handle returned by HCLS_HID_Open.
reportID
The ID of the report for which to set the idle rate. Set this to zero if you want to set the idle
rate for all reports that are send by the interface.
idleTime
The idle rate to set in a resolution of 4 milliseconds. I.e. a value of 1 specifies an idle rate of 4
milliseconds.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function can be used to set the idle rate for either all or a particular report that is sent by
the interrupt IN endpoint. This is usefull to limit the reporting frequency of the interrupt IN
endpoit of the interface.
The function is blocking.
See Also
HCLS_HID_Open (page 205)
USB Bus Driver Reference Manual 221

12 HID Class Driver Reference
HCLS_HID_GetWriteFifoSize
This function returns the FIFO size in bytes of the write endpoint.
Definition
T_UINT16
HCLS_HID_GetWriteFifoSize(
HCLS_HID_Handle handle
);
Parameter
handle
The handle returned by HCLS_HID_Open.
Return Value
The FIFO size in bytes of the interrupt OUT endpoint. If the interface does not have an
interrupt OUT endpoint the function returns 0.
Comments
The returned value can be used to calculate whether a zero length packet must be sent.
This function is non blocking.
See Also
HCLS_HID_Open (page 205)
222 USB Bus Driver Reference Manual

HCLS_HID_GetReadFifoSize
This function returns the FIFO size in bytes of the read endpoint.
Definition
T_UINT16
HCLS_HID_GetReadFifoSize(
HCLS_HID_Handle handle
);
Parameter
handle
The handle returned by HCLS_HID_Open.
Return Value
The FIFO size in bytes of the interrupt IN endpoint.
Comments
12 HID Class Driver Reference
The returned value can be used to calculate a valid buffer size for the read operation.
This function is non blocking.
See Also
HCLS_HID_Open (page 205)
USB Bus Driver Reference Manual 223

12 HID Class Driver Reference
HCLS_HID_WriteReport
This function asynchronously sends a report to the interrupt OUT endpoint of the specified
interface.
Definition
USBH_STATUS
HCLS_HID_WriteReport(
HCLS_HID_Handle handle,
URB* urb,
T_UINT8 reportID
);
Parameters
handle
The handle returned by HCLS_HID_Open.
urb
A pointer to a caller provided and initialized URB structure. The caller provides the header
and the URB_BULK_INT_REQUEST information. The class driver adds the endpoint to the
request.
reportID
The ID of the report that should be written. This argument is only be used if the report is sent
over the control pipe (endpoint 0). If the report is sent over the interrupt OUT pipe this
argument is ignored.
Return Value
The function returns USBH_STATUS_PENDING on success or an appropriate error code
otherwise.
Comments
If the interface have an interrupt OUT endpoint the report is sent on this endpoint. Otherwise
the report is sent as a setup request on endpoint 0. Anyhow the URB must be filled in as
URB_BULK_INT_REQUEST.
The submitted URB and the related data transfer buffer is passed to the driver stack with this
function call. When the function returns the status USBH_STATUS_PENDING the URB is
queued for processing in the stack. The caller must neither free the buffer or the URB nor
access it as long as the ownership is at the stack. It has to wait until the callback function
provided in the URB header is called. The write operation can be delayed for an infinite time
by the device. The application can abort the operation with HCLS_HID_AbortWrite.
After this function is called the application has to wait until the completion routine is called.
224 USB Bus Driver Reference Manual

12 HID Class Driver Reference
If the interrupt OUT pipe is used to sent the report the buffer memory that is passed in
URB.Request.BulkIntRequest.Buffer must be DMA memory. For more
information about this memory please see section 5.3 at page 29.
If the device expects a short packet termination of data chunks, the caller must take care on
this. When the size of the data chunk can be divided by the FIFO size without rest the caller
has to send a zero length packet.
The function is non blocking. It can be called in the context of the completion routine of the
URB. But the caller should check the status value of the returned request. When the request
fails the caller should not re-submit the URB to the stack to avoid endless loops.
See Also
HCLS_HID_Open (page 205)
HCLS_HID_GetWriteFifoSize (page 222)
URB (page 108)
HCLS_HID_AbortWrite (page 226)
TAL_AllocateDmaMemory (page 135)
USB Bus Driver Reference Manual 225

12 HID Class Driver Reference
HCLS_HID_AbortWrite
The function aborts all write requests on the specified interface.
Definition
USBH_STATUS
HCLS_HID_AbortWrite(
HCLS_HID_Handle handle
);
Parameter
handle
The handle returned by HCLS_HID_Open.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function starts the abort process for all pending write requests. Typically the abort process
is delayed. The caller has to wait until the completion routine for all pending URBs is called.
The stack sets the status in the canceled URBs to USBH_STATUS_CANCELED.
After a write operation has been canceled it cannot be determined how many data has been
transferred to the device. Furthermore the data toggle mechanism to the device may be out of
order. For that reason the caller should used the function HCLS_HID_ResetWritePipe to
clear all error conditions before the next write operation is started.
The function is blocking.
See Also
HCLS_HID_Open (page 205)
HCLS_HID_WriteReport (page 224)
HCLS_HID_ResetWritePipe (page 227)
226 USB Bus Driver Reference Manual

HCLS_HID_ResetWritePipe
The functions resets the write pipe.
Definition
USBH_STATUS
HCLS_HID_ResetWritePipe(
HCLS_HID_Handle handle
);
Parameter
handle
The handle returned by HCLS_HID_Open.
Return Value
12 HID Class Driver Reference
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function resets the write endpoint. It sends a Clear Feature Endpoint Halt request for the
write endpoint to the device. It resets the data toggle bits and clears any other error state in the
driver stack and in possibly connected external hubs.
When the function is called no pending requests on this endpoint are allowed.
The function is blocking.
See Also
HCLS_HID_Open (page 205)
HCLS_HID_WriteReport (page 224)
HCLS_HID_AbortWrite (page 226)
USB Bus Driver Reference Manual 227

12 HID Class Driver Reference
HCLS_HID_ReadReport
This function asynchronously reads a report from the interrupt IN endpoint of the specified
interface.
Definition
USBH_STATUS
HCLS_HID_ReadReport(
HCLS_HID_Handle handle,
URB* urb
);
Parameters
handle
The handle returned by HCLS_HID_Open.
urb
A pointer to a caller provided and initialized URB structure. The caller provides the header
and the URB_BULK_INT_REQUEST information. The class driver adds the endpoint to the
request.
Return Value
This function returns USBH_STATUS_PENDING in case of success or an appropriate error
code otherwise.
Comments
The submitted URB and the related data transfer buffer is passed to the driver stack with this
function call. When the function returns the status USBH_STATUS_PENDING the URB is
queued for processing in the stack. The caller must neither free the buffer or the URB nor
access it as long as the ownership is at the stack. It has to wait until the callback function
provided in the URB header is called.
When the first read buffer is submitted to the stack the driver starts to send IN tokens to the
interrupt IN endpoint of the HID interface. When no buffer for this endpoint is pending the
driver does not send IN tokens to it. I.e. to allow the device to send data at least one buffer
must be pending. The buffer size should be a multiple of the FIFO size. This avoids buffer
overrun errors. The device should terminate each data chunk with a short packet. When the
device is not able to terminate each data chunk with a short packet the application should use
buffers with the FIFO size of the interrupt IN endpoint. But note: We recommend to use larger
buffer to archive a good performance.
The application can call HCLS_HID_AbortRead to abort all pending buffers. After this
function is called the application has to wait until the completion routine of the aborted buffers
is called.
228 USB Bus Driver Reference Manual

12 HID Class Driver Reference
The buffer memory that is passed in URB.Request.BulkIntRequest.Buffer must be
DMA memory. For more information about this memory please see section 5.3 at page 29.
The function is non blocking. It can be called in the context of the completion routine of the
URB. But the caller should check the status value of the returned request. When the request
fails the caller should not re-submit the URB to the stack to avoid endless loops.
See Also
HCLS_HID_Open (page 205)
HCLS_HID_GetReadFifoSize (page 223)
URB (page 108)
HCLS_HID_AbortRead (page 230)
TAL_AllocateDmaMemory (page 135)
USB Bus Driver Reference Manual 229

12 HID Class Driver Reference
HCLS_HID_AbortRead
The function aborts all read requests on the specified interface.
Definition
USBH_STATUS
HCLS_HID_AbortRead(
HCLS_HID_Handle handle
);
Parameter
handle
The handle returned by HCLS_HID_Open.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function starts the abort process for all pending read requests. Typically the abort process
is delayed. The caller has to wait until the completion routine for all pending URBs is called.
The stack sets the status in the canceled URBs to USBH_STATUS_CANCELED.
After a read operation has been canceled it cannot be determined how many data has been
transferred from the device. Furthermore the data toggle mechanism to the device may be out
of order. For that reason the caller should used the function HCLS_HID_ResetReadPipe
to clear all error conditions before the next read operation is started.
This function is blocking.
See Also
HCLS_HID_Open (page 205)
HCLS_HID_ReadReport (page 228)
HCLS_HID_ResetReadPipe (page 231)
230 USB Bus Driver Reference Manual

HCLS_HID_ResetReadPipe
The functions resets the read pipe.
Definition
USBH_STATUS
HCLS_HID_ResetReadPipe(
HCLS_HID_Handle handle
);
Parameter
handle
The handle returned by HCLS_HID_Open.
Return Value
12 HID Class Driver Reference
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function resets the read endpoint. It sends a Clear Feature Endpoint Halt request for the
read endpoint to the device. It resets the data toggle bits and clears any other error state in the
driver stack and in possibly connected external hubs.
When the function is called no pending requests on this endpoint are allowed.
The function is blocking.
See Also
HCLS_HID_Open (page 205)
HCLS_HID_ReadReport (page 228)
HCLS_HID_AbortRead (page 230)
USB Bus Driver Reference Manual 231

13 Printer Class Driver Reference
13 Printer Class Driver Reference
13.1 Application programming interface
HCLS_PRN_Init
The function initializes this class.
Definition
T_BOOL
HCLS_PRN_Init();
Return Value
It returns T_TRUE on success or T_FALSE if some resources are not available.
Comments
The function must be called one time before any other API functions of this class driver can be
called. When the class driver is no longer required HCLS_PRN_Exit must be called. If
HCLS_PRN_Exit is not called the class driver has a memory leak.
This function is non blocking.
See Also
HCLS_PRN_Exit (page 233)
232 USB Bus Driver Reference Manual

HCLS_PRN_Exit
The exit function de-registers PnP handler and frees the allocated resources.
Definition
void
HCLS_PRN_Exit();
Comments
13 Printer Class Driver Reference
This function should be called one time when the class is not longer required. After the
function was called no callbacks are called from this class driver.
This function is blocking.
See Also
HCLS_PRN_Init (page 232)
USB Bus Driver Reference Manual 233

13 Printer Class Driver Reference
HCLS_PRN_PrinterConnected
Prototype for a callback function that can be called when a device with a printer interface is
connected to the USB host.
Definition
typedef
void
HCLS_PRN_PrinterConnected(
void* context,
USBH_INTERFACE_ID interfaceID
);
Parameters
context
This is the unchanged context pointer that was passed to the function call
HCLS_PRN_RegisterConnectHandler. It can be used by the application.
interfaceID
The interface ID is an unique identifier for the interface. This identifier can be used to get
more information about the interface. When the device with this interface is disconnected and
reconnected the host stack assigned a different interface ID.
Comments
Do not call any blocking functions in this context. See also the comments in
HCLS_PRN_RegisterConnectHandler.
See Also
HCLS_PRN_RegisterConnectHandler (page 235)
234 USB Bus Driver Reference Manual

HCLS_PRN_RegisterConnectHandler
This function registers a callback function for device connect events.
Definition
USBH_STATUS
HCLS_PRN_RegisterConnectHandler(
HCLS_PRN_PrinterConnected* connectNotification,
void* context
);
Parameters
connectNotification
The address of the callback function that should be called.
13 Printer Class Driver Reference
context
The context that is passed to the callback function. This can be any user defined pointer or
NULL.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function allows event based notifications for connected class interfaces. When this
function is called the stack calls the callback function immediately for all currently connected
class compliant interfaces. An alternative method to be informed about new devices is the
polling of the available devices with HCLS_PRN_CreateInterfaceList.
To unregister the callback call this function with connectNotification set to NULL.
This function is non blocking.
See Also
HCLS_PRN_CreateInterfaceList (page 236)
HCLS_PRN_PrinterConnected (page 234)
USB Bus Driver Reference Manual 235

13 Printer Class Driver Reference
HCLS_PRN_CreateInterfaceList
Creates an internal list with interfaces that expose a printer compliant interface.
Definition
USBH_INTERFACE_LIST_HANDLE
HCLS_PRN_CreateInterfaceList(
unsigned int* InterfaceCount
);
Parameter
InterfaceCount
This parameter returns the number of available interface.
Return Value
It returns a valid list handle on success or NULL if no resources are available.
Comments
The internal list contains a snap shot of the printer interfaces that were available at the calling
time. The returned handle must be freed with HCLS_PRN_DestroyInterfaceList.
The devices in the list can be enumerated with HCLS_PRN_GetInterfaceID. The
relation of the index and the interface ID in a list is constant.
This function is non blocking.
See Also
HCLS_PRN_DestroyInterfaceList (page 237)
HCLS_PRN_GetInterfaceID (page 238)
236 USB Bus Driver Reference Manual

HCLS_PRN_DestroyInterfaceList
The function frees the resources that are used for the internal interface list.
Definition
void
HCLS_PRN_DestroyInterfaceList(
USBH_INTERFACE_LIST_HANDLE InterfaceListHandle
);
Parameter
InterfaceListHandle
A list handle that was returned by a successful call to the function
HCLS_PRN_CreateInterfaceList.
Comments
This function should be called when the list is not longer needed.
This function is non blocking.
See Also
HCLS_PRN_CreateInterfaceList (page 236)
13 Printer Class Driver Reference
USB Bus Driver Reference Manual 237

13 Printer Class Driver Reference
HCLS_PRN_GetInterfaceID
This function can be used to get the unique interface ID in an interface list.
Definition
USBH_INTERFACE_ID
HCLS_PRN_GetInterfaceID(
USBH_INTERFACE_LIST_HANDLE InterfaceListHandle,
unsigned int Index
);
Parameters
InterfaceListHandle
A list handle that was returned by a successful call to the function
HCLS_PRN_CreateInterfaceList.
Index
Is a number between 0 and InterfaceCount-1. The InterfaceCount is returned by
the function HCLS_PRN_CreateInterfaceList.
Return Value
The function returns the unique interface ID that is stored at the position of index in the list.
Comments
The interface list has a constant relation between the index and interface IDs and it is a snap
shoot of the available interface at the point of time when the list was created. When a device is
disconnected and reconnected it gets new interface IDs. A list can contain interface IDs that
are not longer available on the bus.
This function is non blocking.
See Also
HCLS_PRN_CreateInterfaceList (page 236)
238 USB Bus Driver Reference Manual

HCLS_PRN_GetInterfaceInfo
The function returns additional information to a known interface ID.
Definition
USBH_STATUS
HCLS_PRN_GetInterfaceInfo(
USBH_INTERFACE_ID InterfaceID,
USBH_INTERFACE_INFO* InterfaceInfo
);
Parameters
13 Printer Class Driver Reference
InterfaceID
The unique interface ID specifies the interface for which additional information should be
returned. The interface ID is returned either by HCLS_PRN_GetInterfaceID or
HCLS_PRN_PrinterConnected.
InterfaceInfo
The caller provides the storage for this structure and retrieves information about the specified
interface.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The additional information can be used to identify the device more exactly e.g. with the PID
or the serial number.
This function is non blocking.
See Also
HCLS_PRN_GetInterfaceID (page 238)
HCLS_PRN_PrinterConnected (page 234)
USBH_INTERFACE_INFO (page 92)
USB Bus Driver Reference Manual 239

13 Printer Class Driver Reference
HCLS_PRN_PrinterRemove
Prototype for a callback that is called when a the device with the printer interface is removed.
Definition
typedef
void
HCLS_PRN_PrinterRemove(
void* context
);
Parameter
context
The context for the function that was passed to the function call HCLS_PRN_Open.
Comments
A callback of this function can be registered with HCLS_PRN_Open to see when the
corresponding opened interface is removed.
Do not call other blocking functions in this context.
See Also
HCLS_PRN_Open (page 241)
240 USB Bus Driver Reference Manual

HCLS_PRN_Open
13 Printer Class Driver Reference
This function opens an interface exclusively and optionally registers a remove notification
function.
Definition
USBH_STATUS
HCLS_PRN_Open(
USBH_INTERFACE_ID InterfaceID,
HCLS_PRN_PrinterRemove* removeNotification,
void* context,
HCLS_PRN_Handle* handle
);
Parameters
InterfaceID
The unique interface ID specifies the interface which should be opened. The interface ID is
returned either by HCLS_PRN_GetInterfaceID or HCLS_PRN_PrinterConnected.
The device with this interface ID may be removed in the meantime. For that reason the open
function can fail with USBH_STATUS_DEVICE_REMOVED.
removeNotification
This parameter is optional. The caller provides the address of a function prototype
HCLS_PRN_PrinterRemove or NULL. When the caller provides this function pointer and
the open function returns with success, the remove notification function is called when the
device is removed. The function is de-registered and not longer called when the interface is
closed.
context
A user provided context for the remove notification function HCLS_PRN_PrinterRemove
or NULL.
handle
On success the function returns a handle to the interface that is used for the operational access.
If opening of the specified interface fails the handle will be NULL which is an invalid handle
value.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
When the remove notification function is not used the application can poll the presence of the
device with HCLS_PRN_IsPrinterPresent. The returned handle must be closed with
USB Bus Driver Reference Manual 241

13 Printer Class Driver Reference
HCLS_PRN_Close when it is not longer required.
This function is blocking.
See Also
HCLS_PRN_GetInterfaceID (page 238)
HCLS_PRN_PrinterConnected (page 234)
HCLS_PRN_PrinterRemove (page 240)
HCLS_PRN_IsPrinterPresent (page 244)
HCLS_PRN_Close (page 243)
242 USB Bus Driver Reference Manual

HCLS_PRN_Close
The function closes an interface and releases the exclusive use.
Definition
void
HCLS_PRN_Close(
HCLS_PRN_Handle handle
);
Parameter
handle
The handle returned by HCLS_PRN_Open.
Comments
13 Printer Class Driver Reference
The caller has to make sure that all URB buffers that has been passed with HCLS_PRN_Read
and HCLS_PRN_Write has been returned before this function is called. The caller can use
HCLS_PRN_AbortRead and HCLS_PRN_AbortWrite to archive this.
This function is blocking.
See Also
HCLS_PRN_Open (page 241)
HCLS_PRN_Read (page 257)
HCLS_PRN_Write (page 251)
HCLS_PRN_AbortRead (page 261)
HCLS_PRN_AbortWrite (page 255)
USB Bus Driver Reference Manual 243

13 Printer Class Driver Reference
HCLS_PRN_IsPrinterPresent
The function indicates if the printer is present or not.
Definition
T_BOOL
HCLS_PRN_IsPrinterPresent(
HCLS_PRN_Handle Handle
);
Parameter
Handle
The handle returned by HCLS_PRN_Open.
Return Value
The function returns T_TRUE when the printer is present or T_FALSE when the printer is
removed.
Comments
This function is non blocking.
See Also
HCLS_PRN_Open (page 241)
244 USB Bus Driver Reference Manual

HCLS_PRN_GetAvailableInterfaces
13 Printer Class Driver Reference
This function returns an or’ed combination of the possible interfaces that the printer implements.
Definition
T_UINT8
HCLS_PRN_GetAvailableInterfaces(
HCLS_PRN_Handle handle
);
Parameter
handle
The handle returned by HCLS_PRN_Open.
Return Value
The function returns an or’ed combination of the following flags:
CLS_PRINTER_INTERFACE_UNIDIRECTIONAL
The printer implements a uni-directional interface.
CLS_PRINTER_INTERFACE_BIDIRECTIONAL
The printer implements a bi-directional interface.
CLS_PRINTER_INTERFACE_1284_BIDIRECTIONAL
The printer implements a IEEE 1284 compatible bi-directional interface.
Comments
The function is non blocking.
See Also
HCLS_PRN_Open (page 241)
USB Bus Driver Reference Manual 245

13 Printer Class Driver Reference
HCLS_PRN_GetCurrentInterface
This function returns the currently selected interface of the specified printer.
Definition
T_UINT8
HCLS_PRN_GetCurrentInterface(
HCLS_PRN_Handle handle
);
Parameter
handle
The handle returned by HCLS_PRN_Open.
Return Value
The function returns the currently selected interface of the specified printer. The return value
can be one of the following:
CLS_PRINTER_INTERFACE_UNIDIRECTIONAL
The uni-directional interface is currently selected.
CLS_PRINTER_INTERFACE_BIDIRECTIONAL
The bi-directional interface is currently selected.
CLS_PRINTER_INTERFACE_1284_BIDIRECTIONAL
The IEEE 1284 compatible bi-directional interface is currently selected.
Comments
The returned interface is the first selected interface after the printer was enumerated.
The function is non blocking.
See Also
HCLS_PRN_Open (page 241)
246 USB Bus Driver Reference Manual

HCLS_PRN_SetInterface
13 Printer Class Driver Reference
This function issues a request to set the specified printer interface and waits until the request is
completed.
Definition
USBH_STATUS
HCLS_PRN_SetInterface(
HCLS_PRN_Handle handle,
T_UINT8 printerInterface
);
Parameters
handle
The handle returned by HCLS_PRN_Open.
printerInterface
The printer interface that should be set. This can be one of the following:
CLS_PRINTER_INTERFACE_UNIDIRECTIONAL
Set the uni-directional interface.
CLS_PRINTER_INTERFACE_BIDIRECTIONAL
Set the bi-directional interface.
CLS_PRINTER_INTERFACE_1284_BIDIRECTIONAL
Set the IEEE 1284 compatible bi-directional interface.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function can be used to select a printer interface. It should be called before the
communication with the printer starts.
The function is blocking.
See Also
HCLS_PRN_Open (page 241)
USB Bus Driver Reference Manual 247

13 Printer Class Driver Reference
HCLS_PRN_GetDeviceId
This function issues a request to receive the device ID string and waits until the request is
completed.
Definition
USBH_STATUS
HCLS_PRN_GetDeviceId(
HCLS_PRN_Handle handle,
T_UINT8* buffer,
T_UINT16 bufferSize,
T_UINT16* bytesReturned
);
Parameters
handle
The handle returned by HCLS_PRN_Open.
buffer
Pointer to a caller provided buffer that receives the device ID string. The caller provides the
storage of the buffer. The argument must not be NULL.
bufferSize
The size in bytes of the buffer given with buffer.
bytesReturned
Caller provided variable that receives the number of bytes that were written to the buffer.
The caller provides the storage of the variable. The argument must not be NULL.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The requested device ID string is read from the device. When the given buffer is smaller as
the device ID string only the first part of the device ID string is transferred.
The function does not process or test the device ID string in anyway. Therefor the caller
should consists that the string may is inconsistent.
The function is blocking.
See Also
HCLS_PRN_Open (page 241)
248 USB Bus Driver Reference Manual

HCLS_PRN_GetPortStatus
13 Printer Class Driver Reference
This function issues a request to receive the current port status from the specified printer and
waits until the request is completed.
Definition
USBH_STATUS
HCLS_PRN_GetPortStatus(
HCLS_PRN_Handle handle,
T_UINT8* portStatus
);
Parameters
handle
The handle returned by HCLS_PRN_Open.
portStatus
Caller provided variable that receives the current port status. The caller provides the storage of
the variable. The argument must not be NULL.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The received port status is an or’ed combination of the following flags:
TUSB_CLS_PRINTER_STATUS_NOT_ERROR
A value of 1 indicates that the printer has no error, 0 means the printer has an error.
TUSB_CLS_PRINTER_STATUS_SELECT
A value of 1 inidcates that the printer is selected, 0 means not selected.
TUSB_CLS_PRINTER_STATUS_PAPER_EMPTY
A value of 1 indicates that teh printer is out of paper, 0 means the paper is not empty.
Refer to the USB Device Class Definition for Printing Devices for further information about
the port status.
The function is blocking.
See Also
HCLS_PRN_Open (page 241)
USB Bus Driver Reference Manual 249

13 Printer Class Driver Reference
HCLS_PRN_SoftReset
This function issue a request that performs a soft reset on the specified printer and waits until the
request is completed.
Definition
USBH_STATUS
HCLS_PRN_SoftReset(
HCLS_PRN_Handle handle,
T_BOOL recipientInterface
);
Parameters
handle
The handle returned by HCLS_PRN_Open.
recipientInterface
If this argument is set to T_TRUE the recipient of the request is set to interface so the request
is compliant to version 1.1 of the USB Device Class Definition for Printing Devices. If it is set
to T_FALSE the recipient is set to other which is compliant to version 1.0 of the USB Device
Class Definition for Printing Devices.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function is blocking.
See Also
HCLS_PRN_Open (page 241)
250 USB Bus Driver Reference Manual

HCLS_PRN_Write
This function submits an URB with a transfer buffer to the stack.
Definition
USBH_STATUS
HCLS_PRN_Write(
HCLS_PRN_Handle handle,
URB* urb
);
Parameters
handle
The handle returned by HCLS_PRN_Open.
13 Printer Class Driver Reference
urb
A pointer to a caller provided and initialized URB structure. The caller provides the header
and the URB_BULK_INT_REQUEST information. The class driver adds the endpoint to the
request.
Return Value
The function returns USBH_STATUS_PENDING on success or an appropriate error code
otherwise.
Comments
The submitted URB and the related data transfer buffer is passed to the driver stack with this
function call. When the function returns the status USBH_STATUS_PENDING the URB is
queued for processing in the stack. The caller must neither free the buffer or the URB nor
access it as long as the ownership is at the stack. It has to wait until the callback function
provided in the URB header is called. The write operation can be delayed for an infinite time
by the device. The application can abort the operation with HCLS_PRN_AbortWrite.
After this function is called the application has to wait until the completion routine is called.
This function is supported on each interface that is supported by the printer.
The buffer memory that is passed in URB.Request.BulkIntRequest.Buffer must be
DMA memory. For more information about this memory please see section 5.3 at page 29.
If the device expects a short packet termination of data chunks, the caller must take care on
this. When the size of the data chunk can be divided by the FIFO size without rest the caller
has to send a zero length packet.
The function is non blocking. It can be called in the context of the completion routine of the
URB. But the caller should check the status value of the returned request. When the request
fails the caller should not re-submit the URB to the stack to avoid endless loops.
USB Bus Driver Reference Manual 251

13 Printer Class Driver Reference
See Also
HCLS_PRN_Open (page 241)
URB (page 108)
HCLS_PRN_AbortWrite (page 255)
TAL_AllocateDmaMemory (page 135)
252 USB Bus Driver Reference Manual

HCLS_PRN_WriteSync
13 Printer Class Driver Reference
This function performs a synchronous write request to send the given data to the specified printer
interface.
Definition
USBH_STATUS
HCLS_PRN_WriteSync(
HCLS_PRN_Handle handle,
void* buffer,
T_UINT32 size,
T_UINT32 timeout
);
Parameters
handle
The handle returned by HCLS_PRN_Open.
buffer
Pointer to a caller provided buffer that contains the data. The caller provides the storage of the
buffer. The argument must not be NULL.
size
The size in bytes of the buffer given with buffer.
timeout
The timeout for the write request in milliseconds. Specify TAL_WAIT_INFINITE to wait
infinite for the completion of the write request.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. When the timeout value given with timeout is expired before the write
request is completed the function fails with USBH_STATUS_TIMEOUT.
Comments
This function issue a write operation with the given data and waits until the operation is
completed or the given timeout interval elapse, i.e. it behaves in a synchronous manner.
When the function returns with an error it can not be determined how much data has been
transferred.
The function is blocking.
USB Bus Driver Reference Manual 253

13 Printer Class Driver Reference
See Also
HCLS_PRN_Open (page 241)
254 USB Bus Driver Reference Manual

HCLS_PRN_AbortWrite
The function aborts all write requests on the specified interface.
Definition
USBH_STATUS
HCLS_PRN_AbortWrite(
HCLS_PRN_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Return Value
13 Printer Class Driver Reference
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function starts the abort process for all pending write requests. Typically the abort process
is delayed. The caller has to wait until the completion routine for all pending URBs is called.
The stack sets the status in the canceled URBs to USBH_STATUS_CANCELED.
After a write operation has been canceled it cannot be determined how many data has been
transferred to the device. Furthermore the data toggle mechanism to the device may be out of
order. For that reason the caller should used the function HCLS_PRN_ResetWritePipe to
clear all error conditions before the next write operation is started.
This function is blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_PRN_Write (page 251)
HCLS_PRN_ResetWritePipe (page 256)
USB Bus Driver Reference Manual 255

13 Printer Class Driver Reference
HCLS_PRN_ResetWritePipe
The functions resets the write pipe.
Definition
USBH_STATUS
HCLS_PRN_ResetWritePipe(
HCLS_PRN_Handle handle
);
Parameter
handle
The handle returned by HCLS_ACM_Open.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function resets the write endpoint. It sends a Clear Feature Endpoint Halt request for the
write endpoint to the device. It resets the data toggle bits and clears any other error state in the
driver stack and in possibly connected external hubs.
When the function is called no pending requests on this endpoint are allowed.
The function is blocking.
See Also
HCLS_ACM_Open (page 173)
HCLS_PRN_Write (page 251)
HCLS_PRN_AbortWrite (page 255)
256 USB Bus Driver Reference Manual

HCLS_PRN_Read
This function submits an URB with a transfer buffer to the stack.
Definition
USBH_STATUS
HCLS_PRN_Read(
HCLS_PRN_Handle handle,
URB* urb
);
Parameters
handle
The handle returned by HCLS_PRN_Open.
13 Printer Class Driver Reference
urb
A pointer to a caller provided and initialized URB structure. The caller provides the header
and the URB_BULK_INT_REQUEST information. The class driver adds the endpoint to the
request.
Return Value
The function returns USBH_STATUS_PENDING on success or an appropriate error code
otherwise.
Comments
The submitted URB and the related data transfer buffer is passed to the driver stack with this
function call. When the function returns the status USBH_STATUS_PENDING the URB is
queued for processing in the stack. The caller must neither free the buffer or the URB nor
access it as long as the ownership is at the stack. It has to wait until the callback function
provided in the URB header is called.
This function is not supported on unidirectional interfaces of the printer.
When the first read buffer is submitted to the stack the driver starts to send IN tokens to the
bulk IN endpoint of the printer interface. When no buffer for this endpoint is pending the
driver does not send IN tokens to it. The buffer size should be a multiple of the FIFO size.
This avoids buffer overrun errors. The device should terminate each data chunk with a short
packet. When the device is not able to terminate each data chunk with a short packet the
application should use buffers with the FIFO size of the bulk IN endpoint. But note: We
recommend to use larger buffer to archive a good performance.
The application can call HCLS_PRN_AbortRead to abort all pending buffers. After this
function is called the application has to wait until the completion routine of the aborted buffers
is called.
USB Bus Driver Reference Manual 257

13 Printer Class Driver Reference
The buffer memory that is passed in URB.Request.BulkIntRequest.Buffer must be
DMA memory. See section 5.3 for further information about DMA memory.
The function is non blocking. It can be called in the context of the completion routine of the
URB. But the caller should check the status value of the returned request. When the request
fails the caller should not re-submit the URB to the stack to avoid endless loops.
See Also
HCLS_PRN_Open (page 241)
URB (page 108)
HCLS_PRN_AbortRead (page 261)
TAL_AllocateDmaMemory (page 135)
258 USB Bus Driver Reference Manual

HCLS_PRN_ReadSync
13 Printer Class Driver Reference
This function performs a synchronous read request to read data from the specified printer
interface.
Definition
USBH_STATUS
HCLS_PRN_ReadSync(
HCLS_PRN_Handle handle,
void* buffer,
T_UINT32 size,
T_UINT32* transferred,
T_UINT32 timeout
);
Parameters
handle
The handle returned by HCLS_PRN_Open.
buffer
Pointer to a caller provided buffer that receives the data read from the printer interface. The
caller provides the storage of the buffer. The argument must not be NULL.
size
The size in bytes of the buffer given with buffer.
transferred
Caller provided variable that receives the number of bytes that were written to the buffer.
The caller provides the storage of the variable. The argument must not be NULL.
timeout
The timeout for the read request in milliseconds. Specify TAL_WAIT_INFINITE to wait
infinite for the completion of the read request.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. When the timeout value given with timeout is expired before the write
request is completed the function fails with USBH_STATUS_TIMEOUT.
Comments
This function issue a read operation and waits until the operation is completed or the given
timeout interval elapse, i.e. it behaves in a synchronous manner.
The function HCLS_PRN_AbortRead can be used to abort pending read operations.
The function is blocking.
USB Bus Driver Reference Manual 259

13 Printer Class Driver Reference
See Also
HCLS_PRN_Open (page 241)
HCLS_PRN_AbortRead (page 261)
260 USB Bus Driver Reference Manual

HCLS_PRN_AbortRead
The function aborts all read requests on the specified interface.
Definition
USBH_STATUS
HCLS_PRN_AbortRead(
HCLS_PRN_Handle handle
);
Parameter
handle
The handle returned by HCLS_PRN_Open.
Return Value
13 Printer Class Driver Reference
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function starts the abort process for all pending read requests. Typically the abort process
is delayed. The caller has to wait until the completion routine for all pending URBs is called.
The stack sets the status in the canceled URBs to USBH_STATUS_CANCELED.
After a read operation has been canceled it cannot be determined how many data has been
transferred from the device. Furthermore the data toggle mechanism to the device may be out
of order. For that reason the caller should used the function HCLS_PRN_ResetReadPipe
to clear all error conditions before the next read operation is started.
This function is blocking.
See Also
HCLS_PRN_Open (page 241)
HCLS_PRN_Read (page 257)
HCLS_PRN_ResetReadPipe (page 262)
USB Bus Driver Reference Manual 261

13 Printer Class Driver Reference
HCLS_PRN_ResetReadPipe
The functions resets the read pipe.
Definition
USBH_STATUS
HCLS_PRN_ResetReadPipe(
HCLS_PRN_Handle handle
);
Parameter
handle
The handle returned by HCLS_PRN_Open.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function resets the read endpoint. It sends a Clear Feature Endpoint Halt request for the
read endpoint to the device. It resets the data toggle bits and clears any other error state in the
driver stack and in possibly connected external hubs.
When the function is called no pending requests on this endpoint are allowed.
The function is blocking.
See Also
HCLS_PRN_Open (page 241)
HCLS_PRN_Read (page 257)
HCLS_PRN_AbortRead (page 261)
262 USB Bus Driver Reference Manual

14 Mass Storage Class Driver Reference
14.1 Application programming interface
HCLS_MS_Init
The function initializes this class.
Definition
T_BOOL
HCLS_MS_Init();
Return Value
14 Mass Storage Class Driver Reference
It returns T_TRUE on success or T_FALSE if some resources are not available.
Comments
The function must be called one time before any other API functions of this class driver can be
called. When the class driver is no longer required HCLS_MS_Exit must be called. If
HCLS_MS_Exit is not called the class driver has a memory leak.
This function is non blocking.
See Also
HCLS_MS_Exit (page 264)
USB Bus Driver Reference Manual 263

14 Mass Storage Class Driver Reference
HCLS_MS_Exit
The exit function de-registers PnP handler and frees the allocated resources.
Definition
void
HCLS_MS_Exit();
Comments
This function should be called one time when the class is not longer required. After the
function was called no callbacks are called from this class driver.
This function is blocking.
See Also
HCLS_MS_Init (page 263)
264 USB Bus Driver Reference Manual

HCLS_MS_DeviceConnected
14 Mass Storage Class Driver Reference
Prototype for a callback function that can be called when a device with a mass storage interface is
connected to the USB host.
Definition
typedef
void
HCLS_MS_DeviceConnected(
void* context,
USBH_INTERFACE_ID interfaceID
);
Parameters
context
This is the unchanged context pointer that was passed to the function call
HCLS_MS_RegisterConnectHandler. It can be used by the application.
interfaceID
The interface ID is an unique identifier for the interface. This identifier can be used to get
more information about the interface. When the device with this interface is disconnected and
reconnected the host stack assigned a different interface ID.
Comments
Do not call any blocking functions in this context. See also the comments in
HCLS_MS_RegisterConnectHandler.
See Also
HCLS_MS_RegisterConnectHandler (page 266)
USB Bus Driver Reference Manual 265

14 Mass Storage Class Driver Reference
HCLS_MS_RegisterConnectHandler
This function registers a callback function for device connect events.
Definition
USBH_STATUS
HCLS_MS_RegisterConnectHandler(
HCLS_MS_DeviceConnected* connectNotification,
void* context
);
Parameters
connectNotification
The address of the callback function that should be called.
context
The context that is passed to the callback function. This can be any user defined pointer or
NULL.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function allows event based notifications for connected class interfaces. When this
function is called the stack calls the callback function immediately for all currently connected
class compliant interfaces. An alternative method to be informed about new devices is the
polling of the available devices with HCLS_MS_CreateInterfaceList.
To unregister the callback call this function with connectNotification set to NULL.
This function is non blocking.
See Also
HCLS_MS_CreateInterfaceList (page 267)
HCLS_MS_DeviceConnected (page 265)
266 USB Bus Driver Reference Manual

HCLS_MS_CreateInterfaceList
14 Mass Storage Class Driver Reference
Creates an internal list with interfaces that expose a mass storage compliant interface.
Definition
USBH_INTERFACE_LIST_HANDLE
HCLS_MS_CreateInterfaceList(
unsigned int* InterfaceCount
);
Parameter
InterfaceCount
This parameter returns the number of available interfaces.
Return Value
It returns a valid list handle on success or NULL if no resources are available.
Comments
The internal list contains a snap shot of the mass storage interfaces that were available at the
calling time. The returned handle must be freed with
HCLS_MS_DestroyInterfaceList. The devices in the list can be enumerated with
HCLS_MS_GetInterfaceID. The relation of the index and the interface ID in a list is
constant.
This function is non blocking.
See Also
HCLS_MS_DestroyInterfaceList (page 268)
HCLS_MS_GetInterfaceID (page 270)
USB Bus Driver Reference Manual 267

14 Mass Storage Class Driver Reference
HCLS_MS_DestroyInterfaceList
The function frees the resources that are used for the internal interface list.
Definition
void
HCLS_MS_DestroyInterfaceList(
USBH_INTERFACE_LIST_HANDLE InterfaceListHandle
);
Parameter
InterfaceListHandle
A list handle that was returned by a successful call to the function
HCLS_MS_CreateInterfaceList.
Comments
This function should be called when the list is not longer needed.
This function is non blocking.
See Also
HCLS_MS_CreateInterfaceList (page 267)
268 USB Bus Driver Reference Manual

HCLS_MS_GetInterfaceInfo
The function returns additional information to a known interface ID.
Definition
USBH_STATUS
HCLS_MS_GetInterfaceInfo(
USBH_INTERFACE_ID InterfaceID,
USBH_INTERFACE_INFO* InterfaceInfo
);
Parameters
14 Mass Storage Class Driver Reference
InterfaceID
The unique interface ID specifies the interface for which additional information should be
returned. The interface ID is returned either by HCLS_MS_GetInterfaceID or
HCLS_MS_DeviceConnected.
InterfaceInfo
The caller provides the storage for this structure and retrieves information about the specified
interface.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The additional information can be used to identify the device more exactly e.g. with the PID
or the serial number.
This function is non blocking.
See Also
HCLS_MS_GetInterfaceID (page 270)
HCLS_MS_DeviceConnected (page 265)
USBH_INTERFACE_INFO (page 92)
USB Bus Driver Reference Manual 269

14 Mass Storage Class Driver Reference
HCLS_MS_GetInterfaceID
This function can be used to get the unique interface ID in an interface list.
Definition
USBH_INTERFACE_ID
HCLS_MS_GetInterfaceID(
USBH_INTERFACE_LIST_HANDLE InterfaceListHandle,
unsigned int Index
);
Parameters
InterfaceListHandle
A list handle that was returned by a successful call to the function
HCLS_MS_CreateInterfaceList.
Index
Is a number between 0 and InterfaceCount-1. The InterfaceCount is returned by
the function HCLS_MS_CreateInterfaceList.
Return Value
The function returns the unique interface ID that is stored at the position of index in the list.
Comments
The interface list has a constant relation between the index and interface IDs and it is a snap
shoot of the available interface at the point of time when the list was created. When a device is
disconnected and reconnected it gets new interface IDs. A list can contain interface IDs that
are not longer available on the bus.
This function is non blocking.
See Also
HCLS_MS_CreateInterfaceList (page 267)
270 USB Bus Driver Reference Manual

HCLS_MS_DeviceRemove
14 Mass Storage Class Driver Reference
Prototype for a callback that is called when a the device with the mass storage interface is
removed.
Definition
typedef
void
HCLS_MS_DeviceRemove(
void* context
);
Parameter
context
The context for the function that was passed to the function call HCLS_MS_Open.
Comments
A callback of this function can be registered with HCLS_MS_Open to see when the
corresponding opened interface is removed.
Do not call other blocking functions in this context.
See Also
HCLS_MS_Open (page 272)
USB Bus Driver Reference Manual 271

14 Mass Storage Class Driver Reference
HCLS_MS_Open
This function opens an interface exclusively and optionally registers a remove notification
function.
Definition
USBH_STATUS
HCLS_MS_Open(
USBH_INTERFACE_ID InterfaceID,
HCLS_MS_DeviceRemove* removeNotification,
void* context,
HCLS_MS_Handle* msHandle
);
Parameters
InterfaceID
The unique interface ID specifies the interface which should be opened. The interface ID is
returned either by HCLS_MS_GetInterfaceID or HCLS_MS_DeviceConnected. The
device with this interface ID may be removed in the meantime. For that reason the open
function can fail with USBH_STATUS_DEVICE_REMOVED.
removeNotification
This parameter is optional. The caller provides the address of a function prototype
HCLS_MS_DeviceRemove or NULL. When the caller provides this function pointer and
the open function returns with success, the remove notification function is called when the
device is removed. The function is de-registered and not longer called when the interface is
closed.
context
A user provided context for the remove notification function HCLS_MS_DeviceRemove or
NULL.
msHandle
On success the function returns a handle to the interface that is used for the operational access.
If opening of the specified interface fails the handle will be NULL which is an invalid handle
value.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The returned handle must be closed with HCLS_MS_Close when it is not longer required.
This function is blocking.
272 USB Bus Driver Reference Manual

See Also
HCLS_MS_GetInterfaceID (page 270)
HCLS_MS_DeviceConnected (page 265)
HCLS_MS_DeviceRemove (page 271)
HCLS_MS_Close (page 274)
14 Mass Storage Class Driver Reference
USB Bus Driver Reference Manual 273

14 Mass Storage Class Driver Reference
HCLS_MS_Close
The function closes an interface and releases the exclusive use.
Definition
void
HCLS_MS_Close(
HCLS_MS_Handle* handle
);
Parameter
handle
The handle returned by HCLS_MS_Open.
Comments
This function is blocking.
See Also
HCLS_MS_Open (page 272)
274 USB Bus Driver Reference Manual

HCLS_MS_GetLuns
14 Mass Storage Class Driver Reference
This function returns the number of logical units (LUN) of a mass storage interface.
Definition
USBH_STATUS
HCLS_MS_GetLuns(
HCLS_MS_Handle msHandle,
unsigned int* Luns
);
Parameters
msHandle
The handle returned by HCLS_MS_Open.
Luns
Returns the number of LUNs. HCLS_MS_OpenLun opens a LUN.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function is blocking.
See Also
HCLS_MS_Open (page 272)
HCLS_MS_OpenLun (page 276)
USB Bus Driver Reference Manual 275

14 Mass Storage Class Driver Reference
HCLS_MS_OpenLun
This function opens a LUN and returns a LUN handle.
Definition
USBH_STATUS
HCLS_MS_OpenLun(
HCLS_MS_Handle msHandle,
unsigned int lun,
HCLS_MS_LUN_HANDLE* unitHandle
);
Parameters
msHandle
The handle returned by HCLS_MS_Open.
lun
This is the zero based physical LUN number in the range from zero to Lun numbers - 1.
The Lun number can be received due a call to HCLS_MS_GetLuns.
unitHandle
On success the function returns a handle to the LUN that is used for the operational access. If
opening of the specified LUN fails the handle will be NULL which is an invalid handle value.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The returned handle must be closed with HCLS_MS_CloseLun if it is no longer required.
This function is blocking.
See Also
HCLS_MS_Open (page 272)
HCLS_MS_CloseLun (page 277)
HCLS_MS_ReadSectors (page 285)
276 USB Bus Driver Reference Manual

HCLS_MS_CloseLun
This function closes a previously opened interface.
Definition
void
HCLS_MS_CloseLun(
HCLS_MS_LUN_HANDLE Handle
);
Parameter
Handle
This parameter is the LUN handle returned by HCLS_MS_OpenLun.
Comments
14 Mass Storage Class Driver Reference
Each handle must be closed one time. The parameter Handle must be a valid handle.
The function is blocking.
See Also
HCLS_MS_OpenLun (page 276)
USB Bus Driver Reference Manual 277

14 Mass Storage Class Driver Reference
HCLS_MS_InitLun
This function retrieves some informations from the unit.
Definition
USBH_STATUS
HCLS_MS_InitLun(
HCLS_MS_LUN_HANDLE Handle,
T_UNIT_INFO* Info
);
Parameters
Handle
This parameter is the LUN handle returned by HCLS_MS_OpenLun.
Info
The caller provides the storage for this structure and receives some additional informations of
the logical unit.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
If the function fails with an error the logical unit is not supported by the mass storage class
driver and should be closed.
The function is blocking.
See Also
HCLS_MS_OpenLun (page 276)
HCLS_MS_CloseLun (page 277)
278 USB Bus Driver Reference Manual

HCLS_MS_ReadCapacity
This function reads the capacity of the medium.
Definition
USBH_STATUS
HCLS_MS_ReadCapacity(
HCLS_MS_LUN_HANDLE Handle,
T_UINT32* totalSectors,
T_UINT16* bytesPerSector
);
Parameters
Handle
This parameter is the LUN handle returned by HCLS_MS_OpenLun.
totalSectors
This parameter returns the total sector numbers.
bytesPerSector
This parameter returns the number of bytes per sector.
Return Value
14 Mass Storage Class Driver Reference
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
The function fails if the medium is not ready. Call HCLS_MS_IsMediumReady to see if the
medium is ready.
The function is blocking.
See Also
HCLS_MS_OpenLun (page 276)
HCLS_MS_IsMediumReady (page 284)
USB Bus Driver Reference Manual 279

14 Mass Storage Class Driver Reference
HCLS_MS_ModeSenseAllPages
This function returns some fields of the mode parameter header if the SCSI mode sense
command is executed to return all available mode pages. It is a optional command.
Definition
USBH_STATUS
HCLS_MS_ModeSenseAllPages(
HCLS_MS_LUN_HANDLE Handle,
T_UINT8* ParamHeaderMediumType,
T_UINT8* ParamHeaderDeviceParameter,
T_BOOL* IsWriteProtectFlag
);
Parameters
Handle
This parameter is the LUN handle returned by HCLS_MS_OpenLun.
ParamHeaderMediumType
Caller provided variable that receives the medium type field. The value is device specific, for
more information see also the SCSI-2 specification.
ParamHeaderDeviceParameter
Caller provided variable that receives the device parameter field. The value is device specifc,
for more information see also the SCSI-2 specification.
IsWriteProtectFlag
Caller provoded variable that recieves the extracted write protect flag of the medium type field.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
This function fails if the device is not ready, see also HCLS_MS_IsMediumReady. This
function does not return any page information, see also
HCLS_MS_ReadModeSenseRawPage. The mode sense command is a optional SCSI
command but is implemented in USB mass storage devices.
The function is blocking.
See Also
HCLS_MS_OpenLun (page 276)
280 USB Bus Driver Reference Manual

HCLS_MS_IsMediumReady (page 284)
HCLS_MS_ReadModeSenseRawPage (page 282)
14 Mass Storage Class Driver Reference
USB Bus Driver Reference Manual 281

14 Mass Storage Class Driver Reference
HCLS_MS_ReadModeSenseRawPage
This function returns the mode parameter in raw format. It is a optional command and it is not
always needed.
Definition
USBH_STATUS
HCLS_MS_ReadModeSenseRawPage(
HCLS_MS_LUN_HANDLE Handle,
T_UINT8 pageCode,
T_UINT8* buffer,
T_UINT32 size,
T_UINT32* length,
T_BOOL* modeHeader8ByteFlag
);
Parameters
Handle
This parameter is the LUN handle returned by HCLS_MS_OpenLun.
pageCode
Page code of the Mode parameter that is returned. The page code is value of type
TSCSI_XXX_MODE_PAGE (xxx represent the page), see also tscsi.h. It can be combined
through an OR operator with a value of type TSCSI_PAGE_CONTROL_XXX.
buffer
Pointer to a caller provided buffer that receives the mode parameter in raw format. The caller
provides the storage of the buffer. The argument must not be NULL.
size
The size in bytes of the buffer given with buffer.
length
Caller provided variable that receives the number of bytes that were written to the buffer.
The caller provides the storage of the variable. The argument must not be NULL.
modeHeader8ByteFlag
Caller provided variable that receives T_TRUE or T_FALSE depending on the type of the
header. The caller provides the storage of the variable. The argument must not be NULL. This
parameter is needed to detect the mode parameter header type. If the parameter receives
T_TRUE the header has a size of 8 byte, otherwise if T_FALSE is received the header has a
size of 4 byte. For more information see SCSI-2 specification.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
282 USB Bus Driver Reference Manual

Comments
14 Mass Storage Class Driver Reference
If the device is not ready the function fails, see also HCLS_MS_IsMediumReady.
The function is blocking.
See Also
HCLS_MS_OpenLun (page 276)
HCLS_MS_IsMediumReady (page 284)
USB Bus Driver Reference Manual 283

14 Mass Storage Class Driver Reference
HCLS_MS_IsMediumReady
Send a Test Unit Ready SCSI command to the device.
Definition
USBH_STATUS
HCLS_MS_IsMediumReady(
HCLS_MS_LUN_HANDLE Handle
);
Parameter
Handle
This parameter is the LUN handle returned by HCLS_MS_OpenLun.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
It is useful for Detection of a medium, e.g. to detect a SD card in the medium. Before any file
operation the device and the medium should be ready.
The function is blocking.
284 USB Bus Driver Reference Manual

HCLS_MS_ReadSectors
This function reads sectors from a USB Mass Storage device.
Definition
USBH_STATUS
HCLS_MS_ReadSectors(
HCLS_MS_LUN_HANDLE Handle,
T_UINT32 SectorAddress,
T_UINT32 NumSectors,
T_UINT8* Buffer
);
Parameters
Handle
This parameter is the LUN handle returned by HCLS_MS_OpenLun.
SectorAddress
This parameter describes the first sector to read.
NumSectors
This parameter determines the number of sectors to read.
14 Mass Storage Class Driver Reference
Buffer
Pointer to a caller provided buffer that receives the data read from the sectors. The caller
provides the storage of the buffer. The argument must not be NULL. The buffer memory that
is passed to this function must be DMA memory. For more information about this memory
please see section 5.3 at page 29.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise.
Comments
A valid LUN has to be requested by a call to HCLS_MS_GetLuns before you are able to
successfully call HCLS_MS_ReadSectors.
If the LUN is not ready it returns an error, see also HCLS_MS_IsMediumReady.
The function is blocking.
See Also
HCLS_MS_OpenLun (page 276)
HCLS_MS_WriteSectors (page 287)
USB Bus Driver Reference Manual 285

14 Mass Storage Class Driver Reference
HCLS_MS_GetLuns (page 275)
HCLS_MS_IsMediumReady (page 284)
286 USB Bus Driver Reference Manual

HCLS_MS_WriteSectors
This function writes sectors to a USB Mass Storage device.
Definition
USBH_STATUS
HCLS_MS_WriteSectors(
HCLS_MS_LUN_HANDLE Handle,
T_UINT32 SectorAddress,
T_UINT32 NumSectors,
T_UINT8* Buffer
);
Parameters
Handle
This parameter is the LUN handle returned by HCLS_MS_OpenLun.
SectorAddress
This parameter describes the first sector to write.
NumSectors
This parameter determines the number of sectors to write.
14 Mass Storage Class Driver Reference
Buffer
Pointer to a caller provided buffer that contains the data to write to the sectors. The caller
provides the storage of the buffer. The argument must not be NULL. The buffer memory that
is passed to this function must be DMA memory. For more information about this memory
please see section 5.3 at page 29.
Return Value
This function returns USBH_STATUS_SUCCESS in case of success or an appropriate error
code otherwise. If the medium is write protected the function returns
HCLS_MS_STATUS_WRITE_PROTECT.
Comments
HCLS_MS_WriteSectors can be called after a valid LUN was requested by a call to
HCLS_MS_GetLuns.
If the LUN is not ready it returns an error, see also HCLS_MS_IsMediumReady.
The function is blocking.
USB Bus Driver Reference Manual 287

14 Mass Storage Class Driver Reference
See Also
HCLS_MS_OpenLun (page 276)
HCLS_MS_ReadSectors (page 285)
HCLS_MS_GetLuns (page 275)
HCLS_MS_IsMediumReady (page 284)
288 USB Bus Driver Reference Manual

14.2 Structures
T_UNIT_INFO
This structure contains information of a logical unit.
Definition
typedef struct _T_UNIT_INFO{
T_UINT8 InquiryDeviceType;
unsigned int physLun;
} T_UNIT_INFO;
Members
14 Mass Storage Class Driver Reference
InquiryDeviceType
This field contains the device type returned from the SCSI INQUIRY command, see also
define TSCSI_INQUIRY_xxx_DEVICE_TYPE in tscsi.h.
physLun
This specify the zero indexed based LUN.
USB Bus Driver Reference Manual 289

14 Mass Storage Class Driver Reference
14.3 Status Codes
Table 2 lists the error codes returned by the Mass Storage Class Driver. A detailed description can
be found in section 14.4 at page 291.
Table 2: Error codes
Error Code Numerical Value
HCLS_MS_STATUS_LENGTH 0x1000
HCLS_MS_STATUS_COMMAND_FAILED 0x1002
HCLS_MS_STATUS_INTERFACE_PROTOCOL 0x1003
HCLS_MS_STATUS_INTERFACE_SUB_CLASS 0x1004
HCLS_MS_STATUS_SENSE_REPEAT 0x1006
HCLS_MS_STATUS_WRITE_PROTECT 0x1007
HCLS_MS_STATUS_NOT_READY 0x1008
290 USB Bus Driver Reference Manual

14.4 Status Codes Description
HCLS_MS_STATUS_LENGTH (0x1000L)
The operation detected a length error.
HCLS_MS_STATUS_COMMAND_FAILED (0x1002L)
14 Mass Storage Class Driver Reference
This error is reported if the command code was sent successfully but the status returned from the
device indicates a command error.
HCLS_MS_STATUS_INTERFACE_PROTOCOL (0x1003L)
The used interface protocol is not supported. The interface protocol is defined by the interface
descriptor.
HCLS_MS_STATUS_INTERFACE_SUB_CLASS (0x1004L)
The used interface sub class is not supported. The interface sub class is defined by the interface
descriptor.
HCLS_MS_STATUS_SENSE_REPEAT (0x1006L)
The command is repeated again because the device has aborted the command or at the time the
command is send the device has been reset.
HCLS_MS_STATUS_WRITE_PROTECT (0x1007L)
This error indicates that the medium is write protected. It is returned by HCLS_MS_WriteSectors.
HCLS_MS_STATUS_NOT_READY (0x1008L)
This error indicates the logical unit addressed cannot be accessed. Operator intervention may be
required to correct this condition, e.g. insert the medium.
USB Bus Driver Reference Manual 291

Index
HCLS_ACM_AbortRead, 192
HCLS_ACM_AbortWrite, 187
HCLS_ACM_Close, 175
HCLS_ACM_CreateInterfaceList, 168
HCLS_ACM_DestroyInterfaceList, 169
HCLS_ACM_DeviceConnected, 166
HCLS_ACM_DeviceRemoved, 172
HCLS_ACM_DeviceStatusChanged, 179
HCLS_ACM_Exit, 165
HCLS_ACM_GetDeviceStatus, 177
HCLS_ACM_GetInterfaceID, 170
HCLS_ACM_GetInterfaceInfo, 171
HCLS_ACM_GetReadFifoSize, 189
HCLS_ACM_GetWriteFifoSize, 184
HCLS_ACM_Init, 164
HCLS_ACM_IsDevicePresent, 176
HCLS_ACM_LineCoding, 194
HCLS_ACM_Open, 173
HCLS_ACM_Read, 190
HCLS_ACM_RegisterConnectHandler, 167
HCLS_ACM_RegisterStatusChangeHandler, 180
HCLS_ACM_ResetReadPipe, 193
HCLS_ACM_ResetWritePipe, 188
HCLS_ACM_SendBreak, 183
HCLS_ACM_SetControlLineState, 182
HCLS_ACM_SetLineCoding, 181
HCLS_ACM_Write, 185
HCLS_HID_AbortRead, 230
HCLS_HID_AbortWrite, 226
HCLS_HID_Close, 207
HCLS_HID_CreateInterfaceList, 200
HCLS_HID_DestroyInterfaceList, 201
HCLS_HID_DeviceConnected, 198
HCLS_HID_DeviceRemoved, 204
HCLS_HID_Exit, 197
HCLS_HID_GetHidDescriptor, 209
HCLS_HID_GetIdleRequest, 220
HCLS_HID_GetInterfaceID, 202
HCLS_HID_GetInterfaceInfo, 203
HCLS_HID_GetNumDescriptors, 210
HCLS_HID_GetProtocolRequest, 218
HCLS_HID_GetReadFifoSize, 223
HCLS_HID_GetReportDescriptorSize, 211
HCLS_HID_GetReportDescriptor, 212
HCLS_HID_GetReportRequest, 214
HCLS_HID_GetWriteFifoSize, 222
293

HCLS_HID_Init, 196
HCLS_HID_IsDevicePresent, 208
HCLS_HID_Open, 205
HCLS_HID_ReadReport, 228
HCLS_HID_RegisterConnectHandler, 199
HCLS_HID_ResetReadPipe, 231
HCLS_HID_ResetWritePipe, 227
HCLS_HID_SetIdleRequest, 221
HCLS_HID_SetProtocolRequest, 219
HCLS_HID_SetReportRequest, 216
HCLS_HID_WriteReport, 224
HCLS_MS_CloseLun, 277
HCLS_MS_Close, 274
HCLS_MS_CreateInterfaceList, 267
HCLS_MS_DestroyInterfaceList, 268
HCLS_MS_DeviceConnected, 265
HCLS_MS_DeviceRemove, 271
HCLS_MS_Exit, 264
HCLS_MS_GetInterfaceID, 270
HCLS_MS_GetInterfaceInfo, 269
HCLS_MS_GetLuns, 275
HCLS_MS_InitLun, 278
HCLS_MS_Init, 263
HCLS_MS_IsMediumReady, 284
HCLS_MS_ModeSenseAllPages, 280
HCLS_MS_OpenLun, 276
HCLS_MS_Open, 272
HCLS_MS_ReadCapacity, 279
HCLS_MS_ReadModeSenseRawPage, 282
HCLS_MS_ReadSectors, 285
HCLS_MS_RegisterConnectHandler, 266
HCLS_MS_STATUS_COMMAND_FAILED, 291
HCLS_MS_STATUS_INTERFACE_PROTOCOL, 291
HCLS_MS_STATUS_INTERFACE_SUB_CLASS, 291
HCLS_MS_STATUS_LENGTH, 291
HCLS_MS_STATUS_NOT_READY, 291
HCLS_MS_STATUS_SENSE_REPEAT, 291
HCLS_MS_STATUS_WRITE_PROTECT, 291
HCLS_MS_WriteSectors, 287
HCLS_PRN_AbortRead, 261
HCLS_PRN_AbortWrite, 255
HCLS_PRN_Close, 243
HCLS_PRN_CreateInterfaceList, 236
HCLS_PRN_DestroyInterfaceList, 237
HCLS_PRN_Exit, 233
HCLS_PRN_GetAvailableInterfaces, 245
HCLS_PRN_GetCurrentInterface, 246
HCLS_PRN_GetDeviceId, 248
294

HCLS_PRN_GetInterfaceID, 238
HCLS_PRN_GetInterfaceInfo, 239
HCLS_PRN_GetPortStatus, 249
HCLS_PRN_Init, 232
HCLS_PRN_IsPrinterPresent, 244
HCLS_PRN_Open, 241
HCLS_PRN_PrinterConnected, 234
HCLS_PRN_PrinterRemove, 240
HCLS_PRN_ReadSync, 259
HCLS_PRN_Read, 257
HCLS_PRN_RegisterConnectHandler, 235
HCLS_PRN_ResetReadPipe, 262
HCLS_PRN_ResetWritePipe, 256
HCLS_PRN_SetInterface, 247
HCLS_PRN_SoftReset, 250
HCLS_PRN_WriteSync, 253
HCLS_PRN_Write, 251
HcohcReadReg, 126
HcohcWriteReg, 125
T_UNIT_INFO, 289
TAL_AllocateDmaDescMemory, 132
TAL_AllocateDmaMemory, 135
TAL_AllocEvent, 148
TAL_AllocMutex, 153
TAL_AllocTimer, 142
TAL_BuildDmaMd, 140
TAL_CancelTimer, 145
TAL_CreateTask, 157
TAL_DeleteTask, 158
TAL_EnterMutex, 155
TAL_Exit, 129
TAL_FlushCache, 138
TAL_FreeDmaDescMemory, 133
TAL_FreeDmaMemory, 136
TAL_FreeEvent, 149
TAL_FreeMutex, 154
TAL_FreeTimer, 143
TAL_Free, 131
TAL_GetCacheLineSize, 134
TAL_GetTime, 146
TAL_Init, 128
TAL_InvalidateCache, 137
TAL_LeaveMutex, 156
TAL_Malloc, 130
TAL_MD_HEADER, 160
TAL_MD_PAGE_ENTRY, 161
TAL_MD, 162
295

TAL_ResetEvent, 151
TAL_SetEvent, 150
TAL_Sleep, 147
TAL_StartTimer, 144
TAL_TIMER_HANDLE, 163
TAL_TimerCallbackRoutine, 141
TAL_WaitEvent, 152
TAL_WaitTask, 159
TAL_WriteSync, 139
URB_BULK_INT_REQUEST, 100
URB_COMPLETION, 73
URB_CONTROL_REQUEST, 98
URB_ENDPOINT_REQUEST, 104
URB_FUNCTION, 116
URB_HEADER, 111
URB_ISO_FRAME, 101
URB_ISO_REQUEST, 102
URB_SET_CONFIGURATION, 105
URB_SET_INTERFACE, 106
URB_SET_SUSPEND_STATE, 107
URB, 108
USBH_AbortEndpointAndWait, 76
USBH_CloseInterface, 54
USBH_CreateEhcController, 40
USBH_CreateInterfaceList, 41
USBH_CreateOhcController, 39
USBH_DestroyInterfaceList, 42
USBH_ENUM_ERROR, 94
USBH_EnumerateDevices, 38
USBH_EnumErrorNotification, 49
USBH_EP_MASK, 96
USBH_Exit, 34
USBH_GetClassDescriptor, 60
USBH_GetCurrentConfigurationDescriptor, 56
USBH_GetDeviceDescriptor, 55
USBH_GetEndpointDescriptor, 62
USBH_GetFrameNumber, 67
USBH_GetHubPortHandlebyInterface, 69
USBH_GetHubPortHandlebyTopology, 70
USBH_GetInterfaceDescriptor, 58
USBH_GetInterfaceIDByHandle, 68
USBH_GetInterfaceID, 43
USBH_GetInterfaceInfo, 44
USBH_GetPortPowerState, 72
USBH_GetSerialNumber, 64
USBH_GetSpeed, 66
USBH_GetStatusStr, 75
296

USBH_Init, 33
USBH_INTERFACE_INFO, 92
USBH_INTERFACE_MASK, 90
USBH_OpenInterface, 53
USBH_PNP_EVENT, 114
USBH_PNP_NOTIFICATION, 110
USBH_PnpNotification, 46
USBH_POWER_STATE, 115
USBH_POWER_SWITCHING_NOT_SUPPORTED, 124
USBH_ProcessInterrupt, 36
USBH_RegisterEnumErrorNotification, 50
USBH_RegisterPnPNotification, 47
USBH_RemoveHostController, 37
USBH_ResetDeviceAndWait, 82
USBH_ResetEndpointAndWait, 80
USBH_RestartEnumError, 52
USBH_ServiceISR, 35
USBH_SetConfigurationAndWait, 84
USBH_SetInterfaceAndWait, 86
USBH_SetPortPowerState, 71
USBH_SetupRequestAndWait, 88
USBH_SPEED, 113
USBH_STATUS_BITSTUFFING, 121
USBH_STATUS_BUFFER_OVERFLOW, 122
USBH_STATUS_BUFFER_OVERRUN, 122
USBH_STATUS_BUFFER_UNDERRUN, 122
USBH_STATUS_BUSY, 123
USBH_STATUS_CANCELED, 123
USBH_STATUS_CRC, 121
USBH_STATUS_DATA_OVERRUN, 121
USBH_STATUS_DATA_UNDERRUN, 122
USBH_STATUS_DATATOGGLE, 121
USBH_STATUS_DEVICE_REMOVED, 123
USBH_STATUS_ENDPOINT_HALTED, 123
USBH_STATUS_ERROR, 122
USBH_STATUS_INVALID_ALIGNMENT, 124
USBH_STATUS_INVALID_DESCRIPTOR, 123
USBH_STATUS_INVALID_PARAM, 122
USBH_STATUS_NO_MEMORY, 124
USBH_STATUS_NO_RESOURCES, 124
USBH_STATUS_NOT_ACCESSED, 122
USBH_STATUS_NOTRESPONDING, 121
USBH_STATUS_PENDING, 123
USBH_STATUS_PID_CHECK, 121
USBH_STATUS_PORT, 123
USBH_STATUS_STALL, 121
USBH_STATUS_SUCCESS, 121
USBH_STATUS_TIMEOUT, 123
297

USBH_STATUS_UNEXPECTED_PID, 121
USBH_STATUS_USER, 124
USBH_SubmitUrbAndWait, 78
USBH_SubmitUrb, 74
USBH_SUSPEND_STATE, 119
USBH_UnregisterEnumErrorNotification, 51
USBH_UnregisterPnPNotification, 48
USBH_WaitForIdleStack, 45
298