Freescale MQX and Tower System RTOS - Getting Started (Part 4)

Transcription

1 June 24, 2010 Freescale MQX and Tower System RTOS - Getting Started (Part 4) FTF-ENT-F0722 Craig Honegger - President Derek Snell Field Application Engineer Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc.

2 Introduction This course covers TCP/IP and USB connectivity concepts using the Freescale MQX RTOS (Real-Time Operating System). Most embedded products use some level of connectivity for a variety of reasons: Communication with other embedded devices or computers Providing a user interface Downloading of diagnostic information Updating of the application image With the concepts presented in this session you will be able to add connectivity to your products to increase their value to your customers, increase their maintainability, and to make development easier. Presenters: Craig Honegger, President, Embedded Access Inc Craig.Honegger@Embedded-Access.com Derek Snell, Field Application Engineer, Freescale Semiconductor Inc Derek.Snell@Freescale.com Session duration is 3 hours Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 2

3 Session Objectives After completing this session you will be able to: Configure and initialize RTCS Use the socket API to create TCP and UDP connections Use the HTTP Web Server to serve dynamic data in a web page Configure and initialize the USB Host Stack Use the USB Host Stack with various Class Drivers Configure and initialize the USB Device Stack Use the USB Device Stack with various Class Drivers Use the MFS File System with the USB Host Stack RTCS Real-Time TCP/IP Communications Suite API Application Programming Interface TCP Transmission Control Protocol UDP User Datagram Protocol USB Universal Serial Bus MFS MS-Dos File System Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 3

4 Agenda 1. Network Concepts 2. Freescale RTCS Initialization & Configuration Interface Initialization Socket API Application Layer Protocols HTTP Web Server 3. Freescale USB Host Stack Initialization Using the Host Stack with Class Drivers 4. Freescale USB Device Stack Initialization Using the Device Stack with Class Drivers 5. Freescale MFS File System Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 4

5 Introduction to RTCS Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 5

6 TCP/IP Stack designed for embedded processors Uses standard socket interface Extensive list of Application Layer Protocols Scalable at compile time and/or run-time: Only used protocols are included Data requirements are tunable Protocol behavior is controllable Integrated with CodeWarrior to provide TCP/IP-aware debugging Standard release across all processors Integrated with a number of 3rd party optional packages RTCS Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 6

7 RTCS Protocols RPC SSH* XML* SMTP* POP3* SNMP XDR Telnet FTP TFTP HTTP DNS SNTP Sockets SSL* BootP DHCP RIP ICMP TCP UDP IGMP NAT** IP IP-E IPCP PAP CHAP CCP LCP ARP PPP * Optional third party package ** On request Ethernet Serial PPPoE** HDLC Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 7

8 RTCS Architecture Application Task Application Task FTP Server FTP Client HTTP Server SNTP Client SNMP Agent Telnet Client Telnet Server DHCP Server Application Task RTCS API TCP UDP ICMP IP IP-E ARP IGMP TCP/IP Task RTCS Serial ADC I2C Enet MQX Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 8

9 RTCS Directory Structure Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 9

10 Initializing RTCS Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 10

11 RTCS Initialization Sequence Create RTCS by calling RTCS_create() Initialize Interface(s) Assign MAC addresses Bind RTCS to Interface Assign IP address, subnet mask Initialize RTCS Applications RTCS API TCP/IP Task RTCS Apps RTCS Enet MQX Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 11

12 RTCS Initialization Sample Code Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 12

13 Socket API Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 13

14 Sockets Data transfer is done with sockets. A socket is one endpoint of a two-way communication link. Socket defines: Protocol Local IP address and port # Remote IP address and port # RTCS supports TCP and UDP sockets Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 14

15 Creating and using sockets Bound to datagram (UDP) recvfrom() sendto() Unbound socket() bind() connect() Bound to stream (TCP) listen() accept() send() recv() select() getsockopt() setsockopt() shutdown () Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 15

16 Using sockets Sample code Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 16

17 RTCS Configuration Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 17

18 Socket Options Socket options can be set to override default socket behavior using setsockopt(): value = 256; setsockopt(listensock,sol_tcp, OPT_TBSIZE, &value, sizeof(value)); Socket options that can be set include: Window Sizes Various timeouts Blocking vs. non-blocking mode Send and receive push flags Some options must be set before socket is bound For memory constrained applications, it will be necessary to override a few defaults Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 18

19 Close to 100 compile time configuration settings Compile Time Configuration Defaults set in RTCSCFG.H, overridden by user_config.h Each protocol can be individually enabled/disabled Protocol statistics can be individually enabled/disabled Level of error checking performed is configurable Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 19

20 Allows dynamic control of RTCS, including: RTCS task priority and stack size RTCS memory allocation (where, how much) Enabled protocols and protocol behavior Socket behavior Run-Time Configuration Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 20

21 Application Layer Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 21

22 RTCS Application Layer Protocols Telnet Server FTP Server TFTP Server DHCP Server HTTP Server IPCFG Telnet Client FTP Client TFTP Client DHCP Client DNS Resolver SNMP Agent SNTP Client RTCS API TCP/IP Task RTCS MQX Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 22

23 HTTP Server Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 23

24 HTTP 1.1 with persistent connections PUT and GET Methods Form decoding HTTP Server Support for multiple virtual WEB folders, with custom WEB folder path mapping to file system paths. Static filesystem content: pages, images, multimedia, Java archives Dynamic page content, suitable for AJAX applications. CGI-like, dynamic content pages ASP-like, in-page placeholders Basic authentication Integrated with MQX I/O subsystem, MFS and TFS Runs as: Single task servicing multiple sessions One task per session Polled mode Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 24

25 Web Page Sources HTTP Client HTTP Server CGI Table CGI TFS MQX I/O Subsystem MFS USB CF Others FN Table CGI fn fn SD etc Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 25

26 HTTP Server Initialization Include tfs.h, httpd.h and httpd_types.h Declare CGI and Function callback tables, if required Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 26

27 HTTP Server Initialization Install Filesystem Initialize HTTP server, specify root directory and home page Register CGI table and function callback table, if required Start server Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 27

28 More Information Demos: Telnet Server Web server SNTP* SMTP with sockets* DNS Resolution* DHCP Client* Digital Sign** RTCS User s Guide *MCF51CN demos only, ** MPC5125 demo only Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 28

29 Hands-On Lab Part 1 Learn to: Initialize RTCS Initialize HTTP Server Setup TFS to store web pages in internal flash Customize look of the Web Server Add form input for controlling Tower System Hardware (LEDs) Add CGI for obtaining Tower System Inputs (Switches) Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 29

30 MQX USB Host Stack Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 30

31 Introduction MQX USB Stack Features Implements USB 2.0 version Layered architecture: Scalability (choose only components needed in application.) Portability (class drivers independent on underlying hardware.) Class drivers supported: HID devices (mouse, keyboard) MSD devices (flash disk) HUB support (transparent communication through HUB) CDC devices (serial communication) Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 31

32 MQX USB Host Structure User Application MFS Others to be developed Intermediat e I/O Drivers MSD HID CDC Host Class Drivers HUB HOST API (class level) Hardware Independent Layer USB 2.0 Chapter 9 API OS and HW-level HOST API KHCI (Kirin2U/Kirin3- specific controller) EHCI (Enhanced Host Controller Interface) USB Module (low-level drivers) Other (OHCI,...) Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 32

33 KHCI MQX USB Host Low-level Drivers MCF522xx-specific USB controller (codename Kirin host controller) Max. 12 Mbps (no support for high speed) Physical transfer done by HW, DMA Scheduling of transfers done by SW USB transactions handled by SW Requires separate task (khci_task), requires higher CPU load Does not handle any service (handled in app callback instead) EHCI Enhanced Host Controller Interface (industry standard) ColdFire extends the specification (registers also contain bits that are not specified by EHCI standard) Runs on interrupts / application requests USB transactions handled by HW, DMA Small CPU load Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 33

34 Initializing USB Host Stack Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 34

35 Host Application Initialization Install low-level host driver using _usb_host_driver_install Registers low-level HCI driver routines in the USB stack. Low-level driver routines are prepared for each HCI (KHCI, EHCI,..). Always use _bsp_usb_host_callback_table as an argument Initialize host _usb_host_init Initializes host, prepares memory buffers and structures Register device classes in the USB host stack Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 35

36 Defining Driver Capabilities Driver capabilities are defined by USB_HOST_DRIVER_INFO Specifies a user callback function that will be called when a device matching the specified criteria is attached. /* Information for one class or device driver */ typedef struct driver_info { uint_8 idvendor[2]; /* Vendor ID per USB-IF */ uint_8 idproduct[2]; /* Product ID per manufacturer */ uint_8 bdeviceclass; /* Class code, 0xFF if any */ uint_8 bdevicesubclass; /* Sub-Class code, 0xFF if any */ uint_8 bdeviceprotocol; /* Protocol, 0xFF if any */ uint_8 reserved; /* Alignment padding */ event_callback attach_call; } USB_HOST_DRIVER_INFO, _PTR_ USB_HOST_DRIVER_INFO_PTR; Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 36

37 The usb_classes.h file is part of your application. Defining Class Drivers This file enables selected device enumeration and class drivers in the USB Host Stack. Use USBCLASS_INC_XXX definitions to enable classes for the device /* uncomment macro definition for class drivers you want to use in the application */ //#define USBCLASS_INC_HID #define USBCLASS_INC_MASS // #define USBCLASS_INC_CDC // #define USBCLASS_INC_PRINTER #define USBCLASS_INC_HUB Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 37

38 Host Application Example Write your device callback function Four event types should be handled in this function: USB_ATTACH_EVENT called after device was attached USB_CONFIG_EVENT called after device was configured USB_INTF_EVENT called after device was interfaced USB_DETACH_EVENT called after device was detached Enumeration, attach, detach, and configuration events are processed by Chapter 9 sublayer of the USB Stack. No special actions are needed in the handler except: Select interface with _usb_hostdev_select_interface after the ATTACH event (where DEV_STATE==USB_DEVICE_ATTACHED) Remember actual state of the device together with handles for further processing in application. After INTF event, the application may communicate with the device using pipes. Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 38

39 MQX USB Device Stack Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 39

40 USB Device Stack Features All USB-IF chapter 9 compliance USB Class support: Human Interface Device (HID) Communication Data Class Abstract Control Model (CDC ACM) PHDC (Personal Health Care Device Class) MSD (Mass Storage Device) Demo applications available: Mouse USB to Serial USB Network Adapter Weigh Scale (IEEE , IEEE ) RAM Disk Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 40

41 Architecture Overview Applications Mouse Medical Communication Storage Class API USB Device Stack Library HID PHDC CDC MSD mcf5229x mcf54455 Device Layer Low level driver V2 USB IP V4 USB IP USB IP Device API Controller API HW Register IF Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 41

42 Device Layers Application Class Device Layer - USB Descriptors, endpoint information - USB Application implementing class specific callbacks - USB Class API user - USB Framework Module implementation (USB Ch9, Control Endpoint ) - USB generic class implementation (Suspend/Resume/Reset.) - USB function specific implementation (Non Control Endpoint Request, Class specific Request) - USB Device API user - Abstracts Hardware specific details and provides generic USB interfaces to the upper layer - Allows easy port of Applications/Class functionality over different USB IPs Low level driver - USB Controller IP interfacing module. - candidate to change for every new USB IP USB IP Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 42

43 Class API HID HID_HANDLE USB_Class_HID_Init( HID_CONFIG_STRUCT_PTR hid_config_ptr) This API is used to initialize the HID class driver The structure passed to the API contains the callback functions and endpoint information uint_8 USB_Class_HID_Send_Data(HID_HANDLE hid_handle, uint_8 ep_num, uint_8_ptr buff_ptr, uint_32 size) This API is used to by application to send HID application data over the bus. The data buffer, size, endpoint are passed as input parameters to the function. Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 43

44 PHDC Personal Healthcare Device Class uses 1 Bulk IN and one Bulk OUT and optionally 1 Interrupt IN endpoint for Medical Data supports IEEE11073 standard for optimized data exchange Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 44

45 Class API PHDC PHDC_HANDLE USB_Class_PHDC_Init( PHDC_CONFIG_STRUCT_PTR phdc_config_ptr) This API is used to initialize the PHDC class driver The structure passed to the API contains the callback functions and endpoint information uint_8 USB_Class_PHDC_Send_Data(PHDC_HANDLE phdc_handle, boolean meta_data, uint_8 num_tfr, uint_8 qos, uint_8_ptr buff_ptr, uint_32 size) This API is used to by application to send PHDC application data over the bus. The data buffer, size are passed as input parameters to the function. The meta_data qos for the data, num_tfr parameters are passed in this API are PHDC class dependent parameters. uint_8 USB_Class_PHDC_Recv_Data(PHDC_HANDLE phdc_handle, uint_8 ep_num, uint_8_ptr buff_ptr, uint_32 size) This API is used to by application to retrieve PHDC application data from the bus. The data buffer, size, endpoint are passed as input parameters to the function. Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 45

46 CDC_HANDLE USB_Class_CDC_Init( CDC_CONFIG_STRUCT_PTR cdc_config_ptr) This API is used to initialize the CDC class driver The structure passed to the API contains the callback functions and endpoint information Class API CDC uint_8 USB_Class_CDC_Send_Data(CDC_HANDLE cdc_handle, uint_8 ep_num, uint_8_ptr buff_ptr, uint_32 size) This API is used to by application to send CDC application data over the bus. The data buffer, size, endpoint are passed as input parameters to the function. uint_8 USB_Class_CDC_Recv_Data(CDC_HANDLE cdc_handle, uint_8 ep_num, uint_8_ptr buff_ptr, uint_32 size) This API is used to by application to retrieve CDC application data from the bus. The data buffer, size, endpoint are passed as input parameters to the function. Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 46

47 Class API MSD MSD_HANDLE USB_Class_MSD_Init( MSD_CONFIG_STRUCT_PTR msd_config_ptr) This API is used to initialize the MSD class driver The structure passed to the API contains the callback functions and endpoint information uint_8 USB_Class_MSD_Send_Data(MSD_HANDLE msd_handle, uint_8 ep_num, uint_8_ptr buff_ptr, uint_32 size) This API is used to by application to send MSD application data over the bus. The data buffer, size, endpoint are passed as input parameters to the function. uint_8 USB_Class_MSD_Recv_Data(MSD_HANDLE msd_handle, uint_8 ep_num, uint_8_ptr buff_ptr, uint_32 size) This API is used to by application to retrieve MSD application data from the bus. The data buffer, size, endpoint are passed as input parameters to the function. Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 47

48 Applications Design Mouse Medical Communication Storage Class API HID PHDC CDC MSD Device Layer Device API Controller API mcf52259x mcf Low level driver V2 USB IP V4 USB IP USB IP HW Register IF Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 48

49 Application Design USB Descriptors and Endpoints This following key information is defined in the usb_descriptor.c and usb_descriptor.h files Key Structures USB_ENDPOINTS: a uniquely identifiable, logical entity containing endpoint information USB Chapter 9 Descriptors Device Descriptors Configuration Descriptors String Descriptors Functions The functions implemented in these files expose the above information to the application/class drivers Key functions USB_Desc_Get_Descriptor: Retrieve the Descriptor Information USB_Desc_Get_Endpoints: Retrieve the Endpoint information USB_Desc_Get_Interface: Retrieve the Alternate Interface information USB_Desc_Set_Interface: Set the Alternate Interface information USB_Desc_Valid_Configation: Check whether Configuration Id received is valid USB_Desc_Remote_Wakeup: Remote WakeUp supported or not Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 49

50 TASK_TEMPLATE_STRUCT MQX_template_list[] = { { MAIN_TASK, Main_Task, 2*3000L, 7L, "Main", MQX_AUTO_START_TASK}, { 0L, 0L, 0L, 0L, 0L, 0L } }; Application Design Main Task void Main_Task(void) { HID_CONFIG_STRUCT config_struct; uint_64 x = 0; _disable_interrupts(); /* initialize the Global Variable Structure */ USB_memzero(&g_mouse, sizeof(mouse_global_variable_struct)); USB_memzero(&config_struct, sizeof(hid_config_struct)); /* Initialize the USB interface */ } config_struct.ep_desc_data = &usb_desc_ep; config_struct.hid_class_callback.callback =USB_App_Callback; config_struct.hid_class_callback.arg = &g_mouse.app_handle; config_struct.param_callback.callback =USB_App_Param_Callback; config_struct.param_callback.arg = &g_mouse.app_handle; config_struct.desc_callback_ptr = &desc_callback; config_struct.desc_endpoint_cnt = HID_DESC_ENDPOINT_COUNT; config_struct.ep = &g_mouse.ep; g_mouse.app_handle = USB_Class_HID_Init(&config_struct); _enable_interrupts(); while (TRUE) { /* call the periodic task function */ USB_HID_Periodic_Task(); } Populate callback function structure Call Class Initialize function Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 50

51 void USB_App_Callback(uint_8 event_type, void* val,pointer arg) { #pragma unused (arg) #pragma unused (val) switch(event_type) { case USB_APP_BUS_RESET: g_mouse.mouse_init=false; break; case USB_APP_ENUM_COMPLETE: g_mouse.mouse_init = TRUE; move_mouse();/* run the coursor movement code */ break; case USB_APP_SEND_COMPLETE: /*check whether enumeration is complete or not */ if(g_mouse.mouse_init) { move_mouse();/* run the coursor movement code */ } break; case USB_APP_ERROR: break; Handle BUS RESET callback Application Design Main Callback Handle enumeration complete callback which implies connection is established with Host Handle completion of previous activation of USB_HID_Send_Data API Handle error condition } default: break; } return; Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 51

52 USB Stack Configuration usb_stack_config.h Which functional class to compile? Compile for network support? Use queuing in class layer? Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 52

53 MQX MFS Stack Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 53

54 What is MFS? Introduction MFS provides a library of functions that is compatible with the Microsoft MS-DOS FAT file system. All the functions guarantee that application tasks have mutually exclusive access to the file system. MFS is implemented as a device driver that an application must install over a lower-level device driver. Examples of lower-level drivers are: drivers for memory devices flash disks floppy disks partition-manager devices. MFS uses the lower-level driver to access the hardware device. MFS supports FAT12, FAT16, and FAT32 file systems. Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 54

55 MFS structure Files and directories MFS Partition manager (optional) Device Hardware Flash cards USB mass storage devices ATA PCMCIA Removable hard drives Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 55

56 MFS Features MFS Features Standard FAT12, FAT16 and FAT32 support Standard handling of directory paths Both \ and / can be used as directory separators Support for * and? wildcard characters File Attributes Supported Standard: Directory, Read-only, Hidden File, System file, Archived file Special: Volume Label file (only one such file allowed in root directory) File Time and Date Each file entry contains 16-bit time and date fields. FAT Copies MFS updates as many FATs as configured for. Only reads the first FAT. High-Level Formatting An application can perform high-level formatting on a disk by calling ioctl(). Partition Manager Support for multiple partitions on one physical drive Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 56

57 MFS Devices Devices usable by MFS MFS can be installed on any memory-oriented device which is standard MQX IO device in terms of open/close/read/write/ioctl calls is able to seek on any given position supports few block-oriented IOCTL Devices supported today ATA PC Card flash cards USB mass storage devices RAM or MRAM FlashX driver working with internal or external Flash memory SPI-based SD Cards Code under development (or legacy not-tested code) ATA hard drives Floppy-disk drives Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 57

58 Partition Manager Partition Manager Special virtual device which may be put between MFS and a hardware device. Enables MFS to work independently on one of multiple partitions installed on a physical disk. Should be installed and opened like other devices before use by MFS. Should be closed and uninstalled when no longer needed in an application. Available functions: _io_part_mgr_install Installs the partition manager device driver. _io_part_mgr_uninstall Uninstalls the partition manager device driver. fclose Closes the partition manager fopen Opens the partition manager. Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 58

59 Basic MFS API MFS API _io_mfs_install - initializes MFS and allocates memory for all of the internal MFS data structures. _io_mfs_uninstall - uninstalls the MFS device driver and frees the memory context. fopen - Opens the device by specifying device name or opens a file if both device name and file path is specified. fd_ptr = fopen( mfsram:\data\march\march2000results.data, w ); fclose Closes the file and frees the memory allocated by given FILE_PTR ioctl File- or device-specific control interface. Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 59

60 Using USB MSD Class with MFS Install and open _usb_mfs device Install and open partition manager Look for valid partition If none found, remove partition manager Install MFS on partition or raw drive Open file system All of this is contained in the file usb_task.c in \mfs\examples\mfs_usb: usb_filesystem_install( ) usb_filesystem_uninstall( ) Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 60

61 Shell Library MFS Shell Shell library implements a simple command line interface for MFS, RTCS, or private application needs. Typically wraps console user interface around low-level use of IOCTL User can extend Shell by writing new commands Commands are registered using string-to-function mapping structures const SHELL_COMMAND_STRUCT Shell_commands[] = { { "cd", Shell_cd }, { "copy", Shell_copy }, { "create", Shell_create }, /*. */ { "sh", Shell_sh }, { "type", Shell_type }, { "write", Shell_write }, { "?", Shell_command_list }, }; { NULL, NULL } Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 61

62 Shell Commands MQX MFS RTCS abort exit help kill pause sh tad cache cd compare copy create del dir flush format mkdir rmdir pwd read ren type write arpdisp echod eds enet exec ftp ftpd gate getroute ghbn ipconfig load nat nstat ping rtcs sendto snmpd tftp tftpc telnet telnetd Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 62

63 Hands-On Lab Part 2 Learn to: Install and initialize USB Host stack Manage enumeration of USB Flash drive Install and open Partition Manager Install MFS Enable web server to read files from USB flash drive Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 63

64 USB HOST HID Walk Through Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 64

65 Using the HID Class Define HID driver capabilities Wait for an attach event On attach, select interface Wait for interfaced event Select keyboard or mouse protocol Find interrupt pipe Initialize a transfer request Receive data Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 65

66 Host Application Example HID Keyboard Example Handling an ATTACH event Event handler gets event code, device and interface handles We should remember the handles and the current state (for main application state machine) Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 66

67 Host Application Example HID Keyboard Example Main task state machine Selecting Interface When first interfaced, HID keyboard requires setting protocol. Note that we need to pass validation structure we obtained during interface select into HID class driver. Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 67

68 Host Application Example HID Keyboard Example Communicating with keyboard Application obtains handle to communication pipe (in this case interrupt receive pipe). Receive transfer is initiated on the pipe, passing buffer pointer for data to be received. Waiting for interrupt transaction Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 68

69 Session Closing Thank you for attending, and I hope you achieved the following: Ability to add connectivity to your products Ability to increase maintainability Capability to develop more easily due to a deeper understanding of Freescale MQX Reg. U.S. Pat. & Tm. Off. BeeKit, BeeStack, CoreNet, the Energy Efficient Solutions logo, Flexis, MXC, Platform in a Package, Processor Expert, QorIQ, QUICC Engine, SMAROS, TurboLink and VortiQa are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners Freescale Semiconductor, Inc. 69

70