FM Universal Peripheral Driver Library Quick Start Guide

Transcription

1 FM Universal Peripheral Driver Library Quick Start Guide Doc. No Rev *A Cypress Semiconductor 198 Champion Court San Jose, CA Phone (USA): Phone (Intnl):

2 Copyrights Cypress Semiconductor Corporation, This document is the property of Cypress Semiconductor Corporation and its subsidiaries, including Spansion LLC ( Cypress ). This document, including any software or firmware included or referenced in this document ( Software ), is owned by Cypress under the intellectual property laws and treaties of the United States and other countries worldwide. Cypress reserves all rights under such laws and treaties and does not, except as specifically stated in this paragraph, grant any license under its patents, copyrights, trademarks, or other intellectual property rights. If the Software is not accompanied by a license agreement and you do not otherwise have a written agreement with Cypress governing the use of the Software, then Cypress hereby grants you under its copyright rights in the Software, a personal, non-exclusive, nontransferable license (without the right to sublicense) (a) for Software provided in source code form, to modify and reproduce the Software solely for use with Cypress hardware products, only internally within your organization, and (b) to distribute the Software in binary code form externally to end users (either directly or indirectly through resellers and distributors), solely for use on Cypress hardware product units. Cypress also grants you a personal, nonexclusive, nontransferable, license (without the right to sublicense) under those claims of Cypress s patents that are infringed by the Software (as provided by Cypress, unmodified) to make, use, distribute, and import the Software solely to the minimum extent that is necessary for you to exercise your rights under the copyright license granted in the previous sentence. Any other use, reproduction, modification, translation, or compilation of the Software is prohibited. CYPRESS MAKES NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS DOCUMENT OR ANY SOFTWARE, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress reserves the right to make changes to this document without further notice. Cypress does not assume any liability arising out of the application or use of any product or circuit described in this document. Any information provided in this document, including any sample design information or programming code, is provided only for reference purposes. It is the responsibility of the user of this document to properly design, program, and test the functionality and safety of any application made of this information and any resulting product. Cypress products are not designed, intended, or authorized for use as critical components in systems designed or intended for the operation of weapons, weapons systems, nuclear installations, life-support devices or systems, other medical devices or systems (including resuscitation equipment and surgical implants), pollution control or hazardous substances management, or other uses where the failure of the device or system could cause personal injury, death, or property damage ( Unintended Uses ). A critical component is any component of a device or system whose failure to perform can be reasonably expected to cause the failure of the device or system, or to affect its safety or effectiveness. Cypress is not liable, in whole or in part, and Company shall and hereby does release Cypress from any claim, damage, or other liability arising from or related to all Unintended Uses of Cypress products. Company shall indemnify and hold Cypress harmless from and against all claims, costs, damages, and other liabilities, including claims for personal injury or death, arising from or related to any Unintended Uses of Cypress products. Cypress, the Cypress logo, Spansion, the Spansion logo, and combinations thereof, PSoC, CapSense, EZ-USB, F-RAM, and Traveo are trademarks or registered trademarks of Cypress in the United States and other countries. For a more complete list of Cypress trademarks, visit cypress.com. Other names and brands may be claimed as property of their respective owners. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 2

3 Contents 1. Introduction Peripheral Driver Library Overview Getting and Installing the PDL PDL Structure Using PDL Example Code Writing Your Own Code Using the PDL Build and Run a PDL Project Before You Begin Building with IAR Embedded Workbench Building with Keil µvision A. PDL-Related Resources B. Migrating a V4 Keil Project to V Revision History Document Revision History FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 3

4 1. Introduction Cypress provides the Peripheral Driver Library (PDL) to simplify software development for the FM0+, FM3, and FM4 MCU families. The PDL reduces the need to understand register usage and bit structures, thus easing software development for the extensive set of peripherals in the FM families. You configure the library for the particular device, and then use API calls to initialize and use a peripheral. Using the PDL makes it easier to port code from one family to the other, because the same code supports all FM families. If you develop code at the register level, you must understand how each peripheral uses which registers and pins, and the bit values required to control the peripheral correctly. You modify register values directly in your code. The PDL makes this unnecessary. However, developers who wish to work at the register level can use the PDL source code as a guide. Combined with study of the appropriate data sheet and peripheral manual, you can learn the information you need to use a peripheral. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 4

5 2. Peripheral Driver Library Overview The PDL supports all devices in the FM0+, FM3, and FM4 families. The PDL provides a high-level API to configure, initialize, and use a peripheral driver. The PDL also provides numerous examples that demonstrate how to use the peripherals. The PDL includes the necessary startup code for each supported device. Table 2-1 lists the peripherals supported by the PDL. Table 2-1. Peripheral Support in the PDL Peripheral Description Peripheral Description ADC Analog Digital Converter I2SL Inter IC Sound Lite BT Base Timer ICC IC Card Interface CAN Controller Area Network LCD Liquid Crystal Display CLK Clock Functions LPM Low Power Modes CR RC Oscillator trimming LVD Low Voltage Detection CRC Cyclic Redundancy Check MFS Multi-Function Serial Interface CSV Clock Supervisor MFT Multi-Function Timer DAC Digital Analog Converter PCRC Programmable CRC DMA Direct Memory Access PPG Programmable Pulse Generator DSTC Descriptor System Data Transfer Controller QPRC Quadrature Position/Revolution Counter DT Dual Timer RC Remote Control (HDMI-CEC/Remote Control Reception/Transmission) EXINT External Interrupts RESET Reset EXTIF External Bus Interface RTC Real Time Clock Flash Flash Memory SDIF SD Card Interface GPIO General Purpose I/O Ports UID Unique ID HBIF HyperBus Interface VBAT VBAT Domain HSSPI High Speed Quad Serial Peripheral Interface WC Watch Counter I2CS Inter IC Slave WDG Software and Hardware Watchdog Counter I2S Inter IC Sound The PDL is a superset of all the code required to build any driver for any supported device. This superset design means: All APIs needed to initialize, configure and use a peripheral are available. The PDL includes error checking, because a peripheral may not be present on the selected device. The superset design means the PDL is useful across all devices, whatever peripherals are available. This enables code to maintain compatibility across platforms where peripherals remain present. If you configure the PDL to include a peripheral that is unavailable on the hardware, your project will fail at compile time, rather than at runtime. The PDL configuration logic knows the target processor and removes the peripheral register headers for unsupported peripherals from the build. Before writing code to use a peripheral, consult the datasheet for the particular series or device to confirm support for the peripheral. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 5

6 Peripheral Driver Library Overview 2.1 Getting and Installing the PDL Most Cypress FM0+ and FM4 starter kits install the PDL as part of the kit's software package. See the PDL-Related Resources section for links to choices. If you install such a kit, the default location for the PDL is Documents/Cypress/FM_PDL_<version>. If your kit does not install the PDL, you can download the PDL Installer from the Cypress FM0+, FM3, or FM4. Product pages. On the Tools & Software tab, look for the link to download the PDL. Each page links to the same PDL download. There is a large ecosystem of tools and tool providers that support the various FM families. There is an extensive list of choices at the Support Tools web page. Click the link for a particular family to see what s available. Build and Run a PDL Project in this document shows a step-by-step process to build a PDL project with either the IAR Embedded Workbench or the Keil µvision IDEs. 2.2 PDL Structure The PDL is organized into several folders. Table 2-2 shows the PDL folder structure. Table 2-2. PDL Folder Structure Path\Folder common doc driver example template\arm template\iar template\source template\source\backup utility Description Common header files PDL documentation Driver source code and headers Example code Keil project and configuration files for use with example code IAR project and configuration files for use with example code Source files, replace with files from example code, or write your own code Copy of original source files, use to restore template Various utility files When you use the PDL, typically you do not modify the common files, documentation, or the driver code. To develop your own code (or use example code) you work with three files in the template\source folder: pdl_device.h pdl_user.h main.c There is a single IAR Embedded Workbench IDE project for all the example code, located in template\iar. Similarly, there is a single Keil µvision IDE project for all the example code, located in template\arm. Build and Run a PDL Project explains how to use the source files and project files. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 6

7 Peripheral Driver Library Overview 2.3 Using PDL Example Code The PDL installation includes more than 100 code examples. Most peripherals have multiple examples. Each example demonstrates the basic initialization and configuration for the peripheral. It includes a ReadMe file that provides a description of what the example demonstrates, and how to use the example. The Build and Run a PDL Project section of this document guides you step-by-step through the process of configuring the PDL, building a project using an IDE, and debugging the code on the hardware. To use the example code, you: Modify project options in your IDE to target the correct device. Copy two files, main.c and pdl_user.h from the example folder into the template\source folder, replacing the existing files of the same name. Specify the target device and package in pdl_device.h. Build and download the code to the target. If you wish to restore the template source files to their initial state, copy the main.c and pdl_user.h files from the template\source\backup folder into the template\source folder. 2.4 Writing Your Own Code Using the PDL You typically begin with an existing project, like an example in a starter kit, which already has the PDL files added, project options set correctly, and peripherals selected for the example. When developing firmware with PDL, you perform the following tasks: Modify project options in your IDE to target the correct device. Specify the target device and package in pdl_device.h. Configure the PDL in pdl_user.h. Add your firmware in main.c, or additional source files as required. Build and download the code to the target. As noted, pdl_device.h, pdl_user.h and main.c are provided for you in the example code. The project files for both IAR and Keil tools use the PDL source code and these three files. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 7

8 3. Build and Run a PDL Project In this section you build and run an example PDL project, using either of these IDEs: IAR Embedded Workbench version 7.3 or later Keil µvision, version 5 or later For either IDE you will perform three major tasks: Configure the IDE s project options for your hardware. Configure the PDL for your hardware. Build and run the example code. For PDL example code you must configure the IDE because there is a single project file you use for any processor. You must set multiple build options, such as specifying the target processor. The example projects that come with a Starter Kit have these options set correctly, because the kit has a specific processor. If you use an example project from a kit, you do not need to configure the IDE. 3.1 Before You Begin Ensure that you have three items: hardware on which to run the code, the PDL, and a development environment. Hardware The PDL supports all FM-family processors. These instructions use the FM0+ S6E1C-Series MCU Starter Kit shown in Figure 3-1. You can modify the details in these instructions to adapt to other kits, or your own hardware. Refer to the PDL-Related Resources section for links to other kits that install and use the PDL. PDL If you do not have the PDL installed, see Getting and Installing the PDL. These instructions assume the PDL is installed in the default location, Documents/Cypress/FM_PDL_<version>. Development Environment Ensure that you have installed a development environment. These instructions cover: Building with IAR Embedded Workbench Building with Keil FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 8

9 Figure 3-1. The S6E1C3-Series Starter Kit Board FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 9

10 3.2 Building with IAR Embedded Workbench This section guides you through the steps required to build, download, and run a PDL project with IAR tools. These instructions use the Descriptor System Data Transfer Controller (DSTC) example from the PDL Configure the IDE Project In this part of the exercise you change target-dependent project options to adapt the PDL template project file to the particular hardware. PDL example code is designed for any supported processor. As a result you must modify the PDL example project options so the project will work with your chosen processor. This section shows you how. You can skip this section if you use a Starter Kit example, which is already configured for a particular processor. For example, the S6E1C3 starter kit has a similar DSTC example project. In a default kit installation, the project file is here: \Documents\Cypress\FM0+ S6E1C-Series Starter Kit\Firmware\Demo Projects\s6e1c3_dstc\IAER\ s6e1c3_dstc.eww You can double-click the project file and go straight to Configure the PDL to learn how. 1. Open the IAR workspace for PDL example code. The file name is pdl_template.eww. In a default installation, the path to the file is: \Documents\Cypress\FM_PDL_<version>\template\IAR. Double-click the file, and the IAR Embedded Workbench IDE opens, as shown in Figure 3-2. Figure 3-2. Open the IAR Workspace for the PDL Example Code FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 10

11 2. Specify the target processor. Figure 3-3 shows the UI for this step. You will set options in the Release build of the project. A. Open the Options window. Use Project -> Options, then click General Options. B. Specify the device. Enable Device, click the device picker button, and navigate to the Spansion S6E1C32D0A. Figure 3-3. Specify the Device What happens as a result of this choice may require a little explanation. You choose either a Core or a Device. The preferred choice is Device. You then navigate among all the supported manufacturers, series, and devices to find the match to your hardware. For example, you click the drop down menu, navigate to Spansion, and so on. However, you may be using a new processor that is not yet supported in the IAR IDE. When a device is not listed, you choose Core and specify the appropriate ARM Cortex core. If you choose Core, the IAR tools use default values for certain options for the ARM core. These options may not match the actual device, so there are additional options to configure that would otherwise be set based upon the device selection. The instructions in Set the CMSIS memory map at the end of this section discuss this case in detail. 3. Specify the linker configuration file. The PDL includes configuration files for supported hardware. In this step you configure the project to use the correct linker configuration file. The file name is s6e1c32.icf. In a default installation the path to the file is \Documents\Cypress\FM_PDL_<version>\template\IAR\config\s6e1c3x. A. In the Options window, click Linker to go to the linker options. The Config panel is the default panel. B. Click the Browse button, navigate to the linker configuration file to specify the correct file, as shown in Figure 3-4. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 11

12 Figure 3-4. Set the Linker Configuration File 4. Specify the flash loader file. See Figure 3-5. The file name is FlashLoader.board. In a default installation the path is Documents\Cypress\FM_PDL_<version>\template\IAR\config\s6e1c3x\flashloader. A. In the Options window, click Debugger to go to the Debugger options. B. Click the Download tab to show the flash loader options. C. Make sure the Use flash loader(s) option is enabled. D. Click the Browse button, then navigate to the file to specify the correct file. Make sure you get the file from the right folder for the S6E1C3 processor. Figure 3-5. Specify the Flash Loader File FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 12

13 5. Specify the debugger. Figure 3-6 shows the tasks for this step. This example uses the CMSIS DAP debugger. A. Click the Setup tab in the Debugger options. B. Set the Driver option to CMSIS DAP, if it is not already set to that value. C. Make sure the Use macro file(s) option is disabled. D. Click OK to save all the changes made so far. The Options window closes. Figure 3-6. Specify the Debugger 6. Set the CMSIS memory map if necessary. The C-SPY debugger that is part of the IAR IDE requires memory configuration information. This information is in an IAR-specific device description file (DDF). If you set a specific Device in the Target options, as shown in Figure 3-7, then the memory configuration is specified automatically by the DDF built into the IAR tools. Figure 3-7. Target Device Option for IAR tools If you are following the steps in this exercise on the specified hardware, you don t need to do anything. However, you may be working with newly-released hardware not yet fully supported in the IAR tools. This step provides the background information you need to adapt to this situation. If you are using a new product not yet included in the IAR device choices, you specified a Core as your processor variant. In this case when you choose CMSIS-DAP -> Memory Configuration, an alert window would appear, as shown in Figure 3-8. Figure 3-8. Memory Configuration Alert FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 13

14 Click OK and the Memory Configuration window appears, as shown in Figure 3-9. When you specify a Device, this is already set correctly. For a Core, you set the map manually. To set the memory map correctly, refer to the datasheet for the device you are using, and set the sections properly. Figure 3-9. CMSIS-DAP Memory Configuration Window There is, however, an easier solution: use a Cypress starter kit. For example, at the time of this writing the FM4 S6E2GM is a new product, and a DDF for this part has not appeared in the IAR tools. The kit examples set up the CMSIS-DAP memory configuration correctly Configure the PDL In the previous section you configured the IAR development environment. In this section you configure the PDL itself. To do this you will: Copy example files into the PDL template project Configure the PDL for the target device Configure PDL functionality This example implements a data transfer using the software-driven Descriptor System Data Transfer Controller (DSTC) example from the PDL. 1. Copy example files into the PDL template project. Each PDL example includes two files: pdl_user.h enables desired PDL functionality main.c contains code to use the PDL In this step you simply copy those files into the project folder. You will explore the contents of these files in subsequent steps. A. Copy the files from the example folder. Navigate to the PDL example folder. In a default installation, the path is: \Documents\Cypress\FM_PDL_<version>\example\dstc\dstc_sw_transfer Select and copy two files, pdl_user.h and main.c. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 14

15 B. Paste the files into the project folder. Navigate to the PDL template project folder. In a default installation, the path is: \Documents\Cypress\FM_PDL_<version>\template\source. Paste the files into this location, and replace the existing files. Backup files are in the template\source\backup folder. The PDL template project includes and uses these two files. 2. Configure the PDL for the target device. You specify the target processor in pdl_device.h. You change two #define statements in this file. A. Open pdl_device.h in the template\source folder. B. Specify the target series and package. Look for the code that defines the values of PDL_MCU_SERIES and PDL_MCU_PACKAGE. In this case, it is already correct. For any other device you would need to change these definitions. The comments in the file point you to the location where you can find the available definitions. In this example, the code at line 57 defines the series targeted in this example. #define PDL_MCU_SERIES PDL_DEVICE_SERIES_S6E1C3X The code at line 68 defines the package targeted in this example. Change the code to: #define PDL_MCU_PACKAGE PDL_DEVICE_PACKAGE_S6_D C. Close the file. Although you made no change, this is how you configure the PDL to compile code for a particular device. 3. Configure PDL functionality. You configure PDL functionality in pdl_user.h. For this example you don t need to do anything; the example code configures the PDL correctly. This step ensures you are aware of how this works and what you need to do when working on your own project. A. Open pdl_user.h in the template\source folder. B. Examine the contents of the file. This file contains a long list of #define statements, one for each configurable feature of the PDL. To enable a feature, you define it as PDL_ON. Otherwise it is PDL_OFF. Pertinent to this example, find the line of code that sets PDL_PERIPHERAL_ENABLE_DSTC to the value PDL_ON. At the time of this writing, it is at line 122 of the file. // DSTC #define PDL_PERIPHERAL_ENABLE_DSTC PDL_ON C. Close the file. You don t need to make any changes Build and Run the Code The code in the main() function performs the following high-level tasks. Fills a small source data buffer with values Configures the DSTC to move data from the source data buffer to the destination data buffer Triggers the data transfer Compares the destination buffer with the source buffer to confirm the operation was successful You can study the source code in main.c for details of how the code accomplishes these tasks. In this step you will execute the code and confirm success. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 15

16 1. Connect the board to your PC. The precise details will vary based on your hardware. For the S6E1C3 starter kit, the board has two connectors, denoted CN3 and CN4. See Figure 3-1 if you re not sure which is which. Use the provided cable and connect to the CN3 (CMSIS-DAP) port on the board. When properly connected, LED3 Power on the board will be green. 2. Download the code and launch the debugger. Choose Project ->Download & Debug. The IDE compiles, links, downloads the code to the board, and launch the debugger. You should see no warnings or errors. The program counter will be halted at the first line of main() as shown in Figure Figure Debugger Halted at the main() Function 3. Prepare to transfer data. In this step you run the code until just before the actual data transfer. A. Set a breakpoint as shown in Figure The code is: Dstc_SwTrigger(0u); // Start SW transfer with DES + 0 offset B. Choose Debug > Go. Execution halts at the breakpoint. Figure Set a Breakpoint FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 16

17 4. Observe the destination data buffer. The project already has the au32destinationdata buffer set up in the Watch window, as shown in Figure Before the data transfer, all values are zero. Figure Observe the Destination Buffer 5. Copy the data to the destination data buffer. In this step you run the rest of the code, halt, and examine the contents of the destination data buffer. A. Choose Debug > Step Over. B. Observe the values of au32destinationdata in the Watch window, shown in Figure Figure Observe Values in the Watch Window The application used the DSTC peripheral to copy the data from the source buffer to the destination buffer. You have successfully built a simple application using the PDL. You can run the rest of the code if you wish. It compares the source and destination buffers to confirm they are the same. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 17

18 3.3 Building with Keil µvision This section guides you through the steps required to build, download, and run a PDL project with Keil tools. These instructions use the Descriptor System Data Transfer Controller (DSTC) example from the PDL. Since the release of the PDL code there has been a major version change in the Keil µvision IDE. The PDL code examples and the µvision project files were built and tested with version 4.7 of the tools. These instructions use the current version (5.x) and show you how to migrate the project file to the new version of the tools. However, you can follow these steps using either version of the µvision IDE. The instructions will highlight any significant difference between versions when they exist. The screenshots are based on version 5.x Configure the IDE In this part of the exercise you change target-dependent project options to adapt the PDL template project file to the particular hardware you are using. PDL example code is designed for any supported processor. As a result you must modify the PDL example project options so the project will work with your chosen processor. This section shows you how. You can skip this entire section if you use a Starter Kit example. The starter kit projects are already configured for a particular processor. For example, the S6E1C3 starter kit has a similar DSTC example project. In a default kit installation, the project file is here: \Documents\Cypress\FM0+ S6E1C-Series Starter Kit\Firmware\Demo Projects\s6e1c3_dstc\ARM\ s6e1c3_dstc.uvprojx You can double-click the kit project file and go straight to the instructions to Configure the PDL. (Note, however, that the starter kit projects are based on Keil µvision IDE version 5.x and will not work correctly with version 4.7.) 1. Open the KEIL project file for PDL example code. The file name is pdl_template.uvproj. In a default installation, the path to the file is: \Documents\Cypress\FM_PDL_<version>\template\ARM Double-click the file, and the Keil µvision IDE opens. What happens next depends upon which version(s) of the IDE you have installed on your machine. If you have version 4 installed, the project will launch and you can continue with the exercise. However, as noted above, these instructions use the current version 5 If on the other hand you have only version 5 installed, when it launches you will see Figure You must migrate the project file to the new version. Figure Migrate to Device pack Click Migrate to Device Pack. If you are comfortable with the µvision IDE, then use the Pack Installer to install the Cypress FM packs, and upgrade the project. If you want guidance on how to do this, please go to Appendix B, Migrating a V4 Keil Project to V5, which walks you through the process in detail. When finished, return here and continue with the next step. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 18

19 2. Specify the target processor. We will use the Release build, which should already be selected in the IDE. Figure 3-15 shows the UI for this step. (Note: If you migrated the PDL project as shown in Migrating a V4 Keil Project to V5, you have already done this.) A. Go to the Device options to choose a device. Use Project -> Options for Target Release and click the Device tab. B. Click to select ARMCM0P. In version 4.7 of the tools you choose ARM > Cortex M0+. You have specified a default Cortex-M0+. You did not pick the S6E1C32D0A specifically because it is not supported in the Keil tools at the time of this writing. You can look in the Cypress folder on the Device tab for fully-supported devices. If you find your processor listed, you don t need to manually configure memory (next step). Figure Specify the Device 3. Configure device memory. Because you selected the default Cortex-M0+ device, you must configure memory, as shown in Figure If you have not already done so, open the options window for the Release target. Use Project -> Options for Target Release. A. Click the Target tab. B. Set the IROM1 size to 0x1FFF0. C. Set the IRAM1 size to 0x4000. In version 4.7 of the tools, set both the Start and Size fields to match Figure These values match the memory configuration of the S6E1C32D0A. The linker is already configured to use the memory map you just specified. When you work with a newer device that is not fully configured in the tools, you can get the memory map information from the data sheet for the device. Alternatively (and much easier), use the Cypress Starter Kit example projects. These are already configured correctly because the kit has a known device. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 19

20 Figure Configure Device Memory 4. Clear the Conditional Assembly symbol. The assembly startup code also supports multiple FM processor families. In this step you define the symbol to control the startup code. A. Click Asm to go to the Assembler panel, shown in Figure B. Delete the contents of the Define field. Defining CORE_FM3 or CORE-FM4 sets up additional IRQs and IRQ handlers on those processors. There is no define necessary for FM0+. Examine startup_fm.s to see how this works. Figure Clear the Conditional Assembly Symbol FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 20

21 5. Set the debugger options. In this step you configure the project to use the CMSIS-DAP debugger as shown in Figure A. Click Debug to go to the Debugger options. B. Set Use to CMSIS-DAP Debugger. The initialization file should be empty. In version 4.7 of the tools, you must also click the Settings button to configure the CMSIS-DAP connection. In the settings window, set the SWJ Port to SW. This is handled automatically by the project migration to version 5. Figure Set the Debugger 6. Install the flash loader file in the Keil tools. Because you selected the default Cortex-M0+ device, rather than the S6E1C3D0A specifically, you should ensure that the Keil IDE has the required flash loader file available. You will not be able to configure the flash loading process or successfully run the code unless the required file is present in the Keil installation. In a default installation, the path and file you need is here: \Documents\Cypress\FM_PDL_<version>\template\ARM\flashloader\ S6E1C32X0.FLM Copy this file to the correct place in the Keil tools. For version 5, the path is: <Installation-Path>\Keil_v5\ARM\Flash In version 4.7 tools, the Keil installation path is: <Installation-Path>\Keil\ARM\Flash FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 21

22 7. Specify the flash programming tool. You can choose either the target driver or an external tool. This exercise uses the target driver. Figure 3-19 shows the UI for this step. A. Click the Utilities tab. B. Confirm that Use Debug Driver is enabled. In version 4.7 of the tools you click to enable this. It is already enabled if you migrated to version 5. C. Click Settings for the Use Target Driver for Flash Programming. The Cortex-M Target Driver Setup dialog appears, which you will use in the next step. Figure Specify the Flash Programming Tool 8. Configure the tools for flash programming. In this step you configure the tools to use the correct flash loader file for the S6E1C3D0A, as shown in Figure A. Confirm the flash Start and Size. For the S6E1C3D0A, flash starts at 0x (seven zeros) and size is 0x1000. B. Remove the existing flash loader file. Select New Device 256kB Flash and click Remove. It will disappear from the list. In version 4.7 of the tools there is no default flash loader file, so you don t need to do this. C. Click Add to select the correct file. D. Add the Flash Loader file. Select S6E1C32 128kB Flash and click Add, as shown in Figure E. Click OK to close the Settings dialog. F. Click OK in the Options window (Figure 3-19) to save all your changes. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 22

23 Figure Configure the Tools for Flash Programming Figure Add the Flash Loader File Configure the PDL You have configured the KEIL development environment. Now you configure the PDL itself. To do this you will: Copy example files into the PDL template project Configure the PDL for the target device Configure PDL functionality This example implements a data transfer using the software-driven Descriptor System Data Transfer Controller (DSTC) code example from the PDL. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 23

24 1. Copy example files into the PDL template project. Each PDL example includes two files: pdl_user.h enables desired PDL functionality main.c contains code to use the PDL In this step you simply copy those files into the project folder. You will explore the contents of these files in subsequent steps. A. Copy the files from the example folder. Navigate to the PDL example folder. In a default installation, the path is: \Documents\Cypress\FM_PDL_<version>\example\dstc\dstc_sw_transfer Select and copy two files, pdl_user.h and main.c. B. Paste the files into the project folder. Navigate to the PDL template project folder. In a default installation, the path is: \Documents\Cypress\FM_PDL_<version>\template\source Paste the files into this location, and replace the existing files. Backup files are in the template\source\backup folder. The PDL template project includes and uses these two files. 2. Configure the PDL for the target device. You specify the target processor in pdl_device.h. You change two #define statements in this file. A. Open pdl_device.h in the template\source folder. B. Specify the target series and package. Look for the code that defines the values of PDL_MCU_SERIES and PDL_MCU_PACKAGE. In this case, it is already correct. For any other device you would need to change these definitions. The comments in the file point you to the location where you can find the available definitions. In this example, the code at line 57 defines the series targeted in this example. #define PDL_MCU_SERIES PDL_DEVICE_SERIES_S6E1C3X The code at line 68 defines the package targeted in this example. Change the code to: #define PDL_MCU_PACKAGE C. Close the file. PDL_DEVICE_PACKAGE_S6_D Although you made no change, this is how you configure the PDL to compile code for a particular device. 3. Configure PDL functionality. You configure PDL functionality in pdl_user.h. For this example you don t need to do anything; the example code configures the PDL correctly. This step ensures you are aware of how this works and what you need to do when working on your own project. A. Open pdl_user.h. B. Examine the contents of the file. This file contains a long list of #define statements, one for each configurable feature of the PDL. To enable a feature, you define it as PDL_ON. Otherwise it is PDL_OFF. Pertinent to this example, find the line of code that sets PDL_PERIPHERAL_ENABLE_DSTC to the value PDL_ON. In this example it is at line 122 of the file. // DSTC #define PDL_PERIPHERAL_ENABLE_DSTC C. Close the file. You don t need to make any changes. PDL_ON FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 24

25 3.3.3 Build and Run the Code The code in the main() function performs the following high-level tasks. Fills a small source data buffer with values Configures the DSTC to move data from the source data buffer to the destination data buffer Triggers the data transfer Compares the destination buffer with the source buffer to confirm the operation was successful You can study the source code in main.c for details of how the code accomplishes these tasks. In this step you will execute the code and confirm success. 1. Connect the board to your PC. The precise details will vary based on your hardware. For the S6E1C3 starter kit, the board has two connectors, denoted CN3 and CN4. See Figure 3-1 if you re not sure which is which. Use the provided cable and connect to the CN3 (CMSIS-DAP) port on the board. When properly connected, LED3 Power on the board will be green. 2. Build the code. Choose Project -> Build Target. The code should compile and link with no warnings or errors. 3. Download the code and launch the debugger. Choose Debug -> Start/Stop Debug Session. The IDE downloads the code to the board and the debugger launches. Execution halts at the first line of main() as shown in Figure Figure Debugger Halted at the main() Function FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 25

26 4. Prepare to transfer data. In this step you run the code until just before the actual data transfer. A. Set a breakpoint as shown in Figure The code is: Dstc_SwTrigger(0u); // Start SW transfer with DES + 0 offset B. Choose Debug > Run. Execution halts at the breakpoint. Figure Set a Breakpoint 5. Set up the Watch window to observe the destination data buffer. A. Double-click the variable au32destinationdata. This selects just the variable name. B. Right-click the selected variable name and choose Add audestinationdata to > Watch 1. When done, the array appears in the Watch window, as shown in Figure Figure Setting Up the Watch Window for the Destination Buffer FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 26

27 6. Copy the data to the destination data buffer. In this step you execute the data transfer examine the contents of the destination data buffer. A. Choose Debug > Step Over. B. Observe the values of au32destinationdata in the Watch window, shown in Figure Figure Observe Values in the Quick Watch Window The application used the DSTC peripheral to copy the data from the source buffer to the destination buffer. You have successfully built a simple application using the PDL. You can run the rest of the code if you wish. It compares the source and destination buffers to confirm they are the same. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 27

28 A. PDL-Related Resources Table A-1 lists some resources available to you for PDL Programing. Table A-1. PDL and FM resources I Want To Evaluate the PDL Learn About Available Tools Select an FM Part Become familiar with the PDL Become familiar with processor peripherals Read this document. Resources Purchase a Starter Kit that includes the PDL and PDL-based examples. FM0+ S6E1B8-Series Starter Kit, FM0+ S6E1C3-Series Starter Kit. FM4 S6E2GM Pioneer Kit Download the PDL separately, from the FM0+, FM3, and FM4 product pages. Look on the Tools & Software tab. Visit the FM Ecosystem page. Follow the links to learn about partners who provide IDEs, compilers, debuggers, operating systems, middleware, boards, training, and more. View the introductory video FM0+ FM4 Download and review the Product Selector Guide. Read AN Differences Among FM0+, FM3, and FM4 Families Review datasheets for the FM families. Read this document. Use the PDL documentation, located in your PDL installation. Explore the PDL example code, located in your PDL installation. Explore the Starter Kit example code, for kits that use the PDL. Use the available Peripheral Manuals as a technical reference. FM0+ For FM3: o o o o FM4 FM3 PERIPHERAL MANUAL Main Part FM3 PERIPHERAL MANUAL Timer Part FM3 PERIPHERAL MANUAL Analog Macro Part FM3 PERIPHERAL MANUAL Communication Macro Part FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 28

29 B. Migrating a V4 Keil Project to V5 This appendix shows you the steps required to migrate a project file from V4 to V5 of the Keil µvision IDE. The PDL template project for the Keil µvision IDE is based on version 4 of the tools. You may have version 5 installed. In that case you need to migrate the project file. 1. Open the project file You may have already done this. The file name is pdl_template.uvproj. In a default installation, the path to the file is: \Documents\Cypress\FM_PDL_<version>\template\ARM Double-click the file, and the Keil µvision IDE opens. If you have V5 installed, when the IDE launches you are asked how you want to work with this project. Click Migrate to Device Pack as shown in Figure B-1. When you do, the Pack Installer opens. Figure B-1. Migrate to Device pack FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 29

30 2. Dismiss the Pack Installer welcome window. Figure B-2 shows the window. Read the contents, then click OK. Appendix B Migrating a V4 Keil Project to V5 Depending on your prior use of the tools and your settings choices, you may see the Pack Installer welcome window. If you do, simply click OK and dismiss the window. Figure B-2. Pack Installer Welcome Window 3. Install Cypress FM packs. See Figure B-3 for the UI in this step. A. Choose Packs > Check for Updates to ensure you get the current packs. B. In the Device column, click Cypress. The contents of the Device Specific column will update to display packs available for Cypress devices. C. Click Install for each FM pack. When done, each button changes to Up to date. D. Close the Pack Installer window. You return to the Keil IDE to take the next steps. Figure B-3. Install Cypress FM Packs FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 30

31 Appendix B Migrating a V4 Keil Project to V5 4. Migrate the PDL project to use Pack devices. When you close the Pack Installer and return to the IDE you see the window in Figure B-4. Click Yes. A window appears to select your device. Figure B-4. Migrate to Use Pack Devices 5. Select the target device. The target device is set per build. The project has two builds, named Release and Debug. So you will do this twice. These instructions use the FM0+ S6E1C-Series MCU Starter Kit, which has a Cortex M0+ processor. Navigate to and click ARMCM0P.Then click OK. This sets the device for the build target named Release in the project. See Figure B-5. Repeat this for the build target named Debug. Figure B-5. Select the Target Device Note: you are choosing a generic ARM Cortex M0+ processor as target, not a specific Cypress processor. The S6E1C is a relatively new series and at the time of this writing is not included in the FM0+ pack you just downloaded. After downloading the packs you can find fully supported processors in the Cypress folder. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 31

32 6. Complete project migration. Appendix B Migrating a V4 Keil Project to V5 After you select the target device for each build in the project, the window shown in Figure B-6 appears. Note the warning that target memory and the debugger setup may have changed. You will address these issues when you continue with the exercise. Click OK to close the window. Figure B-6. Complete Project Migration You have successfully migrated the PDL project to V5 of the Keil µvision IDE. Please return to page 19, Step 3, Configure device memory. to complete the exercise using the Keil IDE. FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 32

33 Revision History Document Revision History Document Title: FM Universal Peripheral Driver Library Quick Start Guide Document Number: Revision Issue Date Origin of Change Description of Change ** 4/4/2015 E Zhang First release *A 2/23/2016 JETT New Quick Start Guide FM Universal Peripheral Driver Library Quick Start Guide, Doc. No Rev *A 33