Cypress EZ-USB® FX3™ SDK Using the FX3 SDK under Mac OS Version 1.3.3 Cypress Semiconductor 198 Champion Court San Jose, CA 95134-1709 Phone (USA): 800.858.1810 Phone (Intl): 408.943.2600 http://www.cypress.com Using the FX3 SDK under Mac OS, Version 1.3.3 1 Copyrights Copyrights Copyright © 2014 Cypress Semiconductor Corporation. All rights reserved. FX3, CX3, FX3S, FX2G2 and SD3 are the trademarks of Cypress Semiconductor. All other trademarks or registered trademarks referenced herein are the property of their respective owners. The information in this document is subject to change without notice and should not be construed as a commitment by Cypress. While reasonable precautions have been taken, Cypress assumes no responsibility for any errors that may appear in this document. No part of this document may be copied or reproduced in any form or by any means without the prior written consent of Cypress. Made in the U.S.A. Disclaimer CYPRESS MAKES NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress reserves the right to make changes without further notice to the materials described herein. Cypress does not assume any liability arising out of the application or use of any product or circuit described herein. Cypress does not authorize its products for use as critical components in life-support systems where a malfunction or failure may reasonably be expected to result in significant injury to the user. The inclusion of Cypress’ product in a lifesupport systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges. License Agreement Please read the license agreement during installation. Using the FX3 SDK under Mac OS, Version 1.3.3 2 Contents 1 Introduction ................................................................................................................................. 4 1.1 SDK Components ............................................................................................................ 4 2 SDK Installation ........................................................................................................................... 5 2.1 Pre-requisites ................................................................................................................... 5 2.2 SDK Installation ................................................................................................................ 5 2.3 Setting Environment Variables ......................................................................................... 7 3 Building the Firmware Examples .............................................................................................. 8 4 Debugging ................................................................................................................................... 9 Using the FX3 SDK under Mac OS, Version 1.3.3 3 1 Introduction The FX3 SDK includes the FX3/FX3S firmware libraries and example firmware applications which can be used with the EZ-USB FX3 DVK, along with documentation on the firmware API and the programming model. All of the firmware examples have an Eclipse project associated with them and can be compiled using the Yagarto GNU ARM tool chain and the Eclipse IDE for C/C++ developers. The FX3 SDK also includes a CyUSB library for MacOS that allows users to develop user space applications to talk to generic USB devices; as well as a set of applications using this library that allow programming and testing data transfers with the FX3 device. This 1.3.3 release of the FX3 SDK supports firmware development using the Eclipse IDE and programming using console based tools. 1.1 SDK Components The FX3 SDK package for Mac OS is a gzipped tar archive that contains: 1. The FX3 firmware libraries and header files. 2. FX3 firmware API documentation and programmer’s manual. 3. Firmware examples 4. CyUSB Suite for Mac OS – API library and applications for talking to generic USB devices connected to a host computer running Mac OS. 5. Yagarto GNU ARM EABI tool chain for compilation of FX3 firmware applications. 6. Eclipse package with the following plugins: a. GNU ARM Eclipse Plugin for managed firmware builds. Using the FX3 SDK under Mac OS, Version 1.3.3 4 2 SDK Installation 2.1 Pre-requisites The following tools are required for proper functioning of various components of the FX3 SDK. 1. Java Runtime Environment – The Eclipse IDE requires Version 7 of the Java Runtime Environment (JRE) or Java Development Kit (JDK). 2. A native C compiler for the host computer (such as gcc) is required to compile the elf2img converter program that converts ELF firmware binaries into the bootable .img file format. 2.2 SDK Installation The EZ-USB FX3 SDK for Mac OS is released in the form of a gzipped tar archive called FX3_SDK_MacOS.tar.gz. On extraction, this tar archive contains four other gzipped tar archives: 1. fx3_firmware_macos.tar.gz: The FX3 firmware library and examples. 2. arm_gcc.tar.gz: Yagarto ARM GNU toolchain. 3. eclipse.tgz: Eclipse Kepler IDE along with required plugins. 4. cyusb_mac_1.0.tar.gz: CyUSB Suite for Mac OS. The installation procedure involves extraction of these archives and the setting of a few environment variables as below. 1. Extract the contents of the FX3_SDK_MacOS.tar.gz archive at a preferred location, say, $HOME/Cypress. Change to the install location ($HOME/Cypress) and extract the contents of the fx3_firmware_macos.tar.gz, arm_gcc.tar.gz, cyusb_mac_1.0.tar.gz and eclipse.tar.gz files. The directory structure after all archives are extracted is shown in Figure 2-1. Using the FX3 SDK under Mac OS, Version 1.3.3 5 Boot firmware library and headers Firmware examples Build scripts Firmware libraries and headers Firmware binary converter libcyusb usage examples libcyusb library header libcyusb library source Eclipse IDE GNU ARM Compilation tools Figure 2-1: FX3 SDK Directory Structure 2. Create the following environment variables pointing to the install path of the firmware build scripts and the GNU ARM compiler. The variables need to be set so that they can be seen by GUI applications launched from Spotlight or Finder. Please see <TBD> for instructions on how the variables can be set. Using the FX3 SDK under Mac OS, Version 1.3.3 6 a. PATH: Add the GNU ARM compiler binary path to the PATH variable (e.g.: $HOME/Cypress/yagarto-4.7.2/bin) b. FX3_INSTALL_PATH: Path where the fx3_firmware_macos.tar.gz has been extracted (e.g.: $HOME/Cypress/cyfx3sdk) c. ARMGCC_INSTALL_PATH: Path where the GNU ARM toolchain is extracted (e.g.: $HOME/Cypress/yagarto-4.7.2) d. ARMGCC_VERSION: ARM GNU toolchain version. This should be set to 4.7.2 3. Change to the Cypress/cyfx3sdk/util/elf2img folder and compile the elf2img program that converts ELF firmware binaries into the .img binaries that can be used to boot the FX3 device. e.g.: cd $FX3_INSTALL_PATH/util/elf2img gcc elf2img.c –o elf2img –Wall 4. Change the Cypress/cyusb_mac_1.0 folder and follow the instructions in the README file for compiling the CyUSB library and sample applications. Refer to the documentation in the Cypress/cyusb_mac_1.0/doc folder for instructions on how to use these tools. 2.3 Setting Environment Variables The following steps provide one way of setting the environment variables in a way that they can be seen by all applications. 1. Launch AppleScript Editor application. 2. Create a new script with the following content (replace the paths with the actual paths where the SDK has been extracted): do shell script "launchctl setenv FX3_INSTALL_PATH /Users/TestUser/Cypress/cyfx3sdk" do shell script "launchctl setenv ARMGCC_INSTALL_PATH /Users/TestUser/Cypress/yagarto-4.7.2" do shell script "launchctl setenv ARMGCC_VERSION 4.7.2” 3. Save the script with File format as Application. 4. Open “System Preferences -> Users & Groups” and select the “Login Items” option for the current user. Browse to the application created above and set this as a login item. 5. Repeat Step 4 for all users that need access to the FX3 SDK. 6. Save preferences, Logout and Login to set the environment variables. Using the FX3 SDK under Mac OS, Version 1.3.3 7 3 Building the Firmware Examples Please see Chapter 2 of the EZUSBSuite_UG.pdf document under the cyfx3sdk/doc/firmware folder. Using the FX3 SDK under Mac OS, Version 1.3.3 8 4 Debugging Please see Chapter 3 of the EZUSBSuite_UG.pdf document under the cyfx3sdk/doc/firmware folder. Using the FX3 SDK under Mac OS, Version 1.3.3 9