PSoC® Creator™ System Reference Guide cy_boot Component v2.40 Document Number: 001-73816, Rev. ** Cypress Semiconductor 198 Champion Court San Jose, CA 95134-1709 Phone (USA): 800.858.1810 Phone (Intl): 408.943.2600 http://www.cypress.com Copyrights © Cypress Semiconductor Corporation, 2011. The information contained herein is subject to change without notice. Cypress Semiconductor Corporation assumes no responsibility for the use of any circuitry other than circuitry embodied in a Cypress product. Nor does it convey or imply any license under patent or other rights. Cypress products are not warranted nor intended to be used for medical, life support, life saving, critical control or safety applications, unless pursuant to an express written agreement with Cypress. Furthermore, 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 products in life-support systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges. PSoC® is a registered trademark, and PSoC Creator™ and Programmable System-on-Chip™ are trademarks of Cypress Semiconductor Corp. All other trademarks or registered trademarks referenced herein are property of the respective corporations. Any Source Code (software and/or firmware) is owned by Cypress Semiconductor Corporation (Cypress) and is protected by and subject to worldwide patent protection (United States and foreign), United States copyright laws and international treaty provisions. Cypress hereby grants to licensee a personal, non-exclusive, non-transferable license to copy, use, modify, create derivative works of, and compile the Cypress Source Code and derivative works for the sole purpose of creating custom software and or firmware in support of licensee product to be used only in conjunction with a Cypress integrated circuit as specified in the applicable agreement. Any reproduction, modification, translation, compilation, or representation of this Source Code except as specified above is prohibited without the express written permission of Cypress. 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 life-support systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges. Use may be limited by and subject to the applicable Cypress software license agreement. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 2 Contents 1 Introduction .................................................................................................................................... 5 Conventions............................................................................................................................... 6 References ................................................................................................................................ 6 Revision History......................................................................................................................... 6 2 Standard Types and Defines ......................................................................................................... 7 Base Types ................................................................................................................................ 7 Hardware Register Types .......................................................................................................... 7 Compiler Defines ....................................................................................................................... 7 Keil 8051 Compatibility Defines................................................................................................. 8 Return Codes............................................................................................................................. 8 Interrupt Types and Macros ....................................................................................................... 9 Intrinsic Defines ......................................................................................................................... 9 Device Version Defines ............................................................................................................. 9 3 Clocking ........................................................................................................................................ 11 PSoC Creator Clocking Implementation.................................................................................. 11 APIs ......................................................................................................................................... 20 4 Power Management ..................................................................................................................... 29 Clock Configuration ................................................................................................................. 29 Wakeup Time Configuration .................................................................................................... 30 Wakeup Source Configuration................................................................................................. 30 APIs ......................................................................................................................................... 31 Instance Low Power APIs ........................................................................................................ 37 5 Interrupts....................................................................................................................................... 39 APIs ......................................................................................................................................... 39 6 Cache............................................................................................................................................. 43 PSoC 3 Cache Functionality.................................................................................................... 43 PSoC 5 Cache Functionality.................................................................................................... 43 7 Pins................................................................................................................................................ 45 APIs ......................................................................................................................................... 45 8 Register Access ........................................................................................................................... 47 APIs ......................................................................................................................................... 47 PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 3 Contents 9 DMA ............................................................................................................................................... 51 10 Flash and EEPROM...................................................................................................................... 53 APIs ......................................................................................................................................... 54 11 Bootloader System ...................................................................................................................... 59 Bootloader Component............................................................................................................ 59 Communications Component .................................................................................................. 60 Custom Bootloader Component .............................................................................................. 61 Bootloader Project Types ........................................................................................................ 63 Memory Usage ........................................................................................................................ 65 Bootloader Parameters............................................................................................................ 66 Bootloadable Parameters ........................................................................................................ 68 Bootloader API......................................................................................................................... 69 Bootloader Commands............................................................................................................ 69 Bootloader Packets ................................................................................................................. 74 Bootloader Status/Error Codes................................................................................................ 75 Bootloader Application & Code Data File Format.................................................................... 75 Bootloader Host Tool ............................................................................................................... 76 12 System Functions ........................................................................................................................ 79 General APIs............................................................................................................................ 79 CyDelay APIs........................................................................................................................... 80 13 Startup and Linking...................................................................................................................... 83 PSoC 3 .................................................................................................................................... 83 PSoC 5 .................................................................................................................................... 83 CMSIS Support (PSoC 5)........................................................................................................ 84 Preservation of Reset Status (PSoC 3 and PSoC 5)............................................................... 84 14 Watchdog Timer ........................................................................................................................... 85 APIs ......................................................................................................................................... 85 15 cy_boot Component Changes .................................................................................................... 87 Version 2.40............................................................................................................................. 87 Version 2.30............................................................................................................................. 87 Version 2.21............................................................................................................................. 88 Version 2.20............................................................................................................................. 89 Version 2.10............................................................................................................................. 89 Version 2.0............................................................................................................................... 90 PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 4 1 Introduction This System Reference Guide describes functions supplied by the PSoC Creator cy_boot component. The cy_boot component provides the system functionality for a project to give better access to chip resources. The functions are not part of the component libraries but may be used by them. You can use the function calls to reliably perform needed chip functions. The cy_boot component is unique: Included automatically into every project Only a single instance can be present No symbol representation Not present in the Component Catalog (by default) As the system component, cy_boot includes various pieces of library functionality. This guide is organized by these functions: DMA Flash Clocking Power management Start up code Various library functions Linker scripts The cy_boot component presents an API that enables user firmware to accomplish the tasks described in this guide. There are multiple major functional areas that are described separately. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 5 Introduction Conventions The following table lists the conventions used throughout this guide: Convention Usage Courier New Displays file locations and source code: C:\ …cd\icc\, user entered text Displays file names and reference documentation: sourcefile.hex Displays keyboard commands in procedures: [Enter] or [Ctrl] [C] Represents menu paths: File > New Project > Clone Displays commands, menu paths and selections, and icon names in procedures: Click the Debugger icon, and then click Next. Displays cautions or functionality unique to PSoC Creator or the PSoC device. Italics [bracketed, bold] File > New Project Bold Text in gray boxes References This guide is one of a set of documents pertaining to PSoC Creator and PSoC devices. Refer to the following other documents as needed: PSoC Creator Help PSoC Creator Component Data Sheets PSoC Creator Component Author Guide PSoC 3 and PSoC 5 Technical Reference Manual (TRM) Revision History Document Title: PSoC® Creator™ System Reference Guide, cy_boot Component v2.40 Document Number: 001-73816 Revision Date Description of Change ** 11/15/2011 New document for version 2.40 of the cy_boot component. Refer to the change section for component changes from previous versions. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 6 2 Standard Types and Defines To support the operation of the same code across multiple CPUs with multiple compilers, the cy_boot component provides types and defines that create consistent results across platforms. Base Types Type Description char8 8-bit (signed or unsigned, depending on the compiler selection for char) uint8 8-bit unsigned uint16 16-bit unsigned uint32 32-bit unsigned int8 8-bit signed int16 16-bit signed int32 32-bit signed Hardware Register Types Hardware registers typically have side effects and therefore are referenced with a volatile type. Define Description reg8 Volatile 8-bit unsigned reg16 Volatile 16-bit unsigned reg32 Volatile 32-bit unsigned Compiler Defines The compiler being used can be determined by testing for the definition of the specific compiler. For example, to test for the PSoC 3 Keil compiler: #if defined(__C51__) Define Description __C51__ Keil 8051 compiler __GNUC__ ARM GCC compiler __ARMCC_VERSION ARM Realview compiler used by Keil MDK and RVDS tool sets PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 7 Standard Types and Defines Keil 8051 Compatibility Defines The Keil 8051 compiler supports type modifiers that are specific to this platform. For other platforms these modifiers must not be present. For compatibility these types are supported by defines that map to the appropriate string when compiled for Keil and an empty string for other platforms. These defines are used to create optimized Keil 8051 code while still supporting compilation on other platforms. Define Keil Type CYBDTA bdata CYBIT bit CYCODE code CYCOMPACT compact CYDATA data CYFAR far CYIDATA idata CYLARGE large CYPDATA pdata CYREENTRANT reentrant CYSMALL small CYXDATA xdata Other Platforms uint8 Return Codes Return codes from Cypress routines are returned as an 8-bit unsigned value type: cystatus. The standard return values are: Define Description CYRET_SUCCESS Successful CYRET_UNKNOWN Unknown failure CYRET_BAD_PARAM One or more invalid parameters CYRET_INVALID_OBJECT Invalid object specified CYRET_MEMORY Memory related failure CYRET_LOCKED Resource lock failure CYRET_EMPTY No more objects available CYRET_BAD_DATA Bad data received (CRC or other error check) CYRET_STARTED Operation started, but not necessarily completed yet CYRET_FINISHED Operation completed CYRET_CANCELED Operation canceled CYRET_TIMEOUT Operation timed out CYRET_INVALID_STATE Operation not setup or is in an improper state PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 8 Standard Types and Defines Interrupt Types and Macros Types and macros provide consistent definition of interrupt service routines across compilers and platforms. Note that the macro to use is different between the function definition and the function prototype. Function definition example: CY_ISR(MyISR) { /* ISR Code here */ } Function prototype example: CY_ISR_PROTO(MyISR); Interrupt vector address type Type Description cyisraddress Interrupt vector (address of the ISR function) Intrinsic Defines Define Description CY_NOP Processor NOP instruction Device Version Defines Define Description CY_PSOC3 Any PSoC 3 Device CY_PSOC5 Any PSoC 5 Device CY_PSOC3_ES3 PSoC 3 ES3 or Later CY_PSOC3_ES2 PSoC 3 ES2 PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 9 Standard Types and Defines PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 10 3 Clocking PSoC Creator Clocking Implementation PSoC devices supported by PSoC Creator have flexible clocking capabilities. These clocking capabilities are controlled in PSoC Creator by selections within the Design-Wide Resources settings, connectivity of clocking signals on the design schematic, and API calls that can modify the clocking at runtime. This section describes how PSoC Creator maps clocks onto the device and provides guidance on clocking methodologies that are optimized for the PSoC architecture. Clock Connectivity The PSoC architecture includes flexible clock generation logic. Refer to the Technical Reference Manual for a detailed description of all the clocking sources available in a particular device. The usage of these various clocking sources can be categorized by how those clocks are connected to elements of a design. BUS_CLK This is a special clock. It is closely related to MASTER_CLK. For most designs, MASTER_CLK and BUS_CLK will be the same frequency and considered to be the same clock. These must be the highest speed clocks in the system. The CPU will be running off of BUS_CLK and all the peripherals will communicate to the CPU and DMA using BUS_CLK. When a clock is synchronized, it is synchronized to MASTER_CLK. When a pin is synchronized it is synchronized to BUS_CLK. Global Clock This is a clock that is placed on one of the global low skew digital clock lines. This also includes BUS_CLK. When a clock is created using a Clock component, it will be created as a global clock. This clock must be directly connected to a clock input or may be inverted before connection to a clock input. Global clock lines connect only to the clock input of the digital elements in PSoC. If a global clock line is connected to something other than a clock input (that is, combinatorial logic or a pin), then the signal is not sent using low skew clock lines. Routed Clock Any clock that is not a global clock is a routed clock. This includes clocks generated by logic (with the exception of a single inverter) and clocks that come in from a pin. Clock Synchronization Each clock in a PSoC device is either synchronous or asynchronous. This is in reference to BUS_CLK and MASTER_CLK. PSoC is designed to operate as a synchronous system. This was done to enable communication between the programmable logic and either the CPU or DMA. If these are not PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 11 Clocking synchronous to a common clock, then any communication requires clocking crossing circuitry. Generally, asynchronous clocking is not supported except for PLD logic that does not interact with the CPU system. Synchronous Clock Examples of synchronous clocks include: Global clock with sync to MASTER_CLK option set. This option is set by default on the Advanced tab of the Clock component Configure dialog. Clock from an input pin with the "Input Synchronized" option selected. This option is set by default on the Input tab of the Pins component Configure dialog. Clock derived combinatorially from signals that were all generated from registers that are clocked by synchronous clocks. Asynchronous Clock An asynchronous clock is any clock that is not synchronous. Some examples are: Any signal coming in from the Digital System Interconnect (DSI) other than a synchronized pin. These signals must be considered asynchronous because their timing is not guaranteed. This includes: What would normally be a global clock (if connected directly to a clock input) that is fed through logic before being used as a clock Fixed function block outputs (that is, Counter, Timer, PWM) Digital signals from the analog blocks Global clock without the sync option set Clock from an input pin with Input Synchronized not selected Clock that is combinatorially created using any asynchronous signal Making Signals Synchronous Depending on the source of the clock signal, it can be made synchronous using different methods: An asynchronous global clock can be made synchronous by checking the Sync with MASTER_CLK option in the Clock component Configure dialog (this is the default selection). A routed clock coming from a pin can be made synchronous by checking the Input Synchronized option in the Pins component Configure dialog (this is the default selection, under the Pins tab). Any signal can be made synchronous by using the Sync component and a synchronous clock as the clock signal. When synchronizing a signal: The synchronizing clock must be at least 2x the frequency of the signal being synchronized. If this rule is violated, then incoming clock edges can be missed and therefore not reflected in the resulting synchronized clock. The clock signal output will have all its transitions on the rising edge of the synchronizing clock. The clock signal output will have its edges moved from their original timing. The clock signal output will have variation in the high and low pulse widths unless the incoming clock and the synchronizing clock are directly related to each other. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 12 Clocking The following example shows two clocks that have been synchronized to BUS_CLK. Clock_1 has exactly 2x the period of BUS_CLK. Clock_2 has a period of approximately 3x the period of BUS_CLK. That results in the high and low pulse widths varying between 1 and 2 BUS_CLK periods. In both cases all transitions occur at the rising edge of BUS_CLK. Routed Clock Implementation The clocking implementation in PSoC directly connects global clock signals to the clock input of clocked digital logic. This applies to both synchronous and asynchronous clocks. Since global clocks are distributed on low skew clock lines, all clocked elements connected to the same global clock will be clocked at the same time. Routed clocks are distributed using the general digital routing fabric. This results in the clock arriving at each destination at different times. If that clock signal was used directly as the clock, then it would force the clock to be considered an asynchronous clock. This is because it cannot be guaranteed to transition at the rising edge of BUS_CLK. This can also result in circuit failures if the output of a register clocked by an early arriving clock is used by a register clocked by a late arriving version of the same clock. Under some circumstances, PSoC Creator can transform a routed clock circuit into a circuit that uses a global clock. If all the sources of a routed clock can be traced back to the output of registers that are clocked by common global clocks, then the circuit is transformed automatically by PSoC Creator. The cases where this is possible are: All signals are derived from the same global clock. This global clock can be asynchronous or synchronous. All signals are derived from more than one synchronous global clock. In this case, the common global clock is BUS_CLK. The clocking implementation in PSoC includes a built-in edge detection circuit that is used in this transformation. This does not use PLD resources to implement. The following shows the logical implementation and the resulting clock timing diagram. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 13 Clocking This diagram shows that the resulting clock occurs synchronous to the global clock on the first clock after a rising edge of the routed clock. When analyzing the design to determine the source of a routed clock, another routed clock that was transformed may be encountered. In that case, the global clock used in that transformation is considered the source clock for that signal. The clock transformation used for every routed clock is reported in the report file. This file is located in the Workspace Explorer under the Results tab after a successful build. The details are shown under the "Initial Mapping" heading. Each routed clock will be shown with the "Effective Clock" and the "Enable Signal". The "Effective Clock" is the global clock that is used and the "Enable Signal" is the routed clock that is edge detected and used as the enable for that clock. Example with a Divided Clock A simple divided clock circuit can be used to observe how this transformation is done. The following circuit clocks the first flip-flop (cydff_1) with a global clock. This generates a clock that is divided by 2 in frequency. That signal is used as a routed clock that clocks the next flip-flop (cydff_2). The report file indicates that one global clock has been used and that the single routed clock has been transformed using the global clock as the effective clock. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 14 Clocking The resulting signals generated by this circuit are as follows. It may appear that the Div4 signal is generated by the falling edge of the Div2 signal. This is not the case. The Div4 signal is generated on the first Clock_1 rising edge following a rising edge on Div2. Example with a Clock from a Pin In the following circuit, a clock is brought in on a pin with synchronization turned on. Since synchronization of pins is done with BUS_CLK, the transformed circuit uses BUS_CLK as the Effective Clock and uses the rising edge of the pin as the Enable Signal. If input synchronization was not enabled at the pin, there would not be a global clock to use to transform the routed clock, and the routed clock would be used directly. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 15 Clocking Example with Multiple Clock Sources In this example, the routed clock is derived from flip-flops that are clocked by two different clocks. Both of these clocks are synchronous, so BUS_CLK is the common global clock that becomes the Effective Clock. If either of these clocks had been asynchronous, then the routed clock would have been used directly. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 16 Clocking Overriding Routed Clock Transformations The automatic transformation that PSoC Creator performs on routed clocks is generally the implementation that should be used. There is however a method to force the routed clock to be used directly. The UDBClkEn component configured in Async mode will force the clock used to be the routed clock, as shown in the following circuit. Using Asynchronous Clocks Asynchronous clocks can be used with PLD logic. However, they are not automatically supported by control registers, status registers and datapath elements because of the interaction with the CPU those elements have. Most Cypress library components will only work with synchronous clocks. They specifically force the insertion of a synchronizer automatically if the clock provided is asynchronous. Components that are designed to work with asynchronous clocks such as the SPI Slave will specifically describe how they handle clocking in their datasheet. If an asynchronous clock is connected directly to something other than PLD logic, then a Design Rule Check (DRC) error is generated. For example, if an asynchronous pin is connected to a control register clock, a DRC error is generated. As stated in the error message, the error can be removed by using a UDBClkEn component in async mode. That won’t remove the underlying synchronization issue, but it will allow the design to override the error if the design has handled synchronization in some other way. Clock Crossing Multiple clock domains are commonly needed in a design. Often these multiple domains do not interact and therefore clocking crossings do not occur. In the case where signals generated in one clock domain need to be used in another clock domain, special care must be taken. There is the case where the two clock domains are asynchronous from each other and the case where both clock domains are synchronous to BUS_CLK. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 17 Clocking When both clocks are synchronous to BUS_CLK, signals from the slower clock domain can be freely used in the other clock domain. In the other direction, care must be taken that the signals from the faster clock domain are active for a long enough period that they will be sampled by the slower clock domain. In both directions the timing constraints that must be met are based on the speed of BUS_CLK not the speed of either of the clock domains. The only guarantee between the clock domains is that their edges will always occur on a rising edge of BUS_CLK. That means that the rising edges of the two clock domains can be as close as a single BUS_CLK cycle apart. This is true even when the clock domains are multiples of each other, since their clock dividers are not necessarily aligned. If combinatorially logic exists between the two clock domains, a flip-flop may need to be inserted to keep from limiting the frequency of BUS_CLK operation. By inserting the flip-flop, the crossing from one clock domain to the other is a direct flip-flop to flip-flop path. When the clock domains are unrelated to each other, a synchronizer must be used between the clock domains. The Sync component can be used to implement the synchronization function. It should be clocked by the destination clock domain. The Sync component is implemented using a special mode of the status register that implements a double synchronizer. The input signal must have a pulse width of at least the period of the sampling clock. The exact delay to go through the synchronizer will vary depending on the alignment of the incoming signal to the synchronizing clock. This can vary from just over one clock period to just over two clock periods. If multiple signals are being synchronized, the time difference between two signals entering the synchronizer and those same two signals at the output can change by as much as one clock period, depending on when each is successfully sampled by the synchronizer. Gated Clocks Global clocks should not be used for anything other than directly clocking a circuit. If a global clock is used for logic functionality, the signal is routed using an entirely different path without guaranteed timing. A circuit such as the following should be avoided since timing analysis cannot be performed. This circuit is implemented with a routed clock, has no timing analysis support, and is prone to the generation of glitches on the clock signal when the clock is enabled and disabled. The following circuit implements the equivalent function and is supported by timing analysis, only uses global clocks, and has no reliability issues. This circuit does not gate the clock, but instead logically enables the clocking of new data or maintains the current data. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 18 Clocking If access to a clock is needed, for example to generate a clock to send to a pin, then a 2x clock should be used to clock a toggle flip-flop. The output of that flip-flop can then be used with the associated timing analysis available. Fixed-Function Clocking On the schematic, the clock signals sent to fixed-function peripherals and to UDB-based peripherals appear to be the same clock. However, the timing relationship between the clock signals as they arrive at these different peripheral types is not guaranteed. Additionally the routing delay for the data signals is not guaranteed. Therefore when fixed-function peripherals are connected to signals in the UDB array, the signals must be synchronized as shown in the following example. No timing assumptions should be made about signals coming from fixed-function peripherals. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 19 Clocking APIs uint8 CyPLL_OUT_Start(uint8 wait) Description: Enables the PLL. Optionally waits for it to become stable. Waits at least 250 us or until it is detected that the PLL is stable. Parameters: wait: 0: Return immediately after configuration 1: Wait for PLL lock or timeout Return Value: Status CYRET_SUCCESS - Completed successfully CYRET_TIMEOUT - Timeout occurred without detecting a stable clock. If the input source of the clock is jittery, then the lock indication may not occur. However, after the timeout has expired the generated PLL clock can still be used. Side Effects and If wait is enabled: Restrictions: Uses the Fast Time Wheel to time the wait. Any other use of the Fast Time Wheel will be stopped during the period of this function and then restored. Uses the 100 KHz ILO. If not enabled, this function will enable the 100 KHz ILO for the period of this function. No changes to the setup of the ILO, Fast Time Wheel, Central Time Wheel or Once Per Second interrupt may be made by interrupt routines during the period of this function. The current operation of the ILO, Central Time Wheel and Once Per Second interrupt are maintained during the operation of this function provided the reading of the Power Manager Interrupt Status Register is only done using the CyPMReadStatus() function. void CyPLL_OUT_Stop() Description: Disables the PLL. Parameters: None Return Value: None void CyPLL_OUT_SetPQ(uint8 P, uint8 Q, uint8 current) Description: Sets the P and Q dividers and the charge pump current. The Frequency Out will be P/Q * Frequency In. The PLL must be disabled before calling this function. Parameters: P: Valid range [4 - 255] Q: Valid range [1 - 16]. Input Frequency / Q must be in the range of 1 MHz to 3 MHz. current: Valid range [1 - 7]. Charge pump current in uA. Recommendation of 2uA for output frequencies of 67 MHz or less and 3 uA for higher output frequencies. Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 20 Clocking void CyPLL_OUT_SetSource(uint8 source) Description: Sets the input clock source to the PLL. The PLL must be disabled before calling this function. Parameters: source: One of the three available PLL clock sources Value Define Source 0 CY_PLL_SOURCE_IMO IMO 1 CY_PLL_SOURCE_XTAL MHz Crystal 2 CY_PLL_SOURCE_DSI DSI Return Value: None void CyIMO_Start(uint8 wait) Description: Enables the IMO. Optionally waits at least 6us for it to settle. Parameters: wait: 0: Return immediately after configuration 1: Wait for at least 6us for the IMO to settle Return Value: None Side Effects and If wait is enabled: Restrictions: Uses the Fast Time Wheel to time the wait. Any other use of the Fast Time Wheel will be stopped during the period of this function and then restored. Uses the 100 KHz ILO. If not enabled, this function will enable the 100 KHz ILO for the period of this function. No changes to the setup of the ILO, Fast Time Wheel, Central Time Wheel or Once Per Second interrupt may be made by interrupt routines during the period of this function. The current operation of the ILO, Central Time Wheel and Once Per Second interrupt are maintained during the operation of this function provided the reading of the Power Manager Interrupt Status Register is only done using the CyPMReadStatus() function. void CyIMO_Stop() Description: Disables the IMO. Parameters: None Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 21 Clocking void CyIMO_SetFreq(uint8 freq) Description: Sets the frequency of the IMO. Changes may be made while the IMO is running. When the USB setting is chosen, the USB clock locking circuit is enabled. Otherwise this circuit is disabled. The USB block must be powered before selecting the USB setting. If the IMO is currently driving the Master clock, then the Flash wait states must be set appropriately before making this change by using CyFlash_SetWaitCycles(). Parameters: freq: Frequency of IMO operation Return Value: Value Define Frequency 0 CY_IMO_FREQ_3MHZ 3 MHz 1 CY_IMO_FREQ_6MHZ 6 MHz 2 CY_IMO_FREQ_12MHZ 12 MHz 3 CY_IMO_FREQ_24MHZ 24 MHz 4 CY_IMO_FREQ_48MHZ 48 MHz 5 CY_IMO_FREQ_62MHZ 62.6 MHz 6 CY_IMO_FREQ_74MHZ 74.7 MHz (PSoC 5) 8 CY_IMO_FREQ_USB 24 MHz (Trimmed for USB operation) None void CyIMO_SetSource(uint8 source) Description: Sets the source of the clock output from the IMO block. The output from the IMO is by default the IMO itself. Optionally the MHz Crystal or a DSI input can be the source of the IMO output instead. If the IMO is currently driving the Master clock, then the Flash wait states must be set appropriately before making this change by using CyFlash_SetWaitCycles(). Parameters: source: One of the three available IMO output sources Value Define Source 0 CY_IMO_SOURCE_IMO IMO 1 CY_IMO_SOURCE_XTAL MHz Crystal 2 CY_IMO_SOURCE_DSI DSI Return Value: None void CyIMO_EnableDoubler() Description: Enables the IMO doubler. The 2x frequency clock is used to convert a 24 MHz input to a 48 MHz output for use by the USB block. Parameters: None Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 22 Clocking void CyIMO_DisableDoubler() Description: Disables the IMO doubler. Parameters: None Return Value: None void CyMasterClk_SetSource(uint8 source) Description: Sets the source of the master clock. The current source and the new source must both be running and stable before calling this function. The Flash wait states must be set appropriately before making this change by using CyFlash_SetWaitCycles(). Parameters: source: One of the four available Master clock sources Value Define Source 0 CY_MASTER_SOURCE_IMO IMO 1 CY_MASTER_SOURCE_PLL PLL 2 CY_MASTER_SOURCE_XTAL MHz Crystal 3 CY_MASTER_SOURCE_DSI DSI Return Value: None void CyMasterClk_SetDivider(uint8 divider) Description: Sets the divider value used to generate Master Clock. The Flash wait states must be set appropriately before making this change by using CyFlash_SetWaitCycles(). Parameters: divider: Valid range [0-255]. The clock will be divided by this value + 1. For example to divide by 2 this parameter should be set to 1. Return Value: None void CyBusClk_SetDivider(uint16 divider) Description: Sets the divider value used to generate Bus Clock. The Flash wait states must be set appropriately before making this change by using CyFlash_SetWaitCycles(). Parameters: divider: Valid range [0-65535]. The clock will be divided by this value + 1. For example to divide by 2 this parameter should be set to 1. Return Value: None void CyCpuClk_SetDivider(uint8 divider) Description: Sets the divider value used to generate the CPU Clock. Applies to PSoC 3 only. Parameters: divider: Valid range [0-15]. The clock will be divided by this value + 1. For example to divide by 2 this parameter should be set to 1. Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 23 Clocking void CyUsbClk_SetSource(uint8 source) Description: Sets the source of the USB clock. Parameters: source: One of the four available USB clock sources Value Define Source 0 CY_USB_SOURCE_IMO2X IMO 2x 1 CY_USB_SOURCE_IMO IMO 2 CY_USB_SOURCE_PLL PLL 3 CY_USB_SOURCE_DSI DSI Return Value: None void CyILO_Start1K() Description: Enables the ILO 1 KHz oscillator. Note The ILO 1 KHz oscillator is always enabled by default, regardless of the selection in the Clock Editor. Therefore, this API is only needed if the oscillator was turned off manually. Parameters: None Return Value: None void CyILO_Stop1K() Description: Disables the ILO 1 KHz oscillator. Note The ILO 1 KHz oscillator must be enabled if Sleep or Hibernate low power mode APIs are expected to be used. For more information, refer to the Power Management section of this document. Parameters: None Return Value: None void CyILO_Start100K() Description: Enables the ILO 100 KHz oscillator. Parameters: None Return Value: None void CyILO_Stop100K() Description: Disables the ILO 100 KHz oscillator. Parameters: None Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 24 Clocking void CyILO_Enable33K() Description: Enables the ILO 33 KHz divider. Note The 33 KHz clock is generated from the 100 KHz oscillator, so it must also be running in order to generate the 33 KHz output. Parameters: None Return Value: None void CyILO_Disable33K() Description: Disables the ILO 33 KHz divider. Note that the 33 KHz clock is generated from the 100 KHz oscillator, but this API does not disable the 100 KHz clock. Parameters: None Return Value: None void CyILO_SetSource(uint8 source) Description: Sets the source of the clock output from the ILO block. Parameters: source: One of the three available ILO output sources Value Define Source 0 CY_ILO_SOURCE_100K ILO 100 KHz 1 CY_ILO_SOURCE_33K ILO 33 KHz 2 CY_ILO_SOURCE_1K ILO 1 KHz Return Value: None uint8 CyILO_SetPowerMode(uint8 mode) Description: Sets the power mode used by the ILO during power down. Allows for lower power down power usage resulting in a slower startup time. Parameters: mode: Value Define Description 0 CY_ILO_FAST_START Faster start-up, internal bias left on when powered down. 1 CY_ILO_SLOW_START Slower start-up, internal bias off when powered down. Return Value: Previous power mode void CyXTAL_32KHZ_Start() Description: Enables the 32 KHz Crystal Oscillator. Parameters: None Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 25 Clocking void CyXTAL_32KHZ_Stop() Description: Disables the 32 KHz Crystal Oscillator. Parameters: None Return Value: None uint8 CyXTAL_32KHZ_ReadStatus() Description: Reads the two status bits for the 32 KHz oscillator. Parameters: None Return Value: Status Value Define Source 0x20 CY_XTAL32K_ANA_STAT Analog measurement 1: Stable 0: Not stable 0x10 CY_XTAL32K_DIG_STAT Digital measurement (Requires the 33 KHz ILO to make this measurement) 1: Stable 0: Not stable uint8 CyXTAL_32KHZ_SetPowerMode(uint8 mode) Description: Sets the power mode for the 32 KHz oscillator used during sleep mode. Allows for lower power during sleep when there are fewer sources of noise. During active mode the oscillator is always run in high power mode. Parameters: mode: 0: High power mode 1: Low power mode during sleep Return Value: Previous power mode PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 26 Clocking uint8 CyXTAL_Start(uint8 wait) Description: Enables the MHz crystal. Waits until the XERR bit is low (no error) for 1 ms or until the number of milliseconds specified by the wait parameter has expired. Parameters: wait: Valid range [0-255]. This is the timeout value in milliseconds. The appropriate value is crystal specific. Return Value: Status CYRET_SUCCESS - Completed successfully CYRET_TIMEOUT - Timeout occurred without detecting a low value on XERR. Side Effects and If wait is enabled (non-zero wait): Restrictions: Uses the Fast Time Wheel to time the wait. Any other use of the Fast Time Wheel will be stopped during the period of this function and then restored. Uses the 100 KHz ILO. If not enabled, this function will enable the 100 KHz ILO for the period of this function. No changes to the setup of the ILO, Fast Time Wheel, Central Time Wheel or Once Per Second interrupt may be made by interrupt routines during the period of this function. The current operation of the ILO, Central Time Wheel and Once Per Second interrupt are maintained during the operation of this function provided the reading of the Power Manager Interrupt Status Register is only done using the CyPMReadStatus() function. void CyXTAL_Stop() Description: Disables the megahertz crystal oscillator. Parameters: None Return Value: None void CyXTAL_EnableErrStatus() Description: Enables the generation of the XERR status bit for the megahertz crystal. Parameters: None Return Value: None void CyXTAL_DisableErrStatus() Description: Disables the generation of the XERR status bit for the megahertz crystal. Parameters: None Return Value: None uint8 CyXTAL_ReadStatus() Description: Reads the XERR status bit for the megahertz crystal. This status bit is a sticky clear on read value. Parameters: None Return Value: Status: 0: No error, 1: Error PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 27 Clocking void CyXTAL_EnableFaultRecovery() Description: Enables the fault recovery circuit which will switch to the IMO in the case of a fault in the megahertz crystal circuit. The crystal must be up and running with the XERR bit at 0, before calling this function to prevent immediate fault switchover. Parameters: None Return Value: None void CyXTAL_DisableFaultRecovery() Description: Disables the fault recovery circuit which will switch to the IMO in the case of a fault in the megahertz crystal circuit. Parameters: None Return Value: None void CyXTAL_SetStartup(uint8 setting) Description: Sets the startup settings for the crystal. Parameters: setting: Valid range [0-31]. Value is dependent on the frequency and quality of the crystal being used. Refer to the TRM for appropriate values for a specific crystal. Return Value: None void CyXTAL_SetFbVoltage(uint8 setting) Description: For PSoC 3 ES3 devices only, this function sets the feedback reference voltage to use for the crystal circuit. Parameters: setting: Valid range [0-15]. Refer to the TRM for details on the mapping of the setting value to specific voltages. Return Value: None Side Effects and The feedback reference voltage must be greater than the watchdog reference Restrictions: voltage. void CyXTAL_SetWdVoltage(uint8 setting) Description: For PSoC 3 ES3 devices only, this function sets the reference voltage used by the watchdog to detect a failure in the crystal circuit. Parameters: setting: Valid range [0-7]. Refer to the TRM for details on the mapping of the setting value to specific voltages. Return Value: None Side Effects and The feedback reference voltage must be greater than the watchdog reference Restrictions: voltage. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 28 4 Power Management There is a full range of power modes supported by PSoC devices to control power consumption and the amount of available resources. Both PSoC 3 and PSoC 5 devices support the following power modes (in order of high to low power consumption): Active, Alternate Active, Sleep, and Hibernate. Note PSoC 5 will not go into low power modes while the debugger is running. Note For PSoC 3 and PSoC 5, the power manager will not put the device into a low power state if the system performance controller (SPC) is executing a command. The device will go into low power mode after the SPC completes command execution. The IMO value must be 12 MHz before entering Sleep and Hibernate modes. The IMO frequency is set to 12 MHz just before entering the specified low power mode (without correcting the number of wait cycles for the flash). The IMO frequency is restored immediately on wakeup. All pending interrupts should be cleared before the device is put into low power mode, even if it is masked. Clock Configuration There are a few device configuration requirements for proper low power mode entry and wakeup. The clock system should be prepared before entering Sleep and Hibernate mode to ensure that it will switch between Active modes and low power modes as expected. The CyPmSaveClocks() and CyPmRestoreClocks() functions are responsible for preparing clock configuration before entering low power mode and after waking up to Active mode, respectively. In general, CyPmSaveClocks() saves the configuration and sets the requirements for low power mode entry. CyPmRestoreClocks() restores the clock configuration to its original state. The IMO is required to be the source for the Master clock. So, the IMO clock value is set corresponding to the "Enable Fast IMO During Startup" option on the Design-Wide Resources System Editor. If this option is enabled, the IMO clock frequency is set to 48 MHz; otherwise, is set to 12 MHz. Note The IMO clock frequency is always set to 12 MHz on PSoC 5. The PLL and MHz ECO are turned off when the Master clock is sourced by IMO. The Bus and Master clock dividers are set to a divide-by-one value and the new value of flash wait cycles is set to match the new value of the CPU frequency. Refer to the description of the CyFlash_SetWaitCycles() function for more information. The 1 KHz ILO must be enabled for all devices for correct operation in Sleep and Hibernate low power modes. For PSoC 3 ES3 devices, the 1 KHz ILO is used to measure the Hibernate/Sleep regulator settling time after a reset. During this time, the system ignores requests to enter these modes. The holdoff delay is measured using rising edges of the 1 kHz ILO. The terminal count is set by the Sleep Regulator Trim Register. Caution Do not modify this register. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 29 Power Management For PSoC 5 devices, an interrupt is required for the CPU to wake up. The Power Management implementation assumes that wakeup time is configured with a separate component (component-based wakeup time configuration) for an interrupt to be issued on terminal count. For more information, refer to the following section. Wakeup Time Configuration There are three timers that can wake up a device from low power mode: Central Time Wheel (CTW), Fast Timer Wheel (FTW) and one pulse per second (One PPS). Refer to the device TRM and datasheet for more information on these timers. There are two ways of configuring wakeup time: Parameter-based wakeup time configuration is done by calling the CyPmSleep() and CyPmAltAct() functions with desired parameters. This configuration method is available only for the PSoC 3 devices. Component-based wakeup time configuration. The CTW wakeup interval is configured with the Sleep Timer component. The one second interval is configured with the RTC component. There is no wakeup time configuration available for the Hibernate mode. It is important to keep in mind that it is only guaranteed that the first CTW and FTW intervals will be less than specified. To make subsequent intervals to have nominal values, the corresponding timer is enabled by the CyPmSleep() and CyPmAltAct() functions, and the timer left enabled. Note that some APIs can also use this timer. This can cause the timer to always be enabled (the timer interval can be changed only if the corresponding timer is disabled) before low power mode entry and hence the wakeup interval will always be less than expected. The CyPmReadStatus() function must be called just after wakeup with a corresponding parameter (for example, with CY_PM_CTW_INT if the device is configured to wake up on CTW) to clear interrupt status bits. When CTW is used as a wakeup timer, the CyPmReadStatus() function must always be called (when wakeup is configured in a parameter or component based method) after wakeup to clear the CTW interrupt status bit. It is required for this function to be called within 1 ms (1 clock cycle of the ILO) after the CTW event occurred. Wakeup Source Configuration For the PSoC 3 ES3 device, you can configure which wakeup source may wake up the device from Alternate Active and Sleep low power modes. For PSoC 5 and PSoC 3 ES2 silicon, the wakeup source is not selectable. In this case, the wakeup source argument is ignored and any of the available wakeup sources will wake the device. For PSoC 5 silicon, the CTW is the only supported wakeup source from sleep. PSoC 3 Alternate Active Mode Specific Issues Any interrupt, whether it is enabled at the interrupt controller or not, will wake the device from Alternate Active power mode. The edge detector is also bypassed, so the wakeup source is always level triggered. Directly connected DMA interrupts will not wake from this mode. They must be routed through the DSI in order to generate a wakeup condition. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 30 Power Management APIs void CyPmSaveClocks() Description: This function is called in preparation for entering sleep or hibernate low power modes. Saves all state of the clocking system that doesn’t persist during sleep/hibernate or that needs to be altered in preparation for sleep/hibernate. Shuts down all the digital and analog clock dividers. Switches the master clock over to the IMO and shuts down the PLL and MHz Crystal. The IMO frequency is set to either 12 MHz or 48 MHz to match the Design-Wide Resources System Editor "Enable Fast IMO During Startup" setting. The ILO and 32 KHz oscillators are not impacted. The current Flash wait state setting is saved and the Flash wait state setting is set for the current IMO speed. Note If the Master Clock source is routed through the DSI inputs, then it must be set manually to another source before using the CyPmSaveClocks() / CyPmRestoreClocks() functions. Parameters: None Return Value: None Side Effects and All peripheral clocks will be off after this API method call. Restrictions void CyPmRestoreClocks() Description: Restores any state that was preserved by the last call to CyPmSaveClocks. The Flash wait state setting is also restored. Note If the Master Clock source is routed through the DSI inputs, then it must be set manually to another source before using the CyPmSaveClocks() / CyPmRestoreClocks() functions. PSoC 3 ES3: The merge region could be used to process state when the megahertz crystal is not ready after the hold-off timeout. PSoC 5: The megahertz crystal is given up to 130 ms to stabilize. Its readiness is not verified after the hold-off timeout. Parameters: None Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 31 Power Management void CyPmAltAct(uint16 wakeupTime, uint16 wakeupSource) Description: Puts the part into the Alternate Active (Standby) state. The Alternate Active state can allow for any of the capabilities of the device to be active, but the operation of this function is dependent on the CPU being disabled during the Alternate Active state. The configuration code and the component APIs will configure the template for the Alternate Active state to be the same as the Active state with the exception that the CPU will be disabled during Alternate Active. Note Before calling this function, you must manually configure the power mode of the source clocks for the timer that is used as the wakeup timer. PSoC 3: Before switching to Alternate Active, if a wakeupTime other than NONE is specified, then the appropriate timer state is configured as specified with the interrupt for that timer disabled. The wakeup source will be the combination of the values specified in the wakeupSource and any timer specified in the wakeupTime argument. Once the wakeup condition is satisfied, then all saved state is restored and the function returns in the Active state. Note If the wakeupTime is made with a different value, the period before the wakeup occurs can be significantly shorter than the specified time. If the next call is made with the same wakeupTime value, then the wakeup will occur the specified period after the previous wakeup occurred. If a wakeupTime other than NONE is specified, then upon exit the state of the specified timer will be left as specified by wakeupTime with the timer enabled and the interrupt disabled. If the CTW, FTW or One PPS is already configured for wakeup, for example with the SleepTimer or RTC components, then specify NONE for the wakeupTime and include the appropriate source for wakeupSource. PSoC 5: Neither parameter is used for PSoC 5. The device will go into Alternate Active mode until an enabled interrupt occurs. Parameters: wakeupTime: Specifies a timer wakeup source and the frequency of that source. For PSoC 5 this parameter is ignored. Value Define Time 0 PM_ALT_ACT_TIME_NONE None 1 PM_ALT_ACT_TIME_ONE_PPS One PPS: 1 second 2 PM_ALT_ACT_TIME_CTW_2MS CTW: 2 ms 3 PM_ALT_ACT_TIME_CTW_4MS CTW: 4 ms 4 PM_ALT_ACT_TIME_CTW_8MS CTW: 8 ms 5 PM_ALT_ACT_TIME_CTW_16MS CTW: 16 ms 6 PM_ALT_ACT_TIME_CTW_32MS CTW: 32 ms 7 PM_ALT_ACT_TIME_CTW_64MS CTW: 64 ms 8 PM_ALT_ACT_TIME_CTW_128MS CTW: 128 ms 9 PM_ALT_ACT_TIME_CTW_256MS CTW: 256 ms 10 PM_ALT_ACT_TIME_CTW_512MS CTW: 512 ms 11 PM_ALT_ACT_TIME_CTW_1024MS CTW: 1024 ms 12 PM_ALT_ACT_TIME_CTW_2048MS CTW: 2048 ms 13 PM_ALT_ACT_TIME_CTW_4096MS CTW: 4096 ms PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 32 Power Management CyPmAltAct (Continued) Parameters: wakeupTime (continued): Specifies a timer wakeup source and the frequency of that source. For PSoC 5 this parameter is ignored. Value Define Time 14 - 269 PM_ALT_ACT_TIME_FTW(1-256) FTW: 10 µs to 2.56 ms The PM_ALT_ACT_TIME_FTW() macro takes an argument that specifies how many increments of 10 µs to delay. For PSoC 3 ES2, the valid range of values is 1 to 32. For PSoC 3 ES3 silicon the valid range of values is 1 to 256. wakeupSource: Specifies a bitwise mask of wakeup sources. In addition, if a wakeupTime has been specified, the associated timer will be included as a wakeup source. The wakeup source configuration is restored before function exit. For PSoC 5 this parameter is ignored. Value Define Source 0 PM_ALT_ACT_SRC_NONE None 1 PM_ALT_ACT_SRC_COMPARATOR0 Comparator 0 2 PM_ALT_ACT_SRC_COMPARATOR1 Comparator 1 4 PM_ALT_ACT_SRC_COMPARATOR2 Comparator 2 8 PM_ALT_ACT_SRC_COMPARATOR3 Comparator 3 16 PM_ALT_ACT_SRC_INTERRUPT Interrupt 64 PM_ALT_ACT_SRC_PICU PICU 128 PM_ALT_ACT_SRC_I2C I2C 512 PM_ALT_ACT_SRC_BOOSTCONVERTER Boost Converter 1024 PM_ALT_ACT_SRC_FTW Fast Time Wheel 2048* PM_ALT_ACT_SRC_CTW Central Time Wheel 2048* PM_ALT_ACT_SRC_ONE_PPS One PPS 4096 PM_ALT_ACT_SRC_LCD LCD Note CTW and One PPS wakeup signals are in the same mask bit. When specifying a Comparator as the wakeupSource, use an instance specific define that will track with the specific comparator for that instance. As an example, for a Comparator instance named "MyComp" the value to OR into the mask is: MyComp_ctComp__CMP_MASK. When CTW, FTW, or One PPS is used as a wakeup source, the CyPmReadStatus function must be called upon wakeup, with the corresponding parameter. Refer to the CyPmReadStatus API for more information. Return Value: None Side Effects and For PSoC 3 ES2 and PSoC 5 silicon, the wakeup source is not selectable. In this Restrictions: case the wakeupSource argument is ignored and any of the available wakeup sources will wake the device. If a wakeupTime other than NONE is specified, then upon exit the state of the specified timer will be left as specified by wakeupTime with the timer enabled and the interrupt disabled. Also, the ILO 1 KHz (if CTW timer is used as wakeup time) or ILO 100 KHz (if FTW timer is used as wakeup time) will be left started. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 33 Power Management void CyPmSleep(uint8 wakeupTime, uint16 wakeupSource) Description: Puts the part into the Sleep state. Note Before calling this function, you must manually configure the power mode of the source clocks for the timer that is used as wakeup timer. PSoC 3: Before switching to Sleep, if a wakeupTime other than NONE is specified, then the appropriate timer state is configured as specified with the interrupt for that timer disabled. The wakeup source will be the combination of the values specified in the wakeupSource and any timer specified in the wakeupTime argument. Once the wakeup condition is satisfied, then all saved state is restored and the function returns in the Active state. Note If the wakeupTime is made with a different value, the period before the wakeup occurs can be significantly shorter than the specified time. If the next call is made with the same wakeupTime value, then the wakeup will occur the specified period after the previous wakeup occurred. If a wakeupTime other than NONE is specified, then upon exit the state of the specified timer will be left as specified by wakeupTime with the timer enabled and the interrupt disabled. If the CTW or One PPS is already configured for wakeup, for example with the SleepTimer or RTC components, then specify NONE for the wakeupTime and include the appropriate source for wakeupSource. PSoC 5: Neither parameter to this function is used for PSoC 5. The device will go into Sleep mode until it is woken by an interrupt from the Central Time Wheel (CTW). The CTW must already be configured to generate an interrupt. It is configured using the SleepTimer component. Only the CTW can be used to wake the device from sleep mode. This function automatically disables other interrupt sources and then restores them after the device is woken by the CTW. The duration of sleep needs to be controlled so that the device doesn't wake up too soon after going to sleep or remain asleep for too long. Reliable sleep times of between 1ms and 8ms can be supported. This requirement is satisfied with CTW settings of 4, 8 or 16 ms. To control the sleep time the CTW is reset automatically just before putting the device to sleep. The resulting wakeup time is half the duration programmed into the CTW with an uncertainty of 1 ms due to the arrival time of the first ILO clock edge. For example, the setting of 4 ms will result in a sleep time between 1 ms and 2 ms. Parameters: wakeupTime: Specifies a timer wakeup source and the frequency of that source. For PSoC 5, this parameter is ignored. Value Define Time 0 PM_SLEEP_TIME_NONE None 1 PM_SLEEP_TIME_ONE_PPS One PPS: 1 second 2 PM_SLEEP_TIME_CTW_2MS CTW: 2 ms 3 PM_SLEEP_TIME_CTW_4MS CTW: 4 ms 4 PM_SLEEP_TIME_CTW_8MS CTW: 8 ms 5 PM_SLEEP_TIME_CTW_16MS CTW: 16 ms 6 PM_SLEEP_TIME_CTW_32MS CTW: 32 ms 7 PM_SLEEP_TIME_CTW_64MS CTW: 64 ms 8 PM_SLEEP_TIME_CTW_128MS CTW: 128 ms 9 PM_SLEEP_TIME_CTW_256MS CTW: 256 ms 10 PM_SLEEP_TIME_CTW_512MS CTW: 512 ms PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 34 Power Management CyPmSleep (Continued) Parameters: wakeupTime (continued) Value Define Time 11 PM_SLEEP_TIME_CTW_1024MS CTW: 1024 ms 12 PM_SLEEP_TIME_CTW_2048MS CTW: 2048 ms 13 PM_SLEEP_TIME_CTW_4096MS CTW: 4096 ms wakeupSource: Specifies a bitwise mask of wakeup sources. In addition, if a wakeupTime has been specified, the associated timer will be included as a wakeup source. The wakeup source configuration is restored before function exit. For PSoC 5 this parameter is ignored. Value Define Source 0 PM_SLEEP_SRC_NONE None 1 PM_SLEEP_SRC_COMPARATOR0 Comparator 0 2 PM_SLEEP_SRC_COMPARATOR1 Comparator 1 4 PM_SLEEP_SRC_COMPARATOR2 Comparator 2 8 PM_SLEEP_SRC_COMPARATOR3 Comparator 3 64 PM_SLEEP_SRC_PICU PICU 128 PM_SLEEP_SRC_I2C I2C 512 PM_SLEEP_SRC_BOOSTCONVERTER Boost Converter 2048* PM_SLEEP_SRC_CTW Central Time Wheel 2048* PM_SLEEP_SRC_ONE_PPS One PPS 4096 PM_SLEEP_SRC_LCD LCD Note CTW and One PPS wakeup signals are in the same mask bit. For PSoC 5, these are in a different bit (value 1024). When specifying a Comparator as the wakeupSource, use an instance specific define that will track with the specific comparator for that instance. As an example for a Comparator instance named "MyComp" the value to OR into the mask is: MyComp_ctComp__CMP_MASK. When CTW or One PPS is used as a wakeup source, the CyPmReadStatus function must be called upon wakeup, with the corresponding parameter. Refer to the CyPmReadStatus API for more information. Return Value: None Side Effects and If a wakeupTime other than NONE is specified, then upon exit the state of the Restrictions: specified timer will be left as specified by wakeupTime with the timer enabled and the interrupt disabled. Also, the ILO 1 KHz (if CTW timer is used as wake up time) will be left started. PSoC 3 ES2 silicon has a defect that causes connections to several analog resources to be unreliable when the device is placed in a low power mode. refer to the silicon errata for details. The 1 kHz ILO clock is expected to be enabled for PSoC3 ES3 silicon to measure Hibernate/Sleep regulator settling time after a reset. The hold-off delay is measured using rising edges of the 1 kHz ILO. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 35 Power Management void CyPmHibernate() Description: Puts the part into the Hibernate state. PSoC 3: Before switching to Hibernate, the current status of the PICU wakeup source bit is saved and then set. This configures the device to wake up from the PICU. Make sure you have at least one pin configured to generate a PICU interrupt. For pin Px.y, the register "PICU_INTTYPE_PICUx_INTTYPEy" controls the PICU behavior. In the TRM, this register is "PICU[0..15]_INTTYPE[0..7]." In the Pins component datasheet, this register is referred to as the IRQ option. Once the wakeup occurs, the PICU wakeup source bit is restored and the PSoC returns to the Active state. PSoC 5: The only method supported for waking up from the Hibernate state is a hardware reset of the device. PICU interrupt sources are automatically disabled by this function before putting the device into the Hibernate state. Parameters: None Return Value: None Side Effects and Applications must wait 20 µs before re-entering hibernate or sleep after waking Restrictions: up from hibernate. The 20 µs allows the sleep regulator time to stabilize before the next hibernate / sleep event occurs. The 20 µs requirement begins when the device wakes up. There is no hardware check that this requirement is met. The specified delay should be done on ISR entry. After wakeup PICU interrupt occurs, the Pin_ClearInterrupt() function (where "Pin" is the instance name of the Pins component) must be called to clear the latched pin events. This allows proper Hibernate mode entry and enables detection of future events. PSoC 3 ES2 silicon has a defect that causes connections to several analog resources to be unreliable when the device is placed in a low power mode. Refer to the silicon errata for details. The 1 kHz ILO clock is expected to be enabled for PSoC3 ES3 silicon to measure Hibernate/Sleep regulator settling time after a reset. The hold-off delay is measured using rising edges of the 1 kHz ILO. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 36 Power Management uint8 CyPmReadStatus(uint8 mask) Description: Manages the Power Manager Interrupt Status Register. This register has the interrupt status for the one pulse per second, Central Time Wheel, and Fast Time Wheel timers. This hardware register clears on read. To allow for only clearing the bits of interest and preserving the other bits, this function uses a shadow register that retains the state. This function reads the status register and ORs that value with the shadow register. That is the value that is returned. Then the bits in the mask that are set are cleared from this value and written back to the shadow register. Note You must call this function within 1 ms (1 clock cycle of the ILO) after a CTW event has occurred. Parameters: mask: Bits in the shadow register to clear Value Define Source 1 CY_PM_FTW_INT Fast Time Wheel 2 CY_PM_CTW_INT Central Time Wheel 4 CY_PM_ONEPPS_INT One Pulse Per Second Return Value: Status. Same enumerated bit values as used for the mask parameter. Instance Low Power APIs Most components have an instance-specific set of low power APIs that allow you to put the component into its low power state (sleep or hibernate). These functions are listed below generically. Refer to the individual data sheet for specific information regarding register retention information if applicable. void `=instance_name`_Sleep (void) Description: The _Sleep() function checks to see if the component is enabled and saves that state. Then it calls the _Stop() function and calls _SaveConfig() function to save the user configuration. Call the _Sleep() function before calling the CyPmSleep() or the CyPmHibernate() function. Parameters: None Return Value: None Side Effects: None void `=instance_name`_Wakeup (void) Description: The _Wakeup() function calls the _RestoreConfig() function to restore the user configuration. If the component was enabled before the _Sleep() function was called, the _Wakeup() function will re-enable the component. Parameters: None Return Value: None Side Effects: Calling the _Wakeup() function without first calling the _Sleep() or _SaveConfig() function may produce unexpected behavior. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 37 Power Management void `=instance_name`_SaveConfig(void) Description: This function saves the component configuration. This will save non-retention registers. This function will also save the current component parameter values, as defined in the Configure dialog or as modified by appropriate APIs. This function is called by the _Sleep() function. Parameters: None Return Value: None Side Effects: None void `=instance_name`_RestoreConfig(void) Description: This function restores the component configuration. This will restore non-retention registers. This function will also restore the component parameter values to what they were prior to calling the _Sleep() function. Parameters: None Return Value: None Side Effects: Calling this function without first calling the _Sleep() or _SaveConfig() function may produce unexpected behavior. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 38 5 Interrupts The APIs in this chapter apply to all architectures except as noted. Refer also to the Interrupt component datasheet for more information about interrupts. APIs CyGlobalIntEnable Description: Macro statement that enables interrupts using the global interrupt mask. CyGlobalIntDisable Description: Macro statement that disables interrupts using the global interrupt mask. uint32 CyDisableInts() Description: Disables the interrupt enable for each interrupt. Parameters: None Return Value: 32-bit mask of interrupts previously enabled void CyEnableInts(uint32 mask) Description: Enables all interrupts specified in the 32-bit mask. Parameters: mask: 32-bit mask of interrupts to enable Return Value: None Note Interrupt service routines must follow the policy that they restore the CYDEV_INTC_CSR_EN register bits and interrupt enable state (EA) to the way they were found on entry. The ISR does not need to do anything special as long as it uses properly nested CyEnterCriticalSection() and CyExitCriticalSection() function calls. void CyIntEnable(uint8 number) Description: Enables the specified interrupt number. Parameters: number: Interrupt number. Valid range: [0-31] Return Value: None Note Interrupt service routines must follow the policy that they restore the CYDEV_INTC_CSR_EN register bits and interrupt enable state (EA) to the way they were found on entry. The ISR does not need PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 39 Interrupts to do anything special as long as it uses properly nested CyEnterCriticalSection() and CyExitCriticalSection() function calls. void CyIntDisable(uint8 number) Description: Disables the specified interrupt number. Parameters: number: Interrupt number. Valid range: [0-31] Return Value: None Note Interrupt service routines must follow the policy that they restore the CYDEV_INTC_CSR_EN register bits and interrupt enable state (EA) to the way they were found on entry. The ISR does not need to do anything special as long as it uses properly nested CyEnterCriticalSection() and CyExitCriticalSection() function calls. uint8 CyIntGetState(uint8 number) Description: Gets the enable state of the specified interrupt number. Parameters: number: Interrupt number. Valid range: [0-31] Return Value: Enable status: 1 if enabled, 0 if disabled cyisraddress CyIntSetVector(uint8 number, cyisraddress address) Description: Sets the interrupt vector of the specified interrupt number. Parameters: number: Interrupt number. Valid range: [0-31] address: Pointer to an interrupt service routine Return Value: Previous interrupt vector value cyisraddress CyIntGetVector(uint8 number) Description: Gets the interrupt vector of the specified interrupt number. Parameters: number: Interrupt number. Valid range: [0-31] Return Value: Interrupt vector value cyisraddress CyIntSetSysVector(uint8 number, cyisraddress address) Description: This function applies to ARM based processors only and therefore does not apply to the PSoC 3 device. It sets the interrupt vector of the specified exception. These exceptions in the ARM architecture operate similar to user interrupts, but are specified by the system architecture of the processor. The number of each exception is fixed. Note that the numbering of these exceptions is separate from the numbering used for user interrupts. Parameters: number: Exception number. Valid range: [0-15]. address: Pointer to an interrupt service routine Return Value: Previous interrupt vector value PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 40 Interrupts cyisraddress CyIntGetSysVector(uint8 number) Description: This function applies to ARM based processors only and therefore does not apply to the PSoC 3 device. It gets the interrupt vector of the specified exception. These exceptions in the ARM architecture operate similar to user interrupts, but are specified by the system architecture of the processor. The number of each exception is fixed. Note that the numbering of these exceptions is separate from the numbering used for user interrupts. Parameters: number: Exception number. Valid range: [0-15]. Return Value: Interrupt vector value void CyIntSetPriority(uint8 number, uint8 priority) Description: Sets the priority of the specified interrupt number. Parameters: number: Interrupt number. Valid range: [0-31] priority: Interrupt priority. 0 is the highest priority. Valid range: [0-7] Return Value: None uint8 CyIntGetPriority(uint8 number) Description: Gets the priority of the specified interrupt number. Parameters: number: Interrupt number. Valid range: [0-31] Return Value: Interrupt priority void CyIntSetPending(uint8 number) Description: Forces the specified interrupt number to be pending. Parameters: number: Interrupt number. Valid range: [0-31] Return Value: None void CyIntClearPending(uint8 number) Description: Clears any pending interrupt for the specified interrupt number. Parameters: number: Interrupt number. Valid range: [0-31] Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 41 Interrupts PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 42 6 Cache PSoC 3 Cache Functionality The PSoC 3 cache is enabled by default. It can be disabled using the PSoC Creator Design-Wide Resources System Editor. There are no defines, functions or macros for cache handling for PSoC 3. PSoC 5 Cache Functionality void CyFlushCache() Description: Flushes the PSoC 5 cache by invalidating all entries. Parameters: None Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 43 Cache PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 44 7 Pins In addition to the functionality provided for pins as part of the Pins component, a library of pin macros is provided in the cypins.h file. These macros all make use of the port pin configuration register that is available for every pin on the device. The address of that register is provided in the cydevice_trm.h file. Each of these pin configuration registers is named: CYREG_PRTx_PCy where x is the port number and y is the pin number within the port. APIs uint8 CyPins_ReadPin(uint16/uint32 pinPC) Description: Reads the current value on the pin (pin state, PS). Parameters: pinPC: Port pin configuration register (uint16 PSoC 3 / uint32 PSoC 5) Return Value: Pin state 0: Logic low value Non-0: Logic high value void CyPins_SetPin(uint16/uint32 pinPC) Description: Set the output value for the pin (data register, DR) to a logic high. Note that this only has an effect for pins configured as software pins that are not driven by hardware. Parameters: pinPC: Port pin configuration register (uint16 PSoC 3 / uint32 PSoC 5) Return Value: None void CyPins_ClearPin(uint16/uint32 pinPC) Description: Clear the output value for the pin (data register, DR) to a logic low. Note that this only has an effect for pins configured as software pins that are not driven by hardware. Parameters: pinPC: Port pin configuration register (uint16 PSoC 3 / uint32 PSoC 5) Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 45 Pins void CyPins_SetPinDriveMode(uint16/uint32 pinPC, uint8 mode) Description: Sets the drive mode for the pin (DM). Parameters: pinPC: Port pin configuration register (uint16 PSoC 3 / uint32 PSoC 5) mode: Desired drive mode Define Source PIN_DM_ALG_HIZ PIN_DM_DIG_HIZ PIN_DM_RES_UP PIN_DM_RES_DWN PIN_DM_OD_LO PIN_DM_OD_HI PIN_DM_STRONG PIN_DM_RES_UPDWN Analog HiZ Digital HiZ Resistive pull up Resistive pull down Open drain - drive low Open drain - drive high Strong CMOS Output Resistive pull up/down Return Value: None uint8 CyPins_ReadPinDriveMode(uint16/uint32 pinPC) Description: Reads the drive mode for the pin (DM). Parameters: pinPC: Port pin configuration register (uint16 PSoC 3 / uint32 PSoC 5) Return Value: Current drive mode for the pin Define Source PIN_DM_ALG_HIZ PIN_DM_DIG_HIZ PIN_DM_RES_UP PIN_DM_RES_DWN PIN_DM_OD_LO PIN_DM_OD_HI PIN_DM_STRONG PIN_DM_RES_UPDWN Analog HiZ Digital HiZ Resistive pull up Resistive pull down Open drain - drive low Open drain - drive high Strong CMOS Output Resistive pull up/down void CyPins_FastSlew(uint16/uint32 pinPC) Description: Set the slew rate for the pin to fast edge rate. Note that this only applies for pins in strong output drive modes, not to resistive drive modes. Parameters: pinPC: Port pin configuration register (uint16 PSoC 3 / uint32 PSoC 5) Return Value: None void CyPins_SlowSlew(uint16/uint32 pinPC) Description: Set the slew rate for the pin to slow edge rate. Note that this only applies for pins in strong output drive modes, not to resistive drive modes. Parameters: pinPC: Port pin configuration register (uint16 PSoC 3 / uint32 PSoC 5) Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 46 8 Register Access A library of macros provides read and write access to the registers of the device. These macros are used with the defined values made available in the generated cydevice.h, cydevice_trm.h and cyfitter.h files. Access to registers should be made using these macros and not the functions that are used to implement the macros. This allows for device independent code generation. PSoC 3 is an 8-bit architecture, so the processor does not have endianness. However, the compiler for an 8-bit architecture will implement endianness. For PSoC 3, the Keil compiler implements a big endian (MSB in lowest address) ordering. The PSoC 5 processor architecture uses little endian ordering. SRAM and Flash storage in both the PSoC 3 and PSoC 5 architectures is done using the endianness of the architecture and compilers. However, the registers in both these chips are laid out in little endian order. These macros allow register accesses to match this little endian ordering. If you perform operations on multi-byte registers without using these macros, you must consider the byte ordering of the specific architecture. Examples include usage of DMA to transfer between memory and registers, as well as function calls that are passed an array of bytes in memory. The PSoC 3 is an 8-bit processor, so all accesses will be done a byte at a time. The PSoC 5 will perform accesses using the appropriate 8-, 16- and 32-bit accesses. The PSoC 5 does not require these accesses to be aligned to the width of the transaction. APIs uint8 CY_GET_REG8(uint16/uint32 reg) Description: Reads the 8-bit value from the specified register. For PSoC 3, the address must be in the lower 64 K address range. Parameters: reg: Register address (uint16 PSoC 3 / uint32 PSoC 5) Return Value: Read value void CY_SET_REG8(uint16/uint32 reg, uint8 value) Description: Writes the 8-bit value to the specified register. For PSoC 3 the address must be in the lower 64 K address range. Parameters: reg: Register address (uint16 PSoC 3 / uint32 PSoC 5) value: Value to write Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 47 Register Access uint16 CY_GET_REG16(uint16/uint32 reg) Description: Reads the 16-bit value from the specified register. This macro implements the byte swapping required for proper operation. For PSoC 3 the address must be in the lower 64 K address range. Parameters: reg: Register address (uint16 PSoC 3 / uint32 PSoC 5) Return Value: Read value void CY_SET_REG16(uint16/uint32 reg, uint16 value) Description: Writes the 16-bit value to the specified register. This macro implements the byte swapping required for proper operation. For PSoC 3 the address must be in the lower 64 K address range. Parameters: reg: Register address (uint16 PSoC 3 / uint32 PSoC 5) value: Value to write Return Value: None uint32 CY_GET_REG24(uint16/uint32 reg) Description: Reads the 24-bit value from the specified register. This macro implements the byte swapping required for proper operation. For PSoC 3 the address must be in the lower 64 K address range. Parameters: reg: Register address (uint16 PSoC 3 / uint32 PSoC 5) Return Value: Read value void CY_SET_REG24(uint16/uint32 reg, uint32 value) Description: Writes the 24-bit value to the specified register. This macro implements the byte swapping required for proper operation. For PSoC 3 the address must be in the lower 64 K address range. Parameters: reg: Register address (uint16 PSoC 3 / uint32 PSoC 5) value: Value to write Return Value: None uint32 CY_GET_REG32(uint16/uint32 reg) Description: Reads the 32-bit value from the specified register. This macro implements the byte swapping required for proper operation. For PSoC 3 the address must be in the lower 64 K address range. Parameters: reg: Register address (uint16 PSoC 3 / uint32 PSoC 5) Return Value: Read value PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 48 Register Access void CY_SET_REG32(uint16/uint32 reg, uint32 value) Description: Writes the 32-bit value to the specified register. This macro implements the byte swapping required for proper operation. For PSoC 3 the address must be in the lower 64 K address range. Parameters: reg: Register address (uint16 PSoC 3 / uint32 PSoC 5) value: Value to write Return Value: None uint8 CY_GET_XTND_REG8(uint32 reg) Description: Reads the 8-bit value from the specified register. Supports the full address space for PSoC 3, but requires more execution cycles than the standard register get function. Identical to CY_GET_REG8 for PSoC 5. Parameters: reg: Register address Return Value: Read value void CY_SET_XTND_REG8(uint32 reg, uint8 value) Description: Writes the 8-bit value to the specified register. Supports the full address space for PSoC 3, but requires more execution cycles than the standard register set function. Identical to CY_SET_REG8 for PSoC 5. Parameters: reg: Register address value: Value to write Return Value: None uint16 CY_GET_XTND_REG16(uint32 reg) Description: Reads the 16-bit value from the specified register. This macro implements the byte swapping required for proper operation. Supports the full address space for PSoC 3, but requires more execution cycles than the standard register get function. Identical to CY_GET_REG16 for PSoC 5. Parameters: reg: Register address Return Value: Read value void CY_SET_XTND_REG16(uint32 reg, uint16 value) Description: Writes the 16-bit value to the specified register. This macro implements the byte swapping required for proper operation. Supports the full address space for PSoC 3, but requires more execution cycles than the standard register set function. Identical to CY_SET_REG16 for PSoC 5. Parameters: reg: Register address value: Value to write Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 49 Register Access uint32 CY_GET_XTND_REG24(uint32 reg) Description: Reads the 24-bit value from the specified register. This macro implements the byte swapping required for proper operation. Supports the full address space for PSoC 3, but requires more execution cycles than the standard register get function. Identical to CY_GET_REG24 for PSoC 5. Parameters: reg: Register address Return Value: Read value void CY_SET_XTND_REG24(uint32 reg, uint32 value) Description: Writes the 24-bit value to the specified register. This macro implements the byte swapping required for proper operation. Supports the full address space for PSoC 3, but requires more execution cycles than the standard register set function. Identical to CY_SET_REG24 for PSoC 5. Parameters: reg: Register address value: Value to write Return Value: None uint32 CY_GET_XTND_REG32(uint32 reg) Description: Reads the 32-bit value from the specified register. This macro implements the byte swapping required for proper operation. Supports the full address space for PSoC 3, but requires more execution cycles than the standard register get function. Identical to CY_GET_REG32 for PSoC 5. Parameters: reg: Register address Return Value: Read value void CY_SET_XTND_REG32(uint32 reg, uint32 value) Description: Writes the 32-bit value to the specified register. This macro implements the byte swapping required for proper operation. Supports the full address space for PSoC 3, but requires more execution cycles than the standard register set function. Identical to CY_SET_REG32 for PSoC 5. Parameters: reg: Register address value: Value to write Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 50 9 DMA The DMA files provide the API functions for the DMA controller, DMA channels and Transfer Descriptors. This API is the library version, not the code that is generated when the user places a DMA component on the schematic. The automatically generated code would use the APIs in this module. Refer to the DMA component datasheet for more information. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 51 DMA PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 52 10 Flash and EEPROM Flash and EEPROM are programmed using a common set of functions. Refer also to the EEPROM component datasheet for more information. Flash and EEPROM are programmed through the system performance controller (SPC) calls. The Flash/EEPROM specific API abstracts this for simplicity. Only PSoC 3 parts have error correction codes (ECC) storage. This can be configured to be true ECC or used for data storage. The most common use for ECC memory as data storage is to store configuration data which is directly supported by PSoC Creator. When programming Flash with ECC disabled (available for data storage), there are multiple methods for writing a row of data: the entire row including ECC the entire row without ECC just the ECC memory. If ECC memory is used for the storage of configuration data, then ensure you do not overwrite an area of ECC memory that is being used for configuration data. The caller must first call the CySetTemp and CySetFlashEEBuffer functions. The temperature is needed to adjust the write times to the flash for optimal performance. The Buffer is used to store intermediate data while communicating with the SPC. The SPC is push/pull with a register to send commands to and read data back from. Flash or EEPROM can be written to one row at a time by calling the same function "CyWriteRowData". The first parameter will determine the flash or EEPROM array. The number of Arrays that are flash and the number of Arrays that are EEPROM are specific to the exact part selected. Check your part to know which array IDs are valid. A Flash array has, at most, 64 KB plus ECC bytes. PSoC 3 architecture has one Flash array, the size of which is 16 KB, 32 KB, or 64 KB plus ECC bytes. Therefore, the only valid array ID is 0x00. An EEPROM array has, at most, 2 KB. PSoC 3 and PSoC 5 devices have one EEPROM array, the size of which is 512 bytes, 1 KB, or 2 KB. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 53 Flash and EEPROM APIs cystatus CySetTemp() Description: Gets the temperature of the die and leaves the result in a static location used by the Flash and EEPROM writing functions. This function must be called once before executing a series of Flash / EEPROM writing functions. Parameters: None Return Value: Status Value Description CYRET_SUCCESS Successful CYRET_LOCKED Flash / EEPROM writing already in use CYRET_UNKNOWN Failure Side Effects and Execution of this function takes an extended period of time. Restrictions: Function doesn’t return until the SPC has returned to an idle state. cystatus CySetFlashEEBuffer(uint8 *buffer) Description: Sets the buffer used for temporary storage of a complete row of flash plus associated ECC used during writes to Flash and EEPROM. This buffer is only necessary when Flash ECC is disabled. Parameters: uint8 *buffer: Allocated buffer that is (SIZEOF_FLASH_ROW + SIZEOF_ECC_ROW) bytes. Return Value: Status Value Description CYRET_SUCCESS Successful CYRET_LOCKED Flash / EEPROM writing already in use PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 54 Flash and EEPROM cystatus CyWriteRowFull(uint8 arrayId, uint16 rowAddress, uint8 *rowData, uint16 rowSize) Description: Allows a row to be erased and programmed. If the array is a flash array and ECC is being used for configuration storage, the function expects that both the row data and the ECC data have been provided as part of rowData. Parameters: uint8 arrayId: ID of the array to write. The type of write, Flash or EEPROM, is determined from the array ID. The arrays in the part are sequential starting at the first ID for the specific memory type. Type First ID Array Size Flash FIRST_FLASH_ARRAYID 64 K Bytes EEPROM FIRST_EE_ARRAYID 2 K Bytes uint16 rowAddress: Row address within the specified arrayId. Type Rows per Array Row size in Bytes Flash (ECC Enabled) 256 SIZEOF_FLASH_ROW (256) Flash (ECC Disabled) 288 SIZEOF_FLASH_ROW + SIZEOF_ECC_ROW (288) EEPROM 128 SIZEOF_EEPROM_ROW (16) uint8 *rowData: Address of the data to be programmed. The size of this row will be SIZEOF_FLASH_ROW or SIZEOF_EEPROM_ROW depending on the ‘arrayId’. Note This cannot be the same buffer passed as SPC buffer uint16 rowSize: Number of bytes of row data Return Value: Status Value Description CYRET_SUCCESS Successful CYRET_LOCKED Flash / EEPROM writing already in use CYRET_CANCELED Command not accepted Other non-zero Failure PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 55 Flash and EEPROM cystatus CyWriteRowData(uint8 arrayId, uint16 rowAddress, uint8 *rowData) Description: Writes a row of Flash or EEPROM. For Flash, the ECC will be written automatically if ECC is enabled. If ECC is disabled, the current contents of the ECC memory is maintained. Parameters: uint8 arrayId: ID of the array to write. The type of write, Flash or EEPROM, is determined from the array ID. The arrays in the part are sequential starting at the first ID for the specific memory type. Type First ID Array Size Flash FIRST_FLASH_ARRAYID 64K Bytes EEPROM FIRST_EE_ARRAYID 2K Bytes uint16 rowAddress: Row address within the specified arrayId. Type Rows per Array Row size in Bytes Flash 256 SIZEOF_FLASH_ROW (256) EEPROM 128 SIZEOF_EEPROM_ROW (16) uint8 *rowData Array of bytes to write. Return Value: Status Value Description CYRET_SUCCESS Successful CYRET_LOCKED Flash / EEPROM writing already in use CYRET_CANCELED Command not accepted Other non-zero Failure PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 56 Flash and EEPROM cystatus CyWriteRowConfig(uint8 arrayId, uint16 rowAddress, uint8 *rowData) Description: Writes the ECC portion of a Flash row. This function is only present when ECC is disabled and is not being used to store configuration data. This function is only valid for Flash array IDs (not for EEPROM). Parameters: arrayId: ID of the array to write. The arrays in the part are sequential starting at the first ID for the specific memory type. Type First ID ECC Array Size Flash FIRST_FLASH_ARRAYID 8 K Bytes rowAddress: Row address within the specified arrayId. Type Rows per Array ECC Row size in Bytes Flash 256 SIZEOF_ECC_ROW (32) rowData: Array of bytes to write. Return Value: Status Value Description CYRET_SUCCESS Successful CYRET_LOCKED Flash / EEPROM writing already in use CYRET_CANCELED Command not accepted Other non-zero Failure void CyFlash_Start() Description: Enables the Flash. By default Flash is enabled. For PSoC 3 ES2 or earlier and PSoC 5, the same bit controls both EEPROM and Flash. Starting or stopping either will cause both to be started or stopped. Parameters: None Return Value: None void CyFlash_Stop() Description: Disables the Flash. This setting is ignored as long as the CPU is currently running. This will only take effect when the CPU is later disabled. For PSoC 3 ES2 or earlier and PSoC 5, the same bit controls both EEPROM and Flash. Starting or stopping either will cause both to be started or stopped. Parameters: None Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 57 Flash and EEPROM void CyFlash_SetWaitCycles(uint8 freq) Description: Sets the correct number of wait cycles for the flash based on the frequency of operation of the devices. This function should be called before increasing the clock frequency. It can optionally be called after lowering the clock frequency in order to improve CPU performance. Parameters: freq: Frequency of operation in Megahertz Return Value: None void CyEEPROM_Start() Description: Enables the EEPROM. For PSoC 3 ES2 or earlier and PSoC 5, the same bit controls both EEPROM and Flash. Starting or stopping either will cause both to be started or stopped. Also for those silicon versions, the EEPROM is enabled by default. For later silicon, the EEPROM is controlled by a separate bit and must be started before it can be used. Parameters: None Return Value: None void CyEEPROM_Stop() Description: Disables the EEPROM. For PSoC 3 ES2 or earlier and PSoC 5, the same bit controls both EEPROM and Flash. Starting or stopping either will cause both to be started or stopped. Parameters: None Return Value: None void CyEEPROM_ReadReserve() Description: Request access to the EEPROM for reading and waits until that access is available. The access to EEPROM is arbitrated between the controller that writes to the EEPROM and the normal access to read from EEPROM. It is not required to reserve access to the EEPROM for reading, but if a write is still active and a read is attempted a fault is generated and the wrong data is returned. Parameters: None Return Value: None void CyEEPROM_ReadRelease() Description: Releases the read reservation of the EEPROM. If the EEPROM has been reserved for reading, then it must be released before further writes to the EEPROM can be performed. Parameters: None Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 58 11 Bootloader System In PSoC Creator, the bootloader system manages the process of updating the device flash memory with new application code and/or data ("code"). This is accomplished by the following parts: Bootloader component Communications component Bootloader project, used to create the bootloader component Bootloadable project, used to create the code The following sections describe the various aspects of the bootloader process in greater detail. Bootloader Component The bootloader component allows you to update the device flash memory with new code. The bootloader accepts and executes commands, and passes responses to those commands back to the communications component. The bootloader collects and arranges the received data and manages the actual writing of flash through a simple command/status register interface. The bootloader component is not a typical component. It is not available in the Component Catalog. Instead it is always present, behind the scenes, if you have a bootloader type project. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 59 Bootloader System The following diagram shows how the bootloader works. Power Up/Startup Start Application Requested? Y Valid Application? Y N N Run Bootloader CyBtldr_Start() Came from Application? N Valid Application? Y DWR Wait for Command Set? N Y N Run Application Y Set Wait Time (Forever) CyBtldr_Load() Set Wait Time (DWR Wait Time) Request Start Bootloader Perform Bootload Wait for Command Set Wait Time (Forever) Data Received? N Time Expired? Y N Process Command Exit Bootloader Command? N Y Y Valid Application? Y Request Start Application N Reset Communications Component The communications component manages the communications protocol to receive commands from an external system, and passes those commands to the bootloader. It also passes command responses from the bootloader back to the off-chip system. 2 Note USB and I C are the only officially supported communication methods for the bootloader. Refer to 2 the USBFS or I C component datasheet as needed for more details about the appropriate communication method. There is also a Custom option to add bootloader support to any existing communications component. See "Custom Bootloader Component." PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 60 Bootloader System You can also create your own bootloader component for any number of communication methods. For information and instructions on how to do this, refer to the Component Author Guide. Custom Bootloader Component You can create custom bootloader components using any desired communication component. Under the DWR System Editor "IO Component" select the "Custom_Interface" option. See also the "IO Component" parameter. This allows for implementing the necessary functions in any way necessary in your application code. The following shows an example of code inserted into the main.c file for an SPI communication component. For more information about the CyBtldr_ APIs, refer to the Component Author Guide. void CyBtldrCommStart(void) { SPIS_1_Start(); } void CyBtldrCommStop (void) { SPIS_1_Stop(); } void CyBtldrCommReset(void) { } cystatus CyBtldrCommWrite(uint8* buffer, uint16 size, uint16* count, uint8 timeOut) { uint16 i; cystatus status = CYRET_EMPTY; uint8 intStatus = CyEnterCriticalSection(); SPIS_1_ClearRxBuffer(); SPIS_1_ClearTxBuffer(); for (i = 0; i < size; i++) { SPIS_1_WriteTxData(buffer[i]); } CyExitCriticalSection(intStatus); while (timeOut-- > 0) { if ((SPIS_1_ReadTxStatus() & SPIS_1_STS_SPI_DONE) != SPIS_1_STS_SPI_DONE) { *count = size; status = CYRET_SUCCESS; break; } PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 61 Bootloader System CyDelay(10); } return status; } cystatus CyBtldrCommRead (uint8* buffer, uint16 size, uint16* count, uint8 timeOut) { uint16 i = 0; cystatus status = CYRET_EMPTY; uint8 validData = 0; uint8 dataByte; while (timeOut-- > 0) { if (SPIS_1_GetRxBufferSize() > 0 && SPIS_1_GetTxBufferSize() == 0) { while (!validData && SPIS_1_GetRxBufferSize() > 0) { dataByte = SPIS_1_ReadRxData(); validData = (1 == dataByte); } if (validData) { buffer[0] = dataByte; i = 1; } CyDelay(10); while (SPIS_1_GetRxBufferSize() > 0) { buffer[i++] = SPIS_1_ReadRxData(); } if (i > 0) { while(buffer[--i] != 0x17); *count = i+1; status = CYRET_SUCCESS; break; } } CyDelay(10); } return status; } PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 62 Bootloader System Bootloader Project Types In order to implement both a bootloader component and the code, you must create special PSoC Creator project types: bootloader Project and bootloadable Project. Bootloader Project The bootloader component only exists within a bootloader type PSoC Creator design project. When you create a bootloader project, a bootloader component automatically exists in the project. There are two types of bootloaders available: the "Standard Bootloader" and the "Dual Application Bootloader." The "Standard Bootloader" option allows for a single application code, while the "Dual Application Bootloader" allows two applications to reside in flash. The "Dual Application Bootloader" is useful for designs that require a guarantee that there is always a valid application that can be run. This guarantee comes with the limitation that each application has one half of the flash available from what would have been available for a "Standard Bootloader" project. You typically complete a bootloader design project by dragging a communications component onto the schematic, routing the I/O to pins, setting up clocks, etc. A bootloader project with a communications component implements the basic boot loader function of receiving new code and writing it to flash. You can add custom functions to a basic bootloader project by dragging other components onto the schematic or by adding source code. Bootloadable Project The bootloadable project is actually the code. It is very similar to a "standard" design project; the project type can easily be changed between the two during the design phase. The main differences are that a bootloadable project is always associated with a bootloader project, and a standard project is never associated with a bootloader project. A standard project resides in flash starting at address zero. A bootloadable project occupies flash at an address above zero; the associated bootloader project occupies flash starting at address zero, as shown in the following: Meta Data Meta Data (Image 1) Meta Data (Image 2) Bootloadable Project (Image 2) Bootloadable Project Standard Project Standard Bootloader Bootloadable Project (Image 1) Dual Application Bootloader Address 0 PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 63 Bootloader System Bootloader and Bootloadable Project Functions The bootloader project performs overall transfer of a bootloadable project, or new code, to the flash via the bootloader project’s communications component. After the transfer, the processor is always reset. The bootloader project is also responsible at reset time for testing certain conditions and possibly autoinitiating a transfer if the bootloadable project is non-existent or is corrupt. At startup, the bootloader code loads configuration bytes for its own configuration. It must also initialize the stack and other resources and peripherals to do the transfer. When the transfer is complete, control is passed to the bootloadable project via a software reset. The bootloadable project then loads configuration bytes for its own configuration; and re-initializes the stack and other resources and peripherals for its functions. The bootloadable project may call the CyBtldr_Load() function in the bootloader project to initiate a transfer (this results in another software reset). PSoC Creator Project Output Files When either project type – bootloader or bootloadable - is built, an output file is created for that project. In addition, an output file for both projects – a "combination" file – is created when the bootloadable project is build. This file includes both the bootloader and bootloadable projects. This file is typically used to facilitate downloading both projects (via JTAG / SWD) to device flash in a production environment. For bootloader projects the configuration bytes are always stored in the main flash that is occupied by the bootloader, and never in ECC flash. Configuration bytes for bootloadable projects may be stored in either main flash or in ECC flash. The format of the bootloadable project output file is such that when the device has ECC bytes which are disabled, transfer operations are executed in less time. This is done by interleaving records in the bootloadable main flash address space with records in the ECC flash address space. The bootloader takes advantage of this interleaved structure by programming the associated flash row once – the row contains bytes for both main flash and ECC flash. Each project has its own checksum. The checksums is included in the output files at project build time. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 64 Bootloader System Memory Usage The following diagram shows the device's flash memory layout for the PSoC 3 and PSoC 5. Byte 0 Byte 1 ••••••• Byte L Byte 0 Byte 1 ••••••• Byte L Byte 0 Byte 1 ••••••• Row 1 Row 1 Row 1 Row 2 Row 2 Row 2 Row 3 Row 3 Row 3 • • • • • • • • • • • • • • • • • • • • • • • • Row 4 Row 5 Row 6 Row 7 Row 8 • • • • • ••••••• Byte L Row N Array 0 Array 1 Array M L = 256 or 288 if ECC disabled N = 32, 64, 128, or 256 depending on part M = 1, 2, 3, or 4 depending on part = Bootloader Portion = Bootloadable Portion = Reserved for Metadata The bootloader project always occupies the bottom N 256-byte blocks of flash. N is set so that there is enough flash for: the vector table for this project, starting at address 0 (except PSoC 3), and the bootloader project configuration bytes, and the bootloader project code and data, and the checksum for the bootloader portion of flash. Note that the bootloader project configuration bytes are always stored in main flash, never in ECC flash. The relevant option is removed from the project’s .cydwr file. The bootloader portion of flash is protected; it can only be overwritten by downloading via JTAG / SWD. The bootloadable project occupies flash starting at the first 256-byte boundary after the bootloader, and includes: the vector table for the project (except PSoC 3), the bootloadable project code and data, and 64 bytes of data reserved at the very end of the last flash array to store metadata used by both the bootloader and bootloadable. The bootloadable project’s configuration bytes may be stored in the same manner as in a standard project, i.e. in either main flash or in ECC flash, per settings in the project’s .cydwr file. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 65 Bootloader System The highest 64-byte block of flash is used as a common area for both projects. Various parameters are saved in this block, which may include: the entry in flash of the bootloadable project (4 byte address) the amount of flash occupied by the bootloadable project (Number of flash rows) the checksum for the bootloadable portion of flash (one byte) the size of the bootloadable portion of flash (4 bytes, in bytes) 8051 Details (PSoC 3) In the PSoC 3, the only "exception vector" is the 3-byte instruction at address 0, which is executed at processor reset. (The interrupt vectors are not in flash – they are supplied by the Interrupt Controller [IC] ). So at reset the 8051 bootloader code simply starts executing from flash address 0. ARM Cortex-M3 Details (PSoC 5) In the PSoC 5, a table of exception vectors must exist at address 0. (The table is pointed to by the Vector Table Offset Register, at address 0xE000ED08, whose value is set to 0 at reset.) The bootloader code starts immediately after this table. The table contains the initial stack pointer (SP) value for the bootloader project, and the address of the start of the bootloader project code. It also contains vectors for the exceptions and interrupts to be used by the bootloader. The bootloadable project also has its own vector table, which contains that project’s starting SP value and first instruction address. When the transfer is complete, as part of passing control to the bootloadable project the value in the Vector Table Offset Register is changed to the address of the bootloadable project’s table. Bootloader Parameters To access the bootloader parameters, open the Design-Wide Resources System Editor and expand the bootloader section of the editor. Wait for Command Description: At reset, if the bootloader detects that the checksum in bootloadable project flash is valid then it may optionally wait for a command to start a transfer operation before jumping to the bootloadable project code. Settings: Yes or no that the wait will take place. Default: Yes Modifiable by API or No Driver Firmware: Relationship to other If the selection is "yes" then the Wait for Command Time parameter is parameters editable. If the selection is "no" then that parameter is grayed out. In that case an external system typically is not able to initiate a transfer, however the bootloadable project code can still launch a transfer operation by calling Bootloader_Start(). PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 66 Bootloader System Wait for Command Time Description: At reset, if the bootloader detects that the checksum in bootloadable project flash is valid then it may optionally wait for a command to start a transfer operation before jumping to the bootloadable project code. This parameter is the wait timeout period. Settings: 1 – 255, in units of 10 msec. Default: 10, or 100 msec. Modifiable by API or No Driver Firmware: Relationship to other This parameter is editable only if the Wait for Command parameter is set to parameters "yes", otherwise it is grayed out. IO Component Description: This is the communications component that the bootloader uses to receive commands and send responses. One and only one communications component must be selected. Only two-way communications components are used. For example, a UART must have both RX and TX enabled, and an infrared (IrDA) component could not be used. A design rule check (DRC) exists for the case where no two-way communications component has been placed onto the bootloader project schematic. Settings: This property is a list of the available IO communications protocols on the schematic that have bootloader support. In all cases, independent of what is on the schematic, there is also a Custom option available that allows for implementing the bootloader functions directly. Default: If no communications component is on the schematic, then the Custom option will be selected. This allows for implementing the communication in any way. Modifiable by API or No Driver Firmware: Relationship to other None. parameters Fast Application Verification Description: If enabled, the bootloader will compute the checksum for the application code. If successful, it will store this information for future boot operations to avoid the need to validate the application code at every boot. Settings: Yes or no whether verification is remembered. Default: No Modifiable by API or No Driver Firmware: Relationship to other None. parameters PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 67 Bootloader System Checksum Type Description: Provides a couple of options for the type of checksum to use when transferring packets of data between the host and the bootloader. Settings: Basic Sum which just adds up all the bytes and takes a 2's compliment. 16bit CRC using the CCITT algorithm. Default: Basic Sum. Modifiable by API or No Driver Firmware: Relationship to other None. parameters Version Description: Provides a 2 byte number to represent the version of the bootloader. Settings: Any 2 byte number. Default: 0x0000 Modifiable by API or No Driver Firmware: Relationship to other None. parameters Bootloadable Parameters Version Description: Provides a 2 byte number to represent the version of the bootloadable application. Settings: Any 2 byte number. Default: 0x0000 Modifiable by API or No Driver Firmware: Relationship to other None. parameters Bootloadable ID Description: Provides a 2 byte number to represent the ID of the bootloadable application. Settings: Any 2 byte number. Default: 0x0000 Modifiable by API or No Driver Firmware: Relationship to other None. parameters PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 68 Bootloader System Custom ID Description: Provides a 4 byte custom ID number to represent anything in the application. Settings: Any 4 byte number. Default: 0x00000000 Modifiable by API or No Driver Firmware: Relationship to other None. parameters Bootloader API The bootloader provides a public API call solely for the purpose of launching a transfer operation from bootloadable project code. Once called, a software reset is executed, and then the bootloader takes over the CPU. Bootloadable project code, including interrupt handlers, is not executed. When a transfer operation starts, resources and peripherals are reconfigured as needed. All other resources and peripherals are disabled. When the transfer operation is complete, the CPU is reset. void CyBtldr_Load( void ) Description: Starts a transfer operation. Reconfigures the device per bootloader project configuration. Parameters: void Return Value: None. The processor is reset when the transfer is complete. Side Effects: None Bootloader Commands The bootloader supports the following commands. All received bytes that do not start with one of the set of command bytes is discarded with no response generated. All multi-byte fields are output LSB first. Note The time required for the bootloader to execute any command is based on the configuration of the device. Some of the factors that impact the timing include: clock speed at which the part is running toolchain used to build the project optimization settings used during the build number of interrupts running in the background PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 69 Bootloader System Enter Bootloader All other commands are ignored until this command is received. Input Command Byte: 0x38 Data Bytes: NA Output Status/Error Codes: Success Error Command Error Data Error Length Error Checksum Data Bytes: 4 bytes - Silicon ID 1 byte - Silicon Rev 3 bytes - Bootloader Version Get Flash Size Responds with the first and last available rows in the selected flash array. Input Command Byte: 0x32 Data Bytes: 1 byte - Flash Array ID Output Status/Error Codes: Success Error Command Error Data Error Length Error Checksum Data Bytes: 2 bytes - First available row 2 bytes - Last available row PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 70 Bootloader System Program Row Writes one row of flash data to the device. Input Command Byte: 0x39 Data Bytes: 1 byte - Flash Array ID 2 bytes - Flash Row Number n bytes - Data to write into the flash row Output Status/Error Codes: Success Error Command Error Data Error Length Error Checksum Error Flash Row Error Active Data Bytes: NA Erase Row Erases the contents of the provided flash row. Input Command Byte: 0x34 Data Bytes: 1 byte - Flash Array ID 2 bytes - Flash Row Number Output Status/Error Codes: Success Error Command Error Data Error Length Error Checksum Error Flash Row Error Active Data Bytes: NA PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 71 Bootloader System Verify Row Gets a 1 byte checksum for the contents of the provided row of flash Input Command Byte: 0x3A Data Bytes: 1 byte - Flash Array ID 2 bytes - Flash Row Number Output Status/Error Codes: Success Error Command Error Data Error Length Error Checksum Data Bytes: 1 byte - Row checksum Verify Checksum Gets a 1-byte value indicating whether the checksum for the flash matches the expected checksum value. A return value of 1 indicates that the checksums match and that the application is considered good. A return value of 0 indicates that the checksums do not match, and that the application is invalid. This is the same check that the bootloader will run before attempting to run the application code. Input Command Byte: 0x31 Data Bytes: N/A Output Status/Error Codes: Success Error Command Error Data Error Length Error Checksum Data Bytes: 1 byte - Application checksum valid PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 72 Bootloader System Send Data Sends a block of data to the device. This data is buffered up in anticipation of another command that will inform the bootloader what to do with the data. If multiple send data commands are issued back-to-back, the data is appended to the previous block. This command is used to breakup large transfers into smaller pieces to prevent bus starvation in some protocols. Input Command Byte: 0x37 Data Bytes: n bytes - Data to save in the device Output Status/Error Codes: Success Error Command Error Data Error Length Error Checksum Data Bytes: NA Sync Bootloader Resets the bootloader to a clean state, ready to accept a new command. Any data that was buffered will be thrown out. This is only necessary if the host and client get out of sync with each other. Input Command Byte: 0x35 Data Bytes: NA Output NA - This packet is not acknowledged Exit Bootloader Exits from the bootloader by triggering a software reset of the device. Before the software reset is executed, the bootloadable application is verified. If the application passes verification, the application will be executed after the software reset. If the application fails verification, then execution will begin again with the bootloader after the software reset. Input Command Byte: 0x3B Data Bytes: NA Output NA - This packet is not acknowledged PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 73 Bootloader System Get Application Status (Dual Application Bootloader Only) Input Command Byte: 0x33 Data Bytes: 1byte – Application # Output Status/Error Codes: Success Error Length Error Checksum Error Data Data Bytes: 1byte – Application # Valid 1byte –Application # Active Set Active Application (Dual Application Bootloader Only) Input Command Byte: 0x36 Data Bytes: 1byte – Application # Output Status/Error Codes: Success Error Application Error Length Error Data Error Checksum Data Bytes: NA Bootloader Packets Packets sent to the bootloader have the following structure: 1-byte packet start (0x01) 1-byte command 2-bytes data length n-bytes data 2-bytes checksum 1-byte packet end (0x17) PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 74 Bootloader System Packets output from the bootloader have the following structure: 1-byte packet start (0x01) 1-byte status/error code 2-bytes data length n-bytes data 2-bytes checksum 1-byte packet end (0x17) Bootloader Status/Error Codes The possible status/error codes output from the bootloader are as follows: Bootloader Application Success – The command was successfully received and executed. Value = 0x00 Error Length (CYRET_ERR_LENGTH) – The amount of data available is outside the expected range. Value = 0x03 Error Data (CYRET_ERR_DATA) – The data is not of the proper form. Value = 0x04 Error Command (CYRET_ERR_CMD) – The command is not recognized. Value = 0x05 Error Checksum (ERR_CHECKSUM) – The checksum does not match the expected value. Value = 0x08 Error Flash Row (ERR_ROW) – The flash row is not valid. Value = 0x0A Error Unknown (ERR_UNK) – An unknown error occurred. Value = 0x0F Error Application (CYRET_ERR_APP) – The application is not valid and cannot be set as active. Value = 0x0C. (Dual Application Bootloader Only) Error Active (CYRET_ERR_ACTIVE) – The application is currently marked as active. Value = 0x0D. (Dual Application Bootloader Only) Bootloader Host Error Device (CYRET_ERR_DEVICE) – The expected device does not match the detected device. Value = 0x06 Error Version (CYRET_ERR_VERSION) – The bootloader version detected is not supported. Value = 0x07 Bootloader Application & Code Data File Format The bootloader application & code data (.cyacd) file format is used to store the bootloadable portion of a design. The file consists of a header followed by lines of flash data. Excluding the header, each line in the .cyacd file represents an entire row of flash data. The data is stored as ASCII data in big endian format. The header record has the format: [4-byte SiliconID][1-byte SiliconRev][1-byte Checksum Type] PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 75 Bootloader System The data records have the format: [1-byte ArrayID][2-byte RowNumber][2-byte DataLength][N-byte Data] [1-byte Checksum] The checksum type in the header indicates the type of checksum used for packets sent between the bootloader host and the bootloader itself. The checksum in the data records is a basic summation, computed by summing all bytes (excluding the checksum itself) and then taking the 2's complement. Bootloader Host Tool PSoC Creator ships with a bootloader host tool (bootloader_host.exe) that can be used to test out the bootloader running on a PSoC chip. The bootloader host tool is the application that communicates with the bootloader itself to send new bootloadable images. The bootloader host tool provided is intended to be used as a development and testing tool only. Source Code In addition to the host executable itself, much of the source code used is also provided. This source code can be reused to create your own bootloader host applications. The source code is located in the following directory: <Install Dir>\cybootloaderutils\ By default, this directory is: C:\Program Files\Cypress\PSoC Creator\<Release Version>\PSoC Creator\cybootloaderutils\ This source code is broken up into four different modules. These modules provide implementations for the various pieces of functionality required for a bootloader host. Depending on the desired level of control, some or all of these modules can be used in developing a custom bootloader host application. cybtldr_command.c/h This module handles construction of packets to send to the bootloader, and the parsing of packets received from the bootloader. It has a single function for constructing each type of packet that the bootloader understands, and a single function for parsing the results for each packet the bootloader can send back. cybtldr_parse.c/h This module handles the parsing of the *.cyacd file that contains the bootloadable image to send to the device. It has functions for Setting up access to the file, Reading the header, Reading the row data, and closing the file. cybtldr_api.c/h Is a row level API that allows for sending a single row of data at a time to the bootloader using a supplied communication mechanism. It has functions for setting up the bootload operation, programming a row, erasing a row, verifying a row, and ending the bootload operation. cybtldr_api2.c/h Is a higher level API that handles the entire bootload process. It has functions for programming the device, erasing the device, verifying the device, and aborting the current operation. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 76 Bootloader System Versions The following are the features provided with different versions of the bootloader host tool: Version 1.0.0 (PSoC Creator 1.0, Beta5) Initial version; provides APIs for: Parsing *.cyacd file Constructing packets of data to send to the bootloader Functions for Programming, Erasing, Verifying rows of data Functions for performing the entire bootload operation Version 1.1.0 (PSoC Creator 1.0, Production) Provides all the functionality contained in Bootloader Host version 1.0.0. Adds support for using either a basic sum (used in 1.0.0) or a new 16-bit CCITT checksum for ensuring packet integrity when communicating with the bootloader. Version 1.2.0 (PSoC Creator 2.0) Provides all the functionality contained in Bootloader Host version 1.1.0. Adds support for communicating with either the "Standard Bootloader" or the "Dual Application Bootloader." PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 77 Bootloader System PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 78 12 System Functions These functions apply to all architectures. General APIs uint8 CyEnterCriticalSection(void) Description: CyEnterCriticalSection disables interrupts and returns a value indicating whether interrupts were previously enabled (the actual value depends on whether the device is PSoC 3 or PSoC 5). Note Implementation of CyEnterCriticalSection manipulates the IRQ enable bit with interrupts still enabled. The test and set of the interrupt bits is not atomic; this is true for both PSoC 3 and PSoC 5. Therefore, to avoid corrupting processor state, it must be the policy that all interrupt routines restore the interrupt enable bits as they were found on entry. Parameters: None Return Value: uint8 PSoC 3 – Returns a value containing two bits: bit 0: 1 if interrupts were enabled before CyEnterCriticalSection was called. bit 1: 1 if IRQ generation was disabled before CyEnterCriticalSection was called. PSoC 5 – Returns 1 if interrupts were previously enabled or 0 if interrupts were previously disabled. void CyExitCriticalSection(uint8 savedIntrStatus) Description: CyExitCriticalSection re-enables interrupts if they were enabled before CyEnterCriticalSection was called. The argument should be the value returned from CyEnterCriticalSection. Parameters: uint8 savedIntrStatus: Saved interrupt status returned by the CyEnterCriticalSection function. Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 79 System Functions void CYASSERT(uint32 expr) Description: Macro that evaluates the expression and if it is false (evaluates to 0) then the processor is halted. This macro is evaluated unless NDEBUG is defined. If NDEBUG is defined, then no code is generated for this macro. NDEBUG is defined by default for a Release build setting and not defined for a Debug build setting. Parameters: expr: Logical expression. Asserts if false. Return Value: None void CyHalt(uint8 reason) Description: Halts the CPU. Parameters: reason: Value to be passed for debugging. This value may be useful to know the reason why CyHalt() was invoked. Return Value: None void CySoftwareReset(void) Description: Forces a software reset of the device. Parameters: None Return Value: None CyDelay APIs There are four CyDelay APIs that implement simple software-based delay loops. The loops compensate for bus clock frequency. The CyDelay functions provide a minimum delay. If the processor is interrupted, the length of the loop will be extended by as long as it takes to implement the interrupt. Other overhead factors, including function entry and exit, may also affect the total length of time spent executing the function. This will be especially apparent when the nominal delay time is small. void CyDelay(uint32 milliseconds) Description: Delay by the specified number of milliseconds. By default the number of cycles to delay is calculated based on the clock configuration entered in PSoC Creator. If the clock configuration is changed at run-time, then the function CyDelayFreq is used to indicate the new Bus Clock frequency. CyDelay is used by several components, so changing the clock frequency without updating the frequency setting for the delay can cause those components to fail. Parameters: milliseconds: Number of milliseconds to delay. Return Value: None Side Effects and CyDelay has been implemented with the instruction cache assumed enabled. Restrictions: When instruction cache is disabled on PSoC 5, CyDelay will be two times larger. For example, with instruction cache disabled CyDelay(100) would result in about 200 ms delay instead of 100 ms. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 80 System Functions void CyDelayUs(uint16 microseconds) Description: Delay by the specified number of microseconds. By default the number of cycles to delay is calculated based on the clock configuration entered in PSoC Creator. If the clock configuration is changed at run-time, then the function CyDelayFreq is used to indicate the new Bus Clock frequency. CyDelayUs is used by several components, so changing the clock frequency without updating the frequency setting for the delay can cause those components to fail. Parameters: microseconds: Number of microseconds to delay. Return Value: Void Side Effects and CyDelayUS has been implemented with the instruction cache assumed enabled. Restrictions: When instruction cache is disabled on PSoC 5, CyDelayUs will be two times larger. For example, with instruction cache disabled CyDelayUs(100) would result in about 200 us delay instead of 100 us. void CyDelayFreq(uint32 freq) Description: Sets the Bus Clock frequency used to calculate the number of cycles needed to implement a delay with CyDelay. By default the frequency used is based on the value determined by PSoC Creator at build time. Parameters: freq: Bus clock frequency in Hz. 0: Use the default value non-0: Set frequency value Return Value: None void CyDelayCycles(uint32 cycles) Description: Delay by the specified number of cycles using a software delay loop. Parameters: cycles: Number of cycles to delay. Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 81 System Functions PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 82 13 Startup and Linking The cy_boot component is responsible for the startup of the system. The following functionality has been implemented: Provide the reset vector Setup processor for execution Setup interrupts Setup the stack including the reentrant stack for the 8051 Configure the device Initialize static and global variables with initialization values Clear all remaining static and global variables Integrate with the boot loader Call main() C entry point PSoC 3 Startup is all handled by a single assembly file (KeilStart.a51) which is based on a template provided by Keil. There isn’t a file specifically associated with linking. PSoC 5 The startup and linker scripts have been custom developed by Cypress, but both of the toolchain vendors that we currently support provide example linker implementations and complete libraries that solve many of the issues that have been created by our custom implementations. GCC Implementation Use all the standard GCC libraries (libcs3, libc, libcs3unhosted, libgcc, libcs3micro). All of these libraries are linked in by default. Realview Implementation (applicable for MDK and RVDS) Use all the standard libraries (C standardlib, C microlib, fplib, mathlib). All of these libraries are linked in by default. Support for RTOS and user replacement of routines. This is possible because the library routines are denoted as "weak" allowing their replacement if another implementation is provided. A mechanism is provided that allows for the replacement of the provided linker/scatter file with a user version. This is implemented by allowing the user to create the file local to their project and PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 83 Startup and Linking having a build setting that allows the specification of this file as the linker/scatter file instead of the file provided automatically. Currently the heap and stack size are specified as a fixed quantity (4 K Stack, 1 K Heap). If possible the requirement to specify Heap and Stack sizes should be removed entirely. If that is not possible, then these values should be the defaults with the option to choose other values in the Design-Wide Resources GUI. All the code in the Generated Source tree is compiled into a single library as part of the build process. Then that compiled library is linked in with the user code in the final link. CMSIS Support (PSoC 5) Cortex Microcontroller Software Interface Standard (CMSIS) is a standard from ARM for interacting with Cortex M-series processors. There are multiple levels of support. The following support is provided: Core Peripheral Access Layer core_cm3.c core_cm3.h These files are used without modification. The same files work for all of our supported platforms. Preservation of Reset Status (PSoC 3 and PSoC 5) The value of the reset status register shall be read and cleared any time the device is booted and that value shall be saved to a global SRAM variable. This register is RESET_SR0 for PSoC 3. That variable along with defines for the fields in the register shall be provided. uint8 CyResetStatus Name Description CY_RESET_LVID Low voltage detect digital CY_RESET_LVIA Low voltage detect analog CY_RESET_HVIA High voltage detect analog CY_RESET_WD Watchdog reset CY_RESET_SW Software reset CY_RESET_GP0 General purpose bit 0 CY_RESET_GP1 General purpose bit 1 PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 84 14 Watchdog Timer APIs void CyWdtStart(uint8 ticks, uint8 lpMode) Description: Enables the watchdog timer. The timer is configured for the specified count interval, the Central Time Wheel is cleared, the setting for low power mode is configured, and the watchdog timer is enabled. Once enabled the watchdog cannot be disabled. The watchdog counts each time the Central Time Wheel (CTW) reaches the period specified. The watchdog must be cleared using the CyWdtClear() function before the watchdog counts to three. The CTW is free running, so this will occur after between 2 and 3 timer periods elapse. Parameters: ticks: One of the four available timer periods Value Define Time 0 CYWDT_2_TICKS 2 CTW Ticks 1 CYWDT_16_TICKS 16 CTW Ticks 2 CYWDT_128_TICKS 128 CTW Ticks 3 CYWDT_1024_TICKS 1024 CTW Ticks lpMode: Low power mode configuration Value Define Effect 0 CYWDT_LPMODE_NOCHANGE No Change 1 CYWDT_LPMODE_MAXINTER Switch to longest timer mode during sleep / hibernate 3 CYWDT_LPMODE_DISABLED Disable WDT during sleep / hibernate Return Value: None Side effects and All 'lpMode' parameter values are supported by PSoC 3 production silicon. PSoC 5 restrictions and PSoC 3 ES2 support only NOCHANGE. The hardware implementation of the watchdog timer prevents any modification of the timer once it has been enabled. It also prevents the timer from being disabled once it has been enabled. This protects the watchdog timer from changes caused by errant code. As a result, only the first call to CyWdtStart() after reset will have any effect. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 85 Watchdog Timer void CyWdtClear() Description: Clears (feeds) the watchdog timer. Parameters: None Return Value: None PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 86 15 cy_boot Component Changes Version 2.40 This section lists and describes the major changes in the cy_boot component version 2.40: Description of Version 2.30 Changes Reason for Changes / Impact Updated the CyPmSleep() and CyPmHibernate() APIs. Changes were made to improve power mode configuration. Version 2.30 This section lists and describes the major changes in the cy_boot component version 2.30: Description of Version 2.30 Changes Reason for Changes / Impact CyIntEnable and CyIntDisable functions have been changed to be CYREENTRANT by default. Many components require CyIntEnable and CyIntDisable to be reentrant and these components have no way to cause that to happen. This means you no longer need to populate a cyre file for these functions that you do not call. User was made responsible for clock power modes configuration during Sleep and Alternate Active mode. The implementation of CyPmSleep() and CyPmAltActive() functions were modified by removing 32 KHz ECO,100 KHz and 1 KHz ILO power mode configuration before device low power mode entry. The CyILO_SetPowerMode() and CyXTAL_32KHZ_SetPowerMode() can be used to configure clock power modes. The information regarding user responsibility of clock power mode configuration was added at the PM API section. The IMO value should match FIMO and FIMO is always 12 MHz. The implementation of the CyPmSaveClocks() was updated to set IMO clock frequency to 48 MHz when "Enable Fast IMO during startup" is enabled, and to 12 MHz otherwise. The IMO frequency is always set to 12 MHz just before the low power mode entry and restored immediately after wakeup. The CyPmRestoreClocks() restores original value of the IMO clock. The implementation of the CyPmRestoreClocks() The CyPmRestoreClocks() function is expected to function was updated by removing restoring MHz be called only after CyPmSaveClocks(), while the ECO and PLL disabled state. last one always disables MHz ECO and PLL. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 87 cy_boot Component Changes Description of Version 2.30 Changes Reason for Changes / Impact Global interrupts are disabled on CyPmSleep()/CyPmHibernate() entry and restored before return from the function. The CyPmSleep() and CyPmAltAct() function implementations for PSoC 5 devices were updated to ignore all parameters. The PSoC 5 device will go into Sleep mode until it is woken by an interrupt from one of three wakeup sources: Central Time Wheel (CTW), Once per second, or Port Interrupt Controller (PICU). These wakeup sources must already be configured to generate an interrupt. The CTW is configured using the SleepTimer component and the Once per second interrupt using the Real Time Clock component. Updated architecture- and silicon-specific #defines to be used across the content. Improved performance of non-DMA configuration on 8051 devices. Interrupts are disabled to prevent their occurrence before the state of the device has been restored. The implementation of the CyPmRestoreClocks() was updated for PSoC5 silicon. The megahertz crystal is given 130 ms to stabilize. Its readiness is not verified after the hold-off timeout. The power mode of the source clocks for the timer used as the wakeup timer was removed from PM API functions. PSoC Creator Power Management section was updated. The CyPmSleep() and CyPmAltAct() functions have to be used only with the following parameters: CyPmSleep(PM_SLEEP_TIME_NONE, PM_SLEEP_SRC_NONE) and CyPmAltAct(PM_ALT_ACT_TIME_NONE, PM_ALT_ACT_SRC_NONE). These modifications decrease the startup time and slightly reduce consumption of code memory and internal data memory. These modifications increase crystal startup time, but ensure that crystal is ready to be used. Before calling PM API function, you must manually configure the power mode of the source clocks for the timer that will be used as the wakeup timer. More detailed information on Power Management API usage was added. Version 2.21 This section lists and describes the major changes in the cy_boot component version 2.21: Description of Version 2.21 Changes Reason for Changes / Impact Provide a new option for selecting how to compute checksums on data transferred from the bootloader host to the bootloader. Provide a generic option to allow users to define their own custom bootloader communication functions. Provide a more robust way to check for errors during IO transfers. Updated a few Power Management functions to prevent some possible issues. Make adding support for additional communication protocols (SPI, UART, ...) easier. Also provides a means of supporting multiple communications components concurrently in the same design. Some parentheses were missing which could cause items to be evaluated in the wrong order. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 88 cy_boot Component Changes Description of Version 2.21 Changes Reason for Changes / Impact Added a variable CyResetStatus that can be used to get the information from the RESET_SR0 register. This is provided because many of the fields contained within the RESET_SR0 register are clear-on-read. Since the bootloader needs to access this register as part of its operation, it prevents the actual application code from accessing the values. The variable is provided so that the application can still get access to all the information. On some PSoC 3 devices the NVL information may not be initialized properly. This workaround is provided to ensure that the NVLs are properly loaded before performing any of the startup code. Added a workaround for some PSoC3 devices to ensure that the NVL values have been properly initialized. Version 2.20 This section lists and describes the major changes in the cy_boot component version 2.20: Description of Version 2.20 Changes Reason for Changes / Impact Updated the CyDelayCycles function to work with instruction cache enabled. The original CyDelayCycles function was designed to be used with the instruction cache disabled. For PSoC 3 ES3 and Production silicon, when the instruction cache is enabled, the length of the delay was no longer correct. The comments and descriptions for the CyPmSleep(), CyPmHibernate(), and CyPmAltAct() functions we clarified to refer to the silicon errata for a PSoC 3 ES2 and PSoC 5 defect. Fixed an issue in the bootloader for PSoC 5 that would cause it to fail to verify the application code if the application code was larger than 64 K. Modified what is required for the bootloader to consider that there is activity and that someone appears to be attempting to communicate. Previously, if the Bootloader received any data over the selected communications component it would then wait forever for data. With this change, the bootloader will now only wait forever if it has received the Enter Bootloader command. Change was made to address an issue. There is no impact. Updated comments in the code and descriptions in this guide for low power mode functions. Fixed a bootloader issue with the CyBtldr_ValidateApp function. Addressed a bootloader wait for traffic issue. Updated the CySetTemp function to read the die temperature twice to make sure it has a stable value. Version 2.10 This section lists and describes the major changes in the cy_boot component version 2.10: Description of Version 2.10 Changes Reason for Changes / Impact Updated Flash verification code in the bootloader Fixed an issue in the bootloader's Verify routine that could cause a failure to be reported even for a valid image if flash was disabled. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 89 cy_boot Component Changes Version 2.0 This section lists and describes the major changes in the cy_boot component version 2.0: Description of Version 2.0 Changes Reason for Changes / Impact Keil C51 keywords available as macros These macros allow code to specify the memory space of variables and pointers while maintaining compatibility with other compilers. The most commonly used keywords are CYCODE, CYXDATA, and CYDATA, which represent C51’s code, xdata, and data keywords, respectively. On other compilers, these macros are ignored. It is no longer necessary to define macros such as CYLIB_POWER_MANAGEMENT to include API functions from CyLib. This prevents potential errors and warnings when building projects in RealView with DMA-based configuration enabled. In previous versions, only the first 32 entries of the table were being initialized. In previous versions, the reserved vectors were initialized to 0, which is not a valid interrupt service routine address. In previous versions, the high and low bytes were swapped. CyLib APIs are no longer conditional Add separate section for .dma_init in RealView linker script Initialize complete SRAM interrupt vector table Initialize reserved interrupt vectors to default interrupt handler Fix incorrect endian in CyIntSetVector return value on PSoC 3 Apply interrupt attribute to interrupt service routine declarations Make CY_GET_REGxx/CY_SET_REGxx reentrant and improve performance PSoC 3 ES3 support in CyDelay Use limits.h and ctype.h to replace some macros in CyLib.h Support for RealView in --gnu mode Update PSoC 5 startup code to make better use of standard libraries Replaced cydevice.h with cydevice_trm.h Interrupt service routines declared with CY_ISR/CY_ISR_PROTO/cyisraddress now have the interrupt attribute, which causes the compiler to emit code to adjust the stack alignment. RealView checks for the interrupt attribute as part of the type, so interrupt service routines or vectors that do not have the interrupt attribute will fail to compile on RealView. For this reason, cy_isr_v1_20 and earlier are not compatible with cy_boot_v1_50 when using RealView. This affects PSoC 5 only; the interrupt attribute was already present in the PSoC 3 version. The functions that implemented this functionality, CyGetRegXX and CySetRegXX, have been replaced with assembly routines. The new routines may be safely used in interrupt service routines. CPUCLK_DIV has been moved from a SFR to the CLKDIST_MSTR1 in ES3. The LONG_MIN, LONG_MAX, and ULONG_MAX macros are now provided by the toolchain-specific limits.h. This prevents warnings caused by differences between the compiler’s limits.h and CyLib.h. Corrected some preprocessor conditionals that caused errors when RealView was used with the --gnu option. The startup code used in PSoC 5 projects has been updated to use standard libraries to provide the initialization. This provides for a standard initialization. cydevice.h has been marked obsolete, so the APIs and generated code provided with PSoC Creator should not use it. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 90 cy_boot Component Changes Description of Version 2.0 Changes Reason for Changes / Impact CYCODE, CYDATA, CYXDATA and CYFAR defines are copied over to cytypes.h Fix for the cache flash cycles incorrect behavior after sleep. Miscellaneous Flash/EEPROM API changes. Now any component can make use of these defines, Ex Flash component Added reentrancy support. Converted cymemset and cymemcpy to macros, removed cymemmove. CYREG_CACHE_CR doesn't retain its value in PSOC 3 after the sleep Define active/standby power configuration registers based on silicon. Define active/standby power configuration register constant based on silicon. Added CyFlash_Start() and CyFlash_Stop() APIs. Removed CyFlashEEActivePower() and CyFlashEEStandbyPower() APIs, Modified CySetFlashEEBuffer()for PSoC 3 so as not to test whether the buffer is not a pointer at 0. Changed an argument in CyWriteRowConfig() API to rowData. Added CyEEPROM_Start(), CyEEPROM_Stop(), CyEEPROM_ReadReserve(), CyEEPROM_ReadRelease(), and CyFlash_SetWaitCycles(uint8 freq) APIs. Power mode registers and power mode register constants are defined based on the silicon. Cache Control register is defined based on the silicon. Appropriate APIs in cylib.c/h, cyflash.c/h, cydmac.c/h and cyspc.c/h files were updated to include reentrant support. The memset/memcpy/memmove provided by the toolchain vendor are typically faster than the generic implementation because they are designed for the specific target platform. Including both the vendor-provided functions and the generic implementation wastes code space. Non-legacy code should use memset and memcpy directly. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 91 cy_boot Component Changes Description of Version 2.0 Changes Reason for Changes / Impact Added numerous new clock APIs: CyPLL_OUT_Start_confirm CyMasterClock_SetSource CyMasterClock_ActivateIMOAndSet CyMasterClock_ActivatePLLAndSet CyIMO_ActivateAndWait CyIMO_SetFrequency CyIMO_EnableDisableDoubler CyIMO_EnableDoubler CyIMO_DisableDoubler CyIMO2X_SetSource CyPLL_P_SetValue CyPLL_Q_SetValue CyPLL_SetInput CyXTAL_SetGain CyXTAL_SetVref CyILO_1KHZ_Start CyILO_1KHZ_Stop CyILO_100KHZ_Start CyILO_100KHZ_Stop CyILO_33KHZ_Start CyILO_33KHZ_Stop CyILO_SelectClock CyUSB_Start CyUSB_Stop CyUSB_SetClockSource CyUSB_SetClockSource_IMO2X CyUSB_SetClockSource_IMO CyUSB_SetClockSource_PLL CyUSB_SetClockSource_DSI CyUSB_EnableDivider CyUSB_DisableDivider CyCLK_SetDividerValue CyCLK_SetBusDividerValue char8 datatype is defined as char. Renamed CySleep and CyHibernate APIs to CyPmSleep and CyPmHibernate; added new CyPmAltAct API. To provide additional functionality. To support new compilers in future. There were deficiencies in the low power APIs before cy_boot 2.0. You must update your design to use cy_boot 2.0 and rewrite the low power portion of the design to use the new APIs. PSoC® Creator™ System Reference Guide, Document Number: 001-73816, Rev. ** 92