MCUXpresso SDK USB Stack User's Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 50
| Download | |
| Open PDF In Browser | View PDF |
NXP Semiconductors User's Guide MCUXpresso SDK USB Stack User’s Guide Document Number: MCUXSDKUSBSUG Rev 8, 05/2018 Contents Contents Chapter 1 Overview............................................................................................. 4 Chapter 2 Build the USB examples in MCUXpresso SDK................................5 2.1 Requirements for building USB examples....................................................................................................................5 2.1.1 Hardware....................................................................................................................................................... 5 2.1.2 Software........................................................................................................................................................ 5 2.2 USB code structure......................................................................................................................................................5 2.3 Compiling or running the USB stack and examples..................................................................................................... 6 2.3.1 Step-by-step guide for MCUXpresso IDE......................................................................................................7 2.3.2 Step-by-step guide for IAR.......................................................................................................................... 12 2.3.3 Step-by-step guide for Keil µVision5........................................................................................................... 13 2.3.4 Step-by-step guide for ARM GCC............................................................................................................... 14 2.3.4.1 Setup tool chains..........................................................................................................................14 2.3.4.2 Install GCC ARM embedded tool chain....................................................................................... 14 2.3.4.3 Install MinGW...............................................................................................................................14 2.3.4.4 Add new system environment variable ARMGCC_DIR................................................................15 2.3.4.5 Install CMake............................................................................................................................... 16 2.3.4.6 Build the USB demo.....................................................................................................................17 2.3.4.7 Run a demo application............................................................................................................... 18 2.4 USB stack configuration.............................................................................................................................................20 2.4.1 Device configuration....................................................................................................................................20 2.4.2 Host configuration....................................................................................................................................... 21 2.4.3 USB OSA resource configuration................................................................................................................21 2.4.4 USB cache-related MACROs definitions.....................................................................................................22 Chapter 3 Porting to a new platform................................................................ 25 3.1 System-on-Chip (SoC) files........................................................................................................................................25 3.2 Board files.................................................................................................................................................................. 25 3.3 Porting examples....................................................................................................................................................... 27 3.3.1 Copy a new platform example.....................................................................................................................27 3.3.2 Porting the example.................................................................................................................................... 27 3.3.3 Modify the example project......................................................................................................................... 29 3.3.4 USB host CDC example..............................................................................................................................31 3.3.5 USB device MSC SD card example............................................................................................................ 32 3.3.6 USB device audio speaker example........................................................................................................... 32 3.3.7 USB device CCID Smart card example...................................................................................................... 33 Chapter 4 Developing a new USB application................................................ 34 4.1 Developing a new USB device application.................................................................................................................34 4.1.1 Application interfaces.................................................................................................................................. 34 4.1.2 How to develop a new device application.................................................................................................... 34 4.1.2.1 Changing the usb_device_descriptor.c file................................................................................... 35 MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 2 NXP Semiconductors Contents 4.1.2.2 Changing the usb_device_descriptor.h file .................................................................................. 41 4.1.2.3 Changing the application file........................................................................................................ 41 4.2 Developing a New USB Host Application...................................................................................................................41 4.2.1 Background................................................................................................................................................. 41 4.2.2 How to develop a new host application....................................................................................................... 42 4.2.2.1 Creating a project.........................................................................................................................42 4.2.2.2 Main application function flow...................................................................................................... 43 4.2.2.3 Event callback function................................................................................................................ 44 4.2.2.4 Class initialization........................................................................................................................ 47 4.2.2.5 Sending/Receiving data to/from the device..................................................................................47 Chapter 5 USB compliance tests......................................................................48 Chapter 6 Revision history............................................................................... 49 MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 3 Overview Chapter 1 Overview This document provides the following: • Detailed steps to compile the USB examples, download a binary image, and run the examples. • Detailed steps to port the USB stack to a new platform. • Detailed steps to develop a new application based on the existing classes in the USB stack. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 4 NXP Semiconductors Requirements for building USB examples Chapter 2 Build the USB examples in MCUXpresso SDK This section describes how to compile the USB stack and examples, download a binary image, and run the examples. 2.1 Requirements for building USB examples The TWR-K22F120M Tower System module or FRDM-K64F Freedom platform is used as an example in this document. The process for compiling, downloading, and running examples is similar on all other boards. For a detailed version of the toolchain software, see the MCUXpresso SDK Release Notes (document MCUXSDKRN). 2.1.1 Hardware • TWR-K22F120M Tower System module and (optional) TWR-SER Tower System module and Elevator • MCUXpresso SDK Boards • J-Link debugger (optional) • USB cables 2.1.2 Software • MCUXpresso SDK release package ® • IAR Embedded Workbench for ARM Version 8.11.3 ® ® • Keil µVision5 Integrated Development Environment Version 5.23 , available for ARM Cortex -M4 devices • MCUXpresso IDE v10.1.0 • Makefiles support with GCC revision 6-2017-q2-update from ARM Embedded 2.2 USB code structure The USB code is located in the folder:/middleware/usb MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 5 Build the USB examples in MCUXpresso SDK Figure 1. MCUXpresso SDK folder structure The USB folder includes the source code for stack and examples. Note that the version number of the USB folder may vary. Figure 2. USB folder structure The USB folder includes three subfolders: • device This subfolder includes the controller driver and common device driver for the USB device. • include This subfolder includes the definitions and structures for the USB stack. • osa This subfolder includes the adapter interfaces for various OSes. NOTE For different USB stack versions, the folder structure may be a little different. See the folder structure in the release package to get the exact folder structure. 2.3 Compiling or running the USB stack and examples MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 6 NXP Semiconductors Compiling or running the USB stack and examples NOTE The USB example maybe not support all compilers. The steps below just provide information on how to compile and run on all compilers. To know which compilers have support for the USB example, see the specific MCUXpresso SDK documentation. 2.3.1 Step-by-step guide for MCUXpresso IDE 1. Prepare a compressed release package , such as SDK_2.0_FRDM-K64F.zip. 2. Open MCUXpresso IDE and drag and drop the MCUXpresso SDK (zip file/folder) into the ‘Installed SDKs’. The MCUXpresso SDK should install. Figure 3. Installed SDK 3. To select an example, select the “Import SDK example(s) [To match the figure]” button. Click the “Next” button after selecting the available board. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 7 Build the USB examples in MCUXpresso SDK Figure 4. Import project button MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 8 NXP Semiconductors Compiling or running the USB stack and examples Figure 5. Select boards 4. To import one example, click the “Finish” button after selecting the available example. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 9 Build the USB examples in MCUXpresso SDK Figure 6. Import project 5. After importing, the window should look like the below figure. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 10 NXP Semiconductors Compiling or running the USB stack and examples Figure 7. The USB projects workspace 6. Choose the appropriate build target, “Debug” or “Release”, by left-clicking the build configuration icon as show in the below figure. Figure 8. Manage build configuration button 7. If the project build does not begin after selecting the desired target, left-click the build icon to start the build. Figure 9. Build project button 8. To check debugger configurations, click the down arrow next to the green debug button and select “Debug Configurations”. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 11 Build the USB examples in MCUXpresso SDK Figure 10. Configure debug button 9. After verifying the debugger configurations are correct, click the “Debug” button. Figure 11. MCUXpresso IDE debug configurations 10. The application is downloaded to the target and automatically runs to main(): 11. Run the code by clicking the “Resume” button to start the application: Figure 12. Resume button 12. See the example-specific document for more test information. 2.3.2 Step-by-step guide for IAR This section shows how to use IAR. Open IAR as shown in this figure: MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 12 NXP Semiconductors Compiling or running the USB stack and examples 1. Open the worksace corresponding to different examples. For example, the workspace file is located at: /boards/twrk22f120m/usb_examples/usb_host_hid_mouse/bm/ iar/host_hid_mouse_bm.eww. Figure 13. IAR workspace 2. Build the host_hid_mouse_bm example. 3. Connect the micro USB cable from a PC to the J25 of the TWR-K22F120M Tower System module to power on the board. 4. Click the “Download and Debug” button. Wait for the download to complete. 5. Click the “Go” button to run the example. 6. See the example-specific readme.pdf for more test information. 2.3.3 Step-by-step guide for Keil µVision5 This section shows how to use Keil µVision5. Open Keil µVision5 as shown in this figure: 1. Open the workspace corresponding to different examples. For example, the workspace file is located in /boards/twrk22f120m/usb_examples/usb_host_hid_mouse/bm/ mdk/host_hid_mouse_bm.uvmpw. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 13 Build the USB examples in MCUXpresso SDK Figure 14. Keil µVision5 workspace 2. Build the host_hid_mouse_bm example. 3. Click the “Start/Stop” debug session button. Wait for the download to complete. 4. Click the “Go” button to run the example. 5. See the example-specific readme.pdf for more test information. 2.3.4 Step-by-step guide for ARM GCC 2.3.4.1 Setup tool chains 2.3.4.2 Install GCC ARM embedded tool chain Download and install the installer from www.launchpad.net/gcc-arm-embedded. 2.3.4.3 Install MinGW 1. Download the latest mingw-get-setup.exe. 2. Install the GCC ARM Embedded toolchain. The recommended path is C:/MINGW. However, you may install to any location. Note that the installation path may not contain a space. 3. Ensure that the mingw32-base and msys-base are selected under Basic Setup. 4. Click “Installation” and “Apply changes”. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 14 NXP Semiconductors Compiling or running the USB stack and examples Figure 15. Setup MinGW and MSYS 5. Add paths C:/MINGW/msys/1.0/bin;C:/MINGW/bin to the system environment. Note that, if the GCC ARM Embedded tool chain was installed somewhere other than the recommended location, the system paths added should reflect this change. An example using the recommended installation locations is shown below. NOTE There is a high chance that if the paths are not set correctly, the tool chain will not work properly. Figure 16. Add Path to systems environment 2.3.4.4 Add new system environment variable ARMGCC_DIR Create a new system environment variable ARMGCC_DIR. The value of this variable should be the short name of the ARM GCC Embedded tool chain installation path. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 15 Build the USB examples in MCUXpresso SDK Figure 17. Add ARMGCC_DIR system variable 2.3.4.5 Install CMake 1. Download CMake 3.0.1 from www.cmake.org/cmake/resources/software.html. 2. Install Cmake 3.0.1 and ensure that the option "Add CMake to system PATH" is selected. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 16 NXP Semiconductors Compiling or running the USB stack and examples Figure 18. Install CMake 2.3.4.6 Build the USB demo 1. Change the directory to the project directory: 2. /boards/twrk22f120m/usb_examples/usb_host_hid_mouse/bm/armgcc. Run the build_all.bat. The build output is shown in this figure: MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 17 Build the USB examples in MCUXpresso SDK Figure 19. USB host demo built successfully 2.3.4.7 Run a demo application This section describes steps to run a demo application using J-Link GDB Server application. 1. Connect the J-Link debug port to the SWD/JTAG connector of the board. 2. Open the J-Link GDB Server application and modify your connection settings as shown in this figure. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 18 NXP Semiconductors Compiling or running the USB stack and examples Figure 20. SEGGER J-Link GDB Server configuration NOTE The target device selection should be MK22FN512xxx12. The target interface should be SWD. 3. After connected, the screen should resemble this figure: MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 19 Build the USB examples in MCUXpresso SDK Figure 21. SEGGER J-Link GDB Server screen after successful connection NOTE The CPU selection should be CPU to: MK22FN512xxx12. 4. Open the ARM GCC command prompt and change the directory to the output directory of the desired demo. For this example, the directory is: /boards/twrk22f120m/usb_examples/usb_host_hid_mouse/bm/armgcc/debug. 5. Run the command “arm-none-eabi-gdb.exe .elf”. Run these commands: • “target remote localhost: 2331” • “monitor reset” • “monitor halt” • “load” • “monitor reset” 6. The application is downloaded and connected. Execute the “monitor go” command to start the demo application. 7. See the example-specific document for more test information. 2.4 USB stack configuration 2.4.1 Device configuration A device configuration file is set up for each example, such as: MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 20 NXP Semiconductors USB stack configuration /boards/twrk22f120m/usb_examples/usb_host_hid_mouse This file is used to either enable or disable the USB class driver and to configure the interface type (high-speed or full speed). The object number is configurable either to decrease the memory usage or to meet specific requirements. If the device stack configuration is changed, rebuild the example projects. For each device, follow these steps. If the board is a Tower or Freedom platform, enable the following macros: Enable this macro for full speed. #define USB_DEVICE_CONFIG_KHCI (0U) Enable this macro if the board supports high-speed. #define USB_DEVICE_CONFIG_EHCI (0U) If board is part of the LPC series, enable the following macros: Enable this macro for full speed. #define USB_DEVICE_CONFIG_LPCIP3511FS (0U) Enable this macro if the board supports high-speed. #define USB_DEVICE_CONFIG_LPCIP3511HS (0U) 2.4.2 Host configuration A host configuration file is set up for each example, such as: /boards/twrk22f120m/usb/usb_host_hid_mouse/bm/usb_host_config.h This file is used to either enable or disable the USB class driver. The object number is configurable either to decrease the memory usage or to meet specific requirements. If the Host stack configuration is changed, rebuild the example projects. For each Host, follow these steps. If the board is a Tower for Freedom platform, enable the following macros: Enable this macro for full speed. #define USB_HOST_CONFIG_KHCI (0U) Enable this macro if the board supports high-speed. #define USB_HOST_CONFIG_EHCI (0U) If board is part of the LPC series, enable the following macros: Enable this macro for full speed. #define USB_HOST_CONFIG_OHCI (0U) Enable this macro if the board supports high-speed. #define USB_HOST_CONFIG_IP3516HS (0U) 2.4.3 USB OSA resource configuration In the USB stack, some static resources for USB OSA, such as event and message, are defined. The user should update the configuration number if the resource is not enough. For bare metal, the related macro is in usb_osa_bm.c. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 21 Build the USB examples in MCUXpresso SDK #define USB_OSA_BM_EVENT_COUNT (2U) #define USB_OSA_BM_SEM_COUNT (1U) #define USB_OSA_BM_MSGQ_COUNT (1U) #define USB_OSA_BM_MSG_COUNT (8U) #define USB_OSA_BM_MSG_SIZE (4U) For FreeRTOS OS, if the configSUPPORT_STATIC_ALLOCATION macro is enabled, the related macro is in usb_osa_freertos.c. #define USB_OSA_FREERTOS_EVENT_COUNT (2U) #define USB_OSA_FREERTOS_SEM_COUNT (1U) #define USB_OSA_FREERTOS_MUTEX_COUNT (3U) #define USB_OSA_FREERTOS_MSGQ_COUNT (1U) #define USB_OSA_FREERTOS_MSG_COUNT (8U) #define USB_OSA_FREERTOS_MSG_SIZE (4U) 2.4.4 USB cache-related MACROs definitions There are few MACROs in the USB stack to define USB data attributes. • USB_STACK_USE_DEDICATED_RAM The following values are used to configure the USB stack to use dedicated RAM or not. 1. USB_STACK_DEDICATED_RAM_TYPE_BDT_GLOBAL - The USB device global variables (controller data and device stack data) are put into the USB-dedicated RAM. 2. USB_STACK_DEDICATED_RAM_TYPE_BDT - The USB device controller global variables (BDT data) are put into the USB-dedicated RAM. 3. 0 - There is no USB-dedicated RAM. • USB_DEVICE_CONFIG_BUFFER_PROPERTY_CACHEABLE The following values are used to configure the device stack cache to be enabled or not. 0: disabled 1: enable • USB_HOST_CONFIG_BUFFER_PROPERTY_CACHEABLE The following values are used to configure host stack cache to be enabled or not. 0: disable 1: enable Based on the above MACROs, the following cache-related MACROs are defined in the USB stack. Table 1. Cache and global variable attribute relation USB_DEVICE_CONFIG_BUFFER_PROPERTY_CACHEABLE || USB_HOST_CONFIG_BUFFER_PROPERTY_CACHEABLE USB_STACK_USE_DEDICATED_RAM ’s Value 1 0 MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 22 NXP Semiconductors USB stack configuration Table 1. Cache and global variable attribute relation (continued) USB_STACK_DEDICATED_RAM_TYPE _BDT_GLOBAL USB_STACK_DEDICATED_RAM_TYPE _BDT USB_GLOBAL dedicated ram, stack use only USB_GLOBAL dedicated ram, stack use only USB_BDT dedicated ram, stack use only USB_BDT dedicated ram, stack use only USB_CONTROLL ER_DATA NonCachable, stack use only USB_CONTROLL ER_DATA dedicated ram, stack use only USB_DMA_NONI cachable ram & NIT_DATA_ALIGN( alignment n) USB_DMA_NONI alignment NIT_DATA_ALIGN( n) USB_DMA_INIT_D cachable ram & ATA_ALIGN(n) alignment USB_DMA_INIT_D alignment ATA_ALIGN(n) USB_GLOBAL cachable ram & alignment, stack use only USB_GLOBAL Put in bss, stack use only USB_BDT USB_BDT dedicated ram, stack use only dedicated ram, stack use only USB_CONTROLL ER_DATA NonCachable, stack use only USB_CONTROLL ER_DATA NULL, stack use only USB_DMA_NONI cachable ram & NIT_DATA_ALIGN( alignment n) USB_DMA_INIT_D cachable ram & ATA_ALIGN(n) alignment USB_DMA_NONI alignment NIT_DATA_ALIGN( n) USB_DMA_INIT_D alignment ATA_ALIGN(n) 0 USB_GLOBAL cachable ram & alignment, stack use only USB_BDT NonCachable, stack use only USB_CONTROLL ER_DATA NonCachable, stack use only USB_DMA_NONI cachable ram & NIT_DATA_ALIGN( alignment n) USB_DMA_INIT_D cachable ram & ATA_ALIGN(n) alignment USB_GLOBAL Put in bss, stack use only USB_BDT Put in bss, stack use only USB_CONTROLL ER_DATA NULL, stack use only USB_DMA_NONI alignment NIT_DATA_ALIGN( n) USB_DMA_INIT_D alignment ATA_ALIGN(n) NOTE “NULL” means that the MACRO is empty and has no influence. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 23 Build the USB examples in MCUXpresso SDK There are four assistant MACROs: USB_DATA_ALIGN_SIZE Used in USB stack and application, defines the default align size for USB data. USB_DATA_ALIGN_SIZE_MULTIPLE(n) Used in USB stack and application, calculates the value that is multiple of the data align size. USB_DMA_DATA_NONCACHEABLE Used in USB stack and application, puts data in the noncacheable region if the cache is enabled. USB_GLOBAL_DEDICATED_RAM Used in USB stack and application, puts data in the dedicated RAM if dedicated RAM is enabled. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 24 NXP Semiconductors System-on-Chip (SoC) files Chapter 3 Porting to a new platform To port the USB stack to a new platform in the MCUXpresso SDK, the SoC-related files, board-related files, and a linker file for a specified compiler are required. Assume that the new platform’s name is “xxxk22f120m” based on the MK22F51212 SoC. 3.1 System-on-Chip (SoC) files SoC source/header files are in the following directory, which are available by default from MCUXpresso SDK. Figure 22. SoC header file directory NOTE Linker files for each toolchain are in the linker directory. Different toolchains’ SoC startup assembler files are in the Arm, GCC, and IAR directories. 3.2 Board files The files for the board configuration and the clock configuration on a specific platform are needed to enable the USB stack. The clock configuration files are shown in the following image. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 25 Porting to a new platform Figure 23. Clock configuration files 1. Create a folder “xxxk22f120m” under the examples directory. 2. Copy the clock_config.c and clock_config.h file from the similar platform. For example, the TWR-K22F120M Tower System module. 3. Ensure that BOARD_BootClockxxx is implemented in the clock_config.c file. For example, BOARD_BootClockRUN and BOARD_BootClockHSRUN. The user can change the function name. However, the BOARD_InitHardware must call the function. BOARD_InitHardware is introduced later. The board clock initialization is based on the board crystal oscillator. Ensure that the following two MACROs are defined in the clock_config.h file: #define BOARD_XTAL0_CLK_HZ #define BOARD_XTAL32K_CLK_HZ 8000000U 32768U The user can updatethe MACROs according to the board design. For example, if the XTAL0 crystal oscillator is 16000000U and the XTAL32K is 32768U, change the following MACROs as follows: #define BOARD_XTAL0_CLK_HZ #define BOARD_XTAL32K_CLK_HZ 16000000U 32768U The board configuration files are shown in the following image: Figure 24. Board configuration files 4. Copy board.c and board.h from the similar platform. For example, the TWR-K22F120M platform. Ensure that the BOARD_InitDebugConsole is implemented in board.c file and that the BOARD_InitHardware calls the function. The BOARD_InitHardware function is introduced later. The Debug console-related MACROS are needed in the board.h file, as follows: #define #define #define #define BOARD_DEBUG_UART_TYPE DEBUG_CONSOLE_DEVICE_TYPE_UART BOARD_DEBUG_UART_BASEADDR (uint32_t) UART2 BOARD_DEBUG_UART_CLKSRC BUS_CLK BOARD_DEBUG_UART_BAUDRATE 115200 MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 26 NXP Semiconductors Porting examples Update the MACROs according to the board design. For example, the default UART instance on the board is LPUART1, the type of default UART instance on one specific platform is LPUART, and the LPUART clock source is the external clock. In this case, change the above MACROs as follows: #define #define #define #define BOARD_DEBUG_UART_TYPE DEBUG_CONSOLE_DEVICE_TYPE_LPUART BOARD_DEBUG_UART_BASEADDR (uint32_t) LPUART1 BOARD_DEBUG_UART_CLKSRC kCLOCK_Osc0ErClk BOARD_DEBUG_UART_BAUDRATE 115200 Note that there are three kinds of UART instances provided in MCUXpresso SDK devices, UART, LPUART, and LPSCI. The interfaces of the UART instance are different. To provide a uniform UART interface to a USB Host example in which the UART function is used, a UART instance wrapper is provided. The wrapper is implemented in the usb_uart_drv.c, usb_lpuart_drv.c, or usb_lpsci_drv.c file and has a common header file usb_uart_drv.h. For a different UART instance, use the corresponding UART instance wrapper file in the project. 3.3 Porting examples 3.3.1 Copy a new platform example The platform USB examples directory is shown in the following figure. Figure 25. USB examples directory Copy the existed example’s whole directory from the similar platform, which ensures that all example source files and project files are copied. For example, copy the twrk22f120m/usb/usb_device_audio_generator_lite to the twrkxx/usb location, which ensures that sources files and project files for usb_device_audio_generator_lite example are copied. 3.3.2 Porting the example For different examples, different pins are used. As a result, the pin_mux.c/h files are needed to assign different pins to a specific functionality. Check the board schematic for correct pin settings. Example-related port pin configurations are required in the following files: MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 27 Porting to a new platform Figure 26. Example-related port pin configuration files Ensure the BOARD_InitPins function is implemented in the pin_mux.c file. In this function, the port clock and pin mux are initialized. Ensure that the BOARD_InitHardware calls the function. The BOARD_InitHardware function will be introduced later. For example, on the TWR-K65F180M board, the VBUS of the USB Host is controlled by the PORTD_8 as a GPIO. Therefore, the PORTD clock needs to be enabled first and then the PORTD_8 configured to GPIO functionality. The debug console uses UART2. The TX/RX pins are PORTE_16 and PORTE_17. As a result, the clock of PORTE needs to be enabled first and then the PORTE_16 and PORTE_17 configured to alternative 3. This is example code for TWR-K65F180M: void BOARD_InitPins(void) { /* Initialize UART2 pins below */ CLOCK_EnableClock(kCLOCK_PortE); PORT_SetPinMux(PORTE, 16u, kPORT_MuxAlt3); PORT_SetPinMux(PORTE, 17u, kPORT_MuxAlt3); } /* Initialize usb vbus pin */ CLOCK_EnableClock(kCLOCK_PortD); PORT_SetPinMux(PORTD, 8u, kPORT_MuxAsGpio); Check the specific board design to find out which port is used to control the USB VBUS and which port is used for the debug console. For example, in the customer’s board design, the PORTC_15 is used to control the USB VBUS, and PORTD_1 and PORTD_2 is used for debug console. The following shows the example code: void BOARD_InitPins(void) { /* Initialize UART2 pins below */ CLOCK_EnableClock(kCLOCK_PortD); PORT_SetPinMux(PORTD, 1u, kPORT_MuxAlt3); PORT_SetPinMux(PORTD, 2u, kPORT_MuxAlt3); } /* Initialize usb vbus pin */ CLOCK_EnableClock(kCLOCK_PortC); PORT_SetPinMux(PORTC, 15u, kPORT_MuxAsGpio); The VBUS must output high. The following is example code for TWR-K65F180M: void BOARD_InitHardware(void) { gpio_pin_config_t pinConfig; BOARD_InitPins(); MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 28 NXP Semiconductors Porting examples BOARD_BootClockRUN(); BOARD_InitDebugConsole(); /* vbus gpio output high */ pinConfig.pinDirection = kGPIO_DigitalOutput; pinConfig.outputLogic = 1U; GPIO_PinInit(PTD, 8U, &pinConfig); } The user can change the function as follows: void BOARD_InitHardware(void) { gpio_pin_config_t pinConfig; BOARD_InitPins(); BOARD_BootClockxxx(); BOARD_InitDebugConsole(); /* vbus gpio output high */ pinConfig.pinDirection = kGPIO_DigitalOutput; pinConfig.outputLogic = 1U; GPIO_PinInit(PTC, 15U, &pinConfig); } 3.3.3 Modify the example project USB example project files are kept in the example directory, as shown in the following figure. Figure 27. Modify the example project 1. Open the project and change the SoC. NOTE a. Check the project SoC and update to the porting platform SoC. b. Update the SoC full name, platform name, and board type name macros if the SoC is updated. For example, for TWR-K22F120M, update the CPU_MK22FN512VDC12, TWR_K22F120M, and TOWER macros. 2. Check the files in startup group, for example (IAR): MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 29 Porting to a new platform Figure 28. Check files in startup group Ensure that the system_MK22F51212.c, system_MK22F51212.h, and strtup_MK22F51212.s are the porting SoC files. Also change the include path. 3. Check the files in the platform/clock group, for example (IAR): Figure 29. Check files in platform/clock group Ensure that the fsl_clock_MK22F51212.c, and fsl_clock_MK22F51212.h are porting SoC files. Additionally, change the include path. 4. Change the files in board group, for example (IAR): Figure 30. Change files in board group MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 30 NXP Semiconductors Porting examples Ensure that board.c, board.h, clock_config.c, and clock_config.h are porting platform files. Additionally, change the include path. 5. Check the files in the sources group, for example (IAR): Figure 31. Check files in source group The example application source files are copied when copying the example directory. Change the include path. 6. Change the linker file to the new platform. Ensure that the linker file is the porting SoC file. 7. Debug console may use UART, LPUART, or LPSCI according to the platform. As a result, the example project needs to contain UART, LPUART, or LPSCI driver files according to the platform. Figure 32. UART, LPUART, and LPSCI files For example, for TWR-K22F120M all UART files are all in the project. In another example, TWR-K80F150M, all LPUART files are in the project. 3.3.4 USB host CDC example The MCUXpresso SDK debug console can be based on The MCUXpresso SDK UART, LPUART, or LPSCI driver. Because different platforms may use different drivers, the CDC has a wrapper code. The files, which call the corresponding driver API MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 31 Porting to a new platform according to the debug console use UART, LPUART, or LPSCI. The utility uses the BOARD_DEBUG_UART_TYPE toidentify the UART type. To use a different UART instance, use the corresponding UART instance wrapper file. The MCUXpresso SDK debug console only enables send. The Host CDC example needs the receive function. Therefore, configuration MACROs need to be defined in the board.h file. The debug console and the Host CDC share the same configuration. This is an example: #define #define #define #define BOARD_DEBUG_UART_TYPE BOARD_DEBUG_UART_BASEADDR BOARD_DEBUG_UART_CLKSRC BOARD_DEBUG_UART_BAUDRATE DEBUG_CONSOLE_DEVICE_TYPE_UART (uint32_t)UART1 kCLOCK_CoreSysClk 115200 Update MACROs according to board design. For example, the default UART instance on the board is LPUART1, the type of default UART instance on one specific platform is LPUART, and the LPUART clock source is the external clock. In this case, change the above MACROs as follows: #define #define #define #define BOARD_DEBUG_UART_TYPE DEBUG_CONSOLE_DEVICE_TYPE_LPUART BOARD_DEBUG_UART_BASEADDR (uint32_t) LPUART1 BOARD_DEBUG_UART_CLKSRC kCLOCK_Osc0ErClk BOARD_DEBUG_UART_BAUDRATE 115200 3.3.5 USB device MSC SD card example USB device MSC SD card example needs SDHC driver support and SD card support. The example works only if the platform supports both SD card and the SDHC. To enable this example using the same code, the following MACROs are defined in the board.h file: #define #define #define #define #define #define #define BOARD_SDHC_BASEADDR BOARD_SDHC_CLKSRC BOARD_SDHC_CD_GPIO_BASE BOARD_SDHC_CD_GPIO_PIN BOARD_SDHC_CD_PORT_BASE BOARD_SDHC_CD_PORT_IRQ BOARD_SDHC_CD_PORT_IRQ_HANDLER SDHC kCLOCK_CoreSysClk GPIOB 20U PORTB PORTB_IRQn PORTB_IRQHandler Update the MACROs according to the board design. For example, the SD card detection GPIO on the board is PORTD_1. In this case, change the above MACROs as follows: #define #define #define #define #define #define #define BOARD_SDHC_BASEADDR BOARD_SDHC_CLKSRC BOARD_SDHC_CD_GPIO_BASE BOARD_SDHC_CD_GPIO_PIN BOARD_SDHC_CD_PORT_BASE BOARD_SDHC_CD_PORT_IRQ BOARD_SDHC_CD_PORT_IRQ_HANDLER SDHC kCLOCK_CoreSysClk GPIOD 1U PORTD PORTD_IRQn PORTD_IRQHandler 3.3.6 USB device audio speaker example USB device audio speaker example needs the I2C, SAI, and DMA driver support. The instance of SAI (I2S) and I2C are defined in the app.h file in the example directory as follows: #define DEMO_SAI I2S0 #define DEMO_I2C I2C0 #define DEMO_SAI_CLKSRC kCLOCK_CoreSysClk Update the MACROs according to board design. For example, the I2S instance on the board is I2S2. In this case, change the above MACROs as follows: #define DEMO_SAI I2S2 #define DEMO_I2C I2C2 #define DEMO_SAI_CLKSRC kCLOCK_CoreSysClk MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 32 NXP Semiconductors Porting examples 3.3.7 USB device CCID Smart card example The example is based on the EMVL1 stack, which works on the EMV protocol. As a result, the example can only be ported to the platform that supports both the EMVL1 stack and the EMV protocol. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 33 Developing a new USB application Chapter 4 Developing a new USB application The following sections provide information regarding how to develop a new USB application. 4.1 Developing a new USB device application This chapter introduces how to develop a new USB device application. The user needs to use the application interface and the following steps to develop a new application. 4.1.1 Application interfaces The interface definition between the application and the classes includes the calls shown in the following table: Table 2. Application and classes interface definition API Call Description Class Initialization This API is used to initialize the class. Receive Data This API is used by the application to receive data from the host system. Send Data This API is used by the application to send data to the host system. USB descriptor-related callback Handles the callback to get the descriptor. USB Device call back function Handles the callback by the class driver to inform the application about various USB bus events. USB Class-specific call back function Handles the specific callback of the class. 4.1.2 How to develop a new device application Perform these steps to develop a new device application: 1. Create a new application directory under /boards/ /usb_examples/ usb_device_ _ to locate the application source files and header files. For example, /boards/ /usb_examples/usb_device_hid_test. 2. Copy the following files from the similar existing applications to the application directory that is created in Step 1. usb_device_descriptor.c usb_device_descriptor.h The usb_device_descriptor.c and usb_device_descriptor.h files contain the USB descriptors that are dependent on the application and the class driver. 3. Copy the bm directory from the similar existing application directory to the new application directory. Remove the unused project directory from the bm directory. Modify the project directory name to the new application project name. For example, to create toolchain-IAR, board-frdmk64 class-hid related application, create the new application hid_test based on a similar existing application hid_mouse. Change /boards/ /usb_examples/usb_device_hid_mouse to /boards/ /usb_examples/usb_device_hid_test MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 34 NXP Semiconductors Developing a new USB device application 4. Modify the project file name to the new application project file name, for example, from dev_hid_mouse_bm.ewp to dev_hid_test_bm.ewp. Globally replace the existing name to the new project name by editing the project files. The dev_hid_test_bm.ewp file includes the new application project setting. 5. Create a new source file to implement the main application functions and callback functions. The name of this file is similar to the new application name, such as mouse.c and keyboard.c. The following sections describe the steps to change application files created in the steps above to match the new application. 4.1.2.1 Changing the usb_device_descriptor.c file This file contains the class driver interface. It also contains USB standard descriptors such as device descriptor, configuration descriptor, string descriptor, and the other class-specific descriptors that are provided to class driver when required. The lists below show user-modifiable variable types for an already implemented class driver. The user should also modify the corresponding MACROs defined in the usb_device_descriptor.h file. See the MCUXpresso SDK API Reference Manual (document MCUXSDKAPIRM) for details. • usb_device_endpoint_struct_t; • usb_device_endpoint_list_t; • usb_device_interface_struct_t; • usb_device_interfaces_struct_t; • usb_device_interface_list_t; • usb_device_class_struct_t; • usb_device_class_config_struct_t; • usb_device_class_config_list_struct_t; This diagram shows the relationship between these items: Figure 33. Relationship diagram This is the sample code implementation of the endpoint descriptor for the HID class: /* HID mouse endpoint information */ usb_device_endpoint_struct_t g_UsbDeviceHidMouseEndpoints[USB_HID_MOUSE_ENDPOINT_COUNT] = { /* HID mouse interrupt IN pipe */ { USB_HID_MOUSE_ENDPOINT_IN | (USB_IN << USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_SHIFT), MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 35 Developing a new USB application }; }, USB_ENDPOINT_INTERRUPT, FS_HID_MOUSE_INTERRUPT_IN_PACKET_SIZE, The endpoint address, transfer type, and max packet size in this variable are defined in the usb_device_descriptor.h file. The user may change these value as required. For example, to implement a CDC class application: /* Define endpoint for a communication class */ usb_device_endpoint_struct_t g_UsbDeviceCdcVcomCicEndpoints[USB_CDC_VCOM_ENDPOINT_CIC_COUNT] = { { USB_CDC_VCOM_INTERRUPT_IN_ENDPOINT | (USB_IN << 7U), USB_ENDPOINT_INTERRUPT, FS_CDC_VCOM_INTERRUPT_IN_PACKET_SIZE, }, }; /* Define endpoint for data class */ usb_device_endpoint_struct_t g_UsbDeviceCdcVcomDicEndpoints[USB_CDC_VCOM_ENDPOINT_DIC_COUNT] = { { USB_CDC_VCOM_BULK_IN_ENDPOINT | (USB_IN << 7U), USB_ENDPOINT_BULK, FS_CDC_VCOM_BULK_IN_PACKET_SIZE, }, { USB_CDC_VCOM_BULK_OUT_ENDPOINT | (USB_OUT << 7U), USB_ENDPOINT_BULK, FS_CDC_VCOM_BULK_OUT_PACKET_SIZE, } }; The endpoint count and alternate setting of the interface may differ in various applications. The user may change these values as required. For example, the interface structure of a CDC class application is as follows: /* Define interface for communication class */ usb_device_interface_struct_t g_UsbDeviceCdcVcomCommunicationInterface[] = {{ 1U, { USB_CDC_VCOM_ENDPOINT_CIC_COUNT, g_UsbDeviceCdcVcomCicEndpoints, }, }}; /* Define interface for data class */ usb_device_interface_struct_t g_UsbDeviceCdcVcomDataInterface[] = { { 0, { USB_CDC_VCOM_ENDPOINT_DIC_COUNT, g_UsbDeviceCdcVcomDicEndpoints, }, NULL } }; The class code, subclass code, and protocol code may differ in various classes. For example, the usb_device_interfaces_struct of a CDC class is as follows: /* Define interfaces for the virtual com */ usb_device_interfaces_struct_t g_UsbDeviceCdcVcomInterfaces[USB_CDC_VCOM_INTERFACE_COUNT] = { {USB_CDC_VCOM_CIC_CLASS, USB_CDC_VCOM_CIC_SUBCLASS, USB_CDC_VCOM_CIC_PROTOCOL, USB_CDC_VCOM_COMM_INTERFACE_INDEX, g_UsbDeviceCdcVcomCommunicationInterface, sizeof(g_UsbDeviceCdcVcomCommunicationInterface) / sizeof(usb_device_interfaces_struct_t)}, {USB_CDC_VCOM_DIC_CLASS, USB_CDC_VCOM_DIC_SUBCLASS, USB_CDC_VCOM_DIC_PROTOCOL, USB_CDC_VCOM_DATA_INTERFACE_INDEX, g_UsbDeviceCdcVcomDataInterface, sizeof(g_UsbDeviceCdcVcomDataInterface) / sizeof(usb_device_interfaces_struct_t)}, }; MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 36 NXP Semiconductors Developing a new USB device application The interface count may differ in various applications. For example, the usb_device_interface_list of a CDC class application is as follows: /* Define configurations for virtual com */ usb_device_interface_list_t g_UsbDeviceCdcVcomInterfaceList[USB_DEVICE_CONFIGURATION_COUNT] = { { USB_CDC_VCOM_INTERFACE_COUNT, g_UsbDeviceCdcVcomInterfaces, }, }; The interface list, class type and configuration count may differ in various applications. For example, the usb_device_class_struct of a CDC class application is as follows: /* Define class information for virtual com */ usb_device_class_struct_t g_UsbDeviceCdcVcomConfig = { g_UsbDeviceCdcVcomInterfaceList, kUSB_DeviceClassTypeCdc, USB_DEVICE_CONFIGURATION_COUNT, }; • g_UsbDeviceDescriptor This variable contains the USB Device Descriptor. Sample code implementation of the device descriptor for the HID class is shown as follows: uint8_t g_UsbDeviceDescriptor[USB_DESCRIPTOR_LENGTH_DEVICE] = { USB_DESCRIPTOR_LENGTH_DEVICE, /* Size of this descriptor in bytes */ USB_DESCRIPTOR_TYPE_DEVICE, /* DEVICE Descriptor Type */ USB_SHORT_GET_LOW(USB_DEVICE_SPECIFIC_BCD_VERSION), USB_SHORT_GET_HIGH(USB_DEVICE_SPECIFIC_BCD_VERSION),/* USB Specification Release Number in Binary-Coded Decimal (i.e., 2.10 is 210H). */ USB_DEVICE_CLASS, /* Class code (assigned by the USB-IF). */ USB_DEVICE_SUBCLASS, /* Subclass code (assigned by the USB-IF). */ USB_DEVICE_PROTOCOL, /* Protocol code (assigned by the USB-IF). */ USB_CONTROL_MAX_PACKET_SIZE, /* Maximum packet size for endpoint zero (only 8, 16, 32, or 64 are valid) */ 0xA2U, 0x15U, /* Vendor ID (assigned by the USB-IF) */ 0x7CU, 0x00U, /* Product ID (assigned by the manufacturer) */ USB_SHORT_GET_LOW(USB_DEVICE_DEMO_BCD_VERSION), USB_SHORT_GET_HIGH(USB_DEVICE_DEMO_BCD_VERSION),/* Device release number in binarycoded decimal */ 0x01U, /* Index of string descriptor describing manufacturer */ 0x02U, /* Index of string descriptor describing product */ 0x00U, /* Index of string descriptor describing the device serial number */ USB_DEVICE_CONFIGURATION_COUNT, /* Number of possible configurations */ }; The macros in the variable above are defined in the usb_device_descriptor.h file, such as the USB_DEVICE_CLASS, USB_DEVICE_SUBCLASS, and USB_DEVICE_PROTOCOL. Those values may need to be modified as required. The vendor ID and product ID can also be modified. • g_UsbDeviceConfigurationDescriptor This variable contains the USB Configuration Descriptor. Sample code implementation of the configuration descriptor for the HID class is providing in the following: uint8_t g_UsbDeviceConfigurationDescriptor[USB_DESCRIPTOR_LENGTH_CONFIGURATION_ALL] = { USB_DESCRIPTOR_LENGTH_CONFIGURE, /* Size of this descriptor in bytes */ USB_DESCRIPTOR_TYPE_CONFIGURE, /* CONFIGURATION Descriptor Type */ USB_SHORT_GET_LOW(USB_DESCRIPTOR_LENGTH_CONFIGURATION_ALL), USB_SHORT_GET_HIGH(USB_DESCRIPTOR_LENGTH_CONFIGURATION_ALL),/* Total length of data returned for this configuration. */ USB_HID_MOUSE_INTERFACE_COUNT, /* Number of interfaces supported by this configuration */ USB_HID_MOUSE_CONFIGURE_INDEX, /* Value to use as an argument to the MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 37 Developing a new USB application */ SetConfiguration() request to select this configuration 0x00U, /* Index of string descriptor describing this configuration */ (USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_D7_MASK) | (USB_DEVICE_CONFIG_SELF_POWER << USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_SELF_POWERED_SHIFT) | (USB_DEVICE_CONFIG_REMOTE_WAKEUP << USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_REMOTE_WAKEUP_SHIFT), /* Configuration characteristics D7: Reserved (set to one) D6: Self-powered D5: Remote Wakeup D4...0: Reserved (reset to zero) */ USB_DEVICE_MAX_POWER, /* Maximum power consumption of the USB * device from the bus in this specific * configuration when the device is fully * operational. Expressed in 2 mA units * (i.e., 50 = 100 mA). */ The macro USB_DESCRIPTOR_LENGTH_CONFIGURATION_ALL, which is defined in the usb_device_descriptor.h, needs to be modified to equal the size of this variable. The interface count and configuration index may differ in various applications. For example, this part of a CDC class application is as shown below: /* Size of this descriptor in bytes */ USB_DESCRIPTOR_LENGTH_CONFIGURE, /* CONFIGURATION Descriptor Type */ USB_DESCRIPTOR_TYPE_CONFIGURE, /* Total length of data returned for this configuration. */ USB_SHORT_GET_LOW(USB_DESCRIPTOR_LENGTH_CONFIGURATION_ALL), USB_SHORT_GET_HIGH(USB_DESCRIPTOR_LENGTH_CONFIGURATION_ALL), /* Number of interfaces supported by this configuration */ USB_CDC_VCOM_INTERFACE_COUNT, /* Value to use as an argument to the SetConfiguration() request to select this configuration */ USB_CDC_VCOM_CONFIGURE_INDEX, /* Index of string descriptor describing this configuration */ 0, /* Configuration characteristics D7: Reserved (set to one) D6: Self-powered D5: Remote Wakeup D4...0: Reserved (reset to zero) */ (USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_D7_MASK) | (USB_DEVICE_CONFIG_SELF_POWER << USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_SELF_POWERED_SHIFT) | (USB_DEVICE_CONFIG_REMOTE_WAKEUP << USB_DESCRIPTOR_CONFIGURE_ATTRIBUTE_REMOTE_WAKEUP_SHIFT), /* Maximum power consumption of the USB * device from the bus in this specific * configuration when the device is fully * operational. Expressed in 2 mA units * (i.e., 50 = 100 mA). */ USB_DEVICE_MAX_POWER, The interface descriptor may differ from various applications. For example, the interface descriptor of a CDC class application would be as shown below. /* Communication Interface Descriptor */ USB_DESCRIPTOR_LENGTH_INTERFACE, USB_DESCRIPTOR_TYPE_INTERFACE, USB_CDC_VCOM_COMM_INTERFACE_INDEX, 0x00, USB_CDC_VCOM_ENDPOINT_CIC_COUNT, USB_CDC_VCOM_CIC_CLASS, USB_CDC_VCOM_CIC_SUBCLASS, USB_CDC_VCOM_CIC_PROTOCOL, 0x00, /* Interface Description String Index*/ The class specific descriptor may differ from various applications. For example, the class specific descriptor of a CDC class application would be as shown below. /* CDC Class-Specific descriptor */ USB_DESCRIPTOR_LENGTH_CDC_HEADER_FUNC, /* Size of this descriptor in bytes */ USB_DESCRIPTOR_TYPE_CDC_CS_INTERFACE, /* CS_INTERFACE Descriptor Type */ HEADER_FUNC_DESC, 0x10, MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 38 NXP Semiconductors Developing a new USB device application 0x01, /* USB Class Definitions for Communications the Communication specification version 1.10 */ USB_DESCRIPTOR_LENGTH_CDC_CALL_MANAG, /* Size of this descriptor in bytes */ USB_DESCRIPTOR_TYPE_CDC_CS_INTERFACE, /* CS_INTERFACE Descriptor Type */ CALL_MANAGEMENT_FUNC_DESC, 0x01, /*Bit 0: Whether device handle call management itself 1, Bit 1: Whether device can send/receive call management information over a Data Class Interface 0 */ 0x01, /* Indicates multiplexed commands are handled via data interface */ USB_DESCRIPTOR_LENGTH_CDC_ABSTRACT, /* Size of this descriptor in bytes */ USB_DESCRIPTOR_TYPE_CDC_CS_INTERFACE, /* CS_INTERFACE Descriptor Type */ USB_CDC_ABSTRACT_CONTROL_FUNC_DESC, 0x06, /* Bit 0: Whether device supports the request combination of Set_Comm_Feature, Clear_Comm_Feature, and Get_Comm_Feature 0, Bit 1: Whether device supports the request combination of Set_Line_Coding, Set_Control_Line_State, Get_Line_Coding, and the notification Serial_State 1, Bit ... */ USB_DESCRIPTOR_LENGTH_CDC_UNION_FUNC, /* Size of this descriptor in bytes */ USB_DESCRIPTOR_TYPE_CDC_CS_INTERFACE, /* CS_INTERFACE Descriptor Type */ USB_CDC_UNION_FUNC_DESC, 0x00, /* The interface number of the Communications or Data Class interface */ 0x01, /* Interface number of subordinate interface in the Union */ The endpoint descriptor may differ from various applications. For example, the endpoint descriptor of a CDC class application is as follows: /*Notification Endpoint descriptor */ USB_DESCRIPTOR_LENGTH_ENDPOINT, USB_DESCRIPTOR_TYPE_ENDPOINT, USB_CDC_VCOM_INTERRUPT_IN_ENDPOINT | (USB_IN << 7U), USB_ENDPOINT_INTERRUPT, USB_SHORT_GET_LOW(FS_CDC_VCOM_INTERRUPT_IN_PACKET_SIZE), USB_SHORT_GET_HIGH(FS_CDC_VCOM_INTERRUPT_IN_PACKET_SIZE), FS_CDC_VCOM_INTERRUPT_IN_INTERVAL, } • String Descriptors Users can modify string descriptors to customize their product. String descriptors are written in the UNICODE format. An appropriate language identification number is specified in the USB_STR_0. Multiple language support can also be added. • USB_DeviceGetDeviceDescriptor This interface function is invoked by the application. This call is made when the application receives the kUSB_DeviceEventGetDeviceDescriptor event from the Host. Mandatory descriptors that an application is required to implement are as follows: — Device Descriptor — Configuration Descriptor — Class-Specific Descriptors (For example, for HID class implementation, Report Descriptor, and HID Descriptor) Apart from the mandatory descriptors, an application should also implement various string descriptors as specified by the Device Descriptor and other configuration descriptors. Sample code for HID class application is as follows: /* Get device descriptor request */ usb_status_t USB_DeviceGetDeviceDescriptor(usb_device_handle handle, usb_device_get_device_descriptor_struct_t *deviceDescriptor) { deviceDescriptor->buffer = g_UsbDeviceDescriptor; deviceDescriptor->length = USB_DESCRIPTOR_LENGTH_DEVICE; return kStatus_USB_Success; } MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 39 Developing a new USB application The user may assign the appropriate variable of the device descriptor. For example, if the device descriptor variable name is g_UsbDeviceDescriptorUser, the sample code is as follows: /* Get device descriptor request */ usb_status_t USB_DeviceGetDeviceDescriptor(usb_device_handle handle, usb_device_get_device_descriptor_struct_t *deviceDescriptor) { deviceDescriptor->buffer = g_UsbDeviceDescriptorUser; deviceDescriptor->length = USB_DESCRIPTOR_LENGTH_DEVICE; return kStatus_USB_Success; } • USB_DeviceGetConfigurationDescriptor This interface function is invoked by the application. This call is made when the application receives the kUSB_DeviceEventGetConfigurationDescriptor event from the Host. /* Get device configuration descriptor request */ usb_status_t USB_DeviceGetConfigurationDescriptor( usb_device_handle handle, usb_device_get_configuration_descriptor_struct_t *configurationDescriptor) { if (USB_HID_MOUSE_CONFIGURE_INDEX > configurationDescriptor->configuration) { configurationDescriptor->buffer = g_UsbDeviceConfigurationDescriptor; configurationDescriptor->length = USB_DESCRIPTOR_LENGTH_CONFIGURATION_ALL; return kStatus_USB_Success; } return kStatus_USB_InvalidRequest; } The macro HID_MOUSE_CONFIGURE_INDEX may differ from various applications. For example, the implementation of a CDC class application would be as follows: usb_status_t USB_DeviceGetConfigurationDescriptor( usb_device_handle handle, usb_device_get_configuration_descriptor_struct_t *configurationDescriptor) { if (USB_CDC_VCOM_CONFIGURE_INDEX > configurationDescriptor->configuration) { configurationDescriptor->buffer = g_UsbDeviceConfigurationDescriptor; configurationDescriptor->length = USB_DESCRIPTOR_LENGTH_CONFIGURATION_ALL; return kStatus_USB_Success; } return kStatus_USB_InvalidRequest; } • USB_DeviceGetStringDescriptor This interface function is invoked by the application. This call is made when the application receives the kUSB_DeviceEventGetStringDescriptor event from the Host. See the usb_device_hid_mouse example for sample code. • USB_DeviceGetHidReportDescriptor This interface function is invoked by the application. This call is made when the application receives the kUSB_DeviceEventGetHidReportDescriptor event from the Host. See the usb_device_hid_mouse example for sample code. • USB_DeviceSetSpeed Because HS and FS descriptors are different, the device descriptors and configurations need to be updated to match the current speed. By default, the device descriptors and configurations are configured using FS parameters for EHCI, KHCI, and other controllers, such as LPC IP3511. When the EHCI is enabled, the application needs to call this function to update the device by using the current speed. The updated information includes the endpoint max packet size, endpoint interval, and so on. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 40 NXP Semiconductors Developing a New USB Host Application 4.1.2.2 Changing the usb_device_descriptor.h file This file is mandatory for the application to implement. The usb_device_descriptor.c file includes this file for function prototype definitions. When the user modifies the usb_device_descriptor.c, MACROs in this file should also be modified. 4.1.2.3 Changing the application file • Main application function The main application function is provided by two functions: USB_DeviceApplicationInit and APP_task (optional). The USB_DeviceApplicationInit enables the clock and the USB interrupt and also initialize the specific USB class. See the usb_device_hid_mouse example for the sample code. • USB device call back function The device callback function handles the USB device-specific requests. See the usb_device_hid_mouse example for the sample code. • USB Class-specific call back function The class callback function handles the USB class-specific requests. See the usb_device_hid_mouse example for the sample code. 4.2 Developing a New USB Host Application 4.2.1 Background In the USB system, the host software controls the bus and talks to the target devices following the rules defined by the specification. A device is represented by a configuration that is a collection of one or more interfaces. Each interface comprises one or more endpoints. Each endpoint is represented as a logical pipe from the application software perspective. The host application software registers a callback with the USB host stack, which notifies the application about the device attach/ detach events and determines whether the device is supported or not. The following figure shows the enumeration and detachment flow. MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 41 Developing a new USB application Figure 34. Enumeration and detachment flow The USB host stack is a few lines of code executed before starting communication with the USB device. The examples on the USB stack are written with class driver APIs. Class drivers work with the host API as a supplement to the functionality. They make it easy to achieve the target functionality (see example sources for details) without dealing with the implementation of standard routines. The following code steps are taken inside a host application driver for any specific device. 4.2.2 How to develop a new host application 4.2.2.1 Creating a project Perform the following steps to create a project. • Create a new application directory under /boards/ /usb_examples/ usb_host_ _ to locate the application source files and header files. For example, / boards/ /usb_examples/usb_host_hid_mouse. • Copy the following files from the similar existing applications to the application directory that is created in step 1. app.c usb_host_config.h The app.c file contains the common initialization code for USB host and the usb_host_config.h file contains the configuration MACROs for the USB host. • Copy the bm directory from the similar existing application directory to the new application directory. Remove the unused project directory from the bm directory. Modify the project directory name to the new application project name. For example, to create toolchain-IAR, board-frdmk64 class-hid related application , create the new application hid_test based on a similar existing application hid_mouse. Copy /boards/frdmk64f/usb_examples/usb_host_hid_mouse/bm MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 42 NXP Semiconductors Developing a New USB Host Application to /boards/frdmk64f/usb_examples/usb_host_hid_test/bm • Modify the project file name to the new application project file name, for example, from host_hid_mouse_bm.ewp to host_hid_test_bm.ewp . Globally replace the existing name to the new project name by editing the project files. The host_hid_test_bm.ewp file includes the new application project setting. • Create a new source file to implement the main application function, application task function, and the callback function. The name of this file is similar to the new application name, such as host_mouse.c and host_keyboard.c. The following sections describe the steps to modify application files created in the steps above to match the new application. 4.2.2.2 Main application function flow In the main application function, follow these steps: Figure 35. Main application function flow • Initialize the USB clock. Call the MCUXpresso SDK API to initialize the KHCI, or the EHCI USB clock. • Initialize the host controller. This allows the stack to initialize the necessary memory required to run the stack and register the callback function to the stack. For example:status = USB_HostInit(CONTROLLER_ID, &g_HostHandle, USB_HostEvent); • Enable the USB ISR. Set the USB interrupt priority and enable the USB interrupt. • Initialize the host stack task and application task. For example (Bare metal): while (1) { #if (defined(USB_HOST_CONFIG_KHCI) && (USB_HOST_CONFIG_KHCI > 0U)) USB_HostKhciTaskFunction(g_HostHandle); #endif /* USB_HOST_CONFIG_KHCI */ #if (defined(USB_HOST_CONFIG_EHCI) && (USB_HOST_CONFIG_EHCI > 0U)) USB_HostEhciTaskFunction(g_HostHandle); #endif /* USB_HOST_CONFIG_EHCI */ USB_HostMsdTask(&g_MsdCommandInstance); } Note that in this code, the g_MsdCommandInstance variable contains all states and pointers used by the application to control or operate the device. If implementing the application task as USB_HostHidTestTask and use g_HidTestInstance to maintain the application states, modify the code as follows: MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 43 Developing a new USB application while (1) { #if (defined(USB_HOST_CONFIG_KHCI) && (USB_HOST_CONFIG_KHCI > 0U)) USB_HostKhciTaskFunction(g_HostHandle); #endif /* USB_HOST_CONFIG_KHCI */ #if (defined(USB_HOST_CONFIG_EHCI) && (USB_HOST_CONFIG_EHCI > 0U)) USB_HostEhciTaskFunction(g_HostHandle); #endif /* USB_HOST_CONFIG_EHCI */ USB_HostHidTestTask(&g_HidTestInstance); } 4.2.2.3 Event callback function In the app.c file, there is one USB_HostEvent function. By default, the function is registered to the host stack when calling the USB_HostInit. In the USB Host stack, customers do not have to write any enumeration code. When the device is connected to the host controller, the USB Host stack enumerates the device. The device attach/detach events are notified by this callback function. Application needs to implement one or more functions to correspond to one class process. These application functions are called in the USB_HostEvent. The device’s configuration handle and interface list are passed to the application through the function so that the application can determine whether the device is supported by this application. There are four events in the callback: kUSB_HostEventAttach, kUSB_HostEventNotSupported, kUSB_HostEventEnumerationDone, and kUSB_HostEventDetach. The events occur as follows: • When one device is attached, host stack notifies kUSB_HostEventAttach. • The application returns kStatus_USB_Success to notify the host stack that the device configuration is supported by this class application, or return the kStatus_USB_NotSupported to notify the host stack that the device configuration is not supported by this class application. • The Host stack continues for enumeration if the device is supported by the application and notifies kUSB_HostEventEnumerationDone when the enumeration is done. • The Host stack checks the next device’s configuration if the current configuration is not supported by the application. • When the Host stack checks all configurations and all are not supported by the application, it notifies the kUSB_HostEventNotSupported. • When the device detaches, the Host stack notifies the kUSB_HostEventDetach. This is the sample code for the HID mouse application. The USB_HostHidMouseEvent function should be called bythe USB_HostEvent. In this code, the g_HostHidMouse variable contains all states and pointers used by the application to control or operate the device: usb_status_t USB_HostHidMouseEvent ( usb_device_handle deviceHandle, usb_host_configuration_handle configurationHandle, uint32_t eventCode ) { /* Process the same and supported device's configuration handle */ static usb_host_configuration_handle s_ConfigHandle = NULL; usb_status_t status = kStatus_USB_Success; uint8_t id; usb_host_configuration_t *configuration; uint8_t interfaceIndex; usb_host_interface_t *interface; switch (eventCode) { case kUSB_HostEventAttach: /* judge whether is configurationHandle supported */ configuration = (usb_host_configuration_t *)configurationHandle; MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 44 NXP Semiconductors Developing a New USB Host Application for (interfaceIndex = 0; interfaceIndex < configuration->interfaceCount; + +interfaceIndex) { interface = &configuration->interfaceList[interfaceIndex]; id = interface->interfaceDesc->bInterfaceClass; if (id != USB_HOST_HID_CLASS_CODE) { continue; } id = interface->interfaceDesc->bInterfaceSubClass; if ((id != USB_HOST_HID_SUBCLASS_CODE_NONE) && (id != USB_HOST_HID_SUBCLASS_CODE_BOOT)) { continue; } id = interface->interfaceDesc->bInterfaceProtocol; if (id != USB_HOST_HID_PROTOCOL_MOUSE) { continue; } else { /* the interface is supported by the application */ g_HostHidMouse.deviceHandle = deviceHandle; g_HostHidMouse.interfaceHandle = interface; s_ConfigHandle = configurationHandle; return kStatus_USB_Success; } } status = kStatus_USB_NotSupported; break; case kUSB_HostEventNotSupported: break; case kUSB_HostEventEnumerationDone: if (s_ConfigHandle == configurationHandle) { if ((g_HostHidMouse.deviceHandle != NULL) && (g_HostHidMouse.interfaceHandle ! = NULL)) { /* the device enumeration is done */ if (g_HostHidMouse.deviceState == kStatus_DEV_Idle) { g_HostHidMouse.deviceState = kStatus_DEV_Attached; } else { usb_echo("not idle mouse instance\r\n"); } } } break; case kUSB_HostEventDetach: if (s_ConfigHandle == configurationHandle) { /* the device is detached */ s_ConfigHandle = NULL; if (g_HostHidMouse.deviceState != kStatus_DEV_Idle) { g_HostHidMouse.deviceState = kStatus_DEV_Detached; } } break; default: break; } return status; } MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 45 Developing a new USB application If implementing the callback as USB_HostHidTestEvent, use g_HidTestInstance, and support the device that the class code is USB_HOST_HID_TEST_CLASS_CODE, sub-class code is USB_HOST_HID_TEST_SUBCLASS_CODE, and the protocol is USB_HOST_HID_TEST_PROTOCOL. The code can be modified as follows: usb_status_t USB_HostHidMouseEvent ( usb_device_handle deviceHandle, usb_host_configuration_handle configurationHandle, uint32_t eventCode ) { /* Process the same and supported device's configuration handle */ static usb_host_configuration_handle s_ConfigHandle = NULL; usb_status_t status = kStatus_USB_Success; uint8_t id; usb_host_configuration_t *configuration; uint8_t interfaceIndex; usb_host_interface_t *interface; switch (eventCode) { case kUSB_HostEventAttach: /* judge whether is configurationHandle supported */ configuration = (usb_host_configuration_t *)configurationHandle; for (interfaceIndex = 0; interfaceIndex < configuration->interfaceCount; + +interfaceIndex) { interface = &configuration->interfaceList[interfaceIndex]; id = interface->interfaceDesc->bInterfaceClass; if (id != USB_HOST_HID_TEST_CLASS_CODE) { continue; } id = interface->interfaceDesc->bInterfaceSubClass; if (id != USB_HOST_HID_TEST_SUBCLASS_CODE) { continue; } id = interface->interfaceDesc->bInterfaceProtocol; if (id != USB_HOST_HID_TEST_PROTOCOL) { continue; } else { /* the interface is supported by the application */ g_HidTestInstance.deviceHandle = deviceHandle; g_HidTestInstance.interfaceHandle = interface; s_ConfigHandle = configurationHandle; return kStatus_USB_Success; } } status = kStatus_USB_NotSupported; break; case kUSB_HostEventNotSupported: break; case kUSB_HostEventEnumerationDone: if (s_ConfigHandle == configurationHandle) { if ((g_HidTestInstance.deviceHandle != NULL) && (g_HidTestInstance.interfaceHandle != NULL)) { /* the device enumeration is done */ if (g_HidTestInstance.deviceState == kStatus_DEV_Idle) { g_HidTestInstance.deviceState = kStatus_DEV_Attached; } else { MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 46 NXP Semiconductors Developing a New USB Host Application } usb_echo("not idle mouse instance\r\n"); } } break; case kUSB_HostEventDetach: if (s_ConfigHandle == configurationHandle) { /* the device is detached */ s_ConfigHandle = NULL; if (g_HidTestInstance.deviceState != kStatus_DEV_Idle) { g_HidTestInstance.deviceState = kStatus_DEV_Detached; } } break; default: break; } } return status; Note that the kStatus_DEV_Attached, kStatus_DEV_Detached MACROs are defined in the example. 4.2.2.4 Class initialization When the supported device is attached, the device’s class needs to be initialized. For example, the HID mouse initialization flow is as follows: Figure 36. HID mouse initialization flow • Call class initialization function to initialize the class instance. • Call class set interface function to set the class interface • When the set interface callback returns successfully, the application can run. 4.2.2.5 Sending/Receiving data to/from the device The transfer flow is as follows: 1. Call the USB_hostClassxxx API to begin the transfer. 2. The transfer result is notified by the callback function that is passed as a parameter. 3. The HID mouse host uses the following code to receive data from the device:USB_HostHidRecv(classHandle, mouseBuffer, bufferLength, callbackFunction, callbackParameter); MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 47 USB compliance tests Chapter 5 USB compliance tests For the device, this is enabled on "dev_hid_mouse_bm" as an example. enable USB_DEVICE_CONFIG_USB20_TEST_MODE (0U) The macro is defined in usb_device_config.h. Use the TWR-K65F180M Tower System module as an example. The file path is /boards/twrk65f180m/usb_examples/usb_device_hid_mouse/bm/usb_device_config.h. For the host, this is enabled on "host_mad_fatfs_bm" as an example. enable USB_HOST_CONFIG_COMPLIANCE_TEST (0U) The macro is defined in the usb_host_config.h file. For example, for the TWR-K65F180M Tower System module, the file path is /boards/twrk65f180m/usb_examples/usb_host_msd_fatfs/bm/usb_host_config.h MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 48 NXP Semiconductors Chapter 6 Revision history This table summarizes revisions to this document since the release of the previous version. Table 3. Revision history Revision number Date Substantive changes 1 01/2016 KSDK 2.0.0 release 2 08/2016 Added LPC content for release 3 09/2016 Updated for KSDK 2.0.0 release 5 4 11/2016 Updated IAR version and USB code structure version, Section 2.4.1 and Section 2.4.2. 5 03/2017 Updated for MCUXpresso SDK 6 04/2017 Added note in Section 2.3 7 11/2017 MCUXpresso SDK 2.3.0 release 8 05/2018 Updated Section 4.1.2.1., "Changing the usb_device_descriptor.c file" Removed Section 2.3.4, "Step-by-step guide for Kinetis Design Studio (KDS) IDE", Updated for MCUXpresso SDK 2.4.0 release MCUXpresso SDK USB Stack User’s Guide, Revision 8, May 2018 NXP Semiconductors 49 How To Reach Us Home Page: nxp.com Information in this document is provided solely to enable system and software implementers to use NXP products. There are no express or implied copyright licenses granted hereunder to design or fabricate any integrated circuits based on the information in this document. NXP reserves the right to make changes without further notice to any products herein. Web Support: NXP makes no warranty, representation, or guarantee regarding the suitability of its products for nxp.com/support any particular purpose, nor does NXP assume any liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. “Typical” parameters that may be provided in NXP data sheets and/or specifications can and do vary in different applications, and actual performance may vary over time. All operating parameters, including “typicals,” must be validated for each customer application by customer's technical experts. NXP does not convey any license under its patent rights nor the rights of others. NXP sells products pursuant to standard terms and conditions of sale, which can be found at the following address: nxp.com/ SalesTermsandConditions. NXP, the NXP logo, NXP SECURE CONNECTIONS FOR A SMARTER WORLD, All other product or service names are the property of their respective owners. ARM, AMBA, ARM Powered, are registered trademarks of ARM Limited (or its subsidiaries) in the EU and/or elsewhere. All rights reserved. Ⓒ 2018 NXP B.V.
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Author : NXP Semiconductors Create Date : 2018:05:13 22:10:28-08:00 Keywords : MCUXSDKUSBSUG Modify Date : 2018:05:14 00:15:32-05:00 Language : EN XMP Toolkit : Adobe XMP Core 5.6-c015 84.159810, 2016/09/10-02:41:30 Creator Tool : AH XSL Formatter V6.2 MR6 for Windows (x64) : 6.2.8.19325 (2015/01/06 12:40JST) Metadata Date : 2018:05:14 00:15:32-05:00 Producer : Antenna House PDF Output Library 6.2.640 (Windows (x64)) Trapped : False Format : application/pdf Title : MCUXpresso SDK USB Stack User's Guide Description : This document provides the following:..• Detailed steps to compile the USB examples, download a binary image, and run the examples...• Detailed steps to port the USB stack to a new platform...• Detailed steps to develop a new application based on the existing classes in the USB stack. Creator : NXP Semiconductors Subject : MCUXSDKUSBSUG Document ID : uuid:86a157f6-d858-4ec1-a943-5fefa56aa7be Instance ID : uuid:5d0a6c35-33f9-4c63-8dee-82b6a6e42385 Page Mode : UseOutlines Page Count : 50 Warning : [Minor] Ignored duplicate Info dictionaryEXIF Metadata provided by EXIF.tools