1 /******************************************************************************* 2 * Copyright 2019-2020 Microchip FPGA Embedded Systems Solutions. 3 * 4 * SPDX-License-Identifier: MIT 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 22 * IN THE SOFTWARE. 23 * 24 * PolarFire SoC MSS USB Driver Stack 25 * USB Logical Layer (USB-LL) 26 * USBH driver 27 * 28 * USBH driver public API. 29 * 30 */ 31 /*=========================================================================*//** 32 @mainpage PolarFire SoC MSS USB Host driver (USBH) 33 34 ============================================================================== 35 Introduction 36 ============================================================================== 37 The USB Host Driver (USBH) is part of the USB-LL layer of the MSS USB driver 38 stack. The USBH driver implements the core functionality of the USB host mode 39 operations. The USBH driver is responsible for the following functionalities. 40 - Device attach and detach handling 41 - Enumeration and USB Standard requests 42 - Device Suspend, Resume and Reset handling 43 - USB transfers management 44 - USBH-Class call-back interface 45 - Application call-back interface 46 47 ============================================================================== 48 Theory of Operation 49 ============================================================================== 50 The following steps are involved in the operation of the USBH driver: 51 - Configuration 52 - Initialization 53 - USBH-Class Interface 54 - Application Interface 55 - Data transfer 56 57 The USBH driver operation depends on user configuration provided in 58 mss_usb_config.h. 59 60 -------------------------------- 61 Configuration 62 -------------------------------- 63 The following parameter must be defined in the mss_usb_config.h file to 64 operate the MSS USB hardware block in USB Host mode. 65 66 MSS_USB_HOST_MODE Configures the MSS USB Driver Stack to operate in USB 67 host mode. 68 69 -------------------------------- 70 Initialization 71 -------------------------------- 72 The USBH driver must be initialized by calling the MSS_USBH_init() 73 initialization function with a parameter to provide the application call-back 74 interface. Once initialized the USBH driver is ready to detect the attach 75 event on the USB port. The application call-back interface is used to provide 76 information about the events on the USB bus to the application. The 77 MSS_USBH_task() is the main task of the USBH driver which implements the state 78 machines for monitoring the USB bus activities. This function must be called 79 repeatedly by the application to allow USBH driver to run it's state machines. 80 A timer/scheduler can be used to call this function at regular intervals or it 81 can be called from the main continuous foreground loop of the application. 82 The function MSS_USBH_1ms_tick() must be called to provide a 1milisecond time 83 tick to the USBH driver. This time tick is used by the USBH driver to track 84 the enumeration process and other housekeeping purposes. The 85 MSS_USBH_get_milis() function is provided to get the number of milliseconds 86 lapsed from the system reset. The MSS_USBH_test_mode() function is provided to 87 force the MSS USB in test modes as required by the USB compliance test 88 specification. This function has no use in normal operations with a attached 89 USB device. 90 91 -------------------------------- 92 USBH-Class Call-back Interface 93 -------------------------------- 94 This driver encapsulates the generic USB protocol functionality from the USB 95 class functionality. This driver needs the USBH-Class driver to implement a 96 set of call-back functions to pass on the control to the USBH-Class driver for 97 handling the USB class specific functionality. This driver provides a data 98 type mss_usbh_class_cb_t which must be implemented by the USBH-Class driver. 99 This data type is the collection of call-back functions which must be 100 implemented by the USBH-Class driver. Implementing all the elements of this 101 structure may not be necessary for a specific USB class. The USBH-Class driver 102 must define a structure of type mss_usbh_class_cb_t and implement its required 103 elements. The function MSS_USBH_register_class_driver() must be used to inform 104 the USBH driver about this call-back interface and the supported USB Class 105 information 106 The table below lists the prototypes of the call-back functions which are part 107 of the mss_usbh_class_cb_t type and the event in which they are called. 108 109 | Call-back Element | Event | 110 |------------------------|---------------------------------------------------| 111 | usbh_class_allocate | Called when a match is found between the class | 112 | | sub-class code and protocol code of the attached | 113 | | device and the corresponding parameters provided | 114 | | by the USBH-Class driver in the class_id parameter| 115 | usbh_class_release | Called when the device for which this USBH-Class | 116 | | driver is assigned is detached | 117 | usbh_class_cep_xfr_done| Called when a transfer started by this USBH-Class | 118 | | driver is complete | 119 | usbh_class_tx_done | Called when a transfer started on the OUT pipe by | 120 | | this USBH-Class driver is complete | 121 | usbh_class_rx_done | Called when a transfer started on the IN pipe by | 122 | | this USBH-Class driver is complete | 123 | usbh_class_sof | The function pointed by the usbh_class_sof element| 124 | | will be called when a new (micro) frame starts | 125 126 -------------------------------- 127 Application Call-back Interface 128 -------------------------------- 129 The USBH driver uses interrupts to respond to the events on MSS USB. The 130 USBH driver handles the enumeration of the attached device internally. 131 The enumeration process can take long time (hundreds of milliseconds) to 132 complete. The USBH driver uses application call-back interface to inform the 133 application about the events on the USB bus as they happen. The application 134 may implement these call-back functions to take application specific action 135 on each event or to provide error/status messages to the user. 136 137 The table below lists the prototypes of the call-back functions which are 138 part of the mss_usbh_user_cb_t type and the event in which they are called. 139 140 | Element | Call-back Event | 141 |---------------------------------|------------------------------------------| 142 | usbh_tdev_attached | Called when a device-attach event is | 143 | | detected by the USBH driver. At this | 144 | | point the device is not enumerated. | 145 | usbh_tdev_dettached | Called when a device-detach event is | 146 | | detected by the USBH driver | 147 | usbh_tdev_oc_error | Called when an over-current condition is | 148 | | detected by the USBH driver | 149 | usbh_tdev_enumerated | Called when the attached device is | 150 | | successfully enumerated | 151 | usbh_tdev_class_driver_assigned | Called when a matching class driver is | 152 | | assigned to the attached device | 153 | usbh_tdev_not_supported | Called when a device which is not | 154 | | supported by the USBH driver is detected | 155 | usbh_tdev_permanent_error | Called if there was error during data | 156 | | transfer operations with the attached | 157 | | device | 158 159 -------------------------------- 160 Data transfer 161 -------------------------------- 162 The USB host uses pipe, a representation of logical connection from endpoint 163 on MSS USB to the endpoint on the target device. The transmit pipe or the 164 receive pipe must first be configured before starting the data transfer on it. 165 The functions MSS_USBH_configure_in_pipe() and MSS_USBH_configure_out_pipe() 166 must be used to configure an IN(data moving from device to host) and an 167 OUT(data moving from host to device) pipe respectively. 168 169 The application must use MSS_USBH_write_out_pipe() function to start data 170 transmission on a OUT pipe. This function prepares the MSS USB to transmit 171 data to the device. However, actual transmission happens depending on the 172 transfer type and the selected interval. This function is non-blocking. 173 The USBH-Class driver will be informed about data transmission completion or 174 transmission errors by a call to its call-back function. Please refer 175 USBH-Class Interface section above for more details. 176 177 To receive data from attached USB device, application must use 178 MSS_USBH_read_in_pipe() function. This function prepares the MSS USB to 179 receive data from the attached device. However, actual data transfer happens 180 depending on the transfer type and the selected interval. This function is 181 non-blocking. On receiving data or in case of errors during this operation 182 the USBH-Class driver will be informed about it by calling a call-back 183 function. Please refer the USBH-Class Interface section above for more 184 details. 185 186 This driver supports multi-packet Bulk transfer (both IN and OUT), to make 187 sure that it is able to use the full bandwidth offered by USB Bulk transfers. 188 When a transfer size of more than wMaxPktSize is provided to this driver using 189 MSS_USBH_write_out_pipe() function or MSS_USBH_read_in_pipe() function, this 190 driver handles this multi-packet transfer internally by dividing it into 191 multiple Bulk transfers of wMaxPktSize each. This way no application 192 intervention is required till the total multi-packet Bulk transfer is 193 complete. 194 195 The USBH driver supports Bulk transfers using the DMA inside MSS USB or 196 without using the internal DMA. It is advised that the USBH driver is 197 configured to use the internal DMA in order to free up the application from 198 transferring data to/from MSS USB hardware block. However, the internal DMA 199 can access only aligned address. Care must be taken that the buffer address 200 provided to the USBH driver must be modulo-4. This is not a requirement when 201 the MSS USB driver is configured not to use internal DMA. 202 203 All the control transfers happen on the control pipe. The control pipe is 204 shared by the USBH driver and the USBH-Class driver. When the USBH-Class 205 driver needs to perform control transfer on the attached device, it must first 206 configure the control pipe using the MSS_USBH_configure_control_pipe() 207 function. The MSS_USBH_start_control_xfr() function can be used to start the 208 control transfer After the control pope is configured. The data direction is 209 determined by a parameter provided with this function. The USBH-Class driver 210 will be informed about the data transfer completion or the error status by 211 calling a call-back function. Please refer the USBH-Class Interface section 212 above for more details. The control transfer can be started by a USBH-Class 213 driver only when the control pipe is free.The MSS_USBH_get_cep_state() 214 function can be used to know the current state of the control pipe. At the 215 start of the control transfer the USBH driver must send a setup-packet to the 216 attached device in the setup phase. The function 217 MSS_USBH_construct_get_descr_command() can be used to construct the setup 218 packet as per the USB specification for the transfer to be performed. This 219 function formats the setup packet depending on the parameters provided with 220 this function. 221 222 The application may choose to keep the MSS USB in suspend state to conserve 223 power to the USB device, and the MSS USB, In this state the MSS USB does not 224 send any frames on the bus and there will be no bus activity. This will also 225 ensure that the attached device enters suspend state as specified in the 226 USB2.0 specification. The USBH driver provides the MSS_USBH_suspend() function 227 to suspend the MSS USB. The MSS_USBH_resume() function must be used to 228 resume the normal operations. 229 230 The table below provides the list of all the functions provided by USBH 231 driver. 232 233 | function | Description | 234 |------------------------------|---------------------------------------------| 235 | MSS_USBH_init() | Initialize the MSS USB to operate in the | 236 | | host mode | 237 | | | 238 | MSS_USBH_task() | Main task of the USBH driver where the state| 239 | | machines are implemented | 240 | | | 241 | MSS_USBH_register_class_ | Used to register the class driver handle | 242 | driver() | with the USBH driver | 243 | | | 244 | MSS_USBH_configure_control_ | Configures the control pipe for control | 245 | pipe() | transfers with the attached device | 246 | | | 247 | MSS_USBH_configure_in_pipe() | Configures the IN pipe for the USB IN | 248 | | transfers with the attached device | 249 | | | 250 | MSS_USBH_configure_out_pipe()| Configures the OUT pipe for the USB OUT | 251 | | transfers with the attached device | 252 | | | 253 | MSS_USBH_write_out_pipe() | Writes data on to the attached device using | 254 | | the OUT pipe | 255 | | | 256 | MSS_USBH_read_in_pipe() | Reads data from the attached device using | 257 | | the IN pipe | 258 | | | 259 | MSS_USBH_get_tdev_state() | Used to find out the current state of the | 260 | | attached device | 261 | | | 262 | MSS_USBH_suspend() | Suspends the MSS USB core. No frames are | 263 | | transferred | 264 | | | 265 | MSS_USBH_resume() | Resumes the previously suspended MSS USB | 266 | | | 267 | MSS_USBH_get_std_dev_descr() | Reads the device descriptor from the | 268 | | attached device | 269 | | | 270 | MSS_USBH_1ms_tick() | Time stamping and housekeeping function | 271 | | | 272 | MSS_USBH_get_milis() | Used to know the number of milliseconds | 273 | | lapsed after reset | 274 | | | 275 | MSS_USBH_construct_get_descr | Formats the provided parameters into a USB | 276 | _command() | standard setup packet for GET_DESCRIPTOR | 277 | | command | 278 | | | 279 | MSS_USBH_start_control_xfr() | Starts a control transfer on previously | 280 | | configured control pipe | 281 | | | 282 | MSS_USBH_get_cep_state() | Provides the current state of the control | 283 | | pipe | 284 | | | 285 | MSS_USBH_test_mode() | Initiates compliance test mode as specified | 286 | | by the parameter. | 287 288 *//*=========================================================================*/ 289 290 #ifndef __MSS_USB_HOST_H_ 291 #define __MSS_USB_HOST_H_ 292 293 #include "mss_usb_common_cif.h" 294 #include "mss_usb_common_reg_io.h" 295 296 #ifdef __cplusplus 297 extern "C" { 298 #endif 299 300 #ifdef MSS_USB_HOST_ENABLED 301 302 /*-------------------------------------------------------------------------*//** 303 Constant values exported by USBH driver 304 */ 305 306 /*-------------------------------------------------------------------------*//** 307 The following constants are used to identify the exact reason due to which the 308 USBH driver is not supporting the attached device. One of these values is 309 passed as a parameter to the call-back function usbh_tdev_not_supported when 310 USBH driver detects respective condition. 311 */ 312 /* 313 Devices operating at the USB full speed are not supported. 314 */ 315 #define FS_DEV_NOT_SUPPORTED -15 316 317 /* 318 Devices operating at the USB low speed are not supported. 319 */ 320 #define LS_DEV_NOT_SUPPORTED -14 321 322 /* 323 Device belonging to the USB HUB class is detected. The Hub class is not 324 supported by the USBH driver. 325 */ 326 #define HUB_CLASS_NOT_SUPPORTED -13 327 328 /* 329 Attached device class description does not match the class description 330 supported by the registered class driver. 331 */ 332 #define CLASS_DRIVER_NOT_MATCHED -12 333 334 /* 335 The registered class driver is already in assigned state when new device 336 attachment is detected. 337 */ 338 #define CLASS_DRIVER_NOT_FREE -11 339 340 /* 341 The power requirement for the attached device, as described in the bMaxPower 342 field of configuration descriptor, can not be supported by the USBH driver. 343 */ 344 #define CONF_DESC_POWER_LIM_EXCEED -10 345 346 /* 347 The value received in bDescriptorType field in configuration descriptor is 348 invalid. 349 */ 350 #define CONF_DESC_WRONG_DESC_TYPE -9 351 352 /* 353 The value received in bLength field of the configuration descriptor does not 354 match the standard value (9) as specified in the USB2.0 specification. 355 */ 356 #define CONF_DESC_WRONG_LENGTH -8 357 358 /* 359 The value received in bMaxPacketSize0 field of the device descriptor is not 8 360 for a LS device. 361 */ 362 #define DEV_DESC_LS_MAXPKTSZ0_NOT8 -7 363 364 /* 365 The value received in bMaxPacketSize0 field of the device descriptor is not 64 366 for a HS device. 367 */ 368 #define DEV_DESC_HS_MAXPKTSZ0_NOT64 -6 369 370 /* 371 The value received in bcdDevice field of the device descriptor for a HS device 372 does not indicate USB2.0 373 */ 374 #define DEV_DESC_HS_USBBCD_NOT200 -5 375 376 /* 377 The value received in the bMaxPacketSize0 field of the device descriptor is 378 invalid. For LS device this value must be 8. For HS device this value must be 379 64. For FS device this value must be 8, 16, 32, or 64. 380 */ 381 #define DEV_DESC_WRONG_MAXPKTSZ0 -4 382 383 /* 384 The value received in the bcdDevice field of the device descriptor is invalid. 385 For HS device this value must indicate USB2.0. 386 */ 387 #define DEV_DESC_WRONG_USBBCD -3 388 389 /* 390 The value received in the bDescriptorType field in device descriptor is 391 invalid. 392 */ 393 #define DEV_DESC_WRONG_DESC_TYPE -2 394 395 /* 396 The value received in the bLength field of the device descriptor does not 397 match the standard value (18). 398 */ 399 #define DEV_DESC_WRONG_LENGTH -1 400 401 /* 402 The following constants are used as the return values for the call-back 403 functions, implemented by the USBH-Class driver as part of mss_usbh_class_cb_t 404 type, which are called by the USBH driver. The USBH driver uses these values 405 to infer whether or not the call-back function was successfully executed. The 406 current control transfer is stalled if the return value is USB_FAIL. 407 */ 408 #define USB_FAIL 0u 409 #define USB_SUCCESS 1u 410 411 /*-------------------------------------------------------------------------*//** 412 Data structures exported by USBH driver 413 */ 414 415 /*-------------------------------------------------------------------------*//** 416 The mss_usbh_class_cb_t provides the prototype of the structure that must be 417 implemented by the USBH-Class driver to provide the call-back functions which 418 will be called by the USBH driver to communicate events on the target device. 419 420 class_id 421 The class_id parameter is the place-holder for identifying the USBH-Class 422 driver which is implementing this call-back interface. This parameter is used 423 by the USBH driver to identify and assign the class driver to the attached 424 device.The MSS_USBH_register_class_driver() function must be used to register 425 a class driver with the the USBH driver. This parameter must be of the form: 426 427 | Class id bit | Description | 428 |-------------- |------------------------------------------------------------| 429 | D7 - D0 | USB Std Protocol code | 430 | D15 - D8 | USB Std sub-class code | 431 | D23 - D16 | USB Std class code | 432 | D31 - D24 | 0x00 | 433 434 usbh_class_allocate 435 The function pointed by the usbh_class_allocate element will be called when a 436 match is found between the class code, sub-class code and protocol code of the 437 attached device and the corresponding parameters provided by the USBH-Class 438 driver in class_id parameter. The tdev_addr parameter provides the non-zero 439 device address assigned to the attached device by the USBH driver. 440 441 usbh_class_release 442 The function pointed by the usbh_class_release element will be called when the 443 device for which this USBH-Class driver is assigned is detached. The tdev_addr 444 parameter provides the non-zero device address assigned to the attached device 445 by the USBH driver. 446 447 usbh_class_cep_xfr_done 448 The function pointed by the usbh_class_cep_xfr_done element will be called 449 when a control transfer started by this USBH-Class driver is complete. The 450 tdev_addr parameter provides the non-zero device address assigned to the 451 attached device by the USBH driver. The status parameter indicates whether or 452 not the current control transfer was completed successfully. The count 453 parameter provides the number of bytes transferred in the current control 454 transfer. The status parameter provides the error status of current control 455 transfer. A non-zero value indicates that there was an error. 456 457 usbh_class_tx_done 458 The function pointed by the usbh_class_tx_done element will be called 459 when a transfer started on OUT pipe by this USBH-Class driver is complete. 460 The tdev_addr parameter provides the non-zero device address assigned to the 461 attached device by USBH driver. The status parameter indicates whether or not 462 the current transfer was completed successfully. The count parameter provides 463 the number of bytes transferred in the current control transfer. The status 464 parameter provides the error status of the current control transfer. A 465 non-zero value indicates that there was an error. 466 467 usbh_class_rx_done 468 The function pointed by the usbh_class_rx_done element will be called 469 when a transfer started on the IN pipe by this USBH-Class driver is complete. 470 The tdev_addr parameter provides the non-zero device address assigned to the 471 attached device by the USBH driver. The status parameter indicates whether or 472 not the current transfer was completed successfully. The count parameter 473 provides the number of bytes transferred in the current control transfer. 474 The status parameter provides the error status of current control transfer. 475 A non-zero value indicates that there was an error. 476 477 usbh_class_sof 478 The function pointed by the usbh_class_sof element will be called when a new 479 micro frame starts. The frame_number provides the number of the current 480 micro frame. 481 482 */ 483 typedef struct mss_usbh_class_cb { 484 uint32_t class_id; 485 uint8_t (*usbh_class_allocate)(uint8_t tdev_addr); 486 uint8_t (*usbh_class_release)(uint8_t tdev_addr); 487 uint8_t (*usbh_class_cep_xfr_done)(uint8_t tdev_addr, 488 uint8_t status, 489 uint32_t count); 490 491 uint8_t (*usbh_class_tx_done)(uint8_t tdev_addr, 492 uint8_t status, 493 uint32_t count); 494 495 uint8_t (*usbh_class_rx_done)(uint8_t tdev_addr, 496 uint8_t status, 497 uint32_t count); 498 499 uint8_t (*usbh_class_sof)(uint32_t frame_number); 500 }mss_usbh_class_cb_t; 501 502 /*-------------------------------------------------------------------------*//** 503 The mss_usbh_tdev_info_t type provides the prototype for the detailed 504 information of the attached device. Some of the parameters are only applicable 505 when multi-point support is enabled on MSS USB. Multi-point support is 506 currently not enabled in the USBH driver. 507 508 addr 509 The addr parameter provides the device address assigned to the attached device 510 by the USBH driver. 511 512 speed 513 The speed parameter indicates the USB speed of operation at which the USBH 514 driver is communicating with the attached device. 515 516 state 517 The state parameter provides the current state of the attached device. E.g. 518 address, Configured etc. 519 520 hub_addr 521 The hub_addr parameter provides the address of the hub to which the device is 522 attached. This parameter is meaningful only when Multi-Point support is 523 enabled. Multi-point support is currently not enabled in the USBH driver. 524 525 hub_port 526 The hub_port parameter provides the port number of the hub to which the device 527 is attached. This parameter is meaningful only when Multi-Point support is 528 enabled. Multi-point support is currently not enabled in the USBH driver. 529 530 hub_mtt 531 The hub_mtt parameter indicates whether or not the hub to which the device is 532 attached supports multiple transaction translators. This parameter is 533 meaningful only when Multi-Point support is enabled. Multi-point support is 534 currently not enabled in the USBH driver. 535 536 maxpktsz0 537 The maxpktsz0 parameter provides the maximum packet size of the control 538 endpoint on the attached device. 539 540 state 541 The state parameter provides the current state of the attached device. 542 E.g. address, Configured etc. 543 544 class_handle 545 The class_handle parameter is the class handle registered with the USBH driver 546 using MSS_USBH_register_class_driver() function. This handle is used by the 547 USBH driver to call the call-back functions implemented by the USBH-Class 548 driver. 549 550 */ 551 typedef struct mss_usbh_target_info { 552 uint8_t addr; 553 mss_usb_device_speed_t speed; 554 mss_usb_state_t state; 555 uint8_t hub_addr; 556 uint8_t hub_port; 557 uint8_t hub_mtt; 558 uint16_t tdev_maxpktsz0; 559 mss_usbh_class_cb_t* class_handle; 560 } mss_usbh_tdev_info_t; 561 562 /*-------------------------------------------------------------------------*//** 563 The mss_usbh_user_cb_t provides the prototype of the structure that must be 564 implemented by the application to provide the call-back functions which will 565 be called by the USBH driver to communicate events on the target device. These 566 call-back functions can be used by the application to know the USBH driver 567 state and information about the attached device from the USBH driver. 568 These events are not specific to any USB class. 569 570 usbh_tdev_attached 571 The function pointed by the usbh_tdev_attached element will be called when a 572 device attach even is detected by the USBH driver. At this point the device is 573 not enumerated. The speed parameter indicates the USB speed of operation at 574 which the USBH driver is going to communicate with the attached device. 575 576 usbh_tdev_dettached 577 The function pointed by the usbh_tdev_dettached element will be called when 578 a device detach even is detected by the USBH driver. 579 580 usbh_tdev_oc_error 581 The function pointed by the usbh_tdev_oc_error element will be called when an 582 over-current condition is detected by the USBH driver. 583 584 usbh_tdev_enumerated 585 The function pointed by the usbh_tdev_enumerated element will be called when 586 the attached device is successfully enumerated. At this point the device 587 descriptor is successfully read from the attached device. No class specific 588 information is read from the device yet. The tdev_info parameter gives the 589 information about the attached device. 590 591 usbh_tdev_class_driver_assigned 592 The function pointed by the usbh_tdev_class_driver_assigned element will be 593 called when a matching class driver is assigned to the attached device. 594 The class driver must be previously registered with the USBH driver using 595 MSS_USBH_register_class_driver() function. 596 597 usbh_tdev_not_supported 598 The function pointed by the usbh_tdev_not_supported element will be called 599 when a device which is not supported by the USBH driver is attached. The 600 error_code parameter provides the exact reason why the device is not 601 supported. 602 E.g. devices belonging to Hub class are not supported. 603 604 usbh_tdev_ permanent_error 605 The function pointed by the usbh_tdev_permanent_error element will be called 606 if there is error during data transfer operations with the attached device 607 persists after retries. On detecting an error in data transfer with the 608 attached device, the USBH driver retries for maximum three times. 609 */ 610 typedef struct mss_usbh_user_cb 611 { 612 void (*usbh_tdev_attached)(mss_usb_device_speed_t speed); 613 void (*usbh_tdev_dettached)(void); 614 void (*usbh_tdev_oc_error)(void); 615 void (*usbh_tdev_enumerated)(mss_usbh_tdev_info_t tdev_info); 616 void (*usbh_tdev_class_driver_assigned) (void); 617 void (*usbh_tdev_not_supported)(int8_t error_code); 618 void (*usbh_tdev_permanent_error)(void); 619 } mss_usbh_user_cb_t; 620 621 /*-------------------------------------------------------------------------*//** 622 Data structures internally used by USBH driver 623 */ 624 625 /*-------------------------------------------------------------------------*//** 626 The dev_desc_t provides the prototype of the structure for the standard USB 627 device descriptor. All the parameters of this structure are as per the 628 standard setup packet defined in the USB2.0 specification. 629 630 bLength 631 The bLength parameter indicates the length of the device descriptor in bytes. 632 The meaning of this parameter is exactly as defined by the USB2.0 633 specification. 634 635 bDescriptorType 636 The bDescriptorType parameter indicates the standard descriptor type of this 637 descriptor. The meaning of this parameter is exactly as defined by the USB2.0 638 specification. 639 640 bcdUSB 641 The bcdUSB parameter indicates the USB standard (BCD format) supported by the 642 device. The meaning of this parameter is exactly as defined by the USB2.0 643 specification. 644 645 bDeviceClass 646 The bDeviceClass parameter indicates the standard USB class supported by the 647 device. The meaning of this parameter is exactly as defined by the USB2.0 648 specification. 649 650 bDeviceSubClass 651 The bDeviceSubClass parameter indicates the standard USB sub-class supported 652 by the device. The meaning of this parameter is exactly as defined by the 653 USB2.0 specification. 654 655 bDeviceProtocol 656 The bDeviceProtocol parameter indicates the standard USB data transfer 657 protocol supported by the device. The meaning of this parameter is exactly as 658 defined by the USB2.0 specification. 659 660 bMaxPacketSize0 661 The bMaxPacketSize0 parameter indicates the Maximum packet size of the 662 Endpoint0 on the device. The meaning of this parameter is exactly as defined 663 by the USB2.0 specification. 664 665 idVendor 666 The idVendor parameter indicates Vendor ID of the connected device. The 667 meaning of this parameter is exactly as defined by the USB2.0 specification. 668 669 idProduct 670 The idProduct parameter indicates Product ID of the connected device. The 671 meaning of this parameter is exactly as defined by the USB2.0 specification. 672 673 bcdDevice 674 The bcdDevice parameter indicates release number (BCD format) of the connected 675 device. The meaning of this parameter is exactly as defined by the USB2.0 676 specification. 677 678 iManufacturer 679 The iManufacturer parameter indicates the index of the string descriptor 680 describing the manufacture name of the connected device. The meaning of this 681 parameter is exactly as defined by the USB2.0 specification. 682 683 iProduct 684 The iProduct parameter indicates index of string descriptor describing the 685 product name of the connected device. The meaning of this parameter is exactly 686 as defined by the USB2.0 specification. 687 688 iSerialNumber 689 The iSerialNumber parameter indicates the index of the string descriptor 690 describing the serial number of the connected device. The meaning of this 691 parameter is exactly as defined by the USB2.0 specification. 692 693 bNumConfigurations 694 The bNumConfigurations parameter indicates number of configurations supported 695 by the connected device. The meaning of this parameter is exactly as defined 696 by the USB2.0 specification. 697 698 reserved 699 The reserved parameter does not have a specific meaning. It is provided to 700 make the structure word aligned. 701 */ 702 typedef struct 703 { 704 uint8_t bLength; 705 uint8_t bDescriptorType; 706 uint16_t bcdUSB; 707 uint8_t bDeviceClass; 708 uint8_t bDeviceSubClass; 709 uint8_t bDeviceProtocol; 710 uint8_t bMaxPacketSize0; 711 uint16_t idVendor; 712 uint16_t idProduct; 713 uint16_t bcdDevice; 714 uint8_t iManufacturer; 715 uint8_t iProduct; 716 uint8_t iSerialNumber; 717 uint8_t bNumConfigurations; 718 uint16_t reserved; /*Word alignment*/ 719 }dev_desc_t; 720 721 /*-------------------------------------------------------------------------*//** 722 The def_conf_desc_t provides the prototype of the structure for the standard 723 USB configuration descriptor. All the parameters of this structure are as per 724 the standard setup packet defined in the USB2.0 specification. 725 726 bLength 727 The bLength parameter indicates the length of the configuration descriptor in 728 bytes. The meaning of this parameter is exactly as defined by the USB2.0 729 specification. 730 731 bDescriptorType 732 The bDescriptorType parameter indicates the standard descriptor type of this 733 descriptor. The meaning of this parameter is exactly as defined by the USB2.0 734 specification. 735 736 bTotalLength 737 The bTotalLength parameter indicates the total length (in bytes) of the 738 configuration descriptor including the class specific subordinate descriptors. 739 The meaning of this parameter is exactly as defined by the USB2.0 740 specification. 741 742 bNumInterface 743 The bNumInterfaces parameter indicates the number of interfaces supported by 744 this configuration. The meaning of this parameter is exactly as defined by 745 the USB2.0 specification. 746 747 bConfigurationValue 748 The bConfigurationValue parameter indicates the value to be use as an argument 749 to SET_CONFIGURATION request to select this configuration. The meaning of this 750 parameter is exactly as defined by the USB2.0 specification. 751 752 iConfiguration 753 The iConfiguration parameter indicates the index of the string descriptor 754 describing this configuration. The meaning of this parameter is exactly as 755 defined by the USB2.0 specification. 756 757 bmAttributes 758 The bmAttributes parameter provides configuration characteristics of this 759 configuration. The meaning of this parameter is exactly as defined by the 760 USB2.0 specification. 761 762 bMaxPower 763 The bMaxPower parameter indicates the Maximum power consumption of the USB 764 device from the bus in this specific configuration when the device is fully 765 operational. The meaning of this parameter is exactly as defined by the 766 USB2.0 specification. 767 768 upended_desc 769 The upended_desc parameter can be used to store the class specific subordinate 770 descriptor information. This might be useful to retrieve some basic 771 information about the selected configuration. 772 */ 773 typedef struct { 774 uint8_t bLength; 775 uint8_t bDescriptorType; 776 uint16_t wTotalLength; 777 uint8_t bNumInterfaces; 778 uint8_t bConfigurationValue; 779 uint8_t iConfiguration; 780 uint8_t bmAttributes; 781 uint8_t bMaxPower; 782 uint8_t upended_desc[11]; 783 }def_conf_desc_t; 784 785 786 /*---------------------------USBH Public APIs---------------------------------*/ 787 788 /*-------------------------------------------------------------------------*//** 789 The MSS_USBH_init() function initializes the MSS USB driver in the USB host 790 mode. This function initializes the internal data structures and readies the 791 MSS USB hardware block to detect the device attachment event. This function 792 also configures the control endpoint to keep it ready for communicating with 793 the detected device on the USB port. The parameter app_cb provided with this 794 function must be implemented by the application. This driver uses the app_cb 795 to inform the application about the events on the USB bus by calling the 796 appropriate callback element. 797 798 The MSS_USBH_init() function must be called before any other function to 799 initialize the USBH driver in the USB host mode. 800 801 @param app_cb 802 The app_cb parameter provides the pointer to the structure of type 803 mss_usbh_user_cb_t. This structure is used to call the user call-back 804 functions by the USBH driver. These call-back functions can be used to 805 provide error/status messages to the user for the application specific 806 handling of the events. 807 808 @return 809 This function does not return any value. 810 811 Example: 812 @code 813 mss_usbh_user_cb_t MSS_USBH_user_cb = 814 { 815 USB_DEV_attached, 816 USB_DEV_dettached, 817 USB_DEV_oc_error, 818 USB_DEV_enumerated, 819 USB_DEV_class_driver_assigned, 820 USB_DEV_not_supported, 821 USB_DEV_permanent_erro 822 }; 823 824 MSS_USBH_init(&MSS_USBH_user_cb); 825 MSS_USBH_register_class_driver(MSS_USBH_HID_get_handle()); 826 @endcode 827 */ 828 void 829 MSS_USBH_init 830 ( 831 mss_usbh_user_cb_t* app_cb 832 ); 833 834 /*-------------------------------------------------------------------------*//** 835 The MSS_USBH_task() function is the main task of the USBH driver. This 836 function must be called repeatedly by the application to allow the USBH driver 837 to perform the housekeeping tasks. A timer/scheduler can be used to call this 838 function at regular intervals or it can be called from the main continuous 839 foreground loop of the application. 840 841 @param 842 This function does not take any parameters. 843 844 @return 845 This function does not return any value. 846 847 Example: 848 @code 849 void 850 Host_controller_task 851 ( 852 void 853 ) 854 { 855 MSS_USBH_task(); 856 MSS_USBH_HID_task(); 857 switch (c_state) 858 { 859 case CONTROLLER_IDLE: 860 if(USBH_MSD_DEVICE_READY == MSS_USBH_MSC_get_state()) 861 { 862 c_state = CONTROLLER_INQUIRY; 863 } 864 break; 865 . 866 default: 867 break; 868 } 869 } 870 @endcode 871 */ 872 void 873 MSS_USBH_task 874 ( 875 void 876 ); 877 878 /*-------------------------------------------------------------------------*//** 879 The MSS_USBH_register_class_driver() function must be used by the application 880 to register a USBH-Class driver with the USBH driver. The application must 881 first get the handle from the USBH-Class driver before assigning it to the 882 USBH driver. Refer the USBH-Class section to know how to get a handle from the 883 USBH-Class driver. This handle is used by the USBH driver to communicate with 884 the USBH-Class driver. 885 886 @param class_handle 887 The class_handle parameter specifies the class driver handle to be 888 registered with the USBH driver. 889 890 @return 891 This function returns zero when execution was successful. 892 893 Example: 894 @code 895 mss_usbh_user_cb_t MSS_USBH_user_cb = 896 { 897 USB_DEV_attached, 898 USB_DEV_dettached, 899 USB_DEV_oc_error, 900 USB_DEV_enumerated, 901 USB_DEV_class_driver_assigned, 902 USB_DEV_not_supported, 903 USB_DEV_permanent_erro 904 }; 905 906 MSS_USBH_init(&MSS_USBH_user_cb); 907 MSS_USBH_register_class_driver(MSS_USBH_HID_get_handle()); 908 @endcode 909 */ 910 int8_t 911 MSS_USBH_register_class_driver 912 ( 913 void* class_handle 914 ); 915 916 /*-------------------------------------------------------------------------*//** 917 The MSS_USBH_configure_control_pipe() function is used to configure the 918 control pipe for the control transactions with attached device with the 919 address provided in target_addr parameter. This function also enables the 920 control pipe interrupt. 921 922 This function must be called before any other function for the control pipe. 923 924 @param target_addr 925 The target_addr parameter is address of the attached device with which the 926 MSS USB needs to communicate. 927 928 @return 929 This function returns zero when execution was successful. 930 931 Example: 932 @code 933 typedef enum { 934 TDEV_R, 935 TDEV_RHP1, 936 TDEV_RHP2 937 } tdev_id_t; 938 939 MSS_USBH_configure_control_pipe(TDEV_R); 940 @endcode 941 */ 942 int8_t 943 MSS_USBH_configure_control_pipe 944 ( 945 uint8_t target_addr 946 ); 947 948 /*-------------------------------------------------------------------------*//** 949 The MSS_USBH_configure_in_pipe() function is used to configure the IN pipe 950 for the IN transactions with the attached device with the address provided in 951 the target_addr parameter. This function also enables the IN pipe interrupt. 952 953 This function must be called before any other function for the IN pipe. 954 955 @param target_addr 956 The target_addr parameter is the address of the attached device with which 957 MSS USB needs to communicate. 958 959 @param inpipe_num 960 The inpipe_num parameter indicates the IN pipe number (endpoint) on MSS USB 961 which must be used for IN transfers with the attached device. 962 963 @param target_ep 964 The target_ep parameter indicates the IN endpoint number on the attached 965 device with which MSS USB needs to communicate. 966 967 @param fifo_addr 968 The fifo_addr parameter is the address of the FIFO in the MSS USB internal 969 RAM. The valid FIFO address values are from 0x00 to 0xFFF8. The FIFO Address 970 must be a multiple of 8. If the value provided is not a multiple of 8, then 971 the immediate lower value which is a multiple of 8 is taken as the FIFO 972 address. 973 E.g. If the provided value is 0x09, the actual value taken by the driver is 974 0x08. If the provided value is less than 0x08 then the FIFO address is taken 975 as 0x00. 976 977 @param fifo_size 978 The fifo_size parameter provides the endpoint FIFO size in the USB core 979 internal RAM. The valid FIFO size values are 8, 16, 32, 64, 128, 512, 1024, 980 2048, 4096. The MSS USB assigns 8 byte FIFO by default if the FIFO size is 981 not configured. 982 983 @param max_pkt_size 984 The max_pkt_size parameter provides the maximum packet size of the USB 985 transfer. This value must be equal to the maximum packet size as mentioned 986 in the endpoint descriptor which is used during enumeration process. 987 988 Note: This value must be less than or equal to the FIFO size value. 989 990 991 @param num_usb_pkt 992 The num_usb_pkt parameter has different meanings for different types of 993 transfers. 994 995 Low bandwidth ISO/interrupt transfers - This parameter must always be 1u. 996 This parameter represents the number of packets transferred in one (micro) 997 frame. 998 999 High bandwidth ISO transfers - This parameter represents the number of 1000 packets transferred in one (Micro) frame. In this case, this parameter can 1001 have a value of 1 2 or 3. High bandwidth ISO transfers are not yet 1002 implemented. 1003 1004 Bulk transfers. - For Bulk transfer this value must always be 1u. This 1005 parameter is be used with the auto-amalgamation/auto-split feature where it 1006 indicates number of bulk packets to be auto-amalgamated/auto-split in bulk 1007 transfer. The auto-amalgamation/auto-split feature is implemented but not 1008 yet tested. 1009 1010 @param dma_enable 1011 The dma_enable parameter specifies whether or not the internal DMA must be 1012 used for the data transfer from the provided buffer to the USB FIFO. 1013 1014 @param dma_channel 1015 The dma_channel parameter specifies the internal DMA channel to be used for 1016 the data transfers. DMA channel will be associated with selected endpoint. 1017 A unique DMA channel must be selected to transfer data on individual 1018 endpoints. This parameter is ignored when dma_enable parameter indicates 1019 that the DMA must not be used. 1020 1021 @param xfr_type 1022 The xfr_type parameter specifies the type of transfer to be performed on the 1023 specified endpoint. All other types of transfers (Interrupt, Isochronous, 1024 and Bulk) can be selected except the control transfer. 1025 1026 @param add_zlp 1027 The add_zlp parameter indicates whether to expect a zero length packet (ZLP) 1028 if the transfer size is exact a multiple of wMaxPacketSize. This parameter 1029 is only applicable for bulk transfers. For all other transfer types this 1030 parameter is ignored. 1031 1032 @param interval 1033 The interval parameter for interrupt and isochronous transfers defines the 1034 polling interval for the currently-selected IN pipe. For bulk transfers, 1035 this parameter indicates the number of frames/microframes after which the IN 1036 pipe must timeout on receiving a stream of NAK responses. The valid values 1037 for this parameter are as mentioned in the table below. 1038 1039 | Transfer Type | Speed | Valid values | 1040 |------------------|------------|------------------------------------------| 1041 | Interrupt | LS or FS | 1 – 255 | 1042 | Interrupt | HS | 1,2,4,8,16,32,64…32768 microframes | 1043 | | | | 1044 | Isochronous | FS or HS | 1,2,4,8,16,32,64…32768 frames/microframes| 1045 | | | | 1046 | Bulk | HS | 0,2,4,8,16,32,64…32768 microframes | 1047 | | | Note:Value 0 disables the NAK Timeout | 1048 | | | detection on Bulk endpoint | 1049 1050 @return 1051 This function returns zero when execution was successful. 1052 1053 Example: 1054 @code 1055 case USBH_MSC_CONFIG_BULK_ENDPOINTS: 1056 MSS_USBH_configure_out_pipe(g_msd_tdev_addr, 1057 USBH_MSC_BULK_TX_PIPE, 1058 g_tdev_out_ep.num, 1059 USBH_MSC_BULK_TX_PIPE_FIFOADDR, 1060 USBH_MSC_BULK_TX_PIPE_FIFOSZ, 1061 g_tdev_out_ep.maxpktsz, 1062 1, 1063 DMA_DISABLE, 1064 MSS_USB_DMA_CHANNEL_NA, 1065 MSS_USB_XFR_BULK, 1066 NO_ZLP_TO_XFR, 1067 32768u); 1068 1069 MSS_USBH_configure_in_pipe(g_msd_tdev_addr, 1070 USBH_MSC_BULK_RX_PIPE, 1071 g_tdev_in_ep.num, 1072 USBH_MSC_BULK_RX_PIPE_FIFOADDR, 1073 USBH_MSC_BULK_RX_PIPE_FIFOSZ, 1074 g_tdev_in_ep.maxpktsz, 1075 1, 1076 DMA_DISABLE, 1077 MSS_USB_DMA_CHANNEL_NA, 1078 MSS_USB_XFR_BULK, 1079 NO_ZLP_TO_XFR, 1080 32768u); 1081 1082 g_msc_state = USBH_MSC_TEST_UNIT_READY_CPHASE; 1083 break; 1084 @endcode 1085 */ 1086 int8_t 1087 MSS_USBH_configure_in_pipe 1088 ( 1089 uint8_t target_addr, 1090 uint8_t inpipe_num, 1091 uint8_t target_ep, 1092 uint16_t fifo_addr, 1093 uint16_t fifo_size, 1094 uint16_t max_pkt_size, 1095 uint8_t num_usb_pkt, 1096 uint8_t dma_enable, 1097 mss_usb_dma_channel_t dma_channel, 1098 mss_usb_xfr_type_t xfr_type, 1099 uint32_t add_zlp, 1100 uint32_t interval 1101 ); 1102 1103 /*-------------------------------------------------------------------------*//** 1104 The MSS_USBH_configure_out_pipe() function is used to configure the OUT pipe 1105 for the OUT transactions with attached device with the address provided in the 1106 target_addr parameter. This function also enables the OUT pipe interrupt. 1107 1108 This function must be called before any other function for the OUT pipe. 1109 1110 @param target_addr 1111 The target_addr parameter is the address of the attached device with which 1112 MSS USB needs to communicate. 1113 1114 @param outpipe_num 1115 The outpipe_num parameter indicates the OUT pipe number (endpoint) on MSS 1116 USB which must be used for OUT transfers with the attached device. 1117 1118 @param target_ep 1119 The target_ep parameter indicates the OUT endpoint number on the attached 1120 device with which MSS USB needs to communicate. 1121 1122 @param fifo_addr 1123 The fifo_addr parameter is the address of the FIFO in the MSS USB internal 1124 ram. The valid FIFO address values are from 0x00 to 0xFFF8. The FIFO address 1125 must be a multiple of 8. If the value provided is not a multiple of 8, then 1126 the immediate lower value which is a multiple of 8 is taken as the FIFO 1127 address. 1128 E.g. If the provided value is 0x09, the actual value taken by the driver is 1129 0x08. If the provided value is less than 0x08 then the FIFO address is 1130 taken as 0x00. 1131 1132 @param fifo_size 1133 The fifo_size parameter provides the endpoint FIFO size in the USB core 1134 internal RAM. The valid FIFO size values are 8, 16, 32, 64, 128, 512, 1024, 1135 2048, 4096. The MSS USB assigns 8 byte FIFO by default if the FIFO size is 1136 not configured. 1137 1138 @param max_pkt_size 1139 The max_pkt_size parameter provides the maximum packet size of the USB 1140 transfer. This value must be equal to the maximum packet size as mentioned 1141 in the endpoint descriptor which is used during enumeration process. 1142 1143 Note: This value must be less than or equal to the FIFO size value. 1144 1145 @param num_usb_pkt 1146 The num_usb_pkt parameter has different meanings for different types of 1147 transfers. 1148 1149 Low bandwidth ISO/interrupt transfers - This parameter must always be '1u'. 1150 This parameter represents the number of packets transferred in one (micro) 1151 frame. 1152 1153 High bandwidth ISO transfers - This parameter represents the number of 1154 packets transferred in one (Micro) frame. In this case, this parameter can 1155 have a value of 1 2 or 3. High bandwidth ISO transfers are not yet 1156 implemented. 1157 1158 Bulk transfers. - For Bulk transfer this value must always be '1u'. This 1159 parameter will be used with the auto-amalgamation/auto-split feature where 1160 it indicates the number of bulk packets to be auto-amalgamated/auto-split 1161 in bulk transfer. The auto-amalgamation/auto-split feature is implemented 1162 but not yet tested. 1163 1164 @param dma_enable 1165 The dma_enable parameter specifies whether or not the internal DMA must be 1166 used for the data transfer from the provided buffer to the USB FIFO. 1167 1168 @param dma_channel 1169 The dma_channel parameter specifies the internal DMA channel to be used for 1170 the data transfers. The DMA channel will be associated with the specified 1171 endpoint. A unique DMA channel must be selected to transfer data on 1172 individual endpoints. This parameter is ignored when the dma_enable 1173 parameter indicates that the DMA must not be used. 1174 1175 @param xfr_type 1176 The xfr_type parameter specifies the type of transfer to be performed on the 1177 specified endpoint. All other types of transfers (Interrupt, Isochronous, 1178 and Bulk) can be selected except control transfer. 1179 1180 @param add_zlp 1181 The add_zlp parameter indicates whether to send a zero length packet (ZLP) 1182 if the transfer size is a exact multiple of wMaxPacketSize. This parameter 1183 is only applicable for Bulk transfers. For all other transfer types this 1184 parameter is ignored. 1185 1186 @param interval 1187 The interval parameter for interrupt and isochronous transfers, defines the 1188 polling interval for the currently-selected OUT pipe. For the bulk 1189 transfers, this parameter indicates the number of frames/microframes after 1190 which the OUT Pipe must time out on receiving a stream of NAK responses. 1191 The valid values for this parameter are as mentioned in the table below. 1192 1193 | Transfer Type | Speed | Valid values | 1194 |------------------|-----------|-------------------------------------------| 1195 | Interrupt | LS or FS | 1 – 255 | 1196 | Interrupt | HS | 1,2,4,8,16,32,64…32768 microframes | 1197 | | | | 1198 | Isochronous | FS or HS | 1,2,4,8,16,32,64…32768 frames/microframes | 1199 | | | | 1200 | Bulk | HS | 0,2,4,8,16,32,64…32768 microframes | 1201 | | | Note:Value 0 disables the NAK Timeout | 1202 | | | detection on Bulk endpoint | 1203 1204 @return 1205 This function returns zero when execution was successful. 1206 1207 Example: 1208 @code 1209 case USBH_MSC_CONFIG_BULK_ENDPOINTS: 1210 MSS_USBH_configure_out_pipe(g_msd_tdev_addr, 1211 USBH_MSC_BULK_TX_PIPE, 1212 g_tdev_out_ep.num, 1213 USBH_MSC_BULK_TX_PIPE_FIFOADDR, 1214 USBH_MSC_BULK_TX_PIPE_FIFOSZ, 1215 g_tdev_out_ep.maxpktsz, 1216 1, 1217 DMA_DISABLE, 1218 MSS_USB_DMA_CHANNEL_NA, 1219 MSS_USB_XFR_BULK, 1220 NO_ZLP_TO_XFR, 1221 32768u); 1222 1223 MSS_USBH_configure_in_pipe(g_msd_tdev_addr, 1224 USBH_MSC_BULK_RX_PIPE, 1225 g_tdev_in_ep.num, 1226 USBH_MSC_BULK_RX_PIPE_FIFOADDR, 1227 USBH_MSC_BULK_RX_PIPE_FIFOSZ, 1228 g_tdev_in_ep.maxpktsz, 1229 1, 1230 DMA_DISABLE, 1231 MSS_USB_DMA_CHANNEL_NA, 1232 MSS_USB_XFR_BULK, 1233 NO_ZLP_TO_XFR, 1234 32768u); 1235 1236 g_msc_state = USBH_MSC_TEST_UNIT_READY_CPHASE; 1237 break; 1238 @endcode 1239 */ 1240 int8_t 1241 MSS_USBH_configure_out_pipe 1242 ( 1243 uint8_t target_addr, 1244 uint8_t outpipe_num, 1245 uint8_t target_ep, 1246 uint16_t fifo_addr, 1247 uint16_t fifo_size, 1248 uint16_t max_pkt_size, 1249 uint8_t num_usb_pkt, 1250 uint8_t dma_enable, 1251 mss_usb_dma_channel_t dma_channel, 1252 mss_usb_xfr_type_t xfr_type, 1253 uint32_t add_zlp, 1254 uint32_t interval 1255 ); 1256 1257 /*-------------------------------------------------------------------------*//** 1258 The MSS_USBH_write_out_pipe() function writes the data provided by the user 1259 into the previously configured out pipe FIFO. The data is ready to be 1260 transferred after calling this function. The Data will be transferred by the 1261 MSS USB according to the transfer type and interval parameter set for this 1262 OUT pipe using MSS_USBH_configure_out_pipe() function. This function is 1263 non-blocking.A call-back function will be called to indicate the status of 1264 this transfer after the status phase of the current OUT transaction is 1265 complete. 1266 1267 @param target_addr 1268 The target_addr parameter is the address of the attached device with which 1269 the MSS USB needs to communicate. 1270 1271 @param outpipe_num 1272 The outpipe_num parameter indicates the OUT pipe number (endpoint) on the 1273 MSS USB which must be used for the OUT transfers with the attached device. 1274 1275 @param target_ep 1276 The target_ep parameter indicates the OUT endpoint number on the attached 1277 device with which MSS USB needs to communicate. 1278 1279 @param max_pkt_size 1280 The max_pkt_size parameter provides the maximum packet size of the USB 1281 transfer. This value must be equal to the maximum packet size as mentioned 1282 in the endpoint descriptor which is used during enumeration process. 1283 1284 @param buf 1285 The buf parameter is the address of the buffer provided by the user from 1286 which the data is copied to the selected pipe buffer. 1287 1288 @param length 1289 The length parameter specifies the length of the data buffer in bytes. 1290 1291 @return 1292 This function does not return a value. 1293 1294 Example: 1295 @code 1296 case USBH_MSC_TEST_UNIT_READY_CPHASE: 1297 MSS_USBH_MSC_construct_cbw_cb6byte(USB_MSC_SCSI_TEST_UNIT_READY, 1298 0u, 1299 &g_bot_cbw); 1300 1301 MSS_USBH_write_out_pipe(g_msd_tdev_addr, 1302 USBH_MSC_BULK_TX_PIPE, 1303 g_tdev_out_ep.num, 1304 g_tdev_out_ep.maxpktsz, 1305 (uint8_t*)&g_bot_cbw, 1306 31u); 1307 1308 g_msc_state = USBH_MSC_TEST_UNIT_READY_SPHASE; 1309 break; 1310 @endcode 1311 */ 1312 int8_t 1313 MSS_USBH_write_out_pipe 1314 ( 1315 uint8_t target_addr, 1316 uint8_t outpipe_num, 1317 uint8_t tdev_ep_num, 1318 uint16_t maxpktsz, 1319 uint8_t* buf, 1320 uint32_t length 1321 ); 1322 1323 /*-------------------------------------------------------------------------*//** 1324 The MSS_USBH_read_in_pipe() function writes the data provided by the user into 1325 the previously configured out pipe FIFO. The data is ready to be transferred 1326 after calling this function. The data will be transferred by the MSS USB 1327 according to the transfer type and the interval parameter set for this OUT 1328 pipe using theMSS_USBH_configure_in_pipe() function. This function is 1329 non-blocking. A call-back function will be called to indicate the status of 1330 this transfer after the status phase of the current IN transaction is 1331 complete. 1332 1333 @param target_addr 1334 The target_addr parameter is the address of the attached device with which 1335 the MSS USB needs to communicate. 1336 1337 @param outpipe_num 1338 The outpipe_num parameter indicates the OUT pipe number (endpoint) on MSS 1339 USB which must be used for the OUT transfers with the attached device. 1340 1341 @param target_ep 1342 The target_ep parameter indicates the OUT endpoint number on the attached 1343 device with which the MSS USB needs to communicate. 1344 1345 @param max_pkt_size 1346 The max_pkt_size parameter provides the maximum packet size of the USB 1347 transfer. This value must be equal to the maximum packet size as mentioned 1348 in the endpoint descriptor which is used during enumeration process. 1349 1350 @param buf 1351 The buf parameter is the address of the buffer provided by the user from 1352 which the data is copied to the selected pipe buffer. 1353 1354 @param length 1355 The length parameter specifies the length of the data buffer in bytes. 1356 1357 @return 1358 This function does not return a value. 1359 1360 Example: 1361 @code 1362 case USBH_MSC_TEST_UNIT_READY_SPHASE: 1363 if(g_usbh_msc_tx_event) 1364 { 1365 g_usbh_msc_tx_event = 0; 1366 g_msc_state = USBH_MSC_TEST_UNIT_READY_WAITCOMPLETE; 1367 MSS_USBH_read_in_pipe(g_msd_tdev_addr, 1368 USBH_MSC_BULK_RX_PIPE, 1369 g_tdev_in_ep.num, 1370 g_tdev_in_ep.maxpktsz, 1371 (uint8_t*)&g_bot_csw, 1372 13u); 1373 } 1374 break; 1375 @endcode 1376 */ 1377 int8_t 1378 MSS_USBH_read_in_pipe 1379 ( 1380 uint8_t target_addr, 1381 uint8_t inpipe_num, 1382 uint8_t tdev_ep_num, 1383 uint16_t tdev_ep_maxpktsz, 1384 uint8_t* buf, 1385 uint32_t length 1386 ); 1387 1388 /*-------------------------------------------------------------------------*//** 1389 The MSS_USBH_get_tdev_state() function can be used to find out the current 1390 state of the attached device. E.g. ADDRESS, CONFIGURED etc. (as defined by 1391 USB2.0). 1392 1393 @param target_addr 1394 The target_addr parameter is the address of the attached device with which 1395 the MSS USB needs to communicate. 1396 1397 @return 1398 This function returns a value of type mss_usb_state_t indicating the current 1399 state of the attached device. 1400 1401 Example: 1402 @code 1403 static mss_usb_state_t msd_tdev_state = MSS_USB_NOT_ATTACHED_STATE; 1404 msd_tdev_state = MSS_USBH_get_tdev_state(g_msd_tdev_addr); 1405 @endcode 1406 1407 */ 1408 mss_usb_state_t 1409 MSS_USBH_get_tdev_state 1410 ( 1411 uint8_t target_addr 1412 ); 1413 1414 /*-------------------------------------------------------------------------*//** 1415 The MSS_USBH_suspend() function can be used to suspend the MSS USB. The MSS 1416 USB will complete the current transaction then stop the transaction scheduler 1417 and frame counter. No further transactions will be started and no SOF packets 1418 will be generated. 1419 1420 @param 1421 This function does not take any parameters. 1422 1423 @return 1424 This function does not return any value. 1425 1426 Example: 1427 @code 1428 @endcode 1429 */ 1430 void 1431 MSS_USBH_suspend 1432 ( 1433 void 1434 ); 1435 1436 /*-------------------------------------------------------------------------*//** 1437 The MSS_USBH_resume() function can be used to resume the previously suspended 1438 MSS USB. If the MSS USB was in suspend mode then it will start the transaction 1439 scheduler and frame counter after calling this function. 1440 1441 @param 1442 This function does not take any parameters. 1443 1444 @return 1445 This function does not return any value. 1446 1447 Example: 1448 @code 1449 @endcode 1450 */ 1451 void 1452 MSS_USBH_resume 1453 ( 1454 void 1455 ); 1456 1457 /*-------------------------------------------------------------------------*//** 1458 The MSS_USBH_1ms_tick() function must be used to provide the 1ms time tick to 1459 the USBH driver. This time reference is used by the USBH driver to keep track 1460 of different time delays required during enumeration process. This way the 1461 application need not wait for the enumeration to complete which may take long 1462 time. 1463 1464 @param 1465 This function does not take any parameters. 1466 1467 @return 1468 This function does not return any value. 1469 1470 Example: 1471 @code 1472 void SysTick_Handler(void) 1473 { 1474 MSS_USBH_task(); 1475 MSS_USBH_HID_task(); 1476 MSS_USBH_1ms_tick(); 1477 } 1478 @endcode 1479 */ 1480 void 1481 MSS_USBH_1ms_tick 1482 ( 1483 void 1484 ); 1485 1486 /*-------------------------------------------------------------------------*//** 1487 The MSS_USBH_get_milis() function is used to find out the number of 1488 milliseconds elapsed from the time when last reset occurred. 1489 1490 @param 1491 This function does not take any parameters. 1492 1493 @return 1494 This function returns a 32-bit unsigned integer value. This value indicates 1495 the number of milliseconds elapsed from the time when the last reset 1496 occurred. This integer value will overflow after approximately 49Hrs after 1497 reset. 1498 1499 Example: 1500 @code 1501 case USBH_MSC_WAIT_SET_CONFIG: 1502 if(g_usbh_msc_cep_event) 1503 { 1504 g_usbh_msc_cep_event = 0; 1505 wait_mili = MSS_USBH_get_milis(); 1506 g_msc_state = USBH_MSC_WAIT_DEV_SETTLE; 1507 } 1508 break; 1509 1510 case USBH_MSC_WAIT_DEV_SETTLE: 1511 if((MSS_USBH_get_milis() - wait_mili) > 60) 1512 { 1513 g_msc_state = USBH_MSC_GET_MAX_LUN; 1514 } 1515 break; 1516 @endcode 1517 */ 1518 uint32_t 1519 MSS_USBH_get_milis 1520 ( 1521 void 1522 ); 1523 1524 /*-------------------------------------------------------------------------*//** 1525 The MSS_USBH_construct_get_descr_command() function is be used to construct 1526 the setup packet which is to be sent on the USB bus. This function formats the 1527 provided parameters into a USB standard format GET_DESCRIPTOR request and 1528 stores it in the location provided by the buf parameter. 1529 1530 @param buf 1531 The buf parameter is the address of the buffer where the formatted 1532 GET_DESCRIPTOR request is stored. 1533 1534 @param xfr_dir 1535 The xfr_dir parameter indicates the direction of the data transfer on the 1536 USB bus. The value USB_STD_REQ_DATA_DIR_IN indicates that the direction of 1537 the data transfer is from the USB device to USB host (USB IN transaction). 1538 The value USB_STD_REQ_DATA_DIR_OUT indicates that the direction of the data 1539 transfer is from the USB host to the USB device (USB OUT transaction). 1540 1541 @param req_type 1542 The req_type parameter indicates the request type. The request type can be 1543 one of the following: standard request, class request or vendor request. 1544 1545 @param recip_type 1546 The recip_type parameter indicates the recipient type on the USB device. The 1547 request recipient on the attached device can be one of the following: 1548 device, endpoint or interface. 1549 1550 @param request 1551 The request parameter indicates the request that needs to be sent to the 1552 attached device. 1553 1554 @param desc_type 1555 The desc_type parameter indicates the descriptor type that needs to be 1556 requested from the attached device. 1557 1558 @param strng_idx 1559 The strng_idx parameter indicates the index of the string descriptor when 1560 the desc_type parameter indicates STRING TYPE. 1561 1562 @param length 1563 The length parameter indicates the number of bytes to be received from 1564 attached device as part of the requested descriptor. 1565 1566 @return 1567 This function does not return any value. 1568 1569 Example: 1570 @code 1571 MSS_USBH_configure_control_pipe(g_msd_tdev_addr); 1572 memset(std_req_buf, 0u, 8*(sizeof(uint8_t))); 1573 MSS_USBH_construct_get_descr_command(std_req_buf, 1574 USB_STD_REQ_DATA_DIR_IN, 1575 USB_STANDARD_REQUEST, 1576 USB_STD_REQ_RECIPIENT_DEVICE, 1577 USB_STD_REQ_GET_DESCRIPTOR, 1578 USB_CONFIGURATION_DESCRIPTOR_TYPE, 1579 0, 1580 32u); 1581 1582 g_msc_state = USBH_MSC_WAIT_GET_CLASS_DESCR; 1583 MSS_USBH_start_control_xfr(std_req_buf, 1584 (uint8_t*)&g_msd_conf_desc, 1585 USB_STD_REQ_DATA_DIR_IN, 1586 32u); 1587 @endcode 1588 */ 1589 void 1590 MSS_USBH_construct_get_descr_command 1591 ( 1592 uint8_t* buf, 1593 uint8_t xfr_dir, 1594 uint8_t req_type, 1595 uint8_t recip_type, 1596 uint8_t request, 1597 uint8_t desc_type, 1598 uint8_t strng_idx, 1599 uint16_t length 1600 ); 1601 1602 /*-------------------------------------------------------------------------*//** 1603 The MSS_USBH_start_control_xfr() function must be used to start a control 1604 transfer with the attached USB device. This is a non-blocking function. 1605 This function prepares the control pipe for the control transfer. A call-back 1606 function will be called to indicate the status of the transfer after the 1607 status phase of the control transfer is complete. 1608 1609 @param cbuf_addr 1610 The cbuf_addf parameter is the address of the buffer where the USB request 1611 setup packet is available. 1612 1613 @param dbuf_addr 1614 The dbuf_addf parameter is the address of the buffer for the data phase of 1615 the control transfer. The USBD driver will put the data received from 1616 attached device in this buffer for the USB IN transfers. The data from this 1617 buffer will be sent to the attached device for the USB OUT transfers. 1618 1619 @param data_dir 1620 The data_dir parameter indicates the direction of the data flow in the data 1621 phase of the control transfer. The value USB_STD_REQ_DATA_DIR_IN indicates 1622 that the direction of the data transfer is from the USB device to the USB 1623 host (USB IN transaction). The value USB_STD_REQ_DATA_DIR_OUT indicates 1624 that the direction of the data transfer is from the USB host to the USB 1625 device (USB OUT transaction). 1626 1627 @param data_len 1628 The data_len parameter indicates the number of bytes to be transferred 1629 during the data phase of the control transfer. 1630 1631 @return 1632 This function returns zero when execution was successful. 1633 1634 Example: 1635 @code 1636 MSS_USBH_configure_control_pipe(g_msd_tdev_addr); 1637 memset(std_req_buf, 0u, 8*(sizeof(uint8_t))); 1638 MSS_USBH_construct_get_descr_command(std_req_buf, 1639 USB_STD_REQ_DATA_DIR_IN, 1640 USB_STANDARD_REQUEST, 1641 USB_STD_REQ_RECIPIENT_DEVICE, 1642 USB_STD_REQ_GET_DESCRIPTOR, 1643 USB_CONFIGURATION_DESCRIPTOR_TYPE, 1644 0, 1645 32u); 1646 1647 g_msc_state = USBH_MSC_WAIT_GET_CLASS_DESCR; 1648 MSS_USBH_start_control_xfr(std_req_buf, 1649 (uint8_t*)&g_msd_conf_desc, 1650 USB_STD_REQ_DATA_DIR_IN, 1651 32u); 1652 @endcode 1653 */ 1654 uint8_t 1655 MSS_USBH_start_control_xfr 1656 ( 1657 uint8_t* cbuf_addr, 1658 uint8_t* dbuf_addr, 1659 uint8_t data_dir, 1660 uint32_t data_len 1661 ); 1662 1663 /*-------------------------------------------------------------------------*//** 1664 The MSS_USBH_get_cep_state() function can be used to find out the current 1665 state of the control pipe. A new control transfer can be started when the 1666 control pipe is in the MSS_USB_CEP_IDLE state. 1667 1668 @param 1669 This function does not take any parameters. 1670 1671 @return 1672 This function returns a value of type mss_usb_ep_state_t indicating the 1673 current state of the control pipe. 1674 1675 Example: 1676 @code 1677 mss_usb_ep_state_t cep_st; 1678 cep_st = MSS_USBH_get_cep_state(); 1679 if(MSS_USB_CEP_IDLE == cep_st) 1680 { 1681 MSS_USBH_configure_control_pipe(g_msd_tdev_addr); 1682 memset(std_req_buf, 0u, 8*(sizeof(uint8_t))); 1683 MSS_USBH_construct_get_descr_command(std_req_buf, 1684 USB_STD_REQ_DATA_DIR_IN, 1685 USB_STANDARD_REQUEST, 1686 USB_STD_REQ_RECIPIENT_DEVICE, 1687 USB_STD_REQ_GET_DESCRIPTOR, 1688 USB_CONFIGURATION_DESCRIPTOR_TYPE, 1689 0, 1690 32u); 1691 1692 g_msc_state = USBH_MSC_WAIT_GET_CLASS_DESCR; 1693 MSS_USBH_start_control_xfr(std_req_buf, 1694 (uint8_t*)&g_msd_conf_desc, 1695 USB_STD_REQ_DATA_DIR_IN, 1696 32u); 1697 } 1698 @endcode 1699 */ 1700 mss_usb_ep_state_t 1701 MSS_USBH_get_cep_state 1702 ( 1703 void 1704 ); 1705 1706 /*-------------------------------------------------------------------------*//** 1707 The MSS_USBH_test_mode() function can be used to initiate one of the 1708 compliance test modes in the MSS USB. This function is useful only for 1709 compliance test procedures. The MSS USB goes into the specified test mode once 1710 this function is executed. A hard reset is required to resume normal 1711 operations. 1712 1713 @param test_case 1714 The test_case parameter indicates the compliance test that need to be 1715 executed.The compliance tests could be one of the following: 1716 Test-J (USB_TEST_MODE_SELECTOR_TEST_J), 1717 Test-K (USB_TEST_MODE_SELECTOR_TEST_K), 1718 SE0-NAK (USB_TEST_MODE_SELECTOR_TEST_SE0NAK), 1719 Test-Packet (USB_TEST_MODE_SELECTOR_TEST_PACKET) 1720 1721 @return 1722 This function does not return any value. 1723 1724 Example: 1725 @code 1726 case '1': 1727 MSS_USBH_test_mode(USB_TEST_MODE_SELECTOR_TEST_PACKET); 1728 MSS_UART_polled_tx_string(&g_mss_uart1, 1729 (uint8_t *)"\n\n\r Test-Packet started..."); 1730 break; 1731 1732 case '2': 1733 MSS_USBH_test_mode(USB_TEST_MODE_SELECTOR_TEST_J); 1734 MSS_UART_polled_tx_string(&g_mss_uart1, 1735 (uint8_t *)"\n\n\r Test-J started..."); 1736 break; 1737 1738 case '3': 1739 MSS_USBH_test_mode(USB_TEST_MODE_SELECTOR_TEST_K); 1740 MSS_UART_polled_tx_string(&g_mss_uart1, 1741 (uint8_t *)"\n\n\r Test-K started..."); 1742 break; 1743 1744 case '4': 1745 MSS_USBH_test_mode(USB_TEST_MODE_SELECTOR_TEST_SE0NAK); 1746 MSS_UART_polled_tx_string(&g_mss_uart1, 1747 (uint8_t *)"\n\n\r Test-SE0-NAK started..."); 1748 break; 1749 1750 case '5': 1751 MSS_USBH_test_mode(USB_TEST_MODE_SELECTOR_TEST_FORCE_ENA); 1752 MSS_UART_polled_tx_string(&g_mss_uart1, 1753 (uint8_t *)"\n\n\r Test-Force-Host started..."); 1754 break; 1755 1756 default: 1757 invalid_selection_menu(); 1758 break; 1759 @endcode 1760 */ 1761 void 1762 MSS_USBH_test_mode 1763 ( 1764 uint8_t test_case 1765 ); 1766 1767 /*-------------------------------------------------------------------------*//** 1768 The MSS_USBH_get_std_dev_descr() function can be used to get the 8 byte USB 1769 standard device descriptor from the attached device. This function is provided 1770 specifically for the �Standard Descriptor� test case of USB-IF compliance 1771 procedure. This function might not be useful In general scenarios. 1772 1773 @param buffer 1774 The buffer parameter is the pointer to the buffer where the USB standard 1775 device descriptor received from the attached device will be stored. 1776 1777 @return 1778 This function returns zero on successful execution. 1779 1780 Example: 1781 @code 1782 mss_usb_ep_state_t cep_st; 1783 cep_st = MSS_USBH_get_cep_state(); 1784 if(MSS_USB_CEP_IDLE == cep_st) 1785 { 1786 MSS_USBH_configure_control_pipe(g_msd_tdev_addr); 1787 memset(std_req_buf, 0u, 8*(sizeof(uint8_t))); 1788 MSS_USBH_construct_get_descr_command(std_req_buf, 1789 USB_STD_REQ_DATA_DIR_IN, 1790 USB_STANDARD_REQUEST, 1791 USB_STD_REQ_RECIPIENT_DEVICE, 1792 USB_STD_REQ_GET_DESCRIPTOR, 1793 USB_CONFIGURATION_DESCRIPTOR_TYPE, 1794 0, 1795 32u); 1796 1797 g_msc_state = USBH_MSC_WAIT_GET_CLASS_DESCR; 1798 MSS_USBH_start_control_xfr(std_req_buf, 1799 (uint8_t*)&g_msd_conf_desc, 1800 USB_STD_REQ_DATA_DIR_IN, 1801 32u); 1802 } 1803 @endcode 1804 */ 1805 int8_t 1806 MSS_USBH_get_std_dev_descr 1807 ( 1808 uint8_t* buffer 1809 ); 1810 1811 void 1812 MSS_USBH_abort_in_pipe 1813 ( 1814 mss_usb_ep_num_t inpipe_num 1815 ); 1816 1817 void 1818 MSS_USBH_abort_out_pipe 1819 ( 1820 mss_usb_ep_num_t outpipe_num 1821 ); 1822 1823 #endif /* MSS_USB_HOST_ENABLED */ 1824 1825 #ifdef __cplusplus 1826 } 1827 #endif 1828 1829 #endif /* __MSS_USB_HOST_H_ */ 1830